harness-everything 0.3.6 → 0.4.0

package/docs/routing.md

@@ -1,58 +1,171 @@
 # Harness Routing & Task Triage
 
-To prevent both over-engineering and under-planning, Harness classifies every user request into one of three execution tiers. This ensures that trivial tasks are executed instantly without unnecessary bloat, while complex architectural refactoring is strictly designed and verified.
+Harness classifies software work into three tiers to prevent both over-engineering and under-planning. **The tier is a scope recommendation, not a workflow pipeline.**
 
-This is a default, not an order: `tier-router.js`'s own output tells the agent to follow its own read of the task when it clearly disagrees, and an explicit instruction from the Human Partner always wins. The keyword heuristic exists to catch the common case cheaply and deterministically, not to override judgment when it's wrong - the tier-router hook and the `zoom-out` step-back-and-retry loop are the safety net for when a hard call is actually needed, not the routing keywords themselves.
+The current architecture follows one rule:
 
-## Tuning the keyword heuristic
+> **Do not enforce workflow order. Enforce workflow invariants.**
 
-`tier-router.js` reads its keyword/guide tables from the sibling `harness-everything/scripts/routing-keywords.json` instead of hardcoding them. Edit that file directly to retune which prompts route to Tier 2/3 or surface a given knowledge guide - no code changes, no re-install, and it travels with `tier-router.js` automatically on every install/update since it lives in the same skill folder. Each `guideGroups` entry matches via a plain-substring `keywords` array (case-insensitive OR) or a `regex` source string; if the file is missing or hand-edited into invalid JSON, the router fails open (empty tables, Tier 1 default) instead of breaking the hook.
+A strong model should be free to decide how to complete the task. Harness protects only the small set of behaviors that must not disappear when the host chooses a peer/domain skill directly.
 
-## Non-Software Task Bypass
+## Kernel invariants
 
-If the user's prompt is non-software engineering (general Q&A, text translation, web searching, or conversational chat), Harness OS routing is **bypassed completely**. The model replies directly and naturally without emitting a Routing Checkpoint block.
+For software/project work, Harness establishes three mandatory rails before mutation:
 
----
+1. **Route before execution** — establish task scope/tier.
+2. **Verify before claim** — completion requires objective evidence appropriate to the change.
+3. **Re-plan after repeated failure** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
 
-## The Three-Tier Routing System
+Skill selection, ordering, planning style, and delegation remain agent decisions unless the user or an authoritative project contract explicitly requires them.
 
-Upon receiving a software engineering request, the `tier-router.js` script analyzes the scope, affected files, and instruction patterns to route the task:
+## Public routing path
 
+```text
+kernel-router.js
+  ├─ delegates classification / guide discovery → tier-router.js
+  ├─ preserves tier + rationale + dynamic-skill recommendations
+  ├─ suppresses legacy fixed-pipeline wording
+  ├─ emits required invariants
+  └─ emits advisory skill suggestions
 ```
-                  [ User Request ]
-                         |
-                 [ Software Task? ]
-                /                  \
-             (No)                  (Yes)
-             /                        \
-    [ Bypass Router ]          [ Triage Analysis ]
-    Direct Response           /        |         \
-                             /         |          \
-                    (Trivial)      (Standard)     (Macro)
-                    /                  |                 \
-                   v                   v                  v
-               [ Tier 1 ]          [ Tier 2 ]         [ Tier 3 ]
-               Direct Edit      Test-Driven (TDD)    Multi-Agent Flow
-               (No plans)      (Red-Green-Refactor)   (Fable-Mode)
+
+Use:
+
+```bash
+node harness-everything/scripts/kernel-router.js "<prompt>"
+# or
+npx github:dyphn1/Harness-everything next "<prompt>"
+```
+
+On a host where `UserPromptSubmit` is wired, reuse the hook output instead of running it twice.
+
+## Non-software bypass
+
+General Q&A, translation, ordinary web search, and non-software writing bypass Harness routing. The model should answer directly and naturally.
+
+A software prompt that already says "use TDD", "security review", `repo-docs`, or another skill **does not bypass the kernel**. Host skill routing and Harness routing are different layers: the kernel establishes cross-cutting invariants; the host/model selects useful expertise.
+
+## Three-tier recommendation model
+
+```mermaid
+flowchart TD
+    U([User Request]) --> S{Software / project work?}
+    S -- No --> B[Bypass Harness]
+    S -- Yes --> K[Harness Kernel<br/>scope + invariants]
+    K --> T{Tier recommendation}
+    T -- Tier 1 --> A[Agent self-orchestrates]
+    T -- Tier 2 --> A
+    T -- Tier 3 --> A
+    A --> E[Execute selected tactics / skills]
+    E --> V{Evidence supports completion?}
+    V -- Yes --> D([Done])
+    V -- No --> R[Diagnose and iterate]
+    R --> F{Same failure x3?}
+    F -- No --> E
+    F -- Yes --> Z[Zoom out / re-plan]
+    Z --> E
+```
+
+### Tier 1 — Trivial
+
+Typical triggers: typos, narrow single-file edits, straightforward cleanup, code explanation, simple Git operations.
+
+Guidance:
+- prefer direct execution,
+- avoid large plans/delegation,
+- load a focused skill only when it adds value,
+- still gather enough evidence to support the completion claim.
+
+### Tier 2 — Standard
+
+Typical triggers: normal feature work, bug fixes, multi-file changes, security review, focused benchmark/evaluation.
+
+Possible suggestions:
+- `todo-driven-workflow` when explicit progress tracking helps,
+- `tdd` when executable behavioral tests are a useful design/verification tool,
+- `verification-loop` when systematic build/lint/test/diff selection helps,
+- `security-review` for trust/input/auth/secrets/network boundaries,
+- `using-git-worktrees` where isolation reduces workspace risk,
+- `eval-harness` for quantitative scoring.
+
+None of those imply a universal `TODO → TDD → verification-loop` sequence.
+
+### Tier 3 — Macro
+
+Typical triggers: repository-wide refactors, architecture/migration work, large ambiguous requirements, broad documentation/system design, or work that may benefit from delegation.
+
+Possible suggestions:
+- `fable-mode` / `fable-discipline` for deliberate macro planning,
+- `multi-agent-workspace` for bounded delegation,
+- `repo-docs` for project-level documentation,
+- `grill-with-docs`, `to-spec`, and `to-tickets` when design decisions/specs/issues genuinely help.
+
+Tier 3 does **not** automatically mean multi-agent. If one capable agent can complete the work safely and efficiently, direct execution is valid.
+
+## Classifier tuning
+
+`tier-router.js` reads keyword/guide tables from `harness-everything/scripts/routing-keywords.json`. Edit that data to tune Tier 2/3 signals or knowledge-guide matches without changing classifier code.
+
+The classifier remains heuristic:
+- its recommendation is the default, not an order,
+- a clear task reading may override it,
+- explicit user intent wins,
+- when overriding a materially different tier, record the reason briefly.
+
+## Pre-action `actionGate`
+
+The router may predict that a request needs `workflowPlan.actionGate`, but the Phase 5 enforcement hook deliberately **re-classifies the exact tool payload**. A missing or incorrect router prediction therefore cannot authorize a destructive command.
+
+The executable policy lives in `hooks/scripts/action-gate-rules.json`. A missing or invalid table activates built-in safety defaults and reports the degradation. A valid empty table remains empty so the CI negative control can detect accidental policy erasure.
+
+| Exact tool action | Harness result | Audit disposition before execution |
+|---|---|---|
+| Safe unmatched command such as `git status` | allow/no decision | no gate record |
+| Matched command on Claude Code (default policy) | no decision: the session's permission mode, rules and auto-mode classifier decide | `deferred-to-host` |
+| Matched command on Claude Code with `HARNESS_ACTION_GATE_POLICY=always-ask` | `permissionDecision: "ask"` | `pending-approval` |
+| Matched command on a host without Harness-verified ask semantics | block with exit 2 | `rejected` |
+| Payload reaches `PostToolUse` | continue | `executed` with exact payload SHA-256 |
+| Payload reaches `PostToolUseFailure` | continue | `executed` + failed execution outcome |
+| Deferred or pending payload never executes before `Stop` | no execution | `rejected` |
+| Hook internal error | Claude: no decision plus a `systemMessage` warning (`always-ask`: `ask`); other/unverified host: exit 2 | host decides on Claude; fail closed elsewhere |
+
+`rm -rf` and `Remove-Item -Recurse -Force` are exempt only when every parsed target is inside the OS temp directory, the current session scratch directory, or an explicitly supplied Harness scratch directory. An uncertain target is gated conservatively.
+
+```mermaid
+flowchart TD
+    P[PreToolUse exact payload] --> C{Matches action-gate rule?}
+    C -- No --> A[Allow without gate record]
+    C -- Yes --> X{Scratch-only destructive delete?}
+    X -- Yes --> A
+    X -- No --> H{Host has a native permission flow?}
+    H -- Claude Code --> Y{always-ask policy?}
+    Y -- No --> D[No decision: the permission mode decides<br/>record deferred-to-host + payload hash]
+    Y -- Yes --> Q[Emit permissionDecision: ask<br/>record pending-approval + payload hash]
+    H -- No / unknown --> B[Exit 2 block<br/>record rejected]
+    D --> U{Did the exact tool payload execute?}
+    Q --> U
+    U -- PostToolUse --> E[record executed]
+    U -- PostToolUseFailure --> F[record executed + failure]
+    U -- no execution by Stop --> R[record rejected]
 ```
 
-### Tier 1: Trivial Tasks (Direct Execution)
-*   **Trigger criteria:** Single-file edits, typos, simple styling fixes, readme corrections, or clean-up tasks.
-*   **Behavior:** Harness bypasses plans, code-reviews, and sub-agents. The model makes the edit directly, emitting a brief single-line routing checkpoint or direct response.
-*   **Verification:** Basic syntax checks or a quick compile verify success.
-
-### Tier 2: Standard Tasks (Test-Driven Development)
-*   **Trigger criteria:** Normal feature requests, bug fixes, algorithm additions, API endpoint creations, SRP object splitting, or security reviews affecting multiple files.
-*   **Behavior:** Harness enforces the `todo-driven-workflow` base execution loop (prioritizing native IDE tools like `manage_todo_list`, with `tasks/todo.md` as the portable fallback) and the `tdd` skill. The model is strictly guided through the Red-Green-Refactor loop:
-    1.  **Red:** Write an automated test first that reproduces the issue or covers the feature, then run it to verify failure.
-    2.  **Green:** Implement the minimal amount of code to make the test pass.
-    3.  **Refactor:** Polish the code, clean up duplicates, and ensure coverage targets are met.
-*   **Verification:** Strict execution of the test suite and pre-delivery checks (`verification-loop`).
-
-### Tier 3: Macro Tasks (Multi-Agent/Fable-Mode)
-*   **Trigger criteria:** High-level design changes, migration of modules, large-scale refactoring, or major capability additions affecting multiple domains.
-*   **Behavior:** Harness routes the macro task to `fable-mode` and `multi-agent-workspace`, with the macro plan materialized via `todo-driven-workflow`. Hosts that support sub-agents may then delegate bounded work streams.
-    1.  **Planning & Alignment:** Perform grilling (`grill-me` / `grill-with-docs`), present an outline preview via `to-spec`, and publish formal specs or vertical-slice tickets (`to-tickets`).
-    2.  **Delegation:** Specialized sub-agents (or inline persona role-switches) handle specific work streams or audits.
-    3.  **Handoffs & Memory:** Milestone progress is saved to `todo-driven-workflow` state, and lessons learned are recorded via `self-evolve` (enforcing the 60-line cleanliness and lazy-loading rule).
-*   **Verification:** Multi-layer unit, integration, and E2E verification loops (`verification-loop`).
+On Claude Code the gate returns no decision by default. The [hooks reference](https://code.claude.com/docs/en/hooks) says a hook's `ask` "also forces a permission prompt in auto mode: the classifier can still deny the tool call, but it can't approve the call silently". A forced `ask` would therefore override the permission mode the user picked (#107).
+
+With no decision, the normal permission flow applies:
+
+- Manual and `acceptEdits` prompt unless a rule or the mode already allows the command.
+- Auto mode lets the classifier decide.
+- `dontAsk` denies anything that is not pre-approved.
+- Deny rules apply in every mode.
+
+Set `HARNESS_ACTION_GATE_POLICY=always-ask` to have Harness force its own prompt instead. Either way the gate classifies and audits every matched payload.
+
+The deterministic suite verifies two things: the deferred result for every known `permission_mode` value, and the `ask` JSON under `always-ask`. That is **mechanism evidence only** until preserved live evidence exists.
+
+## Cognitive OS relationship
+
+`install-cognitive-os` remains the canonical explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is **not** required to win peer-skill selection before domain work begins. The runtime kernel establishes the smaller invariant contract independently; domain skills provide their own tactics inside that contract.
+
+## Enforcement strength
+
+A lifecycle hook can mechanically inject/guard supported invariants. Instruction-only integrations can only advise the model. Do not label advisory behavior as hard enforcement, and do not infer cross-host parity from shared skill text alone.

package/docs/security-audit.md

@@ -0,0 +1,38 @@
+# Security Audit: Verifier Boundaries
+
+Date: 2026-09-10
+
+## Scope
+
+The audit covers `scripts/lib/path-boundary.js` and
+`scripts/lib/execution-contract.js`, which are shared by later verifier,
+workspace, installer, and plugin fixes. The standalone consumers also have
+focused regressions for archive output, legacy migration, global installation,
+fixture construction, and reflection patch authorization.
+
+## STRIDE and abuse cases
+
+| Threat | Abuse case | Boundary |
+|---|---|---|
+| Tampering | A junction or symlink below an output root redirects a new file outside it. | Resolve the deepest existing ancestor and reject link components below the root. |
+| Tampering | `..` or an absolute patch path escapes the repository allowlist. | Normalize repository-relative paths and reject traversal/absolute paths. |
+| Information disclosure | A verifier treats a path fragment as proof that a different command ran. | Compare the complete normalized command or exact argv. |
+| Elevation of privilege | A mixed patch includes one allowed file and one unrelated file. | Require every parsed patch path to be authorized; reject the entire patch otherwise. |
+| Repudiation | A caller cannot distinguish an outside path from a link alias. | Stable error codes identify the rejected boundary condition. |
+
+## Residual risks
+
+- Callers must still use the returned physical target and perform the check
+  immediately before the filesystem operation; a check done earlier can be
+  invalidated by a time-of-check/time-of-use race.
+- The helper does not grant permission to choose a boundary root. Consumers
+  must establish that the root itself is trusted before calling it.
+- Live model behavioral evidence remains an environment/acceptance concern and
+  is not manufactured by these deterministic helpers.
+
+## Verification
+
+`ci/mechanism-2v-verifier-boundaries.test.js` covers normal paths, traversal,
+junction/symlink escapes, missing leaves, Windows casing, exact commands, and
+all-or-nothing patch authorization. `npm run test:mutations` then verifies that
+eight corresponding production protections are load-bearing.

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Harness OS Troubleshooting Guide
 
-This guide helps you resolve common issues with Harness OS installation and usage.
+This guide helps you resolve common issues with Harness OS installation and usage. Platform enforcement claims follow [platform-capabilities.md](platform-capabilities.md).
 
 ## Installation Issues
 
@@ -69,13 +69,11 @@ yarn install
    ```bash
    cat .claude/settings.json | grep -A 10 "hooks"
    ```
-
 2. Check hook file permissions:
    ```bash
    ls -la hooks/scripts/*.js
    ```
-
-3. Restart Claude Code session
+3. Restart Claude Code session.
 
 ### Hook Execution Errors
 
@@ -99,18 +97,19 @@ npx github:dyphn1/Harness-everything install
 **Symptom:** `RULE OF 3 CIRCUIT BREAKER TRIGGERED!` frequently
 
 **Solution:**
-1. This is normal behavior - Harness is protecting you from infinite loops
-2. Follow the zoom-out instructions in the error message
-3. If it's a false positive, check the error signature:
+1. This is normal behavior on an integration surface that actually packages the circuit-breaker hooks: Harness is protecting you from infinite loops.
+2. Follow the zoom-out instructions in the error message.
+3. If it's a false positive on the Claude Code hook path, check the error signature:
    ```bash
    cat .claude/harness-everything/state/sessions/default/rule-of-3-state.json
    ```
-
 4. Reset if needed:
    ```bash
    npm run harness:reset
    ```
 
+Do not expect this Claude Code state file merely because Harness skills or an instruction-only platform integration are installed.
+
 ## Platform-Specific Issues
 
 ### Cursor Not Showing Rules
@@ -122,13 +121,11 @@ npx github:dyphn1/Harness-everything install
    ```bash
    cat .cursorrules | head -20
    ```
-
 2. If missing, reinstall with Cursor flag:
    ```bash
    npx github:dyphn1/Harness-everything install --cursor
    ```
-
-3. Restart Cursor
+3. Restart Cursor.
 
 ### Copilot Not Following Rules
 
@@ -139,43 +136,90 @@ npx github:dyphn1/Harness-everything install
    ```bash
    cat .github/copilot-instructions.md | head -20
    ```
+2. Ensure Copilot is using the instructions file.
+3. Restart VS Code/GitHub Copilot.
 
-2. Ensure Copilot is using the instructions file
-3. Restart VS Code/GitHub Copilot
-
-### Codex/AGENTS.md Issues
+### Codex advisory installer / AGENTS.md issues
 
-**Symptom:** Codex not recognizing Harness
+**Symptom:** Codex does not appear to receive the general installer guidance.
 
 **Solution:**
-1. Check AGENTS.md exists:
+1. Check `AGENTS.md` exists and contains Harness guidance:
    ```bash
    cat AGENTS.md | head -20
    ```
-
-2. Reinstall with Codex flag:
+2. Reinstall the advisory Codex target if needed:
    ```bash
    npx github:dyphn1/Harness-everything install --codex
    ```
+3. Remember that this is the instruction-oriented installer path. It is different from the **local OpenAI plugin** package described below.
+
+### Codex / local OpenAI plugin not appearing
+
+**Symptom:** The Harness plugin is missing from the local Plugins Directory, skills are stale, or packaged lifecycle behavior does not reflect the current repository package.
+
+**Checks:**
+```bash
+npm run plugin:sync
+npm run test:plugin:openai
+```
+
+Then verify the repository contains:
+
+```text
+.agents/plugins/marketplace.json
+plugins/harness-everything/.codex-plugin/plugin.json
+plugins/harness-everything/hooks/hooks.json
+plugins/harness-everything/hooks/session-start.js
+plugins/harness-everything/skills/
+```
+
+If those checks pass but the host still shows an older copy:
+
+1. Refresh/sync the imported marketplace or repository plugin in the host.
+2. Restart/refresh the local ChatGPT/Codex host if it cached the plugin package.
+3. Start a **new chat/session** before judging `SessionStart` or `UserPromptSubmit` behavior.
+4. Re-review/trust changed command hooks if the host asks again after hook definitions changed.
+
+The local plugin mechanically injects the session policy and invariant-first routing contract, and its package includes mechanism-tested supported-tool, subagent, and stop adapters. If those events do not appear in a live session, verify the host loaded the current package and that changed command hooks were reviewed/trusted; package tests alone cannot prove host loading.
+
+See [openai-plugin.md](openai-plugin.md) for installation and validation details.
+
+### Public OpenAI Skills-only plugin behaves differently from local Codex plugin
+
+**Symptom:** A public/reviewer Skills-only install does not run local `.codex-plugin` lifecycle hooks.
+
+**Expected behavior:** This is by design. The public Skills-only upload contains reusable skills and referenced assets, but not the local `.codex-plugin` lifecycle hooks. Validate public behavior with:
+
+```bash
+npm run plugin:submission:build
+npm run test:plugin:submission
+```
+
+Do not troubleshoot a missing `SessionStart` or `UserPromptSubmit` hook in the public Skills-only artifact as if it were a packaging defect.
+
+### OpenCode plugin implementation works in tests but host loading is uncertain
+
+**Symptom:** Source/mechanism tests pass, but there is no evidence that a real OpenCode session loaded and fired the plugin.
+
+**Interpretation:** The current repository claim is intentionally **mechanism-tested, live loading unverified**. Check [`../opencode-plugin/README.md`](../opencode-plugin/README.md) and run the OpenCode mechanism coverage. Do not promote a source-level pass into a live-host pass without a real session artifact.
 
 ## Performance Issues
 
 ### Slow Hook Execution
 
-**Symptom:** Terminal commands feel slower
+**Symptom:** Terminal commands feel slower on a hook-enabled integration.
 
 **Solution:**
-1. Check hook execution time:
+1. Check Claude Code hook execution time where applicable:
    ```bash
    time node hooks/scripts/rule-of-3.js < /dev/null
    ```
-
 2. If >200ms, check for:
    - Large state files
    - Network calls in hooks
    - Complex file operations
-
-3. Reset state:
+3. Reset state if appropriate:
    ```bash
    rm -rf .claude/harness-everything/state/sessions/
    ```
@@ -187,47 +231,43 @@ npx github:dyphn1/Harness-everything install
 **Solution:**
 1. Check for memory leaks:
    ```bash
-   # Monitor Node.js processes
    ps aux | grep node
    ```
-
-2. Restart session if needed
-3. Report issue if persistent
+2. Restart session if needed.
+3. Report issue if persistent.
 
 ## Debugging
 
 ### Enable Verbose Logging
 
 ```bash
-# Set debug environment variable
 export HARNESS_DEBUG=1
-
-# Run with verbose output
 node hooks/scripts/rule-of-3.js < payload.json
 ```
 
 ### Check State Files
 
 ```bash
-# View current state
+# Claude Code hook-path state example
 cat .claude/harness-everything/state/sessions/default/rule-of-3-state.json
 cat .claude/harness-everything/state/sessions/default/handoff-state.json
 
-# Reset all state
+# Reset Claude hook-path state
 rm -rf .claude/harness-everything/state/sessions/
 npm run harness:reset
 ```
 
 ### Manual Hook Testing
 
-```bash
-# Test rule-of-3 hook
-echo '{"tool_name":"Bash","tool_input":{"command":"test"}}' | node hooks/scripts/rule-of-3.js
+For deterministic cross-platform mechanism checks, prefer:
 
-# Test state-persist hook
-echo '{"tool_name":"Edit","tool_input":{"file_path":"test.js"}}' | node hooks/scripts/state-persist.js
+```bash
+npm run test:mechanism
+npm run test:docs:capabilities
 ```
 
+When isolating a specific Claude hook, use the Windows-safe `spawnSync` recipes in [../VERIFICATION.md](../VERIFICATION.md) rather than assuming a shell `echo | node` pipeline behaves the same on every OS.
+
 ## Getting Help
 
 ### Collect Diagnostic Information
@@ -244,22 +284,18 @@ cat package.json | grep version >> harness-diagnostic.txt
 echo "" >> harness-diagnostic.txt
 
 echo "=== Installed Platforms ===" >> harness-diagnostic.txt
-ls -la .claude/ .cursorrules .github/copilot-instructions.md AGENTS.md .continue/rules/ .hermes.md 2>/dev/null >> harness-diagnostic.txt
+ls -la .claude/ .cursorrules .github/copilot-instructions.md AGENTS.md .continue/rules/ .hermes.md .agents/plugins/ plugins/harness-everything/ 2>/dev/null >> harness-diagnostic.txt
 echo "" >> harness-diagnostic.txt
 
 echo "=== Hook Status ===" >> harness-diagnostic.txt
 cat .claude/settings.json | grep -A 20 "hooks" >> harness-diagnostic.txt 2>/dev/null
-echo "" >> harness-diagnostic.txt
-
-echo "=== Recent Errors ===" >> harness-diagnostic.txt
-# Add any recent error logs here
 ```
 
 ### Contact Support
 
 1. **GitHub Issues:** https://github.com/dyphn1/Harness-everything/issues
 2. **Include:** Diagnostic report, error messages, steps to reproduce
-3. **Platform:** Specify which AI tool you're using (Claude Code, Cursor, etc.)
+3. **Platform:** Specify which AI tool and which Harness installation surface you're using (for example `--codex` advisory installer vs local OpenAI plugin vs public Skills-only plugin).
 
 ## Common Error Messages
 
@@ -272,8 +308,8 @@ echo "=== Recent Errors ===" >> harness-diagnostic.txt
 - **Solution:** Will fail open to Tier 1 - reinstall to restore
 
 ### "Session state not found"
-- **Cause:** First run or state cleared
-- **Solution:** Normal - state will be created on first use
+- **Cause:** First run, state cleared, or the selected platform surface does not create that runtime state
+- **Solution:** Confirm the platform/integration surface first; on a supported stateful hook path, state is created on first use
 
 ### "Zoom-out report not found"
 - **Cause:** Circuit breaker tripped but no report written

package/docs/verifier-boundaries.md

@@ -0,0 +1,45 @@
+# Verifier Boundary Contracts
+
+This repository handles paths and execution evidence produced by local agent
+sessions. Consumers must use these contracts before writing, deleting, or
+grading anything derived from a session. The repository-side evidence archiver
+and legacy workspace migration use the same checks; the standalone OpenCode
+plugin mirrors the patch authorization rule because it is distributed as one
+file.
+
+## Physical path containment
+
+```js
+const { assertContainedPath } = require('../scripts/lib/path-boundary');
+
+const { target } = assertContainedPath(outputRoot, requestedPath);
+```
+
+`assertContainedPath()` resolves the deepest existing ancestor before appending
+missing segments. It rejects lexical traversal, junction/symlink components
+below the selected root, and physical paths outside the root. Call it for the
+final target, not only for the user-provided parent directory. Consumers must
+handle `PATH_OUTSIDE_BOUNDARY`, `LINK_COMPONENT_IN_BOUNDARY`, and
+`INVALID_BOUNDARY_PATH` as hard failures.
+
+## Exact execution evidence
+
+Use `commandMatches()` for command expectations. Complete strings compare after
+whitespace normalization; argv arrays compare each argument and length exactly.
+The only shorthand accepted is a script basename when an approved interpreter
+(`node`, `bun`, `deno`, Python, or Ruby) is the command launcher. Substring
+checks are not valid evidence.
+
+Use `extractPatchPaths()` and `patchPathsAuthorized()` for patch-shaped tool
+output. A patch is authorized only when every touched path is allowlisted;
+mixed authorized and unauthorized patches must be rejected atomically.
+
+Prefer structured argv and patch metadata when the producer provides them.
+These string fallbacks intentionally fail closed rather than guessing intent.
+
+## Mutation gate
+
+`npm run test:mutations` runs focused tests against temporary in-memory source
+mutations for each consumer boundary. A green result means the test would fail
+if its corresponding protection were removed; it does not replace the normal
+mechanism, consistency, or live behavioral-evidence gates.