@event4u/agent-config 14.16.0 → 14.18.0

package/src/scripts/install-hooks.sh

@@ -12,7 +12,25 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 # (where $PROJECT_ROOT/.git is a file, not a dir, and a literal .git/hooks path
 # would break under `set -e`). --git-common-dir points at the main .git even from
 # a worktree; fall back to the literal path only outside a git repo.
-if COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
+#
+# AGENT_CONFIG_HOOKS_DIR overrides the destination. It exists so that
+# `check_installed_hooks_fresh` can render what this installer WOULD write into
+# a scratch directory and byte-compare it against what is installed — the only
+# way to answer "is the installed copy stale?" without re-parsing these
+# heredocs, which carry an appended block (post-merge / post-checkout) that no
+# heredoc slice can reproduce. It is a test/inspection seam; a normal install
+# never sets it.
+if [ -n "${AGENT_CONFIG_HOOKS_DIR+set}" ]; then
+    # SET-BUT-EMPTY is refused rather than ignored. A caller that meant to
+    # redirect an inspection run and passed an empty value would otherwise fall
+    # through to the real .git/hooks and INSTALL over it — including over a
+    # pre-push that is running the inspection, which truncates it silently.
+    if [ -z "$AGENT_CONFIG_HOOKS_DIR" ]; then
+        echo "❌  AGENT_CONFIG_HOOKS_DIR is set but empty — refusing to fall back to the real .git/hooks." >&2
+        exit 2
+    fi
+    HOOKS_DIR="$AGENT_CONFIG_HOOKS_DIR"
+elif COMMON_GIT_DIR="$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)"; then
     case "$COMMON_GIT_DIR" in /*) : ;; *) COMMON_GIT_DIR="$PROJECT_ROOT/$COMMON_GIT_DIR" ;; esac
     HOOKS_DIR="$COMMON_GIT_DIR/hooks"
 else
@@ -20,6 +38,12 @@ else
 fi
 
 mkdir -p "$HOOKS_DIR"
+# Name the destination. AGENT_CONFIG_HOOKS_DIR is a global override, and a
+# stray non-empty value would otherwise redirect a real `task install-hooks`
+# while it printed six "hook installed" lines that name no path at all — the
+# freshness check would then report every hook missing with nothing pointing at
+# the cause.
+echo "→  installing git hooks into $HOOKS_DIR" >&2
 
 cat > "$HOOKS_DIR/pre-push" << 'EOF'
 #!/usr/bin/env bash
@@ -85,6 +109,96 @@ fi
 
 fail=0
 
+# BASE FRESHNESS — first, and it EXITS rather than setting fail=1.
+#
+# The header above has promised "when this hook refuses for staleness" since the
+# hook was written, and nothing below ever asked. Measured over the 50 PRs
+# preceding 2026-09-04: 25 of them carried at least one `Merge branch 'main'
+# into <branch>` commit (52 such commits in total), and 17 of the 36 PRs whose
+# workflow runs were still readable had at least one FAILED run — the three
+# workflows that failed most (Tests 18, Consistency 16, Rule Backstops 13) are
+# exactly the base-relative ones: ratchets, budgets and generated counts that
+# were green against the base the branch forked from and red against the base it
+# merges into. A branch pushed behind its base buys a CONFLICTING PR, a red run,
+# or both, and the contributor pays for it after the work looks finished.
+#
+# It runs FIRST because everything after it is invalidated by the merge that has
+# to happen anyway: `task consistency` regenerates derived files against the
+# stale base, the merge then re-dirties them, and the ~10s is spent twice. And
+# it EXITS instead of accumulating into `fail`, for the same reason — there is
+# no useful second finding to collect from a tree that is about to move.
+#
+# It never merges. `check_branch_freshness` asks the REMOTE (one `ls-remote`,
+# measured 4.5s) and returns 1 only on a VERIFIED behind state; offline, in CI,
+# on a detached HEAD, or standing on the base itself it returns 0 and says so.
+# So an unreachable network cannot block a push, and a stale local tracking ref
+# cannot fake a green.
+echo "🔍 Base freshness — is this branch behind the base it will merge into?"
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1"
+elif [ ! -x ./scripts-run ]; then
+    echo "⚠️  ./scripts-run not found — skipping the freshness check for this push."
+elif ! ./scripts-run src/scripts/check_branch_freshness --quiet; then
+    echo ""
+    echo "   Push blocked — the branch is behind its base, and the gates you just"
+    echo "   passed were answered against a base that no longer exists."
+    echo ""
+    echo "     task push-ready         # fetch → integrate the base SET → regenerate"
+    echo "                             # → verify → re-check freshness, then push"
+    echo "     task push-ready DRY=1   # the same steps, read-only"
+    echo ""
+    echo "   This hook refuses; it never merges. Bypass a genuine WIP push with"
+    echo "   AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1."
+    exit 1
+fi
+
+# INSTALLED-HOOK FRESHNESS — ADVISORY, and deliberately AFTER base freshness.
+#
+# What it answers: are the hooks in .git/hooks still what THIS checkout's
+# install-hooks.sh would write? Measured 2026-09-05: the installed pre-push here
+# was 146 lines against a 189-line source body, missing the entire base-freshness
+# gate above, merged five days earlier. It read as live in the source, in CI and
+# in the skill documenting it, and did not run here.
+#
+# WHY IT DOES NOT REFUSE. The predicate is "installed == what this checkout
+# renders", and .git/hooks is SHARED by every linked worktree through the common
+# dir. With two worktrees whose installer bodies differ, at most one can satisfy
+# it at a time and each re-install flips which — so a refusal would fire on
+# ordinary parallel work, and the documented skip variable would become routine,
+# which retires the gate rather than enforcing it. An AI council (claude-sonnet-4-5
+# + codex-default, 2026-09-05, 2 of 2 seats) chose advisory unanimously after an
+# independent review raised exactly that. Blocking returns only with a
+# single-referent predicate — per-worktree hook isolation via core.hooksPath, or a
+# branch-independent dispatcher installed once in the common dir.
+#
+# WHY AFTER BASE FRESHNESS. Being behind a base that moved the installer is the
+# most common cause of a mismatch, and the repair for THAT is to merge, not to
+# re-install: re-installing from a behind-base checkout writes the OLDER hook set
+# over the shared directory. Base freshness exits first, so that contributor is
+# told the correct thing and never reaches this notice.
+echo "🔍 Installed-hook freshness — do .git/hooks still match this checkout?"
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_HOOKFRESH:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_HOOKFRESH=1"
+elif [ ! -x ./scripts-run ] || [ ! -d node_modules ] \
+    || [ ! -f src/scripts/check_installed_hooks_fresh.ts ]; then
+    # Three guards, and each has been a real miss. `-d node_modules`: without
+    # dependencies ./scripts-run cannot start tsx and the non-zero exit would
+    # read as staleness. `-f`: .git/hooks is shared, so this file also runs in a
+    # worktree standing on a branch that predates the gate, and calling a script
+    # that is not on that checkout would report the wrong thing.
+    echo "⏭️  check_installed_hooks_fresh not runnable on this checkout — skipping."
+else
+    ./scripts-run src/scripts/check_installed_hooks_fresh --quiet
+    hookfresh_rc=$?
+    # The gate's three exit codes mean three different things, and collapsing
+    # them reports a false cause: 0 = match or nothing installed, 1 = mismatch,
+    # 2 = it could not render (installer failed, unwritable TMPDIR, usage error).
+    if [ "$hookfresh_rc" = "2" ]; then
+        echo "⚠️  could not compare the installed hooks (see above) — not a staleness verdict."
+    fi
+    # Advisory in both cases: nothing here sets fail=1 or exits.
+fi
+
 if ! command -v task >/dev/null 2>&1; then
     echo "⚠️  'task' (go-task) not found — cannot run the consistency gate locally."
     echo "    Install it (https://taskfile.dev) so pre-push can mirror the CI check;"
@@ -381,6 +495,25 @@ if [ -n "\$prev" ] && [ -n "\$new" ] && [ "\$prev" != "\$new" ]; then
         if command -v npm >/dev/null 2>&1 && [ -d node_modules ]; then
             npm run build:cli >/dev/null 2>&1 || true
         fi
+        # Installed-hook staleness — REPORT it here, never repair it here.
+        #
+        # This is the event that CAUSES the staleness, so it is where the news
+        # belongs. It is NOT where the repair belongs: linked worktrees SHARE
+        # .git/hooks through the common dir, so re-running the installer from a
+        # checkout would let one worktree silently redefine the gates every
+        # other worktree runs, and an older branch would reinstall older hooks
+        # over newer ones. An AI council (claude-sonnet-4-5 + codex-default,
+        # 2026-09-05, 2 of 2 seats) refused that mutation unanimously.
+        #
+        # Output goes to stderr and is NOT swallowed: the rest of this block is
+        # "|| true" so a pull is never blocked, and a repair notice nobody can
+        # see is the same silence this check exists to remove.
+        # The -f guard is not belt-and-braces: this hook is shared across
+        # linked worktrees, so it also runs on checkouts that predate the gate.
+        if [ -x ./scripts-run ] && [ -d node_modules ] \
+            && [ -f src/scripts/check_installed_hooks_fresh.ts ]; then
+            ./scripts-run src/scripts/check_installed_hooks_fresh --quiet >&2 || true
+        fi
     fi
 fi
 EOF

package/src/scripts/language_mirror_hook.ts

@@ -630,9 +630,17 @@ export function _setPinLost(consumer_root: string, session_id: string): void {
   _migrateLegacyMarker(consumer_root);
   try {
     atomic_write_text(path.join(consumer_root, pinLostMarker(session_id)), new Date().toISOString());
-  } catch {
-    // Observability only — a failed marker write costs one un-restored pin,
-    // never a broken turn.
+  } catch (err) {
+    // The COST is unchanged and still bounded — one un-restored pin, never a
+    // broken turn. What changed on 2026-09-04 is that it stops being silent.
+    // The legacy-marker migration above documents exactly how this catch can
+    // become PERMANENT for a root (`EEXIST` then `ENOTDIR`, reproduced against
+    // Node), and a permanently dead mechanism that never says so is the failure
+    // the sibling swallows in `git_authorization_hook` were repaired for.
+    process.stderr.write(
+      `language-mirror: pin-lost marker write failed (${_errText(err)}) — ` +
+        "the pin will NOT be re-emitted after this compaction. Turn outcome unchanged.\n",
+    );
   }
 }
 
@@ -1124,8 +1132,16 @@ export function run(
       // per tool call — and never before the write it is cleaning up after.
       _pruneLegacyState(options.consumer_root);
       _pruneStaleSessions(options.consumer_root, Date.now());
-    } catch {
-      // Observability only — a failed state write never blocks the turn.
+    } catch (err) {
+      // Direction unchanged: the turn is never blocked. But the pin lives ONLY
+      // in this file, so a failed write silently reverts the next turn to
+      // re-derivation — the user re-states a language they already pinned and
+      // has no way to know why. Named rather than swallowed.
+      process.stderr.write(
+        `language-mirror: pin-state write failed (${_errText(err)}) — ` +
+          "the language pin did NOT persist and the next turn re-derives it. " +
+          "This turn's notice is unchanged.\n",
+      );
     }
   }
 
@@ -1146,6 +1162,12 @@ export function run(
  */
 export { isSyntheticPrompt };
 
+/** One-line, bounded rendering of a caught value for a stderr diagnostic. */
+function _errText(err: unknown): string {
+  const t = err instanceof Error ? err.message : String(err);
+  return t.replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
 export function main(argv?: string[]): number {
   const args = argv ?? process.argv.slice(2);
   let consumer_root = process.cwd();

package/src/scripts/measure_release_mix.ts

@@ -0,0 +1,384 @@
+#!/usr/bin/env tsx
+/**
+ * Release governance-vs-product mix — measured from changed paths, published as
+ * two views, with no threshold.
+ *
+ * Why this exists, and what it deliberately is not.
+ *
+ * An external reviewer asked twice for a per-PR rule: "no meta/governance
+ * feature without a user-facing artifact in the same PR". The AI council
+ * DECLINED that proposal (2026-09-04, anthropic/claude-sonnet-4-5 +
+ * openai/codex-default, 2 rounds, quorum 2/2, $0.00 — both seats
+ * subscription-authed) on two grounds: a same-PR gate measures packaging rather
+ * than progress, since one token consumer-file edit legitimises an otherwise
+ * governance-only pull request; and it rejects legitimate work by construction,
+ * since a CI fix, a dependency bump and an analysis round producing only
+ * roadmaps are all real work with no consumer surface. The decline is recorded
+ * in `docs/decisions/ADR-253-per-pr-user-artifact-gate-declined.md`.
+ *
+ * This script is the replacement both seats specified: classify at RELEASE
+ * level, publish two views, attach a response obligation, and refuse to pick a
+ * threshold until at least two readings exist. It therefore **enforces
+ * nothing about the ratio**. It measures and it publishes. The one enforced
+ * consequence lives in `check_release_highlights.ts` and is about the
+ * completeness of the written response, never about the number.
+ *
+ * The two views.
+ *
+ * - **Commit view** — exclusive counts per category, plus `mixed`, plus
+ *   `unclassified`. A commit is classified from the files it touches.
+ * - **Diff view** — added/deleted lines per category over the whole range.
+ *
+ * Generated projections and lockfiles (`dist/`, `.augment/`, `.claude/`,
+ * `package-lock.json`, …) are removed from BOTH views by name. In this
+ * repository `dist/` is a byte-exact projection of `src/`, so leaving it in
+ * would let a mechanical regeneration dominate every reading. A commit left
+ * with no path after that exclusion lands in the `generated_only` diagnostic
+ * rather than in maintenance — otherwise the ratio would depend on whether the
+ * regeneration was committed separately from the source edit that caused it.
+ *
+ * Classification reads paths, never subjects.
+ *
+ * Commit subjects are mutable, inconsistently formatted, and can contradict the
+ * files a commit touches. Nothing in this file reads `%s`, `%b` or any other
+ * message field; the only git output consumed is a name list and a numstat.
+ * `tests/scripts/measure_release_mix.test.ts` pins that by rewriting a
+ * subject with `git commit --amend` and asserting the reading is byte-identical.
+ *
+ * `mixed` is never collapsed into a category.
+ *
+ * Collapsing `mixed` into product would recreate the exact gaming the declined
+ * rule permits. A commit touching two classified categories is `mixed` and is
+ * reported as its own bucket in both views.
+ *
+ * `unclassified` is separate from `mixed` and does not cause it. A commit whose
+ * paths are all unmatched is `unclassified`; a commit with one classified
+ * category plus unmatched paths keeps that category and carries
+ * `has_unclassified`. Conflating taxonomy uncertainty with genuine
+ * cross-category work would hide both.
+ *
+ * Usage.
+ *
+ *   measure_release_mix --from <ref> --to <ref> [--label <tag>] [--json <path>] [--quiet]
+ *   measure_release_mix --audit          # every top-level tracked path resolves
+ *
+ * Exit codes: 0 clean · 1 an unresolved path in `--audit` · 2 usage or git error.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const TAXONOMY_PATH = path.join(_HERE, '..', 'release_mix_taxonomy.json');
+
+export type Category = 'consumer' | 'governance' | 'maintenance' | 'unclassified';
+export const CLASSIFIED: readonly Category[] = ['consumer', 'governance', 'maintenance'];
+
+export interface Taxonomy {
+    taxonomy_version: string;
+    excluded_generated: string[];
+    rules: { prefix: string; category: Category }[];
+    governance_contracts: string[];
+}
+
+export function loadTaxonomy(file = TAXONOMY_PATH): Taxonomy {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as Taxonomy;
+    if (!raw.taxonomy_version) throw new Error('taxonomy carries no taxonomy_version');
+    return raw;
+}
+
+/** True when the path is a generated projection or a lockfile — dropped from both views. */
+export function isExcluded(p: string, tax: Taxonomy): boolean {
+    return tax.excluded_generated.some((pre) => (pre.endsWith('/') ? p.startsWith(pre) : p === pre));
+}
+
+/**
+ * Longest-prefix-wins. A path matching no rule is `unclassified` — a reported
+ * state, never a silent default into some category.
+ */
+export function classifyPath(p: string, tax: Taxonomy): Category {
+    return classifyPathDetailed(p, tax).category;
+}
+
+/**
+ * The same decision, with the rule that made it. `matched: false` is the
+ * failure `--audit` looks for: a path that fell through every rule, which is
+ * not the same thing as a path the taxonomy deliberately calls unclassified.
+ */
+export function classifyPathDetailed(
+    p: string,
+    tax: Taxonomy,
+): { category: Category; matched: boolean; rule: string } {
+    if (tax.governance_contracts.includes(p)) {
+        return { category: 'governance', matched: true, rule: `governance_contracts:${p}` };
+    }
+    let best: { len: number; category: Category; rule: string } | null = null;
+    for (const rule of tax.rules) {
+        if (!p.startsWith(rule.prefix)) continue;
+        if (best === null || rule.prefix.length > best.len) {
+            best = { len: rule.prefix.length, category: rule.category, rule: rule.prefix };
+        }
+    }
+    return best === null
+        ? { category: 'unclassified', matched: false, rule: '' }
+        : { category: best.category, matched: true, rule: best.rule };
+}
+
+export interface CommitVerdict {
+    /** The bucket the commit lands in. `generated_only` is a diagnostic, not a view bucket. */
+    bucket: Category | 'mixed' | 'generated_only';
+    categories: Category[];
+    has_unclassified: boolean;
+}
+
+/** Classify ONE commit from its changed paths. Nothing here reads the subject. */
+export function classifyCommit(paths: readonly string[], tax: Taxonomy): CommitVerdict {
+    const kept = paths.filter((p) => !isExcluded(p, tax));
+    if (kept.length === 0) {
+        return { bucket: 'generated_only', categories: [], has_unclassified: false };
+    }
+    const seen = new Set<Category>();
+    for (const p of kept) seen.add(classifyPath(p, tax));
+    const has_unclassified = seen.has('unclassified');
+    const classified = [...seen].filter((c) => c !== 'unclassified').sort();
+    if (classified.length === 0) return { bucket: 'unclassified', categories: [], has_unclassified: true };
+    if (classified.length === 1) return { bucket: classified[0]!, categories: classified, has_unclassified };
+    return { bucket: 'mixed', categories: classified, has_unclassified };
+}
+
+function git(args: string[], cwd = REPO_ROOT): string {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${(r.stderr || '').trim()}`);
+    return r.stdout;
+}
+
+export interface Reading {
+    schema_version: 1;
+    taxonomy_version: string;
+    classifier_version: string;
+    label: string;
+    range: { from: string; to: string; from_sha: string; to_sha: string };
+    merge_handling: 'no-merges';
+    rename_handling: 'git-default';
+    commit_view: Record<string, number>;
+    diff_view: Record<string, { added: number; deleted: number }>;
+    diagnostics: {
+        generated_only_commits: number;
+        commits_with_unclassified: number;
+        unclassified_paths: string[];
+        mixed_combinations: Record<string, number>;
+        largest_contributors: Record<string, [string, number][]>;
+    };
+    response_obligation: { triggered: boolean; rule: string; governance_only: number; consumer_only: number };
+}
+
+/** The classifier's own version, bumped independently of the taxonomy's. */
+export const CLASSIFIER_VERSION = '1.0.0';
+
+/**
+ * The response obligation's trigger, stated once so the gate and the report
+ * cannot drift: governance-only commits STRICTLY outnumber consumer-only
+ * commits over the span. Strict inequality is the literal reading of the
+ * roadmap's own wording and both council seats named it explicitly.
+ */
+export const OBLIGATION_RULE = 'governance-only commits > consumer-only commits';
+
+export function measureRange(from: string, to: string, tax: Taxonomy, label = '', cwd = REPO_ROOT): Reading {
+    const shas = git(['log', '--no-merges', '--format=%H', `${from}..${to}`], cwd)
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+
+    const commit_view: Record<string, number> = {
+        consumer: 0, governance: 0, maintenance: 0, unclassified: 0, mixed: 0,
+    };
+    const mixed_combinations: Record<string, number> = {};
+    const unclassified_paths = new Set<string>();
+    let generated_only_commits = 0;
+    let commits_with_unclassified = 0;
+
+    for (const sha of shas) {
+        const paths = git(['show', '--name-only', '--format=', sha], cwd)
+            .split('\n').map((s) => s.trim()).filter(Boolean);
+        const v = classifyCommit(paths, tax);
+        if (v.bucket === 'generated_only') { generated_only_commits += 1; continue; }
+        commit_view[v.bucket] = (commit_view[v.bucket] ?? 0) + 1;
+        if (v.has_unclassified) commits_with_unclassified += 1;
+        if (v.bucket === 'mixed') {
+            const key = v.categories.join('+');
+            mixed_combinations[key] = (mixed_combinations[key] ?? 0) + 1;
+        }
+        for (const p of paths) {
+            if (!isExcluded(p, tax) && classifyPath(p, tax) === 'unclassified') unclassified_paths.add(p);
+        }
+    }
+
+    const diff_view: Record<string, { added: number; deleted: number }> = {
+        consumer: { added: 0, deleted: 0 },
+        governance: { added: 0, deleted: 0 },
+        maintenance: { added: 0, deleted: 0 },
+        unclassified: { added: 0, deleted: 0 },
+    };
+    const touchCount: Record<string, Record<string, number>> = {
+        consumer: {}, governance: {}, maintenance: {}, unclassified: {},
+    };
+
+    for (const line of git(['diff', '--numstat', `${from}..${to}`], cwd).split('\n')) {
+        const parts = line.split('\t');
+        if (parts.length < 3) continue;
+        const [addRaw, delRaw, pathRaw] = parts as [string, string, string];
+        // `git diff --numstat` renders a rename as `old => new`; take the new path.
+        const p = pathRaw.includes('=>') ? pathRaw.replace(/^.*=>\s*/, '').replace(/[{}]/g, '') : pathRaw;
+        if (isExcluded(p, tax)) continue;
+        const cat = classifyPath(p, tax);
+        // A binary file renders as `-`; it contributes a touch, not a line count.
+        diff_view[cat]!.added += addRaw === '-' ? 0 : Number(addRaw);
+        diff_view[cat]!.deleted += delRaw === '-' ? 0 : Number(delRaw);
+        const top = p.split('/').slice(0, 2).join('/');
+        touchCount[cat]![top] = (touchCount[cat]![top] ?? 0) + 1;
+    }
+
+    const largest_contributors: Record<string, [string, number][]> = {};
+    for (const cat of Object.keys(touchCount)) {
+        largest_contributors[cat] = Object.entries(touchCount[cat]!)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5) as [string, number][];
+    }
+
+    const governance_only = commit_view.governance ?? 0;
+    const consumer_only = commit_view.consumer ?? 0;
+
+    return {
+        schema_version: 1,
+        taxonomy_version: tax.taxonomy_version,
+        classifier_version: CLASSIFIER_VERSION,
+        label: label || `${from}..${to}`,
+        range: {
+            from, to,
+            from_sha: git(['rev-parse', from], cwd).trim(),
+            to_sha: git(['rev-parse', to], cwd).trim(),
+        },
+        merge_handling: 'no-merges',
+        rename_handling: 'git-default',
+        commit_view,
+        diff_view,
+        diagnostics: {
+            generated_only_commits,
+            commits_with_unclassified,
+            unclassified_paths: [...unclassified_paths].sort().slice(0, 50),
+            mixed_combinations,
+            largest_contributors,
+        },
+        response_obligation: {
+            triggered: governance_only > consumer_only,
+            rule: OBLIGATION_RULE,
+            governance_only,
+            consumer_only,
+        },
+    };
+}
+
+export function renderReading(r: Reading): string {
+    const cv = r.commit_view;
+    const lines: string[] = [];
+    lines.push(`release-mix · ${r.label} · taxonomy ${r.taxonomy_version} · classifier ${r.classifier_version}`);
+    lines.push(`  range            ${r.range.from_sha.slice(0, 9)}..${r.range.to_sha.slice(0, 9)} (${r.merge_handling})`);
+    lines.push(`  commit view      consumer ${cv.consumer} · governance ${cv.governance} · maintenance ${cv.maintenance} · mixed ${cv.mixed} · unclassified ${cv.unclassified}`);
+    for (const cat of ['consumer', 'governance', 'maintenance', 'unclassified'] as const) {
+        const d = r.diff_view[cat]!;
+        lines.push(`  diff view        ${cat.padEnd(13)} +${d.added} / -${d.deleted}`);
+    }
+    lines.push(`  diagnostics      generated-only commits ${r.diagnostics.generated_only_commits} · commits carrying unclassified paths ${r.diagnostics.commits_with_unclassified}`);
+    lines.push(`  response owed    ${r.response_obligation.triggered ? 'YES' : 'no'} (${r.response_obligation.rule}: ${r.response_obligation.governance_only} vs ${r.response_obligation.consumer_only})`);
+    lines.push('  NOTE             a level, not a verdict — no threshold is committed to this repository.');
+    return lines.join('\n');
+}
+
+/**
+ * AC-2 — every tracked path resolves to exactly one category, or to a rule that
+ * says `unclassified` on purpose. A path that matches NO rule is the failure:
+ * it would otherwise be counted as taxonomy uncertainty when it is really a
+ * taxonomy hole. Reported grouped by the level at which the taxonomy actually
+ * decides, so `src/` shows its subdirectories rather than one aggregate row.
+ */
+export function auditTree(tax: Taxonomy, cwd = REPO_ROOT): {
+    rows: { unit: string; category: Category; files: number }[];
+    unmatched: string[];
+} {
+    const byUnit = new Map<string, { category: Category; files: number }>();
+    const unmatched: string[] = [];
+    for (const f of git(['ls-files'], cwd).split('\n')) {
+        const file = f.trim();
+        if (!file || isExcluded(file, tax)) continue;
+        const d = classifyPathDetailed(file, tax);
+        if (!d.matched) {
+            unmatched.push(file);
+            continue;
+        }
+        const unit = d.rule.startsWith('governance_contracts:') ? 'docs/contracts/ (exception list)' : d.rule;
+        const cur = byUnit.get(unit);
+        if (cur) cur.files += 1;
+        else byUnit.set(unit, { category: d.category, files: 1 });
+    }
+    const rows = [...byUnit.entries()]
+        .map(([unit, v]) => ({ unit, category: v.category, files: v.files }))
+        .sort((a, b) => a.unit.localeCompare(b.unit));
+    return { rows, unmatched };
+}
+
+function usage(msg: string): never {
+    process.stderr.write(`measure_release_mix: ${msg}\n`);
+    process.stderr.write('usage: measure_release_mix --from <ref> --to <ref> [--label <tag>] [--json <path>] [--quiet]\n');
+    process.stderr.write('       measure_release_mix --audit\n');
+    process.exit(2);
+}
+
+export function main(argv: readonly string[]): number {
+    const args = [...argv];
+    const flag = (name: string): string | undefined => {
+        const i = args.indexOf(name);
+        return i === -1 ? undefined : args[i + 1];
+    };
+    const tax = loadTaxonomy();
+
+    if (args.includes('--audit')) {
+        const { rows, unmatched } = auditTree(tax);
+        for (const r of rows) {
+            process.stdout.write(`  ${r.category.padEnd(13)} ${String(r.files).padStart(5)}  ${r.unit}\n`);
+        }
+        if (unmatched.length > 0) {
+            process.stderr.write(`\nmeasure_release_mix: ${unmatched.length} tracked path(s) match no rule:\n`);
+            for (const u of unmatched.slice(0, 20)) process.stderr.write(`  ${u}\n`);
+            return 1;
+        }
+        const files = rows.reduce((n, r) => n + r.files, 0);
+        process.stdout.write(
+            `\nOK — ${files} tracked paths over ${rows.length} classification units, all resolved (taxonomy ${tax.taxonomy_version}).\n`,
+        );
+        return 0;
+    }
+
+    const from = flag('--from');
+    const to = flag('--to');
+    if (!from || !to) usage('--from and --to are required');
+    const reading = measureRange(from, to, tax, flag('--label') ?? '');
+    const jsonPath = flag('--json');
+    if (jsonPath) {
+        fs.mkdirSync(path.dirname(path.resolve(jsonPath)), { recursive: true });
+        fs.writeFileSync(path.resolve(jsonPath), `${JSON.stringify(reading, null, 2)}\n`, 'utf8');
+    }
+    if (!args.includes('--quiet')) process.stdout.write(`${renderReading(reading)}\n`);
+    return 0;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    try {
+        process.exit(main(process.argv.slice(2)));
+    } catch (e) {
+        process.stderr.write(`measure_release_mix: ${(e as Error).message}\n`);
+        process.exit(2);
+    }
+}