session-orchestrator 3.19.0 → 3.21.0

package/docs/instruction-delivery.md

@@ -415,6 +415,337 @@ appears.
 
 ---
 
+## 7. The learnings index is not a second delivery path (GitLab #1014)
+
+> Measured **2026-08-13** at commit `c87102b`, branch `feat/memory-pipeline-1015-1014-1016`.
+> `.claude/rules/` and `CLAUDE.md` were **clean at HEAD** for every measurement below
+> (`git status --porcelain -- .claude/rules CLAUDE.md` → 0 lines); the dirty paths in the
+> working tree were sibling agents' `scripts/` and `tests/` files, none of which this
+> section measures.
+
+§5 recommends against building a second delivery path, because injecting a scoped rule
+block alongside undiminished native loading costs **+72%**. Issue #1014 then shipped an
+injected block. This section exists to answer the obvious question — *is the learnings
+index the thing §5 forbids?* — with numbers rather than with an assurance.
+
+**It is not, by a factor of 92.** The forbidden path re-sends 122,875 bytes the agent is
+already receiving. The index sends **1,405–1,727 bytes the agent receives nowhere else**:
+**+0.79% to +0.97%** of the re-measured baseline.
+
+> **⚠ Amendment, 2026-08-13 — every byte figure in §7 below is PRE-FRAMING.**
+>
+> §7 was measured at `c87102b`. A review panel then found that this block shipped
+> agent-authored text with none of the neutralisation `<APPLICABLE-RULES>` had received in
+> the same session — no fence, no wrapper-forgery rejection, no invisible-character
+> stripping. The fix added a content-derived block fence and a framing preamble, at a
+> **constant +320 B** independent of entry count.
+>
+> Re-measured by the coordinator after the fix (2 scopes, `wc -c` on the real CLI):
+> `scripts/lib/reconcile/**` → **2,047 B** (was 1,727); `docs/**` → **1,234 B** (was 914).
+>
+> | | §7 as measured | after framing |
+> |---|---:|---:|
+> | band | 912–1,727 B | **1,234–2,047 B** |
+> | share of the 178,096 B baseline | +0.51% – +0.97% | **+0.69% – +1.15%** |
+> | ceiling (entry caps lifted) | 2,221 B / +1.25% | **2,541 B / +1.43%** |
+>
+> The 92× argument is unaffected — the comparison is against +122,875 B, and +320 B does not
+> move it. `LEARNINGS_INDEX_MAX_CHARS = 2000` is likewise untouched: the framing sits outside
+> the capped body, as the header and retrieval pointer already did.
+>
+> The per-scope table in §7.2 and the figures in §7.4 are left at their measured values rather
+> than overwritten, so each keeps the SHA it was taken at. Read them as pre-framing.
+
+### 7.1 The baseline, re-measured — and it did not drift
+
+The wave-1 baseline was captured at `0fbea29`. Re-measuring at `c87102b` (3 commits later,
+`git rev-list --count 0fbea29..HEAD` → `3`) gives a **byte-identical** rule corpus:
+
+```console
+$ find .claude/rules -name '*.md' | wc -l
+29
+$ find .claude/rules -name '*.md' -exec cat {} + | wc -c
+165097
+$ wc -c CLAUDE.md
+9666
+$ wc -c ~/.claude/CLAUDE.md
+1220
+$ sed -n '266,286p' skills/wave-executor/SKILL.md | wc -c   # the fenced memory.propose block
+2113
+```
+
+| Component | Bytes @ `0fbea29` | Bytes @ `c87102b` | Drift | Fires |
+|---|---:|---:|---:|---|
+| `.claude/rules/**` (29 files) | 165,097 | 165,097 | 0 | every agent, native project-instruction loading |
+| `CLAUDE.md` / `AGENTS.md` (root) | 9,666 | 9,666 | 0 | every agent |
+| `~/.claude/CLAUDE.md` (user-level) | 1,220 | 1,220 | 0 | every agent on this host, outside repo control |
+| `memory.propose` boilerplate | 2,112 | **2,113** | +1 | every Impl-Core / Impl-Polish / Quality agent |
+| **TOTAL** | **178,095** | **178,096** | **+1** | per Impl-wave agent, before task text |
+
+The corpus figures are reproducible from the git object store rather than from the working
+tree, which is what makes the zero-drift claim checkable:
+
+```console
+$ git ls-tree -r --name-only 0fbea29 -- .claude/rules | grep '\.md$' \
+    | while read f; do git cat-file blob "0fbea29:$f"; done | wc -c
+165097
+```
+
+The single byte is the boilerplate's trailing newline: the block is lines 266–286 of
+`skills/wave-executor/SKILL.md`, and wave 1 evidently measured it without the final `\n`.
+Recording it rather than rounding it away is the point — a figure that reproduces to ±1
+byte across two SHAs is a measurement; one that "matches" is an assertion.
+
+**The rules corpus did not change this session.** The 100-record learnings corpus did. Those
+are different corpora, and only the second one is what §7 adds.
+
+### 7.2 What the index actually costs, per scope
+
+Four **disjoint** agent file scopes, each naming real tracked files
+(`git ls-files --error-unmatch` → TRACKED for all eight paths):
+
+```console
+$ echo '["hooks/pre-bash-destructive-guard.mjs","hooks/on-session-start.mjs"]' > /tmp/scope-hooks.json
+$ node scripts/print-learnings-index.mjs --file-scope /tmp/scope-hooks.json --no-event | wc -c
+1405
+$ node scripts/print-learnings-index.mjs --file-scope /tmp/scope-hooks.json --no-event --json   # count + scopeMatched
+```
+
+| Agent file scope | Bytes | Entries | Scoped | Global fill | % of 178,096 |
+|---|---:|---:|---:|---:|---:|
+| `hooks/**` (2 files) | 1,405 | 7 | 3 | 4 | +0.789% |
+| `scripts/lib/reconcile/**` (2 files) | 1,727 | 9 | 5 | 4 | +0.970% |
+| `tests/**` (2 files) | 912 | 4 | 0 | 4 | +0.512% |
+| `docs/**` (2 files — this agent's own scope) | 914 | 4 | 0 | 4 | +0.513% |
+| *control:* `tests/**` naming two paths the corpus does carry | 1,240 | 6 | 2 | 4 | +0.696% |
+
+The corpus behind these numbers, measured rather than quoted:
+
+```console
+$ wc -l < .orchestrator/metrics/learnings.jsonl
+100
+$ node -e '…JSON.parse each line; count Array.isArray(r.file_paths) && r.file_paths.length>0…'
+total=100 with_file_paths=17 pct=17.0%
+```
+
+**17 of 100 records carry `file_paths`.** That fraction, not the CLI, is what governs the
+scoped column — and the `tests/**` row is the honest demonstration. It returned **0 scoped
+matches** even though the corpus holds 6 `tests/` path entries, because those 6 name
+different files (`tests/lib/session-registry.test.mjs`,
+`tests/scripts/gates/gate-helpers.test.mjs`, …) than the two a plausible agent declared.
+The control row re-runs the same scope against two paths the corpus *does* carry and
+recovers 2 scoped matches. Matching is exact-path; the 0 is correct behaviour, not a defect.
+
+The practical reading: **at 17% `file_paths` coverage, a majority of scopes will fall back
+entirely to the global fill.** The index degrades to "top 4 general learnings" rather than
+to nothing, which is the right failure mode, but it is not yet per-agent for most agents.
+The lever is `--file-paths` adoption at proposal time, not the selector.
+
+### 7.3 The delta, and the comparison that settles the question
+
+Absolute: **+912 to +1,727 bytes**, ceiling **+2,221** (§7.4). As a share of the
+re-measured 178,096-byte baseline: **+0.51% to +0.97%**, ceiling **+1.25%**.
+
+| Path | Added bytes | As % of baseline |
+|---|---:|---:|
+| §5's forbidden path — scoped rule block alongside native delivery | +122,875 | **+72.3%** |
+| §7's learnings index — measured worst case of four scopes | +1,727 | **+0.97%** |
+
+**92×.** Two structural facts produce that gap, and each is checkable:
+
+1. **It rides a channel the repo already writes itself.** The index is prepended to the
+   dispatch prompt — the same channel that already carries the task text and the 2,113-byte
+   `memory.propose` boilerplate. It does not add a delivery mechanism; it adds a block to a
+   prompt the coordinator was already composing. §5's +72% is entirely the cost of
+   *duplicating* a channel that keeps delivering regardless.
+2. **Learnings have no native delivery to duplicate.** `.orchestrator/metrics/learnings.jsonl`
+   is not a `.md` file under `.claude/rules/`, and neither `CLAUDE.md` nor its Codex-CLI
+   alias `AGENTS.md` imports it (`grep -c "^@" CLAUDE.md` → `0`, unchanged from §1). Nothing
+   in the 178,096-byte baseline carries this content. The index is the *first* delivery of
+   it, not the second.
+
+#### 7.3.1 …except for 13 records, and the index does not exclude them
+
+Fact 2 is true of the corpus but not of every record in it. `/reconcile` converts qualifying
+learnings into `.claude/rules/*.md` files — which **are** natively delivered. Those rules
+carry their source in provenance, so the overlap is measurable:
+
+```console
+$ grep -rlha "learning-id:" .claude/rules/*.md | wc -l
+13
+$ grep -rha "^- learning-id:" .claude/rules/*.md | sed 's/.*`\(.*\)`.*/\1/' > /tmp/rule-lids.txt
+$ # then: for each scope, intersect the index's learning ids with /tmp/rule-lids.txt
+hooks:   entries=7 already_a_rule=1
+scripts: entries=9 already_a_rule=0
+tests:   entries=4 already_a_rule=0
+docs:    entries=4 already_a_rule=1
+```
+
+**13 of 100 learnings have already become natively-delivered rules, and the selector does
+not filter them out.** In two of four scopes, one indexed entry was content the agent was
+already receiving in full — a genuine, if small, second delivery of that record. The
+duplicated unit is one ~150-byte index line against a multi-KB rule file, so the waste is
+bounded and far below the measurement noise of §7.1; it does not change the +0.97% figure
+or the 92× conclusion. But it is a real instance of the exact pattern §5 forbids, found by
+looking for it, and it is cheap to close: the selector has each record's id and the rule
+files carry theirs. **Filed as a follow-up rather than fixed here — this section's file
+scope is documentation, and the fix is a change to `scripts/lib/learnings/select.mjs`.**
+
+### 7.4 The 2,000-character cap is slack; the entry-count caps bind
+
+`LEARNINGS_INDEX_MAX_CHARS = 2000` (`scripts/lib/learnings/select.mjs:89`) is a hard cap on
+the rendered **body**. Under the shipped defaults it is never reached:
+
+```console
+$ node scripts/print-learnings-index.mjs --file-scope /tmp/scope-hooks.json --no-event | wc -c
+1405
+$ node scripts/print-learnings-index.mjs --file-scope /tmp/scope-hooks.json --no-event \
+    --max-scoped 100 --max-global 100 | wc -c
+2221
+$ node scripts/print-learnings-index.mjs --file-scope /tmp/scope-hooks.json --no-event \
+    --max-scoped 100 --max-global 100 --max-chars 100000 | wc -c
+15588
+```
+
+| Constraint | Result | Binds? |
+|---|---:|---|
+| default caps (8 scoped / 4 global / 2,000 chars) | 1,405–1,727 B | entry caps bind |
+| entry caps lifted, char cap at 2,000 | 2,221 B | **char cap binds** |
+| both lifted (whole corpus as an index) | 15,588 B | nothing binds |
+
+The binding constraint under defaults is **`--max-global 4`**, not the char cap. The
+telemetry's `truncated: true` says so precisely: it is set at `select.mjs:389` by
+`scoped.length > maxScoped || global.length > maxGlobal` — an **entry-count** overflow, not
+a character overflow. Reading `truncated: true` on a 1,405-byte block as "the 2,000 cap bit"
+would be wrong.
+
+Slack, stated plainly: **816 bytes of body headroom on the `hooks` scope, 494 on `scripts`**
+(the rendered block carries a 221-byte header outside the capped body, which is why the
+lifted-caps run reports 2,221 rather than 2,000). The cap is a backstop against a corpus
+that grows an order of magnitude — at 100 records it never fires. The number that would
+make it fire is 15,588: the whole corpus rendered as an index is **7.8×** the cap, so the
+cap is doing real work as a ceiling even while slack today.
+
+### 7.5 The per-agent claim, verified empirically
+
+Not read off the code — run, on two disjoint scopes, comparing the emitted subjects:
+
+```console
+$ # hooks scope
+## Learnings Index (selected for your file scope)
+
+7 entries (3 matched your declared file scope, 4 general). One line each — this is an INDEX, not the corpus.
+Full text of any line: `grep -F '"subject":"<subject>"' .orchestrator/metrics/learnings.jsonl`
+
+- anti-pattern/an inline @returns-never warn helper at a rule-loop warn site flips a later block to ALLOW: …
+- anti-pattern/policy rule with a new type field must ship with its consuming hook branch in the same change: …
+- anti-pattern/release() proof gate hinges on proof !== undefined — every call site must spread-guard: …
+[4 more]
+
+$ # scripts scope
+## Learnings Index (selected for your file scope)
+
+9 entries (5 matched your declared file scope, 4 general). One line each — this is an INDEX, not the corpus.
+Full text of any line: `grep -F '"subject":"<subject>"' .orchestrator/metrics/learnings.jsonl`
+
+- anti-pattern/A hardcoded expected value that coincides with a clamp/floor for one day is a green that proves nothing: …
+- proven-pattern/security-floor policy loaders must merge, not first-hit-resolve: …
+- recurring-issue/Eine Session ohne durchgelaufenes /close hinterlaesst unpushed Commits …
+[6 more]
+```
+
+Set-compared rather than eyeballed:
+
+```console
+$ # intersect the two --json subject lists
+hooks entries: 7 | scripts entries: 9
+intersection: 2 | hooks-only: 5 | scripts-only: 7 | Jaccard: 0.143
+```
+
+**Two disjoint scopes share 2 of 14 distinct entries (Jaccard 0.143).** Both shared entries
+are global fill; the scoped selections are fully disjoint. The block is genuinely
+per-agent, not a constant wearing a scope's name — which is the claim §3.1 could *not* make
+about glob-scoped rules, where the "scoped" saving turned out to be a constant 40,254 bytes
+of tier filtering.
+
+### 7.6 The telemetry answers "did the injector ever run?"
+
+§1 could establish that `rule-loader.mjs` does not run at delivery time only by grepping for
+the absence of a caller. That is an argument from silence, and §1.2 records how it failed:
+a census keyed on the payload missed the prose call site entirely. The index does not
+require that argument — it emits an event:
+
+```console
+$ grep -ac 'orchestrator.learnings.index.injected' .orchestrator/metrics/events.jsonl
+1
+$ node scripts/print-learnings-index.mjs --file-scope /tmp/scope-hooks.json > /dev/null
+$ grep -ac 'orchestrator.learnings.index.injected' .orchestrator/metrics/events.jsonl
+2
+$ grep -a 'orchestrator.learnings.index.injected' .orchestrator/metrics/events.jsonl | tail -1
+{
+ "timestamp": "2026-08-13T05:53:29.824Z",
+ "event": "orchestrator.learnings.index.injected",
+ "count": 7,
+ "scope_matched": 3,
+ "global_count": 4,
+ "candidates": 94,
+ "truncated": true,
+ "bytes": 1405,
+ "scope_source": "file-scope"
+}
+```
+
+The counter moves 1 → 2 on one invocation, and the record's `bytes: 1405` is independently
+equal to this section's `wc -c`. "Did it run, on what scope, and how big was it" is now a
+`grep` over `events.jsonl` instead of an inference. `candidates: 94` also shows the pool is
+the 94 *active* records of the 100 on disk — 6 are filtered before ranking.
+
+### 7.7 What is NOT established — explicitly unbelegt
+
+Four gaps. Each would move the denominator, and none is closed by anything above.
+
+- **Whether this Claude Code build loads a root `AGENTS.md`.** One exists on disk —
+  `ls -la AGENTS.md` → 14,661 bytes, **untracked** (`git ls-files AGENTS.md | wc -l` → `0`).
+  The coordinator of this session confirmed from its own context window that it is *not*
+  delivered to the coordinator. **Whether a dispatched subagent receives it is unverified**,
+  and this agent cannot settle it: a subagent introspecting its own context is the
+  self-report §1.1 already flagged as corroborating-not-load-bearing. If subagents do
+  receive it, the baseline is 192,757 rather than 178,096 and the index's share *falls* to
+  +0.73%. Tracked as issue **#973**.
+- **Whether the `<APPLICABLE-RULES>` block fires in practice.** `wave-loop.md` makes the
+  pre-dispatch injection a SHOULD, not a gate. In **this** session it was deliberately
+  skipped and logged as a deviation, so the 178,096 figure **excludes it**. If it fires, the
+  denominator grows by up to the 122,875 bytes §3 measured for a live wave scope and the
+  index's share falls correspondingly — to roughly +0.57%. Every percentage in §7.3 is
+  therefore a *conservative* upper bound on the index's share: the honest reading is
+  "≤1% under the smallest defensible denominator".
+- **Whether 17% `file_paths` coverage is representative.** It is the coverage of a 100-record
+  corpus, 11 of whose records were recovered from a data-loss incident. Whether the recovered
+  records are systematically poorer in `file_paths` than organically-proposed ones was not
+  measured, and it would bias the scoped column if so.
+- **Whether the §7.3.1 rule/learning overlap grows.** Measured once, at 13/100, on four
+  scopes. `/reconcile` promotes learnings into rules continuously, so this ratio rises by
+  construction. Nothing currently measures it on a schedule.
+
+### 7.8 Correction to §1.3
+
+§1.3 records a second delivery source outside this repo — the parent workspace's
+`.claude/rules/parallel-sessions.md`, 5,623 bytes — and concludes the real delivered corpus
+is 175,584 rather than 169,961. **That file no longer exists on this host:**
+
+```console
+$ ls -la "$(dirname "$PWD")"/.claude/rules/
+ls: /Users/…/Projects/.claude/rules/: No such file or directory
+```
+
+§7's baseline therefore does not carry a parent-workspace term. This is a host-local
+observation about one machine at one date, not proof the mechanism is gone — the directory
+could be recreated at any time, and §1.3's structural point (that
+`print-applicable-rules.mjs` reads only `<repoRoot>/.claude/rules` and cannot see such a
+file) stands unchanged.
+
+---
+
 ## Reproducing this document
 
 ```bash
@@ -434,6 +765,23 @@ node scripts/print-applicable-rules.mjs --wave-scope /tmp/scope.json | wc -c   #
 
 # blast radius
 git grep -l "\.claude/rules/" | wc -l
+
+# §7 — baseline re-measure, reproducible from the object store at any SHA
+git ls-tree -r --name-only <sha> -- .claude/rules | grep '\.md$' \
+  | while read f; do git cat-file blob "<sha>:$f"; done | wc -c
+sed -n '266,286p' skills/wave-executor/SKILL.md | wc -c   # memory.propose boilerplate
+
+# §7 — the learnings index for one agent scope (never writes; --no-event suppresses telemetry)
+echo '["hooks/on-session-start.mjs"]' > /tmp/scope.json
+node scripts/print-learnings-index.mjs --file-scope /tmp/scope.json --no-event | wc -c
+node scripts/print-learnings-index.mjs --file-scope /tmp/scope.json --no-event --json
+
+# §7.4 — which cap binds
+node scripts/print-learnings-index.mjs --file-scope /tmp/scope.json --no-event \
+  --max-scoped 100 --max-global 100 --max-chars 100000 | wc -c
+
+# §7.6 — did the injector run?
+grep -ac 'orchestrator.learnings.index.injected' .orchestrator/metrics/events.jsonl
 ```
 
 ## See also
@@ -442,3 +790,5 @@ git grep -l "\.claude/rules/" | wc -l
 - `scripts/print-applicable-rules.mjs` — the CLI bridge; reads only `<repoRoot>/.claude/rules`
 - `scripts/lib/instruction-budget-guard.mjs` — the existing measurement + ceiling instrument
 - `docs/rule-authoring.md` — frontmatter contract (and the stale claim at line 8)
+- `scripts/print-learnings-index.mjs` — §7's per-agent index CLI; emits `orchestrator.learnings.index.injected`
+- `scripts/lib/learnings/select.mjs` — the selector; `LEARNINGS_INDEX_MAX_CHARS = 2000` at line 89, `truncated` at line 389

package/docs/migration-v3.md

@@ -32,12 +32,15 @@ Optional but recommended:
 ### 3a. Claude Code
 
 ```bash
-# 1. Pull the latest plugin
-cd "$(claude plugin dir session-orchestrator 2>/dev/null || echo ~/.claude/plugins/session-orchestrator)"
-git pull
-
-# 2. Install Node dependencies
-npm install
+# 1. Update the plugin — run this INSIDE Claude Code, not in a shell:
+#      /plugin update session-orchestrator@kanevry
+#    A marketplace-installed plugin lives in a managed cache, not in a git checkout,
+#    so `git pull` does not apply to it.
+
+# 2. Install Node dependencies. Claude Code has no `plugin dir` subcommand,
+#    so resolve the install path from the cache:
+SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
+cd "$SO_DIR" && npm install
 
 # 3. Restart Claude Code so hooks.json is re-read
 ```

package/docs/persona-panel.md

@@ -33,7 +33,9 @@ mkdir -p .claude/personas
 Templates ship with the plugin at `templates/personas/`. Copy one as a starting point:
 
 ```bash
-cp "$(claude plugin dir session-orchestrator)/templates/personas/klima-physicist.v1.md" \
+# Claude Code has no `plugin dir` subcommand — resolve the install path from the cache.
+SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
+cp "$SO_DIR/templates/personas/klima-physicist.v1.md" \
    .claude/personas/klima-physicist.md
 ```
 

package/docs/scope-collision-guard.md

@@ -0,0 +1,167 @@
+# Scope-Collision Guard — Pre-Dispatch File-Scope Deconfliction
+
+> Reference for the mechanism that stops a wave from handing the SAME file to two agents (issue #1020).
+> Four moving parts: the per-agent scope files, `scripts/validate-wave-scope.mjs` (`--assert-disjoint` / `--union`), `findScopeCollisions()` + `unionFileScopes()` in [`scripts/lib/scope-gate.mjs`](../scripts/lib/scope-gate.mjs), and the `PreToolUse` hook [`hooks/pre-task-scope-disjoint.mjs`](../hooks/pre-task-scope-disjoint.mjs).
+> The coordinator-side **runbook** is `skills/wave-executor/wave-loop.md` § Scope Manifest 3.1–3.3 — this document does not restate it. What lives here instead: how the mechanism works, how it fails, what it deliberately does not see, and how to debug it.
+
+## 1. What the pre-existing gates could not see
+
+`assertFileScopeSubset()` (#796) checks each agent's scope **⊆** the wave's `allowedPaths` union, and `wave-scope-commit-guard` checks writes against that same union. A file claimed by two agents is a subset **twice over**, and the union grants it exactly once — so a double assignment is structurally invisible to both. It surfaced only afterwards, from an agent's own PSA-002 report (`findScopeCollisions()` header: `tests/scripts/sweep-expired-learnings-cli.test.mjs` handed to two agents of one wave). Per `.claude/rules/parallel-sessions.md` § Decision Tree, a file inside two declared scopes of one dispatch round is never a benign sibling signal — it is a deconfliction gap.
+
+Two things follow, and both are the point of #1020:
+
+- `allowedPaths` is **computed** from the per-agent declarations (`unionFileScopes()`), not transcribed by hand.
+- Disjointness is asserted on the **declarations**, before the union exists.
+
+## 2. The chain, in order
+
+| # | Step | Artefact | Mechanism |
+|---|------|----------|-----------|
+| 1 | Declare | `<state-dir>/filescopes/wave-<N>/<agent-id>.json` (one per agent, plus `coordinator.json`) | written verbatim from the session plan |
+| 2 | Assert disjointness | the sidecar array `[{id, files}, …]` | `validate-wave-scope.mjs --assert-disjoint` → `findScopeCollisions()` |
+| 3 | Compute the union | stdout of `--union` → `allowedPaths` | `expandTestSiblings(unionFileScopes(scopes), { role })` |
+| 4 | Inject | `FILE-SCOPE — exactly these:` + a fenced block in each agent prompt | the per-agent file from step 1 |
+| 5 | Dispatch | `.orchestrator/wave-dispatch-scopes.json` (ledger) | `hooks/pre-task-scope-disjoint.mjs`, `PreToolUse` matcher `Agent` |
+
+`<state-dir>` is the first of `.pi` / `.cursor` / `.codex` / `.claude` that carries a `wave-scope.json` — the same precedence `findScopeFile()` and the hook's `waveKeyOf()` use.
+
+### 2.1 Why `--union` runs last
+
+A union computed over colliding scopes **launders the defect into the artefact meant to prevent it**: `allowedPaths` then grants the contested file, and every later gate — `--assert-subset`, `enforce-scope` Gate 7, the commit guard — sees a perfectly legal write. `validate()` in `validate-wave-scope.mjs` enforces the order in code: `--assert-subset` → `--assert-disjoint` → `--union`, and `--union` returns early because it is a QUERY MODE that replaces the manifest echo on stdout.
+
+The same ordering argument applies one level up: step 2 runs on the **declared** scopes, before step 3 expands test siblings. See § 6 for the limit that buys.
+
+### 2.2 Why the scope files are not temp files
+
+Steps 1, 2, 3, 4 and the `--assert-subset` assertion all read the *same* file, addressed by wave and agent id. A `$TMPDIR` copy is the one failure in this chain that **costs no error**: the injector finds nothing, no `FILE-SCOPE` block reaches the prompt, `extractScopeFromPrompt()` returns `[]`, and the hook allows the dispatch exactly as it did before #1020 — signal-free (matrix rows 5/6 below). The scope files are control state like `wave-scope.json` itself, never a wave territory; writing them legitimately trips `bash-write-verify` once per wave rollover, and widening `allowedPaths` to silence that would grant agents write access to the deconfliction record.
+
+The coordinator's **own** planned direct edits belong in `coordinator.json` in the identical form. They are not dispatches, so the hook can never see them (§ 6); the CLI check is the only gate that covers them.
+
+## 3. The collision algorithm
+
+`findScopeCollisions(agentScopes, { knownFiles })` compares every cross-agent entry pair through `classifyEntryCollision()`, in three binding stages:
+
+1. **Exact string equality** → kind `concrete`. The commonest real case, and the only stage that works for a file that **does not exist yet**.
+2. **Concrete vs glob** via `pathMatchesPattern(concrete, glob)` → kind `concrete`. Exact and I/O-free. Two *distinct concrete* paths are disjoint and return immediately.
+3. **Glob ∩ glob**, in two sub-stages:
+   - **3a — witness:** expand both entries against `KNOWN = knownFiles ∪ {every concrete entry of every agent}`; a non-empty intersection is `glob-expanded`. The second half of that union matters — a file the wave is about to *create* is not in `git ls-files`, but a concrete claim by one agent can still witness another's glob.
+   - **3b — prefix fallback:** for the intersection that exists only in files not yet on disk. Requires literal-prefix containment in either direction, at least one **recursive** entry (`**`, or a trailing `/`, which `pathMatchesPattern` matches by `startsWith` at any depth), and compatible literal suffixes. The suffix filter is a necessary condition, so it adds no false negative while removing `scripts/**/*.ts` vs `scripts/**/*.mjs`.
+
+`knownFiles` is **injected, never discovered**: `scope-gate.mjs` is hook-safe (pure, sync, no I/O, no spawn) because `enforce-scope.mjs` reaches it on a hot path, and under the exit-0/stdout-JSON protocol a throw there reads as "no decision" = ALLOW. The CLI spawns `git ls-files` in `knownRepoFiles()`; the hook does the same in `listTrackedFiles()`, both resolving `git rev-parse --show-toplevel` first so a session started in a subdirectory produces repo-relative paths on both sides.
+
+Duplicate agent ids are reported separately (`duplicateIds`), not as a self-collision. A record with no usable id runs as `<unnamed#i>` rather than being dropped — an unreviewed scope is exactly the one that collides.
+
+### 3.1 Why `pathMatchesPattern` alone cannot do stage 3
+
+The matcher is **directed**: argument 2 is compiled into a regex, argument 1 is tested as a literal string. Measured in this working tree on 2026-08-14:
+
+```
+$ node --input-type=module -e "import { pathMatchesPattern } from './scripts/lib/scope-gate.mjs';
+  console.log(pathMatchesPattern('scripts/**/*.mjs','scripts/lib/*.mjs'));
+  console.log(pathMatchesPattern('scripts/lib/x.mjs','scripts/**/*.mjs'),
+              pathMatchesPattern('scripts/lib/x.mjs','scripts/lib/*.mjs'));"
+false
+true true
+```
+
+Both globs match `scripts/lib/x.mjs`, yet the direct comparison says `false`. For `assertFileScopeSubset()` that inexactness is *safe*: its glob branch reduces to verbatim presence plus literal-prefix coverage and therefore **over-approximates coverage**, which at worst accepts a union it could not fully prove. For a **collision** check the sign flips — the same over-approximation becomes a **false negative**, i.e. a missed collision, i.e. the incident. That is why the two exact stages decide first and stage 3 is reached only for pairs neither can settle.
+
+## 4. The hook
+
+`hooks/pre-task-scope-disjoint.mjs` is a `PreToolUse` hook on matcher **`Agent`** (registered in `hooks/hooks.json`). It blocks a wave from handing the same file to two agents at the moment of dispatch, before either has written a byte.
+
+It cannot compare a batch of siblings directly — the header records why, measured against 12 archived transcripts of this repo (147 dispatch `tool_use` blocks, 51 batches, measured 2026-08-14): the dispatch tool is named `Agent` and not `Task`; the payload carries **no** structured file scope (`files` / `file_scope` / `scope` → 441 probes, zero hits), so the scope exists only as prose inside `prompt`; and the not-yet-dispatched siblings of a batch are not visible in the transcript at dispatch time. What remains is a **ledger**: each dispatch records its scope under a wave key, and the next dispatch is checked against everything already recorded.
+
+- **Ledger:** `.orchestrator/wave-dispatch-scopes.json` (gitignored), keyed `<session-id>|w<wave>|<role>` from `<state-dir>/wave-scope.json`.
+- **Lock:** `.orchestrator/wave-dispatch-scopes.lock` — the read-modify-write cycle runs under `withFileLock()` (the primitive behind the PSA-005 STATE.md lock). `writeJsonAtomicSync` makes the write atomic, never the *cycle*.
+- **Scope extraction:** `extractScopeFromPrompt()` finds a scope marker line and takes the FIRST fenced block after it, accepting only lines that survive a deliberately strict `looksLikeRepoPath()`. `normalizeScopeEntry()` then folds `./`, `//` and `/./` spellings together, and `promoteDirEntries()` rewrites `scripts/lib` → `scripts/lib/` **on evidence** (not a tracked file itself, at least one tracked file beneath it) — both because two spellings of one path previously compared as disjoint.
+- **DENY** fires on exactly one condition: a collision involving THIS dispatch with a prior agent of the same wave that is **still in flight** (§ 5). The reason names the agent pair, the collision kind and the evidence paths; the suggestion is "give the file exactly ONE owner, or wait for the named agent(s) and re-dispatch", plus the ledger path to delete if the state is stale. The ledger is deliberately **not** persisted on a deny — the dispatch did not happen, so recording it would make the retry-after-fix look like a duplicate.
+
+### 4.1 Error-class matrix — deliberately fail-**open**
+
+The blast radius is asymmetric. A false positive on the dispatch path blocks every agent of the session — the guard becomes a session outage, and nothing downstream catches a dispatch that never happened. A false negative is a double assignment that three later gates still catch (`validate-wave-scope.mjs`, `enforce-scope.mjs` at write time, the W5 verification pass). Fail-closed is right for a WRITE guard (`enforce-scope.mjs` is), and wrong here. Each row is a choice, not an oversight:
+
+| # | Condition | Decision |
+|---|-----------|----------|
+| 1 | disabled via profile/env | exit 0, silent |
+| 2 | repo module failed to load | ALLOW + `GUARD INACTIVE` banner on stderr |
+| 3 | stdin empty / not JSON | ALLOW |
+| 4 | `tool_name` is not `Agent` | ALLOW |
+| 5 | prompt carries no scope marker | ALLOW |
+| 6 | scope block present but unparseable | ALLOW |
+| 7 | ledger unreadable / corrupt | WARN + ALLOW + **self-heal** (the verdict carries a fresh ledger) |
+| 8 | `git ls-files` failed | ALLOW, degraded (stage 3a loses witnesses; concrete collisions still found) |
+| 9 | `findScopeCollisions` not evaluable | WARN + ALLOW |
+| 10 | same agent id re-dispatched | ALLOW, ledger record replaced (a retry must not self-lock) |
+| 10a | collision, but every colliding prior agent has FINISHED | ALLOW + prune those records |
+| 11 | collision with a prior agent still IN FLIGHT | **DENY** |
+| 12 | unexpected throw in `main()` | ALLOW + stderr |
+| 13 | liveness probe throws / no evidence at all | treated as IN FLIGHT (bounded by the TTL, § 5) |
+| 14 | ledger lock not acquirable within its budget | run the cycle UNLOCKED (degraded), never deny |
+
+Two structural rules keep this matrix honest, both recorded in the hook header:
+
+- `decide()` is a **pure function returning a verdict**; the module emits exactly once, at the end. `emitWarn`/`emitDeny` call `process.exit(0)` and never return, so a warn emitted from inside the checking flow would terminate the process before a later collision could be denied — and would skip the lock's release `finally`.
+- Row 9's discriminator is **not** `ok !== true`. `ok` means *disjoint*, so `ok === false` is the normal result of a real collision; "not evaluable" is `ok === false` with BOTH result arrays empty. Reading `ok` as evaluability would turn every genuine collision into a warn, i.e. an allow — the exact fail-open the hook exists to prevent.
+
+## 5. The liveness probe
+
+A ledger with no notion of completion denies the wrong thing. Measured over 38 archived transcripts of this repo (346 `Agent` dispatch blocks; hook header, 2026-08-14): 0 of 4 same-batch overlaps and **2 of 2 cross-dispatch overlaps** would have been denied — and both cross-dispatch pairs were legitimate **sequential repair passes** (a dispatch and its later fix). Because a deny deliberately does not persist the ledger, the re-dispatch would have met the same stale record: a permanent block.
+
+The discriminator is therefore neither time nor the agent's name, but whether the recorded agent is **still in flight**. Two transcript shapes carry that:
+
+- **Synchronous dispatch** — the `tool_result` for the dispatch's `tool_use` id arrives when the agent is done (measured: five `Agent` rows within 0.44 s, their results 5–11 minutes later). At the fifth agent's `PreToolUse` none of the first four has a result → all in flight → a real same-batch overlap still denies.
+- **Asynchronous dispatch** — the `tool_result` arrives in ~0.2 s and reads `Async agent launched successfully`. **That text is a launch receipt, not a completion.** Treating it as one would let every real background-batch collision through. The completion arrives later as a `<task-notification>` record carrying `<tool-use-id>` and `<status>completed</status>` (measured: launch 14:14:26.768 → notification 14:24:39.360).
+
+`buildTranscriptIndex()` reads all three record shapes and counts a description as finished only when **every** one of its dispatch ids is finished. Cost containment: the transcript is read **only once a collision has already been found** — i.e. only on the path that is about to deny; the no-collision path pays nothing. Transcripts above 256 MiB are treated as *no evidence*, never as a completion.
+
+**Blind fallback and its named ceiling (BV-004).** With no transcript, or none carrying a record of that agent, liveness falls back to the ledger entry's own age with `IN_FLIGHT_TTL_MS = 30 min`. The ceiling is derived: the largest **measured** same-batch dispatch spread is 95.7 s, so 30 min is ~19× headroom against the false-ALLOW direction, while both measured sequential repair gaps (36 min, 49 min) sit above it. **Revisit trigger:** a same-batch spread above ~5 min appearing in `.orchestrator/metrics/`, or a harness change that stops writing `transcript_path` — either invalidates the headroom the number rests on.
+
+## 6. Named limits
+
+Complete list of what this guard does **not** see, or sees only approximately:
+
+1. **The blind TTL window.** Without transcript evidence the only liveness signal is the 30-minute TTL above. Inside that window a finished agent still blocks (false deny, recoverable by deleting the ledger); outside it a running agent no longer blocks (false allow). Revisit trigger as stated in § 5.
+2. **Test-sibling collisions.** Disjointness is asserted on the **declared** scopes (step 2), before `expandTestSiblings()` runs (step 3). Two agents whose production files share a basename receive the *same* emitted sibling glob (`tests/**/{basename}*.test.mjs`), which a declared-scope check cannot see. Revisit if a wave is ever scoped by basename family instead of by directory.
+3. **Prose extraction fails only toward ALLOW.** The hook's only channel is the `FILE-SCOPE` prose block. A missing marker, a missing fence, a decorated path that fails `looksLikeRepoPath()` — all resolve to allow (rows 5/6). Measured: 42 of 147 archived prompts (28.6 %) carried a scope marker at all, so denying the non-extractable case would have denied ~7 dispatches in 10. The CLI check (step 2) is the gate that does not depend on prose.
+4. **Coordinator-direct edits are invisible to the hook.** They are not dispatches, so no ledger entry exists for them. They participate in the CLI check via `coordinator.json` only — and 2 of the 5 divergences that motivated #1020 were coordinator-direct edits.
+5. **The wave-key fallback.** With no readable `wave-scope.json`, `waveKeyOf()` degrades to `<session>|w?|?` and the ledger spans the whole session, so a wave-3 dispatch is compared against wave-1 records. Bounded, not eliminated, by the liveness probe: a prior record binds only while its agent is in flight.
+6. **Glob ∩ glob without witnesses.** Stage 3a needs tracked files; with git unavailable (row 8) or for files not yet on disk, only stage 3b's prefix fallback carries the load — and it requires at least one recursive entry, so two non-recursive globs that intersect only in an unborn file are not detected.
+7. **Only collisions involving the current dispatch are actionable.** A pair among already-dispatched agents was either denied at its own dispatch or predates the guard; re-denying it would block an innocent third agent.
+8. **Lock loss reopens the race.** On lock timeout the cycle runs unlocked (row 14) — two dispatches starting together can then read the same ledger state and one record is lost. That is the pre-lock behaviour, chosen over denying on a lock-file problem.
+
+## 7. Debugging
+
+**A dispatch was denied and you do not believe it.** Read `.orchestrator/wave-dispatch-scopes.json`: it carries `waveKey`, `updated`, and one `{id, desc, files, at}` record per already-dispatched agent. The deny reason names the other agent — find its record and compare its `files` to the ones in your prompt's `FILE-SCOPE` block. Three outcomes:
+
+- The other agent is genuinely running and the overlap is real → fix the ownership in the session plan (one file, one agent), rewrite the affected `filescopes/wave-<N>/*.json`, re-assert, re-dispatch.
+- The other agent has finished, but the ledger still binds it → the transcript carried no evidence (§ 5) and you are inside the TTL window. Delete `.orchestrator/wave-dispatch-scopes.json`; the next dispatch rebuilds it.
+- The `waveKey` names an older wave → the `<session>|w?|?` fallback (limit 5). Check that `<state-dir>/wave-scope.json` exists and is readable, then delete the ledger.
+
+**A dispatch was NOT denied and should have been.** Work down the allow rows: is `FILE-SCOPE` present in the prompt with a fenced block right after it (rows 5/6)? Is the hook armed at all (`GUARD INACTIVE` on stderr = row 2)? Did a `systemMessage` warning appear (rows 7/9)? Cross-check the same scopes through the CLI, which does not depend on prose:
+
+```bash
+node scripts/validate-wave-scope.mjs --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
+```
+
+Exit 1 prints one `ERROR:` line per collision (`agents "A" and "B" both claim [...]`) and one per duplicate id. Exit 0 — nothing on stderr, the manifest echoed back on stdout — means the declared scopes really are disjoint and the hook was right to allow; the divergence is then in the prompt, not in the plan.
+
+**Reset.** Delete `.orchestrator/wave-dispatch-scopes.json` (and `.orchestrator/wave-dispatch-scopes.lock` if a dead holder is suspected). Both are gitignored, both are rebuilt on the next dispatch, and neither is shared with any other mechanism. After the final wave, `<state-dir>/filescopes/` is deleted along with `wave-scope.json` — a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified.
+
+**Disable.** The hook honours the repo's profile gate (`shouldRunHook('pre-task-scope-disjoint')`, row 1) — a silent exit 0, no decision at all.
+
+## 8. Provenance of the numbers
+
+Every figure above is quoted from a measurement recorded next to the code that carries it, with its date:
+
+- Transcript-shape figures (147 dispatch blocks / 12 transcripts / 51 batches / 441 zero-hit probes / 28.6 % marker coverage; 346 blocks / 38 transcripts for liveness; the 95.7 s, 36 min and 49 min spreads; the 0.44 s and 10-minute observations) — header of `hooks/pre-task-scope-disjoint.mjs`, measured 2026-08-14 against this project's archived transcripts.
+- The directedness transcript in § 3.1 — run in this working tree on 2026-08-14; the command is printed with it.
+
+Re-measure before citing any of these downstream. A count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006).
+
+## See Also
+
+- `skills/wave-executor/wave-loop.md` § Scope Manifest — the coordinator runbook (steps 3.1–3.3) and § Pre-Dispatch: File-Scope Injection (the prompt block shape).
+- `.claude/rules/parallel-sessions.md` § Decision Tree (why a file in two declared scopes is never a benign sibling signal), § PSA-006 (measurement discipline).
+- `hooks/enforce-scope.mjs` — the write-time gate, fail-**closed**; the deliberate inversion of this hook's posture.
+- [`docs/adr/0011-guard-degradation-semantics.md`](adr/0011-guard-degradation-semantics.md) — the exit-0 hook protocol (#906) and why a truncated stdout envelope reads as no-decision, i.e. as ALLOW.

package/docs/session-config-reference.md

@@ -74,7 +74,7 @@ Some sub-configs live in dedicated policy files under `.orchestrator/policy/`:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. Plain integers remain plain. |
+| `agents-per-wave` | integer or integer with overrides | `6` | Maximum parallel subagents per wave. Supports session-type overrides: `6 (deep: 18)` outputs `{"default": 6, "deep": 18}`. Plain integers remain plain. The override key names a session type but does **not** create one: there is no `session-type:` Session Config key — `parseSessionConfig()` emits none, so writing one into a repo's `## Session Config` block is inert prose. The session type comes from the `/session` argument (default `deep`, see `commands/session.md`) and is persisted to STATE.md frontmatter as `session-type:`, which is the only live read (`scripts/print-applicable-rules.mjs` rule mode-gating). |
 | `agent-mapping` | object | null | Optional mapping of role keys to agent names for explicit agent binding. Keys: `impl`, `test`, `db`, `ui`, `security`, `compliance`, `docs`, `perf`. Example: `{ impl: code-editor, test: test-specialist }`. Overrides auto-discovery when present. |
 | `waves` | integer | `5` | Number of execution waves for feature and deep sessions. |
 | `recent-commits` | integer | `20` | Number of recent commits to display during session start git analysis. |
@@ -1638,46 +1638,6 @@ Leave disabled (default) when:
 - `skills/wave-executor/wave-loop.md` § 3b — the wave-executor hook contract.
 - `agents/schemas/persona-panel-sidecar.schema.json` — sidecar JSON Schema enforced before write.
 
-## Compact Nudge (#620)
-
-Advisory-only checkpoint surfaced at inter-wave boundaries in the wave-executor loop. Never auto-compacts — `/compact` is a user slash-command, and the coordinator/operator decides when to invoke it. When the gate conditions are met, the wave-executor appends ONE advisory bullet to the wave progress update suggesting a `/compact` before the next wave.
-
-All fields live under a top-level `compact-nudge` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
-
-```yaml
-compact-nudge:
-  enabled: false                       # opt-in advisory /compact nudge at inter-wave checkpoints (never auto-compacts)
-  after: [discovery, impl]             # wave boundaries that may fire the nudge — subset of {discovery, impl, failed-wave}
-  mode: warn                           # warn (surface one bullet in the wave progress update) | off (silent no-op)
-```
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `compact-nudge.enabled` | boolean | `false` | Master toggle. When `false` (or the block is absent), the nudge never fires — zero behaviour change. |
-| `compact-nudge.after` | list of `"discovery"` \| `"impl"` \| `"failed-wave"` | `[discovery, impl]` | Wave boundaries that may fire the nudge. `discovery`/`impl` are wave ROLES, matched against the just-completed wave's role string. `failed-wave` is not a role — it keys off the wave's failure OUTCOME (any wave that did not pass its quality gate), so it can fire after a wave of any role. |
-| `compact-nudge.mode` | `warn` \| `off` | `warn` | `warn` emits the advisory bullet in the wave progress update. `off` is a silent no-op even when `enabled: true`. |
-
-**Used by:** `skills/wave-executor/wave-loop.md` § 3c "Strategic Compact-Nudge". Issue #620. See `.claude/rules/loop-and-monitor.md` for the broader `/loop` vs `/goal` vs Monitor routing this nudge composes with.
-
-## Goal Integration (#636)
-
-Opt-in advisory continuation anchor that surfaces a suggested `/goal` command at named seams — the inter-wave fix-loop (`inter-wave-fixloop`) and the session-end backlog drain (`session-end-backlog`). Never auto-invokes `/goal`, never blocks forward progress; `/goal` remains a user slash-command the operator chooses to run. Per ADR-0010, `/goal` provides CONTINUATION, never JUDGMENT — the suggested condition always references freshly-run deterministic gate output and embeds a bound (e.g. "or stop after N attempts"); the exit-code result of the underlying gate stays the authority.
-
-All fields live under a top-level `goal-integration` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
-
-```yaml
-goal-integration:
-  enabled: false                       # opt-in advisory; default off — zero behaviour change when absent
-  seams: [session-end-backlog, inter-wave-fixloop]   # subset of {session-end-backlog, inter-wave-fixloop}; one goal per session — pick ONE seam at a time
-```
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `goal-integration.enabled` | boolean | `false` | Master toggle. When `false` (or the block is absent), no `/goal` suggestion is ever surfaced — zero behaviour change. |
-| `goal-integration.seams` | list of `"session-end-backlog"` \| `"inter-wave-fixloop"` | `[session-end-backlog, inter-wave-fixloop]` | Which seam(s) may surface the advisory `/goal` suggestion. Only ONE `/goal` can be active per session — if both seams are listed, the operator picks a single seam to actually invoke; the two cannot hold simultaneous active goals. |
-
-**Used by:** `skills/wave-executor/wave-loop.md` § "/goal Continuation Anchor" (inter-wave-fixloop seam), `skills/session-end/SKILL.md` § 1.3a "Optional /goal Backlog-Drain" (session-end-backlog seam). Lever 5 / issue #636. See `.claude/rules/loop-and-monitor.md` § LM-008 for the full continuation-vs-judgment contract.
-
 ## Skill Evolution (#646)
 
 Opt-in configuration for the Skill Self-Evolution Foundation (Epic #643, Sub-issue #646). Controls whether `/evolve` surfaces skill health signals for operator review only (`advisory`) or additionally applies deterministic repairs to local config artifacts behind an evidence gate (`autonomous-gated`). The default is `off` — no behavior change for repos that omit this block.