harness-everything 0.2.2 → 0.4.0

package/docs/architecture.md

@@ -1,95 +1,179 @@
-# Harness Architecture
-
-This document details the internal architecture, lifecycle, and integration touchpoints of the Harness behavior layer.
-
----
-
-## Architectural Overview
-
-Harness acts as a **system supervisor** wrapping around your AI development sessions. Instead of controlling the model's generation directly, it leverages native hook systems (like Claude Code's lifecycle hooks) and instruction files (like `.cursorrules` or `.github/copilot-instructions.md`) to inject contextual guardrails.
-
-The diagram below outlines the full lifecycle of a task under Harness:
-
-```mermaid
-flowchart TD
-    subgraph User_Session [User Session]
-        U([User Request]) --> Boot[bootstrap.js: Session Start]
-    end
-
-    subgraph OS_Kernel [Harness Engine]
-        Boot -->|Check Handoff Checkpoint| Preflight[preflight.js: Environment Audit]
-        Preflight --> Router{tier-router.js: Task Triage}
-        
-        Router -->|Tier 1: Trivial Task| T1[Direct Execution - No Plans]
-        Router -->|Tier 2: Standard Task| T2[tdd: Test-Driven Development]
-        Router -->|Tier 3: Macro Task| T3[fable-mode: Multi-Agent Spawn]
-        T2 & T3 --> TDW[todo-driven-workflow: Base Execution Checklist]
-    end
-
-    subgraph Defense_Safety [Circuit Breakers]
-        T1 & TDW --> Tools[Agent Tool Call]
-        Tools -->|PreToolUse| CG[context-compact.js: Bloat Warning]
-        Tools -->|PreToolUse| CB{rule-of-3.js: Circuit Breaker}
-        
-        CB -->|Fails 3x| ZO(zoom-out: Halt, Reflect & Fact-Check)
-        ZO -->|Fresh diagnosis: RESUME| Tools
-        CB -->|Succeeds| Done[Success / Finish]
-    end
-
-    subgraph Continuous_Learning [Continuous Learning]
-        ZO -->|Genuine human decision / 2nd trip| Human[Human Decision & Guidance]
-        Human --> SE[self-evolve: Deep Reflection]
-        Done -->|Complex Breakthrough| SE
-        SE --> RunSR[self-regression.js: CI Check]
-        RunSR -->|Pass 100%| Mem[(Long-term Memory / RULES.md)]
-        Mem -.->|Immunize| Preflight
-    end
-
-    style OS_Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
-    style Defense_Safety fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
-    style Continuous_Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
-```
-
----
-
-## Integration touchpoints
-
-Harness is designed to align with the unique capabilities of various AI IDEs and CLI tools — but those capabilities are not equivalent across platforms, and this repo does not pretend otherwise.
-
-**Self-healing:** integration touchpoints can drift — installed from one editor, opened in another. `harness-everything/scripts/self-heal.js` audits all six touchpoints below and re-runs the idempotent installer to backfill whatever is missing. On Claude Code, `bootstrap.js` performs the audit at SessionStart and reports missing touchpoints (repair is left to the model so an intentionally removed file isn't silently re-created every session); on hook-less platforms, the audit runs when `harness-everything` or `environment-detection`'s Discover phase loads. Only Claude Code has a hook system with exit-code-based blocking; every other platform below gets **advisory text only**, with the same protection level as the "Prompt-Only" column in the README's own comparison table. There is no `preflight.js` audit, no `Rule of 3` circuit breaker, and no WAL on those platforms — nothing runs the `.claude/harness-everything/state/*` runtime-state scripts unless Claude Code (or another hook-capable tool) is also driving the same repo.
-
-**Placement rule:** a platform's own native file/folder (`.claude/settings.json`, `.cursorrules`, `.cursor/skills/`, …) is never moved — it lives exactly where that platform expects it. Anything Harness itself needs that has no native home converges into one exclusively-owned subfolder per platform: `<platform-dir>/harness-everything/`. Nothing else ever creates a directory literally named `harness-everything`, which is what lets the installer add or remove it as a unit — including on uninstall — without touching anything else already in that platform's directory (another tool's files, or skills the user installed by hand).
-
-**Runtime state vs. installed skill content:** `<platform-dir>/harness-everything/` holds runtime state (pure runtime state: hook JSON, circuit-breaker counters, handoff/verification timestamps) kept apart in the `state/` subfolder. On the other hand, the actual installed skills go to each platform's native/expected skills directories (e.g., `.claude/skills/` for Claude, `.cursor/skills/` for Cursor, `.github/skills/` for Copilot, `.codex/skills/` for Codex, `.continue/skills/` for Continue, and `~/.agents/skills/` or `~/.claude/skills/` for Global scope) where they are dynamically discovered and processed. A `manifest.json` under `<platform-dir>/harness-everything/` (or global home) records exactly what the installer put where, per platform, so uninstall can match against the manifest files and perform precise cleanup without guessing. Both runtime state and skills directories are gitignored.
-
-### 1. Claude Code (hook-enforced)
-Our installer configures native lifecycle hooks inside `.claude/settings.json`, and places project-level skills inside the native `.claude/skills/` directory where Claude Code natively auto-discovers and registers them.
-*   `SessionStart`: Runs `bootstrap.js` to restore previous handoffs, check environment variables, and initialize session state.
-*   `PreToolUse`: Triggers `rule-of-3.js`, `boundary-guard.js`, `depth-guard.js`, `context-compact.js`, and `subagent-scope-guard.js` to intercept tool invocations before they run, and can actually block one (`exit(2)`) — e.g. the Rule of 3 circuit breaker.
-*   `PostToolUse`: Records tool outcomes, updates the persistent transaction log (WAL) via `state-persist.js`, tracks repeat failures, and can only add advisory context back (the tool already ran; nothing here blocks it).
-*   `Stop`: Runs `stop-gate.js` — when a turn ends with uncommitted edits that were never followed by a successful verification command (test/build/lint), it bounces the stop back once per edit batch. This is the mechanical form of `verification-loop`'s pre-delivery gate; on every other platform that gate remains advisory prose.
-
-### 2. Cursor (advisory only)
-The installer appends guidance to `.cursorrules`. Cursor has no hook/execution mechanism, so nothing in `.claude/harness-state/` gets read or written by Cursor itself, and no tool call can be blocked — the model is simply asked (in the same file, every session) to self-regulate: discover the environment before acting, stop after 3 repeated failures instead of continuing to retry, and prefer small commits.
-
-### 3. Copilot Chat (advisory only)
-Same mechanism and same limits as Cursor, via `.github/copilot-instructions.md`.
-
-### 4. Codex (advisory only)
-Same mechanism and same limits again, via `AGENTS.md` — Codex's actual custom-instruction file, read automatically at session start (`.codex/config.toml` controls CLI/sandbox behavior, not prompt content, and was never a valid target for this).
-
-### 5. Continue.dev (advisory only)
-Continue's rules system reads individual Markdown files (with YAML frontmatter — `name`, `globs`, `alwaysApply`) from a `.continue/rules/` folder rather than one shared file, so the installer writes a dedicated `.continue/rules/harness.md` with `alwaysApply: true` instead of appending into an arbitrary pre-existing file. No hook/execution mechanism, same limits as Cursor. Global scope writes to `~/.continue/rules/harness.md`.
-
-### 6. Hermes Agent (advisory only)
-[Hermes](https://hermes-agent.nousresearch.com/) (Nous Research) auto-injects project context into its system prompt from `.hermes.md`, `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` if present in the directory it's launched from (truncated at ~20k chars) — meaning a Codex or Cursor install already reaches Hermes for free. The installer still writes a dedicated `.hermes.md` for explicit coverage. No hook/execution mechanism. Project scope only: Hermes has no documented global project-instructions equivalent (its own settings live under `~/.hermes/`, which governs model/terminal/skills config, not per-project behavior text), so `--global --hermes` is a deliberate no-op rather than a guess.
-
----
-
-## Security Model & Data Locality
-
-Harness runs with a **zero-trust, fully local security model**:
-
-1. **No External APIs:** Harness does not send telemetry, code snippets, or configuration files to external servers. All processing is done locally via native Node.js scripts.
-2. **Credential Protection:** Harness never asks for or stores API keys or secrets. If any terminal command prompts for a password, Harness's rules immediately direct the model to halt and request manual entry by the human partner.
-3. **Execution Gating:** The hook scripts are written in standard CommonJS, ensuring they compile and run fast (<200ms) to prevent blocking terminal operations.
+# Harness Architecture
+
+This document describes the internal architecture, lifecycle, and integration boundaries of the Harness behavior layer. The current cross-platform claim boundary is centralized in [platform-capabilities.md](platform-capabilities.md); host sections here must remain consistent with it.
+
+---
+
+## Architectural Overview
+
+Harness is a **system supervisor**, not a universal workflow engine. Skills remain independently useful, while runtime mechanisms establish a small cross-cutting contract around software work.
+
+The architecture follows a mechanism-first skill mesh with a **minimal kernel**:
+
+- classify scope before mutation,
+- require evidence before completion claims,
+- stop repeated same-signature micro-retries and re-plan,
+- leave domain skill selection, ordering, planning style, and delegation to the agent.
+
+> **Do not enforce workflow order. Enforce workflow invariants.**
+
+This is intentionally different from the older design where Tier 2 implied a fixed TDD/checklist pipeline and Tier 3 implied a mandatory Fable/multi-agent pipeline.
+
+```mermaid
+flowchart TD
+    subgraph User_Session [User Session]
+        U([User Request]) --> Boot[bootstrap.js: Session Start / restore]
+    end
+
+    subgraph Kernel [Harness Kernel]
+        Boot --> Preflight[Environment / integration discovery]
+        Preflight --> KR[kernel-router.js]
+        KR --> TR[tier-router.js<br/>classifier + guide discovery]
+        TR --> Inv[Inject minimal invariants]
+        Inv --> Choice[Agent chooses useful skills / tactics]
+    end
+
+    subgraph Execution [Agent-Controlled Execution]
+        Choice --> Tools[Tool calls / edits / tests]
+        Tools --> Evidence{Evidence supports completion?}
+        Evidence -- Yes --> Done[Evidence-backed completion]
+        Evidence -- No --> Retry[Diagnose / iterate]
+    end
+
+    subgraph Defense [Runtime Boundaries]
+        Retry --> CB{Same-signature failure x3?}
+        CB -- No --> Tools
+        CB -- Yes --> ZO[zoom-out / fresh diagnosis]
+        ZO --> Tools
+    end
+
+    subgraph Learning [Optional Learning / State]
+        Done --> Record[Record / self-evolve when useful]
+    end
+
+    style Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
+    style Defense fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
+    style Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
+```
+
+### Router responsibilities
+
+`kernel-router.js` is the public runtime entry point. It delegates heuristic classification and dynamic guide/skill discovery to `tier-router.js`, then converts the result into the Harness contract:
+
+- recommended Tier + rationale,
+- required invariants,
+- advisory skill suggestions.
+
+The kernel deliberately suppresses the old fixed `BASE EXECUTION LOOP` wording so that a host selecting `tdd`, `security-review`, `repo-docs`, or another peer skill cannot accidentally replace or bypass the cross-cutting Harness contract.
+
+`harness-everything` remains the public/manual skill entry point for routing, debugging, and re-routing. `install-cognitive-os` remains the explanatory/manual entry point for the Discover → Think → Try → Summarize → Record policy. Automatic correctness must not depend on either one winning host peer-skill selection first.
+
+---
+
+## Integration Touchpoints
+
+Harness aligns to each host's real capabilities. Enforcement strength is platform-specific; shared skill text does not prove mechanism parity.
+
+### Self-healing and placement
+
+`harness-everything/scripts/self-heal.js` audits supported integration touchpoints and can re-run the idempotent installer to repair missing pieces. If a user intentionally removed an integration, respect that choice.
+
+A platform's native files stay where that platform expects them. Harness-owned runtime state converges under the platform's `harness-everything/` state directory, while skills remain in each platform's native skill location. `manifest.json` records installed artifacts so uninstall can remove only Harness-owned files.
+
+### Runtime state vs. skill content
+
+Runtime state includes hook metadata, circuit-breaker counters, handoff/verification timestamps, and WAL-style session state. Skill content is separate and independently discoverable. This separation lets a domain skill remain useful even when a host does not support Harness runtime hooks.
+
+---
+
+## Host Adapters
+
+### 1. Claude Code — hook-enforced
+
+The installer configures native lifecycle hooks and project skills.
+
+- `SessionStart`: `bootstrap.js` restores prior state and audits integrations.
+- `UserPromptSubmit`: `kernel-router.js` establishes routing + invariants before peer/domain skill execution.
+- `PreToolUse`: circuit breaker, boundary/depth/context guards, and subagent scope guards can block supported tool calls.
+- `PostToolUse`: records outcomes/state and tracks repeated failures.
+- `Stop`: `stop-gate.js` prevents an edit batch from being claimed complete without successful verification evidence.
+
+The prompt hook is intentionally lightweight: it does **not** prescribe TODO/TDD/Fable order. It gives the model the rails and lets the model orchestrate itself.
+
+### 2. OpenCode — plugin enforcement, live loading still unverified
+
+`opencode-plugin/` maps supported enforcement behavior to OpenCode's real plugin API. Source-level/mechanism tests exist, but live plugin loading remains unverified; do not promote source/mechanism evidence into a live-host enforcement claim until a real OpenCode session artifact exists.
+
+### 3. Cursor — skills plus advisory rules
+
+The current installer uses `.cursor/skills/` plus `.cursorrules`. Cursor’s documented skill and plugin surfaces are separate from Harness runtime hooks; routing/verification/retry boundaries remain self-directed unless a compatible mechanism is independently verified.
+
+### 4. GitHub Copilot agent surfaces — skills plus advisory instructions
+
+The current installer uses `.github/skills/` plus `.github/copilot-instructions.md`. GitHub’s Agent Skills paths are documented, but no Harness-specific plugin or live session is verified here.
+
+### 5. Codex — local OpenAI plugin plus advisory installer path
+
+Codex has two distinct Harness integration surfaces and documentation must keep them separate:
+
+- The general `--codex` installer path writes Codex-facing skills/instructions such as `AGENTS.md`; where the host only consumes those instructions, that path is advisory.
+- The packaged local OpenAI plugin under `plugins/harness-everything/` includes `.codex-plugin/plugin.json`, all 26 canonical skills, and lifecycle hooks for `SessionStart`, `UserPromptSubmit`, supported local `PreToolUse` / `PostToolUse`, `SubagentStart` / `SubagentStop`, and `Stop`. Those hooks inject the compact session policy, run the invariant-first kernel, track supported edits and verification, and surface subagent scope changes.
+
+The local plugin therefore has **mechanism-tested local enforcement** for the packaged event/tool mappings. This is package evidence, not a live-host claim; the host's hook review/trust flow and a fresh session are still required. Do not infer broader Claude parity for events or tools that are not listed in the package.
+
+The public OpenAI **Skills-only** submission is narrower again: it ships reusable skills and referenced assets, not the local `.codex-plugin` lifecycle hooks. Public reviewer/listing claims must describe skill/workflow behavior rather than local hook enforcement. See [openai-plugin.md](openai-plugin.md).
+
+### 6. Continue.dev — rules documented, skill discovery unknown
+
+The installer writes `.continue/rules/harness.md` with the platform's native rules format and retains `.continue/skills/` as an adapter candidate. The reviewed official Continue documentation does not establish standalone `SKILL.md` discovery, so no skill-loading or hard-gate parity is claimed.
+
+### 7. Hermes Agent — trusted skills plus advisory context
+
+The installer writes `.hermes.md` for explicit project coverage and can install trusted project skills under `.agents/skills/` plus global skills under `~/.hermes/skills/`. Project skill loading remains subject to Hermes trust; no hard-gate parity is claimed.
+
+---
+
+## Cognitive OS and Skill Mesh
+
+The Cognitive OS is a policy layer, not a parent skill that every domain skill must call.
+
+```mermaid
+flowchart LR
+    D[Discover] --> T[Think]
+    T --> Y[Try]
+    Y --> S[Summarize]
+    S --> R[Record]
+    S -- insufficient evidence --> T
+    Y -- same failure x3 --> Z[Zoom Out]
+    Z --> T
+```
+
+A domain skill may have its own lifecycle — for example RED/GREEN/REFACTOR inside `tdd` — without being forced into a global sequence. The only shared obligations are the kernel invariants.
+
+This separation solves the peer-skill routing problem: a strong host may correctly decide that a task primarily needs `tdd` or `security-review`; that choice is allowed. What it cannot silently erase is the routing/evidence/retry contract established by the runtime.
+
+---
+
+## Security Model & Data Locality
+
+Harness runs with a local-first, zero-trust model:
+
+1. **No Harness telemetry:** runtime scripts do not upload project code or state as a Harness service.
+2. **Credential protection:** scripts do not require storing user secrets; interactive credentials remain human-controlled.
+3. **Small hook surface:** hook scripts are local Node.js programs and should stay fast and auditable.
+4. **Explicit enforcement labels:** unsupported/advisory behavior must not be documented as hard enforcement.
+5. **Deterministic regression:** mechanism and routing behavior is tested with executable CI gates rather than inferred from documentation.
+
+---
+
+## Validation Boundary
+
+Static configuration is not enough to claim that a host behaves correctly. Validation is layered:
+
+- syntax/reference/manifest checks prove package integrity,
+- `ci/invariant-routing.test.js` proves the kernel contract and documentation invariants,
+- `ci/doc-capability-consistency.test.js` prevents current platform capability claims from drifting apart,
+- mechanism tests prove supported hook/plugin behavior,
+- live host sessions are required before promoting a source/mechanism-tested adapter to live host enforcement.
+
+The architecture and its Mermaid diagrams are part of that contract. Runtime changes that alter orchestration must update these documents in the same change.

package/docs/audit.md

@@ -0,0 +1,55 @@
+# Harness System Audit Log
+
+Maintainer-facing audit record. If you just want to know whether Harness works and how to verify it yourself, start at [VERIFICATION.md](../VERIFICATION.md) instead — this file records *how the scores below were obtained* and what changed between audit cycles.
+
+> **Historical snapshot boundary:** the scorecard below is the 2026-09-01 audit and is intentionally preserved as evidence of what was measured on that date. Platform capabilities have changed since then (including the OpenAI/Codex local plugin work and the OpenCode plugin implementation). Do not treat the 2026-09-01 platform rows as current-state documentation; use [platform-capabilities.md](platform-capabilities.md) for the current matrix.
+
+**Last self-audited: 2026-09-01**, by running the actual test suite and the VERIFICATION.md recipes on Windows 11 — not by reading the code and assuming it works.
+
+## The 2026-07-23 mis-measurement incident
+
+Seven independent AI-model audits (Gemini 3.1 Pro, Gemini 3.5 Flash, GPT/Copilot on Mistral Medium/Small, and others) ran the same week and disagreed sharply on whether core hooks even functioned. Three of them tested `rule-of-3.js`, `boundary-guard.js`, and `state-persist.js` by piping JSON through `echo '...' | node script.js` in Windows Git Bash, which mangles stdin/TTY state and produced false "broken" verdicts. Re-running the identical payloads through Node's own `child_process` stdin API (the technique VERIFICATION.md's recipes now use) showed every one of those mechanisms working exactly as documented — the scores below reflect that corrected, verified state, not the average of the seven reports.
+
+This incident is why VERIFICATION.md's recipes were rewritten to be Windows-safe (`node -e` stdin instead of a shell `echo` pipe), and why the §2 mechanism checks were automated as `ci/mechanism-test.js` (`npm run test:mechanism`) — copy-paste recipes that can be mis-executed are not a reliable verification substrate.
+
+## Five Core Verification Criteria (per VERIFICATION.md §5a)
+
+| Criterion | Score | Verified basis |
+|---|---|---|
+| **Skill Description Completeness** | 10/10 | All 26 skill directories present in the 2026-09-01 snapshot had a complete four-row Skill Contract and the required trigger sections. Four PreToolUse hooks remained internal mechanisms, not standalone skills. |
+| **Routing Accuracy** | 9/10 | The local router passed 34/34 positive prompts across all 26 skills in that snapshot, including the foundation and meta routes added in the audit. Waza verification was not runnable in that Windows checkout; ambiguous/metaphorical generalization remained unmeasured. |
+| **Test Coverage of All Skills** | 9.5/10 | `npm test` included syntax, CLI, routing matrix, positive route coverage, references, behavioral-case structure, Fable contract, and mechanism checks at the time. Waza and live model sessions remained separate CI/on-demand evidence. |
+| **Configuration Balance** | 8.5/10 | **Historical 2026-09-01 result:** hard `exit(2)` blocking hooks were measured on Claude Code and the other then-installed platform paths were evaluated as advisory. This row predates the later OpenAI/Codex local plugin and OpenCode plugin work; see `docs/platform-capabilities.md` for current status. |
+| **Workflow Conformance** | 8.5/10 | Every skill in the snapshot had a matching workflow document, and `ci/skill-routing-check.js` executed every positive route case against the real router. Runtime tool-call sequence conformance remained host-dependent and was not claimed. |
+
+## Overall Scorecard
+
+| Category | Score | Notes |
+|---|---|---|
+| **Architecture** | 9/10 | Per-session state isolation, per-platform state directories, fail-open-by-default hooks — all re-verified directly against `hooks/scripts/lib/harness-state.js` in the 2026-09-01 audit. |
+| **Test Coverage** | 9/10 | Deterministic checks covered syntax, routing, skill references, release-tag catalog, install tree/version drift, behavioral-case structure, and 12 mechanism suites at the time. Live model evaluation remained on-demand and was not represented by a local simulation. |
+| **README Completeness** | 9.5/10 | Catalog counts, layer labels, route coverage, and the local baseline matched the then-current 26-skill tree. |
+| **Maintainability** | 9/10 | The custom cross-session todo CLI and obsolete multi-agent compatibility stubs were absent; route coverage was a deterministic regression gate. |
+| **Skills Design** | 9.5/10 | All 26 skills in the snapshot used the same four-row Skill Contract and exact trigger-section contract; internal hooks remained intentionally non-routable. |
+| **Agent Compatibility** | 9/10 | **Historical 2026-09-01 result:** full hard-mechanism support was measured on Claude Code and advisory fallback on the other installer targets then covered by the audit. This is not the current platform matrix. |
+| **Beginner Friendliness** | 7.5/10 | Quick Start was genuinely 10 seconds, but Tier Routing / Rule of 3 / session-scoped state were load-bearing concepts a newcomer had to absorb before the system's behavior made sense. Not addressed in that audit round. |
+
+## Change log by audit cycle
+
+### 2026-09-01
+- Fable v3 integration exposed explicit Haiku, Sonnet, and Opus entrypoints, with deterministic model selection and visible inline fallback or blocked escalation in `fable-mode/model-matrix.json` and `fable-mode/scripts/model-selector.js`.
+- The workflow used native host TODO tracking or Markdown checklists. The older shared TODO CLI/state-machine references below are retained only as historical audit evidence; no current runtime, test, or active workflow depends on them.
+- Strict catalog audit: removed obsolete compatibility directories and stale workflow; added the missing `find-skills` workflow.
+- Corrected documentation and runtime references to the per-session `.claude/harness-everything/state/` path, aligned README/registry layer labels, and removed unimplemented workflow claims.
+- Added `ci/skill-routing-check.js`; all 34 positive routing cases across the 26-skill catalog passed locally, and all positive eval descriptions exactly matched their skill frontmatter.
+
+### 2026-07-26
+- `verify-gate.js` was no longer a simulated stub: it discovered the nearest `package.json` (scoped to the enclosing git repo), ran its real `lint`/`test` scripts via the detected package manager (npm/pnpm/yarn/bun), and blocked completion on failure. The `.verify-fail.tmp` injection hook was kept for hermetic mechanism tests, and `HARNESS_SKIP_PROJECT_CHECKS=1` guarded against self-recursion in projects whose test suite itself drove the Harness runtime. When no runnable scripts existed it exited 0 but explicitly warned that no mechanical checks ran — the exit code was not evidence.
+- CI added: `.github/workflows/ci.yml` ran `npm test` on push/PR, closing the "local-gate-only" gap called out in the previous cycle.
+- README restructured to be user-facing (problem → quick start → what gets installed/uninstall → platform support); audit narrative moved to this file.
+- `harness-everything/SKILL.md`: tier-router output wording and the Skill Contract were aligned (router output is the default route, overridable with a one-line reason — previously the contract said "MUST follow" while the script itself said "default, not an order"); section numbering fixed (§5 registry now precedes §6).
+
+### 2026-07-23
+- VERIFICATION.md §2's mechanism checks automated (`npm run test:mechanism`).
+- VERIFICATION.md's test recipes rewritten to be Windows-safe (`node -e` stdin instead of a shell `echo` pipe).
+- Workflow progress was recorded in the host TODO tracker or a Markdown checklist.

package/docs/codex-action-gate.md

@@ -0,0 +1,90 @@
+# Codex action-gate policy
+
+This document records the Codex-specific action-gate contract. It intentionally differs from Claude Code because the two hosts expose different approval semantics.
+
+## Current official capability boundary
+
+Harness treats the current Codex hooks documentation as the release-behavior contract.
+
+### PreToolUse
+
+For Codex, Harness may safely block a covered local tool call with a supported deny/block result or exit code 2. Harness must not emit `permissionDecision: "ask"`: Codex currently parses that value but does not support it as an authorization decision, so relying on it would be fail-open.
+
+The packaged action gate therefore keeps the existing fail-closed behavior for a destructive rule match:
+
+```text
+covered local tool
+    -> PreToolUse
+    -> Harness destructive rule match
+    -> exit 2 / block
+```
+
+An internal failure in this pre-action path also remains fail-closed.
+
+### PermissionRequest
+
+Codex exposes a separate `PermissionRequest` lifecycle event when Codex is already going to request approval. A PermissionRequest hook can refine that request, but the event is not a mechanism for manufacturing an approval prompt for an otherwise permitted command.
+
+Harness therefore registers `codex-permission-request.js` as an observer only:
+
+- it records that Codex entered its native approval flow;
+- it records the Harness rule match when the current rule table recognizes the tool input;
+- it stores a SHA-256 of the exact tool input rather than the raw command/tool arguments;
+- it returns no `allow`, `deny`, or `ask` decision;
+- an observer/audit failure returns no authorization decision, so Codex's already-active native approval flow remains authoritative.
+
+The current documented PermissionRequest payload does not provide the same `tool_use_id` correlation used by PreToolUse/PostToolUse. PermissionRequest evidence therefore explicitly records `exactToolCallCorrelation: false` and uses only the turn id plus the payload hash for limited correlation.
+
+### PostToolUse
+
+Codex uses the documented `PostToolUse` lifecycle for completion evidence, including non-zero Bash outcomes. Harness does not declare a Codex `PostToolUseFailure` hook.
+
+`codex-action-gate-post.js` is kept in canonical `hooks/scripts/` and copied into the plugin package by `sync-openai-plugin.js`. This prevents a package sync from deleting the Codex-only adapter.
+
+## Native execpolicy prompt rules
+
+Codex rules/execpolicy can express native `prompt` decisions for command prefixes. That is a promising native confirmation path, but Harness does not automatically install or bundle those rules yet.
+
+Reasons:
+
+1. the plugin packaging contract does not establish a plugin-owned execpolicy-rules component that Harness can assume is installed and active;
+2. execpolicy is an approval/sandbox layer and is not proven to cover every destructive operation that may already be allowed in the active sandbox;
+3. rule activation and approval behavior must be verified in the real Codex host before a hard safety guard is weakened.
+
+Until live evidence establishes a guaranteed native approval path for a matched action, a Harness destructive match remains a hard PreToolUse block.
+
+## Required live verification before native-prompt delegation
+
+A future change may delegate selected destructive rules to Codex-native prompting only after preserving evidence for at least:
+
+- `approval_policy = "on-request"`;
+- `approval_policy = "never"`;
+- granular approvals with rules enabled;
+- `approvals_reviewer = "user"`;
+- `approvals_reviewer = "auto_review"`;
+- plugin-hook trust/review enabled in the actual host;
+- Windows and one Unix-like environment where practical.
+
+The evidence must distinguish:
+
+```text
+Harness PreToolUse block
+Codex execpolicy/native prompt
+PermissionRequest defer/allow/deny
+PostToolUse execution result
+```
+
+Package and mechanism tests must not be promoted to `Live verified` in the compatibility matrix.
+
+## Tool coverage
+
+Current Harness PreToolUse enforcement remains wired to the tool set explicitly covered by the package (`Bash|apply_patch`). Codex hooks can cover additional local function/MCP tools, but those tools must not be claimed as action-gated until Harness has a safe classifier/rule representation for their structured inputs. Hosted or specialized tool paths may have different hook behavior and remain outside this guarantee unless separately verified.
+
+## References
+
+- Codex Hooks: https://developers.openai.com/codex/hooks
+- Codex Rules: https://developers.openai.com/codex/rules
+- Codex agent approvals and security: https://developers.openai.com/codex/agent-approvals-security
+- Codex configuration reference: https://developers.openai.com/codex/config-reference
+
+Related tracking: #82, #85, #98, #100, #109, #110.

package/docs/issue-20-rollup.md

@@ -0,0 +1,47 @@
+# Issue #20 umbrella rollup
+
+This rollup turns issue #20's historical checklist into bounded acceptance decisions. The review snapshot is `main` at `ba7853b`, checked on 2026-09-07. The umbrella owns coordination and release evidence; implementation details remain with the linked issue.
+
+## Closure status
+
+Issue #20 remains open after this PR. This branch adds deterministic parser,
+collision-gate, plugin-runner, and negative-control coverage, but it does not
+provide live opencode session evidence, a paid behavioral rerun, the proposed
+100-case study, or the three skill-specific improvements below. Those gaps are
+recorded explicitly rather than treated as closed by the deterministic gates.
+
+## Workstream decisions
+
+| Workstream | Evidence in the review snapshot | Acceptance state | Remaining claim boundary |
+| --- | --- | --- | --- |
+| #37 opencode enforcement | The real plugin API is implemented and mechanism coverage exists in `ci/mechanism-2n-opencode-plugin.test.js`; the integrated reflection lifecycle is `d790e7f` on the integration branch. | Integrated, pending final integration gates | No live opencode loading or session smoke evidence was available; do not claim live enforcement. |
+| #52 behavioral transcript parsing | Claude stream fixtures and parser coverage are integrated in `77efb06`; deterministic parser tests are available. | Integrated, pending final integration gates | No new paid behavioral rerun is part of this umbrella. Parse failures and missing tool visibility remain evidence states, not skill failures. |
+| Systematic gate hardening | The local gates now execute real negative controls; YAML frontmatter parsing fails closed in `ci/description-collision.js`, `ci/routing-check.js` skips clearly when waza is absent, and `ci/mechanism-2t-issue-20.test.js` covers CRLF behavioral parsing and plugin validation. | Deterministic hardening integrated | Live platform loading and model behavior remain unverified. |
+| #42 workspace identity and migration | Workspace-keyed state and migration coverage are integrated in `9dd2e3d`; the issue review identified session and migration acceptance as the relevant boundary. | Integrated, pending final integration gates | Do not claim every host/session migration path is live verified until the integration gate and targeted fixtures pass. |
+| #43 multi-agent workspace layout | The reviewed plan makes its root contract depend on #42. No implementation commit was present in the issue #20 review snapshot. | Deferred to its owner | Do not duplicate its layout or runtime work in this umbrella. |
+| #44 progressive disclosure | Documentation and reference checks are integrated in `b33f598`; `ci/disclosure-check.js` and its mechanism coverage are present. | Integrated, pending final integration gates | This records repository documentation evidence; it does not establish behavioral-model effectiveness. |
+| #56 behavioral rubric triage | The review found grader/source-boundary issues, including `command_exit_0` proving the grader command rather than the agent action. | Deferred to its owner | Do not reuse the historical pass-rate claims until the rubric and trace evidence are corrected. |
+| Extended 100-case study | The original issue proposed 100 cases, but the review did not establish a decision threshold or clean attribution between skill text, plugin enforcement, and grader behavior. | Explicitly deferred | No uncontrolled 100-case run is authorized by this rollup. Define paired design, failure taxonomy, and decision rule first. |
+| Five historical baseline failures | The committed 2026-08-27 records show one failed expectation in each of `baseline-debugging` (edge-case consideration), `baseline-performance` (binary-search suggestion), `baseline-security-review` (MD5 identification), `baseline-simple-bugfix` (function understanding), and `verify-before-done` (verification actually run). | Explicitly deferred | These are historical observations, not a new causal investigation or rerun; do not claim they were fixed by this PR. |
+| Skill-specific improvements | No targeted changes were made to `verification-loop`, `zoom-out`, or `security-review` in this branch. | Explicitly deferred | Strengthening verification enforcement, reflection-report detection, and vulnerability detection requires separate design and behavioral evidence. |
+| Release | The tag-triggered full gate and provenance publish workflow already exists. Historical `0.3.6` evidence is recorded in [docs/release-evidence.md](release-evidence.md). | Documentation complete; next release unproven | A prepared `0.3.7-beta` version is not evidence of a tag, npm publication, or GitHub release. |
+
+## Focused acceptance checks
+
+The integration owner should run these checks after incorporating the issue branches:
+
+```text
+npm test
+npm run test:mechanism
+npm run test:consistency
+npm run test:references
+npm run test:release
+npm run test:collision
+npm run test:routing:skills
+```
+
+The checks establish deterministic repository and routing health. They do not substitute for live opencode loading, a paid behavioral run, or npm/GitHub release evidence. Those claims require the artifacts named in [RELEASING.md](../RELEASING.md) and [docs/release-evidence.md](release-evidence.md).
+
+## Historical evidence boundary
+
+The local review artifact `.git/issue-review-20260907/release-evidence.md` records a successful `0.3.6` workflow (`33466676632`) and npm observation. It explicitly says that this is not proof of a `0.3.7-beta` release. This rollup preserves that distinction so an old successful release cannot be mistaken for current publication evidence.