@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -30,7 +30,8 @@
  * lockfile-freshness · bridge-drift · mcp-mode · mcp-beta-readiness ·
  * offline-readiness · python-runtime · humanizer-runtime · tier-usage-readiness ·
  * council-cli · team ·
- * unsupported-combos · wizard-state.
+ * unsupported-combos · wizard-state · settings-review-pending ·
+ * memory-merge-union.
  * Each emits a structured `{id, status, message, remedy}` record with
  * `status` ∈ `ok` / `warn` / `fail` / `skipped` (rendered
  * `✅` / `⚠️` / `❌` / `⏭️`). `--check <id>` runs a single check.
@@ -88,6 +89,7 @@ import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
 import * as global_deploy_inventory from '../_lib/global_deploy_inventory.js';
+import * as sync_gitattributes from '../sync_gitattributes.js';
 import {
     PROJECT_ROOT_ENV,
     ROOT_OVERRIDE_ENV,
@@ -759,6 +761,7 @@ const CHECK_IDS = [
     'unsupported-combos',
     'wizard-state',
     'settings-review-pending',
+    'memory-merge-union',
 ] as const;
 
 /** Checks that need only the project root and run regardless of a lockfile. */
@@ -782,6 +785,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'team',
     'wizard-state',
     'settings-review-pending',
+    'memory-merge-union',
 ]);
 
 /** Checks that genuinely cannot run without the project manifest. */
@@ -2557,6 +2561,61 @@ function _check_settings_review_pending(): Dict {
     };
 }
 
+/**
+ * `memory-merge-union` — read-only warn check (road-to-reachable-code-memory
+ * Phase 5). The `merge=union` .gitattributes block lets two branches each
+ * appending a NEW memory entry (intake JSONL, or the flat curated
+ * `agents/memory/<type>.yml` files) merge cleanly instead of conflicting.
+ * Without it, ordinary parallel memory writes on separate branches produce a
+ * merge conflict the human has to resolve by hand. Never fails the run —
+ * this is advisory, same posture as `offline-readiness`.
+ */
+function _check_memory_merge_union(project_root: string): Dict {
+    const remedy =
+        'run: npx tsx src/scripts/sync_gitattributes.ts (or `agent-config refresh --project`)';
+    const target = path.join(project_root, sync_gitattributes.DEFAULT_GITATTRIBUTES);
+    if (!pathExists(target)) {
+        return {
+            id: 'memory-merge-union',
+            status: 'warn',
+            message:
+                'no .gitattributes at project root — memory merge-safety attributes not applied',
+            remedy,
+        };
+    }
+    let text: string;
+    try {
+        text = readText(target);
+    } catch (exc) {
+        return {
+            id: 'memory-merge-union',
+            status: 'warn',
+            message: `unreadable .gitattributes at ${target}: ${osErrorStr(exc)}`,
+            remedy,
+        };
+    }
+    const has_block = text.includes(sync_gitattributes.SECTION_HEADER);
+    const has_intake_union = /agents\/memory\/intake\/\*\.jsonl\s+merge=union/.test(text);
+    if (has_block && has_intake_union) {
+        return {
+            id: 'memory-merge-union',
+            status: 'ok',
+            message:
+                '.gitattributes carries the memory merge-safety block (intake JSONL union-merge present)',
+            remedy: '',
+        };
+    }
+    return {
+        id: 'memory-merge-union',
+        status: 'warn',
+        message: has_block
+            ? '.gitattributes has the managed block but is missing the intake merge=union line'
+            : '.gitattributes is missing the memory merge-safety block — parallel-branch ' +
+              'memory writes can conflict instead of merging',
+        remedy,
+    };
+}
+
 interface JsonDecodeError {
     msg: string;
     lineno: number;
@@ -2691,6 +2750,7 @@ function _run_checks(
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
+        'memory-merge-union': () => _check_memory_merge_union(project_root),
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {
@@ -2765,6 +2825,7 @@ function _run_checks_no_manifest(
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
+        'memory-merge-union': () => _check_memory_merge_union(project_root),
     };
     const out: Dict[] = [];
     for (const cid of CHECK_IDS) {

package/src/scripts/_cli/cmd_memory_get.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config memory:get` — CLI twin of the `memory_get` MCP tool
+ * (`src/scripts/mcp_server/tools.ts` `_memoryGetHandler`, road-to-memory-
+ * retrieval-economy Phase 1).
+ *
+ * Batch-fetches FULL memory entries by id — the second half of the
+ * index-first retrieval workflow: `memory:lookup --detail index` returns
+ * compact priced rows, this fetches ONLY the bodies actually needed, in one
+ * call. Reuses the exact same shared function the MCP tool calls
+ * (`memory_get_v1` in `../memory_lookup.js`) — no duplicated lookup logic.
+ *
+ * Unlike the MCP handler (which `chdir`s into the consumer root before
+ * calling), this CLI relies on `agent-config`'s existing invariant that the
+ * dispatcher never changes CWD — `memory_get_v1` resolves `agents/memory`
+ * relative to `process.cwd()`, which is already the consumer's repo root.
+ *
+ * Usage: memory:get <id> [<id> ...] [--format text|json]
+ * Exit codes:
+ *   0 — every requested id was found.
+ *   1 — at least one requested id was not found (unknown id).
+ *   2 — usage error (no ids given, unrecognized flag, missing flag value).
+ */
+import process from 'node:process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { memory_get_v1 } from '../memory_lookup.js';
+
+const PROG = 'agent-config memory:get';
+const USAGE = `usage: ${PROG} <id> [<id> ...] [--format text|json]\n`;
+
+/** argparse-style usage / help exit (code 2 / 0). Caught at the CLI entry. */
+class ArgparseExit extends Error {
+    constructor(public readonly code: number) {
+        super(`argparse-exit-${code}`);
+    }
+}
+
+interface Opts {
+    ids: string[];
+    format: 'text' | 'json';
+}
+
+function _argError(msg: string): never {
+    process.stderr.write(USAGE);
+    process.stderr.write(`${PROG}: error: ${msg}\n`);
+    throw new ArgparseExit(2);
+}
+
+function _parse(argv: string[]): Opts {
+    const opts: Opts = { ids: [], format: 'text' };
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i] as string;
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                `${USAGE}\n` +
+                    'Batch-fetch FULL memory entries by id — the second half of the\n' +
+                    "index-first retrieval workflow (`memory:lookup --detail index`\n" +
+                    'first, then `memory:get` the ids that justify the fetch).\n\n' +
+                    'options:\n' +
+                    '  --format text|json   output format (default: text)\n' +
+                    '  -h, --help           show this help and exit\n\n' +
+                    'exit codes:\n' +
+                    '  0  every requested id was found\n' +
+                    '  1  at least one requested id was not found\n' +
+                    '  2  usage error\n',
+            );
+            throw new ArgparseExit(0);
+        } else if (a === '--format') {
+            const val = argv[i + 1];
+            if (val === undefined) _argError('argument --format: expected one argument');
+            if (val !== 'text' && val !== 'json') {
+                _argError(`argument --format: invalid choice: '${val}' (choose from 'text', 'json')`);
+            }
+            opts.format = val;
+            i += 2;
+        } else if (a.startsWith('--format=')) {
+            const val = a.slice('--format='.length);
+            if (val !== 'text' && val !== 'json') {
+                _argError(`argument --format: invalid choice: '${val}' (choose from 'text', 'json')`);
+            }
+            opts.format = val;
+            i += 1;
+        } else if (a.startsWith('--')) {
+            _argError(`unrecognized arguments: ${a}`);
+        } else {
+            opts.ids.push(a);
+            i += 1;
+        }
+    }
+    if (opts.ids.length === 0) {
+        _argError('at least one <id> is required');
+    }
+    return opts;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Render one fetched entry as an indented `key: value` block. */
+function _renderEntryText(entry: Record<string, unknown>): string {
+    const lines: string[] = [];
+    const id = typeof entry['id'] === 'string' ? entry['id'] : '(unknown id)';
+    const type = typeof entry['type'] === 'string' ? entry['type'] : '(unknown type)';
+    lines.push(`[${id}] ${type}`);
+    const body = entry['body'];
+    if (isPlainObject(body)) {
+        for (const key of Object.keys(body).sort()) {
+            lines.push(`  ${key}: ${_renderValue(body[key])}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Render one body value for text output. `memory_lookup.ts` wraps YAML
+ * date scalars in a `PyTimestamp`-shaped object (`{ pyStr: string }`, not
+ * exported) to mirror Python's `yaml.safe_load` date parsing — duck-type
+ * that shape rather than importing the private class.
+ */
+function _renderValue(value: unknown): string {
+    if (typeof value === 'string') return value;
+    if (isPlainObject(value) && typeof value['pyStr'] === 'string' && Object.keys(value).length === 1) {
+        return value['pyStr'];
+    }
+    return JSON.stringify(value);
+}
+
+export function main(argv: string[] | null = null): number {
+    const opts = _parse(argv ?? process.argv.slice(2));
+    const envelope = memory_get_v1(opts.ids);
+    const entries = Array.isArray(envelope['entries']) ? (envelope['entries'] as Record<string, unknown>[]) : [];
+    const idStatus = isPlainObject(envelope['ids']) ? (envelope['ids'] as Record<string, string>) : {};
+    const unknown = opts.ids.filter((id) => idStatus[id] === 'unknown');
+
+    if (opts.format === 'json') {
+        process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    } else {
+        if (entries.length === 0) {
+            process.stdout.write('  (no entries found)\n');
+        } else {
+            for (const entry of entries) {
+                process.stdout.write(`${_renderEntryText(entry)}\n`);
+            }
+        }
+        for (const id of unknown) {
+            process.stderr.write(`${PROG}: unknown id: ${id}\n`);
+        }
+    }
+
+    return unknown.length > 0 ? 1 : 0;
+}
+
+// --- CLI entry ---
+
+const _HERE = fileURLToPath(import.meta.url);
+
+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;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    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.exitCode = main(process.argv.slice(2));
+    } catch (exc) {
+        if (exc instanceof ArgparseExit) {
+            process.exitCode = exc.code;
+        } else {
+            throw exc;
+        }
+    }
+}
+
+export { ArgparseExit };
+export type { Opts };

package/src/scripts/_cli/cmd_refresh.ts

@@ -68,6 +68,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as cli_wrapper from '../_lib/cli_wrapper.js';
 import * as sync_gitignore from '../sync_gitignore.js';
+import * as sync_gitattributes from '../sync_gitattributes.js';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 
@@ -306,6 +307,12 @@ function _refresh_project(project_root: string, out: OutSink, err: OutSink): num
     if (rc !== 0) {
         return rc;
     }
+
+    // Memory merge-safety attributes (road-to-reachable-code-memory Phase 5):
+    // advisory, same shape as the gitignore sync above — never fails the
+    // refresh on its own.
+    _sync_gitattributes(project_root, out, err);
+
     _print(out, '✅  refresh --project complete.');
     return 0;
 }
@@ -329,6 +336,28 @@ function _sync_gitignore(project_root: string, out: OutSink, err: OutSink): numb
     return 0;
 }
 
+/**
+ * Sync the memory-merge-safety block into the consumer's `.gitattributes`.
+ * Advisory only (mirrors `_sync_gitignore`'s failure shape) — a missing
+ * template or a write failure is reported but never fails the refresh.
+ */
+function _sync_gitattributes(project_root: string, out: OutSink, err: OutSink): number {
+    let mod: typeof sync_gitattributes;
+    try {
+        mod = sync_gitattributes;
+    } catch (exc) {
+        _print(err, `⚠️  refresh --project: gitattributes sync unavailable (${osErrorStr(exc)})`);
+        return 0;
+    }
+    const rc = mod.main(['--path', path.join(project_root, '.gitattributes')]);
+    if (rc !== 0 && rc !== null && rc !== undefined) {
+        _print(err, `⚠️  refresh --project: gitattributes sync returned ${rc}`);
+    } else {
+        _print(out, '✅  .gitattributes memory merge-safety block synced.');
+    }
+    return 0;
+}
+
 interface Args {
     is_global: boolean;
     is_project: boolean;
@@ -460,6 +489,7 @@ export {
     _is_source_repo,
     _refresh_project,
     _sync_gitignore,
+    _sync_gitattributes,
     _remove_legacy_consumer_bridge_marker,
     ArgparseExit,
 };

package/src/scripts/_dispatch.bash

@@ -76,6 +76,7 @@ TS-shell native (run via the installed `agent-config` binary):
   commands [ls|explain]      List/explain the command surface from the discovery manifest
   mcp-server                 Turnkey read-only stdio MCP server (no repo clone; ADR-085)
   doctor-shell               Probe the TS-shell environment
+  rtk:detect                 rtk (Rust Token Killer) presence + identity readout (--json)
   eval:record                Record a live trigger-eval result into a corpus manifest
 EOF
 
@@ -173,6 +174,8 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              relation-graph with a node budget. Flags: --budget N
   benchmark                  Report context-token reduction vs the full always-loaded
                              projection (from the pinned token baseline). Flags: --format
+  code-graph                 Deterministic code-graph engine (ADR-124, Class A).
+                             Usage: code-graph build|validate|detect|query|explain|affected|path [options]
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
@@ -215,12 +218,21 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              read-only request per declared backend; never runs in CI,
                              writes nothing)
   memory:lookup              Retrieve memory entries (text or JSON envelope)
+  memory:get                 Batch-fetch full memory entries by id (CLI twin of the
+                             memory_get MCP tool). Usage: memory:get <id> [<id> ...] [--format text|json]
   linked-projects:list       List opted-in IDE-attached sibling repos (path · detected_via · large)
                              Flags: --all (show undecided too), --format json
   memory:signal              Append a provisional intake signal (memory proposal)
   memory:hash                Hash a memory entry (YAML or JSON stdin)
   memory:check               Validate memory YAML schema + staleness
   memory:check-proposal      Run the admission gate on a memory proposal
+  memory:learn               Aggregate memory intake signals into the local learning
+                             sidecar (read-only; --write to emit). Usage: memory:learn [--intake-dir DIR]
+                             [--out-dir DIR] [--now ISO] [--write] [--format text|json]
+  analytics                  Local-only workspace analytics (emit|show|prune|migrate).
+                             Usage: analytics show [--window 30d|7d|24h] · analytics prune
+  knowledge                  Global knowledge-card store (list|show|trace|forget|promote|
+                             validate|lead-check|purge). Usage: knowledge list [--json]
   proposal:check             Validate a learning/skill/rule proposal markdown
   refine-ticket:detect       Run the deterministic refine-ticket detection helper
   chat-history:hook          Platform hook entry point (read JSON from stdin)
@@ -305,8 +317,12 @@ Examples (Tier 2):
   ./agent-config hooks:install
   ./agent-config hooks:replay --platform augment --event post_tool_use --payload post_tool_use --json
   ./agent-config memory:lookup --types domain-invariants --key billing
+  ./agent-config memory:get a1-crosshost-subagent-degradation
   ./agent-config memory:signal --type architecture-decision --path src/Foo.php --body "…"
   ./agent-config memory:check --path agents/memory
+  ./agent-config memory:learn --format json
+  ./agent-config code-graph detect
+  ./agent-config code-graph query <symbol>
   ./agent-config refine-ticket:detect ticket-body.txt
   ./agent-config telemetry:status
   ./agent-config telemetry:status --format json
@@ -464,6 +480,15 @@ cmd_benchmark() {
   exec_ts "$script" "$@"
 }
 
+# `agent-config code-graph` — deterministic code-graph engine (ADR-124,
+# Class A). Delegates 1:1 to the engine CLI's own subcommand dispatch
+# (build|validate|detect|query|explain|affected|path); no re-parsing here.
+cmd_code_graph() {
+  local script
+  script="$(resolve_script "src/scripts/code_graph/cli.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_mcp_check() {
   local script
   script="$(resolve_script "src/scripts/mcp_render.ts")"
@@ -480,6 +505,13 @@ cmd_mcp_setup() {
 # package (PACKAGE_ROOT/src/scripts/mcp_server/) as a TypeScript module run
 # via tsx — no Python venv / SDK install any more (the runtime is Node/tsx).
 cmd_mcp_run() {
+  # Precompiled bundle first (road-to-credible-install Phase 1 tsx sweep):
+  # one node start, no tsx in the runtime tree. tsx path is the dev-tree
+  # fallback only.
+  local server_bundle="$PACKAGE_ROOT/dist/mcp/server.mjs"
+  if [[ -f "$server_bundle" ]]; then
+    exec node "$server_bundle" "$@"
+  fi
   local server_main="$PACKAGE_ROOT/src/scripts/mcp_server/__main__.ts"
   if [[ ! -f "$server_main" ]]; then
     echo "❌  agent-config: MCP server module not found at $server_main" >&2
@@ -551,6 +583,43 @@ cmd_memory_lookup() {
   exec_ts "$script" "$@"
 }
 
+# `agent-config memory:get` — CLI twin of the `memory_get` MCP tool
+# (batch full-entry fetch by id). Package-internal handler
+# (src/scripts/_cli/cmd_memory_get.ts) reuses `memory_get_v1` from
+# src/scripts/memory_lookup.ts — no separate resolve needed, same
+# direct-PACKAGE_ROOT pattern as cmd_export / cmd_sync / cmd_validate.
+cmd_memory_get() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_memory_get.ts" "$@"
+}
+
+# `agent-config memory:learn` — aggregate the memory intake signal log
+# into the local, gitignored learning sidecar (road-to-retrieval-
+# substrate-hardening B3). Read-only by default (the sidecar's own
+# default); `--write` emits `.agent-learning.json` + `LESSONS.md`.
+cmd_memory_learn() {
+  local script
+  script="$(resolve_script "src/scripts/learning_sidecar.ts")" || return 1
+  exec_ts "$script" "$@"
+}
+
+# `agent-config analytics` — local-only workspace analytics
+# (docs/contracts/local-analytics.md). Delegates 1:1 to the module's own
+# subcommand dispatch (emit|show|prune|migrate|decrypt-all|rekey).
+cmd_analytics() {
+  local script
+  script="$(resolve_script "src/cli/python/workspace_analytics.ts")" || return 1
+  exec_ts "$script" "$@"
+}
+
+# `agent-config knowledge` — file-first global knowledge-card store
+# (ADR-100). Delegates 1:1 to the store CLI's own subcommand dispatch
+# (list|show|trace|forget|promote|validate|lead-check|purge).
+cmd_knowledge() {
+  local script
+  script="$(resolve_script "src/scripts/knowledge_global_cli.ts")" || return 1
+  exec_ts "$script" "$@"
+}
+
 cmd_linked_projects_list() {
   local script
   script="$(resolve_script "src/scripts/linked_projects_list.ts")" || return 1
@@ -630,6 +699,13 @@ cmd_context_hygiene_hook() {
 }
 
 cmd_dispatch_hook() {
+  # Hook hot path (road-to-credible-install Phase 1): prefer the precompiled
+  # single-process bundle — one node start, concerns in-process, no tsx.
+  # Fallback to the tsx path only on a stale dev tree without dist/.
+  local bundle="$PACKAGE_ROOT/dist/hooks/dispatch.js"
+  if [[ -f "$bundle" ]]; then
+    exec node "$bundle" "$@"
+  fi
   exec_hook "src/scripts/hooks/dispatch_hook" "$@"
 }
 
@@ -1072,6 +1148,7 @@ main() {
     affected)                cmd_affected "$@" ;;
     graph-explain)           cmd_graph_explain "$@" ;;
     benchmark)               cmd_benchmark "$@" ;;
+    code-graph)              cmd_code_graph "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;
@@ -1083,11 +1160,15 @@ main() {
     implement-ticket)        cmd_implement_ticket "$@" ;;
     work)                    cmd_work "$@" ;;
     memory:lookup)           cmd_memory_lookup "$@" ;;
+    memory:get)              cmd_memory_get "$@" ;;
     linked-projects:list)    cmd_linked_projects_list "$@" ;;
     memory:signal)           cmd_memory_signal "$@" ;;
     memory:hash)             cmd_memory_hash "$@" ;;
     memory:check)            cmd_memory_check "$@" ;;
     memory:check-proposal)   cmd_memory_check_proposal "$@" ;;
+    memory:learn)            cmd_memory_learn "$@" ;;
+    analytics)               cmd_analytics "$@" ;;
+    knowledge)               cmd_knowledge "$@" ;;
     proposal:check)          cmd_proposal_check "$@" ;;
     refine-ticket:detect)    cmd_refine_ticket_detect "$@" ;;
     chat-history:hook)       cmd_chat_history_hook "$@" ;;

package/src/scripts/_lib/auto_dispatch.corpus.test.ts

@@ -15,7 +15,13 @@
  */
 import { describe, expect, it } from 'vitest';
 
-import { classifyTask, type ActivationInputs, type TaskSignals } from './auto_dispatch.js';
+import {
+    classifyLookup,
+    classifyTask,
+    type ActivationInputs,
+    type LookupClass,
+    type TaskSignals,
+} from './auto_dispatch.js';
 
 const ON: ActivationInputs = { enabled: true, auto: 'on', subagent_spawn: true };
 
@@ -85,3 +91,60 @@ describe('parallelizable classifier — corpus recall', () => {
         }
     });
 });
+
+/**
+ * Lookup-class corpus (L0 — road-to-lean-agent-init Phase 1). The first four
+ * entries are the live-observed 2026-07-28 task shapes that burned ~1.21M
+ * subagent tokens; each must route to a primitive, never a spawn. The
+ * negative controls are non-lookup tasks that must escalate unchanged.
+ */
+const LOOKUP_CORPUS: Array<{ id: string; text: string; expect: LookupClass | null }> = [
+    // ── the four observed shapes (live evidence, 2026-07-28 session) ──
+    { id: 'lk-01', text: 'Confirming ExternalApiProviderEnum definition location', expect: 'definition' },
+    { id: 'lk-02', text: 'Confirming GWInput import call sites', expect: 'references' },
+    { id: 'lk-03', text: 'Running check_enforcement_coverage report', expect: 'report-run' },
+    { id: 'lk-04', text: 'Probing candidate strings with tsx', expect: 'string-existence' },
+    // ── generalizations of the same shapes ──
+    { id: 'lk-05', text: 'Where is classifyTask defined?', expect: 'definition' },
+    { id: 'lk-06', text: 'Who calls readOrchestrationMetrics across the repo?', expect: 'references' },
+    { id: 'lk-07', text: 'Does the string "lean-init-2026" exist anywhere in src/?', expect: 'string-existence' },
+    { id: 'lk-08', text: 'Run the roadmap:progress-check report and summarize', expect: 'report-run' },
+    { id: 'lk-09', text: 'Find all usages of InferredTier in tests', expect: 'references' },
+    { id: 'lk-10', text: 'Locate the enum that lists the dispatch actions', expect: 'definition' },
+    // ── negative controls — must escalate, never route to a primitive ──
+    { id: 'lk-n1', text: 'Refactor the auth middleware to use the new session store', expect: null },
+    { id: 'lk-n2', text: 'Fix the failing corpus test and explain the root cause', expect: null },
+    { id: 'lk-n3', text: 'Design a migration plan for the audit schema', expect: null },
+    { id: 'lk-n4', text: 'Review this diff for security issues', expect: null },
+];
+
+describe('lookup-class routing — corpus recall + FP=0 (lean-init L0)', () => {
+    for (const c of LOOKUP_CORPUS) {
+        it(`${c.id}: ${c.text}`, () => {
+            const r = classifyLookup(c.text);
+            expect(r.lookup_class).toBe(c.expect);
+            expect(r.route).toBe(c.expect === null ? 'escalate' : 'primitive');
+        });
+    }
+
+    it('recall on the four live-observed shapes is 4/4', () => {
+        const observed = LOOKUP_CORPUS.filter((c) => c.id.startsWith('lk-0') && Number(c.id.slice(3)) <= 4);
+        expect(observed).toHaveLength(4);
+        for (const c of observed) {
+            expect(classifyLookup(c.text).route).toBe('primitive');
+        }
+    });
+
+    it('false-positive rate is 0 — no negative control routes to a primitive', () => {
+        for (const c of LOOKUP_CORPUS.filter((x) => x.expect === null)) {
+            expect(classifyLookup(c.text).route).toBe('escalate');
+        }
+    });
+
+    it('unknown resolves to escalate with a non-degradation reason', () => {
+        const r = classifyLookup('Do something clever with the codebase');
+        expect(r.route).toBe('escalate');
+        expect(r.primitive).toBeNull();
+        expect(r.reason).toContain('never down-guessed');
+    });
+});