harness-everything 0.3.6 → 0.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
-Harness is a lightweight, local behavior and orchestration runtime that wraps around your AI development sessions (Claude Code, Cursor, Copilot Chat, Codex, Continue.dev, Hermes Agent). It provides reactive hooks, routing boundaries, and circuit breakers designed to prevent infinite trial-and-error loops, costly over-engineering, and "lost-in-the-middle" context drift.
+Harness is a lightweight, local behavior and orchestration runtime that wraps around your AI development sessions (Claude Code, Cursor, GitHub Copilot agent surfaces, Codex, Continue.dev, Hermes Agent). It provides reactive hooks, routing boundaries, and circuit breakers designed to prevent infinite trial-and-error loops, costly over-engineering, and "lost-in-the-middle" context drift.
 
 ---
 
@@ -19,26 +19,28 @@ AI coding agents are highly capable, but they struggle with self-regulation, env
 
 Harness acts as an automated system supervisor. It remains completely silent and out of the way, intervening only when execution boundaries are violated or failures are detected.
 
+Harness deliberately follows a **minimal rails, maximum freedom** design: the runtime enforces only a few cross-cutting invariants — route before execution, verify before claim, and re-plan after repeated identical failure — while capable agents remain free to choose, combine, reorder, or skip domain skills according to the task.
+
 ### Comparison: Prompt vs. Skill vs. Harness
 
 | Dimension | Prompt-Only (Custom Instructions) | Skill-Only (Task Guides) | Harness (Behavior Layer) |
 |---|---|---|---|
-| **Activation** | Always loaded (wastes prompt space) | Loaded on demand (requires manual trigger) | Reacts dynamically via native lifecycle hooks |
-| **Fail-Safe** | No protection (model keeps retrying) | No protection (loops until token limit) | **Circuit Breaker:** Halts execution after 3 failures and alerts human |
-| **Context Aware** | High risk of lost-in-the-middle bloat | Manages scope manually | **Bloat Shield:** Proactively audits diff sizes and logs warning alerts |
-| **System Audit** | Blindly assumes shell syntax | Requires manual shell check | **Preflight:** Proactively detects Windows/Unix paths, shell type, and package manager |
-| **Memory** | Resets on every new chat session | Static text rules | **Continuous Persistence:** Writes Write-Ahead Logs (WAL) for session recovery and immunizes workspace rules |
+| **Activation** | Always loaded (wastes prompt space) | Loaded on demand (requires manual trigger) | Reacts dynamically when the selected host surface exposes compatible hooks/plugins |
+| **Fail-Safe** | No protection (model keeps retrying) | No protection by itself | Can add mechanical retry/verification boundaries on surfaces that package those mechanisms |
+| **Context Aware** | High risk of lost-in-the-middle bloat | Manages scope manually | Can add preflight/boundary mechanisms where the host exposes the required lifecycle/tool hooks |
+| **System Audit** | Blindly assumes shell syntax | Requires manual shell check | Uses environment detection and explicit verification paths instead of assuming one shell/runtime |
+| **Memory** | Resets on every new chat session | Static text rules | Stateful hook/plugin integrations can persist bounded runtime state; instruction-only integrations cannot |
 
-The "Harness" column above is Claude Code's behavior. On Cursor, Copilot, Codex, Continue.dev, and Hermes Agent — platforms with no hook/exit-code execution mechanism — Harness can only inject advisory text, which lands in the **Prompt-Only** column instead. See [Supported AI IDEs & Tools](#supported-ai-ides--tools) below.
+The exact "Harness" behavior depends on the installation surface. Claude Code has the broadest currently verified lifecycle-hook coverage. OpenCode has a real plugin implementation with deterministic mechanism tests, but **live loading remains unverified**. Codex has both an advisory `--codex` installer path and a **local OpenAI plugin** path with mechanism-tested session, prompt, supported-tool, subagent, and stop hooks. The public OpenAI **Skills-only** submission is narrower and does not include those local lifecycle hooks. See [Supported AI IDEs & Tools](#supported-ai-ides--tools) and [docs/platform-capabilities.md](docs/platform-capabilities.md).
 
 ### When should I use Harness?
 * You regularly use agentic coding tools (like Claude Code, Cursor, or Copilot) on medium-to-large codebases.
 * You develop on Windows or in mixed shells (Git Bash, WSL, PowerShell) where agents frequently get shell syntax wrong.
-* You want automated test-driven development (TDD) enforcement and safety guards to save token budgets.
+* You want lightweight routing, objective verification, and failure-loop safety without forcing every task through a rigid workflow.
 
 ### When should I NOT use Harness?
 * You only use chat interfaces for general questions without letting the AI run local commands or modify files.
-* Your project has no test suite, or you prefer unconstrained, free-form agent generation.
+* You deliberately want completely unconstrained execution with no routing, verification, or retry boundaries.
 
 ---
 
@@ -46,40 +48,52 @@ The "Harness" column above is Claude Code's behavior. On Cursor, Copilot, Codex,
 
 Harness integrates directly into your workspace. There is no heavy daemon, no paid external APIs, and zero configuration required.
 
+**Runtime:** Harness supports **Node.js 22+**. Node.js **24** is the primary/recommended development and CI runtime (`.nvmrc`). The generated current-state runtime/workflow summary is [docs/repository-contract.md](docs/repository-contract.md).
+
 ```bash
 # Option A: Claude Code plugin (marketplace manifest included)
 #   /plugin marketplace add dyphn1/Harness-everything
 #   /plugin install harness-everything
 
-# Option B: install Harness hooks and skills into your current workspace
+# Option B: install Harness hooks/skills/advisory integrations into your workspace
 npx github:dyphn1/Harness-everything install
+
+# OpenAI/Codex local plugin packaging is repository-owned under:
+#   .agents/plugins/marketplace.json
+#   plugins/harness-everything/.codex-plugin/plugin.json
+# See docs/openai-plugin.md for local import/install and public Skills-only submission.
 ```
 
 ### Expected Behavior After Installation:
-1. **Hook Registration:** Harness registers native hooks (e.g., inside `.claude/settings.json` for Claude Code) to intercept session starts and tool use.
-2. **Preflight Audit:** At session startup, a lightweight preflight script runs, printing a diagnostic environment block that tells the agent your exact OS, active shell, and package manager.
-3. **Guard Active:** The circuit breaker and context compactors are active in the background, consuming zero overhead unless triggered.
+1. **Use the selected surface's real mechanism:** Claude Code hooks, the local OpenAI plugin lifecycle hooks, OpenCode's plugin API, or advisory instructions depending on what you installed.
+2. **Preflight / session context where packaged:** Hook-capable surfaces can inject environment/session context automatically; advisory-only surfaces must not be described as if they do.
+3. **Verification boundary:** Completion claims require objective evidence; whether that boundary is mechanically invoked or explicitly called depends on the host surface.
+4. **Agent Freedom Preserved:** Tier classification suggests useful skills, but does not impose a universal TODO/TDD/Fable sequence.
 
 ### What Gets Installed (and How to Remove It)
 
-The installer only ever writes to your workspace (or, with `--global`, your home directory) — no daemons, no registry entries, no network services. Depending on which platforms you select, it creates:
+The general installer only writes to your workspace (or, with `--global`, your home directory) — no daemons, no registry entries, no network services. Depending on which platforms you select, it creates:
 
 | File / Directory | Purpose |
 |---|---|
 | `.claude/settings.json` (merged) + `.claude/skills/` + `.claude/agents/` | Claude Code lifecycle hooks, project skills, and named Fable agents |
-| `.cursorrules` | Cursor advisory rules |
-| `.github/copilot-instructions.md` | Copilot Chat advisory instructions |
-| `AGENTS.md` | Codex advisory instructions |
-| `.continue/rules/harness.md` | Continue.dev advisory rules |
-| `.hermes.md` | Hermes Agent advisory context |
-| `.claude/harness-everything/` (or the per-platform equivalent) | Harness state: `manifest.json`, WAL, circuit-breaker counters |
+| `.cursorrules` + `.cursor/skills/` | Cursor advisory rules and project skills |
+| `.github/copilot-instructions.md` + `.github/skills/` | GitHub Copilot agent-surface instructions and project skills |
+| `AGENTS.md` + `.agents/skills/` | Codex advisory instructions plus repo-scoped Agent Skills; Hermes can also consume trusted project skills from `.agents/skills/` |
+| `.continue/rules/harness.md` + `.continue/skills/` | Continue.dev advisory rule and installer candidate skill path; standalone skill discovery is `Unknown` |
+| `.hermes.md` | Hermes Agent project advisory context |
+| `.claude/harness-everything/` (or the per-platform equivalent) | Harness installer/runtime bookkeeping owned by that integration |
+
+For `--global`, the installer uses each host's supported user-level skill location rather than assuming one shared directory works everywhere: shared Agent Skills remain under `~/.agents/skills/` where natively consumed, Continue uses `~/.continue/skills/`, Hermes uses `~/.hermes/skills/`, and Claude uses `~/.claude/skills/`.
 
-The installer records the state directories in `.git/info/exclude` — a local-only git ignore file — so Harness state never lands in a commit and your working tree (including `.gitignore`) is never modified. Everything is removed with the built-in uninstaller:
+The repository also ships a separate local OpenAI/Codex plugin package under `plugins/harness-everything/` with marketplace metadata in `.agents/plugins/marketplace.json`. That package is not the same thing as the `--codex` advisory installer path. The public OpenAI Skills-only upload is narrower again; see [docs/openai-plugin.md](docs/openai-plugin.md).
+
+The installer records its state directories in `.git/info/exclude` — a local-only git ignore file — so Harness state never lands in a commit and your working tree (including `.gitignore`) is never modified. Everything owned by the general installer is removed with the built-in uninstaller:
 
 ```bash
 npx github:dyphn1/Harness-everything uninstall            # interactive
 npx github:dyphn1/Harness-everything uninstall --local --skills -y   # non-interactive, workspace only
-npx github:dyphn1/Harness-everything uninstall --global   # also remove ~/.agents etc.
+npx github:dyphn1/Harness-everything uninstall --global   # also remove Harness-owned global state
 ```
 
 ---
@@ -100,57 +114,65 @@ flowchart TD
     style A fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
 ```
 
-### With Harness (Guarded and Routed Execution)
+### With Harness (Invariant-First, Agent-Orchestrated Execution)
 ```mermaid
 flowchart TD
-    U([User Request]) --> H_Router[Harness Router]
-    H_Router -->|Tier 1: Trivial| T1[Direct Edit]
-    H_Router -->|Tier 2: Standard| T2["Native TODO / Markdown checklist"]
-    H_Router -->|Tier 3: Macro| T3[Fable Multi-Agent Flow]
-    
-    T2 & T3 --> Exec[Execute Code / Run Commands]
-    Exec --> Gate{verify-gate.js}
-    
-    Gate -->|Exit 1: Fix & retry| Exec
-    Gate -->|Exit 1 - Repeated| CB{Circuit Breaker rule-of-3.js}
-    CB -->|Fails 3x| ZO[Zoom Out: Ask Human / Reflect]
-    ZO -->|Fresh Diagnosis| Exec
-    Gate -->|Exit 0: Success| Done[Checklist item complete]
-    
-    Done --> SE[Self-Evolve: Update Rules]
-    style H_Router fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px,color:#000000
+    U([User Request]) --> K[Harness Kernel<br/>classify scope + establish invariants]
+    K --> T{Tier recommendation}
+    T -->|Tier 1| A[Agent chooses smallest useful tactic / skill set]
+    T -->|Tier 2| A
+    T -->|Tier 3| A
+    A --> Exec[Execute Code / Run Commands]
+    Exec --> Gate{Objective evidence supports completion?}
+    Gate -->|No| Retry[Diagnose / iterate]
+    Retry --> CB{Same-signature failure x3?}
+    CB -->|No| Exec
+    CB -->|Yes| ZO[Zoom Out / Re-plan]
+    ZO --> Exec
+    Gate -->|Yes| Done[Evidence-backed completion]
+    Done --> SE[Optional Self-Evolve / Record]
+    style K fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px,color:#000000
     style CB fill:#fff9c4,stroke:#fbc02d,stroke-width:1px,color:#000000
     style ZO fill:#ffcc80,stroke:#ef6c00,stroke-width:1px,color:#000000
     style Gate fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
 ```
 
+The Tier changes the **recommendations**, not the required order. Tier 2 may suggest `tdd`, `todo-driven-workflow`, or `verification-loop`; Tier 3 may suggest Fable or multi-agent capabilities. The model decides what actually helps.
+
 ---
 
 ## Core Modules & Concepts
 
 Harness operates through six core cognitive concepts:
 
-1. **Router (`tier-router.js`):** Prevents over-engineering. Triages incoming tasks into Tiers: Tier 1 (Direct Edit, no plans), Tier 2 (Standard TDD enforcement), or Tier 3 (Macro Multi-Agent planning and delegation). It also scans every installed platform's `manifest.json` for skills `self-evolve` has generated dynamically, and auto-surfaces the ones whose keyword triggers match the current prompt — so a lesson learned in one session gets suggested again without the human having to remember it exists. If nothing matches at all — including nothing already kept from the open skills ecosystem — `find-skills` checks `npx skills list` live and, if still nothing, searches `skills.sh`/`npx skills`. With explicit approval it defaults to applying the result ephemerally (a content-addressed OS-temp cache, zero footprint after the OS reclaims it) and only permanently installs via `npx skills add` when the user says they'll reuse it — neither path is cached into `manifest.json` the way `generated[]` is, since third-party content isn't lifecycle-owned by Harness.
-2. **Guard (`rule-of-3.js`):** The fail-safe circuit breaker. Tracks failure signatures across terminal runs. If a test or command fails 3 times with the same signature, it locks mutating tools and forces a `zoom-out` reflection: re-verify every assumption with read-only tools, write a fact-checked report, then resume on a fresh diagnosis. The human partner is pulled in only for genuine decisions — or when the same signature trips the breaker a second time. A companion `Stop` gate (`stop-gate.js`) bounces the end of a turn once per edit batch when edits were never followed by a successful verification command.
-3. **Memory (`state-persist.js`):** Session transaction logging. Stores a local Write-Ahead Log (WAL) of milestones, preventing agents from forgetting their current task state if a session limits out or restarts.
+1. **Kernel Router (`kernel-router.js` + `tier-router.js`):** `tier-router.js` remains the classifier, dynamic-skill detector, and knowledge-guide matcher. `kernel-router.js` is the public runtime boundary: it preserves the classifier result, removes legacy fixed-pipeline instructions, injects the three mandatory invariants, and presents domain skills as advisory suggestions. This prevents host peer-skill selection from bypassing Harness while preserving agent autonomy. If nothing matches at all — including nothing already kept from the open skills ecosystem — `find-skills` checks `npx skills list` live and, if still nothing, searches `skills.sh`/`npx skills` with explicit approval before installation.
+2. **Guard (`rule-of-3.js`):** The fail-safe circuit breaker. Tracks failure signatures across terminal runs on integration surfaces that package the required lifecycle hooks. If a test or command fails 3 times with the same signature, it locks mutating tools and forces a `zoom-out` reflection: re-verify every assumption with read-only tools, write a fact-checked report, then resume on a fresh diagnosis. A companion `Stop` gate (`stop-gate.js`) can bounce the end of a turn once per edit batch when edits were never followed by successful verification on hosts where that hook is installed.
+3. **Memory (`state-persist.js`):** Session transaction logging for stateful hook/plugin integrations. Static skills/instructions alone do not create WAL state.
 4. **Reflection (`self-evolve`):** Long-term workspace immunization. Upon task completion, the agent reflects on the root cause of resolved issues, then judges whether the lesson is a simple rule or a reusable, complex pattern: simple rules are appended to local workspace rules (`RULES.md`); genuinely reusable patterns are instead packaged as a dynamic skill (via `skill-creator`'s Dynamic Skill Generation Contract) and registered in `manifest.json` so the Router picks it up in future sessions. Either path is validated by a hermetic self-regression suite before it's persisted.
-5. **Subagent Scope Guard (`subagent-scope-guard.js`):** Diffs the whole repo's `git status` before and after every subagent (`Task`) burst, not just the files it was briefed to touch. Catches a subagent that was told to only read/verify but edited files anyway — a real failure mode, not a hypothetical one.
-6. **Cognitive Laws (Agent Cognitive OS):** Six governing laws — Intent Precedence, State Handoff Awakening, Elimination & Prediction, Evidence Assertion, Adversarial Falsification, and Code-Documentation Alignment — are woven directly into the specific skill phase each one governs (e.g. Evidence Assertion inside `tdd`'s RED/GREEN/REFACTOR gates, State Handoff Awakening inside `zoom-out`'s reflection phase) rather than duplicated in one shared file. See the relevant skill's own `SKILL.md` for where a given law actually applies.
+5. **Subagent Scope Guard (`subagent-scope-guard.js`):** Diffs the whole repo's `git status` before and after every supported subagent (`Task`) burst, not just the files it was briefed to touch. Catches a subagent that was told to only read/verify but edited files anyway — where that host/integration actually invokes the guard.
+6. **Cognitive Laws (Agent Cognitive OS):** The Cognitive OS is a policy layer, not a peer skill that must win host routing before domain work can begin. Its Discover → Think → Try → Summarize → Record loop remains available as an explicit/manual entry point, while runtime integrations establish the smaller cross-cutting invariants independently.
 
 ---
 
 ## Supported AI IDEs & Tools
 
-**Only Claude Code gets the hard-boundary hooks.** Every other platform below has no hook/exit-code execution mechanism, so `harness-everything` can only inject advisory text — same protection level as the "Prompt-Only" column in the comparison table above. There is no circuit breaker, no preflight audit, and no WAL on those platforms unless Claude Code (or another hook-capable tool) is also driving the same repo.
+The authoritative current matrix is [docs/platform-capabilities.md](docs/platform-capabilities.md). The important distinction is that **one host can have multiple Harness installation surfaces**.
 
-| AI Agent Tool | Integration Method | Local Target Location | Enforcement |
+[`opencode-plugin/`](opencode-plugin/) (`index.mjs`) implements a verification gate and a Rule of 3 breaker against OpenCode's real, source-verified plugin API (`tool.execute.before`/`.after`, the `session.idle` event). `ci/mechanism-2n-opencode-plugin.test.js` drives the exported hooks directly against a mock context matching that API. What's *not* yet done: a live OpenCode session actually loading and firing the plugin, so the current claim remains **hard-capable / mechanism-tested, unverified live**.
+
+| AI Agent Tool / Surface | Integration Method | Local Target Location | Enforcement claim |
 |---|---|---|---|
-| **Claude Code** | Native Lifecycle Hooks (`PreToolUse`, `PostToolUse`, `SessionStart`) | `.claude/settings.json` (project) / `~/.claude/settings.json` (user)<br>*.claude/skills/* (Project Skills) / *~/.claude/skills/* (Global Skills) | **Hard** — hooks can block a tool call (`exit(2)`) |
-| **Cursor** | Native Project Rules | `.cursorrules` | Advisory only |
-| **Copilot Chat** | Custom Instructions | `.github/copilot-instructions.md` | Advisory only |
-| **Codex** | Custom Instructions (`AGENTS.md`, not `.codex/config.toml` — that file controls CLI/sandbox behavior, not prompt content) | `AGENTS.md` | Advisory only |
-| **Continue.dev** | Native project rules (a dedicated Markdown file with YAML frontmatter, `alwaysApply: true`) | `.continue/rules/harness.md` (project) / `~/.continue/rules/harness.md` (user, via `--global`) | Advisory only |
-| **Hermes Agent** ([Nous Research](https://hermes-agent.nousresearch.com/)) | Auto-loaded project context file (Hermes also reads `AGENTS.md`/`CLAUDE.md`/`.cursorrules` from the same directory if present, truncated at ~20k chars) | `.hermes.md` (project only — Hermes has no documented global project-instructions equivalent, so `--global --hermes` is a documented no-op) | Advisory only |
+| **Claude Code** | Native lifecycle hooks (`PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`) | `.claude/settings.json`, `.claude/skills/`, `.claude/agents/` | **Hard** for the supported verified hook gates |
+| **OpenCode** | Native plugin module ([`opencode-plugin/index.mjs`](opencode-plugin/index.mjs)) | `.opencode/plugins/` | **Hard-capable, unverified live** — mechanism/source coverage exists; live host loading is not yet evidence-backed |
+| **Codex — general installer path** | Skills + `AGENTS.md` guidance | `AGENTS.md` + repo-scoped `.agents/skills/` | **Advisory/instruction-oriented** where the host only consumes instructions |
+| **Codex / local OpenAI plugin** | `.codex-plugin` package with session, prompt, supported-tool, subagent, and stop hooks plus 26 canonical skills | `.agents/plugins/marketplace.json` → `plugins/harness-everything/` | **Mechanism-tested local enforcement** for the packaged mappings; live host loading remains unverified |
+| **Public OpenAI Skills-only plugin** | Public Skills-only bundle | Generated submission ZIP from `plugins/harness-everything/skills/` | **Skill/workflow behavior only**; no local `.codex-plugin` lifecycle hooks in the public artifact |
+| **Cursor** | Native Project Rules + project skills | `.cursorrules` + `.cursor/skills/` | Advisory only |
+| **GitHub Copilot agent surfaces** | Agent Skills + repository custom instructions | `.github/copilot-instructions.md` + `.github/skills/` | Agent Skills path is documented; no live Harness session or plugin install is verified |
+| **Continue.dev** | Native project rules; skill path retained as an installer adapter candidate | `.continue/rules/harness.md` + `.continue/skills/`; global candidate `~/.continue/skills/` | Rules are documented; standalone `SKILL.md` discovery is `Unknown` |
+| **Hermes Agent** | Trusted project context + skills | `.hermes.md` + trusted project `.agents/skills/`; global skills `~/.hermes/skills/` | Skill path and installer contract are checked; project loading remains subject to trust |
+
+For local OpenAI packaging, marketplace import, plugin tests, and the public Skills-only submission boundary, see [docs/openai-plugin.md](docs/openai-plugin.md).
 
 ---
 
@@ -166,54 +188,59 @@ node multi-agent-workspace/scripts/scaffold.js --workspace . \
   --agency-source <path-to-agency-agents> --division engineering --platform codex
 ```
 
-The source is read-only input. The generated `.harness/multi-agent/` directory
-records the six zones, selected metadata, supported converter targets,
-launcher, immutable router, memory index, and structured handoff. Omit the
-source for an explicit unavailable-catalog fallback; do not treat it as a
-complete roster.
+The source is read-only input. Runtime metadata, selected roles, the launcher,
+resolved router, memory index, and structured handoff are keyed under the
+global Harness state home; no generated router, executable, or zone skeleton is
+written to the target workspace. Decision, domain, and architecture records
+are resolved per repository from `CONTEXT-MAP.md`, project configuration,
+existing documentation folders, or a committable fallback. Omit the source for
+an explicit unavailable-catalog fallback; do not treat it as a complete roster.
 
 This repo uses a flat layout (waza/agentskills.io convention). The table below maps each top-level directory to its role.
 
 | Directory | Category | Description |
 |---|---|---|
-| `harness-everything` | **Core Runtime** | Bootstrap, tier-router, verify-gate, self-heal |
-| `hooks` | **Core Runtime** | Claude Code lifecycle hooks (circuit breaker, scope guard, stop gate, etc.) |
-| `scripts` | **Core Runtime** | Installer, manifest, prompts, workspace utilities |
+| `harness-everything` | **Core Runtime** | Bootstrap, kernel-router, tier-router, verify-gate, self-heal |
+| `hooks` | **Core Runtime** | Claude Code lifecycle hooks (prompt routing, circuit breaker, scope guard, stop gate, etc.) |
+| `scripts` | **Core Runtime** | Installer, manifest, prompts, workspace utilities, repository contract extraction/sync |
 | `bin` | **Core Runtime** | `harness` CLI entry point |
-| `ci` | **Quality Gates** | Consistency check, description collision, mechanism tests, negative controls |
+| `ci` | **Quality Gates** | Consistency checks, description collision, mechanism tests, invariant-routing regression, documentation/runtime contract drift guards |
 | `.github` | **CI/CD** | GitHub Actions workflows (ci.yml, release.yml, behavioral-evals.yml) |
 | `.claude-plugin` | **Distribution** | Plugin manifests for Claude Code marketplace |
+| `.agents/plugins` | **Distribution** | OpenAI/Codex repository marketplace metadata |
+| `plugins/harness-everything` | **Distribution** | Local OpenAI/Codex plugin package plus canonical skill copies |
+| `submission/openai` | **Distribution / Review** | Public OpenAI Skills-only listing/test inputs |
 | `evals` | **Routing Evals** | 26 trigger/routing eval suites (waza format) |
-| `behavioral-evals` | **Behavioral Evals** | LLM-level discipline cases (headless agent sessions) |
+| `behavioral-evals` | **Behavioral Evals** | LLM-level discipline cases plus weekly structural validation workflow |
 | `benchmarks` | **Benchmarks** | BENCHMARK_SOP fixtures and recorded A/B results |
-| `docs` | **Documentation** | Philosophy, architecture, routing, reflection, audit |
+| `docs` | **Documentation** | Philosophy, architecture, routing, reflection, platform capabilities, generated repository contract, audit |
 | `references` | **Documentation** | Shared checklists (security, performance, definition-of-done) |
 | `multi-agent-workspace` | **Skill (Tier 3)** | Scaffold six zones, select agency specialists, and generate bounded launchers |
 | `environment-detection` | **Foundation** | Preflight: detect OS, shell, package manager |
 | `eval-harness` | **Skill (Tier 2)** | Evaluate agent outputs against rubrics |
-| `fable-discipline` | **Skill (Tier 3)** | Enforce Fable execution guardrails |
-| `fable-mode` | **Skill (Tier 3)** | Multi-agent orchestration with milestone gates |
+| `fable-discipline` | **Skill (Tier 3)** | Fable execution guardrails when Fable is selected |
+| `fable-mode` | **Skill (Tier 3)** | Optional macro/multi-agent orchestration with milestone gates |
 | `find-skills` | **Meta** | Discover and install skills from open ecosystems |
 | `git-commit` | **Skill (Tier 1)** | Conventional commit messages with verification |
 | `grill-me` | **Skill (Tier 2)** | Adversarial plan interrogation before implementation |
 | `grill-with-docs` | **Skill (Tier 3)** | Domain-model and decision alignment before design publication |
 | `improve-codebase-architecture` | **Skill (Tier 2)** | Architectural refactoring with evidence |
-| `install-cognitive-os` | **Foundation** | Install Harness cognitive OS into workspace |
+| `install-cognitive-os` | **Foundation / Manual Entry** | Explain or explicitly apply the cognitive policy; runtime invariants do not depend on host selecting it |
 | `repo-docs` | **Skill (Tier 3)** | Generate repository documentation |
 | `rewrite-commits` | **Skill (Tier 1)** | Interactive rebase and commit history cleanup |
 | `security-review` | **Skill (Tier 2)** | OWASP/STRIDE security review |
 | `self-evolve` | **Skill (Tier 2)** | Workspace immunization via dynamic skills |
 | `skill-creator` | **Meta** | Create new skills from patterns |
 | `skill-style` | **Meta** | Skill authoring style guide |
-| `tdd` | **Skill (Tier 2)** | Test-driven development enforcement |
+| `tdd` | **Skill (Tier 2)** | Test-driven development when executable behavior benefits from it |
 | `to-spec` | **Advisory (Tier 2/3)** | Publish specs from settled conversations |
 | `to-tickets` | **Advisory (Tier 2/3)** | Decompose settled specs into tracked tickets |
-| `todo-driven-workflow` | **Foundation** | Native TODO or Markdown checklist discipline |
+| `todo-driven-workflow` | **Advisory Foundation** | Progress tracking when explicit multi-step state helps |
 | `using-git-worktrees` | **Skill (Tier 2)** | Git worktree concurrency patterns |
-| `verification-loop` | **Skill (Tier 2)** | Verify-before-complete enforcement |
+| `verification-loop` | **Skill (Tier 2)** | Select systematic verification evidence; kernel still requires evidence before completion |
 | `verify-before-claim` | **Always-on discipline** | Fact-audit before asserting claims |
 | `zoom-out` | **Circuit breaker** | Circuit-breaker reflection protocol |
-| `opencode-plugin` | **Platform Plugin** | Enforcement hooks for opencode (post-edit, pre-complete, circuit-breaker) |
+| `opencode-plugin` | **Platform Plugin** | Enforcement logic for OpenCode's real plugin API; live-session firing still unverified (#37) |
 
 ---
 
@@ -221,47 +248,52 @@ This repo uses a flat layout (waza/agentskills.io convention). The table below m
 
 For a deep dive into individual modules and the underlying philosophy, explore our sub-documents:
 
-*   [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
-*   [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
-*   [Harness Routing & Triage](docs/routing.md): Detailed trigger criteria for Tiers 1, 2, and 3.
-*   [Harness Reflection & Memory](docs/reflection.md): WAL session handoffs and workspace rules immunization.
-*   [Harness Audit Log](docs/audit.md): Dated self-audit scorecards, methodology, and per-cycle change log.
+* [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
+* [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
+* [Platform Capability Matrix](docs/platform-capabilities.md): Canonical current enforcement/install/evidence boundary per surface.
+* [Repository Runtime & Workflow Contract](docs/repository-contract.md): Generated Node/action/workflow/gate state used by consistency CI.
+* [OpenAI / ChatGPT Plugin Packaging](docs/openai-plugin.md): Local Codex/OpenAI plugin packaging plus public Skills-only submission boundary.
+* [Harness Routing & Triage](docs/routing.md): Detailed trigger criteria for Tiers 1, 2, and 3.
+* [Harness Reflection & Memory](docs/reflection.md): WAL session handoffs and workspace rules immunization.
+* [Harness Audit Log](docs/audit.md): Dated historical self-audit scorecards, methodology, and per-cycle change log.
 
 Fable model selection is documented in [fable-mode/references/model-matrix.md](fable-mode/references/model-matrix.md); the explicit entrypoints are `fable-haiku`, `fable-sonnet`, and `fable-opus`.
 
+Maintainers should follow [RELEASING.md](RELEASING.md) for tag-driven npm releases and record observations in [docs/release-evidence.md](docs/release-evidence.md). The issue #20 coordination decisions and evidence boundaries are captured in [docs/issue-20-rollup.md](docs/issue-20-rollup.md).
+
 ---
 
 ## Benchmarks & Testing
 
-**If you are an agent asked to verify a Harness install, start at [VERIFICATION.md](VERIFICATION.md), not here.** It gives exact commands with exact expected output — install artifact checks for every platform, mechanism-level checks (Claude Code only), the behavioral test prompts below, and an acceptance scorecard to fill in. Do not report "it works" from reading the code — every check there names a command to actually run.
+**If you are an agent asked to verify a Harness install, start at [VERIFICATION.md](VERIFICATION.md), not here.** It separates package/integrity checks, mechanism evidence, live-host evidence, and behavioral evidence so one kind of pass is not mistaken for another.
 
-`npm test` (`self-evolve/scripts/self-regression.js`) runs deterministic syntax, CLI, routing-matrix, positive skill-route coverage, reference, behavioral-case, Fable model-mode, and mechanism checks (`ci/mechanism-test.js`, `npm run test:mechanism` to run it alone). The suite checks real exit codes and stderr, not just "the code looks right." It runs in CI on every push and pull request (`.github/workflows/ci.yml`); live model evaluations remain explicitly on-demand.
+`npm test` (`self-evolve/scripts/self-regression.js`) runs deterministic syntax, CLI, routing-matrix, positive skill-route coverage, **invariant-first routing regression**, reference, behavioral-case, Fable model-mode, and mechanism checks (`ci/mechanism-test.js`, `npm run test:mechanism` to run it alone). The suite checks real exit codes and stderr, not just "the code looks right." Primary CI runs on Node.js 24 across Ubuntu, Windows, and macOS for every push and pull request (`.github/workflows/ci.yml`), with a separate Node.js 22 compatibility lane for the advertised minimum runtime.
 
 For a fuller vanilla-vs-Harness behavioral comparison, see [Harness Skills Benchmark SOP](BENCHMARK_SOP.md) — standardized, reproducible scenarios:
-*   **Test A:** Over-engineering defense (Tier 1 typo correction)
-*   **Test B:** Micro-error loop defense (Tier 2 bug resolution)
-*   **Test C:** Attention loss and hallucination (Tier 3 module refactoring)
-*   **Test D:** Knowledge boundary constraints (Offline hallucination prevention)
-*   **Test E:** Terminal environment and shell awareness (Windows/Unix shell detection)
-*   **Test F** (in VERIFICATION.md, not BENCHMARK_SOP.md): fact-audit discipline — does the agent verify an external-behavior claim before asserting it?
+* **Test A:** Over-engineering defense (Tier 1 typo correction)
+* **Test B:** Micro-error loop defense (Tier 2 bug resolution)
+* **Test C:** Attention loss and hallucination (Tier 3 module refactoring)
+* **Test D:** Knowledge boundary constraints (Offline hallucination prevention)
+* **Test E:** Terminal environment and shell awareness (Windows/Unix shell detection)
+* **Test F** (in VERIFICATION.md, not BENCHMARK_SOP.md): fact-audit discipline — does the agent verify an external-behavior claim before asserting it?
 
 Benchmark **results** are tracked in [benchmarks/](benchmarks/README.md) (`run.js scaffold` builds the fixture, `record` commits a schema-validated result bound to a session log). Until those cells are filled, effectiveness claims are unbacked by recorded evidence.
 
-### Behavioral evals (LLM-level, on demand)
+### Behavioral evals (LLM-level, on demand + weekly structural validation)
 
-Mechanism tests prove the hooks enforce gates; only live sessions prove agents follow the disciplines. [behavioral-evals/](behavioral-evals/README.md) runs discipline cases (including pressure variants like "we ship in 5 minutes, skip checks") against headless agent sessions (`claude -p`, opencode) in throwaway workspaces: `npm run eval:behavioral`. Token-costing by design — never wired into CI.
+Mechanism tests prove individual packaged mechanisms; only real host/session evidence proves the host actually loaded and fired them. [behavioral-evals/](behavioral-evals/README.md) runs discipline cases (including pressure variants like "we ship in 5 minutes, skip checks") against headless agent sessions (`claude -p`, OpenCode) in throwaway workspaces: `npm run eval:behavioral`. Live runs remain token-costing and can be invoked on demand. The weekly `behavioral-evals.yml` workflow always validates case structure and runs live cases only when the runner actually has the Claude CLI.
 
 ### Catalog hygiene
 
-`npm run test:consistency` keeps the distribution manifests, docs links, skill frontmatter, and routing-eval coverage in lockstep with what is actually on disk; `npm run test:references` checks every executable/deep-dive path named by `SKILL.md`; `npm run test:release` compares the skill catalog and references with `v0.3.3-beta`; and `harness verify-install` detects stale installed versions or file trees. `npm run test:collision` fails CI when two skills' descriptions overlap enough to confuse the router. The repository checks run on every push (`.github/workflows/ci.yml`).
+`npm run test:consistency` keeps distribution manifests, docs links, skill frontmatter, routing-eval coverage, platform capability claims, and the generated repository runtime/workflow contract in lockstep with what is actually on disk. `npm run test:repo-contract` runs the runtime/workflow drift gate directly, while `npm run docs:sync` regenerates [docs/repository-contract.md](docs/repository-contract.md) after an intentional change. `npm run test:docs:capabilities` runs the platform-doc drift check directly. `npm run test:references` checks every executable/deep-dive path named by `SKILL.md`; `npm run test:release` compares release/catalog evidence; `npm run test:routing:skills` recursively classifies nested skills and executes the real router for every directly-routable skill's positive cases; `npm run test:routing:invariants` guards the invariant-first architecture; and `harness verify-install` detects stale installed versions or file trees. The installer E2E gate performs install → verify-install → uninstall against seeded user-owned files on Ubuntu, Windows, and macOS so path and ownership symmetry regressions fail CI. `npm run test:collision` fails CI when two skills' descriptions overlap enough to confuse the router.
 
 ---
 
 ## 📊 System Evaluation
 
-Harness audits itself on a dated cycle by running its own test suite and VERIFICATION.md recipes — never by reading the code and assuming it works. The full scorecards, methodology, and per-cycle change log live in [docs/audit.md](docs/audit.md).
+Harness audits itself on a dated cycle by running its own test suite and VERIFICATION.md recipes — never by reading the code and assuming it works. The full scorecards, methodology, and per-cycle change log live in [docs/audit.md](docs/audit.md). Audit scorecards are historical snapshots; current platform capability claims live in [docs/platform-capabilities.md](docs/platform-capabilities.md).
 
-**Latest local baseline — 2026-09-01**: 26/26 on-disk skills, 26/26 routing-eval directories, and the local npm gates are green. Waza remains a CI-only gate in this checkout because its installer is not available as an npm package; run it on an LF-normalized export as documented by CI.
+**Latest local audit baseline — 2026-09-01**: 26/26 on-disk skills, 26/26 routing-eval directories, and the local npm gates were green for that audit snapshot. Waza remained a CI-only gate in that checkout because its installer was not available as an npm package; run it on an LF-normalized export as documented by CI.
 
 Measure on an LF export, not a Windows working tree — CRLF can inflate waza's token counts and trigger false budget failures.
 
@@ -269,11 +301,14 @@ Measure on an LF export, not a Windows working tree — CRLF can inflate waza's
 
 ## 🤝 For Contributors
 
-To contribute to Harness or modify any Skill behavior, ensure you run the local self-regression suite first:
+To contribute to Harness or modify any Skill behavior, ensure you run the local self-regression suite and consistency gates first:
 
 ```bash
-# Run full hermetic static syntax & routing simulations
 npm run self-regression
+npm run test:consistency
+npm run test:repo-contract
+npm run test:plugin:openai
+npm run test:plugin:submission
 ```
 
-All script modifications must pass 100% cleanly before pushing to keep the runtime immunized against behavioral regression.
+After intentional runtime/workflow changes, run `npm run docs:sync` and commit the regenerated repository contract. All script modifications must pass 100% cleanly before pushing to keep the runtime immunized against behavioral regression.

package/RELEASING.md

@@ -0,0 +1,93 @@
+# Releasing Harness Everything
+
+Harness releases are stable SemVer releases generated automatically from Conventional Commit history on `main`. Do not manually choose or bump a release version in normal pull requests.
+
+## Version policy
+
+`semantic-release` compares `main` with the latest stable `vX.Y.Z` tag and selects the highest required bump:
+
+| Commit | Release |
+| --- | --- |
+| `BREAKING CHANGE:` footer or breaking `!` | major |
+| `feat:` | minor |
+| `fix:` / `perf:` / `refactor:` / `build:` / `revert:` | patch |
+| `docs:` / `test:` / `ci:` / `style:` / `chore:` | none |
+
+There are no alpha, beta, or rc release channels. Historical prerelease tags remain history, but new releases come only from `main` and use `vX.Y.Z` tags.
+
+Do not hard-code a "current release baseline" in this guide. `semantic-release` discovers the latest stable tag from Git history on each run, and release evidence belongs in [docs/release-evidence.md](docs/release-evidence.md).
+
+## Runtime contract
+
+The release job uses the repository's primary Node runtime from the checked-in current-state policy: Node.js 24 today, with Node.js 22 retained as the minimum supported product runtime. The generated source-of-truth summary is [docs/repository-contract.md](docs/repository-contract.md).
+
+When changing Node versions, GitHub Action majors, or workflow triggers, run:
+
+```bash
+npm run docs:sync
+npm run test:repo-contract
+```
+
+## Release flow
+
+A push to `main` runs the full reusable CI gate and then semantic-release. A manual `workflow_dispatch` run is available for a safe retry.
+
+1. Check out full Git history and tags.
+2. Run the same CI jobs used for pull requests, including the Node 22 minimum-runtime compatibility lane.
+3. Analyze Conventional Commits since the latest stable release.
+4. Exit without publishing when there is no releasable commit.
+5. Calculate the next stable SemVer.
+6. Run `scripts/sync-release-version.js` to synchronize package, Claude, OpenAI/Codex, OpenCode, lockfile, and changed canonical skill version fields.
+7. Regenerate and verify plugin packages.
+8. Update `CHANGELOG.md` and create `chore(release): X.Y.Z [skip ci]`.
+9. Create tag `vX.Y.Z`, publish npm with provenance, and create the GitHub Release.
+
+Release concurrency is serialized so two updates to `main` cannot publish competing versions.
+
+## Version ownership
+
+The following checked-in fields are release outputs and are synchronized together:
+
+- `package.json`
+- `package-lock.json` and its root package entry
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `plugins/harness-everything/plugin.json`
+- `plugins/harness-everything/.codex-plugin/plugin.json`
+- `opencode-plugin/plugin.json`
+- `metadata.version` for canonical skills changed since the previous release tag; when a top-level skill changes, all nested sub-skill `SKILL.md` files inherit that same release version
+
+Unchanged skills keep the version of the release in which they last changed. This preserves useful per-skill provenance while removing manual version edits from normal PRs.
+
+The release workflow passes the previous stable tag explicitly:
+
+```bash
+node scripts/sync-release-version.js 1.2.3 --base v1.2.2
+node scripts/sync-release-version.js --check 1.2.3 --base v1.2.2
+node scripts/sync-release-version.js --validate 1.2.3
+```
+
+Prerelease/build suffixes such as `1.2.3-beta` or `1.2.3+meta` are rejected.
+
+## Contributor requirements
+
+The final commit that lands on `main` must use a Conventional Commit type because it is release input. With squash merging, the PR title becomes especially important. Use `feat`, `fix`, `perf`, `refactor`, `build`, or `revert` when a shipped change needs a release, and use non-releasing types for changes that should not publish.
+
+Keep human-authored pending notes under `[Unreleased]` in `CHANGELOG.md`; semantic-release owns stable release headings and release notes.
+
+## Verification and evidence
+
+The release workflow runs the reusable CI gate before semantic-release. After publication, verify the workflow, GitHub Release, and npm registry rather than inferring publication from source state:
+
+```text
+gh run list --workflow release.yml --limit 5
+gh run view <run-id> --json conclusion,headSha,jobs
+gh release view v<version> --json tagName,publishedAt,url
+npm view harness-everything version dist-tags --json
+```
+
+Record release evidence in [docs/release-evidence.md](docs/release-evidence.md) when the release process requires an auditable observation.
+
+## Failure and retry
+
+A failure before tag/publication leaves no completed release. Running the workflow again against unchanged commit history calculates the same next version. Once a release tag exists, semantic-release treats it as the new baseline and will not republish that version. The generated release commit uses `[skip ci]` and a non-releasing `chore` type to prevent recursive releases.

package/SUPPORT.md

@@ -0,0 +1,27 @@
+# Support
+
+Harness Everything is an open-source, skill-only plugin for software-development workflows in ChatGPT, Codex, and compatible coding-agent hosts.
+
+## Get help
+
+For installation, routing, skill behavior, or publication-related problems, open a GitHub issue:
+
+https://github.com/dyphn1/Harness-everything/issues
+
+Please include:
+
+- the host and version you were using;
+- the Harness Everything version or commit;
+- the smallest prompt or workflow that reproduces the problem;
+- expected and observed behavior;
+- relevant logs with secrets, credentials, private source, and personal data removed.
+
+## Security reports
+
+Do not post sensitive vulnerability details or credentials in a public issue. Follow the reporting guidance in `SECURITY.md`:
+
+https://github.com/dyphn1/Harness-everything/blob/main/SECURITY.md
+
+## Scope
+
+Harness Everything does not operate a hosted support service, hosted backend, or separate user account. Support covers the open-source plugin package and its documented workflows; support for ChatGPT, Codex, GitHub, package registries, and other third-party services remains with those providers.

package/TERMS.md

@@ -0,0 +1,21 @@
+# Terms of Use
+
+Harness Everything is open-source software distributed under the Apache License 2.0. Use, copying, modification, and distribution of the software are governed by the terms of the repository `LICENSE` file.
+
+## No hosted service
+
+The project does not provide a hosted service or separate user account. The plugin packages skills and local hooks that run through the user's supported ChatGPT/Codex or coding-agent environment.
+
+## User responsibility
+
+Harness workflows can guide an agent to inspect code, modify files, run commands, and interact with tools made available by the user or host. Users remain responsible for reviewing permissions, commands, generated changes, third-party service terms, and verification evidence before relying on or deploying results.
+
+## Third-party platforms
+
+Use of ChatGPT, Codex, GitHub, package registries, external tools, or connected services remains subject to the applicable third-party terms. Harness Everything does not grant additional rights to those services and does not bypass their authorization or workspace controls.
+
+## Warranty and liability
+
+The warranty, limitation-of-liability, and other license conditions in the Apache License 2.0 apply to the software. Nothing in this document creates a warranty or service-level commitment beyond that license.
+
+For project questions or reports, use the repository issue tracker: https://github.com/dyphn1/Harness-everything/issues