@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/project_thin_rules.ts

@@ -18,11 +18,10 @@
  * target dir of your choosing — it never overwrites the live `.claude/` /
  * `.augment/` projections.
  *
- * NOTE (faithful literal): the thin-entry pointer keeps the verbatim
- * `Body: [`{rule_id}`](../../dist/agent-src/rules/{rule_id}.md)`
- * Markdown link from the retired Python implementation. The same-basename `.py` twin
- * carries that literal, so the ADR-051 legacy-path guard exempts this `.ts`
- * file by twin-parity.
+ * NOTE: the thin-entry pointer literal moved with the mechanism — it is
+ * `BODY_LINK_PREFIX` in `_lib/thin_rules.ts` now, so the twin-parity argument
+ * that exempted it from the ADR-051 legacy-path guard belongs to THAT file and
+ * no longer describes this one, which holds the string nowhere.
  *
  * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
@@ -35,338 +34,46 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import {
-    pathOnlyRuleIds,
-    triggerlessRuleIds,
-    type Router,
-} from './_lib/rule_injection.js';
 import * as token_count from './_lib/token_count.js';
 
-const _HERE = fileURLToPath(import.meta.url);
-// REPO_ROOT = Path(__file__).resolve().parent.parent.parent — three dirs up
-// from src/scripts/<file>.
-export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-
-export const RULES_SOURCE = path.join(REPO_ROOT, 'dist/agent-src', 'rules');
-export const ROUTER = path.join(REPO_ROOT, 'dist', 'router.json');
-
-/** `sorted(dir.glob("*.md"))` — non-recursive, lexically sorted abs paths. */
-function _globSortedMd(dir: string): string[] {
-    let names: string[];
-    try {
-        names = fs.readdirSync(dir);
-    } catch {
-        return [];
-    }
-    const out = names.filter((n) => n.endsWith('.md')).map((n) => path.join(dir, n));
-    out.sort();
-    return out;
-}
-
-/** The always-full-bodied set — authoritative kernel list from the router. */
-export function kernel_ids(): Set<string> {
-    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8')) as Record<string, unknown>;
-    const kernel = data.kernel;
-    if (Array.isArray(kernel)) {
-        return new Set(kernel.map((x) => String(x)));
-    }
-    return new Set();
-}
-
-/**
- * Tier rules the router gives NO trigger at all.
- *
- * These cannot be delivered on a match, so thinning them would remove a body
- * that nothing can ever put back — a silent hole rather than a saving. They
- * project full-bodied, and `measure` reports them by name so the residue is
- * visible instead of being absorbed into the pointer count
- * (road-to-trigger-delivered-rule-bodies 1.3).
- */
-/**
- * Rules whose ONLY triggers are path-shaped — reachable from `pre_tool_use`
- * and from no other slot (road-to-delivery-for-every-host 3.2).
- *
- * They must never be thinned while the delivery concern is NOT bound on
- * `pre_tool_use`, because a stub plus a slot nobody listens on is a rule that
- * reaches the model at no scope at all. This is the same failure the
- * `no_trigger_ids` exemption prevents, one step out: there the rule has nothing
- * to match on, here it has nothing to match ON.
- *
- * Stated as a PROPERTY rather than a list of ids. If the concern is ever bound
- * on `pre_tool_use` again, this exemption is what should be reconsidered — not
- * three names someone has to remember.
- *
- * WHAT THIS EXEMPTION DOES **NOT** COVER — recorded 2026-09-08, R2 finding 1,
- * because the silence read as coverage. The predicate is `every` trigger
- * path-shaped. A rule with BOTH path and non-path triggers is therefore THINNED,
- * and its path-shaped half then has no carrier at all: the stub carries no
- * frontmatter (`condense.ts` writes it with `_writeText`, bypassing
- * `_emit_claude_rule`'s host-native `paths:` key), `pre_tool_use` lost the
- * binding under owner ruling E2, and `user_prompt_submit` never populates
- * `openFiles`. Measured over the current `dist/router.json`: **18 such rules**,
- * all non-kernel and all thinned — augment-edit-discipline, design-fidelity,
- * doc-screenshot-hygiene, domain-adoption-policy,
- * framework-neutrality-in-generic-skills, image-likeness-and-rights,
- * laravel-translations, lethal-trifecta-guard, linked-projects-onboarding-gate,
- * low-impact-corpus-privacy-floor, markdown-safe-codeblocks, onboarding-gate,
- * persona-governance, php-coding, provider-lifecycle-discipline,
- * roadmap-ci-steps-policy, roadmap-progress-sync, settings-ask-protocol.
- *
- * They do NOT reach the model at no scope: every non-path route
- * (keyword / phrase / command) still delivers the body through the concern, and
- * on `claude-code` they never had a separate host-native path route to lose —
- * `_claude_paths_plan` emits no `paths:` for a mixed-trigger rule on purpose, so
- * under `eager-all` they loaded UNCONDITIONALLY. What is lost is the difference
- * between unconditional and prompt-triggered: a session that touches a matching
- * file and says nothing that matches gets nothing.
- *
- * The labelled corpus cannot see this and the endpoint says so rather than
- * implying otherwise — `model_rule_injection --endpoints` (b) now publishes the
- * shipped `user_prompt_submit` reach beside the pre-registered reading, and
- * every one of these 18 has at least one prompt-matching positive, so none
- * appears in its "reachable only via a path trigger" column.
- *
- * WHY THIS IS NOT WIDENED TO `some` HERE. Measured: exempting all 18 moves the
- * thin rule layer 23,592 -> 39,921 GPT tok (+16,329, +69 %), which is a budget
- * move of a magnitude no agent may take, and it would erase most of the saving
- * the flip is licensed on. Restoring a path route needs either that exemption
- * under a re-anchored baseline or a `pre_tool_use` binding under a raised slot
- * cap — both owner-reserved, so the closure is tracked rather than taken here.
- * ADR-267's Consequences section names the receiver.
- */
 /**
- * ONE spelling of the router-derived sets, shared with the injector (R2
- * finding 11).
- *
- * `path_only_ids` and `no_trigger_ids` were each a second, hand-rolled
- * implementation of `_lib/rule_injection.ts::pathOnlyRuleIds` /
- * `triggerlessRuleIds` — verified identical over the current router at the time
- * (symmetric difference empty), so drift risk rather than a live defect. It is
- * exactly the hazard `THIN_ENTRY_MARKER`'s own comment argues against one
- * screen below ("a gate that re-spelled this string would drift from the writer
- * silently"), and the two consumers here are the PROJECTOR's exemption set and
- * the INJECTOR's reachability set: they must not be able to disagree about which
- * rules the delivery path can reach.
+ * The mechanism lives in `_lib/thin_rules.ts`; this file is its CLI.
  *
- * The finding named `path_only_ids`. The defect-pattern sweep found the SECOND
- * instance one function down — `no_trigger_ids` against `triggerlessRuleIds` —
- * and it is delegated in the same change. Count: 2 of 2 duplicated
- * router-derived sets in this file, 0 remaining.
- */
-function _router(): Router {
-    return JSON.parse(fs.readFileSync(ROUTER, 'utf-8')) as Router;
-}
-
-export function path_only_ids(): Set<string> {
-    return pathOnlyRuleIds(_router());
-}
-
-export function no_trigger_ids(): Set<string> {
-    return new Set(triggerlessRuleIds(_router()));
-}
-
-/**
- * id → workspaces for every non-kernel router entry (router.json schema v2,
- * road-to-request-scoped-rule-load Phase 1). Rules absent from the map (or
- * with an empty list) fail safe: they stay in scope.
+ * Re-exported wholesale so every existing importer of
+ * `project_thin_rules.{build_thin,thin_entry,is_thin_entry,RULES_SOURCE,…}`
+ * keeps working unchanged. The split exists because `src/scripts/install.ts` is
+ * a bundle entry and `check_installer_import_purity` forbids it reaching a
+ * module-level `process.exit()` — which this file has, at its foot, by design.
  */
-export function rule_workspaces_map(): Map<string, string[]> {
-    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8')) as Record<string, unknown>;
-    const map = new Map<string, string[]>();
-    for (const tier of ['tier_1', 'tier_2']) {
-        const entries = data[tier];
-        if (!Array.isArray(entries)) continue;
-        for (const e of entries) {
-            const obj = e as Record<string, unknown>;
-            const ws = Array.isArray(obj.workspaces) ? obj.workspaces.map((w) => String(w)) : [];
-            map.set(String(obj.id), ws);
-        }
-    }
-    return map;
-}
-
-/**
- * Whether a rule id survives a workspace scope. Kernel always survives;
- * `scope === null` = legacy-all. An out-of-scope non-kernel rule is dropped
- * entirely — neither body nor pointer line (the pointer floor shrinks with
- * consumer scoping).
- */
-export function id_in_scope(
-    rule_id: string,
-    scope: readonly string[] | null,
-    kernel: ReadonlySet<string>,
-    wsMap: ReadonlyMap<string, string[]>,
-    fallback_ws: readonly string[] = [],
-): boolean {
-    if (scope === null || kernel.has(rule_id)) {
-        return true;
-    }
-    // Router map first (schema v2); `type: manual` rules are reference-only
-    // and never emitted to the router — their frontmatter is the fallback.
-    const ws = wsMap.get(rule_id) ?? fallback_ws;
-    if (ws.length === 0) {
-        return true; // untagged / unknown → fail safe
-    }
-    return ws.some((w) => scope.includes(w));
-}
-
-/** `workspaces:` list parsed straight from a rule file's frontmatter. */
-export function fm_workspaces(text: string): string[] {
-    const [fm] = split_frontmatter(text);
-    // Flow style: `workspaces: [a, b, c]`
-    const flow = /^workspaces:[ \t]*\[([^\]]*)\]/m.exec(fm);
-    if (flow) {
-        return (flow[1] as string)
-            .split(',')
-            .map((s) => s.trim().replace(/^["']|["']$/g, ''))
-            .filter((s) => s.length > 0);
-    }
-    // Block style; tolerate the list being the LAST frontmatter key.
-    const m = /^workspaces:[ \t]*\n((?:[ \t]+-[ \t]+.*(?:\n|$))+)/m.exec(fm);
-    if (!m) {
-        return [];
-    }
-    return [...(m[1] as string).matchAll(/-[ \t]+(\S+)/g)].map((x) => x[1] as string);
-}
-
-/** Return [frontmatter_including_fences, body]. Empty fm if none. */
-export function split_frontmatter(text: string): [string, string] {
-    if (text.startsWith('---\n')) {
-        const end = text.indexOf('\n---\n', 4);
-        if (end !== -1) {
-            return [text.slice(0, end + 5), text.slice(end + 5)];
-        }
-    }
-    return ['', text];
-}
-
-function _description(fm: string): string {
-    // re.search(r'^description:\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
-    const m = /^description:\s*"?(.+?)"?\s*$/m.exec(fm);
-    return m ? (m[1] as string).trim() : '';
-}
-
-// How many trigger keywords/phrases to surface as the always-on match hint.
-const _TRIGGER_HINT_LIMIT = 6;
-
-/** A short, comma-joined sample of the rule's trigger keywords/phrases. */
-function _trigger_hint(fm: string): string {
-    const hits: string[] = [];
-    // re.finditer(r'^\s*-\s*(?:keyword|phrase):\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
-    const re = /^\s*-\s*(?:keyword|phrase):\s*"?(.+?)"?\s*$/gm;
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(fm)) !== null) {
-        hits.push((m[1] as string).trim());
-        if (hits.length >= _TRIGGER_HINT_LIMIT) {
-            break;
-        }
-    }
-    return hits.join(', ');
-}
-
-/** Python `str.title()` — uppercase first alpha of each run, rest lowercase. */
-function _title(s: string): string {
-    return s.replace(/[A-Za-z]+/g, (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
-}
-
-/**
- * The marker that makes a projected entry recognisable as a stub.
- *
- * Exported so the WRITER and every DETECTOR share one definition. A gate that
- * re-spelled this string would drift from the writer silently, and the failure
- * would be invisible in exactly the direction that matters: a stub the gate
- * fails to recognise reads as a complete rule body.
- */
-export const THIN_ENTRY_MARKER = '> Routed rule — load the body on trigger-match.';
-
-/** Is this projected entry a pointer stub rather than a rule body? */
-export function is_thin_entry(text: string): boolean {
-    return text.includes(THIN_ENTRY_MARKER);
-}
-
-/**
- * Where a stub tells a reader the body actually is.
- *
- * FIXED 2026-09-07: this pointed into the uncondensed source tree ADR-051
- * retired — the literal path is deliberately NOT reproduced here, because
- * `check_no_uncondensed_refs` matches the string and cannot tell a repair
- * record from a live reference; `git log -S` on this file finds the old value.
- * It exists in no checkout, so EVERY stub's fallback pointer
- * resolved to nothing — invisible under `delivery`, where the hook loads the
- * body from `dist/agent-src/rules` and never follows this link, and total under
- * `thin`, where the pointer is the only path to the body there is.
- *
- * KNOWN LIMIT, stated rather than discovered later: one relative prefix cannot
- * be right for every tree, because they sit at different depths — `.claude/rules`
- * and `.cursor/rules` are two levels below the repo root and `.clinerules` is
- * one. `../../` is correct for the first two, which are the only trees the
- * shipped `lean_projection.hosts` default can thin. A stub in `.clinerules`
- * needs an operator to have added `cline` to that list, and its pointer is off
- * by one level. That is strictly better than the previous state, where the
- * pointer was dead in all three, and it is recorded here so the remaining case
- * is a known limit rather than a surprise.
- */
-const BODY_LINK_PREFIX = '../../dist/agent-src/rules/';
-
-/** Build the minimal progressive-disclosure pointer for a non-kernel rule. */
-export function thin_entry(rule_id: string, text: string): string {
-    const [fm] = split_frontmatter(text);
-    const desc = _description(fm);
-    const hint = _trigger_hint(fm);
-    const title = _title(rule_id.replace(/-/g, ' '));
-    const fires = hint ? ` Fires on: ${hint}.` : '';
-    return (
-        `## ${title}\n` +
-        `${THIN_ENTRY_MARKER}${fires} ${desc} ` +
-        `Body: [\`${rule_id}\`](${BODY_LINK_PREFIX}${rule_id}.md)\n`
-    );
-}
+export * from './_lib/thin_rules.js';
+import {
+    _globSortedMd,
+    build_thin,
+    fm_workspaces,
+    id_in_scope,
+    kernel_ids,
+    no_trigger_ids,
+    REPO_ROOT,
+    RULES_SOURCE,
+    rule_workspaces_map,
+} from './_lib/thin_rules.js';
+void REPO_ROOT;
 
-/** Map {filename: thin_or_full_text} for every rule. Kernel stays full. */
-export function build_thin(
-    rules_dir: string = RULES_SOURCE,
-    scope: readonly string[] | null = null,
-    /**
-     * Optional sink for the D3 diagnostic
-     * (road-to-delivery-for-every-host 2.2).
-     *
-     * An `auto` rule the router gives NO trigger is already kept full-bodied by
-     * `noTrigger` below, which is the substantive protection and predates this
-     * roadmap. What did not exist is any way to SEE it happen: the rule is
-     * silently exempted, so an author who removes a rule's last trigger gets a
-     * silently eager rule and no signal. The line makes the exemption audible.
-     */
-    announce: ((message: string) => void) | null = null,
-): Map<string, string> {
-    const kernel = kernel_ids();
-    const noTrigger = no_trigger_ids();
-    const pathOnly = path_only_ids();
-    const wsMap = scope !== null ? rule_workspaces_map() : new Map<string, string[]>();
-    const out = new Map<string, string>();
-    for (const p of _globSortedMd(rules_dir)) {
-        const text = fs.readFileSync(p, 'utf-8');
-        const stem = path.basename(p).replace(/\.md$/, '');
-        if (!id_in_scope(stem, scope, kernel, wsMap, fm_workspaces(text))) {
-            continue; // out of workspace scope — no body, no pointer line
-        }
-        const full = kernel.has(stem) || noTrigger.has(stem) || pathOnly.has(stem);
-        if (announce !== null && noTrigger.has(stem) && !kernel.has(stem)) {
-            announce(`D3: trigger-less auto rule ${path.basename(p)} — kept full-bodied, never thinned`);
-        }
-        if (announce !== null && pathOnly.has(stem) && !kernel.has(stem) && !noTrigger.has(stem)) {
-            announce(
-                `E2: path-only auto rule ${path.basename(p)} — kept full-bodied; its only triggers ` +
-                    `are path-shaped and the delivery concern is not bound on pre_tool_use`,
-            );
-        }
-        out.set(path.basename(p), full ? text : thin_entry(stem, text));
-    }
-    return out;
-}
+const _HERE = fileURLToPath(import.meta.url);
 
 export interface ThinMeasure {
     rules_total: number;
     kernel_full: number;
+    /**
+     * Everything non-kernel that the no-trigger residue does not claim — which
+     * is NOT the same as everything actually thinned, and the gap grew with the
+     * `no_stub` subset. The path-only residue and the declared `no_stub`
+     * members project full-bodied and are counted here anyway, because the
+     * field's identity (`rules_total = kernel_full + non_kernel_thinned +
+     * no_trigger_full`) is pinned by a test and is what the CLI's own line
+     * arithmetic rests on. Named rather than silently widened: for the real
+     * thinned count, ask `build_thin` and filter on {@link is_thin_entry}.
+     */
     non_kernel_thinned: number;
     /** Non-kernel rules kept full-bodied because the router gives them no trigger. */
     no_trigger_full: number;

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.
  *