harness-everything 0.7.0 → 0.8.1

package/docs/architecture.md

@@ -1,141 +1,154 @@
 # Harness Architecture
 
-This document describes the internal architecture, lifecycle, and integration boundaries of the Harness behavior layer. The current cross-platform claim boundary is centralized in [platform-capabilities.md](platform-capabilities.md); host sections here must remain consistent with it.
-
----
+This document describes Harness runtime architecture and integration boundaries. Current host capability/evidence claims are centralized in [platform-capabilities.md](platform-capabilities.md); package wiring is not live-host proof.
 
 ## Architectural Overview
 
-Harness is a **system supervisor**, not a universal workflow engine. Skills remain independently useful, while runtime mechanisms establish a small cross-cutting contract around software work.
+Harness is a **behavior and workflow supervisor**, not one universal fixed workflow. The router chooses the smallest sufficient execution topology; once selected, that topology becomes a lifecycle contract. The model retains freedom over reasoning, tools, and implementation technique inside the contract.
 
-The architecture follows a mechanism-first skill mesh with a **minimal kernel**:
+The minimal kernel establishes:
 
-- classify scope before mutation,
-- require evidence before completion claims,
-- stop repeated same-signature micro-retries and re-plan,
-- leave domain skill selection, ordering, planning style, and delegation to the agent.
+- scope/tier before mutation,
+- a selected workflow topology when task evidence supports one,
+- applicability evaluation for every suggested skill before omission,
+- objective evidence before completion,
+- bounded re-plan/recovery after repeated failure,
+- explicit blocked/degraded/escape state instead of silent workflow deletion.
 
-> **Do not enforce workflow order. Enforce workflow invariants.**
+> **Mandatory applicable workflow; flexible reasoning/implementation inside it.**
+>
+> A suggested skill can be `not-applicable` after evaluating its real flow. A selected topology cannot be replaced with a direct path merely because the model is confident. Escape is only for genuinely uncovered workflow scope and requires evidence.
 
-This is intentionally different from the older design where Tier 2 implied a fixed TDD/checklist pipeline and Tier 3 implied a mandatory Fable/multi-agent pipeline.
+This avoids both extremes: the old universal Tier-2/Tier-3 pipeline and a purely advisory system where the model can rationalize away verification, staging, documentation, or other applicable obligations.
 
 ```mermaid
 flowchart TD
-    subgraph User_Session [User Session]
-        U([User Request]) --> Boot[bootstrap.js: Session Start / restore]
-    end
-
-    subgraph Kernel [Harness Kernel]
-        Boot --> Preflight[Environment / integration discovery]
-        Preflight --> KR[kernel-router.js]
-        KR --> TR[tier-router.js<br/>classifier + guide discovery]
-        TR --> Inv[Inject minimal invariants]
-        Inv --> Choice[Agent chooses useful skills / tactics]
-    end
-
-    subgraph Execution [Agent-Controlled Execution]
-        Choice --> Tools[Tool calls / edits / tests]
-        Tools --> Evidence{Evidence supports completion?}
-        Evidence -- Yes --> Done[Evidence-backed completion]
-        Evidence -- No --> Retry[Diagnose / iterate]
-    end
-
-    subgraph Defense [Runtime Boundaries]
-        Retry --> CB{Same-signature failure x3?}
-        CB -- No --> Tools
-        CB -- Yes --> ZO[zoom-out / fresh diagnosis]
-        ZO --> Tools
-    end
-
-    subgraph Learning [Optional Learning / State]
-        Done --> Record[Record / self-evolve when useful]
-    end
-
-    style Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
-    style Defense fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
-    style Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
+    U([User Request]) --> B[Session bootstrap / environment]
+    B --> K[kernel-router.js]
+    K --> T[tier-router.js<br/>classification + task shape]
+    T --> P[Structured workflow plan]
+    P --> A{Strategy selected?}
+    A -- No / deferred --> D[Preserve invariants<br/>choose smallest justified workflow]
+    A -- Yes --> C[ACTIVE workflow contract]
+    C --> S{Suggested skills?}
+    S -- Yes --> E[Read SKILL.md<br/>resolve applicability]
+    S -- No --> X[Execute topology]
+    E --> X
+    X --> V{Required stage/check resolved?}
+    V -- Yes --> Done[Evidence-backed completion]
+    V -- No --> R[Diagnose / bounded re-plan]
+    R --> X
+    R -- topology cannot cover scope --> Esc[Evidence-backed escape<br/>uncovered scope only]
 ```
 
 ### Router responsibilities
 
-`kernel-router.js` is the public runtime entry point. It delegates heuristic classification and dynamic guide/skill discovery to `tier-router.js`, then converts the result into the Harness contract:
+`kernel-router.js` is the public runtime entry. It consumes the structured classifier contract and exposes:
 
-- recommended Tier + rationale,
+- tier + rationale,
+- selected/deferred execution strategy,
 - required invariants,
-- advisory skill suggestions.
+- suggested skills that require applicability evaluation,
+- the visible routing checkpoint,
+- a workflow execution contract.
 
-The kernel deliberately suppresses the old fixed `BASE EXECUTION LOOP` wording so that a host selecting `tdd`, `security-review`, `repo-docs`, or another peer skill cannot accidentally replace or bypass the cross-cutting Harness contract.
+The router does not tell the model *how* to solve each stage. It decides what lifecycle shape is required. `direct-single`, `iterative-single`, `fable-staged`, `fable-parallel`, and `fable-multi-agent-workspace` remain deliberately small, non-overlapping topology choices.
 
-`harness-everything` remains the public/manual skill entry point for routing, debugging, and re-routing. `install-cognitive-os` remains the explanatory/manual entry point for the Discover → Think → Try → Summarize → Record policy. Automatic correctness must not depend on either one winning host peer-skill selection first.
+### Skill applicability vs. topology execution
 
----
+Router suggestions remain useful domain/workflow knowledge, not a universal sequence. Before omission, the agent reads the complete `SKILL.md` entry and evaluates `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. Name/description/router-summary or “routine task” is insufficient evidence.
 
-## Integration Touchpoints
+The selected topology is stronger. Once selected, it must be entered and resolved unless the runtime records a permitted workflow escape with uncovered scope + evidence. Covered obligations survive the escape.
 
-Harness aligns to each host's real capabilities. Enforcement strength is platform-specific; shared skill text does not prove mechanism parity.
+### Runtime workflow state
 
-### Self-healing and placement
+On host paths that can persist it, `kernel-router.js` records session-scoped `workflow-run.json` with the selected strategy and lifecycle state. Prompt text is not persisted; only a content hash is retained for correlation.
 
-`harness-everything/scripts/self-heal.js` audits supported integration touchpoints and can re-run the idempotent installer to repair missing pieces. If a user intentionally removed an integration, respect that choice.
+For selected Fable topologies on Claude:
 
-A platform's native files stay where that platform expects them. Harness-owned runtime state converges under the platform's `harness-everything/` state directory, while skills remain in each platform's native skill location. `manifest.json` records installed artifacts so uninstall can remove only Harness-owned files.
+- `workflow-gate.js` checks supported shell/direct mutation, actual direct/patch targets, and registered Git worktree isolation before major-workflow mutation; Fable also requires a run bound to the workflow/session identity;
+- Fable owns stage contracts, `dependsOn`/`writeSet`, validated execution batches, objective per-stage checks, synthesis, cold verification, and bounded re-plans;
+- `workflow-stop-gate.js` rejects completion while correlated stage contracts remain unresolved;
+- `workflow-disposition.js` starts/replans within budget, records blockers, and permits only declared-stage evidence-backed escape (`workflow-uncovered-scope` or `host-capability-unavailable`). Covered obligations, isolation, and independent verification survive escape. See [runtime transitions and limitations](workflow-runtime.md).
 
-### Runtime state vs. skill content
+Other topologies use their own applicable mechanisms: loop budgets, regular verification stop-gates, action gates, and task-specific skills. Mechanism coverage is not assumed identical across hosts.
+
+## Integration Touchpoints
 
-Runtime state includes hook metadata, circuit-breaker counters, handoff/verification timestamps, and WAL-style session state. Skill content is separate and independently discoverable. This separation lets a domain skill remain useful even when a host does not support Harness runtime hooks.
+Harness aligns to each host's actual lifecycle/tool APIs. Shared skill text defines a contract; only supported host mechanisms can mechanically block or observe particular transitions.
 
----
+### Runtime state vs. skill content
 
-## Host Adapters
+Runtime state includes hook metadata, workflow lifecycle, circuit-breaker counters, handoff/verification evidence, and WAL-style session state. Skill content is independently discoverable and remains useful on instruction-only surfaces.
 
-### 1. Claude Code — hook-enforced
+### Claude Code — hook-enforced mechanisms
 
 The installer configures native lifecycle hooks and project skills.
 
-- `SessionStart`: `bootstrap.js` restores prior state and audits integrations.
-- `UserPromptSubmit`: `kernel-router.js` establishes routing + invariants before peer/domain skill execution.
-- `PreToolUse`: circuit breaker, boundary/depth/context guards, and subagent scope guards can block supported tool calls.
-- `PostToolUse`: records outcomes/state and tracks repeated failures.
-- `Stop`: `stop-gate.js` prevents an edit batch from being claimed complete without successful verification evidence.
+- `SessionStart`: bootstrap/restoration.
+- `UserPromptSubmit`: kernel routing + active workflow contract.
+- `PreToolUse`: workflow bypass gate, action gate, rule-of-3, boundary/depth/context guards, subagent scope guard.
+- `PostToolUse`: outcomes, state, repeated-failure evidence, stage checks.
+- `Stop`: action-gate audit, selected-Fable completion gate, and ordinary verify-before-claim stop gate.
+
+These hooks make some lifecycle obligations mechanically enforceable. They still do not prove a real session loaded/fired them; live evidence remains separate.
+
+### OpenCode — plugin enforcement, scoped live verification
 
-The prompt hook is intentionally lightweight: it does **not** prescribe TODO/TDD/Fable order. It gives the model the rails and lets the model orchestrate itself.
+The retained [OpenCode evidence](../benchmarks/results/live-host/opencode-2026-09-16/README.md) supports **project-scope `.js` loading and edit/verification state on OpenCode 1.18.31 (macOS)**. The final snapshot is **post-reset**. Hard-lock is an **interactive observation** with **no retained blocked-tool trace**; reflection was **operator-seeded** and then agent-rewritten. Global scope, npm-package installation, and other OpenCode versions remain unverified.
 
-### 2. OpenCode — plugin enforcement, scoped live verification
+This evidence does not establish the new mandatory-workflow lifecycle on OpenCode. That requires its own adapter/evidence before parity is claimed.
 
-`opencode-plugin/` maps supported enforcement behavior to OpenCode's real plugin API with deterministic mechanism coverage. Partial live-host evidence supports project-scope `.js` loading and edit/verification state on OpenCode 1.18.31 (macOS): [retained evidence](../benchmarks/results/live-host/opencode-2026-09-16/README.md). The final snapshot is post-reset (`hardLock: false`, `count: 1`), not a full enforcement history. Hard lock is only an interactive observation with no retained blocked-tool trace. Reflection was operator-seeded, then agent-rewritten; state-file deletion is an agent-controlled reset, not durable hard enforcement. This does not establish behavioral effectiveness. `.mjs` auto-discovery is broken on this host version (issue #127). Global scope, npm-package installation, and other host versions remain unverified.
+### Cursor — skills plus advisory rules
 
-### 3. Cursor — skills plus advisory rules
+Cursor receives project skills and advisory rules. The semantic workflow contract can be stated, but unsupported lifecycle transitions are not mechanically enforced.
 
-The current installer uses `.cursor/skills/` plus `.cursorrules`. Cursor’s documented skill and plugin surfaces are separate from Harness runtime hooks; routing/verification/retry boundaries remain self-directed unless a compatible mechanism is independently verified.
+### GitHub Copilot agent surfaces — skills plus advisory instructions
 
-### 4. GitHub Copilot agent surfaces — skills plus advisory instructions
+Copilot receives Agent Skills/repository instructions. No Harness-specific live hook-enforcement claim is made from repository text alone.
 
-The current installer uses `.github/skills/` plus `.github/copilot-instructions.md`. GitHub’s Agent Skills paths are documented, but no Harness-specific plugin or live session is verified here.
+### Codex / local OpenAI plugin
 
-### 5. Codex — local OpenAI plugin plus advisory installer path
+Codex has multiple distinct Harness surfaces:
 
-Codex has two distinct Harness integration surfaces and documentation must keep them separate:
+- The general `--codex` installer writes repo-scoped `.agents/skills/` plus `AGENTS.md`; when consumed only as instructions, workflow enforcement is advisory/instruction-governed.
+- The **Codex / local OpenAI plugin** under `plugins/harness-everything/` packages canonical skills plus session/prompt/supported-tool/subagent/stop hooks. The package includes workflow-gate adapters, but this is mechanism/package evidence until a live Codex session proves loading/firing.
+- The public OpenAI **Skills-only** artifact excludes local `.codex-plugin` lifecycle hooks; it carries reusable workflow knowledge, not local hard gates.
 
-- The general `--codex` installer path writes Codex-facing skills/instructions such as `AGENTS.md`; where the host only consumes those instructions, that path is advisory.
-- The packaged local OpenAI plugin under `plugins/harness-everything/` includes `.codex-plugin/plugin.json`, all 26 canonical skills, and lifecycle hooks for `SessionStart`, `UserPromptSubmit`, supported local `PreToolUse` / `PostToolUse`, `SubagentStart` / `SubagentStop`, and `Stop`. Those hooks inject the compact session policy, run the invariant-first kernel, track supported edits and verification, and surface subagent scope changes.
+Do not infer Claude parity from package similarity.
 
-The local plugin therefore has **mechanism-tested local enforcement** for the packaged event/tool mappings. This is package evidence, not a live-host claim; the host's hook review/trust flow and a fresh session are still required. Do not infer broader Claude parity for events or tools that are not listed in the package.
+### Continue.dev — rules documented, standalone discovery uncertain
 
-The public OpenAI **Skills-only** submission is narrower again: it ships reusable skills and referenced assets, not the local `.codex-plugin` lifecycle hooks. Public reviewer/listing claims must describe skill/workflow behavior rather than local hook enforcement. See [openai-plugin.md](openai-plugin.md).
+Continue uses native rule files; standalone skill discovery remains separately bounded by the capability matrix.
 
-### 6. Continue.dev — rules documented, skill discovery unknown
+### Hermes Agent — trusted skills plus advisory context
 
-The installer writes `.continue/rules/harness.md` with the platform's native rules format and retains `.continue/skills/` as an adapter candidate. The reviewed official Continue documentation does not establish standalone `SKILL.md` discovery, so no skill-loading or hard-gate parity is claimed.
+Hermes uses trusted project/global skill surfaces plus advisory context. Trust/loading and lifecycle enforcement remain host-specific.
 
-### 7. Hermes Agent — trusted skills plus advisory context
+## Fable Execution Architecture
 
-The installer writes `.hermes.md` for explicit project coverage and can install trusted project skills under `.agents/skills/` plus global skills under `~/.hermes/skills/`. Project skill loading remains subject to Hermes trust; no hard-gate parity is claimed.
+Fable is the execution owner for selected `fable-*` topologies.
 
----
+```mermaid
+flowchart TD
+    P[Selected Fable plan] --> M[Stage map<br/>dependsOn + writeSet]
+    M --> B{Validated batch?}
+    B -- No --> Block[Blocked / re-plan]
+    B -- Yes --> W[Named workers]
+    W --> C[Objective stage checks]
+    C --> S[Synthesis barrier]
+    S --> V{Verification pass?}
+    V -- Yes --> D[Delivery evidence]
+    V -- No --> R{Re-plan budget remains?}
+    R -- Yes --> M
+    R -- No --> Block
+```
+
+The orchestrator controls lifecycle and completion; workers do not create peer-to-peer meshes or widen their own write scope. The model remains creative inside each bounded stage, while stage existence/checks/termination are contract state.
 
 ## Cognitive OS and Skill Mesh
 
-The Cognitive OS is a policy layer, not a parent skill that every domain skill must call.
+The Cognitive OS remains a reasoning policy:
 
 ```mermaid
 flowchart LR
@@ -148,32 +161,25 @@ flowchart LR
     Z --> T
 ```
 
-A domain skill may have its own lifecycle — for example RED/GREEN/REFACTOR inside `tdd` — without being forced into a global sequence. The only shared obligations are the kernel invariants.
-
-This separation solves the peer-skill routing problem: a strong host may correctly decide that a task primarily needs `tdd` or `security-review`; that choice is allowed. What it cannot silently erase is the routing/evidence/retry contract established by the runtime.
-
----
-
-## Security Model & Data Locality
-
-Harness runs with a local-first, zero-trust model:
+A domain skill may define RED/GREEN/REFACTOR or another local lifecycle. The selected Harness topology supplies the outer execution contract; domain skills supply tactics/stages when applicable.
 
-1. **No Harness telemetry:** runtime scripts do not upload project code or state as a Harness service.
-2. **Credential protection:** scripts do not require storing user secrets; interactive credentials remain human-controlled.
-3. **Small hook surface:** hook scripts are local Node.js programs and should stay fast and auditable.
-4. **Explicit enforcement labels:** unsupported/advisory behavior must not be documented as hard enforcement.
-5. **Deterministic regression:** mechanism and routing behavior is tested with executable CI gates rather than inferred from documentation.
+## Security and Data Locality
 
----
+1. **No Harness telemetry service:** project code/state is not uploaded by Harness runtime scripts.
+2. **Credential protection:** credentials remain human/host controlled.
+3. **Small mechanism surface:** hooks should remain fast and auditable.
+4. **Explicit enforcement labels:** instruction, mechanism, and live evidence are distinct.
+5. **Deterministic regression:** workflow/routing/hook contracts are executable CI gates.
+6. **No silent widening:** workflow escape cannot widen authorization, permissions, or external side effects.
 
 ## Validation Boundary
 
-Static configuration is not enough to claim that a host behaves correctly. Validation is layered:
+Validation is layered:
 
-- syntax/reference/manifest checks prove package integrity,
-- `ci/invariant-routing.test.js` proves the kernel contract and documentation invariants,
-- `ci/doc-capability-consistency.test.js` prevents current platform capability claims from drifting apart,
-- mechanism tests prove supported hook/plugin behavior,
-- live host sessions are required before promoting a source/mechanism-tested adapter to live host enforcement.
+- syntax/reference/package checks prove package integrity;
+- routing tests prove plan and workflow-contract semantics;
+- mechanism tests prove supported hook/plugin behavior;
+- live-host evidence proves a specific host actually loaded/fired the mechanism;
+- paired behavioral evaluation (#71) is required before claiming the new lifecycle improves outcomes.
 
-The architecture and its Mermaid diagrams are part of that contract. Runtime changes that alter orchestration must update these documents in the same change.
+The architecture diagrams are part of the contract. A runtime orchestration change must update these docs and tests in the same change.

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

@@ -1,165 +1,159 @@
 # Mechanism-First Skill Mesh
 
-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.
+Harness coordinates independently useful skills through a small workflow runtime. It does **not** make every skill part of one universal DAG, but it also does not leave selected execution topology to model discretion.
 
-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).
+The preferred shape is:
 
----
+> **mandatory applicable workflow + local skill autonomy + narrow runtime mechanisms**
+
+Platform-specific enforcement claims remain bounded by [platform-capabilities.md](platform-capabilities.md).
 
 ## Design Intent
 
-Harness exists to improve engineering collaboration, not to replace model judgment with a fixed state machine.
+Each skill remains understandable/executable on its own, while the kernel provides an outer lifecycle contract.
 
-Each skill should be able to answer four questions on its own:
+A skill should answer:
 
-1. **When should I activate?** The trigger should be clear without requiring another skill to interpret it.
-2. **What do I protect?** The skill should describe the failure mode it prevents or the engineering habit it reinforces.
-3. **What mechanism do I expose?** When possible, the skill should provide a script, command, checklist primitive, verifier, or return-value contract that makes its guidance concrete.
-4. **What should I hand to nearby skills?** The skill may recommend a next skill, but it should not require a global handoff template to remain useful.
+1. **When should I activate?** Clear `USE FOR` / `DO NOT USE FOR` applicability.
+2. **What do I protect?** The failure mode or engineering discipline it addresses.
+3. **What workflow/mechanism do I expose?** A local flow, verifier, script, gate, or stable result when useful.
+4. **What evidence means I am done?** A check, artifact, or explicit blocked state.
 
-This keeps the system composable: `tdd` can run alone, `verification-loop` can run alone, `todo-driven-workflow` can run alone, and `harness-everything` can route among them when the task benefits from orchestration.
+The router may surface several skills. Those suggestions must be evaluated from their actual `SKILL.md` flows before omission. They are **not** automatically all executed. Separately, the router selects one smallest sufficient outer topology. **The selected topology is mandatory for the run.**
 
----
+## Why Not One Global Skill Sequence?
 
-## Why Not a Single Handoff Block?
+A universal TODO/TDD/Fable sequence would:
 
-A universal handoff block makes workflow state easy to parse, but it also has costs:
+- add prompt/runtime overhead to small tasks;
+- confuse domain skills with orchestration topology;
+- suppress useful model judgment inside stages;
+- fail poorly on hosts that cannot enforce the same lifecycle APIs.
 
-- It encourages every platform and model to speak in the same rigid shape, even when a natural response would be clearer.
-- It can turn skills into a centralized workflow runner instead of a federation of local engineering disciplines.
-- It can make the model optimize for satisfying the template rather than making the best next engineering move.
-- It adds prompt weight on platforms where the mechanism cannot actually enforce the block.
+So Harness separates **topology** from **capabilities/domain skills**:
 
-Harness should avoid mandatory global handoff text. Local skills may still use concise reports when they need them, but the mesh should not depend on one universal response format.
+```text
+tier / task shape
+      +
+selected execution topology
+      +
+applicable skills/capabilities
+      +
+required invariants/gates
+```
 
----
+The topology is the lifecycle contract. Skills are resolved for applicability within/around that contract.
 
 ## Mechanisms Over Prose
 
-LLMs are highly sensitive to tool results, command outputs, exit codes, and short structured decisions. Harness should prefer those signals over long textual handoffs.
+Prefer short structured state, tool results, exit codes, and objective evidence over stronger prompt wording.
 
-Good mechanism outputs are:
-
-- **Short:** the result should be easy for the model to keep in active attention.
-- **Actionable:** the output should name the next constraint, gate, or recommended skill.
-- **Non-authoritarian:** the mechanism should guide the model without stealing all judgment from it.
-- **Portable:** hook-capable platforms can run the mechanism automatically; hook-less platforms can call the same script explicitly.
-
-Example shape:
+Example:
 
 ```text
 HARNESS_DECISION
 tier: 2
-required: route-before-execution, verify-before-claim, re-plan-after-repeat-failure
-suggest: todo-driven-workflow, verification-loop
-reason: user requested code changes
+strategy: iterative-single
+workflow_state: active
+required: route-before-execution, objective-verification, loop-budget
+suggest: tdd, verification-loop
+suggestion_policy: evaluate-applicability
+escape_policy: workflow-uncovered-scope-only
 ```
 
-This is not a handoff block. It is a compact mechanical signal. The model remains free to decide how to present the work, explain trade-offs, and collaborate with the engineer.
-
----
+This says what must happen without prescribing private reasoning or exact implementation tactics.
 
-## Skill Autonomy Contract
+Good mechanisms are:
 
-Every skill in the mesh should remain useful when loaded directly.
+- **short** enough to remain salient;
+- **actionable** with an explicit next state;
+- **failable** when a requirement is unmet;
+- **bounded** by host capability/evidence;
+- **non-prescriptive about HOW** unless a safety/contract requirement needs it.
 
-Recommended contract:
+## Skill Autonomy Contract
 
-- **Independent trigger:** the skill description should identify the problem or situation that activates it.
-- **Local workflow:** the skill should contain enough guidance to execute without reading the whole Harness ecosystem.
-- **Mechanism hook:** if a script can make the skill more reliable, expose it as an optional or required command.
-- **Neighbor links:** when another skill is commonly needed, recommend it by name and explain why.
-- **Exit discipline:** if the skill reaches a blocking state, it should say what evidence is missing or what human decision is needed.
+Every skill should retain:
 
-This contract keeps skills interoperable without requiring central ownership of every task path.
+- an independent trigger;
+- a local workflow;
+- objective/failable checks where possible;
+- explicit neighbor links rather than hidden dependencies;
+- blocked/exit discipline.
 
----
+Read-before-omission exists so the agent can inspect this local contract without loading the entire ecosystem. If the skill flow applies, follow it; reading a skill is not permission to discard an applicable discipline because the model believes it already knows the answer.
 
 ## Coordination Patterns
 
-Harness should coordinate skills through small, composable patterns.
-
 ### Router Decision
 
-`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.
+`harness-everything/scripts/kernel-router.js` emits tier, strategy, invariants, skill suggestions, and an execution contract.
 
-### Checklist State
+- Suggested skills: read and resolve applicability (`use`, `not-applicable`, `unresolved/unavailable`).
+- Selected topology: execute to resolution (`active` → verified/satisfied, blocked, or explicit evidence-backed escape).
 
-`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.
+Names/descriptions/router summaries or “routine task” judgements cannot resolve applicability by themselves.
+
+### Fable Stage Contracts
+
+For `fable-*` strategies, Fable owns stage lifecycle: `dependsOn`, `writeSet`, validated batches, objective checks, synthesis, cold verification, and bounded re-planning. The parent cannot replace a selected Fable topology with direct editing on hook-capable paths that package the workflow gate.
 
 ### Verification Gate
 
-`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.
+`verification-loop`, `verify-gate.js`, ordinary stop-gates, and Fable stage evidence provide objective completion signals. Verification is not an optional courtesy when selected/applicable workflow state requires it.
 
 ### Recovery Gate
 
-`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.
+Rule-of-3 stops repeated same-signature micro-retries and requires a new diagnosis. Fable verification failures return to bounded re-planning; budget exhaustion becomes blocked instead of endless iteration.
 
-### Skill Suggestion
+### Action Gate
 
-`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.
+Irreversible/external side effects are orthogonal to topology and require their pre-action gate where supported. Workflow escape never widens permissions or bypasses action approval.
 
----
+### Self-Evolve
 
-## Platform Strategy
+Learning should consume verified lifecycle evidence (escape, re-plan, recovery, recurrence), not operate as a side door around the active workflow.
 
-Harness should use the strongest mechanism each installation surface actually provides.
+## Platform Strategy
 
-| Platform class | Preferred coordination style | Enforcement level |
+| Platform class | Workflow contract | Mechanical enforcement |
 | --- | --- | --- |
-| 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 |
-
-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 Instruction-Only / Hook-Less Paths
-
-Do not recreate hooks with a rigid universal handoff template. Instead, make mechanisms easy to call.
+| Hook/plugin-capable | Same selected-workflow contract | Supported transitions can be blocked/observed by packaged mechanisms |
+| CLI/tool-capable without lifecycle hooks | Same contract stated/called explicitly | Instruction/mechanism guided; no automatic blocking claim |
+| Prompt-only | Same semantic obligations | Self-regulated only |
 
-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`):
+Contract semantics and enforcement evidence are separate. Claude currently packages the broadest Harness lifecycle surface. The local OpenAI/Codex plugin packages supported adapters but requires live-host evidence before parity claims. The public OpenAI Skills-only artifact carries skill/workflow knowledge without local lifecycle hooks. OpenCode has its own plugin path and evidence boundaries.
 
-- `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.
+## Hook-Less Paths
 
-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.
+Two explicit commands provide high-signal state without pretending hooks exist:
 
-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. 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 instruction-only Codex installs, Cursor, Copilot, Continue, and Hermes receive high-signal mechanical feedback without forcing them into a single scripted conversation shape.
+```bash
+npx github:dyphn1/Harness-everything next "<prompt>"
+npx github:dyphn1/Harness-everything verify
+```
 
----
+`next` emits the routing/workflow contract. `verify` runs the explicit verification path. Instruction-only hosts must treat these requirements as real even though the host cannot mechanically prevent skipping them.
 
 ## Anti-Goals
 
 Harness should not become:
 
-- A centralized DAG runner where every skill depends on one global workflow file.
-- A mandatory response-template system that suppresses useful model variation.
-- A command-only framework where skills cannot be understood by reading `SKILL.md`.
-- A hidden daemon that performs broad actions without visible evidence.
-- A platform-specific product that only works well when Claude Code hooks are available.
-
-The mesh should remain local, legible, and cooperative.
-
----
+- one global DAG containing every skill;
+- a mandatory response-template system;
+- a command-only framework whose skills are unreadable without runtime code;
+- a hidden daemon with broad authority;
+- a system that claims cross-host hard enforcement from package text;
+- a recommendation system where selected workflows can be rationalized away.
 
 ## Practical Authoring Rules
 
-When adding or revising a skill:
-
-1. Keep the skill independently executable.
-2. Add a script only when a mechanism can make the behavior more reliable than prose.
-3. Keep script output compact and stable enough for models to react to.
-4. Prefer gates at natural decision points: before editing, after repeated failure, before final delivery, and before persistence.
-5. Let the model choose wording and presentation unless the skill truly needs a specific artifact format.
-6. Document neighboring skills as recommendations, not hidden dependencies, unless the dependency is required for safety.
+1. Keep skills independently understandable/executable.
+2. Put applicability/basic flow in `SKILL.md`; deep detail belongs in references.
+3. Add mechanisms when they make behavior more reliable than prose.
+4. Make checks failable and evidence-based.
+5. Put gates at real transition boundaries: before mutation/side effects, after repeated failure, before completion, before persistence.
+6. Let the model choose HOW inside the contract.
+7. Treat workflow escape as a measured coverage gap, not convenience.
 
-The result should feel like an engineering co-pilot with good reflexes: autonomous where creativity matters, constrained where repeated mistakes are expensive, and explicit whenever evidence is needed.
+The result should feel like a capable engineer operating inside explicit lifecycle obligations rather than either a scripted automaton or an unconstrained model that can skip its own process.

package/docs/openai-plugin.md

@@ -28,7 +28,7 @@ flowchart TD
     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`.
+The local OpenAI adapter enforces cross-cutting invariants through the lifecycle events that it packages. Suggested skills require applicability evaluation; the selected topology is mandatory with scoped, evidence-backed escape. The [workflow runtime](workflow-runtime.md) documents pending/running/satisfied/blocked state, Fable entry, worktree isolation, completion evidence, and degradation limits. Tool enforcement is limited to the host tool names declared in `hooks/hooks.json`.
 
 ## Package layout