archive: tier 2 leak prevention

conductor/archive/tier2_leak_prevention_20260620/spec.md

@@ -0,0 +1,86 @@
+# Tier 2 Sandbox File Leak Prevention — Spec
+
+**Track:** `tier2_leak_prevention_20260620`
+**Created:** 2026-06-20
+**Type:** fix (recovery + defense-in-depth)
+**Scope:** 5 new files, 1 modified file, 4 commits
+
+## Background
+
+On 2026-06-19, commit `00e5a3f2` ("chore(env): pre-existing tier2 setup files") was pushed to `origin/master`. The commit contained 9 file changes:
+
+| Status | File | Notes |
+|--------|------|-------|
+| ADDED | `.opencode/agents/tier2-autonomous.md` | tier-2 SANDBOX agent (canonical source: `conductor/tier2/agents/tier2-autonomous.md`) |
+| ADDED | `.opencode/commands/tier-2-auto-execute.md` | tier-2 SANDBOX command (canonical source: `conductor/tier2/commands/tier-2-auto-execute.md`) |
+| MODIFIED | `opencode.json` | tier-2 sandbox overrode MCP path → `manual_slop_tier2`, default_agent → `tier2-autonomous`, model → `minimax-coding-plan/MiniMax-M3` |
+| MODIFIED | `mcp_paths.toml` | tier-2 sandbox cleared `extra_dirs` to `[]` |
+| MODIFIED | `project_history.toml` | timestamp update only (out of scope) |
+| ADDED | `scripts/tier2/artifacts/.../*.py` | 4 throwaway scripts (out of scope; legitimately tier-2 working artifacts) |
+
+The commit message ("pre-existing tier2 setup files") was misleading. The actual root cause: `setup_tier2_clone.ps1` legitimately modifies these files **in the clone** (`C:\projects\manual_slop_tier2\`), but the modifications leaked into the **main repo** via an accidental `git add .` in the tier-2 clone. The canonical sources live at `conductor/tier2/*` (per `setup_tier2_clone.ps1:48-49`); the main repo should NEVER see the sandbox's local config drift.
+
+## What the user asked for
+
+1. **Selective revert** of the offending files: `./opencode/*`, `mcp_paths.toml`, `opencode.json`. Leave the 4 throwaway scripts and `project_history.toml` timestamp at HEAD per the user's explicit list.
+2. **A way to make sure tier-2 autonomous never commits those files** — explicitly NOT via gitignore.
+
+## Design
+
+### Layer 1 (existing): OpenCode permission system
+The tier-2-autonomous agent profile denies direct edits to the forbidden files. This was already in place but the deny rules didn't cover the auto-modifications done by `setup_tier2_clone.ps1` (the script itself writes the files, not the agent directly).
+
+### Layer 2 (this track): pre-commit hook at the commit boundary
+`conductor/tier2/githooks/pre-commit`:
+- Reads `conductor/tier2/githooks/forbidden-files.txt` (substring patterns, one per line)
+- For each staged file, checks if any pattern is a substring of the path
+- Auto-unstages matching files via `git rm --cached --force`
+- Always exits 0 (removes the leak rather than blocking the commit, since tier-2 cannot run `git restore --staged` per the sandbox permission rules)
+- Hook source lives at `conductor/tier2/githooks/pre-commit`; config lives alongside as `conductor/tier2/githooks/forbidden-files.txt`
+
+### Layer 3 (this track): working-tree audit
+`scripts/audit_tier2_leaks.py`:
+- Default mode (informational, exit 0): scans working tree for forbidden files
+- `--strict` mode (CI gate, exit 1 if leaks): catches anything the hook missed (manual edits, ops mistakes)
+- `--json` mode: machine-readable output for CI integration
+- Skips `tests/`, `conductor/`, `node_modules/`, `.git/`, etc.
+- Reports only `untracked` and `modified` files (tracked-and-clean files are legitimate)
+
+### Hook installation
+`scripts/tier2/setup_tier2_clone.ps1` step 4 (Install git hooks) is updated to copy the new `pre-commit` hook into the clone's `.git/hooks/` directory alongside the existing `pre-push` and `post-checkout` hooks. The forbidden-files.txt config is already committed to the clone (as part of the canonical `conductor/tier2/*` source), so the hook can find it via the project root.
+
+## Forbidden patterns (substring matches)
+
+```
+.opencode/agents/tier2-autonomous    # sandbox agent, NOT the interactive tier2-tech-lead
+.opencode/commands/tier-2-auto-execute  # sandbox slash command
+opencode.json       # MCP path / default_agent / model override
+mcp_paths.toml      # extra_dirs cleared in clone
+```
+
+Patterns are SPECIFIC (not prefix-based) so they do not match the legitimate interactive tier-2 tech-lead prompt at `.opencode/agents/tier2-tech-lead.md`.
+
+## Tests
+
+- `tests/test_tier2_pre_commit_hook.py` (12 tests): pre-commit hook behavior
+- `tests/test_audit_tier2_leaks.py` (13 tests): audit script behavior
+
+All 25 tests pass.
+
+## Files changed
+
+| Status | File |
+|--------|------|
+| NEW | `conductor/tier2/githooks/pre-commit` |
+| NEW | `conductor/tier2/githooks/forbidden-files.txt` |
+| NEW | `scripts/audit_tier2_leaks.py` |
+| NEW | `tests/test_tier2_pre_commit_hook.py` |
+| NEW | `tests/test_audit_tier2_leaks.py` |
+| MODIFIED | `scripts/tier2/setup_tier2_clone.ps1` |
+
+## Out of scope
+
+- Wiring `audit_tier2_leaks.py --strict` into CI (deferred to a follow-up track)
+- Rebasing stale tier-2 branches on the new master tip (user action required; see `TRACK_COMPLETION_tier2_leak_prevention_20260620.md` §Next Steps)
+- The 4 throwaway scripts in `scripts/tier2/artifacts/.../*.py` (legitimate tier-2 working artifacts per the tier-2 convention)
+- The `project_history.toml` timestamp update (harmless side effect)