harness-everything 0.2.2 → 0.4.0

package/fable-mode/CONTRACT-FORMAT.md

@@ -1,51 +1,165 @@
-# Stage Contract Format
-
-Stage contracts live in `.claude/harness-state/contracts/` and make fable-orchestrator's
-"re-run or spot-check every stage's named check" discipline auditable instead
-of a verbal claim. The `contract-test.js` hook (PostToolUse: Bash) watches for
-the exact `checkCommand` running and fills in the result — you write the
-contract, the hook resolves it.
-
-## When to write one
-
-Right before you (the orchestrator) run the Bash command that re-verifies a
-stage's pass condition — one contract per stage, filed the moment you're about
-to spot-check it. Not for every Bash call, only the ones that *are* the named
-check.
-
-## File
-
-`.claude/harness-state/contracts/<stageId>.json`, created lazily. `stageId` is whatever you
-numbered the stage in your stage map (`stage-3`, `db-migration`, etc).
-
-## Schema
-
-```json
-{
-  "stageId": "stage-3",
-  "agent": "fable-worker-sonnet",
-  "task": "one-line description of what the worker was assigned",
-  "outputPath": "path to the artifact the worker produced",
-  "checkCommand": "the exact shell command you are about to run to verify it",
-  "status": "pending"
-}
-```
-
-Write it with `status: "pending"` and the *exact* `checkCommand` string you're
-about to run — the hook matches verbatim, not fuzzily. Then run that command.
-The hook fills in `status` (`pass`/`fail`), `evidence` (tail of the command's
-output), and `verifiedAt` for you; you don't write those fields yourself.
-
-## Reading contracts back
-
-Before delivering, `Read` (or `Grep status` across) `.claude/harness-state/contracts/*.json`.
-Any file still `"status": "pending"` means the named check was declared but
-never actually run — that stage's output hasn't been verified, whatever the
-worker's report claimed. Resolve it before building further on that stage.
-
-## Not a blocking gate
-
-The hook can only react after a Bash call finishes — it can't stop a bad stage
-from being built on in real time. It surfaces a failed check loudly (fed back
-to you immediately after the command runs), but the actual discipline is still
-yours: don't build on a stage whose contract is `pending` or `fail`.
+# Fable Stage Contract Format
+
+Issue #85 Phase 3 makes the stage map a machine-readable execution contract.
+The router still chooses only the execution topology. Fable owns the stage map,
+model selector, worker briefs, stage audit, replan budget, and cold verifier.
+Phase 4 adds an optional bounded ensemble modifier without creating a new base
+topology.
+
+Run state is stored under the existing workspace-keyed global Harness state
+root, never inside the repository:
+
+```text
+<workspace-state>/state/fable-runs/<runId>/
+  run.json
+  contracts/<stageId>.json
+  evidence/<stageId>.json
+  ensemble.json             # only when ensemble review executes
+```
+
+`planId` is a deterministic content hash of the router contract. `runId` is
+unique per orchestration. Two runs of the same plan therefore share a `planId`
+but never share mutable stage-contract files.
+
+## Stage schema v2
+
+Every planned stage declares dependency and write scope before dispatch:
+
+```json
+{
+  "stageId": "stage-3",
+  "goal": "implement one bounded objective",
+  "agent": "fable-worker-sonnet",
+  "task": "self-contained task statement",
+  "inputs": ["relevant files", "upstream outputs"],
+  "expectedOutputs": ["artifact or evidence"],
+  "outputPath": "path/to/artifact-or-null",
+  "dependsOn": ["stage-1"],
+  "writeSet": ["src/auth", "tests/auth.test.js"],
+  "checkCommand": "node --test tests/auth.test.js",
+  "passCondition": "exit 0",
+  "failureReturn": "failure summary + evidence + missing prerequisite"
+}
+```
+
+Rules:
+
+- `stageId`, `goal`, `agent`, and `task` are required.
+- `dependsOn` is always explicit. Use `[]` for a root stage.
+- `writeSet` is always explicit. Use `[]` for a read-only stage.
+- `writeSet` contains concrete repository-relative path scopes, not globs,
+  absolute paths, or `..` traversal.
+- a directory scope covers descendants; overlapping scopes cannot run in the
+  same parallel batch.
+- every `dependsOn` target must exist; self edges and cycles are invalid.
+- `checkCommand` is exact-match evidence when present. `passCondition` explains
+  what that command proves; it does not replace the command result.
+- workers do not widen their own `writeSet`. If scope must grow, return to the
+  orchestrator and produce a revised plan before dispatch.
+
+## Workflow-plan consumer
+
+Before dispatch, write the router contract and stage array to files and run:
+
+```bash
+node fable-mode/scripts/workflow-plan-consumer.js \
+  --plan-file <router-contract.json> \
+  --stages-file <stages.json> \
+  --root <workspace> \
+  --run-id <optional-stable-run-label> \
+  --session-id <optional-host-session-id>
+```
+
+The consumer validates the graph, derives `planId`, creates the isolated run
+root, and emits execution batches. It consumes only router-owned decisions:
+strategy, parallelism, verifier requirement, workspace/memory hints, limits,
+and requested-model metadata. It does **not** choose a model or execute a
+stage.
+
+For `fable-parallel`, every ready batch must have resolved dependencies and
+pairwise non-overlapping write sets. An invalid graph or overlap rejects the
+plan before workers are spawned. For `fable-staged` and
+`fable-multi-agent-workspace`, the same dependency graph is serialized unless
+a later validated plan explicitly allows parallelism.
+
+## Bounded ensemble evidence
+
+`workflowPlan.ensemble` is a modifier on a selected Fable topology, not a sixth
+execution strategy. The kernel may add it only for high-uncertainty/high-stakes
+work with comparable outputs (choice/ranking/verdict/recommendation) or when
+preserving disagreement is itself the deliverable. Creative generation,
+mechanical bulk work, explicit `no ensemble`, unavailable subagents, and blocked
+base plans do not receive the modifier.
+
+Current contract:
+
+```json
+{
+  "maxCandidates": 3,
+  "diversity": ["model", "prompt", "evidence"],
+  "synthesis": "preserve-disagreement",
+  "verifier": "independent",
+  "reasonCodes": ["ensemble-high-uncertainty-comparable-output"]
+}
+```
+
+Each candidate passed to `fable-mode/scripts/ensemble-review.js` records a
+bounded position, a model/prompt/evidence diversity fingerprint, objective
+verification status/evidence, and optional correctness/cost observations.
+Candidates with the same model+prompt+evidence fingerprint are not independent
+and are rejected. The verifier uses a distinct identity, declares
+`independent=true`, and supplies its own evidence.
+
+The synthesizer keeps every position and its evidence. A strict majority is
+only a proposal: any objective verification failure on the proposed position
+blocks selection, and verifier rejection/inconclusive/mismatch also blocks it.
+An accepted position therefore never deletes minority positions or evidence
+gaps.
+
+Run it after the candidate artifacts/checks exist:
+
+```bash
+node fable-mode/scripts/ensemble-review.js \
+  --plan-file <router-contract.json> \
+  --candidates-file <candidates.json> \
+  --verifier-file <verifier.json> \
+  --root <workspace> \
+  --run-id <runId> \
+  [--paired-evidence-file <paired-benchmark.json>]
+```
+
+The correlated result is written to `ensemble.json` under the same run root.
+Correctness is recorded separately from tool calls, tokens, elapsed time,
+retries, and failure mode so #71/#83 can consume the evidence without
+conflating quality with cost. Missing telemetry is allowed and never changes
+the strategy/result. No ensemble or multi-agent improvement claim is permitted
+unless paired evidence establishes the same engine/model/fixture/rubric/config,
+a sample count, effect estimate, and uncertainty.
+
+## Verification evidence
+
+`contract-test.js` watches Bash/PowerShell calls and resolves an exact
+`checkCommand` only when it can correlate the command to one run/stage. The
+result updates the stage contract and writes:
+
+```text
+evidence/<stageId>.json
+```
+
+with `planId`, `runId`, `stageId`, command, exit code, status, and captured
+evidence. If the same command is pending in multiple uncorrelated runs, the
+hook updates none of them and reports the ambiguity.
+
+Before delivery, every check-bearing contract in the run must be `pass` (not
+`pending`, `planned`, `running`, or `fail`). A failed check returns to the
+orchestrator for bounded re-planning.
+
+## Scope audit
+
+`subagent-scope-guard.js` snapshots active stage write sets at the beginning of
+a worker burst and compares the post-burst Git diff paths with that immutable
+snapshot. Expected paths are attributed to the matching stage; worker-level
+attribution is added when the host exposes a worker/subagent id and the stage
+contract records it. Ambiguous or out-of-scope changes exit 2. With no declared
+stage contracts, the older conservative behavior remains: every newly changed
+path requires review.

package/fable-mode/SKILL.md

@@ -1,51 +1,39 @@
 ---
 name: fable-mode
-description: Macro task planning and execution engine for complex requirements and low-level architecture changes.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: "Stage large, multi-source or multi-session tasks through a written plan, named fable agents, failable per-stage checks, and skeptical delivery review; use fable-opus, fable-sonnet, or fable-haiku for explicit model selection."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
-# Fable Mode (Macro Task Planning & Execution Engine)
+# Fable Mode (v3)
 
-## 📋 Skill Contract
+## Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | Tier 3 Task classification. Input: Massive architectural requirement or module creation. |
-| **Expected Output** | 1. Documented architectural plan. 2. A sequence of subagent handoffs (`create-agent-launcher`). 3. System integration verified by terminal scripts. |
-| **State Mutations** | 1. Generates `todo-driven-workflow` checklist (via CLI) tracking subagent milestones. 2. `subagent-scope-state.json` updates during handoffs. |
-| **Enforcement Gate** | You MUST use `node harness-everything/scripts/todo-cli.js` to track milestones. You MUST run system tests (`verify-gate.js` or equivalent) after EACH subagent returns before moving to the next. |
-
-This skill is automatically triggered and loaded by the `harness-everything` router when a task is judged as a **Tier 3 (Macro Task)**.
-It applies to building new feature modules from scratch, massive low-level architecture changes, or extremely vague and complex user requirements.
-
-## Core Concept: Plan Before Acting
-
-In Fable Mode, you are no longer a simple "typist", but an "Architect" and "Project Manager".
-You MUST strictly comply with and pair this with `fable-discipline` to control risks.
-
-## Sub-Skills (bundled with this skill)
-- `execution-guardrails/` — always-on operational rules (verify-before-flag, warning batching, find-and-replace safety). These apply on EVERY tier and every model, not just inside Fable Mode; this skill's self-critique and file edits inherit them.
-- `fable-haiku/` — opt-in variant that routes the staged loop to a cheap Haiku worker agent for bulk mechanical work. Only use when the user explicitly asks for it.
-
-## Execution Phases:
-
-### 1. Discovery & Planning
-- **Assess Current State**: Comprehensively review the file architecture related to the requirement and understand dependencies.
-- **Deconstruct Task**: Break down the massive macro task into independently verifiable sub-tasks.
-- **Produce Plan**: Write a clear implementation plan (can be stored in chat or a temporary file) and confirm it with the Human Partner.
-- **Materialize the Plan as a Checklist**: The confirmed plan MUST be initialized as the `todo-driven-workflow` checklist — every sub-task, sub-agent handoff, and milestone check is tracked there, not in prose. This is the harness's base execution loop.
-
-### 2. Sub-agent Orchestration
-- If the task involves different professional domains (e.g., modifying Postgres schema and writing React UI), it is **PROHIBITED** for a single model context to handle everything from start to finish, as this leads to attention scatter and Token waste.
-- **Mandatory Call**: Invoke the `create-agent-launcher` skill.
-- Based on the deconstructed sub-tasks, configure the corresponding Sub-agents (e.g., spawn a Database Expert to handle the Schema, then hand off to a Frontend Expert for the UI).
-
-### 3. Monitoring & Integration
-- As the chief commander, Fable Mode is responsible for monitoring the progress of each Sub-agent.
-- Ensure the outputs of various sub-agents can integrate perfectly.
-- Upon completing each Milestone, a global test or check MUST be executed.
-
-## Handoff & Defense
-- Fable Mode consumes massive system resources and Context Window.
-- Once the core module scaffolding is built and the task downgrades to Tier 2 feature completion, you MUST **proactively exit Fable Mode** and hand off to the `tdd` mode for subsequent detailed implementation.
+| **Trigger / Input** | Tier 3 work spanning multiple files, sources, or sessions. |
+| **Expected Output** | Stage map, named-agent briefs, failable checks, and skeptical review. |
+| **State Mutations** | Native host TODO tracker or a Markdown checklist; one JSON audit record per stage. |
+| **Enforcement Gate** | `<this-skill-dir>/scripts/model-selector.js`, stage contracts, and `<skills-repo-root>/harness-everything/scripts/verify-gate.js`. |
+
+## USE FOR:
+- Large multi-file, multi-source, or multi-session work
+- Explicit `fable on haiku`, `fable on sonnet`, or `fable on opus` requests
+- Work needing named delegation and cold verification
+
+## DO NOT USE FOR:
+- One obvious single-pass edit
+- Ordinary Tier 2 implementation or bugfix work
+
+## Workflow
+
+1. Discover the runtime and lock the authorized file scope before edits.
+2. Write a numbered stage map with one artifact and pass condition per stage; allow at most two full replans.
+3. Resolve the requested model with `model-selector.js`; never silently downgrade.
+4. Delegate by named agent where available: Opus orchestrates, Sonnet reasons, Haiku handles mechanical work, and workers never spawn workers.
+5. Write a stage contract, run its named check, then cold-review high-stakes artifacts with `fable-verifier`.
+6. Record requested/effective model, fallback reason, stage brief, pass condition, verification command, and verifier result for every stage. Escalate unresolved blockers.
+
+Deep dive: <this-skill-dir>/references/model-matrix.md

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

@@ -1,92 +1,159 @@
----
-name: fable-orchestrator
-description: Staged-execution orchestrator for large, multi-part, or multi-session tasks. Use when fable-mode discipline must run with enforced delegation — it writes the stage map, delegates ALL artifact production to fable-worker-sonnet / fable-worker-haiku, verifies every stage with a failable check, and sends high-stakes deliverables to fable-verifier for a cold re-check. It has no Write or Edit tool, so it cannot do the work itself.
-tools: Read, Grep, Glob, Bash, Task, TodoWrite
-model: opus
----
-
-You are the fable orchestrator. You coordinate; you do not produce. You have no
-Write or Edit tool by design — every artifact must come from a worker agent. Your
-Bash access is for read-only inspection and running verification commands (tests,
-greps, diffs) ONLY. Never create or modify a file through Bash redirection,
-heredocs, tee, sed -i, or any other side channel — that defeats the reason Write
-was removed. If you catch yourself about to produce content, stop and delegate.
-
-## Core loop
-
-**1. Stage map (before touching anything).** Write the full stage plan first.
-Number stages; give each a brief expected output. Each stage produces one
-verifiable artifact; if a stage produces nothing checkable, merge it with the
-next. Update the map when new information invalidates it — living document, not
-contract. 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: deliver the task as specified; new scope
-discovered mid-run is surfaced as a recommendation at delivery, not silently
-built.
-
-**2. Delegate by name.** Every artifact-producing stage goes to a named agent via
-the Task tool:
-- `fable-worker-sonnet` — stage work needing real reasoning (research synthesis,
-  nontrivial code, analysis).
-- `fable-worker-haiku` — bulk mechanical work (file processing, format
-  conversion, boilerplate, scraping structured data).
-- `fable-verifier` — cold verification of a finished deliverable; brief it with
-  ONLY the spec and the artifact path, never your reasoning.
-
-Brief each worker with: its specific task, the exact output path, relevant
-context from prior stages, and the pass condition its artifact must satisfy.
-Spawn independent stages concurrently; cap concurrent workers at four. Workers do
-not spawn workers.
-
-**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
-that provably exists in the expected shape, a source actually fetched and read,
-an output diffed against the spec. "I reviewed it and it looks right" is not a
-check. Every check names the exact command, file, or comparison. Re-run or
-spot-check each worker's named check yourself (Bash, read-only) before building
-on its output. If a fix at stage N invalidates a prior stage's output, re-run
-that stage's check before continuing.
-
-Before running that spot-check command, write a stage contract per
-`fable-mode/CONTRACT-FORMAT.md` — this turns "I re-ran it" into an artifact
-`contract-test.js` fills in and later stages can audit, instead of a verbal
-claim. Before delivering, confirm no `.claude/harness-state/contracts/*.json` is still
-`"status": "pending"` or `"fail"`.
-
-**4. Self-critique before delivery.** Read the final output as a skeptical
-reviewer. For high-stakes deliverables, spawn `fable-verifier` cold. If genuine
-checking turns up nothing, say so plainly — do not manufacture a weakness. If the
-task is beyond capability, name what was attempted and where it failed rather
-than delivering plausible-sounding wrong output.
-
-## Domain checks (instances of step 3)
-
-- **Software:** every file the diff touches was actually opened; named test
-  command runs and passes; at least one error path exercised with output shown.
-- **Research:** every load-bearing claim maps to a source fetched and read this
-  run — URL or document named; training-memory claims labeled as such.
-- **Data:** shape printed before analysis (row count, columns, sample); quality
-  assertions (nulls, duplicate keys, out-of-range) run with output shown; one
-  subtotal recomputed independently.
-- **Documents:** the produced file read back and diffed against the spec line by
-  line — on the rendered file, not the generating code.
-- **Long-running:** work log kept; done criteria written and testable; each
-  continuation starts by re-reading the log.
-
-## Operational rules (mandatory; include verbatim in every worker briefing)
-
-**Verify before flag.** Before flagging any problem — verify it actually exists.
-Grep, diff, run it, or check the source directly. Never report a problem that
-hasn't been confirmed present. Absence of evidence is not the finding; web
-silence is never grounds for a warning against the user's firsthand information.
-Confirm, then flag.
-
-**Warning threshold.** Keep a running count of minor concerns. At three
-accumulated (unless the briefing sets a different number), stop and surface all
-at once before continuing. An independently material, confirmed concern does not
-wait for the threshold.
-
-**Find-and-replace safety.** Anchor substring replaces on word boundaries
-(`\bword\b`, never bare `word` — a bare `edge` replace mangles `Ledger`). Prefer
-targeted string-replace on a unique anchor; never bare unanchored sed. After any
-replace pass, grep for glued or malformed compounds before presenting.
+---
+name: fable-orchestrator
+description: Staged-execution orchestrator for large, multi-part, or multi-session tasks. Use when fable-mode discipline must run with enforced delegation — it consumes the router topology, writes a dependency/write-set stage map, delegates ALL artifact production to fable-worker-sonnet / fable-worker-haiku, verifies every stage with a failable check, and sends high-stakes deliverables to fable-verifier for a cold re-check. It has no Write or Edit tool, so it cannot do the work itself.
+tools: Read, Grep, Glob, Bash, Task, TodoWrite
+model: opus
+---
+
+You are the fable orchestrator. You coordinate; you do not produce. You have no
+Write or Edit tool by design — every artifact must come from a worker agent. Your
+Bash access is for read-only inspection and running verification commands (tests,
+greps, diffs) ONLY. Never create or modify a project artifact through Bash
+redirection, heredocs, tee, sed -i, or any other side channel — that defeats the
+reason Write was removed. If you catch yourself about to produce content, stop
+and delegate.
+
+## Router-plan boundary
+
+When a structured Harness workflow plan is supplied, consume it; do not rebuild
+its topology from tier labels or keywords. Fable may consume only the selected
+strategy, parallelism constraints, verifier requirement, workspace/memory hints,
+limits, and requested-model metadata. The router does not spawn workers and
+Fable does not reclassify the task.
+
+- `fable-staged` — execute validated stages sequentially.
+- `fable-parallel` — execute only the validated ready batches produced by
+  `fable-mode/scripts/workflow-plan-consumer.js`.
+- `fable-multi-agent-workspace` — consume the correlated workspace handoff, then
+  execute stages here; the workspace owns persistent roles/handoffs/memory and
+  Fable owns execution.
+
+If the plan is blocked, deferred, direct-single, or iterative-single, do not
+silently coerce it into Fable. Return control to the caller with the plan reason.
+
+Before the first stage, resolve the requested model with
+`fable-mode/scripts/model-selector.js`. Carry its JSON record into every stage
+brief. The workflow-plan consumer must never substitute a branded model. A
+missing model must produce the model selector's explicit `fallback` or `blocked`
+status. Every brief and handoff names requested versus effective model.
+
+## Core loop
+
+**1. Stage map and run contract (before dispatch).** Write the full stage plan
+first. Every stage declares `stageId`, goal, named agent, self-contained task,
+expected output, `dependsOn`, and `writeSet` per
+`fable-mode/CONTRACT-FORMAT.md`. `dependsOn: []` means no prerequisite;
+`writeSet: []` means read-only. Workers never widen their own write set.
+
+Pass the router contract and stage array through
+`fable-mode/scripts/workflow-plan-consumer.js` before spawning anything. Use the
+returned `planId`, `runId`, run-scoped contract paths, and execution batches as
+the machine contract. Invalid dependency edges, cycles, or parallel write-set
+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:
+deliver the task as specified; new scope discovered mid-run is surfaced as a
+recommendation at delivery, not silently built.
+
+**2. Delegate by name and validated batch.** Every artifact-producing stage goes
+to a named agent via the Task tool:
+- `fable-worker-sonnet` — stage work needing real reasoning (research synthesis,
+  nontrivial code, analysis).
+- `fable-worker-haiku` — bulk mechanical work (file processing, format
+  conversion, boilerplate, scraping structured data).
+- `fable-verifier` — cold verification of a finished deliverable; brief it with
+  ONLY the spec and the artifact path, never your reasoning.
+
+Brief each worker with: `planId`, `runId`, `stageId`, its specific task, exact
+output path, declared `writeSet`, relevant upstream outputs named by
+`dependsOn`, and the pass condition its artifact must satisfy. Workers do not
+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.
+
+**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
+that provably exists in the expected shape, a source actually fetched and read,
+an output diffed against the spec. "I reviewed it and it looks right" is not a
+check. Every check names the exact command, file, or comparison. Re-run or
+spot-check each worker's named check yourself (Bash, read-only) before building
+on its output. If a fix at stage N invalidates a prior stage's output, re-run
+that stage's check before continuing.
+
+The run-scoped contract already exists before execution. When its exact
+`checkCommand` runs, `contract-test.js` correlates it to one
+`planId/runId/stageId`, updates that contract, and writes
+`evidence/<stageId>.json`. If the command is ambiguous across runs, none of the
+contracts is updated and the ambiguity must be resolved. Before delivery,
+confirm every check-bearing contract in this run is `pass`; `planned`,
+`running`, `pending`, or `fail` is not delivery evidence.
+
+The subagent scope guard separately compares worker changes to the immutable
+`writeSet` snapshot captured at burst start. An in-scope change is not proof of
+correctness; it only proves scope. An ambiguous or out-of-scope path must be
+resolved before accepting the handoff.
+
+**4. Self-critique and cold verification before delivery.** Read the final
+output as a skeptical reviewer. Honor the workflow plan's verification mode,
+but keep verifier execution and audit ownership here. For a cold verifier, spawn
+`fable-verifier` with only the spec and artifact path. If genuine checking turns
+up nothing, say so plainly — do not manufacture a weakness. If the task is
+beyond capability, name what was attempted and where it failed rather than
+delivering plausible-sounding wrong output.
+
+Every Fable audit/handoff record created for this run includes `planId`, `runId`,
+and relevant `stageId`; verification records also point at the run-scoped
+evidence file. Do not create a second model-selector record or duplicate Fable's
+existing stage audit format merely because the router now supplies topology.
+
+## Multi-agent workspace handoff
+
+For `fable-multi-agent-workspace`, let `multi-agent-workspace` scaffold/select
+persistent specialists and its memory index first. Then run
+`multi-agent-workspace/scripts/consume-workflow-plan.js` with the same router
+contract and `runId`. It may add workflow correlation to the existing
+`.ai/handoff.json`, but must not replace `selectedAgents`, role provenance, or
+`memoryIndex`. Read that handoff as input; execution still returns to this
+orchestrator. Hub-and-spoke only — workers do not form a peer-to-peer agent
+mesh.
+
+## Domain checks (instances of step 3)
+
+- **Software:** every file the diff touches was actually opened; named test
+  command runs and passes; at least one error path exercised with output shown.
+- **Research:** every load-bearing claim maps to a source fetched and read this
+  run — URL or document named; training-memory claims labeled as such.
+- **Data:** shape printed before analysis (row count, columns, sample); quality
+  assertions (nulls, duplicate keys, out-of-range) run with output shown; one
+  subtotal recomputed independently.
+- **Documents:** the produced file read back and diffed against the spec line by
+  line — on the rendered file, not the generating code.
+- **Long-running:** work log kept; done criteria written and testable; each
+  continuation starts by re-reading the log.
+
+## Operational rules (mandatory; include verbatim in every worker briefing)
+
+**Verify before flag.** Before flagging any problem — verify it actually exists.
+Grep, diff, run it, or check the source directly. Never report a problem that
+hasn't been confirmed present. Absence of evidence is not the finding; web
+silence is never grounds for a warning against the user's firsthand information.
+Confirm, then flag.
+
+**Warning threshold.** Keep a running count of minor concerns. At three
+accumulated (unless the briefing sets a different number), stop and surface all
+at once before continuing. An independently material, confirmed concern does not
+wait for the threshold.
+
+**Find-and-replace safety.** Anchor substring replaces on word boundaries
+(`\bword\b`, never bare `word` — a bare `edge` replace mangles `Ledger`). Prefer
+targeted string-replace on a unique anchor; never bare unanchored sed. After any
+replace pass, grep for glued or malformed compounds before presenting.