harness-everything 0.3.6 → 0.4.0

package/docs/audit.md

@@ -2,6 +2,8 @@
 
 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
@@ -14,40 +16,40 @@ This incident is why VERIFICATION.md's recipes were rewritten to be Windows-safe
 
 | Criterion | Score | Verified basis |
 |---|---|---|
-| **Skill Description Completeness** | 10/10 | All 26 current skill directories have a complete four-row Skill Contract and the required trigger sections. Four PreToolUse hooks remain internal mechanisms, not standalone skills. |
-| **Routing Accuracy** | 9/10 | The local router passes 34/34 positive prompts across all 26 skills, including the foundation and meta routes added in this audit. Waza verification is not runnable in this Windows checkout; ambiguous/metaphorical generalization remains unmeasured. |
-| **Test Coverage of All Skills** | 9.5/10 | `npm test` now includes syntax, CLI, routing matrix, positive route coverage, references, behavioral-case structure, Fable contract, and mechanism checks. Waza and live model sessions remain separate CI/on-demand evidence. |
-| **Configuration Balance** | 8.5/10 | Confirmed asymmetric-by-design: hard `exit(2)` blocking hooks on Claude Code, advisory-only text on the other five platforms, with `self-heal.js` auto-repairing missing integration files on every platform. No platform is either silently ignored or over-blocked. |
-| **Workflow Conformance** | 8.5/10 | Every current skill has a matching workflow document, and `ci/skill-routing-check.js` executes every positive route case against the real router. Runtime tool-call sequence conformance remains host-dependent and is not claimed. |
+| **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`. |
-| **Test Coverage** | 9/10 | See above — deterministic checks now cover syntax, routing, skill references, release-tag catalog, install tree/version drift, behavioral-case structure, and 12 mechanism suites. Live model evaluation remains on-demand and is not represented by a local simulation. |
-| **README Completeness** | 9.5/10 | Catalog counts, layer labels, route coverage, and the local baseline now match the current 26-skill tree. |
-| **Maintainability** | 9/10 | The custom cross-session todo CLI and obsolete multi-agent compatibility stubs are absent; route coverage is now a deterministic regression gate. |
-| **Skills Design** | 9.5/10 | All 26 current skills use the same four-row Skill Contract and exact trigger-section contract; internal hooks remain intentionally non-routable. |
-| **Agent Compatibility** | 9/10 | Full hard-mechanism support on Claude Code; verified advisory-text fallback on the other five platforms via `docs/architecture.md` and `scripts/installer.js`. |
-| **Beginner Friendliness** | 7.5/10 | Quick Start is genuinely 10 seconds, but Tier Routing / Rule of 3 / session-scoped state are load-bearing concepts a newcomer has to absorb before the system's behavior makes sense. Not addressed this round. |
+| **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 now exposes 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 current workflow uses native host TODO tracking or Markdown checklists. The older shared TODO CLI/state-machine references below are retained only as historical audit evidence; no runtime, test, or active workflow depends on them.
+- 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 current 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 pass locally, and all positive eval descriptions now exactly match their skill frontmatter.
+- 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` is no longer a simulated stub: it now discovers the nearest `package.json` (scoped to the enclosing git repo), runs its real `lint`/`test` scripts via the detected package manager (npm/pnpm/yarn/bun), and blocks completion on any failure. The `.verify-fail.tmp` injection hook is kept for hermetic mechanism tests, and `HARNESS_SKIP_PROJECT_CHECKS=1` guards against self-recursion in projects (like this one) whose test suite itself drives the Harness runtime. When no runnable scripts exist it exits 0 but explicitly warns that no mechanical checks ran — the exit code is not evidence.
-- CI added: `.github/workflows/ci.yml` runs `npm test` on push/PR, closing the "local-gate-only" gap called out in the previous cycle.
+- `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 now agree (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).
+- `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 is recorded in the host TODO tracker or a Markdown checklist.
+- 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.

package/docs/mechanism-first-skill-mesh.md

@@ -2,7 +2,7 @@
 
 Harness is not intended to be a rigid workflow engine. Its skills should remain independently useful, while still coordinating through lightweight mechanisms that help the model and the software engineer work together with less drift, fewer loops, and better evidence.
 
-The preferred shape is a **mechanism-first skill mesh**: skills are autonomous, coordination is explicit, and enforcement happens at narrow decision points through scripts, hooks, exit codes, and compact return values.
+The preferred shape is a **mechanism-first skill mesh**: skills are autonomous, coordination is explicit, and enforcement happens at narrow decision points through scripts, hooks, exit codes, and compact return values. Platform-specific enforcement claims follow [platform-capabilities.md](platform-capabilities.md).
 
 ---
 
@@ -50,8 +50,8 @@ Example shape:
 ```text
 HARNESS_DECISION
 tier: 2
-load: todo-driven-workflow, verification-loop
-gate: verify-before-final
+required: route-before-execution, verify-before-claim, re-plan-after-repeat-failure
+suggest: todo-driven-workflow, verification-loop
 reason: user requested code changes
 ```
 
@@ -81,57 +81,59 @@ Harness should coordinate skills through small, composable patterns.
 
 ### Router Decision
 
-`harness-everything/scripts/tier-router.js` is the model-facing triage mechanism. It should return the smallest useful routing decision: tier, rationale, suggested skills, and any gate that should apply before editing or final delivery.
+`harness-everything/scripts/kernel-router.js` is the public invariant-first runtime entry point. It delegates classification and guide discovery to `tier-router.js`, then returns the recommended tier, rationale, required invariants, and advisory skill suggestions. It intentionally does not emit a mandatory global execution pipeline.
 
 ### Checklist State
 
-`todo-driven-workflow` should own task decomposition state when a task is Tier 2 or Tier 3. The state should be machine-readable when possible, but the model should not be forced into a single response format.
+`todo-driven-workflow` may own explicit task decomposition state when that helps a Tier 2 or Tier 3 task. It is a suggested tactic, not a universal prerequisite, and the model may use native host TODO tracking or a Markdown checklist instead.
 
 ### Verification Gate
 
-`verification-loop` and `verify-gate.js` should provide the delivery check. Hook-capable platforms can run it automatically before stop; hook-less platforms can run it as an explicit pre-final command.
+`verification-loop` and `verify-gate.js` provide reusable verification mechanisms. Hosts with a compatible stop/completion hook can invoke verification mechanically; instruction-only hosts can call the same verifier explicitly before final delivery.
 
 ### Recovery Gate
 
-`rule-of-3` and `zoom-out` should coordinate through failure signatures and recovery instructions. The key handoff is the observed failure signature, not a prose summary.
+`rule-of-3` and `zoom-out` coordinate through failure signatures and recovery instructions where the host exposes the required lifecycle/tool hooks. On hosts without those hooks, `zoom-out` remains usable as an explicit recovery discipline, but the automatic failure counter must not be implied.
 
 ### Skill Suggestion
 
-`self-evolve` and generated skills should feed the router through manifest metadata. The router should surface likely skills, but the model keeps final responsibility for selecting what actually applies.
+`self-evolve` and generated skills feed the router through manifest metadata. The router should surface likely skills, but the model keeps final responsibility for selecting what actually applies.
 
 ---
 
 ## Platform Strategy
 
-Harness should use the strongest mechanism each platform provides.
+Harness should use the strongest mechanism each installation surface actually provides.
 
 | Platform class | Preferred coordination style | Enforcement level |
 | --- | --- | --- |
-| Hook-capable platforms | Hooks run routers, guards, trackers, and stop gates automatically | Mechanical blocking is possible |
-| CLI/tool-capable but hook-less platforms | The model explicitly calls Harness scripts at decision points | Mechanism-guided, not automatically enforced |
-| Prompt-only platforms | Advisory instructions include command snippets and decision rules | Self-regulated by the model |
+| Hook/plugin-capable surfaces | Hooks/plugins run routers, guards, trackers, or completion gates automatically | Mechanical injection/blocking is possible for the mechanisms actually packaged |
+| CLI/tool-capable but hook-less surfaces | The model explicitly calls Harness scripts at decision points | Mechanism-guided, not automatically enforced |
+| Prompt-only surfaces | Advisory instructions include command snippets and decision rules | Self-regulated by the model |
 
-The same skills should work across all three classes. The difference is whether the mechanism is invoked automatically, explicitly, or only described.
+One host may expose more than one surface. Codex is the important example: the general `--codex` installer path is instruction/advisory oriented, while the **local OpenAI plugin** packages session, prompt, supported-tool, subagent, and stop hooks for mechanism-tested runtime enforcement. The public OpenAI **Skills-only** submission does not include those local lifecycle hooks.
+
+OpenCode is plugin-capable and has mechanism coverage, but live plugin loading remains unverified. Claude Code has the broadest currently verified Harness lifecycle-hook surface.
 
 ---
 
-## Guidance for Hook-Less Platforms
+## Guidance for Instruction-Only / Hook-Less Paths
 
 Do not recreate hooks with a rigid universal handoff template. Instead, make mechanisms easy to call.
 
 Implemented today, both wired into `bin/cli.js` and referenced by name in the advisory text each platform's installer writes (`scripts/lib/advisory-text.js`):
 
-- `npx github:dyphn1/Harness-everything next "<prompt>"`: wraps `tier-router.js`, printing the recommended tier, base execution loop, and matching knowledge guides for a prompt.
-- `npx github:dyphn1/Harness-everything verify`: wraps `verify-gate.js`, running the target project's own lint/test scripts and exiting non-zero on failure. This is the explicit, hookless stand-in for Claude Code's `stop-gate.js`.
+- `npx github:dyphn1/Harness-everything next "<prompt>"`: runs the Harness routing path and prints the recommended tier, invariant contract, and matching knowledge/skill suggestions.
+- `npx github:dyphn1/Harness-everything verify`: wraps `verify-gate.js`, running the target project's own lint/test scripts and exiting non-zero on failure. This is the explicit hook-less verification path; it is not equivalent to claiming that a host automatically runs a `Stop` hook.
 
-Both resolve their target scripts relative to the CLI's own package install, not the caller's cwd, so they work the same way regardless of which platform-specific directory (`.codex/skills/`, `.cursor/skills/`, `.github/skills/`, ...) a copy of the `harness-everything` skill also happens to be sitting in - a fixed relative path like `harness-everything/scripts/tier-router.js` would silently point at nothing depending on which platform installed it.
+Both resolve their target scripts relative to the CLI's own package install, not the caller's cwd, so they work the same way regardless of which platform-specific directory (`.codex/skills/`, `.cursor/skills/`, `.github/skills/`, ...) a copy of the `harness-everything` skill also happens to be sitting in — a fixed relative path like `harness-everything/scripts/tier-router.js` would silently point at nothing depending on which platform installed it.
 
-Not yet implemented - still aspirational, do not reference these as if they exist until they're built:
+Not yet implemented — still aspirational, do not reference these as if they exist until they're built:
 
-- `harness recover`: summarize repeated failure signatures and recommend `zoom-out` when needed. Blocked on hookless platforms not having anything that collects failure signatures the way `rule-of-3.js`'s `PostToolUse` hook does on Claude Code - the state to summarize doesn't exist yet.
+- `harness recover`: summarize repeated failure signatures and recommend `zoom-out` when needed. Hook-less paths do not collect failure signatures the way the Claude Code `PostToolUse` mechanism does, so there is no reliable state to summarize yet.
 - `harness skills`: list installed, generated, and matching skills for the current workspace.
 
-These commands let Codex, Cursor, Copilot, Continue, and Hermes receive high-signal mechanical feedback without forcing them into a single scripted conversation shape.
+These commands let instruction-only Codex installs, Cursor, Copilot, Continue, and Hermes receive high-signal mechanical feedback without forcing them into a single scripted conversation shape.
 
 ---
 

package/docs/openai-plugin.md

@@ -0,0 +1,118 @@
+# OpenAI / ChatGPT Plugin Packaging
+
+Harness Everything ships an Agent Plugin package under `plugins/harness-everything/`. The root skill directories remain canonical; packaged copies are synchronized from them.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    U([User prompt]) --> H[UserPromptSubmit hook]
+    H --> K[Harness Kernel Router]
+    K --> I[Required invariants]
+    I --> A[Agent chooses useful domain skills]
+    A --> E[Execute / inspect / edit]
+    E --> P[PreToolUse guards]
+    P --> T[Supported local tool]
+    T --> Q[PostToolUse state and evidence]
+    Q --> V{Objective evidence?}
+    V -->|yes| D[Evidence-backed completion]
+    V -->|no| R[Diagnose and retry]
+    R --> F{Same-signature failure x3?}
+    F -->|no| E
+    F -->|yes| Z[Zoom out / re-plan]
+    Z --> E
+
+    S[SessionStart hook] --> C[Cognitive OS policy]
+    C --> K
+    G[SubagentStart / Stop] --> A
+    X[Stop hook] --> V
+```
+
+The local OpenAI adapter enforces cross-cutting invariants through the lifecycle events that it packages. Tier-specific skills remain advisory; the model may choose, combine, reorder, or skip them. Tool enforcement is limited to the host tool names declared in `hooks/hooks.json`.
+
+## Package layout
+
+```text
+plugins/harness-everything/
+├── plugin.json                 # portable Agent Plugin manifest
+├── .codex-plugin/plugin.json   # Codex compatibility manifest
+├── hooks/
+│   ├── hooks.json
+│   ├── session-start.js
+│   └── scripts/                # shared runtime hook dependencies
+└── skills/                     # 26 synchronized canonical skills
+```
+
+The portable manifest follows the Agent Plugins schema and uses a root `skills/` directory. OpenAI-specific hook and interface metadata lives under `extensions.com.openai`; the compatibility manifest keeps the legacy `.codex-plugin` shape for clients that still expect it. These are two distribution manifests for the same package, not two different products.
+
+The package is intentionally skill-only: it does not declare `mcpServers` or `apps`. Hooks are a local package capability and require the host’s trust/review flow; they are not a claim that every OpenAI surface provides the same lifecycle enforcement.
+
+Run:
+
+```bash
+npm run plugin:sync
+npm run test:plugin:openai
+npm run test:plugin:submission
+```
+
+`plugin:sync` refreshes package copies from canonical skill directories and copies the shared hook runtime/dependencies into the package. Text parity is normalized to LF so the same package is reproducible from Windows and Unix checkouts. The checks compare both skill trees byte-for-byte, validate both manifest forms, execute local hook entry points, and verify deterministic routing/runtime behavior.
+
+## Managed ChatGPT workspace import
+
+OpenAI documents GitHub marketplace import for workspace administrators. The repository provides both `.agents/plugins/marketplace.json` and `.claude-plugin/marketplace.json`; the source entry resolves to `plugins/harness-everything/`.
+
+Use the repository URL as the source, leave Path empty so the marketplace is read from the repository root, and select the intended branch (normally `main`). In ChatGPT, use **Workspace settings > Plugins > Add > Import marketplace**, review the import results, and set the workspace installation policy. OpenAI documents automatic daily synchronization and a **Sync now** action for later refreshes.
+
+This repository contains the marketplace/package artifacts and deterministic import-shape checks. It does not contain a managed-workspace import report or a fresh host smoke-test artifact, so those operations remain `Unknown` in the compatibility matrix.
+
+Official documentation: [Importing and syncing plugin marketplaces from GitHub](https://help.openai.com/en/articles/20001504-importing-and-syncing-plugin-marketplaces-from-github) and [Plugins in Codex](https://help.openai.com/en/articles/20001256-plugins-in-codex).
+
+## Local Codex / OpenAI package
+
+The local package path is distinct from the general `--codex` installer. The general installer writes advisory `AGENTS.md` and repo-scoped `.agents/skills/`; the plugin package additionally contains local session, prompt, supported-tool, subagent, and stop hooks.
+
+The package tests prove the following repository-side contract:
+
+- the portable root manifest and `.codex-plugin` compatibility manifest agree on identity, version, interface, and hook entry point;
+- the root `skills/` tree contains exactly the 26 canonical skills;
+- Windows and POSIX hook commands resolve through `PLUGIN_ROOT`;
+- session start emits the compact policy and prompt submission invokes invariant-first routing;
+- supported local `Bash` and `apply_patch` calls receive the packaged guards and state tracking;
+- subagent lifecycle and stop verification contracts are covered;
+- identical routing input produces identical output.
+
+These are package/mechanism results. They do not prove that a live Codex or ChatGPT host loaded the package; a preserved host/session artifact is required for that claim. OpenAI’s current event/tool contract is documented in the [Codex/ChatGPT hooks reference](https://learn.chatgpt.com/docs/hooks).
+
+## Public Skills-only submission
+
+OpenAI’s public submission flow supports a **Skills only** plugin. This is separate from managed-workspace marketplace import and from the local hook-capable package.
+
+Build the final upload from the synchronized package:
+
+```bash
+npm run plugin:submission:build
+```
+
+The generated ZIP contains only `skills/<name>/...` files from `plugins/harness-everything/skills/`. It does **not** include the local `.codex-plugin` lifecycle hooks, MCP definitions, or a fake app wrapper. The generated manifest records every path, byte count, file hash, and final bundle hash; repeated builds from the same revision must match.
+
+The submission source files in [`../submission/openai/`](../submission/openai/) model the official review inputs: listing metadata, starter prompts, release notes, exactly five positive cases, and exactly three negative cases. Positive cases specify the prompt, expected skill/workflow behavior, expected result shape, and fixture/account data. Negative cases specify the prompt/scenario, expected refusal/clarification/safe fallback, and why completion is not appropriate.
+
+The official portal flow is: **Create plugin → Skills only → upload the final skill bundle → provide review cases and listing metadata → complete identity, availability, policy, and access requirements → submit for review → publish after approval**. The repository cannot complete verified identity, logo upload, availability selection, Apps Management write access, review, approval, or public-directory publication.
+
+Official documentation: [Submit a plugin](https://developers.openai.com/plugins/deploy/submission) and [Build plugins](https://developers.openai.com/plugins/build/plugins).
+
+## Evidence boundary
+
+The local plugin and public Skills-only artifact must not be conflated:
+
+| Artifact | Repository evidence | Claim that is safe today |
+| --- | --- | --- |
+| Portable/root plugin package | Manifest, tree, hook, and routing mechanism tests | Package shape and local mechanism are verified |
+| Managed workspace marketplace | Marketplace JSON and source-path checks | Import-ready repository artifact; live import remains unverified |
+| Public Skills-only ZIP | Deterministic builder and 5+3 review-input checks | Reproducible skills bundle; approval and live public behavior remain unverified |
+
+See the [platform capability matrix](platform-capabilities.md) for the complete ten-dimension status table and official source URLs.
+
+## Publication smoke checklist
+
+Before public submission, run `plugin:sync`, both OpenAI package checks, and the platform compatibility check. Confirm all 26 skills are content-identical to canonical sources after EOL normalization, the ZIP is reproducible, public links are current, the publisher identity and Apps Management access are ready, and final reviewer-facing cases run against the exact submitted skills tree.

package/docs/philosophy.md

@@ -1,47 +1,58 @@
 # Harness Philosophy
 
-Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.** 
+Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.**
 
-Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral runtime**—a lightweight, non-intrusive layer that guides, guards, and immunizes.
+Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral layer** — reusable skills plus the strongest lightweight runtime mechanisms each supported installation surface actually provides.
+
+The current mechanism/enforcement boundary is platform-specific; see [Platform Capability Matrix](platform-capabilities.md). A skill-only or instruction-only install must not be described as if it automatically runs lifecycle hooks.
 
 ---
 
 ## The Core Philosophy: Intervene Only When Necessary
 
-Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it destroys the model's creative problem-solving capability when tackling complex, novel engineering challenges.
+Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it can suppress useful model judgment on complex, novel engineering work.
 
 Harness takes the opposite approach:
 
-1. **Model Autonomy is Paramount:** The model should have full freedom to explore, choose its tools, and design its solution.
-2. **Context-Driven Guidance:** Harness injects high-context, low-friction signals (via hooks, rules, and local preflight checks) rather than forcing rigid execution paths.
-3. **Reactive Guardrails:** Harness remains completely silent and out of the way until a critical failure state is detected (e.g., repeating the same error 3 times, or context bloat reaching a dangerous threshold).
-4. **Behavior-First, Not Prompt-First:** Harness is not a collection of static templates or "magic prompts." It is a dynamic runtime that reacts to terminal outcomes, git status, and actual workspace conditions.
+1. **Model Autonomy is Paramount:** The model should have freedom to explore, choose useful skills/tools, and design its solution inside a small set of cross-cutting invariants.
+2. **Context-Driven Guidance:** Harness uses high-context, low-friction signals — skills, rules, local checks, and hooks/plugins where the host supports and packages them — rather than one rigid global execution path.
+3. **Reactive Guardrails:** On integration surfaces that expose the required lifecycle/tool hooks, Harness can stay quiet until a boundary is violated or a repeated failure is detected. On advisory surfaces, the same principles remain guidance rather than automatic blocking.
+4. **Behavior-First, Not Prompt-First:** Harness is not a collection of magic prompts. Its skills remain independently useful, while supported runtime adapters can react to real tool/session outcomes and workspace conditions.
 
 ---
 
 ## The 4 Pillars of AI Model Guidance
 
-To keep agents aligned and productive, Harness operates across four distinct domains:
+To keep agents aligned and productive, Harness operates across four distinct domains. The **principle** applies everywhere; whether it is injected or enforced automatically depends on the selected host surface.
 
 ### 1. Environment Alignment (Discovery over Assumption)
-AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shells, or package managers (especially on Windows or within sandboxed shells). 
-Harness forces a **Discovery** phase immediately upon session start. By auditing the environment beforehand, the model knows exactly what commands are safe to run, preventing wasted tokens on syntax trial-and-error.
+
+AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shell, or package manager — especially on Windows or mixed-shell setups.
+
+Harness requires environment assumptions to be discovered rather than guessed. On surfaces that package a session-start/preflight hook, that context can be injected automatically. On instruction/skill-only paths, the agent must discover it explicitly before relying on shell-specific commands.
 
 ### 2. Guardrails (The Circuit Breakers)
-When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly (the "infinite loop of trial-and-error"). 
-Harness implements a **Circuit Breaker** (the `Rule of 3`). If the exact same failure occurs three times, Harness halts execution and forces a "zoom out": the agent must rebuild the full picture and fact-check the assumptions behind its failed attempts before it may touch the code again. Most loops die right there, resolved by a fresh diagnosis. The human partner is asked to step in only when a genuine decision is on the table — a requirement conflict, an architecture trade-off, a destructive step — preserving both your token budget and your sanity.
+
+When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly.
+
+The Harness recovery invariant is to stop same-signature micro-retries and re-plan after repeated failure. On hosts where the Rule-of-3 mechanism is actually packaged, a circuit breaker can track failures and block further mutation until a `zoom-out` diagnosis is performed. On other surfaces, `zoom-out` remains a reusable recovery discipline but there is no claim that an automatic counter/blocker exists.
 
 ### 3. Context Preservation (Anti-Bloat Protection)
-As sessions grow, models often read too many large files or run commands that generate massive output, causing severe "Lost in the Middle" attention degradation. 
-Harness acts as an informational dashboard that tracks active file counts and staging queues, proactively nudging the model to commit changes, clean the terminal, or compact its context.
+
+As sessions grow, models can read too broadly or produce oversized output, degrading active context.
+
+Harness uses narrow reads, explicit scope, compact evidence, and — where a compatible runtime adapter exists — boundary mechanisms that can react mechanically. Skill-only surfaces still receive the discipline, but not an imaginary background daemon or hook.
 
 ### 4. Self-Evolution (Continuous Workspace Memory)
-When a complex issue is resolved, the model should never have to solve it again. Harness abstracts the underlying root cause and permanently saves it to local workspace rules. On subsequent sessions, the model immediately imports these lessons, preventing regression.
+
+When a complex issue is resolved, Harness can turn the verified lesson into durable workspace knowledge through `self-evolve`: a concise rule or a reusable generated skill, when persistence is actually justified.
+
+This long-term learning path is distinct from **runtime session state** such as WAL/checkpoint files. Runtime state exists only on integrations that package the corresponding state hooks; reusable rules/skills are project artifacts and can outlive a single host session.
 
 ---
 
 ## A Non-Intrusive Cognitive Amplifier
 
-Harness does not run a heavy daemon, send your code to third-party APIs, or lock you into a proprietary ecosystem. It runs entirely locally within your project, acting as a quiet guardian that ensures your AI sessions are efficient, secure, and successful.
+Harness does not require a heavy daemon or a proprietary service. The repository's mechanisms and skill content operate locally in the developer/host environment, while each platform gets only the enforcement strength its real integration supports.
 
-For the skill-level coordination philosophy, see [Mechanism-First Skill Mesh](mechanism-first-skill-mesh.md). It explains why Harness prefers autonomous skills coordinated by scripts, hooks, exit codes, and compact return values over a single rigid handoff template.
+For skill-level coordination, see [Mechanism-First Skill Mesh](mechanism-first-skill-mesh.md). For the exact current platform/install/evidence boundary, see [Platform Capability Matrix](platform-capabilities.md).