session-orchestrator 3.19.0 → 3.20.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
-    "version": "3.19.0"
+    "version": "3.20.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.19.0+codex.20260804175819",
+  "version": "3.20.0+codex.20260813195914",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "keywords": [
     "session",

package/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.20.0] - 2026-08-13
+
+Memory-pipeline line. The learning store had been accumulating for 233 sessions and delivering
+to nobody: 100 learnings, and not one read path into a dispatched agent. Closing that gap
+surfaced two defects underneath it — agent-authored text reaching every agent's project
+instructions unfiltered, and a prune path that deleted learnings into neither the store nor
+the archive. The headline is not a feature; it is that the review panel then found the same
+class **inside the fix**: this line hardened one delivery channel and shipped a second,
+unhardened one alongside it.
+
+### Added
+
+- **Learnings reach wave agents (#1014)** — a per-agent index in the dispatch prompt, selected
+  from the agent's own declared file scope. Two-tier with **split** caps (scope-matched, then
+  top-scored fill), because only 17 of 100 learnings carry `file_paths` and a single shared cap
+  lets the global tier crowd out the per-agent guarantee that is the acceptance criterion.
+  Rides the channel the coordinator already composes — `docs/instruction-delivery.md` §5
+  measured a *separate* injection path at **+72.3%**; this one costs **+0.69% to +1.15%** of a
+  178,096-byte baseline. Factor 92. `LEARNINGS_INDEX_MAX_CHARS = 2000` is derived (1.12% of the
+  measured baseline, 0.92× the median rule file), not chosen. Delivery is observable rather than
+  assumed: `orchestrator.learnings.index.injected` carries entry count, scope-matched split and
+  byte size, so "did the injector run?" is a grep instead of an inference.
+- **Semantic dedup + contradiction detection (#1016)** — IDF-Dice top-K candidate pool
+  (K=8, FLOOR=0.085), per-seed, bounded, deliberately **non-transitive**: even at K=3 the
+  similarity graph collapses into a 99-of-100 giant component, so a clustering pass returns
+  "the corpus". `type` neither filters nor boosts — both strongest ground-truth links are
+  cross-type, and a type gate drops connectivity 6/6 → 4/6 while still retaining 26% of pairs.
+  A German stoplist is mandatory, not cosmetic: without it the top-scoring pair in the whole
+  corpus is two records sharing function words. The judgment layer is fail-closed and atomic
+  (one malformed decision voids the batch, never the valid subset), and enforces structurally
+  that **rendering an AUQ from an unreadable judgment is itself a write** — the AUQ renderer
+  sits in the same effect map as the archive writer, behind one gate.
+- **`scripts/print-learnings-index.mjs`**, **`scripts/backfill-learnings-from-vault.mjs`**,
+  **`scripts/lib/validate/check-learning-provenance.mjs`**, and a `--prune` mode on
+  `sweep-expired-learnings.mjs`. Five new leaf modules under `scripts/lib/learnings/`
+  (`affinity`, `select`, `candidates`, `judgment`, `kebab`).
+
+### Fixed
+
+- **Agent-authored text is neutralised at the render point (#1015)** — the reconcile renderer
+  interpolated it verbatim into `.claude/rules/<slug>.md`, a file Claude Code then delivers to
+  every agent in every session as a project instruction, with no revocation: the frontmatter
+  gates are not a containment boundary for the body. Machine values now **reject** (a repaired
+  `learning-key` breaks idempotency; a dropped `globs[]` element can leave `globs: []`, which
+  the loader excludes everywhere — silently dead beats loudly rejected); prose is framed and
+  capped without a meaning filter, because a blocklist is the guard that looks green and does
+  not bite. Two premises in the issue text did not survive verification and are corrected in
+  the issue: `description` was already defended against newlines, and the frontmatter parser is
+  hand-rolled — so the newline is the *only* escape and a YAML-shaped sanitiser would have been
+  both wrong and destructive (14 `description` lines in the corpus carry a second colon).
+- **The learning store is durable again (#1017)** — `/evolve` pruned by rewriting the store with
+  **no archive append**; 11 of 13 provenance pointers in generated rules resolved to nothing, in
+  neither store nor archive nor any backup. Both callers now share one `archiveThenRewrite()`
+  (KEEP-probe, archive **before** rewrite so a crash leaves the record in both places and never
+  in neither, `.bak` snapshot), and `pruneLearnings()` archives any record the caller's next
+  generation omits — reconciled by `id`, or by content fingerprint when a record carries no
+  usable one. **11 of 11 lost records were recovered** from the vault mirror with per-field
+  origin labelling; dangling pointers **11 → 0**.
+- **Rule-block delivery boundaries were unrecoverable without any adversarial input** — rule
+  `content` is byte-identical to disk *including* its YAML fence, so joining rules on `---`
+  produced 56 separator-shaped lines for 18 rules. Replaced with per-rule fence tags carrying a
+  content-derived token and the source path (information an agent previously could not get at
+  all). An existing test had pinned the broken contract.
+- **`learning_key` was derived five ways** on a *stored* contract, with the writer kebabbing the
+  `type` half and all four readers not. One shared derivation now; proven byte-identical across
+  107 records, all 13 stamped keys reproduced.
+- **Two tracked `.mjs` files carried NUL bytes** and were therefore skipped **silently** by every
+  grep-based audit — exit 1, no output, which reads exactly like a clean result.
+
+### Notes
+
+- The review panel (security, qa, architect, independently) returned **FIX_REQUIRED** with four
+  HIGH blockers; all four were closed in one fix cycle, which found three further holes of the
+  same class. Every new guard is proven by fake regression, not by a green test.
+- `CANDIDATE_FLOOR` is deliberately **unchanged** despite its justification no longer
+  reproducing: this line's own backfill moved every IDF weight, and the wave-1 ground-truth
+  labels were never persisted. A constant whose evidence has evaporated is not re-guessed from
+  the evaporated evidence (#1021).
+- Follow-ups: #1018, #1019, #1020, #1021 — each with a named revisit trigger.
+
 ## [3.19.0] - 2026-08-04
 
 Guard-hardening and release-mechanics line. Headline: the destructive-command guard closed

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.19.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.20.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 [![Tests](https://img.shields.io/badge/tests-12%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
@@ -127,17 +127,17 @@ The system is markdown-driven config plus a thin Node runtime — skills, comman
 - **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
 - **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
 
-## Recent highlights (v3.19.0)
+## Recent highlights (v3.20.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.19.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.20.0 line:
 
-- **Destructive-command guard, hardened in depth** — wrapper unwrapping (`sudo`/`doas`/`env`/`nohup`/`timeout`/`nice`/`stdbuf`, with depth-capped `-c` payload recursion) closes six measured bypasses (#982); the blocked-commands policy becomes a floor ∪ overlay model that can only escalate, never weaken (#972); shell redirects gain a target denylist — an `&>` redirect into a protected instruction file was a silent allow-with-truncation before (#983); and the denylist now resolves absolute paths, not just repo-relative ones.
-- **Session identity with proof** — the session lock persists an owner proof at genesis, so an ending session can no longer release a living foreign lock, and the abandoned-session backfiller no longer deletes the very alarm it exists to raise (#987, #926, #914).
-- **Supply chain** — two high-severity transitive vulnerabilities that `npm audit fix` could not reach are closed via package overrides.
-- **Release as one dispatch** — `scripts/release.mjs` (#978, local half): a single surfaces table drives version rewrite and preflight (12 version literals across 10 files, CHANGELOG gate, tag/registry collision, drift sweep over all tracked files, CI-green-on-HEAD, leakage gate), and the git tag is created only AFTER a verified npm publish. Found two real gaps on its first run: v3.18.0 had been tagged but never published to npm, and the hidden `.codex-plugin` manifest was invisible to a plain ripgrep census.
-- **session-orchestrator.com redesigned** — terminal hero, wave pipeline, leaderboard shell.
+- **Learnings finally reach the agents doing the work (#1014)** — 233 sessions of accumulated memory had exactly zero read paths into a dispatched agent. Now a per-agent index, selected from that agent's declared file scope, riding the dispatch prompt the coordinator already writes. Measured at **+0.69%–1.15%** of the prompt an agent already receives, against **+72.3%** for the separate-injection path the delivery doc forbids — factor 92. The character cap is derived from that measurement, not chosen, and delivery emits an event so "did it run?" is a grep rather than an inference.
+- **Agent-authored text no longer reaches every agent unfiltered (#1015)** — the reconcile renderer wrote it verbatim into `.claude/rules/`, which Claude Code hands to every agent in every session, with no revocation. Machine values now reject, prose is framed and capped. Two premises in the issue itself did not survive verification and were corrected rather than implemented.
+- **The learning store is durable again (#1017)** — `/evolve` pruned by rewriting with no archive append; **11 of 13 provenance pointers in generated rules resolved to nothing**. One shared archive-then-rewrite path, and **11 of 11 lost records recovered** from the vault mirror. Dangling pointers 11 → 0.
+- **Semantic dedup + contradiction detection (#1016)** — a bounded, deliberately non-transitive candidate pool and a fail-closed judgment layer in which rendering an approval prompt from an unreadable verdict counts, structurally, as a write.
+- **The review panel found the same class inside the fix** — three independent reviewers returned FIX_REQUIRED: this line had hardened one delivery channel and shipped a second, unhardened one beside it. Closed in one cycle, which surfaced three further holes of the same shape. Every new guard is proven by fake regression, not by a green test.
 
-Previous line (v3.18.0): panel-follow-ups and consolidation — bash-write-verify self-silencing vectors closed (#938), credential stripping at the source (#907), instruction-corpus diet 471→~440 directives, mutation-sweep-backed test consolidation.
+Previous line (v3.19.0): guard hardening and release mechanics — six wrapper bypasses closed (#982), blocked-commands floor ∪ overlay (#972), session-lock ownership proof, and release as one dispatch (#978).
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 

package/commands/session.md

@@ -5,9 +5,13 @@ argument-hint: "[housekeeping|feature|deep]"
 
 # Session Start
 
-You are beginning a new development session. The user has invoked `/session` with type: **$ARGUMENTS** (if empty, auto-detect from the project's `## Session Config` block or default to `feature`).
+You are beginning a new development session. The user has invoked `/session` with type: **$ARGUMENTS** (if empty, default to **`deep`**).
 
-**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then auto-detect from the project's `## Session Config` block or default to `feature`.
+**Default rationale (measured, not assumed):** `deep` is the default because it is what operators actually run — 77.3 % of 489 recorded sessions across 5 repos, and 115 of 228 (50.4 %) in this repo's own `.orchestrator/metrics/sessions.jsonl`. The former `feature` default made the majority case the one that had to be typed out every time. A `deep` default costs a downgrade keystroke in the minority case; a `feature` default cost an upgrade keystroke in the majority case.
+
+**Argument validation:** Valid session types are `housekeeping`, `feature`, and `deep`. An explicit `$ARGUMENTS` value ALWAYS wins over the default — `/session housekeeping` and `/session feature` behave exactly as before. If `$ARGUMENTS` is not empty and does not match any valid type, inform the user: "Invalid session type '$ARGUMENTS'. Valid types: housekeeping, feature, deep." Then fall back to `deep`.
+
+> **Not read from Session Config.** There is deliberately no `session-type:` (or equivalent) key in the `## Session Config` block — `scripts/lib/config.mjs` `parseSessionConfig()` does not emit one, so any such key in a repo's CLAUDE.md (or its Codex CLI equivalent AGENTS.md) is inert prose. The `session-type:` scalar that IS live lives in STATE.md frontmatter (read by `scripts/print-applicable-rules.mjs` for rule mode-gating) and is written per session, not configured per repo. Do not reintroduce a Session Config key here without wiring it into the parser first.
 
 ## Resume Support
 

package/docs/USER-GUIDE.md

@@ -1297,7 +1297,7 @@ No. The orchestrator never commits code until you run `/close`. During wave exec
 
 ### What happens to unfinished work?
 
-During `/close`, any work that was planned but not completed is documented. The orchestrator creates carryover issues on your VCS platform with the title prefix `[Carryover]`, including context on what was done and what remains. Nothing is silently dropped.
+During `/close`, any work that was planned but not completed is documented. The orchestrator creates carryover issues on your VCS platform with the title prefix `[Carryover]`, including context on what was done, what remains, and a mandatory Revisit-Trigger naming the condition that reopens the work. Nothing is silently dropped.
 
 ### Can I use this across multiple repos?
 

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