@event4u/agent-config 14.10.0 → 14.12.0

package/src/scripts/lint_skill_trigger_corpus.ts

@@ -0,0 +1,349 @@
+#!/usr/bin/env tsx
+/**
+ * `lint_skill_trigger_corpus` — the routing-matrix corpus DISCIPLINE, applied
+ * to the skill corpus that already exists.
+ *
+ * `road-to-routing-assurance` Phase 2.1, as re-scoped by the AI council
+ * (2/2 convergent, recorded at the step): the roadmap's literal text said "one
+ * YAML per skill", which would have created a THIRD corpus surface next to the
+ * 74 `queries`-shaped and 2 `should_trigger`-shaped JSON files already in the
+ * tree. The step's *verify* condition is format-agnostic — "a corpus file
+ * failing the discipline is rejected by a schema check, not by review" — so the
+ * discipline is enforced on the existing JSON and the amendment is recorded
+ * rather than performed silently.
+ *
+ * ## Three separate contracts, and this gate owns exactly one
+ *
+ * The council's sharpest point: serialization, case semantics, and coverage are
+ * three different questions and choosing JSON answers only the first.
+ *
+ *   - **Coverage** — how many skills have a corpus at all — is
+ *     `check_routing_coverage`'s ratio, and stays there.
+ *   - **Discipline** — is each covered skill's corpus adequate — is this gate.
+ *   - **Semantics** — is a `trigger: false` case a genuine NEAR-MISS rather
+ *     than an unrelated negative — is NOT machine-decidable and this gate does
+ *     not pretend otherwise. It counts negatives; whether they are near enough
+ *     to be informative stays a human read, and saying so is cheaper than a
+ *     heuristic that would be wrong quietly.
+ *
+ * ## Why language is metadata, never detection
+ *
+ * The discipline asks for at least one German positive. A gate that *detected*
+ * German would be a heuristic in a file called a schema check: it would pass a
+ * German-looking English sentence and fail a short German one, and its
+ * failures would be unactionable. So German is declared — `"language": "de"`
+ * on the case — and declaration is checked. Forward-only, because zero of the
+ * 76 existing files carry the field: requiring it everywhere today would red
+ * 76 files for a field that did not exist when they were written.
+ *
+ * ## Forward-only, in two different senses
+ *
+ * The COUNT discipline (>=3 positives, >=2 near-misses) applies to every file
+ * today: exactly two files fail it, and both are listed as grandfathered by
+ * name rather than by a numeric baseline, so a third failure cannot hide inside
+ * a count. The LANGUAGE discipline applies only to files the diff adds or
+ * changes.
+ *
+ * Exit codes: 0 = clean · 1 = a discipline violation · 2 = dead scope.
+ */
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { type SelfTestCase, runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const HERE = fileURLToPath(import.meta.url);
+const REAL_REPO_ROOT = path.resolve(path.dirname(HERE), '..', '..');
+const REPO_ROOT = process.env['LINT_SKILL_TRIGGER_CORPUS_ROOT'] ?? REAL_REPO_ROOT;
+
+export const MIN_POSITIVES = 3;
+export const MIN_NEAR_MISSES = 2;
+
+/**
+ * The two corpus files that predate the discipline, named rather than counted.
+ *
+ * A numeric baseline would let a third failure arrive while the number stayed
+ * put if one of these were fixed in the same change. Names cannot do that.
+ */
+export const GRANDFATHERED = new Set(['brand-asset-generation', 'estimate-ticket']);
+
+export interface CorpusStats {
+    unit: string;
+    positives: number;
+    nearMisses: number;
+    germanPositives: number;
+    /** True when at least one case declares a language at all. */
+    declaresLanguage: boolean;
+}
+
+export interface Violation {
+    unit: string;
+    rule: 'positives' | 'near-misses' | 'german' | 'malformed';
+    message: string;
+}
+
+interface RawCase {
+    q?: string;
+    trigger?: boolean;
+    language?: string;
+}
+
+/** Read one corpus file into counts, across both shapes that exist. */
+export function statsFor(unit: string, file: string): CorpusStats {
+    const doc = JSON.parse(fs.readFileSync(file, 'utf-8')) as {
+        queries?: RawCase[];
+        should_trigger?: string[];
+        should_not_trigger?: string[];
+    };
+    const queries = doc.queries ?? [];
+    let positives = queries.filter((q) => q.trigger === true).length;
+    let nearMisses = queries.filter((q) => q.trigger === false).length;
+    positives += (doc.should_trigger ?? []).length;
+    nearMisses += (doc.should_not_trigger ?? []).length;
+    return {
+        unit,
+        positives,
+        nearMisses,
+        germanPositives: queries.filter((q) => q.trigger === true && q.language === 'de').length,
+        declaresLanguage: queries.some((q) => typeof q.language === 'string'),
+    };
+}
+
+export function judge(s: CorpusStats, requireLanguage: boolean): Violation[] {
+    const out: Violation[] = [];
+    if (GRANDFATHERED.has(s.unit)) return out;
+    if (s.positives < MIN_POSITIVES) {
+        out.push({
+            unit: s.unit,
+            rule: 'positives',
+            message: `${String(s.positives)} positive(s), the discipline asks for ${String(MIN_POSITIVES)}`,
+        });
+    }
+    if (s.nearMisses < MIN_NEAR_MISSES) {
+        out.push({
+            unit: s.unit,
+            rule: 'near-misses',
+            message: `${String(s.nearMisses)} near-miss(es), the discipline asks for ${String(MIN_NEAR_MISSES)}`,
+        });
+    }
+    if (requireLanguage && s.germanPositives < 1) {
+        out.push({
+            unit: s.unit,
+            rule: 'german',
+            message:
+                'no positive declares `"language": "de"`. Declared, never detected — ' +
+                'a detector would pass German-looking English and fail short German',
+        });
+    }
+    return out;
+}
+
+/** Corpus files the diff added or modified, relative to a base ref. */
+export function changedUnits(root: string, base: string): Set<string> {
+    let out = '';
+    try {
+        out = execFileSync('git', ['diff', '--name-only', `${base}...HEAD`], {
+            cwd: root,
+            encoding: 'utf-8',
+            // Silenced deliberately: outside a repo (a self-test fixture, a
+            // tarball install) git prints its whole usage text to stderr, and
+            // a gate that dumps a manual page on a path it already handles is
+            // noise a reader has to learn to ignore.
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    } catch {
+        return new Set();
+    }
+    const units = new Set<string>();
+    for (const line of out.split('\n')) {
+        const m = /^src\/skills\/([^/]+)\/evals\/triggers\.json$/.exec(line.trim());
+        if (m?.[1] !== undefined) units.add(m[1]);
+    }
+    return units;
+}
+
+export interface Result {
+    violations: Violation[];
+    scanned: number;
+    ledger: GateLedger;
+}
+
+export function evaluate(root = REPO_ROOT, base = 'origin/main'): Result {
+    const dir = path.join(root, 'src', 'skills');
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        throw new DeadScopeError(
+            'lint_skill_trigger_corpus',
+            'src/skills is unreadable — a corpus gate with no corpus passes every tree.',
+        );
+    }
+    const changed = changedUnits(root, base);
+    const ledger = new GateLedger('lint_skill_trigger_corpus');
+    const violations: Violation[] = [];
+    let scanned = 0;
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const file = path.join(dir, e.name, 'evals', 'triggers.json');
+        if (!fs.existsSync(file)) continue;
+        scanned += 1;
+        ledger.plan(e.name);
+        let own: Violation[];
+        try {
+            own = judge(statsFor(e.name, file), changed.has(e.name));
+        } catch {
+            own = [{ unit: e.name, rule: 'malformed', message: 'is not parseable JSON' }];
+        }
+        if (own.length === 0) ledger.complete(e.name);
+        else ledger.fail(e.name, own.map((v) => `[${v.rule}] ${v.message}`).join(' · '));
+        violations.push(...own);
+    }
+    if (scanned === 0) {
+        throw new DeadScopeError(
+            'lint_skill_trigger_corpus',
+            'zero corpus files found under src/skills/*/evals/triggers.json — 76 exist ' +
+                'in the shipped tree, so an empty scan is a moved root, not a clean one.',
+        );
+    }
+    return { violations, scanned, ledger };
+}
+
+export function selfTest(): number {
+    const os = process.env['TMPDIR'] ?? '/tmp';
+    const tmp = fs.mkdtempSync(path.join(os, 'lstc-'));
+    const mkRoot = (unit: string, body: unknown): string => {
+        const root = fs.mkdtempSync(path.join(tmp, 'repo-'));
+        const d = path.join(root, 'src', 'skills', unit, 'evals');
+        fs.mkdirSync(d, { recursive: true });
+        fs.writeFileSync(path.join(d, 'triggers.json'), JSON.stringify(body));
+        return root;
+    };
+    const run = (root: string): number => {
+        process.env['LINT_SKILL_TRIGGER_CORPUS_ROOT'] = root;
+        try {
+            return runGateCli(REAL_REPO_ROOT, 'src/scripts/lint_skill_trigger_corpus.ts', [], root);
+        } finally {
+            delete process.env['LINT_SKILL_TRIGGER_CORPUS_ROOT'];
+        }
+    };
+    const good = {
+        queries: [
+            { q: 'a', trigger: true },
+            { q: 'b', trigger: true },
+            { q: 'c', trigger: true },
+            { q: 'd', trigger: false },
+            { q: 'e', trigger: false },
+        ],
+    };
+    const cases: SelfTestCase[] = [
+        {
+            name: 'a compliant corpus is accepted',
+            expect: 'accept',
+            run: () => run(mkRoot('probe', good)),
+        },
+        {
+            name: 'the should_trigger shape is read, not silently skipped',
+            expect: 'accept',
+            run: () =>
+                run(
+                    mkRoot('probe', {
+                        should_trigger: ['a', 'b', 'c'],
+                        should_not_trigger: ['d', 'e'],
+                    }),
+                ),
+        },
+        {
+            name: 'a grandfathered unit stays accepted at zero cases',
+            expect: 'accept',
+            run: () => run(mkRoot('estimate-ticket', { queries: [] })),
+        },
+        {
+            name: 'too few positives is rejected',
+            expect: 'reject',
+            run: () => run(mkRoot('probe', { queries: good.queries.slice(1) })),
+        },
+        {
+            name: 'too few near-misses is rejected',
+            expect: 'reject',
+            run: () => run(mkRoot('probe', { queries: good.queries.slice(0, 4) })),
+        },
+        {
+            name: 'a malformed corpus file is rejected, not skipped',
+            expect: 'reject',
+            run: () => {
+                const root = mkRoot('probe', good);
+                fs.writeFileSync(
+                    path.join(root, 'src', 'skills', 'probe', 'evals', 'triggers.json'),
+                    '{ not json',
+                );
+                return run(root);
+            },
+        },
+        {
+            name: 'a scan root with no corpus at all exits 2 rather than reporting clean',
+            expect: 'reject',
+            run: () => {
+                const root = fs.mkdtempSync(path.join(tmp, 'empty-'));
+                fs.mkdirSync(path.join(root, 'src', 'skills'), { recursive: true });
+                return run(root);
+            },
+        },
+    ];
+    try {
+        return runSelfTest({
+            gate: 'lint_skill_trigger_corpus',
+            cases,
+            minCases: 7,
+            minRejectCases: 4,
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: string[] = process.argv.slice(2), root = REPO_ROOT): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const quiet = argv.includes('--quiet');
+    let r: Result;
+    try {
+        r = evaluate(root);
+        reportScanned({
+            gate: 'lint_skill_trigger_corpus',
+            scanned: r.scanned,
+            units: 'skill corpus file(s)',
+            roots: ['src/skills/*/evals/triggers.json'],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+    r.ledger.report(quiet ? () => undefined : process.stdout.write.bind(process.stdout));
+    if (r.violations.length === 0) {
+        process.stdout.write(
+            `lint_skill_trigger_corpus: ${String(r.scanned)} corpus file(s) hold the discipline ` +
+                `(>=${String(MIN_POSITIVES)} positives, >=${String(MIN_NEAR_MISSES)} near-misses; ` +
+                `${String(GRANDFATHERED.size)} grandfathered by name).\n`,
+        );
+        return 0;
+    }
+    for (const v of r.violations) {
+        process.stderr.write(`  ${v.unit}: [${v.rule}] ${v.message}\n`);
+    }
+    process.stderr.write(
+        `${String(r.violations.length)} discipline violation(s). Add the missing cases — ` +
+            'widening GRANDFATHERED is a defect, not a fix.\n',
+    );
+    return 1;
+}
+
+if (path.resolve(process.argv[1] ?? '') === path.resolve(HERE)) {
+    process.exit(main());
+}

package/src/scripts/lint_spawn_payload.ts

@@ -4,7 +4,19 @@
  * ("NEVER BULK-DUMP CONTEXT INTO A SUBAGENT") deterministic
  * (road-to-lean-agent-init Phase 3).
  *
- * Scans two surfaces for spawn-brief-shaped payloads: (a) JSON fixtures
+ * WIDENED 2026-08-23 (road-to-review-independence step 0.4) to a THIRD surface: the
+ * SHIPPED prompt templates under `src/skills/subagent-orchestration/prompts/`. The gate
+ * made the "NEVER BULK-DUMP CONTEXT INTO A SUBAGENT" Iron Law deterministic over test
+ * fixtures and golden transcripts — i.e. over the places a violation is *simulated* —
+ * while the templates that actually construct a spawn brief in production sat outside
+ * it. Eight diff-payload placeholder sites across five of those files, plus two further
+ * placeholder shapes in two more, were unscanned.
+ *
+ * Still WARN-ONLY, exactly as before: this surface is prose with placeholders, and a
+ * placeholder is not yet a payload. What the widening buys is that a template growing a
+ * bulk-dump shape is now visible rather than invisible.
+ *
+ * Scans three surfaces for spawn-brief-shaped payloads: (a) JSON fixtures
  * matching `tests/fixtures/**\/*spawn*.json`; (b) fenced code blocks in
  * `tests/reasoning-layer-eval/golden-transcripts/*.md` that either parse as
  * JSON with both a `task` and a `knowledge_refs` key, or are introduced by
@@ -41,7 +53,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
@@ -219,6 +231,22 @@ function scanRepo(repoRoot: string): Finding[] {
         }
     }
 
+    // The shipped templates — step 0.4's surface. Counted the same way as the other two
+    // (the walk, not the filter), so "no violations" and "no files read" stay
+    // distinguishable; that distinction is why `scanned` is incremented before any
+    // content test in all three loops.
+    const templatesDir = path.join(repoRoot, 'src', 'skills', 'subagent-orchestration', 'prompts');
+    if (fs.existsSync(templatesDir)) {
+        for (const entry of fs.readdirSync(templatesDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                scanned += 1;
+                findings.push(
+                    ...scanMarkdownTranscript(path.join(templatesDir, entry.name), repoRoot),
+                );
+            }
+        }
+    }
+
     const transcriptsDir = path.join(repoRoot, 'tests', 'reasoning-layer-eval', 'golden-transcripts');
     if (fs.existsSync(transcriptsDir)) {
         for (const entry of fs.readdirSync(transcriptsDir, { withFileTypes: true })) {
@@ -229,11 +257,20 @@ function scanRepo(repoRoot: string): Finding[] {
         }
     }
 
-    assertScanned({
+    // `reportScanned`, not `assertScanned`: step 0.4's verify compares the scanned count
+    // against the pre-change one, and a count the gate never prints cannot be compared.
+    // The helper's own docstring makes the same point — "a count only visible without
+    // `--quiet` is not a count, since CI passes `--quiet`" — so the line goes to stdout
+    // unconditionally.
+    reportScanned({
         gate: 'lint_spawn_payload',
         scanned,
-        units: 'fixture / transcript file(s)',
-        roots: ['tests/fixtures', 'tests/reasoning-layer-eval/golden-transcripts'],
+        units: 'fixture / transcript / template file(s)',
+        roots: [
+            'tests/fixtures',
+            'tests/reasoning-layer-eval/golden-transcripts',
+            'src/skills/subagent-orchestration/prompts',
+        ],
     });
     return findings;
 }

package/src/scripts/lint_symptom_intake.ts

@@ -30,6 +30,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { asOf } from './_lib/as_of.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
@@ -132,7 +133,7 @@ function _now(): Date {
         const parsed = Date.parse(`${flag.slice('--now='.length)}T00:00:00Z`);
         if (!Number.isNaN(parsed)) return new Date(parsed);
     }
-    return new Date();
+    return asOf();
 }
 
 function main(): number {

package/src/scripts/mcp_parity_smoke.ts

@@ -420,6 +420,15 @@ async function _run_http_leg(target: string): Promise<number> {
     return failed;
 }
 
+/**
+ * The turnkey stdio surface's tool names, code-point sorted and joined.
+ * Kept as a literal rather than imported from `src/cli/` so this maintainer
+ * script does not take a build dependency on the CLI bundle; the CLI-side
+ * source of truth is `LITE_TOOLS` in `src/cli/mcp/dispatch.ts`, and
+ * `tests/scripts/mcp_lite_tools.test.ts` pins that side.
+ */
+const LITE_TOOL_NAMES_EXPECTED = 'read_skill,suggest_skill_for_task';
+
 /** ALL skill+command prompt metas (uncapped — for full-set parity). */
 function _local_prompts_all(): Record<string, unknown>[] {
     const [prompts] = load_all_prompts();
@@ -438,7 +447,8 @@ function _local_resources_all(): Record<string, unknown>[] {
  * Compares the FULL SUBSET the turnkey surface serves (skill/command prompts,
  * rule/guideline resources — contexts excluded by design) via cursor
  * pagination, on name/kind/uri keys, and asserts the read-only boundary
- * (`tools/list` empty). Skips with a note if the binary isn't built.
+ * (the two read-only discovery tools and nothing else). Skips with a note if
+ * the binary isn't built.
  */
 function _run_node_leg(cli: string): number {
     if (!_exists(cli)) {
@@ -473,13 +483,29 @@ function _run_node_leg(cli: string): number {
         _subset_resources(_normalize_resources({ resources: _local_resources_all() })),
         _subset_resources(_normalize_resources({ resources: nodeResources })),
     );
-    if (nodeTools.length > 0) {
+    // Phase 1.1 of `road-to-skill-delivery-over-mcp`: the turnkey surface now
+    // serves exactly two read-only discovery tools, and this leg is where risk 6
+    // ("two implementations diverge silently") stops being a claim. Both names
+    // are checked, not counted — a count would pass on the wrong pair.
+    //
+    // `suggest_skill_for_task` is shared with the kernel and both now compute
+    // their score through the single `src/shared/skillRanking.ts` formula.
+    // `read_skill` is lite-only and deliberately NARROWER than the kernel's
+    // `read_resource_body`: it resolves a skill NAME through the content tree's
+    // uri map and can reach nothing else.
+    const nodeToolNames = nodeTools
+        .map((t) => String(t.name ?? ''))
+        .sort(_cmpCodePoints)
+        .join(',');
+    if (nodeToolNames !== LITE_TOOL_NAMES_EXPECTED) {
         process.stdout.write(
-            `❌  node tools/list: expected empty (read-only), got ${nodeTools.length}\n`,
+            `❌  node tools/list: expected exactly [${LITE_TOOL_NAMES_EXPECTED}], got [${nodeToolNames}]\n`,
         );
         failed += 1;
     } else {
-        process.stdout.write('✅  node tools/list: empty (read-only, ADR-085)\n');
+        process.stdout.write(
+            `✅  node tools/list: ${LITE_TOOL_NAMES_EXPECTED} (read-only discovery, ADR-085 + Phase 1.1)\n`,
+        );
     }
     process.stdout.write(
         `${`${failed ? '' : 'node-stdio parity OK '}(${path.basename(cli)})`.trim()}\n`,

package/src/scripts/mcp_render.ts

@@ -13,6 +13,15 @@
  *     .windsurf/mcp.json                                     (in-project)
  *     ~/.config/claude-desktop/claude_desktop_config.json    (user, opt-in)
  *
+ * `.mcp.json` — Claude Code's project-scope config — is a CHECK-ONLY target
+ * (Phase 1.3 of `road-to-skill-delivery-over-mcp`). It is deliberately not
+ * rendered: the installer writes it with `merge_json_file`, which touches only
+ * this package's own server key and records it in `agents/installed-tools.lock`
+ * so uninstall subtracts exactly that key. Rendering it here would overwrite a
+ * file the consumer also edits and silently delete servers they added by hand.
+ * `--check` therefore asserts CONTAINMENT of our entry rather than equality with
+ * a rendering, and says so on the same line.
+ *
  * All targets use the same `mcpServers` top-level key. The source file uses
  * `servers` to keep our internal schema stable if a downstream format ever
  * diverges.
@@ -40,6 +49,36 @@ export function default_project_root(): string {
     return fs.realpathSync(process.cwd());
 }
 
+/** The one entry `.mcp.json` must contain. Mirrors `install.ts:MCP_SERVER_KEY`. */
+export const MCP_JSON_SERVER_KEY = 'agent-config';
+
+/** Claude Code's project-scope MCP config. Checked here, written by the installer. */
+export function claude_code_mcp_target(projectRoot: string): string {
+    return path.join(projectRoot, '.mcp.json');
+}
+
+/**
+ * Does `.mcp.json` carry this package's server entry?
+ *
+ * `absent` is a distinct verdict from `missing-entry` on purpose: absent means
+ * the installer has not run for `claude-code` here, which is a hint; a file that
+ * exists WITHOUT our key means something removed it, which is a failure.
+ */
+export function check_mcp_json(projectRoot: string): 'absent' | 'ok' | 'missing-entry' | 'unreadable' {
+    const target = claude_code_mcp_target(projectRoot);
+    if (!fs.existsSync(target)) return 'absent';
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(target, 'utf-8'));
+    } catch {
+        return 'unreadable';
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return 'unreadable';
+    const servers = (parsed as Record<string, unknown>)['mcpServers'];
+    if (servers === null || typeof servers !== 'object' || Array.isArray(servers)) return 'missing-entry';
+    return MCP_JSON_SERVER_KEY in (servers as Record<string, unknown>) ? 'ok' : 'missing-entry';
+}
+
 export function in_project_targets(projectRoot: string): Record<string, string> {
     return {
         cursor: path.join(projectRoot, '.cursor', 'mcp.json'),
@@ -274,7 +313,33 @@ function cmd_check(args: ParsedArgs): number {
         return 1;
     }
     process.stdout.write('✅  All MCP targets match source.\n');
-    return 0;
+    return _report_mcp_json(projectRoot);
+}
+
+/**
+ * The `.mcp.json` leg of `--check`. Additive: it can only turn a green run red
+ * when the file EXISTS and has lost our entry, never on a fresh tree where the
+ * installer has not run.
+ */
+function _report_mcp_json(projectRoot: string): number {
+    const verdict = check_mcp_json(projectRoot);
+    const rel = path.relative(projectRoot, claude_code_mcp_target(projectRoot)) || '.mcp.json';
+    if (verdict === 'ok') {
+        process.stdout.write(`✅  ${rel} carries the \`${MCP_JSON_SERVER_KEY}\` server (containment, not equality).\n`);
+        return 0;
+    }
+    if (verdict === 'absent') {
+        process.stdout.write(
+            `ℹ️   ${rel} not present — written by \`agent-config install\` for the ` +
+                'claude-code tool, never rendered from mcp.json.\n',
+        );
+        return 0;
+    }
+    process.stderr.write(
+        `❌  ${rel} exists but does not carry the \`${MCP_JSON_SERVER_KEY}\` server ` +
+            `(${verdict}). Re-run \`agent-config install\`.\n`,
+    );
+    return 1;
 }
 
 class ArgError extends Error {}