session-orchestrator 4.1.0 → 5.0.0

package/skills/wave-executor/SKILL.md

@@ -87,6 +87,8 @@ Before starting the first wave (Discovery role):
    - `persistence` (default: true), `enforcement` (default: warn), `isolation` (default: auto)
    - `agents-per-wave` (default: 6), `max-turns` (default: auto), `pencil` (default: null)
    
+   **Neither `agents-per-wave` nor `max-turns` carries its own default here.** The per-wave `agentCap` and `maxTurns` come from the RESOLVED SHAPE (`node scripts/session-shape.mjs --repo-root "$PWD" --session-type <session-type> [--profile <session-profile>] [--known-scope true|false]`, module `scripts/lib/session-shape.mjs`) — that is the one place a session mode becomes an execution shape. Session Config's `agents-per-wave` (with its per-type override, e.g. `6 (deep: 18)`) CLAMPS the shape's `agentCap`; `max-turns: auto` is expanded per type inside the shape, not in this file.
+   
    **Execution Config shortcut:** If the session-plan output contains an `### Execution Config` section, its execution-level fields (waves, agents-per-wave, isolation, enforcement, max-turns) take precedence over `$CONFIG`. Session-level fields (persistence, pencil) always come from `$CONFIG`. If the Execution Config section is missing, use `$CONFIG` alone.
 6. **Initialize session metrics** (if `persistence` enabled): Prepare a metrics tracking object for this session:
    - `session_id`: `<branch>-<YYYY-MM-DD>-<HHmm>` (HHmm from `started_at` — ensures uniqueness across multiple sessions per day)
@@ -119,70 +121,9 @@ Store this value for use throughout the session — it is needed by the simplifi
 
 ## Pre-Wave 1b: Initialize STATE.md
 
-> Skip this section entirely if `persistence: false`.
-
-Before dispatching Wave 1, write `<state-dir>/STATE.md` with YAML frontmatter and Markdown body:
-
-```yaml
----
-schema-version: 1
-session-type: feature|deep|housekeeping
-branch: <current branch>
-issues: [<issue numbers from plan>]
-started_at: <ISO 8601 timestamp with timezone>
-status: active
-current-wave: 0
-total-waves: <from session plan>
----
-```
-
-```markdown
-## Current Wave
-
-Wave 0 — Initializing
-
-## Wave History
-
-(none yet)
-
-## Deviations
-
-(none yet)
-```
-
-Create the `<state-dir>` directory if needed (`mkdir -p <state-dir>`) before writing. This file is the persistent state record — other skills and resumed sessions read it.
-
-#### Pre-Wave 1b Extension: Docs Tasks Persistence (A3 / #230)
-
-After writing the base STATE.md frontmatter above, conditionally persist the docs tasks block emitted by session-plan:
-
-**Condition:** BOTH of the following must be true:
-1. The session plan contains a `### Docs Tasks (machine-readable)` section with a YAML code block.
-2. `$CONFIG."docs-orchestrator".enabled` is `true`.
-
-If either condition is false → omit the `docs-tasks` field entirely. Do NOT write an empty key (`docs-tasks: []`). Absence means "no docs tasks planned this session" — downstream consumers (session-end Phase 3.2) treat absence the same as an empty list.
-
-When the condition is met, parse the YAML block from the session plan's `### Docs Tasks (machine-readable)` section and append the following field to the STATE.md YAML frontmatter (alongside the base fields above):
-
-```yaml
-docs-tasks:
-  - id: <task id from plan>
-    audience: <user|dev|vault>
-    target-pattern: <glob pattern from plan>
-    rationale: <rationale string from plan>
-    wave: <wave number the task is assigned to>
-    status: planned
-```
-
-Each entry's `status` is initialized to `planned`. session-end Phase 3.2 (Docs Verify) writes the terminal value per task: `ok` (diff is substantive), `partial` (diff region contains `<!-- REVIEW: source needed -->` markers), or `gap` (no matching diff). wave-executor does NOT perform intermediate status updates — `planned` remains until session-end runs.
+> Skip entirely if `persistence: false`. Otherwise, before dispatching Wave 1, write `<state-dir>/STATE.md` (YAML frontmatter + Markdown body), then VALIDATE `total-waves` against the resolved shape — do not skip this step, a plan whose wave count the shape does not produce must never be dispatched silently. Full template, the shape-mismatch AUQ procedure, and the Docs Tasks Persistence extension (A3 / #230): [references/wave-executor-state-init.md](references/wave-executor-state-init.md).
 
-> **Schema note:** `schema-version: 1` now includes the optional `docs-tasks` array. The field is backwards-compatible — its absence is a valid schema-version-1 STATE.md meaning "no docs tasks planned". Readers MUST treat a missing `docs-tasks` key identically to `docs-tasks: []`.
-
-> **Ownership clarification:** session-plan does NOT write STATE.md directly. The wave-executor owns ALL STATE.md writes — initialization here (Pre-Wave 1b) is the canonical write point for `docs-tasks`. session-plan only emits the source `### Docs Tasks (machine-readable)` block for the coordinator to consume. See `skills/_shared/state-ownership.md` for the full ownership matrix.
-
-> **Consumer cross-reference:** session-end reads `STATE.md` frontmatter's `docs-tasks` field (if present) during Phase 3.2 Docs Verify — see `skills/session-end/SKILL.md`. The field is also readable by the docs-writer agent if it needs to know which tasks were planned for the current session.
-
-> **Ownership:** STATE.md is owned by the wave-executor. Only the wave-executor writes to it (initialization + post-wave updates). session-end reads it for metrics extraction and sets `status: completed`. session-start reads it only for continuity checks (Phase 0.5). No other skill should write to STATE.md.
+**Read WHEN:** before the first wave dispatches, every session with `persistence: true`; the VALIDATE step must not be skipped.
 
 ## Wave Execution Loop
 
@@ -227,7 +168,7 @@ Claude Code's `Agent` tool with `isolation: "worktree"` changes `process.cwd()`
 
 **Rules for the coordinator (this is YOU during wave execution):**
 
-1. **After every Agent() dispatch** (before reading its output), call `restoreCoordinatorCwd()` from `scripts/lib/worktree.mjs`. `wave-loop.md § 2` makes this explicit.
+1. **After every Agent() dispatch** (before reading its output), call `restoreCoordinatorCwd()` from `scripts/lib/workspace.mjs`. `wave-loop.md § 2` makes this explicit.
 2. **Prefer absolute file paths** for Read/Edit/Write tool calls. A drifted CWD turns relative paths into silent cross-tree writes.
 3. **Before any Bash git command**, either `cd` inside a subshell (`cd /path && cmd`) or rely on `git -C /path <cmd>`. Do not assume CWD.
 4. **Verify at checkpoints** — when in doubt, run `git rev-parse --show-toplevel` to confirm which tree is currently active.
@@ -302,29 +243,44 @@ Cross-reference: PRD F2.1 / issue #501 / `docs/memory-proposal-flow.md` (coordin
 
 ## Session Type Behavior
 
-### Housekeeping Sessions
+### Housekeeping Sessions — the Maintenance Loop
+
+A housekeeping session is **ONE coordinator-direct wave**, not a shrunken multi-wave run: `node scripts/session-shape.mjs --repo-root "$PWD" --session-type housekeeping --no-event` resolves to `totalWaves: 1` with that wave's `coordinatorDirect: true` and `writes: true`. "Coordinator-direct" means **no wave-executor dispatch loop** — it does not mean zero subagents (`/evolve dialectic` dispatches the read-only `dialectic-deriver`).
+
+**Ordered default scope — the maintenance loop.** Run it in this order, before the session's selected issues:
+
+| # | Run | Gate | Artefact that proves it ran |
+|---|---|---|---|
+| 1 | `claude-md-drift-check` | unconditional | checker JSON (`errors`/`warnings` counts) |
+| 2 | expired-learnings sweep | unconditional | `orchestrator.learnings.sweep_applied` |
+| 3 | `/evolve analyze` | AUQ-gated (the operator approves the proposed learnings) | `orchestrator.evolve.completed` |
+| 4 | `/reconcile` | AUQ-gated (rule proposals are never applied unasked) | `orchestrator.reconcile.completed` with `dry_run: false` |
+| 5 | `/evolve dialectic` | AUQ-gated (the derived thesis is presented, not committed) | `orchestrator.dialectic.completed` |
+| 6 | `/memory-cleanup` | AUQ-gated (deletions are operator-approved) | `orchestrator.memory.cleanup_completed` |
 
-Housekeeping sessions use a simplified single-wave execution model instead of the multi-wave role-based dispatch:
+The session-start probe `maintenance-due` (`scripts/lib/maintenance-due-banner.mjs`) says which of these are DUE for this repo; a run that is not due may be skipped, and the skip is reported. An AUQ-gated run the operator declines is reported as declined — never as done. **Absence of the artefact event is the only evidence that counts**: a run claimed in prose without its event is not a run (`.claude/rules/verification-before-completion.md`).
+
+Then the mechanics:
 
 1. Initialize STATE.md as normal (`session-type: housekeeping`, `total-waves: 1`)
-2. Do NOT create `wave-scope.json` — scope enforcement is not needed for low-risk housekeeping tasks
-3. Dispatch tasks serially with 1-2 agents per task
+2. Do NOT create `wave-scope.json` — there is no agent fan-out to constrain; the coordinator's own edits stay governed by its `coordinator.json` record
+3. Execute the maintenance loop above, then the session's selected issues, serially as coordinator actions
 4. Run Baseline quality checks after all tasks complete (not between tasks)
 5. Skip session-reviewer dispatch — housekeeping changes are low-risk
 6. Do NOT update STATE.md to `status: completed` — that write is reserved for session-end per state-ownership contract (`skills/_shared/state-ownership.md`). Leave `status: active`.
 7. Proceed directly to session-end (`/close`)
 
-Focus: git cleanup, SSOT refresh, CI fixes, branch merges, documentation.
+Beyond the loop: git cleanup, SSOT refresh, CI fixes, branch merges, documentation.
 End with a single commit summarizing all housekeeping work.
 
 ### Feature Sessions
-- Full wave execution (5 roles mapped to configured wave count)
-- 4-6 agents per wave (read from Session Config)
+- **3 waves** (Impl-Core → Impl-Polish+Quality → Finalization) with **no Discovery wave** — read them from the shape, not from this file: `node scripts/session-shape.mjs --repo-root "$PWD" --session-type feature --no-event`
+- Per-wave agent caps come from the shape's `agentCap` (the shape caps a feature wave at 4), clamped by Session Config `agents-per-wave`
 - Balance between implementation speed and quality
 
 ### Deep Sessions
-- Full wave execution (5 roles mapped to configured wave count)
-- Up to 10-18 agents per wave (read from Session Config)
+- **5 waves** from the shape (`--session-type deep`); the **Discovery wave is conditional** — pass `--known-scope true` when the scope is already established and the shape drops Discovery, leaving 4 waves
+- Per-wave agent caps come from the shape's `agentCap`, clamped by Session Config `agents-per-wave` with its per-type override (this repo: `agents-per-wave: 6 (deep: 18)`)
 - Extra emphasis on Discovery role and Quality role
 - May include security audits, performance profiling, architecture refactoring
 
@@ -332,9 +288,9 @@ End with a single commit summarizing all housekeeping work.
 
 Not a fourth session type — a PROFILE over `session-type: deep`, resolved from the `/session ultradeep` argument alias (`commands/session.md`). Everything below applies only when STATE.md frontmatter carries `session-profile: ultradeep`; every other behaviour in this skill is unchanged, because downstream still reads `deep`. Full spec — wave table, mandatory artefacts, cost model: `docs/prd/2026-09-06-ultradeep-session-profile.md`.
 
-- **7 waves**, per `skills/session-plan/SKILL.md` § Role-to-Wave Mapping: Research+Code-Discovery → Synthesis-Gate → Impl-Core → Impl-Polish → Review-Panel → Quality → Release/Finalization.
+- **The wave count and the wave roles come from the shape**, not from this file: `node scripts/session-shape.mjs --repo-root "$PWD" --session-type deep --profile ultradeep --no-event` returns `totalWaves: 7` (Research+Code-Discovery → Synthesis-Gate → Impl-Core → Impl-Polish → Review-Panel → Quality → Release/Finalization) and reports `wavesConfigHonored: false` with the ignored Session Config `waves` value — the profile OWNS its wave count. Role narrative: `skills/session-plan/SKILL.md` § Role-to-Wave Mapping.
 - **Wave 2 is coordinator-direct and dispatches ZERO agents.** Make NO `Agent()` call in this wave. The coordinator consolidates wave 1 into `docs/audits/<YYYY-MM-DD>-<slug>.md`, updates STATE.md, and asks ONE **blocking** `AskUserQuestion` (confirm scope / narrow / abort) per `.claude/rules/ask-via-tool.md`. Wave 3 does not start until that question is answered — this is the one gate the profile exists for, so a silent "no tasks, skip it" is a defect, not an optimisation (`skills/session-plan/SKILL.md` § Empty roles, coordinator-direct exception).
-- **`max-turns` per ROLE, not per session:** 40 for Research/Code-Discovery (wave 1), 25 for the implementing waves (3, 4, and the writing part of 6/7), 15 for Release/Finalization. Set it on the dispatch; the Session Config `max-turns` value is the fallback when a role has no entry here.
+- **`max-turns` is per ROLE, and the numbers live in the shape:** take each wave's value from `waves[].maxTurns` in the shape output above (the Research, implementing and Release/Finalization figures are produced there, not restated here). Set it on the dispatch; a wave whose `maxTurns` is `null` is coordinator-direct and dispatches nothing.
 - **Web tools are role-bound.** Research agents in wave 1 receive `WebSearch` and `WebFetch`. **No write-capable agent may receive them** — not in wave 1's Code-Discovery half, and not in any later wave. The grant follows the READ-ONLY property, so the pairing "has Write/Edit" + "has WebSearch/WebFetch" must never occur in a single dispatch. Research findings carry URL + retrieval date, the web analogue of the PSA-006 evidence rule (`.claude/rules/parallel-sessions.md`).
 - **Budgets are not implemented.** The PRD's `ultradeep.max-*` block (§ 7) is deferred until three runs have been measured (HR-105: no threshold without a firing rate). Nothing reads such a key today — do not invent one, and do not gate a wave on it.
 
@@ -412,58 +368,7 @@ The diff JSON block (`{ new_errors, resolved_errors, baseline_count, current_cou
 
 ## Inter-Wave Quality-Gate (with Auto-Fix Loop — #521)
 
-After each wave, run the Quality-Gate. If `verification-auto-fix.enabled: true`
-in Session Config, the gate uses `runQualityGateWithRetry()` from
-`scripts/lib/quality-gate.mjs` which dispatches up to `max-retries` (default 2)
-fixer-agent dispatches on failure.
-
-**Quality-wave Full-Gate mandate (#724 C6):** the inter-wave gate following the **Quality wave** is ALWAYS the Full Gate (typecheck + test + lint) — never the cached Incremental short-circuit. The wave-executor threads the wave's `waveRole` into `shouldSkipIncremental` (see `wave-loop.md § Baseline cache check`); when `waveRole === 'Quality'` the cache is bypassed mechanically, so a valid cache or a narrow diff cannot downgrade the Quality-wave close-safety gate. See `skills/quality-gates/SKILL.md § Variant 3: Full Gate` — its dual consumers are session-end (Phase 2) and the Quality wave, and its Baseline-Cache invariant records that both are un-skippable.
-
-### Invocation
-
-```javascript
-import { runQualityGateWithRetry } from '../../scripts/lib/quality-gate.mjs';
-
-const result = await runQualityGateWithRetry({
-  maxRetries: config['verification-auto-fix']?.['max-retries'] ?? 2,
-  repoRoot: process.cwd(),
-  dispatchFixer: async ({ failures, correctiveContext, changedFiles }) => {
-    // Coordinator dispatches a code-implementer fixer subagent here with:
-    //   - failures (gate + output)
-    //   - correctiveContext (from .orchestrator/current-session.json)
-    //   - changedFiles (since last green SHA)
-    // Subagent's task: fix the failing gate, never broaden scope.
-    await dispatchFixerSubagent({ failures, correctiveContext, changedFiles });
-  },
-});
-```
-
-### Decision flow
-
-- `result.ok === true` → Wave green, proceed to next wave or session-end.
-- `result.ok === false` → Hard abort.
-  - quality-gate.mjs writes `.orchestrator/metrics/verification-failures/<ts>.json` (diagnostics bundle — automatic, redacted per `redactDiagnosticsBundle()`).
-  - **Coordinator** (not fixer-subagent) appends a deviation entry to STATE.md via `appendDeviationOnDisk()` — see `wave-loop.md` § STATE.md Deviation — Auto-Fix Result.
-  - Wave execution is blocked; operator must manually fix or disable auto-fix.
-- `result.attempts > 1` → **Coordinator** logs a Deviation in STATE.md via `appendDeviationOnDisk()`: `auto-fix used N retries to clear Wave <wave>`.
-
-### Skip Conditions
-
-- `verification-auto-fix.enabled: false` (default) → fall back to single-shot
-  quality-gate, abort on first failure (current behavior preserved per PRD § 3
-  Gherkin negative path).
-- `verification-auto-fix.max-retries: 0` → equivalent to disabled.
-
-### Anti-pattern (BE-012 awareness)
-
-The fixer-agent prompt MUST include a reminder of `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention"
-"test-the-mock" anti-pattern. A fix that makes tests green by mocking out the
-real failure is a regression vector. The fixer prompt should explicitly say:
-"Do NOT change test mocks to make tests pass. Fix the actual code defect."
-
-### Heartbeat cadence at inter-wave checkpoints (#590-3)
-
-After each quality-gate PASS, the coordinator refreshes the session-lock heartbeat via the post-wave STATE.md step. See `wave-loop.md § 3a. Post-Wave: Update STATE.md` — step 5 contains the `updateHeartbeat` instruction and best-effort framing. The `sessionId` passed to `updateHeartbeat` is the session identifier established by session-start Phase 1.2 `acquire()` and stored in `.orchestrator/session.lock` (its `session_id` field); it matches the STATE.md frontmatter `session:` field written during Pre-Wave 1b initialization.
+> **Reference:** See [references/wave-executor-quality-gate.md](references/wave-executor-quality-gate.md) for the invocation, decision flow, skip conditions, the BE-012 test-the-mock anti-pattern reminder, the Quality-wave Full-Gate mandate (#724 C6), and the inter-wave heartbeat cadence (#590-3). Read after each wave completes, before proceeding to the next wave or session-end.
 
 ## Agent-Status Telemetry (#565)
 

package/skills/wave-executor/circuit-breaker.md

@@ -4,7 +4,7 @@ Sub-reference for the wave-executor skill. Defines safety mechanisms for agent e
 
 ## Circuit Breaker
 
-1. **MaxTurns enforcement**: Read `max-turns` from Session Config (default: auto — housekeeping=8, feature=15, deep=25). Include this instruction in EVERY agent prompt:
+1. **MaxTurns enforcement**: Read the wave's `maxTurns` from the resolved shape (`scripts/session-shape.mjs` / `scripts/lib/session-shape.mjs`; a Session Config `max-turns: auto` is expanded per session type THERE, not here). Include this instruction in EVERY agent prompt:
    ```
    TURN LIMIT: You have a maximum of [N] turns. If you cannot complete within [N] turns, report PARTIAL with what you accomplished and what remains.
    ```
@@ -93,6 +93,8 @@ The function never throws — it always returns a result object. Treat `skipped:
    | 3–4 | feature / deep | `worktree` |
    | ≥ 5 | any | `worktree` |
 
+   `sessionType` for `resolveIsolation` comes from the resolved shape (the same `session-type` the shape was resolved for), not from a value re-derived at dispatch time.
+
    Rationale: the verified learning `coordinator-over-worktree-on-shared-files` (confidence 0.75) shows that small waves on partitioned scopes merge cleaner when run in-place. Two consecutive deep-session regressions (2026-04-20 07:30, 09:00) were worktree base-ref staleness on ≤2-agent waves editing the same SKILL.md. Graduated default makes worktree the tool for parallelism, not the default tax on every wave.
 
 2. **Enforcement auto-promote (#194)**: Call `resolveEnforcement({ isolation, configEnforcement })` from the same module. When isolation resolves to `none` and the user has not explicitly set `configEnforcement: 'off'`, enforcement auto-promotes from `warn` → `strict`. Worktrees provide filesystem-level isolation; in-place dispatch relies on the scope hook as the only barrier — it must be hard, not informational. Write the resolved value into `wave-scope.json` `enforcement`.

package/skills/wave-executor/references/wave-executor-quality-gate.md

@@ -0,0 +1,61 @@
+# Wave Executor — Inter-Wave Quality-Gate (Auto-Fix Loop, #521)
+
+> Reference of the wave-executor skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`, `wave-loop.md` → `../wave-loop.md`, `circuit-breaker.md` → `../circuit-breaker.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+> Read after each wave completes, before proceeding to the next wave or session-end — see `../SKILL.md` § Inter-Wave Quality-Gate for the pointer.
+
+## Inter-Wave Quality-Gate (with Auto-Fix Loop — #521)
+
+After each wave, run the Quality-Gate. If `verification-auto-fix.enabled: true`
+in Session Config, the gate uses `runQualityGateWithRetry()` from
+`scripts/lib/quality-gate.mjs` which dispatches up to `max-retries` (default 2)
+fixer-agent dispatches on failure.
+
+**Quality-wave Full-Gate mandate (#724 C6):** the inter-wave gate following the **Quality wave** is ALWAYS the Full Gate (typecheck + test + lint) — never the cached Incremental short-circuit. The wave-executor threads the wave's `waveRole` into `shouldSkipIncremental` (see `wave-loop.md § Baseline cache check`); when `waveRole === 'Quality'` the cache is bypassed mechanically, so a valid cache or a narrow diff cannot downgrade the Quality-wave close-safety gate. See `skills/quality-gates/SKILL.md § Variant 3: Full Gate` — its dual consumers are session-end (Phase 2) and the Quality wave, and its Baseline-Cache invariant records that both are un-skippable.
+
+### Invocation
+
+```javascript
+import { runQualityGateWithRetry } from '../../scripts/lib/quality-gate.mjs';
+
+const result = await runQualityGateWithRetry({
+  maxRetries: config['verification-auto-fix']?.['max-retries'] ?? 2,
+  repoRoot: process.cwd(),
+  dispatchFixer: async ({ failures, correctiveContext, changedFiles }) => {
+    // Coordinator dispatches a code-implementer fixer subagent here with:
+    //   - failures (gate + output)
+    //   - correctiveContext (from .orchestrator/current-session.json)
+    //   - changedFiles (since last green SHA)
+    // Subagent's task: fix the failing gate, never broaden scope.
+    await dispatchFixerSubagent({ failures, correctiveContext, changedFiles });
+  },
+});
+```
+
+### Decision flow
+
+- `result.ok === true` → Wave green, proceed to next wave or session-end.
+- `result.ok === false` → Hard abort.
+  - quality-gate.mjs writes `.orchestrator/metrics/verification-failures/<ts>.json` (diagnostics bundle — automatic, redacted per `redactDiagnosticsBundle()`).
+  - **Coordinator** (not fixer-subagent) appends a deviation entry to STATE.md via `appendDeviationOnDisk()` — see `wave-loop.md` § STATE.md Deviation — Auto-Fix Result.
+  - Wave execution is blocked; operator must manually fix or disable auto-fix.
+- `result.attempts > 1` → **Coordinator** logs a Deviation in STATE.md via `appendDeviationOnDisk()`: `auto-fix used N retries to clear Wave <wave>`.
+
+### Skip Conditions
+
+- `verification-auto-fix.enabled: false` (default) → fall back to single-shot
+  quality-gate, abort on first failure (current behavior preserved per PRD § 3
+  Gherkin negative path).
+- `verification-auto-fix.max-retries: 0` → equivalent to disabled.
+
+### Anti-pattern (BE-012 awareness)
+
+The fixer-agent prompt MUST include a reminder of `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention"
+"test-the-mock" anti-pattern. A fix that makes tests green by mocking out the
+real failure is a regression vector. The fixer prompt should explicitly say:
+"Do NOT change test mocks to make tests pass. Fix the actual code defect."
+
+### Heartbeat cadence at inter-wave checkpoints (#590-3)
+
+After each quality-gate PASS, the coordinator refreshes the session-lock heartbeat via the post-wave STATE.md step. See `wave-loop.md § 3a. Post-Wave: Update STATE.md` — step 5 contains the `updateHeartbeat` instruction and best-effort framing. The `sessionId` passed to `updateHeartbeat` is the session identifier established by session-start Phase 1.2 `acquire()` and stored in `.orchestrator/session.lock` (its `session_id` field); it matches the STATE.md frontmatter `session:` field written during Pre-Wave 1b initialization.
+

package/skills/wave-executor/references/wave-executor-state-init.md

@@ -0,0 +1,86 @@
+# Wave Executor — STATE.md Initialization (Pre-Wave 1b)
+
+> Reference of the wave-executor skill, split out of `SKILL.md` (#1246). Body moved **byte-identical**; only this header is new.
+> **Sibling-file paths inside this body are relative to the parent directory, not to `references/`**: `SKILL.md` → `../SKILL.md`, `wave-loop.md` → `../wave-loop.md`, `circuit-breaker.md` → `../circuit-breaker.md`. They were deliberately NOT rewritten, so the moved bytes stay verifiable against the pre-split file.
+> Read at Pre-Wave 1b, before dispatching Wave 1 — see `../SKILL.md` § Pre-Wave 1b for the pointer.
+
+## Pre-Wave 1b: Initialize STATE.md
+
+> Skip this section entirely if `persistence: false`.
+
+Before dispatching Wave 1, write `<state-dir>/STATE.md` with YAML frontmatter and Markdown body:
+
+```yaml
+---
+schema-version: 1
+session-type: feature|deep|housekeeping
+branch: <current branch>
+issues: [<issue numbers from plan>]
+started_at: <ISO 8601 timestamp with timezone>
+status: active
+current-wave: 0
+total-waves: <from session plan>
+---
+```
+
+```markdown
+## Current Wave
+
+Wave 0 — Initializing
+
+## Wave History
+
+(none yet)
+
+## Deviations
+
+(none yet)
+```
+
+Create the `<state-dir>` directory if needed (`mkdir -p <state-dir>`) before writing. This file is the persistent state record — other skills and resumed sessions read it.
+
+**Then VALIDATE `total-waves` against the resolved shape — do not skip this.** A plan whose wave count the shape does not produce must never be dispatched silently:
+
+```bash
+node scripts/session-shape.mjs --repo-root "$PWD" \
+  --session-type <session-type> [--profile <session-profile>] [--known-scope true|false] \
+  --no-event | jq .totalWaves
+```
+
+`--no-event` is used HERE because the plan-time run already recorded `orchestrator.session.shape_resolved` — this is a re-read, not a second resolution. Compare the printed number with the plan's wave count (the value just written to `total-waves`):
+
+- **Equal** → continue to Wave 1.
+- **Mismatch** → STOP. Surface it via `AskUserQuestion` per `.claude/rules/ask-via-tool.md`, with the shape's number and the plan's number both in the option descriptions: **re-plan to the shape (Recommended)** — rebuild the wave plan at the shape's wave count, the only outcome that keeps STATE.md, the ledger and the dispatch loop describing the same session — versus **proceed with a logged Deviation**, which requires appending the divergence to STATE.md `## Deviations` (`appendDeviationOnDisk()` from `scripts/lib/state-md.mjs`) before the first dispatch.
+
+#### Pre-Wave 1b Extension: Docs Tasks Persistence (A3 / #230)
+
+After writing the base STATE.md frontmatter above, conditionally persist the docs tasks block emitted by session-plan:
+
+**Condition:** BOTH of the following must be true:
+1. The session plan contains a `### Docs Tasks (machine-readable)` section with a YAML code block.
+2. `$CONFIG."docs-orchestrator".enabled` is `true`.
+
+If either condition is false → omit the `docs-tasks` field entirely. Do NOT write an empty key (`docs-tasks: []`). Absence means "no docs tasks planned this session" — downstream consumers (session-end Phase 3.2) treat absence the same as an empty list.
+
+When the condition is met, parse the YAML block from the session plan's `### Docs Tasks (machine-readable)` section and append the following field to the STATE.md YAML frontmatter (alongside the base fields above):
+
+```yaml
+docs-tasks:
+  - id: <task id from plan>
+    audience: <user|dev|vault>
+    target-pattern: <glob pattern from plan>
+    rationale: <rationale string from plan>
+    wave: <wave number the task is assigned to>
+    status: planned
+```
+
+Each entry's `status` is initialized to `planned`. session-end Phase 3.2 (Docs Verify) writes the terminal value per task: `ok` (diff is substantive), `partial` (diff region contains `<!-- REVIEW: source needed -->` markers), or `gap` (no matching diff). wave-executor does NOT perform intermediate status updates — `planned` remains until session-end runs.
+
+> **Schema note:** `schema-version: 1` now includes the optional `docs-tasks` array. The field is backwards-compatible — its absence is a valid schema-version-1 STATE.md meaning "no docs tasks planned". Readers MUST treat a missing `docs-tasks` key identically to `docs-tasks: []`.
+
+> **Ownership clarification:** session-plan does NOT write STATE.md directly. The wave-executor owns ALL STATE.md writes — initialization here (Pre-Wave 1b) is the canonical write point for `docs-tasks`. session-plan only emits the source `### Docs Tasks (machine-readable)` block for the coordinator to consume. See `skills/_shared/state-ownership.md` for the full ownership matrix.
+
+> **Consumer cross-reference:** session-end reads `STATE.md` frontmatter's `docs-tasks` field (if present) during Phase 3.2 Docs Verify — see `skills/session-end/SKILL.md`. The field is also readable by the docs-writer agent if it needs to know which tasks were planned for the current session.
+
+> **Ownership:** STATE.md is owned by the wave-executor. Only the wave-executor writes to it (initialization + post-wave updates). session-end reads it for metrics extraction and sets `status: completed`. session-start reads it only for continuity checks (Phase 0.5). No other skill should write to STATE.md.
+

package/skills/wave-executor/references/wave-loop-dispatch.md

@@ -113,7 +113,7 @@ When `worker-pool.enabled: true` in Session Config, dispatch via `runWavePool()`
 
 Use the **Agent tool** to dispatch this wave's agents. **`run_in_background: true` is the PLATFORM DEFAULT for wave dispatch, not a deviation of ours** — since Claude Code **2.1.232**, non-teammate agent spawns default to background in interactive sessions. Our own measurement 2026-08-22 (v2.1.239) is why that default is the right one for a wave: under blocking dispatch the coordinator was 143 s incapable of acting between an agent's mid-run escalation and its own next turn — escalation latency equals the batch's remaining runtime. Background dispatch returns turns to the coordinator between agent completions; a running agent received a queued message mid-run and answered ~9 min before its final report.
 
-Dispatch in **SMALL BATCHES of 3–4 Agent() calls per message** (cumulative up to the wave's `agents-per-wave` cap). Large single-message fan-outs (>4 Agent() calls in one message) remain **FORBIDDEN** — fleet evidence (conf 1.0, 5 sessions) shows they drop Agent() calls SILENTLY (the coordinator receives fewer results than it dispatched, with no error), whereas serial / small-batch dispatch held 13/13 and 8/8. That evidence PREDATES backgrounding and is untouched by it; what backgrounding changes is the *cost* of batching, which is now near zero — a background batch returns its launch acks immediately, so batches no longer serialize the wave. Dispatch a batch, let its acks return, then dispatch the next, until every planned agent is started; then run **Started-Set Verification** below. See `docs/specs/2026-07-02-fleet-mining-followup-grill.md` (C4) for the batching-policy rationale. The `worker-pool.enabled: true` path (above) is the mechanised opt-in alternative to manual batching.
+Dispatch in **SMALL BATCHES of 3–4 Agent() calls per message** (cumulative up to the wave's `agents-per-wave` cap). Large single-message fan-outs (>4 Agent() calls in one message) remain **FORBIDDEN** — fleet evidence (conf 1.0, 5 sessions) shows they drop Agent() calls SILENTLY (the coordinator receives fewer results than it dispatched, with no error), whereas serial / small-batch dispatch held 13/13 and 8/8. That evidence PREDATES backgrounding and is untouched by it; what backgrounding changes is the *cost* of batching, which is now near zero — a background batch returns its launch acks immediately, so batches no longer serialize the wave. Dispatch a batch, let its acks return, then dispatch the next, until every planned agent is started; then run **Started-Set Verification** below. The archived, private spec `docs/specs/2026-07-02-fleet-mining-followup-grill.md` (C4) records the batching-policy rationale. The `worker-pool.enabled: true` path (above) is the mechanised opt-in alternative to manual batching. <!-- path-check: historical -->
 
 **What is NOT the reason for 3–4 (platform caps, as of Claude Code 2.1.232).** The batch size defends against the SILENT DROP measured above. It is not, and never was, a workaround for a platform concurrency limit — and the upstream numbers no longer permit reading it as one: **2.1.217** set the concurrent-subagent cap to **20** (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`), **2.1.219** set subagent nesting depth to **3**, **2.1.224** REMOVED the former 200-spawn-per-session cap, and **2.1.232** made background the spawn default (above). So neither 3–4, nor `agents-per-wave: 6`, nor `deep: 18` sits anywhere near a platform ceiling; the only ceiling a wave can actually reach is the concurrency cap of 20, and only through the worker-pool `maxParallel` path. The rule stays at 3–4 because the drop evidence is about how many `Agent()` calls survive ONE assistant message — a question no version bump has addressed. **Revisit-Trigger:** a measurement showing a >4-call single message delivering 100% of its calls. A raised cap is not that measurement. Version provenance: `docs/audits/2026-09-06-360-audit/w1/d9-claude-code-fable.md` (FA-6, 2026-09-06).
 
@@ -123,6 +123,8 @@ After resolving `isolation`, compute the wave's enforcement via `resolveEnforcem
 
 Before dispatching, verify the wave's agent count does not exceed `$CONFIG.agents-per-wave` — if it does, warn the user and request plan revision.
 
+`sessionType` for `resolveIsolation` is the session type the shape was resolved for, and the wave's `coordinatorDirect` and `writes` flags are READ FROM the shape's wave entry (`scripts/session-shape.mjs` → `waves[]`) rather than inferred from the role name. The dispatch-side marker is unchanged: the coordinator still keys the table below on `coordinator-direct: true` in the wave-plan item — the shape says which waves are expected to carry it, the plan item is what the coordinator acts on.
+
 **Coordinator-direct waves (`coordinator-direct: true`) dispatch NOTHING — and that is not a silent drop.** Keyed on the marker, never on a profile name (`skills/session-plan/SKILL.md` keys its matching empty-role exception the same way), so any future coordinator-direct wave inherits this:
 
 | Step | Behaviour when the wave-plan item carries `coordinator-direct: true` |
@@ -480,7 +482,7 @@ After `wave-scope.json` is written for this wave and before assembling the `Agen
 
 **Gate:** runs when `.claude/rules/` exists. When it does not, the CLI prints nothing and exits 0 — zero behaviour change. This step never blocks dispatch: any non-zero exit or empty output means "inject nothing, continue" (same best-effort framing as Pre-Dispatch Grounding Injection above).
 
-**Per-wave scoping (not per-agent):** the rule set is computed ONCE per wave from the wave's `allowedPaths` union (the same `wave-scope.json` source used elsewhere), not per agent. The CLI resolves `scopePaths` from `allowedPaths`, `mode` from the `session-type:` frontmatter in `.claude/STATE.md`, and `hostClass` from `.orchestrator/host.json` — all overridable, all degrading to "no gating" when unreadable.
+**Per-wave scoping (not per-agent):** the rule set is computed ONCE per wave from the wave's `allowedPaths` union (the same `wave-scope.json` source used elsewhere), not per agent. The CLI resolves `scopePaths` from `allowedPaths`, `mode` from the `session-type:` frontmatter in the active harness's `STATE.md`, and `hostClass` from `.orchestrator/host.json` — all overridable, all degrading to "no gating" when unreadable. Default state and scope paths resolve independently: state-directory override first, then active-harness and legacy fallback.
 
 **Invocation:** once per wave, run from the repo root and capture stdout as `$RULES_BLOCK`:
 
@@ -551,6 +553,14 @@ Marker line plus fenced block, in that order: `hooks/pre-task-scope-disjoint.mjs
 
 > **Registration note.** That hook was armed in `hooks/hooks.json` on 2026-08-14, after a green Full Gate. Its `PreToolUse` matcher is **`Agent`** — measured over 12 archived transcripts of this repo, `Agent` accounts for 147 of 147 dispatch `tool_use` blocks. A `Task` matcher would hit the unrelated todo family (`TaskCreate`/`TaskUpdate`/`TaskGet`/…) and never once fire on a dispatch: armed and inert, the failure mode that reads as done. It is deliberately absent from `hooks-codex.json` / `hooks-cursor.json` / `hooks-pi.json` — those platforms have no `Agent` dispatch tool, so the asymmetry is registered in `DOCUMENTED_ASYMMETRIES` rather than papered over with a matcher that can never fire.
 
+**Scope-echo line (#1092).** Immediately AFTER the fenced `FILE-SCOPE` block, append one more line — the receive-side counterpart of the hook's send-side `scope_checked` record. Get it from the CLI, never hand-typed:
+
+```bash
+node scripts/lib/scope-echo.mjs --scope-file "$AGENT_FILESCOPE_JSON" --instruction
+```
+
+It prints exactly one line (`renderScopeEchoInstruction` in `scripts/lib/scope-echo.mjs`), naming the `scopeDigest` of that agent's own scope file: `End your final report with the line: SCOPE-DIGEST: <8-hex>`. Append it verbatim. It prints NOTHING when the scope file is empty, missing or unreadable — Discovery waves therefore inject nothing here, exactly as they inject no `FILE-SCOPE` block. The post-wave comparison is `wave-loop-review.md` step 3d-bis; what the echo does and does not prove is stated there.
+
 #### Structured Reasoning (STATE:/PLAN:) — opt-in via `reasoning-output: true` (#79)
 
 When `$CONFIG.reasoning-output` is `true`, append the following block to every agent prompt. The pattern is adapted from the BitGN PAC Agent's Soft-SGR: short structured transparency lines before tool invocations, without forcing structured output. Leave the block OUT when the flag is `false` (default) — this preserves exact legacy prompt behavior.

package/skills/wave-executor/references/wave-loop-review.md

@@ -9,7 +9,7 @@
 **Step 2.0 — Restore coordinator CWD (#219):** BEFORE reading any agent output or running any quality check, restore the coordinator's working directory. Claude Code's `Agent` tool with `isolation: "worktree"` `chdir()`s into each worktree internally and does NOT restore it on agent return. Subsequent Edit/Write/Bash calls would silently route to whichever worktree's tree CWD last drifted into.
 
 ```js
-import { restoreCoordinatorCwd } from '$PLUGIN_ROOT/scripts/lib/worktree.mjs';
+import { restoreCoordinatorCwd } from '$PLUGIN_ROOT/scripts/lib/workspace.mjs';
 
 const cwd = await restoreCoordinatorCwd();
 if (cwd.restored) {
@@ -119,6 +119,19 @@ Log every non-`pass` result as an event to `.orchestrator/metrics/events.jsonl`
 
    Cross-reference `.claude/rules/verification-before-completion.md` § VBC-004 Exception 2: a subagent's `STATUS: done` is a claim that needs its own verification — this step is that verification for the file-write side effect. `$WAVE_PREDISPATCH_HEAD` is the HEAD snapshot captured before this wave dispatched (same snapshot used by `### 3c. File-level grounding`). When `persistence: false` (no STATE.md), still perform the check and surface any violation in the wave progress update; only the deviation-write is skipped.
 
+3d-bis. **Scope-echo check (#1092)** (per agent, INFORMATIONAL — never blocks): the send-side `orchestrator.wave_dispatch.scope_checked` record says what the guard saw in the prompt the coordinator handed to the dispatch tool; nothing observes the receive side. This step collects the one signal that is available — the agent's own echo of the digest injected in `wave-loop-dispatch.md` § Pre-Dispatch: File-Scope Injection.
+
+   For each agent that reported, write its final report text to a file and run:
+
+   ```bash
+   node scripts/lib/scope-echo.mjs --scope-file "<state-dir>/filescopes/wave-<N>/<agent-id>.json" \
+     --report-file "<report.txt>" --wave <N> --agent-id "<agent-id>" --emit
+   ```
+
+   `checkScopeEcho` prints the verdict as JSON and `--emit` appends one `orchestrator.wave_dispatch.scope_echo_checked` record (payload: `docs/events-schema.md`; counts, digests and closed enums only — no path, no prompt text). `match: false` or `echoed: false` is logged in the wave progress update as `scope-echo: <agent> missing|mismatch` and changes NOTHING else — no re-dispatch, no deviation write, no gate.
+
+   **What it proves:** the agent's final report carried the digest the coordinator handed it, i.e. the injected line survived the round trip into the agent's context and back. **What it does not prove:** that the model read the `FILE-SCOPE` block, understood it, or obeyed it — the digest is in the prompt, so it can be copied without ever looking at the paths (BV-004 ceiling, `docs/scope-collision-guard.md` § 4.2). Obedience is still measured at write time (`enforce-scope.mjs`) and by the W5 verification pass.
+
 3e. **Collect Open Questions** (Close Handover-Alignment-Gate, PRD 2026-07-07): scan every completed agent's report from this wave for an optional `OPEN-QUESTIONS:` line (see the report-line convention in `wave-loop-dispatch.md` `#### Agent-Type Resolution` — an agent MAY emit `OPEN-QUESTIONS: <question> | context: <...> | candidates: <opt A / opt B>`; most agents emit none). For each such line found:
 
    - Parse the question text (portion before the first ` | `).
@@ -317,9 +330,9 @@ If the commit itself fails (e.g., nothing to commit, pre-commit hook rejects), d
    - **Discovery** and **Finalization** waves: skip session-reviewer dispatch — Discovery is read-only and Finalization is a final git status check only.
    - This is complementary to the incremental verification in step 4 — the session-reviewer provides deeper analysis (security, silent failures, test depth, type design) that automated checks do not cover.
 6. **Pencil design review** (after Impl-Core and Impl-Polish roles only, if `pencil` configured in Session Config):
-   a. Check Pencil editor state: `get_editor_state({ include_schema: false })`. If no editor active, open the configured `.pen` file via `open_document({ filePathOrTemplate: "<pencil-path>" })`. If that also fails → skip with note "Pencil review skipped — .pen file unavailable."
-   b. Get design structure: `batch_get({ filePath: "<pencil-path>", patterns: [{ type: "frame" }], readDepth: 2, searchDepth: 2 })` — find frames relevant to this wave's UI work.
-   c. Screenshot relevant frames: `get_screenshot({ filePath: "<pencil-path>", nodeId: "<frame-id>" })` for each frame matching the wave's UI tasks.
+   a. Check Pencil app state: `mcp__pencil__get_app_state`. If the configured `.pen` file is not open, open it through the `mcp__pencil__execute` surface (an Open/activate call on `filePath` — `.pen` files are encrypted, so never `Read`/`Grep` them; follow the tool's own input schema, which the Pencil MCP server instructions describe as "be aware of the .pen schema and the instructions for the execute tool"). If that also fails → skip with note "Pencil review skipped — .pen file unavailable."
+   b. Get design structure: `mcp__pencil__execute` with a **Get visitor** scoped to `filePath: "<pencil-path>"` at depth 1 (top-level frames) or depth 2 (frame children) — find frames relevant to this wave's UI work. Read the execute tool's input schema for the exact visitor shape before calling; do not guess it.
+   c. Render relevant frames: there is no direct screenshot tool on the current surface — use `mcp__pencil__browser` to view/capture each frame matching the wave's UI tasks (`filePath` plus the frame's node id).
    d. Read the actual UI files changed in this wave (from agent outputs).
    e. **Compare**: layout structure, component hierarchy, visual elements (headings, buttons, inputs, cards), responsive behavior.
    f. **Report** in wave progress:
@@ -334,7 +347,7 @@ If the commit itself fails (e.g., nothing to commit, pre-commit hook rejects), d
         3. If "Revise" → re-run session-plan for remaining waves only
         4. If "Abort" → mark remaining waves as DEFERRED, proceed to session-end
    
-   Always use the `filePath` parameter on Pencil MCP calls. Only review frames relevant to the current wave, not the entire file.
+   Always use the `filePath` parameter on Pencil MCP calls. Only review frames relevant to the current wave, not the entire file. The live tool names (`mcp__pencil__get_app_state`, `mcp__pencil__execute`, `mcp__pencil__browser`) have one definition in code — `PENCIL_TOOL_NAMES` in `scripts/lib/ux-grill/pencil-coverage.mjs`; the pre-2026 tool surface it replaced no longer exists (dead names enumerated in that module's JSDoc).
 
 7. **Capture wave metrics**: If `persistence` is enabled in Session Config, record for this wave after all agents complete and quality checks run. If `persistence` is `false`, skip metrics capture entirely — do not accumulate in-memory metrics. Record:
    - `wave_number`, `role`, `started_at` (when agents were dispatched), `completed_at` (when all finished)
@@ -462,7 +475,7 @@ After each wave completes and before the progress update, update `<state-dir>/ST
 
 **Gate:** `persistence: true` in Session Config. When `persistence: false`, skip every push below — there is no runtime side-channel to feed.
 
-The helper is `scripts/lib/agent-status.mjs`. Its exports (`setStatus`, `setProgress`, `readCurrentStatus`) are all no-throw and return `{ ok: true } | { ok: false, reason }`; the coordinator ignores the return value (best-effort). Push at **three anchors** in the wave loop:
+The helper is `scripts/lib/agent-status.mjs`. The writers (`setStatus`, `setProgress`) are no-throw and return `{ ok: true } | { ok: false, reason }`; the coordinator ignores the return value (best-effort). The reader `readCurrentStatus()` returns `{ entries, source: 'live-map'|'rebuilt-log'|'stale-cache', at, degraded? }` — the ledger `agent-status.jsonl` is the source of truth and the current-map is a rebuildable cache (#1342), so a consumer must SHOW `source`/`at`; `readCurrentStatusEntries()` is the bare-map accessor. Push at **three anchors** in the wave loop:
 
 1. **dispatch** — in `### 1. Dispatch Agents`, as each agent is dispatched, push its status. Use `setProgress` when the wave's per-agent ordinal is meaningful, else `setStatus`:
 

package/skills/wave-executor/references/wave-loop-scope-manifest.md

@@ -61,13 +61,13 @@ Before each wave dispatch:
 2. Validate by piping through `node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs"` (`$PLUGIN_ROOT` — see "Shell variables used in this section" above). If validation fails (exit 1), fix the JSON based on stderr errors and retry.
 3. **`allowedPaths` is COMPUTED from one canonical declaration array — never hand-transcribed (#1020/#1083).** Transcribing either declaration shape or the union by hand produced scope divergences. Globs stay verbatim (`scripts/*.sh`) — the enforcement hook resolves them at check time.
 
-   **3.1 — materialize both declaration shapes once.** Build one JSON array from the session plan, one `{id, files}` record for every agent plus exactly one `coordinator` record for the coordinator's planned direct edits. `files` arrays, their entries and their order are the plan's verbatim declarations. Materialize it ONCE and capture the aggregate-sidecar path:
+   **3.1 — materialize both declaration shapes once.** Build one JSON array from the session plan, one `{id, files}` record for every agent plus exactly one `coordinator` record for the coordinator's planned direct edits. `files` arrays, their entries and their order are the plan's verbatim declarations. Run from the **project root**, materialize it ONCE and capture the aggregate-sidecar path:
 
    ```bash
    WAVE_SCOPE_RECORDS='[{"id":"W3-I1","files":["scripts/example.mjs"]},{"id":"coordinator","files":["skills/wave-executor/wave-loop.md"]}]'
    WAVE_SCOPES_SIDECAR="$(
      printf '%s' "$WAVE_SCOPE_RECORDS" | node "$PLUGIN_ROOT/scripts/materialize-wave-scope.mjs" \
-       --state-dir "$STATE_DIR" --wave "$WAVE"
+       --state-dir "$STATE_DIR" --wave "$WAVE" --warn-missing
    )"
    [ -n "$WAVE_SCOPES_SIDECAR" ] || { echo "materialize-wave-scope produced no sidecar path" >&2; exit 1; }
    ```
@@ -81,6 +81,10 @@ Before each wave dispatch:
 
    `materialize-wave-scope.mjs` validates the COMPLETE input before writing; it writes `<state-dir>/filescopes/wave-<N>/<agent-id>.json` as each bare `files` array first, then writes `<state-dir>/filescopes/wave-<N>.scopes.json` as the unchanged aggregate record array last. Its human stdout is only that final sidecar path, so the command substitution above is the canonical `$WAVE_SCOPES_SIDECAR`. On error, do not continue with a partial declaration set; correct the plan and run the one command again.
 
+   **Check missing-path warnings before dispatch (#1235).** The recipe opts into `--warn-missing`: each absent concrete path is named with its agent on stderr. Relative paths resolve from the current project working directory, never from `$STATE_DIR`. A warning does not fail materialization or alter stdout, declaration bytes, ordering, or session binding. Grants containing `*` or ending in `/` retain their existing glob/prefix meaning and are skipped; `?` and braces remain literal path characters.
+
+   For each file the plan intentionally creates, append **`--new-file PATH`**, repeating the option for multiple files. Each exception must exactly match a path already declared in a `files` array and pass the same path validation. Invalid or undeclared exceptions fail before any scope file is written, even without `--warn-missing`. This explicit declaration suppresses only that path's warning; the materializer never guesses a filename or rewrites a grant. Without `--warn-missing`, existing callers keep their quiet missing-path behavior.
+
    The per-agent path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and File-Scope Injection (#1020) consume. Never write a `$TMPDIR` copy: it degrades to a signal-free allow when an injector cannot find the addressable wave-keyed file. The coordinator's record is materialized as `coordinator.json` and included in the aggregate, so its direct edits are covered by the two checks below.
 
    > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so writing these files reports `bash-write-verify: N file(s) changed by a Bash call OUTSIDE the wave's allowedPaths` naming `filescopes/wave-<N>/*.json`. Expected once per wave rollover at this step; it is information, not a scope violation. Never widen `allowedPaths` to silence it — that would grant agents write access to the deconfliction record itself.