harness-everything 0.8.0 → 0.9.0

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.9.0
 ---
 
 # Fable Mode (v3)

package/fable-mode/agents/fable-orchestrator.md

@@ -53,9 +53,10 @@ overlap reject dispatch instead of becoming a verbal warning.
 
 The stage map remains a living orchestration document only inside those
 constraints. When new information invalidates it, re-plan and create revised
-stage contracts before dispatching new work. Replan budget: at most two full
-replans per run; a third means the task is ambiguous at the requirements level —
-return the ambiguity to the caller instead of burning stages. Scope rule:
+stage contracts before dispatching new work. Replan budget comes from `workflowPlan.limits.maxReplans` and is accounted by
+the runtime controller. Re-enter through `workflow-disposition.js start`; a
+third full replan under the default budget is machine-blocked as
+`replan-budget-exhausted` instead of being only an orchestration reminder. Scope rule:
 deliver the task as specified; new scope discovered mid-run is surfaced as a
 recommendation at delivery, not silently built.
 
@@ -75,10 +76,11 @@ spawn workers.
 
 For `fable-parallel`, spawn only stages in the same validated execution batch;
 never invent an additional parallel edge. A stage depending on another stage is
-not in the same ready batch. Cap concurrent workers at four — this remains
-Fable's single source of truth for the numeric worker cap. For other Fable
-strategies, serialize the returned batches unless a later validated plan says
-otherwise.
+not in the same ready batch. Never exceed `workflowPlan.limits.maxWorkers`. The router plan is the numeric
+source of truth; `workflow-plan-consumer.js` chunks ready sets to that cap and
+runtime worker leases enforce it when the host exposes stable worker IDs. For
+other Fable strategies, serialize the returned batches unless a later validated
+plan says otherwise.
 
 **3. Verify with a check that can fail — external artifacts only.** Each stage
 defines a pass condition an external artifact satisfies: a test that runs, a file

package/fable-mode/execution-guardrails/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.9.0
 ---
 
 # Execution Guardrails

package/fable-mode/fable-haiku/SKILL.md

@@ -4,7 +4,7 @@ description: "Run staged fable work on Haiku for bulk mechanical tasks with expl
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.9.0
 ---
 
 # Fable Mode — Haiku

package/fable-mode/fable-opus/SKILL.md

@@ -4,7 +4,7 @@ description: "Run staged fable orchestration on Opus for cross-stage synthesis,
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.9.0
 ---
 
 # Fable Mode — Opus

package/fable-mode/fable-sonnet/SKILL.md

@@ -4,7 +4,7 @@ description: "Run staged fable work on Sonnet for non-trivial implementation, re
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.9.0
 ---
 
 # Fable Mode — Sonnet

package/fable-mode/scripts/workflow-plan-consumer.js

@@ -155,20 +155,23 @@ function validateParallelBatch(stages) {
   }
 }
 
-function dependencyBatches(stages, validateWrites) {
+function dependencyBatches(stages, validateWrites, maxBatchSize = Infinity) {
   const byId = new Map(stages.map(stage => [stage.stageId, stage]));
   const remaining = new Set(byId.keys());
   const completed = new Set();
   const batches = [];
+  const boundedSize = Number.isInteger(maxBatchSize) && maxBatchSize > 0 ? maxBatchSize : Infinity;
 
   while (remaining.size > 0) {
     const ready = [...remaining]
       .filter(stageId => byId.get(stageId).dependsOn.every(dep => completed.has(dep)))
       .sort();
     if (ready.length === 0) throw new Error('unresolved or cyclic dependency graph');
-    const batch = ready.map(stageId => byId.get(stageId));
-    if (validateWrites) validateParallelBatch(batch);
-    batches.push(batch.map(stage => stage.stageId));
+    const readyStages = ready.map(stageId => byId.get(stageId));
+    if (validateWrites) validateParallelBatch(readyStages);
+    for (let offset = 0; offset < readyStages.length; offset += boundedSize) {
+      batches.push(readyStages.slice(offset, offset + boundedSize).map(stage => stage.stageId));
+    }
     for (const stageId of ready) {
       remaining.delete(stageId);
       completed.add(stageId);
@@ -177,8 +180,8 @@ function dependencyBatches(stages, validateWrites) {
   return batches;
 }
 
-function topologicalBatches(stages) {
-  return dependencyBatches(stages, true);
+function topologicalBatches(stages, maxWorkers) {
+  return dependencyBatches(stages, true, maxWorkers);
 }
 
 function sequentialBatches(stages) {
@@ -209,7 +212,7 @@ function atomicWriteJson(filePath, value) {
   fs.renameSync(tempPath, filePath);
 }
 
-function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null }) {
+function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId = null, workflowId = null }) {
   const plan = validateRouterPlan(routerContract);
   const normalizedStages = validateStageGraph(stages || []);
   if (normalizedStages.length === 0) throw new Error('at least one stage contract is required');
@@ -222,7 +225,7 @@ function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId =
   if (fs.existsSync(runRoot)) throw new Error(`runId already exists in this workspace: ${resolvedRunId}`);
 
   const batches = plan.strategy === 'fable-parallel'
-    ? topologicalBatches(normalizedStages)
+    ? topologicalBatches(normalizedStages, plan.limits && plan.limits.maxWorkers)
     : sequentialBatches(normalizedStages);
 
   const createdAt = new Date().toISOString();
@@ -237,6 +240,7 @@ function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId =
       planId,
       runId: resolvedRunId,
       sessionId: sessionId || null,
+      workflowId,
       workspaceRoot: root,
       ...stage,
       workerId: null,
@@ -252,6 +256,7 @@ function prepareRun({ routerContract, stages, workspaceRoot, runId, sessionId =
     planId,
     runId: resolvedRunId,
     sessionId: sessionId || null,
+    workflowId,
     workspaceRoot: root,
     workspaceKey: getWorkspaceKey(root),
     strategy: plan.strategy,

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through the Harness kernel: classify T
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.8.0
+  version: 0.9.0
 ---
 
 # Harness Everything
@@ -12,26 +12,27 @@ metadata:
 Kernel routing entry.
 
 ## USE FOR:
-- Software/project triage, re-routing, and suggested-skill evaluation.
+- Software/project triage, routing, re-routing, and workflow selection.
 - Work that names or matches another skill.
 
 ## DO NOT USE FOR:
 - General Q&A or non-software writing.
 
 ## Invariants
-1. **Route before execution** — establish scope/tier.
+1. **Route before execution** — establish scope/tier and the smallest applicable workflow.
 2. **Verify before claim** — require objective evidence.
 3. **Re-plan on repetition** — after 3 same-signature failures, use `zoom-out`.
-4. **Evaluate before skip** — read each suggested skill's complete `SKILL.md`.
-
-Tier guidance is not a fixed pipeline.
+4. **Evaluate before omission** — read each suggested skill's `SKILL.md` before deciding applicability.
+5. **Resolve selected workflow** — model confidence is not an escape condition.
 
 ## Workflow
 1. Reuse kernel output, or run `node "<this-skill-dir>/scripts/kernel-router.js" "<prompt summary>"`.
-2. Make the **Harness Routing Checkpoint** user-visible.
-3. For every suggestion, read its `SKILL.md`; evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. Name, description, router summary, or "routine/common task" alone cannot justify skip. Read extra material only when explicitly required for applicability.
-4. Execution is advisory after evaluation. Unreadable suggestions are `unresolved/unavailable`. Using one suggestion does not waive evaluation of others. If all are skipped, give one brief flow-grounded reason.
+2. Surface the **Harness Routing Checkpoint**.
+3. Read each suggested `SKILL.md`; evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. "Simple", "routine", names, or summaries alone cannot justify omission.
+4. Execute the selected workflow topology to resolution. Suggested skills are conditional on applicability; the selected topology is not advisory.
+5. If the workflow genuinely cannot represent part of the task, use the explicit escape with uncovered scope + evidence. Covered obligations remain mandatory.
+6. Complete only after applicable workflow obligations and objective verification resolve.
 
-**Rule:** mandatory evaluation, advisory execution; no fixed workflow order.
+**Rule:** mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only for uncovered scope.
 
 Deep dive: <this-skill-dir>/references/triage-and-tiers.md

package/harness-everything/references/triage-and-tiers.md

@@ -1,8 +1,8 @@
 # Task Triage & Tier Details
 
-Harness uses tiers to estimate scope and surface useful capabilities. A tier is **not** a fixed pipeline. The runtime enforces a small set of cross-cutting invariants plus mandatory evaluation of router-suggested skills; execution choice, ordering, and delegation remain with the agent after that evaluation.
+Harness uses tiers to estimate scope and select the smallest sufficient execution topology. A tier is **not** a fixed TODO/TDD/Fable pipeline. Once the router selects an applicable topology, however, that topology becomes the run's execution contract.
 
-> Architecture rule: **Do not enforce workflow order. Enforce workflow invariants and evaluate suggestions before skipping them.**
+> Architecture rule: **Mandatory applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only for workflow-uncovered scope.**
 
 ## 0. When Harness Routing Applies
 
@@ -10,52 +10,51 @@ Harness uses tiers to estimate scope and surface useful capabilities. A tier is
 flowchart TD
     U([User Prompt]) --> S{Software / project work?}
     S -- No --> B[Bypass Harness<br/>Answer naturally]
-    S -- Yes --> K[Harness Kernel<br/>classify scope + inject invariants]
-    K --> T{Tier recommendation}
-    T --> G{Suggested skills?}
-    G -- Yes --> R[Read each suggested SKILL.md<br/>evaluate basic flow + applicability]
-    G -- No --> C[Agent chooses smallest useful tactic]
-    R --> C
-    C --> E[Execute with agent-selected tactics]
-    E --> V{Objective evidence supports completion?}
-    V -- No --> D[Diagnose / iterate]
-    D --> F{Same-signature failure x3?}
-    F -- No --> E
-    F -- Yes --> Z[Zoom out / re-plan]
-    Z --> E
+    S -- Yes --> K[Harness Kernel<br/>classify + select topology]
+    K --> W{Workflow selected?}
+    W -- No / deferred --> D[Preserve invariants<br/>choose smallest justified workflow]
+    W -- Yes --> A[ACTIVE workflow contract]
+    A --> G{Suggested skills?}
+    G -- Yes --> R[Read each suggested SKILL.md<br/>resolve applicability]
+    G -- No --> E[Execute selected workflow]
+    R --> E
+    E --> V{Required checks / stages resolved?}
     V -- Yes --> O([Claim completion])
+    V -- No --> P[Diagnose / re-plan]
+    P --> X{Workflow covers next step?}
+    X -- Yes --> E
+    X -- No --> C[Record evidence-backed escape<br/>for uncovered scope only]
 ```
 
 ### Bypass Rules
 
 - **Pure chat, translation, general web search, non-software writing:** bypass Harness routing.
-- **Software engineering / codebase / project work:** establish the Harness Kernel contract before mutating work, even when the prompt already names a domain skill such as `tdd`, `security-review`, or `repo-docs`.
+- **Software engineering / codebase / project work:** establish the Harness Kernel contract before mutation, even when the prompt already names a domain skill.
 
-A host may auto-select a peer/domain skill. That selection must not be treated as proof that Harness routing already happened.
+Host skill selection is not proof that Harness routing already happened.
 
-## 1. The Minimal Harness Kernel
+## 1. Minimal Kernel Contract
 
-The kernel exists to keep strong models free while protecting the few behaviors that should not disappear under autonomous skill selection.
+The kernel protects lifecycle obligations without micromanaging model reasoning.
 
 ### Mandatory invariants
 
-1. **Route before execution** — establish task scope/tier before mutating software work.
-2. **Verify before claim** — completion claims require objective evidence appropriate to the change.
+1. **Route before execution** — establish task scope/tier and the smallest justified topology.
+2. **Verify before claim** — completion requires objective evidence appropriate to the change.
 3. **Re-plan on repetition** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
-4. **Evaluate before skip** — when the router suggests a skill, read that skill's complete `SKILL.md` entry/basic flow before omitting it.
+4. **Evaluate before omission** — when the router suggests a skill, read its complete `SKILL.md` entry/basic flow before deciding applicability.
+5. **Resolve selected workflow** — once a topology is selected, execute it to a resolved state; "simple", "routine", "already clear", or model confidence are not escape conditions.
 
-The fourth invariant is conditional: it applies when the router emits one or more suggestions. It makes **evaluation mandatory, not execution**.
+The model remains free to choose tools, implementation technique, decomposition details, and reasoning inside the workflow.
 
 ### What is intentionally *not* mandatory
 
-- Executing `todo-driven-workflow` for every Tier 2/3 task after its applicability has been evaluated.
-- Running TDD where the `tdd` flow has been read and executable behavioral tests do not add value.
-- Entering Fable/multi-agent mode merely because the task is Tier 3 after those suggested flows have been evaluated.
-- Following a universal `TODO → TDD → verification-loop` or `Fable → subagent → verification-loop` sequence.
-- Loading `install-cognitive-os` as a peer skill before every other skill.
-- Reading every optional deep-dive/reference linked by a suggested skill. Only material the skill entry explicitly requires to decide applicability joins the mandatory evaluation set.
+- One universal `TODO → TDD → verification-loop` sequence for every Tier 2/3 task.
+- Multi-agent execution merely because a task is Tier 3.
+- Every router-suggested skill when its evaluated flow is objectively not applicable.
+- Every optional deep-dive/reference linked from a skill.
 
-`install-cognitive-os` remains the human-readable/manual entry point for the cognitive policy. Supported runtime integrations should establish the kernel invariants without depending on that skill being selected first.
+A suggested skill may resolve as `use`, `not-applicable`, or `unresolved/unavailable`. `not-applicable` needs a flow-grounded reason; a metadata-only or confidence-only judgement is insufficient. The selected **topology** is different: it is mandatory after selection unless an explicit workflow escape records genuinely uncovered scope plus evidence.
 
 ## 2. Routing Mechanism
 
@@ -63,100 +62,67 @@ Use the public kernel entry point:
 
 ```bash
 node "<this-skill-dir>/scripts/kernel-router.js" "<brief prompt summary>"
+# or
+npx github:dyphn1/Harness-everything next "<brief prompt summary>"
 ```
 
-or:
+`kernel-router.js` delegates classification/guide discovery to `tier-router.js` and emits:
 
-```bash
-npx github:dyphn1/Harness-everything next "<brief prompt summary>"
-```
+- recommended tier + rationale,
+- structured workflow plan,
+- compact **Harness Routing Checkpoint**,
+- required invariants,
+- suggested skills whose applicability must be evaluated,
+- **Workflow Execution Contract** for the selected topology.
 
-`kernel-router.js` delegates classification and guide discovery to `tier-router.js`, removes legacy fixed-pipeline instructions, and emits:
+If `UserPromptSubmit` already ran the kernel this turn, reuse that output. Do not infer a silent Tier 1/direct path from missing or degraded routing.
 
-- the recommended tier and rationale,
-- a compact **Harness Routing Checkpoint**,
-- the **required Harness invariants**,
-- suggested skills under a **mandatory evaluation / advisory execution** contract,
-- the policy that the agent may choose the smallest useful skill/tool set after evaluating suggestions.
+### Suggestion applicability contract
 
-If a host's `UserPromptSubmit` integration already ran the kernel this turn, reuse that output rather than running it twice. The checkpoint must still become user-visible for software/project work: use the host's visible hook rendering when it has one, otherwise include the checkpoint in the first progress/update message.
+For every router-suggested skill:
 
-The tier classifier is heuristic. Treat its result as the default route, not an oracle. A clear task reading or explicit user instruction may override it; record the reason when doing so.
+1. 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 to decide applicability.
+4. Resolve the suggestion as `use`, `not-applicable`, or `unresolved/unavailable`.
 
-### Suggestion evaluation contract
+A name, description, router summary, tier label, or generic "routine/common task" judgement is not enough to mark a suggestion not applicable. Using one suggestion does not resolve the others automatically.
 
-For every router-suggested skill:
+### Workflow escape contract
+
+Escape is an exception path, not an alternative default. Use it only when the selected topology genuinely cannot represent part of the task. The permitted reason codes are:
 
-1. Resolve and read the complete `SKILL.md` entry.
-2. Evaluate `USE FOR`, `DO NOT USE FOR`, its workflow/basic flow, and any hard rules in the entry 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. Only then choose `use`, `skip`, or `unresolved/unavailable`.
+- `workflow-uncovered-scope` — the selected topology cannot represent a bounded part of the task;
+- `host-capability-unavailable` — the host lacks a capability required to execute the selected topology.
 
-A skill must not be skipped from only its name, frontmatter description, router summary, or a generic judgement such as “routine/common task.” Using one suggested skill does not waive evaluation of the other suggestions before they are skipped. A suggestion that cannot be resolved/read is not a valid skip; mark it `unresolved/unavailable`.
+Every escape must name a declared stage in the correlated run and record the reason code, uncovered scope, and evidence explaining the coverage/capability gap. The entire workflow never becomes escaped; isolation and independent verification cannot be waived. Covered workflow obligations remain mandatory. Host capability loss must be visible as degradation/blocked/escape evidence, never silently converted into optional execution.
 
 ## 3. Tier Guidance
 
 ### Tier 1 — Trivial
 
-Typical shape:
-- typo/small documentation correction,
-- simple local code edit,
-- narrow explanation,
-- straightforward Git operation.
+Typical shape: typo/small docs correction, narrow local edit, bounded explanation, straightforward Git operation.
 
-Default behavior:
-- prefer direct execution,
-- avoid large plans and unnecessary delegation,
-- when the router emits no suggestions, proceed with the bounded direct path,
-- when it does emit a focused suggestion, evaluate that skill entry before omitting it,
-- still verify any completion claim with evidence appropriate to the change.
+Default topology is normally `direct-single`. Keep the lifecycle minimal, but still satisfy applicable scope/safety/verification obligations.
 
 ### Tier 2 — Standard
 
-Typical shape:
-- a specific feature or bug fix,
-- multi-file coordination,
-- behavioral changes needing tests,
-- focused benchmark/review work.
+Typical shape: specific feature/bug fix, multi-file coordination, behavioral change, focused benchmark/review.
 
-Common **suggestions**, not a pipeline:
+The router normally selects `iterative-single`: bounded reason/act work plus objective verification. It may surface `tdd`, `verification-loop`, `security-review`, `using-git-worktrees`, or other focused skills. Those suggestions are applicability decisions, not a universal sequence.
 
-| Need observed in the task | Useful skill |
-|---|---|
-| Several verifiable steps need explicit tracking | `todo-driven-workflow` |
-| Behavior can be specified by executable tests | `tdd` |
-| Delivery needs systematic build/lint/test/diff evidence | `verification-loop` |
-| Auth/input/secrets/network boundaries are touched | `security-review` |
-| Isolated workspace would reduce risk | `using-git-worktrees` |
-| Quantitative scoring/benchmarking is requested | `eval-harness` |
-
-Every emitted suggestion is mandatory to **evaluate** by reading its skill entry/basic flow. After that, the model decides which skills are useful and in what order; it may execute none, one, or several while preserving the kernel invariants. Adopting one suggestion does not permit the others to be skipped without evaluation. If every suggestion is skipped after evaluation, the visible checkpoint/progress update must include one brief reason grounded in the evaluated flow mismatch.
+When an evaluated skill is applicable, follow its workflow rather than reading it and then discarding it because the implementation seems obvious.
 
 ### Tier 3 — Macro
 
-Typical shape:
-- repository-wide or architectural changes,
-- large ambiguous requirements,
-- broad documentation/system design,
-- work where deliberate delegation may reduce risk or improve coverage.
-
-Common **suggestions**, not a pipeline:
+Typical shape: repository-wide/architectural work, large ambiguous requirements, cross-source synthesis, or bounded delegation.
 
-| Need observed in the task | Useful skill |
-|---|---|
-| Deliberate macro planning / model-mode selection | `fable-mode`, `fable-discipline` |
-| Bounded parallel delegation genuinely helps | `multi-agent-workspace` |
-| Project-level docs need creation/update | `repo-docs` |
-| Important decisions need challenge before implementation | `grill-with-docs` |
-| Settled intent needs a spec | `to-spec` |
-| Settled work needs tracer-bullet issues | `to-tickets` |
+The router may select `fable-staged`, `fable-parallel`, or `fable-multi-agent-workspace`. A selected Fable topology is not advisory: enter its stage-contract lifecycle, honor dependency/write-set constraints, run objective checks, synthesize, cold-verify where required, and use bounded re-planning on failure.
 
-Tier 3 does **not** automatically require multi-agent execution. It does require evaluation of the suggested entries before omission. A strong model may still complete macro work directly when, after reading those flows, direct execution is the safer/smaller choice. The same evaluated all-skipped rationale rule applies.
+Tier 3 does **not** automatically mean multi-agent; the router still chooses the smallest sufficient topology.
 
 ## 4. Cognitive OS Relationship
 
-The cognitive loop remains useful:
-
 ```mermaid
 flowchart LR
     D[Discover] --> T[Think]
@@ -168,39 +134,42 @@ flowchart LR
     Z --> T
 ```
 
-But this diagram describes a reasoning policy, not a peer-skill dependency graph. Domain skills may implement their own local phases and gates. They do not need to invoke `install-cognitive-os` first as long as the Harness invariants remain satisfied.
+This describes a reasoning policy. The workflow contract governs lifecycle obligations; domain skills may define their own local phases inside it.
 
 ## 5. Host Integration and Enforcement Strength
 
 | Host mode | Expected behavior |
 |---|---|
-| Lifecycle hook available | Run the Harness Kernel on prompt submission so routing context exists before domain-skill execution. Surface the emitted checkpoint through a host-visible hook surface when supported; otherwise the agent carries it into the first visible progress/update. Suggested-skill execution stays agent-controlled, but each suggested skill must be evaluated before omission. Hard gates may enforce supported invariants at tool/stop boundaries. |
-| Advisory instructions only | Tell the agent to run/reuse `harness next` before software mutation, surface the checkpoint, read/evaluate each suggested skill before skipping it, and run `harness verify` before completion. The behavior is instruction-governed, not a hard host gate. |
-| Manual use | Invoke `harness-everything` or `install-cognitive-os` explicitly to inspect/re-establish and surface the contract; suggested skills still follow read-before-skip. |
+| Lifecycle hooks available | Kernel creates the selected workflow contract. Supported PreToolUse/Stop gates may mechanically prevent known bypasses. |
+| Advisory instructions only | Agent is instructed to establish and resolve the same contract, but the host cannot be described as mechanically enforcing it. |
+| Manual use | Invoke `harness-everything` / `harness next`, then execute the selected topology explicitly. |
+
+On Claude and the local OpenAI package, supported mutation hooks require Fable entry and Tier 3/Fable Git worktree isolation. Follow-up prompts preserve unresolved state. The router displays a session `workflow-stages.json` path and `workflow-disposition.js start` command; declare stages there before entry. Stop checks expected stage contracts plus correlated exit-zero/worker evidence. A retry records `blocked`, never false success. Direct/patch paths and explicit shell targets are checked, but arbitrary scripts are not sandboxed. Other selected topologies still rely on their applicable mechanisms (for example objective verification/stop gates) and shared contract text.
 
-Never describe an advisory integration as hard enforcement. Platform-specific adapters may differ while preserving functional intent. Kernel emission alone is not proof that a host UI displayed the checkpoint or that the host compelled the model to read a suggested skill; #82 live evidence owns those claims.
+Never turn mechanism/package evidence into a cross-host live-enforcement claim. #82 owns host-specific retained evidence.
 
 ## 6. Routing Checkpoint
 
-For software/project work, the kernel always emits a compact checkpoint and the execution surface must make it user-visible before or with the first progress update:
+For software/project work, surface this state before or with the first progress update:
 
 ```markdown
 ## 🚦 Harness Routing Checkpoint
 - Tier: Tier X — <reason>
 - Strategy: <selected/deferred strategy>
-- Required invariants: route-before-execution; verify-before-claim; re-plan-after-3-same-failures; evaluate-suggestions-before-skip (when suggestions exist)
-- Suggested skills: <deduplicated suggestions, or none>
-- Suggestion evaluation: <required before skip | no suggestions>
-- Suggestion disposition: <using one or more | skipped all after evaluation — brief reason | unresolved/unavailable>
+- Workflow state: <pending | running | satisfied | deferred | blocked>
+- Required invariants: <router invariants>
+- Suggested skills: <deduplicated suggestions or none>
+- Suggestion applicability: <use | not-applicable + reason | unresolved/unavailable>
+- Escape: <none | reason + uncovered scope + evidence>
 ```
 
-The checkpoint reports state; it does not prescribe a universal workflow. Suggested skills are **mandatory to evaluate and advisory to execute**. A non-empty suggestion set cannot disappear silently or be rejected from summaries alone. When every suggestion is skipped after evaluation, state one brief reason grounded in the evaluated flows. When at least one is used, no prose explanation is required for each other omission, but read-before-skip still applies to every omitted suggestion.
+The checkpoint is state, not a universal response template. The key distinction is: **skill suggestions are evaluated for applicability; a selected workflow topology is executed to resolution.**
 
 ## 7. Self-Healing and Dynamic Skills
 
-Existing self-heal, generated-skill discovery, knowledge-guide matching, and fact-audit behavior remain part of the classifier/runtime. They may recommend resources; recommendations trigger mandatory applicability evaluation, not automatic execution or mandatory pipeline stages.
+Self-heal, generated-skill discovery, knowledge-guide matching, and fact-audit behavior remain part of the runtime. Dynamic recommendations still require applicability evaluation.
 
-If bootstrap reports missing integration touchpoints, use the existing self-heal command:
+If bootstrap reports missing integration touchpoints:
 
 ```bash
 node "<this-skill-dir>/scripts/self-heal.js"