peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/doctor/doctor-service.js

@@ -0,0 +1,929 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { readText } from '../../shared/fs.js';
+import { requiredSchemaFiles, requiredSkillNames, schemasDir } from '../../shared/paths.js';
+import { getErrorMessage } from '../../shared/result.js';
+import { loadSkillRegistry } from '../skills/skill-registry.js';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+import { planStatusLineInstall } from '../skills/statusline-settings-service.js';
+import { findProjectRoot } from '../config/config-safety.js';
+import { isValidSessionId } from '../workspace/sid-naming-guard.js';
+import { CLI_VERSION } from '../../shared/version.js';
+const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
+const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+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 defaultStatusLineInstalledProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    // Check both scopes: a user may have installed the statusLine globally, which
+    // the project-only check would miss and falsely report as "not installed".
+    try {
+        if (projectRoot !== null && planStatusLineInstall('project', projectRoot).alreadyInstalled) {
+            return true;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* fall through to global */
+    }
+    try {
+        return planStatusLineInstall('global').alreadyInstalled;
+    }
+    catch {
+        return false;
+    }
+}
+function defaultWorkspaceInitializedProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null)
+        return false;
+    // Workspace is "initialized" when EITHER the canonical runtime-layer session
+    // binding (`.peaks/_runtime/session.json`, the home since slice
+    // 2026-06-05-peaks-runtime-layer) OR the legacy top-level binding
+    // (`.peaks/.session.json`, kept as read-only back-compat for one minor
+    // release) is present. The legacy check is what catches projects that ran
+    // `peaks workspace init` before the runtime-layer migration and have not yet
+    // been reconciled; both paths must continue to satisfy the doctor until the
+    // legacy location is removed.
+    return isWorkspaceInitializedAt(projectRoot);
+}
+/**
+ * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
+ * drive the filesystem check without monkey-patching `process.cwd()` or
+ * `findProjectRoot`. Returns `true` when EITHER the canonical
+ * `.peaks/_runtime/session.json` OR the legacy `.peaks/.session.json` exists.
+ */
+export function isWorkspaceInitializedAt(projectRoot) {
+    return (existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json')) ||
+        existsSync(join(projectRoot, '.peaks', '.session.json')));
+}
+/**
+ * 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) {
+    // Synchronous read is fine: the dist version.js is small and on the
+    // local build pipeline's hot path. readFileSync + regex is cheaper
+    // than pulling in fs/promises for a single short file.
+    const distPath = join(projectRoot, 'dist', 'src', '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() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null) {
+        return { dist: null, source: 'unknown', match: false, distReadable: false };
+    }
+    return compareDistVersion({ projectRoot });
+}
+/**
+ * Pure helper that inspects the on-disk workspace layout for
+ * post-F3-canonical violations. The post-F3 canonical layout puts
+ * session dirs under `.peaks/_runtime/<sid>/` and the runtime
+ * binding at `.peaks/_runtime/session.json`; the legacy paths
+ * (top-level `<YYYY-MM-DD-session-<hex>>/` dirs and the legacy
+ * top-level `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * dotfiles) must be absent. This helper is exported so tests can
+ * drive the filesystem walk without monkey-patching `process.cwd()`
+ * or `findProjectRoot`.
+ *
+ * Both scanners fail-soft (return `[]` on read errors) so a flaky
+ * filesystem read on a non-fatal probe path never escalates into a
+ * doctor failure.
+ */
+export function inspectWorkspaceLayout(opts) {
+    const topLevel = opts.topLevelScanner ?? defaultTopLevelSessionDirScanner;
+    const dotfiles = opts.dotfileScanner ?? defaultLegacyDotfileScanner;
+    const perChangeId = opts.perChangeIdScanner ?? defaultPerChangeIdDirScanner;
+    return {
+        topLevelSessionDirs: safeList(() => topLevel(opts.projectRoot)),
+        legacyDotfiles: safeList(() => dotfiles(opts.projectRoot)),
+        perChangeIdDirs: safeList(() => perChangeId(opts.projectRoot))
+    };
+}
+function safeList(reader) {
+    try {
+        const out = reader();
+        return Array.isArray(out) ? out : [];
+    }
+    catch {
+        return [];
+    }
+}
+const SESSION_DIR_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
+function defaultTopLevelSessionDirScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const offenders = [];
+    for (const name of names) {
+        if (!SESSION_DIR_PATTERN.test(name))
+            continue;
+        const full = join(peaksRoot, name);
+        try {
+            const stat = existsSync(full) ? lstatSync(full) : null;
+            if (stat === null)
+                continue;
+            // Directories only — the regex should never match a dotfile or
+            // regular file, but be defensive against weird filesystem state
+            // (e.g. someone manually created a file whose name happens to
+            // match the session-id pattern).
+            if (stat.isDirectory()) {
+                offenders.push(join('.peaks', name) + '/');
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return offenders;
+}
+const LEGACY_DOTFILES = ['.session.json', '.active-skill.json'];
+function defaultLegacyDotfileScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    const offenders = [];
+    for (const name of LEGACY_DOTFILES) {
+        if (existsSync(join(peaksRoot, name))) {
+            offenders.push(join('.peaks', name));
+        }
+    }
+    return offenders;
+}
+function defaultWorkspaceLayoutProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot === null) {
+        return { topLevelSessionDirs: [], legacyDotfiles: [], perChangeIdDirs: [] };
+    }
+    return inspectWorkspaceLayout({ projectRoot });
+}
+// Slice 007 — per-change-id top-level dir pattern. Matches the
+// F3-canonical (pre-canonicalization) layout the 5 already-shipped
+// slices left behind, e.g. `.peaks/001-2026-06-06-doctor-dist-version-check/`.
+// The pattern is intentionally narrow so it does NOT match the
+// post-F3 system dirs (`_runtime/`, `_dogfood/`, `retrospective/`,
+// `memory/`, `perf-baseline/`, `project-scan/`, `sops/`,
+// `0NN-session-...`, `YYYY-MM-DD-session-...`).
+const PER_CHANGE_ID_PATTERN = /^\d{3}-\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+function defaultPerChangeIdDirScanner(projectRoot) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(peaksRoot);
+    }
+    catch {
+        return [];
+    }
+    const offenders = [];
+    for (const name of names) {
+        if (!PER_CHANGE_ID_PATTERN.test(name))
+            continue;
+        const full = join(peaksRoot, name);
+        try {
+            const stat = existsSync(full) ? lstatSync(full) : null;
+            if (stat === null)
+                continue;
+            // Directories only — the regex should never match a dotfile
+            // or regular file, but be defensive against weird filesystem
+            // state (e.g. someone manually created a file whose name
+            // happens to match the per-change-id pattern).
+            if (stat.isDirectory()) {
+                offenders.push(join('.peaks', name) + '/');
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return offenders;
+}
+const DESTRUCTIVE_APPLY_PATTERNS = [
+    /peaks\s+memory\s+sync[^\n]*--apply/,
+    /peaks\s+memory\s+extract[^\n]*--apply/,
+    /peaks\s+artifacts\s+sync[^\n]*--apply/,
+    /peaks\s+openspec\s+archive[^\n]*--apply/,
+    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/
+];
+const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
+function extractRunbookSection(body) {
+    const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
+    return match === null ? null : (match[1] ?? null);
+}
+function findDestructiveApplyLines(section) {
+    const lines = section.split(/\r?\n/);
+    return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
+}
+// ---------------------------------------------------------------------------
+// 2026-06-10 — gateguard-fact-force integration check (NOT a peaks-loop hook).
+//
+// The `gateguard-fact-force` hook is a third-party PreToolUse hook that
+// fires on Edit / Write / MultiEdit and demands a 4-fact questionnaire
+// before allowing the edit. It is unrelated to peaks-loop, but when the
+// LLM is in a peaks-qa flow and edits `.peaks/_runtime/<sid>/qa/requests/
+// *.md`, the questionnaire demands facts that do not apply (no
+// importers, no public API, no data files, user instruction already
+// in the conversation context). The check below detects the hook in
+// `~/.claude/settings.json` and the project `.claude/settings.json`,
+// and warns when no `.peaks/**` skip is configured.
+//
+// Probing is split out of the check so the check itself stays a pure
+// mapping over `GateguardProbeResult`. Tests inject the probe to keep
+// `~/.claude/settings.json` from leaking into test fixtures.
+// ---------------------------------------------------------------------------
+/** Hook command fragments that identify the gateguard-fact-force hook. */
+const GATEGUARD_HOOK_NEEDLES = ['gateguard', 'fact-force', 'fact_force'];
+/** Token the gateguard hook exposes for "skip these paths" — the check
+ *  treats any match against `.peaks` (path or globs) as a routed
+ *  configuration. We accept a few common spellings because the third-
+ *  party hook's CLI surface is not part of peaks-loop's contract. */
+const GATEGUARD_PEAKS_SKIP_NEEDLES = [
+    '.peaks',
+    'peaks-skip',
+    'skip-glob',
+    '--skip',
+    'skip_paths'
+];
+function commandMentionsGateguard(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return false;
+    const lower = command.toLowerCase();
+    return GATEGUARD_HOOK_NEEDLES.some((needle) => lower.includes(needle));
+}
+function entrySkipsPeaks(entry) {
+    const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+    const matcherMentionsPeaks = matcher.toLowerCase().includes('.peaks');
+    if (matcherMentionsPeaks)
+        return true;
+    for (const hook of entry.hooks) {
+        const command = typeof hook.command === 'string' ? hook.command : '';
+        const lower = command.toLowerCase();
+        if (GATEGUARD_PEAKS_SKIP_NEEDLES.some((needle) => lower.includes(needle))) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractGateguardEntries(source, sourcePath, settings) {
+    if (settings === null || typeof settings !== 'object')
+        return [];
+    const hooks = settings.hooks;
+    if (hooks === null || typeof hooks !== 'object')
+        return [];
+    const preToolUse = hooks.PreToolUse;
+    if (!Array.isArray(preToolUse))
+        return [];
+    const out = [];
+    for (const rawEntry of preToolUse) {
+        if (rawEntry === null || typeof rawEntry !== 'object')
+            continue;
+        const entry = rawEntry;
+        if (!Array.isArray(entry.hooks))
+            continue;
+        const hooks = [];
+        for (const rawHook of entry.hooks) {
+            if (rawHook === null || typeof rawHook !== 'object')
+                continue;
+            const h = rawHook;
+            const hookEntry = {};
+            if (typeof h.type === 'string')
+                hookEntry.type = h.type;
+            if (typeof h.command === 'string')
+                hookEntry.command = h.command;
+            hooks.push(hookEntry);
+        }
+        if (!hooks.some((h) => commandMentionsGateguard(h.command)))
+            continue;
+        const outEntry = { hooks };
+        if (typeof entry.matcher === 'string')
+            outEntry.matcher = entry.matcher;
+        out.push({ source, sourcePath, entry: outEntry });
+    }
+    return out;
+}
+function readSettingsJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function defaultGateguardProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    const globalPath = join(homedir(), '.claude', 'settings.json');
+    const projectPath = projectRoot === null ? null : join(projectRoot, '.claude', 'settings.json');
+    return {
+        globalSettingsPath: globalPath,
+        globalSettings: readSettingsJson(globalPath),
+        projectSettingsPath: projectPath,
+        projectSettings: projectPath === null ? null : readSettingsJson(projectPath)
+    };
+}
+export function collectGateguardEntries(probe) {
+    const fromGlobal = extractGateguardEntries('global', probe.globalSettingsPath ?? '~/.claude/settings.json', probe.globalSettings);
+    const fromProject = probe.projectSettingsPath === null
+        ? []
+        : extractGateguardEntries('project', probe.projectSettingsPath, probe.projectSettings);
+    return [...fromGlobal, ...fromProject];
+}
+export async function runDoctor(options = {}) {
+    const checks = [];
+    const registry = await loadSkillRegistry(options.skillsBaseDir);
+    const skills = registry.skills;
+    const skillNames = new Set(skills.map((skill) => skill.name));
+    for (const requiredSkill of requiredSkillNames) {
+        checks.push({
+            id: `skill:${requiredSkill}`,
+            ok: skillNames.has(requiredSkill),
+            message: skillNames.has(requiredSkill)
+                ? `Required skill ${requiredSkill} exists`
+                : `Missing required skill ${requiredSkill}`
+        });
+    }
+    for (const skill of skills) {
+        checks.push({
+            id: `skill-name:${skill.directory}`,
+            ok: skill.name === skill.directory,
+            message: skill.name === skill.directory
+                ? `Skill ${skill.name} matches its directory`
+                : `Skill ${skill.directory} declares mismatched name ${skill.name}`
+        });
+    }
+    for (const failure of registry.failures) {
+        checks.push({
+            id: `skill-parse:${failure.directory}`,
+            ok: false,
+            message: `Skill ${failure.directory} has invalid metadata: ${failure.message}`
+        });
+    }
+    const requiredSkillNameSet = new Set(requiredSkillNames);
+    for (const skill of skills) {
+        if (!requiredSkillNameSet.has(skill.name)) {
+            continue;
+        }
+        try {
+            const body = await readText(skill.skillPath);
+            const hasRunbook = /## Default runbook\s/.test(body);
+            checks.push({
+                id: `skill-runbook:${skill.name}`,
+                ok: hasRunbook,
+                message: hasRunbook
+                    ? `Skill ${skill.name} declares a Default runbook`
+                    : `Skill ${skill.name} is missing a ## Default runbook section`
+            });
+            const runbookSection = extractRunbookSection(body);
+            if (runbookSection !== null) {
+                const destructiveLines = findDestructiveApplyLines(runbookSection);
+                if (destructiveLines.length === 0) {
+                    checks.push({
+                        id: `skill-apply-note:${skill.name}`,
+                        ok: true,
+                        message: `Skill ${skill.name} runbook has no destructive --apply commands to gate`
+                    });
+                }
+                else {
+                    const hasAuthorizationNote = AUTHORIZATION_KEYWORDS_PATTERN.test(runbookSection);
+                    checks.push({
+                        id: `skill-apply-note:${skill.name}`,
+                        ok: hasAuthorizationNote,
+                        message: hasAuthorizationNote
+                            ? `Skill ${skill.name} gates ${destructiveLines.length} destructive --apply command(s) with an authorization note`
+                            : `Skill ${skill.name} has ${destructiveLines.length} destructive --apply command(s) without an authorization/dry-run note in the runbook section`
+                    });
+                }
+            }
+        }
+        catch (error) {
+            checks.push({
+                id: `skill-runbook:${skill.name}`,
+                ok: false,
+                message: `Skill ${skill.name} runbook check failed: ${getErrorMessage(error)}`
+            });
+        }
+    }
+    const schemaRoot = options.schemasBaseDir ?? schemasDir;
+    for (const schemaFile of requiredSchemaFiles) {
+        try {
+            JSON.parse(await readText(join(schemaRoot, schemaFile)));
+            checks.push({ id: `schema:${schemaFile}`, ok: true, message: `Schema ${schemaFile} is valid JSON` });
+        }
+        catch (error) {
+            checks.push({
+                id: `schema:${schemaFile}`,
+                ok: false,
+                message: `Schema ${schemaFile} is missing or invalid: ${getErrorMessage(error)}`
+            });
+        }
+    }
+    const userConfigPath = join(homedir(), '.peaks', 'config.json');
+    const hasUserConfig = existsSync(userConfigPath);
+    checks.push({
+        id: 'config:user',
+        ok: true,
+        message: hasUserConfig ? 'User config exists at ~/.peaks/config.json' : 'Optional user config not found at ~/.peaks/config.json'
+    });
+    const presenceProbe = options.skillPresenceProbe ?? getSkillPresence;
+    const freshnessThresholdMs = options.skillPresenceFreshnessThresholdMs ?? SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS;
+    let presence = null;
+    try {
+        presence = presenceProbe();
+    }
+    catch {
+        presence = null;
+    }
+    if (presence === null) {
+        checks.push({
+            id: 'skill-presence:current',
+            ok: true,
+            message: 'No active Peaks skill presence (.peaks/.active-skill.json absent or invalid)'
+        });
+        checks.push({
+            id: 'skill-presence:freshness',
+            ok: true,
+            message: 'No active Peaks skill presence to age-check'
+        });
+    }
+    else {
+        const modePart = presence.mode !== undefined ? `, mode ${presence.mode}` : '';
+        const gatePart = presence.gate !== undefined ? `, gate ${presence.gate}` : '';
+        checks.push({
+            id: 'skill-presence:current',
+            ok: true,
+            message: `Active Peaks skill presence: ${presence.skill}${modePart}${gatePart} (set ${presence.setAt})`
+        });
+        const setAtMs = Date.parse(presence.setAt);
+        if (Number.isNaN(setAtMs)) {
+            checks.push({
+                id: 'skill-presence:freshness',
+                ok: false,
+                message: `Skill presence ${presence.skill} has invalid setAt: ${presence.setAt}`
+            });
+        }
+        else {
+            const ageMs = Date.now() - setAtMs;
+            if (ageMs > freshnessThresholdMs) {
+                const ageHours = Math.round(ageMs / (60 * 60 * 1000));
+                checks.push({
+                    id: 'skill-presence:freshness',
+                    ok: false,
+                    message: `Skill presence ${presence.skill} is stale (set ${presence.setAt}, ~${ageHours}h ago); run peaks skill presence:clear if the role has ended`
+                });
+            }
+            else {
+                checks.push({
+                    id: 'skill-presence:freshness',
+                    ok: true,
+                    message: `Skill presence ${presence.skill} is fresh (set ${presence.setAt})`
+                });
+            }
+        }
+    }
+    // Workspace guard: an active workflow presence (peaks-code) with no workspace
+    // session means the skill was anchored but `peaks workspace init` never ran —
+    // the #1 reported failure where .peaks/ artifacts are never created. This
+    // turns the SKILL.md "MUST create the workspace" prose into an executable check.
+    const workspaceProbe = options.workspaceInitializedProbe ?? defaultWorkspaceInitializedProbe;
+    let workspaceInitialized = false;
+    try {
+        workspaceInitialized = workspaceProbe();
+    }
+    catch {
+        workspaceInitialized = false;
+    }
+    if (presence !== null && !workspaceInitialized) {
+        checks.push({
+            id: 'skill-presence:workspace',
+            ok: false,
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-code Step 0 must anchor the workspace before any work`
+        });
+    }
+    else {
+        checks.push({
+            id: 'skill-presence:workspace',
+            ok: true,
+            message: presence === null
+                ? 'No active skill presence; workspace guard not applicable'
+                : `Workspace session present for active skill ${presence.skill}`
+        });
+    }
+    // Discoverability nudge: when a skill is actively orchestrating but the
+    // out-of-band statusLine isn't installed, the user has no terminal-level
+    // signal that Peaks is in control. Suggest installing it (non-failing).
+    const statusLineProbe = options.statusLineInstalledProbe ?? defaultStatusLineInstalledProbe;
+    let statusLineInstalled = false;
+    try {
+        statusLineInstalled = statusLineProbe();
+    }
+    catch {
+        statusLineInstalled = false;
+    }
+    if (presence !== null && !statusLineInstalled) {
+        checks.push({
+            id: 'statusline:install',
+            ok: true,
+            message: 'A Peaks skill is active but the statusLine is not installed; run `peaks statusline install` so the active skill shows in the terminal status bar'
+        });
+    }
+    else {
+        checks.push({
+            id: 'statusline:install',
+            ok: true,
+            message: statusLineInstalled
+                ? 'Peaks statusLine is installed'
+                : 'Peaks statusLine not installed (no active skill; install optional)'
+        });
+    }
+    // Runtime/platform diagnostic for the "statusLine shows nothing" reports.
+    // Surfaces (a) the running peaks version — a stale global install predating
+    // the statusLine feature is a common cause — and (b) on Windows, the fact that
+    // the bare `peaks statusline` command must resolve in the shell Claude Code
+    // spawns, which fails when the npm global bin dir is not on that shell's PATH.
+    const platform = options.platform ?? process.platform;
+    if (platform === 'win32') {
+        checks.push({
+            id: 'statusline:runtime',
+            ok: true,
+            message: `peaks ${CLI_VERSION} (win32): if the statusLine shows nothing in git bash, verify \`peaks\` resolves on PATH in the shell Claude Code uses (run \`peaks -v\` there), reinstall globally with \`npm i -g peaks-loop@latest\` if the version is older than ${CLI_VERSION}, then re-run \`peaks statusline install\` and reload Claude Code`
+        });
+    }
+    else {
+        checks.push({
+            id: 'statusline:runtime',
+            ok: true,
+            message: `peaks ${CLI_VERSION} (${platform}): statusLine command is \`peaks statusline\``
+        });
+    }
+    const probe = options.codegraphProbe ?? defaultCodegraphProbe;
+    try {
+        const result = probe();
+        const versionOk = result.version === CODEGRAPH_EXPECTED_VERSION;
+        if (!versionOk) {
+            checks.push({
+                id: 'capability:codegraph',
+                ok: false,
+                message: `@colbymchenry/codegraph version mismatch: expected ${CODEGRAPH_EXPECTED_VERSION}, resolved ${result.version} at ${result.packagePath}`
+            });
+        }
+        else if (!result.binaryExists) {
+            checks.push({
+                id: 'capability:codegraph',
+                ok: false,
+                message: `@colbymchenry/codegraph@${result.version} resolved at ${result.packagePath} but binary is missing at ${result.binaryPath}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'capability:codegraph',
+                ok: true,
+                message: `@colbymchenry/codegraph@${result.version} resolves with binary at ${result.binaryPath}`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'capability:codegraph',
+            ok: false,
+            message: `@colbymchenry/codegraph not resolvable: ${getErrorMessage(error)}`
+        });
+    }
+    // Build-hygiene check: the published `dist/` ships a different CLI_VERSION
+    // than the source-of-truth `src/shared/version.ts` / `package.json#version`
+    // whenever the user runs `npx peaks` or `node bin/peaks.js` after `pnpm
+    // install` but before `pnpm build`. This is the silent-stale-CLI failure
+    // mode reported in `.peaks/2026-06-05-session-fecddb/txt/dogfood-2026-06-04-05.md`
+    // (F1). 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.
+    const distProbe = options.distVersionProbe ?? defaultDistVersionProbe;
+    try {
+        const result = distProbe();
+        if (!result.distReadable) {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: true,
+                message: `dist/ is not present; run \`pnpm build\` to populate dist/src/shared/version.js (source version ${result.source})`
+            });
+        }
+        else if (result.match) {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: true,
+                message: `dist/src/shared/version.js ships CLI_VERSION ${result.dist} matching source ${result.source}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'build:dist-version-matches-source',
+                ok: false,
+                message: `dist/src/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) {
+        checks.push({
+            id: 'build:dist-version-matches-source',
+            ok: false,
+            message: `dist version check failed: ${getErrorMessage(error)}`
+        });
+    }
+    // Build-hygiene check: a non-canonical post-F3 workspace layout is
+    // the silent-regression failure mode that slice 003 explicitly chose
+    // to allow (the current session binding was kept at top-level as a
+    // safety measure). This check surfaces any leftover top-level
+    // session dirs, the legacy runtime dotfiles (`.peaks/.session.json`,
+    // `.peaks/.active-skill.json`), OR per-change-id top-level dirs
+    // (`.peaks/NNN-YYYY-MM-DD-<slug>/`) so a future contributor who
+    // manually recreates one of them is warned. The check is read-only;
+    // the fix path is `peaks workspace migrate --to-runtime --project
+    // <repo> --apply`.
+    //
+    // Slice 007 broadened this check to flag per-change-id top-level
+    // dirs (the 5 already-shipped slices left them behind). Until
+    // slice 008's migration consolidates them, the check reports
+    // `ok: false` for any repo that still has the legacy per-change-id
+    // layout.
+    const layoutProbe = options.workspaceLayoutProbe ?? defaultWorkspaceLayoutProbe;
+    try {
+        const layout = layoutProbe();
+        // Back-compat: probes injected by older tests (pre-slice-007)
+        // return a 2-field shape (no perChangeIdDirs). Treat missing
+        // field as empty.
+        const perChangeIdDirs = layout.perChangeIdDirs ?? [];
+        if (layout.topLevelSessionDirs.length === 0 && layout.legacyDotfiles.length === 0 && perChangeIdDirs.length === 0) {
+            checks.push({
+                id: 'build:workspace-layout-canonical',
+                ok: true,
+                message: 'Workspace layout is canonical: no top-level session dirs, no legacy runtime dotfiles, no per-change-id top-level dirs'
+            });
+        }
+        else {
+            const offenders = [
+                ...layout.topLevelSessionDirs.map((p) => `top-level session dir: ${p}`),
+                ...layout.legacyDotfiles.map((p) => `legacy dotfile: ${p}`),
+                ...perChangeIdDirs.map((p) => `per-change-id top-level dir: ${p}`)
+            ];
+            checks.push({
+                id: 'build:workspace-layout-canonical',
+                ok: false,
+                message: `Workspace layout is not canonical. Offenders: ${offenders.join('; ')}. Run \`peaks workspace migrate --to-runtime --project <repo> --apply\` to consolidate.`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'build:workspace-layout-canonical',
+            ok: false,
+            message: `Workspace layout check failed: ${getErrorMessage(error)}`
+        });
+    }
+    // 2026-06-10 — gateguard-fact-force integration check. The hook is a
+    // third-party PreToolUse that fires on Edit / Write and demands a
+    // 4-fact questionnaire; when the LLM is in a peaks-qa flow updating
+    // `.peaks/_runtime/<sid>/qa/requests/*.md` the facts do not apply.
+    // We warn when the hook is installed and no `.peaks/**` skip is
+    // configured. The check stays a pure mapping over the probe result
+    // so tests can drive it without touching the real `~/.claude/`.
+    const gateguardProbe = options.gateguardProbe ?? defaultGateguardProbe;
+    try {
+        const probe = gateguardProbe();
+        const offending = collectGateguardEntries(probe);
+        if (offending.length === 0) {
+            checks.push({
+                id: 'integration:gateguard-peaks-conflict',
+                ok: true,
+                message: 'No gateguard-fact-force PreToolUse hook detected in ~/.claude/settings.json or project .claude/settings.json; the Edit/Write fact-forcing flow will not interfere with peaks-qa .peaks/ artifact writes'
+            });
+        }
+        else {
+            const unrouted = offending.filter((location) => !entrySkipsPeaks(location.entry));
+            if (unrouted.length === 0) {
+                checks.push({
+                    id: 'integration:gateguard-peaks-conflict',
+                    ok: true,
+                    message: `gateguard-fact-force hook is installed in ${offending.map((l) => l.source).join(' + ')} but a .peaks/** skip pattern is configured; peaks-qa .peaks/ artifact writes are not blocked`
+                });
+            }
+            else {
+                const sources = Array.from(new Set(unrouted.map((u) => u.sourcePath))).join(' + ');
+                const matchers = unrouted.map((u) => u.entry.matcher ?? '*').join(', ');
+                checks.push({
+                    id: 'integration:gateguard-peaks-conflict',
+                    ok: false,
+                    message: `gateguard-fact-force PreToolUse hook is installed (${sources}, matcher: ${matchers}) with no .peaks/** skip pattern; every Edit/Write of a peaks-qa envelope (.peaks/_runtime/<sid>/qa/requests/*.md) will be intercepted and demand a 4-fact questionnaire that does not apply to QA templates. Workaround: set \`ECC_DISABLED_HOOKS=pre:edit-write:gateguard-fact-force\` for the session, OR add a paired PreToolUse entry whose matcher restricts the hook to non-.peaks paths. peaks-loop is NOT the source of this hook.`
+                });
+            }
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'integration:gateguard-peaks-conflict',
+            ok: true,
+            message: `gateguard probe failed (${getErrorMessage(error)}); skipping check`
+        });
+    }
+    try {
+        const schemaText = await readText(join(schemaRoot, 'doctor-report.schema.json'));
+        const schema = JSON.parse(schemaText);
+        const patternSource = schema.properties?.checks?.items?.properties?.id?.pattern;
+        if (typeof patternSource === 'string') {
+            const pattern = new RegExp(patternSource);
+            const mismatches = checks.filter((check) => !pattern.test(check.id)).map((check) => check.id);
+            checks.push({
+                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(', ')}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'doctor-self:check-id-pattern',
+                ok: false,
+                message: 'doctor-report.schema.json does not declare a check.id pattern'
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'doctor-self:check-id-pattern',
+            ok: false,
+            message: `Failed to load doctor-report.schema.json for self-validation: ${getErrorMessage(error)}`
+        });
+    }
+    // Slice L3.2: project doctor MVP — 2 new diagnostic checks.
+    //   1. L3:l3-orphan-sessions — flags bare sids in .peaks/_runtime/ that
+    //      fail isValidSessionId. Reuses the Slice 0.5 sid-naming-guard.
+    //   2. L3:l3-memory-health — verifies .peaks/memory/index.json is
+    //      well-formed JSON with the expected schema_version field and
+    //      references real files on disk.
+    // Slice L3.2: project doctor MVP — 2 new diagnostic checks.
+    //   1. L3:l3-orphan-sessions — flags bare sids in .peaks/_runtime/ that
+    //      fail isValidSessionId. Reuses the Slice 0.5 sid-naming-guard.
+    //   2. L3:l3-memory-health — verifies .peaks/memory/index.json is
+    //      well-formed JSON with the expected schema_version field and
+    //      references real files on disk.
+    //
+    // Round 2 (slice 2026-06-24-doctor-1xdetector-residual): the reducer
+    // must skip canonical system subdirs that intentionally live under
+    // `.peaks/_runtime/` — used by `request-artifact-service` /
+    // `workflow-autonomous-service` to route reviewable artifacts under
+    // session-axis dirs. Excluding these from the orphan scan is a
+    // reducer-level narrowing of which entries are subject to the check;
+    // it does NOT change the pass/fail rule for actual session ids.
+    const RUNTIME_SYSTEM_SUBDIRS = new Set(['change']);
+    const l3ProjectRoot = options.l3ProjectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    try {
+        const runtimeDir = join(l3ProjectRoot, '.peaks/_runtime');
+        if (existsSync(runtimeDir)) {
+            const entries = readdirSync(runtimeDir, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name)
+                .filter((name) => !RUNTIME_SYSTEM_SUBDIRS.has(name));
+            const validSids = entries.filter((sid) => isValidSessionId(sid));
+            const invalidSids = entries.filter((sid) => !isValidSessionId(sid));
+            checks.push({
+                id: 'L3:l3-orphan-sessions',
+                ok: invalidSids.length === 0,
+                message: invalidSids.length === 0
+                    ? `All ${validSids.length} session(s) under .peaks/_runtime/ are valid (isValidSessionId)`
+                    : `${invalidSids.length} orphan session(s) under .peaks/_runtime/ fail isValidSessionId: ${invalidSids.slice(0, 5).join(', ')}${invalidSids.length > 5 ? '...' : ''}. Run \`peaks workspace clean --project <repo>\` to archive.`
+            });
+        }
+        else {
+            checks.push({
+                id: 'L3:l3-orphan-sessions',
+                ok: true,
+                message: 'No .peaks/_runtime/ directory; nothing to check.'
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'L3:l3-orphan-sessions',
+            ok: true,
+            message: `L3:l3-orphan-sessions probe failed (${getErrorMessage(error)}); skipping check`
+        });
+    }
+    try {
+        const memoryIndexPath = join(l3ProjectRoot, '.peaks/memory/index.json');
+        if (existsSync(memoryIndexPath)) {
+            const raw = readFileSync(memoryIndexPath, 'utf8');
+            try {
+                // Slice 2026-06-13-repair-pre-existing-test-failures: the
+                // production MemoryIndex schema (see
+                // src/services/memory/project-memory-service.ts) uses
+                // `version: 1` as the schema marker, NOT `schema_version`.
+                // Accept BOTH names for back-compat with any external index
+                // writers (e.g. a future `schema_version: '2.0.0'` form).
+                const parsed = JSON.parse(raw);
+                const schemaMarker = parsed.schema_version ?? parsed.version;
+                if (schemaMarker === undefined) {
+                    checks.push({
+                        id: 'L3:l3-memory-health',
+                        ok: false,
+                        message: '.peaks/memory/index.json missing schema_version / version field'
+                    });
+                }
+                else {
+                    const hotCount = Object.values(parsed.hot ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
+                    const warmCount = Object.values(parsed.warm ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
+                    checks.push({
+                        id: 'L3:l3-memory-health',
+                        ok: true,
+                        message: `.peaks/memory/index.json is well-formed JSON; version=${schemaMarker}; ${hotCount} hot + ${warmCount} warm memory entries`
+                    });
+                }
+            }
+            catch (parseError) {
+                checks.push({
+                    id: 'L3:l3-memory-health',
+                    ok: false,
+                    message: `.peaks/memory/index.json is not valid JSON: ${getErrorMessage(parseError)}`
+                });
+            }
+        }
+        else {
+            checks.push({
+                id: 'L3:l3-memory-health',
+                ok: true,
+                message: 'No .peaks/memory/index.json yet (no memories extracted)'
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'L3:l3-memory-health',
+            ok: true,
+            message: `L3:l3-memory-health probe failed (${getErrorMessage(error)}); skipping check`
+        });
+    }
+    const failed = checks.filter((check) => !check.ok).length;
+    return {
+        checks,
+        summary: {
+            ok: failed === 0,
+            passed: checks.length - failed,
+            failed
+        }
+    };
+}