@event4u/agent-config 7.4.0 → 8.0.0

package/src/scripts/lint_roadmap_blockers.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env tsx
+/**
+ * Hard-gate linter for the roadmap `## Blockers` contract
+ * (`templates/roadmaps.md` rule 20 / `roadmap-ci-steps-policy` siblings).
+ *
+ * Validates, for every active roadmap under `agents/roadmaps/*.md`:
+ *
+ *   1. Every `### blocker: <id>` entry declares all five required fields
+ *      (Status, Owner, Blocks, What to do, Resolved when).
+ *   2. Every inline `<!-- blocked-by: <id> -->` annotation resolves to a
+ *      `### blocker: <id>` entry declared in the SAME file.
+ *
+ * Fenced code blocks are stripped before scanning so a roadmap that shows
+ * the `## Blockers` shape as a documentation example is not flagged.
+ *
+ * Exit codes: 0 = clean / no active roadmaps, 1 = violations.
+ */
+
+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 QUIET = process.argv.slice(2).includes('--quiet');
+
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const ROADMAP_GLOB = 'agents/roadmaps/*.md';
+
+const FENCED_CODE_RE = /^[ \t]*```[^\n]*\n[\s\S]*?^[ \t]*```[ \t]*$/gm;
+const BLOCKERS_SECTION_RE = /^##[ \t]+Blockers[ \t]*$/im;
+const NEXT_H2_RE = /^##[ \t]+\S/m;
+const BLOCKER_HEADING_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/gim;
+// Only a real checkbox line (`- [ ] … <!-- blocked-by: id -->`) counts — a
+// wrapped continuation line or inline-code documentation example of the
+// syntax (as this very lint script's own roadmap step describes it) must
+// not be mistaken for a live cross-reference.
+const BLOCKED_BY_LINE_RE = /^-[ \t]*\[[ xX~-]\].*<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*-->/i;
+
+const REQUIRED_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
+    ['Status', /^-[ \t]*\*\*Status:\*\*/im],
+    ['Owner', /^-[ \t]*\*\*Owner:\*\*/im],
+    ['Blocks', /^-[ \t]*\*\*Blocks:\*\*/im],
+    ['What to do', /^-[ \t]*\*\*What to do:\*\*/im],
+    ['Resolved when', /^-[ \t]*\*\*Resolved when:\*\*/im],
+];
+
+interface Violation {
+    line: number;
+    message: string;
+}
+
+/** 1-based line number of a character offset. */
+function _lineAt(text: string, index: number): number {
+    let n = 1;
+    for (let i = 0; i < index && i < text.length; i++) {
+        if (text.charCodeAt(i) === 10) {
+            n += 1;
+        }
+    }
+    return n;
+}
+
+/** Blank out fenced code blocks, preserving line count and offsets. */
+function _stripFencedCode(text: string): string {
+    return text.replace(FENCED_CODE_RE, (m) => '\n'.repeat((m.match(/\n/g) ?? []).length));
+}
+
+function _scan(rawText: string): Violation[] {
+    const violations: Violation[] = [];
+    const text = _stripFencedCode(rawText);
+    const declaredIds = new Set<string>();
+
+    const sectionMatch = BLOCKERS_SECTION_RE.exec(text);
+    if (sectionMatch) {
+        const sectionStart = sectionMatch.index + sectionMatch[0].length;
+        const rest = text.slice(sectionStart);
+        const h2 = NEXT_H2_RE.exec(rest);
+        const sectionEnd = h2 ? sectionStart + h2.index : text.length;
+        const section = text.slice(sectionStart, sectionEnd);
+
+        BLOCKER_HEADING_RE.lastIndex = 0;
+        const heads: Array<{ start: number; end: number; id: string }> = [];
+        let hm: RegExpExecArray | null;
+        while ((hm = BLOCKER_HEADING_RE.exec(section)) !== null) {
+            heads.push({
+                start: hm.index,
+                end: hm.index + hm[0].length,
+                id: (hm[1] as string).trim(),
+            });
+            if (hm.index === BLOCKER_HEADING_RE.lastIndex) {
+                BLOCKER_HEADING_RE.lastIndex++;
+            }
+        }
+        for (let i = 0; i < heads.length; i++) {
+            const cur = heads[i] as { start: number; end: number; id: string };
+            declaredIds.add(cur.id);
+            const bodyEnd = i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
+            const body = section.slice(cur.end, bodyEnd);
+            const missing = REQUIRED_FIELDS.filter(([, re]) => !re.test(body)).map(([name]) => name);
+            if (missing.length) {
+                violations.push({
+                    line: _lineAt(text, sectionStart + cur.start),
+                    message: `blocker '${cur.id}' missing required field(s): ${missing.join(', ')}`,
+                });
+            }
+        }
+    }
+
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        // A real annotation is bare markdown (an actual checkbox + HTML
+        // comment); an inline-code-quoted mention (`` `<!-- blocked-by: id -->` ``,
+        // e.g. this very lint script's own roadmap step documenting the
+        // syntax) is prose, not a live cross-reference — blank inline code
+        // spans before matching.
+        const cleaned = (lines[i] as string).replace(/`[^`\n]*`/g, (m) => ' '.repeat(m.length));
+        const m = BLOCKED_BY_LINE_RE.exec(cleaned);
+        if (!m) {
+            continue;
+        }
+        const id = m[1] as string;
+        if (!declaredIds.has(id)) {
+            violations.push({
+                line: i + 1,
+                message:
+                    `blocked-by references unknown blocker id '${id}' ` +
+                    `(no matching '### blocker: ${id}' in this file)`,
+            });
+        }
+    }
+    violations.sort((a, b) => a.line - b.line);
+    return violations;
+}
+
+/** Sorted `agents/roadmaps/*.md` (non-recursive — active roadmaps only). */
+function _globRoadmaps(): string[] {
+    const dir = path.join(REPO_ROOT, 'agents', 'roadmaps');
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+            out.push(path.join(dir, entry.name));
+        }
+    }
+    return out.sort();
+}
+
+function _relPosix(target: string, root: string): string {
+    return path.relative(root, target).split(path.sep).join('/');
+}
+
+function main(): number {
+    const roadmaps = _globRoadmaps();
+    if (roadmaps.length === 0) {
+        if (!QUIET) {
+            process.stdout.write(`✅  no active roadmaps under ${ROADMAP_GLOB}\n`);
+        }
+        return 0;
+    }
+    let failed = 0;
+    for (const roadmap of roadmaps) {
+        const rel = _relPosix(roadmap, REPO_ROOT);
+        const text = fs.readFileSync(roadmap, 'utf-8');
+        const violations = _scan(text);
+        if (violations.length) {
+            failed += 1;
+            process.stderr.write(`❌  ${rel}\n`);
+            for (const v of violations) {
+                process.stderr.write(`    line ${v.line}: ${v.message}\n`);
+            }
+        } else if (!QUIET) {
+            process.stdout.write(`✅  ${rel}\n`);
+        }
+    }
+    if (failed) {
+        process.stderr.write(
+            `\n❌  ${failed} roadmap(s) violate the ## Blockers contract — ` +
+                'see .augment/rules/roadmap-progress-sync.md and ' +
+                '.augment/templates/roadmaps.md rule 20\n',
+        );
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(`\n✅  ${roadmaps.length} roadmap(s) blocker-contract-clean\n`);
+    }
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { REPO_ROOT, ROADMAP_GLOB, REQUIRED_FIELDS, _scan, _globRoadmaps, main };
+export type { Violation };

package/src/scripts/lint_roadmap_complexity.ts

@@ -42,6 +42,9 @@ const COUNCIL_PAT = /^## Council Round \d+\b/m;
 const VERDICT_PAT = /^### Verdict\b/m;
 // re.compile(r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE)
 const COMPLEXITY_PAT = /^complexity:\s*(lightweight|structural)\s*$/m;
+// execution.mode (templates/roadmaps.md rule 18): nested under `execution:`.
+const EXEC_MODE_PAT = /^execution:[^\S\n]*\n(?:[ \t]+(?!mode:).*\n)*[ \t]+mode:[ \t]*([^\s#]+)/m;
+const EXEC_MODE_VALUES = new Set(['autonomous', 'phase-checkpoints', 'interactive']);
 
 // Plate / horizon detection — template rule 16 forbids time-boxed plates.
 const PLATE_PATS: ReadonlyArray<readonly [RegExp, string]> = [
@@ -161,7 +164,11 @@ function _check_no_plate(text: string, problems: string[]): void {
     }
 }
 
-function lint_roadmap(p: string, horizon_weeks: number): string[] {
+function lint_roadmap(
+    p: string,
+    horizon_weeks: number,
+    warnings?: string[],
+): string[] {
     const text = fs.readFileSync(p, 'utf-8');
     const line_count = _countChar(text, '\n') + (text && !text.endsWith('\n') ? 1 : 0);
     const problems: string[] = [];
@@ -180,9 +187,77 @@ function lint_roadmap(p: string, horizon_weeks: number): string[] {
     if (horizon_weeks <= 0) {
         _check_no_plate(text, problems);
     }
+    _check_execution_mode(fm, problems);
+    if (warnings) {
+        _check_autonomous_authoring(text, fm, warnings);
+    }
     return problems;
 }
 
+// Vague-step patterns (ask-when-uncertain trigger subset) — under
+// execution.mode: autonomous these guarantee mid-run ambiguity halts,
+// so they warn at authoring time instead. Warnings never fail the lint.
+const VAGUE_STEP_PATS: Array<[RegExp, string]> = [
+    [/\b(improve|optimi[sz]e)\b(?!.*\bby\b)/i, "'improve / optimize' without a measurable target"],
+    [/\bmake (it|this|.{0,30}) (better|cleaner|nicer)\b/i, "'make it better/cleaner'"],
+    [/\bclean ?up\b(?!.*\(<)/i, "'clean up' without named scope"],
+    [/\bfix (this|it)\b/i, "'fix this' without a symptom"],
+    [/\buse best practices\b/i, "'use best practices'"],
+    [/\bhandle errors properly\b/i, "'handle errors properly'"],
+];
+
+function _check_autonomous_authoring(text: string, fm: string, warnings: string[]): void {
+    const m = EXEC_MODE_PAT.exec(fm);
+    if (m === null || m[1]!.replace(/^['"]|['"]$/g, '') !== 'autonomous') {
+        return;
+    }
+    const deferred = _countMatches(/^\s*-\s*\[~\]/m, text);
+    if (deferred > 0) {
+        warnings.push(
+            `execution.mode: autonomous with ${deferred} pre-existing [~] deferred item(s) — ` +
+                'the deferred-resolution archival gate (roadmap-progress-sync Iron Law 3) ' +
+                'WILL interrupt the run at the end; resolve or re-author them now',
+        );
+    }
+    for (const rawLine of text.split('\n')) {
+        if (!/^\s*-\s*\[ \]/.test(rawLine)) {
+            continue;
+        }
+        for (const [re, label] of VAGUE_STEP_PATS) {
+            if (re.test(rawLine)) {
+                warnings.push(
+                    `vague step under execution.mode: autonomous (${label}): ` +
+                        `"${rawLine.trim().slice(0, 80)}" — vagueness resolves cheaply at ` +
+                        'authoring time, expensively as a mid-run ambiguity halt',
+                );
+                break;
+            }
+        }
+    }
+}
+
+function _check_execution_mode(fm: string, problems: string[]): void {
+    if (!fm || !/^execution:/m.test(fm)) {
+        return; // absent field = interactive default — valid
+    }
+    const m = EXEC_MODE_PAT.exec(fm);
+    if (m === null) {
+        problems.push(
+            "'execution:' frontmatter block present but no 'mode:' key found " +
+                "(expected execution.mode: autonomous | phase-checkpoints | interactive " +
+                'per templates/roadmaps.md rule 18)',
+        );
+        return;
+    }
+    const value = m[1]!.replace(/^['"]|['"]$/g, '');
+    if (!EXEC_MODE_VALUES.has(value)) {
+        problems.push(
+            `unknown execution.mode '${value}' — allowed: autonomous | ` +
+                'phase-checkpoints | interactive (templates/roadmaps.md rule 18)',
+        );
+    }
+}
+
 function main(): number {
     const roadmaps = _globRoadmaps();
     const horizon_weeks = _read_horizon_weeks();
@@ -196,7 +271,11 @@ function main(): number {
     const summary: Array<[string, string]> = [];
     for (const roadmap of roadmaps) {
         const rel = _relPosix(roadmap, REPO_ROOT);
-        const problems = lint_roadmap(roadmap, horizon_weeks);
+        const warnings: string[] = [];
+        const problems = lint_roadmap(roadmap, horizon_weeks, warnings);
+        for (const w of warnings) {
+            process.stderr.write(`⚠️  ${rel}\n    - ${w}\n`);
+        }
         const text = fs.readFileSync(roadmap, 'utf-8');
         const complexity = _read_complexity(_frontmatter(text)) ?? 'untagged';
         summary.push([rel, complexity]);

package/src/scripts/lint_subagent_determinism.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env tsx
+/**
+ * Lint subagent determinism — the ADR-109 guarantees the schema mini-validator
+ * cannot express.
+ *
+ * `validate_frontmatter` (the schema gate) covers type / enum / required /
+ * pattern, but its mini-validator ignores JSON-Schema `const` and `uniqueItems`.
+ * This lint closes that gap for `src/subagents/*.md`:
+ *
+ *   1. `schema_version` MUST equal `subagent-v1` (schema `const`).
+ *   2. `discovery.visible` MUST be exactly `false` — default-off (schema `const`).
+ *   3. `tools` MUST have no duplicate entries (schema `uniqueItems`).
+ *   4. `name` MUST match the filename stem (addressable-handle invariant).
+ *   5. `name` MUST be globally unique across the subagent category
+ *      (projection-path collision guard — two units would overwrite each other
+ *      in `.claude/agents/`).
+ *
+ * Exit codes: 0 clean, 1 any violation.
+ *
+ * See ADR-109 (§ 6 determinism) and `src/scripts/schemas/subagent.schema.json`.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { parse_frontmatter } from './validate_frontmatter.js';
+
+const QUIET = process.argv.includes('--quiet');
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const SUBAGENT_DIR = path.join(REPO, 'src', 'subagents');
+
+function _listSubagents(dir: string): string[] {
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((f) => path.join(dir, f));
+}
+
+function main(dir: string = SUBAGENT_DIR): number {
+    const findings: string[] = [];
+    const namesSeen = new Map<string, string>();
+
+    for (const file of _listSubagents(dir)) {
+        const rel = path.relative(REPO, file);
+        const stem = path.basename(file, '.md');
+        const text = fs.readFileSync(file, 'utf-8');
+        const [data] = parse_frontmatter(text);
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            findings.push(`${rel}: no parseable frontmatter`);
+            continue;
+        }
+        const fm = data as Record<string, unknown>;
+
+        if (fm.schema_version !== 'subagent-v1') {
+            findings.push(`${rel}: schema_version must be 'subagent-v1' (got ${JSON.stringify(fm.schema_version)})`);
+        }
+
+        const discovery = fm.discovery;
+        const visible =
+            discovery !== null && typeof discovery === 'object' && !Array.isArray(discovery)
+                ? (discovery as Record<string, unknown>).visible
+                : undefined;
+        if (visible !== false) {
+            findings.push(`${rel}: discovery.visible must be exactly false (default-off; got ${JSON.stringify(visible)})`);
+        }
+
+        const tools = fm.tools;
+        if (Array.isArray(tools)) {
+            const seen = new Set<unknown>();
+            const dupes = new Set<unknown>();
+            for (const t of tools) {
+                if (seen.has(t)) {
+                    dupes.add(t);
+                }
+                seen.add(t);
+            }
+            if (dupes.size > 0) {
+                findings.push(`${rel}: tools has duplicate entr(y/ies): ${[...dupes].map((d) => JSON.stringify(d)).join(', ')}`);
+            }
+        }
+
+        const name = fm.name;
+        if (typeof name !== 'string' || name !== stem) {
+            findings.push(`${rel}: name must match the filename stem '${stem}' (got ${JSON.stringify(name)})`);
+        } else {
+            const prior = namesSeen.get(name);
+            if (prior !== undefined) {
+                findings.push(`${rel}: duplicate subagent name '${name}' (also in ${prior}) — projection-path collision`);
+            } else {
+                namesSeen.set(name, rel);
+            }
+        }
+    }
+
+    if (findings.length > 0) {
+        process.stdout.write('❌ subagent determinism:\n');
+        for (const f of findings.sort()) {
+            process.stdout.write(`  - ${f}\n`);
+        }
+        return 1;
+    }
+
+    if (!QUIET) {
+        process.stdout.write(
+            `✅  subagent determinism: ${namesSeen.size} subagent(s) clean.\n`,
+        );
+    }
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry) {
+    process.exit(main());
+}
+
+export { main };

package/src/scripts/measure_augment_budget.ts

@@ -16,8 +16,10 @@
  * 2. `always`-type rules under `.augment/rules/` — full body injected.
  * 3. `auto`-type rules — only a registry stub is injected per rule.
  *
- * The 49,512-char ceiling is the empirical limit observed against the
- * Augment Code workspace prompt (2026-05-08 baseline).
+ * The cap comes from `src/config/budgets.yml`
+ * (augment_workspace_guidelines) — the single source of truth for the
+ * budget gates. The internal cap is deliberately below the verified
+ * platform maximum recorded there.
  *
  * Exit codes: 0 = under fail threshold, 1 = at/above fail threshold,
  * 3 = internal error.
@@ -39,10 +41,48 @@ export const TREND_FILE = path.join(
     '.augment-budget-history.jsonl',
 );
 
-// Augment workspace-guidelines ceiling — empirical 2026-05-08.
-export const TOTAL_CAP = 49_512;
-export const WARN_THRESHOLD = 0.85;
-export const FAIL_THRESHOLD = 0.95;
+// Budget caps — loaded from src/config/budgets.yml (single source of truth).
+export const BUDGETS_FILE = path.join(REPO_ROOT, 'src', 'config', 'budgets.yml');
+
+interface BudgetConfig {
+    platform_max_chars: number;
+    total_cap_chars: number;
+    warn_threshold: number;
+    fail_threshold: number;
+}
+
+function _load_budget_config(): BudgetConfig {
+    // Tiny purpose-built reader (keys are flat scalars) — avoids a hard yaml
+    // dependency in a script that must run before `npm ci` in some flows.
+    const text = fs.readFileSync(BUDGETS_FILE, 'utf-8');
+    const section = text.split(/^augment_workspace_guidelines:\s*$/m)[1] ?? '';
+    const num = (key: string): number => {
+        const m = new RegExp(`^\\s+${key}:\\s*([0-9.]+)\\s*$`, 'm').exec(section);
+        if (!m) {
+            throw new Error(`budgets.yml: missing augment_workspace_guidelines.${key}`);
+        }
+        return Number(m[1]);
+    };
+    const cfg: BudgetConfig = {
+        platform_max_chars: num('platform_max_chars'),
+        total_cap_chars: num('total_cap_chars'),
+        warn_threshold: num('warn_threshold'),
+        fail_threshold: num('fail_threshold'),
+    };
+    if (cfg.total_cap_chars > cfg.platform_max_chars) {
+        throw new Error(
+            `budgets.yml: total_cap_chars (${cfg.total_cap_chars}) must never exceed ` +
+                `platform_max_chars (${cfg.platform_max_chars})`,
+        );
+    }
+    return cfg;
+}
+
+const _BUDGET = _load_budget_config();
+export const PLATFORM_MAX = _BUDGET.platform_max_chars;
+export const TOTAL_CAP = _BUDGET.total_cap_chars;
+export const WARN_THRESHOLD = _BUDGET.warn_threshold;
+export const FAIL_THRESHOLD = _BUDGET.fail_threshold;
 
 // Stub template Augment injects for `type: auto` rules.
 function STUB(desc: string, p: string): string {

package/src/scripts/measure_patterns.ts

@@ -21,8 +21,9 @@
  *   7. Runtime boundary disclaimer
  *   8. Anti-sycophancy rules in "Do NOT"
  *
- * NOTE: the .py reads from the legacy `.agent-src.uncondensed/skills`
- * literal; this faithful twin replicates it byte-for-byte.
+ * NOTE: scans `src/skills` — the canonical source-of-truth skill library.
+ * (The pre-py2ts .py read the now-removed legacy condensed-source skills
+ * corpus; repointed here so the scanner runs on the live tree.)
  */
 
 import * as fs from 'node:fs';
@@ -32,7 +33,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/measure_patterns.ts → parents[2] is the repo root.
 const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const SKILLS_DIR = path.join(ROOT, '.agent-src.uncondensed', 'skills');
+const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
 
 type Tier = number | string;
 

package/src/scripts/measure_skill_reduction.ts

@@ -20,11 +20,11 @@
  *     measure_skill_reduction
  *     measure_skill_reduction --json
  *
- * NOTE: the .py references the legacy `.agent-src.uncondensed/skills`
- * literal; this faithful twin replicates it byte-for-byte. When the
- * directory is absent the .py raises an uncaught FileNotFoundError
- * (iterdir on a missing dir) → exit 1, empty stdout; this twin mirrors
- * that by throwing, so the dispatcher / Node surfaces a non-zero exit.
+ * NOTE: scans `src/skills` — the canonical source-of-truth skill library.
+ * (The pre-py2ts .py read the now-removed legacy condensed-source skills
+ * corpus; repointed here so the scanner runs on the live tree.) When
+ * the directory is absent the scanner throws (iterdir on a missing dir) →
+ * non-zero exit, empty stdout.
  */
 
 import * as fs from 'node:fs';
@@ -35,7 +35,7 @@ import { parse as parseYaml } from 'yaml';
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/measure_skill_reduction.ts → parents[2] is the repo root.
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const SKILLS_DIR = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
+const SKILLS_DIR = path.join(REPO_ROOT, 'src', 'skills');
 const TARGET_REDUCTION = 0.4;
 const PHASE_3_USER_TYPES = ['consultant', 'creator'] as const;
 

package/src/scripts/migration_status.ts

@@ -2,7 +2,7 @@
 /**
  * migration_status.ts — Python→TypeScript migration dashboard.
  *
- * Phase 1 Step 13 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+ * Phase 1 Step 13 of `agents/roadmaps/archive/road-to-typescript-only-scripts.md`.
  *
  * Counts the remaining tracked `.py` files (via `git ls-files '*.py'`),
  * buckets them into the roadmap's migration categories, compares each
@@ -100,6 +100,10 @@ const EXCLUDED_PREFIXES: readonly string[] = [
     '.claude/',
     '.augment/',
     'internal/bench/',
+    // Eval fixtures simulate CONSUMER project files (a python DB model the
+    // structure-grounding eval reads as foreign source) — carve-out, not
+    // package source. Same class as the internal/bench/ trap fixtures.
+    'internal/evals/',
     'tmp/',
     '.tmp/',
 ];
@@ -225,7 +229,7 @@ function renderDashboard(
     lines.push('');
     lines.push(
         'Tracks remaining tracked `.py` files per roadmap phase of ' +
-            '`agents/roadmaps/road-to-typescript-only-scripts.md`. ' +
+            '`agents/roadmaps/archive/road-to-typescript-only-scripts.md`. ' +
             'Baseline = Phase 1 snapshot (hardcoded in the script).',
     );
     lines.push('');