@event4u/agent-config 9.20.0 → 9.22.0

package/src/config/gate-coverage.yml

@@ -72,10 +72,15 @@
 #
 # What remains is NOT one line per gate. For the ~201 the count would have to be
 # INVENTED (what is this gate's unit?) rather than published, and that judgement
-# is per-gate. It is tracked as a vulnerability ratchet — `gate-hardening:
-# unhardened-scan-scope` in src/config/gate-violation-baselines.json, which fails
-# on a RISE and targets 0 — and charter-owned by
-# `agents/roadmaps/road-to-gate-hardening-adoption.md`.
+# is per-gate. It was tracked as a vulnerability ratchet — `gate-hardening:
+# unhardened-scan-scope` in src/config/gate-violation-baselines.json, which
+# failed on a RISE and targeted 0 — under the road-to-gate-hardening-adoption
+# charter. That charter closed 2026-08-05: the count reached 0 and the baseline
+# entry was DELETED rather than zeroed, so `checkRatchet` now returns
+# `unbaselined` with `ok = (actual === 0)`. Zero is mandatory, not a floor — any
+# new gate written without a scope assertion reds immediately, and
+# `tests/scripts/check_gate_coverage.test.ts` pins both the empty population and
+# the entry's continued absence.
 #
 # `tests/scripts/check_gate_coverage.test.ts` fails the build the moment a gate
 # starts emitting the line without being registered here, so the list cannot
@@ -441,3 +446,16 @@ gates:
     note: >
       Emits on stderr, not stdout: `--format json` owns this gate's stdout and a
       count written there would corrupt the payload. The guard reads both streams.
+
+  - id: check_cli_registry_budget_sync
+    argv: []
+    min_scanned: 3
+    corpus: "the three named inputs it cross-checks — src/cli/registry.ts, src/config/evaluator-budgets.json, internal/bench/reports/evaluator-measurements.json"
+    status: enforced
+    note: >
+      Registered because its count became REAL, not to pad the manifest. The
+      gate always printed a hardcoded `scanned: 3`; hardening derived it from
+      the watch list that actually resolved, which is what makes a floor of 3
+      meaningful — it now falls when one of the three inputs is renamed away.
+      `argv: []` is the CI-identical invocation: both `taskfiles/ci-fast.yml`
+      and `.github/workflows/tests.yml` call it bare.

package/src/config/gate-violation-baselines.json

@@ -1,15 +1,10 @@
 {
   "$comment": "Violation ratchet for gates whose dead scan root was repaired. A repair REVEALS pre-existing debt; it does not create it. Each entry records the count revealed at repair time — the gate fails only when its count RISES. Lowering a count is a normal commit; raising one is a defect. Entries expire: a baseline that has not dropped within 56 days of `landed` (or of `reaffirmed.date`) fails its gate, because a number that never moves is suppression with extra steps. Mechanism + rationale: src/scripts/_lib/gate_baseline.ts. Decision: AI council 2026-08-02, roadmap road-to-gates-that-can-fail blocker `dead-gate-finding-triage`.",
   "gates": {
-    "gate-hardening:unhardened-scan-scope": {
-      "count": 189,
-      "landed": "2026-08-04",
-      "note": "Gate scripts under src/scripts (population 223, the lint_/check_/audit_ prefix set) that neither route through _lib/scan_scope nor emit the machine-readable 'scanned:' line — the gates that can still report success over a moved or empty root without saying so. This is a VULNERABILITY count, not a coverage percentage: it measures how much of the original defect class is still reachable, it RISES whenever a new gate is written without a scope assertion, and its target is 0. That direction is the whole point — an adoption-reach metric ('hardened gates must increase') can never regress and would be threshold-lowering wearing a ratchet's clothes (AI council 2026-08-04, anthropic/claude-sonnet-4-5 + openai/gpt-4o, convergent on scope decomposition plus this discriminator). Clearing it is the charter of road-to-gate-hardening-adoption; the 56-day non-stagnation clause applies unchanged, so a number that never drops fails this gate rather than hardening into configuration. NEW ENTRY, not a raised threshold: this records newly-measured pre-existing exposure at first measurement — nothing was loosened."
-    },
     "check_no_new_legacy_path:hardcoded-scan-roots": {
-      "count": 51,
-      "landed": "2026-08-02",
-      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` — a filesystem path CONSTRUCTED against the tree ADR-051 abandoned, which is the exact shape of all 14 dead gates. Deliberately narrow so the number is signal, not noise: 236 raw mentions under src/scripts → 147 string-literal lines → 67 path-constructing lines when the pass was written, after exempting src/scripts/_lib/agent_src.ts (the shared resolver, whose job IS owning the constant — gates that route through it survived the move). Detectors holding the literal as data to match, strip, or print are not counted, and no prose, docs, tests or fixtures are read: that full-tree shape was measured at 44 files / 213 hits and rejected as the wrong lint (see the note in check_no_new_legacy_path.ts::find_offenders). Recorded at 58 rather than 67 because Phase 1's scan-root repairs were landing on this branch while the pass was being written and had already removed 9 — a baseline above the truth silently permits new violations. This count goes to ZERO as the remaining repairs land; every repair is a lowering commit. Lowered 56→51 by the road-to-renewal-foundation Phase 1 dead-root sweep (check_always_budget, check_portability, check_references, lint_framework_leakage, lint_agents_md)."
+      "count": 49,
+      "landed": "2026-08-04",
+      "note": "Lines under src/scripts/**/*.{ts,mts,mjs} that pass the retired `.agent-src.uncondensed` directory into `path.join(...)` — a filesystem path CONSTRUCTED against the tree ADR-051 abandoned, which is the exact shape of all 14 dead gates. Deliberately narrow so the number is signal, not noise: 236 raw mentions under src/scripts → 147 string-literal lines → 67 path-constructing lines when the pass was written, after exempting src/scripts/_lib/agent_src.ts (the shared resolver, whose job IS owning the constant — gates that route through it survived the move). Detectors holding the literal as data to match, strip, or print are not counted, and no prose, docs, tests or fixtures are read: that full-tree shape was measured at 44 files / 213 hits and rejected as the wrong lint (see the note in check_no_new_legacy_path.ts::find_offenders). Recorded at 58 rather than 67 because Phase 1's scan-root repairs were landing on this branch while the pass was being written and had already removed 9 — a baseline above the truth silently permits new violations. This count goes to ZERO as the remaining repairs land; every repair is a lowering commit. Lowered 56→51 by the road-to-renewal-foundation Phase 1 dead-root sweep (check_always_budget, check_portability, check_references, lint_framework_leakage, lint_agents_md). Lowered 51→49 by the gate-hardening adoption PR: skill_collision_clusters and skill_overlap were repointed at the live skills tree via the shared resolver — two gates that had been reading the retired container and scoring 0 of 288 skills."
     },
     "audit_user_type_axis": {
       "count": 1,

package/src/scripts/_lib/bench_ab_activation.ts

@@ -0,0 +1,368 @@
+/**
+ * Measurement-integrity primitives for the bench:ab v2 paired sweep.
+ *
+ * Implements deltas #1–#4 of the S0.3 harness-feasibility spike
+ * (`agents/evidence/investigations/solution-minimalism-phase0-spikes.md`
+ * § "Deltas required before a paid run") — the four cheap ones the roadmap's
+ * Phase-3 halt note says "land before any spend".
+ *
+ * Why this exists at all: the sweep has ALREADY produced a full set of invalid
+ * nulls once. Clones lived inside the repo, so the `vanilla` arm inherited the
+ * package through project scope and every prior null was void
+ * (`bench_ab_v2_run.ts` § arm-isolation note). The fix at the time was a `/tmp`
+ * path constant with no runtime assertion behind it, and the only activation
+ * field on a trial record — `injected_chars` — is the `String.length` of a file
+ * the harness itself wrote. It proves nothing about the model, and it is `0` by
+ * construction for the `package` arm, which arrives through global settings.
+ * If the plugin were disabled or version-drifted mid-sweep, every treatment run
+ * would silently degrade to `vanilla` and the report would look identical.
+ *
+ * Everything here is pure and host-free so it can be unit-tested without a
+ * model call. The sweep wires it in `bench_ab_v2_run.ts`.
+ */
+
+/** Four-bucket usage split as reported by the Claude CLI JSON envelope. */
+export interface TokensBreakdown {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+}
+
+/** Per-1M-token rates for one pricing tier (mirrors `_lib/bench_cost.TierRates`). */
+export interface TierRates {
+    input: number;
+    output: number;
+    cache_write: number;
+    cache_read: number;
+}
+
+/**
+ * How an arm is supposed to reach the model.
+ *
+ * - `plugin` — the package rides global settings (`setting_sources: null`).
+ *   Invisible to `injected_chars`; only the prompt footprint can see it.
+ * - `text`   — an `--append-system-prompt-file` injection the harness wrote.
+ * - `none`   — the baseline: settings scoped away AND no text injection.
+ */
+export type ExpectedInjection = 'plugin' | 'text' | 'none';
+
+/**
+ * `unknown` is deliberately not a violation: an errored or budget-capped run
+ * carries a zeroed usage block, so its footprint says nothing. Attrition is
+ * reported separately (delta #5) rather than laundered into an integrity fail.
+ */
+export type ActivationVerdict = 'ok' | 'violation' | 'unknown';
+
+export interface Activation {
+    expected: ExpectedInjection;
+    prompt_tokens: number;
+    injected_chars: number;
+    verdict: ActivationVerdict;
+    reason: string;
+}
+
+export interface ActivationViolation {
+    task_id: string;
+    seed: number;
+    arm: string;
+    kind: 'text-injection-missing' | 'text-injection-unexpected' | 'collapsed-to-baseline' | 'model-mismatch';
+    detail: string;
+}
+
+export interface ActivationAudit {
+    checked: number;
+    skipped: number;
+    violations: ActivationViolation[];
+}
+
+/**
+ * Minimum prompt-footprint ratio a plugin-bearing arm must hold over the paired
+ * baseline run before the pair is believed.
+ *
+ * Calibrated DOWNWARD from the three stored sweeps in S0.3's cost sheet, whose
+ * observed treatment/vanilla total-token ratios were 4.68× (sonnet, `package`),
+ * 1.71× (haiku, `rules-kernel-dc`) and 6.79× (haiku, `package`). 1.2 sits below
+ * the smallest of those by a wide margin on purpose: this flags a COLLAPSE to
+ * baseline — a disabled or drifted plugin — never ordinary run-to-run variance.
+ * Raising it toward the observed values would start failing legitimate runs;
+ * lowering it toward 1.0 would stop catching the failure it exists for.
+ */
+export const ACTIVATION_MIN_LIFT_RATIO = 1.2;
+
+/**
+ * The footprint an injection actually moves: everything the model was fed.
+ *
+ * Output tokens are excluded — they measure how much the model wrote, which a
+ * bigger system prompt does not reliably change, so including them would blur
+ * the very signal this audit reads.
+ */
+export function prompt_tokens(b: TokensBreakdown | Record<string, never> | null | undefined): number {
+    if (!b) {
+        return 0;
+    }
+    const t = b as Partial<TokensBreakdown>;
+    return _int(t.input_tokens) + _int(t.cache_read_input_tokens) + _int(t.cache_creation_input_tokens);
+}
+
+/** Classify an arm spec into the injection channel it is supposed to use. */
+export function expected_injection(spec: { setting_sources: string | null; inject: string | null }): ExpectedInjection {
+    if (spec.inject) {
+        return 'text';
+    }
+    return spec.setting_sources === null ? 'plugin' : 'none';
+}
+
+/**
+ * Per-trial verdict — the direction that IS decidable from one run.
+ *
+ * A text injection is checked both ways: an arm that declares one must carry
+ * it, and an arm that declares none must not. The plugin direction needs the
+ * paired baseline and is handled by `audit_activation`.
+ */
+export function activation_verdict(args: {
+    expected: ExpectedInjection;
+    tokens_breakdown: TokensBreakdown | Record<string, never> | null | undefined;
+    injected_chars: number;
+    errored: boolean;
+}): Activation {
+    const pt = prompt_tokens(args.tokens_breakdown);
+    const base = { expected: args.expected, prompt_tokens: pt, injected_chars: args.injected_chars };
+    if (args.errored || pt === 0) {
+        return { ...base, verdict: 'unknown', reason: 'errored or zero usage — footprint unreadable' };
+    }
+    if (args.expected === 'text' && args.injected_chars <= 0) {
+        return { ...base, verdict: 'violation', reason: 'text arm carried no injection' };
+    }
+    if (args.expected !== 'text' && args.injected_chars > 0) {
+        return {
+            ...base,
+            verdict: 'violation',
+            reason: `${args.expected} arm carried a ${args.injected_chars}-char injection`,
+        };
+    }
+    return { ...base, verdict: 'ok', reason: 'expected channel present' };
+}
+
+/**
+ * Cross-arm audit over a finished (or partial) record set — the plugin
+ * direction plus every per-trial verdict already stamped on the records.
+ *
+ * A pair is only judged when BOTH sides are readable; unreadable pairs are
+ * counted as `skipped`, never silently passed.
+ */
+export function audit_activation(
+    records: readonly Record<string, unknown>[],
+    opts: { baseline_arm: string; lift_arms: readonly string[]; min_ratio?: number },
+): ActivationAudit {
+    const minRatio = opts.min_ratio ?? ACTIVATION_MIN_LIFT_RATIO;
+    const violations: ActivationViolation[] = [];
+    let checked = 0;
+    let skipped = 0;
+
+    for (const rec of records) {
+        const taskId = String(rec['id'] ?? '');
+        const arms = _dict(rec['arms']);
+
+        for (const [arm, runsRaw] of Object.entries(arms)) {
+            for (const run of _list(runsRaw)) {
+                const act = _dict(run['activation']);
+                if (act['verdict'] === 'violation') {
+                    const reason = String(act['reason'] ?? '');
+                    violations.push({
+                        task_id: taskId,
+                        seed: _int(run['seed']),
+                        arm,
+                        kind: reason.includes('no injection') ? 'text-injection-missing' : 'text-injection-unexpected',
+                        detail: reason,
+                    });
+                }
+                const mc = _dict(run['model_check']);
+                if ('ok' in mc && !_truthy(mc['ok'])) {
+                    violations.push({
+                        task_id: taskId,
+                        seed: _int(run['seed']),
+                        arm,
+                        kind: 'model-mismatch',
+                        detail: String(mc['reason'] ?? ''),
+                    });
+                }
+            }
+        }
+
+        const baseBySeed = new Map<number, number>();
+        for (const run of _list(arms[opts.baseline_arm])) {
+            const pt = _runPromptTokens(run);
+            if (!_truthy(run['errored']) && pt > 0) {
+                baseBySeed.set(_int(run['seed']), pt);
+            }
+        }
+
+        for (const arm of opts.lift_arms) {
+            for (const run of _list(arms[arm])) {
+                const seed = _int(run['seed']);
+                const basePt = baseBySeed.get(seed);
+                const armPt = _runPromptTokens(run);
+                if (_truthy(run['errored']) || basePt === undefined || armPt === 0) {
+                    skipped += 1;
+                    continue;
+                }
+                checked += 1;
+                if (armPt < basePt * minRatio) {
+                    violations.push({
+                        task_id: taskId,
+                        seed,
+                        arm,
+                        kind: 'collapsed-to-baseline',
+                        detail:
+                            `prompt footprint ${armPt} vs baseline ${basePt} ` +
+                            `(ratio ${(armPt / basePt).toFixed(2)} < ${minRatio}) — ` +
+                            'the treatment surface may not have reached the model',
+                    });
+                }
+            }
+        }
+    }
+
+    return { checked, skipped, violations };
+}
+
+// ── delta #3 — model-id verification ────────────────────────────────────────
+
+/**
+ * Aliases the Claude CLI resolves server-side to whatever is current.
+ *
+ * A stored report already contains the bare alias `"sonnet"`, which makes that
+ * report unreproducible: nothing in it records which model actually answered.
+ */
+export const BARE_MODEL_ALIASES: readonly string[] = ['default', 'haiku', 'opus', 'sonnet', 'sonnet[1m]'];
+
+/** True when `model` is an alias rather than a pinned, reproducible id. */
+export function is_bare_alias(model: string): boolean {
+    return BARE_MODEL_ALIASES.includes(model.trim().toLowerCase());
+}
+
+/** Drop a trailing `-YYYYMMDD` build stamp so `claude-x-1` == `claude-x-1-20250101`. */
+export function normalize_model_id(model: string): string {
+    return model.trim().toLowerCase().replace(/-\d{8}$/, '');
+}
+
+/**
+ * Compare the requested model against the ids the CLI actually billed.
+ *
+ * `models_seen` comes from the envelope's `modelUsage` keys — the only place
+ * the run states which model answered. An empty list is `ok`: some envelopes
+ * omit the block, and refusing there would fail runs for a reporting gap
+ * rather than a real mismatch.
+ */
+export function verify_model_id(requested: string, models_seen: readonly string[]): { ok: boolean; reason: string } {
+    if (is_bare_alias(requested)) {
+        return { ok: false, reason: `requested model "${requested}" is a bare alias — pin a full model id` };
+    }
+    if (models_seen.length === 0) {
+        return { ok: true, reason: 'envelope reported no model usage — nothing to contradict' };
+    }
+    const want = normalize_model_id(requested);
+    const seen = models_seen.map(normalize_model_id);
+    if (seen.every((s) => s === want)) {
+        return { ok: true, reason: `billed model matches ${requested}` };
+    }
+    return {
+        ok: false,
+        reason: `requested ${requested} but envelope billed ${[...new Set(models_seen)].sort().join(', ')}`,
+    };
+}
+
+// ── delta #4 — sweep-level cost ─────────────────────────────────────────────
+
+/** Map a full model id onto a `pricing.yaml` tier, or null when unrecognised. */
+export function tier_for_model(model: string): string | null {
+    const m = model.toLowerCase();
+    for (const tier of ['haiku', 'sonnet', 'opus']) {
+        if (m.includes(tier)) {
+            return tier;
+        }
+    }
+    return null;
+}
+
+/**
+ * Price one run's four buckets separately.
+ *
+ * The buckets differ in price by up to 125×, so a single blended rate over the
+ * summed total is not an approximation — it is a different number.
+ */
+export function cost_usd(b: TokensBreakdown | Record<string, never> | null | undefined, rates: TierRates): number {
+    if (!b) {
+        return 0;
+    }
+    const t = b as Partial<TokensBreakdown>;
+    return (
+        (_int(t.input_tokens) * rates.input +
+            _int(t.output_tokens) * rates.output +
+            _int(t.cache_creation_input_tokens) * rates.cache_write +
+            _int(t.cache_read_input_tokens) * rates.cache_read) /
+        1_000_000
+    );
+}
+
+/**
+ * Cumulative sweep spend with a hard cap.
+ *
+ * `--max-budget-usd` is per RUN (default 1.0), so a 30×4×3 sweep at `--budget
+ * 3.5` has a $1,260 ceiling with nothing to stop it. This is the sweep-level
+ * counterpart: the first run that pushes cumulative spend over the cap aborts
+ * the sweep instead of discovering the overrun on the invoice.
+ */
+export class SweepBudget {
+    private _spent = 0;
+
+    constructor(
+        readonly cap_usd: number | null,
+        private readonly rates: TierRates | null,
+    ) {}
+
+    get spent_usd(): number {
+        return this._spent;
+    }
+
+    /** Add one run's cost; return an abort reason when the cap is crossed. */
+    add(b: TokensBreakdown | Record<string, never> | null | undefined): string | null {
+        if (!this.rates) {
+            return null;
+        }
+        this._spent += cost_usd(b, this.rates);
+        if (this.cap_usd !== null && this._spent > this.cap_usd) {
+            return `sweep budget abort: cumulative $${this._spent.toFixed(2)} > cap $${this.cap_usd.toFixed(2)}`;
+        }
+        return null;
+    }
+}
+
+// ── internals ───────────────────────────────────────────────────────────────
+
+function _int(v: unknown): number {
+    return typeof v === 'number' && Number.isFinite(v) ? Math.trunc(v) : 0;
+}
+
+function _dict(v: unknown): Record<string, unknown> {
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+function _list(v: unknown): Record<string, unknown>[] {
+    return Array.isArray(v) ? (v as Record<string, unknown>[]) : [];
+}
+
+function _truthy(v: unknown): boolean {
+    return Boolean(v);
+}
+
+/**
+ * Prompt footprint of one trial record — the stamped `activation` block when
+ * the sweep wrote one, else recomputed from the preserved breakdown (delta #2),
+ * so the audit also reads reports written before the stamp existed.
+ */
+function _runPromptTokens(run: Record<string, unknown>): number {
+    const stamped = _int(_dict(run['activation'])['prompt_tokens']);
+    return stamped > 0 ? stamped : prompt_tokens(run['tokens_breakdown'] as TokensBreakdown | undefined);
+}

package/src/scripts/_lib/gate_population.ts

@@ -0,0 +1,70 @@
+/**
+ * "What is a gate?" — asserted once, read by everything that needs the answer.
+ *
+ * Three call sites each carried their own regex and each got a different number
+ * (measured 2026-08-04):
+ *
+ * | Site | Pattern | Population |
+ * |---|---|---:|
+ * | `check_gate_coverage` (the ratchet) | `(lint\|check\|audit)_` minus `.d.ts` | 223 |
+ * | `sweep_dead_scan_roots` | `(lint\|audit\|check\|verify)_` | 225 |
+ * | the manifest-registration test | `(lint\|check\|audit\|skill)_` | 232 |
+ *
+ * Harmless while the numbers were only reported. Load-bearing the moment the
+ * ratchet read one of them, which it now does — and it read the narrowest:
+ *
+ * - it counted `check_secret_leak.test.ts`, a **test file**, which can never be
+ *   hardened, so its target of 0 was unreachable by construction;
+ * - it missed 10 real gates the other two definitions caught — 8 × `skill_*`
+ *   (including `skill_linter`, which already carries an enforced floor of 380 in
+ *   the coverage manifest, so the manifest and the ratchet openly disagreed
+ *   about whether it is a gate) and 2 × `verify_*`.
+ *
+ * ## Why a prefix filter and not manifest membership
+ *
+ * AI council 2026-08-04 (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 3 rounds):
+ * making manifest registration the classifier inverts a dependency that runs the
+ * other way in practice. A new gate script lands BEFORE anyone registers it —
+ * that is precisely how the registration test found the drift — so a
+ * manifest-driven population would ignore every gate during the window when it
+ * is least proven. Classification is structural (this filter); registration is
+ * operational and layered on top (`enforced_manifest_ids`).
+ *
+ * The prefix set is a proxy for "this script certifies something and can lie
+ * about it", and an imperfect one: `skill_usage_report` reports rather than
+ * validates. It is kept because it is mechanical and over-inclusive in the safe
+ * direction — a reporting script that asserts its scan scope loses nothing,
+ * while a validator missing from the population is invisible exposure.
+ */
+
+/** Prefixes that mark a script as gate-shaped. */
+const GATE_PREFIX = /^(lint|check|audit|skill|verify)_/;
+
+/**
+ * Is this filename a gate script?
+ *
+ * Structural only — takes a bare filename, never touches disk, so it answers
+ * for a file that does not exist yet (a diff, a plan, a test fixture).
+ */
+export function matchesGatePattern(filename: string): boolean {
+    if (!filename.endsWith('.ts')) return false;
+    // A type declaration has no runtime behaviour to harden; a test file cannot
+    // be hardened at all, and counting one made the ratchet's own target
+    // unreachable.
+    if (filename.endsWith('.d.ts') || filename.endsWith('.test.ts')) return false;
+    return GATE_PREFIX.test(filename);
+}
+
+/** The gate scripts in `dir`, as bare ids (no `.ts`), sorted. Missing dir → `[]`. */
+export function listGateScripts(dir: string, readdir: (d: string) => string[]): string[] {
+    let entries: string[];
+    try {
+        entries = readdir(dir);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter(matchesGatePattern)
+        .map((f) => f.replace(/\.ts$/, ''))
+        .sort();
+}

package/src/scripts/_lib/roadmap_granularity.ts

@@ -0,0 +1,157 @@
+/**
+ * Bite-sized task-granularity check for structural roadmaps.
+ *
+ * A `complexity: structural` roadmap's task bullets must name real work. A
+ * placeholder in a task bullet — `<something>`, TODO, FIXME, XXX, TBD, `???` —
+ * means the step was filed before it was decided, which is the failure the
+ * bite-sized standard exists to catch.
+ *
+ * ## Why this lives in `_lib/` and not in a gate of its own
+ *
+ * It used to be `src/scripts/check_bite_sized_granularity.ts`: a pure library
+ * with no CLI, no `main`, no exit code, and — measured — no production caller
+ * outside its own test. It was carried over from a retired Python module for
+ * API parity and never wired up, so a real check that no other gate covers ran
+ * nowhere, while the `check_` prefix kept it inside the gate population where
+ * the scan-scope ratchet counted it as a gate that could not assert a scan
+ * scope.
+ *
+ * AI council 2026-08-05 resolved it by folding rather than deleting: the checks
+ * are the only placeholder coverage in the tree (`lint_roadmap_complexity`
+ * covers the complexity tag, the lightweight caps, and the plate/horizon
+ * prohibition, and greps clean for every placeholder pattern), so deleting them
+ * would have discarded live value to reach a count. Folding into the gate that
+ * already owns the roadmap corpus adds no gate script, no CI job, and no
+ * manifest entry, and the population member disappears with the old file.
+ *
+ * ## Inline-code masking (the reason this is not a verbatim move)
+ *
+ * The original patterns matched inside backticked spans, which made CLI
+ * metasyntax a violation. Measured across 22 structural roadmaps, the only hit
+ * in the whole tree was `` `settings set <key> <value>` `` — argument
+ * metasyntax in a code span, on a step that is otherwise fully specified. The
+ * council flagged folding a check with an unaudited hit in an out-of-scope
+ * directory as a time-bomb: it would fire the day the gate's scope widened. So
+ * the fix is precision, not scope-limiting — inline code spans are masked
+ * before matching, the same technique `lint_readme_serial_comma` already uses
+ * on README prose. With masking the count is 0 across every structural roadmap,
+ * `later/` and `stubs/` included, so widening the gate's scope later cannot
+ * surprise anyone.
+ */
+
+/** Placeholder patterns in (kind, regex) order. */
+const PLACEHOLDER_PATTERNS: ReadonlyArray<[string, RegExp]> = [
+    ['angle-placeholder', /<[a-z][a-z0-9 _\-/]*>/i],
+    ['todo', /\bTODO\b/],
+    ['fixme', /\bFIXME\b/],
+    ['xxx', /\bXXX\b/],
+    ['tbd', /\btbd\b/i],
+    ['triple-question', /\?\?\?/],
+];
+
+const COMPLEXITY_PAT = /^complexity:\s*(lightweight|structural)\s*$/m;
+
+const TASK_PREFIXES = ['- [ ]', '- [x]', '- [/]', '- [-]'] as const;
+
+export interface Placeholder {
+    kind: string;
+    line: number;
+    text: string;
+}
+
+export interface GranularityResult {
+    complexity: string | null;
+    gated: boolean;
+    violations: Placeholder[];
+}
+
+function frontmatter(text: string): string {
+    if (!text.startsWith('---\n')) {
+        return '';
+    }
+    const end = text.indexOf('\n---\n', 4);
+    return end !== -1 ? text.slice(4, end) : '';
+}
+
+export function read_complexity(text: string): string | null {
+    const fm = frontmatter(text);
+    if (fm === '') {
+        return null;
+    }
+    const m = COMPLEXITY_PAT.exec(fm);
+    return m ? m[1]! : null;
+}
+
+const ANGLE_PLACEHOLDER = /<[a-z][a-z0-9 _\-/]*>/gi;
+
+/**
+ * Blank inline code spans that are COMMAND TEMPLATES, so CLI argument
+ * metasyntax is not read as an undecided step.
+ *
+ * Blanking every backtick span (the first attempt) was too blunt, and the ported
+ * test corpus proved it: `` `<file>` `` in *"Edit `<file>` and add the new
+ * method"* is a real placeholder — the file is genuinely undecided — while
+ * `` `settings set <key> <value>` `` on a step that goes on to specify
+ * zod-validation, atomicity and key-class refusal is a command signature.
+ *
+ * The discriminator is what else the span holds: strip the placeholders and if
+ * nothing but whitespace is left, the span IS the placeholder (violation); if
+ * real content remains (`settings set`), it is a command template naming its
+ * arguments (masked). Only the angle pattern gets this treatment — a literal
+ * TODO / FIXME / XXX / TBD / `???` in a task bullet is unfinished work wherever
+ * it sits, backticks included.
+ */
+function mask_command_templates(line: string): string {
+    return line.replace(/`[^`]*`/g, (span) => {
+        const withoutPlaceholders = span.slice(1, -1).replace(ANGLE_PLACEHOLDER, '');
+        return withoutPlaceholders.trim() === '' ? span : ' ';
+    });
+}
+
+export function scan_placeholders(text: string): Placeholder[] {
+    const hits: Placeholder[] = [];
+    const lines = text.split('\n');
+    for (let idx = 0; idx < lines.length; idx++) {
+        const line = lines[idx]!;
+        const stripped = line.replace(/^\s+/, '');
+        if (!TASK_PREFIXES.some((p) => stripped.startsWith(p))) {
+            continue;
+        }
+        // Command-template masking applies to the angle pattern ONLY. A literal
+        // TODO / FIXME / XXX / TBD / `???` is unfinished work wherever it sits,
+        // so those patterns read the raw line.
+        const masked = mask_command_templates(line);
+        for (const [kind, pat] of PLACEHOLDER_PATTERNS) {
+            const probe = kind === 'angle-placeholder' ? masked : line;
+            if (pat.test(probe)) {
+                hits.push({ kind, line: idx + 1, text: line.replace(/\s+$/, '') });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+
+/**
+ * Gated only for `complexity: structural`. Violations are empty when the gate
+ * is not active, regardless of placeholder presence.
+ */
+export function check_granularity(text: string): GranularityResult {
+    const complexity = read_complexity(text);
+    const gated = complexity === 'structural';
+    if (!gated) {
+        return { complexity, gated: false, violations: [] };
+    }
+    return { complexity, gated: true, violations: scan_placeholders(text) };
+}
+
+/** One human-readable problem line per violation, for a gate's problem list. */
+export function granularity_problems(text: string): string[] {
+    return check_granularity(text).violations.map(
+        (v) =>
+            `bite-sized granularity: line ${v.line} has a ${v.kind} placeholder in a ` +
+            `task bullet — a structural roadmap's steps name decided work: ${v.text.trim()}`,
+    );
+}
+
+export { PLACEHOLDER_PATTERNS, COMPLEXITY_PAT };