dotmd-cli 0.81.0 → 0.83.0

package/README.md

@@ -282,6 +282,26 @@ export const types = {
 };
 ```
 
+### Code references
+
+Archive and rename repair every reference inside the doc roots. `codeRoots`
+extends that to source files that cite a document by its repo-relative path in
+a comment, a docstring or a string literal:
+
+```js
+export const codeRoots = ['packages', 'scripts', 'services'];
+export const codeRefsUntouched = ['scripts/guards/plan-baseline.json'];
+```
+
+`runlist refs <old> <new>` reports every citation by file and line and writes
+only on `--fix`; `runlist refs repair` does the same for every archived
+document still cited at its previous path. Archive and rename print the count
+afterwards and take `--fix-refs`. Only the full repo-relative path matches,
+never a bare basename, and only that segment is replaced, so a trailing `§` or
+`#` anchor survives. A citation inside a string literal waits for `--strings`,
+a file in `codeRefsUntouched` is never written, and with no `codeRoots` set
+nothing is scanned.
+
 Configuration supports multiple roots, custom types and templates, taxonomy,
 reference fields, presets, rendering, lifecycle hooks, validation hooks, and
 AI summarization hooks. See [`runlist.config.example.mjs`](runlist.config.example.mjs)

package/bin/dotmd.mjs

@@ -256,6 +256,8 @@ Validate & Fix:
   self-check                        Project/version skew diagnostic (alias: doctor --project)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
+  refs <old> <new> [--fix]          Report (or rewrite) code-root citations of a moved document
+  refs repair [--fix]               Same, for every archived document still cited at its old path
   fix-membership [<hub>...]         Add unambiguous missing child parent_plan back-references
   sync-status [<hub>...] [--adopt]  Rewrite hub table rows whose printed status drifted from the plan
 
@@ -891,6 +893,39 @@ a parentless child ranked by multiple hubs as ambiguous.
   runlist fix-membership --dry-run       preview without writing
   runlist fix-membership --dry-run --json`,
 
+  refs: `runlist refs <old> <new> — code-root citations of a moved document
+       runlist refs repair          — every archived document still cited at its old path
+
+Reference repair inside the doc roots is what archive and rename already do.
+This is the other half: a source comment, docstring or string literal that
+cites a document by its repo-relative path, in the roots \`codeRoots\` names.
+Absent that key, nothing is scanned and nothing changes.
+
+What it matches:
+  - The full repo-relative path only (\`docs/plans/<slug>.md\`). Never a bare
+    basename — a corpus cites slugs as words, and matching one is how a rename
+    corrupts an unrelated line.
+  - A trailing \`§\` or \`#\` anchor is kept as written: only the path is
+    replaced, so quotes, backticks and punctuation around it survive.
+
+What it writes:
+  - Report is the default. \`--fix\` rewrites citations in comments.
+  - A citation inside a string literal (or bare in code) is reported in its own
+    group and rewritten only with \`--strings\` — a test or a guard may assert
+    on it.
+  - A file listed in \`codeRefsUntouched\` is reported and never written.
+  - A file that is not writable, or that resolves outside the repository, is
+    refused by name.
+
+  runlist refs docs/plans/a.md docs/plans/archived/a.md
+  runlist refs docs/plans/a.md docs/plans/archived/a.md --fix
+  runlist refs repair                   report every stale archived citation
+  runlist refs repair --fix --strings   rewrite them, string literals included
+
+\`repair\` reads each previous path from the archive directory mapping, which is
+the one move the tool leaves a readable trace of. A rename records none, so a
+renamed document is covered by the two-argument form.`,
+
   'fix-refs': `runlist fix-refs — auto-fix broken reference paths
 
 Scans all docs for reference fields that point to non-existent files,
@@ -1717,12 +1752,18 @@ async function main() {
     process.stderr.write(`Repo root: ${config.repoRoot}\n`);
   }
 
+  // A printed list shows status, title, age and next step, none of which the
+  // validating passes produce, so it reads the index the way `prompts` and
+  // `hud` do. `--json` emits each document's warnings and errors, so it still
+  // pays for the full pass.
+  const listIndexOptions = listArgs => (listArgs.includes('--json') ? {} : { fast: true });
+
   // Preset aliases (user config can override built-in commands below)
   if ((command === 'stale' || command === 'actionable') && !config.configuredPresetNames.has(command)) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
     const { statusMetadataFor } = await import('../src/status-metadata.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     const docs = index.docs.filter(doc => {
       const metadata = statusMetadataFor(config, doc.type, doc.status);
@@ -1739,7 +1780,7 @@ async function main() {
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions([...config.presets[command], ...restArgs]));
     applyIndexFilters(index);
     runQuery(index, [...config.presets[command], ...restArgs], config, { preset: command, type: typeArg, root: rootArg });
     return;
@@ -1752,7 +1793,7 @@ async function main() {
   if (command === 'plans') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     const sub = restArgs[0];
     let defaults;
@@ -1772,7 +1813,7 @@ async function main() {
   if (command === 'runlists') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runRunlists } = await import('../src/query.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     runRunlists(index, restArgs, config);
     return;
@@ -1783,7 +1824,7 @@ async function main() {
   if (command === 'roadmaps') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runRoadmaps } = await import('../src/roadmap.mjs');
-    const index = buildIndex(config);
+    const index = buildIndex(config, listIndexOptions(restArgs));
     applyIndexFilters(index);
     runRoadmaps(index, restArgs, config);
     return;
@@ -1873,6 +1914,7 @@ async function main() {
   if (command === 'rename') { const { runRename } = await import('../src/rename.mjs'); await runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { const { runMigrate } = await import('../src/migrate.mjs'); runMigrate(restArgs, config, { dryRun }); return; }
   if (command === 'fix-refs') { const { runFixRefs } = await import('../src/fix-refs.mjs'); runFixRefs(restArgs, config, { dryRun }); return; }
+  if (command === 'refs') { const { runRefs } = await import('../src/code-refs.mjs'); runRefs(restArgs, config, { dryRun }); return; }
   if (command === 'fix-membership') { const { runFixMembership } = await import('../src/fix-membership.mjs'); await runFixMembership(restArgs, config, { dryRun }); return; }
   if (command === 'sync-status') { const { runSyncStatus } = await import('../src/sync-status.mjs'); await runSyncStatus(restArgs, config, { dryRun }); return; }
   if (command === 'self-check') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.81.0",
+  "version": "0.83.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/runlist.config.example.mjs

@@ -21,6 +21,38 @@ export const excludeDirs = ['evidence'];
 // checks, which are deliberate subsets.
 // export const minDocs = 500;
 
+// ─── Code references (`runlist refs`) ────────────────────────────────────────
+//
+// Archive and rename repair every reference inside the doc roots. These four
+// keys extend that to source files that cite a document by its repo-relative
+// path in a comment, a docstring or a string literal. With no `codeRoots` the
+// scan never runs and nothing changes.
+//
+// `runlist refs <old> <new>` reports, `--fix` writes; `runlist refs repair`
+// does the same for every archived document still cited at its previous path.
+// Archive and rename print the count afterwards and take `--fix-refs`.
+//
+// Only the full repo-relative path matches, never a bare basename — a corpus
+// cites slugs as words, and matching one is how a rename corrupts an
+// unrelated line. Only the path segment is replaced, so a trailing `§` or `#`
+// anchor, a backtick or a quote is kept as written.
+
+// Repo-relative directories scanned for path-shaped citations. Empty = off.
+// export const codeRoots = ['packages', 'scripts', 'services'];
+
+// File kinds considered. An entry with no leading dot is an exact basename,
+// which is how a file with no extension opts in. Unset = the built-in list.
+// export const codeExtensions = ['.ts', '.tsx', '.mjs', '.swift', '.sql', '.py', '.sh', 'Dockerfile'];
+
+// Never scanned. Vendored trees and generated output, where a rewrite is
+// undone by the next codegen run and the citation belongs upstream.
+// Unset = node_modules, dist/build, and the usual generated-output shapes.
+// export const codeExcludes = ['**/node_modules/**', '**/*.generated.*', '**/__generated__/**'];
+
+// Files whose content is data keyed on document paths — a guard baseline
+// whose keys are plan paths, for instance. Reported, never written.
+// export const codeRefsUntouched = ['scripts/guards/plan-baseline.json'];
+
 // Document types — each type has its own status vocabulary and context layout.
 // Defaults: plan, doc, prompt. Override to customize statuses per type, or add new types.
 //

package/src/code-refs.mjs

@@ -0,0 +1,546 @@
+// Reference repair outside the doc roots.
+//
+// Every sweep the lifecycle runs is pushed through `authorizeManagedSweep` →
+// `authorizeManagedSource`, which refuses anything that is not a `.md` file
+// inside a configured docs root. That chokepoint is what makes a move's write
+// set provable, so it is deliberately NOT widened here: this module walks the
+// configured code roots on its own, outside the move transaction, and archive
+// and rename call it after their own doc-root repair has committed.
+//
+// Two rules separate it from the document rewriter:
+//   1. It matches the full repo-relative path only, never a bare basename. A
+//      corpus cites slugs as words in prose comments, so a basename match is
+//      how a rename corrupts an unrelated line.
+//   2. It replaces the path segment and nothing else, so a `§`/`#` anchor, a
+//      closing backtick, a quote or a trailing comma all survive untouched.
+//      That also means the rendering is repo-relative, which is the spelling a
+//      reader of a source comment can paste; the doc rewriter's doc-relative
+//      rendering is not reused.
+
+import { accessSync, constants, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { escapeRegex, toRepoPath } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { bold, dim, green, yellow } from './color.mjs';
+
+// Measured file kinds in a corpus of 839 stale mentions: TypeScript, Swift,
+// SQL, ESM scripts, TSX, shell, Python, GraphQL, Dockerfiles, and a long tail.
+// An entry without a leading dot is an exact basename, which is how a file
+// with no extension opts in.
+export const DEFAULT_CODE_EXTENSIONS = Object.freeze([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.swift', '.kt', '.sql', '.py', '.sh', '.rb', '.go', '.rs',
+  '.graphql', '.gql', '.yml', '.yaml', '.css', '.scss', '.toml',
+  'Dockerfile', 'Justfile', 'Makefile',
+]);
+
+// Generated output is excluded rather than reported: rewriting an artifact is
+// undone by the next codegen run, and the citation lives in the schema
+// description upstream.
+export const DEFAULT_CODE_EXCLUDES = Object.freeze([
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.next/**',
+  '**/*.generated.*',
+  '**/__generated__/**',
+  '**/generated/**',
+]);
+
+// Comment openers by file kind. The classifier only asks whether an opener
+// precedes the match on the same line, so a table this small is enough — and
+// getting it wrong is safe in one direction only, which is why `#` is not
+// handed to every language.
+const COMMENT_OPENERS = {
+  c: ['//', '/*', '*'],
+  hash: ['#'],
+  sql: ['--', '/*', '*'],
+  all: ['//', '/*', '*', '#', '--'],
+};
+
+const OPENERS_BY_EXTENSION = new Map([
+  ['.ts', 'c'], ['.tsx', 'c'], ['.js', 'c'], ['.jsx', 'c'], ['.mjs', 'c'], ['.cjs', 'c'],
+  ['.swift', 'c'], ['.kt', 'c'], ['.css', 'c'], ['.scss', 'c'], ['.go', 'c'], ['.rs', 'c'],
+  ['.sql', 'sql'],
+  ['.py', 'hash'], ['.sh', 'hash'], ['.rb', 'hash'], ['.yml', 'hash'], ['.yaml', 'hash'],
+  ['.toml', 'hash'], ['.graphql', 'hash'], ['.gql', 'hash'],
+]);
+
+export function codeRefsConfig(config) {
+  const roots = config?.codeRefs?.roots ?? [];
+  return {
+    roots,
+    extensions: config?.codeRefs?.extensions ?? [...DEFAULT_CODE_EXTENSIONS],
+    excludes: config?.codeRefs?.excludes ?? [...DEFAULT_CODE_EXCLUDES],
+    untouched: new Set(config?.codeRefs?.untouched ?? []),
+    enabled: roots.length > 0,
+  };
+}
+
+// ── Globs ────────────────────────────────────────────────────────────────
+
+// A deliberately small subset: `**` spans segments, `*` stays inside one, `?`
+// is one character. Enough for the exclude shapes a code root needs, and it
+// refuses to grow into a dependency.
+export function globToRegex(pattern) {
+  let out = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i++;
+        if (pattern[i + 1] === '/') { i++; out += '(?:.*/)?'; }
+        else out += '.*';
+      } else {
+        out += '[^/]*';
+      }
+    } else if (ch === '?') {
+      out += '[^/]';
+    } else {
+      out += escapeRegex(ch);
+    }
+  }
+  return new RegExp(out + '$');
+}
+
+export function matchesAnyGlob(repoPath, patterns) {
+  return patterns.some(pattern => globToRegex(pattern).test(repoPath));
+}
+
+// ── Walking the code roots ───────────────────────────────────────────────
+
+function extensionAllowed(basename, extensions) {
+  const ext = path.extname(basename);
+  if (ext && extensions.includes(ext)) return true;
+  return extensions.includes(basename);
+}
+
+export function collectCodeFiles(config) {
+  const settings = codeRefsConfig(config);
+  if (!settings.enabled) return [];
+  const files = [];
+  const seen = new Set();
+
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      const repoPath = toRepoPath(abs, config.repoRoot);
+      if (matchesAnyGlob(repoPath, settings.excludes)) continue;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) { walk(abs); continue; }
+      if (!entry.isFile()) continue;
+      if (!extensionAllowed(entry.name, settings.extensions)) continue;
+      if (seen.has(abs)) continue;
+      seen.add(abs);
+      files.push(abs);
+    }
+  };
+
+  for (const root of settings.roots) {
+    const abs = path.resolve(config.repoRoot, root);
+    let stat;
+    try { stat = statSync(abs); } catch { continue; }
+    if (!stat.isDirectory()) continue;
+    walk(abs);
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+// ── The matcher ──────────────────────────────────────────────────────────
+
+// The path may not continue in either direction: a preceding path character
+// means this is a longer path that merely ends with ours, and a following one
+// means the citation names something below it. Everything else — a quote, a
+// backtick, a bracket, a space, a line start, a trailing `§` or `#` anchor —
+// is a boundary, and is left exactly as it was found.
+export function referenceRegex(repoPath) {
+  return new RegExp(`(?<![A-Za-z0-9_\\-/.])${escapeRegex(repoPath)}(?![A-Za-z0-9_\\-/])`, 'g');
+}
+
+const ANCHOR = /^\s*(?:§|#[A-Za-z0-9])/;
+
+function commentOpenerIndex(line, kind) {
+  const openers = COMMENT_OPENERS[kind] ?? COMMENT_OPENERS.all;
+  let best = -1;
+  for (const opener of openers) {
+    let from = 0;
+    for (;;) {
+      const at = line.indexOf(opener, from);
+      if (at === -1) break;
+      from = at + 1;
+      // `https://` is not a comment. A lone `*` only opens a continuation
+      // line when it is the first thing on the line.
+      if (opener === '//' && line[at - 1] === ':') continue;
+      if (opener === '*' && line.slice(0, at).trim() !== '') continue;
+      if (best === -1 || at < best) best = at;
+      break;
+    }
+  }
+  return best;
+}
+
+function insideQuotes(line, index) {
+  let quote = null;
+  for (let i = 0; i < index; i++) {
+    const ch = line[i];
+    if (ch === '\\') { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === '"' || ch === "'" || ch === '`') quote = ch;
+  }
+  return quote;
+}
+
+// `comment` is written by `--fix`; `string` and `code` wait for `--strings`,
+// because a path inside a quoted string can be data a test or a guard asserts
+// on rather than prose a reader follows.
+export function classifyMatch(line, index, fileKind) {
+  const opener = commentOpenerIndex(line, fileKind);
+  if (opener !== -1 && opener < index) return 'comment';
+  return insideQuotes(line, index) ? 'string' : 'code';
+}
+
+function fileKindFor(filePath) {
+  return OPENERS_BY_EXTENSION.get(path.extname(filePath)) ?? 'all';
+}
+
+export function findCodeReferences(content, repoPath, filePath) {
+  const kind = fileKindFor(filePath);
+  const lines = content.split('\n');
+  const hits = [];
+  for (let n = 0; n < lines.length; n++) {
+    const line = lines[n];
+    const regex = referenceRegex(repoPath);
+    let match;
+    while ((match = regex.exec(line)) !== null) {
+      hits.push({
+        line: n + 1,
+        column: match.index + 1,
+        text: line.trim(),
+        form: classifyMatch(line, match.index, kind),
+        anchored: ANCHOR.test(line.slice(match.index + repoPath.length)),
+      });
+    }
+  }
+  return hits;
+}
+
+export function rewriteCodeReferences(content, oldRepoPath, newRepoPath, filePath, { strings = false } = {}) {
+  const kind = fileKindFor(filePath);
+  const lines = content.split('\n');
+  let changed = 0;
+  const out = lines.map(line => {
+    const regex = referenceRegex(oldRepoPath);
+    return line.replace(regex, (found, offset) => {
+      const form = classifyMatch(line, offset, kind);
+      if (form !== 'comment' && !strings) return found;
+      changed++;
+      return newRepoPath;
+    });
+  });
+  return { content: out.join('\n'), changed };
+}
+
+// ── Scanning ─────────────────────────────────────────────────────────────
+
+function writability(absPath, repoRoot) {
+  let canonical;
+  try { canonical = realpathSync(absPath); } catch (err) { return `cannot be resolved (${err.code ?? err.message})`; }
+  const repoCanonical = realpathSync(repoRoot);
+  const relative = path.relative(repoCanonical, canonical);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return 'resolves outside the repository';
+  try { accessSync(canonical, constants.W_OK); } catch { return 'is not writable'; }
+  return null;
+}
+
+/**
+ * Report every code-root citation of `oldRepoPath`. Pure read: `runlist refs`
+ * and the archive / rename count line share it, the same way `fixBrokenRefs`
+ * is shared by `fix-refs` and `check --fix`.
+ */
+export function scanCodeRefs(config, oldRepoPath, { files = null } = {}) {
+  const settings = codeRefsConfig(config);
+  const result = emptyScan(settings.enabled);
+  if (!settings.enabled) return result;
+
+  for (const absPath of files ?? collectCodeFiles(config)) {
+    let content;
+    try { content = readFileSync(absPath, 'utf8'); } catch { continue; }
+    if (!content.includes(oldRepoPath)) continue;
+    const repoPath = toRepoPath(absPath, config.repoRoot);
+    const hits = findCodeReferences(content, oldRepoPath, absPath);
+    if (!hits.length) continue;
+    const untouched = settings.untouched.has(repoPath);
+    result.files.push({ path: repoPath, absPath, untouched, hits });
+    result.total += hits.length;
+    if (untouched) result.untouchedCount += hits.length;
+    for (const hit of hits) result.byForm[hit.form]++;
+  }
+  return result;
+}
+
+// Any document-shaped path, so a sweep reads each file once instead of once
+// per moved document. `repair` over a corpus of 1,000 archived documents and
+// 2,000 code files is 2 million file reads the other way round; the captured
+// token is then looked up in the work list, which keeps the match rule
+// identical to the single-document scan.
+const ANY_DOC_PATH = /(?<![A-Za-z0-9_\-/.])([A-Za-z0-9_\-./]+\.md)(?![A-Za-z0-9_\-/])/g;
+
+function emptyScan(enabled) {
+  return { enabled, files: [], total: 0, byForm: { comment: 0, string: 0, code: 0 }, untouchedCount: 0, refused: [] };
+}
+
+/**
+ * One pass over the code roots for many document paths at once. Returns a Map
+ * of path → the same scan shape `scanCodeRefs` returns, for the paths that
+ * were actually cited.
+ */
+export function scanManyCodeRefs(config, wanted, { files = null } = {}) {
+  const settings = codeRefsConfig(config);
+  const byPath = new Map();
+  if (!settings.enabled || wanted.size === 0) return byPath;
+
+  for (const absPath of files ?? collectCodeFiles(config)) {
+    let content;
+    try { content = readFileSync(absPath, 'utf8'); } catch { continue; }
+    if (!content.includes('.md')) continue;
+    const repoPath = toRepoPath(absPath, config.repoRoot);
+    const untouched = settings.untouched.has(repoPath);
+    const kind = fileKindFor(absPath);
+    const lines = content.split('\n');
+    const perPath = new Map();
+
+    for (let n = 0; n < lines.length; n++) {
+      const line = lines[n];
+      if (!line.includes('.md')) continue;
+      ANY_DOC_PATH.lastIndex = 0;
+      let match;
+      while ((match = ANY_DOC_PATH.exec(line)) !== null) {
+        const found = match[1];
+        if (!wanted.has(found)) continue;
+        if (!perPath.has(found)) perPath.set(found, []);
+        perPath.get(found).push({
+          line: n + 1,
+          column: match.index + 1,
+          text: line.trim(),
+          form: classifyMatch(line, match.index, kind),
+          anchored: ANCHOR.test(line.slice(match.index + found.length)),
+        });
+      }
+    }
+
+    for (const [found, hits] of perPath) {
+      if (!byPath.has(found)) byPath.set(found, emptyScan(true));
+      const scan = byPath.get(found);
+      scan.files.push({ path: repoPath, absPath, untouched, hits });
+      scan.total += hits.length;
+      if (untouched) scan.untouchedCount += hits.length;
+      for (const hit of hits) scan.byForm[hit.form]++;
+    }
+  }
+  return byPath;
+}
+
+/** Writable citations only: what `--fix` (or `--fix --strings`) would change. */
+export function fixableCount(scan, { strings = false } = {}) {
+  let count = 0;
+  for (const file of scan.files) {
+    if (file.untouched) continue;
+    for (const hit of file.hits) {
+      if (hit.form === 'comment' || strings) count++;
+    }
+  }
+  return count;
+}
+
+export function applyCodeRefs(config, scan, oldRepoPath, newRepoPath, { strings = false, dryRun = false } = {}) {
+  const written = [];
+  const refused = [];
+  let changed = 0;
+  for (const file of scan.files) {
+    if (file.untouched) continue;
+    const reason = writability(file.absPath, config.repoRoot);
+    if (reason) { refused.push({ path: file.path, reason }); continue; }
+    const content = readFileSync(file.absPath, 'utf8');
+    const result = rewriteCodeReferences(content, oldRepoPath, newRepoPath, file.absPath, { strings });
+    if (!result.changed || result.content === content) continue;
+    if (!dryRun) writeFileSync(file.absPath, result.content, 'utf8');
+    written.push({ path: file.path, changed: result.changed });
+    changed += result.changed;
+  }
+  return { written, refused, changed };
+}
+
+// ── The work list for `refs repair` ──────────────────────────────────────
+
+// Nothing in the tool records where a document used to live: a rename moves
+// the file and rewrites the doc-root references, and neither writes the old
+// path anywhere. The one move that leaves a readable trace is the archive,
+// whose destination is the source path with the archive directory inserted,
+// so the previous path is that segment removed. A hand-moved or renamed
+// document is out of reach here and `refs <old> <new>` covers it by hand.
+export function archivedPreviousPaths(config) {
+  const docs = collectDocFiles(config).map(file => toRepoPath(file, config.repoRoot));
+  const live = new Set(docs);
+  const pairs = [];
+  for (const current of docs) {
+    const segments = current.split('/');
+    const at = segments.lastIndexOf(config.archiveDir);
+    if (at === -1) continue;
+    const previous = [...segments.slice(0, at), ...segments.slice(at + 1)].join('/');
+    if (previous === current) continue;
+    // A live document at that path means the citation is not stale.
+    if (live.has(previous)) continue;
+    pairs.push({ previous, current });
+  }
+  return pairs;
+}
+
+// ── Output ───────────────────────────────────────────────────────────────
+
+const FORM_LABELS = { comment: 'In a comment', string: 'In a string literal', code: 'In code' };
+
+function writeGroup(out, label, entries, { prefix = '' } = {}) {
+  if (!entries.length) return;
+  const lines = entries.reduce((sum, entry) => sum + entry.hits.length, 0);
+  out.write(`${prefix}${bold(label)} (${lines} in ${entries.length} file${entries.length === 1 ? '' : 's'}):\n`);
+  for (const entry of entries) {
+    for (const hit of entry.hits) {
+      out.write(`${prefix}  ${entry.path}:${hit.line}  ${dim(hit.text)}\n`);
+    }
+  }
+}
+
+function groupBy(scan, form) {
+  return scan.files
+    .filter(file => !file.untouched)
+    .map(file => ({ path: file.path, hits: file.hits.filter(hit => hit.form === form) }))
+    .filter(file => file.hits.length);
+}
+
+export function reportScan(scan, oldRepoPath, newRepoPath, out, { prefix = '' } = {}) {
+  out.write(`${prefix}${oldRepoPath} → ${newRepoPath}\n\n`);
+  for (const form of ['comment', 'string', 'code']) {
+    writeGroup(out, FORM_LABELS[form], groupBy(scan, form), { prefix });
+  }
+  const untouched = scan.files.filter(file => file.untouched);
+  if (untouched.length) {
+    writeGroup(out, 'Never written (listed in codeRefsUntouched)', untouched, { prefix });
+  }
+  const anchored = scan.files.reduce((sum, file) => sum + file.hits.filter(hit => hit.anchored).length, 0);
+  if (anchored) out.write(`${prefix}${dim(`${anchored} carry a section anchor, which is kept as written.`)}\n`);
+}
+
+export function countLine(scan, oldRepoPath, newRepoPath) {
+  const files = scan.files.length;
+  return `${scan.total} code reference${scan.total === 1 ? '' : 's'} in ${files} file${files === 1 ? '' : 's'} still ${scan.total === 1 ? 'cites' : 'cite'} the old path; run \`runlist refs ${oldRepoPath} ${newRepoPath} --fix\``;
+}
+
+// ── The verb ─────────────────────────────────────────────────────────────
+
+function requireConfigured(settings, out) {
+  if (settings.enabled) return true;
+  out.write(`${yellow('No code roots configured.')} Set \`codeRoots\` in runlist.config.mjs to scan source files for document citations.\n`);
+  return false;
+}
+
+export function runRefs(argv, config, opts = {}) {
+  const out = opts.out ?? process.stdout;
+  const fix = argv.includes('--fix');
+  const strings = argv.includes('--strings');
+  const dryRun = Boolean(opts.dryRun);
+  const positional = argv.filter(arg => !arg.startsWith('-'));
+  const settings = codeRefsConfig(config);
+  if (!requireConfigured(settings, out)) return { enabled: false };
+
+  if (positional[0] === 'repair') return repairAll(config, { fix, strings, dryRun, out });
+
+  const [oldInput, newInput] = positional;
+  if (!oldInput || !newInput) {
+    out.write('Usage: runlist refs <old> <new> [--fix] [--strings]\n       runlist refs repair [--fix] [--strings]\n');
+    return { enabled: true };
+  }
+  const oldRepoPath = normalizeInput(oldInput, config);
+  const newRepoPath = normalizeInput(newInput, config);
+  return reportOne(config, oldRepoPath, newRepoPath, { fix, strings, dryRun, out, showEmpty: true });
+}
+
+function normalizeInput(input, config) {
+  const abs = path.resolve(config.repoRoot, input);
+  return toRepoPath(abs, config.repoRoot);
+}
+
+function reportOne(config, oldRepoPath, newRepoPath, { fix, strings, dryRun, out, showEmpty = false, files = null, scan: given = null }) {
+  const scan = given ?? scanCodeRefs(config, oldRepoPath, { files });
+  if (!scan.total) {
+    if (showEmpty) out.write(green(`No code references to ${oldRepoPath}.\n`));
+    return { enabled: true, scan, changed: 0 };
+  }
+  reportScan(scan, oldRepoPath, newRepoPath, out);
+  if (!fix) {
+    const writable = fixableCount(scan, { strings });
+    out.write(`\n${scan.total} reference${scan.total === 1 ? '' : 's'} in ${scan.files.length} file${scan.files.length === 1 ? '' : 's'}. `);
+    out.write(`${writable} would be rewritten by --fix${strings ? ' --strings' : ''}.\n`);
+    if (!strings && (scan.byForm.string || scan.byForm.code)) {
+      out.write(dim('Add --strings to rewrite the ones inside string literals and code.\n'));
+    }
+    return { enabled: true, scan, changed: 0 };
+  }
+  const applied = applyCodeRefs(config, scan, oldRepoPath, newRepoPath, { strings, dryRun });
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  out.write(`\n${prefix}${green(`Rewrote ${applied.changed} reference(s) in ${applied.written.length} file(s).`)}\n`);
+  for (const entry of applied.refused) {
+    out.write(`${yellow('Refused')}: ${entry.path} ${entry.reason}.\n`);
+  }
+  return { enabled: true, scan, changed: applied.changed, refused: applied.refused };
+}
+
+function repairAll(config, { fix, strings, dryRun, out }) {
+  const pairs = archivedPreviousPaths(config);
+  const wanted = new Map(pairs.map(pair => [pair.previous, pair.current]));
+  const found = scanManyCodeRefs(config, new Set(wanted.keys()));
+  let total = 0;
+  let changed = 0;
+  const stale = [];
+  for (const pair of pairs) {
+    const scan = found.get(pair.previous);
+    if (!scan?.total) continue;
+    stale.push({ ...pair, scan });
+    total += scan.total;
+  }
+  if (!stale.length) {
+    out.write(green(`No stale code references across ${pairs.length} archived document(s).\n`));
+    return { enabled: true, total: 0, changed: 0, documents: 0 };
+  }
+  out.write(`${bold(`${total} stale code reference(s) across ${stale.length} archived document(s).`)}\n\n`);
+  for (const entry of stale) {
+    const applied = reportOne(config, entry.previous, entry.current, { fix, strings, dryRun, out, scan: entry.scan });
+    changed += applied.changed ?? 0;
+    out.write('\n');
+  }
+  out.write(dim('Previous paths come from the archive directory mapping — a rename records none, so `refs <old> <new>` covers those by hand.\n'));
+  return { enabled: true, total, changed, documents: stale.length };
+}
+
+/**
+ * The line archive and rename print after their own doc-root repair. Returns
+ * null when no code root is configured, which is today's behaviour exactly.
+ */
+export function reportMovedCodeRefs(config, oldRepoPath, newRepoPath, { fix = false, strings = false, dryRun = false, out = process.stdout, prefix = '' } = {}) {
+  const settings = codeRefsConfig(config);
+  if (!settings.enabled) return null;
+  const scan = scanCodeRefs(config, oldRepoPath);
+  if (!scan.total) return { total: 0, changed: 0 };
+  if (!fix) {
+    out.write(`${prefix}${countLine(scan, oldRepoPath, newRepoPath)}\n`);
+    return { total: scan.total, changed: 0 };
+  }
+  const applied = applyCodeRefs(config, scan, oldRepoPath, newRepoPath, { strings, dryRun });
+  out.write(`${prefix}Rewrote ${applied.changed} code reference(s) in ${applied.written.length} file(s).\n`);
+  for (const entry of applied.refused) {
+    out.write(`${prefix}${yellow('Refused')}: ${entry.path} ${entry.reason}.\n`);
+  }
+  return { total: scan.total, changed: applied.changed, refused: applied.refused };
+}

package/src/commands.mjs

@@ -120,7 +120,7 @@ const definitions = [
   command('status', mutates('managed source and same-root destination'), 'mutate', [form('<file> [status]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
   command('set', mutates('managed source and same-root destination'), 'mutate', [form('<status> [file]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
   command('ship', mutates('repository release/index paths and global release tooling'), 'mutate', [form('[patch|minor|major]', { args: positionals(0, 1) })]),
-  command('archive', mutates('managed source and same-root destination'), 'mutate', [form('<file>', { args: positionals(1, 1), options: [...LIFECYCLE_OPTIONS, flag('--closeout-template')] })]),
+  command('archive', mutates('managed source and same-root destination'), 'mutate', [form('<file>', { args: positionals(1, 1), options: [...LIFECYCLE_OPTIONS, flag('--closeout-template'), flag('--fix-refs'), flag('--strings')] })]),
   command('bulk', mutates('managed source sweep; archive destinations preserve roots'), 'mutate', [
     form('archive <files...>', { subcommands: ['archive'], args: positionals(1, Infinity), options: [flag('--json'), flag('--no-index'), flag('--show-files')] }),
     form('tag [files...]', { subcommands: ['tag'], args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] }),
@@ -133,9 +133,13 @@ const definitions = [
     dashPositionalsAfter: 1,
   })]),
   command('lint', mutates('managed source sweep with --fix; otherwise read-only'), 'mutate', [form('', { options: [flag('--fix')] })]),
-  command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files')] })]),
+  command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files'), flag('--fix-refs'), flag('--strings')] })]),
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),
+  command('refs', mutates('configured code roots with --fix; otherwise read-only'), 'mutate', [
+    form('repair', { subcommands: ['repair'], options: [flag('--fix'), flag('--strings')] }),
+    form('<old> <new>', { args: positionals(2, 2), options: [flag('--fix'), flag('--strings')] }),
+  ]),
   command('fix-membership', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--json')] })]),
   command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
   command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),

package/src/config.mjs

@@ -22,6 +22,18 @@ const DEFAULTS = {
   // Floor under the scan surface; null = off. See `applyScanFloor` in validate.mjs.
   minDocs: null,
 
+  // Reference repair outside the doc roots (`runlist refs`). An empty
+  // `codeRoots` is off, which is the behaviour before this key existed: the
+  // doc-root repair archive and rename already run is unchanged either way.
+  // Paths are repo-relative. `null` on the two lists means "the built-in
+  // list", which lives in code-refs.mjs so config.mjs stays a leaf.
+  codeRoots: [],
+  codeExtensions: null,
+  codeExcludes: null,
+  // Files whose content is data keyed on document paths — a guard baseline
+  // whose keys are plan paths, for instance. Reported, never written.
+  codeRefsUntouched: [],
+
   types: {
     plan: {
       statuses: ['in-session', 'active', 'planned', 'blocked', 'partial', 'paused', 'awaiting', 'queued-after', 'archived'],
@@ -394,6 +406,17 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     warnings.push("Config: index.snapshot must be 'status' or 'state'.");
   }
 
+  for (const key of ['codeRoots', 'codeRefsUntouched']) {
+    if (config[key] !== undefined && !Array.isArray(config[key])) {
+      warnings.push(`Config: ${key} must be an array.`);
+    }
+  }
+  for (const key of ['codeExtensions', 'codeExcludes']) {
+    if (config[key] != null && !Array.isArray(config[key])) {
+      warnings.push(`Config: ${key} must be an array.`);
+    }
+  }
+
   // Unknown top-level user config keys
   for (const key of Object.keys(userConfig)) {
     if (!VALID_CONFIG_KEYS.has(key)) {
@@ -608,6 +631,13 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     docsRootPrefix,
     minDocs,
 
+    codeRefs: {
+      roots: Array.isArray(config.codeRoots) ? config.codeRoots : [],
+      extensions: Array.isArray(config.codeExtensions) ? config.codeExtensions : null,
+      excludes: Array.isArray(config.codeExcludes) ? config.codeExcludes : null,
+      untouched: Array.isArray(config.codeRefsUntouched) ? config.codeRefsUntouched : [],
+    },
+
     statusOrder,
     validStatuses,
     validTypes,

package/src/extractors.mjs

@@ -42,7 +42,8 @@ export function extractNextStep(body) {
 }
 
 export function extractBodyLinks(body) {
-  if (!body) return [];
+  // Every inline link contains `](`, and masking never creates one.
+  if (!body || !body.includes('](')) return [];
   // Strip fenced code blocks, then MASK inline code rather than delete it.
   // Deleting it ate the commonest link idiom in a plan hub: [`plan.md`](plan.md)
   // has its link TEXT as a code span, so removing the span left `[](plan.md)`,

package/src/index.mjs

@@ -4,6 +4,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
 import { findLexicalDocsRoot } from './managed-path.mjs';
+import { openParseCache, fileStamp, stampSize } from './parse-cache.mjs';
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, checkRoadmapHubExecutionMode, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
@@ -30,7 +31,9 @@ export function buildIndex(config, opts = {}) {
   const invokeHooks = opts.invokeHooks ?? !config._execution?.suppressSideEffects;
   const gitStaleness = opts.gitStaleness ?? config._execution?.gitStaleness ?? true;
   const skipWarningOnlyChecks = fast || errorsOnly;
-  const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
+  const cache = openParseCache(config);
+  const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast, cache }));
+  if (cache && !config._execution?.suppressSideEffects) cache.save();
   if (!fast) {
     // Per-file validation (validateDoc) ran during parse without sibling
     // visibility. Now that the full index is materialized, enrich
@@ -271,16 +274,45 @@ function walkMarkdownFiles(directory, files, excludedDirs, skipPaths, seen = new
   }
 }
 
-export function parseDocFile(filePath, config, opts = {}) {
-  const { fast = false } = opts;
-  const relativePath = toRepoPath(filePath, config.repoRoot);
-  const raw = readFileSync(filePath, 'utf8');
-  const { frontmatter, body } = extractFrontmatter(raw);
+// Everything parseDocFile takes from the file's text alone, with no config and
+// no clock, which is what the parse cache may keep.
+function extractDocText(frontmatter, body) {
   const fmWarnings = [];
   const parsedFrontmatter = parseSimpleFrontmatter(frontmatter, fmWarnings);
-  const headingTitle = extractFirstHeading(body);
+  return {
+    parsedFrontmatter,
+    fmWarnings: fmWarnings.map(w => ({ message: w.message })),
+    headingTitle: extractFirstHeading(body),
+    bodySummary: extractSummary(body),
+    bodyStatusSnapshot: extractStatusSnapshot(body),
+    bodyNextStep: extractNextStep(body),
+    checklist: extractChecklistCounts(body),
+    bodyLinks: extractBodyLinks(body),
+    hasCloseout: /^##\s+Closeout/m.test(body),
+  };
+}
+
+export function parseDocFile(filePath, config, opts = {}) {
+  const { fast = false, cache = null } = opts;
+  const relativePath = toRepoPath(filePath, config.repoRoot);
+  const stamp = cache ? fileStamp(filePath) : null;
+  let text = stamp ? cache.get(relativePath, stamp) : null;
+  // Validation reads the body itself, so only a fast build can skip the read.
+  let body = null;
+  if (!text || !fast) {
+    const raw = readFileSync(filePath, 'utf8');
+    const extracted = extractFrontmatter(raw);
+    body = extracted.body;
+    // A file rewritten between the stat and the read no longer matches its stamp.
+    if (text && Buffer.byteLength(raw) !== stampSize(stamp)) text = null;
+    if (!text) {
+      text = extractDocText(extracted.frontmatter, body);
+      if (stamp) cache.set(relativePath, stamp, text);
+    }
+  }
+  const { parsedFrontmatter, fmWarnings, headingTitle, checklist, bodyLinks, hasCloseout } = text;
   const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
-  const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
+  const summary = asString(parsedFrontmatter.summary) ?? text.bodySummary ?? null;
   // For terminal-status docs (archived / reference / deprecated by default),
   // skip the body-scrape and the "No current_state set" fallback when the user
   // didn't set `current_state:` in frontmatter explicitly. Body text on a
@@ -305,7 +337,7 @@ export function parseDocFile(filePath, config, opts = {}) {
   } else if (isTerminalDoc) {
     currentState = null;
   } else {
-    const scraped = extractStatusSnapshot(body);
+    const scraped = text.bodyStatusSnapshot;
     if (scraped) {
       currentState = scraped;
       currentStateOrigin = 'body';
@@ -313,7 +345,7 @@ export function parseDocFile(filePath, config, opts = {}) {
       currentState = 'No current_state set';
     }
   }
-  const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
+  const nextStep = asString(parsedFrontmatter.next_step) ?? text.bodyNextStep ?? null;
   // `blocked_by` is accepted as an alias for `blockers` since 0.39.3 — agents
   // filing tickets naturally reach for the JIRA/Linear name. If both are set,
   // they're merged (de-duped via normalizeBlockers → mergeUniqueStrings).
@@ -328,9 +360,6 @@ export function parseDocFile(filePath, config, opts = {}) {
   const domain = asString(parsedFrontmatter.domain) ?? null;
   const audience = asString(parsedFrontmatter.audience) ?? null;
   const executionMode = asString(parsedFrontmatter.execution_mode) ?? null;
-  const checklist = extractChecklistCounts(body);
-  const bodyLinks = extractBodyLinks(body);
-  const hasCloseout = /^##\s+Closeout/m.test(body);
 
   // Dynamic reference field extraction. A leading `>` on a value (e.g.
   // `"> docs/audit-beyond-platform.md"`) marks that single ref as one-way —

package/src/lifecycle.mjs

@@ -13,6 +13,7 @@ import { walkSections, findSection } from './section.mjs';
 import { authorizeManagedDestination, authorizeManagedSource, authorizeManagedSweep } from './managed-path.mjs';
 import { withPathLocks, snapshotFile, replaceSnapshot, moveFileAtomic, mutateFile, mutateFileSet } from './atomic-mutation.mjs';
 import { configuredReferenceFields, createReferenceIdentitySet, rewriteDocumentReferences } from './reference-planner.mjs';
+import { reportMovedCodeRefs } from './code-refs.mjs';
 import {
   assertPlanMutationAuthorized,
   assertHookDeliveryTakeoverSafe,
@@ -705,7 +706,10 @@ export function runArchive(argv, config, opts = {}) {
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   const showFiles = argv.includes('--show-files') || opts.showFiles;
   const closeoutTemplate = argv.includes('--closeout-template');
-  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files' && a !== '--closeout-template' && a !== '--force');
+  const fixCodeRefs = argv.includes('--fix-refs') || opts.fixRefs;
+  const codeRefStrings = argv.includes('--strings');
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files' && a !== '--closeout-template' && a !== '--force'
+    && a !== '--fix-refs' && a !== '--strings');
   let note = opts.note ?? null;
   const noteIdx = argv.indexOf('--note');
   if (noteIdx !== -1) {
@@ -833,6 +837,10 @@ export function runArchive(argv, config, opts = {}) {
       }
     }
 
+    if (!opts.skipInboundRefs) {
+      reportMovedCodeRefs(config, oldRepoPath, newRepoPath, { dryRun: true, out, prefix: `${prefix} ` });
+    }
+
     // Preview onArchive hook fire
     if (config.hooks?.onArchive) {
       out.write(`${prefix} Would fire hook: onArchive\n`);
@@ -868,6 +876,12 @@ export function runArchive(argv, config, opts = {}) {
   }
   if (selfRefsFixed) out.write('Updated references in archived file.\n');
   if (updatedRefCount > 0) out.write(`Updated references in ${updatedRefCount} file(s).\n`);
+  // The doc-root repair above is committed. The code roots are a separate
+  // sweep outside the move transaction, so the count is reported and the
+  // write waits for --fix-refs.
+  if (!opts.skipInboundRefs) {
+    reportMovedCodeRefs(config, oldRepoPath, newRepoPath, { fix: fixCodeRefs, strings: codeRefStrings, out });
+  }
   if (config.indexPath && indexRegenerated) out.write('Index regenerated.\n');
   if (config.indexPath && noIndex) out.write(dim('(index not regenerated — run `runlist index` to refresh)\n'));
 

package/src/markdown-code-spans.mjs

@@ -1,7 +1,5 @@
-function maskRange(value, start, end) {
-  return value.slice(0, start)
-    + value.slice(start, end).replace(/[^\n]/g, 'x')
-    + value.slice(end);
+function mask(text) {
+  return text.includes('\n') ? text.replace(/[^\n]/g, 'x') : 'x'.repeat(text.length);
 }
 
 // Markdown code spans close only on a backtick run of the same length as their
@@ -11,13 +9,19 @@ function maskRange(value, start, end) {
 // rewriter survive: after an unmatched opener, nothing is treated as prose
 // until a compatible closer appears.
 export function maskInlineCodeLine(line, state = { run: null }) {
-  const ranges = [];
+  if (!line.includes('`')) return state.run === null ? line : mask(line);
+
   const runs = [...line.matchAll(/`+/g)];
+  const findCloser = (from, length) => {
+    for (let i = from; i < runs.length; i++) if (runs[i][0].length === length) return i;
+    return -1;
+  };
+  const ranges = [];
   let index = 0;
 
   if (state.run !== null) {
-    const closingIndex = runs.findIndex(candidate => candidate[0].length === state.run);
-    if (closingIndex === -1) return maskRange(line, 0, line.length);
+    const closingIndex = findCloser(0, state.run);
+    if (closingIndex === -1) return mask(line);
     const closing = runs[closingIndex];
     ranges.push([0, closing.index + closing[0].length]);
     index = closingIndex + 1;
@@ -26,8 +30,7 @@ export function maskInlineCodeLine(line, state = { run: null }) {
 
   for (; index < runs.length; index++) {
     const opening = runs[index];
-    const closingIndex = runs.findIndex((candidate, candidateIndex) =>
-      candidateIndex > index && candidate[0].length === opening[0].length);
+    const closingIndex = findCloser(index + 1, opening[0].length);
     if (closingIndex === -1) {
       ranges.push([opening.index, line.length]);
       state.run = opening[0].length;
@@ -38,7 +41,15 @@ export function maskInlineCodeLine(line, state = { run: null }) {
     index = closingIndex;
   }
 
-  return ranges.reduceRight((masked, [start, end]) => maskRange(masked, start, end), line);
+  // Ranges are ascending and disjoint, so one left-to-right pass builds the
+  // result instead of re-copying the whole line once per span.
+  let out = '';
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    out += line.slice(cursor, start) + mask(line.slice(start, end));
+    cursor = end;
+  }
+  return out + line.slice(cursor);
 }
 
 export function maskInlineCodeSpans(value) {

package/src/parse-cache.mjs

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, statSync, writeFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { commitRename } from './durable-rename.mjs';
+import { readEnv, stateDir } from './naming.mjs';
+
+// What every build of the index used to redo from scratch: read each document
+// and pull its frontmatter, links, checklist and summary out of the body. None
+// of that depends on the config or the clock, so it is kept per file under the
+// state directory and reused while the file's size, times and inode are
+// unchanged. Everything that does depend on them (terminal statuses, staleness,
+// reference fields, validation) is still computed on every run.
+//
+// One line per document, `path \t stamp \t json`, so a hit parses only its own
+// line and hands back fresh objects: nothing a caller does to a document can
+// leak into what is saved. The cache is an optimisation and never an input:
+// a missing, unreadable or foreign-version file is treated as empty, a failed
+// write is dropped, and `RUNLIST_NO_PARSE_CACHE=1` turns it off.
+
+const SCHEMA = 1;
+const FILE_NAME = 'parse-cache';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version; }
+  catch { return 'unknown'; }
+})();
+const HEADER = JSON.stringify({ schema: SCHEMA, version: VERSION });
+
+export function fileStamp(filePath) {
+  try {
+    const s = statSync(filePath, { bigint: true });
+    return `${s.size}:${s.mtimeNs}:${s.ctimeNs}:${s.ino}`;
+  } catch {
+    return null;
+  }
+}
+
+export function stampSize(stamp) {
+  return Number(stamp.slice(0, stamp.indexOf(':')));
+}
+
+export function openParseCache(config) {
+  if (readEnv('NO_PARSE_CACHE') === '1') return null;
+  const dir = stateDir(config.repoRoot);
+  // The state directory is created, and ignored by git, by `init` and the
+  // commands that own it; a repo without one gets no cache rather than a new
+  // untracked folder from a read-only command.
+  if (!existsSync(dir)) return null;
+  const cachePath = path.join(dir, FILE_NAME);
+  const lines = new Map();
+  try {
+    const text = readFileSync(cachePath, 'utf8');
+    const rows = text.split('\n');
+    if (rows[0] === HEADER) {
+      for (let i = 1; i < rows.length; i++) {
+        const row = rows[i];
+        const a = row.indexOf('\t');
+        const b = row.indexOf('\t', a + 1);
+        if (a < 0 || b < 0) continue;
+        lines.set(row.slice(0, a), { stamp: row.slice(a + 1, b), row });
+      }
+    }
+  } catch { /* no cache yet */ }
+
+  const seen = new Set();
+  let dirty = false;
+
+  return {
+    get(key, stamp) {
+      seen.add(key);
+      const entry = lines.get(key);
+      if (!entry || entry.stamp !== stamp) return null;
+      try { return JSON.parse(entry.row.slice(entry.row.indexOf('\t', entry.row.indexOf('\t') + 1) + 1)); }
+      catch { return null; }
+    },
+    set(key, stamp, value) {
+      seen.add(key);
+      if (/[\t\n]/.test(key)) return;
+      lines.set(key, { stamp, row: `${key}\t${stamp}\t${JSON.stringify(value)}` });
+      dirty = true;
+    },
+    save({ complete = true } = {}) {
+      if (complete) {
+        for (const key of lines.keys()) {
+          if (!seen.has(key)) { lines.delete(key); dirty = true; }
+        }
+      }
+      if (!dirty) return;
+      const temp = `${cachePath}.${process.pid}.${Date.now()}.tmp`;
+      try {
+        writeFileSync(temp, [HEADER, ...[...lines.values()].map(entry => entry.row)].join('\n'), 'utf8');
+        commitRename(temp, cachePath);
+        dirty = false;
+      } catch {
+        try { unlinkSync(temp); } catch { /* already gone */ }
+      }
+    },
+  };
+}

package/src/pickup.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { authorizeManagedSource, authorizeRepoGeneratedPath } from './managed-path.mjs';
 import os from 'node:os';
@@ -233,7 +233,48 @@ function validateBinding(record, identity, config) {
   return record;
 }
 
+// Working out a plan's canonical identity lists every directory on its path,
+// three times over, and listing plans asks it of every plan in the repo. A
+// record can only belong to a plan whose file name it carries, so the names in
+// the ownership folder rule most plans out first. The summary is rebuilt
+// whenever the folder changes, and any record it cannot read turns the check
+// off, so the full identity check still decides every case it could get wrong.
+let ownershipNamesCache = null;
+
+function ownershipNames(config) {
+  const dir = ownershipRoot(config);
+  let stamp;
+  try { stamp = `${dir}\0${statSync(dir, { bigint: true }).mtimeNs}`; }
+  catch { return new Set(); }
+  if (ownershipNamesCache?.stamp === stamp) return ownershipNamesCache.names;
+  let names = new Set();
+  try {
+    for (const entry of readdirSync(dir)) {
+      if (!entry.endsWith('.json')) continue;
+      const record = parseOwnership(readFileSync(path.join(dir, entry), 'utf8'), entry);
+      if (record.corrupt) { names = null; break; }
+      names.add(path.basename(record.canonicalPath).toLowerCase());
+      names.add(path.basename(record.plan).toLowerCase());
+    }
+  } catch { names = null; }
+  ownershipNamesCache = { stamp, names };
+  return names;
+}
+
+function mayHaveOwnershipRecord(absolutePath, config) {
+  const names = ownershipNames(config);
+  if (names === null || names.has(path.basename(absolutePath).toLowerCase())) return true;
+  try {
+    if (lstatSync(absolutePath).isSymbolicLink()) return true;
+    // A record whose fields were rewritten still sits at its identity's file
+    // name, and has to be found to be reported corrupt.
+    const guess = createHash('sha256').update(realpathSync(absolutePath)).digest('hex');
+    return existsSync(path.join(ownershipRoot(config), `${guess}.json`));
+  } catch { return true; }
+}
+
 export function readPlanOwnership(repoPath, config) {
+  if (!mayHaveOwnershipRecord(path.resolve(config.repoRoot, repoPath), config)) return null;
   let identity;
   try { identity = canonicalPlanIdentity(path.resolve(config.repoRoot, repoPath), config); }
   catch { return null; }

package/src/rename.mjs

@@ -10,9 +10,12 @@ import { authorizeManagedDestination, authorizeManagedSource, authorizeManagedSw
 import { availableSessionId, prepareOwnershipMigration } from './pickup.mjs';
 import { moveFileAtomic } from './atomic-mutation.mjs';
 import { configuredReferenceFields, createReferenceIdentitySet, planReferenceMove, rewriteDocumentReferences } from './reference-planner.mjs';
+import { reportMovedCodeRefs } from './code-refs.mjs';
 
 export async function runRename(argv, config, opts = {}) {
   const { dryRun } = opts;
+  const fixCodeRefs = argv.includes('--fix-refs') || opts.fixRefs;
+  const codeRefStrings = argv.includes('--strings');
   const positional = argv.filter(arg => !arg.startsWith('-'));
   const oldInput = positional[0];
   let newInput = positional[1];
@@ -58,6 +61,7 @@ export async function runRename(argv, config, opts = {}) {
       for (const item of referencePlan.updates) process.stdout.write(`${prefix}   ${toRepoPath(item.path, config.repoRoot)}\n`);
     }
     if (ownership) process.stdout.write(`${prefix} Would migrate this session's ownership record.\n`);
+    reportMovedCodeRefs(config, oldRepoPath, newRepoPath, { dryRun: true, prefix: `${prefix} ` });
     return;
   }
 
@@ -93,6 +97,10 @@ export async function runRename(argv, config, opts = {}) {
   regenIndex(config);
   process.stdout.write(`${green('Renamed')}: ${oldRepoPath} → ${newRepoPath}\n`);
   if (result.updatedPaths.length) process.stdout.write(`Updated references in ${result.updatedPaths.length} file(s).\n`);
+  // The doc-root repair above is committed. The code roots are a separate
+  // sweep outside the move transaction, so the count is reported and the
+  // write waits for --fix-refs.
+  reportMovedCodeRefs(config, oldRepoPath, newRepoPath, { fix: fixCodeRefs, strings: codeRefStrings });
   try { config.hooks.onRename?.({ oldPath: oldRepoPath, newPath: newRepoPath, referencesUpdated: result.updatedPaths.length }); }
   catch (err) { warn(`Hook 'onRename' threw: ${err.message}`); }
   return { oldRepoPath, newRepoPath, referencePaths: result.updatedPaths.map(item => toRepoPath(item, config.repoRoot)) };