@event4u/agent-config 14.22.0 → 14.23.0

package/src/scripts/hooks/rule_inject_hook.ts

@@ -11,12 +11,23 @@
  * the 36.2 %-against-48 % run at `docs/CLAIMS.md:188-189`. Whatever that
  * instrument's flaws — and ADR-202 closed it — it points one way.
  *
- * DEFAULT OFF, AND OFF MEANS ZERO BYTES. The concern registers on two slots but
- * returns before reading the router unless `lean_projection.mode: delivery` is
- * set. Under every shipped default it emits nothing, costs no injection budget,
- * and leaves the standing corpus exactly as it is today. That is why its
- * `hook-token-budget.json` row is registered against the per-prompt cap rather
- * than a measured emission: there is no measured emission to register yet.
+ * SHIPPED ON FOR CLAUDE CODE SINCE ADR-265 — corrected 2026-09-08 (R2 finding
+ * 4), because this paragraph read "DEFAULT OFF, AND OFF MEANS ZERO BYTES …
+ * under every shipped default it emits nothing … there is no measured emission
+ * to register yet" and all four clauses became false in the same change that
+ * edited the paragraph below it. The shipped template carries
+ * `lean_projection.mode: delivery` with `hosts: [claude-code]`
+ * (`src/config/agent-settings.template.yml`), `gateOpen` returns true on that
+ * pair, and the emission IS measured: p50 6,674 B, p90 16,188 B, max 20,406 B
+ * over 318 gate-open fires on the frozen corpus, which is the distribution the
+ * `user_prompt_submit` slot raise in `src/config/hook-token-budget.json` is
+ * derived from.
+ *
+ * OFF STILL MEANS ZERO BYTES, and that half is unchanged: the concern returns
+ * before reading the router unless the resolved (mode, hosts) pair actually
+ * thins THIS host — see `gateOpen`, which checks both, because the projector
+ * does. On any other host, and on a `lean_projection.mode: eager-all` rollback,
+ * it emits nothing.
  *
  * ONE MATCHER, SHARED WITH THE OFFLINE MODEL. Everything about selection,
  * ordering, capping and body loading comes from `_lib/rule_injection.ts`, which
@@ -31,6 +42,29 @@
  * uses. State lives under `agents/runtime/state/`, the class
  * `context-hygiene.json` already occupies; no new state convention is created.
  *
+ * WHAT IS RE-DELIVERED AFTER A COMPACTION, EXACTLY
+ * (road-to-delivery-for-every-host 2.4 — stated because a rule lost at a
+ * compaction boundary is lost for the rest of the session, and "re-armed" alone
+ * does not say what a reader may rely on):
+ *
+ *   · `pre_compact` clears the WHOLE seen-set for that session, not the rules
+ *     matched on the compacted turn. There is no per-rule bookkeeping to be
+ *     partially wrong about.
+ *   · Nothing is delivered BY the compaction itself. The slot emits zero bytes
+ *     and exits allow; re-arming is silent.
+ *   · A rule's body returns on the NEXT turn whose trigger matches it — which
+ *     means a rule whose trigger does not fire again is NOT restored. Delivery
+ *     is trigger-driven on both sides of the boundary; compaction resets the
+ *     de-duplication, it does not replay a transcript.
+ *   · The seen-set is per session, so a compaction in one session re-arms only
+ *     that session.
+ *
+ * Held by three fixtures in `tests/scripts/rule_inject_hook.test.ts` under
+ * "once per session per rule, re-armed on compaction": the dedup case, the
+ * matched-rule → compaction → matching-turn → body-present case, and the
+ * per-session case. All three predate this roadmap; 2.4 adds the contract
+ * above, not the coverage, and says so rather than claiming new tests.
+ *
  * NEVER BLOCKS. Every failure path returns 0: unreadable stdin, malformed JSON,
  * missing router, unreadable body, unwritable state. The one non-zero exit is
  * the host's advisory context channel (exit 2 + `decision: "warn"`), the same
@@ -54,8 +88,12 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { hookSectionEnabled, leanProjectionModeRaw } from '../_lib/hook_settings.js';
-import { deliversBodies, normalizeLeanProjectionMode } from '../_lib/lean_projection_mode.js';
+import { hookSectionEnabled, leanProjectionHostsRaw, leanProjectionModeRaw } from '../_lib/hook_settings.js';
+import {
+    deliversBodies,
+    normalizeLeanProjectionMode,
+    resolveLeanProjectionHosts,
+} from '../_lib/lean_projection_mode.js';
 import {
     loadRuleBody,
     loadRouter,
@@ -81,15 +119,38 @@ const EXIT_WARN = 2;
  * slot, for a concern that is default-OFF and emits nothing. Measured: 202 ms
  * -> 196 ms on the `pre_tool_use` p95 when the concern is unbound entirely, and
  * the CI latency gate went red on the branch that introduced it while passing
- * on main. So the runtime cap is the same bound in the unit
+ * on main. So the runtime cap is stated in the unit
  * `hook-token-budget.json` already enforces — 5,000 tok at the ~4 bytes/token
- * this corpus measures is 20,480 B, which is exactly this concern's registered
- * row. Cap and budget row are now one number instead of two units.
+ * this corpus measures was 20,480 B, and that WAS this concern's registered
+ * row until 2026-09-08. It matched the concern row and not the slot row; see
+ * the correction below.
+ *
+ * LOWERED 20480 -> 16384 on 2026-09-08 (R2 finding 3), and the paragraphs above
+ * are kept because they record how the retired number was derived. The defect
+ * was that the derivation above and the one behind the
+ * `user_prompt_submit` slot row were TWO STATISTICS IN TWO UNITS: this cap was
+ * the p90 of the matched-body TOKEN distribution, converted at ~4 B/tok; the
+ * slot row is the p90 gate-open FIRE SIZE in bytes, which is the activation
+ * charge owner ruling E2 specifies. They disagreed by 25 %, in the direction
+ * that licensed ONE concern to emit more than the whole slot — carrying 12
+ * other concerns — is registered for. Reconciled downward onto the slot row,
+ * because that is the owner-specified charge; the cost is measured and recorded
+ * in `hook-token-budget.json`'s own `rule-inject_reason` (33 -> 45 fires
+ * truncated, 63 -> 88 bodies withheld over 330 corpus fires).
+ *
+ * WHAT THIS CAP DOES, precisely: `selectForInjection` drops whole bodies to
+ * stay under it, so a fire is TRUNCATED and never over-emitted. It is the only
+ * number that acts on a single fire — the per-slot sums are an authoring-time
+ * control read by `bench_hook_injection`, and the runtime dispatcher enforces
+ * only `per_turn_aggregate_bytes.ceiling_bytes`.
  *
  * Re-run that command if the corpus or the bodies move; a cap copied from a
- * stale measurement is worse than no cap, because it looks derived.
+ * stale measurement is worse than no cap, because it looks derived. The
+ * tripwire in `tests/scripts/rule_inject_hook.test.ts` holds this equal to the
+ * registered concern row and at or below the slot sum, so the two units cannot
+ * drift apart again unnoticed.
  */
-export const CAP_BYTES = 20480;
+export const CAP_BYTES = 16384;
 
 /** Tools whose input names a file this concern can match path triggers against. */
 export const FILE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit', 'Read', 'MultiEdit']);
@@ -216,18 +277,44 @@ export function buildInjection(
 
 // ── main ─────────────────────────────────────────────────────────────────
 
+/**
+ * The one host this concern is bound on.
+ *
+ * The manifest binds `rule-inject` under `claude` alone, so the host axis
+ * `gateOpen` has to consult is a constant here rather than something read off
+ * the envelope — the envelope carries no host id, and inventing one from the
+ * process environment would be a guess where the manifest is a fact.
+ */
+export const DELIVERY_HOST = 'claude-code';
+
 /**
  * Whether the settings gate applies.
  *
- * Through the dispatcher the gate is absolute: no `lean_projection.mode:
- * delivery`, no bytes. A DIRECT CLI invocation is a probe by definition — an
- * operator piping an envelope into this file is asking to see what it would
- * deliver — so there the mode defaults to on. `AGENT_CONFIG_REPLAY` re-imposes
- * the gate, which is what keeps `bench_hook_injection` measuring the shipped
- * default (zero bytes) rather than the probe.
+ * BOTH AXES, because the projector reads both. Until 2026-09-08 this keyed on
+ * `lean_projection.mode` alone while `condense` gates stub-writing on
+ * `thinsHost(mode, hosts, host)` (R2 finding 5). The two disagreed in exactly
+ * the states the host axis exists for: `mode: delivery` with a `hosts:` list
+ * that does not resolve to `claude-code` — the documented "thin no host"
+ * state, which a fully typo'd list also produces — left this host with a
+ * FULL-BODIED tree while the hook kept injecting on a match, so every matched
+ * rule was delivered twice. `hosts: [cursor]` was the same defect with a
+ * second half: cursor received stubs with no bound slot to deliver them back.
+ *
+ * `deliversBodies` is checked separately from the host list rather than via
+ * `thinsHost`, which is true for `thin` as well: `thin` writes the same stubs
+ * and binds NO delivery concern, so it must never open this gate.
+ *
+ * An explicit `hooks.rule_inject` opt-in still opens it — that is an operator
+ * asking for the concern by name, independent of the projection mode. A DIRECT
+ * CLI invocation is a probe by definition — an operator piping an envelope into
+ * this file is asking to see what it would deliver — so there the gate defaults
+ * to open. `AGENT_CONFIG_REPLAY` re-imposes it, which is what keeps
+ * `bench_hook_injection` measuring the configured tree rather than the probe.
  */
 export function gateOpen(root: string, cliEntry: boolean): boolean {
-    if (deliversBodies(normalizeLeanProjectionMode(leanProjectionModeRaw(root)))) return true;
+    const mode = normalizeLeanProjectionMode(leanProjectionModeRaw(root));
+    const hosts = resolveLeanProjectionHosts(leanProjectionHostsRaw(root)).hosts;
+    if (deliversBodies(mode) && hosts.includes(DELIVERY_HOST)) return true;
     if (hookSectionEnabled(root, 'rule_inject')) return true;
     return cliEntry && process.env['AGENT_CONFIG_REPLAY'] !== '1';
 }

package/src/scripts/hooks/session_eol_hook.ts

@@ -45,7 +45,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
 
-import { recycle_envelope_rel } from '../_lib/recycle_envelope_paths.js';
+import {
+    listContinuityRecords,
+    RECYCLE_MAX_AGE_HOURS,
+    recycle_envelope_rel,
+} from '../_lib/recycle_envelope_paths.js';
 import {
     emptyCounters,
     eolSessionKey,
@@ -56,6 +60,12 @@ import {
 } from '../_lib/session_eol.js';
 import { readContextObservation } from '../_lib/context_observation.js';
 import { buildCheckpoint, writeCheckpoint } from '../_lib/run_checkpoint.js';
+import {
+    auto_record_enabled,
+    buildContinuityRecord,
+    run_checkpoints_enabled,
+} from '../_lib/continuity_writer.js';
+import { publishContinuityRecord } from '../_lib/continuity_slot.js';
 import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
@@ -210,6 +220,62 @@ export function envelopeExists(
     }
 }
 
+/**
+ * Records that were written and never read — the detection layer this defect
+ * did not have.
+ *
+ * `road-to-a-recycle-envelope-that-is-consumed` step 1.2. Twelve unconsumed
+ * envelopes accumulated across the estate over roughly a month, and the only
+ * reason anyone found them was a stray-copy check during an unrelated task. The
+ * producer reported success, the consumer reported `absent`, and nothing
+ * compared the two — so the mechanism was inert for weeks with no signal.
+ *
+ * Advisory ONLY. A hook that blocks a session end over a stale runtime file is
+ * worse than the file, and that is Kill-register K3 of the roadmap rather than
+ * a preference here.
+ *
+ * Silent in the normal case, which is what keeps it worth reading: a record
+ * younger than {@link RECYCLE_MAX_AGE_HOURS} is a pending resume, not a defect,
+ * and past that age the consumer discards it loudly on its own. What this
+ * reports is the third state — old enough to be dead, still sitting there,
+ * which means no successor ever came for it.
+ */
+export function unconsumedRecordLines(
+    workspaceRoot: string,
+    now: Date = new Date(),
+    maxAgeHours: number = RECYCLE_MAX_AGE_HOURS,
+): string[] {
+    const out: string[] = [];
+    for (const file of listContinuityRecords(workspaceRoot)) {
+        let raw: string;
+        try {
+            raw = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue; // an unreadable record proves nothing in either direction
+        }
+        let written: unknown;
+        let nextTask: unknown;
+        try {
+            const parsed = JSON.parse(raw) as { written_at?: unknown; next_task?: unknown };
+            written = parsed.written_at;
+            nextTask = parsed.next_task;
+        } catch {
+            continue;
+        }
+        if (typeof written !== 'string') continue;
+        const stamp = Date.parse(written);
+        if (Number.isNaN(stamp)) continue;
+        const ageHours = (now.getTime() - stamp) / 3_600_000;
+        if (ageHours <= maxAgeHours) continue;
+        const task = typeof nextTask === 'string' && nextTask.trim() !== '' ? nextTask.trim() : '(no next_task)';
+        out.push(
+            `unconsumed continuity record: ${path.relative(workspaceRoot, file)} is ` +
+                `${ageHours.toFixed(0)}h old and was never read — next_task was "${task.slice(0, 120)}"`,
+        );
+    }
+    return out;
+}
+
 /**
  * The follow-up line: the advisory already fired, and no envelope arrived.
  *
@@ -389,7 +455,7 @@ export function main(): number {
     // Best-effort throughout. A checkpoint is a recovery aid, and a
     // recovery aid that can fail a Stop is a liability.
     const checkpointRunId = payloadSessionId(payload, envelope);
-    if (shouldAdvise && checkpointRunId !== '') {
+    if (shouldAdvise && checkpointRunId !== '' && run_checkpoints_enabled(workspaceRoot)) {
         try {
             const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
             if (slug !== null) {
@@ -411,6 +477,8 @@ export function main(): number {
         }
     }
 
+    writeContinuityRecord(workspaceRoot, rawSessionId, counters, threshold, tokens);
+
     if (shouldAdvise && threshold !== null && tokens !== null) {
         process.stdout.write(
             `${JSON.stringify({
@@ -434,6 +502,56 @@ export function main(): number {
     return 0;
 }
 
+/**
+ * The continuity-record handler — one of the three lifecycle handlers this
+ * concern carries, and independently switchable from the other two.
+ *
+ * `road-to-continuity-writer-activation` step 1.2, and it lands INSIDE this
+ * concern rather than as a fourth concern id on purpose: `check_estate_count`
+ * ratchets `concern_count` with allowance 0, and the 2026-09-08 AI council
+ * refused a temporary allowance 2/2. The substance the 2026-09-07 council's D2
+ * asked for is independent switching and failure isolation, and a handler
+ * behind its own settings key inside a `try` gives both without a manifest
+ * split. The split itself is step 2.1 and stays blocked until a concern is
+ * retired to pay for it.
+ *
+ * Fires from the recycle THRESHOLD, not from the once-per-session advisory
+ * stamp: the stamp fires once, so a record written from it would be frozen at
+ * the moment the session crossed the threshold and would go stale as the
+ * session continued. Driving it from the raw threshold condition instead means
+ * every later Stop supersedes the record under the slot's own policy, so what a
+ * successor reads is always the newest state, and the write rate is still
+ * bounded to the end phase of a session rather than every turn of it.
+ *
+ * Best-effort throughout, like the checkpoint above it: a continuity record is
+ * a recovery aid, and a recovery aid that can fail a Stop is a liability.
+ */
+function writeContinuityRecord(
+    workspaceRoot: string,
+    rawSessionId: string | null,
+    counters: EolCounters,
+    threshold: number | null,
+    tokens: number | null,
+): void {
+    if (threshold === null || tokens === null || tokens < threshold) return;
+    const sessionId = String(rawSessionId ?? '').trim();
+    if (sessionId === '') return;
+    try {
+        if (!auto_record_enabled(workspaceRoot)) return;
+        const slug = read_claimed_slug(workspaceRoot, sessionId);
+        const decision = buildContinuityRecord({
+            root: workspaceRoot,
+            sessionId,
+            slug,
+            counters,
+        });
+        if (decision.record === null) return;
+        publishContinuityRecord(workspaceRoot, sessionId, decision.record);
+    } catch {
+        // never block the Stop path, and never suppress a sibling handler
+    }
+}
+
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where
 // every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;

package/src/scripts/hot_context_hook.ts

@@ -397,27 +397,74 @@ export function restore_hot_context(
 
 /**
  * Build the compact memory index when `memory.session_index: on`; `null`
- * on the default-off path, empty corpus, or any failure (never blocks).
- * Memory roots are cwd-relative (same contract as the MCP tool handlers),
- * so the build runs chdir-wrapped to the workspace root.
+ * on the default-off path, empty corpus, a refused root, an already-served
+ * session, or any failure (never blocks).
+ *
+ * Memory roots are cwd-relative (same contract as the MCP tool handlers), so
+ * the build runs chdir-wrapped to the workspace root — and that relativity is
+ * exactly why the trust contract exists: whatever cwd this lands on is where
+ * `agents/memory` is read from. `_lib/session_index_trust.ts` carries the six
+ * properties the 2026-09-07 D3 ruling required (identity, canonicalization,
+ * freshness, ordering, duplicate invocation, size limits); this function is
+ * where two of them bind, because they need runtime facts the module cannot
+ * see — the workspace root and the session id.
+ *
+ * Refusals are logged with their code rather than swallowed. `null` alone
+ * cannot distinguish "no curated memory here" from "this root pointed at
+ * another tree", and that distinction is the whole point of the contract.
  */
-function _session_index_block_or_null(root: string): string | null {
+function _session_index_block_or_null(root: string, sessionId: string): string | null {
     try {
         // Lazy require (ESM-safe via createRequire) keeps the default-off
         // fast path free of the memory_lookup + settings-cascade import cost.
         const req = createRequire(import.meta.url);
         const mod = req('./session_memory_index.js') as {
             session_index_enabled: (root: string) => boolean;
-            build_session_index_block: () => string | null;
+            serve_session_index_block: (grant: unknown, cap?: number) => string | null;
+            session_index_trust: (workspaceRoot: string) => { ok: boolean; code?: string; detail?: string };
         };
         if (!mod.session_index_enabled(root)) return null;
+
+        // P1-P3, computed ONCE here and handed to the server as a grant. The
+        // builder used to re-check it, which R2 finding 7 named as a duplicate
+        // for a diagnostic nothing forwards; `serve_session_index_block` now
+        // takes the grant, so the check cannot be skipped and is not repeated.
+        const verdict = mod.session_index_trust(root);
+        if (!verdict.ok) {
+            process.stderr.write(`hot-context-hook: session index refused [${String(verdict.code)}]: ${String(verdict.detail)}\n`);
+            return null;
+        }
+
         const prev = process.cwd();
+        let block: string | null;
         try {
             process.chdir(root);
-            return mod.build_session_index_block();
+            block = mod.serve_session_index_block(verdict);
         } finally {
             process.chdir(prev);
         }
+
+        // P5 — duplicate invocation, claimed LAST. `session_start` can fire
+        // more than once for one session (resume, host reconnect, compaction
+        // boundary on some hosts), and two injections double a fixed cost while
+        // presenting two corpora as one session's memory.
+        //
+        // The ordering is the whole property and it took two corrections to get
+        // right. Claiming before the verdict let a refused root burn the
+        // session's one claim; claiming before the RENDER let an empty corpus
+        // burn it too (R2 finding 5) — so a session that started before its
+        // memory was curated would never receive an index afterwards. Nothing
+        // is claimed until there is something to serve.
+        if (block === null) return null;
+        const trust = req('./_lib/session_index_trust.js') as {
+            claimSessionOnce: (workspaceRoot: string, sessionId: string) => { ok: boolean; code?: string };
+        };
+        const claim = trust.claimSessionOnce(root, sessionId);
+        if (!claim.ok) {
+            process.stderr.write(`hot-context-hook: session index already served [${String(claim.code)}]\n`);
+            return null;
+        }
+        return block;
     } catch (exc) {
         process.stderr.write(`hot-context-hook: session index skipped: ${String(exc)}\n`);
         return null;
@@ -486,7 +533,15 @@ export function main(): number {
             // Opt-in compact memory index (road-to-memory-retrieval-economy
             // P5) — default OFF; rides the same injection surface. Memory
             // roots are cwd-relative, so resolve from the workspace root.
-            const indexBlock = _session_index_block_or_null(root);
+            // R2 finding 1: reading the payload alone left P5 INERT whenever
+            // the host supplied no payload id. `dispatch_hook.ts` resolves
+            // `envelope.session_id` from the payload OR `AGENT_SESSION_ID`, and
+            // every sibling concern reads the envelope first — proven by two
+            // dispatcher runs that emitted the block twice and never latched.
+            const sessionId = String(
+                envelope.session_id ?? payload.session_id ?? payload.sessionId ?? '',
+            );
+            const indexBlock = _session_index_block_or_null(root, sessionId);
             if (indexBlock !== null) {
                 blocks.push(indexBlock);
             }

package/src/scripts/lint_roadmap_blockers.ts

@@ -360,6 +360,130 @@ function _countRoadmapTree(dir: string): number {
     return n;
 }
 
+/**
+ * Blocker ids declared `Status: open` in one file, by id.
+ *
+ * Reads exactly one fact per blocker — id and open-ness. It is deliberately
+ * NOT `_scanBoth`: the five-field contract, the class taxonomy and the
+ * decidability ratchet are not applied here, because the corpus this runs over
+ * includes `archive/` and applying the contract there lands 23 findings on day
+ * one against a change that caused none of them. That shape has been reverted
+ * twice in this repository — `lint_roadmap_later_disposition` at 68 files and
+ * `check_no_new_legacy_path` at 46 — and the exclusion also protects a true
+ * thing an archived roadmap is allowed to say: a blocker genuinely unresolved
+ * when its roadmap closed is history, not a defect.
+ */
+function _openBlockerIds(text: string): Set<string> {
+    const stripped = _stripFencedCode(text);
+    const out = new Set<string>();
+    const sectionMatch = BLOCKERS_SECTION_RE.exec(stripped);
+    if (!sectionMatch) {
+        return out;
+    }
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+    const rest = stripped.slice(sectionStart);
+    const h2 = NEXT_H2_RE.exec(rest);
+    const section = stripped.slice(sectionStart, h2 ? sectionStart + h2.index : stripped.length);
+
+    BLOCKER_HEADING_RE.lastIndex = 0;
+    const heads: Array<{ end: number; start: number; id: string }> = [];
+    let hm: RegExpExecArray | null;
+    while ((hm = BLOCKER_HEADING_RE.exec(section)) !== null) {
+        heads.push({ start: hm.index, end: hm.index + hm[0].length, id: (hm[1] as string).trim() });
+        if (hm.index === BLOCKER_HEADING_RE.lastIndex) {
+            BLOCKER_HEADING_RE.lastIndex++;
+        }
+    }
+    for (let i = 0; i < heads.length; i++) {
+        const cur = heads[i] as { end: number; start: number; id: string };
+        const bodyEnd =
+            i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
+        const body = section.slice(cur.end, bodyEnd);
+        // Resolved is a prefix test for the same reason `blocker_is_resolved`
+        // makes it one: `resolved 2026-09-08 by …` is resolved.
+        if (!/^-[ \t]*\*\*Status:\*\*[ \t]*resolved\b/im.test(body)) {
+            out.add(cur.id);
+        }
+    }
+    return out;
+}
+
+/** Sorted `*.md` directly under the archive directory. */
+function _globArchivedRoadmaps(): string[] {
+    const dir = path.join(REPO_ROOT, 'agents', 'roadmaps', 'archive');
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+
+interface Overlap {
+    id: string;
+    active: string[];
+    archived: string[];
+}
+
+/** id → the files (repo-relative, sorted by input order) declaring it open. */
+function _openIdIndex(files: string[]): Map<string, string[]> {
+    const index = new Map<string, string[]>();
+    for (const f of files) {
+        const rel = _relPosix(f, REPO_ROOT);
+        for (const id of _openBlockerIds(fs.readFileSync(f, 'utf-8'))) {
+            const hits = index.get(id);
+            if (hits === undefined) {
+                index.set(id, [rel]);
+            } else {
+                hits.push(rel);
+            }
+        }
+    }
+    return index;
+}
+
+/**
+ * Blocker ids declared open in BOTH an active and an archived roadmap.
+ *
+ * The assertion is the one an archived record cannot legitimately make: a
+ * blocker still being decided in the active tree, simultaneously declared open
+ * in a file that says the work closed. The transition check in
+ * `archive_completed_roadmaps` catches the archival that produces this state;
+ * this catches it however else it arrives — a hand edit, a bad merge, or a
+ * commit that shipped stale index content.
+ *
+ * `open_blockers` is a shrink-only ratchet over the ACTIVE tree only, so
+ * without this the count is satisfiable by archiving rather than by resolving.
+ *
+ * Deliberately NOT "no id open in more than one file". Two ACTIVE roadmaps may
+ * legitimately share one cross-cutting blocker, and forbidding that would break
+ * a real pattern to catch a different defect (AI council 2026-09-08, 2/2
+ * present: the unscoped form "forbids legitimate cross-cutting blockers in
+ * multiple active roadmaps"). Two ARCHIVED files sharing an open id is out of
+ * scope for the same day-one reason as the contract itself: measured at 2 on
+ * this tree, so a hard assertion there would red the build on records this
+ * change did not create.
+ */
+function _archiveOverlap(
+    activeFiles: string[] = _globRoadmaps(),
+    archivedFiles: string[] = _globArchivedRoadmaps(),
+): Overlap[] {
+    const active = _openIdIndex(activeFiles);
+    const archived = _openIdIndex(archivedFiles);
+    const out: Overlap[] = [];
+    for (const [id, activeHits] of [...active.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        const archivedHits = archived.get(id);
+        if (archivedHits !== undefined) {
+            out.push({ id, active: activeHits, archived: archivedHits });
+        }
+    }
+    return out;
+}
+
 function main(): number {
     try {
         assertScanned({
@@ -411,6 +535,38 @@ function main(): number {
         return 1;
     }
 
+    // An archived roadmap says the work closed. An open blocker declared in one
+    // AND in an active roadmap therefore contradicts itself, and the shrink-only
+    // `open_blockers` ratchet reads the active tree only — so without this the
+    // count is satisfiable by archiving rather than by resolving.
+    //
+    // HARD rather than ratcheted, and measured before it shipped: 0 overlapping
+    // ids on this tree at 2026-09-08 (12 active open ids, 33 archived), so on
+    // the day it lands it fires on nothing and there is no backlog to
+    // grandfather — the same argument the `Class:` contract above makes.
+    const overlap = _archiveOverlap();
+    if (overlap.length > 0) {
+        process.stderr.write(
+            `\n❌  ${overlap.length} blocker id(s) declared open in both an active ` +
+                'and an archived roadmap\n',
+        );
+        for (const o of overlap) {
+            process.stderr.write(`    ${o.id}\n`);
+            for (const rel of o.active) {
+                process.stderr.write(`        active:   ${rel}\n`);
+            }
+            for (const rel of o.archived) {
+                process.stderr.write(`        archived: ${rel}\n`);
+            }
+        }
+        process.stderr.write(
+            '\n    Resolve it in one place. An archived record may keep a blocker that\n' +
+                '    was genuinely unresolved when its roadmap closed; it may not keep one\n' +
+                '    the active tree is still deciding.\n',
+        );
+        return 1;
+    }
+
     // The decidability ratchet. A blocker that names no option, no command and
     // no recommendation is a research task handed to the person with the least
     // context — the defect this half of the gate exists to stop growing.
@@ -434,6 +590,10 @@ function main(): number {
     }
     if (!QUIET) {
         process.stdout.write(`\n✅  ${roadmaps.length} roadmap(s) blocker-contract-clean\n`);
+        process.stdout.write(
+            `✅  0 blocker id(s) open in both an active and an archived roadmap ` +
+                `(${_globArchivedRoadmaps().length} archived file(s) read)\n`,
+        );
         process.stdout.write(`✅  ${verdict.message}\n`);
     }
     return 0;
@@ -477,6 +637,9 @@ export {
     _scan,
     _scanBoth,
     _globRoadmaps,
+    _globArchivedRoadmaps,
+    _openBlockerIds,
+    _archiveOverlap,
     main,
 };
-export type { Violation, ScanResult };
+export type { Violation, ScanResult, Overlap };