@event4u/agent-config 14.6.0 → 14.7.0

package/src/scripts/_lib/self_repair_class_b.ts

@@ -0,0 +1,171 @@
+/**
+ * The Class-B path (road-to-org-telemetry Phase 5, step 5.2).
+ *
+ * Class A is the automatic half: structural fields, no content, shipped under
+ * recorded org consent. Class B is an abstracted CASE — what was expected
+ * versus what happened, and which artefacts were involved — and it ships only
+ * on explicit per-case approval of the exact text that would leave.
+ *
+ * THE GATE IS THE HUMAN READING THE OUTBOUND TEXT, NOT A FILTER. Rank 1 of the
+ * roadmap risk register is "an abstraction miss ships a path or an identifier
+ * out of a consumer project", and its stated mitigation is per-case review of
+ * the exact outbound text rather than a filter heuristic. So this module's job
+ * is to make the exact bytes visible and then refuse to release them unless the
+ * approval names those same bytes. `approve` takes a digest of the rendered
+ * text; a text that changed after the human read it no longer matches, and the
+ * release refuses rather than shipping something nobody approved.
+ *
+ * SILENT SHIPPING IS PERMANENTLY OUT OF SCOPE, and the step says so in those
+ * words. There is deliberately no "auto-approve", no allow-list of
+ * self-evidently safe classes, and no timeout that approves by default.
+ *
+ * TWO EXISTING PRIMITIVES ARE REUSED RATHER THAN RE-INVENTED:
+ *  - `renderReport` is "the existing symptom format" the step names.
+ *  - `egressBlockedReason` is the audited privacy floor — the same one the
+ *    local corpus write and the upstream release already pass through. It
+ *    REFUSES rather than rewriting, which is the property that makes it a gate;
+ *    a module that silently scrubbed and shipped would be a soft gate wearing
+ *    a hard gate's name.
+ *
+ * WHAT THIS MODULE DOES NOT DO: send anything. Transport and sink-side storage
+ * are Phase 5 step 5.3, transferred with `sink-choice` — no sink exists for an
+ * approved case to travel to. `ClassBRecord` is therefore built, gated and
+ * held; the field that carries the text is `case_text` and it is a typed
+ * member of a typed record, never a string interpolated into a prompt.
+ */
+import * as crypto from 'node:crypto';
+
+import {
+    type DefectRecord,
+    egressBlockedReason,
+    renderReport,
+} from './self_repair.js';
+
+/** Schema version for the Class-B envelope, independent of Class A. */
+export const CLASS_B_SCHEMA_VERSION = 1;
+
+/**
+ * One approved case.
+ *
+ * `case_text` is the ONLY free-form member and it exists on purpose: Class B
+ * is defined as an abstracted case, so a Class-B record without text would be
+ * a Class-A record. The controls are that it is (a) a named, typed field
+ * rather than an open `payload`, (b) present only after `approve` matched a
+ * digest a human read, and (c) documented as data end to end — see
+ * `assertNeverInterpolated`.
+ */
+export interface ClassBRecord {
+    schema_version: number;
+    record_class: 'case';
+    /** Detector / intake class, from the pinned vocabulary. */
+    defect_class: string;
+    /** Fingerprint of the local record this case abstracts. */
+    fingerprint: string;
+    /** SHA-256 of `case_text`, so a consumer can verify what was approved. */
+    case_digest: string;
+    /** The abstracted case, exactly as the human approved it. */
+    case_text: string;
+}
+
+export type ClassBRefusal =
+    | { ok: false; reason: string; kind: 'privacy-floor' | 'digest-mismatch' | 'empty' };
+
+export type ClassBResult = { ok: true; record: ClassBRecord } | ClassBRefusal;
+
+/** SHA-256 hex of the exact bytes a human is asked to approve. */
+export function caseDigest(text: string): string {
+    return crypto.createHash('sha256').update(text, 'utf-8').digest('hex');
+}
+
+/**
+ * Render the exact outbound text for one record, or refuse.
+ *
+ * Refusal comes from the audited privacy floor and is returned as a reason
+ * string for the caller to show. It is NOT downgraded to a scrub-and-continue:
+ * a record whose evidence trips the floor stays local, which is the same
+ * verdict the upstream release path already reaches.
+ */
+export function renderCase(
+    record: DefectRecord,
+    repoRoot?: string | null,
+): { ok: true; text: string; digest: string } | ClassBRefusal {
+    const blocked = egressBlockedReason(record, repoRoot ?? null);
+    if (blocked !== null) {
+        return { ok: false, reason: blocked, kind: 'privacy-floor' };
+    }
+    // `issue` is the route whose rendering carries no patch and no repository
+    // path — the narrowest of the existing shapes, and the right one for a
+    // case that travels to a telemetry sink rather than to a code host.
+    const text = renderReport(record, 'issue');
+    if (text.trim() === '') {
+        return { ok: false, reason: 'nothing to send', kind: 'empty' };
+    }
+    return { ok: true, text, digest: caseDigest(text) };
+}
+
+/**
+ * Approve one rendered case for release.
+ *
+ * `approved_digest` is what the human saw. If the text has changed since —
+ * a new occurrence folded in, a re-render, anything — the digests differ and
+ * this refuses. That is the difference between approving a case and approving
+ * a category.
+ */
+export function approve(
+    record: DefectRecord,
+    text: string,
+    approved_digest: string,
+): ClassBResult {
+    const actual = caseDigest(text);
+    if (actual !== approved_digest) {
+        return {
+            ok: false,
+            kind: 'digest-mismatch',
+            reason:
+                'the approved text is not the text that would be sent — '
+                + 're-render, read it again, and approve the new digest',
+        };
+    }
+    return {
+        ok: true,
+        record: {
+            schema_version: CLASS_B_SCHEMA_VERSION,
+            record_class: 'case',
+            defect_class: record.defect_class,
+            fingerprint: record.fingerprint,
+            case_digest: actual,
+            case_text: text,
+        },
+    };
+}
+
+/**
+ * Serialise an approved case as ONE JSON object.
+ *
+ * This is the whole of "quoted, typed data" (step 5.3's repository-side half):
+ * the text is a JSON string value, so a downstream reader parses it into a
+ * field. Nothing here concatenates it into a sentence, a prompt, or a shell
+ * argument, and rank 2 of the risk register — a crafted complaint steering a
+ * generated change — is what that discipline is for.
+ */
+export function serialiseCase(record: ClassBRecord): string {
+    return JSON.stringify(record);
+}
+
+/**
+ * Guard for a downstream consumer: refuse a prompt-shaped use of case text.
+ *
+ * Deliberately a narrow, honest tool. It cannot stop a caller that never asks;
+ * what it does is give the generation step in Phase 6 something to call, so
+ * "reads taxonomy fields only, never Class-B free text" is a check rather than
+ * a convention. The intended use is at the boundary where a record becomes
+ * model input.
+ */
+export function assertNeverInterpolated(candidate: string, record: ClassBRecord): void {
+    if (record.case_text !== '' && candidate.includes(record.case_text)) {
+        throw new Error(
+            'Class-B case text must reach a model as quoted data, never as part '
+            + 'of an instruction string — pass the record, not a concatenation',
+        );
+    }
+}

package/src/scripts/ai_council/cli_help.ts

@@ -0,0 +1,55 @@
+/**
+ * Sub-help rendering for the council CLI.
+ *
+ * Lives here rather than in `council_cli.ts` for a measured reason: that file
+ * sits ~2,500 lines above the 1,500-line source ceiling, and
+ * `check_source_size_budget` is a shrink-only ratchet — every line added there
+ * is a new violation, so a 45-line help renderer reds the build. Extraction is
+ * the documented response; raising the baseline is not.
+ *
+ * WHAT IT FIXES. `council run --help` printed `usage: agent-config council run
+ * [-h] ...` and no flag list at all. Measured 2026-08-20: a first council run
+ * cost six calls, two of them spent discovering `--confirm` and `--output` by
+ * grepping the CLI source. The information was available at runtime all along —
+ * the parser's own spec table carries it — it simply was not printed.
+ *
+ * Rendered from those specs rather than hand-listed on purpose: a hand-written
+ * flag list is a second source of truth that drifts the first time a flag is
+ * added.
+ */
+
+/** The shape `council_cli`'s spec table exposes, narrowed to what help needs. */
+export interface HelpSpec {
+    readonly positionals: readonly string[];
+    readonly opts: readonly { readonly flag: string; readonly takesValue: boolean; readonly choices?: readonly string[] | null }[];
+    readonly requiredOpts: readonly string[];
+}
+
+/**
+ * `usageLine` first (its exact text is asserted elsewhere and must not move),
+ * then positionals, then every flag with its value shape and a `[required]`
+ * marker where the parser demands one.
+ */
+export function renderSubHelp(_cmd: string, usageLine: string, spec: HelpSpec): string {
+    const lines: string[] = [usageLine.trimEnd()];
+    if (spec.positionals.length > 0) {
+        lines.push('', 'positional arguments:');
+        for (const p of spec.positionals) {
+            lines.push(`  ${p}`);
+        }
+    }
+    if (spec.opts.length > 0) {
+        lines.push('', 'options:');
+        const required = new Set(spec.requiredOpts);
+        for (const o of spec.opts) {
+            const value = o.takesValue
+                ? o.choices && o.choices.length > 0
+                    ? ` {${o.choices.join(',')}}`
+                    : ' VALUE'
+                : '';
+            lines.push(`  ${o.flag}${value}${required.has(o.flag) ? '   [required]' : ''}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}

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_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}\`.`,
         );