@event4u/agent-config 9.13.0 → 9.15.0

package/src/scripts/check_artefact_count_messaging.ts

@@ -33,7 +33,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { canonical_counts } from './check_command_count_messaging.js';
-import { count } from './update_counts.js';
+import { count, TARGETS } from './update_counts.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -164,6 +164,93 @@ export function scan_structured(
     return { findings, seen };
 }
 
+// --- Anchor-coverage pass (road-to-reproducible-artefact-counts) ----------
+//
+// The two gates used to overlap only by accident. This scanner flags any
+// count-shaped prose; `update_counts` rewrites a hand-written list of
+// anchors. Nothing asserted the second list covered the first, so positions
+// existed that the scanner could turn red and the generator could not fix —
+// the README Commands badge and the getting-started browse line drifted to
+// 191 against a canonical 192 exactly there, each explicitly left unanchored
+// to "avoid double-ownership". The reconciliation was a human's job, and the
+// gate's own advice said so ("run update_counts … OR correct the prose").
+//
+// This pass removes the human: every position this scanner can flag must be
+// rewritable by the generator, or be a generated file whose source is. A new
+// count-shaped sentence with no anchor now fails CI as a coverage gap.
+
+/**
+ * Scanner kind → the generator kinds that legitimately write it.
+ *
+ * One prose kind can have several canonical numbers and they are NOT
+ * interchangeable: "N commands" in prose means ACTIVE commands (total minus
+ * deprecation shims), and a scoped-projection sentence carries the projected
+ * skill count beside the catalog total. Anchoring an active-count position
+ * to the raw `commands` total would silently write the wrong number the day
+ * a command is superseded — which is why this is a mapping and not equality.
+ */
+const ANCHOR_KINDS: Readonly<Record<string, readonly string[]>> = {
+    skills: ['skills', 'skills_scoped'],
+    commands: ['commands', 'commands_active'],
+    rules: ['rules'],
+    guidelines: ['guidelines'],
+    personas: ['personas'],
+};
+
+/**
+ * Surfaces regenerated from an anchored source — exempt because fixing the
+ * source fixes them. Each entry names the generator, so the exemption stays
+ * falsifiable rather than becoming a place to hide drift.
+ */
+export const GENERATED_DOWNSTREAM: Readonly<Record<string, string>> = {
+    'docs/proof.md': 'generated from docs/CLAIMS.md by src/scripts/build_proof.ts',
+};
+
+export interface CoverageGap {
+    file: string;
+    line: number;
+    kind: string;
+    text: string;
+}
+
+/**
+ * Positions this scanner can flag that `update_counts` cannot rewrite.
+ *
+ * A position counts as anchored when some `TARGETS` pattern for the same
+ * file, bound to a compatible kind, matches the same line.
+ */
+export function anchor_coverage_gaps(root: string = ROOT): CoverageGap[] {
+    const anchorsByFile = new Map<string, ReadonlyArray<[string, string]>>();
+    for (const [rel, patterns] of TARGETS) {
+        anchorsByFile.set(rel, patterns);
+    }
+
+    const gaps: CoverageGap[] = [];
+    for (const rel of SURFACES) {
+        if (rel in GENERATED_DOWNSTREAM) continue;
+        const p = path.join(root, rel);
+        if (!fs.existsSync(p)) continue;
+        const lines = fs.readFileSync(p, 'utf-8').split('\n');
+        const anchors = anchorsByFile.get(rel) ?? [];
+        for (const [kind, pattern] of KIND_PATTERNS) {
+            const allowed = ANCHOR_KINDS[kind] ?? [kind];
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i]!;
+                const re = new RegExp(pattern.source, pattern.flags);
+                if (!re.test(line)) continue;
+                const anchored = anchors.some(
+                    ([raw, anchorKind]) =>
+                        allowed.includes(anchorKind) && new RegExp(raw).test(line),
+                );
+                if (!anchored) {
+                    gaps.push({ file: rel, line: i + 1, kind, text: line.trim().slice(0, 100) });
+                }
+            }
+        }
+    }
+    return gaps;
+}
+
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const QUIET = argv.includes('--quiet');
     const expected: Record<string, number> = {};
@@ -213,29 +300,55 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         }
     }
 
-    if (allFindings.length === 0 && inconsistent.length === 0) {
+    // Anchor coverage — every position this gate can flag must be a position
+    // `update_counts` can rewrite, so the two never need a human to reconcile.
+    const gaps = anchor_coverage_gaps();
+
+    if (allFindings.length === 0 && inconsistent.length === 0 && gaps.length === 0) {
         if (!QUIET) {
-            process.stdout.write('✅  All artefact-count prose in sync with source.\n');
+            process.stdout.write(
+                '✅  All artefact-count prose in sync with source, every position anchored.\n',
+            );
         }
         return 0;
     }
 
-    process.stdout.write(
-        `❌  Artefact-count messaging drift — ${allFindings.length} mismatch(es):\n`,
-    );
-    for (const f of allFindings) {
-        const tag = f.approx ? ' (approximation "~" not allowed on flagship surfaces)' : '';
+    if (allFindings.length > 0 || inconsistent.length > 0) {
+        process.stdout.write(
+            `❌  Artefact-count messaging drift — ${allFindings.length} mismatch(es):\n`,
+        );
+        for (const f of allFindings) {
+            const tag = f.approx ? ' (approximation "~" not allowed on flagship surfaces)' : '';
+            process.stdout.write(
+                `    ${f.file}:${f.line}: ${f.kind} says ${f.found}, expected ${f.expected}${tag}\n`,
+            );
+        }
+        for (const line of inconsistent) {
+            process.stdout.write(`    internal inconsistency — ${line}\n`);
+        }
         process.stdout.write(
-            `    ${f.file}:${f.line}: ${f.kind} says ${f.found}, expected ${f.expected}${tag}\n`,
+            '\nFix: run `./scripts-run src/scripts/update_counts` — every checked position\n' +
+                'is anchored, so the generator can write it. Never hand-type a count.\n',
         );
     }
-    for (const line of inconsistent) {
-        process.stdout.write(`    internal inconsistency — ${line}\n`);
+
+    if (gaps.length > 0) {
+        process.stdout.write(
+            `❌  Anchor-coverage gap — ${gaps.length} position(s) this gate checks but\n` +
+                '    `update_counts` cannot rewrite:\n',
+        );
+        for (const g of gaps) {
+            process.stdout.write(`    ${g.file}:${g.line}: ${g.kind} — ${g.text}\n`);
+        }
+        process.stdout.write(
+            '\nFix: add an anchor for each position to `TARGETS` in\n' +
+                '`src/scripts/update_counts.ts`, bound to the kind that position\n' +
+                'actually carries (`commands_active` for active-command mentions,\n' +
+                '`skills_scoped` for the projected-skill figure). If the file is\n' +
+                'generated from an anchored source, register it in\n' +
+                '`GENERATED_DOWNSTREAM` with the generator that produces it.\n',
+        );
     }
-    process.stdout.write(
-        '\nFix: run `./scripts-run src/scripts/update_counts` for anchored positions,\n' +
-            'or correct the prose to the canonical number (never hand-type a new one).\n',
-    );
     return 1;
 }
 

package/src/scripts/check_augment_description_cap.ts

@@ -91,11 +91,32 @@ function _globMdSorted(dir: string): string[] {
     return out;
 }
 
-export function main(): number {
+/**
+ * Injection seam for tests: `--root <dir>` overrides the scan root.
+ *
+ * Additive — no flag means the CI-identical bare call scans `RULES_DIR`, so the
+ * pinned CLI contract is unchanged. Without a seam the only way to exercise a
+ * real over-cap violation was to tamper with a committed rule, which is why this
+ * gate shipped with tests that never called `main()` at all.
+ */
+function _resolve_root(argv: readonly string[]): string {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--root') {
+            const v = argv[i + 1];
+            if (v !== undefined) return path.resolve(v);
+        } else if (a.startsWith('--root=')) {
+            return path.resolve(a.slice('--root='.length));
+        }
+    }
+    return RULES_DIR;
+}
+
+export function main(argv: readonly string[] = []): number {
     const failures: Array<[string, number, string]> = [];
     let checked = 0;
 
-    for (const p of _globMdSorted(RULES_DIR)) {
+    for (const p of _globMdSorted(_resolve_root(argv))) {
         const text = fs.readFileSync(p, 'utf-8');
         const fm = parse_frontmatter(text);
         if (fm['type'] !== 'auto') {
@@ -157,7 +178,7 @@ function _isCliEntry(): boolean {
 }
 
 if (_isCliEntry() || process.argv[1] === _HERE) {
-    process.exit(main());
+    process.exit(main(process.argv.slice(2)));
 }
 
 export { REPO_ROOT, RULES_DIR, DESC_CAP };

package/src/scripts/check_ci_strict_superset.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env tsx
+/**
+ * Assert `ci-strict` is a superset of `ci` BY CONSTRUCTION.
+ *
+ * WHY THIS EXISTS (road-to-renewal-foundation Phase 1, council 2026-08-02
+ * decision A1, 2/2):
+ *
+ * `Taskfile.yml` used to carry `ci` (202 gate entries) and `ci-strict` (197)
+ * as two independently maintained literal lists. They drifted, and nothing
+ * detected it — `check_ci_local_parity.ts` deliberately scopes itself to
+ * `LOCAL_ROOTS = ['ci', 'consistency']`, so `ci-strict` was outside every
+ * assertion in the repo. Six gates ran in `ci` with no counterpart in
+ * `ci-strict` at all:
+ *
+ *   preflight (fans out to 11 scripts, incl. check_no_new_legacy_path and
+ *   check_kernel_rule_bundle), check-ci-local-parity,
+ *   check-gitignore-freshness, check-generator-output-coverage,
+ *   check-tracked-but-ignored, check-generated-artefact-headers
+ *
+ * — so the "release-tag gate" was strictly WEAKER than the everyday gate on
+ * ~16 concrete script runs. A stricter tier that checks less is the worst
+ * possible shape for a release gate: it is trusted more and proves less.
+ *
+ * The fix was structural, not a bigger checker: `ci-strict` now delegates to
+ * `ci` and adds only strict-only entries on top, so the superset property is
+ * tautological. This gate guards the ONE invariant that keeps it tautological
+ * — the first gate entry of `ci-strict` is `- task: ci`.
+ *
+ * It deliberately does NOT re-parse and diff both lists. That would recreate
+ * the very "maintain a second model of the same thing" problem the delegation
+ * removed, and it would pass happily on a re-forked pair of lists that merely
+ * happened to match on the day it ran.
+ *
+ * Exit codes: 0 ok · 1 invariant violated · 2 usage / environment error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const TASKFILE = path.join(REPO_ROOT, 'Taskfile.yml');
+
+/** The delegation entry that makes the superset property tautological. */
+const DELEGATION = '- task: ci';
+
+/**
+ * Extract the `cmds:` entries of a top-level task, in order.
+ *
+ * Minimal line scan rather than a YAML dependency: the shape is fixed
+ * (`  <name>:` at two-space indent, `    cmds:` at four, `      - ...` at
+ * six) and the repo has no YAML anchors anywhere, so a parser buys nothing
+ * here and adds an import to a gate that must stay cheap.
+ */
+function taskCmds(source: string, taskName: string): string[] | null {
+    const lines = source.split('\n');
+    const header = `  ${taskName}:`;
+    let i = lines.findIndex((l) => l === header);
+    if (i === -1) {
+        return null;
+    }
+    const out: string[] = [];
+    let inCmds = false;
+    for (i += 1; i < lines.length; i++) {
+        const line = lines[i]!;
+        if (line.trim() === '') {
+            continue;
+        }
+        // Any line at two-space indent that is not deeper ends this task.
+        if (/^ {2}\S/.test(line)) {
+            break;
+        }
+        if (/^ {4}cmds:\s*$/.test(line)) {
+            inCmds = true;
+            continue;
+        }
+        if (!inCmds) {
+            continue;
+        }
+        const m = /^ {6}(- .*)$/.exec(line);
+        if (m) {
+            out.push(m[1]!.trim());
+        }
+    }
+    return out;
+}
+
+export function main(): number {
+    let source: string;
+    try {
+        source = fs.readFileSync(TASKFILE, 'utf-8');
+    } catch (err) {
+        process.stderr.write(`❌  check_ci_strict_superset: cannot read ${TASKFILE}: ${String(err)}\n`);
+        return 2;
+    }
+
+    const strict = taskCmds(source, 'ci-strict');
+    if (strict === null) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: no `ci-strict:` task found in Taskfile.yml.\n' +
+                '    The gate cannot verify an invariant on a task that does not exist.\n',
+        );
+        return 2;
+    }
+    if (taskCmds(source, 'ci') === null) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: no `ci:` task found in Taskfile.yml.\n',
+        );
+        return 2;
+    }
+
+    // Skip the internal timing wrappers; they carry no gate semantics and
+    // `ci-strict` intentionally does not repeat them (`ci` already brackets
+    // the run, so the duration line prints once).
+    const gateEntries = strict.filter(
+        (e) => !e.startsWith('- defer:') && e !== '- task: _ci-start' && e !== '- task: _ci-end',
+    );
+
+    if (gateEntries.length === 0) {
+        process.stderr.write('❌  check_ci_strict_superset: `ci-strict` has no gate entries.\n');
+        return 1;
+    }
+
+    if (gateEntries[0] !== DELEGATION) {
+        process.stderr.write(
+            '❌  check_ci_strict_superset: `ci-strict` no longer delegates to `ci`.\n' +
+                `    expected first gate entry: \`${DELEGATION}\`\n` +
+                `    found:                    \`${gateEntries[0]}\`\n\n` +
+                '    `ci-strict` must run every `ci` gate plus strict-only extras. It used\n' +
+                '    to be an independently maintained copy of the list and silently drifted\n' +
+                '    to SIX fewer gates than `ci` — a release gate that proved less than the\n' +
+                '    everyday gate. Delegation is what makes the superset property structural\n' +
+                '    instead of asserted. If you need a strict variant of a gate, add the\n' +
+                '    `-strict` task AFTER the delegation entry; never re-inline the list.\n',
+        );
+        return 1;
+    }
+
+    const extras = gateEntries.slice(1);
+    process.stdout.write(
+        `✅  ci-strict ⊇ ci by construction (delegates to \`ci\`, plus ${extras.length} strict-only ` +
+            `entr${extras.length === 1 ? 'y' : 'ies'}).\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main());
+}

package/src/scripts/check_cluster_patterns.ts

@@ -18,6 +18,19 @@
  * must document the bare-invocation behaviour (menu / default route /
  * detection fallback) per command-clusters.md § Bare invocation.
  *
+ * Filesystem-enumeration addition (road-to-renewal-leverage, 2026-08-02): the
+ * checks above all read the CONTRACT and ask "does what it names exist?".
+ * Nothing asked the inverse — "does what exists get named?" — so a
+ * sub-command could sit on disk while appearing in neither its hub's
+ * `## Sub-commands` table nor its `routes_to:`, invisibly. Two instances were
+ * live when this was added (`/roadmap:materialize`, `/memory:learn-low-impact`)
+ * plus incomplete `routes_to` on 12 of 25 dispatch clusters.
+ * `check_completeness` closes that direction: for a `type: orchestrator`
+ * dispatcher, every on-disk `<sub>/command.md` sibling directory must be named
+ * in the table and listed in `routes_to`. Scoped to orchestrators on purpose —
+ * a few contract rows point at full working commands that merely happen to
+ * carry one nested sub-command, and those own no dispatch table.
+ *
  * Exit codes: 0 = clean, 1 = pattern violations, 3 = internal error.
  */
 
@@ -170,6 +183,90 @@ function _repr(v: string | undefined): string {
     return `'${v.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
+/** Parse a `routes_to: [a, b]` frontmatter value into its entries. */
+export function parse_routes_to(raw: string | undefined): string[] {
+    if (raw === undefined) {
+        return [];
+    }
+    const m = /^\[(.*)\]$/.exec(raw.trim());
+    if (!m) {
+        return [];
+    }
+    return (m[1] as string)
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+        .filter((s) => s.length > 0);
+}
+
+/** Sub-command directory names that carry a `command.md`, sorted. */
+export function on_disk_subs(dispatcher_path: string): string[] {
+    const dir = path.dirname(dispatcher_path);
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && _isFile(path.join(dir, e.name, 'command.md')))
+        .map((e) => e.name)
+        .sort();
+}
+
+/**
+ * Does the body name `<sub>` as a sub-command of `<cluster>`?
+ *
+ * Both `` `/cluster:sub` `` and `` `/cluster sub` `` count — command-clusters.md
+ * § 157 makes the space form a first-class equivalent of the colon form, so
+ * requiring one of them would be inventing a rule the contract does not carry.
+ * The trailing class allows a row that decorates the name inside the same
+ * backticks (`` `/team review [--background]` ``).
+ */
+export function names_sub(body: string, cluster: string, sub: string): boolean {
+    const re = new RegExp('`/' + cluster + '[: ]' + sub + '(?![a-z0-9-])');
+    return re.test(body);
+}
+
+/**
+ * Every on-disk sub-command of an orchestrator must be named in its
+ * `## Sub-commands` table and listed in `routes_to:`.
+ *
+ * Non-orchestrator dispatchers are skipped: a handful of contract rows point
+ * at full working commands that merely happen to carry a nested sub-command,
+ * and those own no dispatch table to be complete against.
+ */
+export function check_completeness(
+    cluster: string,
+    dispatcher_path: string,
+    fm: Record<string, string>,
+    body: string,
+): string[] {
+    if (fm['type'] !== 'orchestrator') {
+        return [];
+    }
+    const subs = on_disk_subs(dispatcher_path);
+    if (subs.length === 0) {
+        return [];
+    }
+    const errors: string[] = [];
+    const routes = parse_routes_to(fm['routes_to']);
+    for (const sub of subs) {
+        if (!names_sub(body, cluster, sub)) {
+            errors.push(
+                `sub-command \`${sub}\` exists on disk but is not named in the ` +
+                    '`## Sub-commands` table',
+            );
+        }
+        if (!routes.includes(`${cluster}-${sub}`) && !routes.includes(sub)) {
+            errors.push(
+                `sub-command \`${sub}\` exists on disk but is missing from ` +
+                    '`routes_to:`',
+            );
+        }
+    }
+    return errors;
+}
+
 export function check_dispatcher(cluster: string, slug_map: Map<string, string>): FileReport {
     const p = _resolve_command(cluster, slug_map);
     if (p === null) {
@@ -241,6 +338,9 @@ export function check_dispatcher(cluster: string, slug_map: Map<string, string>)
         }
     }
 
+    // Completeness (2026-08-02): every sub-command that EXISTS must be named.
+    rep.errors.push(...check_completeness(cluster, p, fm, body));
+
     // Bare-invocation story (Phase 4 / ADR-115): the Dispatch section must say
     // what a bare `/<cluster>` does — a menu, a default route, or detection.
     const dispatchIdx = body.indexOf('## Dispatch');

package/src/scripts/check_consumer_scope_flip.ts

@@ -63,7 +63,7 @@ export interface FlipVerdict {
 
 export function verify_flip(repoRoot = '.'): FlipVerdict {
     const template = parseYaml(fs.readFileSync(path.join(repoRoot, TEMPLATE), 'utf-8')) as Record<string, unknown>;
-    const scope = ruleScopeFromSettings(template);
+    const scope = ruleScopeFromSettings(template, repoRoot);
     if (scope.workspaces === null) {
         throw new Error('template rule_workspaces is empty — nothing flipped, nothing to verify');
     }
@@ -149,8 +149,26 @@ async function main(): Promise<number> {
         },
         pass: v.pass,
     };
-    fs.mkdirSync(path.dirname(REPORT), { recursive: true });
-    fs.writeFileSync(REPORT, `${JSON.stringify(report, null, 1)}\n`);
+    // WRITE IS OPT-IN (road-to-renewal-foundation Phase 1). This used to write
+    // unconditionally, which made a `check_*` script mutate a TRACKED, DATED
+    // artifact as a side effect of merely being executed. Two concrete costs,
+    // both hit in one session:
+    //
+    //   * Any sweep that runs "every gate" — a coverage census, a timing pass,
+    //     or the pooled umbrella runner this roadmap proposes — silently dirties
+    //     the tree, and the next `task consistency` then reports derived-output
+    //     drift that has nothing to do with the diff under test.
+    //   * A dated report is a RECORD of a past measurement. Rewriting it in
+    //     place with today's numbers destroys the thing its filename claims.
+    //
+    // Verification is unchanged and still runs on every invocation; only the
+    // persistence is gated. `--write` reproduces the old behaviour for a
+    // deliberate re-measure.
+    const wrote = process.argv.includes('--write');
+    if (wrote) {
+        fs.mkdirSync(path.dirname(REPORT), { recursive: true });
+        fs.writeFileSync(REPORT, `${JSON.stringify(report, null, 1)}\n`);
+    }
     process.stdout.write(`excluded ${v.excluded.length} rules under scope [${v.scope.join(', ')}]\n`);
     if (v.violations.length > 0) {
         process.stdout.write(`❌  NON-MAINTAINER rules would drop: ${v.violations.join(' · ')}\n`);
@@ -162,7 +180,11 @@ async function main(): Promise<number> {
         `legacy-all ${legacyRules} rules / ${legacyTok} tok → scoped ${scopedRules} rules / ${scopedTok} tok `
         + `(−${legacyTok - scopedTok} tok, −${report.delta.tokens_pct}%)\n`,
     );
-    process.stdout.write(v.pass ? `✅  flip verified — wrote ${REPORT}\n` : '❌  flip NOT verified\n');
+    process.stdout.write(
+        v.pass
+            ? `✅  flip verified${wrote ? ` — wrote ${REPORT}` : ' (read-only; pass --write to persist the report)'}\n`
+            : '❌  flip NOT verified\n',
+    );
     return v.pass ? 0 : 1;
 }