@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/token_sink_report.ts

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Token-sink ranking + re-read measurement over the local transcript store.
+ *
+ * `road-to-role-scoped-spawn-profiles` Phase 3 Steps 1-3. Phase 3 is declared
+ * independent of that roadmap's Phases 0-2 in both directions: it needs no
+ * payload capture and it arms nothing.
+ *
+ * **The denominator is published, deliberately.** Step 2's whole content is
+ * that *"a sink's share is only meaningful against the total it was measured
+ * from, and the store is one machine's history — the report says so rather
+ * than reading as a property of the package."* Every rendered figure is
+ * therefore accompanied by the record count, the date range, and the
+ * single-store caveat, and {@link Report.provenance} carries that sentence as
+ * data so a JSON consumer cannot strip it by taking the numbers only.
+ *
+ * **Two things this report is NOT.** It is not a cost figure — the weighting
+ * is the cost-SHAPED `weightedInputUnits` from `_lib/cc_transcript.ts`, not a
+ * price. And the wasted-token column is a `chars / 4` proxy over duplicate
+ * `tool_result` bodies (see `_lib/transcript_reads.ts`), because the
+ * transcript records no per-tool-result token count; it is named
+ * `wasted_tokens_proxy` everywhere so the label travels with the number.
+ *
+ * Class A: in-process, per-invocation, read-only, no network, no daemon, no
+ * writes outside stdout.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/token_sink_report [--format text|json]
+ *     [--root <path>] [--max-age-days <n>] [--top <n>]
+ */
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    DEFAULT_PROJECTS_ROOT,
+    billableInputTokens,
+    listTranscriptFiles,
+    scanTranscripts,
+    weightedInputUnits,
+    type TranscriptRecord,
+} from './_lib/cc_transcript.js';
+import { computeRereads, type RereadResult } from './_lib/transcript_reads.js';
+
+/**
+ * One token sink: a `bucket/model` pair. The bucket half is what makes the
+ * ranking answer the question the roadmap asks — `main` versus `subagent` is
+ * the axis a scoping decision acts on — and the model half keeps a cheap
+ * worker's traffic from being summed with an expensive orchestrator's.
+ */
+export interface Sink {
+    sink: string;
+    bucket: string;
+    model: string;
+    calls: number;
+    billable_input: number;
+    weighted_input_units: number;
+    /** This sink's share of total weighted input units, 0..1. */
+    weighted_share: number;
+}
+
+export function rankSinks(records: readonly TranscriptRecord[]): Sink[] {
+    const acc = new Map<string, Sink>();
+    for (const r of records) {
+        const key = `${r.bucket}/${r.model}`;
+        const row = acc.get(key) ?? {
+            sink: key,
+            bucket: r.bucket,
+            model: r.model,
+            calls: 0,
+            billable_input: 0,
+            weighted_input_units: 0,
+            weighted_share: 0,
+        };
+        row.calls += 1;
+        row.billable_input += billableInputTokens(r.usage);
+        row.weighted_input_units += weightedInputUnits(r.usage);
+        acc.set(key, row);
+    }
+    const rows = [...acc.values()];
+    const total = rows.reduce((s, r) => s + r.weighted_input_units, 0);
+    for (const r of rows) {
+        r.weighted_share = total > 0 ? r.weighted_input_units / total : 0;
+    }
+    rows.sort((a, b) => b.weighted_input_units - a.weighted_input_units || a.sink.localeCompare(b.sink));
+    return rows;
+}
+
+export interface Options {
+    format: 'text' | 'json';
+    root: string;
+    maxAgeDays: number;
+    top: number;
+}
+
+const DEFAULT_TOP = 15;
+
+export function parseArgs(argv: string[]): Options {
+    const opts: Options = {
+        format: 'text',
+        root: DEFAULT_PROJECTS_ROOT,
+        maxAgeDays: 90,
+        top: DEFAULT_TOP,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined) continue;
+        if (a === '--format') opts.format = (argv[++i] as Options['format']) ?? opts.format;
+        else if (a.startsWith('--format=')) opts.format = a.slice('--format='.length) as Options['format'];
+        else if (a === '--root') opts.root = argv[++i] ?? opts.root;
+        else if (a.startsWith('--root=')) opts.root = a.slice('--root='.length);
+        else if (a === '--max-age-days') opts.maxAgeDays = Number(argv[++i]) || opts.maxAgeDays;
+        else if (a.startsWith('--max-age-days=')) opts.maxAgeDays = Number(a.slice('--max-age-days='.length)) || opts.maxAgeDays;
+        else if (a === '--top') opts.top = Number(argv[++i]) || opts.top;
+        else if (a.startsWith('--top=')) opts.top = Number(a.slice('--top='.length)) || opts.top;
+    }
+    if (opts.format !== 'text' && opts.format !== 'json') opts.format = 'text';
+    return opts;
+}
+
+/**
+ * The single-store caveat, carried as DATA rather than as rendering. A JSON
+ * consumer that keeps `sinks` and drops the prose still keeps this field.
+ */
+export const PROVENANCE =
+    'Local-store-derived: computed from one machine\'s ~/.claude/projects transcripts. ' +
+    'Every share below is a fact about this store, not a property of the package.';
+
+export interface Report {
+    schema: 'token-sink-report/v1';
+    root: string;
+    window_days: number;
+    provenance: string;
+    total_seen: number;
+    deduped_count: number;
+    dedup_ratio: number;
+    legs_scanned: number;
+    date_range: { first: string | null; last: string | null };
+    sinks: Sink[];
+    rereads: RereadResult;
+    wasted_tokens_proxy_note: string;
+}
+
+const PROXY_NOTE =
+    'wasted_tokens_proxy is a chars / 4 estimate over duplicate tool_result bodies. ' +
+    'The transcript records no per-tool-result token count, so this is a proxy, never a measurement.';
+
+export function buildReport(opts: Options): Report {
+    const scan = scanTranscripts({ root: opts.root, maxAgeDays: opts.maxAgeDays });
+    const files = listTranscriptFiles({ root: opts.root, maxAgeDays: opts.maxAgeDays });
+    const rereads = computeRereads(files);
+
+    const stamps = scan.records
+        .map((r) => r.timestamp)
+        .filter((t): t is string => typeof t === 'string' && t.length > 0)
+        .sort();
+
+    return {
+        schema: 'token-sink-report/v1',
+        root: opts.root,
+        window_days: opts.maxAgeDays,
+        provenance: PROVENANCE,
+        total_seen: scan.totalSeen,
+        deduped_count: scan.dedupedCount,
+        dedup_ratio: scan.dedup_ratio,
+        legs_scanned: rereads.legs_scanned,
+        date_range: { first: stamps[0] ?? null, last: stamps[stamps.length - 1] ?? null },
+        sinks: rankSinks(scan.records),
+        rereads,
+        wasted_tokens_proxy_note: PROXY_NOTE,
+    };
+}
+
+function pct(v: number): string {
+    return `${(v * 100).toFixed(1)}%`;
+}
+
+export function renderText(r: Report, top: number = DEFAULT_TOP): string {
+    const out: string[] = [];
+    out.push('token-sink report · schema token-sink-report/v1');
+    out.push('');
+    out.push('Denominator (read this before any share below):');
+    out.push(`  records (deduped) : ${r.deduped_count} of ${r.total_seen} seen (dedup ${pct(r.dedup_ratio)})`);
+    out.push(`  transcript legs   : ${r.legs_scanned}`);
+    out.push(`  date range        : ${r.date_range.first ?? 'n/a'} .. ${r.date_range.last ?? 'n/a'}`);
+    out.push(`  window            : ${r.window_days} days · root ${r.root}`);
+    out.push(`  provenance        : ${r.provenance}`);
+    out.push('');
+
+    if (r.deduped_count === 0) {
+        out.push('No records in this store for the given window — nothing to rank.');
+        out.push('');
+    } else {
+        out.push(`Token sinks, ranked by weighted input units (top ${top}):`);
+        for (const s of r.sinks.slice(0, top)) {
+            out.push(
+                `  ${s.sink.padEnd(38)} calls=${String(s.calls).padStart(6)} ` +
+                    `weighted=${s.weighted_input_units.toFixed(0).padStart(12)} share=${pct(s.weighted_share)}`,
+            );
+        }
+        out.push('');
+    }
+
+    out.push('Re-reads within a single transcript leg:');
+    out.push(`  reads observed    : ${r.rereads.total_reads}`);
+    out.push(`  duplicate reads   : ${r.rereads.duplicate_reads}`);
+    out.push(`  wasted (proxy)    : ${r.rereads.wasted_tokens_proxy} tokens`);
+    out.push(`  note              : ${r.wasted_tokens_proxy_note}`);
+    if (r.rereads.files.length === 0) {
+        out.push('  no file was read twice inside one leg in this window.');
+    } else {
+        out.push(`  top ${top} by wasted (proxy):`);
+        for (const f of r.rereads.files.slice(0, top)) {
+            out.push(
+                `    ${f.file_path}\n      reads=${f.total_reads} dup=${f.duplicate_reads} ` +
+                    `legs_with_reread=${f.legs_with_reread} wasted_proxy=${f.wasted_tokens_proxy}`,
+            );
+        }
+    }
+    return out.join('\n');
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const opts = parseArgs(argv);
+    const report = buildReport(opts);
+    if (opts.format === 'json') {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else {
+        process.stdout.write(renderText(report, opts.top) + '\n');
+    }
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+if (!_bundled && process.argv[1] !== undefined) {
+    const invokedUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (pathToFileURL(_HERE).href === invokedUrl) process.exit(main());
+}

package/src/scripts/trigger_coverage.ts

@@ -338,14 +338,18 @@ interface ParsedArgs {
     json: boolean;
     /** `rule` keeps the pinned byte-identical contract; `skill` is additive. */
     scope: 'rule' | 'skill';
+    /** `--ratchet`: compare the skill scope against its published baseline. */
+    ratchet: boolean;
 }
 
 function parse_args(argv: string[]): ParsedArgs {
-    const out: ParsedArgs = { json: false, scope: 'rule' };
+    const out: ParsedArgs = { json: false, scope: 'rule', ratchet: false };
     for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i]!;
         if (a === '--json') {
             out.json = true;
+        } else if (a === '--ratchet') {
+            out.ratchet = true;
         } else if (a === '--scope') {
             const v = argv[i + 1];
             if (v !== 'rule' && v !== 'skill') {
@@ -355,7 +359,9 @@ function parse_args(argv: string[]): ParsedArgs {
             out.scope = v;
             i += 1;
         } else if (a === '-h' || a === '--help') {
-            process.stdout.write('usage: trigger_coverage [-h] [--json] [--scope rule|skill]\n');
+            process.stdout.write(
+                'usage: trigger_coverage [-h] [--json] [--scope rule|skill] [--ratchet]\n',
+            );
             process.exit(0);
         }
     }
@@ -372,6 +378,113 @@ function parse_args(argv: string[]): ParsedArgs {
  * its own change, not against a number invented on the day the instrument
  * shipped.
  */
+/** The published skill-coverage baseline `--ratchet` compares against. */
+export const SKILL_RATCHET_BASELINE = path.join(
+    REPO_ROOT,
+    'agents',
+    'evidence',
+    'metrics',
+    'skill-trigger-coverage-baseline.json',
+);
+
+export interface SkillRatchetBaseline {
+    skills_with_triggers: number;
+    activations: number;
+}
+
+/** Read the baseline, or `null` when none is published yet. */
+export function loadSkillRatchetBaseline(file = SKILL_RATCHET_BASELINE): SkillRatchetBaseline | null {
+    if (!fs.existsSync(file)) return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>;
+        const c = parsed['skills_with_triggers'];
+        const a = parsed['activations'];
+        if (typeof c !== 'number' || typeof a !== 'number') return null;
+        return { skills_with_triggers: c, activations: a };
+    } catch {
+        return null;
+    }
+}
+
+export interface RatchetVerdict {
+    ok: boolean;
+    lines: string[];
+}
+
+/**
+ * The Phase-3.2 ratchet, as a pure function of two readings.
+ *
+ * TWO directions, and only one of them is a floor. Coverage
+ * (`skills_with_triggers`) may only RISE — a tranche that removes triggers is
+ * the regression this exists to catch. Activations over the matrix may only
+ * FALL OR HOLD — that is the noise ceiling, and it is the half that makes
+ * seeding safe rather than merely measurable.
+ *
+ * A missing baseline is NOT a pass. It is `ok: false` with a line saying to
+ * publish one, because a ratchet that silently no-ops when its baseline is gone
+ * is the failure mode a ratchet exists to prevent.
+ */
+export function ratchetVerdict(
+    current: SkillRatchetBaseline,
+    baseline: SkillRatchetBaseline | null,
+): RatchetVerdict {
+    if (baseline === null) {
+        return {
+            ok: false,
+            lines: [
+                '❌  no published baseline — cannot ratchet.',
+                `    Publish one: {"skills_with_triggers": ${current.skills_with_triggers}, ` +
+                    `"activations": ${current.activations}}`,
+                `    at agents/evidence/metrics/skill-trigger-coverage-baseline.json`,
+            ],
+        };
+    }
+    const lines: string[] = [];
+    let ok = true;
+    if (current.skills_with_triggers < baseline.skills_with_triggers) {
+        ok = false;
+        lines.push(
+            `❌  coverage fell: ${baseline.skills_with_triggers} → ${current.skills_with_triggers} ` +
+                'skills declaring triggers. The ratchet only turns one way.',
+        );
+    } else {
+        lines.push(
+            `✅  coverage ${baseline.skills_with_triggers} → ${current.skills_with_triggers} ` +
+                'skills declaring triggers.',
+        );
+    }
+    if (current.activations > baseline.activations) {
+        ok = false;
+        lines.push(
+            `❌  matrix activations rose: ${baseline.activations} → ${current.activations}. ` +
+                'A tranche may raise coverage only without raising noise.',
+        );
+    } else {
+        lines.push(`✅  matrix activations ${baseline.activations} → ${current.activations}.`);
+    }
+    return { ok, lines };
+}
+
+function runSkillRatchetCli(json: boolean): number {
+    const report = runSkillScope(loadSkillTriggers(SKILLS_DIR), loadMatrixPrompts(MATRIX_DIR));
+    const current = {
+        skills_with_triggers: report.skills_with_triggers,
+        activations: report.activations,
+    };
+    const verdict = ratchetVerdict(current, loadSkillRatchetBaseline());
+    if (json) {
+        process.stdout.write(_jsonDumps({ current, ok: verdict.ok, lines: verdict.lines }) + '\n');
+        return verdict.ok ? 0 : 1;
+    }
+    for (const line of verdict.lines) process.stdout.write(`${line}\n`);
+    process.stdout.write(
+        verdict.ok
+            ? '\nskill-trigger ratchet: OK\n'
+            : '\nskill-trigger ratchet: FAILED\n',
+    );
+    return verdict.ok ? 0 : 1;
+}
+
 function runSkillScopeCli(json: boolean): number {
     const report = runSkillScope(loadSkillTriggers(SKILLS_DIR), loadMatrixPrompts(MATRIX_DIR));
     if (json) {
@@ -405,7 +518,13 @@ function runSkillScopeCli(json: boolean): number {
 
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
-    if (args.scope === 'skill') return runSkillScopeCli(args.json);
+    if (args.ratchet && args.scope !== 'skill') {
+        process.stderr.write('error: --ratchet requires --scope skill\n');
+        return 2;
+    }
+    if (args.scope === 'skill') {
+        return args.ratchet ? runSkillRatchetCli(args.json) : runSkillScopeCli(args.json);
+    }
 
     let isFile = false;
     try {

package/src/scripts/update_counts.ts

@@ -281,9 +281,13 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
             // claim names as its own method.
             ['(installs ships )(\\d+)( of )', 'skills_scoped'],
             ['( of )(\\d+)( skills \\(untagged core)', 'skills'],
-            // "14 of 111 governed rules" — the total was scanner-checked and
-            // generator-blind for the same reason.
-            ['( of )(\\d+)( governed rules \\()', 'rules'],
+            // The "N of M governed rules" position was retired on 2026-08-23:
+            // the `enforcement-coverage-resolved` entry no longer restates any
+            // enforcement figure, because five hand-written numbers for one
+            // property is the defect `check_enforcement_denominator` now reds
+            // on. The denominator lives in ONE place — the resolver's own output,
+            // projected into docs/proof.md § 4b — so there is no longer a
+            // literal here for a generator to keep in sync.
         ],
     ],
     [

package/src/scripts/validate_frontmatter.ts

@@ -872,6 +872,69 @@ export function check_obligation_frequency(
     ];
 }
 
+/**
+ * Shape check for a skill's optional `scope:` write-scope declaration.
+ *
+ * WHAT IT CHECKS, and only this: when `scope:` is present it carries exactly ONE
+ * of `verification_command` / `verification_reason`. The `access` enum, the
+ * `pattern` shape and the closed key set are `skill.schema.json`'s and are
+ * already enforced by {@link validate} — including through `skill_linter`, which
+ * calls the same validator. This covers the one constraint JSON Schema cannot
+ * express in the subset implemented here: **exactly one of two optional
+ * siblings**. `oneOf` / `anyOf` / `not` are not implemented (nor are
+ * `minProperties` / `maxProperties`), so a schema-only attempt would be silently
+ * inert — which is worse than absent, because it reads as enforced.
+ *
+ * WHY EXACTLY ONE. Neither branch is a formality. A declaration with NEITHER is a
+ * scope claim nobody can check and nobody has excused, which is the pro-forma
+ * field the whole shape exists to avoid. A declaration with BOTH reads as
+ * "verified, with an excuse attached" — and the excuse is the half a reader would
+ * act on, so the pair is strictly less informative than either alone.
+ *
+ * WHY IT LIVES HERE AND NOT IN `skill_linter.ts`. It was written there and
+ * `check_source_size_budget` refused it: `skill_linter.ts` is 4,742 lines, the
+ * ratchet sums lines ABOVE 1,500 per file, and 63 added lines were 63 new
+ * violations against a shrink-only baseline. Extracting the body to `_lib` still
+ * left the import plus the call, i.e. +2, and a ratchet turns one way. This file
+ * is 1,120 lines, so the same code costs zero — and it sits beside
+ * {@link check_obligation_frequency}, the existing precedent for an
+ * artefact-specific check that the generic validator cannot express.
+ *
+ * WHAT IT DOES NOT CHECK, stated plainly: whether the declared paths are the
+ * paths the skill actually writes. Nothing observes a skill's writes, so that
+ * half is model-carried and `scope:` is a declaration, not a control.
+ */
+export function check_scope_declaration(data: Record<string, YamlValue>): SchemaError[] {
+    const scope = data['scope'];
+    if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) return [];
+    const keys = scope as Record<string, YamlValue>;
+    const hasCommand = typeof keys['verification_command'] === 'string';
+    const hasReason = typeof keys['verification_reason'] === 'string';
+    if (hasCommand && hasReason) {
+        return [
+            new SchemaError(
+                '$.scope',
+                'scope-verification-both',
+                'declares BOTH verification_command and verification_reason — exactly one. A reason ' +
+                    'beside a command reads as a verified claim with an excuse attached, and the excuse ' +
+                    'is the half a reader would act on.',
+            ),
+        ];
+    }
+    if (!hasCommand && !hasReason) {
+        return [
+            new SchemaError(
+                '$.scope',
+                'scope-verification-missing',
+                'declares neither verification_command nor verification_reason — exactly one. A scope ' +
+                    'claim with no command and no stated reason is unfalsifiable, which is the ' +
+                    'pro-forma field this declaration exists to avoid.',
+            ),
+        ];
+    }
+    return [];
+}
+
 // --- CLI entry point -------------------------------------------------------
 
 /** Yield `[artefact_type, path]` pairs for all lintable artefacts. */
@@ -999,6 +1062,9 @@ export function _main(argv: string[]): number {
             if (artefactType === 'rule') {
                 errors.push(...check_obligation_frequency(p, text, data));
             }
+            if (artefactType === 'skill') {
+                errors.push(...check_scope_declaration(data));
+            }
             const fatal = errors.filter((e) => e.severity === 'error');
             const warnings = errors.filter((e) => e.severity === 'warning');
             if (fatal.length > 0) {

package/src/server/schemas/settings.ts

@@ -511,6 +511,11 @@ export const settingsSchema = z.object({
                 'PreToolUse anti-slop nudge (road-to-anti-slop-detector Phase 3). Default off. When on, runs the lint_design_slop registry against about-to-be-written UI content and WARNS (never blocks) on P0/P1 aesthetic tells (side-stripe, gradient-text, magic z-index, …). Flags are rebuttable via DESIGN.md / design-slop-disable. Anti-loop: a file::rule signature surfaced 3x goes silent. Host-limited convenience layer; the universal gate is the lint_design_slop linter/CI.',
             ),
         }).default({}),
+        design_pass: z.object({
+            enabled: z.boolean().default(false).describe(
+                'PostToolUse + stop design pass (road-to-frontend-power E1.1/E1.2/E1.3). Default off. One concern on two slots: on post_tool_use a write to a UI surface delivers the design findings as context and never blocks; on stop the same pass runs over every UI file touched this session, deduped against what the post pass surfaced, and a P0 objective floor (contrast, font size, heading skip, focus) blocks with a continuation. P1-P3 never block. post_tool_use rather than pre_tool_use for two measured reasons: pre_tool_use is declared by three hosts and honoured by one while post_tool_use is declared by six, and _lib/ui_surface.ts is a path predicate, so a pre-write gate cannot fire on the first write of a new surface. A pass that could not fully run reports verification: degraded with a reason rather than passing silently. Does not replace design_slop: two design keys is the honest state until the tiering experiment has a number.',
+            ),
+        }).default({}),
         ui_route_nudge: z.object({
             enabled: z.boolean().default(false).describe(
                 'PreToolUse UI-route nudge (road-to-frontend-skill-application Phase 4). Default off. When on, a Write/Edit to a UI surface with no design consultation latched this session WARNS (never blocks) naming the route — run existing-ui-audit, then the fe-design loop. A read or search touching fe-design / existing-ui-audit / design-review / design-intelligence latches consultation and silences it for the session. Anti-loop: at most 2 nudges per session. It does not read the rules: the UI-surface decision comes from _lib/ui_surface.ts and no code parses rule frontmatter, so this runs parallel to the two UI rules rather than consuming their triggers, and a test keeps the sets from drifting. It is a nudge, so their enforced_by: none stays accurate.',