harness-everything 0.3.6 → 0.4.0

package/fable-mode/CONTRACT-FORMAT.md

@@ -1,51 +1,165 @@
-# Stage Contract Format
+# Fable Stage Contract Format
 
-Stage contracts live in `.claude/harness-everything/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.
+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.
 
-## When to write one
+Run state is stored under the existing workspace-keyed global Harness state
+root, never inside the repository:
 
-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.
+```text
+<workspace-state>/state/fable-runs/<runId>/
+  run.json
+  contracts/<stageId>.json
+  evidence/<stageId>.json
+  ensemble.json             # only when ensemble review executes
+```
 
-## File
+`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.
 
-`.claude/harness-everything/state/contracts/<stageId>.json`, created lazily. `stageId` is whatever you
-numbered the stage in your stage map (`stage-3`, `db-migration`, etc).
+## Stage schema v2
 
-## Schema
+Every planned stage declares dependency and write scope before dispatch:
 
 ```json
 {
   "stageId": "stage-3",
+  "goal": "implement one bounded objective",
   "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"
+  "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"]
 }
 ```
 
-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.
+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
+```
 
-## Reading contracts back
+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 delivering, `Read` (or `Grep status` across) `.claude/harness-everything/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.
+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.
 
-## Not a blocking gate
+## Scope audit
 
-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`.
+`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

@@ -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.3.5
+  version: 0.4.0
 ---
 
 # Fable Mode (v3)
@@ -16,7 +16,7 @@ metadata:
 | **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** | `fable-mode/scripts/model-selector.js`, stage contracts, and `harness-everything/scripts/verify-gate.js`. |
+| **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
@@ -36,4 +36,4 @@ metadata:
 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.
 
-Model roles, fallback behavior, and the audit schema live in `references/model-matrix.md`.
+Deep dive: <this-skill-dir>/references/model-matrix.md

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

@@ -1,6 +1,6 @@
 ---
 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.
+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
 ---
@@ -8,31 +8,59 @@ 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.
+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. A missing model must produce an explicit `fallback` or `blocked` status;
-never silently substitute a model. Every brief and handoff names the stage
-artifact, pass condition, verification command, verifier result, and requested
-versus effective model.
+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 (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:
+**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
@@ -40,10 +68,17 @@ the Task tool:
 - `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.
+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
@@ -54,17 +89,42 @@ 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-everything/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.
+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)
 

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

@@ -7,7 +7,7 @@ description: >-
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.3.5
+  version: 0.4.0
 ---
 
 # Execution Guardrails
@@ -40,4 +40,4 @@ metadata:
 
 These rules are always-on, even when `fable-mode`'s staged loop is not running.
 
-Deep dive: references/guardrail-rules.md
+Deep dive: <this-skill-dir>/references/guardrail-rules.md

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.3.5
+  version: 0.4.0
 ---
 
 # Fable Mode — Haiku
@@ -28,9 +28,9 @@ metadata:
 
 ## Run it
 
-1. Resolve `haiku` through `../scripts/model-selector.js`.
+1. Resolve `haiku` through `<this-skill-dir>/../scripts/model-selector.js`.
 2. Spawn `fable-worker-haiku` when available; otherwise use an inline fallback only when the audit record says so.
 3. Brief one bounded output path and a named check; workers do not spawn workers.
 4. Route synthesis blockers to Sonnet/Opus and cold-review unsupervised delivery with `fable-verifier`.
 
-Use `../references/model-matrix.md` for the audit fields and fallback policy.
+Use `<this-skill-dir>/../references/model-matrix.md` for the audit fields and fallback policy.

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.3.5
+  version: 0.4.0
 ---
 
 # Fable Mode — Opus
@@ -28,9 +28,9 @@ metadata:
 
 ## Run it
 
-1. Resolve `opus` through `../scripts/model-selector.js`.
+1. Resolve `opus` through `<this-skill-dir>/../scripts/model-selector.js`.
 2. Spawn `fable-orchestrator` when the runtime exposes it; otherwise report the inline fallback explicitly.
 3. The orchestrator owns scope lock, at most two replans, stage contracts, named worker delegation, and escalation; it never produces artifacts itself.
 4. Cold-review high-stakes deliverables with `fable-verifier`; report every unverified stage.
 
-Use `../references/model-matrix.md` for the audit fields and fallback policy.
+Use `<this-skill-dir>/../references/model-matrix.md` for the audit fields and fallback policy.

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.3.5
+  version: 0.4.0
 ---
 
 # Fable Mode — Sonnet
@@ -28,9 +28,9 @@ metadata:
 
 ## Run it
 
-1. Resolve `sonnet` through `../scripts/model-selector.js`; normalize `sonnect` to Sonnet.
+1. Resolve `sonnet` through `<this-skill-dir>/../scripts/model-selector.js`; normalize `sonnect` to Sonnet.
 2. Spawn `fable-worker-sonnet` when available, otherwise use a visible inline fallback.
 3. Brief the exact artifact path, context, and pass condition; workers do not spawn workers.
 4. Send high-stakes artifacts to `fable-verifier` and escalate contradictions instead of guessing.
 
-Use `../references/model-matrix.md` for the audit fields and fallback policy.
+Use `<this-skill-dir>/../references/model-matrix.md` for the audit fields and fallback policy.