@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/check_no_local_settings_committed.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env tsx
+/**
+ * Fail if any `.agent-settings.local.yml` is tracked by git.
+ *
+ * TypeScript twin of `src/scripts/check_no_local_settings_committed.py`
+ * (ADR-200, Phase 4 / Wave 4c). Mirrors the Python CLI contract EXACTLY —
+ * no flags, exit codes (0 clean, 1 offenders), stdout, byte-identical
+ * finding messages, same `git ls-files` scan and basename match. No
+ * behaviour changes.
+ *
+ * `.agent-settings.local.yml` is the per-developer, per-machine override
+ * layer (see `scripts/_lib/agent_settings.py` `LOCAL_PROJECT_FILE`). It is
+ * gitignored on purpose — committing one would leak one developer's local
+ * machine paths (e.g. linked-project siblings) into everyone's checkout.
+ *
+ * Exit 0 when none are tracked, 1 (with the offending paths) otherwise.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const LOCAL_FILE = '.agent-settings.local.yml';
+
+function tracked_local_settings(): string[] {
+    const res = spawnSync('git', ['ls-files'], { encoding: 'utf-8' });
+    // Mirror Python: CalledProcessError (non-zero) or FileNotFoundError
+    // (git missing) → return [] (nothing to enforce).
+    if (res.error !== undefined || res.status !== 0 || typeof res.stdout !== 'string') {
+        return [];
+    }
+    const out = res.stdout;
+    return out
+        .split('\n')
+        .filter((line) => line !== '')
+        .filter((line) => {
+            const parts = line.split('/');
+            return parts[parts.length - 1] === LOCAL_FILE;
+        });
+}
+
+function main(): number {
+    const offenders = tracked_local_settings();
+    if (offenders.length === 0) {
+        process.stdout.write(`✅  No tracked ${LOCAL_FILE} files.\n`);
+        return 0;
+    }
+    process.stdout.write(
+        `❌  ${LOCAL_FILE} must never be committed (per-machine local layer):\n`,
+    );
+    for (const p of offenders) {
+        process.stdout.write(`  🔴 ${p}\n`);
+    }
+    process.stdout.write(
+        `\nRun: git rm --cached <path>  — and confirm ${LOCAL_FILE} is gitignored.\n`,
+    );
+    return 1;
+}
+
+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 { LOCAL_FILE, tracked_local_settings, main };

package/src/scripts/check_no_new_legacy_path.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+/**
+ * Regression guard: no NEW `.agent-src.uncondensed/` references in `src/`.
+ *
+ * TypeScript twin of `src/scripts/check_no_new_legacy_path.py` (ADR-200,
+ * Phase 4 / Wave 4c). The CLI contract is mirrored EXACTLY — `--base`
+ * / `--stdin` flags, exit codes (0 no new references, 1 a new reference,
+ * 2 internal error), stdout split, byte-identical finding messages,
+ * same diff parsing, same EXEMPT set, and the same faithful-twin rule.
+ * No behaviour changes — latent bugs replicated.
+ *
+ * NOTE (faithful-twin rule): this guard's `.py` original is in its own
+ * EXEMPT set and legitimately contains the literal `.agent-src.uncondensed`
+ * as data. This `.ts` twin contains it too — and the faithful-twin rule
+ * (matching the bare directory name against the same-stem `.py` sibling)
+ * auto-exempts it, so the guard does not flag its own port.
+ *
+ * `.agent-src.uncondensed/` is the dead pre-relocation source path (the source
+ * of truth moved to `src/`, ADR-051). Existing stale prose mentions in `src/`
+ * are fixed opportunistically; this guard stops the debt from growing: it
+ * fails when a diff ADDS a new `.agent-src.uncondensed/` line under `src/`.
+ *
+ * Files that legitimately contain the literal forever are exempt:
+ *   - src/scripts/_lib/agent_src.py        (the LEGACY_SRC constant)
+ *   - src/scripts/check_references.py       (forbidden-substring detector)
+ *   - src/scripts/check_condensed_paths.py  (forbidden-substring detector)
+ *
+ * Faithful-twin rule (Python→TypeScript migration): a `*.ts` file is also
+ * exempt when a same-stem `*.py` sibling exists AND already contains the
+ * literal. A TS twin that faithfully mirrors a pre-existing legacy reference
+ * (e.g. agent_src.ts, install_regenerator.ts) is not a NEW dead-path — the
+ * reference already lived in the ported `.py`. This cannot mask a genuinely
+ * new dead-path: a fresh one introduced only in a `.ts` has no `.py` sibling
+ * already carrying it.
+ *
+ * Diff-based: compares added lines against a base ref (default `origin/main`).
+ * On a clean checkout with no diff, it is a no-op (exit 0).
+ *
+ * Usage:  tsx src/scripts/check_no_new_legacy_path.ts [--base <ref>]
+ * Exit:   0 = no new references, 1 = a new reference was added, 2 = internal error.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const LEGACY = '.agent-src.uncondensed/';
+const EXEMPT: ReadonlySet<string> = new Set([
+    'src/scripts/_lib/agent_src.py',
+    'src/scripts/check_references.py',
+    'src/scripts/check_condensed_paths.py',
+    'src/scripts/check_no_new_legacy_path.py', // this file documents the literal
+]);
+
+type TwinCheck = (curFile: string) => boolean;
+
+/**
+ * True when `curFile` is a `*.ts` whose same-stem `*.py` sibling exists and
+ * already references the legacy tree — a faithful TS port of a pre-existing
+ * legacy reference, not a new dead-path. The sibling check matches the bare
+ * directory name (`.agent-src.uncondensed`, no trailing slash) because the
+ * `.py` may reference it as a path SEGMENT (`root / ".agent-src.uncondensed"`)
+ * while the `.ts` twin / its comments use the slash form — both are the same
+ * faithful reference. Reads from disk relative to cwd (CI runs the guard at
+ * the repo root); injectable in tests via the `twinCheck` param of
+ * `find_offenders`.
+ */
+function _is_faithful_twin(curFile: string): boolean {
+    if (!curFile.endsWith('.ts')) {
+        return false;
+    }
+    const sibling = curFile.slice(0, -3) + '.py';
+    try {
+        const content = fs.readFileSync(sibling, 'utf-8');
+        return content.includes(LEGACY.replace(/\/+$/, ''));
+    } catch {
+        return false;
+    }
+}
+
+function _base(): string {
+    const argv = process.argv;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--base' && i + 1 < argv.length) {
+            return argv[i + 1]!;
+        }
+    }
+    return 'origin/main';
+}
+
+/**
+ * Added (`+`) lines under a non-exempt src/ file that introduce the legacy
+ * path. Pure over the diff string except for the faithful-twin sibling check
+ * (`twinCheck`, injectable for unit tests).
+ */
+function find_offenders(diffText: string, twinCheck: TwinCheck = _is_faithful_twin): string[] {
+    let curFile: string | null = null;
+    const offenders: string[] = [];
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('+++ b/')) {
+            curFile = line.slice(6);
+            continue;
+        }
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            // src/-scoped: a full diff (e.g. `gh pr diff`) carries every path;
+            // only added lines under src/ (minus the exempt detectors and
+            // faithful TS twins) count.
+            if (
+                curFile &&
+                curFile.startsWith('src/') &&
+                !EXEMPT.has(curFile) &&
+                line.includes(LEGACY) &&
+                !twinCheck(curFile)
+            ) {
+                offenders.push(`${curFile}: ${line.slice(1).trim().slice(0, 100)}`);
+            }
+        }
+    }
+    return offenders;
+}
+
+function main(): number {
+    // --stdin: read a unified diff from stdin (CI pipes `gh pr diff` — auth-safe,
+    // no `git fetch <base>` extraheader race on shallow PR-merge checkouts, the
+    // documented failure the kernel-bundle step sidesteps the same way).
+    let offenders: string[];
+    if (process.argv.includes('--stdin')) {
+        const stdin = fs.readFileSync(0, 'utf-8') as string;
+        offenders = find_offenders(stdin);
+    } else {
+        const base = _base();
+        // Two-dot diff: working tree vs base — catches committed + uncommitted
+        // additions (robust locally and where the working tree is the branch tip).
+        let proc: ReturnType<typeof spawnSync>;
+        try {
+            proc = spawnSync('git', ['diff', base, '--', 'src/'], {
+                encoding: 'utf-8',
+            });
+        } catch (exc) {
+            const msg = exc instanceof Error ? exc.message : String(exc);
+            process.stdout.write(`❌  check_no_new_legacy_path: git diff failed: ${msg}\n`);
+            return 2;
+        }
+        if (proc.error) {
+            process.stdout.write(
+                `❌  check_no_new_legacy_path: git diff failed: ${proc.error.message}\n`,
+            );
+            return 2;
+        }
+        const code = proc.status;
+        if (code !== 0 && code !== 1) {
+            // base ref missing (shallow clone / detached) — degrade to no-op.
+            process.stdout.write(
+                `⚠️  check_no_new_legacy_path: base '${base}' unavailable; skipping (no-op).\n`,
+            );
+            return 0;
+        }
+        offenders = find_offenders((proc.stdout as string | null) ?? '');
+    }
+
+    if (offenders.length) {
+        process.stdout.write(
+            '❌  New `.agent-src.uncondensed/` reference(s) added under src/ ' +
+                '(the source of truth is `src/` — ADR-051):\n',
+        );
+        for (const o of offenders) {
+            process.stdout.write(`  🔴 ${o}\n`);
+        }
+        process.stdout.write(
+            '\nFix: reference the real `src/` target. Existing stale prose is ' +
+                'migrated opportunistically; do not ADD new dead-path references.\n',
+        );
+        return 1;
+    }
+
+    process.stdout.write('✅  No new `.agent-src.uncondensed/` references added under src/.\n');
+    return 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+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 { LEGACY, EXEMPT, _is_faithful_twin, find_offenders, main };

package/src/scripts/check_no_roadmap_refs.ts

@@ -0,0 +1,304 @@
+#!/usr/bin/env tsx
+/**
+ * No-roadmap-references checker.
+ *
+ * TypeScript twin of `src/scripts/check_no_roadmap_refs.py` (ADR-200,
+ * Phase 4 / Wave 4a). The CLI contract is mirrored EXACTLY — `--format`
+ * / `--root` flags, exit codes (0 clean, 1 violations, 3 internal error),
+ * stdout/stderr split, byte-identical finding messages, same scan trees
+ * and order, same fenced-code-block skipping, same self-documenting
+ * allowlist. No behaviour changes — latent bugs replicated.
+ *
+ * Stable artifacts (rules, skills, commands, contexts, guidelines, AGENTS.md,
+ * README, copilot-instructions) must NOT cite a specific roadmap file in
+ * `agents/roadmaps/`. Roadmap files are transient — archived, skipped, or
+ * deleted as work completes — and stable artifacts citing them rot.
+ *
+ * Allowed: directory mentions (`agents/roadmaps/`, `agents/roadmaps/archive/`,
+ * `agents/roadmaps/skipped/`). Forbidden: specific `*.md` files inside those
+ * directories.
+ *
+ * Contract: .agent-src.uncondensed/rules/no-roadmap-references.md
+ *
+ * Exit codes: 0 = clean, 1 = violations, 3 = internal error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// src/scripts/check_no_roadmap_refs.ts → three dirs up is the repo root.
+// Mirrors the Python `Path(__file__).resolve().parent.parent.parent`.
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+// Stable artefact trees — every `*.md` below MUST be free of roadmap-file
+// citations. Directory mentions stay allowed (the regex below excludes them).
+const STABLE_TREES = [
+    '.agent-src.uncondensed/rules',
+    '.agent-src.uncondensed/skills',
+    '.agent-src.uncondensed/commands',
+    '.agent-src.uncondensed/contexts',
+    '.agent-src.uncondensed/templates',
+    '.agent-src.uncondensed/personas',
+    'agents/settings/contexts',
+    'docs/guidelines',
+    'docs/contracts',
+] as const;
+
+// Stable single-file artefacts at well-known paths.
+const STABLE_FILES = [
+    'AGENTS.md',
+    'README.md',
+    'copilot-instructions.md',
+    'docs/architecture.md',
+    'docs/customization.md',
+    'docs/getting-started.md',
+    'docs/catalog.md',
+] as const;
+
+// Roadmap-file pattern: any `*.md` file under `agents/roadmaps/` at any
+// depth (including `archive/`, `skipped/`, and nested topical subfolders
+// like `agent-memory/`). Directory-only mentions (`agents/roadmaps/`
+// with trailing slash, no filename) and placeholder mentions like
+// `agents/roadmaps/<file>.md` (angle-bracket placeholder) do NOT match.
+const ROADMAP_FILE_RE =
+    /agents\/roadmaps\/(?:[a-z0-9][a-z0-9_-]*\/)*[a-z0-9][a-z0-9_-]*\.md/gi;
+
+// Files that may legitimately quote forbidden patterns inside backticks for
+// documentation purposes — the rule itself, the companion CI script docs,
+// and the contract doc that names the rule.
+const SELF_DOCUMENTING_ALLOWLIST: ReadonlySet<string> = new Set([
+    '.agent-src.uncondensed/rules/no-roadmap-references.md',
+    'docs/guidelines/agent-infra/no-roadmap-references.md',
+]);
+
+interface Violation {
+    file: string;
+    line: number;
+    match: string;
+}
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** POSIX relative path of `target` under `root` (str(Path.relative_to)). */
+function _relTo(target: string, root: string): string {
+    return path.relative(root, target).split(path.sep).join('/');
+}
+
+/** Recursively list `*.md` files under `dir`, sorted (mirrors sorted(rglob)). */
+function _rglobMdSorted(dir: string): string[] {
+    const out: string[] = [];
+    const walk = (current: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            } else if (entry.isFile() && entry.name.endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+
+function _scan_file(p: string, root: string): Violation[] {
+    const rel = _relTo(p, root);
+    if (SELF_DOCUMENTING_ALLOWLIST.has(rel)) {
+        return [];
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: Violation[] = [];
+    let inFence = false;
+    const lines = text.split('\n');
+    for (let idx = 0; idx < lines.length; idx++) {
+        const n = idx + 1;
+        const line = lines[idx]!;
+        // Skip fenced code blocks — path listings inside ``` are functional
+        // constants (command contracts, runtime checks), not link rot.
+        const stripped = line.replace(/^\s+/, '');
+        if (stripped.startsWith('```')) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) {
+            continue;
+        }
+        ROADMAP_FILE_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = ROADMAP_FILE_RE.exec(line)) !== null) {
+            out.push({ file: rel, line: n, match: m[0] });
+        }
+    }
+    return out;
+}
+
+function _collect_targets(root: string): string[] {
+    const targets: string[] = [];
+    for (const d of STABLE_TREES) {
+        const base = path.join(root, d);
+        if (!_exists(base)) {
+            continue;
+        }
+        targets.push(..._rglobMdSorted(base));
+    }
+    for (const f of STABLE_FILES) {
+        const p = path.join(root, f);
+        if (_exists(p)) {
+            targets.push(p);
+        }
+    }
+    return targets;
+}
+
+function scan(root: string): Violation[] {
+    const out: Violation[] = [];
+    for (const p of _collect_targets(root)) {
+        out.push(..._scan_file(p, root));
+    }
+    return out;
+}
+
+function format_text(violations: Violation[]): string {
+    if (violations.length === 0) {
+        return '✅  No roadmap-file references in stable artifacts.';
+    }
+    const lines: string[] = [
+        `❌  Found ${violations.length} roadmap reference(s) in stable artifacts:\n`,
+    ];
+    for (const v of violations) {
+        lines.push(`  🔴 ${v.file}:${v.line}  →  ${v.match}`);
+    }
+    lines.push(
+        '\nPromote the durable conclusion to agents/settings/contexts/ and cite that ' +
+            'instead. See .agent-src.uncondensed/rules/no-roadmap-references.md.',
+    );
+    return lines.join('\n');
+}
+
+/** Mirror Python `json.dumps(obj, indent=2)` with `ensure_ascii=True`. */
+function _json_dumps_ascii(obj: unknown): string {
+    const raw = JSON.stringify(obj, null, 2);
+    let out = '';
+    for (const ch of raw) {
+        const code = ch.codePointAt(0)!;
+        if (code < 0x80) {
+            out += ch;
+        } else {
+            for (let k = 0; k < ch.length; k++) {
+                out += '\\u' + ch.charCodeAt(k).toString(16).padStart(4, '0');
+            }
+        }
+    }
+    return out;
+}
+
+interface ParsedArgs {
+    format: 'text' | 'json';
+    root: string;
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    let format: 'text' | 'json' = 'text';
+    let root = ROOT;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!;
+        if (arg === '--format') {
+            const v = argv[++i];
+            if (v === undefined) {
+                _argparse_error('argument --format: expected one argument');
+            }
+            if (v !== 'text' && v !== 'json') {
+                _argparse_error(
+                    `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                );
+            }
+            format = v;
+        } else if (arg.startsWith('--format=')) {
+            const v = arg.slice('--format='.length);
+            if (v !== 'text' && v !== 'json') {
+                _argparse_error(
+                    `argument --format: invalid choice: '${v}' (choose from 'text', 'json')`,
+                );
+            }
+            format = v;
+        } else if (arg === '--root') {
+            const v = argv[++i];
+            if (v === undefined) {
+                _argparse_error('argument --root: expected one argument');
+            }
+            root = v;
+        } else if (arg.startsWith('--root=')) {
+            root = arg.slice('--root='.length);
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: check_no_roadmap_refs [-h] [--format {text,json}] [--root ROOT]\n',
+            );
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return { format, root };
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`check_no_roadmap_refs: error: ${message}\n`);
+    process.exit(2);
+}
+
+function main(): number {
+    const args = parse_args(process.argv.slice(2));
+    let violations: Violation[];
+    try {
+        violations = scan(args.root);
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`Internal error: ${msg}\n`);
+        return 3;
+    }
+    if (args.format === 'json') {
+        process.stdout.write(_json_dumps_ascii(violations) + '\n');
+    } else {
+        process.stdout.write(format_text(violations) + '\n');
+    }
+    return violations.length ? 1 : 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 {
+    type Violation,
+    ROOT,
+    STABLE_TREES,
+    STABLE_FILES,
+    ROADMAP_FILE_RE,
+    SELF_DOCUMENTING_ALLOWLIST,
+    scan,
+    format_text,
+    main,
+};