@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/layer_baseline_report.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env tsx
+/**
+ * The rule layer a setup delivers today, per host, as a reproducible fixture.
+ *
+ * Installed layer: a real `--global --tools=<host>` install into a scratch HOME,
+ * which is the only scope a consumer gets (ADR-020). Projected layer: the
+ * project rule directories of the package root at the measured commit. Hook
+ * commands: what the install wrote into the scratch HOME's claude settings.
+ * Resolved form: the layer-form decision fed the scratch HOME's machine evidence.
+ *
+ * DETERMINISTIC BY EXCLUSION, NOT BY CHANCE. A receipt, lock or install log is
+ * never read: each carries an install time. The scratch root is replaced by
+ * `<HOME>` and the measured checkout by `<PACKAGE_ROOT>` before a hook command
+ * is recorded, and the host's own version is not
+ * read, because it belongs to the machine and not to the commit. What remains is
+ * a function of the package tree, so two runs at one commit are byte-equal.
+ *
+ * REPORT-ONLY: exit 0 whenever every install ran, 1 when one failed, 2 on usage.
+ * Not named `check_*` or `lint_*`, which would enter it into the gate population.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/layer_baseline_report                     # print
+ *   ./scripts-run src/scripts/layer_baseline_report --write             # write the evidence file
+ *   ./scripts-run src/scripts/layer_baseline_report --package-root <dir> # measure another checkout
+ *   ./scripts-run src/scripts/layer_baseline_report --hosts claude-code # a subset
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { GLOBAL_RULE_DIRS, PROJECT_RULE_DIRS } from '../install/globalRuleLayers.js';
+import { decideLayerForm, gatherShippedEvidence, type LayerFormDecision } from './_lib/layer_form_decision.js';
+import { readMachineEvidence, withMachineEvidence } from './_lib/layer_form_evidence.js';
+import { is_thin_entry } from './_lib/thin_rules.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const REPORT_REL = 'agents/evidence/analysis/setup-layer-baseline.md';
+
+export interface RuleFile {
+    readonly name: string;
+    readonly bytes: number;
+    readonly form: 'full' | 'stub';
+}
+
+export interface LayerFixture {
+    readonly host: string;
+    readonly scope: 'installed' | 'projected';
+    readonly dir: string;
+    readonly present: boolean;
+    readonly files: readonly RuleFile[];
+    readonly bytes: number;
+    readonly full: number;
+    readonly stub: number;
+    readonly digest: string;
+}
+
+export interface HostFixture {
+    readonly host: string;
+    readonly installed: LayerFixture;
+    readonly hookCommands: readonly string[];
+    readonly form: LayerFormDecision;
+}
+
+export interface Baseline {
+    readonly commit: string;
+    readonly packageVersion: string;
+    readonly hosts: readonly HostFixture[];
+    readonly projected: readonly LayerFixture[];
+}
+
+export function readRuleLayer(host: string, scope: LayerFixture['scope'], dir: string, label: string): LayerFixture {
+    const present = fs.existsSync(dir);
+    const names = present ? fs.readdirSync(dir).filter((f) => /\.(md|mdc)$/.test(f)).sort() : [];
+    const files: RuleFile[] = names.map((name) => {
+        const body = fs.readFileSync(path.join(dir, name));
+        return { name, bytes: body.length, form: is_thin_entry(body.toString('utf-8')) ? 'stub' : 'full' };
+    });
+    const digest = createHash('sha256')
+        .update(files.map((f) => `${f.name}\t${f.bytes}\t${f.form}`).join('\n'))
+        .digest('hex')
+        .slice(0, 16);
+    return {
+        host,
+        scope,
+        dir: label,
+        present,
+        files,
+        bytes: files.reduce((n, f) => n + f.bytes, 0),
+        full: files.filter((f) => f.form === 'full').length,
+        stub: files.filter((f) => f.form === 'stub').length,
+        digest,
+    };
+}
+
+export function readHookCommands(home: string, packageRoot?: string): string[] {
+    const settings = path.join(home, '.claude', 'settings.json');
+    if (!fs.existsSync(settings)) return [];
+    const parsed = JSON.parse(fs.readFileSync(settings, 'utf-8')) as {
+        hooks?: Record<string, { matcher?: string; hooks?: { command?: string }[] }[]>;
+    };
+    const out: string[] = [];
+    for (const event of Object.keys(parsed.hooks ?? {})) {
+        for (const group of parsed.hooks?.[event] ?? []) {
+            for (const h of group.hooks ?? []) {
+                if (typeof h.command !== 'string') continue;
+                let command = h.command.split(home).join('<HOME>');
+                if (packageRoot !== undefined) command = command.split(packageRoot).join('<PACKAGE_ROOT>');
+                out.push(`${event}${group.matcher ? ` [${group.matcher}]` : ''}: ${command}`);
+            }
+        }
+    }
+    return out;
+}
+
+function scratchEnv(home: string): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = { ...process.env };
+    delete env['AGENT_CONFIG_DEPLOY_INVENTORY'];
+    delete env['AGENT_CONFIG_INSTALLED_TOOLS'];
+    env['HOME'] = home;
+    env['EVENT4U_CONFIG_HOME'] = path.join(home, '.event4u', 'agent-config');
+    env['AGENT_CONFIG_NO_UI'] = '1';
+    env['CI'] = '1';
+    return env;
+}
+
+function readPackageVersion(packageRoot: string): string {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')) as { version?: unknown };
+        return typeof raw.version === 'string' && raw.version.trim() ? raw.version.trim() : 'unknown';
+    } catch {
+        return 'unknown';
+    }
+}
+
+function readCommit(packageRoot: string): string {
+    const r = spawnSync('git', ['-C', packageRoot, 'rev-parse', '--short=9', 'HEAD'], { encoding: 'utf-8' });
+    return r.status === 0 ? r.stdout.trim() : 'unknown';
+}
+
+export function measureHost(host: string, packageRoot: string, version: string): HostFixture {
+    const scratch = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'layer-baseline-')));
+    try {
+        const home = path.join(scratch, 'home');
+        const cwd = path.join(scratch, 'cwd');
+        fs.mkdirSync(home);
+        fs.mkdirSync(cwd);
+        const env = scratchEnv(home);
+        const r = spawnSync('bash', [path.join(packageRoot, 'src', 'scripts', 'install'), '--global', `--tools=${host}`, '--yes', '--quiet'], {
+            cwd,
+            env,
+            encoding: 'utf-8',
+            timeout: 240_000,
+        });
+        if (r.status !== 0) throw new Error(`install --tools=${host} exited ${String(r.status)}:\n${r.stdout}\n${r.stderr}`);
+        const rel = GLOBAL_RULE_DIRS[host] as string;
+        const installed = readRuleLayer(host, 'installed', path.join(home, rel), `<HOME>/${rel}`);
+        const machine = readMachineEvidence(packageRoot, { HOME: home, EVENT4U_CONFIG_HOME: env['EVENT4U_CONFIG_HOME'] });
+        const form = decideLayerForm(withMachineEvidence(gatherShippedEvidence(packageRoot, version)(host), machine));
+        return { host, installed, hookCommands: readHookCommands(home, packageRoot), form };
+    } finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+
+export function buildBaseline(packageRoot: string, hosts: readonly string[]): Baseline {
+    const version = readPackageVersion(packageRoot);
+    const projected = Object.keys(PROJECT_RULE_DIRS)
+        .sort()
+        .map((rel) => readRuleLayer(PROJECT_RULE_DIRS[rel] as string, 'projected', path.join(packageRoot, rel), rel));
+    return {
+        commit: readCommit(packageRoot),
+        packageVersion: version,
+        hosts: hosts.map((h) => measureHost(h, packageRoot, version)),
+        projected,
+    };
+}
+
+function layerRow(l: LayerFixture, form: string): string {
+    return `| ${l.host} | ${l.scope} | \`${l.dir}\` | ${l.present ? l.files.length : 'absent'} | ${l.bytes} | ${l.full} | ${l.stub} | \`${l.digest}\` | ${form} |`;
+}
+
+export function renderBaseline(b: Baseline): string {
+    const lines = [
+        '<!-- evidence-type: analysis -->',
+        '# Setup layer baseline',
+        '',
+        `Measured at commit \`${b.commit}\`, package version \`${b.packageVersion}\`, by`,
+        '`./scripts-run src/scripts/layer_baseline_report`. Every row below names that commit.',
+        '',
+        'Excluded so that two runs at one commit are byte-equal: the install receipt, lock and',
+        'log (each carries an install time), the scratch root (recorded as `<HOME>`), the',
+        'measured checkout (recorded as `<PACKAGE_ROOT>`), and the host\'s own version (a',
+        'property of the machine, not of the commit).',
+        '',
+        '| host | scope | dir | files | bytes | full | stub | file-set digest | resolved form |',
+        '|---|---|---|---|---|---|---|---|---|',
+    ];
+    for (const h of b.hosts) lines.push(layerRow(h.installed, `${h.form.form} (${h.form.reason})`));
+    for (const p of b.projected) lines.push(layerRow(p, 'project tree, not decided per machine'));
+    lines.push('', '## Hook commands written', '');
+    for (const h of b.hosts) {
+        lines.push(`### ${h.host} — ${h.hookCommands.length} command(s)`, '');
+        if (h.hookCommands.length === 0) lines.push('None written.', '');
+        else lines.push('~~~text', ...h.hookCommands, '~~~', '');
+    }
+    lines.push('## File sets', '');
+    const seen = new Set<string>();
+    for (const l of [...b.hosts.map((h) => h.installed), ...b.projected]) {
+        if (!l.present || seen.has(l.digest)) continue;
+        seen.add(l.digest);
+        lines.push(`### \`${l.digest}\``, '', '~~~text', ...l.files.map((f) => `${f.name}\t${f.bytes}\t${f.form}`), '~~~', '');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+
+interface Args {
+    readonly write: boolean;
+    readonly packageRoot: string;
+    readonly hosts: readonly string[];
+}
+
+export function parseArgs(argv: readonly string[]): Args | null {
+    let write = false;
+    let packageRoot = REPO_ROOT;
+    let hosts: string[] = Object.keys(GLOBAL_RULE_DIRS).sort();
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--write') write = true;
+        else if (a === '--package-root' && argv[i + 1] !== undefined) packageRoot = path.resolve(argv[++i] as string);
+        else if (a === '--hosts' && argv[i + 1] !== undefined) {
+            hosts = (argv[++i] as string).split(',').filter(Boolean);
+            if (hosts.some((h) => !(h in GLOBAL_RULE_DIRS))) return null;
+        } else return null;
+    }
+    return { write, packageRoot, hosts };
+}
+
+export function main(argv: readonly string[]): number {
+    const args = parseArgs(argv);
+    if (args === null) {
+        process.stderr.write(
+            `usage: layer_baseline_report [--write] [--package-root <dir>] [--hosts ${Object.keys(GLOBAL_RULE_DIRS).sort().join(',')}]\n`,
+        );
+        return 2;
+    }
+    let report: string;
+    try {
+        report = renderBaseline(buildBaseline(args.packageRoot, args.hosts));
+    } catch (e) {
+        process.stderr.write(`layer_baseline_report: ${(e as Error).message}\n`);
+        return 1;
+    }
+    if (args.write) {
+        fs.writeFileSync(path.join(REPO_ROOT, REPORT_REL), report);
+        process.stdout.write(`wrote ${REPORT_REL}\n`);
+    } else process.stdout.write(report);
+    return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/learning_sidecar.ts

@@ -43,7 +43,7 @@ const PROG = 'learning_sidecar.ts';
 
 /** Half-life of a signal's weight, in days. */
 export const HALF_LIFE_DAYS = 30;
-/** Distinct origins required before a lesson is promoted. */
+/** Distinct origins required before a lesson is promoted — the local row of the evidence threshold in docs/contracts/retro-v1.md. */
 export const MIN_CORROBORATIONS = 2;
 // cache-invalidation: regenerated wholesale from the intake JSONL on every run
 // (no incremental/partial state); the in-file `schema_version` field is the

package/src/scripts/lint_agents_layout.ts

@@ -35,6 +35,9 @@ const AGENTS_ROOT = 'agents';
 const ALLOWED_FLAT_FILES: ReadonlySet<string> = new Set([
     'index.md',
     'roadmaps-progress.md',
+    // Generated owned-roadmap digest; beside the dashboard because inside
+    // `roadmaps/` every active-roadmap glob would read it as a roadmap.
+    'roadmaps-owned.md',
     '.gitkeep',
     '.event4u-bridge.yml',
     '.agent-tools.yml',

package/src/scripts/lint_blocker_citations.ts

@@ -21,13 +21,20 @@
  * `lint_blocker_citations`): line numbers drift, so a miss already in the tree
  * is drift rather than a new defect, and the count may only fall.
  *
+ * Usage:
+ *   ./scripts-run src/scripts/lint_blocker_citations
+ *   ./scripts-run src/scripts/lint_blocker_citations --root <repo>
+ *   ./scripts-run src/scripts/lint_blocker_citations --self-test
+ *
  * Exit codes: 0 within the ratchet · 1 above it · 2 usage error.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { checkRatchet } from './_lib/gate_baseline.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { reportScanned } from './_lib/scan_scope.js';
 
 type MissKind = 'missing-file' | 'beyond-end';
@@ -133,11 +140,108 @@ function scanTree(root: string): { misses: Miss[]; scanned: number; citations: n
 
 const _DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
+/**
+ * Five fixtures over a temporary tree, driven through the real CLI.
+ *
+ * Each fixture carries its own baselines file pinned at 0, so the ratchet is
+ * out of the way and a single planted miss has to redden. That is the one thing
+ * the repository's own run cannot show: on the real tree this gate sits two
+ * below its baseline, so a planted citation reads green there — which is why
+ * this gate's `gate-coverage.yml` row carries `no_canary_reason` and leans on
+ * exactly these cases instead.
+ */
+function selfTest(): number {
+    const repoRoot = _DEFAULT_ROOT;
+    const rel = 'src/scripts/lint_blocker_citations.ts';
+    const BASELINE = JSON.stringify({
+        gates: {
+            lint_blocker_citations: {
+                count: 0,
+                landed: '2026-10-13',
+                falsifier: 'self-test fixture — pinned at zero so one planted miss must redden',
+                note: 'Self-test fixture baseline. Not a tree reading.',
+            },
+        },
+    });
+
+    const over = (blockers: string, extra?: { file: string; body: string }): (() => number) => (): number => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'blocker-cites-self-'));
+        try {
+            const roadmaps = path.join(dir, 'agents', 'roadmaps');
+            fs.mkdirSync(roadmaps, { recursive: true });
+            fs.mkdirSync(path.join(dir, 'src', 'config'), { recursive: true });
+            fs.writeFileSync(path.join(dir, 'src', 'config', 'gate-violation-baselines.json'), BASELINE);
+            if (extra !== undefined) {
+                const abs = path.join(dir, extra.file);
+                fs.mkdirSync(path.dirname(abs), { recursive: true });
+                fs.writeFileSync(abs, extra.body);
+            }
+            fs.writeFileSync(path.join(roadmaps, 'road-to-fixture.md'), blockers);
+            return runGateCli(repoRoot, rel, ['--root', dir], repoRoot);
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    };
+
+    const THREE_LINES = 'one\ntwo\nthree\n';
+
+    return runSelfTest({
+        gate: 'lint_blocker_citations',
+        minCases: 5,
+        minRejectCases: 2,
+        cases: [
+            {
+                name: 'a citation whose file does not exist is rejected',
+                expect: 'reject',
+                run: over('## Blockers\n\nResolved when `src/scripts/nope.ts:12` says so.\n'),
+            },
+            {
+                name: 'a citation past the end of an existing file is rejected',
+                expect: 'reject',
+                run: over('## Blockers\n\nResolved when `src/scripts/real.ts:99` says so.\n', {
+                    file: 'src/scripts/real.ts',
+                    body: THREE_LINES,
+                }),
+            },
+            {
+                name: 'a citation inside an existing file is accepted',
+                expect: 'accept',
+                run: over('## Blockers\n\nResolved when `src/scripts/real.ts:2` says so.\n', {
+                    file: 'src/scripts/real.ts',
+                    body: THREE_LINES,
+                }),
+            },
+            {
+                name: 'a bare `:12` with no path is not a citation and is accepted',
+                expect: 'accept',
+                run: over('## Blockers\n\nResolved when the block at :12 says so.\n'),
+            },
+            {
+                name: 'the same dead citation OUTSIDE the Blockers section is accepted',
+                expect: 'accept',
+                run: over('## Context\n\nSee `src/scripts/nope.ts:12`.\n\n## Goal\n\nNothing.\n'),
+            },
+            {
+                name: 'a roadmap tree with no Blockers section at all is accepted',
+                expect: 'accept',
+                run: over('# Road to nothing\n\nNo blockers here.\n'),
+            },
+        ],
+    });
+}
+
 function main(argv: string[] = process.argv.slice(2)): number {
     let root = _DEFAULT_ROOT;
     let baselineRoot = _DEFAULT_ROOT;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
+        if (arg === '--self-test') {
+            if (process.env['GATE_SELF_TEST_CHILD'] === '1') {
+                process.stderr.write('lint_blocker_citations: --self-test does not recurse\n');
+                return 2;
+            }
+            return selfTest();
+        }
         if (arg === '--root') {
             const v = argv[i + 1];
             if (v === undefined) {

package/src/scripts/lint_breaking_changes_index.ts

@@ -14,7 +14,9 @@
  * breaking note under `## [Unreleased]` is WIP and never trips the gate.
  *
  * REQUIREMENT: when triggered, the same diff must also modify
- * `BREAKING_CHANGES.md`.
+ * `BREAKING_CHANGES.md`, unless the index already carries a by-major row
+ * (`| **N.0.0** |`) for that major — the row the Pending workflow lands on main
+ * before the cut, which the release diff then never touches.
  *
  * Escape hatch (mirrors `check_structural_breaking.ts`'s `ci-override` trailer):
  * an own-line trailer `ci-override: breaking-index-override` (the bare token
@@ -95,23 +97,45 @@ export function added_released_breaking_majors(
     return added;
 }
 
+// A by-major row opens with the version in bold: `| **17.0.0** | 2026-10-21 | …`.
+const INDEX_ROW_RE = /^\|\s*\*\*(?<version>\d+\.\d+\.\d+)\*\*\s*\|/;
+
+/** The majors `BREAKING_CHANGES.md` already carries a by-major row for. */
+export function indexed_majors(indexLines: readonly string[]): Set<string> {
+    const found = new Set<string>();
+    for (const ln of indexLines) {
+        const m = INDEX_ROW_RE.exec(ln);
+        if (m) found.add(m.groups!['version']!);
+    }
+    return found;
+}
+
 export interface CheckResult {
     readonly addedMajors: readonly string[];
+    /** Added majors with no by-major row in the index. */
+    readonly unindexedMajors: readonly string[];
     readonly indexChanged: boolean;
     readonly overridden: boolean;
     readonly violation: boolean;
 }
 
-/** Pure decision: violation iff a released BREAKING was added, the index was not touched, and no override cleared it. */
+/**
+ * Pure decision: violation iff a released BREAKING was added for a major the
+ * index carries no row for, the index was not touched, and no override cleared
+ * it. A row landed before the cut satisfies the index: the Pending workflow
+ * writes it on main, so the release diff itself never touches the file.
+ */
 export function evaluate(
     oldLines: readonly string[],
     newLines: readonly string[],
     indexChanged: boolean,
     overridden: boolean,
+    indexed: ReadonlySet<string> = new Set(),
 ): CheckResult {
     const addedMajors = added_released_breaking_majors(oldLines, newLines);
-    const violation = addedMajors.length > 0 && !indexChanged && !overridden;
-    return { addedMajors, indexChanged, overridden, violation };
+    const unindexedMajors = addedMajors.filter((v) => !indexed.has(v));
+    const violation = unindexedMajors.length > 0 && !indexChanged && !overridden;
+    return { addedMajors, unindexedMajors, indexChanged, overridden, violation };
 }
 
 // ─── git helpers (CLI only) ──────────────────────────────────────────────────
@@ -267,12 +291,21 @@ function main(argv?: readonly string[]): number {
     const log = _git('log', '--format=%B', `${base}..HEAD`);
     const overridden = OVERRIDE_RE.test(log) || process.env['BREAKING_INDEX_OVERRIDE'] === '1';
 
-    const result = evaluate(oldLines, newLines, indexChanged, overridden);
+    const indexPath = path.join(REPO_ROOT, INDEX_REL);
+    const indexed = fs.existsSync(indexPath)
+        ? indexed_majors(_splitlines(fs.readFileSync(indexPath, 'utf-8')))
+        : new Set<string>();
+
+    const result = evaluate(oldLines, newLines, indexChanged, overridden, indexed);
 
     if (!result.violation) {
         if (!args.quiet) {
             if (result.addedMajors.length > 0) {
-                const why = result.overridden ? 'override' : `${INDEX_REL} updated`;
+                const why = result.indexChanged
+                    ? `${INDEX_REL} updated`
+                    : result.unindexedMajors.length === 0
+                      ? `an existing ${INDEX_REL} row`
+                      : 'override';
                 process.stdout.write(
                     `✅ lint-breaking-changes-index: ${result.addedMajors.length} released ` +
                         `BREAKING addition(s), cleared by ${why}\n`,
@@ -290,7 +323,7 @@ function main(argv?: readonly string[]): number {
         `❌ lint-breaking-changes-index: released BREAKING entr(y/ies) added to ${CHANGELOG_REL} ` +
             `without a matching ${INDEX_REL} change:\n`,
     );
-    for (const v of result.addedMajors) {
+    for (const v of result.unindexedMajors) {
         process.stderr.write(`   - ## [${v}] gained a ### BREAKING section\n`);
     }
     process.stderr.write(