harness-everything 0.8.0 → 0.9.0

package/docs/architecture.md

@@ -1,150 +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,
-- when the router suggests skills, require the agent to read/evaluate each suggested `SKILL.md` before omission,
-- require evidence before completion claims,
-- stop repeated same-signature micro-retries and re-plan,
-- leave domain-skill execution, ordering, planning style, and delegation to the agent after evaluation.
+- 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.**
 >
-> **Mandatory evaluation, advisory execution:** a suggested skill must be read/evaluated before skip, but need not be executed when its flow does not apply.
+> 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. It is also stronger than a pure recommendation system where the model can ignore suggestions from their names alone.
+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 invariants]
-        Inv --> Sug{Suggested skills?}
-        Sug -- Yes --> Eval[Read each suggested SKILL.md<br/>evaluate flow + applicability]
-        Sug -- No --> Choice[Agent chooses useful tactics]
-        Eval --> Choice
-    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,
-- baseline required invariants,
-- a conditional `evaluate-suggestions-before-skip` invariant whenever suggestions exist,
-- skill suggestions under a **mandatory evaluation / advisory execution** contract.
+- tier + rationale,
+- selected/deferred execution strategy,
+- required invariants,
+- suggested skills that require applicability evaluation,
+- the visible routing checkpoint,
+- a workflow execution contract.
 
-For each suggested skill, the agent must read the complete `SKILL.md` entry and evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules before omission. A skill name, description, router summary, tier label, or “routine task” judgement is not enough to justify skipping. If the entry explicitly requires another document to determine applicability, that required material joins the evaluation; optional deep-dive references do not automatically become mandatory.
+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.
 
-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. Using one suggested skill also does not waive evaluation of the other omitted suggestions.
+### Skill applicability vs. topology execution
 
-`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.
+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.
 
----
+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.
 
-## Integration Touchpoints
+### Runtime workflow state
 
-Harness aligns to each host's real capabilities. Enforcement strength is platform-specific; shared skill text does not prove mechanism parity.
+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.
 
-### Self-healing and placement
+For selected Fable topologies on Claude:
 
-`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.
+- `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).
 
-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.
+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.
 
-### Runtime state vs. skill content
+## 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 and tells the agent that every suggested skill must be evaluated before omission.
-- `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.
 
-The prompt hook is intentionally lightweight: it does **not** prescribe TODO/TDD/Fable order. It injects the routing rails and the read-before-skip requirement, then lets the model orchestrate execution after evaluation. Kernel emission by itself is not proof that the host/model actually read each skill; that requires retained live behavioral evidence.
+### OpenCode — plugin enforcement, scoped live verification
 
-### 2. OpenCode — plugin enforcement, scoped live verification
+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.
 
-`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.
+This evidence does not establish the new mandatory-workflow lifecycle on OpenCode. That requires its own adapter/evidence before parity is claimed.
 
-### 3. Cursor — skills plus advisory rules
+### Cursor — skills plus advisory rules
 
-The current installer uses `.cursor/skills/` plus `.cursorrules`. Cursor’s documented skill and plugin surfaces are separate from Harness runtime hooks; routing/verification/retry boundaries and read-before-skip remain instruction-governed unless a compatible mechanism is independently verified.
+Cursor receives project skills and advisory rules. The semantic workflow contract can be stated, but unsupported lifecycle transitions are not mechanically enforced.
 
-### 4. GitHub Copilot agent surfaces — skills plus advisory instructions
+### GitHub Copilot agent surfaces — skills plus advisory instructions
 
-The current installer uses `.github/skills/` plus `.github/copilot-instructions.md`. GitHub’s Agent Skills paths are documented, but no Harness-specific plugin or live session is verified here. The generated instructions include read-before-skip, but repository text alone is not live compliance evidence.
+Copilot receives Agent Skills/repository instructions. No Harness-specific live hook-enforcement claim is made from repository text alone.
 
-### 5. Codex — local OpenAI plugin plus advisory installer path
+### Codex / local OpenAI plugin
 
-Codex has two distinct Harness integration surfaces and documentation must keep them separate:
+Codex has multiple distinct Harness surfaces:
 
-- 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 generated `AGENTS.md` tells the agent to evaluate every router-suggested skill entry before omission.
-- The packaged local OpenAI plugin under `plugins/harness-everything/` includes `.codex-plugin/plugin.json`, all 26 canonical skills, and lifecycle hooks for `SessionStart`, `UserPromptSubmit`, supported local `PreToolUse` / `PostToolUse`, `SubagentStart` / `SubagentStop`, and `Stop`. Those hooks inject the compact session policy, run the invariant-first kernel, track supported edits and verification, and surface subagent scope changes.
+- The 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 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, and do not infer that mechanism-tested prompt injection proves the model complied with read-before-skip.
+Do not infer Claude parity from package similarity.
 
-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.dev — rules documented, standalone discovery uncertain
 
-### 6. Continue.dev — rules documented, skill discovery unknown
+Continue uses native rule files; standalone skill discovery remains separately bounded by the capability matrix.
 
-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 Agent — trusted skills plus advisory context
 
-### 7. Hermes Agent — trusted skills plus advisory context
+Hermes uses trusted project/global skill surfaces plus advisory context. Trust/loading and lifecycle enforcement remain host-specific.
 
-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 Execution Architecture
 
----
+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
@@ -157,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 shared obligations are the baseline kernel invariants plus read-before-skip when router suggestions exist.
-
-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 or dismiss other suggestions without evaluating their actual skill flows.
-
----
-
-## 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, read-before-skip, and documentation contracts,
-- `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 or claiming that agents actually followed the evaluation contract.
+- 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,170 +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 to execute, coordination is explicit, and enforcement happens at narrow decision points through scripts, hooks, exit codes, and compact return values. Router-suggested skills are **mandatory to evaluate before omission, but advisory to execute after evaluation**. 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 not execute every suggestion, but it may not discard suggestions without first reading/evaluating their actual `SKILL.md` flows.
+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. The routing checkpoint is a compact state/evaluation surface, not a global handoff protocol.
+```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 about execution:** the mechanism may require an evaluation step without forcing a universal workflow sequence.
-- **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, evaluate-suggestions-before-skip
-suggest: todo-driven-workflow, verification-loop
-suggestion_policy: mandatory-evaluation/advisory-execution
-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 after it has evaluated the suggested skill flows.
-
----
+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:
 
-The local workflow is why read-before-skip can work: the agent can inspect a suggested skill's complete entry and basic flow to judge applicability without loading the whole ecosystem. Optional deep references remain optional unless that entry explicitly makes one necessary to determine applicability.
+- 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 skill suggestions. Suggestions use a **mandatory evaluation / advisory execution** contract: before omission, read the complete suggested `SKILL.md` entry and evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. 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.
 
-A name, frontmatter description, router summary, tier label, or “routine task” judgement is not enough to skip a suggestion. Using one suggestion does not waive read-before-skip for the others. If a suggestion cannot be resolved/read, preserve `unresolved/unavailable` rather than silently converting it into “not applicable.”
+- 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).
 
-### Checklist State
+Names/descriptions/router summaries or “routine task” judgements cannot resolve applicability by themselves.
 
-`todo-driven-workflow` may own explicit task decomposition state when that helps a Tier 2 or Tier 3 task. It is not a universal prerequisite. When the router suggests it, however, the agent must evaluate its actual skill flow before deciding that native host TODO tracking, a Markdown checklist, or no explicit checklist is the better choice.
+### 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. If `verification-loop` is router-suggested, read/evaluate its flow before omission even though the kernel already carries a verify-before-claim invariant.
+`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. Once the router surfaces a likely skill, the suggestion becomes an evaluation obligation: inspect its real entry/basic flow before deciding whether it applies. This does **not** make execution mandatory and does not create a fixed pipeline.
+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; prompt routing can inject the read-before-skip contract | Mechanical injection/blocking is possible for packaged mechanisms; actual model compliance with skill evaluation still needs live behavioral evidence |
-| CLI/tool-capable but hook-less surfaces | The model explicitly calls Harness scripts at decision points and reads/evaluates suggested skills | Mechanism-guided/instruction-governed, not automatically enforced |
-| Prompt-only surfaces | Advisory instructions include command snippets and read-before-skip decision rules | Self-regulated by the model |
+| 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 |
 
-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.
+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.
 
-OpenCode is plugin-capable and has partial live-host evidence for project-scope loading/state effects, but the read-before-skip behavioral contract still requires separate retained evidence before being called live-enforced. Claude Code has the broadest currently verified Harness lifecycle-hook surface.
+## Hook-Less Paths
 
----
+Two explicit commands provide high-signal state without pretending hooks exist:
 
-## Guidance for Instruction-Only / Hook-Less Paths
-
-Do not recreate hooks with a rigid universal handoff template. Instead, make mechanisms easy to call and make the evaluation requirement explicit.
-
-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>"`: runs the Harness routing path and prints the recommended tier, invariant contract, and matching knowledge/skill suggestions. Every suggested skill must then be read/evaluated before omission.
-- `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.
-
-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.
-- A recommendation system whose suggestions are routinely ignored without inspecting the workflows they represent.
-
-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. Put enough applicability and basic-flow information in `SKILL.md` for read-before-skip evaluation; do not hide the decision-critical contract only in optional deep references.
-3. Add a script only when a mechanism can make the behavior more reliable than prose.
-4. Keep script output compact and stable enough for models to react to.
-5. Prefer gates at natural decision points: before editing, after repeated failure, before final delivery, and before persistence.
-6. Let the model choose wording and presentation unless the skill truly needs a specific artifact format.
-7. Document neighboring skills as recommendations, not hidden execution dependencies, unless the dependency is required for safety. Router-surfaced recommendations still inherit mandatory evaluation before omission.
+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 or applicability evaluation 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.