@event4u/agent-config 8.8.0 → 8.10.0

package/src/scripts/check_release_adjacent_health.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env tsx
+/**
+ * Release-adjacent workflow health tripwire — road-to-proof-under-real-conditions
+ * Phase 1. The "red for five releases without anyone noticing" detector:
+ * the MCP worker deploy failed on every release from one minor line to the
+ * next and nothing surfaced it, because post-tag workflows are nobody's PR.
+ *
+ * For each watched workflow, look at its most recent COMPLETED run on the
+ * default branch (any trigger). If that run's conclusion is not `success`
+ * and it finished more than --max-red-hours ago (default 48) with no newer
+ * successful run, the workflow counts as durably red → exit 1 and print a
+ * GitHub error annotation per offender. The calling workflow turns that
+ * into a visible failure on main.
+ *
+ * Auth: GITHUB_TOKEN (or GH_TOKEN) env. Repo: GITHUB_REPOSITORY env or
+ * --repo owner/name.
+ *
+ * Exit codes: 0 all green/absent · 1 durably-red workflow(s) · 2 usage/env.
+ */
+
+import { argv, env, exit } from 'node:process';
+
+const WATCHED = [
+    'publish-npm.yml',
+    'deploy-mcp-worker.yml',
+    'deploy-site.yml',
+    'site.yml',
+    'consumer-matrix.yml',
+    'release.yml',
+] as const;
+
+interface RunInfo {
+    conclusion: string | null;
+    updated_at: string;
+    html_url: string;
+}
+
+async function latestCompletedRun(
+    repo: string,
+    token: string,
+    workflow: string,
+    branch: string,
+): Promise<RunInfo | null> {
+    const url =
+        `https://api.github.com/repos/${repo}/actions/workflows/${workflow}/runs` +
+        `?status=completed&per_page=1${branch ? `&branch=${branch}` : ''}`;
+    const res = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        },
+    });
+    if (res.status === 404) return null; // workflow not present (yet)
+    if (!res.ok) throw new Error(`GitHub API ${res.status} for ${workflow}: ${await res.text()}`);
+    const body = (await res.json()) as { workflow_runs?: RunInfo[] };
+    return body.workflow_runs?.[0] ?? null;
+}
+
+async function main(): Promise<number> {
+    const args = argv.slice(2);
+    const getOpt = (flag: string): string | undefined => {
+        const i = args.indexOf(flag);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const token = env.GITHUB_TOKEN ?? env.GH_TOKEN ?? '';
+    const repo = getOpt('--repo') ?? env.GITHUB_REPOSITORY ?? '';
+    const maxRedHours = Number(getOpt('--max-red-hours') ?? '48');
+    if (!token || !repo) {
+        process.stderr.write('❌  release-adjacent-health: GITHUB_TOKEN and GITHUB_REPOSITORY (or --repo) required.\n');
+        return 2;
+    }
+
+    // Tag/release-triggered workflows have no branch association — query
+    // without the branch filter for those; branch-scoped for PR/push ones.
+    const branchless = new Set(['publish-npm.yml', 'deploy-mcp-worker.yml', 'release.yml']);
+    let red = 0;
+    for (const wf of WATCHED) {
+        let run: RunInfo | null;
+        try {
+            run = await latestCompletedRun(repo, token, wf, branchless.has(wf) ? '' : 'main');
+        } catch (err) {
+            process.stderr.write(`⚠️  ${wf}: ${(err as Error).message}\n`);
+            continue; // transient API failure must not fake a red
+        }
+        if (!run) {
+            process.stderr.write(`·   ${wf}: no completed runs (or workflow absent) — skipping\n`);
+            continue;
+        }
+        if (run.conclusion === 'success') {
+            process.stderr.write(`✅  ${wf}: last completed run green\n`);
+            continue;
+        }
+        const ageHours = (Date.now() - Date.parse(run.updated_at)) / 3_600_000;
+        if (ageHours >= maxRedHours) {
+            process.stdout.write(
+                `::error::release-adjacent workflow durably red: ${wf} — last completed run ` +
+                    `'${run.conclusion}' ${ageHours.toFixed(0)}h ago with no newer success. ${run.html_url}\n`,
+            );
+            red += 1;
+        } else {
+            process.stderr.write(
+                `⚠️  ${wf}: last run '${run.conclusion}' ${ageHours.toFixed(0)}h ago (< ${maxRedHours}h window)\n`,
+            );
+        }
+    }
+    if (red > 0) {
+        process.stderr.write(`❌  ${red} release-adjacent workflow(s) durably red.\n`);
+        return 1;
+    }
+    process.stderr.write('✅  release-adjacent workflows healthy.\n');
+    return 0;
+}
+
+main().then(
+    (code) => exit(code),
+    (err) => {
+        process.stderr.write(`❌  release-adjacent-health crashed: ${(err as Error).stack ?? err}\n`);
+        exit(2);
+    },
+);

package/src/scripts/check_roadmap_trackable.ts

@@ -37,10 +37,11 @@ const ROADMAP_ROOT = 'agents/roadmaps';
 // CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
 const CHECKBOX_RE = /^[ \t]*[-*][ \t]+\[([ xX~\-])\][ \t\f\v]/m;
 // PHASE_RE = re.compile(
-//   r"^(#{2,3})\s+Phase\s+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)"
+//   r"^(#{2,3})\s+Phase\s+(\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)"
 //   r"(?:[\s:—\-]+(.*?))?\s*$", re.MULTILINE)
+// Numeric ids accept dotted sub-phases ("1.0", "4.1") — mirrors the dashboard's PHASE_RE.
 const PHASE_RE =
-    /^(#{2,3})[ \t\f\v]+Phase[ \t\f\v]+(\d+[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+(.*?))?[ \t\f\v]*$/gm;
+    /^(#{2,3})[ \t\f\v]+Phase[ \t\f\v]+(\d+(?:\.\d+)*[a-z]?|[IVX]+|[A-Z](?:\d+)?)(?:[\s:—\-]+(.*?))?[ \t\f\v]*$/gm;
 // FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\s*\n/;
 const DRAFT_VALUES: ReadonlySet<string> = new Set(['draft']);

package/src/scripts/check_rule_invariants.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env tsx
+/**
+ * Kernel semantic-invariants checker.
+ *
+ * Counterfactual (2026-07-10): PRs #840/#844 showed MERGED on GitHub but their
+ * content vanished from main (merge commits unreachable after a history repair);
+ * re-landed as #847 (13f244c9b — non-destructive "Irreversible external action"
+ * row + "Never act while asking" clause) and #849 (2c46e7f3b — direct-answers
+ * "no duration estimates" + "never cite the rule"). This checker's invariant set
+ * covers those exact strings — it would have flagged the loss at CI time.
+ *
+ * Loads `tests/golden/invariants.json` and verifies that every invariant
+ * string (whitespace-normalised: runs of whitespace collapse to a single
+ * space) is present in BOTH the kernel rule's `src/rules/` source and its
+ * `dist/agent-src/rules/` projection. A missing string means a rule's
+ * behaviour guarantee was silently lost in a merge / condensation pass.
+ *
+ * Kernel set: docs/contracts/kernel-membership.md § 4 (9 locked rules).
+ *
+ * Usage:
+ *   npx tsx src/scripts/check_rule_invariants.ts [--root ROOT]
+ *   npx tsx src/scripts/check_rule_invariants.ts --mutation-selftest
+ *
+ * `--mutation-selftest` picks the first invariant and verifies the check
+ * WOULD fail if that string were absent (in-memory mutation) — guards the
+ * checker itself against a silently-green normalisation bug.
+ *
+ * Exit codes: 0 = clean / selftest passed, 1 = missing invariant(s) or
+ * selftest failure, 2 = usage error, 3 = internal error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// src/scripts/check_rule_invariants.ts → two dirs up is the repo root.
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const INVARIANTS_JSON = 'tests/golden/invariants.json';
+
+interface InvariantEntry {
+    rule: string;
+    file: string;
+    dist: string;
+    strings: string[];
+}
+
+interface Miss {
+    rule: string;
+    file: string;
+    invariant: string;
+}
+
+/** Collapse every run of whitespace (incl. newlines) to a single space. */
+function normalize(text: string): string {
+    return text.replace(/\s+/g, ' ').trim();
+}
+
+function loadEntries(root: string): InvariantEntry[] {
+    const p = path.join(root, INVARIANTS_JSON);
+    const raw = fs.readFileSync(p, 'utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${INVARIANTS_JSON}: expected a top-level array`);
+    }
+    for (const entry of parsed as InvariantEntry[]) {
+        if (
+            typeof entry.rule !== 'string' ||
+            typeof entry.file !== 'string' ||
+            typeof entry.dist !== 'string' ||
+            !Array.isArray(entry.strings) ||
+            entry.strings.some((s) => typeof s !== 'string' || s.length === 0)
+        ) {
+            throw new Error(
+                `${INVARIANTS_JSON}: malformed entry ${JSON.stringify(entry.rule ?? entry)}`,
+            );
+        }
+    }
+    return parsed as InvariantEntry[];
+}
+
+/** Check one entry against pre-normalised file contents. */
+function checkEntry(
+    entry: InvariantEntry,
+    normalizedByFile: ReadonlyMap<string, string>,
+): Miss[] {
+    const misses: Miss[] = [];
+    for (const target of [entry.file, entry.dist]) {
+        const haystack = normalizedByFile.get(target);
+        if (haystack === undefined) {
+            for (const s of entry.strings) {
+                misses.push({ rule: entry.rule, file: target, invariant: s });
+            }
+            continue;
+        }
+        for (const s of entry.strings) {
+            if (!haystack.includes(normalize(s))) {
+                misses.push({ rule: entry.rule, file: target, invariant: s });
+            }
+        }
+    }
+    return misses;
+}
+
+function readNormalized(root: string, entries: readonly InvariantEntry[]): Map<string, string> {
+    const out = new Map<string, string>();
+    for (const entry of entries) {
+        for (const target of [entry.file, entry.dist]) {
+            if (out.has(target)) {
+                continue;
+            }
+            const p = path.join(root, target);
+            try {
+                out.set(target, normalize(fs.readFileSync(p, 'utf-8')));
+            } catch {
+                // Leave absent — checkEntry reports every string as missing.
+            }
+        }
+    }
+    return out;
+}
+
+function scan(root: string): Miss[] {
+    const entries = loadEntries(root);
+    const normalizedByFile = readNormalized(root, entries);
+    const misses: Miss[] = [];
+    for (const entry of entries) {
+        misses.push(...checkEntry(entry, normalizedByFile));
+    }
+    return misses;
+}
+
+function formatText(misses: Miss[], invariantCount: number): string {
+    if (misses.length === 0) {
+        return `✅  All ${invariantCount} kernel rule invariants present in src + dist.`;
+    }
+    const lines: string[] = [
+        `❌  ${misses.length} missing kernel rule invariant(s):\n`,
+    ];
+    for (const m of misses) {
+        lines.push(`  🔴 ${m.rule} — ${m.file}\n     missing: "${m.invariant}"`);
+    }
+    lines.push(
+        '\nA kernel rule lost a load-bearing clause — likely a merge or condensation ' +
+            'dropped it silently (see the #840/#844 incident in this file header). ' +
+            'Restore the clause or deliberately update tests/golden/invariants.json.',
+    );
+    return lines.join('\n');
+}
+
+/**
+ * Mutation self-test: remove the first invariant string from its src file's
+ * content in-memory and verify the check catches the absence.
+ */
+function mutationSelftest(root: string): number {
+    const entries = loadEntries(root);
+    const first = entries[0];
+    if (first === undefined || first.strings[0] === undefined) {
+        process.stderr.write('mutation-selftest: no invariants defined\n');
+        return 1;
+    }
+    const invariant = first.strings[0];
+    const p = path.join(root, first.file);
+    const original = normalize(fs.readFileSync(p, 'utf-8'));
+    const needle = normalize(invariant);
+    if (!original.includes(needle)) {
+        process.stderr.write(
+            `mutation-selftest: baseline broken — "${invariant}" not present in ${first.file}\n`,
+        );
+        return 1;
+    }
+    const mutated = original.split(needle).join('');
+    if (mutated.includes(needle)) {
+        process.stderr.write('mutation-selftest: mutation did not remove the string\n');
+        return 1;
+    }
+    // Run the REAL check path against the mutated content: swap the src
+    // file's normalised content in-memory and assert checkEntry reports
+    // the removed invariant as missing.
+    const normalizedByFile = readNormalized(root, [first]);
+    normalizedByFile.set(first.file, mutated);
+    const misses = checkEntry(first, normalizedByFile);
+    const detected = misses.some(
+        (m) => m.file === first.file && m.invariant === invariant,
+    );
+    if (!detected) {
+        process.stderr.write(
+            `mutation-selftest: FAILED — removing "${invariant}" from ${first.file} was NOT detected\n`,
+        );
+        return 1;
+    }
+    process.stdout.write(
+        `✅  mutation-selftest passed: removing "${invariant}" from ${first.file} is detected.\n`,
+    );
+    return 0;
+}
+
+interface ParsedArgs {
+    root: string;
+    mutationSelftest: boolean;
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    let root = ROOT;
+    let selftest = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!;
+        if (arg === '--root') {
+            const v = argv[++i];
+            if (v === undefined) {
+                _argparse_error('argument --root: expected one argument');
+            }
+            root = v;
+        } else if (arg.startsWith('--root=')) {
+            root = arg.slice('--root='.length);
+        } else if (arg === '--mutation-selftest') {
+            selftest = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: check_rule_invariants [-h] [--root ROOT] [--mutation-selftest]\n',
+            );
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return { root, mutationSelftest: selftest };
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`check_rule_invariants: error: ${message}\n`);
+    process.exit(2);
+}
+
+function main(): number {
+    const args = parse_args(process.argv.slice(2));
+    try {
+        if (args.mutationSelftest) {
+            return mutationSelftest(args.root);
+        }
+        const entries = loadEntries(args.root);
+        const invariantCount = entries.reduce((n, e) => n + e.strings.length, 0);
+        const misses = scan(args.root);
+        process.stdout.write(formatText(misses, invariantCount) + '\n');
+        return misses.length ? 1 : 0;
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`Internal error: ${msg}\n`);
+        return 3;
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { type InvariantEntry, type Miss, ROOT, INVARIANTS_JSON, normalize, scan, main };

package/src/scripts/condense.ts

@@ -40,6 +40,7 @@ import {
     strip_source_prefix,
 } from './_lib/agent_src.js';
 import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.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 { info, success, flush_summary, resolve_level } from './_lib/script_output.js';
 import {
@@ -1529,6 +1530,7 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     const current_slugs = new Set<string>();
     let count = 0;
     let skipped = 0;
+    let reserved = 0;
     let rendered = 0;
     const auto = _read_model_auto_switch() === 'auto';
     for (const [source_file, slug] of iterCommands()) {
@@ -1539,6 +1541,15 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
             skipped += 1;
             continue;
         }
+        // Never claim a `/name` that is a Claude Code built-in command or
+        // bundled skill — a same-name entry shadows the built-in (e.g. a
+        // `review` entry hides Claude Code's own /review). Nested
+        // `/cluster:sub` slugs are hyphen-joined and cannot collide.
+        // See src/scripts/_lib/claude_builtin_names.ts.
+        if (is_claude_builtin_name(slug)) {
+            reserved += 1;
+            continue;
+        }
         current_slugs.add(slug);
 
         const skill_dir = path.join(MODULE_STATE.CLAUDE_SKILLS_DIR, slug);
@@ -1588,6 +1599,9 @@ export function generate_claude_commands(active_command_slugs: ReadonlySet<strin
     if (skipped) {
         msg += ` (${skipped} skipped — same-name skill exists)`;
     }
+    if (reserved) {
+        msg += ` (${reserved} withheld — Claude Code built-in name)`;
+    }
     if (removed_dirs) {
         msg += ` (${removed_dirs} stale dirs removed)`;
     }