@iowarp/clio-coder 0.3.4 → 0.3.7

package/docs/evidence-and-memory.md

@@ -1,9 +1,9 @@
 # Evidence Corpus and Long-Term Memory
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.4). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.7). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
 
-Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.3.4, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
+Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. In v0.3.7, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.
 
@@ -148,11 +148,11 @@ Each run receipt (persisted under `<stateDir>/receipts/<runId>.json`) carries an
 ### Computation and Lifecycle
 - **Circular Dependency Prevention**: To prevent circular dependencies, `findingsSummary` is calculated **cheaply in-memory** at receipt-record time using the draft envelope and tool statistics (in `src/domains/dispatch/receipt-findings.ts`). It never reads from disk or calls `buildEvidence`.
 - **First-Pass Success**: Calculated as `true` only if the terminal outcome was `"succeeded"`, the lineage attempt was `0` (no dispatch retries), the tool stats confirm at least one successful validation tool was executed, and no failure-cause tags were detected.
-- **Cryptographic Coverage**: Current receipts use strict v15 and authenticate every current receipt field, including briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, and result-contract conformance, against the reconstructed ledger. Every version other than v15 is rejected; there is no historical receipt reader.
+- **Cryptographic Coverage**: Current receipts use strict v19 and authenticate every current receipt field, including briefing and steering provenance, routing intent and decision, route quality, worker identity, execution role, result-contract conformance, council provenance, and fleet gate provenance, against the reconstructed ledger. Every version other than v19 is rejected; there is no historical receipt reader.
 
 | Version | Verification policy | Compatibility policy |
 |---|---|---|
-| v15 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
+| v19 | Current canonical projection; every current receipt and reconstructible ledger field is authenticated | Accepted |
 | Any other version | No reader | Rejected; remove or archive the incompatible state rather than expecting migration |
 
 Receipt integrity and evidence verification answer different questions. The
@@ -227,7 +227,7 @@ finish-contract records without changing receipt-owned axes. Findings such as
 domain artifacts remain in the receipt, gate, audit, and trace files.
 
 The canonical aggregate is an additive projection for downstream work. Receipt
-integrity remains version 15, evidence bundles remain version 1, gate decisions
+integrity remains version 18, evidence bundles remain version 1, gate decisions
 remain version 2, and no persisted receipt field or cryptographic algorithm
 changes.
 
@@ -246,7 +246,8 @@ Mutation-report receipts are grounded directly against observed tool events reco
 
 ```bash
 clio-coder memory list
-clio-coder memory propose --from-evidence <evidenceId>
+clio-coder memory propose --from-evidence <evidenceId> [scope options]
+clio-coder memory promote --from-handoff <path> [--entry <id>...] --scope <scope> [scope options]
 clio-coder memory approve <memoryId>
 clio-coder memory reject <memoryId>
 clio-coder memory prune --stale
@@ -267,6 +268,8 @@ The store is capped at `500` records and is sorted by scope, key, creation time,
 ```mermaid
 stateDiagram-v2
     evidence --> proposed: propose --from-evidence
+    taskBank --> proposed: /memory selected-entry action
+    redactedHandoff --> proposed: promote --from-handoff
     proposed --> approved: approve <id>
     proposed --> rejected: reject <id>
     approved --> rejected: reject <id>
@@ -277,6 +280,45 @@ stateDiagram-v2
 
 Records must cite at least one evidence ID to be considered for prompt injection. Rejected records remain in the store until stale pruning so the same bad lesson is not immediately re-proposed from the same evidence.
 
+Task-bank promotion is a reviewed export from transient execution memory. The
+`/memory` overlay offers repo and global proposal actions only on selected
+knowledge and procedural rows. Status remains private and cannot enter the
+promotion service. The first global action arms a warning, and the second
+action acknowledges the broader applicability. A successful action writes an
+unapproved record and names the separate `memory approve` command required to
+make it injectable.
+
+The CLI consumes a version 2 `clio-task-memory` handoff snapshot. Omitting
+`--entry` proposes every knowledge and procedural entry; repeating `--entry`
+selects exact entry IDs. Version 2 snapshots carry source session, evidence,
+runtime, agent, timestamps, and export-redaction facts. Version 1 snapshots
+remain seedable but cannot be promoted because they do not carry source
+session or evidence provenance.
+
+Every promotion redacts secret-shaped values before `records.json` is written.
+The durable provenance block records the source kind, session, selected entry,
+entry class and timestamps, plus the replacement count and source field paths.
+Promotion never approves its own output.
+
+### Explicit scope selection
+
+Reviewed scope options are closed to four choices:
+
+| Scope | Required selection | Validation |
+| --- | --- | --- |
+| `repo` | `--repository <canonical-absolute-path>` | The path must exist and already equal its canonical absolute identity. Symlink aliases and paths containing unresolved segments are rejected. |
+| `global` | `--acknowledge-global` | The acknowledgement is separate from `--scope global`. |
+| `runtime` | `--runtime <id>` | The ID must be valid and must occur in the source provenance. |
+| `agent` | `--agent <id>` | The ID must be valid and must occur in the source provenance. |
+
+The same options may be added to `memory propose --from-evidence`. With no
+scope option, evidence proposals keep the existing inference order. An
+explicit repository may differ from the repository that produced the
+evidence, which supports a reviewed lesson about repository A learned while
+working in repository B. Runtime and agent overrides may only select an exact
+identity already recorded by the evidence. Global scope always requires its
+own acknowledgement. No inference path widens an explicit choice.
+
 ---
 
 ## Prompt injection rules
@@ -287,7 +329,7 @@ Defaults:
 
 | Constraint | Default |
 | --- | --- |
-| Scopes | `global`, `repo` |
+| Base scopes | `global`, `repo` |
 | Token budget | `400` estimated tokens |
 | Max records | `5` |
 | Required status | `approved: true` |
@@ -296,6 +338,12 @@ Defaults:
 
 Rendered memory lines always cite record ID, scope, lesson, and evidence IDs. The prompt tells the model not to extrapolate beyond cited findings.
 
+Interactive main-agent sessions additionally admit records for the exact
+active runtime. `clio-coder run --agent` admits records for the exact resolved
+runtime and selected agent. Runtime and agent records use structured identity
+fields; `appliesWhen` text cannot grant either applicability. Missing,
+malformed, or different active identities exclude those records.
+
 ### Repository-scoped identity
 
 Repository memory is selected by an exact canonical absolute-path identity. The interactive orchestrator and `clio-coder run --agent` compute that identity from the active working directory; symlink aliases collapse to the same key. A repository move, a different Git worktree path, a subdirectory launch, a malformed identity, or a missing identity does not inherit another repository's memory. Global records are unaffected.
@@ -308,15 +356,27 @@ Every `scope: "repo"` record must carry:
 
 The structured `repository` field is the only applicability mechanism: store validation rejects repo records without it, and `appliesWhen` tokens never grant repository applicability. There is intentionally no automatic path rewrite for moved repositories or worktrees: a filesystem move produces a different identity and the record simply stops applying until it is re-scoped with new evidence.
 
+Runtime and agent records follow the same fail-closed shape:
+
+```json
+{ "runtime": { "kind": "runtime", "key": "openai" } }
+```
+
+```json
+{ "agent": { "kind": "agent", "key": "coder" } }
+```
+
+Only the field matching the record scope is present.
+
 ---
 
 ## Recommended workflow
 
 1. Build evidence from the run/session/eval that taught the lesson.
 2. Inspect the evidence and findings.
-3. Propose memory from the evidence.
-4. Review the proposed lesson for correctness and scope.
-5. Approve only if it is durable and useful.
+3. Propose memory from the evidence, or promote selected public task memory from `/memory` or a redacted handoff.
+4. Review the proposed lesson, source provenance, redaction facts, and exact scope.
+5. Approve only if it is durable and useful under that scope.
 6. Reject incorrect or overbroad records.
 7. Prune stale records periodically.
 

package/docs/evolution.md

@@ -1,7 +1,7 @@
 # Evolution and Change Manifests
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.3.7).
 
 Clio Coder uses change manifests to make harness changes reviewable, falsifiable, and rollback-friendly. CLIO stands for Context Layer for Input/Output, named for the Greek muse of history. A manifest is JSON, generated or checked with `clio-coder evolve manifest`, and should describe what changed, why, what evidence supports it, what could regress, how to validate it, and how to roll it back.
 

package/docs/exit-codes-and-output.md

@@ -1,6 +1,6 @@
 # Exit Codes & Machine-Readable Output Contracts
 
-This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.4`.
+This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.7`.
 
 Source implementations: `src/cli/` and `src/entry/`.
 
@@ -66,6 +66,9 @@ Many Clio CLI subcommands provide structured JSON output for integration with sc
 | `clio-coder targets` | `--json` | JSON object containing the configured `targets` array. |
 | `clio-coder models` | `--json` | JSON array of catalog models with capability flags. |
 | `clio-coder fleet status` | `--json` | JSON snapshot object with `generatedAt`, `admission` (`open` or `draining`), `running`, `retrying`, and `totals`. Each run row carries its `node`, defaulting to `local`. |
+| `clio-coder fleet validate` | `--json` | JSON report with `valid`, `fleet`, and either successful `checks` plus `planHash` or failure `diagnostics`. Validation failures exit `1`; usage errors exit `2`. |
+| `clio-coder fleet graph` | `--json` | JSON object with `fleet`, `planHash`, compiled `waves`, and expanded `loops`. Contract failures exit `1`; usage errors exit `2`. |
+| `clio-coder fleet run --resume` | `--json` | NDJSON step records include `status: "replayed"` and the original receipt reference for replayed prefix steps. Plan or variable mismatches exit `1`. |
 | `clio-coder trace runs` | `--json` | JSON array of trace run records. |
 | `clio-coder trace sql` | Positional query | JSON array of rows returned by the read-only SQLite query. A single `SELECT` or read-only `WITH` statement is accepted; multiple statements and mutating keywords are refused with exit code 2. |
 | `clio-coder paths` | `--json` | JSON object mapping platform directory names to absolute paths. |

package/docs/extensions-and-sharing.md

@@ -1,7 +1,7 @@
 # Extensions, Prompt Templates, Skills, and Share Archives
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.7).
 
 Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts and skills. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators. Themes are built into the engine and are no longer loaded from extensions.
 
@@ -251,7 +251,7 @@ Share archives are single JSON files:
   "formatVersion": 1,
   "manifest": {
     "format": "clio.share.v1",
-    "clioVersion": "0.3.4",
+    "clioVersion": "0.3.7",
     "createdAt": "...",
     "files": []
   },
@@ -280,6 +280,8 @@ Options:
 | `--skills` | Include skills. |
 | `--settings` | Include non-secret settings fragment. |
 | `--extensions` | Include extension bundle files, excluding extension `state.json`. |
+| `--agents` | Include agent recipe files. |
+| `--fleets` | Include fleet contract files. |
 | `--all` | Include every supported resource class. |
 
 If no include flags are supplied, export includes all supported classes for the selected scope.
@@ -296,6 +298,8 @@ clio-coder share import project.clio-coder-share.json --force
 
 Dry-run imports produce a plan and report conflicts without writing. Without `--force`, conflicting destination files block writes. With `--force`, conflicting files are overwritten and supported settings-fragment keys are merged into the current settings file.
 
+Archives accept `agent` and `fleet` file entry types alongside prompts and skills. Agent entries import into the user agent root and must pass the recipe parser and policy checks. Fleet entries import into the user fleet root and must pass `parseFleetContract` before any write. Dry-run plans report both types by kind.
+
 Aliases:
 
 ```bash

package/docs/fleet-demo-runbook.md

@@ -136,7 +136,7 @@ clio-coder evidence inspect <evidenceId>
 run ledger; a tampered or mismatched receipt fails the build with the field
 that diverged. The receipts of the remote runs verify on the orchestrator host because the
 ledger and receipts live on the shared filesystem. Current receipts use strict
-v15 and authenticate every current receipt and reconstructed-ledger field.
+v16 and authenticate every current receipt and reconstructed-ledger field.
 Every other receipt version is rejected rather than reported as partial; the
 current binary has no historical receipt reader.
 
@@ -168,7 +168,7 @@ reconstruct:
    complete receipt schema and its stable ledger row. `clio-coder evidence build
    --run <id>` recomputes and cross-checks it; `verifyReceiptIntegrity` in
    `src/domains/dispatch/receipt-integrity.ts` is the reference
-	implementation. Current receipts use v15 and every other version fails
+	implementation. Current receipts use v16 and every other version fails
 	verification. Incompatible state must be archived or removed; it is never
 	read as evidence through a compatibility verifier.
 

package/docs/fleet-dispatch.md

@@ -1,6 +1,6 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.4).
+> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.7).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -77,7 +77,11 @@ briefing wins. Supplying both `task` and `tasks` fails instead of choosing one.
 After approval, execution consumes only the registry-owned resolved plan, so
 later mutation of raw arguments cannot change either field.
 
-Recipes may declare `budget: {toolCalls, readReserve, synthesis}`. `toolCalls` is the admitted-call phase boundary; the final `readReserve` slots accept canonical `read` plus the agent's granted mutation tools, so a writer can still deliver inside its own reserve; `synthesis: true` forces a text-only final round, while `false` stops after the admitted phase. `guardrails.workerToolCallCap` is transported separately as the ceiling on executed calls and always wins when lower. Native workers and Claude SDK enforce this policy. Claude Code and Antigravity reject explicit-budget recipes because their black-box loops cannot provide equivalent per-call mediation. Before launch, every admitted WorkerSpec v3 contains one concrete effective budget and a settings fingerprint, including custom recipes whose source omitted a budget.
+Recipes declare a default with `budget: {toolCalls, readReserve, synthesis}`. They may also declare `maximum: {toolCalls, readReserve}` inside that object. A recipe without `maximum` is an exact pin, which preserves the fixed behavior of existing recipes. A ranged recipe admits the optional dispatch request `budget: {toolCalls, readReserve, retryRevision?}` only when the request is inside its maximum. `retryRevision` has the same two integer fields and preauthorizes the ceiling that a later automatic retry, bounded result-contract revision, or review revision may select. The loop guard raises a result-contract revision boundary only in this case. A phase without that ceiling cannot grow and retains the existing text-only repair behavior.
+
+`toolCalls` is the admitted-call phase boundary. The final `readReserve` slots accept canonical `read` plus the agent's granted mutation tools, so a writer can still deliver inside its own reserve. Admission requires integers and `0 <= readReserve < toolCalls` for every declared phase. `synthesis: true` forces a text-only final round, while `false` stops after the admitted phase. `guardrails.workerToolCallCap` remains the operator-controlled lifetime ceiling and always wins when lower. A default may be clamped by a lower operator cap so default callers retain their prior behavior; an explicit request outside the operator cap is denied.
+
+Admission computes one immutable envelope with the recipe policy, invocation request, effective worker budget, and every clamp or escalation reason. Native workers and Claude SDK enforce the effective budget. Claude Code, Antigravity, and ACP delegation reject invocation envelopes because their black-box loops cannot provide equivalent per-call mediation. Before launch, every admitted WorkerSpec v3 still contains one concrete effective budget and a settings fingerprint. The envelope provenance is sealed in the run ledger and receipt and appears in monitor, fleet status, and the live fleet card.
 
 ## Node setup
 
@@ -156,7 +160,7 @@ Use `clio-coder fleet resume [--json]` to reopen admission early. Detailed drain
 
 With no fleet configured and nothing requested, placement resolves to the
 implicit local path and optional fleet-node provenance may remain absent.
-Every new receipt uses strict integrity v15; older receipt formats are not
+Every new receipt uses strict integrity v19; older receipt formats are not
 accepted by the current reader.
 
 ## Failure semantics
@@ -198,8 +202,92 @@ request-level `autonomy` can only narrow the level (reviewers and judges run
 | Detached | `detach: true` | Return logical assignment ids and a batch id immediately; collect later. |
 | Review gate | `review: {reviewer?, max_cycles?}` | Builder, read-only reviewer verdict, bounded revise loop. |
 | Compete | `mode: "compete", candidates: 2..4` | N candidates in scratch worktrees, read-only judge, winner applied or preserved. |
+| Council | `mode: "council", roster: "design"` | Two to five read-only members answer the same task, with optional vote or judge synthesis. |
 | Agent automation | `agent: "auto"` | Baselines candidate agent from task shape via shared classifier (`coder`, `tester`, `documenter`, `verifier`, `researcher`, `scout`); advisory unless activated. |
 
+### Single-writer token
+
+A parallel batch may declare `writers: 1`. One is the only accepted value in
+this release, and omission retains ordinary parallel admission. The scheduler
+admits at most one write-scope step at a time. An agent step with a nonempty
+`writes` allowlist is a writer, as is a workspace-scope step that may mutate
+the checkout. Read-scope steps and agent steps with `writes: []` remain
+concurrent. Waiting writers follow the plan's declared step order and then the
+request order. Agent ledger claims remain advisory and do not enforce the
+token.
+
+The first checkout writer acquires a process-owned lease under the Clio state
+directory. Its key is the canonical checkout path, and its record contains the
+owner pid, process birth token, and acquisition time. A live sibling process
+causes admission to fail with `checkout_writer_lease_held` and the holder pid.
+A dead owner or reused pid is reclaimed. The lease remains held until the last
+writer settles, including writers collected from detached batches. Read-only
+runs never acquire it.
+
+### Worktree per task
+
+A singular writer or an item in `tasks` may declare `worktree: true` and
+`apply: "merge" | "preserve"`. The default is `merge`. Clio creates
+`.clio-coder/worktrees/<runId>/` on `clio/task/<runId>`, maps the worker cwd and
+protected artifacts into that checkout, and runs declared host verification
+there. The approved execution snapshot renders both fields and freezes the
+parent checkout as the merge destination.
+
+After a successful worker and successful host verification, merge application
+commits the task branch, rechecks protected paths, and uses the same guarded
+merge path as compete. A conflict fails closed with
+`worktree_merge_conflict` and preserves the branch and worktree. Preserve
+application never merges and reports the branch. A detached task applies when its run finalizes, so `monitor(mode="collect")` returns the sealed application receipt.
+Admission refuses a non-git checkout, a read-only agent, compete mode, or an
+explicit cwd outside the parent checkout with a named reason.
+
+### Typed intent and host-run verification
+
+The singular request and every object in `tasks` accept an optional `intent`:
+
+```json
+{
+  "read_roots": ["src/domains/dispatch"],
+  "write_roots": ["src/tools"],
+  "relevant_paths": ["docs/fleet-dispatch.md"],
+  "expected_outputs": ["dist/cli.js"],
+  "verification": [{ "check": "test", "timeout_ms": 600000 }]
+}
+```
+
+A top-level intent is inherited by batch items unless an item supplies its own
+intent. `gate: "test"` is exact shorthand for
+`intent.verification: [{check: "test"}]`; supplying both spellings is refused.
+Every path is normalized into a sorted, duplicate-free repository-relative
+POSIX path list before approval. Absolute paths, empty paths, root escapes,
+malformed entries, and values beyond the documented caps fail admission.
+Normalized `intent.writeRoots` feeds the existing worker write-boundary
+enforcement when no legacy `JobSpec.writeRoots` exists. Conflicting declarations
+are refused as `intent_write_roots_contradiction`.
+
+Verification values are declared check ids, never shell commands. Admission
+resolves each id from a package script or `.clio-coder/verifiers.yaml`, clamps
+the requested timeout to the declaration, and freezes the exact argv, cwd,
+timeout, and normalized intent into the execution snapshot and plan hash. A
+later catalog edit cannot change the approved command. Undeclared ids fail
+before approval with `verification_check_undeclared` and declaration guidance.
+
+After a successful worker attempt, the orchestrator runs the frozen checks with
+no shell, a fixed cwd, and the code-step environment allowlist. Logs are written
+under the run artifact directory. Successful evidence is memoized by the
+workspace fingerprint, resolved argv, cwd, and allowed environment values. A
+memo hit names the run that produced the original evidence. A changed tree is a
+miss. An unsuccessful worker records `hostVerification.status="skipped"` with
+`reason="worker_not_successful"`; a failed host check records `rejected` with
+its exit code, bounded output tail, and artifact path. Worker-reported command
+success never populates this status.
+
+Host checks are supported for singular, parallel, sequential, pipeline, and
+detached native runs. Review and compete accept intent paths and outputs but
+refuse verification entries with `verification_unsupported_for_mode`.
+Claude Code subprocess routes refuse them with
+`verification_unsupported_runtime`.
+
 ### Agent ledger
 
 Every topology that runs more than one worker at once opens an agent ledger, the
@@ -317,6 +405,32 @@ the workers are quiesced but the candidates remain until that output is bound
 to an integrity-verified judge receipt; a recovered winner is preserved for
 operator inspection rather than silently auto-applied after restart.
 
+### Council
+
+Council is the read-only sibling of compete. Two to five members run the same
+singular task concurrently on local HTTP or native targets. A request selects
+exactly one configured `workers.rosters` entry or supplies inline `members`.
+Admission pins every member to `read-only` autonomy and to the `read`, `grep`,
+`find`, `ls`, `code_nav`, and `context` tool surface. A route that resolves to
+an SSH fleet node is refused before approval. Council never creates a worktree
+and never mutates the workspace.
+
+Council supports one to three rounds. The first round gives every member the
+same task and briefing. A later round gives each member the other members'
+prior answers as labelled, untrusted briefing data. The member never receives
+its own prior answer. Each briefing is limited to 8 KiB and carries an explicit
+truncation marker when necessary. A failed peer contributes a labelled failure
+marker and no answer text.
+
+`synthesis: "none"` returns the final member answers directly. `vote` performs
+a deterministic majority tally over structured `verdict` fields without a
+model call. A vote with no majority reports `no_majority`, and a vote with no
+verdict fields reports `no_verdict_field`. `judge` runs one additional read-only judge against all final
+answers. Every member run seals a receipt. A judge receipt points backward to
+every final member receipt through gate provenance. The approval artifact names
+each member's label, target, model, thinking level, node, color, round count,
+and synthesis mode, so the plan hash binds the whole council contract.
+
 ### ExecutionPlan and plan approval
 
 Every orchestration shape compiles to one strict ExecutionPlan v2 DAG with
@@ -363,11 +477,36 @@ rejected.
 
 Clio ships three builtin fleet contracts under `src/domains/agents/fleets/`: `build-test`, `build-review`, and `sdlc`. Projects can declare custom fleet contracts or shadow builtin fleets by placing Markdown files under `.clio-coder/fleets/<name>.md`. A file named `.clio-coder/fleets/<name>.md` shadows a builtin fleet of the same name.
 
-Fleet contracts support schema versions 1 through 4:
+Fleet contracts support schema versions 1 through 5:
 - Version 1: Supports agent steps only.
 - Version 2: Introduces deterministic code steps.
 - Version 3: Adds bounded check/repair loops and commit steps with `commitFrom` message sources.
 - Version 4 (`FLEET_WRITE_BOUNDARY_VERSION = 4`): Introduces per-step declared write boundaries (`writes`) and orchestrator post-step enforcement.
+- Version 5 (`FLEET_DYNAMIC_STEP_VERSION = 5`): Adds plan steps, executable gate steps, per-step target or worker-profile defaults, and the optional single-writer declaration.
+
+#### Contract v5: plan, gate, and per-step target
+
+A version 5 agent step, including an agent loop check or repair, may declare either `target: <targetId>` or `profile: <workers.profiles key>`. It may never declare both. Fleet preflight resolves these values through the same worker routing used by `/run --target` and `/run --agent-profile`. An unknown value refuses before approval and names the target or profile. Versions 1 through 4 continue to refuse both fields.
+
+A `kind: gate` step asks its validator agent to write exactly one repository-relative `path`. The contract derives the step's write boundary from that path, so a separate `writes` property is refused. Its `run` property names a command whose argv contains one whole-token `{{path}}` placeholder. After the agent writes the executable acceptance check, the coordinator runs it without a shell against the otherwise untouched tree. A red result admits the gate. A green result refuses the run as `gate_not_discriminating`. The fleet ledger records the gate path hash. A loop may use `check: {kind: gate, gate: <stepId>}`. Only the bounded output lines beginning with `FAIL` cross that failed check edge into the repair agent.
+
+A `kind: plan` step defaults to the builtin `architect`. It declares `roster`, `maxTasks` from 1 through 16, an optional `proposals: true`, its own scope and write boundary, and an optional target or profile default. The architect returns a `delegation-plan` object whose tasks contain `id`, `agent`, `description`, `depends_on`, `writes`, and an optional `mode` of `sequential` or `parallel`. The coordinator admits only roster agents, unique and acyclic task ids, resolvable dependencies, the declared task count, and task writes contained by the plan step boundary. Successful tasks carry lineage to the plan step and inherit its target or profile. A contract with `writers: 1` serializes write tasks through the existing single-writer token.
+
+When `proposals: true`, every roster member first runs with read-only autonomy against the same task. Their answers reach the architect as labelled, bounded briefing data. Proposal agents do not choose targets for generated work. The plan step's contract default remains authoritative for every admitted task.
+
+### Fleet authoring
+
+The fleet CLI provides five authoring and inspection operations:
+
+- `clio-coder fleet new <name> --from <builtin>` copies one of `build-review`, `build-test`, or `sdlc` into `.clio-coder/fleets/<name>.md`. The command requires a safe file stem and refuses to replace an existing contract.
+- `clio-coder fleet validate <name> [--json]` parses the contract, validates its graph and command bindings, resolves every agent, and compiles the execution plan. It creates no state directory, ledger row, reservation, worker, or receipt.
+- `clio-coder fleet graph <name> [--json]` renders the compiled waves with each step kind, agent or command, scope, and write boundary. Bounded loops also show their check and repair nodes beneath the loop identifier.
+- `clio-coder fleet commands init` discovers declared package scripts, just recipes, Makefile targets, and supported `pyproject.toml` script and tool entries. It writes a fully commented `.clio-coder/fleets/commands.yaml` draft. Uncommenting an entry confirms its exact argument vector, and an existing registry is never replaced.
+- `clio-coder fleet run <name> --resume <runId>` starts a new fleet run after replaying the successful, integrity-valid prefix recorded for the named prior fleet run.
+
+Run resumption is separate from `clio-coder fleet resume`, which continues to reopen dispatch admission after an operator drain. A resumable fleet run records its contract name, rendered plan hash, ordered step identifiers, variables, and receipt references in the durable fleet ledger. Runs started from the TUI through `/fleet run` use the same durable record and can be resumed by the authoring CLI. The new run records the prior fleet run as its resume parent. Replayed steps are reported as `replayed`, retain their original receipt or code-report references, and do not create new receipts.
+
+The current contract must compile to the same plan hash. A mismatch refuses before execution and prints the changed positions in the ordered step list. Variables must exactly match the original run. A different value, an added value, or an omitted value is refused even when the resulting task text would otherwise be similar.
 
 ### Per-step write boundaries (Contract v4)
 
@@ -428,7 +567,10 @@ commands:
     argv: ["npm", "run", "build"]
     timeoutMs: 600000
   commit:
-    argv: ["git", "commit", "-m"]
+    argv: ["git", "commit", "-m", "{{commitMessage}}"]
+    timeoutMs: 60000
+  acceptance:
+    argv: ["node", "{{path}}"]
     timeoutMs: 60000
 ```
 
@@ -439,6 +581,8 @@ Each command entry supports:
 - `env` (optional): Array of extra environment variable names to pass through on top of `FLEET_COMMAND_BASE_ENV` (`PATH`, `HOME`, `LANG`, `LC_ALL`, `TZ`, `TMPDIR`).
 - `description` (optional): Human-readable description.
 
+The whole-token `{{commitMessage}}` substitution is available to commit steps. The whole-token `{{path}}` substitution is available to version 5 gate commands. Each substitution becomes exactly one argv element and never passes through a shell.
+
 
 ## Measured route selection and agent automation
 
@@ -522,7 +666,7 @@ assignment failed, reports the reason on stderr, and records it in the
 assignment's `outcomeDetail`.
 
 Assignment status, attempt ids, and terminal run id are stored separately in
-`assignments.json` while each attempt keeps its own strict v15 receipt.
+`assignments.json` while each attempt keeps its own strict v19 receipt.
 Pipelines and batches await assignment terminals, so downstream stages consume
 the successful fallback output rather than an earlier failed attempt.
 
@@ -536,7 +680,7 @@ closed while a winner remains unapplied.
 
 ## Receipts
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 15`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
+Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
 include:
 
 - `node`: the fleet node the worker ran on (`id`, `kind`, `host`). The `node.id` explicitly identifies the worker process host executing the task, not the model host (which is represented by the `target` id). This behavior tracks issue #120.
@@ -547,11 +691,22 @@ include:
   approval kind, and the registry approval identity when supervised).
 - `briefing`: byte count and SHA-256 of the exact canonical parent briefing;
   the prose is not retained and is distinct from bounded project context.
+- `intent`: the normalized typed path, expected-output, and verification
+  declaration that admission sealed for the run.
+- `verification`: the existing evidence state and basis observed from worker
+  tool execution.
+- `hostVerification`: host-run status and the resolved check evidence, including
+  argv, cwd, exit code, duration, memo provenance, bounded output tail, and
+  optional artifact path.
+- `worktree`: task worktree path, branch, diff hash, requested application,
+  applied status, and an optional closed failure reason.
 - `steering`: ordered byte/hash/timestamp and acknowledgement provenance for
   successfully written steers; steering prose is never stored.
 - `outcomeCode`: the stable terminal classifier, including
   `worker_final_output_missing` when an otherwise successful worker exits
-  without a nonempty receipt-sealed final answer.
+  without a nonempty receipt-sealed final answer and
+  `host_verification_rejected` when a declared host check rejects the settled
+  tree. Both suppress automatic retry.
 - `routingIntent`, `routeDecision`, and `quality`: the normalized hard bounds,
   complete current-policy decision, exact execution role, route estimate and
   readiness evidence, and authenticated quality sources.
@@ -571,11 +726,14 @@ retained only as `state: "partial"` diagnostics and automatic retry is
 suppressed. Dispatch, monitor, ledger, receipt, terminal bus event, and retry
 policy all consume that same final classification.
 
-Receipt integrity and evidence verification are separate axes. Integrity says
+Receipt integrity, host verification, and evidence verification are separate axes. Integrity says
 that the sealed receipt matches its ledger envelope; evidence verification
 reports whether Clio observed an applicable validation tool (or marks the
-basis unknown/not applicable). A read-only Scout can therefore report `receipt_integrity=verified/v15/sha256` alongside
-`evidence_verification=not_applicable/read-only-agent`. Briefing provenance and
+basis unknown/not applicable). A read-only Scout can therefore report `receipt_integrity=verified/v19/sha256` alongside
+`evidence_verification=not_applicable/read-only-agent`. Host verification is
+rendered independently as `host_verification=verified|rejected|skipped|not_requested`.
+A host-executed successful check projects onto canonical validation grounding as
+authenticated validator evidence. Briefing provenance and
 bounded `project_context` provenance are also rendered independently; neither
 hash substitutes for the other.
 
@@ -658,15 +816,70 @@ hard block.
   renders `local`), gate badges (`gate reviewer c2`), reroute badges, live
   tool activity (names only; arguments never cross the worker stdout seam),
   and a per-worker context meter.
+- `Enter` on the selected Fleet Runs row opens its worker detail: the phase,
+  the running call with a redacted action descriptor (`bash running npm
+  test`), and the bounded tail of the worker's own prose. The default list
+  stays compact, so a fan-out of scouts costs one card each until an operator
+  opens one. Detail follows the cursor rather than pinning to a run.
+- The board and the transcript worker block read one projection
+  (`src/interactive/worker-progress.ts`), so they cannot disagree about what a
+  worker is saying or touching. It keeps 40 lines and 4096 bytes of tail, 8
+  distinct tool names, 4 recent actions, and accepts 16 KB of delta bytes per
+  250 ms; what the bounds refuse is counted and named on the card beside the
+  `/view dispatch:<runId>` deep link.
+- Action descriptors are composed where the arguments are trusted: the tool
+  registry's admission path, the Claude tool mapper, and the ACP update
+  mapper. Each reads a fixed verb vocabulary and a fixed argument-field
+  allowlist, scrubs credentials, strips escape sequences, and bounds the
+  result to 64 characters before it crosses the worker stdout seam. Raw
+  argument objects never cross at all.
+- Reasoning content is never displayed. The detail may name a `thinking`
+  phase and the usage facts the card already carries, never the text.
+- Settlement replaces the provisional tail with the sealed receipt's answer;
+  a run whose receipt cannot be read keeps its own last durable message.
 - The context meter renders the worker's last-message context occupancy
   against the model's context window: healthy below 80 percent, warn from 80,
   critical from 95.
 - `/fleet` opens Settings → Fleet: profiles (with the node pin), bindings,
   and read-only node rows (state, capacity, and last-seen). Running and
   retrying runs, with their node, live in the `Alt+W` Fleet Runs board.
+- `/fleet run <name> [--var k=v ...]` compiles the contract's plan and opens
+  the approval overlay before anything dispatches. The overlay lists the steps
+  grouped by wave, and for each step its kind, its agent and resolved target
+  (or its command id and the exact argv from `commands.yaml` for a code step),
+  its scope, and its declared write boundary, followed by the budget ceiling
+  the run would be admitted under. Enter dispatches the plan through the same
+  path `clio-coder fleet run` uses, so admission, autonomy, receipts, and the
+  durable ledger are identical. Esc cancels with nothing dispatched and nothing
+  written. A contract that fails preflight opens the same overlay with its
+  diagnostics and no accept key. A turn in flight refuses the command with a
+  notice rather than queueing it: an approved plan describes the workspace as
+  it stands.
+- A council is one question asked of several members, so its rows render as one
+  card rather than as three to five unrelated neighbours. On the `Alt+W` board the
+  members sit side by side, one column each, as long as every column keeps at
+  least 34 cells; below that the whole group stacks one member under another
+  rather than squeezing some columns and not others. Each column carries the
+  member label in its roster color (a member with no color takes the accent), the
+  target and model, the round, the status, and the same bounded answer tail the
+  run's own card would show. The synthesis run takes the full width under the
+  members, because it is the council's answer rather than one voice in it. A
+  council that ran several rounds still shows one column per member: each label
+  keeps its newest round, so the card describes the council rather than its
+  history.
+- The compact Fleet Runs island shows a council as one card naming the group, how
+  many members are seated, and which round they are on. The grid belongs to the
+  board, where there is width to read an answer in. `/share` is what moves a
+  council answer into the main agent's context; the card moves nothing.
+- Board rows a fleet plan dispatched carry a phase column naming the step's
+  wave index and step id (`w2 build`). A run that is not a fleet step renders
+  the column empty. The compact Fleet Runs island keeps its fixed width, so it
+  shows the column only when the row can still hold a readable agent label;
+  otherwise the phase appears on the expanded card.
 - The monitor tool reports the node and reroute lineage on `status`, `list`,
   and `collect`.
 - `clio-coder fleet status [--json]` shows the durable ledger view cross-process.
+- A worker permission escalation uses the `Worker escalation` consequence tier in operator presentation. The tier names the worker agent and run and describes where the one-shot answer returns. It does not approve the request, change the worker's inherited autonomy, or weaken the safety net; the existing worker escalation protocol remains the only resolution path.
 
 ## Speculation observer
 

package/docs/git-commit-provenance.md

@@ -49,11 +49,11 @@ Co-authored-by: Clio Coder <clio-coder@iowarp.ai>
 Existing human trailers stay in place. A Clio trailer already present in any
 letter case is respected rather than repeated, line endings are normalized only
 while attribution is enabled, and repeated processing is idempotent. When a directly relevant
-receipt-v15 digest passes integrity verification, Clio may additionally add the
+receipt-v19 digest passes integrity verification, Clio may additionally add the
 full digest:
 
 ```text
-Clio-Evidence: receipt-v15/sha256:<64-character digest>
+Clio-Evidence: receipt-v19/sha256:<64-character digest>
 ```
 
 Clio does not invent, shorten, or add an unrelated digest. The role trailers do

package/docs/glossary.md

@@ -28,7 +28,7 @@ This document defines the 45 core architectural concepts and terminology used th
 
 ### 6. Receipt
 - **Definition**: An immutable, cryptographically sealed record of a completed run containing full execution facts, tool telemetry, token accounting, validation grounding, and outcome codes.
-- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 15`).
+- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 19`).
 
 ### 7. Envelope
 - **Definition**: A bounded container enforcing byte-length limits and truncation indicators on a dynamic payload. Tool output carries shown and total byte counts plus a continuation fragment; a parent briefing carries byte count and SHA-256 content hash instead.

package/docs/installation-and-lifecycle.md

@@ -3,7 +3,7 @@
 Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.4). You can open it directly in any web browser to view details dynamically.
+> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.7). You can open it directly in any web browser to view details dynamically.
 
 ---
 
@@ -229,7 +229,7 @@ Upgrading from 0.3.1 to 0.3.3 is automated:
 clio-coder upgrade
 ```
 
-Key lifecycle and operational updates in v0.3.4:
+Key lifecycle and operational updates in v0.3.7:
 - Upgraded the underlying engine SDK libraries to 0.84.0 with signal-aware OAuth cancellation.
 - Hardened migration resilience: damaged `credentials.yaml` files no longer block upgrades when no renames are needed (#121); `--skip-migrations` is available as a recovery override.
 - Fullscreen TUI mode (`terminal.tuiMode`, `terminal.fullscreenScrollbar`) is available via Settings → Terminal (restart required). Adaptive presentation pacing is the live `terminal.smoothStreaming` setting; 0.3.3 defaults it to `off`, with conservative `auto` and explicit `on` available from the same section.