feat(directives): harvest 8 directives from feature_flags/RAG/cache/knowledge styleguides + 4 new styleguides

2026-07-02 22:17:20 -04:00
parent 09d6a9c7c8
commit cdc0f1405c
8 changed files with 436 additions and 0 deletions
@@ -0,0 +1,49 @@
+# test_sandbox — v1
+
+**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/test_sandbox.md` §"The 4-Layer Model" + §"The `--config` CLI Flag" + §"The `--basetemp` Rule" (lines 5-58). This is the baseline encoding — the layered-table-plus-mechanism style currently in production.
+Future variants will test alternative encodings (rule-only, before/after) against this baseline.
+
+**Source:** `conductor/code_styleguides/test_sandbox.md:5-58`
+
+---
+
+## The 4-Layer Model
+
+| Layer | Mechanism | Where | Default-on? |
+|---|---|---|---|
+| Layer 1 | Python runtime file-I/O guard (`sys.addaudithook`) | `tests/conftest.py:_sandbox_audit_hook` | Yes |
+| Layer 2 | `isolate_workspace` autouse + `pyproject.toml --basetemp` | `tests/conftest.py` + `pyproject.toml` | Yes |
+| Layer 3 | OS-level restricted-token PowerShell wrapper | `scripts/run_tests_sandboxed.ps1` | **Opt-in** |
+| Layer 4 | Static audit script (CI gate) | `scripts/audit_test_sandbox_violations.py` | Yes (informational) / opt-in (`--strict`) |
+
+Layer 1 + Layer 2 + Layer 4 are file-presence-on = enabled (delete the relevant file to disable). Layer 3 requires explicit invocation.
+
+## The `--config` CLI Flag (replaces `SLOP_CONFIG`)
+
+The historical `SLOP_CONFIG` env var has been removed from `src/paths.py`. The CLI flag `--config <path>` is now the ONLY supported mechanism for overriding the default `<project_root>/config.toml` location.
+
+```bash
+# Use the default <project_root>/config.toml
+uv run python sloppy.py
+
+# Override
+uv run python sloppy.py --config /path/to/your/config.toml
+```
+
+`sloppy.py` calls `paths.set_config_override(Path(args.config).resolve())` AFTER `parse_args()` and BEFORE any `from src.gui_2 import App` import. This is the only way to override the config path in production.
+
+## The `--basetemp` Rule
+
+`pyproject.toml` sets `addopts = "--basetemp=tests/artifacts/_pytest_tmp"`. This redirects pytest's `tmp_path` and `tmp_path_factory` fixtures (which default to `%TEMP%\pytest-of-<user>\` on Windows) into `./tests/artifacts/`. This is what allows the Layer 1 allowlist to be a single rule: "anything under `./tests/` is allowed."
+
+## Layer 1 Audit Hook Contract
+
+`tests/conftest.py:_sandbox_audit_hook` is a `sys.addaudithook` callback. It fires on every `open()` call. Behavior:
+
+- **Reads** (mode `r`, `rb`): pass through, no check
+- **Writes** (mode contains `w`, `a`, `x`, `+`): check path
+- **Allowed** if path resolves under:
+  - `<project_root>/tests/`
+  - Path contains `.pytest_cache`, `__pycache__`, `.coverage`, `.slop_cache`, or `.ruff_cache`
+  - Original path string starts with `\\.\` (Windows device namespace) or `/dev/` (Unix device namespace)
+- **Blocked** otherwise: raises `RuntimeError("TEST_SANDBOX_VIOLATION: attempted to write to <path>...")`