harness-everything 0.7.0 → 0.8.1

package/docs/philosophy.md

@@ -1,58 +1,68 @@
 # Harness Philosophy
 
-Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.**
+Harness is built on a simple observation: **strong AI coding models reason well, but can still self-authorize away process obligations when they believe the task is already clear.**
 
-Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral layer** — reusable skills plus the strongest lightweight runtime mechanisms each supported installation surface actually provides.
+Harness therefore separates reasoning freedom from workflow reliability. It does not prescribe the model's chain of thought or force one giant pipeline. Instead, it establishes the smallest applicable lifecycle contract and lets the model choose how to satisfy it.
 
-The current mechanism/enforcement boundary is platform-specific; see [Platform Capability Matrix](platform-capabilities.md). A skill-only or instruction-only install must not be described as if it automatically runs lifecycle hooks.
+The mechanism/enforcement boundary remains platform-specific; see [Platform Capability Matrix](platform-capabilities.md). A semantic contract can be mandatory even when an instruction-only host cannot mechanically block every violation, so contract strength and host enforcement evidence must be reported separately.
 
----
+## Core Philosophy: Constrain Lifecycle, Not Reasoning
 
-## The Core Philosophy: Intervene Only When Necessary
+1. **Reasoning autonomy remains high.** The model chooses implementation technique, tools, decomposition details, and tactics inside the selected workflow.
+2. **Applicable workflow is mandatory.** Once routing selects a topology, it must be executed to resolution. Model confidence, “simple”, “routine”, and “already clear” are not escape conditions.
+3. **Skill applicability is explicit.** Router-suggested skills are read/evaluated before omission. A suggestion can be `not-applicable` when its actual flow does not match; a selected topology is stronger and cannot simply be skipped.
+4. **Escape is conditional, not default.** If the selected workflow genuinely cannot represent part of the task, record the uncovered scope and evidence, then allow model-defined handling only for that uncovered portion.
+5. **Mechanisms beat stronger wording.** Important lifecycle transitions should use structured state, objective evidence, hooks/plugins, exit codes, and completion gates where the host supports them rather than escalating `MUST`/`CRITICAL` prose.
 
-Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it can suppress useful model judgment on complex, novel engineering work.
+This principle can be summarized as:
 
-Harness takes the opposite approach:
+> **Mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only where the workflow does not cover the task.**
 
-1. **Model Autonomy is Paramount:** The model should have freedom to explore, choose useful skills/tools, and design its solution inside a small set of cross-cutting invariants.
-2. **Context-Driven Guidance:** Harness uses high-context, low-friction signals — skills, rules, local checks, and hooks/plugins where the host supports and packages them — rather than one rigid global execution path.
-3. **Reactive Guardrails:** On integration surfaces that expose the required lifecycle/tool hooks, Harness can stay quiet until a boundary is violated or a repeated failure is detected. On advisory surfaces, the same principles remain guidance rather than automatic blocking.
-4. **Behavior-First, Not Prompt-First:** Harness is not a collection of magic prompts. Its skills remain independently useful, while supported runtime adapters can react to real tool/session outcomes and workspace conditions.
+The goal is not to make the model less capable. It is to prevent capability/confidence from silently deleting engineering obligations such as verification, bounded re-planning, stage checks, documentation checks, or safety gates when those obligations are applicable.
 
----
+## Why This Is Not a Rigid Global Pipeline
 
-## The 4 Pillars of AI Model Guidance
+Harness still rejects a universal `TODO → TDD → Fable → verification` sequence.
 
-To keep agents aligned and productive, Harness operates across four distinct domains. The **principle** applies everywhere; whether it is injected or enforced automatically depends on the selected host surface.
+The router chooses the **smallest sufficient topology**:
 
-### 1. Environment Alignment (Discovery over Assumption)
+- `direct-single` for bounded one-pass work;
+- `iterative-single` for ordinary bounded reason/act work with objective verification;
+- `fable-staged` for dependent multi-stage work;
+- `fable-parallel` only for validated independent workstreams;
+- `fable-multi-agent-workspace` when persistent roles/handoffs/memory are materially needed.
 
-AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shell, or package manager — especially on Windows or mixed-shell setups.
+Domain skills remain conditional on applicability. The contract says “execute the selected lifecycle”, not “execute every skill in the repository.”
 
-Harness requires environment assumptions to be discovered rather than guessed. On surfaces that package a session-start/preflight hook, that context can be injected automatically. On instruction/skill-only paths, the agent must discover it explicitly before relying on shell-specific commands.
+## The 4 Pillars of AI Model Guidance
 
-### 2. Guardrails (The Circuit Breakers)
+### 1. Environment Alignment — Discovery over Assumption
 
-When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly.
+Discover OS, shell, package/runtime context, repository boundaries, and available host capabilities before relying on them. On surfaces that package preflight/session hooks this can be injected automatically; instruction-only hosts must do it explicitly.
 
-The Harness recovery invariant is to stop same-signature micro-retries and re-plan after repeated failure. On hosts where the Rule-of-3 mechanism is actually packaged, a circuit breaker can track failures and block further mutation until a `zoom-out` diagnosis is performed. On other surfaces, `zoom-out` remains a reusable recovery discipline but there is no claim that an automatic counter/blocker exists.
+### 2. Guardrails — Lifecycle Boundaries
 
-### 3. Context Preservation (Anti-Bloat Protection)
+Circuit breakers, action gates, workflow gates, scope guards, and completion gates protect specific transitions. They should remain narrow and evidence-driven. On integration surfaces that expose the required lifecycle/tool hooks, Harness can mechanically block supported violations; elsewhere the same contract is instruction-governed and must not be mislabeled hard enforcement.
 
-As sessions grow, models can read too broadly or produce oversized output, degrading active context.
+### 3. Context Preservation — Progressive Disclosure
 
-Harness uses narrow reads, explicit scope, compact evidence, and — where a compatible runtime adapter exists — boundary mechanisms that can react mechanically. Skill-only surfaces still receive the discipline, but not an imaginary background daemon or hook.
+Load the smallest useful context. Read a suggested skill's complete entry before deciding applicability, but do not load the entire skill tree or every optional deep reference. Machine-visible workflow state should carry lifecycle facts instead of repeating large prompt blocks.
 
-### 4. Self-Evolution (Continuous Workspace Memory)
+### 4. Self-Evolution — Learn from Workflow Evidence
 
-When a complex issue is resolved, Harness can turn the verified lesson into durable workspace knowledge through `self-evolve`: a concise rule or a reusable generated skill, when persistence is actually justified.
+`self-evolve` should learn from verified recovery and workflow gaps: escape events, repeated replans, verifier fail→pass transitions, and recurrence outcomes. It should improve future coverage rather than granting a shortcut around the current workflow. Durable learning remains distinct from runtime session state.
 
-This long-term learning path is distinct from **runtime session state** such as WAL/checkpoint files. Runtime state exists only on integrations that package the corresponding state hooks; reusable rules/skills are project artifacts and can outlive a single host session.
+## Mechanism-First Cooperation
 
----
+Harness prefers a compact control loop:
 
-## A Non-Intrusive Cognitive Amplifier
+```text
+route -> select workflow -> execute -> verify
+                              | fail -> bounded re-plan
+                              | uncovered -> evidence-backed escape
+                              | pass -> complete
+```
 
-Harness does not require a heavy daemon or a proprietary service. The repository's mechanisms and skill content operate locally in the developer/host environment, while each platform gets only the enforcement strength its real integration supports.
+This leaves creativity where stronger models benefit from it while making lifecycle obligations observable and testable.
 
-For skill-level coordination, see [Mechanism-First Skill Mesh](mechanism-first-skill-mesh.md). For the exact current platform/install/evidence boundary, see [Platform Capability Matrix](platform-capabilities.md).
+For skill-level coordination, see [Mechanism-First Skill Mesh](mechanism-first-skill-mesh.md). For current installation/enforcement/evidence status, see [Platform Capability Matrix](platform-capabilities.md).

package/docs/platform-capabilities.md

@@ -17,6 +17,12 @@ Statuses are intentionally explicit:
 
 All `liveHostVerification` rows except OpenCode are `Unknown`. OpenCode's row is `Partial`: retained evidence supports project-scope `.js` loading and edit/verification state on OpenCode 1.18.31 (macOS), not durable hard enforcement. No fresh artifacts exist yet for the other surfaces, managed-workspace import, or public OpenAI approval.
 
+### Routing contract vs. host evidence
+
+The repository routing contract uses **mandatory applicable workflow / conditional scoped escape**. Each suggested skill still requires reading its complete `SKILL.md` entry/basic flow before omission; the selected topology must resolve its applicable lifecycle obligations. A name, description, router summary, tier label, or generic “routine task” judgement is not enough skip evidence; unreadable suggestions are `unresolved/unavailable`, not silent skips.
+
+This is a **repository/agent contract**, not an automatic upgrade to any platform row below. A hook can prove that the contract was injected into a session; it does not prove the model actually read every suggested skill. Instruction-only surfaces can carry the same rule without mechanically enforcing it. Promoting this behavior to live-host compliance requires retained host/session evidence under the #82 compatibility program. The Claude and local OpenAI packages now carry workflow entry/completion gates, but this package/mechanism change does not upgrade `platform-compatibility.json` live-host status values. See [workflow runtime](workflow-runtime.md) for scope, worktree isolation, and failure behavior. OpenCode and instruction-only/public Skills-only surfaces do not acquire equivalent runtime gating. Shell inspection is not a filesystem sandbox; absent hooks, agent-writable state, and indirect script effects remain limits.
+
 ## Current capability summary
 
 | Platform surface | Standalone skills | Plugin support | Hooks/lifecycle | Project scope | Global scope | Current evidence boundary |
@@ -47,14 +53,16 @@ The general installer’s target paths are tested independently from host discov
 
 These targets apply to both default link mode and explicit `--copy` mode. A canonical store is only a deduplication detail; it cannot make an unsupported host path supported. Install/uninstall tests also protect user-owned files and cover Linux, Windows, and macOS round-trip fixtures.
 
+The advisory installer text generated for Codex/Cursor/Copilot/Continue/Hermes carries the same read-before-skip rule. That proves only what Harness writes, not that the host/model complied with it.
+
 ## Codex / local OpenAI plugin boundary
 
 Codex has two paths that must not be collapsed:
 
-1. The general `--codex` installer writes advisory `AGENTS.md` plus repo-scoped skills under `.agents/skills/`.
+1. The general `--codex` installer writes advisory `AGENTS.md` plus repo-scoped skills under `.agents/skills/`. Its generated instructions require reading/evaluating every router-suggested skill before omission, but this remains instruction-governed.
 2. The local OpenAI plugin at `plugins/harness-everything/` packages the skills plus lifecycle hooks for session start, prompt routing, supported local tool calls, subagent lifecycle, and stop verification. Those hooks are mechanically checked, but no live plugin/session artifact is committed.
 
-The package is tested at the mechanism layer and remains subject to the host’s hook review/trust flow. A fresh host session is still required before claiming that a particular ChatGPT/Codex installation loaded and fired the hooks.
+The package is tested at the mechanism layer and remains subject to the host’s hook review/trust flow. A fresh host session is still required before claiming that a particular ChatGPT/Codex installation loaded and fired the hooks or that the model followed read-before-skip.
 
 The public OpenAI Skills-only plugin is narrower again. Its ZIP contains the packaged `skills/` tree and referenced files, but not the local `.codex-plugin` lifecycle hooks. Public submission readiness is therefore a package/form contract, not evidence of public-directory approval or live hook execution.
 

package/docs/reviews/pr-142-issue-131.md

@@ -0,0 +1,89 @@
+# PR #142 / issue #131 completion review
+
+This review covers the implementation in the commit containing this report,
+starting from PR head `8b99baec44745e171f078fe9eb3dac6fd812b5c8`. It evaluates
+Harness engineering and the latest #131 decision, including mandatory mutation
+isolation. It is not a measured agent-performance benchmark.
+
+## Findings resolved
+
+| Original gap | Delivered behavior | Regression evidence |
+| --- | --- | --- |
+| Escape changed the whole workflow state and skipped isolation | Stage-scoped escape; isolation survives legacy escape and blocked states | `mechanism-2af-worktree-isolation.test.js`, `mechanism-2ah-workflow-lifecycle.test.js` |
+| Only cwd was checked | Registered linked checkout of the bound repo; direct/patch targets, move destinations, traversal, and links checked | `mechanism-2af-worktree-isolation.test.js` |
+| Windows runner used 8.3 paths while Git reported long names | Native physical-path resolution equates both spellings without relaxing isolation | Windows path regression and worktree suites |
+| Read-only shell prefixes accepted writes | Reject redirects, substitutions, chained commands and dangerous options; require isolated cwd for mutation/unknown commands | `mechanism-2af-worktree-isolation.test.js` |
+| Next prompt erased unresolved obligations | Stable workflow identity across steering prompts; stronger route requires replan | `mechanism-2ah-workflow-lifecycle.test.js` |
+| Same strategy/timestamp loosely matched any Fable run | Exact workflow, session and run correlation | `mechanism-2ah-workflow-lifecycle.test.js` |
+| Entry gate blocked its own bootstrap path | One bounded stage-specification file and trusted start controller; state/source writes remain gated | `mechanism-2ah-workflow-lifecycle.test.js` |
+| Stop trusted directory contents and pass labels | Expected manifest stages, correlated exit-zero evidence, worker attribution and fresh verifier required | `mechanism-2ah-workflow-lifecycle.test.js` |
+| Stop retry silently passed unresolved work | Retry records blocked; no satisfied state without required evidence | `mechanism-2ah-workflow-lifecycle.test.js` |
+| Failures could not recover cleanly | Observed fail-to-pass checks; explicit bounded replan; retained prior run evidence | `mechanism-2ah-workflow-lifecycle.test.js` |
+| Runtime policy scraped human-readable output | Kernel imports the structured core result; complete invariants persist with the plan | routing tests and lifecycle tests |
+| Current documents contradicted the PR | README, platform matrix, routing, architecture, Fable/worktree references and mirrors aligned | consistency/capability/reference gates |
+| Existing CI selected the first matching hook group | Action-gate regression finds its actual adapter among shared tool matchers | `ci/action-gate.test.js` |
+
+The first added isolation regression run failed 16 assertions against the PR
+baseline, then passed after repair. The baseline's four failing GitHub CI jobs
+also reported the action-gate matcher defect. The initial local checkout lacked
+dependencies, producing a separate CRLF-fixture setup failure; `npm ci` resolved
+that environment prerequisite.
+
+## Verification
+
+Local environment: Windows, PowerShell, Node.js 24.15.0, npm 11.12.1. Work was
+performed in an isolated linked worktree; the primary checkout remained clean.
+
+All 14 required gate categories passed: `npm test`, mutations, mechanism,
+consistency, repository contract, capability docs, references, release,
+collision, positive skill routing, routing invariants, OpenAI package/runtime,
+public submission, and platform compatibility. Failed checks were corrected and
+the affected gates rerun. The final `npm test` includes **44 mechanism suites**.
+
+The new lifecycle suite exercises **50 assertions against source and the same
+50 against the packaged OpenAI layout**, using actual child processes, Git
+repositories, worktrees, controller commands and hook payloads. Host payloads
+are fixtures: these are deterministic mechanism tests, not live agent sessions.
+
+Waza passed 30 canonical/nested skill readiness checks, 26 routing-spec checks,
+and token validation (57 successful commands). Positive routing covered 34
+cases across 26 direct skills and classified four nested skills.
+
+Build/types/lint have no separate project scripts; repository syntax and
+consistency gates apply. No coverage percentage is claimed. The security scanner
+reported 12 pre-existing documentation/test-pattern matches, including its own
+patterns and an explicitly fake token fixture; changed production code added no
+scanner findings. `npm ci` reported zero dependency vulnerabilities. Diff review
+and `git diff --check` passed. See the retained [gate summary](../../benchmarks/results/reviews/pr142-verification.json).
+
+Remote CI is a separate evidence layer. Its result must be read at the final PR
+head; this local record does not assert a future GitHub Actions outcome.
+
+## Reassessment
+
+Scores are review judgments about engineering readiness, each out of 100.
+Each row has four equally weighted criteria (25 points each), with the observed
+deductions shown. They are not success probabilities or benchmark results.
+
+| Dimension | Criteria scores | Total | Remaining deductions |
+| --- | --- | ---: | --- |
+| Contract coherence | entry 22, transitions 23, scoped exceptions 24, docs 23 | 92 | Skill applicability and iterative budgets still partly rely on executor compliance |
+| Mutation safety | worktree identity 23, targets 23, shell handling 17, state trust 12 | 75 | Arbitrary script effects need a host sandbox; runtime state is agent-writable |
+| Deterministic verification | gate breadth 25, negative cases 24, package parity 24, evidence checks 18 | 91 | Host-shaped fixtures cannot establish real host behavior or semantic check quality |
+| Operation and maintenance | entry/recovery 22, modularity 21, distribution 23, diagnostics/migration 18 | 84 | Manual stage setup, missing-metadata blocks and legacy-state repair add operator work |
+
+Equal-weight engineering score: **85.5/100** (approximately **86/100**).
+The system now has substantially stronger tested lifecycle and isolation
+contracts. It is suitable for further host validation with explicit boundaries.
+
+**Live-host reliability of these new gates remains unverified. Behavioral gain
+from this PR remains unmeasured.** Neither receives an invented effectiveness
+score. Older retained OpenCode evidence and older behavioral cases cannot prove
+this workflow change. This review does not claim superiority over other skill
+collections, reduced token cost, or improved task success rates.
+
+The next evidence needed is a retained Claude/Codex session showing routing,
+entry, mutation denial/allow, numeric stage results, worker correlation and Stop
+resolution; then paired same-model/same-task behavioral runs. OpenCode needs its
+own adapter before parity can be claimed. See [runtime limits](../workflow-runtime.md)
+and [platform capabilities](../platform-capabilities.md).

package/docs/routing.md

@@ -1,22 +1,26 @@
 # Harness Routing & Task Triage
 
-Harness classifies software work into three tiers to prevent both over-engineering and under-planning. **The tier is a scope recommendation, not a workflow pipeline.**
+Harness classifies software work and selects the smallest sufficient execution topology. **A tier is a scope/risk signal, not a fixed skill sequence. A selected topology is an execution contract, not an optional suggestion.**
 
-The current architecture follows one rule:
+The current architecture follows two coupled rules:
 
-> **Do not enforce workflow order. Enforce workflow invariants.**
+> **Mandatory applicable workflow; flexible reasoning/implementation inside it.**
+>
+> **Skill applicability is evaluated explicitly; workflow escape is exception-only and evidence-backed.**
 
-A strong model should be free to decide how to complete the task. Harness protects only the small set of behaviors that must not disappear when the host chooses a peer/domain skill directly.
+A strong model remains free to decide *how* to perform the work. It may not decide that an applicable selected lifecycle can be skipped because the task feels simple or already understood.
 
 ## Kernel invariants
 
-For software/project work, Harness establishes three mandatory rails before mutation:
+For software/project work, Harness establishes mandatory rails before mutation:
 
-1. **Route before execution** — establish task scope/tier.
+1. **Route before execution** — establish scope/tier and the smallest justified topology.
 2. **Verify before claim** — completion requires objective evidence appropriate to the change.
 3. **Re-plan after repeated failure** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
+4. **Evaluate before omission** — read every suggested skill's complete `SKILL.md` entry before deciding applicability.
+5. **Resolve selected workflow** - successful completion requires `satisfied`; `blocked` is a reportable incomplete outcome. Escape covers only a declared stage and preserves other obligations.
 
-Skill selection, ordering, planning style, and delegation remain agent decisions unless the user or an authoritative project contract explicitly requires them.
+The model owns tools, implementation technique, reasoning, and decomposition details inside those rails.
 
 ## Public routing path
 
@@ -24,9 +28,10 @@ Skill selection, ordering, planning style, and delegation remain agent decisions
 kernel-router.js
   ├─ delegates classification / guide discovery → tier-router.js
   ├─ preserves tier + rationale + dynamic-skill recommendations
-  ├─ suppresses legacy fixed-pipeline wording
-  ├─ emits required invariants
-  └─ emits advisory skill suggestions
+  ├─ emits required invariants + structured workflow plan
+  ├─ requires applicability evaluation for suggested skills
+  ├─ activates the selected workflow execution contract
+  └─ exposes explicit blocked/degraded/escape state instead of silent downgrade
 ```
 
 Use:
@@ -37,13 +42,29 @@ node harness-everything/scripts/kernel-router.js "<prompt>"
 npx github:dyphn1/Harness-everything next "<prompt>"
 ```
 
-On a host where `UserPromptSubmit` is wired, reuse the hook output instead of running it twice.
+On a host where `UserPromptSubmit` is wired, reuse that hook output instead of running it twice.
 
-## Non-software bypass
+## Suggested skills vs. selected workflow
 
-General Q&A, translation, ordinary web search, and non-software writing bypass Harness routing. The model should answer directly and naturally.
+These are intentionally different concepts.
 
-A software prompt that already says "use TDD", "security review", `repo-docs`, or another skill **does not bypass the kernel**. Host skill routing and Harness routing are different layers: the kernel establishes cross-cutting invariants; the host/model selects useful expertise.
+For **every suggested skill**:
+
+1. Resolve/read the complete `SKILL.md` entry.
+2. Evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules.
+3. Read extra material only when the entry explicitly requires it for applicability.
+4. Resolve the suggestion as `use`, `not-applicable`, or `unresolved/unavailable`.
+
+A name, description, router summary, tier label, or generic “routine/common task” judgement is not sufficient evidence for `not-applicable`.
+
+For the **selected workflow topology**:
+
+- enter it and execute it to resolution;
+- do not silently replace it with a weaker/direct path because the model is confident;
+- preserve objective checks, stage contracts, synthesis barriers, re-plan limits, and other obligations selected by the plan;
+- use escape only for genuinely uncovered workflow scope, recording reason + uncovered scope + evidence.
+
+This prevents two opposite failures: forcing every task through one giant pipeline, and allowing a model to rationalize away the entire engineering lifecycle.
 
 ## Three-tier recommendation model
 
@@ -51,121 +72,65 @@ A software prompt that already says "use TDD", "security review", `repo-docs`, o
 flowchart TD
     U([User Request]) --> S{Software / project work?}
     S -- No --> B[Bypass Harness]
-    S -- Yes --> K[Harness Kernel<br/>scope + invariants]
-    K --> T{Tier recommendation}
-    T -- Tier 1 --> A[Agent self-orchestrates]
-    T -- Tier 2 --> A
-    T -- Tier 3 --> A
-    A --> E[Execute selected tactics / skills]
-    E --> V{Evidence supports completion?}
-    V -- Yes --> D([Done])
-    V -- No --> R[Diagnose and iterate]
-    R --> F{Same failure x3?}
-    F -- No --> E
-    F -- Yes --> Z[Zoom out / re-plan]
-    Z --> E
+    S -- Yes --> K[Kernel: classify + select topology]
+    K --> W{Strategy selected?}
+    W -- Deferred --> D[Keep invariants<br/>choose smallest justified workflow]
+    W -- Selected --> A[ACTIVE workflow contract]
+    A --> E[Execute with model-chosen tactics]
+    E --> V{Workflow obligations resolved?}
+    V -- Yes --> Done([Evidence-backed completion])
+    V -- No --> X[Diagnose / re-plan / satisfy missing stage]
+    X --> E
 ```
 
 ### Tier 1 — Trivial
 
-Typical triggers: typos, narrow single-file edits, straightforward cleanup, code explanation, simple Git operations.
-
-Guidance:
-- prefer direct execution,
-- avoid large plans/delegation,
-- load a focused skill only when it adds value,
-- still gather enough evidence to support the completion claim.
+Typical triggers: typo/docs correction, narrow local edit, bounded explanation, straightforward Git operation. Usually selects `direct-single`; keep overhead minimal while still satisfying applicable verification/safety rails.
 
 ### Tier 2 — Standard
 
-Typical triggers: normal feature work, bug fixes, multi-file changes, security review, focused benchmark/evaluation.
-
-Possible suggestions:
-- `todo-driven-workflow` when explicit progress tracking helps,
-- `tdd` when executable behavioral tests are a useful design/verification tool,
-- `verification-loop` when systematic build/lint/test/diff selection helps,
-- `security-review` for trust/input/auth/secrets/network boundaries,
-- `using-git-worktrees` where isolation reduces workspace risk,
-- `eval-harness` for quantitative scoring.
+Typical triggers: normal feature work, bug fixes, multi-file changes, focused benchmark/review. Usually selects `iterative-single`: bounded reason/act work plus objective verification. Focused skills such as `tdd`, `verification-loop`, `security-review`, `using-git-worktrees`, and `eval-harness` may be surfaced and must be resolved for applicability.
 
-None of those imply a universal `TODO → TDD → verification-loop` sequence.
+No universal `TODO → TDD → verification-loop` order is implied. But when a skill is applicable, reading it does not grant permission to ignore its flow.
 
 ### Tier 3 — Macro
 
-Typical triggers: repository-wide refactors, architecture/migration work, large ambiguous requirements, broad documentation/system design, or work that may benefit from delegation.
-
-Possible suggestions:
-- `fable-mode` / `fable-discipline` for deliberate macro planning,
-- `multi-agent-workspace` for bounded delegation,
-- `repo-docs` for project-level documentation,
-- `grill-with-docs`, `to-spec`, and `to-tickets` when design decisions/specs/issues genuinely help.
-
-Tier 3 does **not** automatically mean multi-agent. If one capable agent can complete the work safely and efficiently, direct execution is valid.
+Typical triggers: repository-wide refactors, architecture/migration work, broad synthesis, or bounded delegation. The router may select `fable-staged`, `fable-parallel`, or `fable-multi-agent-workspace`.
 
-## Classifier tuning
+A selected Fable topology is mandatory for that run. `fable-parallel` dispatches only validated independent batches; `fable-staged` preserves ordered stage contracts; workspace mode preserves durable handoffs/roles while Fable owns staged execution.
 
-`tier-router.js` reads keyword/guide tables from `harness-everything/scripts/routing-keywords.json`. Edit that data to tune Tier 2/3 signals or knowledge-guide matches without changing classifier code.
-
-The classifier remains heuristic:
-- its recommendation is the default, not an order,
-- a clear task reading may override it,
-- explicit user intent wins,
-- when overriding a materially different tier, record the reason briefly.
+Tier 3 does **not** automatically mean multi-agent. The smallest sufficient topology still wins.
 
 ## Pre-action `actionGate`
 
-The router may predict that a request needs `workflowPlan.actionGate`, but the Phase 5 enforcement hook deliberately **re-classifies the exact tool payload**. A missing or incorrect router prediction therefore cannot authorize a destructive command.
+`workflowPlan.actionGate` is orthogonal to topology. The executable hook re-classifies the exact tool payload, so an incorrect router hint cannot authorize a destructive/external side effect.
 
-The executable policy lives in `hooks/scripts/action-gate-rules.json`. A missing or invalid table activates built-in safety defaults and reports the degradation. A valid empty table remains empty so the CI negative control can detect accidental policy erasure.
+Policy lives in `hooks/scripts/action-gate-rules.json`. Matched actions are handled according to host capability and configured policy; approved/executed payload identity is audited. `HARNESS_ACTION_GATE_POLICY=always-ask` forces Claude's ask path where supported. Unsupported host behavior must remain visible rather than being described as equivalent hard enforcement.
 
-| Exact tool action | Harness result | Audit disposition before execution |
-|---|---|---|
-| Safe unmatched command such as `git status` | allow/no decision | no gate record |
-| Matched command on Claude Code (default policy) | no decision: the session's permission mode, rules and auto-mode classifier decide | `deferred-to-host` |
-| Matched command on Claude Code with `HARNESS_ACTION_GATE_POLICY=always-ask` | `permissionDecision: "ask"` | `pending-approval` |
-| Matched command on a host without Harness-verified ask semantics | block with exit 2 | `rejected` |
-| Payload reaches `PostToolUse` | continue | `executed` with exact payload SHA-256 |
-| Payload reaches `PostToolUseFailure` | continue | `executed` + failed execution outcome |
-| Deferred or pending payload never executes before `Stop` | no execution | `rejected` |
-| Hook internal error | Claude: no decision plus a `systemMessage` warning (`always-ask`: `ask`); other/unverified host: exit 2 | host decides on Claude; fail closed elsewhere |
+## Workflow lifecycle gates
 
-`rm -rf` and `Remove-Item -Recurse -Force` are exempt only when every parsed target is inside the OS temp directory, the current session scratch directory, or an explicitly supplied Harness scratch directory. An uncertain target is gated conservatively.
+The [workflow runtime contract](workflow-runtime.md) defines the executable boundary:
 
-```mermaid
-flowchart TD
-    P[PreToolUse exact payload] --> C{Matches action-gate rule?}
-    C -- No --> A[Allow without gate record]
-    C -- Yes --> X{Scratch-only destructive delete?}
-    X -- Yes --> A
-    X -- No --> H{Host has a native permission flow?}
-    H -- Claude Code --> Y{always-ask policy?}
-    Y -- No --> D[No decision: the permission mode decides<br/>record deferred-to-host + payload hash]
-    Y -- Yes --> Q[Emit permissionDecision: ask<br/>record pending-approval + payload hash]
-    H -- No / unknown --> B[Exit 2 block<br/>record rejected]
-    D --> U{Did the exact tool payload execute?}
-    Q --> U
-    U -- PostToolUse --> E[record executed]
-    U -- PostToolUseFailure --> F[record executed + failure]
-    U -- no execution by Stop --> R[record rejected]
-```
+- `workflow-gate.js` checks shell/direct mutation, correlated Fable entry, and major-workflow Git isolation.
+- `workflow-stop-gate.js` checks manifest stage membership and observed verification evidence before `satisfied`.
+- `workflow-disposition.js` starts/replans the run, records a scoped stage escape, or reports `blocked`.
 
-On Claude Code the gate returns no decision by default. The [hooks reference](https://code.claude.com/docs/en/hooks) says a hook's `ask` "also forces a permission prompt in auto mode: the classifier can still deny the tool call, but it can't approve the call silently". A forced `ask` would therefore override the permission mode the user picked (#107).
+A follow-up prompt cannot erase unresolved obligations. Start from the router's displayed session stage-specification path; source mutation waits for entry and isolation. Replan is bounded. Escape requires `workflow-uncovered-scope` or `host-capability-unavailable`, a stage id, uncovered scope, and evidence. It never waives isolation or independent verification.
 
-With no decision, the normal permission flow applies:
+Direct/iterative verification milestones are checked, while semantic check quality and iteration budgeting remain executor obligations. Shell inspection does not contain arbitrary script side effects. Package/mechanism tests do not prove host loading or behavioral compliance; #82 owns retained live evidence.
 
-- Manual and `acceptEdits` prompt unless a rule or the mode already allows the command.
-- Auto mode lets the classifier decide.
-- `dontAsk` denies anything that is not pre-approved.
-- Deny rules apply in every mode.
+## Cognitive OS relationship
 
-Set `HARNESS_ACTION_GATE_POLICY=always-ask` to have Harness force its own prompt instead. Either way the gate classifies and audits every matched payload.
+`install-cognitive-os` remains the explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is a reasoning policy, not a peer skill that must be selected before domain work. The selected workflow contract governs lifecycle obligations; the model retains freedom inside it.
 
-The deterministic suite verifies two things: the deferred result for every known `permission_mode` value, and the `ask` JSON under `always-ask`. That is **mechanism evidence only** until preserved live evidence exists.
+## Enforcement strength
 
-## Cognitive OS relationship
+A contract can be semantically mandatory even when a host cannot mechanically enforce every transition. Keep those claims separate:
 
-`install-cognitive-os` remains the canonical explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is **not** required to win peer-skill selection before domain work begins. The runtime kernel establishes the smaller invariant contract independently; domain skills provide their own tactics inside that contract.
+- **contract:** what the agent is required to do;
+- **mechanism:** which transitions a packaged hook/plugin can block or observe;
+- **live evidence:** whether a real host actually loaded/fired that mechanism.
 
-## Enforcement strength
+Instruction-only integrations receive the same workflow contract as guidance, but must not be labeled hard-enforced. Kernel emission alone does not prove model compliance. #82 owns host-specific retained evidence.
 
-A lifecycle hook can mechanically inject/guard supported invariants. Instruction-only integrations can only advise the model. Do not label advisory behavior as hard enforcement, and do not infer cross-host parity from shared skill text alone.
+Do not infer cross-host parity from shared runtime code or passing package tests.

package/docs/workflow-runtime.md

@@ -0,0 +1,109 @@
+# Selected workflow runtime
+
+The selected applicable topology is mandatory. This contract governs lifecycle
+obligations; agents still choose tools, reasoning, and implementation inside it.
+Skill suggestions require individual applicability evaluation, not one universal
+skill sequence. Git mutation isolation and durable multi-agent workspace state
+are separate concerns.
+
+## State and entry
+
+`UserPromptSubmit` records `workflow-run.json` in the bound workspace's global
+Harness session state. It includes a unique `workflowId`, complete plan, prompt
+hash (no prompt text), revision count, and scoped exceptions. Unresolved work
+survives follow-up/status prompts; a weaker route cannot erase it. A stronger
+route blocks mutation until an explicit replan. A new task after `satisfied`
+gets a new identity. Invalid recorded state fails closed with a diagnostic.
+
+```text
+pending -> running -> satisfied
+              |          (only after required evidence)
+              -> blocked -> start/replan (within budget)
+```
+
+`blocked` is a reportable incomplete outcome, never successful completion.
+`deferred` means no topology has been selected. Legacy `active`/`escaped` records
+remain subject to isolation and cannot supply a correlated run implicitly.
+
+For Fable, write a stage array in the exact `workflow-stages.json` path displayed
+by the router. This one file is allowed as runtime bootstrap data before entry;
+the exception does not authorize changing workflow state or source artifacts.
+Use the [stage schema](../fable-mode/CONTRACT-FORMAT.md); each stage needs an
+objective `checkCommand` and `passCondition`. If the plan requires independent
+verification, declare a read-only `fable-verifier` stage depending on every
+other stage. Then run the displayed controller with the host session id:
+
+```text
+node "<hooks>/workflow-disposition.js" start --session-id "<session>"
+```
+
+The controller prepares the existing Fable consumer's run at the **bound** state
+root, even when tool execution has moved to a linked worktree. The run records
+both `workflowId` and `sessionId`; matching only strategy or creation time is
+insufficient. `start` creates contracts, not agents. Fable retains ownership of
+worker dispatch, dependency/write-set scheduling, and synthesis.
+
+## Isolation boundary
+
+Before Tier 3 or Fable source/artifact mutation, the gate verifies a registered
+linked Git worktree with the same common Git directory as the bound repository.
+It checks the tool's execution directory and actual Edit/Write/apply_patch paths,
+including move destinations, relative traversal, and symlink/junction resolution.
+Unknown direct targets, Git metadata, and nested repositories are rejected.
+Read-only discovery and a literal `git worktree add` transition remain available
+before entry. Prefer an already-ignored path or sibling path for setup; never
+edit the primary tree's ignore file just to establish mandatory isolation.
+
+Shell recognition is conservative: redirects, substitutions, chained commands,
+and side-effect options are not accepted as read-only. Mutation-capable shell
+execution requires an isolated working-directory field, with explicit outside
+paths and directory changes rejected. **This is not a filesystem sandbox**:
+arbitrary scripts, aliases/configuration, indirect variable paths, and races can
+have effects a hook cannot infer. OS/host sandboxing is needed to contain them.
+Agent-writable state is also not tamper-proof. These mechanisms prevent tested
+bypasses; they do not establish durable containment against a malicious agent.
+
+## Escape, replan, and completion
+
+Escape names one stage in the correlated run and records the uncovered scope,
+evidence, and `workflow-uncovered-scope` or `host-capability-unavailable` reason:
+
+```text
+node "<hooks>/workflow-disposition.js" escape --session-id "<session>" --stage-id "<stage>" --reason-code workflow-uncovered-scope --scope "<uncovered scope>" --evidence "<evidence>"
+node "<hooks>/workflow-disposition.js" block --session-id "<session>" --evidence "<blocker>"
+```
+
+An escape never resolves the whole run, waives isolation, or removes independent
+verification. Covered stages remain mandatory. Unavailable required verification
+means blocked. The controller permits the initial run plus the plan's
+`maxRevisionRounds` replans; exhaustion stays blocked. Previous run evidence is
+retained, but cannot satisfy a replacement run.
+
+`contract-test.js` records exact check commands, observed worker/session identity,
+numeric exit code, and run/plan/stage evidence. A failed check can recover on a
+later observed pass. A dependent check cannot pass before its prerequisites.
+Stop enumerates the manifest's expected stages, so deleting a contract does not
+make the run complete. A `pass` label without matching exit-zero evidence fails.
+The independent verifier must have a distinct observed identity and evidence
+after the latest mutation/check. This proves attribution, not reasoning quality.
+
+Unresolved Stop exits 2. If the host marks a Stop retry, the contract becomes
+`blocked` with diagnostics instead of looping indefinitely or recording success.
+Direct/iterative routes use observed edit/verification milestones; iteration
+counting and semantic check quality remain executor obligations, not proven by
+these gates. Broad verification-command recognition is a heuristic.
+
+## Host evidence
+
+Claude's manifest carries the shell/direct-mutation and Stop hooks. The local
+OpenAI package carries the same runtime for its declared `Bash|apply_patch`
+surface. Package tests exercise both layouts. Missing worker/exit metadata keeps
+Fable completion unresolved; it must be reported as degraded/blocked, not passed.
+Manual CLI routing without a session cannot persist lifecycle state.
+
+OpenCode and instruction-only/public Skills-only surfaces do not gain these
+runtime gates from this change. An absent/disabled hook or deleted state cannot
+be detected as an active contract by that same hook. No host compatibility status
+is upgraded: see [platform capabilities](platform-capabilities.md). Live hook
+loading, enforced host transitions, and behavioral improvement need separately
+retained host traces and paired evaluations.

package/fable-mode/CONTRACT-FORMAT.md

@@ -59,7 +59,9 @@ Rules:
 
 ## Workflow-plan consumer
 
-Before dispatch, write the router contract and stage array to files and run:
+For a session with an active mandatory workflow, write the stage array to the router-displayed `workflow-stages.json` path and invoke its `workflow-disposition.js start --session-id <id>` command. This binds the run to the active `workflowId` and bound workspace even after entering a linked worktree. Every required stage needs an objective check, and an independent plan needs a read-only `fable-verifier` stage depending on all other stages. Stage results need observed worker identities and numeric exit codes; missing metadata is blocked/degraded, not success.
+
+For standalone use without an active session contract, write the router contract and stage array to files and run:
 
 ```bash
 node fable-mode/scripts/workflow-plan-consumer.js \

package/fable-mode/SKILL.md

@@ -4,7 +4,7 @@ description: "Stage large, multi-source or multi-session tasks through a written
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.8.1
 ---
 
 # Fable Mode (v3)