peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -0,0 +1,254 @@
+/**
+ * doctor-service facade (slice rid-004).
+ *
+ * Public entrypoint for the code-driven fixed-registry doctor
+ * pipeline. Replaces the legacy 1309-line monolithic `runDoctor`
+ * with a thin dispatcher that:
+ *
+ *   1. Resolves all cross-domain injections (project-root resolver,
+ *      skill loader, sid validator, schema root, presence, etc.)
+ *      and builds a read-only `DoctorContext` once.
+ *   2. Walks the `PLUGINS` array in `plugin-registry.ts` in order,
+ *      calling each plugin's `run(context)`, flattening the
+ *      returned `DoctorCheck[]` into the accumulator.
+ *   3. Updates `context.accumulatedChecks` after each plugin so the
+ *      `check-id-schema` self-validation plugin observes the full
+ *      prior list.
+ *   4. Hands the accumulated checks to `report/final-summary.ts`
+ *      which builds the public `DoctorReport`.
+ *
+ * The `runDoctor` signature is unchanged from the legacy version;
+ * main peaks-loop package imports it via
+ * `import { runDoctor } from '../index.js'`.
+ *
+ * slice-3b Option C: the doctor package stays standalone by
+ * accepting the cross-domain utilities as injectable probes. When
+ * no injection is provided, the doctor falls back to a safe
+ * "no-op / assume healthy" probe so the standalone test suite
+ * does not depend on the main package. The CLI wires the main-
+ * package implementations at call-site
+ * (`src/cli/commands/core/doctor-command.ts`).
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { schemasDir, skillsDir } from 'peaks-loop-shared/paths';
+import { PLUGINS } from './plugin-registry.js';
+import { buildReport } from './report/final-summary.js';
+/**
+ * slice-3b Option C: inlined sid regex. The main package's canonical
+ * definition lives in `src/services/workspace/sid-naming-guard.ts`. The
+ * regex MUST stay byte-identical with that file. If
+ * `sid-naming-guard.ts` is ever moved to `peaks-loop-shared`, swap this
+ * for a `peaks-loop-shared/workspace/sid-naming-guard` import and drop
+ * the inlined copy.
+ */
+const VALID_SID_REGEX = /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])-session-[0-9a-z]{3,6}$/;
+function defaultIsValidSessionId(sid) {
+    return VALID_SID_REGEX.test(sid);
+}
+function defaultProjectRootResolver() {
+    // slice-3b Option C: minimal in-package project-root resolver.
+    // Mirrors the high-level behaviour of the main package's
+    // `findProjectRoot` (src/services/config/config-safety.ts) without
+    // pulling in its full safety-validation surface. The CLI may
+    // inject a richer resolver at call-site.
+    let current = process.cwd();
+    let pkgRoot = null;
+    while (true) {
+        const parent = dirname(current);
+        if (parent === current) {
+            return pkgRoot;
+        }
+        if (existsSync(join(current, '.peaks', 'config.json'))) {
+            return current;
+        }
+        if (existsSync(join(current, '.git'))) {
+            return current;
+        }
+        if (pkgRoot === null && existsSync(join(current, 'package.json'))) {
+            pkgRoot = current;
+        }
+        current = parent;
+    }
+}
+/**
+ * Pure helper extracted 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')));
+}
+function defaultWorkspaceInitializedProbe(projectRootResolver) {
+    const projectRoot = projectRootResolver();
+    if (projectRoot === null)
+        return false;
+    // Workspace is "initialized" when EITHER the canonical runtime-layer
+    // session binding (`.peaks/_runtime/session.json`) OR the legacy
+    // top-level binding (`.peaks/.session.json`, kept as read-only
+    // back-compat for one minor release) is present.
+    return isWorkspaceInitializedAt(projectRoot);
+}
+async function defaultLoadSkills(baseDir, listDirectories, pathExists, readText) {
+    // slice-3b Option C: minimal skill-loader. Walks
+    // `<baseDir>/*/SKILL.md` (and one level into `bee/`, mirroring the
+    // upstream `skill-registry.ts`), parses the frontmatter, and returns
+    // `{ skills, failures }`. The CLI may inject a richer loader at
+    // call-site.
+    const target = baseDir ?? skillsDir;
+    if (!(await pathExists(target))) {
+        return { skills: [], failures: [] };
+    }
+    const skills = [];
+    const failures = [];
+    const directories = await listDirectories(target);
+    for (const directory of directories) {
+        if (directory === 'bee') {
+            const subEntries = await listDirectories(join(target, 'bee'));
+            for (const subDir of subEntries) {
+                const skillPath = join(target, 'bee', subDir, 'SKILL.md');
+                if (!(await pathExists(skillPath)))
+                    continue;
+                try {
+                    const { name } = parseDoctorSkillFrontmatter(await readText(skillPath));
+                    skills.push({ name, directory: subDir, skillPath });
+                }
+                catch (error) {
+                    failures.push({ directory: subDir, skillPath, message: getErrorMessageLite(error) });
+                }
+            }
+            continue;
+        }
+        const skillPath = join(target, directory, 'SKILL.md');
+        if (!(await pathExists(skillPath)))
+            continue;
+        try {
+            const { name } = parseDoctorSkillFrontmatter(await readText(skillPath));
+            skills.push({ name, directory, skillPath });
+        }
+        catch (error) {
+            failures.push({ directory, skillPath, message: getErrorMessageLite(error) });
+        }
+    }
+    skills.sort((left, right) => left.name.localeCompare(right.name));
+    failures.sort((left, right) => left.directory.localeCompare(right.directory));
+    return { skills, failures };
+}
+function parseDoctorSkillFrontmatter(body) {
+    // slice-3b Option C: minimal SKILL.md frontmatter parser. The
+    // doctor only needs `name` and `description` for the
+    // skill-name-matches-directory and skill-runbook checks.
+    const lines = body.split(/\r?\n/);
+    if (lines[0] !== '---') {
+        throw new Error('Missing YAML frontmatter opening marker');
+    }
+    const endIndex = lines.findIndex((line, index) => index > 0 && line === '---');
+    if (endIndex === -1) {
+        throw new Error('Missing YAML frontmatter closing marker');
+    }
+    const metadata = {};
+    for (let index = 1; index < endIndex; index += 1) {
+        const line = lines[index];
+        if (line === undefined)
+            continue;
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const match = /^([A-Za-z0-9_.-]+):\s*(.*)$/.exec(trimmed);
+        if (match?.[1] === undefined)
+            continue;
+        metadata[match[1]] = (match[2] ?? '').trim().replace(/^['"]|['"]$/g, '');
+    }
+    if (!metadata.name) {
+        throw new Error('Missing required frontmatter field: name');
+    }
+    if (!metadata.description) {
+        throw new Error('Missing required frontmatter field: description');
+    }
+    return { name: metadata.name, description: metadata.description };
+}
+function getErrorMessageLite(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/**
+ * Public entrypoint. Walks the `PLUGINS` array, building the
+ * `DoctorContext` once at the top and threading it through every
+ * plugin. The accumulator is a mutable list shared via
+ * `context.accumulatedChecks` so plugins like `check-id-schema`
+ * that need to observe the prior list can do so.
+ */
+export async function runDoctor(options = {}) {
+    // slice-3b Option C: resolve the cross-domain injections up front.
+    const projectRootResolver = options.projectRootResolver ?? defaultProjectRootResolver;
+    const isValidSessionId = options.isValidSessionIdProbe ?? defaultIsValidSessionId;
+    const fsModule = await import('peaks-loop-shared/fs');
+    const listDirectoriesImpl = (target) => fsModule.listDirectories(target);
+    const pathExistsImpl = (target) => fsModule.pathExists(target);
+    const readTextImpl = (target) => fsModule.readText(target);
+    const loadSkills = options.loadSkills ?? ((baseDir) => defaultLoadSkills(baseDir, listDirectoriesImpl, pathExistsImpl, readTextImpl));
+    const registry = await loadSkills(options.skillsBaseDir);
+    const skills = registry.skills;
+    const schemaRoot = options.schemasBaseDir ?? schemasDir;
+    // Skill presence: probe once up front, swallowing probe errors.
+    let presence = null;
+    if (options.skillPresenceProbe !== undefined) {
+        try {
+            presence = options.skillPresenceProbe();
+        }
+        catch {
+            presence = null;
+        }
+    }
+    // Workspace initialized: probe once up front, swallowing probe errors.
+    const workspaceProbe = options.workspaceInitializedProbe ?? (() => defaultWorkspaceInitializedProbe(projectRootResolver));
+    let workspaceInitialized = false;
+    try {
+        workspaceInitialized = workspaceProbe();
+    }
+    catch {
+        workspaceInitialized = false;
+    }
+    // Statusline installed: the legacy code uses a fallback wrapper that
+    // returns false when the CLI injects nothing. Replicate that here.
+    const statusLineProbe = options.statusLineInstalledProbe ?? (() => false);
+    let statusLineInstalled = false;
+    try {
+        statusLineInstalled = statusLineProbe();
+    }
+    catch {
+        statusLineInstalled = false;
+    }
+    const platform = options.platform ?? process.platform;
+    const resolvedL3Root = options.l3ProjectRoot ?? projectRootResolver() ?? process.cwd();
+    // Build the context. We use a mutable holder for the accumulator
+    // so plugins reading `context.accumulatedChecks` see prior
+    // emissions; the dispatcher updates the array reference after
+    // each plugin runs.
+    const accumulated = [];
+    const context = {
+        options,
+        registry,
+        skills,
+        schemaRoot,
+        presence,
+        workspaceInitialized,
+        statusLineInstalled,
+        platform,
+        resolvedL3Root,
+        projectRootResolver,
+        isValidSessionId,
+        accumulatedChecks: accumulated
+    };
+    for (const plugin of PLUGINS) {
+        const emitted = await plugin.run(context);
+        for (const check of emitted) {
+            accumulated.push(check);
+        }
+    }
+    return buildReport(accumulated);
+}

package/dist/services/doctor/doctor-service/plugin-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * doctor-service plugin registry (slice rid-004).
+ *
+ * Holds the fixed-order, code-driven list of `DoctorCheckPlugin`
+ * instances that `runDoctor` iterates. The order is the same as the
+ * legacy monolithic function body — preserving the on-disk check
+ * ordering keeps the existing `report.checks` array unchanged for
+ * every consumer (CLI summary, JSON output, schema self-check).
+ *
+ * Why code-driven (not data-driven):
+ *   - Each check has distinct typed inputs (skills, presence, layout
+ *     probe, gateguard probe, …) and conditional logic that a config
+ *     table cannot express without losing type safety.
+ *   - The check ordering is load-bearing — `skill-presence:workspace`
+ *     depends on `presence` being probed, `doctor-self:check-id-pattern`
+ *     depends on every prior check's IDs, and `L3:l3-orphan-sessions` /
+ *     `L3:l3-memory-health` run last so they observe a clean post-F3
+ *     layout. A config-driven registry would obscure that ordering
+ *     and force callers to read two files to understand execution
+ *     flow. Code-driven keeps it auditable in one place.
+ *   - Adding a check is a code change in any case (the typed probe
+ *     surface has to grow). A code-driven registry makes the diff
+ *     self-contained.
+ *
+ * Adding a new check:
+ *   1. Create `checks/<your-check>.ts` exporting
+ *      `export const check: DoctorCheckPlugin`.
+ *   2. Append `check` to the `PLUGINS` array below IN THE EXACT
+ *      POSITION THE LEGACY MONOLITHIC FUNCTION EMITS IT.
+ *   3. If you need new context state, extend `DoctorContext` in
+ *      `types.ts` and populate it in `index.ts`.
+ */
+import type { DoctorCheckPlugin } from './types.js';
+/**
+ * Ordered list of doctor check plugins. The order mirrors the legacy
+ * monolithic `runDoctor` function body verbatim — DO NOT REORDER
+ * without first re-reading the consumer-side tests in
+ * `tests/doctor.test.ts` / `tests/doctor/35-checks-aggregate.test.ts`
+ * and updating the expected check-id list.
+ */
+export declare const PLUGINS: ReadonlyArray<DoctorCheckPlugin>;

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

@@ -0,0 +1,77 @@
+/**
+ * doctor-service plugin registry (slice rid-004).
+ *
+ * Holds the fixed-order, code-driven list of `DoctorCheckPlugin`
+ * instances that `runDoctor` iterates. The order is the same as the
+ * legacy monolithic function body — preserving the on-disk check
+ * ordering keeps the existing `report.checks` array unchanged for
+ * every consumer (CLI summary, JSON output, schema self-check).
+ *
+ * Why code-driven (not data-driven):
+ *   - Each check has distinct typed inputs (skills, presence, layout
+ *     probe, gateguard probe, …) and conditional logic that a config
+ *     table cannot express without losing type safety.
+ *   - The check ordering is load-bearing — `skill-presence:workspace`
+ *     depends on `presence` being probed, `doctor-self:check-id-pattern`
+ *     depends on every prior check's IDs, and `L3:l3-orphan-sessions` /
+ *     `L3:l3-memory-health` run last so they observe a clean post-F3
+ *     layout. A config-driven registry would obscure that ordering
+ *     and force callers to read two files to understand execution
+ *     flow. Code-driven keeps it auditable in one place.
+ *   - Adding a check is a code change in any case (the typed probe
+ *     surface has to grow). A code-driven registry makes the diff
+ *     self-contained.
+ *
+ * Adding a new check:
+ *   1. Create `checks/<your-check>.ts` exporting
+ *      `export const check: DoctorCheckPlugin`.
+ *   2. Append `check` to the `PLUGINS` array below IN THE EXACT
+ *      POSITION THE LEGACY MONOLITHIC FUNCTION EMITS IT.
+ *   3. If you need new context state, extend `DoctorContext` in
+ *      `types.ts` and populate it in `index.ts`.
+ */
+import { check as skillExistence } from './checks/skill-existence.js';
+import { check as skillNameMatch } from './checks/skill-name-match.js';
+import { check as skillParse } from './checks/skill-parse.js';
+import { check as skillRunbook } from './checks/skill-runbook.js';
+import { check as skillApplyNote } from './checks/skill-apply-note.js';
+import { check as schemaValidity } from './checks/schema-validity.js';
+import { check as userConfig } from './checks/user-config.js';
+import { check as skillPresence } from './checks/skill-presence.js';
+import { check as workspaceInit } from './checks/workspace-init.js';
+import { check as statuslineInstall } from './checks/statusline-install.js';
+import { check as statuslineRuntime } from './checks/statusline-runtime.js';
+import { check as codegraphCapability } from './checks/codegraph-capability.js';
+import { check as distSourceVersion } from './checks/dist-source-version.js';
+import { check as workspaceLayout } from './checks/workspace-layout.js';
+import { check as gateguardConflict } from './checks/gateguard-conflict.js';
+import { check as checkIdSchema } from './checks/check-id-schema.js';
+import { check as l3OrphanSessions } from './checks/l3-orphan-sessions.js';
+import { check as l3MemoryHealth } from './checks/l3-memory-health.js';
+/**
+ * Ordered list of doctor check plugins. The order mirrors the legacy
+ * monolithic `runDoctor` function body verbatim — DO NOT REORDER
+ * without first re-reading the consumer-side tests in
+ * `tests/doctor.test.ts` / `tests/doctor/35-checks-aggregate.test.ts`
+ * and updating the expected check-id list.
+ */
+export const PLUGINS = [
+    skillExistence, // id prefix "skill:"
+    skillNameMatch, // id prefix "skill-name:"
+    skillParse, // id prefix "skill-parse:"
+    skillRunbook, // id prefix "skill-runbook:"
+    skillApplyNote, // id prefix "skill-apply-note:"
+    schemaValidity, // id prefix "schema:"
+    userConfig, // id "config:user"
+    skillPresence, // ids "skill-presence:current" + "skill-presence:freshness"
+    workspaceInit, // id "skill-presence:workspace"
+    statuslineInstall, // id "statusline:install"
+    statuslineRuntime, // id "statusline:runtime"
+    codegraphCapability, // id "capability:codegraph"
+    distSourceVersion, // id "build:dist-version-matches-source"
+    workspaceLayout, // id "build:workspace-layout-canonical"
+    gateguardConflict, // id "integration:gateguard-peaks-conflict"
+    checkIdSchema, // id "doctor-self:check-id-pattern"
+    l3OrphanSessions, // id "L3:l3-orphan-sessions"
+    l3MemoryHealth, // id "L3:l3-memory-health"
+];

package/dist/services/doctor/doctor-service/report/final-summary.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Report aggregator: convert the accumulated `DoctorCheck[]` into the
+ * public `DoctorReport` shape (checks + summary).
+ *
+ * The summary is a pure reduction over the checks — it counts the
+ * passing and failing rows, derives `ok = failed === 0`, and
+ * returns the `{ checks, summary }` tuple. Kept in its own module
+ * so the dispatcher (`index.ts`) stays a thin orchestration loop
+ * and the aggregation rule has a single test surface.
+ */
+import type { DoctorCheck, DoctorReport } from '../types.js';
+/**
+ * Build the final report from the accumulated checks.
+ *
+ * Pure function — no I/O, no clock dependency. The dispatcher
+ * passes the checks it accumulated across the registry run; this
+ * function computes the summary in O(n) and returns the immutable
+ * report shape the public API exposes.
+ */
+export declare function buildReport(checks: readonly DoctorCheck[]): DoctorReport;

package/dist/services/doctor/doctor-service/report/final-summary.js

@@ -0,0 +1,29 @@
+/**
+ * Report aggregator: convert the accumulated `DoctorCheck[]` into the
+ * public `DoctorReport` shape (checks + summary).
+ *
+ * The summary is a pure reduction over the checks — it counts the
+ * passing and failing rows, derives `ok = failed === 0`, and
+ * returns the `{ checks, summary }` tuple. Kept in its own module
+ * so the dispatcher (`index.ts`) stays a thin orchestration loop
+ * and the aggregation rule has a single test surface.
+ */
+/**
+ * Build the final report from the accumulated checks.
+ *
+ * Pure function — no I/O, no clock dependency. The dispatcher
+ * passes the checks it accumulated across the registry run; this
+ * function computes the summary in O(n) and returns the immutable
+ * report shape the public API exposes.
+ */
+export function buildReport(checks) {
+    const failed = checks.filter((check) => !check.ok).length;
+    return {
+        checks: [...checks],
+        summary: {
+            ok: failed === 0,
+            passed: checks.length - failed,
+            failed
+        }
+    };
+}

package/dist/services/doctor/doctor-service/types.d.ts

@@ -0,0 +1,245 @@
+/**
+ * doctor-service types and shared interfaces (slice rid-004).
+ *
+ * This module is the public type surface for the code-driven fixed
+ * registry of doctor checks. Each check is a `DoctorCheckPlugin`
+ * that receives a shared `DoctorContext` (built once at the top of
+ * `runDoctor`) and returns the `DoctorCheck[]` it emits. The registry
+ * in `plugin-registry.ts` lists the plugins in fixed execution order.
+ *
+ * The legacy `runDoctor` API is preserved end-to-end: the public
+ * `DoctorCheck / DoctorReport / DoctorOptions / *Probe` types still
+ * flow through the same names so the main package's `import { runDoctor }`
+ * keeps working unchanged.
+ */
+export type DoctorCheck = {
+    id: string;
+    ok: boolean;
+    message: string;
+};
+export type DoctorReport = {
+    checks: DoctorCheck[];
+    summary: {
+        ok: boolean;
+        passed: number;
+        failed: number;
+    };
+};
+export type CodegraphCapabilityProbe = {
+    packagePath: string;
+    version: string;
+    binaryPath: string;
+    binaryExists: boolean;
+};
+export type DistVersionComparison = {
+    dist: string | null;
+    source: string;
+    match: boolean;
+    distReadable: boolean;
+};
+export type DistVersionProbe = () => DistVersionComparison;
+export type WorkspaceLayoutInspection = {
+    topLevelSessionDirs: string[];
+    legacyDotfiles: string[];
+    /**
+     * Slice 007 — per-change-id top-level dirs (e.g. `.peaks/001-2026-06-06-.../`).
+     * The pre-F3 canonical layout put reviewable artifacts under a
+     * per-change-id top-level dir; the post-F3 canonical layout
+     * consolidates them under `.peaks/_runtime/<sid>/<role>/`. Any
+     * leftover per-change-id top-level dir is a regression to flag.
+     * Slice 008's migration will consolidate these; until then, the
+     * check reports them as `ok: false`.
+     *
+     * Optional in the type for back-compat with test probes that
+     * pre-date the slice 007 broadening; the check itself falls back
+     * to an empty array when the field is missing.
+     */
+    perChangeIdDirs?: string[];
+};
+export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
+/**
+ * 2026-06-10 — `gateguard-fact-force` (a third-party PreToolUse hook,
+ * NOT peaks-loop) fires on Edit / Write and demands a 4-fact questionnaire
+ * before allowing the edit. When the LLM is in a peaks-qa flow and tries
+ * to update `.peaks/_runtime/<sid>/qa/requests/*.md` via the Edit/Write
+ * tool, the hook demands facts that are inapplicable to QA envelope
+ * templates (no importers, no public API, no data files, user
+ * instruction already in the conversation context). The check detects
+ * this hook in the user's global and project `.claude/settings.json` and
+ * warns when no `.peaks/**` skip is configured. The probe is injected so
+ * tests do not depend on the real `~/.claude/settings.json` state.
+ */
+export type GateguardHookLocation = {
+    /** Source file the hook was discovered in (`global` or `project .claude/settings.json`). */
+    source: 'global' | 'project';
+    /** Resolved absolute path to the source file (for the message). */
+    sourcePath: string;
+    /** The PreToolUse entry that contains a gateguard hook command. */
+    entry: {
+        matcher?: string;
+        hooks: ReadonlyArray<{
+            type?: string;
+            command?: string;
+        }>;
+    };
+};
+export type GateguardProbeResult = {
+    /** Absolute path to `~/.claude/settings.json` (or null when the probe could not resolve it). */
+    globalSettingsPath: string | null;
+    /** Parsed global settings payload (or null when missing / unreadable / malformed). */
+    globalSettings: unknown;
+    /** Absolute path to the project `.claude/settings.json` (or null when the project root is not in a peaks project). */
+    projectSettingsPath: string | null;
+    /** Parsed project settings payload (or null when missing / unreadable / malformed). */
+    projectSettings: unknown;
+};
+export type GateguardProbe = () => GateguardProbeResult;
+/**
+ * Subset of SkillPresence consumed by the doctor (slice-3b: the full
+ * `SkillPresence` type lives in `src/services/skills/skill-presence-service.ts`;
+ * the doctor only needs `skill / mode / gate / setAt` for the freshness /
+ * workspace / statusline checks). The probe-returned object must satisfy
+ * this structural shape; the main package reuses the upstream
+ * `SkillPresence` directly so callers do not need to remap.
+ */
+export type DoctorSkillPresence = {
+    skill: string;
+    mode?: string;
+    gate?: string;
+    setAt: string;
+};
+/**
+ * Subset of SkillMetadata consumed by the doctor (slice-3b: the full
+ * type lives in `src/services/skills/skill-registry.ts`; the doctor only
+ * needs `name / directory / skillPath` for the runbook / name-match /
+ * schema checks). Failures from upstream have `directory + message`.
+ */
+export type DoctorSkillEntry = {
+    name: string;
+    directory: string;
+    skillPath: string;
+};
+export type DoctorSkillLoadFailure = {
+    directory: string;
+    skillPath: string;
+    message: string;
+};
+export type DoctorSkillsResult = {
+    skills: DoctorSkillEntry[];
+    failures: DoctorSkillLoadFailure[];
+};
+export type DoctorOptions = {
+    schemasBaseDir?: string;
+    skillsBaseDir?: string;
+    codegraphProbe?: () => CodegraphCapabilityProbe;
+    skillPresenceProbe?: () => DoctorSkillPresence | null;
+    skillPresenceFreshnessThresholdMs?: number;
+    statusLineInstalledProbe?: () => boolean;
+    /** Returns true when a Peaks workspace session (.peaks/.session.json) exists. */
+    workspaceInitializedProbe?: () => boolean;
+    /** Platform string (defaults to process.platform); injectable for tests. */
+    platform?: NodeJS.Platform;
+    /** Injected for the build:dist-version-matches-source check (defaults to compareDistVersion on disk). */
+    distVersionProbe?: DistVersionProbe;
+    /** Injected for the build:workspace-layout-canonical check (defaults to inspectWorkspaceLayout on disk). */
+    workspaceLayoutProbe?: WorkspaceLayoutProbe;
+    /** Injected for the integration:gateguard-peaks-conflict check (defaults to defaultGateguardProbe on disk). */
+    gateguardProbe?: GateguardProbe;
+    /**
+     * Slice 2026-06-13-repair-pre-existing-test-failures: injected
+     * root for the L3:l3-memory-health check (defaults to
+     * `findProjectRoot(process.cwd())`). Tests use this to point the
+     * check at a temp dir without monkey-patching `findProjectRoot`.
+     */
+    l3ProjectRoot?: string;
+    /**
+     * slice-3b Option C: injected project-root resolver.
+     * Replaces the legacy direct call to
+     * `findProjectRoot(process.cwd())` from
+     * `src/services/config/config-safety.ts`. Defaults to a noop
+     * (`() => null`) so standalone tests do not depend on the main
+     * package; the CLI wires `findProjectRoot(process.cwd())` at
+     * call-site.
+     */
+    projectRootResolver?: () => string | null;
+    /**
+     * slice-3b Option C: injected skill loader.
+     * Replaces `loadSkillRegistry` from
+     * `src/services/skills/skill-registry.ts`. Defaults to a noop
+     * `Promise<{ skills: [], failures: [] }>` so standalone tests do
+     * not depend on the main package; the CLI wires the real loader
+     * at call-site.
+     */
+    loadSkills?: (skillsBaseDir?: string) => Promise<DoctorSkillsResult>;
+    /**
+     * slice-3b Option C: injected sid validator.
+     * Replaces `isValidSessionId` from
+     * `src/services/workspace/sid-naming-guard.ts`. Defaults to the
+     * canonical regex below (kept in sync with the main-package
+     * source). The CLI may inject a different implementation but
+     * should keep behaviour identical.
+     */
+    isValidSessionIdProbe?: (sid: string) => boolean;
+};
+/**
+ * Shared context passed to every plugin. The context is built once at
+ * the top of `runDoctor` and is read-only for the duration of check
+ * execution — plugins must not mutate it.
+ *
+ * The set of fields is the minimum union of state that the legacy
+ * monolithic `runDoctor` derived locally. Each plugin reads only what
+ * it needs; nothing forces a plugin to consume every field.
+ */
+export type DoctorContext = {
+    /** The options object passed to `runDoctor`. */
+    readonly options: DoctorOptions;
+    /** Loaded skill registry (skills + failures). Already populated. */
+    readonly registry: DoctorSkillsResult;
+    /** Skills extracted from the registry (alias for `registry.skills`). */
+    readonly skills: DoctorSkillEntry[];
+    /** Resolved schema root dir for the schema validity check. */
+    readonly schemaRoot: string;
+    /** Skill presence result (null when no probe is wired or the probe returned null). */
+    readonly presence: DoctorSkillPresence | null;
+    /** Workspace initialized boolean (false when probe missing or not yet initialized). */
+    readonly workspaceInitialized: boolean;
+    /** Statusline installed boolean (false when probe missing or not installed). */
+    readonly statusLineInstalled: boolean;
+    /** Resolved platform string (defaults to process.platform). */
+    readonly platform: NodeJS.Platform;
+    /** Resolved L3 project root (defaults to projectRootResolver() ?? process.cwd()). */
+    readonly resolvedL3Root: string;
+    /** Final injected project-root resolver. */
+    readonly projectRootResolver: () => string | null;
+    /** Final injected session-id validator. */
+    readonly isValidSessionId: (sid: string) => boolean;
+    /**
+     * Mutable accumulator of checks emitted by prior plugins in the
+     * registry. The dispatcher (index.ts) updates this BEFORE each
+     * plugin runs so the `check-id-schema` self-validation sees the
+     * full prior check list. Reads treat it as a snapshot.
+     *
+     * The field is intentionally a live mutable reference rather
+     * than a per-plugin snapshot — building a snapshot for every
+     * plugin would cost O(n²) on the accumulated array size and
+     * add nothing the dispatcher cannot already guarantee.
+     */
+    readonly accumulatedChecks: readonly DoctorCheck[];
+};
+/**
+ * Doctor check plugin contract. Each plugin receives a shared context
+ * and returns the `DoctorCheck[]` it emits. Plugins may be sync or
+ * async; the registry runs them in order via `await`.
+ *
+ * Design: the plugin is the smallest possible closure over the
+ * context — it owns no mutable state, so the same plugin instance
+ * can be safely reused across multiple `runDoctor()` calls. The
+ * plugin name doubles as the human-readable identifier in any future
+ * `--list-checks` style diagnostic.
+ */
+export type DoctorCheckPlugin = {
+    /** Stable identifier (e.g. `skill-existence`). Used by tests and registry debugging. */
+    readonly name: string;
+    /** Run the check; return every check this plugin emits (typically 1+). */
+    run: (context: DoctorContext) => Promise<readonly DoctorCheck[]> | readonly DoctorCheck[];
+};