session-orchestrator 5.5.0 → 5.7.0

package/hooks/pre-task-scope-disjoint.mjs

@@ -267,6 +267,7 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 /** @type {typeof import('../scripts/lib/scope-echo.mjs').scopeDigest} */ let scopeDigest;
 /** @type {typeof import('../scripts/lib/platform.mjs').resolveSessionRoot} */ let resolveSessionRoot;
 let findScopeCollisions;
+/** @type {typeof import('../scripts/lib/scope-gate.mjs').scopeEntrySpelling} */ let scopeEntrySpelling;
 let findOwnScopeFile;
 let readProcessLocalSessionIds;
 let classifyManifestSession;
@@ -581,7 +582,7 @@ async function bootstrap() {
   );
 
   ({ readStdin, emitAllow, emitDeny, emitWarn, writeJsonAtomicSync } = modules.io);
-  ({ findScopeCollisions, findOwnScopeFile } = modules.scopeGate);
+  ({ findScopeCollisions, findOwnScopeFile, scopeEntrySpelling } = modules.scopeGate);
   ({ readProcessLocalSessionIds, classifyManifestSession } = modules.sessionIdentity);
   ({ withFileLock } = modules.fileLock);
   ({ scopeDigest } = modules.scopeEcho);
@@ -739,36 +740,6 @@ function cleanScopeLine(line) {
     .trim();
 }
 
-/**
- * Canonicalise a scope entry's SPELLING so two agents writing the same file two
- * ways are not read as disjoint (review LOW). Measured before this existed:
- * `['./scripts/lib/foo.mjs']` vs `['scripts/lib/foo.mjs']` compared `ok: true`
- * — the hook extracts from PROSE, and `looksLikeRepoPath` admits a `./` prefix,
- * so both spellings reach the comparison verbatim.
- *
- * Purely syntactic and meaning-preserving: `./` prefixes, `/./` segments and
- * duplicated slashes are removed. A TRAILING slash is deliberately kept — it is
- * the directory-prefix operator of `pathMatchesPattern`, so stripping it would
- * silently narrow a scope. The `dir` ↔ `dir/` case is handled by
- * {@link promoteDirEntries}, which decides it on evidence rather than guessing.
- *
- * `scope-gate.mjs` is a hook-safe pure library and out of this change's scope,
- * so the normalisation lives on THIS side of the call, applied to both sides of
- * every comparison.
- *
- * @param {string} entry
- * @returns {string}
- */
-export function normalizeScopeEntry(entry) {
-  if (typeof entry !== 'string') return '';
-  let s = entry.trim();
-  if (s === '') return '';
-  s = s.replace(/\/{2,}/g, '/');       // `a//b` → `a/b`
-  s = s.replace(/(?:^|\/)\.\//g, (m) => (m.startsWith('/') ? '/' : '')); // `./a`, `a/./b`
-  while (s.startsWith('./')) s = s.slice(2);
-  return s;
-}
-
 /**
  * Promote an entry that names a DIRECTORY to its `dir/` prefix form, on
  * evidence. `scripts/lib` and `scripts/lib/` are the same claim, but
@@ -815,7 +786,11 @@ function collectScopePaths(segments) {
   for (const raw of segments) {
     // A trailing sentence period is punctuation, never part of a path
     // (measured: "docs/events-schema.md." at the end of an inline declaration).
-    const cleaned = normalizeScopeEntry(cleanScopeLine(raw).replace(/\.$/, ''));
+    // Lexical cleaning only (prose → path); the SPELLING rule is
+    // `scopeEntrySpelling` in scope-gate.mjs, applied in `decide()` (#1510 g).
+    // The second trim: a period stripped after `cleanScopeLine`'s trim can
+    // expose a space (`foo.mjs .`), which `looksLikeRepoPath` would reject.
+    const cleaned = cleanScopeLine(raw).replace(/\.$/, '').trim();
     if (!looksLikeRepoPath(cleaned)) continue;
     if (seen.has(cleaned)) continue;
     seen.add(cleaned);
@@ -906,7 +881,8 @@ export function extractScopeSignal(prompt) {
  * (and the tests that pin them) keep the original signature.
  *
  * @param {string} prompt
- * @returns {string[]} repo-relative paths/globs, normalised, deduped, order preserved
+ * @returns {string[]} repo-relative paths/globs as declared (lexically cleaned,
+ *   deduped, order preserved) — the SPELLING rule runs in `decide()` (#1510 g)
  */
 export function extractScopeFromPrompt(prompt) {
   return extractScopeSignal(prompt).files;
@@ -2070,9 +2046,11 @@ export function scopeDigestFields(files, prompt, digestFn) {
  * @param {string} [params.nowIso]            dispatch timestamp recorded on the entry
  * @param {(paths: string[]) => string} [params.digestFn] scope-digest function
  *   (injected for testability; defaults to the late-bound `scopeDigest`)
+ * @param {(entry: string) => string} [params.spellFn] scope-entry spelling rule
+ *   (injected for testability; defaults to the late-bound `scopeEntrySpelling`)
  * @returns {Verdict}
  */
-export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso, digestFn }) {
+export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, collide, isFinished, nowIso, digestFn, spellFn }) {
   const toolName = input?.tool_name;
   // Row 4: not our tool.
   if (toolName !== DISPATCH_TOOL) return { action: 'allow' };
@@ -2083,7 +2061,14 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   const at = typeof nowIso === 'string' ? nowIso : new Date().toISOString();
 
   const signal = extractScopeSignal(toolInput.prompt);
-  const files = signal.files;
+  // #1510 g — ONE spelling rule, scope-gate's, applied before the ledger, the
+  // digest and `promoteDirEntries` see an entry: `./scripts/lib` must reach the
+  // dir-promotion as `scripts/lib`, or a bare-dir claim stays a literal and
+  // compares disjoint with the files beneath it. Re-deduped on the spelling.
+  // Unbound (a direct importer that never ran `bootstrap()`) ⇒ entries as
+  // extracted; `findScopeCollisions` still spells both sides itself.
+  const spell = typeof spellFn === 'function' ? spellFn : scopeEntrySpelling;
+  const files = typeof spell === 'function' ? [...new Set(signal.files.map(spell))] : signal.files;
   const id = agentIdOf(toolInput);
   const priorAgents = (ledger !== null && ledger?.waveKey === waveKey && Array.isArray(ledger.agents))
     ? ledger.agents

package/hooks/wave-scope-commit-guard.mjs

@@ -48,8 +48,8 @@
 //     `git commit --no-verify` skips it entirely (operator opts out by name).
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
 
 // Re-use existing helpers from scripts/lib/hardening.mjs.
 // IMPORTANT: import is resolved relative to THIS file's location (the hook
@@ -59,6 +59,7 @@ import { join, relative } from 'node:path';
 import { pathMatchesPattern } from '../scripts/lib/hardening.mjs';
 import { withStagingFenceLock } from '../scripts/lib/session-lock.mjs';
 import { isMainModule } from '../scripts/lib/is-main-module.mjs';
+import { resolveSessionRoot } from '../scripts/lib/platform.mjs';
 import { classifyEmptyScope, findOwnScopeFile, sessionAgeMs } from '../scripts/lib/scope-gate.mjs';
 import {
   classifyManifestSession,
@@ -153,6 +154,29 @@ function findOverlaps(fenceJsonPath, ourStaged) {
   return matches;
 }
 
+/** Remediation for an allowedPaths violation, printed once per commit. */
+const ALLOWED_PATHS_HINT = [
+  '',
+  'These files were likely added by lint-staged eslint --fix / prettier --write.',
+  'To proceed:',
+  '  1) git restore --staged <path>   # for each foreign path',
+  '  2) git commit                    # retry',
+];
+
+/**
+ * A manifest path for messages: relative to the repo root, the absolute path
+ * when it does not lie beneath it (#1514.2 — two candidate manifests, so a
+ * message must say which one it means).
+ *
+ * @param {string} repoRoot
+ * @param {string} scopePath
+ * @returns {string}
+ */
+function manifestLabel(repoRoot, scopePath) {
+  const rel = relative(repoRoot, scopePath);
+  return rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) ? scopePath : rel;
+}
+
 /** mtime of a file in ms, or `null` when it cannot be stat'ed. */
 function mtimeMsOf(file) {
   try {
@@ -175,14 +199,23 @@ function mtimeMsOf(file) {
  *
  * @param {object} p
  * @param {Record<string, unknown>} p.scope parsed manifest
- * @param {string[]} p.stagedFiles
- * @param {string} p.scopeRel manifest path for messages, repo-relative
+ * @param {string[]} p.stagedFiles  repo-relative, as `git diff --cached` prints them
+ * @param {(f: string) => string|null} [p.scopePathOf]  a staged path as the
+ *   manifest names it — relative to the SESSION root; identity when that is the
+ *   repo root. `null` = the path lies OUTSIDE the session root: a violation
+ *   without pattern matching, since a `../`-prefixed path would match a glob
+ *   like `**\/*.mjs` and enforce-scope denies every write outside its root
+ *   (REQ-04).
+ * @param {string} p.scopeRel manifest path for messages, repo-relative (absolute
+ *   when outside the repo root) — `manifestLabel`
  * @param {Set<string>} p.ownIds this process's session ids
  * @param {number|null} p.scopeMtimeMs
  * @param {number|null} p.sessionAge ms since the newest session clock
- * @returns {{action: 'pass'|'report'|'block', lines: string[]}}
+ * @returns {{action: 'pass'|'report'|'block', lines: string[], hint?: string[]}}
+ *   `hint` = the remediation block; `main()` prints it ONCE after every
+ *   manifest was judged, so two blocking manifests do not repeat it (#1514.3).
  */
-function scopeCommitVerdict({ scope, stagedFiles, scopeRel, ownIds, scopeMtimeMs, sessionAge }) {
+function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeRel, ownIds, scopeMtimeMs, sessionAge }) {
   if (stagedFiles.length === 0) return { action: 'pass', lines: [] };
 
   // Same classifier and same disposition as enforce-scope Gate 3b: only a
@@ -200,7 +233,10 @@ function scopeCommitVerdict({ scope, stagedFiles, scopeRel, ownIds, scopeMtimeMs
   const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
   if (allowedPaths.length > 0) {
     const violations = stagedFiles.filter(
-      (f) => !allowedPaths.some((pattern) => pathMatchesPattern(f, pattern)),
+      (f) => {
+        const scoped = scopePathOf(f);
+        return scoped === null || !allowedPaths.some((pattern) => pathMatchesPattern(scoped, pattern));
+      },
     );
     if (violations.length === 0) return { action: 'pass', lines: [] };
     // Blocks under `warn` too — see the header: in a warn-mode wave this is
@@ -208,14 +244,10 @@ function scopeCommitVerdict({ scope, stagedFiles, scopeRel, ownIds, scopeMtimeMs
     return {
       action: 'block',
       lines: [
-        '✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:',
+        `✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths (${scopeRel}):`,
         ...violations.map((v) => `  - ${v}`),
-        '',
-        'These files were likely added by lint-staged eslint --fix / prettier --write.',
-        'To proceed:',
-        '  1) git restore --staged <path>   # for each foreign path',
-        '  2) git commit                    # retry',
       ],
+      hint: ALLOWED_PATHS_HINT,
     };
   }
 
@@ -258,6 +290,30 @@ function scopeCommitVerdict({ scope, stagedFiles, scopeRel, ownIds, scopeMtimeMs
   };
 }
 
+/**
+ * The session root a commit at `repoRoot` is judged against when it lies
+ * STRICTLY inside the repo, else `null` (judge at `repoRoot`, as before) — see
+ * the call site in `main()` (#1511 point d). Both sides realpath-resolved, so
+ * macOS `/var` vs `/private/var` cannot split one directory in two.
+ *
+ * @param {string} repoRoot  `git rev-parse --show-toplevel`
+ * @returns {{sessionRoot: string, realRepoRoot: string}|null}
+ */
+function subdirSessionRoot(repoRoot) {
+  const canon = (p) => {
+    // `.native` canonicalises letter case on case-insensitive APFS (as
+    // enforce-scope's clamp does since #1504 pt 8); the JS realpath keeps a
+    // case-different CLAUDE_PROJECT_DIR verbatim, which relativises to `../..`
+    // against the git toplevel and switches the subdirectory mode off silently.
+    try { return realpathSync.native(p); } catch { return p; }
+  };
+  const realRepoRoot = canon(repoRoot);
+  const sessionRoot = canon(resolveSessionRoot(repoRoot, repoRoot));
+  const rel = relative(realRepoRoot, sessionRoot);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return null;
+  return { sessionRoot, realRepoRoot };
+}
+
 /**
  * Both sub-modes, in the order the pre-commit hook needs them. Every statement
  * here used to sit at module top level, which meant a bare `import()` of this
@@ -282,8 +338,34 @@ async function main() {
   // committing session's env; there is no hook payload here, so the env tier is
   // the only process-local identity.
   const ownIds = new Set(readProcessLocalSessionIds());
-  const located = findOwnScopeFile(repoRoot, ownIds, classifyManifestSession);
-  const scopePath = located.path ?? located.foreignPath;
+
+  // #1511 point d — ALSO read the manifest at the SESSION root the scope guards
+  // resolve (`resolveSessionRoot`, enforce-scope.mjs): a session launched in a
+  // repo SUBDIRECTORY keeps its manifest there, so the repo root held none and
+  // sub-mode B never ran for it. git runs this hook at the worktree top level
+  // and the committing session's env (the launch dir) is inherited, so the
+  // toplevel stands in for the payload `cwd` the Edit/Write guards get. Only a
+  // root STRICTLY inside the repo is adopted: the one rung that answers above it
+  // (a harness `agent-<hex>` worktree lifted to its launch checkout) would judge
+  // this repo's staged paths against another tree's manifest.
+  //
+  // The repo-root manifest is ALWAYS judged exactly as before #1511 d, and the
+  // subdirectory manifest is judged IN ADDITION, each against its own path
+  // mapping; either one blocking blocks. So the verdict is never laxer than the
+  // repo-root-only guard it extends — choosing ONE of the two manifests let an
+  // unbound or `enforcement: off` subdirectory manifest silence a repo-root wave
+  // that blocked the same commit (second review, MED-1).
+  const subdir = subdirSessionRoot(repoRoot);
+  const judgements = [{ root: repoRoot, scopePathOf: (f) => f }];
+  if (subdir !== null) {
+    judgements.push({
+      root: subdir.sessionRoot,
+      scopePathOf: (f) => {
+        const rel = relative(subdir.sessionRoot, join(subdir.realRepoRoot, f));
+        return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) ? null : rel;
+      },
+    });
+  }
   const fenceDir = join(repoRoot, '.orchestrator', 'staging-fence');
 
   // -------------------------------------------------------------------------
@@ -293,26 +375,41 @@ async function main() {
   const stagedOutput = execSync('git diff --cached --name-only', { encoding: 'utf8' });
   const stagedFiles = stagedOutput.split('\n').filter(Boolean);
 
-  if (scopePath) {
+  let blocked = false;
+  /** @type {string[]|null} printed once after the loop (#1514.3) */
+  let hint = null;
+  const flushHint = () => {
+    if (hint !== null) for (const line of hint) process.stderr.write(`${line}\n`);
+  };
+  for (const { root, scopePathOf } of judgements) {
+    const located = findOwnScopeFile(root, ownIds, classifyManifestSession);
+    const scopePath = located.path ?? located.foreignPath;
+    if (!scopePath) continue;
+    const scopeRel = manifestLabel(repoRoot, scopePath);
     let scope;
     try {
       scope = JSON.parse(readFileSync(scopePath, 'utf8'));
     } catch (err) {
-      process.stderr.write(`wave-scope-commit-guard: failed to parse wave-scope.json: ${err.message}\n`);
+      process.stderr.write(`wave-scope-commit-guard: failed to parse ${scopeRel}: ${err.message}\n`);
+      flushHint();
       process.exit(1);
     }
 
     const verdict = scopeCommitVerdict({
       scope: scope !== null && typeof scope === 'object' ? scope : {},
       stagedFiles,
-      scopeRel: relative(repoRoot, scopePath) || scopePath,
+      scopePathOf,
+      scopeRel,
       ownIds,
       scopeMtimeMs: mtimeMsOf(scopePath),
-      sessionAge: sessionAgeMs(repoRoot),
+      sessionAge: sessionAgeMs(root),
     });
     for (const line of verdict.lines) process.stderr.write(`${line}\n`);
-    if (verdict.action === 'block') process.exit(1);
+    if (verdict.hint) hint = verdict.hint;
+    if (verdict.action === 'block') blocked = true;
   }
+  flushHint();
+  if (blocked) process.exit(1);
 
   // -------------------------------------------------------------------------
   // Sub-mode C — cross-agent staging-fence reconciliation (issue #552)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-orchestrator",
-  "version": "5.5.0",
-  "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
+  "version": "5.7.0",
+  "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
   "keywords": [
@@ -16,7 +16,12 @@
     "orchestration",
     "developer-tools",
     "mcp",
-    "llm"
+    "llm",
+    "workflow",
+    "quality-gates",
+    "ai-coding",
+    "gitlab",
+    "github"
   ],
   "engines": {
     "node": ">=24.0.0"

package/scripts/backfill-abandoned-sessions.mjs

@@ -42,8 +42,8 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
-import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst } from './lib/events.mjs';
-import { ARCHIVE_DIR_NAME, ROTATION_EVENT } from './lib/events-schema.mjs';
+import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst, tombstoneGap } from './lib/events.mjs';
+import { ARCHIVE_DIR_NAME } from './lib/events-schema.mjs';
 import { getProjectDir } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { isLockLive, readLock } from './lib/session-lock.mjs';
@@ -163,7 +163,8 @@ export function planSessions({ repoRoot }) {
  * not one of the sources read (#1498). Pruned history used to shrink the plan
  * silently; non-zero `historyGaps` says the candidate count is a floor.
  *
- * The check is `readEventsWithRotations` rule 1 (`scripts/lib/events.mjs`):
+ * The check is `tombstoneGap` (`scripts/lib/events.mjs`), the one shared with
+ * `readEventsWithRotations` rule 1:
  * resolved by BASENAME against this ledger's own `_archive/` (#1411), and a
  * file that exists but is not a source (renamed out of `ARCHIVE_NAME_RE`)
  * counts as a gap too — existence is not reading (#1423).
@@ -203,10 +204,7 @@ function planWithGaps({ repoRoot }) {
   for (const source of [...sources].reverse()) {
     forEachJsonlRecord(source.path, (ev) => {
       if (!ev || typeof ev !== 'object') return;
-      if (ev.event === ROTATION_EVENT && typeof ev.archived_as === 'string' && ev.archived_as.length > 0
-        && !read.has(path.join(archiveDir, path.basename(ev.archived_as)))) {
-        historyGaps += 1;
-      }
+      if (tombstoneGap(ev, archiveDir, read) !== null) historyGaps += 1;
       if (typeof ev.session_id === 'string' && typeof ev.semantic_session_id === 'string') {
         if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
         else if (ev.event === SESSION_ENDED) {

package/scripts/backfill-learnings-from-vault.mjs

@@ -837,6 +837,19 @@ export async function main(argv = [], deps = {}) {
   const archiveIds = idsInStore(archiveAbs);
   const backups = backupPaths(storeAbs).map((p) => ({ path: p, ids: idsInStore(p) }));
   const { notes, unreadable } = indexVaultNotes(learningsAbs);
+  // #1513: `vault-mirror-prune --apply` moves expired/duplicate/superseded
+  // learning notes to `90-archive/mirror/<subdir>/…` with their bytes intact.
+  // They are still evidence for this restore tool — but only as a FALLBACK:
+  // the archive holds the non-canonical twins of live notes, and searching
+  // both at once would turn every such learning into an ambiguous match.
+  const archivedAbs = resolve(vaultDir, '90-archive', 'mirror', vaultSubdir);
+  const archivedNotes = [];
+  if (archivedAbs !== learningsAbs && existsSync(archivedAbs)) {
+    const archived = indexVaultNotes(archivedAbs);
+    for (const n of archived.notes) n.relPath = join('90-archive', 'mirror', vaultSubdir, n.relPath);
+    archivedNotes.push(...archived.notes);
+    unreadable.push(...archived.unreadable);
+  }
   for (const u of unreadable) process.stderr.write(`backfill-learnings-from-vault: WARN unreadable vault note ${u}\n`);
 
   const repoHint = basename(root);
@@ -879,12 +892,10 @@ export async function main(argv = [], deps = {}) {
 
     orphanIndex += 1;
     const keySubjectSlug = prov.learningKey ? prov.learningKey.split('/').slice(1).join('/') : null;
-    const { note, strategy, ambiguous } = locateNote(notes, {
-      subject: prov.subject,
-      keySlug: keySubjectSlug,
-      learningId: id,
-      repoHint,
-    });
+    const query = { subject: prov.subject, keySlug: keySubjectSlug, learningId: id, repoHint };
+    let located = locateNote(notes, query);
+    if (!located.note && !located.ambiguous && archivedNotes.length > 0) located = locateNote(archivedNotes, query);
+    const { note, strategy, ambiguous } = located;
 
     const { record, fidelity, conflicts, crossChecks, validates, validationError } = reconstructRecord({
       rule: prov,

package/scripts/lib/dispatcher/rank.mjs

@@ -202,7 +202,11 @@ async function defaultStaleDaysFor(repoRoot, nowMs) {
     const days = (nowMs - latestMs) / MS_PER_DAY;
     return days > 0 ? days : 0;
   } catch {
-    // No sessions file (or unreadable) ⇒ never worked on ⇒ maximally stale.
+    // Not the missing/unreadable-ledger path: readCanonicalSessions already
+    // returns [] for both (ENOENT silently, any other read failure with a
+    // stderr WARN — sessions-canonical.mjs § #1188), handled by the
+    // `records.length === 0` branch above. This catch only absorbs an
+    // unexpected throw (e.g. a non-string repoRoot) ⇒ maximally stale.
     return STALENESS_CAP_DAYS;
   }
 }

package/scripts/lib/events.mjs

@@ -578,6 +578,60 @@ function discoverArchives(logPath) {
   return { archives, legacy: present.map((i) => `${logPath}.${i}`), ringHoles, unindexed };
 }
 
+/**
+ * The one tombstone-to-archive match (#1505 5c) — shared by
+ * {@link readEventsWithRotations} rule 1, {@link scanEventsBackwards}, and
+ * `planWithGaps` in `scripts/backfill-abandoned-sessions.mjs`, which used to
+ * carry three hand-kept copies of it.
+ *
+ * #1411 — the tombstone resolves against THIS ledger's own `_archive/`, by
+ * BASENAME, never against the absolute value it stores. The writer keeps
+ * `archived_as` absolute (`events-rotation.mjs` joins the repo root) and that
+ * value stays in the record as PROVENANCE. It is not a lookup key: a moved
+ * checkout, a clone, or a sibling git worktree — routine here — makes every
+ * tombstone name a path that does not exist in THIS tree, so an exact
+ * comparison reported a phantom `missing-archive` for an archive sitting right
+ * beside the active file. Basename, not `realpath`: realpath cannot resolve a
+ * path that no longer exists, which IS the failure mode.
+ *
+ * ORDER (why the absolute value has no second chance): the sibling answer is
+ * consulted first, and an absolute hit would only be trustworthy while it
+ * pointed INSIDE this ledger's own archive dir — but any such path resolves to
+ * exactly the sibling path already tested, so once the sibling misses, an
+ * absolute hit can ONLY be a still-present OLD checkout. Honouring it would
+ * validate THIS ledger against a FOREIGN repo's archive: a silent false
+ * negative, worse than the phantom gap.
+ *
+ * #1423 — THREE outcomes, not two: read (`null`), present-but-unread
+ * (`unindexed-archive`), gone (`missing-archive`). The middle one used to be
+ * folded into the first by `existsSync`, so a tombstone whose archive had been
+ * RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its records
+ * were absent.
+ *
+ * @param {unknown} record  a parsed ledger line
+ * @param {string} ownArchiveDir  this ledger's `_archive/`, built exactly as
+ *   `discoverArchives` builds it so a read archive matches `readSet` by string
+ * @param {Set<string>} readSet  the paths this read actually took as sources
+ * @returns {{kind: 'unindexed-archive'|'missing-archive', path: string,
+ *            archived_as: string, first_ts: string|null, last_ts: string|null}|null}
+ *   `null` when `record` is not a rotation tombstone, names no archive, or its
+ *   archive was read.
+ */
+export function tombstoneGap(record, ownArchiveDir, readSet) {
+  if (record?.event !== ROTATION_EVENT) return null;
+  const target = record.archived_as;
+  if (typeof target !== 'string' || target.length === 0) return null;
+  const sibling = path.join(ownArchiveDir, path.basename(target));
+  if (readSet.has(sibling)) return null;
+  return {
+    kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
+    path: sibling,
+    archived_as: target,
+    first_ts: record.first_ts ?? null,
+    last_ts: record.last_ts ?? null,
+  };
+}
+
 /**
  * Read the events ledger ACROSS rotation boundaries — active file plus every
  * archive still on disk — in time order, reporting what is missing instead of
@@ -660,44 +714,14 @@ export function readEventsWithRotations(repoRoot, opts = {}) {
   // `onDisk` still match by string.
   const ownArchiveDir = path.join(path.dirname(activePath), ARCHIVE_DIR_NAME);
 
-  // Rule 1 — every rotation tombstone must still point at a file.
+  // Rule 1 — every rotation tombstone must still point at a file (resolution
+  // and the three outcomes: {@link tombstoneGap}).
   for (const source of sources) {
     for (const record of source.records) {
-      if (record?.event !== ROTATION_EVENT) continue;
-      const target = record.archived_as;
-      if (typeof target !== 'string' || target.length === 0) continue;
-      // #1411 — resolve the tombstone against THIS ledger's own `_archive/`,
-      // by BASENAME, and never against the absolute value it stores.
-      //
-      // The writer keeps `archived_as` absolute (`events-rotation.mjs` joins
-      // the repo root) and that value stays in the record as PROVENANCE. It is
-      // not a lookup key: a moved checkout, a clone, or a sibling git worktree
-      // — routine here — makes every tombstone name a path that does not exist
-      // in THIS tree, so the old exact comparison reported a phantom
-      // `missing-archive` for an archive sitting right beside the active file.
-      // Basename, not `realpath`: realpath cannot resolve a path that no longer
-      // exists, which IS the failure mode.
-      //
-      // ORDER (why the absolute value has no second chance): the sibling answer
-      // is consulted first, and an absolute hit would only be trustworthy while
-      // it pointed INSIDE this ledger's own archive dir — but any such path
-      // resolves to exactly the sibling path already tested, so once the
-      // sibling misses, an absolute hit can ONLY be a still-present OLD
-      // checkout. Honouring it would validate THIS ledger against a FOREIGN
-      // repo's archive: a silent false negative, worse than the phantom gap.
-      const sibling = path.join(ownArchiveDir, path.basename(target));
-      if (onDisk.has(sibling)) continue;
+      const gap = tombstoneGap(record, ownArchiveDir, onDisk);
+      if (gap === null) continue;
       gaps.push({
-        // #1423 — THREE outcomes, not two: read (above), present-but-unread
-        // (here), gone (below). The middle one used to be silently folded into
-        // the first by `existsSync`, so a tombstone whose archive had been
-        // RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its
-        // records were absent from `events`.
-        kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
-        path: sibling,
-        archived_as: target,
-        first_ts: record.first_ts ?? null,
-        last_ts: record.last_ts ?? null,
+        ...gap,
         lines: record.lines ?? null,
         size_before: record.size_before ?? null,
         reported_by: source.path,
@@ -866,8 +890,7 @@ export function scanEventsBackwards(opts = {}) {
    * LOW-2): `maybeRotate` renames, prunes, THEN appends the tombstone, from an
    * async SessionStart hook, so a concurrent append can land first and push it
    * to line 2. Called BEFORE the caller's `filter`, which names another event
-   * and would otherwise hide the cut. Resolved by basename against this
-   * ledger's own `_archive/`, never by the absolute provenance value (#1411).
+   * and would otherwise hide the cut. Matched by {@link tombstoneGap}.
    */
   const noteCut = (line, source) => {
     if (!line.includes(ROTATION_EVENT)) return;
@@ -877,18 +900,8 @@ export function scanEventsBackwards(opts = {}) {
     } catch {
       return; // counted by `consume` like every other malformed line
     }
-    const target = record?.event === ROTATION_EVENT ? record.archived_as : null;
-    if (typeof target !== 'string' || target.length === 0) return;
-    const sibling = path.join(ownArchiveDir, path.basename(target));
-    if (listed.has(sibling)) return;
-    gaps.push({
-      kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
-      path: sibling,
-      archived_as: target,
-      first_ts: record.first_ts ?? null,
-      last_ts: record.last_ts ?? null,
-      reported_by: source.path,
-    });
+    const gap = tombstoneGap(record, ownArchiveDir, listed);
+    if (gap !== null) gaps.push({ ...gap, reported_by: source.path });
   };
 
   /** @returns {boolean} true ⇒ the caller accepted a record; stop everything. */

package/scripts/lib/io.mjs

@@ -946,16 +946,21 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  * neither may mask the original error.
  *
  * ── BV-004 ceiling + revisit trigger ────────────────────────────────────────
- * TWO PRODUCTION CALL-SITES: `vault-status/board-writer.mjs#writeBoard`
- * (`backup: false`) and {@link writeJsonAtomicSync}, which carries 12 further
- * call-sites across 9 files behind it. That second one is the load-bearing
+ * THREE PRODUCTION CALL-SITES (re-measured 2026-10-03 @ 0e0c4b08 with
+ * `rg -n "atomicWriteWithBackup\(" scripts hooks skills --glob '*.mjs'`):
+ * `vault-status/board-writer.mjs#writeBoard` (`backup: false`),
+ * `reconcile/rule-expiry-sweep.mjs` (no `backup`, i.e. `false`) and
+ * {@link writeJsonAtomicSync}, which carries 14 further call-sites across 11
+ * files behind it (`rg -n "writeJsonAtomicSync\("` over the same scope, minus
+ * the definition and `host-identity.mjs`'s private `_writeJsonAtomicSync`
+ * copy, which does NOT route through this helper). That last one is the load-bearing
  * evidence — the previous revision of this note recorded ONE call-site and
  * concluded the signature was unproven, while the function with an identical
  * body sat 60 lines above in this same file, unmigrated. The cheapest possible
  * migration going unmade is not a neutral fact about a helper: it is the
  * measurement that the helper is not paying for itself.
  *
- * What the second call-site does NOT prove: `writeJsonAtomicSync` passes
+ * What the `writeJsonAtomicSync` call-site does NOT prove: it passes
  * `backup: false` and no `fs`, so the backup half and the injection seam still
  * rest on tests plus one board-writer flag. REVISIT TRIGGER — when a sweep
  * migrates the remaining hand-rolled sites, re-check before widening:

package/scripts/lib/learnings/candidates.mjs

@@ -185,7 +185,7 @@
 
 import { tokenize } from './affinity.mjs';
 import { readLearnings } from './io.mjs';
-import { kebab } from './kebab.mjs';
+import { learningKeyOf } from './kebab.mjs';
 import { normalizeDialects } from './schema.mjs';
 
 // ---------------------------------------------------------------------------
@@ -441,27 +441,18 @@ export function emptyPools() {
 /**
  * Logical identity of a learning: `` `${type}/${kebab(title || subject)}` ``.
  *
- * Returns `null` when either half is unusable — mirroring
- * `validate/check-learning-provenance.mjs::learningKeyOf`, so an unkeyable
- * record simply does not participate in the exact-key pass. It still seeds and
+ * Returns `null` when either half is unusable (non-record input, blank
+ * type/title/subject, or an all-symbol title that kebabs to '') — delegates to
+ * the shared `kebab.mjs::learningKeyOf` (#1021) so the key space cannot fork
+ * from the provenance checker's. An unkeyable record simply does not
+ * participate in the exact-key pass. It still seeds and
  * joins pools: a missing title is not a reason to hide a learning from dedupe.
  *
  * @param {unknown} record
  * @returns {string|null}
  */
 export function learningKey(record) {
-  if (!_isRecord(record)) return null;
-  const type = typeof record.type === 'string' ? record.type.trim() : '';
-  const titleOrSubject =
-    (typeof record.title === 'string' && record.title.trim() !== '' ? record.title : '') ||
-    (typeof record.subject === 'string' && record.subject.trim() !== '' ? record.subject : '');
-  if (type === '' || titleOrSubject === '') return null;
-  const slug = kebab(titleOrSubject);
-  // `kebab` may legally return '' (all-symbol input) — an empty slug is not an
-  // identity, so such a record is unkeyable rather than colliding with every
-  // other empty-slug record of the same type.
-  if (slug === '') return null;
-  return `${type}/${slug}`;
+  return learningKeyOf(record);
 }
 
 /**