@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/classify_change_risk.ts

@@ -0,0 +1,281 @@
+#!/usr/bin/env tsx
+/**
+ * Deterministic risk class for a change, computed from paths and diff shape.
+ *
+ * Step 0.3 of `road-to-target-project-assurance-readiness`. **No model call**, by
+ * construction: the whole point is a class an agent cannot talk itself out of, and
+ * a classifier that asks a model is the agent's self-label wearing a script's
+ * clothes.
+ *
+ * Classes: `R0` cosmetic · `R1` internal · `R2` behaviour-changing · `R3` critical.
+ *
+ * TIES AND UNKNOWNS RESOLVE UPWARD. That is safe per change and corrosive in
+ * aggregate — once most changes read R3 the owed gate set is noise and gets worked
+ * around rather than met (Risk 2 of the roadmap). The mitigation is NOT to soften
+ * the resolution: it is the nightly R3-rate metric, with **> 40 % of changes
+ * classifying R3 named as a defect in the override list** rather than in the people
+ * meeting the gates. So this file resolves upward and the drift ledger is what
+ * catches an over-broad override list.
+ *
+ * SELF-PROTECTION. Changes to this classifier, the override list, the hook
+ * directories, CI workflows, or the agent's own config are R3 **by construction** —
+ * the one place the system can defend itself against being talked down. It is a
+ * deliberate refusal to be configurable: an override list that can be lowered by a
+ * change the list itself classifies as cosmetic protects nothing.
+ *
+ * WHAT THIS DOES NOT DO, and it is the reason the roadmap closed on a null: nothing
+ * consumes this class. Wiring it into `verify-completion-evidence` is Phase 2, and
+ * Phase 2 is cancelled on the pre-registered null route because the human-labelled
+ * corpus the class would have been validated against cannot be produced. Giving an
+ * unvalidated class real authority over every completion claim is Risk 7. So this
+ * ships as a **measurement instrument feeding the nightly drift ledger**, and its
+ * verdict owes no gate.
+ */
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export type RiskClass = 'R0' | 'R1' | 'R2' | 'R3';
+
+const ORDER: readonly RiskClass[] = ['R0', 'R1', 'R2', 'R3'];
+
+/** Upward resolution, expressed once so no caller can pick the other direction. */
+export function higher(a: RiskClass, b: RiskClass): RiskClass {
+    return ORDER.indexOf(a) >= ORDER.indexOf(b) ? a : b;
+}
+
+/**
+ * Paths whose touch is R3 regardless of anything else.
+ *
+ * Two groups, and they are listed together because they fail the same way when
+ * split: a reviewer reading only one of them cannot tell whether a path is missing
+ * on purpose.
+ *
+ * (1) DOMAIN-CRITICAL — auth, migrations, payment, billing, IaC. These are the
+ *     surfaces where a wrong class costs money or exposes data.
+ * (2) SELF-PROTECTION — this file, the assurance policy, hook directories, CI
+ *     workflows, and the agent's own settings. Without these the classifier is
+ *     one cosmetic-looking commit away from classifying itself down.
+ */
+export const R3_PATH_PATTERNS: readonly RegExp[] = [
+    // (1) domain-critical
+    /(^|\/)auth(\/|$)/i,
+    /(^|\/)migrations?(\/|$)/i,
+    /payment/i,
+    /billing/i,
+    /(^|\/)(terraform|terragrunt)(\/|$)/i,
+    /\.tf$/i,
+    /(^|\/)k8s(\/|$)/i,
+    /(^|\/)helm(\/|$)/i,
+    // (2) self-protection
+    /(^|\/)classify_change_risk\.ts$/,
+    /(^|\/)assurance-policy\.json$/,
+    /(^|\/)\.github\/workflows\//,
+    /(^|\/)hooks?\//,
+    /(^|\/)hook_manifest\.(yaml|json)$/,
+    /(^|\/)\.agent-settings\.ya?ml$/,
+    /(^|\/)agent-settings[^/]*\.ya?ml$/,
+    /(^|\/)src\/config\//,
+];
+
+/** Dependency manifests and lockfiles — a supply-chain surface, so at least R2. */
+export const DEPENDENCY_PATTERNS: readonly RegExp[] = [
+    /(^|\/)package(-lock)?\.json$/,
+    /(^|\/)pnpm-lock\.yaml$/,
+    /(^|\/)yarn\.lock$/,
+    /(^|\/)composer\.(json|lock)$/,
+    /(^|\/)(requirements[^/]*\.txt|pyproject\.toml|poetry\.lock|Pipfile(\.lock)?)$/,
+    /(^|\/)go\.(mod|sum)$/,
+    /(^|\/)Cargo\.(toml|lock)$/,
+];
+
+/**
+ * Paths that carry no behaviour.
+ *
+ * A change touching ONLY these is R0. Deliberately narrow — markdown, licences,
+ * editor config, images. `.json` is NOT here: a JSON file is as likely to be a
+ * policy as a fixture, and guessing wrong resolves downward, which is the one
+ * direction this classifier may not guess in.
+ */
+export const COSMETIC_PATTERNS: readonly RegExp[] = [
+    /\.(md|markdown|txt|rst|adoc)$/i,
+    /\.(png|jpe?g|gif|svg|webp|ico)$/i,
+    /(^|\/)(LICENSE|NOTICE|CODEOWNERS|\.gitignore|\.editorconfig|\.gitattributes)$/,
+];
+
+/** Source extensions whose edit can change behaviour. */
+const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|php|go|rs|rb|java|kt|swift|sh|bash)$/i;
+
+/** Test paths — code, but an edit confined to them is internal by default. */
+const TEST_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[a-z]+$/i;
+
+export interface Classification {
+    readonly cls: RiskClass;
+    /** The single reason that BOUND the class — never a list of contributors. */
+    readonly reason: string;
+}
+
+/**
+ * Classify a change from its touched paths.
+ *
+ * Reports the reason that BOUND the class, not every reason that applied, for the
+ * same argument the readiness matrix makes about its binding dimension: a list of
+ * contributing factors invites averaging, and the class is a max rather than a mean.
+ */
+export function classifyPaths(paths: readonly string[]): Classification {
+    if (paths.length === 0) {
+        // An empty diff is UNKNOWN, not cosmetic. Upward resolution applies to the
+        // absence of evidence exactly as it applies to ambiguous evidence — and a
+        // caller passing no paths has not told us the change is empty, only that it
+        // did not say.
+        return { cls: 'R3', reason: 'no paths supplied — unknown resolves upward' };
+    }
+    const norm = paths.map((p) => p.replace(/^\.\//, ''));
+
+    for (const p of norm) {
+        for (const re of R3_PATH_PATTERNS) {
+            if (re.test(p)) return { cls: 'R3', reason: `override-list path: ${p}` };
+        }
+    }
+    for (const p of norm) {
+        for (const re of DEPENDENCY_PATTERNS) {
+            if (re.test(p)) return { cls: 'R2', reason: `dependency manifest: ${p}` };
+        }
+    }
+    if (norm.every((p) => COSMETIC_PATTERNS.some((re) => re.test(p)))) {
+        return { cls: 'R0', reason: 'every touched path is non-behavioural' };
+    }
+    const nonTestCode = norm.filter((p) => CODE_RE.test(p) && !TEST_RE.test(p));
+    if (nonTestCode.length > 0) {
+        return { cls: 'R2', reason: `production code touched: ${nonTestCode[0]!}` };
+    }
+    if (norm.some((p) => TEST_RE.test(p))) {
+        return { cls: 'R1', reason: 'test-only change' };
+    }
+    // Reached only by a path that is neither cosmetic, nor code, nor a test, nor on
+    // a list — a config or data file the patterns above do not name. Upward.
+    return { cls: 'R2', reason: `unrecognised path shape: ${norm[0]!}` };
+}
+
+/** `git diff --name-only <range>` — the only git call this script makes. */
+export function changedPaths(range: string, cwd = REPO_ROOT): string[] {
+    const r = spawnSync('git', ['diff', '--name-only', range], {
+        cwd,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.status !== 0) return [];
+    return (r.stdout || '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l !== '');
+}
+
+function selfTest(): number {
+    const rel = 'src/scripts/classify_change_risk.ts';
+    const run = (args: readonly string[]): number => runGateCli(REPO_ROOT, rel, args, REPO_ROOT);
+    return runSelfTest({
+        gate: 'classify_change_risk',
+        minCases: 6,
+        minRejectCases: 2,
+        cases: [
+            {
+                // 2.3's property, as far as it can be proven without Phase 2's
+                // policy file: an edit to the classifier itself is R3.
+                name: 'the classifier classifies an edit to ITSELF as R3',
+                expect: 'accept',
+                run: () => run(['--paths', rel, '--assert-class', 'R3']),
+            },
+            {
+                name: 'a CI workflow edit is R3',
+                expect: 'accept',
+                run: () => run(['--paths', '.github/workflows/tests.yml', '--assert-class', 'R3']),
+            },
+            {
+                name: 'a docs-only change is R0',
+                expect: 'accept',
+                run: () => run(['--paths', 'README.md', '--assert-class', 'R0']),
+            },
+            {
+                name: 'a test-only change is R1',
+                expect: 'accept',
+                run: () => run(['--paths', 'tests/scripts/x.test.ts', '--assert-class', 'R1']),
+            },
+            {
+                // The reject arms matter more than the accept arms: a suite that
+                // only proves passes proves the harness runs, not that the
+                // classifier discriminates.
+                name: 'asserting R0 for a migrations path is refused',
+                expect: 'reject',
+                run: () => run(['--paths', 'db/migrations/001.sql', '--assert-class', 'R0']),
+            },
+            {
+                name: 'asserting R1 for production code is refused',
+                expect: 'reject',
+                run: () => run(['--paths', 'src/scripts/release.ts', '--assert-class', 'R1']),
+            },
+            {
+                name: 'asserting R0 for an empty path set is refused (unknown resolves upward)',
+                expect: 'reject',
+                run: () => run(['--paths', '', '--assert-class', 'R0']),
+            },
+        ],
+    });
+}
+
+export function main(argv: readonly string[]): number {
+    if (argv.includes('--self-test')) {
+        if (process.env['GATE_SELF_TEST_CHILD'] === '1') {
+            process.stderr.write('classify_change_risk: refusing to recurse into --self-test\n');
+            return 1;
+        }
+        return selfTest();
+    }
+    const pathsIdx = argv.indexOf('--paths');
+    const rangeIdx = argv.indexOf('--range');
+    const assertIdx = argv.indexOf('--assert-class');
+    const json = argv.includes('--json');
+
+    let paths: string[];
+    if (pathsIdx >= 0) {
+        paths = (argv[pathsIdx + 1] ?? '')
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s !== '');
+    } else {
+        paths = changedPaths(rangeIdx >= 0 ? (argv[rangeIdx + 1] ?? 'HEAD~1...HEAD') : 'HEAD~1...HEAD');
+    }
+
+    const v = classifyPaths(paths);
+    if (json) {
+        process.stdout.write(
+            JSON.stringify({ class: v.cls, reason: v.reason, files: paths.length }) + '\n',
+        );
+    } else {
+        process.stdout.write(`${v.cls} — ${v.reason} (${String(paths.length)} file(s))\n`);
+    }
+
+    if (assertIdx >= 0) {
+        const want = argv[assertIdx + 1];
+        if (want !== v.cls) {
+            process.stderr.write(`classify_change_risk: expected ${String(want)}, got ${v.cls}\n`);
+            return 1;
+        }
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    const invoked = process.argv[1];
+    return invoked !== undefined && path.resolve(invoked) === path.resolve(_HERE);
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/compute_skill_tiers.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env tsx
+/**
+ * compute_skill_tiers — which skills the host will describe, and which it won't.
+ *
+ * Phase 2.1 of `road-to-skill-delivery-over-mcp`. Tier A is the set predicted to
+ * survive the host's listing budget; Tier B is everything else, which reaches
+ * the model only through the turnkey server's `suggest_skill_for_task` /
+ * `read_skill`.
+ *
+ * THE OUTPUT'S REAL JOB IS `model_inputs`, not the split. A tier assignment
+ * without the order that produced it is unexplainable and unreproducible, and
+ * risk 5 of the roadmap is precisely that a skill flips tiers between installs
+ * and nobody can tell why. So every run records the context window, the
+ * fraction, the per-entry cap, how many usage rows it actually had, and which
+ * fallback it used when it had none.
+ *
+ * IT WILL USUALLY BE A FALLBACK. `agents/runtime/metrics/skill-usage.jsonl` was
+ * last written 2026-05-16 and does not exist in a fresh checkout, so the
+ * honest common case is `fallback: "alphabetical"` — and the pinned observation
+ * in `tests/scripts/host_listing_model.test.ts` shows that fallback disagreeing
+ * with the one real host observation on four of eight sampled entries. A Tier B
+ * verdict from a fallback order is therefore a PREDICTION, not a measurement.
+ * The `tiered` projection stays opt-in for exactly that reason.
+ *
+ * Output goes to `agents/runtime/state/skill-tiers.json` (gitignored, per-machine).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+    CLAUDE_CODE_LISTING_DEFAULTS,
+    modelListingBudget,
+    type CatalogueEntry,
+    type ModelAssumption,
+} from './_lib/host_listing_model.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+export const DEFAULT_SKILLS_DIR = path.join(REPO, 'src', 'skills');
+export const USAGE_PATH = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage.jsonl');
+export const TIERS_PATH = path.join(REPO, 'agents', 'runtime', 'state', 'skill-tiers.json');
+
+export type Fallback = 'alphabetical' | 'pack-scope' | null;
+
+export interface ModelInputs {
+    context_window_tokens: number;
+    fraction: number;
+    per_entry_cap_chars: number;
+    chars_per_token: number;
+    budget_chars: number;
+    usage_rows_used: number;
+    fallback: Fallback;
+    fill_order: string;
+}
+
+export interface TierSplit {
+    schema: 1;
+    computed_at: string;
+    skills_dir: string;
+    catalogue_count: number;
+    model_inputs: ModelInputs;
+    model_assumptions: readonly ModelAssumption[];
+    tier_a: string[];
+    tier_b: string[];
+}
+
+/** `description:` length in characters, or 0 when the file carries none. */
+function descriptionChars(file: string): number {
+    const raw = fs.readFileSync(file, 'utf8');
+    const fm = /^---\n([\s\S]*?)\n---/.exec(raw);
+    if (!fm) return 0;
+    const line = /^description:[ \t]*(.*)$/m.exec(fm[1]!);
+    if (!line) return 0;
+    return line[1]!.replace(/^["']|["']$/g, '').length;
+}
+
+/** The projected catalogue, alphabetically. Missing dir → empty, never a throw. */
+export function readCatalogue(skillsDir: string): CatalogueEntry[] {
+    if (!fs.existsSync(skillsDir)) return [];
+    return fs
+        .readdirSync(skillsDir)
+        .filter((slug) => fs.existsSync(path.join(skillsDir, slug, 'SKILL.md')))
+        .map((slug) => ({
+            name: slug,
+            descriptionChars: descriptionChars(path.join(skillsDir, slug, 'SKILL.md')),
+        }))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Invocation-frequency order from the usage ledger, most-invoked first.
+ *
+ * A malformed line is skipped rather than fatal: the ledger is appended by a
+ * collector reading host session files, and one bad line must not turn the whole
+ * order into a silent empty — which would look identical to "no usage yet" and
+ * send every skill to Tier B.
+ */
+export function usageOrderFrom(usagePath: string = USAGE_PATH): string[] {
+    if (!fs.existsSync(usagePath)) return [];
+    const counts = new Map<string, number>();
+    for (const line of fs.readFileSync(usagePath, 'utf8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let rec: unknown;
+        try {
+            rec = JSON.parse(trimmed);
+        } catch {
+            continue;
+        }
+        if (!rec || typeof rec !== 'object') continue;
+        const slug = (rec as Record<string, unknown>).slug;
+        if (typeof slug !== 'string' || !slug) continue;
+        counts.set(slug, (counts.get(slug) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map(([slug]) => slug);
+}
+
+export interface ComputeOptions {
+    skillsDir?: string;
+    /** Explicit order; omit to read the ledger. */
+    usageOrder?: readonly string[];
+    contextWindowTokens?: number;
+    fraction?: number;
+}
+
+export function computeTiers(opts: ComputeOptions = {}): TierSplit {
+    const skillsDir = opts.skillsDir ?? DEFAULT_SKILLS_DIR;
+    const catalogue = readCatalogue(skillsDir);
+    const usageOrder = opts.usageOrder ?? usageOrderFrom();
+    const contextWindowTokens = opts.contextWindowTokens ?? 200_000;
+    const fraction = opts.fraction ?? CLAUDE_CODE_LISTING_DEFAULTS.fraction;
+
+    const result = modelListingBudget(catalogue, { contextWindowTokens, fraction, usageOrder });
+
+    return {
+        schema: 1,
+        computed_at: new Date().toISOString().slice(0, 10),
+        skills_dir: skillsDir,
+        catalogue_count: catalogue.length,
+        model_inputs: {
+            context_window_tokens: contextWindowTokens,
+            fraction,
+            per_entry_cap_chars: CLAUDE_CODE_LISTING_DEFAULTS.perEntryCapChars,
+            chars_per_token: CLAUDE_CODE_LISTING_DEFAULTS.charsPerToken,
+            budget_chars: result.budgetChars,
+            usage_rows_used: usageOrder.length,
+            // `pack-scope` is reserved for the day a pack-ordered fallback is
+            // wired; today the only fallback that exists is alphabetical, and
+            // naming a fallback that never runs would be worse than naming none.
+            fallback: usageOrder.length > 0 ? null : 'alphabetical',
+            fill_order: result.fillOrder,
+        },
+        model_assumptions: result.assumptions,
+        tier_a: result.surviving,
+        tier_b: result.bare,
+    };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const dirIdx = argv.indexOf('--skills-dir');
+    const skillsDir = dirIdx >= 0 ? argv[dirIdx + 1] : undefined;
+    const split = computeTiers(skillsDir === undefined ? {} : { skillsDir });
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(split, null, 2)}\n`);
+        return 0;
+    }
+    fs.mkdirSync(path.dirname(TIERS_PATH), { recursive: true });
+    fs.writeFileSync(TIERS_PATH, `${JSON.stringify(split, null, 2)}\n`, 'utf8');
+    process.stdout.write(
+        `✅  skill tiers → ${path.relative(REPO, TIERS_PATH)}\n` +
+            `    Tier A ${split.tier_a.length} · Tier B ${split.tier_b.length} ` +
+            `of ${split.catalogue_count}\n` +
+            `    order: ${split.model_inputs.fill_order}` +
+            `${split.model_inputs.fallback ? ` (fallback: ${split.model_inputs.fallback})` : ''}, ` +
+            `${split.model_inputs.usage_rows_used} usage row(s)\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+    process.exit(main());
+}

package/src/scripts/condense.ts

@@ -48,6 +48,7 @@ import {
 // bundled-CLI-entry-guard landmine. Verified before wiring, not assumed.
 import { build_thin } from './project_thin_rules.js';
 import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
+import { normalizeLeanProjectionMode, writesThinFiles, type LeanProjectionMode } from './_lib/lean_projection_mode.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import { project_settings_path, load_agent_settings } from './_lib/agent_settings.js';
 import { rule_is_compile_enabled } from './_lib/compile_time_toggles.js';
@@ -458,20 +459,14 @@ function _read_projection_scope_dedup(): boolean {
 }
 
 
-function _lean_projection_mode(): string {
+function _lean_projection_mode(): LeanProjectionMode {
     const data = load_agent_settings({ project_path: MODULE_STATE.SETTINGS_FILE });
     const lean = data['lean_projection'];
-    if (
-        typeof lean === 'object' &&
-        lean !== null &&
-        !Array.isArray(lean) &&
-        String((lean as Record<string, unknown>)['mode'] ?? '')
-            .trim()
-            .toLowerCase() === 'thin'
-    ) {
-        return 'thin';
-    }
-    return 'eager-all';
+    const raw =
+        typeof lean === 'object' && lean !== null && !Array.isArray(lean)
+            ? (lean as Record<string, unknown>)['mode']
+            : '';
+    return normalizeLeanProjectionMode(raw);
 }
 
 // --- hashing -----------------------------------------------------------------
@@ -1126,7 +1121,7 @@ export function generate_rule_symlinks(): number {
     const tool_dirs = _filter_tool_dirs(TOOL_DIRS);
 
     let thin_files: Record<string, string> | null = null;
-    if (_lean_projection_mode() === 'thin') {
+    if (writesThinFiles(_lean_projection_mode())) {
         // DEAD-SWITCH REPAIR (road-to-renewal-foundation Phase 2). This branch
         // used to THROW: the port was skipped as "out of scope, not exercised by
         // golden parity", which left a documented, settings-selectable mode that