@event4u/agent-config 7.5.0 → 8.0.0

package/src/scripts/lint_knowledge_scale.ts

@@ -0,0 +1,250 @@
+#!/usr/bin/env tsx
+/**
+ * Warn-only scale + budget tripwires for the memory/knowledge substrate —
+ * road-to-second-brain Phase 0 (council 2026-07-07, see
+ * `agents/settings/contexts/second-brain-delta-verdict.md`).
+ *
+ * These tripwires REPLACE roadmap gates: each warning names its pre-decided
+ * activation path, so a firing tripwire is actionable without re-opening the
+ * decision. The script never fails the build.
+ *
+ * Tripwires:
+ *   - intake scale     — `agents/knowledge/intake/events-*.jsonl` > 2000 events
+ *                        → wire `fold_intake.ts` into post-session/CI
+ *   - sessions scale   — `agents/knowledge/sessions/` > 50 pages
+ *                        → design fold-through-consolidate-gate for tracked pages
+ *   - type scale       — any single memory/knowledge type > 200 files
+ *                        → build the pre-decided file-first in-memory BM25 CLI
+ *   - corpus scale     — > 500 files across all types
+ *                        → same BM25 activation path
+ *   - hot-context size — `agents/runtime/state/hot-context.md` > 600 tokens
+ *                        (estimated at 4 chars/token) → trim schema / fix the
+ *                        deterministic writer
+ *
+ * Usage: lint_knowledge_scale.ts [--dir <repo-root>] [--format text|json] [--quiet]
+ * Exit codes: 0 = ran cleanly (warnings never fail the build), 1 = usage
+ * error, 3 = internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const PROG = 'lint_knowledge_scale.ts';
+
+export const INTAKE_EVENTS_MAX = 2000;
+export const SESSIONS_PAGES_MAX = 50;
+export const TYPE_FILES_MAX = 200;
+export const CORPUS_FILES_MAX = 500;
+export const HOT_CONTEXT_TOKENS_MAX = 600;
+export const CHARS_PER_TOKEN = 4;
+
+const KNOWLEDGE_TYPED_DIRS = ['sessions', 'concepts', 'procedures', 'decisions'] as const;
+
+export interface Warning {
+    rule: string;
+    metric: string; // "<observed>/<threshold>"
+    message: string; // includes the pre-decided activation path
+}
+
+function listFiles(dir: string, exts: readonly string[]): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && exts.some((x) => e.name.endsWith(x)))
+        .map((e) => path.join(dir, e.name));
+}
+
+function countJsonlLines(file: string): number {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return 0;
+    }
+    return text.split('\n').filter((l) => l.trim().length > 0).length;
+}
+
+/** Collect per-type file counts across the knowledge + memory substrate. */
+export function collectTypeCounts(root: string): Map<string, number> {
+    const counts = new Map<string, number>();
+
+    // Knowledge cards (flat, top-level *.md except README/INDEX).
+    const cardsDir = path.join(root, 'agents', 'knowledge');
+    const cards = listFiles(cardsDir, ['.md']).filter((f) => {
+        const base = path.basename(f).toLowerCase();
+        return base !== 'readme.md' && base !== 'index.md';
+    });
+    counts.set('knowledge/cards', cards.length);
+
+    // Lifecycle-typed knowledge dirs.
+    for (const d of KNOWLEDGE_TYPED_DIRS) {
+        counts.set(`knowledge/${d}`, listFiles(path.join(cardsDir, d), ['.md']).length);
+    }
+
+    // Curated memory types: agents/memory/<type>/ dirs and <type>.yml files.
+    // The gitignored per-task scratch (`agents/memory/knowledge/`) is excluded —
+    // it is session state, not a curated type.
+    const memoryDir = path.join(root, 'agents', 'memory');
+    let memEntries: fs.Dirent[] = [];
+    try {
+        memEntries = fs.readdirSync(memoryDir, { withFileTypes: true });
+    } catch {
+        // no memory dir — fine
+    }
+    for (const e of memEntries) {
+        if (e.isDirectory()) {
+            if (e.name === 'knowledge' || e.name === 'intake' || e.name === 'archive') continue;
+            const n = listFiles(path.join(memoryDir, e.name), ['.md', '.yml', '.yaml']).length;
+            counts.set(`memory/${e.name}`, n);
+        } else if (e.isFile() && (e.name.endsWith('.yml') || e.name.endsWith('.yaml'))) {
+            counts.set(`memory/${e.name}`, 1);
+        }
+    }
+    return counts;
+}
+
+export function runChecks(root: string): Warning[] {
+    const warnings: Warning[] = [];
+
+    // 1. Intake scale.
+    const intakeDir = path.join(root, 'agents', 'knowledge', 'intake');
+    const intakeFiles = listFiles(intakeDir, ['.jsonl']).filter((f) =>
+        path.basename(f).startsWith('events-'),
+    );
+    const intakeEvents = intakeFiles.reduce((acc, f) => acc + countJsonlLines(f), 0);
+    if (intakeEvents > INTAKE_EVENTS_MAX) {
+        warnings.push({
+            rule: 'intake-scale',
+            metric: `${intakeEvents}/${INTAKE_EVENTS_MAX}`,
+            message:
+                `intake holds ${intakeEvents} events (> ${INTAKE_EVENTS_MAX}). ` +
+                'Activation path (pre-decided): wire `src/scripts/fold_intake.ts` into the post-session/CI cadence.',
+        });
+    }
+
+    // 2. Sessions scale.
+    const sessionsDir = path.join(root, 'agents', 'knowledge', 'sessions');
+    const sessionPages = listFiles(sessionsDir, ['.md']).length;
+    if (sessionPages > SESSIONS_PAGES_MAX) {
+        warnings.push({
+            rule: 'sessions-scale',
+            metric: `${sessionPages}/${SESSIONS_PAGES_MAX}`,
+            message:
+                `agents/knowledge/sessions/ holds ${sessionPages} pages (> ${SESSIONS_PAGES_MAX}). ` +
+                'Activation path (pre-decided): design fold-through-consolidate-gate for tracked pages — never fold tracked files without the gate.',
+        });
+    }
+
+    // 3 + 4. Type + corpus scale.
+    const typeCounts = collectTypeCounts(root);
+    let total = 0;
+    for (const [type, n] of typeCounts) {
+        total += n;
+        if (n > TYPE_FILES_MAX) {
+            warnings.push({
+                rule: 'type-scale',
+                metric: `${n}/${TYPE_FILES_MAX}`,
+                message:
+                    `type '${type}' holds ${n} files (> ${TYPE_FILES_MAX}). ` +
+                    'Activation path (pre-decided): build the file-first in-memory BM25 CLI (re-index at session start, no vectors, no service).',
+            });
+        }
+    }
+    if (total > CORPUS_FILES_MAX) {
+        warnings.push({
+            rule: 'corpus-scale',
+            metric: `${total}/${CORPUS_FILES_MAX}`,
+            message:
+                `memory/knowledge corpus holds ${total} files (> ${CORPUS_FILES_MAX}). ` +
+                'Activation path (pre-decided): build the file-first in-memory BM25 CLI (re-index at session start, no vectors, no service).',
+        });
+    }
+
+    // 5. Hot-context budget.
+    const hotContext = path.join(root, 'agents', 'runtime', 'state', 'hot-context.md');
+    let hotText = '';
+    try {
+        hotText = fs.readFileSync(hotContext, 'utf-8');
+    } catch {
+        // absent — fine (feature not active or fresh session)
+    }
+    if (hotText) {
+        const tokens = Math.ceil(hotText.length / CHARS_PER_TOKEN);
+        if (tokens > HOT_CONTEXT_TOKENS_MAX) {
+            warnings.push({
+                rule: 'hot-context-budget',
+                metric: `${tokens}/${HOT_CONTEXT_TOKENS_MAX}`,
+                message:
+                    `hot-context.md parses to ~${tokens} tokens (> ${HOT_CONTEXT_TOKENS_MAX}). ` +
+                    'Activation path (pre-decided): trim the schema sections or fix the deterministic writer cap.',
+            });
+        }
+    }
+
+    return warnings;
+}
+
+function main(argv: string[]): number {
+    let dir = '.';
+    let format = 'text';
+    let quiet = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--dir') {
+            dir = argv[++i] ?? '';
+            if (!dir) {
+                process.stderr.write(`${PROG}: error: --dir requires a value\n`);
+                return 1;
+            }
+        } else if (a === '--format') {
+            format = argv[++i] ?? '';
+            if (format !== 'text' && format !== 'json') {
+                process.stderr.write(`${PROG}: error: --format must be text|json\n`);
+                return 1;
+            }
+        } else if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                `usage: ${PROG} [--dir <repo-root>] [--format text|json] [--quiet]\n`,
+            );
+            return 0;
+        } else {
+            process.stderr.write(`${PROG}: error: unknown argument ${a}\n`);
+            return 1;
+        }
+    }
+
+    let warnings: Warning[];
+    try {
+        warnings = runChecks(path.resolve(dir));
+    } catch (exc) {
+        process.stderr.write(`${PROG}: internal error: ${String(exc)}\n`);
+        return 3;
+    }
+
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify({ warnings }, null, 2) + '\n');
+    } else if (warnings.length === 0) {
+        if (!quiet) {
+            process.stdout.write(`${PROG}: all scale tripwires silent (warn-only)\n`);
+        }
+    } else {
+        for (const w of warnings) {
+            process.stdout.write(`⚠️  [${w.rule}] ${w.metric} — ${w.message}\n`);
+        }
+        process.stdout.write(
+            `${PROG}: ${warnings.length} tripwire(s) fired — warn-only, build not failed\n`,
+        );
+    }
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/lint_legal_pack.ts

@@ -74,6 +74,62 @@ export function legalPromotionViolations(packsYml: string, legalNotice: string):
     return [];
 }
 
+// D7 — reference-resolution gate for the floor rule itself. The
+// `legal-safety-floor` rule is authored in `src/rules/` but SHIPS/PROJECTS to
+// `dist/agent-src/rules/`; its relative links must resolve from that SHIPPED
+// projection root (7.5.0 shipped a `LEGAL_NOTICE.md` path that only resolved
+// from the projection — correct by design, but nothing asserted it, so a wrong
+// depth could silently regress). `check_references` does not catch this: it
+// only scans `dist/agent-src/` + `agents/` (never `src/`), and its PATH_PATTERN
+// matches only directory-rooted paths (`skills/…`, `docs/…`), so a bare
+// `../../../LEGAL_NOTICE.md` filename link is invisible to it. This gate is the
+// complementary backstop — every markdown link target in the floor rule must
+// resolve from the projected `dist/agent-src/rules/` location.
+const PROJECTED_FLOOR_DIR = path.join(REPO, 'dist', 'agent-src', 'rules');
+// Markdown inline link: [text](target). Captures the target.
+const MD_LINK_RE = /\[[^\]]*\]\(([^)]+)\)/g;
+
+/**
+ * Pure reference-resolution check for the floor rule. `ruleText` is the floor
+ * rule body (read from `src/rules/legal-safety-floor.md`); every relative
+ * markdown link target it contains MUST resolve from `projectedDir` (the
+ * shipped `dist/agent-src/rules/` location). External (http/anchor/mailto) and
+ * absolute targets are skipped. Returns a Violation per unresolvable link.
+ */
+export function legalFloorReferenceViolations(
+    ruleText: string,
+    projectedDir: string,
+    floorRel: string,
+): Violation[] {
+    const out: Violation[] = [];
+    const seen = new Set<string>();
+    MD_LINK_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = MD_LINK_RE.exec(ruleText)) !== null) {
+        let target = (m[1] ?? '').trim();
+        // Strip a fragment/anchor and any title (`path "Title"`).
+        const titleSplit = target.match(/^(\S+)\s+["'(]/);
+        if (titleSplit) target = titleSplit[1] ?? target;
+        const hashIdx = target.indexOf('#');
+        if (hashIdx >= 0) target = target.slice(0, hashIdx);
+        if (!target) continue;
+        // Skip non-path targets: external URLs, mailto, in-page anchors,
+        // absolute paths (resolution root is the projection, not the FS root).
+        if (/^([a-z][a-z0-9+.-]*:|#|\/)/i.test(target)) continue;
+        if (seen.has(target)) continue;
+        seen.add(target);
+        const resolved = path.resolve(projectedDir, target);
+        if (!fs.existsSync(resolved)) {
+            out.push({
+                file: floorRel,
+                rule: 'floor-reference',
+                msg: `link target "${target}" does not resolve from the shipped projection (dist/agent-src/rules/) — fix the relative depth so it resolves from the projected rule location`,
+            });
+        }
+    }
+    return out;
+}
+
 // D4 — definitive-legal-language blocklist (the floor bans these; this is the
 // deterministic backstop over skill bodies). Narrow on purpose; the floor's
 // prompt layer is the primary enforcement.
@@ -175,6 +231,17 @@ export function lintLegalPack(skillsDir: string = SKILLS_DIR): Violation[] {
         if (fs.existsSync(PACKS_YML) && fs.existsSync(PACK_NOTICE)) {
             violations.push(...legalPromotionViolations(_readText(PACKS_YML), _readText(PACK_NOTICE)));
         }
+        // D7 — floor-rule reference gate: every link in the floor rule must
+        // resolve from its SHIPPED projection (dist/agent-src/rules/).
+        if (fs.existsSync(PROJECTED_FLOOR_DIR)) {
+            violations.push(
+                ...legalFloorReferenceViolations(
+                    _readText(FLOOR_RULE),
+                    PROJECTED_FLOOR_DIR,
+                    path.relative(REPO, FLOOR_RULE),
+                ),
+            );
+        }
     }
     return violations;
 }

package/src/scripts/lint_persona_governance.ts

@@ -26,10 +26,13 @@ const QUIET = process.argv.includes('--quiet');
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const PERSONA_DIR = path.join(REPO, '.agent-src.uncondensed', 'personas');
+// Source of truth is `src/` (ADR-051); the old condensed-legacy source tree is
+// empty post-py2ts, so the previous path silently scanned zero personas and the
+// governance gate was inert. Scan the real source tree.
+const PERSONA_DIR = path.join(REPO, 'src', 'agent-src', 'personas');
 const SKILL_ROOTS: readonly string[] = [
-    path.join(REPO, '.agent-src.uncondensed', 'skills'),
-    path.join(REPO, '.claude', 'skills'),
+    path.join(REPO, 'src', 'skills'),
+    path.join(REPO, 'src', 'rules'),
 ];
 
 // Per-domain cap — mirrors persona-governance.md § Per-domain cap.
@@ -38,6 +41,8 @@ const DOMAIN_MAP: Record<string, string> = {
     'ai-video-technical-director': 'ai-video',
     'backend-architect': 'backend',
     'eloquent-tamer': 'backend',
+    'performance-engineer': 'performance',
+    'data-integrity': 'data',
     cmo: 'gtm',
     revops: 'gtm',
     'growth-pm': 'growth',

package/src/scripts/lint_regression.ts

@@ -114,6 +114,21 @@ function run_linter_json(ref: string | null, repo_root: string): LinterJson {
                 return { results: [], summary: {} };
             }
             const baselineArgs = ['--all', '--format', 'json', '--repo-root', tmpdir];
+            // Local python-skip guard (teardown D2): a historical `.py` baseline
+            // genuinely needs python3; when the runtime is absent, degrade to an
+            // empty baseline (same contract as a missing linter) instead of a
+            // spawn error — decouples the python-free-env shim retirement from
+            // porting pre-migration baselines to a frozen TS golden.
+            if (
+                baseline_linter.endsWith('.py') &&
+                spawnSync('python3', ['--version'], { encoding: 'utf8' }).status !== 0
+            ) {
+                process.stderr.write(
+                    `Warning: baseline '${ref}' is pre-migration (.py) and python3 is ` +
+                        `unavailable — baseline treated as empty.\n`,
+                );
+                return { results: [], summary: {} };
+            }
             const result = baseline_linter.endsWith('.ts')
                 ? (() => {
                       const inv = _resolve_tsx_invocation(baseline_linter, baselineArgs);

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 };