peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/dispatch/test-tool-detection.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Slice 2026-06-24-test-tool-detection-injection.
+ *
+ * The Test Tool Detection block is prepended to every sub-agent prompt
+ * dispatched by peaks-loop (both the single-dispatch chokepoint in
+ * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
+ * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
+ * to read `package.json#scripts.test` first and use the project-local
+ * runner — never `npx <runner>` — so it cannot bypass the lockfile or
+ * spawn a network-bound tool call.
+ *
+ * Why a static constant (not a per-call detector):
+ *  1. Predictable byte budget — the block is part of PROMPT_LIMIT_BYTES
+ *     accounting (see dispatch-commands.ts line 113), and the size must
+ *     be stable across calls.
+ *  2. I/O-free — dispatch is a hot path; reading package.json here would
+ *     add a filesystem hit per dispatch and run before the LLM has any
+ *     context to act on the result.
+ *  3. LLM does runtime lookup — the block itself instructs the sub-agent
+ *     to introspect `package.json#scripts.test` (or `peaks test --json`)
+ *     at run time, so the LLM gets the resolved framework + argv with
+ *     its full context. The dispatch CLI just primes the instruction.
+ *
+ * Why every sub-agent gets the block (Karpathy #2 Simplicity First):
+ *  the rule is machine-injected, not a prompt ritual. The LLM cannot
+ *  "remove the redundancy" of a test-tool-detection instruction because
+ *  the dispatch CLI always prepends it. This is a guarantee, not a
+ *  suggestion.
+ */
+export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\n## Test Scope (mandatory)\n\nThe dispatched test command MUST be **scoped** to a single file or pattern. An unscoped `./node_modules/.bin/vitest run` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:\n\n- **scoped**    \u2192 `./node_modules/.bin/vitest run tests/unit/foo.test.ts` (or any explicit file/pattern)\n- **intentional full run** \u2192 prefix with the explicit opt-in token `PEAKS_FULL_TEST=1` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.\n- **refused**   \u2192 bare `./node_modules/.bin/vitest run` (no argument after `run`) without the opt-in token.\n\n`pnpm test` / `pnpm test:unit` / `pnpm test:cli` / `pnpm test:integration` and any repo-defined `test*` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
+/**
+ * Pure helper that returns the block. Exists as a function (not just an
+ * exported constant) so future variants can take a runtime parameter
+ * (e.g. projectRoot for context) without churning every call site.
+ */
+export declare function formatTestToolDetection(): string;
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-4.1 / AC-4.2) —
+ * pure scope classifier. Returns a typed result so callers (the
+ * dispatch prompt template, future test-runner bridges) can decide
+ * whether the command is allowed, refused, or requires the explicit
+ * opt-in.
+ *
+ *   - 'scoped'    — the command names a file/pattern after `run`
+ *   - 'opt-in'    — the user/LLM set PEAKS_FULL_TEST=1 to override
+ *   - 'refused'   — bare `vitest run` with no path and no opt-in
+ *   - 'unsupported' — the command is not a vitest/jest/mocha run at
+ *     all (the static block does not gate it; the caller decides)
+ *
+ * Pure: no I/O, no process spawn, no env reads. The dispatcher
+ * passes `env` explicitly so the test seam can assert behavior
+ * without mutating process.env.
+ */
+export type TestScopeClassification = 'scoped' | 'opt-in' | 'refused' | 'unsupported';
+export interface TestScopeDecision {
+    readonly classification: TestScopeClassification;
+    readonly reason: string;
+    readonly extractedPath: string | null;
+}
+export declare function classifyTestCommand(command: string, env?: Readonly<Record<string, string | undefined>>): TestScopeDecision;

package/dist/services/dispatch/test-tool-detection.js

@@ -0,0 +1,126 @@
+/**
+ * Slice 2026-06-24-test-tool-detection-injection.
+ *
+ * The Test Tool Detection block is prepended to every sub-agent prompt
+ * dispatched by peaks-loop (both the single-dispatch chokepoint in
+ * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
+ * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
+ * to read `package.json#scripts.test` first and use the project-local
+ * runner — never `npx <runner>` — so it cannot bypass the lockfile or
+ * spawn a network-bound tool call.
+ *
+ * Why a static constant (not a per-call detector):
+ *  1. Predictable byte budget — the block is part of PROMPT_LIMIT_BYTES
+ *     accounting (see dispatch-commands.ts line 113), and the size must
+ *     be stable across calls.
+ *  2. I/O-free — dispatch is a hot path; reading package.json here would
+ *     add a filesystem hit per dispatch and run before the LLM has any
+ *     context to act on the result.
+ *  3. LLM does runtime lookup — the block itself instructs the sub-agent
+ *     to introspect `package.json#scripts.test` (or `peaks test --json`)
+ *     at run time, so the LLM gets the resolved framework + argv with
+ *     its full context. The dispatch CLI just primes the instruction.
+ *
+ * Why every sub-agent gets the block (Karpathy #2 Simplicity First):
+ *  the rule is machine-injected, not a prompt ritual. The LLM cannot
+ *  "remove the redundancy" of a test-tool-detection instruction because
+ *  the dispatch CLI always prepends it. This is a guarantee, not a
+ *  suggestion.
+ */
+export const TEST_TOOL_DETECTION_BLOCK = `## Test Tool Detection (mandatory)
+
+Before running any test, read \`package.json#scripts.test\` to identify the project's test framework. Use the project-local runner — do NOT invoke \`npx <runner>\`:
+
+- **vitest** → \`./node_modules/.bin/vitest run <file>\` (or \`pnpm test -- <file>\`)
+- **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
+- **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
+
+## Test Scope (mandatory)
+
+The dispatched test command MUST be **scoped** to a single file or pattern. An unscoped \`./node_modules/.bin/vitest run\` (no path filter) is **refused** because the 483-file suite is one keystroke from a 36-minute wall clock:
+
+- **scoped**    → \`./node_modules/.bin/vitest run tests/unit/foo.test.ts\` (or any explicit file/pattern)
+- **intentional full run** → prefix with the explicit opt-in token \`PEAKS_FULL_TEST=1\` to override the scope gate. Use only for CI / release verification, never for routine verification during a slice.
+- **refused**   → bare \`./node_modules/.bin/vitest run\` (no argument after \`run\`) without the opt-in token.
+
+\`pnpm test\` / \`pnpm test:unit\` / \`pnpm test:cli\` / \`pnpm test:integration\` and any repo-defined \`test*\` script remain the **human / LLM direct path** and are not gated by this rule (PB-5).
+
+If unsure which framework the consumer project uses, run \`peaks test --json\` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command \`peaks test <file>\` already resolves the local binary for you (Windows-aware).`;
+/**
+ * Pure helper that returns the block. Exists as a function (not just an
+ * exported constant) so future variants can take a runtime parameter
+ * (e.g. projectRoot for context) without churning every call site.
+ */
+export function formatTestToolDetection() {
+    return TEST_TOOL_DETECTION_BLOCK;
+}
+export function classifyTestCommand(command, env = process.env) {
+    if (typeof command !== 'string') {
+        return {
+            classification: 'unsupported',
+            reason: 'command is not a string',
+            extractedPath: null
+        };
+    }
+    const trimmed = command.trim();
+    // Only vitest / jest / mocha runner invocations are in scope; other
+    // commands (e.g. node, curl) are out of the scope-rule's reach
+    // (PB-5: ordinary direct human project scripts are not gated).
+    const lower = trimmed.toLowerCase();
+    const isRunnerInvocation = /(?:\.\/node_modules\/\.bin\/|\b)(?:vitest|jest|mocha)\b/.test(lower);
+    if (!isRunnerInvocation) {
+        return {
+            classification: 'unsupported',
+            reason: 'command is not a vitest/jest/mocha runner invocation',
+            extractedPath: null
+        };
+    }
+    // Split into tokens. Quoted paths (e.g. "tests/unit/foo bar.test.ts")
+    // are preserved as a single token by the simple `match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)`
+    // approach; the static block does not need shell-level fidelity,
+    // only the existence of at least one non-flag, non-runner path
+    // token.
+    const tokens = trimmed.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+    // Find the runner token and look for arguments after it.
+    const runnerIdx = tokens.findIndex((t) => /(^|\/)(vitest|jest|mocha)(\.cmd|\.exe)?$/.test(t.toLowerCase()));
+    if (runnerIdx < 0) {
+        return {
+            classification: 'unsupported',
+            reason: 'runner token not found in command',
+            extractedPath: null
+        };
+    }
+    const after = tokens.slice(runnerIdx + 1);
+    // Strip flags (e.g. --config, --reporter, --coverage). A flag is
+    // any token starting with `-`. The path we care about is the first
+    // non-flag, non-runner, non-keyword token after the runner.
+    const PATH_KEYWORDS = new Set(['run', 'watch', 'test', 'c', 'ci', 'r', 'reporter', 't', 'u', 'coverage']);
+    const pathTokens = [];
+    for (const tok of after) {
+        if (tok.startsWith('-'))
+            continue;
+        if (PATH_KEYWORDS.has(tok.toLowerCase()))
+            continue;
+        pathTokens.push(tok);
+    }
+    if (pathTokens.length === 0) {
+        // No path at all. The opt-in token flips this to 'opt-in'.
+        if (env.PEAKS_FULL_TEST === '1' || env.PEAKS_FULL_TEST === 'true') {
+            return {
+                classification: 'opt-in',
+                reason: 'bare run command with PEAKS_FULL_TEST=1 opt-in',
+                extractedPath: null
+            };
+        }
+        return {
+            classification: 'refused',
+            reason: 'bare runner invocation with no path filter and no PEAKS_FULL_TEST opt-in',
+            extractedPath: null
+        };
+    }
+    return {
+        classification: 'scoped',
+        reason: `runner invocation scoped to ${pathTokens.length} path token(s)`,
+        extractedPath: pathTokens[0] ?? null
+    };
+}

package/dist/services/doc/doc-generator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * v2.15.0 follow-up — G7: documentation auto-generator.
+ *
+ * Two CLI surfaces:
+ *   1. `peaks doc generate-skill --from <code-path>` — produces a SKILL.md
+ *      skeleton by scanning a code directory for command exports,
+ *      with sections derived from JSDoc / signature.
+ *   2. `peaks doc changelog-suggest --since <git-ref>` — diffs
+ *      src/cli/commands/*.ts since the ref and emits a
+ *      "## [Unreleased]" block describing the changes.
+ *
+ * Both are pragmatic / 80% solutions; the goal is to make the operator's
+ * life easier, not to fully automate documentation.
+ */
+export interface SkillSection {
+    readonly heading: string;
+    readonly bullets: readonly string[];
+}
+export interface SkillDoc {
+    readonly name: string;
+    readonly description: string;
+    readonly sections: readonly SkillSection[];
+}
+/** Generate a SKILL.md skeleton from a directory of CLI command files. */
+export declare function generateSkillFromCommands(skillName: string, commandsDir: string): SkillDoc;
+/** Render SkillDoc as markdown. */
+export declare function renderSkillMarkdown(doc: SkillDoc): string;
+export interface ChangelogEntry {
+    readonly kind: 'feat' | 'fix' | 'docs' | 'refactor' | 'chore';
+    readonly subject: string;
+    readonly file: string;
+}
+/** Parse a single commit subject line into a ChangelogEntry. */
+export declare function parseCommitSubject(subject: string, file: string): ChangelogEntry;
+/** Run `git log` for the given ref range, return parsed entries. */
+export declare function gitLogSince(projectRoot: string, since: string): ChangelogEntry[];
+/** Group entries by kind + render a "## [Unreleased]" block. */
+export declare function suggestChangelog(entries: readonly ChangelogEntry[]): string;

package/dist/services/doc/doc-generator.js

@@ -0,0 +1,122 @@
+/**
+ * v2.15.0 follow-up — G7: documentation auto-generator.
+ *
+ * Two CLI surfaces:
+ *   1. `peaks doc generate-skill --from <code-path>` — produces a SKILL.md
+ *      skeleton by scanning a code directory for command exports,
+ *      with sections derived from JSDoc / signature.
+ *   2. `peaks doc changelog-suggest --since <git-ref>` — diffs
+ *      src/cli/commands/*.ts since the ref and emits a
+ *      "## [Unreleased]" block describing the changes.
+ *
+ * Both are pragmatic / 80% solutions; the goal is to make the operator's
+ * life easier, not to fully automate documentation.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+const COMMAND_PATTERN = /program\s*\.\s*command\(\s*['"]([^'"]+)['"]/g;
+const DESC_PATTERN = /\.description\(\s*['"]([^'"]+)['"]\)/g;
+/** Generate a SKILL.md skeleton from a directory of CLI command files. */
+export function generateSkillFromCommands(skillName, commandsDir) {
+    const sections = [];
+    let description = `Auto-generated SKILL.md skeleton for ${skillName}.`;
+    if (!existsSync(commandsDir)) {
+        return { name: skillName, description, sections: [] };
+    }
+    const commandMap = new Map();
+    for (const file of readdirSync(commandsDir)) {
+        if (!file.endsWith('.ts') && !file.endsWith('.js'))
+            continue;
+        const path = join(commandsDir, file);
+        let content;
+        try {
+            content = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const commands = [...content.matchAll(COMMAND_PATTERN)].map((m) => m[1]).filter((c) => c.length > 0);
+        const descs = [...content.matchAll(DESC_PATTERN)].map((m) => m[1]);
+        for (const cmd of commands) {
+            if (!commandMap.has(cmd))
+                commandMap.set(cmd, []);
+            commandMap.get(cmd).push(descs[0] ?? '(no description)');
+        }
+    }
+    if (commandMap.size === 0) {
+        return { name: skillName, description, sections: [] };
+    }
+    const bullets = [];
+    let firstDescription = null;
+    for (const [cmd, descs] of [...commandMap.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const desc = descs[0] ?? '(no description)';
+        bullets.push(`- \`peaks ${cmd}\` — ${desc}`);
+        if (firstDescription === null)
+            firstDescription = desc;
+    }
+    sections.push({ heading: 'Commands', bullets });
+    if (firstDescription !== null) {
+        description = firstDescription.slice(0, 200);
+    }
+    return { name: skillName, description, sections };
+}
+/** Render SkillDoc as markdown. */
+export function renderSkillMarkdown(doc) {
+    const lines = [];
+    lines.push(`# ${doc.name}`);
+    lines.push('');
+    lines.push(doc.description);
+    lines.push('');
+    for (const sec of doc.sections) {
+        lines.push(`## ${sec.heading}`);
+        lines.push('');
+        for (const b of sec.bullets)
+            lines.push(b);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Parse a single commit subject line into a ChangelogEntry. */
+export function parseCommitSubject(subject, file) {
+    const conventionalMatch = /^(feat|fix|docs|refactor|chore)(?:\([^)]+\))?:\s*(.+)$/i.exec(subject);
+    if (conventionalMatch) {
+        return { kind: conventionalMatch[1].toLowerCase(), subject: conventionalMatch[2].trim(), file };
+    }
+    return { kind: 'chore', subject, file };
+}
+/** Run `git log` for the given ref range, return parsed entries. */
+export function gitLogSince(projectRoot, since) {
+    try {
+        const out = execSync(`git log --pretty=format:"%s" ${since}..HEAD`, {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        if (out.trim().length === 0)
+            return [];
+        return out.split('\n').filter((s) => s.length > 0).map((s) => parseCommitSubject(s, 'git log'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Group entries by kind + render a "## [Unreleased]" block. */
+export function suggestChangelog(entries) {
+    if (entries.length === 0)
+        return '## [Unreleased]\n\n(no changes since the reference)';
+    const groups = { feat: [], fix: [], docs: [], refactor: [], chore: [] };
+    for (const e of entries)
+        groups[e.kind].push(e);
+    const lines = ['## [Unreleased]', ''];
+    for (const k of ['feat', 'fix', 'refactor', 'docs', 'chore']) {
+        if (groups[k].length === 0)
+            continue;
+        lines.push(`### ${k.charAt(0).toUpperCase() + k.slice(1)}`);
+        lines.push('');
+        for (const e of groups[k])
+            lines.push(`- ${e.subject}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/services/doctor/doctor-service/checks/check-id-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Check: every emitted check ID matches the `doctor-report.schema.json`
+ * check.id pattern (`doctor-self:check-id-pattern`).
+ *
+ * Self-validation gate that runs after every other check so it can
+ * observe the full list of emitted IDs. Fails when:
+ *   - The schema file is missing / unreadable.
+ *   - The schema does not declare a `checks.items.properties.id.pattern`.
+ *   - Any emitted check ID does not match the declared pattern.
+ *
+ * The accumulator is passed via the `DoctorContext` (see types.ts:
+ * `accumulatedChecks`). The plugin dispatcher in `index.ts` builds
+ * the accumulator incrementally and updates it before each plugin
+ * runs, so by the time this check fires every prior check's IDs are
+ * visible.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/check-id-schema.js

@@ -0,0 +1,64 @@
+/**
+ * Check: every emitted check ID matches the `doctor-report.schema.json`
+ * check.id pattern (`doctor-self:check-id-pattern`).
+ *
+ * Self-validation gate that runs after every other check so it can
+ * observe the full list of emitted IDs. Fails when:
+ *   - The schema file is missing / unreadable.
+ *   - The schema does not declare a `checks.items.properties.id.pattern`.
+ *   - Any emitted check ID does not match the declared pattern.
+ *
+ * The accumulator is passed via the `DoctorContext` (see types.ts:
+ * `accumulatedChecks`). The plugin dispatcher in `index.ts` builds
+ * the accumulator incrementally and updates it before each plugin
+ * runs, so by the time this check fires every prior check's IDs are
+ * visible.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+function runSelfCheck(schemaRoot, emittedIds) {
+    const schemaPath = join(schemaRoot, 'doctor-report.schema.json');
+    if (!existsSync(schemaPath)) {
+        return [{
+                id: 'doctor-self:check-id-pattern',
+                ok: false,
+                message: `Failed to load doctor-report.schema.json for self-validation: ${getErrorMessage(new Error(`ENOENT: ${schemaPath}`))}`
+            }];
+    }
+    try {
+        const schemaText = readFileSync(schemaPath, 'utf8');
+        const schema = JSON.parse(schemaText);
+        const patternSource = schema.properties?.checks?.items?.properties?.id?.pattern;
+        if (typeof patternSource !== 'string') {
+            return [{
+                    id: 'doctor-self:check-id-pattern',
+                    ok: false,
+                    message: 'doctor-report.schema.json does not declare a check.id pattern'
+                }];
+        }
+        const pattern = new RegExp(patternSource);
+        const mismatches = emittedIds.filter((id) => !pattern.test(id));
+        return [{
+                id: 'doctor-self:check-id-pattern',
+                ok: mismatches.length === 0,
+                message: mismatches.length === 0
+                    ? 'All doctor check IDs match the doctor-report schema pattern'
+                    : `Doctor check IDs missing from schema pattern: ${mismatches.join(', ')}`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'doctor-self:check-id-pattern',
+                ok: false,
+                message: `Failed to load doctor-report.schema.json for self-validation: ${getErrorMessage(error)}`
+            }];
+    }
+}
+function run({ schemaRoot, accumulatedChecks }) {
+    return runSelfCheck(schemaRoot, accumulatedChecks.map((check) => check.id));
+}
+export const check = {
+    name: 'check-id-schema',
+    run
+};

package/dist/services/doctor/doctor-service/checks/codegraph-capability.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check: codegraph capability (`capability:codegraph`).
+ *
+ * Verifies that `@colbymchenry/codegraph` resolves at the pinned
+ * version AND that the binary exists at the expected on-disk path.
+ * Fails when the version drifts, when the binary is missing, or
+ * when the package is not resolvable at all.
+ *
+ * The probe is injected so tests do not depend on the real
+ * `node_modules` resolution; the default probe uses
+ * `createRequire(import.meta.url)` to find the package.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/codegraph-capability.js

@@ -0,0 +1,69 @@
+/**
+ * Check: codegraph capability (`capability:codegraph`).
+ *
+ * Verifies that `@colbymchenry/codegraph` resolves at the pinned
+ * version AND that the binary exists at the expected on-disk path.
+ * Fails when the version drifts, when the binary is missing, or
+ * when the package is not resolvable at all.
+ *
+ * The probe is injected so tests do not depend on the real
+ * `node_modules` resolution; the default probe uses
+ * `createRequire(import.meta.url)` to find the package.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { createRequire } from 'node:module';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
+function defaultCodegraphProbe() {
+    const require = createRequire(import.meta.url);
+    const packagePath = require.resolve('@colbymchenry/codegraph/package.json');
+    const pkg = require(packagePath);
+    const binaryPath = resolvePath(dirname(packagePath), 'dist', 'bin', 'codegraph.js');
+    return {
+        packagePath,
+        version: pkg.version ?? 'unknown',
+        binaryPath,
+        binaryExists: existsSync(binaryPath)
+    };
+}
+function runCheck(probe) {
+    try {
+        const result = probe();
+        const versionOk = result.version === CODEGRAPH_EXPECTED_VERSION;
+        if (!versionOk) {
+            return [{
+                    id: 'capability:codegraph',
+                    ok: false,
+                    message: `@colbymchenry/codegraph version mismatch: expected ${CODEGRAPH_EXPECTED_VERSION}, resolved ${result.version} at ${result.packagePath}`
+                }];
+        }
+        if (!result.binaryExists) {
+            return [{
+                    id: 'capability:codegraph',
+                    ok: false,
+                    message: `@colbymchenry/codegraph@${result.version} resolved at ${result.packagePath} but binary is missing at ${result.binaryPath}`
+                }];
+        }
+        return [{
+                id: 'capability:codegraph',
+                ok: true,
+                message: `@colbymchenry/codegraph@${result.version} resolves with binary at ${result.binaryPath}`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'capability:codegraph',
+                ok: false,
+                message: `@colbymchenry/codegraph not resolvable: ${getErrorMessage(error)}`
+            }];
+    }
+}
+function run({ options }) {
+    const probe = options.codegraphProbe ?? defaultCodegraphProbe;
+    return runCheck(probe);
+}
+export const check = {
+    name: 'codegraph-capability',
+    run
+};

package/dist/services/doctor/doctor-service/checks/dist-source-version.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Check: dist CLI_VERSION matches source `package.json#version`
+ * (`build:dist-version-matches-source`).
+ *
+ * Build-hygiene check that surfaces the silent-stale-CLI failure
+ * mode where the user runs `npx peaks` / `node bin/peaks.js` after
+ * `pnpm install` but before `pnpm build`. A missing dist/ is treated
+ * as informational (fresh clone, not broken) so the check does not
+ * flip the summary to red on a clean checkout.
+ *
+ * IMPORTANT: the on-disk path is `dist/shared/version.js` (NOT
+ * `dist/src/shared/version.js`) because `tsconfig.build.json#rootDir
+ * = "src"` trims the `src/` segment from emitted output.
+ *
+ * The pure compare helper is exported as `compareDistVersion` so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+import type { DistVersionComparison, DoctorCheckPlugin } from '../types.js';
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against
+ * the source-of-truth `package.json#version`. Default readers fail-
+ * soft to `null` on missing/unreadable/malformed input. Exported so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+export declare function compareDistVersion(opts: {
+    projectRoot: string;
+    distVersionReader?: (root: string) => string | null;
+    sourceVersionReader?: (root: string) => string | null;
+}): DistVersionComparison;
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/dist-source-version.js

@@ -0,0 +1,110 @@
+/**
+ * Check: dist CLI_VERSION matches source `package.json#version`
+ * (`build:dist-version-matches-source`).
+ *
+ * Build-hygiene check that surfaces the silent-stale-CLI failure
+ * mode where the user runs `npx peaks` / `node bin/peaks.js` after
+ * `pnpm install` but before `pnpm build`. A missing dist/ is treated
+ * as informational (fresh clone, not broken) so the check does not
+ * flip the summary to red on a clean checkout.
+ *
+ * IMPORTANT: the on-disk path is `dist/shared/version.js` (NOT
+ * `dist/src/shared/version.js`) because `tsconfig.build.json#rootDir
+ * = "src"` trims the `src/` segment from emitted output.
+ *
+ * The pure compare helper is exported as `compareDistVersion` so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/**
+ * Pure helper that compares the published dist `CLI_VERSION` against
+ * the source-of-truth `package.json#version`. Default readers fail-
+ * soft to `null` on missing/unreadable/malformed input. Exported so
+ * tests can drive the filesystem reads without monkey-patching
+ * `process.cwd()`.
+ */
+export function compareDistVersion(opts) {
+    const distReader = opts.distVersionReader ?? defaultDistVersionReader;
+    const sourceReader = opts.sourceVersionReader ?? defaultSourceVersionReader;
+    const dist = safeRead(() => distReader(opts.projectRoot));
+    const source = safeRead(() => sourceReader(opts.projectRoot)) ?? 'unknown';
+    const distReadable = dist !== null;
+    return {
+        dist,
+        source,
+        match: distReadable && dist === source,
+        distReadable
+    };
+}
+function safeRead(reader) {
+    try {
+        return reader();
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function defaultDistVersionReader(projectRoot) {
+    const distPath = join(projectRoot, 'dist', 'shared', 'version.js');
+    if (!existsSync(distPath)) {
+        return null;
+    }
+    const body = readFileSync(distPath, 'utf8');
+    const match = /export\s+const\s+CLI_VERSION\s*=\s*["']([^"']+)["']/.exec(body);
+    return match?.[1] ?? null;
+}
+function defaultSourceVersionReader(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return null;
+    }
+    const body = readFileSync(pkgPath, 'utf8');
+    const parsed = JSON.parse(body);
+    return typeof parsed.version === 'string' ? parsed.version : null;
+}
+function defaultDistVersionProbe(projectRootResolver) {
+    const projectRoot = projectRootResolver();
+    if (projectRoot === null) {
+        return { dist: null, source: 'unknown', match: false, distReadable: false };
+    }
+    return compareDistVersion({ projectRoot });
+}
+function run({ options, projectRootResolver }) {
+    const probe = options.distVersionProbe ?? (() => defaultDistVersionProbe(projectRootResolver));
+    try {
+        const result = probe();
+        if (!result.distReadable) {
+            return [{
+                    id: 'build:dist-version-matches-source',
+                    ok: true,
+                    message: `dist/ is not present; run \`pnpm build\` to populate dist/shared/version.js (source version ${result.source})`
+                }];
+        }
+        if (result.match) {
+            return [{
+                    id: 'build:dist-version-matches-source',
+                    ok: true,
+                    message: `dist/shared/version.js ships CLI_VERSION ${result.dist} matching source ${result.source}`
+                }];
+        }
+        return [{
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist/shared/version.js ships CLI_VERSION ${result.dist} but source ${result.source} is in src/shared/version.ts; run \`pnpm build\` to refresh dist/`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist version check failed: ${getErrorMessage(error)}`
+            }];
+    }
+}
+export const check = {
+    name: 'dist-source-version',
+    run
+};