session-orchestrator 3.20.0 → 3.22.0

package/skills/using-orchestrator/SKILL.md

@@ -67,7 +67,7 @@ When two or more candidates score ≥ 0.85 with delta < 0.15, call `AskUserQuest
 AskUserQuestion({
   questions: [{
     question: "Your message matches multiple workflows. Which one did you mean?",
-    header: "Skill Dispatch",
+    header: "Dispatch",
     multiSelect: false,
     options: [
       { label: "<top-skill display name> (Recommended)", description: "<one-line description of what it does>" },

package/skills/vault-mirror/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: vault-mirror
-description: Use when you need to populate the Meta-Vault with machine-generated notes derived from session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely; skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning notes to vault", "vault-mirror failed at session close". <example>Context: session-end is finalizing, vault-integration.mode is "warn". user: "/close" assistant: "Running vault-mirror to write 50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped."</example>
+description: >
+  Use when you need to populate the Meta-Vault with machine-generated notes derived from
+  session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and
+  `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and
+  `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when
+  `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely;
+  skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning
+  notes to vault", "vault-mirror failed at session close". <example>Context: session-end is finalizing,
+  vault-integration.mode is "warn". user: "/close" assistant: "Running vault-mirror to write
+  50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped."</example>
 model: haiku
 ---
 

package/skills/vault-sync/SKILL.md

@@ -1,6 +1,15 @@
 ---
 name: vault-sync
-description: Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes: `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by vault-sync". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true, vault-sync.mode="hard". user: "/close" assistant: "vault-sync found 2 frontmatter errors in vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close."</example>
+description: >
+  Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before
+  closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any
+  `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes:
+  `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from
+  Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at
+  session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by
+  vault-sync". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true,
+  vault-sync.mode="hard". user: "/close" assistant: "vault-sync found 2 frontmatter errors in
+  vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close."</example>
 model: haiku
 ---
 

package/skills/vault-sync/validator.mjs

@@ -254,6 +254,14 @@ for (let i = 0; i < args.length; i++) {
 //   ?     — any single character except `/`
 //   literal path separators and characters otherwise
 // Operates on POSIX-style forward-slash relative paths.
+// `**` compiles to a SEGMENT-ANCHORED alternative, not a free `(?:.*?)` (#1013).
+// The free form ended anywhere, including mid-segment, so every `**/` pattern
+// silently grew a suffix-match: `**/README.md` matched `MYREADME.md`, and
+// `**/archive/**` matched `90-archive/...`. This matcher answers "is this path
+// EXCLUDED from validation", so an over-approximation is not a harmless
+// widening — it is a false negative: the file is never checked and the
+// validator still reports 0 errors. Anchoring narrows exclusion, i.e. it can
+// only ever add files to the checked set.
 function globToRegExp(glob) {
   // Normalise input
   const g = glob.replace(/\\/g, '/');
@@ -262,12 +270,18 @@ function globToRegExp(glob) {
     const c = g[i];
     if (c === '*') {
       if (g[i + 1] === '*') {
-        // `**` — match across path segments
-        // Also swallow a following `/` so that `**/foo` matches `foo` at root.
-        const nextSlash = g[i + 2] === '/';
-        re += '(?:.*?)';
-        if (nextSlash) i += 2;
-        else i += 1;
+        if (g[i + 2] === '/') {
+          // `**/` — zero or more WHOLE path segments. Zero repetitions is what
+          // makes `**/foo` match `foo` at the vault root, and it is why the
+          // trailing `/` is swallowed here rather than emitted literally.
+          re += '(?:[^/]+/)*';
+          i += 2;
+        } else {
+          // Trailing or standalone `**` (e.g. `a/**`) — everything below the
+          // preceding literal, segment boundaries included.
+          re += '.*';
+          i += 1;
+        }
       } else {
         re += '[^/]*';
       }
@@ -658,6 +672,21 @@ const errors = [];
 const warnings = [];
 let filesChecked = 0;
 let filesSkippedNoFrontmatter = 0;
+// The paths behind the count (#1013). A bare count made "0 errors" ambiguous:
+// it meant "everything CHECKED is valid", never "everything is valid", and the
+// operator had no way to see WHICH files were never checked. The list is
+// emitted only by the branches that actually ran the validation pass — so an
+// ABSENT `files_skipped_no_frontmatter_paths` means "never inspected" (mode=off,
+// no vault) while an EMPTY one means "inspected, nothing skipped". Same
+// absence-preserving contract as `scripts/lib/reconcile-nudge-banner.mjs`
+// (`skippedCandidates`), which distinguishes never-checked from checked-clean.
+const filesSkippedNoFrontmatterPaths = [];
+// Ceiling: 50 paths keeps the envelope bounded on a vault that has never been
+// backfilled (real measurement 2026-08-15: 2 of 8574 files in the live vault).
+// `paths.length < files_skipped_no_frontmatter` is itself the truncation
+// signal, so no extra flag is needed. Revisit if a consuming vault routinely
+// reports more than 50 — then the right fix is a backfill, not a bigger cap.
+const SKIPPED_PATHS_CAP = 50;
 let excludedCount = 0;
 let archivedSkippedCount = 0;
 
@@ -686,6 +715,9 @@ for (const rec of records) {
 
   if (!fm.hasFrontmatter) {
     filesSkippedNoFrontmatter++;
+    if (filesSkippedNoFrontmatterPaths.length < SKIPPED_PATHS_CAP) {
+      filesSkippedNoFrontmatterPaths.push(rel);
+    }
     continue;
   }
 
@@ -737,6 +769,19 @@ for (const rec of records) {
 
 const hasErrors = errors.length > 0;
 
+// Silence is not success: a skipped file contributes to neither `errors` nor
+// `files_checked`, so a bare "0 errors" line would let an unvalidated file pass
+// unremarked at the session-end hard gate (#1013). Surface the count on stderr
+// too — stdout stays pure JSON per the caller contract.
+if (filesSkippedNoFrontmatter > 0) {
+  const shown = filesSkippedNoFrontmatterPaths.slice(0, 5).join(', ');
+  const more = filesSkippedNoFrontmatter - Math.min(5, filesSkippedNoFrontmatterPaths.length);
+  process.stderr.write(
+    `WARN: ${filesSkippedNoFrontmatter} file(s) NOT validated — no frontmatter: ` +
+      `${shown}${more > 0 ? ` (+${more} more)` : ''}\n`,
+  );
+}
+
 // ── mode=baseline ─────────────────────────────────────────────────────────
 // Serialize current errors + warnings as a snapshot, then exit 0.
 if (mode === 'baseline') {
@@ -774,6 +819,7 @@ if (mode === 'diff') {
       excluded_count: excludedCount,
       archived_skipped_count: archivedSkippedCount,
       files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+      files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
       errors,
       warnings,
     });
@@ -794,6 +840,7 @@ if (mode === 'diff') {
       excluded_count: excludedCount,
       archived_skipped_count: archivedSkippedCount,
       files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+      files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
       errors,
       warnings,
     });
@@ -816,6 +863,7 @@ if (mode === 'diff') {
     excluded_count: excludedCount,
     archived_skipped_count: archivedSkippedCount,
     files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+    files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
   });
 
   process.stderr.write(
@@ -839,6 +887,7 @@ emit({
   excluded_count: excludedCount,
   archived_skipped_count: archivedSkippedCount,
   files_skipped_no_frontmatter: filesSkippedNoFrontmatter,
+  files_skipped_no_frontmatter_paths: filesSkippedNoFrontmatterPaths,
   errors,
   warnings,
 });

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

@@ -433,7 +433,7 @@ This replaces the older prose slot "Relevant patterns from `<state-dir>/rules/`"
 
 **Gate:** runs when `.orchestrator/metrics/learnings.jsonl` exists. When it does not — or when nothing clears the confidence floor, or the corpus is unreadable — the CLI prints nothing and exits 0. Same best-effort convention as every injector above (Grounding `:307`, Frontmatter-Guard `:386`, Path-Cousin-Guard `:208`): silent no-op on any failure, **never blocks dispatch**. Any non-zero exit means "inject nothing, continue".
 
-**Zero new coordinator obligations.** The per-agent file scope this needs is the SAME `$AGENT_FILESCOPE_JSON` temp file the Pre-Dispatch Scope-Union Assertion (#796, see `## Scope Manifest` § 3) already requires you to write for every agent in every `Agent()` batch. Reuse that file — do not write a second one.
+**Zero new coordinator obligations.** The per-agent file scope this needs is the SAME `$AGENT_FILESCOPE_JSON` — `<state-dir>/filescopes/wave-<N>/<agent-id>.json` — that `## Scope Manifest` § 3.1 already requires you to write for every agent, and that the Scope-Union Assertion (#796) then consumes. Reuse that file — do not write a second one, and never a temp copy.
 
 **Invocation:** once per agent, immediately after that agent's `$AGENT_FILESCOPE_JSON` is written, capture stdout as `$LEARNINGS_INDEX`:
 
@@ -455,6 +455,21 @@ When it is empty (no corpus, no qualifying entries, or any CLI failure), dispatc
 
 **Instrumentation (why this one is measurable and its neighbours are not).** The rule injection above is a SHOULD and emits no signal either way, so "did the coordinator actually inject?" has been unanswerable after the fact — a gap the #1014 discovery wave had to leave open. This CLI emits `orchestrator.learnings.index.injected` to `.orchestrator/metrics/events.jsonl` (via `scripts/emit-event.mjs`, the canonical `emitEvent()` path — the same route `scripts/compute-grounding-injection.sh` uses for `orchestrator.grounding.injected`), carrying `count`, `scope_matched`, `global_count`, `candidates`, `truncated`, `bytes`, and `scope_source`. The before/after measurement is therefore a fact in the event log, not a matter of prose compliance. Emission is best-effort and suppressible with `--no-event`; a failed emit never blocks dispatch.
 
+#### Pre-Dispatch: File-Scope Injection (#1020)
+
+> **Read this first — this block is PER AGENT, unlike `#### Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)` above, which states "Per-wave scoping (not per-agent): the rule set is computed ONCE per wave".** Model it on **Pre-Dispatch Grounding Injection (#85)** — same cadence, same per-agent source. This injector legitimately has BOTH cadences (per-agent for the brief, per-wave for the § Scope Manifest union), which is exactly what makes the collapse tempting: reuse ONE agent's block for the whole batch and every agent reads the territory of every OTHER agent as its own. Deconfliction would then be **lifted rather than enforced**, and the double assignment § 3.2 exists to catch becomes invisible in the one channel where an agent could still notice it.
+
+**Invocation:** for each agent, read `<state-dir>/filescopes/wave-<N>/<agent-id>.json` (= `$AGENT_FILESCOPE_JSON`) — the SAME file written in § Scope Manifest 3.1, not a re-derivation from the session plan and not a temp copy — and prepend its entries to that agent's prompt, one path per line:
+
+    FILE-SCOPE — exactly these:
+    ```
+    <one path or glob per line, verbatim from that agent's scope file>
+    ```
+
+Marker line plus fenced block, in that order: `hooks/pre-task-scope-disjoint.mjs` extracts the scope from the prompt by finding the marker and taking the FIRST fenced block after it, so this shape is what makes an agent's declared territory machine-readable at dispatch time. An unparseable or absent block resolves to ALLOW there, so a malformed injection degrades to today's behaviour rather than blocking dispatch. When the scope file is missing or empty (Discovery waves), inject nothing and dispatch unchanged.
+
+> **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.
+
 #### 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.
@@ -1099,19 +1114,56 @@ Before each wave dispatch:
    ```
    The `gates` field (optional) mirrors `enforcement-gates` from Session Config (#77). When present, hooks check each gate individually via `gate_enabled()`. Missing gate entries default to enabled, preserving default behavior.
 2. Validate by piping through `node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs"` (where `$PLUGIN_ROOT` is `$CLAUDE_PLUGIN_ROOT`, `$CODEX_PLUGIN_ROOT`, or `$CURSOR_RULES_DIR` per platform — see `skills/_shared/config-reading.md`). If validation fails (exit 1), fix the JSON based on stderr errors and retry.
-3. `allowedPaths` is the UNION of all agent file scopes for this wave
-   To compute `allowedPaths`: read each agent's specification from the session plan. Each agent lists its "Files:" scope (e.g., `skills/session-end/SKILL.md`, `scripts/*.sh`). Collect all file paths and glob patterns from all agents in this wave into a single flat array. Deduplicate entries. If an agent's scope uses globs (e.g., `scripts/*.sh`), include the glob pattern as-is — the enforcement hook resolves globs at check time.
+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.
 
-   **Test-Sibling Expansion (#970):** an `allowedPaths` entry that names a production file but NOT its test sibling makes the wave's own regression test unwritable — the scope guard then mechanically enforces exactly the inconsistency the quality gate exists to catch. Cross-repo evidence, three occurrences in ONE session: a migrations glob without the SQL-test directory (the regression test could not be written); a lone `.actions.ts` file (the wave's cross-tenant security test stayed red); a dead-export deletion whose importing test lay outside every scope (the suite ended red). Do NOT hand-derive the sibling paths — expand through the shared helper so the hook, the validator and this prose state one rule:
+   **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:
 
-   ```js
-   import { expandTestSiblings } from '$PLUGIN_ROOT/scripts/lib/scope-gate.mjs';
+   ```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"
+   )"
+   [ -n "$WAVE_SCOPES_SIDECAR" ] || { echo "materialize-wave-scope produced no sidecar path" >&2; exit 1; }
+   ```
+
+   The non-empty check is not decoration. The materializer sends every diagnostic
+   to stderr, so a failure leaves `$WAVE_SCOPES_SIDECAR` empty, and an empty path
+   is what step 3.2 would then pass to `--assert-disjoint`. That combination used
+   to exit 0 with the collision gate never run — the same signal-free-ALLOW shape
+   #1083 exists to close. `validate-wave-scope.mjs` now refuses an empty flag
+   value as well, so this guard and that refusal are belt and braces.
+
+   `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.
+
+   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.
 
-   // unionScopes: the deduplicated flat array from the paragraph above.
-   // role: this wave's role, verbatim from the session plan — the helper GATES on it.
-   const allowedPaths = expandTestSiblings(unionScopes, { role });
+   **3.2 — assert disjointness BEFORE computing the union.** The materialized aggregate is an ARRAY of `{id, files}` records (never an object map: a duplicated agent id must stay visible), including `coordinator.json`. Run:
+
+   ```bash
+   node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
+     --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
    ```
 
+   Exit 1 (one stderr message per collision) means two agents were handed the same file: fix the session plan, re-materialize, re-assert. Never widen the union to make it pass. This runs **before** 3.3 because a union computed over colliding scopes launders the defect into the very artefact meant to prevent it — `allowedPaths` then grants the file and every later gate sees a legal write.
+
+   **3.3 — compute the union.** `--union` is a QUERY MODE that still requires a schema-valid manifest on stdin, so write the skeleton first with `"allowedPaths": []`, then:
+
+   ```bash
+   node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
+     --union "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
+   ```
+
+   It prints the computed `allowedPaths` array as JSON on stdout **instead of** the manifest echo — one JSON document per run, the flag decides which. Insert that array as `allowedPaths`, then write the final `wave-scope.json`. It already applies the Test-Sibling Expansion below (`expandTestSiblings(unionFileScopes(scopes), { role })`, role read from the manifest), so do not also run the helper by hand.
+
+   **Artifact production, disjointness and union computation are mechanized. Native prompt injection is a separate follow-up.** The materializer creates the durable declarations; the validator proves disjointness and computes the union. It does not install or prove the platform's prompt-injection transport, which remains independently responsible for reading `$AGENT_FILESCOPE_JSON` before dispatch.
+
+   **The `--assert-subset` assertion (#796, below) stays unchanged and keeps running.** It checks a DIFFERENT property — each agent's scope ⊆ the union — and a double assignment is structurally invisible to it: a file claimed twice is a subset twice over. `--assert-disjoint` is an addition, never a replacement.
+
+   **Test-Sibling Expansion (#970):** an `allowedPaths` entry that names a production file but NOT its test sibling makes the wave's own regression test unwritable — the scope guard then mechanically enforces exactly the inconsistency the quality gate exists to catch. Cross-repo evidence, three occurrences in ONE session: a migrations glob without the SQL-test directory (the regression test could not be written); a lone `.actions.ts` file (the wave's cross-tenant security test stayed red); a dead-export deletion whose importing test lay outside every scope (the suite ended red). Do NOT hand-derive the sibling paths — step 3.3's `--union` runs `expandTestSiblings(…, { role })` for you, so the hook, the validator and this prose state one rule.
+
    The helper is pure (same input → same output, no filesystem writes) and is also surfaced by `scripts/validate-wave-scope.mjs`. **The role decides, inside the helper** — `scripts/lib/scope-gate.mjs` `TEST_SIBLING_EXPANSION_ROLES` is THE list (currently `Impl-Core`, `Impl-Polish` — exactly where the incident occurred), and #5/#6 below describe that gate rather than restating it. Pass the role string; do not pre-filter by role in prose, and do not hand-roll the equivalent `{ enabled: … }`. Matching is trimmed + case-insensitive, so `impl-core` behaves as `Impl-Core`.
 
    > **Fail-closed:** an ABSENT or unrecognised `role` does **not** expand. Omitting it fails loudly (an agent's write to its own test is blocked, recoverable by one re-union); the opposite default would silently hand a Quality phase-1 simplification agent write access to the suite. `{ enabled: false }` is the unconditional opt-out and `{ enabled: true }` the explicit opt-in — both override the role.
@@ -1123,11 +1175,11 @@ Before each wave dispatch:
    **The sibling rule is repo-configurable, not a hardcoded layout.** THIS repo has zero `__tests__/` directories and no co-located tests; consumer-repo shapes (`<file>.test.*` beside the source, `<dir>/__tests__/**`, `supabase/migrations/** → supabase/tests/**`) are configured per repo and do not apply here.
 
    Three ordering constraints, all load-bearing:
-   - Expand each agent's `fileScope` **before** the overlap/deconfliction check, so a test file newly shared by two agents is visible to the check that exists to catch that collision.
+   - The deconfliction check (3.2) runs on the DECLARED per-agent scopes, **before** the union expands anything. Named ceiling: two agents whose production files share a basename receive the same emitted sibling glob, which a declared-scope check cannot see — revisit if a wave is ever scoped by basename family instead of by directory.
    - Expand **before** `wave-scope.json` is written, in ONE pass. `hooks/post-bash-write-verify.mjs` fingerprints `allowedPaths` via `scopeSignature()` and fires a control notice on change, so a later mutation reads as tampering.
    - Skip **absolute** entries entirely — expanding a Gate-5b out-of-repo grant would sprout a synthetic `tests/**` sibling outside the repo.
 
-   **Pre-Dispatch Scope-Union Assertion (#796):** `wave-scope.json` is GLOBAL per wave — `hooks/enforce-scope.mjs` Gate 7 checks EVERY agent against the same `allowedPaths` union, so a union that (re)written for only ONE agent silently denies its siblings' legitimate writes. Before each `Agent()` batch, mechanically assert — for EVERY agent in the batch — that its fileScope ⊆ `wave-scope.allowedPaths`. Write the agent's "Files:" scope as a JSON array of strings to a temp file (`$AGENT_FILESCOPE_JSON`) and run:
+   **Pre-Dispatch Scope-Union Assertion (#796):** `wave-scope.json` is GLOBAL per wave — `hooks/enforce-scope.mjs` Gate 7 checks EVERY agent against the same `allowedPaths` union, so a union that (re)written for only ONE agent silently denies its siblings' legitimate writes. Before each `Agent()` batch, mechanically assert — for EVERY agent in the batch — that its fileScope ⊆ `wave-scope.allowedPaths`. `$AGENT_FILESCOPE_JSON` is that agent's § 3.1 file — `<state-dir>/filescopes/wave-<N>/<agent-id>.json`, already written above and shared with every other consumer. Do not re-write it to a temp path here (§ 3.1 says why that degrades silently); just run:
 
    ```bash
    node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs" \
@@ -1158,4 +1210,4 @@ Before each wave dispatch:
    5. Delete `<state-dir>/wave-scope.json`
    6. Write Phase 2 wave-scope.json with test file allowedPaths (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
    7. Dispatch test/review agents
-7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup)
+7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup). Delete `<state-dir>/filescopes/` in the same step — the per-agent scope files (§ 3.1) are wave-local working state, and a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified.

package/skills/write-executable-plan/SKILL.md

@@ -163,11 +163,11 @@ Any hit → surface to user via AUQ:
 ```
 AskUserQuestion({
   questions: [{
-    question: "The placeholder linter found forbidden strings in the draft plan:\n\n[list each hit with Task number, Step number, and matched text]\n\nHow do you want to proceed?",
-    header: "Placeholder Linter",
+    question: "The draft plan still contains forbidden placeholder strings. How do you want to proceed?",
+    header: "Platzhalter",
     options: [
-      { label: "Fix automatically (Recommended)", description: "I will resolve each hit by filling in the missing specifics before writing the plan." },
-      { label: "Show me each hit interactively", description: "Walk me through each one so I can provide the missing detail." }
+      { label: "Fix automatically (Recommended)", description: "I fill in the missing specifics myself, then write the plan — fastest, and you review the result at hand-off.", preview: "[each hit: Task number, Step number, matched text]" },
+      { label: "Show me each hit interactively", description: "Walk me through each one so I can provide the missing detail.", preview: "[the same hits, one at a time, starting with the first]" }
     ],
     multiSelect: false
   }]
@@ -202,8 +202,8 @@ Present the plan path and task count to the user via AUQ:
 ```
 AskUserQuestion({
   questions: [{
-    question: "Executable plan written to docs/plans/YYYY-MM-DD-<slug>.md ([N] tasks, ~[total] min estimated).\n\nHow do you want to execute it?",
-    header: "Plan Hand-off",
+    question: "Plan written to docs/plans/YYYY-MM-DD-<slug>.md — [N] tasks, ~[total] min. How to execute?",
+    header: "Plan fertig",
     options: [
       { label: "Dispatch via wave-executor (Recommended)", description: "Parallel agents execute all tasks simultaneously. Fastest for file-disjoint tasks." },
       { label: "Execute coordinator-direct", description: "One task at a time in this session. Safer for tasks with shared state." },

package/scripts/lib/mission-status-schema.mjs

@@ -1,114 +0,0 @@
-/**
- * Mission-Status Enum + Transition Validator (issue #340).
- *
- * Pure ESM, no I/O, no external dependencies. All functions are deterministic.
- *
- * Five-state lifecycle for wave-plan items:
- *
- *   brainstormed → validated → in-dev → testing → completed
- *
- * Rollbacks to `brainstormed` are permitted from any state (user can reset scope).
- * Idempotent self-transitions are always allowed.
- * All other transitions are rejected.
- */
-
-/**
- * Canonical ordered list of valid mission-status values.
- *
- * @type {readonly string[]}
- */
-export const MISSION_STATUS_VALUES = Object.freeze([
-  'brainstormed',
-  'validated',
-  'in-dev',
-  'testing',
-  'completed',
-]);
-
-/**
- * Allowed forward transitions (excluding self-transitions and rollback to
- * 'brainstormed', which are handled separately in isValidMissionStatusTransition).
- *
- * @type {ReadonlyMap<string, string>}
- */
-const FORWARD_TRANSITIONS = new Map([
-  ['brainstormed', 'validated'],
-  ['validated', 'in-dev'],
-  ['in-dev', 'testing'],
-  ['testing', 'completed'],
-]);
-
-/**
- * Returns true when `value` is one of the five canonical status strings.
- *
- * @param {unknown} value
- * @returns {boolean}
- */
-export function isValidMissionStatus(value) {
-  return typeof value === 'string' && MISSION_STATUS_VALUES.includes(value);
-}
-
-/**
- * Returns true when the transition from `from` → `to` is permitted.
- *
- * Allowed transitions:
- *   - Forward: brainstormed→validated, validated→in-dev, in-dev→testing, testing→completed
- *   - Idempotent: any state → itself
- *   - Rollback: any state → brainstormed
- *
- * All other transitions return false.
- *
- * @param {string} from - current status value
- * @param {string} to   - target status value
- * @returns {boolean}
- */
-export function isValidMissionStatusTransition(from, to) {
-  if (!isValidMissionStatus(from) || !isValidMissionStatus(to)) return false;
-  // Idempotent self-transition
-  if (from === to) return true;
-  // Rollback to brainstormed from any state
-  if (to === 'brainstormed') return true;
-  // Forward transition
-  return FORWARD_TRANSITIONS.get(from) === to;
-}
-
-/**
- * Validates a mission-status entry object.
- *
- * Expected shape:
- *   { id: string, task: string, wave: number, status: <MISSION_STATUS_VALUES> }
- *
- * @param {unknown} obj
- * @returns {{ ok: boolean, errors: string[] }}
- */
-export function validateMissionStatusEntry(obj) {
-  const errors = [];
-  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
-    return { ok: false, errors: ['entry must be a non-null, non-array object'] };
-  }
-  const entry = /** @type {Record<string, unknown>} */ (obj);
-
-  // id — non-empty string
-  if (typeof entry.id !== 'string' || entry.id.trim() === '') {
-    errors.push('id must be a non-empty string');
-  }
-
-  // task — non-empty string
-  if (typeof entry.task !== 'string' || entry.task.trim() === '') {
-    errors.push('task must be a non-empty string');
-  }
-
-  // wave — integer >= 1
-  if (!Number.isInteger(entry.wave) || /** @type {number} */ (entry.wave) < 1) {
-    errors.push('wave must be a positive integer');
-  }
-
-  // status — one of MISSION_STATUS_VALUES
-  if (!isValidMissionStatus(entry.status)) {
-    errors.push(
-      `status must be one of [${MISSION_STATUS_VALUES.join(', ')}], got: ${JSON.stringify(entry.status)}`,
-    );
-  }
-
-  return { ok: errors.length === 0, errors };
-}

package/scripts/tests/fixtures/fetch-baseline/sample-rule.md

@@ -1,8 +0,0 @@
-# Sample Baseline Rule (test fixture)
-
-This file is used by scripts/tests/fetch-baseline.bats as the mocked response body
-for the GitLab API raw-file endpoint. It has no real content — presence is enough
-to verify the fetch + cache path.
-
-- Rule ID: TEST-001
-- Purpose: end-to-end fetch verification

package/skills/vault-sync/tests/fixtures/archive-test-vault/90-archive/bad-archived.md

@@ -1,8 +0,0 @@
----
-id: bad-archived
-type: memo
-created: not-a-date
-updated: not-a-date
----
-
-Bad frontmatter — but inside 90-archive, so must be ignored.

package/skills/vault-sync/tests/fixtures/archive-test-vault/live-note.md

@@ -1,8 +0,0 @@
----
-id: live-note
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Lives outside archive — must be validated.

package/skills/vault-sync/tests/fixtures/broken-frontmatter-vault/bad-type.md

@@ -1,8 +0,0 @@
----
-id: bad-type
-type: memo
-created: 2026-04-13
-updated: 2026-04-13
----
-
-`type: memo` is not in the enum.

package/skills/vault-sync/tests/fixtures/broken-frontmatter-vault/good-note.md

@@ -1,8 +0,0 @@
----
-id: good-note
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-OK.

package/skills/vault-sync/tests/fixtures/clean-vault/.obsidian/config.md

@@ -1,8 +0,0 @@
----
-id: bogus
-type: memo
-created: not-a-date
-updated: not-a-date
----
-
-If the validator crawls .obsidian/, this file would FAIL. It must be excluded.

package/skills/vault-sync/tests/fixtures/clean-vault/01-projects/foo/projects-baseline.md

@@ -1,10 +0,0 @@
----
-id: projects-baseline
-type: project
-created: 2026-04-01
-updated: 2026-04-13
-status: active
-tags: [meta, infra]
----
-
-Project overview.

package/skills/vault-sync/tests/fixtures/clean-vault/03-daily/daily-2026-04-13.md

@@ -1,8 +0,0 @@
----
-id: daily-2026-04-13
-type: daily
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Today: wrote vault-sync validator.

package/skills/vault-sync/tests/fixtures/clean-vault/README.md

@@ -1,3 +0,0 @@
-# Clean Vault
-
-No frontmatter here — README-style files must be skipped, not errored.

package/skills/vault-sync/tests/fixtures/clean-vault/hello-world.md

@@ -1,11 +0,0 @@
----
-id: hello-world
-type: note
-created: 2026-04-13
-updated: 2026-04-13
-title: Hello World
-tags: [meta, intro]
-status: active
----
-
-A minimal valid note that links to [[daily-2026-04-13]] and [[projects-baseline]].

package/skills/vault-sync/tests/fixtures/dangling-link-vault/has-dangling.md

@@ -1,9 +0,0 @@
----
-id: has-dangling
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-This note links to [[non-existent-target]] which should be flagged as a warning.
-It also links to [[real-target]] which exists.

package/skills/vault-sync/tests/fixtures/dangling-link-vault/real-target.md

@@ -1,8 +0,0 @@
----
-id: real-target
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Real.

package/skills/vault-sync/tests/fixtures/missing-field-vault/missing-id.md

@@ -1,7 +0,0 @@
----
-type: note
-created: 2026-04-13
-updated: 2026-04-13
----
-
-Missing `id`.

package/skills/vault-sync/tests/fixtures/nested-tag-vault/03-daily/daily-2026-04-13.md

@@ -1,9 +0,0 @@
----
-id: daily-2026-04-13
-type: daily
-created: 2026-04-13
-updated: 2026-04-13
-tags: [area/infrastructure/cleanup, meta/session-log]
----
-
-Daily note using deep-nested Obsidian tags.

package/skills/vault-sync/tests/fixtures/nested-tag-vault/nested-tags-note.md

@@ -1,11 +0,0 @@
----
-id: nested-tags-note
-type: note
-created: 2026-04-13
-updated: 2026-04-13
-title: Nested Tags Note
-tags: [meta/schema, status/in-progress, area/infrastructure, session/2026-04-13]
-status: active
----
-
-A note that uses Obsidian nested-tag conventions (slash-separated hierarchy).

package/skills/vault-sync/tests/fixtures/no-frontmatter-vault/README.md

@@ -1,3 +0,0 @@
-# README only
-
-No frontmatter. Must be counted as `files_skipped_no_frontmatter` and not error.

package/skills/vault-sync/tests/fixtures/no-frontmatter-vault/_MOC.md

@@ -1,3 +0,0 @@
-# Map of Content
-
-No frontmatter — this is a plain index.