@event4u/agent-config 8.8.0 → 8.10.0

package/src/scripts/lint_changelog_rollback.ts

@@ -0,0 +1,293 @@
+#!/usr/bin/env tsx
+/**
+ * CHANGELOG `Rollback:` linter.
+ *
+ * Normative source: `docs/contracts/release-sizing.md § Rollback path`.
+ * Every NEW minor / major section in `CHANGELOG.md` — a heading matching
+ * the repo's `## [X.Y.0](compare-link) (date)` shape (patch component 0)
+ * — must contain at least one `Rollback:` line anywhere in its section,
+ * naming how a consumer undoes the subsystem the release introduced or
+ * substantially reworked.
+ *
+ * Cutoff — decidable, no retro-fail: the gate only fires for section
+ * versions **strictly greater** than the current `package.json` version
+ * at lint time. Historical sections are grandfathered by construction.
+ * `--cutoff X.Y.Z` overrides the cutoff (e.g. the release pipeline can
+ * pass the PREVIOUS released version so the section it is about to cut
+ * is itself in scope).
+ *
+ * Shares the heading / era regexes with the drift gate via
+ * `src/scripts/_lib/changelog_eras.ts` — no parallel copies.
+ *
+ * CLI: exit 0 clean, 1 violations (or selftest failure), 2 usage error.
+ * `--selftest` proves the rule on inline fixtures: a minor section
+ * without `Rollback:` fails; one with it passes.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    CHANGELOG,
+    REPO_ROOT,
+    VERSION_HEADING_RE,
+} from './_lib/changelog_eras.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+const ROLLBACK_LINE_RE = /\bRollback:/;
+// Section ends at the next version heading, the next era header, or any
+// other level-1/2 heading (`## [Unreleased]`, `# Era: …`). `###` sub-
+// headings stay inside the section.
+const SECTION_BOUNDARY_RE = /^##? /;
+
+export interface Violation {
+    readonly version: string;
+    readonly line: number; // 1-based heading line
+}
+
+function parse_semver(v: string): [number, number, number] | null {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    if (!m) {
+        return null;
+    }
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function semver_gt(a: [number, number, number], b: [number, number, number]): boolean {
+    if (a[0] !== b[0]) return a[0] > b[0];
+    if (a[1] !== b[1]) return a[1] > b[1];
+    return a[2] > b[2];
+}
+
+/** Read the cutoff version from package.json at the repo root. */
+function package_json_version(): string {
+    const pkg_path = path.join(REPO_ROOT, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkg_path, 'utf-8')) as { version?: string };
+    if (typeof pkg.version !== 'string' || parse_semver(pkg.version) === null) {
+        throw new Error(`package.json version is not bare semver: '${String(pkg.version)}'`);
+    }
+    return pkg.version;
+}
+
+/**
+ * Core check: return one Violation per minor/major section (`## [X.Y.0]`)
+ * whose version is strictly greater than `cutoff` and whose body carries
+ * no `Rollback:` line.
+ */
+export function check_rollback_lines(lines: readonly string[], cutoff: string): Violation[] {
+    const cut = parse_semver(cutoff);
+    if (cut === null) {
+        throw new Error(`cutoff is not bare semver (X.Y.Z): '${cutoff}'`);
+    }
+    const violations: Violation[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = VERSION_HEADING_RE.exec(lines[i]!);
+        if (!m) {
+            continue;
+        }
+        const version = m.groups!['version']!;
+        const parsed = parse_semver(version);
+        if (parsed === null || parsed[2] !== 0) {
+            continue; // patch release — not a minor/major section
+        }
+        if (!semver_gt(parsed, cut)) {
+            continue; // at or below the cutoff — grandfathered
+        }
+        // Section body: heading line down to (exclusive) the next boundary.
+        let end = lines.length;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (SECTION_BOUNDARY_RE.test(lines[j]!)) {
+                end = j;
+                break;
+            }
+        }
+        const has_rollback = lines.slice(i, end).some((ln) => ROLLBACK_LINE_RE.test(ln));
+        if (!has_rollback) {
+            violations.push({ version, line: i + 1 });
+        }
+    }
+    return violations;
+}
+
+// ─── selftest fixtures ─────────────────────────────────────────────────────────
+
+function _fixture(section_body: string): string[] {
+    return (
+        '# Changelog\n\n' +
+        '## [Unreleased]\n\n' +
+        '# Era: 9.1.x — current\n\n' +
+        '> Started at `9.1.0`.\n\n' +
+        section_body +
+        '# Era: pre-9.0.0 — archived\n'
+    ).split('\n');
+}
+
+function run_selftest(): number {
+    const cutoff = '9.0.0';
+    let failed = 0;
+    const assert = (label: string, ok: boolean): void => {
+        process.stdout.write(`${ok ? '✅' : '❌'}  selftest: ${label}\n`);
+        if (!ok) failed += 1;
+    };
+
+    // 1. New minor section WITHOUT Rollback: → exactly one violation.
+    const red = check_rollback_lines(
+        _fixture(
+            '## [9.1.0](https://example/compare/9.0.0...9.1.0) (2026-07-10)\n\n' +
+                '### Features\n\n* **workspace:** new subsystem ([abc1234](https://example))\n\n',
+        ),
+        cutoff,
+    );
+    assert('minor section without Rollback: FAILS', red.length === 1 && red[0]!.version === '9.1.0');
+
+    // 2. Same section WITH a Rollback: line → clean.
+    const green = check_rollback_lines(
+        _fixture(
+            '## [9.1.0](https://example/compare/9.0.0...9.1.0) (2026-07-10)\n\n' +
+                '### Features\n\n* **workspace:** new subsystem ([abc1234](https://example))\n' +
+                '  Rollback: set `workspace.enabled: false` in `.agent-settings.yml`.\n\n',
+        ),
+        cutoff,
+    );
+    assert('minor section with Rollback: passes', green.length === 0);
+
+    // 3. Historical minor section at/below the cutoff → grandfathered.
+    const old = check_rollback_lines(
+        _fixture('## [9.0.0](https://example/compare/8.9.0...9.0.0) (2026-06-01)\n\n* old entry\n\n'),
+        cutoff,
+    );
+    assert('section at cutoff is grandfathered', old.length === 0);
+
+    // 4. New PATCH section without Rollback: → out of scope.
+    const patch = check_rollback_lines(
+        _fixture('## [9.1.1](https://example/compare/9.1.0...9.1.1) (2026-07-11)\n\n* a fix\n\n'),
+        cutoff,
+    );
+    assert('patch section is out of scope', patch.length === 0);
+
+    // 5. Rollback: in a FOLLOWING section must not satisfy the earlier one.
+    const bleed = check_rollback_lines(
+        _fixture(
+            '## [9.2.0](https://example/compare/9.1.0...9.2.0) (2026-08-01)\n\n* no rollback here\n\n' +
+                '## [9.1.0](https://example/compare/9.0.0...9.1.0) (2026-07-10)\n\n' +
+                'Rollback: only covers 9.1.0.\n\n',
+        ),
+        cutoff,
+    );
+    assert('Rollback: does not bleed across sections', bleed.length === 1 && bleed[0]!.version === '9.2.0');
+
+    if (failed > 0) {
+        process.stderr.write(`❌  selftest: ${failed} fixture(s) failed.\n`);
+        return 1;
+    }
+    process.stdout.write('✅  selftest: all fixtures behave as specified.\n');
+    return 0;
+}
+
+// ─── CLI ───────────────────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+    selftest: boolean;
+    cutoff: string | null;
+    changelog: string | null;
+    quiet: boolean;
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`lint_changelog_rollback: error: ${message}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    const args: ParsedArgs = { selftest: false, cutoff: null, changelog: null, quiet: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!;
+        if (arg === '--selftest') {
+            args.selftest = true;
+        } else if (arg === '--cutoff') {
+            const v = argv[++i];
+            if (v === undefined) _argparse_error('argument --cutoff: expected one argument');
+            args.cutoff = v;
+        } else if (arg.startsWith('--cutoff=')) {
+            args.cutoff = arg.slice('--cutoff='.length);
+        } else if (arg === '--changelog') {
+            const v = argv[++i];
+            if (v === undefined) _argparse_error('argument --changelog: expected one argument');
+            args.changelog = v;
+        } else if (arg.startsWith('--changelog=')) {
+            args.changelog = arg.slice('--changelog='.length);
+        } else if (arg === '--quiet') {
+            args.quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: lint_changelog_rollback [-h] [--selftest] [--cutoff X.Y.Z] [--changelog PATH] [--quiet]\n',
+            );
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return args;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    if (args.selftest) {
+        return run_selftest();
+    }
+
+    const changelog_path = args.changelog ?? CHANGELOG;
+    const cutoff = args.cutoff ?? package_json_version();
+    const text = fs.readFileSync(changelog_path, 'utf-8');
+    const lines = text.split(/\r\n|\r|\n/);
+
+    const violations = check_rollback_lines(lines, cutoff);
+    if (violations.length > 0) {
+        process.stderr.write(
+            `❌  ${violations.length} minor/major CHANGELOG section(s) above ` +
+                `cutoff ${cutoff} without a Rollback: line:\n`,
+        );
+        for (const v of violations) {
+            process.stderr.write(`   - ## [${v.version}] (line ${v.line})\n`);
+        }
+        process.stderr.write(
+            '\nEvery new minor/major section must name a rollback path for each ' +
+                'introduced or substantially reworked subsystem via a `Rollback:` ' +
+                'line — see docs/contracts/release-sizing.md § Rollback path.\n',
+        );
+        return 1;
+    }
+
+    if (!args.quiet) {
+        process.stdout.write(
+            `✅  CHANGELOG Rollback: gate clean (cutoff ${cutoff}, ` +
+                `${path.relative(REPO_ROOT, changelog_path)}).\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) {
+    process.exit(main());
+}
+
+export { main, run_selftest, parse_semver, semver_gt, package_json_version };

package/src/scripts/lint_knowledge_scale.ts

@@ -14,9 +14,10 @@
  *   - 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
+ *                        → rank via `_lib/lexical_index.ts` (hand-rolled BM25 +
+ *                          trigram, no engine fork / no FTS5; ADR-061 honoured)
  *   - corpus scale     — > 500 files across all types
- *                        → same BM25 activation path
+ *                        → same lexical-index activation path
  *   - hot-context size — `agents/runtime/state/hot-context.md` > 600 tokens
  *                        (estimated at 4 chars/token) → trim schema / fix the
  *                        deterministic writer
@@ -151,7 +152,7 @@ export function runChecks(root: string): Warning[] {
                 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).',
+                    'Activation path (resolved, road-to-retrieval-substrate-hardening B2): rank via the hand-rolled BM25 + trigram index in `_lib/lexical_index.ts` (pure stdlib, NO engine fork / NO SQLite-FTS5, ADR-061 honoured). Measured lift: mean tie-set 3.333 → 1.0 (internal/bench/reports/lexical-ranking.json). Wire it lazily at first lookup + a stat-index, no vectors, no service.',
             });
         }
     }

package/src/scripts/lint_roadmap_complexity.ts

@@ -190,6 +190,9 @@ function lint_roadmap(
     _check_execution_mode(fm, problems);
     if (warnings) {
         _check_autonomous_authoring(text, fm, warnings);
+        _check_human_gate_steps(text, warnings);
+        _check_human_gate_phase_headings(text, warnings);
+        _check_human_gate_exit_criteria(text, warnings);
     }
     return problems;
 }
@@ -236,6 +239,127 @@ function _check_autonomous_authoring(text: string, fm: string, warnings: string[
     }
 }
 
+// Human-gate step patterns (templates/roadmaps.md rule 22) — checkbox
+// steps that park work on a human instead of the agent. Steps are
+// agent-executable by default; genuinely user-clearable gates belong in
+// a structured `## Blockers` entry, agent-checkable verifications become
+// commands / targeted tests. Warnings never fail the lint; they fire for
+// every execution mode (an interactive roadmap with sprinkled human-check
+// steps is the same authoring bug, just slower to hurt).
+const HUMAN_GATE_STEP_PATS: Array<[RegExp, string]> = [
+    [
+        /\b(user|maintainer|human|operator|stakeholder|product owner) (verifies|reviews|approves|confirms|signs?[- ]off(?: on)?|inspects|validates)\b/i,
+        "'<human> verifies / reviews / approves …' step",
+    ],
+    [
+        /\bmanually (verify|review|check|test|confirm|inspect|validate)\b/i,
+        "'manually verify / check …' step",
+    ],
+    [
+        /\bwait for (the )?(user|maintainer|stakeholders?|approval|confirmation|review|feedback)\b/i,
+        "'wait for approval / user' step",
+    ],
+    [/\bask the (user|maintainer)\b/i, "'ask the user' step"],
+    [
+        /\b(get|obtain|request|await|collect) ((the|an?|final) )?((user|maintainer|stakeholder|product owner|team) )?(approval|confirmation|sign[- ]?off)\b/i,
+        "'obtain approval / sign-off' step",
+    ],
+    [/\bsign[- ]?off (from|by)\b/i, "'sign-off from <human>' step"],
+    [/\bhuman review (required|needed|gate)\b/i, "'human review required' step"],
+    [
+        /\b(confirm|check|verify|review|clarify) with the (user|maintainer)\b/i,
+        "'confirm with the user' step",
+    ],
+];
+
+// Human-gate phase headings (template rule 22) — a phase whose TITLE is
+// the human checkpoint ("## Phase 5 — Review / Sign-off", "## User
+// Acceptance"). Whole-heading match after an optional "Phase N" prefix,
+// so working headings ("## Review existing skills") never fire.
+const HUMAN_GATE_HEADING_PAT =
+    /^#{2,3}\s+(?:phase\s+\d+\s*(?:[—–:.-])?\s*)?(?:review(?:\s*(?:[/&+]|and)\s*sign[- ]?off)?|sign[- ]?off|approval|user\s+acceptance(?:\s+testing)?|manual\s+(?:verification|review|testing|qa)|human\s+(?:validation|review))\s*$/i;
+
+// Human-approval exit / acceptance criteria (template rule 22) — criteria
+// must be agent-decidable (exit code, file exists, test passes), never
+// "user approves" / "looks good". Applied inside Exit-criteria /
+// Acceptance blocks only.
+const HUMAN_GATE_CRITERIA_PAT =
+    /\b(user|maintainer|human|operator|stakeholder|product owner)\b[^\n]{0,60}\b(approv\w*|confirm\w*|sign[- ]?off|reviews)\b|\b(approval|confirmation|sign[- ]?off)\s+(from|by|received)\b|\blooks good\b/i;
+
+const EXIT_CRITERIA_OPENER_PAT = /^\s*(?:[-*]\s+)?\*{0,2}(exit criteria|acceptance(?: criteria)?)\*{0,2}\s*:?/i;
+
+const RULE22_HINT =
+    'templates/roadmaps.md rule 22: steps and criteria are agent-decidable; ' +
+    'replace with an agent-verifiable check (command / targeted test) or, ' +
+    'if only a human can decide/authorize, a structured ## Blockers entry';
+
+function _check_human_gate_steps(text: string, warnings: string[]): void {
+    for (const rawLine of text.split('\n')) {
+        if (!/^\s*-\s*\[ \]/.test(rawLine)) {
+            continue;
+        }
+        for (const [re, label] of HUMAN_GATE_STEP_PATS) {
+            if (re.test(rawLine)) {
+                warnings.push(
+                    `human-gate step (${label}): ` +
+                        `"${rawLine.trim().slice(0, 80)}" — ${RULE22_HINT}`,
+                );
+                break;
+            }
+        }
+    }
+}
+
+function _check_human_gate_phase_headings(text: string, warnings: string[]): void {
+    for (const rawLine of text.split('\n')) {
+        if (!rawLine.startsWith('#')) {
+            continue;
+        }
+        if (HUMAN_GATE_HEADING_PAT.test(rawLine)) {
+            warnings.push(
+                `human-gate phase heading: "${rawLine.trim().slice(0, 80)}" — ` +
+                    'a phase whose work only a human can finish blocks autonomous ' +
+                    `execution; ${RULE22_HINT}`,
+            );
+        }
+    }
+}
+
+function _check_human_gate_exit_criteria(text: string, warnings: string[]): void {
+    let inHeadingBlock = false;
+    let inInlineBlock = false;
+    for (const rawLine of text.split('\n')) {
+        const heading = /^#{1,6}\s+(.*)$/.exec(rawLine);
+        if (heading) {
+            inHeadingBlock = /\b(acceptance|exit criteria)\b/i.test(heading[1]!);
+            inInlineBlock = false;
+            continue;
+        }
+        if (rawLine.trim() === '') {
+            inInlineBlock = false;
+            continue;
+        }
+        const opener = EXIT_CRITERIA_OPENER_PAT.test(rawLine);
+        if (opener) {
+            inInlineBlock = true;
+        }
+        if (!inHeadingBlock && !inInlineBlock) {
+            continue;
+        }
+        // Open-checkbox lines are covered by _check_human_gate_steps;
+        // done/deferred/cancelled lines record history, not future gates.
+        if (/^\s*-\s*\[[ xX~-]\]/.test(rawLine)) {
+            continue;
+        }
+        if (HUMAN_GATE_CRITERIA_PAT.test(rawLine)) {
+            warnings.push(
+                `human-approval exit criterion: "${rawLine.trim().slice(0, 80)}" — ` +
+                    `criteria must be agent-decidable; ${RULE22_HINT}`,
+            );
+        }
+    }
+}
+
 function _check_execution_mode(fm: string, problems: string[]): void {
     if (!fm || !/^execution:/m.test(fm)) {
         return; // absent field = interactive default — valid

package/src/scripts/lint_versioned_cache.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * Versioned-cache lint (road-to-retrieval-substrate-hardening B5b).
+ *
+ * Every derived cache the suite writes MUST be safe to invalidate when its
+ * producer changes — otherwise a tool-version bump silently reads a
+ * stale-format cache and corrupts the read path. This lint makes that
+ * discipline structural: any cache-file path literal in `src/scripts/**`
+ * must EITHER carry a version namespace in the path (`v<N>`, a `${…version…}`
+ * interpolation, or a `_VERSION`/`schema_version` reference), OR carry an
+ * explicit invalidation justification comment (`cache-version:` /
+ * `cache-invalidation:`) within a few lines — an author's ack that the cache
+ * is invalidated by another mechanism (full overwrite, content hash, …).
+ *
+ * It is a FAILING gate (this roadmap introduces it), scoped tightly to
+ * cache-file SUFFIXES so it has near-zero false-positive surface: it fires on
+ * the derived caches later phases create (B2 index, B3 learning sidecar, B5a
+ * stat-index), not on directories or ordinary data files.
+ *
+ * Usage: lint_versioned_cache.ts [--dir <root>] [--format text|json] [--quiet]
+ * Exit codes: 0 = clean, 1 = usage error, 2 = violations found, 3 = internal.
+ */
+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_versioned_cache.ts';
+
+/** Window (lines) around a cache-path literal scanned for a justification. */
+export const JUSTIFY_WINDOW = 6;
+
+/**
+ * A path literal is a "derived cache file" when its basename matches one of
+ * these suffixes. Suffix-based (not dir-based) to keep the trigger precise —
+ * ordinary data/config JSON does not match.
+ */
+export const CACHE_SUFFIX_RE =
+    /(?:^|[\/'"`\-.])(?:[a-z0-9_\-.]*)(?:-index|\.index|-cache|\.cache|\.stat-index|-stat-index|\.agent-learning)\.json(?:['"`]|$)/i;
+
+/** A version namespace present in the path literal itself. */
+const VERSION_IN_PATH_RE = /(?:[\/_\-.]v\d+|\$\{[^}]*[Vv]ersion[^}]*\}|\$\{[^}]*VERSION[^}]*\})/;
+
+/** An explicit author justification comment near the literal. */
+const JUSTIFY_RE = /(?:cache-version:|cache-invalidation:)/i;
+
+/** A string / template literal containing a cache-file path. */
+const LITERAL_RE = /(['"`])((?:\\.|(?!\1).)*?)\1/g;
+
+export interface Violation {
+    file: string;
+    line: number; // 1-indexed
+    literal: string;
+    message: string;
+}
+
+function listTsFiles(root: string): string[] {
+    const out: string[] = [];
+    const skip = new Set([
+        'node_modules',
+        '.git',
+        'dist',
+        'coverage',
+        '.turbo',
+        '.cache',
+        '__pycache__',
+    ]);
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (!skip.has(e.name)) walk(path.join(dir, e.name));
+            } else if (e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts')) {
+                out.push(path.join(dir, e.name));
+            }
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+
+function _isCachePathLiteral(value: string): boolean {
+    // Reset lastIndex — CACHE_SUFFIX_RE has no /g flag, so test() is safe.
+    return CACHE_SUFFIX_RE.test(value);
+}
+
+export function scanFile(file: string, source: string): Violation[] {
+    const lines = source.split('\n');
+    const violations: Violation[] = [];
+    for (let i = 0; i < lines.length; i++) {
+        const text = lines[i] as string;
+        LITERAL_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = LITERAL_RE.exec(text)) !== null) {
+            const value = m[2] as string;
+            if (!_isCachePathLiteral(value)) continue;
+            if (VERSION_IN_PATH_RE.test(value)) continue; // versioned in the path itself
+
+            // Look for a justification comment in the window around the literal.
+            const from = Math.max(0, i - JUSTIFY_WINDOW);
+            const to = Math.min(lines.length - 1, i + JUSTIFY_WINDOW);
+            let justified = false;
+            for (let j = from; j <= to; j++) {
+                if (JUSTIFY_RE.test(lines[j] as string)) {
+                    justified = true;
+                    break;
+                }
+            }
+            if (justified) continue;
+
+            violations.push({
+                file,
+                line: i + 1,
+                literal: value,
+                message:
+                    'derived cache without a version namespace — add a `v<N>` (or ' +
+                    '`${…version…}`) segment to the path, or an inline ' +
+                    '`// cache-invalidation: <why no version is needed>` comment',
+            });
+        }
+    }
+    return violations;
+}
+
+export function runChecks(root: string): Violation[] {
+    const violations: Violation[] = [];
+    for (const file of listTsFiles(root)) {
+        // Never lint this file itself — its regexes contain the very suffixes
+        // it hunts for.
+        if (path.basename(file) === 'lint_versioned_cache.ts') continue;
+        let source: string;
+        try {
+            source = fs.readFileSync(file, 'utf-8');
+        } catch {
+            continue;
+        }
+        violations.push(...scanFile(file, source));
+    }
+    return violations;
+}
+
+export function main(argv: string[]): number {
+    let dir = 'src/scripts';
+    let format: 'text' | 'json' = 'text';
+    let quiet = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--dir') {
+            dir = argv[++i] ?? dir;
+        } else if (a.startsWith('--dir=')) {
+            dir = a.slice('--dir='.length);
+        } else if (a === '--format') {
+            format = (argv[++i] as 'text' | 'json') ?? 'text';
+        } else if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write(`usage: ${PROG} [--dir <root>] [--format text|json] [--quiet]\n`);
+            return 0;
+        } else {
+            process.stderr.write(`${PROG}: error: unknown argument ${a}\n`);
+            return 1;
+        }
+    }
+
+    let violations: Violation[];
+    try {
+        violations = 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({ violations }, null, 2) + '\n');
+        return violations.length > 0 ? 2 : 0;
+    }
+    if (violations.length === 0) {
+        if (!quiet) process.stdout.write(`${PROG}: no unversioned derived caches\n`);
+        return 0;
+    }
+    for (const v of violations) {
+        process.stdout.write(`❌ ${v.file}:${v.line} — cache '${v.literal}': ${v.message}\n`);
+    }
+    process.stdout.write(`${PROG}: ${violations.length} unversioned derived cache(s)\n`);
+    return 2;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -70,7 +70,8 @@
           "types": {"type": "array", "items": {"type": "string"}, "minItems": 1, "description": "Memory types to scan, e.g. `historical-patterns`, `incident-learnings`, `ownership`. At least one required."},
           "keys": {"type": "array", "items": {"type": "string"}, "description": "Optional anchor paths or globs to match entries against (e.g. a file you are about to edit)."},
           "limit": {"type": "integer", "minimum": 1, "default": 5, "description": "Maximum entries to return per type. Defaults to 5."},
-          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact priced rows (id, title, tokens_estimate) instead of full bodies — call this first, then memory_get the ids you need. 'full' (default) returns complete entries."}
+          "detail": {"type": "string", "enum": ["index", "full"], "default": "full", "description": "'index' returns compact priced rows (id, title, tokens_estimate) instead of full bodies — call this first, then memory_get the ids you need. 'full' (default) returns complete entries."},
+          "token_budget": {"type": "integer", "minimum": 1, "description": "Optional token budget. When set, entries are rendered as one-line compact rows (id, type, confidence, `line`) and the row set is hard-cut at token_budget × 4 chars; omitted hits appear as a top-level `truncation` hint naming a concrete next step. Absent → the envelope is unchanged."}
         },
         "required": ["types"],
         "additionalProperties": false