@event4u/agent-config 14.5.0 → 14.7.0

package/src/scripts/before_complete_hook.ts

@@ -29,7 +29,14 @@
  *   - post_tool_use → inspect tool + command, record verifications
  *   - stop                                → record stop fired (claim-done window)
  *
- * Output: `agents/state/verify-before-complete.json`
+ * Output: `agents/state/verify-before-complete/<sha256(session_id)>.json`
+ *   — ONE FILE PER SESSION. It was one file per project root until 2026-08-20,
+ *   which under this repo's worktree workflow (`CLAUDE_PROJECT_DIR` resolves to
+ *   the PARENT checkout) meant one file across every concurrent run: a
+ *   neighbour's CI witness and verification counters became this run's, and the
+ *   in-file session-boundary reset in `_update` turned into the damage rather
+ *   than the defense, because two live runs then clear each other in a loop.
+ *   Consumers address it via `statePathFor`, never a path literal.
  *   {
  *     "schema_version": 1,
  *     "session_id": "<str>",
@@ -49,14 +56,79 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { atomic_write_json } from "./hooks/state_io.js";
+import {
+  has_stable_session_id,
+  prune_legacy_state_file,
+  prune_stale_session_states,
+  session_state_file,
+  update_json_under_lock,
+} from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
 // constant is `agents/state/`. Replicated verbatim — latent docstring/code
 // divergence in the retired Python implementation (ADR-200 § replicate latent bugs).
+//
+// PRE-SPLIT PATH. Nothing reads it after the per-session split below;
+// `prune_legacy_state_file` removes it once this version owns the tree. Kept
+// exported because `prune_legacy_state_file` needs to name the path it deletes,
+// and because a reader that still resolves it should get a compile-visible
+// symbol rather than a silently stale path literal. It is NOT kept for an
+// "older bundle still writing during an upgrade" — that phrasing was copied
+// here unchecked and is corrected at `state_io.prune_legacy_state_file`, which
+// carries the measured deployment shape and the one narrow window that remains.
 export const STATE_FILE = path.join("agents", "state", "verify-before-complete.json");
 
+/**
+ * Per-SESSION state, one file each.
+ *
+ * WHY, in one sentence: the single file above is shared by every concurrent
+ * session under one project root — which in this repo's worktree workflow is
+ * the PARENT checkout — so a neighbouring run's CI witness and verification
+ * counters became this run's.
+ *
+ * The in-file session-boundary reset in `_update` is NOT the fix and is the
+ * reason this was easy to miss. It is written for SEQUENTIAL sessions: notice a
+ * foreign `session_id`, clear the session-scoped counters, carry on. Under
+ * CONCURRENT sessions that same code is the damage — each run reads the other's
+ * id, resets, and writes, so two sessions erase each other's verification
+ * evidence in a loop. The direction of the loss is toward FORGETTING a
+ * verification that did happen, which then reads as "not verified this turn".
+ *
+ * The reset stays, but NOT for the reasons this comment first gave. It said the
+ * reset "still covers the id-less bucket and a legacy file", and a cross-model
+ * review (2026-08-20, both seats) showed neither is reachable: an id-less
+ * envelope returns from `run()` before `_update` is ever called, and the legacy
+ * file is never LOADED any more — only deleted. Writing an unreachable
+ * justification next to retained code is how dead logic survives review, so the
+ * real one is stated instead.
+ *
+ * Its one reachable case is a file at THIS session's digest path carrying
+ * somebody else's `session_id` — a copy, a restore, a hand-edit, or a buggy
+ * writer. That is integrity recovery on the producer side, and it pairs with the
+ * consumer side refusing the same file outright (`owns_session_state`). Both
+ * halves are needed: the producer cannot refuse to run, and the consumer cannot
+ * repair. `before_complete_session_isolation.test.ts` reaches it directly.
+ *
+ * Rationale, the digest-not-sanitiser property, and the claim-then-revalidate
+ * prune all live once in `hooks/state_io.ts` § Per-session concern state — this
+ * is the second concern to need them, which is what made sharing them right.
+ */
+export const STATE_DIR = path.join("agents", "state", "verify-before-complete");
+
+/**
+ * Days after which an untouched session's state is pruned.
+ *
+ * Matches the language hook and the council session-artefact window — a
+ * convention match, not a measurement, and stated as such.
+ */
+export const STATE_RETENTION_DAYS = 7;
+
+/** Path of one session's state file. */
+export function statePathFor(session_id: string): string {
+  return session_state_file(STATE_DIR, session_id);
+}
+
 // Tool names across platforms whose `command` / `tool_input.command` field
 // carries a shell command we can inspect. Edit tools are deliberately
 // excluded — they cannot run verification.
@@ -125,26 +197,6 @@ function _empty_state(): StateDict {
   };
 }
 
-function _load_state(target: string): StateDict {
-  let isFile = false;
-  try {
-    isFile = fs.statSync(target).isFile();
-  } catch {
-    isFile = false;
-  }
-  if (!isFile) {
-    return _empty_state();
-  }
-  try {
-    const decoded = JSON.parse(fs.readFileSync(target, "utf-8")) as unknown;
-    if (typeof decoded === "object" && decoded !== null && !Array.isArray(decoded)) {
-      return { ..._empty_state(), ...(decoded as StateDict) };
-    }
-  } catch {
-    // fall through
-  }
-  return _empty_state();
-}
 
 /** Return [tool_name, command_text] from a tool-event payload. */
 function _extract_command(payload: StateDict): [string | null, string | null] {
@@ -424,19 +476,92 @@ export function run(
   }
 
   const event = (envelope["event"] || "") as string;
-  const target = path.join(consumer_root, STATE_FILE);
-  let state = _load_state(target);
-  state = _update(state, event, envelope);
+  const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
+
+  // No stable identity → persist NOTHING. Sanitising an empty id into a shared
+  // literal is the original cross-session defect restored in the one case with
+  // no guard left (see `state_io` § has_stable_session_id).
+  //
+  // What that costs, and it is worse than the word this comment first used: on a
+  // host that sends no `session_id` this concern records no evidence at all, so
+  // `readCiSettled` returns "nothing observed" and the turn-end gate's completion
+  // detector never fires. The first version called that "the SAFE direction —
+  // under-refusing". A cross-model review (2026-08-20, both seats) rejected the
+  // word: for a BLOCKING gate, not refusing is fail-OPEN. A premature completion
+  // claim over unsettled CI passes unchallenged. This is DEGRADED ENFORCEMENT, and
+  // naming it "safe" hides the loss behind a reassuring adjective.
+  //
+  // It is still the right call among the options available, which is a different
+  // claim and the only one the evidence supports: the alternative is one shared
+  // file whose contents belong to whichever concurrent run wrote last, i.e. a
+  // gate that refuses or clears on somebody else's evidence. A gate that goes
+  // quiet is recoverable; a gate that acts on a foreign witness is not.
+  // Every host this suite binds `post_tool_use` on sends a `session_id`
+  // (`hook_manifest.yaml` platforms × `native_event_aliases`), so the degraded
+  // path is a fallback rather than a supported mode — but it is not verified per
+  // host, and this comment does not claim it is.
+  if (!has_stable_session_id(session_id)) {
+    if (verbose) {
+      process.stderr.write(
+        "verify-before-complete-hook: no session_id — running stateless, nothing recorded\n",
+      );
+    }
+    return 0;
+  }
 
-  try {
-    atomic_write_json(target, state);
-  } catch {
+  const target = path.join(consumer_root, statePathFor(session_id));
+
+  // LOAD → UPDATE → PUBLISH under ONE lock, not three separate steps.
+  //
+  // This was `_load_state` / `_update` / `atomic_write_json`, which makes the
+  // publish atomic and leaves the transaction racy. A cross-model review
+  // (2026-08-20, both seats) named the interleaving, and this host runs tool
+  // calls in parallel, so it is reachable rather than theoretical: two
+  // `post_tool_use` invocations for the SAME session both load the counter at
+  // N, both compute N+1, both publish N+1, and one verification is lost. The
+  // per-session split does nothing about it — the two failures are independent,
+  // and closing the cross-session one made this one easier to mistake for
+  // solved.
+  //
+  // `state` is captured for the verbose line below; the value that lands is the
+  // one computed inside the lock, from state read inside the lock.
+  let state: StateDict = {};
+  // Three-state result (state_io § Three states, not two). This mutator NEVER
+  // returns null, so `skipped` is unreachable here — but it is handled with
+  // `written` rather than lumped with `failed`, because the two have opposite
+  // meanings for this caller: a decline means the state needed no change, a
+  // failure means the state on disk is not what this run computed. Writing
+  // `!== "written"` would have made a future mutator that learns to decline
+  // silently stop recording, which is the failure this API change exists to
+  // make impossible to write by accident.
+  const outcome = update_json_under_lock<StateDict>(target, (loaded) => {
+    // `_empty_state()` UNDER the loaded value, which is what the `_load_state`
+    // this replaced did (`{ ..._empty_state(), ...decoded }`). Dropping it would
+    // have been a silent regression that the suite could not see: `_asInt`
+    // treats a missing counter as 0 and the `=== true` guards treat a missing
+    // flag as false, so every assertion would still pass while `schema_version`
+    // and an explicit `ci_last: null` vanished from a freshly created file.
+    state = _update({ ..._empty_state(), ...loaded } as StateDict, event, envelope);
+    return state;
+  });
+  if (outcome === "failed") {
     if (verbose) {
       process.stderr.write("verify-before-complete-hook: state write failed\n");
     }
     return 0;
   }
 
+  // Housekeeping on the once-per-turn events only — never on `post_tool_use`,
+  // which fires many times per turn, and never before the write above.
+  if (event === "session_start" || event === "user_prompt_submit") {
+    prune_legacy_state_file(path.join(consumer_root, STATE_FILE));
+    prune_stale_session_states(
+      path.join(consumer_root, STATE_DIR),
+      Date.now(),
+      STATE_RETENTION_DAYS,
+    );
+  }
+
   if (verbose) {
     process.stderr.write(
       `verify-before-complete-hook: event=${event} ` +

package/src/scripts/bench_ab_v2_complexity.ts

@@ -35,6 +35,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { PinnedRepoError, pristine_tree_for } from './_lib/bench_ab_pinned_repo.js';
 import { medianComplexityPerChangedFunction } from './_lib/bench_ab_complexity.js';
 import { changed_files, diff_line_counts } from './_lib/bench_ab_scoring_v2.js';
 
@@ -63,15 +64,15 @@ function _dictOr(v: unknown): Dict {
  * trial to `skipped_reason: 'task id not in the corpus'`, which is a reportable
  * state, rather than aborting a re-score that may still cover most of the report.
  */
-function loadCorpusFixtures(corpusPath: string | null): Map<string, string> {
-    const byId = new Map<string, string>();
+function loadCorpusFixtures(corpusPath: string | null): Map<string, Dict> {
+    const byId = new Map<string, Dict>();
     if (!corpusPath || !fs.existsSync(corpusPath)) return byId;
     try {
         const corpus = _dictOr(parseYaml(fs.readFileSync(corpusPath, 'utf8'), { version: '1.1' }));
         const tasks = Array.isArray(corpus['tasks']) ? (corpus['tasks'] as Dict[]) : [];
         for (const t of tasks) {
-            if (t['id'] !== undefined && t['fixture'] !== undefined) {
-                byId.set(String(t['id']), String(t['fixture']));
+            if (t['id'] !== undefined && (t['fixture'] !== undefined || t['repo'] !== undefined)) {
+                byId.set(String(t['id']), t);
             }
         }
     } catch {
@@ -109,7 +110,7 @@ export async function rescoreReport(
 
     for (const rec of records) {
         const taskId = String(rec['id'] ?? '<unknown>');
-        const fixtureRel = byId.get(taskId) ?? null;
+        const corpusTask = byId.get(taskId) ?? null;
         const arms = _dictOr(rec['arms']);
         for (const [arm, runsRaw] of Object.entries(arms)) {
             const runs = Array.isArray(runsRaw) ? (runsRaw as Dict[]) : [];
@@ -134,12 +135,31 @@ export async function rescoreReport(
                     out.push(row);
                     continue;
                 }
-                if (fixtureRel === null) {
+                if (corpusTask === null) {
                     row.skipped_reason = 'task id not in the corpus';
                     out.push(row);
                     continue;
                 }
-                const fixture = path.join(fixturesRoot, fixtureRel);
+                // Delta #9: a pinned task's pristine tree is a local cache entry, and
+                // this re-scorer is `offlineOnly` on purpose — a cold cache reports
+                // "not materialised" rather than fetching a repository during what is
+                // meant to be an offline re-score of a finished sweep. A malformed pin
+                // is reported per trial, never thrown: one bad corpus entry must not
+                // abort a re-score that still covers every other trial.
+                let fixture: string | null;
+                try {
+                    fixture = pristine_tree_for(corpusTask, { fixturesRoot, offlineOnly: true });
+                } catch (err) {
+                    row.skipped_reason =
+                        err instanceof PinnedRepoError ? `invalid pin: ${err.message}` : 'invalid corpus task';
+                    out.push(row);
+                    continue;
+                }
+                if (fixture === null) {
+                    row.skipped_reason = 'pinned repo not materialised locally';
+                    out.push(row);
+                    continue;
+                }
                 if (!fs.existsSync(fixture)) {
                     row.skipped_reason = 'fixture missing on disk';
                     out.push(row);

package/src/scripts/check_adr_frontmatter.ts

@@ -51,6 +51,92 @@ export const REVIEW_TRIGGER_SINCE = '2026-07-25';
 /** Fields every ADR must carry — the shape that already exists in practice. */
 const REQUIRED = ['adr', 'status', 'date', 'decision'] as const;
 
+/**
+ * Reopen-authority vocabulary (`adr-layout.md` § Reopen authority).
+ *
+ * Both fields are OPTIONAL and stay optional. An absent `reopen_policy`
+ * resolves to `unclassified` at the reader, never to `owner`: with 146 accepted
+ * ADRs a fail-closed default would encode the existing blockage into the new
+ * schema, which is the one thing both council seats (2026-08-19) rejected in
+ * the same words. This validator therefore checks the VALUE when present and
+ * never requires the KEY.
+ */
+const ALLOWED_REOPEN_POLICY = new Set(['directional', 'owner', 'unclassified']);
+
+const ALLOWED_PROTECTED_DIMENSIONS = new Set([
+    'purpose',
+    'security_floor',
+    'privacy_floor',
+    'external_commitment',
+    'governance',
+    'none',
+]);
+
+/** Split an inline `[a, b]` list or a folded multi-value string into members. */
+export function split_dimensions(raw: string): string[] {
+    return raw
+        .replace(/^\[/, '')
+        .replace(/\]$/, '')
+        .split(/[,\s]+/)
+        .map((s) =>
+            s
+                .trim()
+                .replace(/^-\s*/, '')
+                .replace(/^["'](.*)["']$/, '$1'),
+        )
+        .filter((s) => s !== '');
+}
+
+/**
+ * Validate the two optional reopen-authority fields — value only, never
+ * presence. A wrong enum is a real error (it silently mis-routes authority);
+ * an absent field is the documented default and not a finding.
+ */
+export function check_reopen_authority(
+    rel: string,
+    fm: Record<string, string>,
+    findings: AdrFinding[],
+): void {
+    const policy = fm['reopen_policy'];
+    if (policy !== undefined && policy !== '' && !ALLOWED_REOPEN_POLICY.has(policy)) {
+        findings.push({
+            file: rel,
+            level: 'error',
+            message:
+                `\`reopen_policy\` \`${policy}\` is not one of: ` +
+                `${[...ALLOWED_REOPEN_POLICY].sort().join(', ')} (absent = unclassified)`,
+        });
+    }
+
+    const dims = fm['protected_dimensions'];
+    if (dims !== undefined && dims !== '') {
+        for (const d of split_dimensions(dims)) {
+            if (!ALLOWED_PROTECTED_DIMENSIONS.has(d)) {
+                findings.push({
+                    file: rel,
+                    level: 'error',
+                    message:
+                        `\`protected_dimensions\` member \`${d}\` is not one of: ` +
+                        `${[...ALLOWED_PROTECTED_DIMENSIONS].sort().join(', ')}`,
+                });
+            }
+        }
+    }
+
+    // `owner` without a named dimension is the frozen-over-classification shape
+    // the contract warns about: it reserves every future transition, including
+    // the ones that only strengthen the decision, and records no reason.
+    if (policy === 'owner' && (dims === undefined || dims === '')) {
+        findings.push({
+            file: rel,
+            level: 'warn',
+            message:
+                '`reopen_policy: owner` without `protected_dimensions` — name the reserved ' +
+                'interest, or the reservation cannot be checked against a proposed transition',
+        });
+    }
+}
+
 const ALLOWED_STATUS = new Set([
     'accepted',
     'proposed',
@@ -141,6 +227,98 @@ export function check_one(rel: string, text: string): AdrFinding[] {
             message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
         });
     }
+    check_reopen_authority(rel, fm, findings);
+    check_amendment_shape(rel, fm, findings);
+    return findings;
+}
+
+/** `ADR-035`, `035`, `35` → `35`. Returns null when nothing resolves. */
+export function adr_number(raw: string): string | null {
+    const m = /(\d{1,4})/.exec(raw.trim());
+    return m?.[1] === undefined ? null : String(Number(m[1]));
+}
+
+/**
+ * Validate `amends:` / `amended_by:` shape. The reciprocal half is checked in
+ * `check_amendment_links` (it needs the whole corpus); this one only rejects a
+ * value that is neither the em-dash placeholder nor an ADR reference, so a
+ * typo'd link is caught before it becomes an invisible one-sided amendment.
+ */
+export function check_amendment_shape(
+    rel: string,
+    fm: Record<string, string>,
+    findings: AdrFinding[],
+): void {
+    for (const key of ['amends', 'amended_by'] as const) {
+        const v = fm[key];
+        if (v === undefined || v === '' || v === '—') continue;
+        for (const part of v.split(',')) {
+            if (adr_number(part) === null) {
+                findings.push({
+                    file: rel,
+                    level: 'error',
+                    message: `\`${key}\` value \`${part.trim()}\` names no ADR number`,
+                });
+            }
+        }
+    }
+}
+
+/**
+ * Corpus-level check: every `amends:` has its reciprocal `amended_by:` and vice
+ * versa. This is the half the `supersedes:` / `superseded_by:` pair never had —
+ * and its absence is exactly how ADR-035 kept asserting a rejection ADR-232 had
+ * reopened. A one-sided link is invisible from the side that is stale, which is
+ * the side a reader lands on first.
+ */
+export function check_amendment_links(
+    files: { rel: string; fm: Record<string, string> }[],
+): AdrFinding[] {
+    const findings: AdrFinding[] = [];
+    const byNumber = new Map<string, { rel: string; fm: Record<string, string> }>();
+    for (const f of files) {
+        const n = f.fm['adr'] === undefined ? null : adr_number(f.fm['adr']);
+        if (n !== null) byNumber.set(n, f);
+    }
+
+    const reciprocal = { amends: 'amended_by', amended_by: 'amends' } as const;
+    for (const f of files) {
+        for (const key of ['amends', 'amended_by'] as const) {
+            const v = f.fm[key];
+            if (v === undefined || v === '' || v === '—') continue;
+            const self = f.fm['adr'] === undefined ? null : adr_number(f.fm['adr']);
+            for (const part of v.split(',')) {
+                const target = adr_number(part);
+                if (target === null) continue;
+                const other = byNumber.get(target);
+                if (other === undefined) {
+                    findings.push({
+                        file: f.rel,
+                        level: 'error',
+                        message: `\`${key}: ${part.trim()}\` points at an ADR that does not exist`,
+                    });
+                    continue;
+                }
+                const back = other.fm[reciprocal[key]] ?? '';
+                const names_self =
+                    self !== null &&
+                    back
+                        .split(',')
+                        .map((s) => adr_number(s))
+                        .includes(self);
+                if (!names_self) {
+                    findings.push({
+                        file: f.rel,
+                        level: 'error',
+                        message:
+                            `\`${key}: ${part.trim()}\` is one-sided — ${other.rel} carries no ` +
+                            `reciprocal \`${reciprocal[key]}\`. A one-sided amendment link is ` +
+                            `invisible from the stale side.`,
+                    });
+                }
+            }
+        }
+    }
     return findings;
 }
 
@@ -163,13 +341,20 @@ export function check(dir: string = ADR_DIR, ledger?: GateLedger): AdrFinding[]
     const candidates = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort();
     ledger?.plan(candidates);
 
+    // Collected for the corpus-level reciprocal-amendment check below, which
+    // cannot be decided from one file.
+    const corpus: { rel: string; fm: Record<string, string> }[] = [];
+
     for (const name of candidates) {
         if (!/^ADR-.*\.md$/.test(name)) {
             ledger?.outOfScope(name, 'not_applicable_kind');
             continue;
         }
         const rel = path.relative(REPO_ROOT, path.join(dir, name));
-        const own = check_one(rel, fs.readFileSync(path.join(dir, name), 'utf-8'));
+        const text = fs.readFileSync(path.join(dir, name), 'utf-8');
+        const parsed = parse_frontmatter(text);
+        if (parsed !== null) corpus.push({ rel, fm: parsed });
+        const own = check_one(rel, text);
         findings.push(...own);
 
         const errors = own.filter((f) => f.level === 'error').length;
@@ -179,6 +364,7 @@ export function check(dir: string = ADR_DIR, ledger?: GateLedger): AdrFinding[]
             ledger?.complete(name);
         }
     }
+    findings.push(...check_amendment_links(corpus));
     return findings;
 }
 

package/src/scripts/check_references.ts

@@ -473,6 +473,57 @@ function _extract_personas_frontmatter(text: string): Array<[number, string]> {
     return results;
 }
 
+/**
+ * Paths this checker must not call broken because nothing is allowed to fix them.
+ *
+ * `archive_completed_roadmaps` treats `agents/evidence/**` and every `*.patch` as
+ * a FROZEN RECORD and deliberately does not rewrite path strings there — a review
+ * artefact is a record of what a reviewer was shown, and editing it retroactively
+ * makes it claim something that did not happen (measured 2026-08-11: one archival
+ * rewrote four frozen artefacts including a `diff.patch` header, and reported it
+ * as "4 ref(s) migrated"). So when a roadmap is archived, a record naming its old
+ * path keeps naming it — correctly.
+ *
+ * Without this carve-out the two gates contradict each other: the sweep forbids
+ * the rewrite and this checker reds the un-rewritten path, so EVERY archival of a
+ * roadmap a review artefact mentions turns CI red with no compliant fix available.
+ * Measured on the change that made archival automatic: 2 such references.
+ *
+ * Deliberately narrow — three conditions, all required. The source is a frozen
+ * record; the reference is a top-level roadmap path; and the file is still
+ * findable under a terminal disposition. A frozen record pointing at a roadmap
+ * that exists NOWHERE is still broken and still reds, which is the part a blanket
+ * `agents/evidence/reviews` exclusion would have lost: that directory holds live
+ * `*.findings.md` work alongside archived records, so excluding it wholesale would
+ * stop checking documents that are still being acted on.
+ *
+ * The frozen-record predicate is duplicated from `_is_frozen_record` in
+ * `src/agent-src/scripts/archive_completed_roadmaps.ts` rather than imported: that
+ * module is projected into consumer installs and pulls the dashboard generator in
+ * with it, so a package-internal gate importing it would drag the projection layer
+ * into CI's gate path. `tests/scripts/check_references.test.ts` holds the two
+ * copies against one table so the duplication cannot drift silently.
+ */
+const _FROZEN_RECORD_PREFIXES = ['agents/evidence/'];
+const _TERMINAL_ROADMAP_DIRS = ['archive', 'skipped', 'later'];
+
+export function _is_frozen_record_source(rel: string): boolean {
+    const norm = rel.split(path.sep).join('/');
+    return _FROZEN_RECORD_PREFIXES.some((p) => norm.startsWith(p)) || norm.endsWith('.patch');
+}
+
+/** Does `ref` name a top-level roadmap that now lives under a terminal disposition? */
+export function _resolves_under_terminal_disposition(ref: string, root: string): boolean {
+    const norm = ref.split(path.sep).join('/');
+    const m = /^agents\/roadmaps\/([^/]+\.md)$/.exec(norm);
+    if (m === null) {
+        return false;
+    }
+    return _TERMINAL_ROADMAP_DIRS.some((d) =>
+        _exists(path.join(root, 'agents', 'roadmaps', d, m[1] as string)),
+    );
+}
+
 function _find_suggestion(p: string, root: string): string {
     const name = path.basename(p);
     // DEAD-ROOT REPAIR (road-to-renewal-foundation Phase 1): the middle entry
@@ -664,6 +715,15 @@ function check_file(
                 // check above already swallows refs into `agents/runtime/`,
                 // so no extra carve-out is needed.
             }
+            if (
+                !resolved &&
+                _is_frozen_record_source(_relPosix(root, filepath)) &&
+                _resolves_under_terminal_disposition(rawRef, root)
+            ) {
+                // A record naming the pre-archival path of a roadmap that is
+                // still findable. Nothing may rewrite it — see above.
+                resolved = true;
+            }
             if (!resolved) {
                 broken.push(
                     makeBrokenRef(

package/src/scripts/check_release_published.ts

@@ -13,8 +13,9 @@
  * matching git tag, and npm's `latest` therefore lags behind main.
  *
  * Two independent invariants:
- *   1. Tag invariant (always checkable, no network): the version in
- *      `package.json` MUST have a matching git tag (local or remote).
+ *   1. Tag invariant: the version in `package.json` MUST have a matching git
+ *      tag ON THE REMOTE. A local-only tag published nothing — `publish-npm.yml`
+ *      triggers on `push: tags:` — so the probe asks `origin` (one `ls-remote`).
  *   2. npm invariant (`--check-npm`, network): `npm view <pkg>
  *      dist-tags.latest` MUST equal the `package.json` version.
  *
@@ -51,13 +52,32 @@ function _package_name(): string {
     return String(data['name']);
 }
 
-function _tag_exists(tag: string): boolean {
-    const [rc, out] = _git('tag', '-l', tag);
-    if (rc === 0 && out.split('\n').includes(tag)) {
-        return true;
-    }
-    const [rc2] = _git('ls-remote', '--exit-code', '--tags', 'origin', tag);
-    return rc2 === 0;
+/**
+ * True when the tag is PUBLISHED — present on `origin`, never merely local.
+ *
+ * This probe used to answer local-OR-remote, and that made the gate reply
+ * "tagged, therefore published" to the exact state it exists to detect. A tag
+ * created by `release.ts` step 8 whose push then failed sits in the local
+ * repository while nothing has shipped: `publish-npm.yml` triggers on
+ * `push: tags:`, so a tag that never reached the remote published nothing.
+ * Measured 2026-08-20 on 14.6.0 — main carried `package.json` 14.6.0, the tag
+ * existed only in the maintainer's checkout, and npm still served 14.5.0.
+ *
+ * In CI the old form happened to be harmless: `actions/checkout` brings no
+ * unpushed local tag, so the remote arm decided. The hole was LOCAL — a
+ * maintainer running `task check-release-published` (or `task preflight`) on
+ * the machine that minted the tag got a green for an unpublished release, on
+ * the one machine where the stuck state is visible. The sibling defect in
+ * `release.ts::_detect_in_flight_target` is the same construct.
+ *
+ * @param git Seam for the probe. Production passes nothing and gets the real
+ * `_git`; tests inject a stub, because the alternative — reaching the branches
+ * only by creating and deleting tags in the checkout — is why neither arm of
+ * this function had a test while both were wrong.
+ */
+function _tag_exists(tag: string, git: (...args: string[]) => [number, string] = _git): boolean {
+    const [rc] = git('ls-remote', '--exit-code', '--tags', 'origin', tag);
+    return rc === 0;
 }
 
 function _on_main(): boolean {
@@ -179,8 +199,9 @@ function main(argv: readonly string[] = [], hooks: Hooks = _hooks): number {
     if (!hooks._tag_exists(version)) {
         problems.push(
             `package.json is ${version} but no git tag ${version} exists ` +
-                `(local or origin) — the release was bumped/merged but never ` +
-                `tagged. Complete it: tag the release-merge commit and push ` +
+                `on origin — the release was bumped/merged but never tagged, ` +
+                `or the tag push never landed. Complete it: tag the ` +
+                `release-merge commit and push ` +
                 `(triggers publish-npm.yml), e.g. \`git tag ${version} && git ` +
                 `push origin ${version}\`.`,
         );