harness-everything 0.8.0 → 0.9.0

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
 

package/docs/philosophy.md

@@ -1,61 +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 a different approach: preserve execution autonomy, but make important decisions informed rather than superficial.
+> **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. **Mandatory Evaluation, Advisory Execution:** When the router suggests a skill, the model must read/evaluate that skill's actual `SKILL.md` entry/basic flow before omitting it. Execution is still optional after evaluation. This prevents “advisory” from degenerating into “always ignored” without creating a fixed pipeline.
-3. **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.
-4. **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.
-5. **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.
 
-The read-before-skip rule is intentionally narrow. It does not require every optional reference linked by a skill to be loaded, and it does not mean every suggestion must run. The agent reads the complete skill entry, evaluates `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules, follows any explicitly required applicability reference, and then decides whether execution adds value.
+## Why This Is Not a Rigid Global Pipeline
 
----
+Harness still rejects a universal `TODO → TDD → Fable → verification` sequence.
 
-## The 4 Pillars of AI Model Guidance
-
-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. Read-before-skip is bounded to the suggested skill entry and any applicability-critical material that entry explicitly requires; it does not justify indiscriminately loading the whole skills tree. 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

@@ -19,9 +19,9 @@ All `liveHostVerification` rows except OpenCode are `Unknown`. OpenCode's row is
 
 ### Routing contract vs. host evidence
 
-The repository routing contract now uses **mandatory evaluation / advisory execution** for skill suggestions: when the router suggests a skill, the agent is instructed to read that skill's complete `SKILL.md` entry/basic flow before omission. 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.
+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. Because this change does not add or remove a host capability, it does not change `platform-compatibility.json` status values by itself.
+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
 

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,28 +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 two coupled rules:
 
-> **Do not enforce workflow order. Enforce workflow invariants.**
+> **Mandatory applicable workflow; flexible reasoning/implementation inside it.**
 >
-> **Suggested skills are mandatory to evaluate and advisory to execute.**
+> **Skill applicability is evaluated explicitly; workflow escape is exception-only and evidence-backed.**
 
-A strong model should remain free to decide how to complete the task, but it may not discard a router suggestion without first reading the suggested skill's actual entry/basic flow.
+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 baseline 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.
 
-When the router emits one or more skill suggestions, it adds a fourth conditional invariant:
-
-4. **Evaluate before skip** — before omitting any suggested skill, read its complete `SKILL.md` entry and evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules against the task.
-
-Execution, ordering, planning style, and delegation remain agent decisions after evaluation 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
 
@@ -30,10 +28,10 @@ Execution, ordering, planning style, and delegation remain agent decisions after
 kernel-router.js
   ├─ delegates classification / guide discovery → tier-router.js
   ├─ preserves tier + rationale + dynamic-skill recommendations
-  ├─ suppresses legacy fixed-pipeline wording
-  ├─ emits required invariants
-  ├─ requires evaluation of each suggested skill before omission
-  └─ leaves suggested-skill execution advisory after evaluation
+  ├─ 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:
@@ -44,32 +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.
 
-## Suggestion evaluation contract
+## Suggested skills vs. selected workflow
 
-A router suggestion is not permission to make a decision from metadata alone. For **every** suggested skill:
+These are intentionally different concepts.
 
-1. Resolve and read the complete `SKILL.md` entry.
-2. Evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules against the current task.
-3. If the entry explicitly requires another document to determine applicability, read that required material too. Ordinary deep-dive/reference links remain optional unless the entry makes them decision-critical.
-4. Choose `use`, `skip`, or `unresolved/unavailable` only after that evaluation.
+For **every suggested skill**:
 
-The following are not sufficient skip evidence by themselves:
+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`.
 
-- the skill name,
-- the frontmatter description,
-- the router's one-line summary,
-- the tier label,
-- a generic judgement such as “routine/common task.”
+A name, description, router summary, tier label, or generic “routine/common task” judgement is not sufficient evidence for `not-applicable`.
 
-Using one suggested skill does not waive read-before-skip for the other suggestions. If a suggested skill cannot be resolved or read, mark it `unresolved/unavailable` rather than silently treating it as inapplicable. If every suggestion is skipped after evaluation, give one brief flow-grounded reason in the visible routing checkpoint/progress update.
+For the **selected workflow topology**:
 
-## Non-software bypass
+- 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.
 
-General Q&A, translation, ordinary web search, and non-software writing bypass Harness routing. The model should answer directly and naturally.
-
-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 after evaluating router suggestions.
+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
 
@@ -77,123 +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 --> G{Suggested skills?}
-    G -- Yes --> R[Read each suggested SKILL.md<br/>evaluate flow + applicability]
-    G -- No --> A[Agent self-orchestrates]
-    R --> A
-    A --> E[Execute selected tactics / skills]
-    E --> V{Evidence supports completion?}
-    V -- Yes --> D([Done])
-    V -- No --> X[Diagnose and iterate]
-    X --> 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,
-- when there are no suggestions, use the bounded direct path,
-- if a focused skill is suggested, read/evaluate its entry before omitting it,
-- 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.
+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.
 
-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.
-
-Every emitted suggestion must be evaluated from its `SKILL.md` flow before omission. After evaluation, 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. It does mean that any emitted Tier 3 suggestions are read/evaluated before omission. If one capable agent can complete the work safely and efficiently after that evaluation, direct execution remains valid.
-
-## Classifier tuning
+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`.
 
-`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.
+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.
 
-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 the read-before-skip contract into context, but that alone does not prove the model actually read every suggested `SKILL.md`. Instruction-only integrations can only instruct the model. Do not label either case as live behavioral enforcement without retained host/session evidence; #82 owns that evidence boundary. **Do not infer cross-host parity** from one host's mechanism or live evidence; each host needs its own retained evidence.
+Do not infer cross-host parity from shared runtime code or passing package tests.