session-orchestrator 5.5.0 → 5.7.0

package/scripts/vault-mirror-prune.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * vault-mirror-prune.mjs — CLI for the mirror-zone retention prune (#1513).
+ *
+ * Applies the vault-mirror retention rules to the notes the mirror wrote
+ * BEFORE those rules existed: expired / superseded / duplicate learnings,
+ * metrics-only session notes (rolled up first), namespace-alias folders and
+ * flat legacy notes. All decisions live in `scripts/lib/vault-mirror/prune.mjs`
+ * (rules table in its header) and `retention.mjs`; this file is argv parsing,
+ * the manifest, output and exit codes.
+ *
+ * SAFETY: dry run is the DEFAULT and writes nothing — not even the manifest
+ * unless `--manifest` names a path. `--apply` moves files (archive → under
+ * `90-archive/mirror/`), never deletes a note's content, never touches a note
+ * without the mirror's `_generator` marker.
+ *
+ * Usage:
+ *   node scripts/vault-mirror-prune.mjs --vault-dir PATH [--apply]
+ *     [--manifest PATH] [--now ISO] [--min-narrative-chars N]
+ *     [--alias FROM=TO ...] [--json]
+ *
+ * Exit codes: 0 success · 1 usage error · 2 apply finished with per-path errors
+ */
+
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { expandTilde, redactHomeDir } from './lib/common.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+import { MANIFEST_SCHEMA, applyPrune, planPrune } from './lib/vault-mirror/prune.mjs';
+
+const HELP = `Usage: node scripts/vault-mirror-prune.mjs --vault-dir PATH [--apply] [--manifest PATH]
+       [--now ISO] [--min-narrative-chars N] [--alias FROM=TO ...] [--json]
+
+Plans (default) or applies the vault-mirror retention rules to 40-learnings/
+and 50-sessions/ of a vault. Only notes carrying the vault-mirror _generator
+marker are considered; hand-written notes are never touched.
+
+Options:
+  --vault-dir PATH          Vault root (required; no host-local default on purpose)
+  --apply                   Write: rollups, then archive moves to 90-archive/mirror/, then renames
+  --manifest PATH           Write the JSON manifest (path, reason, action, target) there
+  --now ISO                 Injected clock for the expiry check (default: now)
+  --min-narrative-chars N   Session narrative gate (default 400, as vault-mirror.quality)
+  --alias FROM=TO           Explicit namespace alias (repeatable); the hyphen rule applies without it
+  --json                    Print the summary as one JSON line
+
+Exit codes: 0 success  1 usage error  2 apply finished with per-path errors
+`;
+
+function usageError(msg) {
+  process.stderr.write(`vault-mirror-prune: ${msg}\n`);
+  process.exit(1);
+}
+
+export function parseArgs(argv) {
+  const args = { vaultDir: null, apply: false, manifest: null, now: null, minNarrativeChars: 400, aliases: {}, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    const value = () => {
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith('--')) usageError(`${a} needs a value`);
+      i += 1;
+      return v;
+    };
+    if (a === '--help' || a === '-h') {
+      process.stdout.write(HELP);
+      process.exit(0);
+    } else if (a === '--vault-dir') args.vaultDir = value();
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--dry-run') args.apply = false;
+    else if (a === '--manifest') args.manifest = value();
+    else if (a === '--now') {
+      args.now = value();
+      if (!Number.isFinite(Date.parse(args.now))) usageError(`--now is not a date: ${args.now}`);
+    } else if (a === '--min-narrative-chars') {
+      const raw = value();
+      if (!/^\d+$/.test(raw)) usageError(`--min-narrative-chars must be a non-negative integer, got ${raw}`);
+      args.minNarrativeChars = Number(raw);
+    } else if (a === '--alias') {
+      const m = /^([a-z0-9][a-z0-9-]*)=([a-z0-9][a-z0-9-]*)$/.exec(value());
+      if (!m) usageError('--alias expects FROM=TO with lowercase kebab namespaces');
+      args.aliases[m[1]] = m[2];
+    } else if (a === '--json') args.json = true;
+    else usageError(`unknown argument ${a}`);
+  }
+  if (!args.vaultDir) usageError('--vault-dir is required');
+  return args;
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const vaultDir = resolve(expandTilde(args.vaultDir));
+  const today = new Date(args.now ? Date.parse(args.now) : Date.now()).toISOString().slice(0, 10);
+  const plan = planPrune({ vaultDir, today, minNarrativeChars: args.minNarrativeChars, aliases: args.aliases });
+
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    generated_at: new Date().toISOString(),
+    today,
+    dry_run: !args.apply,
+    min_narrative_chars: args.minNarrativeChars,
+    aliases: plan.aliases,
+    skipped_handwritten: plan.handwritten,
+    counts: plan.counts,
+    rollups: Object.fromEntries(Object.entries(plan.rollups).map(([k, rows]) => [k, rows.length])),
+    actions: plan.actions,
+  };
+  let applied = null;
+  if (args.apply) {
+    applied = applyPrune(plan, { vaultDir });
+    // The apply result belongs in the manifest: notes written beside an
+    // occupied archive target (`suffixed`) and per-path errors.
+    manifest.applied = applied;
+  }
+  if (args.manifest) writeFileSync(resolve(expandTilde(args.manifest)), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+
+  const summary = {
+    dry_run: !args.apply,
+    counts: plan.counts,
+    rollups: Object.keys(plan.rollups).length,
+    aliases: plan.aliases,
+    skipped_handwritten: plan.handwritten,
+    ...(applied ? { applied: { ...applied, suffixed: applied.suffixed.length, errors: applied.errors.length } } : {}),
+  };
+  if (args.json) process.stdout.write(JSON.stringify(summary) + '\n');
+  else {
+    process.stdout.write(`vault-mirror-prune ${args.apply ? 'APPLY' : 'dry run'} (today ${today})\n`);
+    for (const [k, n] of Object.entries(plan.counts).sort()) process.stdout.write(`  ${k.padEnd(36)} ${n}\n`);
+    process.stdout.write(`  rollup notes                         ${Object.keys(plan.rollups).length}\n`);
+    for (const [from, to] of Object.entries(plan.aliases)) process.stdout.write(`  alias ${from} -> ${to}\n`);
+    if (applied) {
+      process.stdout.write(`  applied: archived ${applied.archived}, moved ${applied.moved}, rollups written ${applied.rollupsWritten}, suffixed ${applied.suffixed.length}, errors ${applied.errors.length}\n`);
+    }
+  }
+  if (applied && applied.errors.length > 0) {
+    for (const e of applied.errors.slice(0, 20)) process.stderr.write(`vault-mirror-prune: ${e.path}: ${redactHomeDir(e.error)}\n`);
+    return 2;
+  }
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main());
+}

package/scripts/vault-mirror.mjs

@@ -20,7 +20,7 @@
  *       `--repo-root` — #1503)
  *
  * Output: one JSON line per action on stdout:
- *   {"action":"created|updated|skipped-noop|skipped-handwritten|skipped-collision-resolved|skipped-foreign-owner|skipped-invalid|skipped-quality-low|skipped-abandoned|skipped-duplicate-session","path":"...","kind":"...","id":"..."}
+ *   {"action":"created|updated|skipped-noop|skipped-handwritten|skipped-collision-resolved|skipped-foreign-owner|skipped-invalid|skipped-quality-low|skipped-abandoned|skipped-duplicate-session|skipped-metrics-only|skipped-expired|skipped-duplicate-insight","path":"...","kind":"...","id":"..."}
  *
  * Idempotency rules:
  *   1. File does not exist → create.
@@ -45,8 +45,10 @@
  *
  * Quality gate (PRD F1.2):
  *   Learnings with confidence < --quality-min-confidence emit `skipped-quality-low`.
- *   Sessions with rendered-narrative length < --quality-min-narrative-chars emit
- *   `skipped-quality-low`. Quality gate runs BEFORE --force; --force does NOT
+ *   Sessions whose free text (`notes`/`narrative`/`summary`) is shorter than
+ *   --quality-min-narrative-chars get no note: `skipped-metrics-only` with one row
+ *   in the month rollup `50-sessions/<repo>/_rollup-YYYY-MM.md` (#1513; rules in
+ *   scripts/lib/vault-mirror/retention.mjs). Quality gate runs BEFORE --force; --force does NOT
  *   bypass the filter. Quality-skipped entries emit `path: null` and an
  *   additional `reason` field describing the violated threshold.
  *
@@ -65,14 +67,16 @@
  * Part of session-orchestrator vault-mirror (Issue #14).
  */
 
-import { existsSync, realpathSync } from 'node:fs';
-import { basename, dirname, resolve } from 'node:path';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { createReadStream } from 'node:fs';
 
 import {
   processLearning,
   processSession,
+  processArchivedLearning,
+  learningNoteSlugs,
   getMaskerStats,
   emitAction,
 } from './lib/vault-mirror/process.mjs';
@@ -81,6 +85,7 @@ import { emitEvent } from './lib/events.mjs';
 import { autoCommitVaultMirror } from './lib/vault-mirror/auto-commit.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { resolveRepoNamespace } from './lib/vault-mirror/namespace.mjs';
+import { SESSION_NARRATIVE_FIELDS, canonicalNamespace } from './lib/vault-mirror/retention.mjs';
 import { sessionSourceRecord } from './lib/vault-mirror/render-sessions.mjs';
 import { checkCanonicalVault, describeOriginForLog, findRepoRoot, normalizeRemote } from './lib/named-vault-resolver.mjs';
 import { loadOwnerConfig } from './lib/owner-yaml.mjs';
@@ -249,8 +254,9 @@ if (flagValues.help === true) {
       '                                        project holding --source (<root>/.orchestrator/metrics/), else',
       '                                        the git repo containing it, else the cwd. Refused (exit 2,',
       '                                        "source-repo-mismatch") when --source lies in a different repo.',
-      '  --quality-min-narrative-chars <int>   Sessions: minimum rendered-narrative length (default 400).',
-      '                                        Entries below the threshold emit "skipped-quality-low".',
+      '  --quality-min-narrative-chars <int>   Sessions: minimum free text in notes/narrative/summary',
+      '                                        (default 400, 0 = off). Below it: "skipped-metrics-only",',
+      '                                        one row in 50-sessions/<repo>/_rollup-YYYY-MM.md.',
       '  --quality-min-confidence <float>      Learnings: minimum confidence threshold (default 0.5).',
       '                                        Entries below the threshold emit "skipped-quality-low".',
       '',
@@ -641,6 +647,9 @@ async function main() {
     // superseded duplicates included — filled while buffering below, read by
     // processSession's owner guard (a key from this ledger is never foreign).
     sourceRecordKeys: new Set(),
+    // #1513: note slugs of every LIVE learning in --source; the archive pass
+    // below never marks a note one of them still owns.
+    liveLearningSlugs: new Set(),
     qualityMinNarrativeChars,
     qualityMinConfidence,
   };
@@ -662,14 +671,15 @@ async function main() {
    *   always supplies a real line number.
    * @returns {Promise<void>}
    */
-  async function dispatchEntry(entry, entryLineNum) {
+  async function dispatchEntry(entry, entryLineNum, processor = null) {
     try {
       // Both processors return the `action` string they emitted (every one of
       // their exit paths is an `emitAction` call), so the tally needs no second
       // census of the 18 call sites in process.mjs — a census that would go
       // stale the first time a branch is added.
-      const action =
-        kind === 'learning'
+      const action = processor
+        ? await processor(entry, entryLineNum, ctx)
+        : kind === 'learning'
           ? await processLearning(entry, entryLineNum, ctx)
           : await processSession(entry, entryLineNum, ctx);
       tally(action);
@@ -776,9 +786,39 @@ async function main() {
       continue;
     }
 
+    for (const slug of learningNoteSlugs(entry)) ctx.liveLearningSlugs.add(slug);
     await dispatchEntry(entry, lineNum);
   }
 
+  // #1513 ARCHIVE PASS (`--kind learning` only): records /evolve or the expiry
+  // sweep moved out of `learnings.jsonl` live on in the sibling
+  // `learnings-archive.jsonl`. Their vault notes used to stay `status: draft`
+  // forever, because the mirror only ever saw the live store. Each archived
+  // record now marks its existing note archived (never creates one). Counted
+  // into `total` like any other line, so the run partition still holds. A
+  // malformed archive line is reported and skipped — the archive is secondary
+  // input and must not abort a mirror run that already wrote the live store.
+  if (kind === 'learning' && basename(resolve(source)) === 'learnings.jsonl') {
+    const archivePath = join(dirname(resolve(source)), 'learnings-archive.jsonl');
+    if (existsSync(archivePath)) {
+      const archiveLines = readFileSync(archivePath, 'utf8').split('\n');
+      for (let i = 0; i < archiveLines.length; i += 1) {
+        const trimmed = archiveLines[i].trim();
+        if (!trimmed) continue;
+        let archived;
+        try {
+          archived = JSON.parse(trimmed);
+        } catch {
+          process.stderr.write(`WARN vault-mirror: malformed JSON on learnings-archive.jsonl line ${i + 1} — skipped\n`);
+          continue;
+        }
+        if (archived === null || typeof archived !== 'object') continue;
+        runState.total++;
+        await dispatchEntry(archived, i + 1, processArchivedLearning);
+      }
+    }
+  }
+
   if (kind === 'session') {
     // Only an OBJECT entry carrying a non-empty `session_id` is eligible for
     // the dedup collapse — the same predicate canonicalizeSessions itself uses
@@ -803,6 +843,30 @@ async function main() {
     // never a guess (scripts/lib/sessions-canonical.mjs header, "RULE ORDER").
     const survivors = new Set(canonicalizeSessions(identifiable));
 
+    // #1513 review H2: "newest wins" must not cost a session its narrative. A
+    // re-appended record often carries only the metrics; the free text sits on
+    // the line it supersedes (vault ledger: 1.172 chars on line 101, none on the
+    // winning line 108). The winner inherits every narrative field it LACKS
+    // from the losers, latest loser first — its own fields always win.
+    const inherited = new Map();
+    for (const e of sessionEntries) {
+      if (!isIdentifiable(e) || survivors.has(e)) continue;
+      const carry = inherited.get(e.session_id) ?? {};
+      for (const field of SESSION_NARRATIVE_FIELDS) {
+        if (e[field] !== undefined && e[field] !== null && e[field] !== '') carry[field] = e[field];
+      }
+      inherited.set(e.session_id, carry);
+    }
+    const withNarrative = (e) => {
+      const carry = isIdentifiable(e) ? inherited.get(e.session_id) : undefined;
+      if (!carry) return e;
+      const merged = { ...e };
+      for (const [field, value] of Object.entries(carry)) {
+        if (merged[field] === undefined || merged[field] === null || merged[field] === '') merged[field] = value;
+      }
+      return merged;
+    };
+
     for (let i = 0; i < sessionEntries.length; i++) {
       const entry = sessionEntries[i];
       if (isIdentifiable(entry) && !survivors.has(entry)) {
@@ -831,7 +895,7 @@ async function main() {
         );
         continue;
       }
-      await dispatchEntry(entry, sessionLineNums[i]);
+      await dispatchEntry(withNarrative(entry), sessionLineNums[i]);
     }
   }
 
@@ -863,7 +927,8 @@ async function main() {
     autoCommitVaultMirror(
       resolve(vaultDir),
       sessionIdArg,
-      resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot }),
+      // #1513 review M2: the folder the processors actually wrote into.
+      canonicalNamespace(resolve(vaultDir), resolveRepoNamespace({ vaultName, repoRoot: ctx.repoRoot })),
     );
   }
 }

package/skills/_shared/parallel-aware-auq.md

@@ -113,7 +113,7 @@ In-place beside a peer is survivable when the two scopes are DECLARED to each ot
 Four steps, in order. Steps 1 and 2 are the protocol; 3 and 4 are what keeps it honest.
 
 1. **Declare the COMPLETE path list.** The arriving session sends the peer every path it will write — including the ones a script produces (fixtures, snapshots, result files, temp helpers), not only the ones it plans to edit by hand. A path omitted here is a path the peer's guard reports as a violation. In the same message it adopts the peer's resource rules.
-2. **The peer unions.** The receiving coordinator adds those paths to its `allowedPaths` as ONE record `peer-session-<id>` in the wave's scope manifest, re-asserts subset/disjointness, and re-materializes them on every wave rollover (`skills/wave-executor/wave-loop.md` § Scope Manifest).
+2. **The peer unions.** The receiving coordinator adds those paths to its `allowedPaths` as ONE record `peer-session-<id>` in the wave's scope manifest, re-asserts subset/disjointness, and re-materializes them on every wave rollover (`skills/wave-executor/wave-loop.md` § Scope Manifest). Mid-wave, re-run the FULL sequence of `skills/wave-executor/references/wave-loop-scope-manifest.md` § 3, including § 3.3's skeleton write (`"allowedPaths": []`) before the final manifest: `--union` excludes `peer-session-*` records, so re-materializing the sidecar alone leaves the manifest bytes unchanged, `bash-write-verify` keeps the sidecar bound to the OLD hash, and every agreed peer write then reports as a violation for the rest of the wave (#1504 point 5). The skeleton rewrite changes the manifest hash, which re-binds the new sidecar.
 3. **Probe with ONE real write.** Before dispatching any agent, make one small PLANNED Edit from the declared list. A denial here costs one edit; the same denial found after a fan-out costs the wave.
 4. **Announce before committing.** The arriving session sends its final file list, the peer sequences its own push behind it, and the SHAs come back. The git index is shared (PSA-007) — sequencing it is the only thing that makes two sessions in one checkout committable.
 

package/skills/claude-md-drift-check/checker.mjs

@@ -41,6 +41,7 @@ import { isSessionConfigHeading } from '../../scripts/lib/config/section-extract
 import { FRONTMATTER_NOT_AT_TOP, parseGlobsFrontmatter } from '../../scripts/lib/rule-loader.mjs';
 import { resolveRepoSpec } from '../../scripts/lib/vcs-repo-spec.mjs';
 import { userInvocableSkills } from '../../scripts/lib/user-invocable-skills.mjs';
+import { learningKeyOf } from '../../scripts/lib/learnings/kebab.mjs';
 
 const FORWARD_HEADING_RE =
   /(?:^|\b)(what'?s?\s+next|backlog|open\s+issues?|offene\s+(?:issues?|themen)|todo|next\s+steps?|roadmap)(?:$|\b)/i;
@@ -1143,9 +1144,9 @@ function main() {
   // `learning-key` and verify it matches a non-expired entry in
   // `.orchestrator/metrics/learnings.jsonl`.
   //
-  // Key derivation mirrors emitter.mjs `toActivationMetadata`:
-  //   learningKey = `${type}/${kebab(title || subject || '')}`
-  //   kebab(s) = s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  // Key derivation is the shared `learningKeyOf` (scripts/lib/learnings/kebab.mjs):
+  //   `${type.trim()}/${kebab(title || subject)}`, blank title/subject skipped,
+  //   null for an empty type or slug — so a stamped key matches its own learning.
   //
   // WARN (never error) when:
   //   - NEITHER a learnings.jsonl entry NOR a valid `evidence-digest` frontmatter
@@ -1216,13 +1217,6 @@ function main() {
     // copies are pinned equal by `tests/lib/reconcile/renderer.test.mjs`.
     const EVIDENCE_DIGEST_RE = /^sha256-v1:[0-9a-f]{64}$/;
 
-    // Slugify function mirroring emitter.mjs `kebab()`.
-    const kebab = (s) =>
-      String(s)
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-
     // Build the set of known learning keys from learnings.jsonl.
     // key → expires_at (ISO string or null)
     const knownKeys = new Map();
@@ -1239,12 +1233,8 @@ function main() {
           let entry;
           try { entry = JSON.parse(trimmed); } catch { continue; }
           if (!entry || typeof entry !== 'object') continue;
-          const type = typeof entry.type === 'string' ? entry.type : '';
-          const subjectOrTitle =
-            (typeof entry.title === 'string' && entry.title !== '' ? entry.title : '') ||
-            (typeof entry.subject === 'string' && entry.subject !== '' ? entry.subject : '');
-          if (!type || !subjectOrTitle) continue;
-          const derivedKey = `${type}/${kebab(subjectOrTitle)}`;
+          const derivedKey = learningKeyOf(entry);
+          if (!derivedKey) continue;
           // Store the most-recent expires_at (later entries overwrite earlier ones
           // with the same key — safe; duplicates are rare and same-key learnings
           // share the same expiry semantics).

package/skills/vault-mirror/SKILL.md

@@ -59,7 +59,10 @@ One JSON line is written to stdout for each non-empty JSONL entry processed. Exi
 | `skipped-collision-resolved` | A file at the target path has the generator marker but a different `id`; a disambiguated slug was used instead. |
 | `skipped-foreign-owner` | A generator note at the target path was rendered from another record (#1503), and this write must not replace it. **Sessions:** its `source-record` differs from this write and occurs nowhere in this `--source` ledger (`reason: "source-record mismatch"`), or its `id` names a different session (`reason: "id mismatch"`). **Learnings:** only for the disambiguated `<slug>-<uuid8>.md` file — a mismatch on the main `<slug>.md` is routed to disambiguation instead (`skipped-collision-resolved`, see Idempotency rule 6). One `SKIP foreign owner` line goes to stderr; `--force` does not bypass it. A leak in the foreign note is masked in place — owner, content and `source-record` kept — and the line carries `healed_leak: true`. A note without `source-record` (written before #1503) stays writable. |
 | `skipped-invalid` | Entry is missing one or more required fields; entry skipped, processing continues. |
-| `skipped-quality-low` | Entry failed the quality gate (PRD F1.2): learning `confidence` below `vault-mirror.quality.min-confidence` (CLI: `--quality-min-confidence`, default `0.5`), or session rendered-narrative length below `vault-mirror.quality.min-narrative-chars` (CLI: `--quality-min-narrative-chars`, default `400`). The emitted JSON line includes a `reason` field describing the violated threshold and `path: null` (no file was created). The quality gate runs **before** `--force`; `--force` does not bypass it. |
+| `skipped-quality-low` | Learning `confidence` below `vault-mirror.quality.min-confidence` (CLI: `--quality-min-confidence`, default `0.5`), or a metrics-only session whose note ALREADY exists (left untouched; the pruner decides). Carries `reason` and `path: null`. Runs **before** `--force`; `--force` does not bypass it. |
+| `skipped-metrics-only` | Session record below the narrative gate (#1513, see Retention): no note; one row was added to the month rollup `50-sessions/<repo>/_rollup-YYYY-MM.md` (`path`). An unchanged rollup is `skipped-noop`. |
+| `skipped-expired` | Learning past its `expires_at` with no note yet (#1513): nothing is created. |
+| `skipped-duplicate-insight` | A mirror-owned, non-archived note in the same namespace (or the flat layout) already carries the same normalised insight (#1513); `path` names it. Only consulted where a NEW file would be created. |
 
 ### Output line shape
 
@@ -92,10 +95,32 @@ The numeric prefix (`50-sessions/`, `40-learnings/`) follows the vault folder or
 
 **Path contract note:** Issue #187 shipped the flat numeric-prefix layout (deferring the per-`<repo>` subfolder it sketched). Issue #660 adds that per-repo subfolder for write-isolation (above) while keeping the numeric-prefix ordering. If you need a different layout, file a new issue — do NOT silently change the script.
 
-**Learning-coverage self-healing after a store recovery (#740).** vault-mirror always mirrors the CURRENT `learnings.jsonl` store contents at run time — if an earlier session's store was truncated or corrupted and later recovered (e.g. from a `.bak`), the resulting transient coverage gap in the vault is closed automatically by the next mirror run, with no manual backfill required. Note also that `vault-mirror.quality.min-narrative-chars` (see Failure Modes → `skipped-quality-low` below) gates **sessions only** — `processLearning` never applies a narrative-length filter, so a short learning `insight` is never skipped for length; only the confidence gate (`vault-integration.quality.min-confidence`) applies to learnings.
+**Learning-coverage self-healing after a store recovery (#740).** vault-mirror always mirrors the CURRENT `learnings.jsonl` store contents at run time — if an earlier session's store was truncated or corrupted and later recovered (e.g. from a `.bak`), the resulting transient coverage gap in the vault is closed automatically by the next mirror run, with no manual backfill required. Note also that `vault-mirror.quality.min-narrative-chars` (see Retention below) gates **sessions only** — `processLearning` never applies a narrative-length filter, so a short learning `insight` is never skipped for length; only the confidence gate (`vault-integration.quality.min-confidence`) applies to learnings.
 
 **Host-local pseudonym mapping (Epic #725 D5).** Without a map, EVERY owner-leaky repo namespace collapses to a single `redacted-repo/` subdir — which breaks the #660 write-isolation (N private repos share one directory → id/slug collisions) and destroys cross-repo attribution. A host-local **pseudonym map** fixes this: each real repo slug is assigned a stable, non-leaky pseudonym, so the vault gets `40-learnings/<pseudonym>/` (and matching `source-repo` frontmatter, via W2's attribution threading) instead of everyone landing in `redacted-repo/`. The map is a JSON object `{ "real-slug": "pseudonym-slug", … }` at a host-local path referenced by `owner.yaml` → `paths.namespace-map-path` (env `SO_NAMESPACE_MAP` overrides; precedence env > owner.yaml > unset). `resolveRepoNamespace()` consults the map ONLY at the redaction site (i.e. only when a repo would otherwise be redacted), looking up both the sanitised segment and the raw identifier; a hit returns the pseudonym and skips redaction, so clean/public repos never touch the map (or its lazy owner.yaml read). **Privacy guarantee:** the map file lives OUTSIDE every repo (alongside `owner.yaml` under `~/.config/session-orchestrator/`) and is never committed — only the pseudonyms reach the vault, the real names stay host-local. Each pseudonym is validated (must be a kebab slug AND must not itself be owner-leaky); invalid or leaky pseudonyms are dropped with a WARN. **Fallback:** an absent, unreadable, or malformed map — and any UNMAPPED owner-leaky repo — still redacts to `redacted-repo`, identical to pre-#725 behaviour. Implementation: `scripts/lib/vault-mirror/pseudonym-map.mjs` (`loadPseudonymMap`) + `namespace.mjs`.
 
+## Retention (#1513)
+
+The mirror used to write every record and never mark or remove anything; by 2026-10-03 the two zones were 78 % of the Meta-Vault, 91 % of the session notes carried nothing beyond git, and 2.826 expired learnings still read `status: draft`. The rules live in ONE module, `scripts/lib/vault-mirror/retention.mjs`, shared by the mirror and the pruner:
+
+1. **Narrative gate (sessions).** A record gets its own note only when its free-text fields `notes`, `narrative`, `summary` (strings or string arrays, whitespace collapsed) reach `vault-mirror.quality.min-narrative-chars` (default `400`; `0` disables). Wave/agent/file tables are not narrative. All three renderer generations print exactly these fields into `## Notes` (`sessionNarrativeText`), which is what the pruner measures; an existing note with less free text than its record is rewritten once (heal), and when a ledger holds the same `session_id` twice the winning record inherits the narrative fields it lacks from the line it supersedes. Below the gate the record becomes one row (date, session id, type, waves, agents, files) in `50-sessions/<repo>/_rollup-YYYY-MM.md`, keyed by session id, sorted and rendered deterministically — re-runs are no-ops. Calibration (Jev audit, 3.003 notes): free text under 300 chars held 1 of 2.802 notes scored >= 2.5 "beyond git"; from 800 chars on, 18 of 55.
+2. **Legacy slug (learnings).** The pre-#725 slug (subject without the whitespace → hyphen pre-map) is recognised: when only that variant of THIS record's note exists, it is updated in place instead of a canonical twin being created. New notes always get the canonical slug.
+3. **Write-time dedupe (learnings).** Before a new file is created, the normalised `## Insight` (case, whitespace, typographic quotes/dashes, trailing punctuation ignored) is looked up among the mirror-owned, non-archived notes of the namespace, and among flat notes whose `source-repo` is this namespace → `skipped-duplicate-insight`. Placeholder insights (`(legacy record …`, `(none recorded)`, …) and keys under 40 characters never count as the same learning.
+5. **Namespace alias.** Folders equal modulo hyphens are one namespace; the one with more hyphens is canonical (`gotzendorferv2` → `gotzendorfer-v2`). The mirror resolves this before every write and for its auto-commit scope; the pruner uses the same function (`canonicalAmong`).
+4. **Expiry and leaving the store (learnings).** An expired record (`expires_at` before today) is never created; its existing note is re-rendered with `status: archived` + `archived-reason: expired`. After the live pass, `--kind learning` also reads the sibling `learnings-archive.jsonl` and marks each archived record's existing note `archived` with `archived-reason: expired` (`_archive_reason: expired`) or `superseded` (every other reason) — never creating one, never touching a note a live record still owns. `archived` + `archived-reason` instead of `status: expired|superseded` on purpose: the vault frontmatter status enum (SSOT projects-baseline) has no such values, and a status outside it fails vault-sync in any vault that validates the mirror zones.
+
+**Bestand: `scripts/vault-mirror-prune.mjs`.** Applies the same rules to notes written before them. Dry run is the default and writes nothing; `--manifest PATH` writes the JSON manifest (`path`, `reason`, `action`, `target`, `keep`, `rollup`). Expiry is decided first, so an expired or archived copy is never the one kept. Reasons: `duplicate` (canonical copy among the LIVE copies: own namespace folder > any namespace folder > `status: verified` > later `expires` > `source-record` > post-#725 slug > newer `updated`), `superseded` (same slug modulo hyphens, different insight; newest kept), `expired`, `metrics-only-session` (its rollup row is written first), `namespace-alias` (a folder that equals another modulo hyphens and has fewer of them, or `--alias FROM=TO`), `flat-relocate` (flat note whose `source-repo` names its namespace). `--apply` writes the rollups, then moves archived notes to `90-archive/mirror/<zone>/<same path>` with `status: archived` + `archived-reason`, then renames the relocated ones — never deletes, never touches a note without the `_generator` marker, re-checks ownership right before each move, refuses any source or target that resolves outside the vault (realpath of the nearest existing ancestor), writes a note whose archive target is occupied by OTHER content beside it as `<name>.dup-<hash8>.md` (listed under `applied.suffixed` in the manifest), and is idempotent (a second run plans nothing). `90-archive/` is outside vault-sync's checked zones but inside its link-target register, so wiki-links into archived notes keep resolving; the mirror's source-session index walks `90-archive/mirror/50-sessions/` for the same reason, and `backfill-learnings-from-vault.mjs` falls back to `90-archive/mirror/40-learnings/`.
+
+**Order (runbook).** (1) Update the plugin on EVERY host that runs session-end against this vault (M4 and M5): an old mirror re-creates every note the pruner moved. (2) Run one mirror pass per repo ledger so session notes written before the narrative fields were rendered are healed — otherwise the pruner reads them as metrics-only. (3) Dry run, read the manifest. (4) `--apply`, then commit the vault.
+
+```bash
+# (2) per repo, from its canonical checkout
+node scripts/vault-mirror.mjs --vault-dir <vault> --source <repo>/.orchestrator/metrics/sessions.jsonl --kind session --repo-root <repo> --no-commit
+# (3) + (4)
+node scripts/vault-mirror-prune.mjs --vault-dir <vault> --manifest /tmp/vault-prune-manifest.json   # plan
+node scripts/vault-mirror-prune.mjs --vault-dir <vault> --apply --manifest /tmp/vault-prune-applied.json
+```
+
 ## Idempotency
 
 vault-mirror is safe to run multiple times against the same JSONL source:

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

@@ -100,7 +100,7 @@ Before each wave dispatch:
      --assert-disjoint "$WAVE_SCOPES_SIDECAR" < <state-dir>/wave-scope.json
    ```
 
-   Exit 1 (one stderr message per collision) means two agents were handed the same file: fix the session plan, re-materialize, re-assert. Never widen the union to make it pass. This runs **before** 3.3 because a union computed over colliding scopes launders the defect into the very artefact meant to prevent it — `allowedPaths` then grants the file and every later gate sees a legal write.
+   Exit 1 (one stderr message per collision) means two agents were handed the same file: fix the session plan, re-materialize, re-assert. Where no manifest exists yet (`/plan` checking a draft), pass `--no-manifest` instead of piping a fabricated one — it checks the sidecar alone, and is rejected together with `--union` / `--assert-subset` (#1510 f). Never widen the union to make it pass. This runs **before** 3.3 because a union computed over colliding scopes launders the defect into the very artefact meant to prevent it — `allowedPaths` then grants the file and every later gate sees a legal write.
 
    **3.3 — compute the union.** `--union` is a QUERY MODE that still requires a schema-valid manifest on stdin, so write the skeleton first with `"allowedPaths": []`, then:
 
@@ -125,6 +125,8 @@ Before each wave dispatch:
 
    > Measured at `HEAD=730ee9d`, 2026-08-03, clean-tree, via `git ls-files | grep -E '^(scripts|hooks|skills)/.*\.mjs$'` for the denominator, matched against `git ls-files | grep -E '^tests/.*\.test\.mjs$'` by basename (85.4% figure) and by mirrored path (62.0% figure). Re-measure before citing these downstream — a count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006).
 
+   > **Over-grant ceiling (#1030):** the glob is a basename *prefix* (`tests/**/{basename}*.test.mjs`, `scripts/lib/scope-gate.mjs:312`), so a production file sharing a basename with another receives the other's test siblings — and a stem that prefixes another (`cli` → `cli-flags`) does too, so the figure below is a lower bound. Measured at `HEAD=0e0c4b08`, 2026-10-03: `git ls-files '*.mjs' | grep -v '^tests/' | xargs -n1 basename | sort | uniq -d | wc -l` → **34** colliding basenames, covering **80 of 572** production `.mjs` (**14.0 %**; files via `… | sort | uniq -D | wc -l`, denominator via `git ls-files '*.mjs' | grep -v '^tests/' | wc -l`; top: `schema.mjs` 8×). The error direction is the harmless one — a too-wide grant, never a denied write. **Revisit-Trigger:** a plan author disables the sibling expansion to dodge a false-positive collision between two same-named production files — then scope the glob by directory, but NOT by a raw `{dir}`: `renderSiblingTemplate` fills it with `scripts/lib`, while the test tree drops the `scripts/` prefix (`tests/lib/`), so a raw `{dir}` would deny real test writes; it needs a source→test prefix mapping first.
+
    **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: