@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/rebuild_hook_bundle.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env tsx
+/**
+ * Safe self-heal for the self-hosted hook bundle — the builder that
+ * `check_hook_bundle_freshness` deliberately is not.
+ *
+ * WHY THIS EXISTS — measured, not hypothetical.
+ *
+ * The freshness gate reds after ANY hook-source merge from main, because
+ * `dist/hooks/dispatch.js` is untracked and nothing in the local chain
+ * rebuilds it. On 2026-08-09 that turned `task release` (9.28.0) into a
+ * blocked push with a remedy the operator had to run by hand — a routine
+ * pre-push chore promoted to a release incident. The gate is right to never
+ * build (its documented hazard: esbuild overwriting the dispatcher a running
+ * hook is executing can wedge the tool loop). The hazard is in HOW a naive
+ * rebuild writes, not in rebuilding: this script builds to a sibling `.new`
+ * file, proves the result actually dispatches, and only then renames it into
+ * place — an atomic same-directory rename that a running hook holding an open
+ * file descriptor never observes mid-write.
+ *
+ * The `.new` file MUST live in `dist/hooks/` (not a temp dir): the bundle
+ * resolves `src/scripts/hook_manifest.yaml` relative to its OWN location via
+ * the `__AGENT_CONFIG_BUNDLE__` path-depth switch. Built anywhere else, every
+ * probe answers "manifest missing" with exit 0 and the smoke test proves
+ * nothing (measured 2026-08-08).
+ *
+ * The esbuild invocation is NOT duplicated here — it is read from
+ * `package.json`'s `build:hooks` script and only the `--outfile=` is
+ * rewritten, so the flag set (banner, defines, target) has exactly one home.
+ *
+ * Behaviour:
+ *   no self-hosted bundle → no-op (fresh checkout / CI — nothing is running
+ *                           stale code, and materialising a bundle here would
+ *                           change what other gates see)
+ *   bundle fresh          → no-op
+ *   bundle stale          → rebuild to `.new`, probe, rename into place
+ *   build or probe fails  → the `.new` file is removed and the OLD bundle
+ *                           keeps running (old-but-working beats broken);
+ *                           exit 1 so the freshness gate behind this still
+ *                           reds and the failure is loud.
+ *
+ * Exit codes: 0 = fresh / healed / nothing to heal · 1 = heal failed.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { check } from "./check_hook_bundle_freshness.js";
+
+// ledger-exempt: self-heal builder, not a checker — one build → probe → atomic-rename transaction whose outcome is a single aggregate heal verdict; the per-source staleness accounting lives in check_hook_bundle_freshness, which carries the ledger.
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..");
+const LIVE_REL = path.join("dist", "hooks", "dispatch.js");
+const NEW_REL = path.join("dist", "hooks", "dispatch.new.js");
+
+/**
+ * Rewrite the `--outfile=` of the canonical `build:hooks` script to the
+ * `.new` sibling. Returns null when the expected outfile token is absent —
+ * a changed `package.json` must fail loudly, never build to a guessed path.
+ */
+export function rewriteOutfile(script: string, newOutfile: string): string | null {
+  const token = `--outfile=${LIVE_REL}`;
+  if (!script.includes(token)) return null;
+  return script.replace(token, `--outfile=${newOutfile}`);
+}
+
+/**
+ * Verdict on a dispatcher probe. The probe contract is pinned against the
+ * real dry-run output: exit 0 AND parseable JSON AND a non-empty `concerns`
+ * array. Exit 0 alone is NOT enough — a bundle that cannot find its manifest
+ * answers "manifest missing" with exit 0 (measured 2026-08-08), which is
+ * exactly the broken dispatcher this probe exists to keep out of the live
+ * path. Returns null on pass, a human-readable reason on failure.
+ */
+export function probeVerdict(exitCode: number, stdout: string): string | null {
+  if (exitCode !== 0) return `probe exited ${String(exitCode)}`;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return `probe output is not JSON: ${stdout.slice(0, 120)}`;
+  }
+  const concerns = (parsed as { concerns?: unknown }).concerns;
+  if (!Array.isArray(concerns) || concerns.length === 0) {
+    return "probe JSON carries no concerns — the bundle dispatched nothing";
+  }
+  return null;
+}
+
+function cleanup(newAbs: string): void {
+  try {
+    fs.rmSync(newAbs, { force: true });
+  } catch {
+    // Best-effort: a leftover .new file is inert (nothing executes it).
+  }
+}
+
+export function main(): number {
+  const r = check(REPO_ROOT);
+
+  if (r.skipped) {
+    process.stdout.write(
+      `✅  OK  rebuild_hook_bundle: no self-hosted ${LIVE_REL} — nothing runs stale code, nothing to heal\n`,
+    );
+    return 0;
+  }
+  if (r.stale.length === 0) {
+    process.stdout.write("✅  OK  rebuild_hook_bundle: bundle already fresh — no rebuild needed\n");
+    return 0;
+  }
+
+  process.stdout.write(
+    `🔧  hook bundle stale (${String(r.stale.length)} newer source(s)) — rebuilding safely (build .new → probe → atomic rename)\n`,
+  );
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf-8")) as {
+    scripts?: Record<string, string>;
+  };
+  const buildScript = pkg.scripts?.["build:hooks"];
+  if (buildScript === undefined) {
+    console.error("❌  rebuild_hook_bundle: package.json has no build:hooks script");
+    return 1;
+  }
+  const cmd = rewriteOutfile(buildScript, NEW_REL);
+  if (cmd === null) {
+    console.error(
+      `❌  rebuild_hook_bundle: build:hooks no longer targets --outfile=${LIVE_REL} — ` +
+        "refusing to build to a guessed path; update this script alongside package.json",
+    );
+    return 1;
+  }
+
+  const newAbs = path.join(REPO_ROOT, NEW_REL);
+  const build = spawnSync("sh", ["-c", cmd], {
+    cwd: REPO_ROOT,
+    encoding: "utf-8",
+    env: { ...process.env, PATH: `${path.join(REPO_ROOT, "node_modules", ".bin")}:${process.env["PATH"] ?? ""}` },
+  });
+  if (build.status !== 0) {
+    cleanup(newAbs);
+    console.error(`❌  rebuild_hook_bundle: esbuild failed (${String(build.status)}):`);
+    console.error((build.stderr || build.stdout || "").trim());
+    return 1;
+  }
+
+  const probe = spawnSync(
+    "node",
+    [newAbs, "--platform", "claude", "--event", "pre_tool_use", "--dry-run"],
+    { cwd: REPO_ROOT, encoding: "utf-8", input: "{}" },
+  );
+  const verdict = probeVerdict(probe.status ?? 1, probe.stdout ?? "");
+  if (verdict !== null) {
+    cleanup(newAbs);
+    console.error(`❌  rebuild_hook_bundle: new bundle failed its probe — ${verdict}`);
+    console.error("    The old bundle stays in place (old-but-working beats broken).");
+    return 1;
+  }
+
+  fs.renameSync(newAbs, path.join(REPO_ROOT, LIVE_REL));
+  process.stdout.write(
+    `✅  OK  rebuild_hook_bundle: rebuilt + probed + renamed into place (${String(r.checked)} bundled source(s))\n`,
+  );
+  return 0;
+}
+
+const invokedDirectly = ((): boolean => {
+  const entry = process.argv[1];
+  if (entry === undefined) return false;
+  try {
+    return fs.realpathSync(path.resolve(entry)) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  process.exit(main());
+}

package/src/scripts/release.ts

@@ -1073,6 +1073,78 @@ function _tag_exists_remote(tag: string): boolean {
     return r.returncode === 0;
 }
 
+/**
+ * True when git rejected a tag push because the ref already exists on the
+ * remote. Wording pinned from the real failure (2026-08-09, 9.28.0 — two
+ * concurrent resume runs, the loser crashed):
+ *
+ *     ! [remote rejected]  9.28.0 -> 9.28.0 (cannot lock ref 'refs/tags/9.28.0': reference already exists)
+ *
+ * plus the `[rejected] … (already exists)` variant git emits when the local
+ * and remote tag objects differ.
+ */
+export function _is_tag_already_exists(stderr: string, stdout: string): boolean {
+    const text = `${stderr}\n${stdout}`;
+    return /\[(?:remote )?rejected\]/i.test(text) && /already exists/i.test(text);
+}
+
+/** Peeled commit the remote tag points at, or null when the tag is absent. */
+function _remote_tag_commit(tag: string): string | null {
+    const r = run(['git', 'ls-remote', REMOTE, `refs/tags/${tag}`, `refs/tags/${tag}^{}`], {
+        check: false,
+        capture: true,
+    });
+    if (r.returncode !== 0) return null;
+    const lines = r.stdout.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    // An annotated tag lists the tag object AND the peeled `^{}` commit — the
+    // peeled line wins so the comparison is commit-vs-commit regardless of
+    // whether the two runs minted distinct tag objects for the same commit.
+    const peeled = lines.find((l) => l.trimEnd().endsWith('^{}'));
+    return (peeled ?? (lines[0] as string)).split('\t')[0] ?? null;
+}
+
+/**
+ * Push a tag, tolerating exactly ONE failure: the concurrent-release race.
+ * `_tag_exists_remote` in step 8 is a live check, but between it and this
+ * push a parallel `task release` run can land the same tag (measured
+ * 2026-08-09, 9.28.0). When the remote tag already points at the same commit
+ * as the local one, the repository IS in the desired state — continue. Any
+ * other rejection, and a same-name tag on a DIFFERENT commit, stays fatal
+ * with the push output as the error.
+ */
+function _push_tag(tag: string): void {
+    const first = run(['git', 'push', REMOTE, tag], { check: false, capture: true });
+    if (first.returncode === 0) {
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
+        return;
+    }
+    if (_is_tag_already_exists(first.stderr, first.stdout)) {
+        const remote = _remote_tag_commit(tag);
+        const local = git(['rev-list', '-n', '1', tag], { capture: true });
+        if (remote !== null && remote === local) {
+            process.stdout.write(
+                `↻  tag ${tag} already on ${REMOTE} at the same commit — a parallel run pushed it; continuing\n`,
+            );
+            return;
+        }
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
+        die(
+            `tag ${tag} exists on ${REMOTE} pointing at ${remote ?? '<unreadable>'} while the local tag ` +
+                `points at ${local} — refusing to overwrite a published tag; ` +
+                'delete the wrong one deliberately and re-run',
+        );
+    }
+    process.stdout.write(first.stdout);
+    process.stderr.write(first.stderr);
+    die(
+        `push of tag ${tag} failed (exit ${first.returncode}) — ` +
+            'the push output above is the real error (a pre-push gate, credentials, or protection)',
+    );
+}
+
 /** Most recent PR (any state) with `release/X.Y.Z` as head, or null. */
 function _pr_for_branch(branch: string): Record<string, unknown> | null {
     const r = run(
@@ -2029,7 +2101,7 @@ function execute(
             _step(8, total, `Tag ${plan.target} already on ${REMOTE} — skip`);
         } else {
             _step(8, total, `Tag ${plan.target} exists locally — push only`);
-            run(['git', 'push', REMOTE, plan.target]);
+            _push_tag(plan.target);
         }
     } else {
         // Sequencing is load-bearing (release-truth Phase 1, council
@@ -2047,7 +2119,7 @@ function execute(
             );
         }
         run(['git', 'tag', '-a', plan.target, '-m', tag_message_from_section(merged!.body, plan.target)]);
-        run(['git', 'push', REMOTE, plan.target]);
+        _push_tag(plan.target);
     }
 
     // ─── 9. GitHub Release ──────────────────────────────────────────────────

package/src/scripts/report_conformance_funnel.ts

@@ -0,0 +1,284 @@
+#!/usr/bin/env tsx
+/**
+ * report_conformance_funnel.ts — delivery → activation → compliance, one view.
+ *
+ * ⚠️ REPORT ONLY — THIS SCRIPT MUST NEVER BE WIRED INTO A CI WORKFLOW WITHOUT
+ * A MEASURED FALSE-POSITIVE RATE FIRST (locked policy; council requirement,
+ * road-to-feedback-9-29 Phase 4.2). Every source it joins is itself advisory
+ * and says so; a join of advisories does not become a gate by aggregation.
+ *
+ * Executes road-to-feedback-9-29 Phase 4.2: one report join over the existing
+ * conformance sources, so the three questions that were answered in three
+ * places read as the funnel they are:
+ *
+ *   DELIVERY    what rule text the carriers put in front of the model, and
+ *               whether the two carriers agree —
+ *               `conformance_scan.measureDelivered` (carrier census) +
+ *               `report_carrier_divergence.compareCarriers` (divergence).
+ *   ACTIVATION  whether the shipped skills are invoked at all —
+ *               `report_skill_activation.censusSkills` + `measureUsage`.
+ *   COMPLIANCE  whether a loaded skill's obligations were violated (SK-2) —
+ *               `report_skill_obligation_violations.scanStore`.
+ *
+ * JOINS, NEVER RE-DERIVES. Every number below comes from an EXPORTED function
+ * of the source that owns it. A second copy of a classifier is the "second
+ * artefact to keep in sync" this repo forbids — it is how the 8 → 30 spread
+ * and the 303-vs-626 detector defect happened, and both are cited in the
+ * sources this file imports.
+ *
+ * Each axis also carries the honest-scope statement its source already
+ * carries (SK-2's mechanisable-subset ratio, activation's catalogue-not-
+ * persisted caveat, delivery's not-per-session caveat). Where a source has no
+ * local data, the axis prints its honest "no data" line rather than
+ * disappearing — an absent store is an answer, not a zero.
+ *
+ * Reached via `agent-config conformance --funnel` (no new top-level verb —
+ * the flag hangs off the existing `conformance` verb per the dispatcher-verb
+ * registry trap named in the roadmap's risk table).
+ *
+ * Exit: 0 always, except a usage error (1). Deliberate — see the header.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    measureDelivered,
+    defaultStore,
+    type DeliveredPayload,
+} from './conformance_scan.js';
+import {
+    compareCarriers,
+    GLOBAL_RULES,
+    PROJECT_RULES,
+    PROJECTION_SOURCE,
+    type CarrierDivergence,
+} from './report_carrier_divergence.js';
+import {
+    censusSkills,
+    measureUsage,
+    SKILLS_ROOT,
+    type SkillCensus,
+    type UsageReport,
+} from './report_skill_activation.js';
+import { scanStore as scanObligationStore, type Sk2Report } from './report_skill_obligation_violations.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export interface FunnelOptions {
+    /** The checkout whose skills and projection source are measured. */
+    repoRoot?: string;
+    /** The project rule carrier — what the host reads at project scope. */
+    projectRulesDir?: string;
+    /** The machine-global rule carrier. */
+    globalRulesDir?: string;
+    /** The projection source, read only to attribute manual-only absences. */
+    sourceDir?: string;
+    /** Transcript store for the activation and compliance axes. */
+    store?: string;
+    /** Most-recent sessions to scan. */
+    limit?: number;
+}
+
+export interface FunnelReport {
+    /** DELIVERY — carrier census (conformance_scan) + divergence (report_carrier_divergence). */
+    delivered: DeliveredPayload;
+    divergence: CarrierDivergence;
+    /** ACTIVATION — skill census + usage (report_skill_activation). */
+    skills: SkillCensus;
+    usage: UsageReport;
+    /** `false` is the no-data branch for both transcript-fed axes. */
+    storePresent: boolean;
+    /** COMPLIANCE — SK-2 loaded-but-violated (report_skill_obligation_violations). */
+    sk2: Sk2Report;
+}
+
+export function buildFunnel(opts: FunnelOptions = {}): FunnelReport {
+    const repoRoot = opts.repoRoot ?? REPO_ROOT;
+    const projectRulesDir = opts.projectRulesDir ?? path.join(repoRoot, PROJECT_RULES);
+    const globalRulesDir = opts.globalRulesDir ?? path.join(os.homedir(), GLOBAL_RULES);
+    const sourceDir = opts.sourceDir ?? path.join(repoRoot, PROJECTION_SOURCE);
+    const store = opts.store ?? defaultStore(repoRoot);
+    const limit = opts.limit ?? 30;
+    return {
+        delivered: measureDelivered(projectRulesDir, globalRulesDir),
+        divergence: compareCarriers(projectRulesDir, globalRulesDir, sourceDir),
+        skills: censusSkills(path.join(repoRoot, SKILLS_ROOT)),
+        usage: measureUsage(store, limit),
+        storePresent: fs.existsSync(store),
+        sk2: scanObligationStore(repoRoot, store, limit),
+    };
+}
+
+function _pct(n: number, d: number): string {
+    return d === 0 ? 'n/a' : `${((100 * n) / d).toFixed(1)}%`;
+}
+
+function _carrierLine(label: string, c: { present: boolean; files: number; tokens: number }): string {
+    return c.present
+        ? `    ${label}  ${String(c.files).padStart(4)} rules  ${String(c.tokens).padStart(7)} tok`
+        : `    ${label}  ABSENT — not a measured zero, this carrier does not exist here`;
+}
+
+export function render(r: FunnelReport): string {
+    const lines: string[] = [];
+    lines.push('conformance funnel — delivery → activation → compliance (report, not a gate)');
+    lines.push('');
+
+    // ── DELIVERY ───────────────────────────────────────────────────────────
+    lines.push('DELIVERY — rule text the carriers put in front of the model');
+    lines.push(_carrierLine('project', r.delivered.project));
+    lines.push(_carrierLine('global ', r.delivered.global));
+    lines.push(`    union                  ${String(r.delivered.union_tokens).padStart(7)} tok`);
+    lines.push('    Carriers as they stand NOW — a session\'s own payload is NOT recoverable:');
+    lines.push('    the transcript records no system or tools field (conformance_scan).');
+    const d = r.divergence;
+    if (!d.globalPresent) {
+        lines.push('    Divergence: the global carrier is absent — this machine loads the project');
+        lines.push('    projection only, so there is no second copy to diverge from. A real');
+        lines.push('    answer, not a skipped check.');
+    } else if (!d.projectPresent) {
+        lines.push('    Divergence: the project rule tree does not exist in this checkout — it is');
+        lines.push('    generated and gitignored. Run `task generate-tools`, then re-run. Not');
+        lines.push('    substituted with dist/, which would answer a different question.');
+    } else {
+        lines.push(
+            `    Divergence: ${d.shared} shared · ${d.bodyDiff.length} body-diff · ` +
+                `${d.provenanceOnly.length} provenance-only · ${d.projectOnly.length} project-only · ` +
+                `${d.globalOnly.length} global-only` +
+                (d.manualOnlyGlobal.length > 0 ? ` (${d.manualOnlyGlobal.length} by design, ADR-004 manual)` : ''),
+        );
+        if (d.bodyDiff.length > 0) {
+            lines.push(`    BODY DIVERGENCE — both copies reach the model: ${d.bodyDiff.join(', ')}`);
+            lines.push('    Precedence: the project projection is generated from src/ at this commit');
+            lines.push('    and wins; the global install is a release snapshot.');
+        }
+        if (d.unreadable.length > 0) {
+            lines.push(`    Unreadable on one side (${d.unreadable.length}) — a broken install, not a disagreement.`);
+        }
+    }
+    lines.push('');
+
+    // ── ACTIVATION ─────────────────────────────────────────────────────────
+    lines.push('ACTIVATION — are the delivered skills invoked?');
+    lines.push(`    skills shipped                        ${r.skills.total}`);
+    lines.push(
+        `    with a machine-matchable trigger key  ${r.skills.withTriggerKey.length} ` +
+            `(${_pct(r.skills.withTriggerKey.length, r.skills.total)})`,
+    );
+    if (!r.storePresent) {
+        lines.push(`    NO DATA: no transcript store at ${r.usage.store} — usage is not`);
+        lines.push('    measurable here. An absent store is an answer, not a zero.');
+    } else {
+        const distinct = Object.keys(r.usage.bySkill).length;
+        lines.push(
+            `    sessions=${r.usage.sessions} assistant turns=${r.usage.assistantTurns} ` +
+                `Skill invocations=${r.usage.invocations} distinct skills=${distinct} of ${r.skills.total} ` +
+                `(${_pct(distinct, r.skills.total)})`,
+        );
+    }
+    if (r.skills.withTriggerKey.length === 0) {
+        lines.push('    Honest scope: activation is NOT measurable as a rate — no skill declares');
+        lines.push('    a machine-matchable trigger, and matching description prose is the class');
+        lines.push('    this suite excludes (report_skill_activation).');
+    }
+    lines.push('    NOT MEASURED: whether each skill reached the model WITH its description —');
+    lines.push('    the host\'s injected catalogue is not persisted in the transcript, so the');
+    lines.push('    bare-name (truncation) hypothesis stays a single-session observation.');
+    lines.push('');
+
+    // ── COMPLIANCE ─────────────────────────────────────────────────────────
+    const c = r.sk2.census;
+    lines.push('COMPLIANCE — SK-2 loaded-but-violated (coverage is the headline)');
+    lines.push(`    skills with a deterministic obligation  ${c.skills.length}`);
+    lines.push(
+        `    testable without judgement              ${c.forbidden.length} artefact(s) over ` +
+            `${c.totalLines} obligation line(s)`,
+    );
+    lines.push('    The rest are deterministic in WORDING and need a reading to test — the');
+    lines.push('    FC-8 class this suite excludes, reported as uncovered, not approximated');
+    lines.push('    (report_skill_obligation_violations).');
+    if (!r.storePresent) {
+        lines.push('    NO DATA: no transcript store — loaded-but-violated cannot be observed');
+        lines.push('    here. The coverage census above is static and still holds.');
+    } else {
+        lines.push(
+            `    sessions scanned=${r.sk2.sessions} with a skill in context=${r.sk2.sessionsWithASkill} ` +
+                `flags=${r.sk2.flags.length}`,
+        );
+        for (const f of r.sk2.flags) {
+            lines.push(`      ${f.session}  [${f.skill}] ${f.artefact} via ${f.tool}`);
+        }
+    }
+    lines.push('    PRECISION: every flag is hand-read before any number here is cited — the');
+    lines.push('    detector cannot state its false-positive rate, so it ships detection-only.');
+    lines.push('');
+
+    lines.push('This is a REPORT. It gates on nothing and must never be wired into a CI');
+    lines.push('workflow without a measured false-positive rate first (locked policy).');
+    return lines.join('\n');
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const opts: FunnelOptions = {};
+    // A value must not itself be a flag — the same hole the sibling reports
+    // close on both the flag-name and flag-value halves.
+    const value = (i: number): string | null => {
+        const v = args[i + 1];
+        return v === undefined || v.startsWith('-') ? null : v;
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === '--store' || a === '--project' || a === '--global' || a === '--source') {
+            const v = value(i);
+            if (v === null) {
+                process.stderr.write(`report_conformance_funnel: ${a} needs a value\n`);
+                return 1;
+            }
+            const resolved = path.resolve(v);
+            if (a === '--store') opts.store = resolved;
+            else if (a === '--project') opts.projectRulesDir = resolved;
+            else if (a === '--global') opts.globalRulesDir = resolved;
+            else opts.sourceDir = resolved;
+            i += 1;
+        } else if (a === '--limit') {
+            const v = value(i);
+            const n = v === null ? Number.NaN : Number.parseInt(v, 10);
+            if (!Number.isFinite(n) || n <= 0) {
+                process.stderr.write('report_conformance_funnel: --limit must be a positive integer\n');
+                return 1;
+            }
+            opts.limit = n;
+            i += 1;
+        } else if (a === '--help' || a === '-h') {
+            process.stdout.write(
+                'usage: report_conformance_funnel [--store PATH] [--limit N]\n' +
+                    '                                 [--project DIR] [--global DIR] [--source DIR]\n',
+            );
+            return 0;
+        } else if (a !== undefined && a.startsWith('--') && a !== '--quiet') {
+            process.stderr.write(`report_conformance_funnel: unknown flag ${a}\n`);
+            return 1;
+        }
+    }
+    process.stdout.write(`${render(buildFunnel(opts))}\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());
+}

package/src/scripts/report_imperative_density.ts

@@ -32,6 +32,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+// ledger-exempt: advisory report that gates on nothing BY DESIGN (exit 0 always, no threshold, no baseline entry, no gate-coverage row — see the header); there is no pass/fail outcome per target to account, and acquiring one would be the promotion this report must not undergo.
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');