@sabaiway/agent-workflow-memory 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 4.1.0 — the ADR rotation carries your inbound links with it (AD-087)
+
+Rotating `decisions.md` used to be a link-breaking event: `archive-decisions.mjs` moved ADR
+blocks out of the HOT window into per-record `adr/` files while every `decisions.md#ad-NNN…`
+link elsewhere in your `docs/ai/` kept pointing at a heading that was no longer there — and
+neither `--check` nor `--dry-run` would say a word about it. One deployed project measured 114
+such inbound anchors (23 aimed at the first tier a rotation would move) and had raised its HOT
+cap twice specifically so the rotation never runs. A safety valve nobody dares open is not
+shipped; this release makes the crossing carry its links:
+
+- **Rotate and `--migrate --apply` rewrite inbound links.** Every non-fenced
+  `decisions.md#ad-NNN…` link under `docs/ai/` whose id is in the moved set is rewritten to the
+  record file. The heading-slug fragment is preserved — each record holds the verbatim
+  `## AD-NNN — title` block, so the same anchor resolves — and the leading relative prefix
+  survives (`adr/` is a sibling of `decisions.md`). Migrate additionally rewrites links into
+  the retired monolith archives it deletes, each target computed relative to its linking file.
+- **A conservation invariant guards every rewrite.** The rewrite set is computed and verified
+  before the run's first write: every moved-id link rewritten, every other byte identical,
+  per-file and total matched-link counts equal before and after — any mismatch exits 1 with
+  nothing written.
+- **The write order is pinned crash-safe:** records → inbound rewrites → HOT rewrite / monolith
+  removal. Every interrupted intermediate state re-runs to completion; previously a crash after
+  the HOT write re-ran as «nothing to rotate» with the orphans permanent.
+- **`--check` now proves reference integrity.** A `decisions.md#ad-NNN…` anchor whose id has
+  left the HOT window (stale even when the id exists as an archived record) and an
+  `adr/AD-NNN-….md` link naming no existing record file both fail exit 1, every violation
+  listed with `file:line`. A tree with matches but no ADR substrate fails too; the early SKIP
+  remains only for trees with zero matches.
+- **`--dry-run` prints the rewrite set** (`file:line`, old target → new target) alongside the
+  move set and writes nothing; plain `--migrate` prints the same summary, and
+  `--migrate --apply --dry-run` refuses loudly instead of silently writing.
+- **Fail-closed edges, each red-tested:** a rewrite-form link targeting a moved id inside the
+  ADR corpus itself (HOT preamble or block, a record, a monolith tier) refuses pre-write with
+  `file:line` — convert the link (e.g. to `[[AD-NNN]]`) and re-run; a HOT block ABOUT to move
+  that itself links a retained id or carries a record-form link refuses pre-write (the verbatim
+  move would silently break the link from inside the record); symlinked `.md` files and
+  directories in the scan scope refuse loudly; an unparseable scanned file (unclosed fence)
+  aborts either write path before any write; a stale two-pass snapshot refuses instead of
+  rewriting from old bytes.
+
+**Stated limitations:** the scan is line-scoped (a link hand-wrapped across a line break is not
+matched — the same accepted residual as the preamble contract), inline code is not tracked (a
+backtick-wrapped link counts as live), and YAML frontmatter is opaque metadata — a link inside
+it is neither rewritten nor checked, and is preserved byte-exactly on every write. The boundary
+is `docs/ai/` — links in README or agent entry points outside it are neither rewritten nor
+checked.
+
+**Upgrading:** the tool itself has nothing to reconfigure — the rewrite is additive, and on a
+healthy tree whose links resolve the new assertions stay green. **Reaching your deployment:** a
+fresh Node-project bootstrap through the memory 4.1.0 skill — or a clean-layout upgrade where
+the pair is entirely absent — copies the fixed pair from this package (a No-Node project skips
+the scripts; a legacy-monolith layout goes through the consented migration ask); a normal
+upgrade of an already-deployed pair preserves it byte-for-byte (local edits are never
+clobbered — drift repair belongs to a lineage migration), so an existing deployment is NOT
+auto-refreshed by this release; a verified drift-safe refresh lane is queued family work. If
+`--check` then reports a `dead ADR anchor` or `dead ADR record link`, those are real orphans it
+found — each line names the file, line and dead target; fix or remove the link, or re-point it
+at an existing `adr/` record (or the `[[AD-NNN]]` form); with the links live, rotation is safe
+to run again, so a cap raised only to avoid it can come back down. Any other `--check` red
+carries its own printed diagnosis.
+
 ## 4.0.0 — the archivers stop reporting green on files they did not understand (AD-084)
 
 > ### ⚠ BREAKING — the rotation gates fail CLOSED now

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '4.0.0'
+  version: '4.1.0'
 ---
 
 # agent-workflow-memory

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/scripts/archive-decisions.mjs

@@ -17,25 +17,45 @@
 //                                         plateaus at O(governing), never O(cumulative). Not a ledger.
 //
 // Modes:
-//   (default)          rotate: explode the oldest HOT entries beyond the cap into adr/ records, then
-//                      regenerate the navigator + docs/ai/index.md (item (h)). Monoliths present → a
-//                      LOUD legacy-guard refusal ("run --migrate first"); it never half-explodes.
-//   --check            verify HOT cap + adr/ store integrity + the legacy guard + navigator freshness;
-//                      exit 1 on any breach. A STATED skip (exit 0) only when NO ADR substrate exists
-//                      (neither decisions.md NOR docs/ai/adr/).
+//   (default)          rotate: explode the oldest HOT entries beyond the cap into adr/ records,
+//                      REWRITE the inbound `decisions.md#ad-NNN…` links across docs/ai/** to the
+//                      record files (fragment preserved), then regenerate the navigator +
+//                      docs/ai/index.md (item (h)). Monoliths present → a LOUD legacy-guard refusal
+//                      ("run --migrate first"); it never half-explodes.
+//   --check            verify HOT cap + adr/ store integrity + the legacy guard + navigator freshness
+//                      + reference integrity (every inbound `decisions.md#ad-NNN…` anchor must
+//                      resolve to the CURRENT HOT window — an archived id is stale, not resolving —
+//                      and every `adr/AD-NNN-slug.md` link must name an existing record FILE); exit 1
+//                      listing every breach with file:line. A STATED skip (exit 0) only when NO ADR
+//                      substrate exists (neither decisions.md NOR docs/ai/adr/) AND the docs tree
+//                      carries no matching ADR reference.
 //   --migrate          one-time retirement of the 3-tier monoliths → per-file adr/ records. Dry-run by
-//                      default (prints the file set + id diff + conservation proof, writes nothing).
-//   --migrate --apply  writes a durable pre-delete snapshot, writes the records, rewrites the retained
-//                      HOT preamble, and only THEN removes the monoliths — gated on conservation AND
-//                      the snapshot. Re-run skips byte-identical records (crash-resumable).
+//                      default (prints the file set + id diff + conservation proof + the planned
+//                      inbound-rewrite set, writes nothing).
+//   --migrate --apply  writes a durable pre-delete snapshot, writes the records, rewrites the inbound
+//                      links (monolith-form anchors too, targets computed relative to the linking
+//                      file) and the retained HOT preamble, and only THEN removes the monoliths —
+//                      gated on conservation AND the snapshot. Re-run skips byte-identical records
+//                      (crash-resumable). Combining with --dry-run is a loud pre-spend refusal.
 //   --write-navigator  regenerate docs/ai/adr/log.md AND re-trigger the index regen (the authoring /
 //                      supersession write-side; the --write-index analog). With --dry-run it runs
 //                      EXACTLY the same validation (parse, half-migrated guard, store integrity) and
 //                      stops before every write — the read-only preflight a guarded caller needs to
 //                      earn a go-ahead without risking a partial write.
-//   --dry-run          print the planned rotation move-set, change nothing.
+//   --dry-run          print the planned rotation move-set + inbound-rewrite set (file:line, old
+//                      target → new target), change nothing.
 //   --today=YYYY-MM-DD pin the lastUpdated stamp (tests / reproducible runs).
 //
+// Reference-scan boundary + stated limitations: the inbound-link scan covers docs/ai/** ONLY (links
+// in README / agent entry points are out of scope); the ADR corpus surfaces themselves are NEVER
+// rewritten — a rewrite-form link to a moved id inside decisions.md, an adr/ record or a monolith
+// tier is a loud pre-write refusal (convert it, e.g. to the [[AD-NNN]] form, then re-run). Fenced
+// regions never count; inline code is NOT tracked (a backtick-wrapped link is treated as live);
+// matching is line-scoped — a link hand-wrapped across a line break is not matched (the same
+// accepted residual as the hand-wrapped preamble continuation line below); and frontmatter is
+// opaque metadata — an ADR link inside YAML frontmatter is neither rewritten nor checked (it is
+// preserved byte-exactly on every write).
+//
 // FAIL-LOUD invariants (the Issue-009 lesson — never silently glue an entry to the previous body):
 //   • every `## ` heading MUST parse canonically as `## AD-NNN — <title>` (AD-\d{3,}) — a malformed
 //     heading is exit 1 naming file:line, never a silent merge;
@@ -43,6 +63,10 @@
 //   • migration is CONSERVATION-checked before any destructive write: the full multiset
 //     {id → sha256(verbatim block)} across the OLD monoliths equals {retained-HOT ∪ written records};
 //     a drop / renumber / edited-block / stray adr record fails exit 1 before any remove or overwrite;
+//   • inbound-link rewrites are CONSERVATION-checked before the run's first write: every moved-id
+//     link rewritten, every other byte of every scanned file identical — any mismatch is exit 1 with
+//     nothing written; the cross-file write order is pinned (records → inbound rewrites → HOT rewrite
+//     / monolith removal) so every interrupted state re-runs to completion;
 //   • a legacy monolith still on disk fails LOUD on default/--check (it is a half-migrated tree).
 //
 // docs/ai here is git-ignored, so the monoliths were NEVER committed (no VCS recovery) — every
@@ -51,8 +75,8 @@
 //
 // Dependency-free, Node >= 22. Deployed into a consumer's scripts/ like its siblings.
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
-import { dirname, resolve, join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { dirname, resolve, join, posix } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -275,6 +299,265 @@ export const verifyConservation = (oldItems, newItems) => {
   }
 };
 
+// ── inbound reference integrity (the anchor-orphan fix) ─────────────────────────────────
+//
+// Match contract (line-scoped; fenced lines never count): a textual occurrence of the
+// source-file-plus-fragment form. The lookbehind rejects a longer filename
+// (`other-decisions.md#…` is a different file, never a match); a bare `#ad-NNN` has no file part.
+const DOCS_AI_REL = 'docs/ai';
+const HOT_LINK_RE = /(?<![\w.-])decisions\.md#(ad-(\d{3,})[\w-]*)/g;
+const MONOLITH_LINK_RE = /(?<![\w.-])(?:\.\.?\/)*(?:history\/)?decisions-archive(?:-early)?\.md#(ad-(\d{3,})[\w-]*)/g;
+// The right boundary mirrors the lookbehind: `…md.bak` / `…md/child` are DIFFERENT targets, never
+// a match for the base record (the exact-filename contract cuts both ways).
+const RECORD_LINK_RE = /(?<![\w.-])adr\/(AD-(\d{3,})-[A-Za-z0-9-]+\.md)(?![\w./-])/g;
+
+const walkDocsMarkdown = (root) => {
+  const base = resolve(root, DOCS_AI_REL);
+  if (!existsSync(base)) return [];
+  const out = [];
+  const walk = (dir, relDir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const rel = `${relDir}/${entry.name}`;
+      if (entry.isDirectory()) {
+        walk(join(dir, entry.name), rel);
+        continue;
+      }
+      // read/write both FOLLOW a symlink (out of the tree), and silently skipping one hides a
+      // scannable doc or a whole subtree from the reference scan — refuse loudly either way; only
+      // a symlink resolving to a plain non-markdown file stays an ignored stray.
+      if (entry.isSymbolicLink() && !entry.name.endsWith('.md')) {
+        let targetIsDirectory = false;
+        try {
+          targetIsDirectory = statSync(join(dir, entry.name)).isDirectory();
+        } catch {
+          throw fail(1, `${rel}: a dangling symlink in the scan tree — the reference scan cannot classify it; remove or materialize it, then re-run`);
+        }
+        if (targetIsDirectory) {
+          throw fail(1, `${rel}: a symlinked directory in the scan tree would hide its subtree from the reference scan — materialize or remove it, then re-run`);
+        }
+        continue;
+      }
+      if (entry.name.endsWith('.md')) {
+        if (!entry.isFile()) {
+          throw fail(1, `${rel}: a markdown name in the scan tree is not a regular file (a symlink or special file) — the reference scan never reads or writes THROUGH it; materialize or remove it, then re-run`);
+        }
+        out.push(rel);
+      }
+    }
+  };
+  walk(base, DOCS_AI_REL);
+  return out;
+};
+
+// REWRITE scope: docs/ai/** minus the ADR corpus surfaces (HOT, adr/ records + navigator) and the
+// retired monoliths — those are parsed, conservation-hashed and deleted in the same run; a same-run
+// disk rewrite would poison the crash-resume corpus-union guard and write into removed files.
+const isRewriteScope = (rel) =>
+  rel !== HOT_REL && rel !== WARM_REL && rel !== COLD_REL && rel !== NAV_REL && !rel.startsWith(`${ADR_DIR_REL}/`);
+
+// The corpus surfaces are never rewritten: a rewrite-form link to a MOVED id anywhere in them is a
+// loud pre-write refusal — the operator converts the link and re-runs; verbatim blocks stay absolute.
+const assertAdrCorpusFreeOfMovedLinks = (root, movedById, corpusRels, linkRes) => {
+  const violations = [];
+  for (const rel of corpusRels) {
+    const { frontLines, lines, fencedLines } = tokenizeMarkdown(readFileSync(resolve(root, rel), 'utf8'), rel);
+    for (let index = 0; index < lines.length; index += 1) {
+      if (fencedLines.has(index)) continue;
+      for (const re of linkRes) {
+        for (const m of lines[index].matchAll(re)) {
+          if (movedById.has(m[2])) violations.push(`${rel}:${frontLines + index + 1}: "${m[0]}"`);
+        }
+      }
+    }
+  }
+  if (violations.length > 0) {
+    throw fail(1, `refusing pre-write: the ADR corpus itself carries rewrite-form links to a moved id — a corpus surface is never rewritten; convert each link (e.g. to the [[AD-NNN]] form), then re-run:\n  ${violations.join('\n  ')}`);
+  }
+};
+
+// A block leaving decisions.md cannot keep a RELATIVE ADR link meaningful: the block moves
+// verbatim (the conservation invariant forbids editing it) while its base directory changes —
+// refuse pre-write when a TO-EXPLODE block links a RETAINED id (the moved-id complement is
+// refused corpus-wide by assertAdrCorpusFreeOfMovedLinks) or carries ANY record-form link
+// (valid from decisions.md, broken from inside adr/).
+const assertMovingBlocksFreeOfRelativeAdrLinks = (root, movedIds, retainedIds) => {
+  const { frontLines, lines, fencedLines, headings } = tokenizeMarkdown(readFileSync(resolve(root, HOT_REL), 'utf8'), HOT_REL);
+  const violations = [];
+  const h2 = headings.filter((h) => h.level === 2 && HEADING_RE.test(h.text));
+  for (let i = 0; i < h2.length; i += 1) {
+    if (!movedIds.has(HEADING_RE.exec(h2[i].text)[1])) continue;
+    const end = i + 1 < h2.length ? h2[i + 1].index : lines.length;
+    for (let index = h2[i].index; index < end; index += 1) {
+      if (fencedLines.has(index)) continue;
+      for (const m of lines[index].matchAll(HOT_LINK_RE)) {
+        if (retainedIds.has(m[2])) violations.push(`${HOT_REL}:${frontLines + index + 1}: "${m[0]}"`);
+      }
+      for (const m of lines[index].matchAll(RECORD_LINK_RE)) {
+        violations.push(`${HOT_REL}:${frontLines + index + 1}: "${m[0]}"`);
+      }
+    }
+  }
+  if (violations.length > 0) {
+    throw fail(1, `refusing pre-write: a block leaving ${HOT_REL} carries a relative ADR link (a RETAINED decisions.md#… anchor or an adr/… record link) — the block moves verbatim, so the link would change meaning inside the record; convert each link (e.g. to the [[AD-NNN]] form), then re-run:\n  ${violations.join('\n  ')}`);
+  }
+};
+
+// Migrate deletes the monolith files: a monolith-form link whose id is NOT in the moved set could
+// never point at a record after --apply (D5's "all point at records" outcome) — refuse pre-write
+// wherever it sits (rewrite scope, HOT, records, the monolith blocks about to become records).
+const assertNoOrphanedMonolithLinks = (root, movedById, rels) => {
+  const violations = [];
+  for (const rel of rels) {
+    const { frontLines, lines, fencedLines } = tokenizeMarkdown(readFileSync(resolve(root, rel), 'utf8'), rel);
+    for (let index = 0; index < lines.length; index += 1) {
+      if (fencedLines.has(index)) continue;
+      for (const m of lines[index].matchAll(MONOLITH_LINK_RE)) {
+        if (!movedById.has(m[2])) violations.push(`${rel}:${frontLines + index + 1}: "${m[0]}"`);
+      }
+    }
+  }
+  if (violations.length > 0) {
+    throw fail(1, `refusing pre-write: monolith-form links target an id OUTSIDE the moved set — after --apply removes the monoliths these links could never resolve to a record; fix each link, then re-run:\n  ${violations.join('\n  ')}`);
+  }
+};
+
+// The inbound-rewrite plan across the REWRITE scope. HOT-form links keep their leading relative
+// prefix (adr/ is a SIBLING of decisions.md, so the same prefix reaches the record and the fragment
+// resolves verbatim there); monolith-form targets are computed RELATIVE TO THE LINKING FILE with
+// URL-style forward-slash separators on every platform.
+const planInboundRewrites = (root, movedById, withMonolithForms) => {
+  const plans = [];
+  for (const rel of walkDocsMarkdown(root).filter(isRewriteScope)) {
+    const { frontmatter, frontLines, lines, fencedLines } = tokenizeMarkdown(readFileSync(resolve(root, rel), 'utf8'), rel);
+    const rewrites = [];
+    const afterLines = lines.map((line, index) => {
+      if (fencedLines.has(index)) return line;
+      // Every match of every form is collected POSITIONALLY on the ORIGINAL line (the forms are
+      // textually disjoint), then the line is rebuilt by range-splicing — a negative sharing
+      // bytes with a valid link elsewhere on the line can never contaminate the rewrite or its
+      // re-derivation.
+      const matches = [];
+      for (const m of line.matchAll(HOT_LINK_RE)) {
+        const moved = movedById.get(m[2]);
+        if (moved) matches.push({ start: m.index, old: m[0], new: `adr/${moved.fileName}#${m[1]}` });
+      }
+      if (withMonolithForms) {
+        for (const m of line.matchAll(MONOLITH_LINK_RE)) {
+          const moved = movedById.get(m[2]);
+          if (moved) matches.push({ start: m.index, old: m[0], new: `${posix.relative(posix.dirname(rel), `${ADR_DIR_REL}/${moved.fileName}`)}#${m[1]}` });
+        }
+      }
+      if (matches.length === 0) return line;
+      matches.sort((a, b) => a.start - b.start);
+      let cursor = 0;
+      let next = '';
+      for (const match of matches) {
+        if (match.start < cursor) throw fail(1, `${rel}:${frontLines + index + 1}: overlapping link matches — refusing to plan a rewrite`);
+        next += line.slice(cursor, match.start) + match.new;
+        cursor = match.start + match.old.length;
+        rewrites.push({ index, line: frontLines + index + 1, start: match.start, old: match.old, new: match.new });
+      }
+      next += line.slice(cursor);
+      return next;
+    });
+    if (rewrites.length > 0) plans.push({ rel, frontmatter, frontLines, beforeLines: lines, afterLines, rewrites });
+  }
+  return plans;
+};
+
+// Conservation (fail-loud): re-derive the rewritten file from { before + planned rewrites } and
+// require byte-equality — a dropped/altered link or any changed byte outside the plan is exit 1
+// with nothing written. Exported so its failure paths are unit-testable directly.
+export const verifyRewriteConservation = (plan) => {
+  const { rel, frontLines, beforeLines, afterLines, rewrites } = plan;
+  const refuse = (line, detail) => fail(1, `${rel}:${line}: inbound-rewrite conservation violation — ${detail}; refusing with nothing written`);
+  if (beforeLines.length !== afterLines.length) throw refuse(frontLines + 1, `the rewrite changed the line count (${beforeLines.length} → ${afterLines.length})`);
+  const byIndex = new Map();
+  for (const rw of rewrites) {
+    const list = byIndex.get(rw.index);
+    if (list) list.push(rw);
+    else byIndex.set(rw.index, [rw]);
+  }
+  for (let index = 0; index < beforeLines.length; index += 1) {
+    const fileLine = frontLines + index + 1;
+    const planned = byIndex.get(index);
+    if (!planned) {
+      if (beforeLines[index] !== afterLines[index]) throw refuse(fileLine, 'a line outside the planned rewrite set changed');
+      continue;
+    }
+    let expected;
+    if (planned.every((rw) => typeof rw.start === 'number')) {
+      // Range-splicing re-derivation (offsets recorded on the ORIGINAL line) — a same-bytes
+      // negative elsewhere on the line can never contaminate it.
+      const ordered = [...planned].sort((a, b) => a.start - b.start);
+      let cursor = 0;
+      expected = '';
+      for (const rw of ordered) {
+        if (rw.start < cursor) throw refuse(fileLine, 'overlapping planned rewrites');
+        if (beforeLines[index].slice(rw.start, rw.start + rw.old.length) !== rw.old) throw refuse(fileLine, `the planned link "${rw.old}" is not at its recorded offset in the source line`);
+        expected += beforeLines[index].slice(cursor, rw.start) + rw.new;
+        cursor = rw.start + rw.old.length;
+      }
+      expected += beforeLines[index].slice(cursor);
+    } else {
+      // Occurrence-based fallback for plans without offsets (the exported contract's original
+      // shape); longest-first so a link that is a textual prefix of another cannot corrupt it.
+      const unique = [...new Map(planned.map((rw) => [`${rw.old} ${rw.new}`, rw])).values()].sort((a, b) => b.old.length - a.old.length);
+      expected = beforeLines[index];
+      for (const rw of unique) {
+        if (!expected.includes(rw.old)) throw refuse(fileLine, `the planned link "${rw.old}" is absent from the source line`);
+        expected = expected.split(rw.old).join(rw.new);
+      }
+    }
+    if (afterLines[index] !== expected) throw refuse(fileLine, 'the rewritten line diverges from the planned substitution (a link would be dropped or altered)');
+    for (const rw of planned) {
+      if (!afterLines[index].includes(rw.new)) throw refuse(fileLine, `the rewritten link "${rw.new}" is missing from the output line (a link would be dropped)`);
+    }
+  }
+};
+
+const summarizeRewrites = (plans) =>
+  plans.flatMap((plan) => plan.rewrites.map((rw) => `${plan.rel}:${rw.line} ${rw.old} → ${rw.new}`));
+
+export const writeInboundRewrites = (root, plans) => {
+  // Two passes (the plan is computed pre-write, D4): verify the LIVE bytes of EVERY planned file
+  // first, then write — a drift anywhere refuses with NOTHING written in the rewrite phase.
+  for (const plan of plans) {
+    if (readFileSync(resolve(root, plan.rel), 'utf8') !== `${plan.frontmatter}${plan.beforeLines.join('\n')}`) {
+      throw fail(1, `${plan.rel}: changed between the rewrite plan and the write — refusing to overwrite from a stale snapshot; re-run`);
+    }
+  }
+  for (const plan of plans) {
+    writeFileSync(resolve(root, plan.rel), `${plan.frontmatter}${plan.afterLines.join('\n')}`, 'utf8');
+  }
+};
+
+// CHECK scope (read-only, wider): docs/ai/** including decisions.md (whole file) and the adr/
+// records, excluding only the generated navigator. (a) a `decisions.md#ad-NNN…` id outside the
+// CURRENT HOT window is dead (an archived id is stale, not resolving); (b) an `adr/AD-NNN-slug.md`
+// link must name an existing record FILE (exact filename, not id-presence).
+const collectReferenceViolations = (root, hotIds, archivedIds) => {
+  const violations = [];
+  for (const rel of walkDocsMarkdown(root).filter((r) => r !== NAV_REL)) {
+    const { frontLines, lines, fencedLines } = tokenizeMarkdown(readFileSync(resolve(root, rel), 'utf8'), rel);
+    for (let index = 0; index < lines.length; index += 1) {
+      if (fencedLines.has(index)) continue;
+      const fileLine = frontLines + index + 1;
+      for (const m of lines[index].matchAll(HOT_LINK_RE)) {
+        if (hotIds.has(m[2])) continue;
+        const why = archivedIds.has(m[2]) ? `AD-${m[2]} is archived — repoint the link at ${ADR_DIR_REL}/` : `AD-${m[2]} is not in the current HOT window`;
+        violations.push(`${rel}:${fileLine}: dead ADR anchor "${m[0]}" — ${why}`);
+      }
+      for (const m of lines[index].matchAll(RECORD_LINK_RE)) {
+        if (!existsSync(resolve(root, ADR_DIR_REL, m[1]))) {
+          violations.push(`${rel}:${fileLine}: dead ADR record link "${m[0]}" — no record file ${ADR_DIR_REL}/${m[1]}`);
+        }
+      }
+    }
+  }
+  return violations;
+};
+
 // ── tier / store IO ─────────────────────────────────────────────────────────────────────
 
 export const lineCountOf = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
@@ -581,6 +864,10 @@ const parseArgs = (argv) => {
     else if (arg.startsWith('--today=')) today = arg.slice('--today='.length);
     else throw fail(2, `Unknown argument: ${arg}\n${USAGE}`);
   }
+  // Pre-fix, --apply silently won over --dry-run and wrote — a fail-closed contract cannot keep that.
+  if (flags.migrate && flags.apply && flags.dryRun) {
+    throw fail(2, `--migrate --apply --dry-run is contradictory — plain --migrate IS the dry run; drop --apply to preview or --dry-run to apply\n${USAGE}`);
+  }
   return { flags, today };
 };
 
@@ -672,10 +959,23 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   for (const r of records) finalStoreById.set(r.id, { id: r.id, idNum: r.idNum, fileName: r.fileName });
   assertStoreIntegrity(retained, [...finalStoreById.values()]);
 
+  const movedById = new Map(records.map((r) => [r.id, r]));
+  assertAdrCorpusFreeOfMovedLinks(root, movedById, [HOT_REL, ...existingStore.map((e) => e.rel), ...present], [HOT_LINK_RE, MONOLITH_LINK_RE]);
+  assertMovingBlocksFreeOfRelativeAdrLinks(root, new Set(movedById.keys()), new Set(retained.map((e) => e.id)));
+  assertNoOrphanedMonolithLinks(root, movedById, [
+    ...walkDocsMarkdown(root).filter(isRewriteScope),
+    HOT_REL,
+    ...existingStore.map((e) => e.rel),
+    ...present,
+  ]);
+  const rewritePlans = planInboundRewrites(root, movedById, true);
+  for (const plan of rewritePlans) verifyRewriteConservation(plan);
+
   const summary = {
     records: records.map((r) => r.fileName),
     retainedHot: retained.map((e) => `AD-${e.id}`),
     monolithsRetired: present,
+    inboundRewrites: summarizeRewrites(rewritePlans),
     conservation: `${oldItems.length} corpus blocks → ${retained.length} retained-HOT + ${records.length} records (conserved)`,
   };
 
@@ -692,7 +992,9 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   ];
   const snapshot = writeSnapshot(root, snapshotFiles, deps);
 
+  // Pinned write order: records → inbound rewrites → HOT rewrite / monolith removal.
   writeRecords(root, records);
+  writeInboundRewrites(root, rewritePlans);
   const corpus = [...retained, ...loadAdrStore(root)];
   writeNavigatorFile(root, corpus, today);
   writeHot(root, hot, retained, today);
@@ -703,6 +1005,7 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   log('[archive-decisions] migrated the 3-tier cascade → one-file-per-ADR store:');
   log(`  snapshot: ${snapshot.dir} (${snapshot.viaGitDir ? 'git dir' : 'out-of-tree fallback'})`);
   log(`  records written: ${records.length} under ${ADR_DIR_REL}/`);
+  log(`  inbound links rewritten: ${summary.inboundRewrites.length} across ${rewritePlans.length} file(s)`);
   log(`  retained HOT: ${summary.retainedHot.join(', ') || '(none)'}`);
   log(`  retired monoliths: ${present.join(', ')}`);
   log(`  navigator: ${NAV_REL}`);
@@ -756,6 +1059,13 @@ const runCheck = (root, today, log, logError) => {
     return 1;
   }
   if (!hasHot && !hasStore) {
+    // The reference scan still runs: a matching reference over NO substrate is a dead link, never a
+    // clean skip — the SKIP remains only for a tree with zero matches.
+    const orphaned = collectReferenceViolations(root, new Set(), new Set());
+    if (orphaned.length > 0) {
+      for (const v of orphaned) logError(`[archive-decisions] FAIL: ${v}.`);
+      return 1;
+    }
     log(`[archive-decisions] SKIP — no ADR substrate (neither ${HOT_REL} nor ${ADR_DIR_REL}); nothing to check.`);
     return 0;
   }
@@ -783,11 +1093,13 @@ const runCheck = (root, today, log, logError) => {
     problems.push(`${NAV_REL} is stale (out of sync with the ADR corpus) — run \`node scripts/archive-decisions.mjs --write-navigator\` and commit it`);
   }
 
+  problems.push(...collectReferenceViolations(root, new Set(hotEntries.map((e) => e.id)), new Set(adrEntries.map((e) => e.id))));
+
   if (problems.length > 0) {
     for (const p of problems) logError(`[archive-decisions] FAIL: ${p}.`);
     return 1;
   }
-  log('[archive-decisions] OK — HOT within cap, store integrity intact, navigator fresh.');
+  log('[archive-decisions] OK — HOT within cap, store integrity intact, navigator fresh, inbound ADR references resolve.');
   return 0;
 };
 
@@ -825,20 +1137,33 @@ const runRotate = (root, flags, today, deps, log, logError) => {
   for (const rec of records) finalStoreById.set(rec.id, { id: rec.id, idNum: rec.idNum, fileName: rec.fileName });
   assertStoreIntegrity(retained, [...finalStoreById.values()]);
 
-  const summary = { explode: records.map((r) => r.fileName), retainedHot: retained.map((e) => `AD-${e.id}`) };
+  const movedById = new Map(records.map((r) => [r.id, r]));
+  assertAdrCorpusFreeOfMovedLinks(root, movedById, [HOT_REL, ...existingStore.map((e) => e.rel)], [HOT_LINK_RE]);
+  assertMovingBlocksFreeOfRelativeAdrLinks(root, new Set(movedById.keys()), new Set(retained.map((e) => e.id)));
+  const rewritePlans = planInboundRewrites(root, movedById, false);
+  for (const plan of rewritePlans) verifyRewriteConservation(plan);
+
+  const summary = {
+    explode: records.map((r) => r.fileName),
+    retainedHot: retained.map((e) => `AD-${e.id}`),
+    inboundRewrites: summarizeRewrites(rewritePlans),
+  };
   if (flags.dryRun) {
     log('[archive-decisions] DRY-RUN — no files will be changed.');
     log(JSON.stringify(summary, null, 2));
     return 0;
   }
 
+  // Pinned write order: records → inbound rewrites → HOT rewrite (crash-resume idempotency).
   writeRecords(root, records);
+  writeInboundRewrites(root, rewritePlans);
   const corpus = [...retained, ...loadAdrStore(root)];
   writeNavigatorFile(root, corpus, today);
   writeHot(root, hot, retained, today);
   const regen = (deps.regenerateIndex ?? defaultRegenerateIndex)(root, today);
   log('[archive-decisions] rotated:');
   log(`  exploded to adr/: ${summary.explode.join(', ') || '(none)'}`);
+  log(`  inbound links rewritten: ${summary.inboundRewrites.length} across ${rewritePlans.length} file(s)`);
   log(`  retained HOT: ${summary.retainedHot.join(', ')}`);
   if (regen.ok) log('  regenerated docs/ai/index.md');
   else logError(`[archive-decisions] docs/ai/index.md NOT regenerated — ${regen.detail}`);

package/references/scripts/archive-decisions.test.mjs

@@ -1,8 +1,8 @@
 import { describe, it, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync, readdirSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import {
   HOT_REL,
   WARM_REL,
@@ -23,6 +23,8 @@ import {
   lineCountOf,
   runCli,
   defaultRegenerateIndex,
+  verifyRewriteConservation,
+  writeInboundRewrites,
 } from './archive-decisions.mjs';
 
 // Hermetic: this test ships as deploy payload and runs inside CONSUMER repos via the pre-commit
@@ -940,3 +942,521 @@ describe('usage', () => {
     assert.match(text, /Usage: archive-decisions/);
   });
 });
+
+// ── reference integrity — inbound anchor rewrite + check assertions (the anchor-orphan fix) ────
+//
+// Rotation/migration move ADR blocks out of HOT while inbound `decisions.md#ad-NNN…` links keep
+// pointing at the old home. The write passes rewrite those links (monolith forms too under
+// migrate) under a conservation invariant, `--check` asserts every inbound ADR reference
+// resolves, and the exported verifier refuses a dropped/altered rewrite with nothing written.
+// Fenced occurrences never count; inline code is treated as live (a stated limitation).
+
+const writeDoc = (root, rel, text) => {
+  mkdirSync(dirname(join(root, rel)), { recursive: true });
+  writeFileSync(join(root, rel), text);
+};
+
+// An over-cap migrated-shape HOT (no monolith): cap = rendered - 1 → exactly the oldest explodes.
+const seedOverCapHot = (root, ids) => {
+  mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
+  const blocks = ids.map((id) => adrBlock(id));
+  const preamble = '# ADRs\n\n> Newest at the bottom.';
+  const probe = tierText(9999, preamble, blocks);
+  writeFileSync(join(root, HOT_REL), tierText(lineCountOf(probe) - 1, preamble, blocks));
+};
+
+describe('reference integrity — rotate/migrate rewrite inbound links, --check asserts them', () => {
+  // Legacy tree whose migrate moves AD-001…AD-005 (HOT overflows by one) and retains AD-006…AD-008,
+  // with inbound links at two depths: pages (needs ../) and history (monolith sibling).
+  const seedMigrateFixture = (root) => {
+    seedLegacy(root, { hot: ['005', '006', '007', '008'], warm: ['003', '004'], cold: ['001', '002'], hotCapDelta: -1 });
+    writeDoc(root, 'docs/ai/pages/spec.md', [
+      'hot [AD-005](../decisions.md#ad-005--decision-005)',
+      'warm [AD-003](../history/decisions-archive.md#ad-003--decision-003)',
+      '',
+    ].join('\n'));
+    writeDoc(root, 'docs/ai/history/notes.md', 'cold sibling [AD-001](decisions-archive-early.md#ad-001--decision-001)\n');
+  };
+
+  it('rotate rewrites inbound decisions.md anchors to record links, fragment preserved', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    writeDoc(root, 'docs/ai/pages/spec.md', '# Spec\n\nsee [AD-001](../decisions.md#ad-001--decision-001) for the decision.\n');
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 0, errText);
+    const text = readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8');
+    assert.match(text, /\[AD-001\]\(\.\.\/adr\/AD-001-decision-001\.md#ad-001--decision-001\)/);
+    assert.doesNotMatch(text, /decisions\.md#ad-001(?!-)|\(\.\.\/decisions\.md/);
+  });
+
+  it('rotate rewrite is count-preserving: every moved-id link rewritten, all other bytes identical', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    const spec = [
+      '# Spec',
+      '',
+      'moved [AD-001](../decisions.md#ad-001--decision-001) and inline `../decisions.md#ad-001--decision-001` on one line.',
+      'retained [AD-004](../decisions.md#ad-004--decision-004) stays.',
+      'negatives: [other](../other-decisions.md#ad-001--decision-001) and [bare](#ad-001--decision-001).',
+      '',
+    ].join('\n');
+    writeDoc(root, 'docs/ai/pages/spec.md', spec);
+    writeDoc(root, 'docs/ai/history/notes.md', 'notes: [AD-001](../decisions.md#ad-001--decision-001)\n');
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 0, errText);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8'), [
+      '# Spec',
+      '',
+      'moved [AD-001](../adr/AD-001-decision-001.md#ad-001--decision-001) and inline `../adr/AD-001-decision-001.md#ad-001--decision-001` on one line.',
+      'retained [AD-004](../decisions.md#ad-004--decision-004) stays.',
+      'negatives: [other](../other-decisions.md#ad-001--decision-001) and [bare](#ad-001--decision-001).',
+      '',
+    ].join('\n'));
+    assert.equal(readFileSync(join(root, 'docs/ai/history/notes.md'), 'utf8'), 'notes: [AD-001](../adr/AD-001-decision-001.md#ad-001--decision-001)\n');
+  });
+
+  it('rotate dry-run prints the rewrite set and writes nothing', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    const spec = 'see [AD-001](../decisions.md#ad-001--decision-001).\n';
+    writeDoc(root, 'docs/ai/pages/spec.md', spec);
+    const hotBefore = readFileSync(join(root, HOT_REL), 'utf8');
+    const { code, text } = run(['--dry-run', '--today=2026-08-07'], root);
+    assert.equal(code, 0, text);
+    assert.match(text, /docs\/ai\/pages\/spec\.md:1 decisions\.md#ad-001--decision-001 → adr\/AD-001-decision-001\.md#ad-001--decision-001/);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8'), spec, 'the doc is byte-unchanged');
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), hotBefore, 'HOT is byte-unchanged');
+    assert.deepEqual(adrFiles(root), [], 'no record written on a dry-run');
+  });
+
+  it('--check exits 1 listing every stale decisions.md anchor with file:line', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    writeDoc(root, 'docs/ai/pages/spec.md', [
+      'stale-but-archived [AD-001](../decisions.md#ad-001--decision-001)',
+      'nonexistent [AD-099](../decisions.md#ad-099--gone)',
+      '',
+    ].join('\n'));
+    const { code, errText } = run(['--check', '--today=2026-07-09'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/pages\/spec\.md:1: .*ad-001/);
+    assert.match(errText, /docs\/ai\/pages\/spec\.md:2: .*ad-099/);
+  });
+
+  it('--check exits 1 with file:line on a dead adr record link (exact filename)', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] });
+    writeDoc(root, 'docs/ai/pages/spec.md', [
+      'good [AD-001](../adr/AD-001-decision-001.md)',
+      'dead [AD-001](../adr/AD-001-wrong-slug.md)',
+      '',
+    ].join('\n'));
+    const { code, errText } = run(['--check', '--today=2026-07-09'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/pages\/spec\.md:2: .*AD-001-wrong-slug\.md/);
+    assert.doesNotMatch(errText, /spec\.md:1:/, 'the resolving record link is not flagged');
+  });
+
+  it('--migrate --apply rewrites inbound links including monolith-form anchors, source-relative', () => {
+    const root = makeRoot();
+    seedMigrateFixture(root);
+    const { code, errText } = run(['--migrate', '--apply', '--today=2026-08-07'], root);
+    assert.equal(code, 0, errText);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8'), [
+      'hot [AD-005](../adr/AD-005-decision-005.md#ad-005--decision-005)',
+      'warm [AD-003](../adr/AD-003-decision-003.md#ad-003--decision-003)',
+      '',
+    ].join('\n'));
+    assert.equal(readFileSync(join(root, 'docs/ai/history/notes.md'), 'utf8'), 'cold sibling [AD-001](../adr/AD-001-decision-001.md#ad-001--decision-001)\n');
+    assert.equal(run(['--check', '--today=2026-08-07'], root).code, 0, 'the rewritten tree is green end-to-end');
+  });
+
+  it('migrate dry-run prints the monolith and HOT rewrite set and writes nothing', () => {
+    const root = makeRoot();
+    seedMigrateFixture(root);
+    const specBefore = readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8');
+    const notesBefore = readFileSync(join(root, 'docs/ai/history/notes.md'), 'utf8');
+    const { code, text } = run(['--migrate', '--today=2026-08-07'], root);
+    assert.equal(code, 0, text);
+    assert.match(text, /DRY-RUN/);
+    assert.match(text, /docs\/ai\/pages\/spec\.md:1 decisions\.md#ad-005--decision-005 → adr\/AD-005-decision-005\.md#ad-005--decision-005/);
+    assert.match(text, /docs\/ai\/pages\/spec\.md:2 \.\.\/history\/decisions-archive\.md#ad-003--decision-003 → \.\.\/adr\/AD-003-decision-003\.md#ad-003--decision-003/);
+    assert.match(text, /docs\/ai\/history\/notes\.md:1 decisions-archive-early\.md#ad-001--decision-001 → \.\.\/adr\/AD-001-decision-001\.md#ad-001--decision-001/);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8'), specBefore);
+    assert.equal(readFileSync(join(root, 'docs/ai/history/notes.md'), 'utf8'), notesBefore);
+    assert.ok(existsSync(join(root, WARM_REL)) && existsSync(join(root, COLD_REL)), 'monoliths untouched');
+    assert.ok(!existsSync(join(root, ADR_DIR_REL)), 'no adr/ tree created on a dry-run');
+  });
+
+  it('rotate and migrate refuse pre-write when the ADR corpus links a moved id', () => {
+    // (a) the HOT preamble links the moved id
+    {
+      const root = makeRoot();
+      mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
+      const preamble = '# ADRs\n\n> see [old](decisions.md#ad-005--decision-005)';
+      const blocks = ['005', '006', '007', '008'].map((id) => adrBlock(id));
+      const probe = tierText(9999, preamble, blocks);
+      writeFileSync(join(root, HOT_REL), tierText(lineCountOf(probe) - 1, preamble, blocks));
+      const before = readFileSync(join(root, HOT_REL), 'utf8');
+      const { code, errText } = run(['--today=2026-08-07'], root);
+      assert.equal(code, 1);
+      assert.match(errText, /docs\/ai\/decisions\.md:\d+/);
+      assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), before, 'HOT untouched');
+      assert.deepEqual(adrFiles(root), [], 'no record written');
+    }
+    // (b) a HOT block body links the moved id
+    {
+      const root = makeRoot();
+      mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
+      const linked = ['## AD-007 — Decision 007', '', '**Date:** 2026-01-01 · **Status:** Accepted', '', 'refers to [x](decisions.md#ad-005--decision-005)'].join('\n');
+      const blocks = [adrBlock('005'), adrBlock('006'), linked, adrBlock('008')];
+      const probe = tierText(9999, '# ADRs', blocks);
+      writeFileSync(join(root, HOT_REL), tierText(lineCountOf(probe) - 1, '# ADRs', blocks));
+      const before = readFileSync(join(root, HOT_REL), 'utf8');
+      const { code, errText } = run(['--today=2026-08-07'], root);
+      assert.equal(code, 1);
+      assert.match(errText, /docs\/ai\/decisions\.md:\d+/);
+      assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), before, 'HOT untouched');
+      assert.deepEqual(adrFiles(root), [], 'no record written');
+    }
+    // (c) an existing adr/ record block links the moved id
+    {
+      const root = makeRoot();
+      seedOverCapHot(root, ['005', '006', '007', '008']);
+      writeFileSync(join(root, ADR_DIR_REL, 'AD-001-decision-001.md'), `${fm(RECORD_CAP)}\n## AD-001 — Decision 001\n\n**Date:** 2026-01-01\n\nsee [x](../decisions.md#ad-005--decision-005)\n`);
+      const before = readFileSync(join(root, HOT_REL), 'utf8');
+      const { code, errText } = run(['--today=2026-08-07'], root);
+      assert.equal(code, 1);
+      assert.match(errText, /adr\/AD-001-decision-001\.md:\d+/);
+      assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), before, 'HOT untouched');
+      assert.deepEqual(adrFiles(root), ['AD-001-decision-001.md'], 'no new record written');
+    }
+    // (d) a WARM monolith block links a moved id (migrate)
+    {
+      const root = makeRoot();
+      mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+      writeFileSync(join(root, HOT_REL), tierText(500, '# ADRs', [adrBlock('005')]));
+      const warmBlock = ['## AD-003 — Decision 003', '', '**Date:** 2026-01-01', '', 'see [x](../decisions.md#ad-001--decision-001)'].join('\n');
+      writeFileSync(join(root, WARM_REL), tierText(500, WARM_PREAMBLE, [warmBlock]));
+      writeFileSync(join(root, COLD_REL), tierText(500, COLD_PREAMBLE, [adrBlock('001')]));
+      const { code, errText } = run(['--migrate', '--apply', '--today=2026-08-07'], root);
+      assert.equal(code, 1);
+      assert.match(errText, /docs\/ai\/history\/decisions-archive\.md:\d+/);
+      assert.ok(existsSync(join(root, WARM_REL)) && existsSync(join(root, COLD_REL)), 'monoliths untouched');
+      assert.ok(!existsSync(join(root, ADR_DIR_REL)), 'no record written');
+      assert.ok(!existsSync(join(root, '.git', 'agent-workflow-adr-migration-snapshot-STAMP')), 'no snapshot on the refusal');
+    }
+    // (e) a COLD monolith block carries a monolith-form link to a moved id (migrate)
+    {
+      const root = makeRoot();
+      mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+      writeFileSync(join(root, HOT_REL), tierText(500, '# ADRs', [adrBlock('005')]));
+      writeFileSync(join(root, WARM_REL), tierText(500, WARM_PREAMBLE, [adrBlock('003')]));
+      const coldBlock = ['## AD-001 — Decision 001', '', '**Date:** 2026-01-01', '', 'see [x](decisions-archive.md#ad-003--decision-003)'].join('\n');
+      writeFileSync(join(root, COLD_REL), tierText(500, COLD_PREAMBLE, [coldBlock]));
+      const { code, errText } = run(['--migrate', '--apply', '--today=2026-08-07'], root);
+      assert.equal(code, 1);
+      assert.match(errText, /docs\/ai\/history\/decisions-archive-early\.md:\d+/);
+      assert.ok(existsSync(join(root, WARM_REL)) && existsSync(join(root, COLD_REL)), 'monoliths untouched');
+      assert.ok(!existsSync(join(root, ADR_DIR_REL)), 'no record written');
+    }
+  });
+
+  it('--check exits 1 on a dead reference inside an ADR block body', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
+    const hotBlock = ['## AD-005 — Decision 005', '', '**Date:** 2026-01-01', '', 'cites [gone](decisions.md#ad-002--decision-002)'].join('\n');
+    writeFileSync(join(root, HOT_REL), tierText(500, '# ADRs', [hotBlock]));
+    writeFileSync(join(root, ADR_DIR_REL, 'AD-001-decision-001.md'), `${fm(RECORD_CAP)}\n## AD-001 — Decision 001\n\n**Date:** 2026-01-01\n\ncites [gone too](../decisions.md#ad-099--gone)\n`);
+    assert.equal(run(['--write-navigator', '--today=2026-07-09'], root).code, 0);
+    const { code, errText } = run(['--check', '--today=2026-07-09'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/decisions\.md:\d+: .*ad-002/);
+    assert.match(errText, /docs\/ai\/adr\/AD-001-decision-001\.md:\d+: .*ad-099/);
+  });
+
+  it('--check without an ADR substrate still fails on a matching reference', () => {
+    const root = makeRoot();
+    writeDoc(root, 'docs/ai/pages/spec.md', 'orphan [AD-001](../decisions.md#ad-001--decision-001)\n');
+    const { code, errText } = run(['--check'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/pages\/spec\.md:1/);
+
+    const clean = makeRoot();
+    writeDoc(clean, 'docs/ai/pages/spec.md', 'no adr links here\n');
+    const skip = run(['--check'], clean);
+    assert.equal(skip.code, 0);
+    assert.match(skip.text, /SKIP — no ADR substrate/);
+  });
+
+  it('the rewrite conservation verifier refuses a dropped or altered link with nothing written', () => {
+    const base = {
+      rel: 'docs/ai/pages/spec.md',
+      frontLines: 0,
+      rewrites: [{ index: 0, line: 1, old: 'decisions.md#ad-001--decision-001', new: 'adr/AD-001-decision-001.md#ad-001--decision-001' }],
+    };
+    // a dropped link: the output line never received the planned rewrite
+    assert.throws(() => verifyRewriteConservation({
+      ...base,
+      beforeLines: ['see [x](../decisions.md#ad-001--decision-001)', 'tail'],
+      afterLines: ['see [x](../decisions.md#ad-001--decision-001)', 'tail'],
+    }), (e) => e.exitCode === 1 && /conservation/.test(e.message));
+    // an altered byte outside the planned rewrite set
+    assert.throws(() => verifyRewriteConservation({
+      ...base,
+      beforeLines: ['see [x](../decisions.md#ad-001--decision-001)', 'tail'],
+      afterLines: ['see [x](../adr/AD-001-decision-001.md#ad-001--decision-001)', 'tail ALTERED'],
+    }), (e) => e.exitCode === 1 && /conservation/.test(e.message));
+    // the honest plan passes
+    assert.doesNotThrow(() => verifyRewriteConservation({
+      ...base,
+      beforeLines: ['see [x](../decisions.md#ad-001--decision-001)', 'tail'],
+      afterLines: ['see [x](../adr/AD-001-decision-001.md#ad-001--decision-001)', 'tail'],
+    }));
+  });
+
+  it('a fenced dead-link sample leaves --check green and survives rotate byte-identically', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    writeDoc(root, 'docs/ai/pages/spec.md', ['fenced sample:', '', '```md', 'dead [x](../decisions.md#ad-099--gone)', '```', ''].join('\n'));
+    assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0, 'a fenced dead link never counts');
+
+    const root2 = makeRoot();
+    seedOverCapHot(root2, ['001', '002', '003', '004']);
+    const doc2 = ['```md', 'fenced moved link [x](../decisions.md#ad-001--decision-001)', '```', ''].join('\n');
+    writeDoc(root2, 'docs/ai/pages/spec.md', doc2);
+    assert.equal(run(['--today=2026-08-07'], root2).code, 0);
+    assert.equal(readFileSync(join(root2, 'docs/ai/pages/spec.md'), 'utf8'), doc2, 'the fenced occurrence survives rotate byte-identically');
+  });
+
+  it('an unclosed fence in a scanned doc aborts BOTH write paths exit 1 with the tree untouched', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    writeDoc(root, 'docs/ai/pages/broken.md', '```md\nnever closed\n');
+    const hotBefore = readFileSync(join(root, HOT_REL), 'utf8');
+    const r = run(['--today=2026-08-07'], root);
+    assert.equal(r.code, 1);
+    assert.match(r.errText, /never closed/);
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), hotBefore, 'HOT untouched');
+    assert.deepEqual(adrFiles(root), [], 'no record written');
+
+    const root2 = makeRoot();
+    seedLegacy(root2, { hot: ['005'], warm: ['003'], cold: ['001'] });
+    writeDoc(root2, 'docs/ai/pages/broken.md', '```md\nnever closed\n');
+    const m = run(['--migrate', '--apply', '--today=2026-08-07'], root2);
+    assert.equal(m.code, 1);
+    assert.match(m.errText, /never closed/);
+    assert.ok(existsSync(join(root2, WARM_REL)) && existsSync(join(root2, COLD_REL)), 'monoliths untouched');
+    assert.ok(!existsSync(join(root2, ADR_DIR_REL)), 'no record written');
+  });
+
+  it('the migrate rewrite set never targets a monolith file and written records preserve moved blocks verbatim', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai', 'history'), { recursive: true });
+    writeFileSync(join(root, HOT_REL), tierText(500, '# ADRs', [adrBlock('005')]));
+    const warmBlock = ['## AD-003 — Decision 003', '', '**Date:** 2026-01-01', '', 'links retained [AD-005](../decisions.md#ad-005--decision-005)'].join('\n');
+    writeFileSync(join(root, WARM_REL), tierText(500, WARM_PREAMBLE, [warmBlock]));
+    const dry = run(['--migrate', '--today=2026-08-07'], root);
+    assert.equal(dry.code, 0, dry.errText);
+    assert.doesNotMatch(dry.text, /history\/decisions-archive\.md:\d+ /, 'no rewrite entry targets a monolith file');
+    const applied = run(['--migrate', '--apply', '--today=2026-08-07'], root);
+    assert.equal(applied.code, 0, applied.errText);
+    const rec = readFileSync(join(root, ADR_DIR_REL, 'AD-003-decision-003.md'), 'utf8');
+    assert.match(rec, /links retained \[AD-005\]\(\.\.\/decisions\.md#ad-005--decision-005\)/, 'the moved block is preserved verbatim');
+  });
+
+  it('D9 negative fixtures stay byte-identical: a different filename and a bare fragment never match', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    const doc = 'neg: [a](../my-decisions.md#ad-001--decision-001) [b](#ad-001--decision-001)\n';
+    writeDoc(root, 'docs/ai/pages/neg.md', doc);
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 0, errText);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/neg.md'), 'utf8'), doc);
+  });
+
+  it('an interrupted state (records + rewrites written, HOT untrimmed) re-runs to completion', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    const entry = parseDecisionsText(tierText(999, '# T', [adrBlock('001')]), 'x').entries[0];
+    const [rec] = explode([entry], '2026-08-07');
+    writeFileSync(join(root, ADR_DIR_REL, rec.fileName), `${rec.frontmatter}\n${rec.block}\n`);
+    writeDoc(root, 'docs/ai/pages/spec.md', 'see [AD-001](../adr/AD-001-decision-001.md#ad-001--decision-001)\n');
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 0, errText);
+    assert.deepEqual(idsIn(root, HOT_REL), ['002', '003', '004'], 'the re-run completed the trim');
+    assert.equal(run(['--check', '--today=2026-08-07'], root).code, 0);
+  });
+
+  it('--check stays green on a live tree with resolving anchors', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    writeDoc(root, 'docs/ai/pages/spec.md', [
+      'live [AD-005](../decisions.md#ad-005--decision-005)',
+      'archived [AD-001](../adr/AD-001-decision-001.md#ad-001--decision-001)',
+      '',
+    ].join('\n'));
+    assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0);
+  });
+
+  it('--migrate --apply --dry-run refuses loudly pre-spend', () => {
+    const root = makeRoot();
+    seedLegacy(root, { hot: ['005'], warm: ['003'], cold: ['001'] });
+    const { code, errText } = run(['--migrate', '--apply', '--dry-run'], root);
+    assert.equal(code, 2);
+    assert.match(errText, /--migrate --apply --dry-run/);
+    assert.ok(existsSync(join(root, WARM_REL)), 'nothing written');
+  });
+
+  it('a symlinked markdown file in the scan tree refuses loudly (never read or written through)', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    writeFileSync(join(root, 'outside.md'), 'outside the docs tree\n');
+    mkdirSync(join(root, 'docs', 'ai', 'pages'), { recursive: true });
+    symlinkSync(join(root, 'outside.md'), join(root, 'docs/ai/pages/link.md'));
+    const hotBefore = readFileSync(join(root, HOT_REL), 'utf8');
+    const rotate = run(['--today=2026-08-07'], root);
+    assert.equal(rotate.code, 1);
+    assert.match(rotate.errText, /link\.md/);
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), hotBefore, 'HOT untouched');
+    assert.deepEqual(adrFiles(root), [], 'no record written');
+    assert.equal(readFileSync(join(root, 'outside.md'), 'utf8'), 'outside the docs tree\n', 'the symlink target is never touched');
+    const check = run(['--check', '--today=2026-08-07'], root);
+    assert.equal(check.code, 1);
+    assert.match(check.errText, /link\.md/);
+
+    const clean = makeRoot();
+    seedMigrated(clean, { hotIds: ['005'], storeIds: ['001'] });
+    writeFileSync(join(clean, 'notes.txt'), 'plain\n');
+    mkdirSync(join(clean, 'docs', 'ai', 'pages'), { recursive: true });
+    symlinkSync(join(clean, 'notes.txt'), join(clean, 'docs/ai/pages/notes.txt'));
+    assert.equal(run(['--check', '--today=2026-07-09'], clean).code, 0, 'a non-markdown symlink stays an ignored stray');
+  });
+
+  it('a rewrite-scope file that changed after planning refuses pre-write with the human edit intact', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai', 'pages'), { recursive: true });
+    const rel = 'docs/ai/pages/spec.md';
+    const before = 'see [AD-001](../decisions.md#ad-001--decision-001)\n';
+    writeFileSync(join(root, rel), before);
+    const plan = {
+      rel,
+      frontmatter: '',
+      frontLines: 0,
+      beforeLines: before.split('\n'),
+      afterLines: before.replace('decisions.md#ad-001--decision-001', 'adr/AD-001-decision-001.md#ad-001--decision-001').split('\n'),
+      rewrites: [],
+    };
+    writeFileSync(join(root, rel), 'humanly edited meanwhile\n');
+    assert.throws(() => writeInboundRewrites(root, [plan]), (e) => e.exitCode === 1 && /stale snapshot/.test(e.message));
+    assert.equal(readFileSync(join(root, rel), 'utf8'), 'humanly edited meanwhile\n', 'the human edit survives');
+    writeFileSync(join(root, rel), before);
+    writeInboundRewrites(root, [plan]);
+    assert.match(readFileSync(join(root, rel), 'utf8'), /adr\/AD-001-decision-001\.md#ad-001--decision-001/, 'the unchanged file is rewritten');
+  });
+
+  it('a symlinked directory in the scan tree refuses loudly instead of hiding its subtree', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] });
+    mkdirSync(join(root, 'elsewhere'), { recursive: true });
+    writeFileSync(join(root, 'elsewhere', 'notes.md'), 'dead [x](../decisions.md#ad-099--gone)\n');
+    symlinkSync(join(root, 'elsewhere'), join(root, 'docs/ai/pages'));
+    const { code, errText } = run(['--check', '--today=2026-07-09'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/pages/);
+
+    const root2 = makeRoot();
+    seedMigrated(root2, { hotIds: ['005'], storeIds: ['001'] });
+    symlinkSync(join(root2, 'gone-target'), join(root2, 'docs/ai/dangling'));
+    const r2 = run(['--check', '--today=2026-07-09'], root2);
+    assert.equal(r2.code, 1);
+    assert.match(r2.errText, /dangling symlink/);
+  });
+
+  it('migrate refuses pre-write when a monolith-form link targets an id outside the moved set', () => {
+    const root = makeRoot();
+    seedLegacy(root, { hot: ['005'], warm: ['003'], cold: ['001'] });
+    writeDoc(root, 'docs/ai/pages/spec.md', 'dead-after-apply [x](../history/decisions-archive.md#ad-777--nope)\n');
+    const { code, errText } = run(['--migrate', '--apply', '--today=2026-08-07'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/pages\/spec\.md:1/);
+    assert.ok(existsSync(join(root, WARM_REL)) && existsSync(join(root, COLD_REL)), 'monoliths untouched');
+    assert.ok(!existsSync(join(root, ADR_DIR_REL)), 'no record written');
+  });
+
+  it('rotate refuses pre-write when a MOVING block links a retained id', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
+    const moving = ['## AD-001 — Decision 001', '', '**Date:** 2026-01-01', '', 'see [x](decisions.md#ad-004--decision-004)'].join('\n');
+    const blocks = [moving, adrBlock('002'), adrBlock('003'), adrBlock('004')];
+    const probe = tierText(9999, '# ADRs', blocks);
+    writeFileSync(join(root, HOT_REL), tierText(lineCountOf(probe) - 1, '# ADRs', blocks));
+    const before = readFileSync(join(root, HOT_REL), 'utf8');
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/decisions\.md:\d+/);
+    assert.match(errText, /RETAINED/);
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), before, 'HOT untouched');
+    assert.deepEqual(adrFiles(root), [], 'no record written');
+  });
+
+  it('rotate refuses pre-write when a MOVING block carries a record-form link', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
+    const rec = explode(parseDecisionsText(tierText(999, '# T', [adrBlock('001')]), 'x').entries, '2026-08-07')[0];
+    writeFileSync(join(root, ADR_DIR_REL, rec.fileName), `${rec.frontmatter}\n${rec.block}\n`);
+    const moving = ['## AD-005 — Decision 005', '', '**Date:** 2026-01-01', '', 'see [x](adr/AD-001-decision-001.md)'].join('\n');
+    const blocks = [moving, adrBlock('006'), adrBlock('007'), adrBlock('008')];
+    const probe = tierText(9999, '# ADRs', blocks);
+    writeFileSync(join(root, HOT_REL), tierText(lineCountOf(probe) - 1, '# ADRs', blocks));
+    const before = readFileSync(join(root, HOT_REL), 'utf8');
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 1);
+    assert.match(errText, /docs\/ai\/decisions\.md:\d+/);
+    assert.match(errText, /record link|relative ADR link/);
+    assert.equal(readFileSync(join(root, HOT_REL), 'utf8'), before, 'HOT untouched');
+    assert.deepEqual(adrFiles(root), ['AD-001-decision-001.md'], 'no new record written');
+  });
+
+  it('a record-link match ends exactly at .md — a suffixed or child path is a different target', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] });
+    writeDoc(root, 'docs/ai/pages/spec.md', [
+      'not-a-record-link [a](../adr/AD-777-zzz.md.bak)',
+      'not-a-record-link [b](../adr/AD-001-decision-001.md/child)',
+      '',
+    ].join('\n'));
+    assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0, 'suffixed and child paths are different filenames, never record-form links');
+  });
+
+  it('a negative sharing bytes with a valid link on ONE line never poisons the rewrite', () => {
+    const root = makeRoot();
+    seedOverCapHot(root, ['001', '002', '003', '004']);
+    writeDoc(root, 'docs/ai/pages/spec.md', 'both [a](../decisions.md#ad-001--decision-001) and [n](../other-decisions.md#ad-001--decision-001)\n');
+    const { code, errText } = run(['--today=2026-08-07'], root);
+    assert.equal(code, 0, errText);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/spec.md'), 'utf8'),
+      'both [a](../adr/AD-001-decision-001.md#ad-001--decision-001) and [n](../other-decisions.md#ad-001--decision-001)\n');
+  });
+
+  it('a drift in ANY planned file refuses the whole rewrite phase with nothing written', () => {
+    const root = makeRoot();
+    mkdirSync(join(root, 'docs', 'ai', 'pages'), { recursive: true });
+    const before1 = 'one [AD-001](../decisions.md#ad-001--decision-001)\n';
+    const before2 = 'two [AD-001](../decisions.md#ad-001--decision-001)\n';
+    writeFileSync(join(root, 'docs/ai/pages/a.md'), before1);
+    writeFileSync(join(root, 'docs/ai/pages/b.md'), before2);
+    const planOf = (rel, before) => ({
+      rel,
+      frontmatter: '',
+      frontLines: 0,
+      beforeLines: before.split('\n'),
+      afterLines: before.replace('decisions.md#ad-001--decision-001', 'adr/AD-001-decision-001.md#ad-001--decision-001').split('\n'),
+      rewrites: [],
+    });
+    const plans = [planOf('docs/ai/pages/a.md', before1), planOf('docs/ai/pages/b.md', before2)];
+    writeFileSync(join(root, 'docs/ai/pages/b.md'), 'moved meanwhile\n');
+    assert.throws(() => writeInboundRewrites(root, plans), /stale snapshot/);
+    assert.equal(readFileSync(join(root, 'docs/ai/pages/a.md'), 'utf8'), before1, 'the earlier planned file is byte-unchanged');
+  });
+});