@event4u/agent-config 14.13.0 → 14.14.1

package/src/scripts/check_agent_artifact_location.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env tsx
+/**
+ * Agent-artifact location guard — a roadmap-shaped file outside the roadmap root.
+ *
+ * WHAT IT PROTECTS, AND WHAT IT DOES NOT.
+ * ---------------------------------------
+ * This gate protects THIS repository, and only this one. A consumer repository
+ * never runs this repository's CI, so a gate scoped here protects the tree
+ * where the error is LEAST likely to occur — the observed failure was in a
+ * consumer project. That is not a reason to skip it, since the same mistake is
+ * possible here, but it IS a reason to write the limit down: a gate whose reach
+ * is not stated gets cited as broader than it is.
+ *
+ * The outward-facing half is `agent-config doctor --strict`, which already
+ * knows the consumer shape and can now return a non-zero exit.
+ *
+ * The constraint the detection rests on: every other mechanism that governs a
+ * roadmap is keyed on the roadmap root, so a file placed outside it is governed
+ * by nothing. This gate is the one that is keyed on the complement.
+ *
+ * WHY THE NAME TEST ALONE IS NOT THE DETECTOR.
+ * -------------------------------------------
+ * `is_roadmap_candidate` is IMPORTED from `update_roadmap_progress` rather than
+ * mirrored locally, the way `check_estate_count.ts` does it — one definition of
+ * what counts, so the roadmap corpus and this guard cannot drift apart.
+ *
+ * But that function answers "is this filename eligible to be a roadmap inside
+ * the roadmap root", and its answer over an arbitrary tree is YES for nearly
+ * every `.md` file: it excludes four names and one prefix and otherwise accepts
+ * anything. Run bare over this repository it would report thousands of
+ * legitimate documents. So the name test is a PRE-FILTER, and the decision is
+ * made by {@link roadmapShape}, which reads the file: roadmap frontmatter plus a
+ * `## Phase` heading plus at least one checkbox step. All three, because each
+ * alone is common — plenty of documents carry frontmatter, and a design doc can
+ * carry checkboxes.
+ *
+ * The finding NAMES the signals that fired, so a false positive is arguable
+ * rather than mysterious. A document that trips this gate and should not is a
+ * conversation about the signals, which is the conversation worth having.
+ *
+ * Exit codes: 0 = clean · 1 = a roadmap-shaped file sits outside the root · 3 = internal 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 { is_roadmap_candidate as isRoadmapCandidate } from '../agent-src/scripts/update_roadmap_progress.js';
+import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** The one legitimate home. Everything else is a finding. */
+export const ROADMAP_ROOT_REL = 'agents/roadmaps';
+
+/**
+ * Directories the walk never enters.
+ *
+ * `dist/` and the per-tool projection trees are generated copies — a finding
+ * there is a finding about `src/`, reported twice. `node_modules` and `.git`
+ * are not this repository's prose.
+ */
+const SKIP_DIRS: ReadonlySet<string> = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    '.augment',
+    '.claude',
+    '.cursor',
+    '.clinerules',
+    '.agents',
+    'coverage',
+    '.venv',
+]);
+
+/** Frontmatter keys that only a roadmap carries in this tree. */
+const FM_ROADMAP_RE = /^complexity:[ \t]*(lightweight|structural)[ \t]*$/m;
+const FM_RE = /^---\n([\s\S]*?)\n---/;
+const PHASE_RE = /^##[ \t]+Phase[ \t]/m;
+const CHECKBOX_RE = /^[ \t]*- \[[ x~-]\][ \t]/m;
+
+export interface Shape {
+    /** Which signals fired. Empty means not roadmap-shaped. */
+    readonly signals: readonly string[];
+    readonly isRoadmap: boolean;
+}
+
+/**
+ * Decide whether a file's CONTENT is a roadmap.
+ *
+ * All three signals are required. Each is individually common; together they are
+ * this repository's roadmap format and nothing else's.
+ */
+export function roadmapShape(text: string): Shape {
+    const signals: string[] = [];
+    const fm = FM_RE.exec(text);
+    if (fm !== null && FM_ROADMAP_RE.test(fm[1] as string)) {
+        signals.push('roadmap frontmatter (`complexity:` lightweight|structural)');
+    }
+    if (PHASE_RE.test(text)) {
+        signals.push('a `## Phase` heading');
+    }
+    if (CHECKBOX_RE.test(text)) {
+        signals.push('at least one checkbox step');
+    }
+    return { signals, isRoadmap: signals.length === 3 };
+}
+
+export interface Finding {
+    readonly rel: string;
+    readonly signals: readonly string[];
+}
+
+export interface ScanResult {
+    readonly findings: readonly Finding[];
+    /** Every `.md` file the walk visited — the scope, not the matches. */
+    readonly scanned: number;
+}
+
+function walkMarkdown(root: string): string[] {
+    const out: string[] = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const cur = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isSymbolicLink()) continue;
+            const full = path.join(cur, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name)) stack.push(full);
+            } else if (e.name.toLowerCase().endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    }
+    return out.sort();
+}
+
+/** `true` when `child` is at or below `root`. */
+function isUnder(child: string, root: string): boolean {
+    const rel = path.relative(root, child);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+export function scan(root: string): ScanResult {
+    const roadmapRoot = path.join(root, ...ROADMAP_ROOT_REL.split('/'));
+    const files = walkMarkdown(root);
+    const findings: Finding[] = [];
+    for (const f of files) {
+        if (isUnder(f, roadmapRoot)) continue;
+        // Cheap name pre-filter first — the SHARED definition, imported, so the
+        // roadmap corpus and this guard cannot drift apart.
+        if (!isRoadmapCandidate(f)) continue;
+        let text: string;
+        try {
+            text = fs.readFileSync(f, 'utf-8');
+        } catch {
+            continue;
+        }
+        const shape = roadmapShape(text);
+        if (!shape.isRoadmap) continue;
+        findings.push({
+            rel: path.relative(root, f).split(path.sep).join('/'),
+            signals: shape.signals,
+        });
+    }
+    return { findings, scanned: files.length };
+}
+
+interface Args {
+    quiet: boolean;
+    selfTest: boolean;
+    root: string;
+}
+
+function parseArgs(argv: readonly string[]): Args {
+    const args: Args = { quiet: false, selfTest: false, root: REPO_ROOT };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--quiet') args.quiet = true;
+        else if (a === '--self-test') args.selfTest = true;
+        else if (a === '--root') args.root = path.resolve(argv[++i] ?? '.');
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                'usage: check_agent_artifact_location [-h] [--quiet] [--root DIR] [--self-test]\n',
+            );
+            process.exit(0);
+        } else {
+            process.stderr.write(
+                `check_agent_artifact_location: error: unrecognized arguments: ${a}\n`,
+            );
+            process.exit(2);
+        }
+    }
+    return args;
+}
+
+/** A minimal file with all three shape signals. */
+const ROADMAP_FIXTURE =
+    '---\ncomplexity: lightweight\nstatus: ready\n---\n' +
+    '# Road to a fixture\n\n## Phase 1 - a phase\n\n- [ ] **1.1 A step.**\n';
+
+/** Same content, but not roadmap-shaped — frontmatter only. */
+const PROSE_FIXTURE = '---\ntitle: a design note\n---\n\n# A design note\n\n- [ ] a todo\n';
+
+function selfTestCases(): SelfTestCase[] {
+    const mk = (rel: string, body: string): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'artloc-'));
+        const full = path.join(dir, ...rel.split('/'));
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, body);
+        return dir;
+    };
+    const run = (dir: string): number =>
+        runGateCli(
+            REPO_ROOT,
+            'src/scripts/check_agent_artifact_location.ts',
+            ['--root', dir, '--quiet'],
+            REPO_ROOT,
+        );
+    return [
+        {
+            name: 'a roadmap-shaped file under docs/roadmaps/ is reported',
+            expect: 'reject',
+            run: () => run(mk('docs/roadmaps/road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'a roadmap-shaped file at the tree root is reported',
+            expect: 'reject',
+            run: () => run(mk('road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'the SAME file under agents/roadmaps/ is not reported',
+            expect: 'accept',
+            run: () => run(mk('agents/roadmaps/road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'a file under agents/roadmaps/later/ is not reported',
+            expect: 'accept',
+            run: () => run(mk('agents/roadmaps/later/road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'prose carrying frontmatter and a checkbox but no phase is not reported',
+            expect: 'accept',
+            run: () => run(mk('docs/a-design-note.md', PROSE_FIXTURE)),
+        },
+    ];
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = parseArgs(argv ?? process.argv.slice(2));
+
+    if (args.selfTest) {
+        return runSelfTest({
+            gate: 'check_agent_artifact_location',
+            cases: selfTestCases(),
+            minCases: 5,
+            minRejectCases: 2,
+        });
+    }
+
+    let result: ScanResult;
+    try {
+        result = scan(args.root);
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`❌  internal error: ${msg}\n`);
+        return 3;
+    }
+
+    // The unit is every `.md` the walk VISITED, not the matches: zero matches is
+    // the normal clean state, so only the unfiltered walk can tell "nothing
+    // misplaced" from "nothing read".
+    try {
+        reportScanned({
+            gate: 'check_agent_artifact_location',
+            scanned: result.scanned,
+            units: 'markdown file(s)',
+            roots: [path.relative(REPO_ROOT, args.root) || '.'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    if (result.findings.length === 0) {
+        if (!args.quiet) {
+            process.stdout.write(
+                `✅  check_agent_artifact_location: no roadmap-shaped file outside ` +
+                    `${ROADMAP_ROOT_REL}/ (${String(result.scanned)} markdown file(s) read).\n`,
+            );
+        }
+        return 0;
+    }
+
+    process.stderr.write(
+        `❌  check_agent_artifact_location: ${String(result.findings.length)} ` +
+            `roadmap-shaped file(s) outside ${ROADMAP_ROOT_REL}/:\n`,
+    );
+    for (const f of result.findings) {
+        process.stderr.write(`    ${f.rel}\n`);
+        process.stderr.write(`      reads as a roadmap because it carries ${f.signals.join(', ')}\n`);
+    }
+    process.stderr.write(
+        `    Move it to ${ROADMAP_ROOT_REL}/, or — if it is genuinely not a roadmap — ` +
+            'say which of the three signals it should not be carrying.\n' +
+            '    NOTE: this gate scans THIS repository only. A consumer project never runs\n' +
+            '    it; `agent-config doctor` is the surface that carries a finding outward.\n',
+    );
+    return 1;
+}
+
+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 {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/check_artefact_count_messaging.ts

@@ -20,10 +20,14 @@
  *   - `check_command_count_messaging.ts` keeps the command-specific
  *     active-vs-shim split checks.
  *
- * Scope: flagship surfaces only (SURFACES below). Dated census / analysis
- * snapshots (SKILL_CENSUS, skills-taxonomy, positioning-evidence, …) carry
- * point-in-time counts by design and are deliberately out of scope — the
- * gate's charter is the surfaces a fresh reader treats as current.
+ * Scope: flagship surfaces (SURFACES below) PLUS every governed rule under
+ * `src/rules/` (RULE_SURFACE_DIR). Rules were the largest hole this gate had:
+ * they are the most-delivered surface this package ships — a wrong self-count
+ * there reaches every consumer session — and the list below named sixteen doc
+ * paths and no rule path. Dated census / analysis snapshots (SKILL_CENSUS,
+ * skills-taxonomy, positioning-evidence, …) carry point-in-time counts by
+ * design and are deliberately out of scope — the gate's charter is the surfaces
+ * a fresh reader treats as current.
  *
  * Exit codes: 0 clean · 1 drift or internal inconsistency.
  */
@@ -66,6 +70,41 @@ export const SURFACES: readonly string[] = [
     // absent there. A gate must judge repo content, not untracked local state.
 ];
 
+/**
+ * Governed rules, enumerated rather than listed.
+ *
+ * A hand-maintained list of 120 rule paths would go stale on the first rule
+ * added, which is the drift class this gate exists to catch — so the rule
+ * surface is a directory, walked at run time.
+ */
+export const RULE_SURFACE_DIR = 'src/rules';
+
+export function rule_surfaces(root: string = ROOT): string[] {
+    const dir = path.join(root, RULE_SURFACE_DIR);
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((f) => `${RULE_SURFACE_DIR}/${f}`);
+}
+
+/**
+ * A count that belongs to a dated measurement, not to this package's live
+ * totals.
+ *
+ * The gate's charter already excludes point-in-time snapshots; until now it
+ * could only express that by leaving a whole FILE out. A rule may carry a dated
+ * host measurement inside a paragraph of live prose, and neither excluding the
+ * rule nor rewriting the measurement to today's total is correct — the second
+ * falsifies recorded evidence. The marker is per line, and it is a claim a
+ * reviewer can falsify: the line must name the date or the artefact the figure
+ * was measured against.
+ */
+export const DATED_MEASUREMENT_MARKER = '<!-- count: dated -->';
+
 /** kind → canonical-count resolver. "governed rules" is the canonical total
  * phrasing for rules; bare "N rules" is NOT matched (too many legitimate
  * subset scopes: kernel rules, router rules, maintainer-only rules …). */
@@ -108,6 +147,9 @@ export function scan_text(
     for (const [kind, pattern] of KIND_PATTERNS) {
         for (let i = 0; i < lines.length; i++) {
             const re = new RegExp(pattern.source, pattern.flags);
+            if (lines[i]!.includes(DATED_MEASUREMENT_MARKER)) {
+                continue;
+            }
             for (const m of lines[i]!.matchAll(re)) {
                 const found = Number.parseInt(m[2]!, 10);
                 (seen[kind] ??= new Set()).add(found);
@@ -219,6 +261,15 @@ export interface CoverageGap {
  *
  * A position counts as anchored when some `TARGETS` pattern for the same
  * file, bound to a compatible kind, matches the same line.
+ *
+ * `src/rules/**` is scanned for VALUE drift but is deliberately excluded from
+ * this pass, and the reason is mechanical rather than stylistic: satisfying it
+ * would require `update_counts` to become a writer into `src/rules/`, where the
+ * kernel rules live behind `block_kernel_rule_writes`. A generator that must
+ * never touch part of its own target directory is a generator waiting to be
+ * disarmed by a path move. So a stale count in a rule fails on value and a human
+ * fixes it — the coverage claim this pass makes stays true of the surfaces it
+ * actually covers, instead of being widened into a claim it cannot keep.
  */
 export function anchor_coverage_gaps(root: string = ROOT): CoverageGap[] {
     const anchorsByFile = new Map<string, ReadonlyArray<[string, string]>>();
@@ -254,6 +305,16 @@ export function anchor_coverage_gaps(root: string = ROOT): CoverageGap[] {
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const QUIET = argv.includes('--quiet');
+    // Enumerated, not listed. An empty walk means the rule tree moved and this
+    // gate is watching nothing — a dead scope, never a clean run.
+    const rules = rule_surfaces();
+    if (rules.length === 0) {
+        process.stderr.write(
+            `❌  check_artefact_count_messaging: ${RULE_SURFACE_DIR}/ resolved to no .md file — ` +
+                'the rule surface moved and this gate would pass by blindness.\n',
+        );
+        return 1;
+    }
     // This gate walks no tree — it guards a hand-maintained surface list, and
     // every missing entry is skipped with a warning so nothing hard-breaks on a
     // doc rename. That tolerance is also the failure mode: a repo-wide docs
@@ -262,7 +323,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     try {
         assertWatchlistResolves({
             gate: 'check_artefact_count_messaging',
-            candidates: [...SURFACES, ...STRUCTURED_SURFACES.map((s) => s.file)],
+            candidates: [...SURFACES, ...STRUCTURED_SURFACES.map((s) => s.file), ...rules],
             repoRoot: ROOT,
         });
     } catch (exc) {
@@ -285,7 +346,7 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
 
     const allFindings: Finding[] = [];
     const global_seen: Record<string, Set<number>> = {};
-    for (const rel of SURFACES) {
+    for (const rel of [...SURFACES, ...rules]) {
         const p = path.join(ROOT, rel);
         if (!fs.existsSync(p)) {
             process.stderr.write(`  ⚠️  surface missing (skipped): ${rel}\n`);
@@ -347,8 +408,13 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             process.stdout.write(`    internal inconsistency — ${line}\n`);
         }
         process.stdout.write(
-            '\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',
+            '\nFix: on a flagship surface, run `./scripts-run src/scripts/update_counts` —\n' +
+                'every anchored position is generator-written, so never hand-type one there.\n' +
+                `Under ${RULE_SURFACE_DIR}/ the generator does not write (the kernel rules live\n` +
+                'there behind block_kernel_rule_writes), so a rule count is a hand edit: correct\n' +
+                'the number, or — if the figure is a dated measurement rather than a live\n' +
+                `self-count — mark that line \`${DATED_MEASUREMENT_MARKER}\` and say what it was\n` +
+                'measured against.\n',
         );
     }
 

package/src/scripts/check_enforcement_coverage.ts

@@ -628,6 +628,26 @@ export interface Summary {
     frequency_gap: number;
     /** Rules with no `obligation_frequency` to join — the nine kernel rules. */
     frequency_unclassified: number;
+    /**
+     * The three classes that make `undeclared` readable.
+     *
+     * WHY THEY SHIP IN THE ARTEFACT. `undeclared` is the number reviewers quote,
+     * and quoted bare it reads as a backlog of rules somebody forgot to wire.
+     * Most of it is nothing of the kind. `kernel_denied` rules cannot carry an
+     * `enforced_by` field at all — `block_kernel_rule_writes` refuses the write
+     * with no agent-accessible override, so their absence is structural.
+     * `observer` rules have a carrier that fires and cannot block by design.
+     * `carrier_less` rules have no machine carrier of any kind.
+     *
+     * A reader subtracting these from `undeclared` gets the population where
+     * wiring is actually the missing thing — and, more usefully, sees at a glance
+     * that the observer set (10) is the reachable one: a floor set against the
+     * full `undeclared` would stall in its second release and be ignored, which
+     * is the failure `check_release_highlights.ts` already documents for its own
+     * warning.
+     */
+    kernel_denied: number;
+    carrier_less: number;
     /**
      * The denominator every figure above is taken over, WITH its frame. See
      * {@link denominator_frames} for why the frame ships even when the two
@@ -652,6 +672,14 @@ export function summarise(rows: RuleCoverage[]): Summary {
         blocking_pct: rows.length === 0 ? 0 : Math.round((blocking / rows.length) * 1000) / 10,
         frequency_gap: count((r) => r.frequency_verdict === 'gap'),
         frequency_unclassified: count((r) => r.frequency_verdict === 'unclassified'),
+        kernel_denied: count(
+            (r) => KERNEL_RULE_ID_SET.has(r.id) && r.frequency_verdict === 'unclassified',
+        ),
+        carrier_less: count(
+            (r) =>
+                r.declared.length > 0 &&
+                r.declared.every((d) => d.startsWith('observer:maintainer-review')),
+        ),
         frames: denominator_frames(rows.length),
     };
 }
@@ -779,7 +807,13 @@ function main(argv: string[]): number {
                         'blocking and in that bucket at once. Coverage is a ratchet: --check fails ' +
                         'when blocking falls, or unwired / local_only / missing / frequency_gap ' +
                         'rises. Regenerate intentionally with --write-baseline when the change is ' +
-                        'the point.',
+                        'the point. READ `undeclared` WITH ITS THREE CLASSES, never bare: ' +
+                        '`kernel_denied` cannot carry an enforced_by field at all ' +
+                        '(block_kernel_rule_writes refuses the write, no agent-accessible ' +
+                        'override), `observer` has a carrier that fires and cannot block by ' +
+                        'design, and `carrier_less` has no machine carrier of any kind. The ' +
+                        'reachable population is the observer set, not `undeclared` — a floor ' +
+                        'set against the full number would stall in its second release.',
                     summary,
                 },
                 null,
@@ -811,6 +845,11 @@ function main(argv: string[]): number {
         `  frequency: ${summary.frequency_gap} gap · ${summary.frequency_unclassified} unclassified ` +
             `(kernel — block_kernel_rule_writes denies the field)`,
     );
+    lines.push(
+        `  undeclared ${summary.undeclared} splits: ${summary.kernel_denied} kernel-denied · ` +
+            `${summary.observer} observer · ${summary.carrier_less} carrier-less — ` +
+            `the observer set is the reachable population`,
+    );
     // The denominator is published WITH its frame, and it is the only sanctioned
     // source for that number: `check_enforcement_denominator` reds when a
     // tracked doc carries an enforcement count this resolver did not produce.