@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/check_backstop_debt.ts

@@ -7,18 +7,27 @@
  * and had been, invisibly, because no workflow ran them. A rule declared a
  * backstop; the backstop existed; the backstop was red; nothing said so.
  *
- * Those failures are pre-existing debt, not regressions from the wiring change,
- * and fixing eleven framework-leakage spots plus eighteen source-confidentiality
- * hits is a different piece of work with a different reviewer. Folding them in
- * would make one PR unreviewable and would mix "make the gate run" with "clean up
- * what the gate found".
- *
  * So the established pattern applies — the one the decision-homing work already
  * uses and the council endorsed: **baseline the legacy, enforce the boundary.**
  * Each gate's current finding count is committed. The count may fall freely; it
  * may not rise. New violations fail, existing debt is visible and counted, and
  * nothing is silently tolerated.
  *
+ * **The baseline is now 0 across all five gates.** The 37 findings were cleared
+ * in a follow-up pass, so this file no longer records debt — it holds the line at
+ * zero. Keeping the ratchet after the cleanup is the point: it is what stops the
+ * counts creeping back, and the mechanism is identical whether the baseline is 37
+ * or 0.
+ *
+ * Worth recording, because it changes how the next such number should be read:
+ * roughly two thirds of the 37 were never violations. `CREDITS.md` was flagged
+ * for the license-required attribution that `source-confidentiality` explicitly
+ * exempts. A checklist row naming five ecosystems on ONE line read as
+ * PHP-specific because only the PHP family carried a plain-language window hint.
+ * An archived acceptance criterion was flagged for the source names it quotes in
+ * order to assert their absence. Wiring a gate proves that it runs; it does not
+ * prove its findings are real. That takes reading them one at a time.
+ *
  * What this deliberately is NOT: a `continue-on-error` step. That is a WARN
  * wearing a gate's clothes, and removing exactly that confusion is why this
  * workflow exists.
@@ -112,12 +121,12 @@ function main(argv: string[]): number {
             JSON.stringify(
                 {
                     _doc:
-                        'Pre-existing findings in rule backstops that were red when they were first ' +
-                        'wired into CI — they had been failing invisibly because no workflow ran them. ' +
-                        'Counts may FALL freely; a rise fails the build. This is debt made visible, ' +
-                        'not debt tolerated: every number here is a rule whose declared backstop is ' +
-                        'currently not clean. Regenerate with --write-baseline only when the change ' +
-                        'is deliberate.',
+                        'Per-gate finding counts for the rule backstops wired into CI by ' +
+                        'rule-backstops.yml. Counts may FALL freely; a rise fails the build. These ' +
+                        'gates were red on arrival (37 findings) because no workflow had ever run ' +
+                        'them; that debt is now cleared and the baseline holds the line at 0. A ' +
+                        'non-zero number here is a rule whose declared backstop is not currently ' +
+                        'clean. Regenerate with --write-baseline only when the change is deliberate.',
                     gates: Object.fromEntries(measured.map((m) => [m.script, { rule: m.rule, findings: m.findings }])),
                     total: measured.reduce((a, m) => a + m.findings, 0),
                 },
@@ -172,7 +181,8 @@ function main(argv: string[]): number {
         process.stderr.write('❌  rule-backstop debt ratchet:\n');
         for (const r of regressions) process.stderr.write(`    · ${r}\n`);
         process.stderr.write(
-            '    These gates are already failing on pre-existing debt; the ratchet only forbids ADDING to it.\n',
+            '    The baseline is 0 — these gates are clean, so a rise is a NEW violation, not inherited debt.\n' +
+                '    Fix the finding, or re-baseline with --write-baseline if the change is deliberate.\n',
         );
         return 1;
     }

package/src/scripts/check_bundle_path_leakage.ts

@@ -0,0 +1,343 @@
+#!/usr/bin/env tsx
+/**
+ * Guard against build-machine path leakage in the tracked install bundle.
+ *
+ * road-to-feedback-9.2.0-followups Phase 4.1. Three 9.1 commits
+ * (f8752443b, 5933bf1a9, f30adb5a1) each rebuilt `dist/install/install.mjs`
+ * solely to strip a leaked build-environment path esbuild had baked into its
+ * per-module `// <path>` boundary comments: a worktree-relative `../../../
+ * node_modules/...` hop, a repo-relative `../agent-config/node_modules/...`
+ * hop, and a full `/Users/<name>/.../node_modules/...` absolute path. Each
+ * fix was a manual rebuild-and-diff after the fact; this guard makes the
+ * class fail the build instead, so a future leak cannot merge silently.
+ *
+ * Every pattern below is scoped to avoid flagging legitimate bundle content:
+ * the bundle's own emitted runtime strings use relative forms only (e.g.
+ * `"./node_modules/@event4u/agent-config/plugin/agent-config"`, a real
+ * consumer-facing plugin-manifest path), and esbuild's per-module registry
+ * keys are bare `node_modules/<pkg>/...` (no leading `/` or `../`) — neither
+ * shape trips any pattern here.
+ *
+ *   - `macos-linux-home`             — absolute `/Users/<name>/…` or
+ *     `/home/<name>/…`, i.e. a real machine's home directory. Requires at
+ *     least one path segment after the username so a bare `/Users/` or
+ *     `/home/` mention (unlikely, but not impossible in prose) does not
+ *     match on its own.
+ *   - `private-or-opt-root`          — an absolute `/private/…` (macOS's
+ *     `/var` → `/private/var` realpath) or `/opt/…` (common CI-runner tool
+ *     root, e.g. GitHub Actions' hostedtoolcache) path.
+ *   - `windows-drive`                — an absolute Windows path (`C:\…`).
+ *   - `worktree-path`                — a `.claude/worktrees/…` path. This
+ *     package's own git-worktree convention (`worktree-lifecycle` skill) —
+ *     it can never legitimately appear in a shipped consumer artifact.
+ *   - `parent-relative-node-modules`  — any `../`-escaping path that reaches
+ *     a `node_modules/` directory, however many hops or intermediate
+ *     segments (`../../../node_modules/…`, `../agent-config/node_modules/…`).
+ *     A legitimate bundled module reference never needs to climb out of the
+ *     repo root via string literals — node's own resolution algorithm
+ *     handles that internally, not via baked-in `../` path text.
+ *   - `absolute-node-modules`         — any OTHER absolute path (not already
+ *     caught by the three rules above) reaching a `node_modules/` directory.
+ *     The negative lookbehind excludes `./node_modules/…` and mid-identifier
+ *     slashes so a legitimate relative reference is never flagged.
+ *   - `absolute-sourcemap`           — a `sourceMappingURL=` comment pointing
+ *     at an absolute path instead of a bundle-relative filename (the shape
+ *     `.map` files should always use — see `dist/install/*.js.map`, whose
+ *     `sources` field is repo-relative, e.g. `../../src/install/atomic.ts`).
+ *
+ * Usage:
+ *     tsx src/scripts/check_bundle_path_leakage.ts
+ *     tsx src/scripts/check_bundle_path_leakage.ts --quiet
+ *     tsx src/scripts/check_bundle_path_leakage.ts <file> [<file> ...]
+ *
+ * Exit codes: 0 = clean, 1 = leak found, 2 = usage 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 _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+// Tracked directories that may hold a build-generated bundle. Only
+// `dist/install/` is force-included in `.gitignore` today (`!/dist/install/`);
+// `dist/hooks/` and `dist/mcp/` are listed defensively in case a future
+// change tracks them too — `git ls-files` on an untracked directory returns
+// nothing, so listing an as-yet-untracked root here is always safe.
+const BUNDLE_ROOTS: readonly string[] = ['dist/install', 'dist/hooks', 'dist/mcp'];
+
+interface LeakPattern {
+    readonly name: string;
+    readonly re: RegExp;
+    readonly hint: string;
+}
+
+// Every regex carries the `g` flag (all hits scanned, not just the first)
+// and excludes `\s'"` )` from its "rest of the path" class so a match never
+// swallows past the end of a quoted string / comment / parenthesized call.
+const LEAK_PATTERNS: readonly LeakPattern[] = [
+    {
+        name: 'macos-linux-home',
+        re: /\/(?:Users|home)\/[^/\s'"`)]+\/[^\s'"`)]*/g,
+        hint: 'rebuild from a clean, non-worktree checkout after a fresh `npm ci`',
+    },
+    {
+        name: 'private-or-opt-root',
+        re: /(?:^|[^\w.])\/(?:private|opt)\/[^\s'"`)]*/g,
+        hint: 'rebuild in a plain (non-macOS-symlinked, non-CI-tool-cache) tree',
+    },
+    {
+        name: 'windows-drive',
+        re: /\b[A-Za-z]:\\[^\s'"`)]*/g,
+        hint: 'rebuild on a POSIX runner — the published bundle must not carry a Windows path',
+    },
+    {
+        name: 'worktree-path',
+        re: /\.claude\/worktrees\/[^\s'"`)]*/g,
+        hint: 'rebuild from the primary checkout, not a `.claude/worktrees/` git worktree',
+    },
+    {
+        name: 'parent-relative-node-modules',
+        re: /\.\.\/(?:[^\s'"`)]*\/)*node_modules\//g,
+        hint: 'esbuild resolved a dependency outside the repo root (foreign/symlinked node_modules) — rebuild after `npm ci` inside the repo',
+    },
+    {
+        name: 'absolute-node-modules',
+        re: /(?<![.\w/])\/(?:[^\s'"`)]*\/)*node_modules\//g,
+        hint: 'an absolute path reached a node_modules directory — rebuild from a repo-relative tree',
+    },
+    {
+        name: 'absolute-sourcemap',
+        re: /sourceMappingURL=(?:\/|[A-Za-z]:\\)[^\s'"`)]*/g,
+        hint: 'the sourcemap comment must reference a bundle-relative filename, not an absolute path',
+    },
+];
+
+interface Hit {
+    readonly file: string;
+    readonly pattern: string;
+    readonly line: number;
+    readonly snippet: string;
+}
+
+const MAX_SNIPPET = 140;
+const MAX_HITS_SHOWN_PER_GROUP = 5;
+
+/**
+ * Redact the username segment of a `/Users/<name>/…`, `/home/<name>/…`, or
+ * `C:\Users\<name>\…` match before it reaches a log line — the machine
+ * username is incidental PII, not the point of the finding (the finding is
+ * "an absolute path leaked", not "whose machine it was").
+ */
+function mask_snippet(raw: string): string {
+    const masked = raw
+        .replace(/(\/(?:Users|home)\/)[^/\s'"`)]+/, '$1<masked>')
+        .replace(/(:\\Users\\)[^\\'"`)]+/i, '$1<masked>');
+    return masked.length > MAX_SNIPPET ? `${masked.slice(0, MAX_SNIPPET)}…` : masked;
+}
+
+/** 1-based line number of a character offset, mirroring the other check_* scripts' style. */
+function line_of(text: string, index: number): number {
+    let line = 1;
+    for (let i = 0; i < index; i += 1) {
+        if (text.charCodeAt(i) === 0x0a) line += 1;
+    }
+    return line;
+}
+
+/**
+ * Pure scan core: every pattern hit in `content`, tagged with the (already
+ * relative) file path the caller supplies. No filesystem or git access —
+ * tests drive this directly with synthetic strings.
+ */
+function scan_content(relPath: string, content: string): Hit[] {
+    const hits: Hit[] = [];
+    for (const pattern of LEAK_PATTERNS) {
+        pattern.re.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = pattern.re.exec(content))) {
+            hits.push({
+                file: relPath,
+                pattern: pattern.name,
+                line: line_of(content, m.index),
+                snippet: mask_snippet(m[0]),
+            });
+            // Zero-width safety net (none of the patterns above can match
+            // empty, but this mirrors the other check_* scripts' loop guard).
+            if (pattern.re.lastIndex === m.index) pattern.re.lastIndex += 1;
+        }
+    }
+    return hits;
+}
+
+function _git(args: readonly string[]): string {
+    const res = spawnSync('git', [...args], {
+        cwd: REPO,
+        encoding: 'utf-8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    return res.stdout ?? '';
+}
+
+function _splitlines(text: string): string[] {
+    return text.split('\n').filter((l) => l.length > 0);
+}
+
+/** Every tracked path under the bundle roots, deduped and sorted. */
+function tracked_bundle_files(): string[] {
+    const seen = new Set<string>();
+    for (const root of BUNDLE_ROOTS) {
+        for (const rel of _splitlines(_git(['ls-files', root]))) {
+            seen.add(rel);
+        }
+    }
+    return [...seen].sort();
+}
+
+/**
+ * Scan one file from disk. Binary / non-UTF-8 content is skipped (a bundle
+ * artifact is always text; a decode failure means this isn't one).
+ */
+function scan_file(relPath: string): Hit[] {
+    // `--file` args accept both repo-relative (the `git ls-files` default
+    // target list) and absolute paths (ad hoc / test use) — never silently
+    // resolve an already-absolute path underneath REPO.
+    const abs = path.isAbsolute(relPath) ? relPath : path.join(REPO, relPath);
+    let text: string;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(abs));
+    } catch {
+        return [];
+    }
+    return scan_content(relPath, text);
+}
+
+function scan_files(relPaths: readonly string[]): Hit[] {
+    const hits: Hit[] = [];
+    for (const rel of relPaths) hits.push(...scan_file(rel));
+    return hits;
+}
+
+function format_report(hits: readonly Hit[]): string {
+    const groups = new Map<string, Hit[]>();
+    for (const hit of hits) {
+        const key = `${hit.file}::${hit.pattern}`;
+        const group = groups.get(key);
+        if (group) group.push(hit);
+        else groups.set(key, [hit]);
+    }
+    const lines: string[] = [
+        '❌  check_bundle_path_leakage: build-machine path leakage in the tracked bundle:',
+    ];
+    for (const [key, group] of groups) {
+        const [file, patternName] = key.split('::') as [string, string];
+        const pattern = LEAK_PATTERNS.find((p) => p.name === patternName);
+        lines.push(`    ${file} [${patternName}] (${group.length} occurrence(s))`);
+        for (const hit of group.slice(0, MAX_HITS_SHOWN_PER_GROUP)) {
+            lines.push(`        line ${hit.line}: ${hit.snippet}`);
+        }
+        if (group.length > MAX_HITS_SHOWN_PER_GROUP) {
+            lines.push(`        (+${group.length - MAX_HITS_SHOWN_PER_GROUP} more)`);
+        }
+        if (pattern) lines.push(`        → ${pattern.hint}`);
+    }
+    return lines.join('\n');
+}
+
+interface Options {
+    quiet: boolean;
+    files: string[];
+}
+
+/** Thrown instead of calling `process.exit` directly, so `main()` stays testable. */
+class ExitCode extends Error {
+    code: number;
+    constructor(code: number) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+
+function parse_args(argv: readonly string[]): Options {
+    const opts: Options = { quiet: false, files: [] };
+    for (const arg of argv) {
+        if (arg === '--quiet') {
+            opts.quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: check_bundle_path_leakage.ts [--quiet] [<file> ...]\n',
+            );
+            throw new ExitCode(0);
+        } else if (arg.startsWith('--')) {
+            process.stderr.write(
+                `❌  check_bundle_path_leakage: unrecognized argument: ${arg}\n`,
+            );
+            throw new ExitCode(2);
+        } else {
+            opts.files.push(arg);
+        }
+    }
+    return opts;
+}
+
+function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const opts = parse_args(argv);
+    const targets = opts.files.length > 0 ? opts.files : tracked_bundle_files();
+    const hits = scan_files(targets);
+
+    if (hits.length > 0) {
+        process.stderr.write(`${format_report(hits)}\n`);
+        return 1;
+    }
+
+    if (!opts.quiet) {
+        process.stdout.write(
+            `✅  check_bundle_path_leakage: no build-machine path leakage ` +
+                `(${targets.length} tracked bundle file(s) scanned).\n`,
+        );
+    }
+    return 0;
+}
+
+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 {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        if (exc instanceof ExitCode) {
+            process.exit(exc.code);
+        }
+        throw exc;
+    }
+}
+
+export {
+    REPO,
+    BUNDLE_ROOTS,
+    LEAK_PATTERNS,
+    MAX_SNIPPET,
+    MAX_HITS_SHOWN_PER_GROUP,
+    mask_snippet,
+    scan_content,
+    scan_file,
+    scan_files,
+    tracked_bundle_files,
+    format_report,
+    parse_args,
+    main,
+    ExitCode,
+};
+export type { Hit, LeakPattern, Options };

package/src/scripts/check_evaluator_budgets.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env tsx
+/**
+ * check_evaluator_budgets — enforce the outside-in evaluator budgets
+ * (road-to-credible-install Phase 6) against a measurements JSON.
+ *
+ * Two failure modes per metric:
+ *   1. absolute:   measured > budgets[metric].max
+ *   2. regression: measured > last_measured * (1 + regression_pct/100)
+ *      — fails EVEN WHEN still under the absolute budget (the >10%
+ *      creep rule), so slow rot cannot hide under a generous cap.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_evaluator_budgets --measurements <file.json>
+ *   (measurements: flat { metric: number } — produced by evaluator_umbrella.sh)
+ *
+ * Exit codes: 0 green · 1 budget/regression exceeded · 2 internal error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const BUDGETS_PATH = path.join(REPO_ROOT, 'src', 'config', 'evaluator-budgets.json');
+
+interface BudgetEntry {
+    max: number;
+    last_measured: number;
+    method: string;
+    /** Per-metric creep override — wall-clock timings get a loose one
+     * (absolute cap is their real gate); sizes/counts keep the tight
+     * global default. */
+    regression_pct?: number;
+}
+interface BudgetsDoc {
+    regression_pct: number;
+    budgets: Record<string, BudgetEntry>;
+}
+
+export function evaluate(
+    budgetsDoc: BudgetsDoc,
+    measurements: Record<string, number>,
+): string[] {
+    const errors: string[] = [];
+    for (const [metric, entry] of Object.entries(budgetsDoc.budgets)) {
+        const measured = measurements[metric];
+        if (measured === undefined || Number.isNaN(measured)) {
+            errors.push(`${metric}: no measurement supplied (method: ${entry.method})`);
+            continue;
+        }
+        if (measured > entry.max) {
+            errors.push(`${metric}: measured ${measured} exceeds budget ${entry.max}`);
+            continue;
+        }
+        const pct = entry.regression_pct ?? budgetsDoc.regression_pct;
+        const ceiling = entry.last_measured * (1 + pct / 100);
+        if (entry.last_measured > 0 && measured > ceiling) {
+            errors.push(
+                `${metric}: measured ${measured} regressed >${pct}% vs ` +
+                    `last_measured ${entry.last_measured} (ceiling ${ceiling.toFixed(2)}) — ` +
+                    'fails even under the absolute budget',
+            );
+        }
+    }
+    return errors;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const idx = argv.indexOf('--measurements');
+    if (idx < 0 || argv[idx + 1] === undefined) {
+        process.stderr.write('usage: check_evaluator_budgets --measurements <file.json>\n');
+        return 2;
+    }
+    let budgetsDoc: BudgetsDoc;
+    let measurements: Record<string, number>;
+    try {
+        budgetsDoc = JSON.parse(fs.readFileSync(BUDGETS_PATH, 'utf-8')) as BudgetsDoc;
+        measurements = JSON.parse(fs.readFileSync(argv[idx + 1] as string, 'utf-8')) as Record<
+            string,
+            number
+        >;
+    } catch (e) {
+        process.stderr.write(`check_evaluator_budgets: ${(e as Error).message}\n`);
+        return 2;
+    }
+    const errors = evaluate(budgetsDoc, measurements);
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  evaluator budget: ${e}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  evaluator budgets met (${Object.keys(budgetsDoc.budgets).length} metrics)\n`,
+    );
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/check_knowledge_sharing.ts

@@ -66,8 +66,19 @@ export function checkSharing(staged: StagedFile[], readContent: (path: string) =
     const blocked: string[] = [];
     const warnings: string[] = [];
 
+    // The intake DIRECTORY SKELETON is tracked so the write path exists on a
+    // fresh clone (road-to-reachable-code-memory Phase 4); only the signal
+    // CONTENT (JSONL etc.) is local scratch that must never be committed.
+    const INTAKE_SKELETON = new Set([
+        'agents/memory/intake/.gitkeep',
+        'agents/memory/intake/README.md',
+        'agents/knowledge/intake/.gitkeep',
+        'agents/knowledge/intake/README.md',
+    ]);
     const intakeFiles = staged.filter(
-        (f) => f.path.startsWith('agents/memory/intake/') || f.path.startsWith('agents/knowledge/intake/'),
+        (f) =>
+            (f.path.startsWith('agents/memory/intake/') || f.path.startsWith('agents/knowledge/intake/')) &&
+            !INTAKE_SKELETON.has(f.path),
     );
     for (const f of intakeFiles) {
         blocked.push(`${f.path}: gitignored intake staged — intake is local scratch, never committed`);

package/src/scripts/check_no_external_sources.ts

@@ -21,7 +21,7 @@
  * - Vendored Apache/MIT code keeps its license-required attribution.
  * - Recommendation/registry docs may name registries (Smithery/Glama).
  * - A retained source link must be stored encrypted via
- *   src/scripts/_lib/link_crypto.py, never in plaintext.
+ *   src/scripts/_lib/link_crypto.ts, never in plaintext.
  *
  * Exit codes: 0 = clean, 1 = at least one denied token in a non-skipped tracked
  * file, 2 = usage / config error.
@@ -318,7 +318,7 @@ function main(argv: readonly string[]): number {
             process.stdout.write(
                 '\nThese name an external inspiration/harvest source. Remove the name,\n' +
                     'or — if a real source link must be retained — encrypt it via\n' +
-                    'src/scripts/_lib/link_crypto.py. Legitimate carve-outs (vendored code,\n' +
+                    'src/scripts/_lib/link_crypto.ts. Legitimate carve-outs (vendored code,\n' +
                     'registry recommendations) belong in external_sources_denylist.json\n' +
                     'skip_paths. See rule: source-confidentiality.\n',
             );

package/src/scripts/check_source_pointer_freshness.ts

@@ -17,9 +17,12 @@
  * genuinely-historical line inside an allowlisted file is exempted with an
  * inline `<!-- pointer-freshness: historical -->` marker.
  *
- * Extend AUTHORING_FILES as the broader `.agent-src.uncondensed` cleanup lands
- * (186 files still carry the token; see road-to-doc-follows-code Phase 4/5
- * follow-up).
+ * Extend AUTHORING_FILES as the broader `.agent-src.uncondensed` cleanup lands.
+ * road-to-retire-stale-authoring-pointers (2026-07-28) migrated the stale
+ * *authoring-source* pointers (43 `.md` lines) to `src/` and added the now
+ * token-free files here; the remaining `.agent-src.uncondensed/` references in
+ * `src/` are live code constants / pipeline descriptions / catalog paths that
+ * are correct and must stay (not authoring pointers).
  *
  * Exit codes: 0 = clean, 1 = a retired pointer in an allowlisted authoring
  * file, 2 = usage / self-test failure.
@@ -41,8 +44,30 @@ const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 // name the retired `.agent-src.uncondensed/` tree as current. Extend as the
 // broader cleanup lands.
 const AUTHORING_FILES: readonly string[] = [
+    // Seeded by #989 (the source-of-truth README + thin-root skill).
     'src/agent-src/README.md',
     'src/skills/agents-md-thin-root/SKILL.md',
+    // Added by road-to-retire-stale-authoring-pointers (2026-07-28): files whose
+    // stale "edit `.agent-src.uncondensed/`" authoring pointers were migrated to
+    // `src/` and are now token-free — locking them against regression. Files that
+    // retain legitimate `.agent-src.uncondensed/` references (pipeline
+    // descriptions, catalog-asset paths, validator_ignore config, fenced code)
+    // are intentionally NOT listed — they are guarded behaviorally by the
+    // downstream-changes § Doc-Impact rule, not by this any-occurrence scan.
+    'src/agent-src/templates/persona.md',
+    'src/domains/ai-video/image/command.md',
+    'src/domains/ai-video/video/command.md',
+    'src/domains/engineering-base/fix/portability/command.md',
+    'src/domains/engineering-base/fix/refs/command.md',
+    'src/domains/gtm-marketing/post-as/command.md',
+    'src/domains/meta/agents/command.md',
+    'src/domains/meta/agents/user/command.md',
+    'src/domains/meta/optimize/augmentignore/command.md',
+    'src/domains/product-basic/roadmap/ai-council/command.md',
+    'src/domains/product-discovery/research/command.md',
+    'src/skills/md-language-check/SKILL.md',
+    'src/skills/override-management/SKILL.md',
+    'src/skills/rule-refactor/SKILL.md',
 ];
 
 // Retired source-of-truth pointer. Matches both the bare token and the older