@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/probe_host_compliance.ts

@@ -31,7 +31,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { thin_entry } from './project_thin_rules.js';
+import { has_body_pointer, is_thin_entry, thin_entry } from './project_thin_rules.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -42,8 +42,6 @@ const CANARY = path.join(
 const CANARY_ID = 'host-compliance-canary';
 const SENTINEL = 'CANARY_BODY_SENTINEL_DO_NOT_INLINE';
 const KEYWORD = 'xyzzy-canary-probe';
-const POINTER_MARKER = 'Routed rule — load the body on trigger-match';
-
 // The supported hosts whose live thin-compliance must be falsified.
 const HOSTS = ['claude-code', 'cursor', 'augment'];
 
@@ -60,10 +58,40 @@ export function evaluate_demotion(
   thinned: string,
   opts: { sentinel: string; keyword: string } = { sentinel: SENTINEL, keyword: KEYWORD },
 ): DemotionResult {
-  const pointer_present = thinned.includes(POINTER_MARKER);
+  // ONE SPELLING, ASKED OF THE WRITER — step 2.1 of
+  // `road-to-a-thinned-layer-measured-in-one-unit`. This file carried its own
+  // substring of the marker, without the blockquote prefix and the full stop,
+  // so the writer could be shortened and this detector would keep matching the
+  // old sentence — silently, and in the direction that matters: a stub a
+  // detector fails to recognise reads as a complete rule body.
+  const pointer_present = is_thin_entry(thinned);
   const body_removed = !thinned.includes(opts.sentinel);
   const trigger_hint_preserved = thinned.includes(opts.keyword);
-  const link_present = /Body: \[`[^`]+`\]\(/.test(thinned);
+  // THE PATTERN COMES FROM THE WRITER — step 2.3. This was its own regex for
+  // the markdown-link form, so when the pointer became a bare path the gate
+  // would have reported every correct stub as missing its link.
+  const link_present = has_body_pointer(thinned);
+  // HONEST LIMIT OF THIS FUNCTION'S MECHANICAL HALF, stated rather than
+  // papered over. `pointer_present` and `link_present` are now computed from
+  // the writer's own exports, and this probe's only caller feeds them
+  // `thin_entry` output produced in the same process — so against writer output
+  // those two cannot return false, whatever the writer emits. They still
+  // falsify a stub from any OTHER source, which is what the live host half
+  // reads, but the mechanical half's real falsifying power is `body_removed`
+  // and `trigger_hint_preserved`.
+  //
+  // A structural check was tried here and removed: `/\S+\.md\s*$/m` adds
+  // nothing AGAINST WRITER OUTPUT, which is the only input this half ever sees.
+  // It is not implied by `link_present` in general — `Body:  .md`, a two-space
+  // stem, matches the pointer pattern and fails `\S+` — but the writer composes
+  // the pointer from a non-empty prefix and a rule id, so that string is not
+  // reachable from `thin_entry` and the conjunct could never flip `ok` here. A
+  // conjunct that cannot fail is worse than an absent one: it reads as coverage.
+  //
+  // Restoring independence needs a second spelling of the marker, which is the
+  // drift step 2.1 removed. The suite keeps the detectors honest instead:
+  // `thin_marker_single_spelling` runs a non-stub past all three in the false
+  // direction, which is the direction this cannot check.
   return {
     ok: pointer_present && body_removed && trigger_hint_preserved && link_present,
     pointer_present,

package/src/scripts/probe_turnaround.ts

@@ -19,6 +19,7 @@
  *   - API calls per real user request      (F1)
  *   - mean tool-call batch size            (F1 — measured 1.00, i.e. fully serial)
  *   - the >60 s blocking tail and its share of tool time  (F2)
+ *   - that tail split by cause, `unknown` always printed (road-to-blocking-time-by-cause)
  *   - the first-call context floor         (F3 cross-check)
  *
  * A MEASUREMENT, NOT A GATE — by default. `--against-baseline` compares against
@@ -53,6 +54,142 @@ export const BLOCKING_SECONDS = 60;
 
 type Entry = Record<string, unknown>;
 
+/**
+ * What a blocking call waited on. A CLOSED set, and `unknown` is a row of its
+ * own rather than a fallback folded into a named cause: a share hidden inside
+ * `ci-wait` would confirm whatever hypothesis it was folded into.
+ */
+export const BLOCKING_CAUSES = [
+    'ci-wait',
+    'subagent-wait',
+    'test',
+    'build',
+    'network',
+    'sleep-poll',
+    'mcp',
+    // Added by 2.2: the first reading's unknown share was mostly a question
+    // waiting on the human, which no agent-side mitigation can shorten.
+    'user-wait',
+    'unknown',
+] as const;
+export type BlockingCause = (typeof BLOCKING_CAUSES)[number];
+
+/** Non-shell tools, by exact name. A shell call is classified by its command. */
+const TOOL_CAUSE: Readonly<Record<string, BlockingCause>> = {
+    Agent: 'subagent-wait',
+    Task: 'subagent-wait',
+    TaskOutput: 'subagent-wait',
+    Monitor: 'sleep-poll',
+    WebFetch: 'network',
+    WebSearch: 'network',
+    AskUserQuestion: 'user-wait',
+    ExitPlanMode: 'user-wait',
+};
+
+/**
+ * Shell rules, matched against each command SEGMENT's leading words in order.
+ * The first segment any rule matches decides; a segment no rule matches is
+ * skipped, so `cd ../lane; ./scripts-run …/ci_settle 12` reads as the settle it
+ * is and not as the `cd` in front of it.
+ */
+const SHELL_RULES: ReadonlyArray<readonly [RegExp, BlockingCause]> = [
+    [/^(\S*\/)?scripts-run \S*ci_settle\b/, 'ci-wait'],
+    [/^gh (run watch|pr checks)\b/, 'ci-wait'],
+    [/^(sleep|until|while|watch)\b/, 'sleep-poll'],
+    [/^((npx |\S*node_modules\/\.bin\/)?(vitest|jest|pytest|phpunit)\b|npm (run )?test\b|task (ci|test)\b)/, 'test'],
+    [/^(task (sync|generate-tools|build)\b|npm (ci|install|run build)\b|(npx )?tsc\b|make\b|esbuild\b)/, 'build'],
+    [/^(git (push|fetch|pull|clone)\b|curl\b|wget\b|gh (pr (merge|create)|api)\b)/, 'network'],
+    [/^(\S*\/)?scripts-run \S*council_cli run\b/, 'network'],
+];
+
+/** A segment that only changes directory or sets a variable waited on nothing. */
+const NOISE_SEGMENT = /^(cd\b|export\b|set\b|[A-Za-z_][A-Za-z0-9_]*=\S*$)/;
+
+/** A loop keyword in front of a body: `for …; do sleep 60` reads as the sleep. */
+const LOOP_KEYWORD = /^(do|then|else)\s+/;
+
+/**
+ * Split a shell command at `;`, `&&`, `||`, `|` and newlines that sit OUTSIDE
+ * quotes. A separator inside `"…"` or `'…'`, or escaped with a backslash, is
+ * part of an argument — splitting there would read a commit message as a
+ * command. Not a shell parser: subshells, `$(…)` and heredocs are not modelled.
+ */
+function shellSegments(cmd: string): string[] {
+    const out: string[] = [];
+    let cur = '';
+    let quote: '' | '"' | "'" = '';
+    for (let i = 0; i < cmd.length; i++) {
+        const ch = cmd[i] as string;
+        if (quote === '' && ch === '\\' && i + 1 < cmd.length) {
+            cur += ch + (cmd[i + 1] as string);
+            i++;
+            continue;
+        }
+        if (quote !== '') {
+            if (ch === quote) quote = '';
+            cur += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            cur += ch;
+            continue;
+        }
+        const two = cmd.slice(i, i + 2);
+        if (two === '&&' || two === '||') {
+            out.push(cur);
+            cur = '';
+            i++;
+            continue;
+        }
+        if (ch === ';' || ch === '|' || ch === '\n') {
+            out.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    out.push(cur);
+    return out;
+}
+
+/**
+ * Exactly one cause per call; `unknown` when no rule matches. A compound
+ * command takes the cause of its FIRST matching segment, so `git commit && git
+ * push` reads as the push — the whole call's time lands on that one cause.
+ */
+export function classifyBlockingCall(tool: string, input: unknown): BlockingCause {
+    if (tool.startsWith('mcp__')) return 'mcp';
+    const byName = TOOL_CAUSE[tool];
+    if (byName !== undefined) return byName;
+    if (tool !== 'Bash' || !isObj(input) || typeof input['command'] !== 'string') return 'unknown';
+    for (const raw of shellSegments(input['command'])) {
+        const seg = raw.trim().replace(LOOP_KEYWORD, '');
+        if (seg === '' || NOISE_SEGMENT.test(seg)) continue;
+        for (const [re, cause] of SHELL_RULES) if (re.test(seg)) return cause;
+    }
+    return 'unknown';
+}
+
+/**
+ * The in-memory record of one blocking call. `summary` is bounded and never
+ * printed or serialised by `main`: command text names local paths and hosts,
+ * and the published reading carries counts and minutes only.
+ */
+export interface BlockingCall {
+    tool: string;
+    summary: string;
+    cause: BlockingCause;
+    seconds: number;
+}
+
+const SUMMARY_CHARS = 120;
+
+function summarise(tool: string, input: unknown): string {
+    const body = isObj(input) && typeof input['command'] === 'string' ? input['command'] : JSON.stringify(input ?? {});
+    return `${tool}: ${body}`.slice(0, SUMMARY_CHARS);
+}
+
 function isObj(v: unknown): v is Record<string, unknown> {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -72,6 +209,12 @@ export interface Turnaround {
     blockingShare: number;
     contextFloorMin: number;
     contextFloorMax: number;
+    /** Blocking calls and seconds per cause; every cause present, `unknown` included. */
+    blockingByCause: Record<BlockingCause, { calls: number; seconds: number }>;
+}
+
+function emptyByCause(): Turnaround['blockingByCause'] {
+    return Object.fromEntries(BLOCKING_CAUSES.map((c) => [c, { calls: 0, seconds: 0 }])) as Turnaround['blockingByCause'];
 }
 
 const ZERO: Turnaround = {
@@ -88,6 +231,7 @@ const ZERO: Turnaround = {
     blockingShare: 0,
     contextFloorMin: 0,
     contextFloorMax: 0,
+    blockingByCause: emptyByCause(),
 };
 
 function ms(iso: unknown): number | null {
@@ -133,12 +277,20 @@ export function recentSessions(store: string, limit: number, includeCurrent = fa
 }
 
 export function measure(files: readonly string[]): Turnaround {
+    return measureDetailed(files).turnaround;
+}
+
+/** `measure`, plus the per-call blocking records the cause table is built from. */
+export function measureDetailed(files: readonly string[]): { turnaround: Turnaround; blocking: BlockingCall[] } {
     const requestIds = new Set<string>();
     /** requestId → tool_use blocks in it. */
     const batch = new Map<string, number>();
     /** tool_use id → the timestamp the assistant emitted it. */
     const emittedAt = new Map<string, number>();
+    /** tool_use id → what was called, kept only until its result arrives. */
+    const calledWith = new Map<string, { tool: string; input: unknown }>();
     const durations: number[] = [];
+    const blockingCalls: BlockingCall[] = [];
     const contextFloors: number[] = [];
     let userRequests = 0;
     let sessions = 0;
@@ -172,8 +324,20 @@ export function measure(files: readonly string[]): Turnaround {
                         const id = String(b['tool_use_id'] ?? '');
                         const started = emittedAt.get(id);
                         if (started === undefined || at === null) continue;
-                        durations.push((at - started) / 1000);
+                        const seconds = (at - started) / 1000;
+                        durations.push(seconds);
                         emittedAt.delete(id);
+                        const call = calledWith.get(id);
+                        calledWith.delete(id);
+                        if (seconds > BLOCKING_SECONDS) {
+                            const tool = call?.tool ?? '';
+                            blockingCalls.push({
+                                tool,
+                                summary: summarise(tool, call?.input),
+                                cause: classifyBlockingCall(tool, call?.input),
+                                seconds,
+                            });
+                        }
                     }
                 }
                 continue;
@@ -202,7 +366,10 @@ export function measure(files: readonly string[]): Turnaround {
                 if (!isObj(b) || b['type'] !== 'tool_use') continue;
                 n += 1;
                 const id = String(b['id'] ?? '');
-                if (id !== '' && at !== null) emittedAt.set(id, at);
+                if (id !== '' && at !== null) {
+                    emittedAt.set(id, at);
+                    calledWith.set(id, { tool: String(b['name'] ?? ''), input: b['input'] });
+                }
             }
             if (n > 0 && typeof rid === 'string' && rid !== '') {
                 batch.set(rid, (batch.get(rid) ?? 0) + n);
@@ -216,8 +383,14 @@ export function measure(files: readonly string[]): Turnaround {
     const blocking = durations.filter((d) => d > BLOCKING_SECONDS);
     const blockingSeconds = blocking.reduce((a, b) => a + b, 0);
     const round = (x: number, p = 2): number => Math.round(x * 10 ** p) / 10 ** p;
+    const byCause = emptyByCause();
+    for (const c of blockingCalls) {
+        byCause[c.cause].calls += 1;
+        byCause[c.cause].seconds += c.seconds;
+    }
+    for (const c of BLOCKING_CAUSES) byCause[c].seconds = round(byCause[c].seconds, 1);
 
-    return {
+    const turnaround: Turnaround = {
         sessions,
         userRequests,
         apiCalls: requestIds.size,
@@ -231,7 +404,9 @@ export function measure(files: readonly string[]): Turnaround {
         blockingShare: toolSeconds === 0 ? 0 : round(blockingSeconds / toolSeconds, 4),
         contextFloorMin: contextFloors.length === 0 ? 0 : Math.min(...contextFloors),
         contextFloorMax: contextFloors.length === 0 ? 0 : Math.max(...contextFloors),
+        blockingByCause: byCause,
     };
+    return { turnaround, blocking: blockingCalls };
 }
 
 export interface Budget {
@@ -297,6 +472,11 @@ function render(t: Turnaround, store: string): string {
         `  mean tool-call batch size    ${String(t.meanBatchSize)}  (${String(t.toolCalls)} tool calls / ${String(t.toolUsingRequests)} tool-using requests)`,
         `  blocking tail (>${String(BLOCKING_SECONDS)}s)        ${String(t.blockingCalls)} call(s), ${String(Math.round(t.blockingSeconds / 60))} min = ${pct(t.blockingShare)} of ${String(Math.round(t.toolSeconds / 60))} min tool time`,
         `  first-call context floor     ${String(t.contextFloorMin)}–${String(t.contextFloorMax)} tokens`,
+        `  blocking tail by cause`,
+        ...BLOCKING_CAUSES.map((c) => {
+            const row = t.blockingByCause[c];
+            return `    ${c.padEnd(14)}${String(row.calls)} call(s), ${String(Math.round(row.seconds / 60))} min`;
+        }),
         '',
     ].join('\n');
 }

package/src/scripts/ratification_header.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env tsx
+/**
+ * ratification_header — print a ratification artifact's `providers:`,
+ * `verdict:` and `seats:` frontmatter lines, derived from per-seat final
+ * verdicts.
+ *
+ * The two header fields used to be typed by the author, and three findings in
+ * one release were the header saying more than the seats had: `ratified` over a
+ * non-convergent seat, two providers over one closing seat. This is the writer
+ * side of the fix; `readRatification` refuses the same shapes on the reader
+ * side whenever `seats:` is recorded.
+ *
+ * Usage: ratification_header --seat <provider>=<final-verdict> [--seat …]
+ *   final-verdict: ratified | confirmed-non-expanding | refused | non-convergent
+ *                  | no-final-verdict (the seat closed or was absent at the end)
+ *
+ * Exit codes: 0 = header printed · 2 = usage error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    SEAT_PROVIDER_RE,
+    SEAT_VERDICTS,
+    renderRatificationHeader,
+    type SeatVerdict,
+} from './_lib/ratification_artifact.js';
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const seats = new Map<string, SeatVerdict>();
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] !== '--seat') {
+            process.stderr.write(`error: unknown argument ${String(argv[i])}\n`);
+            return 2;
+        }
+        const raw = argv[i + 1] ?? '';
+        i += 1;
+        const eq = raw.indexOf('=');
+        const provider = raw.slice(0, eq);
+        const verdict = raw.slice(eq + 1);
+        if (eq <= 0 || !SEAT_PROVIDER_RE.test(provider) || !SEAT_VERDICTS.includes(verdict)) {
+            process.stderr.write(
+                `error: --seat needs <provider id ${String(SEAT_PROVIDER_RE)}>=<one of ` +
+                    `${SEAT_VERDICTS.join('|')}>, got \`${raw}\`\n`,
+            );
+            return 2;
+        }
+        if (seats.has(provider)) {
+            process.stderr.write(`error: seat \`${provider}\` given twice\n`);
+            return 2;
+        }
+        seats.set(provider, verdict as SeatVerdict);
+    }
+    if (seats.size === 0) {
+        process.stderr.write('error: at least one --seat is required\n');
+        return 2;
+    }
+    process.stdout.write(`${renderRatificationHeader(seats)}\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const here = fileURLToPath(import.meta.url);
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(here) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/refusal_envelope.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env tsx
+/**
+ * refusal_envelope — the hand-off an agent writes when a HOST classifier
+ * refuses a step of an owner-directed task (ADR-282 § Part B).
+ *
+ * The repository cannot change the host classifier, and an agent must never
+ * route around a refused action. With the owner present it asks once for an
+ * explicit in-session authorization and re-runs the same step once; this
+ * envelope is the fallback when that is refused too or no owner is present.
+ * Write one ready-to-paste continuation prompt and name its path in one line,
+ * so the owner never has to ask for it.
+ *
+ * The envelope lands at `agents/tmp/<round-hex>/prompt.md`. The directory name
+ * is an opaque round id because `block-speaking-inbox-dir` refuses any other
+ * shape under `agents/tmp/`; the id is random, so an earlier envelope is never
+ * overwritten.
+ *
+ * Subagent lanes report refusals in the fixed `classifier_refusals` field;
+ * `batchLaneRefusals` folds every lane's field into ONE list so a drain ends in
+ * one envelope instead of N reports the owner collects by hand. A lane report
+ * WITHOUT the field is malformed — "no field" and "no refusals" must not read
+ * the same, or a lane that forgot to report looks like a lane that was clean.
+ *
+ * Usage:
+ *   refusal_envelope --input <file.json> [--root DIR]
+ * The JSON is an `EnvelopeInput`. Prints the written path as the last line.
+ */
+
+import { randomBytes } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export interface Refusal {
+    action: string;
+    reason: string;
+    lane?: string;
+}
+
+export interface EnvelopeInput {
+    task: string;
+    done: string[];
+    refusals: Refusal[];
+    remaining: string[];
+    /** Path of the owner-directive record that authorized the task, if any. */
+    ownerDirective?: string;
+}
+
+export interface LaneReport {
+    lane: string;
+    classifier_refusals: Array<{ action: string; reason: string }>;
+}
+
+const bullets = (items: readonly string[]): string => (items.length > 0 ? items.map((i) => `- ${i}`).join('\n') : '- none');
+
+export function renderEnvelope(input: EnvelopeInput): string {
+    if (input.refusals.length === 0) {
+        throw new Error('an envelope needs at least one refusal — without one there is nothing to hand off');
+    }
+    const refused = input.refusals
+        .map((r) => `- ${r.lane !== undefined ? `[${r.lane}] ` : ''}${r.action} — refused: ${r.reason}`)
+        .join('\n');
+    const auth =
+        input.ownerDirective !== undefined
+            ? `The repository owner directly ordered this task; the order is recorded verbatim in \`${input.ownerDirective}\`. I am the owner and I authorize the remaining steps below in this message.`
+            : 'I am the owner of this repository and I authorize the remaining steps below in this message.';
+    return [
+        '# Continuation prompt — paste into a fresh session',
+        '',
+        '## Task',
+        '',
+        input.task,
+        '',
+        '## Done',
+        '',
+        bullets(input.done),
+        '',
+        '## Refused by the host classifier',
+        '',
+        refused,
+        '',
+        'Do not retry or route around these refusals. If one recurs, stop and say so.',
+        '',
+        '## Remaining steps',
+        '',
+        input.remaining.map((s, i) => `${i + 1}. ${s}`).join('\n'),
+        '',
+        '## Owner authorization',
+        '',
+        auth,
+        '',
+    ].join('\n');
+}
+
+export function writeEnvelope(root: string, input: EnvelopeInput): string {
+    const body = renderEnvelope(input);
+    const dir = path.join(root, 'agents', 'tmp', `round-${randomBytes(4).toString('hex')}`);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'prompt.md');
+    fs.writeFileSync(file, body, { flag: 'wx' });
+    return file;
+}
+
+export function batchLaneRefusals(reports: readonly LaneReport[]): Refusal[] {
+    const out: Refusal[] = [];
+    for (const r of reports) {
+        if (!Array.isArray(r.classifier_refusals)) {
+            throw new Error(`lane ${r.lane} report is missing the classifier_refusals field`);
+        }
+        for (const x of r.classifier_refusals) {
+            out.push({ lane: r.lane, action: x.action, reason: x.reason });
+        }
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let root = process.cwd();
+    let input: string | undefined;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--root') {
+            root = argv[++i] ?? root;
+        } else if (argv[i] === '--input') {
+            input = argv[++i];
+        }
+    }
+    if (input === undefined) {
+        process.stderr.write('usage: refusal_envelope --input <file.json> [--root DIR]\n');
+        return 2;
+    }
+    const file = writeEnvelope(root, JSON.parse(fs.readFileSync(input, 'utf8')) as EnvelopeInput);
+    process.stdout.write(`${path.relative(root, file)}\n`);
+    return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    process.exit(main());
+}

package/src/scripts/release_publication.ts

@@ -466,20 +466,37 @@ export function local_release_gate_argv(): string[] {
  * Returns `null` on any measurement failure — a shallow clone or a missing tag
  * is an environment fact, and a release must not stop over one. `null` means
  * the line is simply not rendered.
+ *
+ * Both ends are resolved to SHAs BEFORE measuring, and the rendered level
+ * carries them. The 16.3.0 line read `23 vs 1` while the measurer re-run on
+ * `16.2.0..16.3.0` reads `83 vs 3`: `HEAD` at write time was not the commit the
+ * tag later named, and the line recorded neither end, so nobody could say which
+ * range it had read. With both SHAs in the line, `measure_release_mix --from
+ * <from> --to <to>` reproduces it.
  */
 export function measure_mix_obligation(
     version: string,
     fromRef?: string | null,
+    opts: { toRef?: string; cwd?: string } = {},
 ): MixObligation | null {
+    const cwd = opts.cwd ?? REPO_ROOT;
+    const toRef = opts.toRef ?? 'HEAD';
     try {
-        const from = fromRef ?? previous_release_tag('HEAD', REPO_ROOT);
+        const from = fromRef ?? previous_release_tag(toRef, cwd);
         if (!from) return null;
-        const reading = measureRange(from, 'HEAD', loadTaxonomy(), version, REPO_ROOT);
+        const from_sha = _resolve_commit(from, cwd);
+        const to_sha = _resolve_commit(toRef, cwd);
+        const reading = measureRange(from_sha, to_sha, loadTaxonomy(), version, cwd);
         const o = reading.response_obligation;
         return {
             level:
                 `governance-only ${String(o.governance_only)} vs consumer-only ` +
-                `${String(o.consumer_only)} (taxonomy ${reading.taxonomy_version})`,
+                `${String(o.consumer_only)} (taxonomy ${reading.taxonomy_version}; ` +
+                `range ${from_sha.slice(0, 12)}..${to_sha.slice(0, 12)})`,
+            from_sha,
+            to_sha,
+            governance_only: o.governance_only,
+            consumer_only: o.consumer_only,
         };
     } catch (err) {
         // Printed rather than swallowed. Nothing refuses over the reading any
@@ -494,6 +511,15 @@ export function measure_mix_obligation(
     }
 }
 
+function _resolve_commit(ref: string, cwd: string): string {
+    const r = spawnSync('git', ['rev-parse', '--verify', `${ref}^{commit}`], { encoding: 'utf-8', cwd });
+    const sha = (r.stdout ?? '').trim();
+    if (r.status !== 0 || !/^[0-9a-f]{40}$/u.test(sha)) {
+        throw new Error(`cannot resolve \`${ref}\` to a commit`);
+    }
+    return sha;
+}
+
 /**
  * Refuse the FIRST remote state of a release whose section is not publishable.
  *

package/src/scripts/report_dispatch_import_closure.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env tsx
+/**
+ * Print the static import closure of the hook dispatcher, one module per line
+ * with its class — `verdict`, `payload`, `neither` or `concern`.
+ *
+ * The reading behind `check_kernel_edit_ratified`'s derived watched set: the
+ * `verdict` rows are what the gate adds to its hand-written plumbing pattern.
+ * Named `report_` because it publishes a reading and gates nothing.
+ *
+ * Inputs:
+ *   --root DIR   tree to read (default: this script's repository)
+ *   --markdown   emit a Markdown table instead of plain lines
+ *
+ * Exit 0 always, unless the dispatcher is absent under `--root` (exit 1): an
+ * empty closure from a tree with no dispatcher is not a reading.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    DISPATCHER_PATH,
+    dispatchImportClosure,
+    type ClosureEntry,
+    type ModuleClass,
+} from './_lib/dispatch_import_closure.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+const ORDER: readonly ModuleClass[] = ['verdict', 'payload', 'neither', 'concern'];
+
+export function render(entries: readonly ClosureEntry[], markdown: boolean): string[] {
+    const sorted = [...entries].sort(
+        (a, b) => ORDER.indexOf(a.class) - ORDER.indexOf(b.class) || a.path.localeCompare(b.path),
+    );
+    const counts = ORDER.map((c) => `${c} ${entries.filter((e) => e.class === c).length}`).join(' · ');
+    const lines: string[] = [];
+    if (markdown) {
+        lines.push('| Class | Module |', '|---|---|');
+        for (const e of sorted) {
+            lines.push(`| ${e.class} | \`${e.path}\` |`);
+        }
+        lines.push('', `Totals: ${counts}.`);
+        return lines;
+    }
+    for (const e of sorted) {
+        lines.push(`${e.class.padEnd(8)} ${e.path}`);
+    }
+    lines.push(`totals: ${counts}`);
+    return lines;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let root = REPO;
+    let markdown = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--root') {
+            root = path.resolve(argv[i + 1] ?? root);
+            i += 1;
+        } else if (argv[i] === '--markdown') {
+            markdown = true;
+        }
+    }
+    if (!fs.existsSync(path.join(root, DISPATCHER_PATH))) {
+        process.stderr.write(`report_dispatch_import_closure: no ${DISPATCHER_PATH} under ${root}\n`);
+        return 1;
+    }
+    process.stdout.write(`${render(dispatchImportClosure(root), markdown).join('\n')}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}