@event4u/agent-config 16.3.0 → 16.4.0

package/src/scripts/check_gate_coverage.ts

@@ -30,7 +30,8 @@
  * definition. It runs the same contract as the review-side canary in
  * `docs/contracts/adversarial-review-protocol.md` § 6 (rotating class, sealed
  * record, NEVER SHIPS) and is deliberately kept OFF the default CI path: it
- * mutates the tree, so it is an operator-invoked biannual experiment, not a
+ * mutates the tree, so it is a scheduled experiment (`.github/workflows/gate-canary.yml`,
+ * monthly, ledger uploaded as a run artifact) or an operator run, never a
  * per-PR gate. Every plant is reverted in a `finally`.
  *
  * CLI:
@@ -415,8 +416,8 @@ function report_negative_control_inventory(specs: readonly GateSpec[]): void {
   // The arithmetic is the guard against skimming: two numbers that reconcile
   // against the enforced total cannot be read as "all of them checked".
   process.stdout.write(
-    `  ⚠️  declared, not run — the mutating --canary path is operator-invoked and off the per-PR workflow, ` +
-      `so no negative control ran here.\n`,
+    `  ⚠️  declared, not run — the mutating --canary path is off the per-PR workflow (it runs monthly ` +
+      `in .github/workflows/gate-canary.yml), so no negative control ran here.\n`,
   );
   for (const s of without) {
     process.stdout.write(`  · ${s.id}: ${s.no_canary_reason ?? '(no reason recorded)'}\n`);

package/src/scripts/check_gate_reachability.ts

@@ -42,6 +42,7 @@ import {
     resetSourceCache,
     type InventoryVerdict,
 } from './_lib/loop_surfaces.js';
+import { analyseModuleReach, groupCounts } from './_lib/module_reach.js';
 
 const REPO_ROOT = process.cwd();
 const TASKFILES_DIR = 'taskfiles';
@@ -312,6 +313,10 @@ function runGate(root: string): number {
         units: 'exemption row(s) + unreachable target(s) + declared loop instrument(s)',
         roots: [EXEMPTIONS_REL, INVENTORY_REL, ROOT_TASKFILE, TASKFILES_DIR],
     });
+    // Phase 3.1 of road-to-modules-that-something-calls.md: five numbers beside
+    // this gate's existing verdicts, printed whether the gate passes or fails —
+    // reported, enforcing nothing, the way the estate gate prints its draft count.
+    process.stdout.write(moduleReachLine(moduleReachSummary(root)));
     const inventoryClean = inv.shape.length === 0 && inv.reach.length === 0;
     if (v.unreasoned.length === 0 && v.stale.length === 0 && inventoryClean) {
         process.stdout.write(
@@ -506,13 +511,54 @@ function selfTest(): number {
     }
 }
 
+export interface ModuleReachSummary {
+    /** The four group counts — the roadmap's "four group counts", over the unreferenced-by-name set only. */
+    groups: Record<'contract-test' | 'open-or-deferred-step' | 'named-outside-open-step' | 'named-in-none', number>;
+    /** "the total of modules reached by nothing" (import edges + run-by-path) — the fifth number. */
+    reachedByNothing: number;
+    /**
+     * Not one of the five — the size of the unreferenced-by-name set the four
+     * groups partition. Kept on the summary because it is a free cross-check
+     * (it must equal the sum of `groups`); never printed as a sixth number.
+     */
+    unreferencedTotal: number;
+}
+
+/**
+ * The five module-reach numbers (road-to-modules-that-something-calls.md
+ * Phase 3.1) — reported beside this gate's own verdicts, the way the estate
+ * gate prints its draft-roadmap count: a number that moves in a change's own
+ * gate output, enforcing nothing.
+ */
+export function moduleReachSummary(root: string): ModuleReachSummary {
+    const { modules } = analyseModuleReach(root);
+    const unreferenced = modules.filter((m) => !m.namedByProduction);
+    return {
+        groups: groupCounts(unreferenced),
+        reachedByNothing: modules.filter((m) => !m.reachedByImportOrPath).length,
+        unreferencedTotal: unreferenced.length,
+    };
+}
+
+export function moduleReachLine(s: ModuleReachSummary): string {
+    return (
+        `module reach (reported, not gated), src/scripts/_lib: ` +
+        `contract-test ${String(s.groups['contract-test'])} · ` +
+        `open-or-deferred-step ${String(s.groups['open-or-deferred-step'])} · ` +
+        `named-outside-open-step ${String(s.groups['named-outside-open-step'])} · ` +
+        `named-in-none ${String(s.groups['named-in-none'])} · ` +
+        `REACHED-BY-NOTHING total ${String(s.reachedByNothing)}\n`
+    );
+}
+
 export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT): number {
     if (argv.includes('--self-test')) return selfTest();
     if (argv.includes('--gate')) return runGate(root);
     const r = analyse(root);
     const inv = inventoryVerdict(root);
+    const moduleReach = moduleReachSummary(root);
     if (argv.includes('--json')) {
-        process.stdout.write(`${JSON.stringify({ ...r, inventory: inv }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ...r, inventory: inv, moduleReach }, null, 2)}\n`);
         return 0;
     }
     // Emitted on the DEFAULT invocation too, not only under `--gate`: the
@@ -538,6 +584,7 @@ export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT):
             `prose-bound surfaces ${String(inv.proseBound.length)}\n`,
     );
     for (const f of inv.reach) process.stdout.write(`  · ${f.id} — ${f.detail}\n`);
+    process.stdout.write(moduleReachLine(moduleReach));
     return 0;
 }
 

package/src/scripts/check_generator_sync.ts

@@ -546,11 +546,59 @@ const HOST_LOWERING_TRIPLE: Triple = {
     },
 };
 
+const GRAMMAR_REFERENCE = 'src/skills/git-workflow/references/commit-subject.md';
+const GRAMMAR_GENERATOR = 'src/scripts/generate_git_convention_grammar.ts';
+
+/**
+ * The commit-subject reference is the fallback a command reads when the
+ * `agent-config` binary cannot run, so its grammar block has to be the grammar
+ * the binary runs. The page itself is a source too: a hand edit to the block is
+ * the drift this row exists to catch.
+ */
+const GIT_CONVENTION_GRAMMAR_TRIPLE: Triple = {
+    id: 'git-convention-grammar',
+    output: GRAMMAR_REFERENCE,
+    remedy: './scripts-run src/scripts/generate_git_convention_grammar',
+    why: 'the reference carries a grammar and measurement block rendered from the modules the git:convention verb runs',
+    sourcesOf() {
+        return {
+            ok: true,
+            sources: [
+                { kind: 'file', value: 'src/scripts/_lib/git_convention_grammar.ts' },
+                { kind: 'file', value: 'src/scripts/_lib/git_convention_measure.ts' },
+                { kind: 'file', value: GRAMMAR_GENERATOR },
+                { kind: 'file', value: GRAMMAR_REFERENCE },
+            ],
+        };
+    },
+    regenerate(root, workDir) {
+        const outFile = path.join(workDir, 'commit-subject.md');
+        const tsx = path.join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'tsx.cmd' : 'tsx');
+        if (!fs.existsSync(tsx)) {
+            return { ok: false, reason: `no tsx at ${path.relative(root, tsx)} — run \`npm ci\` before this gate` };
+        }
+        const res = spawnSync(tsx, [path.join(root, GRAMMAR_GENERATOR), '--out', outFile], {
+            cwd: root,
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        if (res.status !== 0) {
+            return { ok: false, reason: `generate_git_convention_grammar exited ${String(res.status)}: ${(res.stderr ?? '').trim()}` };
+        }
+        try {
+            return { ok: true, text: fs.readFileSync(outFile, 'utf8') };
+        } catch (e) {
+            return { ok: false, reason: `generate_git_convention_grammar reported success but wrote no readable file (${String(e)})` };
+        }
+    },
+};
+
 export const REGISTRY: readonly Triple[] = [
     CENSUS_TRIPLE,
     INSTALL_BUNDLE_TRIPLE,
     HOOK_MANIFEST_TRIPLE,
     HOST_LOWERING_TRIPLE,
+    GIT_CONVENTION_GRAMMAR_TRIPLE,
 ];
 
 // ---------------------------------------------------------------------------

package/src/scripts/check_hook_bundle_composition.ts

@@ -191,6 +191,95 @@ export function verdict(a: Analysis, budget: Budget): string[] {
     return findings;
 }
 
+/**
+ * The raise rule, enforced against the base revision.
+ *
+ * `road-to-a-ratification-fence-that-follows-its-imports` 3.2. The budget's
+ * `shrink_only_note` used to say a raise needs a `raise_log` entry and that
+ * "the gate prints the rule but cannot enforce it, because a raise and a
+ * lowering are the same edit to a number". Against the base revision they are
+ * not: a working `max_bytes` above the base's is a raise, and it passes only if
+ * `raise_log` gained an entry — one absent from the base's log — whose `to`
+ * equals the new ceiling. A lowering needs nothing. The comparison is the
+ * merged value against the base, because that is what ships; a ceiling raised
+ * and lowered inside one branch is judged by where it ends.
+ *
+ * `baseRaw` is the base revision's budget file, or `null` when it has none
+ * (the registration diff), which is not a raise.
+ */
+export function raiseFindings(baseRaw: string | null, workingRaw: string): string[] {
+    if (baseRaw === null) {
+        return [];
+    }
+    const base = JSON.parse(baseRaw) as Record<string, unknown>;
+    const working = JSON.parse(workingRaw) as Record<string, unknown>;
+    const baseMax = base['max_bytes'];
+    const workingMax = working['max_bytes'];
+    if (typeof baseMax !== 'number' || typeof workingMax !== 'number' || workingMax <= baseMax) {
+        return [];
+    }
+    const baseLog = Array.isArray(base['raise_log']) ? (base['raise_log'] as unknown[]) : [];
+    const workingLog = Array.isArray(working['raise_log']) ? (working['raise_log'] as unknown[]) : [];
+    const seen = new Set(baseLog.map((e) => JSON.stringify(e)));
+    const gained = workingLog.filter((e) => !seen.has(JSON.stringify(e)));
+    const matching = gained.find((e) => isRecord(e) && e['to'] === workingMax);
+    if (matching === undefined) {
+        return [
+            `max_bytes raised from ${String(baseMax)} to ${String(workingMax)} against the base revision ` +
+                `with no new raise_log entry whose \`to\` is ${String(workingMax)}. A raise needs a recorded ` +
+                `reason in ${BUDGET_REL}'s raise_log naming what was added and why it could not be avoided.`,
+        ];
+    }
+    const problems = raiseEntryProblems(matching as Record<string, unknown>, baseMax);
+    return problems.length === 0
+        ? []
+        : [`the raise_log entry for ${String(workingMax)} is incomplete: ${problems.join('; ')}.`];
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** The prose fields an entry must carry, matching the entry the log already holds. */
+const RAISE_REASON_FIELDS = ['what_was_added', 'why_it_could_not_be_avoided'] as const;
+
+/**
+ * What a raise entry must say. A bare `{ "to": N }` matched the first version
+ * of this rule, which a ratification reviewer refused on: a log entry with no
+ * reason is the empty log the rule exists to refuse, wearing a key.
+ */
+export function raiseEntryProblems(entry: Record<string, unknown>, baseMax: number): string[] {
+    const problems: string[] = [];
+    if (entry['from'] !== baseMax) {
+        problems.push(`\`from\` must be the base ceiling ${String(baseMax)}`);
+    }
+    if (typeof entry['date'] !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(entry['date'])) {
+        problems.push('`date` must be YYYY-MM-DD');
+    }
+    for (const field of RAISE_REASON_FIELDS) {
+        const v = entry[field];
+        if (typeof v !== 'string' || v.trim().length < 20) {
+            problems.push(`\`${field}\` must say what happened, in at least a sentence`);
+        }
+    }
+    return problems;
+}
+
+/** The base revision's budget file, `null` when absent there, `undefined` when no base resolves. */
+function readBaseBudget(root: string, explicit: string | undefined): string | null | undefined {
+    const candidates = explicit !== undefined ? [explicit] : ['origin/main', 'main'];
+    for (const ref of candidates) {
+        const ok = spawnSync('git', ['rev-parse', '--verify', '--quiet', ref], {
+            cwd: root,
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        if (ok.status !== 0) continue;
+        const shown = spawnSync('git', ['show', `${ref}:${BUDGET_REL}`], { cwd: root, encoding: 'utf-8' });
+        return shown.status === 0 ? shown.stdout : null;
+    }
+    return undefined;
+}
+
 /**
  * Build the hook bundle to a throwaway path and return its metafile JSON.
  *
@@ -331,6 +420,24 @@ export function main(argv: readonly string[] = process.argv.slice(2), root: stri
     }
 
     const findings = verdict(analysis, budget);
+    const baseAt = argv.indexOf('--base-ref');
+    const baseBudget = readBaseBudget(root, baseAt >= 0 ? argv[baseAt + 1] : undefined);
+    if (baseBudget === undefined) {
+        // In CI an unresolvable base is a broken checkout, not a registration
+        // diff: refusing there is the difference between a rule and a notice.
+        // Locally a missing base is ordinary (a fresh clone without origin), so
+        // it is said rather than failed.
+        if (process.env['GITHUB_ACTIONS'] === 'true') {
+            process.stderr.write(
+                'check_hook_bundle_composition: no base revision resolved in CI — the max_bytes raise ' +
+                    'rule cannot be evaluated, and this gate fails closed rather than skip it\n',
+            );
+            return 2;
+        }
+        process.stdout.write('raise rule: no base revision resolved — the max_bytes raise check was not evaluated\n');
+    } else {
+        findings.push(...raiseFindings(baseBudget, fs.readFileSync(path.join(root, BUDGET_REL), 'utf-8')));
+    }
     // Reported on BOTH paths, red included: a census that goes quiet exactly
     // when the gate fires is the shape `reportScanned` exists to prevent.
     reportScanned({

package/src/scripts/check_kernel_edit_ratified.ts

@@ -33,8 +33,10 @@
  * hook plumbing — the YAML sources `hook_manifest.yaml` and
  * `host_lowering.yaml`, their compiled siblings `hook_manifest.json` and
  * `host_lowering.json`, the dispatcher `hooks/dispatch_hook.ts`, the
- * kernel-rule list `_lib/kernel_rules.ts`, a `*-dispatcher.sh`, either hook
- * budget file (see `PLUMBING_SOURCE_RE`) — or this gate itself, so it cannot
+ * kernel-rule list `_lib/kernel_rules.ts`, a `*-dispatcher.sh`, the token,
+ * latency and bundle budget files (see `PLUMBING_SOURCE_RE`), and every module
+ * the dispatcher imports that decides an exit code (derived at run time, see
+ * `derivedPlumbing`) — or this gate itself, so it cannot
  * be weakened without its own record. Such a diff must carry a ratification
  * artifact under the ratifications directory with `verdict: ratified`, valid
  * per the ratification-artifact contract.
@@ -73,6 +75,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { GateLedger } from './_lib/gate_ledger.js';
+import { dispatchImportClosure, verdictModules } from './_lib/dispatch_import_closure.js';
 import { is_kernel_rule } from './_lib/kernel_rules.js';
 import { reportScanned } from './_lib/scan_scope.js';
 import {
@@ -92,6 +95,13 @@ export const SELF_PATH = 'src/scripts/check_kernel_edit_ratified.ts';
 /** The reader this gate shares with the artifact contract, also self-watched. */
 export const READER_PATH = 'src/scripts/_lib/ratification_artifact.ts';
 
+/**
+ * The reader that derives the dispatcher's verdict-deciding imports. It decides
+ * part of this gate's reach, so narrowing it is narrowing the gate — watched as
+ * part of the mechanism for the reason `READER_PATH` is.
+ */
+export const CLOSURE_READER_PATH = 'src/scripts/_lib/dispatch_import_closure.ts';
+
 /** The in-repo quorum policy. Present on every runner; absent means refuse. */
 export const POLICY_PATH = 'src/config/ratification-policy.json';
 
@@ -185,7 +195,67 @@ const GOVERNANCE_HOOK_RE = /^src\/scripts\/hooks\/block_[a-z0-9_]+\.ts$/;
  * is the diff where only the JSON moves.
  */
 const PLUMBING_SOURCE_RE =
-    /^(?:src\/scripts\/hook_manifest\.(?:yaml|json)|src\/scripts\/hooks\/host_lowering\.(?:yaml|json)|src\/scripts\/hooks\/dispatch_hook\.ts|src\/scripts\/_lib\/kernel_rules\.ts|src\/scripts\/hooks\/[a-z0-9-]+-dispatcher\.sh|src\/config\/hook-(?:token|latency)-budget\.json)$/;
+    /^(?:src\/scripts\/hook_manifest\.(?:yaml|json)|src\/scripts\/hooks\/host_lowering\.(?:yaml|json)|src\/scripts\/hooks\/dispatch_hook\.ts|src\/scripts\/_lib\/kernel_rules\.ts|src\/scripts\/hooks\/[a-z0-9-]+-dispatcher\.sh|src\/config\/hook-(?:token|latency|bundle)-budget\.json)$/;
+
+/**
+ * The derived half of the plumbing set: every module in the static import
+ * closure of `dispatch_hook.ts` that decides an exit code or a refusal, read by
+ * `_lib/dispatch_import_closure.ts`.
+ *
+ * `road-to-a-ratification-fence-that-follows-its-imports` 2.2. The pattern
+ * above stayed correct until `_resolve_execution_failure` moved from the
+ * dispatcher into `concern_failure_policy.ts` — release finding `21900086c1a0`:
+ * a diff deciding whether a crashed blocking concern refuses then carried no
+ * record. A hand list fails the same way the next time a function moves, so
+ * this half is computed from the import graph at run time, and a module the
+ * dispatcher newly imports that names an exit code joins it with no edit here.
+ * Concerns stay outside: the walk stops at the concern table, and a governance
+ * concern is already gated by `GOVERNANCE_HOOK_RE`.
+ *
+ * `hook-bundle-budget.json` joins the pattern for D3: its ceiling was raised on
+ * its own registration day, and a raised ceiling is a looser budget reached one
+ * file earlier than the bundle it bounds.
+ */
+let _repoDerived: readonly string[] | null = null;
+export function derivedPlumbing(root: string = REPO): readonly string[] {
+    if (root === REPO) {
+        _repoDerived ??= verdictModules(REPO);
+        return _repoDerived;
+    }
+    return verdictModules(root);
+}
+
+/**
+ * Modules that ARRIVE in the dispatcher's closure: non-concern modules present
+ * in the closure under `root` and absent from the closure under `baseRoot`.
+ *
+ * The classifier reads names, so a verdict-deciding module with neutral names
+ * (`acceptsExecution(): boolean`, no exit constant) reads as `payload` or
+ * `neither` — the gap the first ratification round of this change refused it
+ * on. A name-based classifier cannot close that gap; what can is watching the
+ * one moment such a module becomes reachable. So any module newly reachable
+ * from the dispatcher is gated on the diff that makes it reachable, whatever
+ * its class, and a reviewer reads it once. Modules already in the base closure
+ * are judged by class, so routine edits to a payload helper stay record-free.
+ *
+ * The other direction needs no extra rule: a module the base classes as
+ * `verdict` stays watched through the union in `evaluate` even when the head
+ * strips the names that classed it, so declassifying one is itself a gated
+ * edit of it.
+ *
+ * Meaningful only where the two trees differ — in CI, where the gate's code is
+ * the base revision's and `root` is the head. A local run with `root` equal to
+ * the gate's own tree sees no arrivals, and says nothing it cannot measure.
+ */
+export function closureArrivals(root: string, baseRoot: string = REPO): string[] {
+    if (path.resolve(root) === path.resolve(baseRoot)) {
+        return [];
+    }
+    const base = new Set(dispatchImportClosure(baseRoot).map((e) => e.path));
+    return dispatchImportClosure(root)
+        .filter((e) => e.class !== 'concern' && !base.has(e.path))
+        .map((e) => e.path);
+}
 
 /**
  * A kernel rule, in the source tree or in any projection.
@@ -212,7 +282,11 @@ export interface GatedPaths {
 }
 
 /** Partition a changed-file list into the surfaces this gate watches. */
-export function classifyPaths(files: readonly string[]): GatedPaths {
+export function classifyPaths(
+    files: readonly string[],
+    derived: readonly string[] = derivedPlumbing(),
+): GatedPaths {
+    const derivedSet = new Set(derived);
     const kernelRules: string[] = [];
     const governanceHooks: string[] = [];
     const plumbing: string[] = [];
@@ -225,6 +299,7 @@ export function classifyPaths(files: readonly string[]): GatedPaths {
         if (
             p === SELF_PATH ||
             p === READER_PATH ||
+            p === CLOSURE_READER_PATH ||
             p === POLICY_PATH ||
             p === WORKFLOW_PATH ||
             ANCHOR_PATHS.includes(p)
@@ -241,7 +316,7 @@ export function classifyPaths(files: readonly string[]): GatedPaths {
             governanceHooks.push(p);
             continue;
         }
-        if (PLUMBING_SOURCE_RE.test(p)) {
+        if (PLUMBING_SOURCE_RE.test(p) || derivedSet.has(p)) {
             plumbing.push(p);
         }
     }
@@ -319,7 +394,12 @@ export function evaluate(
     providerCount: number | null,
 ): GateResult {
     const lines: string[] = [];
-    const gated = classifyPaths(files);
+    // The union of the closure read from the tree under review and from this
+    // script's own tree: under CI the gate code is the base revision's and
+    // `root` is the head, so a module present on either side is watched.
+    const gated = classifyPaths(files, [
+        ...new Set([...derivedPlumbing(), ...derivedPlumbing(root), ...closureArrivals(root)]),
+    ]);
     const scanned = files.length;
 
     // Every changed path is a planned target: the gate's denominator is the

package/src/scripts/check_pack_size.ts

@@ -332,7 +332,7 @@ export function payloadFingerprint(entryPath: string, size: number): string {
  * convention and the class is empty by observation.
  */
 const BOUND_PAYLOAD_EXCEPTIONS: readonly BoundPayloadException[] = [
-    { fingerprint: '47e4328e71652a0375ade7eb4dac8a3e4b6df1c6e4e74caa75287266676cc9a6', path: 'agents/templates/.ai-council.yml.example', size: 30561, why: 'shipped council config TEMPLATE — a dotfile because the file it is copied to is one. RE-PINNED 2026-09-07, 29,872 -> 30,561 bytes: the exception is path-AND-size-bound by design, so this branch adding a `disabled_reason` honest-null block to the gemini seat in the template invalidated it and the gate refused the entry as unaccounted. The re-pin excepts the SAME path for the SAME reason at its measured new size — it does not widen the class, raise a cap, or except anything the gate was not already carrying.' },
+    { fingerprint: '6de9a60d02af4883ab8f09171673a44924ca78ddadd55518f743e95651d3d257', path: 'agents/templates/.ai-council.yml.example', size: 31548, why: 'shipped council config TEMPLATE — a dotfile because the file it is copied to is one. RE-PINNED 2026-10-06, 30,561 -> 31,548 bytes: the exception is path-AND-size-bound by design, so step 3.1 of road-to-a-spend-bound-only-where-one-was-set moving the template cost_budget and debate ceilings to 0 (ADR-279), removing the stale "always asks before invoking" sentence and explaining both invalidated it and the gate refused the entry as unaccounted. The re-pin excepts the SAME path for the SAME reason at its measured new size — it does not widen the class, raise a cap, or except anything the gate was not already carrying. (Previously RE-PINNED 2026-09-07, 29,872 -> 30,561 bytes, for a `disabled_reason` honest-null block on the gemini seat.)' },
     { fingerprint: 'd36a53951c184db7481139235056e90b53a853714b3a68b31ba1349ecb95ac1d', path: 'agents/templates/.ai-video.xml.example', size: 9209, why: 'shipped video-provider config template — same reason as the council template' },
     { fingerprint: 'f83229412cf8cceaadd0cb1934140a0c7c8277df43edc590f370572f6df6da98', path: 'dist/agent-src/templates/agents/.gitattributes.fragment', size: 2140, why: 'gitattributes fragment the installer appends to a consumer repo' },
     { fingerprint: 'a4f51dba3a66c0f2c3548e77961271ed4d7b5ec8a6661ea359ff044758f0d921', path: 'src/templates/minimal/.agent-settings.yml', size: 1042, why: 'the minimal-install settings template; the dot is the consumer-side filename' },

package/src/scripts/check_release_manifest_content.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env tsx
+/**
+ * Release-manifest content check — the content half beside
+ * `check_release_pr_shape`.
+ *
+ * The shape check lets a release PR carry `package.json`, `package-lock.json`
+ * and the three plugin manifests, and it reads only their NAMES. Smoke is
+ * skipped on release heads (`docs/contracts/release-pr-gating.md`), so an added
+ * script, a new dependency or a changed `bin` path could ride a release PR with
+ * no gate reading it. This compares each manifest against the base and fails on
+ * any difference outside the version fields the release writes.
+ *
+ * Version fields are named per file, never matched by key name anywhere: in
+ * `package-lock.json` every dependency also has a `version`, and a key-name
+ * rule would wave a dependency bump through as a version bump.
+ *
+ * Usage: check_release_manifest_content [--base REF] [--root DIR]
+ *   --base REF   ref the head is compared against (default: origin/main)
+ *   --root DIR   repository root to read the head and run git in (testing)
+ *
+ * Exit codes: 0 = only version fields differ · 1 = other difference · 2 = usage/env.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+type Segment = string;
+/** A JSON path pattern; `*` matches any array index. */
+type Pattern = readonly Segment[];
+
+/** The manifests a release PR may carry, and the fields the release writes in each. */
+export const VERSION_FIELDS: Readonly<Record<string, readonly Pattern[]>> = {
+    'package.json': [['version']],
+    'package-lock.json': [['version'], ['packages', '', 'version']],
+    '.claude-plugin/marketplace.json': [['version'], ['metadata', 'version'], ['plugins', '*', 'version']],
+    '.augment-plugin/plugin.json': [['version']],
+    '.augment-plugin/marketplace.json': [['version'], ['metadata', 'version'], ['plugins', '*', 'version']],
+};
+
+function _matches(p: readonly Segment[], pat: Pattern): boolean {
+    if (p.length !== pat.length) return false;
+    return pat.every((seg, i) => seg === p[i] || (seg === '*' && /^\d+$/u.test(p[i] ?? '')));
+}
+
+function _render(p: readonly Segment[]): string {
+    return p.length === 0 ? '(root)' : p.map((s) => (/^\d+$/u.test(s) ? `[${s}]` : JSON.stringify(s))).join('.');
+}
+
+function _isObject(v: unknown): v is Record<string, unknown> {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** Every JSON path at which `a` and `b` differ, leaf-first where both are containers. */
+function _diffPaths(a: unknown, b: unknown, at: Segment[] = []): Segment[][] {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) return [at];
+        return a.flatMap((v, i) => _diffPaths(v, b[i], [...at, String(i)]));
+    }
+    if (_isObject(a) && _isObject(b)) {
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+        const out: Segment[][] = [];
+        for (const k of keys) {
+            if (!(k in a) || !(k in b)) {
+                out.push([...at, k]);
+                continue;
+            }
+            out.push(..._diffPaths(a[k], b[k], [...at, k]));
+        }
+        return out;
+    }
+    return JSON.stringify(a) === JSON.stringify(b) ? [] : [at];
+}
+
+/**
+ * The differences between `base` and `head` text of one manifest that are NOT a
+ * version-string change in a declared version field. Empty means in shape.
+ */
+export function manifestDifferences(file: string, base: string | null, head: string | null): string[] {
+    if (base === null && head === null) return [];
+    if (base === null) return [`${file}: added — absent at the base`];
+    if (head === null) return [`${file}: removed — present at the base`];
+    let a: unknown;
+    let b: unknown;
+    try {
+        a = JSON.parse(base);
+        b = JSON.parse(head);
+    } catch (err) {
+        return [`${file}: not parseable JSON (${(err as Error).message})`];
+    }
+    const allowed = VERSION_FIELDS[file] ?? [];
+    const out: string[] = [];
+    for (const p of _diffPaths(a, b)) {
+        const atVersion = allowed.some((pat) => _matches(p, pat));
+        let before: unknown = a;
+        let after: unknown = b;
+        for (const s of p) {
+            before = (before as Record<string, unknown> | undefined)?.[s];
+            after = (after as Record<string, unknown> | undefined)?.[s];
+        }
+        if (atVersion && typeof before === 'string' && typeof after === 'string') continue;
+        out.push(`${file}: ${_render(p)} differs outside the version fields`);
+    }
+    return out;
+}
+
+function _git(args: readonly string[], cwd: string): { status: number; stdout: string } {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+    return { status: r.status ?? 1, stdout: r.stdout ?? '' };
+}
+
+function _readHead(root: string, file: string): string | null {
+    const abs = path.join(root, file);
+    return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let base = 'origin/main';
+    let root = REPO_ROOT;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--base' || a === '--root') {
+            const v = argv[i + 1];
+            if (v === undefined || v === '') {
+                process.stderr.write(`error: ${a} needs a value\n`);
+                return 2;
+            }
+            if (a === '--base') base = v;
+            else root = path.resolve(v);
+            i += 1;
+            continue;
+        }
+        process.stderr.write(`error: unknown argument ${String(a)}\n`);
+        return 2;
+    }
+    if (_git(['rev-parse', '--verify', `${base}^{commit}`], root).status !== 0) {
+        process.stderr.write(`error: base \`${base}\` does not resolve to a commit in ${root}\n`);
+        return 2;
+    }
+
+    const findings: string[] = [];
+    let scanned = 0;
+    for (const file of Object.keys(VERSION_FIELDS)) {
+        const shown = _git(['show', `${base}:${file}`], root);
+        const before = shown.status === 0 ? shown.stdout : null;
+        const after = _readHead(root, file);
+        if (before !== null || after !== null) scanned += 1;
+        findings.push(...manifestDifferences(file, before, after));
+    }
+    try {
+        reportScanned({ gate: 'check_release_manifest_content', scanned, units: 'manifests', roots: [root] });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    if (findings.length > 0) {
+        process.stdout.write(
+            `❌  release manifests differ from ${base} outside their version fields:\n` +
+                findings.map((f) => `  · ${f}`).join('\n') +
+                '\n  A release PR carries version bumps only. Land the other change on main via its own PR.\n',
+        );
+        return 1;
+    }
+    process.stdout.write(`✅  release manifests differ from ${base} in version fields only (${String(scanned)} read)\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    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());
+}