session-orchestrator 3.19.0 → 3.21.0

package/skills/session-start/soul.md

@@ -11,7 +11,7 @@ You are the Session Orchestrator — a seasoned engineering lead who has shipped
 - Bias toward action — do, don't talk
 - When you see a problem, name it. Don't soften bad news.
 - Short sentences. No filler. Every word earns its place.
-- Communication style: {{tone.style}}. Output level: {{efficiency.output-level}}. Preamble: {{efficiency.preamble}}.
+- How much you say is a dial the operator sets, not a matter of taste — see § Output Levels.
 
 ### Have opinions
 - You are NOT a neutral options-lister. You have preferences shaped by experience.
@@ -31,6 +31,46 @@ You are the Session Orchestrator — a seasoned engineering lead who has shipped
 - Never catastrophize. Problems are just tasks that haven't been planned yet.
 - Session end: concrete summary of impact. "Today we moved X forward."
 
+## Output Levels
+
+The active level is `efficiency.output-level` in `~/.config/session-orchestrator/owner.yaml`. If that file is missing, unreadable, or the key is absent, the level is `full`. Apply the matching block below for the whole session.
+
+**How to read a budget.** "Lines before the first question" counts every chat line you author from session start until your first `AskUserQuestion` — raw tool output does not count, your narration of it does. A budget is a ceiling, not a target: under is fine, over is a defect. You meet it by WITHHOLDING, never by dropping — nothing verified disappears, it just waits to be asked for.
+
+**Escalation (all levels).** When the operator writes `expand <topic>` (German: `mehr zu <Abschnitt>`), print that topic's full detail immediately, without re-asking and without the budget applying to that one response. Durable detail also stays on disk — `STATE.md`, the wave plan, `.orchestrator/metrics/` — point there rather than reprinting bulk.
+
+**Never traded for brevity (all levels).** No budget may be met by cutting any of the following. Where a budget and one of them collide, the budget yields:
+- input validation, and the reporting of invalid input;
+- error handling, error messages, and failure disclosure — a swallowed error is never "concise";
+- security findings, warnings, and destructive-action confirmations (PSA-003);
+- accessibility of the output itself — no meaning carried by colour or emoji alone, no bare unlabelled numbers, no table whose header you dropped to save a line;
+- anything the operator explicitly asked to see.
+
+### output-level: ultra
+- Meaning: telegraphic — decisions, data, and diffs only. No narration.
+- Budget: ≤80 lines before the first question; ≤6 lines per finding; ≤1 line of preamble per tool call.
+- Shape: bullets and tables, no prose paragraphs. Findings as `<severity> <file>:<line> — <what>`. Never restate what a tool just printed; never summarise your own summary.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: full
+- Meaning: terse but complete — narration trimmed, data preserved. This is the default.
+- Budget: ≤150 lines before the first question; ≤12 lines per finding; ≤2 lines of preamble per tool call.
+- Shape: one line of rationale per recommendation, then the data. Prose only where a bullet would lose the causal link. Every finding keeps its evidence (command + result); what gets trimmed is the explanation OF the evidence, never the evidence.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### output-level: lite
+- Meaning: verbose — articles, explanations, and context kept. Chosen for learning, not for speed.
+- Budget: ≤300 lines before the first question; ≤30 lines per finding. Still a ceiling — `lite` is not "unbounded".
+- Shape: explain the WHY behind each recommendation, name the alternatives you rejected and why, spell out unfamiliar terms on first use.
+- Escalation: `expand <topic>` — see § Escalation above.
+
+### Companion dials
+
+Same file, same lookup, same fallback-to-default rule:
+
+- `efficiency.preamble` — `minimal` (default): at most one clause before a tool call, and only when the next step is non-obvious; never "Let me check X." immediately followed by checking X. `verbose`: one sentence before each tool call naming what you expect to find.
+- `tone.style` — `direct` (this soul's baseline: lead with the recommendation, name problems plainly), `neutral` (state findings without advocacy; still recommend when asked), `friendly` (same content, softer framing; never softer facts).
+
 ## Decision-Making Philosophy
 
 When ambiguity arises, resolve it using this hierarchy:

package/skills/spinout/SKILL.md

@@ -2,7 +2,11 @@
 name: spinout
 user-invocable: true
 model: sonnet
-description: Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path, confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo, remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
+description: >
+  Use when extracting a project into its own repo — a venture spinout (e.g. a product leaving its
+  incubator repo) or a sanitized content-snapshot fork. Guided 5-step runbook: target sphere + path,
+  confidentiality/sanitize check, copy + fresh git init, SNAPSHOT-FREEZE marker in the source repo,
+  remotes + registration. Trigger on 'spin out X', 'extract this into its own repo', 'fork X sanitized'.
 ---
 
 # spinout — Guided Project-Extraction Runbook

package/skills/sunset-review/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: sunset-review
-description: Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events only) with static reference scanning, classifies every surface item into Active / Investigate / Demote / Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision." <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker, presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
+description: >
+  Use this skill when the user wants to identify unused, near-zero-use, or stale skills/agents/commands in
+  the plugin surface so they can be demoted or retired. Combines agent-dispatch telemetry (start-events
+  only) with static reference scanning, classifies every surface item into Active / Investigate / Demote /
+  Retire, and emits a Markdown report plus JSON sidecar. NEVER auto-deletes — surfaces candidates for
+  human decision. Quarterly cadence. <example>Context: The plugin surface has grown and the maintainer
+  wants to prune dead weight. user: "/sunset-review" assistant: "Running the sunset walk — classifying
+  skills, agents, and commands by usage telemetry + static refs, grouped by Retire / Demote / Investigate
+  / Active. No item is deleted automatically; I'll surface Retire/Demote candidates for your decision."
+  <commentary>The user wants a usage-driven prune candidate list; this skill runs the read-only walker,
+  presents grouped verdicts, and writes a sidecar — it never deletes.</commentary></example>
 model: inherit
 color: amber
 ---

package/skills/tmux-layout/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: tmux-layout
-description: Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels", "show me state-md tail and ci".
+description: >
+  Use this skill when the operator wants a prepared tmux visualization layout for the session's
+  side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug
+  layout. Read-only side-channel observability — the coordinator chat stays in the operator's original
+  terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels",
+  "show me state-md tail and ci".
 model: inherit
 color: cyan
 tools: Read, Bash, Grep, Glob
@@ -47,7 +52,7 @@ The skill prints a one-line tmux command. Paste it into a SECOND terminal (do no
 |---|---|---|
 | 1 | **Shell** (operator scratch — NOT claude) | `bash` (interactive) |
 | 2 | STATE.md tail | `tail -F <state-dir>/STATE.md` |
-| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status --pipeline-id LATEST --output json \| jq ...; sleep 15; done` |
+| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status -R <spec> --output json \| jq -r '.jobs[] \| ...'; sleep 15; done` |
 | 4 | events.jsonl wave/gate filter | `tail -F .orchestrator/metrics/events.jsonl \| jq --unbuffered 'select(.event \| test("wave\|gate\|spiral"))'` |
 | 5 | agent-status telemetry (#565, only with `--with-status-pane`) | `while true; do clear; jq . .orchestrator/runtime/agent-status-current.json 2>/dev/null \|\| echo ...; sleep 2; done` |
 

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/SKILL.md

@@ -245,7 +245,7 @@ Each agent prompt MUST include:
 1. **Clear scope boundary**: "You are working on [X]. Do NOT modify files outside [paths]."
 2. **Full context**: file paths, current code structure, issue description. If a bite-sized executable plan exists at `docs/plans/<feature>.md` for the wave's tasks (see `skills/write-executable-plan/SKILL.md`), include the path in each agent's prompt and instruct the agent to follow the plan's 5-step structure verbatim.
 3. **Acceptance criteria**: measurable definition of done
-4. **Rule references**: the wave's applicable rules are injected automatically as the `<APPLICABLE-RULES>` block produced by `scripts/print-applicable-rules.mjs` (see `wave-loop.md` § "Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)"). The block is computed once per wave from the wave's `allowedPaths` and prepended to every agent prompt — do not hand-copy rule paths into the prompt.
+4. **Rule references**: the wave's applicable rules are injected automatically as the `<APPLICABLE-RULES>` block produced by `scripts/print-applicable-rules.mjs` (see `wave-loop.md` § "Pre-Dispatch: Glob-Scoped Rule Injection (#336/#694)"). The block is computed once per wave from the wave's `allowedPaths` and prepended to every agent prompt — do not hand-copy rule paths into the prompt. Past **learnings** arrive separately as the `<LEARNINGS-INDEX>` block from `scripts/print-learnings-index.mjs` (see `wave-loop.md` § "Pre-Dispatch: Learnings-Index Injection (#1014)"), computed **per agent** from its own file scope rather than once per wave.
 5. **Testing expectation** (need-gated): "Before writing any test, name the concrete bug a NEW test would catch that the existing suite does not. No nameable bug → write NO test and report `no-tests-needed: <reason>` — that is a SUCCESS outcome, not a gap. With a nameable bug: exactly one test for it. Running existing tests is always mandatory."
 6. **Commit instruction**: "Do NOT commit. The coordinator handles commits."
 7. **Turn limit**: Include the maxTurns instruction from `circuit-breaker.md`
@@ -438,10 +438,6 @@ const result = await runQualityGateWithRetry({
   Gherkin negative path).
 - `verification-auto-fix.max-retries: 0` → equivalent to disabled.
 
-### /goal Continuation Anchor (opt-in — #636)
-
-When `goal-integration.enabled: true` with seam `inter-wave-fixloop` in Session Config, the coordinator may surface ONE advisory `/goal` command at the inter-wave fix-loop seam to anchor continuation across the auto-fix retries — see `wave-loop.md` § "##### /goal Continuation Anchor" for the gate conditions, suggested command, and the LM-008 cross-reference. The advisory never alters gate semantics: `runQualityGateWithRetry()`'s exit-code result remains the judgment, and the hard-abort + diagnostics-bundle path after `max-retries` is unchanged. Default off → zero behaviour change.
-
 ### Anti-pattern (BE-012 awareness)
 
 The fixer-agent prompt MUST include a reminder of `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention"

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

@@ -263,6 +263,7 @@ For each agent in this wave:
       - Which files to read/modify (exact paths)
       - Acceptance criteria (how to verify done)
       - Relevant patterns — injected automatically as the <APPLICABLE-RULES> block (see Pre-Dispatch: Glob-Scoped Rule Injection below)
+      - Relevant past learnings — injected automatically as the <LEARNINGS-INDEX> block, computed PER AGENT from its file scope (see Pre-Dispatch: Learnings-Index Injection below)
       - Any repo-state fact carried from an earlier wave: in the ASSERTED/UNVERIFIED form, never as a bare value (see Pre-Dispatch: Fact-Staleness Annotation above)
       - VCS issue reference if applicable
       - What NOT to touch (other agents' files)
@@ -405,7 +406,7 @@ After `wave-scope.json` is written for this wave and before assembling the `Agen
     RULES_BLOCK="$(node "$PLUGIN_ROOT/scripts/print-applicable-rules.mjs" --context wave 2>/dev/null)"
 
 `--context wave` (issue #692) excludes `tier: coordinator-only` rules (owner-persona, lsp, mvp-scope, loop-and-monitor) from the wave-agent prompt — those are operator/coordinator-context rules a wave implementation agent does not need. `tier: always` and `tier: wave-only` rules are unaffected; omitting the flag (or passing `--context coordinator`) disables wave-tier exclusion. Use `--wave-scope <path>` only if `wave-scope.json` is not at the default `.claude/wave-scope.json`. The CLI returns:
-- a Markdown block (header `## Applicable Rules (scoped to this wave)` + each matching rule's raw content, separated by `---`) when one or more rules apply, OR
+- a Markdown block (header `## Applicable Rules (scoped to this wave)`, a preamble naming the block's fence token, then each matching rule's raw content wrapped in `<rule-<token> index="i/N" src="<repo-relative path>">` … `</rule-<token>>`) when one or more rules apply, OR
 - empty output (exit 0) when no rules match — in which case prepend nothing.
 
 **Prompt assembly:** when `$RULES_BLOCK` is non-empty, prepend it to EACH agent's prompt in this wave under a clear separator:
@@ -420,6 +421,55 @@ When `$RULES_BLOCK` is empty (no `.claude/rules/`, no matching rules, or any CLI
 
 This replaces the older prose slot "Relevant patterns from `<state-dir>/rules/`" in the `Agent()` template above: the `<APPLICABLE-RULES>` block IS that injection, now mechanically scoped to the wave instead of left to the coordinator's judgement.
 
+#### Pre-Dispatch: Learnings-Index Injection (#1014)
+
+> **Read this first — it is computed PER AGENT, unlike the block directly above.** The rule injection you just read states "Per-wave scoping (not per-agent): the rule set is computed ONCE per wave". This step is the opposite: **run the CLI once for EACH agent**, because per-agent differentiation IS the acceptance criterion — an agent scoped to `scripts/lib/learnings/**` must receive different entries than its sibling scoped to `skills/**`. Model it on **Pre-Dispatch Grounding Injection (#85)** above, not on its immediate neighbour. Computing it once and reusing it across the wave silently reduces this feature to a worse version of the coordinator banner that already exists.
+
+89 learnings have accumulated across 233 sessions, and a dispatched wave agent receives **zero** of them: the only read paths are a coordinator banner, an autopilot call, and a nudge banner — none reaches an agent prompt. This step closes that loop by prepending a compact, relevance-ranked INDEX of learnings to each agent's prompt.
+
+**Why this does not repeat the #931b mistake.** `docs/instruction-delivery.md` measured that adding a SECOND delivery path alongside Claude Code's native project-instruction loading costs **+72%** (292,836 B vs 169,961 B) — which is why the rule block above carries a "measure before you inject" warning. That warning does **not** transfer here, and not as a matter of argument: learnings have no native delivery path to duplicate. `learnings.jsonl` lives under `.orchestrator/metrics/`, is not a project-instruction file, is not `@`-imported from CLAUDE.md, and reaches nothing agent-facing today. This is the FIRST path, and it rides the dispatch-prompt channel this repo already owns and writes itself — no new mechanism is introduced. It is also bounded by a code constant (`LEARNINGS_INDEX_MAX_CHARS = 2000`, ~1.1% of the measured 178,095 B per-agent prompt baseline) with no `0 = unlimited` sentinel, so it cannot grow into the corpus it indexes.
+
+**An INDEX, not a corpus.** One line per learning plus a retrieval pointer; an agent that needs a full entry greps it by subject. Measured: 12 entries in this form = 1,469 B.
+
+**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` — `<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`:
+
+    LEARNINGS_INDEX="$(node "$PLUGIN_ROOT/scripts/print-learnings-index.mjs" \
+      --file-scope "$AGENT_FILESCOPE_JSON" \
+      --task-text "<the agent's task title / one-line description>" 2>/dev/null)"
+
+`--task-text` is optional and feeds the token axis of the affinity primitive; omitting it yields path-only ranking. **Resolution ladder** (mirrors Grounding Injection `:309`): the agent's own `--file-scope` → the wave-level `allowedPaths` from `.claude/wave-scope.json` (automatic fallback when the agent has no declared "Files:" scope) → empty scope, in which case only the general tier is selected. Caps are `--max-scoped` (default 8) and `--max-global` (default 4) — **split, never shared**, so the general tier can never crowd out the per-agent signal.
+
+**Prompt assembly:** when `$LEARNINGS_INDEX` is non-empty, prepend it to THAT agent's prompt:
+
+    <LEARNINGS-INDEX>
+    $LEARNINGS_INDEX
+    </LEARNINGS-INDEX>
+
+    <original prompt>
+
+When it is empty (no corpus, no qualifying entries, or any CLI failure), dispatch that agent unchanged — the prompt is then byte-identical to the legacy one.
+
+**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.
@@ -667,29 +717,6 @@ Per attempt:
 See `SKILL.md` § "Inter-Wave Quality-Gate (with Auto-Fix Loop — #521)" for
 the full invocation pattern.
 
-##### /goal Continuation Anchor (opt-in — #636)
-
-> Advisory-only continuation anchor at the inter-wave fix-loop seam. Never auto-invokes `/goal`, never blocks forward progress. `/goal` is a user slash-command; the operator decides whether to use it.
-
-**Gate conditions** — ALL must be true for this nudge to surface:
-
-1. `goal-integration.enabled: true` in Session Config (default: `false`).
-2. `inter-wave-fixloop` is listed in `goal-integration.seams`.
-
-When any gate condition is false, skip this step entirely — proceed to `##### STATE.md Deviation — Auto-Fix Result`.
-
-**What it does** — when the gate fires and the inter-wave Quality-Gate is failing (auto-fix retries in flight or about to begin), surface ONE suggested `/goal` command as an advisory bullet in the wave progress update. Example:
-
-```
-/goal Keep fixing Wave <N> quality-gate failures until 'npm run lint', 'npm run typecheck' and 'npm test' each print 0 failures in this turn's output, or stop after <max-retries+1> attempts.
-```
-
-**Advisory-only contract:** the `/goal` is the continuation anchor that keeps the coordinator working across turns while it iterates on the fix. The exit-code result of `runQualityGateWithRetry()` stays the judgment — `/goal` continues the loop, it never decides correctness. The hard-abort + diagnostics-bundle path (`.orchestrator/metrics/verification-failures/<ts>.json` after `max-retries`) is UNCHANGED: an active `/goal` does not extend, replace, or bypass the bounded retry ceiling. This step is informational prose only — no AskUserQuestion, no STATE.md write, no sidecar.
-
-The `/goal` evaluator reads the transcript only and runs NO tools — it anchors CONTINUATION, never JUDGMENT. The suggested condition therefore references freshly-run gate output "in this turn's output" and embeds a bound ("or stop after N attempts"). Cross-reference `.claude/rules/loop-and-monitor.md § LM-008` for the full `/goal` continuation-vs-judgment contract rather than restating it here.
-
-**One goal per session:** only ONE `/goal` can be active at a time. This inter-wave fix-loop seam and the session-end backlog seam (`skills/session-end/SKILL.md` § 1.3a) cannot both hold an active goal simultaneously — the operator picks one.
-
 ##### STATE.md Deviation — Auto-Fix Result
 
 After `runQualityGateWithRetry()` returns:
@@ -1037,53 +1064,6 @@ When the hook is skipped (gate condition false), omit the `persona_gate` field e
 
 **Motivating example:** a flagship product's W5 Buyer-Panel pattern (six buyer personas at `hard-gate-threshold` `6-of-6`, `mode: 'strict'`, `after: 'quality'`) — UI work is gate-checked against every persona before commit, abort on any dissent. See `docs/session-config-reference.md § Persona-Gate Wave (#458)` and `commands/persona-panel.md` for the standalone CLI equivalent.
 
-### 3c. Strategic Compact-Nudge (#620)
-
-> Advisory-only checkpoint. Never auto-compacts. `/compact` is a user slash-command; the coordinator/operator decides when to invoke it.
-
-**Gate conditions** — ALL must be true for the nudge to emit:
-
-1. `compact-nudge.enabled: true` in Session Config (default: `false`).
-2. The just-completed wave's role is listed in `compact-nudge.after` (default: `['discovery', 'impl']`). Compare the wave's canonical role string (lower-case) against the list.
-3. `compact-nudge.mode !== 'off'` (when `mode: 'off'` the nudge is a silent no-op even when `enabled: true`).
-
-When any gate condition is false, skip this step entirely — proceed to `### 4. Progress Update`.
-
-**Nudge format** — when the gate fires, append ONE advisory bullet to the wave progress update (step `### 4`):
-
-```
-- 💡 Compact checkpoint: Wave N (<Role>) complete — consider /compact before Wave N+1 (<NextRole>) to free context (advisory only; see decision table). Never auto-compacts.
-```
-
-**What survives `/compact` vs what is lost:**
-
-| Survives | Lost |
-|---|---|
-| CLAUDE.md, STATE.md (on disk), wave-scope.json, JSONL metrics (.orchestrator/), git history, all files on disk | Intermediate reasoning/thinking traces, previously-read file contents cached in context, tool-call history for prior waves |
-
-This frames the nudge: the persistent artefacts (plan, scope, STATE.md, git diff) are the distilled output of completed work; losing in-context file reads is the cost. Compact is worth it when the completed wave produced bulky research/audit output that is unlikely to be re-referenced verbatim.
-
-**Decision table:**
-
-| Wave boundary (completed → next) | Compact? | Why |
-|---|---|---|
-| Discovery → Impl-Core | Yes — **but only after** Discovery's repo-state facts are written into the plan in annotated form (value + measurement command + `measured_at`) | Research/audit context is bulky and the plan + wave-scope.json is the distilled output. But compacting discards the raw evidence and leaves the briefing text as the only source of truth — the structural amplifier of the #908 damage. Un-annotated facts: re-measure or record them first, else **No**. See Pre-Dispatch: Fact-Staleness Annotation. |
-| Impl-Core → Impl-Polish (long Core) | Maybe | Compact only if Polish targets different files; keep if Polish builds on Core's changes. |
-| Impl-Polish → Quality | No | Quality references the just-written code; losing it is costly. |
-| Quality → Finalization | No | Finalization needs the full session diff. |
-| Mid-implementation (within a wave) | No | Losing file paths + partial state is expensive. |
-| After a FAILED/aborted wave | Yes | Clear the dead-end reasoning before the adapted retry. |
-| Switching to an unrelated task block (deep session) | Yes | Debug/exploration traces pollute unrelated downstream work. |
-
-**Behaviour by mode:**
-
-| `mode` | Action |
-|--------|--------|
-| `off` | No nudge (gate condition above). |
-| `warn` | Emit the advisory bullet in the wave progress update. Coordinator/operator acts at their discretion. |
-
-The nudge is informational only — no AskUserQuestion, no state-md write, no sidecar. This step never blocks forward progress.
-
 ### 4. Progress Update
 
 After each wave, provide a brief status:
@@ -1134,19 +1114,34 @@ 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 per-agent scope files — never hand-transcribed (#1020).** Transcribing the union by hand produced 5 scope divergences in ONE session. Three steps, in this order; none of them is a judgement call. 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 — one file per agent.** Write each agent's "Files:" scope from the session plan, verbatim, as a JSON array of strings to `<state-dir>/filescopes/wave-<N>/<agent-id>.json`. That path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and the File-Scope Injection (#1020) already consume. Do not write a second copy anywhere, and **never to a `$TMPDIR` temp path**: the injector and `hooks/pre-task-scope-disjoint.mjs` need an addressable, wave-keyed location that a temp file cannot be. Reading `$AGENT_FILESCOPE_JSON` as "some temp file" is the one failure that costs no error — the injector finds nothing, no `FILE-SCOPE` block reaches the prompt, `extractScopeFromPrompt` returns `[]`, and the dispatch is ALLOWed exactly as it was before #1020, signal-free. The coordinator's OWN planned direct edits go into `<state-dir>/filescopes/wave-<N>/coordinator.json` in the identical form and take part in both steps below: 2 of those 5 divergences were coordinator-direct edits, for which no agent scope file exists by construction, and the commit guard caught them only at the commit boundary.
 
-   ```js
-   import { expandTestSiblings } from '$PLUGIN_ROOT/scripts/lib/scope-gate.mjs';
+   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs BEFORE the union of 3.3 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.
+
+   **3.2 — assert disjointness BEFORE computing the union.** Build the sidecar — an ARRAY of `{id, files}` records (never an object map: a duplicated agent id must stay visible), one record per file written in 3.1, `coordinator.json` included — and 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, rewrite the affected 3.1 files, 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.
 
-   // 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.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.
+
+   **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.
@@ -1158,11 +1153,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" \
@@ -1193,4 +1188,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.