heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/validate-linkage.mjs

@@ -10,8 +10,26 @@
  *   3. missing_manifest_refs — roadmap manifest entry pointing to a missing file
  *      (basename/unique-id match only — family idCore soft-match is intentionally
  *      NOT enough, so stale Naming V3 era-1/2 listings cannot greenlight).
+ *      Every other ref resolves file-key-first (see buildSpecIndex /
+ *      resolveSpecRef below, shared with register-spec.mjs): the family+TYPE
+ *      core is a soft match for key-less legacy refs only, and only when unique.
  *   4. parent_child_mismatches — one side of a parent/child link not pointing back.
  *
+ * Plus one INFORMATIONAL (non-defect) bucket:
+ *
+ *   5. frozen_parent_child_mismatches — a parent/child mismatch where at least
+ *      one side is `status: closed` / `status: superseded`. Per
+ *      [[closed-trackable-specs-are-historical-record-not-living-docs]] and
+ *      [[spec-hierarchy]] §"Closed specs are historical record — frozen +
+ *      immutable", a closed/superseded spec's frontmatter is frozen: only the
+ *      close-out change-log row, `status:`, `close_reason:` and `superseded_by:`
+ *      may still be touched. A `children:` / `epics:` roster is NOT on that
+ *      list, so roster bookkeeping on a frozen spec is a FORBIDDEN edit and the
+ *      mismatch is unfixable by protocol — a validator false positive, not vault
+ *      debt. These are reported separately so a reader can see they exist and
+ *      why they are excluded, and they do NOT affect the top-level `valid`
+ *      verdict.
+ *
  * Reachability is expressed in the manifest-v3 hierarchy
  * ([[HS-TASK-JN9H-manifest-schema-v3-and-horizon-retirement]]):
  *   roadmap → milestones (roadmap_manifest.milestones)
@@ -31,13 +49,33 @@
  */
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
+import {
+  toCanonicalFamilyFirstId,
+  parseSpecId,
+  fileKeyFromBasename,
+  lookupFileKeyOf,
+  bareFileKeyOf,
+} from './spec-id-lib.mjs';
 
 // Entity kinds that must be reachable from the roadmap. Everything else
 // (research, protocol, memory-*, capture, diagnose, agent, review, adr, …) is
 // exempt — those are referenced by wikilink, not parented into the manifest.
 const SUBJECT_TYPES = new Set(['milestone', 'epic', 'task']);
 
+// Statuses that freeze a spec's frontmatter as historical record. Roster
+// bookkeeping (`children:` / `epics:`) on one of these is a forbidden edit per
+// [[closed-trackable-specs-are-historical-record-not-living-docs]] — the roster
+// is accurate to what was true at close, and "fixing" it corrupts the record.
+const FROZEN_STATUSES = new Set(['closed', 'superseded']);
+
+// A spec is frozen when its `status:` is closed/superseded. Records built by an
+// older caller (or a test fixture) may carry no `status` at all — absent status
+// is never frozen, so the defect path stays the default.
+function isFrozenSpec(spec) {
+  const status = spec && typeof spec.status === 'string' ? spec.status.trim().toLowerCase() : '';
+  return FROZEN_STATUSES.has(status);
+}
+
 // ---------------------------------------------------------------------------
 // Frontmatter extraction (regex-over-raw — byte-tolerant, no YAML dependency)
 // ---------------------------------------------------------------------------
@@ -73,6 +111,47 @@ function listItems(block, field) {
   return out;
 }
 
+// `field:` may be written as an inline YAML flow list — `aliases: [foo, bar]`
+// — rather than the block-list form `listItems()` handles. Splits on commas;
+// each item is unquoted/trimmed. Returns null when the field is absent or not
+// a flow list (caller falls back to listItems()).
+function flowListItems(block, field) {
+  // Quote-aware: an item may contain `,` or `]` inside quotes (e.g.
+  // `"/report/[token]"`, `"[[basename]] links"`), so the closing `]` is the one
+  // that ends the line, not the first one seen.
+  const m = block.match(new RegExp(`^[ \\t]*${field}:[ \\t]*\\[(.*)\\][ \\t]*$`, 'm'));
+  if (!m) return null;
+  const inner = m[1].trim();
+  if (!inner) return [];
+  const items = [];
+  let cur = '';
+  let quote = null;
+  for (const ch of inner) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === ',') {
+      items.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  items.push(cur);
+  return items.map((x) => x.trim()).filter(Boolean);
+}
+
+// `aliases:` — HS-WEGK-OQGQ: a wikilink target matching any of a spec's
+// declared aliases must resolve, honoring both the inline flow-list form
+// (`aliases: [foo, bar]`) and the block-list form.
+function aliasesField(block) {
+  const flow = flowListItems(block, 'aliases');
+  if (flow !== null) return flow;
+  return listItems(block, 'aliases');
+}
+
 // `[[Foo|alias]]` / `[[Foo#anchor]]` / `Foo` → `Foo`. Returns null for empties.
 function stripWikilink(value) {
   if (typeof value !== 'string') return null;
@@ -97,6 +176,237 @@ function idCore(value) {
   return m ? m[1].toUpperCase() : null;
 }
 
+// ---------------------------------------------------------------------------
+// Naming V3 identity ([[HS-J6IE-K2EL-DIAG-heyspex-register-spec-resolves-a-task]])
+//
+// Under Naming V3 (`HS-<fileKey>-<familyKey>-<TYPE>-<slug>`) the UNIQUE key of a
+// spec is its FILE key — the token right after `HS-`. The family key is a
+// surname shared by a whole milestone's descendants, so `idCore` (family+TYPE)
+// is NOT an identity: two tasks in one family (HS-OCL4-NYPR-TASK-… and
+// HS-0HOF-NYPR-TASK-…) collapse to the same idCore. A first-wins idCore map
+// therefore resolved one to the other and `heyspex_register_spec` re-parented
+// an unrelated spec. The helpers below are the ONE resolution rule both this
+// module and register-spec.mjs use:
+//
+//   basename (exact) → id (exact) → file key (unique) → [aliases, opt-in]
+//   → idCore soft match ONLY for a ref that carries no file key, and ONLY when
+//     exactly one spec matches; two or more → AMBIGUOUS (candidates named).
+//   A bare family token (`HS-NYPR`) that matches no file key but names a
+//   family is AMBIGUOUS too, never a silent pick.
+// ---------------------------------------------------------------------------
+
+// File key carried by a ref in any accepted form: bare `HS-OCL4`, display
+// `HS-OCL4-NYPR`, full era-3 id/basename, a `[[wikilink]]` already stripped by
+// the caller, or an era-1/2 basename whose slug leads with the key.
+function refFileKey(ref) {
+  if (typeof ref !== 'string' || !ref.trim()) return null;
+  // Pasted/typed refs may arrive as `hs-ocl4`; the stored shape is `HS-`.
+  const t = ref.trim().replace(/^hs-/i, 'HS-');
+  return lookupFileKeyOf(t) ?? fileKeyFromBasename(t) ?? null;
+}
+
+// The file key a spec record is STORED under: basename first (the era-3
+// filename always leads with it), then the stored `id:` — but only in its
+// stored shapes (bare `HS-OCL4` or a full era-3 id). The two-token DISPLAY form
+// lookupFileKeyOf accepts for pasted refs is never a stored id, and reading it
+// here would misfile e.g. `HS-RECIPE-feature` under file key "RECIPE".
+function storedFileKey(basename, id) {
+  const fromBasename = refFileKey(basename);
+  if (fromBasename) return fromBasename;
+  if (typeof id !== 'string' || !id.trim()) return null;
+  const bare = bareFileKeyOf(id);
+  if (bare) return bare;
+  const p = parseSpecId(id);
+  if (p?.era === 3 && p.fileKey) return p.fileKey;
+  return fileKeyFromBasename(id) ?? null;
+}
+
+export function specFileKey(spec) {
+  if (!spec) return null;
+  if (spec.fileKey !== undefined) return spec.fileKey;
+  return storedFileKey(spec.basename, spec.id);
+}
+
+// Family key of a spec record: explicit frontmatter `family:` when the walker
+// captured it, else the positional family parsed from basename/id.
+function specFamilyKey(spec) {
+  if (!spec) return null;
+  if (typeof spec.family === 'string' && spec.family.trim()) return spec.family.trim().toUpperCase();
+  const p = parseSpecId(spec.basename) ?? parseSpecId(spec.id);
+  return p?.familyKey ?? null;
+}
+
+const pushMulti = (map, key, value) => {
+  if (!key) return;
+  const arr = map.get(key);
+  if (arr) arr.push(value);
+  else map.set(key, [value]);
+};
+
+/**
+ * Build the lookup index every resolver below reads. Collisions are KEPT (each
+ * multimap holds every spec for a key) so a lookup can refuse ambiguity instead
+ * of taking the first file the directory walk happened to yield.
+ */
+export function buildSpecIndex(specs) {
+  const byBasename = new Map();
+  const byId = new Map(); // id → spec[]
+  const byFileKey = new Map(); // fileKey → spec[]
+  const byIdCore = new Map(); // family+TYPE core → spec[]
+  const byFamily = new Map(); // familyKey → spec[]
+  const byAlias = new Map();
+  for (const s of specs) {
+    byBasename.set(s.basename, s);
+    if (s.id) pushMulti(byId, s.id, s);
+    pushMulti(byFileKey, specFileKey(s), s);
+    const core = s.idCore ?? idCore(s.id) ?? idCore(s.basename);
+    pushMulti(byIdCore, core, s);
+    pushMulti(byFamily, specFamilyKey(s), s);
+    for (const a of s.aliases || []) {
+      if (a && !byAlias.has(a)) byAlias.set(a, s);
+    }
+  }
+  // A review companion (`type: review` — `<subject>.review.md` beside an epic,
+  // or `HS-<key>-<family>-REV-…` under specs/reviews) carries its SUBJECT's
+  // file key by convention. That is a pairing, not an identity collision, so
+  // the subject keeps sole claim to the key; two non-review files on one key
+  // stay a real (refused) collision.
+  const preferSubjects = (map) => {
+    for (const [key, arr] of map) {
+      if (arr.length < 2) continue;
+      const subjects = arr.filter((s) => s.type !== 'review');
+      if (subjects.length >= 1 && subjects.length < arr.length) map.set(key, subjects);
+    }
+  };
+  preferSubjects(byFileKey);
+  preferSubjects(byIdCore);
+  preferSubjects(byFamily);
+  return { byBasename, byId, byFileKey, byIdCore, byFamily, byAlias };
+}
+
+// Title slug of an id/basename in any era, or '' (used only to break an
+// idCore tie between a slugged legacy ref and the one sibling that kept its slug).
+function titleSlugOf(value) {
+  const p = parseSpecId(value);
+  return p?.titleSlug ? p.titleSlug.toLowerCase() : '';
+}
+
+const candidateList = (specs) =>
+  specs.map((s) => ({ id: s.id, basename: s.basename, file: s.file ?? null }));
+
+/**
+ * Resolve one reference against the index.
+ *
+ * @returns {{ spec: object|null, ambiguous: boolean, candidates: object[], matched_by: string|null }}
+ *   `spec` is set on a unique hit; `ambiguous: true` + `candidates` when the
+ *   ref names more than one spec; both empty when nothing matched.
+ */
+export function resolveSpecRef(index, ref, { aliases = false, pathFallback = false } = {}) {
+  const none = { spec: null, ambiguous: false, candidates: [], matched_by: null };
+  if (!ref) return none;
+  const raw = stripWikilink(ref) ?? String(ref);
+  const t = raw.replace(/\.md$/i, '').trim();
+  if (!t) return none;
+
+  const unique = (arr, how) =>
+    arr && arr.length === 1
+      ? { spec: arr[0], ambiguous: false, candidates: [], matched_by: how }
+      : arr && arr.length > 1
+        ? { spec: null, ambiguous: true, candidates: candidateList(arr), matched_by: how }
+        : null;
+
+  const exact = index.byBasename.get(t);
+  if (exact) return { spec: exact, ambiguous: false, candidates: [], matched_by: 'basename' };
+
+  const byId = unique(index.byId.get(t), 'id');
+  if (byId) return byId;
+
+  const fileKey = refFileKey(t);
+  if (fileKey) {
+    const hit = unique(index.byFileKey.get(fileKey), 'file_key');
+    if (hit) return hit;
+  }
+
+  if (aliases) {
+    const alias = index.byAlias.get(t);
+    if (alias) return { spec: alias, ambiguous: false, candidates: [], matched_by: 'alias' };
+  }
+
+  // A ref that CARRIES a file key named exactly one spec or nothing — never a
+  // sibling. Only a key-less (era-1/2) ref may fall through to the soft match.
+  if (!fileKey) {
+    const coreHits = index.byIdCore.get(idCore(t));
+    if (coreHits && coreHits.length > 1) {
+      // Pre-rename slugged link (`HS-Q1HZ-TASK-hs-vault-cli-…`) vs the era-3
+      // sibling that kept that exact slug (`HS-GLPP-Q1HZ-TASK-hs-vault-cli-…`):
+      // family + TYPE + identical slug is one file, not a family. Slug-less or
+      // differently-slugged refs stay ambiguous.
+      const slug = titleSlugOf(t);
+      const sameSlug = slug ? coreHits.filter((s) => titleSlugOf(s.basename) === slug) : [];
+      if (sameSlug.length === 1) {
+        return { spec: sameSlug[0], ambiguous: false, candidates: [], matched_by: 'id_core_slug' };
+      }
+    }
+    const hit = unique(coreHits, 'id_core');
+    if (hit) return hit;
+  }
+
+  // Bare token (`HS-XXXX`): bareFileKeyOf is shape-only, so a FAMILY key reads
+  // as a file key too. No file-key hit above → if it names a family, refuse.
+  const bare = bareFileKeyOf(t);
+  if (bare) {
+    const fam = index.byFamily.get(bare);
+    if (fam && fam.length) {
+      return { spec: null, ambiguous: true, candidates: candidateList(fam), matched_by: 'family' };
+    }
+  }
+
+  if (pathFallback && t.includes('/')) {
+    const base = t.split('/').pop();
+    const b = index.byBasename.get(base);
+    if (b) return { spec: b, ambiguous: false, candidates: [], matched_by: 'basename' };
+    const i = unique(index.byId.get(base), 'id');
+    if (i) return i;
+    if (aliases) {
+      const a = index.byAlias.get(base);
+      if (a) return { spec: a, ambiguous: false, candidates: [], matched_by: 'alias' };
+    }
+  }
+  return none;
+}
+
+/**
+ * Does `ref` (a list entry / pointer field) name exactly `spec`? Exact
+ * basename or id, or the same file key. The family+TYPE idCore is accepted
+ * ONLY when neither side carries a file key (two legacy era-1/2 strings) —
+ * once a file key exists on either side it is the identity, and a stale
+ * family-core string must not be mistaken for a reference to this spec.
+ */
+export function refNamesSpec(ref, spec) {
+  if (!ref || !spec) return false;
+  const t = (stripWikilink(ref) ?? String(ref)).replace(/\.md$/i, '').trim();
+  if (!t) return false;
+  if (t === spec.basename || t === spec.id) return true;
+  const refKey = refFileKey(t);
+  const specKey = specFileKey(spec);
+  if (refKey || specKey) return !!refKey && refKey === specKey;
+  const core = spec.idCore ?? idCore(spec.id) ?? idCore(spec.basename);
+  return !!core && idCore(t) === core;
+}
+
+/** Text-level twin of {@link refNamesSpec} for two bare ref strings. */
+export function refsNameSameSpec(a, b) {
+  const ta = (stripWikilink(a) ?? String(a ?? '')).replace(/\.md$/i, '').trim();
+  const tb = (stripWikilink(b) ?? String(b ?? '')).replace(/\.md$/i, '').trim();
+  if (!ta || !tb) return false;
+  if (ta === tb) return true;
+  const ka = refFileKey(ta);
+  const kb = refFileKey(tb);
+  if (ka || kb) return !!ka && ka === kb;
+  const ca = idCore(ta);
+  return !!ca && ca === idCore(tb);
+}
+
 // Every "real" `[[wikilink]]` in the file, with 1-based line numbers for
 // actionable reporting. Links inside fenced code blocks (``` / ~~~) and inline
 // code spans (`...`) are skipped — specs routinely show `[[example]]` syntax as
@@ -182,6 +492,33 @@ function extractLineageTableLinks(raw) {
  * Read every `.md` under `<vaultRoot>/specs/` into a normalized record the
  * analyzer consumes. Exported so the analyzer can be unit-tested with synthetic
  * records (no disk) while the real path walks the vault.
+ *
+ * ## Why this one stays a whole-vault walk
+ *
+ * Judged by [[HS-FDVS-8KK5-TASK-route-sweep-every-api-route-reads]] under
+ * [[HS-49AL-8KK5-EPIC-hot-row-cache-and-bounded-agent-tools]], and kept.
+ * Every answer this module produces is a property of the ENTIRE graph, not of
+ * any page of it:
+ *
+ *   - `orphan_specs` — "not reachable from the roadmap" is only knowable once
+ *     every edge has been seen. A page cannot tell an orphan from a spec whose
+ *     parent lives on the next page.
+ *   - `broken_wikilinks` — a link resolves against the set of all filenames.
+ *   - `parent_child_mismatches` — needs both ends of every link at once.
+ *
+ * Paging the input would not make the analysis cheaper, only wrong. Note also
+ * what this is NOT: it is not a console request path. It runs from the
+ * `heyspex_validate_linkage` MCP tool and the pre-commit `validate` CLI verb —
+ * both explicitly whole-vault operations a human or agent asked for, and both
+ * outside the "no request path does work proportional to vault size" rule the
+ * epic enforces. Its RESPONSE size is bounded separately by
+ * [[HS-4H8T-8KK5-TASK-every-mcp-read-tool-declares-a-byte]].
+ *
+ * The walk itself retires when linkage validity is maintained incrementally
+ * from the outbox instead of recomputed by re-reading the vault
+ * ([[HS-D26S-8KK5-EPIC-incremental-indexing-from-the-outbox]]); no task under
+ * it covers this module yet, so that is the follow-up to file, not a fix to
+ * make here.
  */
 export function collectVaultSpecs(vaultRoot) {
   const specsDir = join(vaultRoot, 'specs');
@@ -202,11 +539,30 @@ export function collectVaultSpecs(vaultRoot) {
     specs.push({
       id,
       type,
+      // `status:` drives the frozen-spec carve-out for parent/child mismatches
+      // (see FROZEN_STATUSES). Read as a plain scalar — absent means not frozen.
+      status: scalarField(block, 'status'),
       basename,
       idCore: idCore(id) || idCore(basename),
+      // Naming V3 identity: the file key is the UNIQUE key (see specFileKey);
+      // `family:` is the shared surname, kept only so a bare family token can
+      // be refused as ambiguous rather than silently matched.
+      fileKey: storedFileKey(basename, id),
+      family: scalarField(block, 'family'),
       file: relative(vaultRoot, abs).split('\\').join('/'),
-      parent: stripWikilink(scalarField(block, 'parent')),
-      milestone: stripWikilink(scalarField(block, 'milestone')),
+      aliases: aliasesField(block),
+      parent: stripWikilink(scalarField(block, 'parent')) || (() => {
+        // HS-OZFL-OPVL: `parent:` written as a one-item YAML block list rather
+        // than the canonical scalar form must still be read, or the spec is
+        // falsely flagged as an orphan.
+        const items = listItems(block, 'parent').map(stripWikilink).filter(Boolean);
+        return items[0] ?? null;
+      })(),
+      milestone: stripWikilink(scalarField(block, 'milestone')) || (() => {
+        // HS-OZFL-OPVL: same list-form fallback as `parent:` above, for epics.
+        const items = listItems(block, 'milestone').map(stripWikilink).filter(Boolean);
+        return items[0] ?? null;
+      })(),
       children: listItems(block, 'children').map(stripWikilink).filter(Boolean),
       epics: listItems(block, 'epics').map(stripWikilink).filter(Boolean),
       related: listItems(block, 'related').map(stripWikilink).filter(Boolean),
@@ -243,20 +599,19 @@ export function collectVaultSpecs(vaultRoot) {
  *        `--staged-only`). null = whole vault.
  */
 export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null } = {}) {
-  const byBasename = new Map();
-  const byId = new Map();
-  const byIdCore = new Map();
-  for (const s of specs) {
-    byBasename.set(s.basename, s);
-    if (s.id) byId.set(s.id, s);
-    if (s.idCore && !byIdCore.has(s.idCore)) byIdCore.set(s.idCore, s);
-  }
-
-  const resolveRef = (ref) => {
-    if (!ref) return null;
-    const t = stripWikilink(ref) ?? ref;
-    return byBasename.get(t) || byId.get(t) || byIdCore.get(idCore(t)) || null;
-  };
+  // One shared index + resolver with register-spec.mjs (HS-J6IE): basename →
+  // id → unique file key → alias → idCore soft match (key-less refs only, and
+  // only when unique). An AMBIGUOUS ref (names two specs in one family) is
+  // treated as NOT resolving here — it cannot be a valid edge to one spec, and
+  // it must never be satisfied by whichever sibling the walk met first.
+  //
+  // HS-WEGK-OQGQ: `.md` is stripped and a folder-prefixed link
+  // (`[[protocols/testing-strategy]]`) falls back to its last path segment so
+  // it resolves folder-agnostically (spex-console/src/lib/vault-shared.ts).
+  const index = buildSpecIndex(specs);
+  const byBasename = index.byBasename;
+  const byId = index.byId;
+  const resolveRef = (ref) => resolveSpecRef(index, ref, { aliases: true, pathFallback: true }).spec;
   // Manifest entries must name an on-disk basename (or unique bare id). Family
   // idCore alone is NOT enough — after Naming V3, an era-1/2 `HS-<family>-MIL-…`
   // string shares idCore with the era-3 file but does not match the console's
@@ -264,13 +619,11 @@ export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null
   const resolveManifestRef = (ref) => {
     if (!ref) return null;
     const t = stripWikilink(ref) ?? ref;
-    return byBasename.get(t) || byId.get(t) || null;
+    const ids = byId.get(t);
+    return byBasename.get(t) || (ids && ids.length === 1 ? ids[0] : null) || null;
   };
   const refResolves = (ref) => resolveRef(ref) != null;
-  const refMatchesSpec = (ref, spec) => {
-    const t = stripWikilink(ref) ?? ref;
-    return t === spec.basename || t === spec.id || (!!spec.idCore && idCore(t) === spec.idCore);
-  };
+  const refMatchesSpec = (ref, spec) => refNamesSpec(ref, spec);
   const listContainsSpec = (list, spec) => list.some((ref) => refMatchesSpec(ref, spec));
 
   // Manifest reachability index — union of every roadmap's milestone entries.
@@ -285,11 +638,13 @@ export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null
   }
   const milestoneInManifest = (spec) =>
     manifestMilestoneRefs.has(spec.basename) || manifestMilestoneRefs.has(spec.id);
-  const inScope = (spec) =>
-    !scopeIds ||
-    scopeIds.has(spec.id) ||
-    scopeIds.has(spec.basename) ||
-    (!!spec.idCore && scopeIds.has(spec.idCore));
+  const inScope = (spec) => {
+    if (!scopeIds) return true;
+    if (scopeIds.has(spec.id) || scopeIds.has(spec.basename)) return true;
+    const key = specFileKey(spec);
+    if (key && (scopeIds.has(`HS-${key}`) || scopeIds.has(key))) return true;
+    return !!spec.idCore && scopeIds.has(spec.idCore);
+  };
 
   // Amends reverse map ([[AMENDS-CONTRACT]] / HS-6DMR-EPIC) — the partial,
   // non-terminal supersession tier. `amends:` lives only on the amending (newer)
@@ -343,14 +698,40 @@ export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null
   const broken_wikilinks = [];
   const missing_manifest_refs = [];
   const parent_child_mismatches = [];
+  // Informational, NOT a defect — see FROZEN_STATUSES and the module header.
+  const frozen_parent_child_mismatches = [];
   const warnings = [];
   const seenMismatch = new Set();
 
+  const FROZEN_NOTE =
+    'Frozen by protocol — at least one side is closed/superseded, whose roster (`children:`/`epics:`) ' +
+    'is historical record accurate to what was true at close. Editing it is a forbidden edit ' +
+    '([[closed-trackable-specs-are-historical-record-not-living-docs]]), so this mismatch is ' +
+    'intentionally unfixable and is excluded from the `valid` verdict. Take no action.';
+
   const pushMismatch = (parent, child, issue, parentSpec, childSpec) => {
     const key = `${parent}|${child}|${issue}`;
     if (seenMismatch.has(key)) return;
     seenMismatch.add(key);
     if (!inScope(parentSpec) && !inScope(childSpec)) return;
+    // Either side frozen → informational bucket, never a defect. Note the
+    // unresolvable-ref call sites pass the parent spec for BOTH arguments; a
+    // frozen parent there is still correct (repairing it would mean editing the
+    // frozen roster), so the same either-side test covers that case.
+    const parentFrozen = isFrozenSpec(parentSpec);
+    const childFrozen = isFrozenSpec(childSpec);
+    if (parentFrozen || childFrozen) {
+      frozen_parent_child_mismatches.push({
+        parent,
+        child,
+        issue,
+        frozen_side: parentFrozen && childFrozen ? 'both' : parentFrozen ? 'parent' : 'child',
+        parent_status: parentSpec?.status ?? null,
+        child_status: childSpec?.status ?? null,
+        note: FROZEN_NOTE,
+      });
+      return;
+    }
     parent_child_mismatches.push({ parent, child, issue });
   };
 
@@ -525,6 +906,8 @@ export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null
     }
   }
 
+  // NOTE: frozen_parent_child_mismatches is intentionally absent here — a
+  // frozen-by-protocol mismatch is not vault debt and must never fail the gate.
   const valid =
     orphan_specs.length === 0 &&
     broken_wikilinks.length === 0 &&
@@ -539,6 +922,8 @@ export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null
     broken_wikilinks,
     missing_manifest_refs,
     parent_child_mismatches,
+    // Informational only — deliberately excluded from `valid` above.
+    frozen_parent_child_mismatches,
     broken_amends,
     amended_by,
     broken_iterates_on,
@@ -550,6 +935,8 @@ export function analyzeLinkage(specs, { includeWarnings = true, scopeIds = null
       broken_links: broken_wikilinks.length,
       missing_refs: missing_manifest_refs.length,
       mismatches: parent_child_mismatches.length,
+      // Informational count — frozen-by-protocol mismatches excluded from `mismatches`.
+      frozen_mismatches: frozen_parent_child_mismatches.length,
       broken_amends: broken_amends.length,
       broken_iterates_on: broken_iterates_on.length,
     },