peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/doctor/doctor-service/checks/gateguard-conflict.js

@@ -0,0 +1,164 @@
+/**
+ * Check: gateguard-fact-force hook does not intercept `.peaks/`
+ * writes (`integration:gateguard-peaks-conflict`).
+ *
+ * 2026-06-10 — the `gateguard-fact-force` hook is a third-party
+ * PreToolUse hook (NOT peaks-loop) that fires on Edit/Write and
+ * demands a 4-fact questionnaire before allowing the edit. 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. We warn when the hook is
+ * installed and 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 fixtures.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/** 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(projectRootResolver) {
+    const projectRoot = projectRootResolver();
+    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)
+    };
+}
+/**
+ * Pure mapping over a `GateguardProbeResult`. Exported so tests
+ * can drive the entry extraction without monkey-patching
+ * `~/.claude/settings.json`.
+ */
+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];
+}
+function run({ options, projectRootResolver }) {
+    const gateguardProbe = options.gateguardProbe ?? (() => defaultGateguardProbe(projectRootResolver));
+    try {
+        const probe = gateguardProbe();
+        const offending = collectGateguardEntries(probe);
+        if (offending.length === 0) {
+            return [{
+                    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'
+                }];
+        }
+        const unrouted = offending.filter((location) => !entrySkipsPeaks(location.entry));
+        if (unrouted.length === 0) {
+            return [{
+                    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`
+                }];
+        }
+        const sources = Array.from(new Set(unrouted.map((u) => u.sourcePath))).join(' + ');
+        const matchers = unrouted.map((u) => u.entry.matcher ?? '*').join(', ');
+        return [{
+                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) {
+        return [{
+                id: 'integration:gateguard-peaks-conflict',
+                ok: true,
+                message: `gateguard probe failed (${getErrorMessage(error)}); skipping check`
+            }];
+    }
+}
+export const check = {
+    name: 'gateguard-conflict',
+    run
+};

package/dist/services/doctor/doctor-service/checks/l3-memory-health.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check: `.peaks/memory/index.json` is well-formed JSON
+ * (`L3:l3-memory-health`).
+ *
+ * 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`.
+ * We accept BOTH names for back-compat with any external index
+ * writers (e.g. a future `schema_version: '2.0.0'` form).
+ *
+ * When no `.peaks/memory/index.json` exists yet, the check passes
+ * (fresh project — no memories have been extracted).
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/l3-memory-health.js

@@ -0,0 +1,57 @@
+/**
+ * Check: `.peaks/memory/index.json` is well-formed JSON
+ * (`L3:l3-memory-health`).
+ *
+ * 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`.
+ * We accept BOTH names for back-compat with any external index
+ * writers (e.g. a future `schema_version: '2.0.0'` form).
+ *
+ * When no `.peaks/memory/index.json` exists yet, the check passes
+ * (fresh project — no memories have been extracted).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+function run({ resolvedL3Root }) {
+    const memoryIndexPath = join(resolvedL3Root, '.peaks/memory/index.json');
+    if (!existsSync(memoryIndexPath)) {
+        return [{
+                id: 'L3:l3-memory-health',
+                ok: true,
+                message: 'No .peaks/memory/index.json yet (no memories extracted)'
+            }];
+    }
+    try {
+        const raw = readFileSync(memoryIndexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const schemaMarker = parsed.schema_version ?? parsed.version;
+        if (schemaMarker === undefined) {
+            return [{
+                    id: 'L3:l3-memory-health',
+                    ok: false,
+                    message: '.peaks/memory/index.json missing schema_version / version field'
+                }];
+        }
+        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);
+        return [{
+                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) {
+        return [{
+                id: 'L3:l3-memory-health',
+                ok: false,
+                message: `.peaks/memory/index.json is not valid JSON: ${getErrorMessage(parseError)}`
+            }];
+    }
+}
+export const check = {
+    name: 'l3-memory-health',
+    run
+};

package/dist/services/doctor/doctor-service/checks/l3-orphan-sessions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Check: orphan sessions under `.peaks/_runtime/` (`L3:l3-orphan-sessions`).
+ *
+ * Flags bare sids under `.peaks/_runtime/` that fail the
+ * `isValidSessionId` regex. The reducer skips canonical system
+ * subdirs that intentionally live under `.peaks/_runtime/`
+ * (e.g. `change/`, which routes reviewable artifacts per F3).
+ *
+ * Slice 2026-06-24-doctor-1xdetector-residual regression net: the
+ * reducer MUST exclude `change/` (and other system subdirs added
+ * by future F3 changes) — without the exclude-list the doctor
+ * flips the summary to fail on every clean workspace, which broke
+ * 7 doctor-family tests.
+ *
+ * When `.peaks/_runtime/` does not exist, the check passes
+ * (nothing to scan).
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/l3-orphan-sessions.js

@@ -0,0 +1,66 @@
+/**
+ * Check: orphan sessions under `.peaks/_runtime/` (`L3:l3-orphan-sessions`).
+ *
+ * Flags bare sids under `.peaks/_runtime/` that fail the
+ * `isValidSessionId` regex. The reducer skips canonical system
+ * subdirs that intentionally live under `.peaks/_runtime/`
+ * (e.g. `change/`, which routes reviewable artifacts per F3).
+ *
+ * Slice 2026-06-24-doctor-1xdetector-residual regression net: the
+ * reducer MUST exclude `change/` (and other system subdirs added
+ * by future F3 changes) — without the exclude-list the doctor
+ * flips the summary to fail on every clean workspace, which broke
+ * 7 doctor-family tests.
+ *
+ * When `.peaks/_runtime/` does not exist, the check passes
+ * (nothing to scan).
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/**
+ * Canonical system subdirs that intentionally live under
+ * `.peaks/_runtime/` and must NOT be flagged as orphan sessions.
+ *
+ * `change/` is the routing target for change-id reviewable
+ * artifacts per F3 audit-p1. Adding a new entry here requires
+ * also updating `RUNTIME_SYSTEM_SUBDIRS_DOC` in the comments
+ * below so the next maintainer knows why each entry is listed.
+ */
+const RUNTIME_SYSTEM_SUBDIRS = new Set(['change']);
+function run({ resolvedL3Root, isValidSessionId }) {
+    try {
+        const runtimeDir = join(resolvedL3Root, '.peaks/_runtime');
+        if (!existsSync(runtimeDir)) {
+            return [{
+                    id: 'L3:l3-orphan-sessions',
+                    ok: true,
+                    message: 'No .peaks/_runtime/ directory; nothing to check.'
+                }];
+        }
+        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));
+        return [{
+                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.`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: 'L3:l3-orphan-sessions',
+                ok: true,
+                message: `L3:l3-orphan-sessions probe failed (${getErrorMessage(error)}); skipping check`
+            }];
+    }
+}
+export const check = {
+    name: 'l3-orphan-sessions',
+    run
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Check: foundation schemas are valid JSON (`schema:<file>`).
+ *
+ * Emits one `DoctorCheck` per `requiredSchemaFiles` entry. Passes
+ * when the file parses as JSON; fails with the parse error message
+ * (so the operator sees e.g. "Unexpected token } in JSON at position
+ * 42" rather than a generic "invalid").
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/schema-validity.js

@@ -0,0 +1,33 @@
+/**
+ * Check: foundation schemas are valid JSON (`schema:<file>`).
+ *
+ * Emits one `DoctorCheck` per `requiredSchemaFiles` entry. Passes
+ * when the file parses as JSON; fails with the parse error message
+ * (so the operator sees e.g. "Unexpected token } in JSON at position
+ * 42" rather than a generic "invalid").
+ */
+import { join } from 'node:path';
+import { readText } from 'peaks-loop-shared/fs';
+import { requiredSchemaFiles } from 'peaks-loop-shared/paths';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+async function run({ schemaRoot }) {
+    const checks = [];
+    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)}`
+            });
+        }
+    }
+    return checks;
+}
+export const check = {
+    name: 'schema-validity',
+    run
+};

package/dist/services/doctor/doctor-service/checks/skill-apply-note.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Check: destructive `--apply` commands in the runbook carry an
+ * authorization/dry-run note (`skill-apply-note:<skill-name>`).
+ *
+ * Emits one `DoctorCheck` per *required* skill that has a
+ * `## Default runbook` section. The check extracts the runbook
+ * section, scans it for known destructive `--apply` patterns
+ * (`peaks memory sync --apply`, `peaks openspec archive --apply`,
+ * etc.), and requires an authorization-style note when any match
+ * is found. Skills with no destructive `--apply` commands emit a
+ * passing "no destructive --apply commands to gate" check so the
+ * CLI summary still surfaces a 1:1 row per required skill.
+ *
+ * The destructive-apply regex table and authorization keyword regex
+ * live in this file (not a shared util) because they are doctor-
+ * internal heuristics; the CLI's `runs/apply.ts` has its own
+ * (slightly different) authorisation gate.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/skill-apply-note.js

@@ -0,0 +1,85 @@
+/**
+ * Check: destructive `--apply` commands in the runbook carry an
+ * authorization/dry-run note (`skill-apply-note:<skill-name>`).
+ *
+ * Emits one `DoctorCheck` per *required* skill that has a
+ * `## Default runbook` section. The check extracts the runbook
+ * section, scans it for known destructive `--apply` patterns
+ * (`peaks memory sync --apply`, `peaks openspec archive --apply`,
+ * etc.), and requires an authorization-style note when any match
+ * is found. Skills with no destructive `--apply` commands emit a
+ * passing "no destructive --apply commands to gate" check so the
+ * CLI summary still surfaces a 1:1 row per required skill.
+ *
+ * The destructive-apply regex table and authorization keyword regex
+ * live in this file (not a shared util) because they are doctor-
+ * internal heuristics; the CLI's `runs/apply.ts` has its own
+ * (slightly different) authorisation gate.
+ */
+import { readText } from 'peaks-loop-shared/fs';
+import { requiredSkillNames } from 'peaks-loop-shared/paths';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const REQUIRED_SKILL_NAMES = new Set(requiredSkillNames);
+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)));
+}
+async function run({ registry }) {
+    const checks = [];
+    for (const skill of registry.skills) {
+        if (!REQUIRED_SKILL_NAMES.has(skill.name)) {
+            continue;
+        }
+        try {
+            const body = await readText(skill.skillPath);
+            const runbookSection = extractRunbookSection(body);
+            if (runbookSection === null) {
+                // No runbook section → the runbook check is the canonical
+                // signal for this failure; we intentionally do NOT emit a
+                // second `skill-apply-note:<name>` here so the doctor
+                // summary surfaces exactly one row per required skill.
+                continue;
+            }
+            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`
+                });
+                continue;
+            }
+            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) {
+            // Mirror the legacy behaviour: a read failure surfaces as a
+            // runbook failure (already emitted by the runbook check) and
+            // does NOT double-report here.
+            void getErrorMessage(error);
+        }
+    }
+    return checks;
+}
+export const check = {
+    name: 'skill-apply-note',
+    run
+};

package/dist/services/doctor/doctor-service/checks/skill-existence.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check: skill existence (`skill:<name>`).
+ *
+ * Emits one `DoctorCheck` per `requiredSkillNames` entry. The check
+ * passes when the loaded registry contains a skill whose `name`
+ * equals the required skill name. Fails with an actionable message
+ * identifying which required skill is missing.
+ *
+ * The required skill names come from `peaks-loop-shared/paths` so the
+ * doctor and the CLI agree on what "required" means.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/skill-existence.js

@@ -0,0 +1,30 @@
+/**
+ * Check: skill existence (`skill:<name>`).
+ *
+ * Emits one `DoctorCheck` per `requiredSkillNames` entry. The check
+ * passes when the loaded registry contains a skill whose `name`
+ * equals the required skill name. Fails with an actionable message
+ * identifying which required skill is missing.
+ *
+ * The required skill names come from `peaks-loop-shared/paths` so the
+ * doctor and the CLI agree on what "required" means.
+ */
+import { requiredSkillNames } from 'peaks-loop-shared/paths';
+function run({ registry }) {
+    const skillNames = new Set(registry.skills.map((skill) => skill.name));
+    const checks = [];
+    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}`
+        });
+    }
+    return checks;
+}
+export const check = {
+    name: 'skill-existence',
+    run
+};

package/dist/services/doctor/doctor-service/checks/skill-name-match.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check: skill name matches its directory (`skill-name:<directory>`).
+ *
+ * Emits one `DoctorCheck` per loaded skill. Passes when the parsed
+ * frontmatter `name` matches the on-disk directory name. A mismatch
+ * is a hard failure — the LLM picks skills by directory, so a drift
+ * between name and directory would silently lose routing.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/skill-name-match.js

@@ -0,0 +1,25 @@
+/**
+ * Check: skill name matches its directory (`skill-name:<directory>`).
+ *
+ * Emits one `DoctorCheck` per loaded skill. Passes when the parsed
+ * frontmatter `name` matches the on-disk directory name. A mismatch
+ * is a hard failure — the LLM picks skills by directory, so a drift
+ * between name and directory would silently lose routing.
+ */
+function run({ registry }) {
+    const checks = [];
+    for (const skill of registry.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}`
+        });
+    }
+    return checks;
+}
+export const check = {
+    name: 'skill-name-match',
+    run
+};

package/dist/services/doctor/doctor-service/checks/skill-parse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check: skill parse failures (`skill-parse:<directory>`).
+ *
+ * Emits one `DoctorCheck` per registry failure (one per skill whose
+ * SKILL.md frontmatter did not parse). All checks fail — the skill
+ * is unusable, so the doctor surfaces it. The message echoes the
+ * parse error so the operator can locate the broken metadata.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/skill-parse.js

@@ -0,0 +1,19 @@
+/**
+ * Check: skill parse failures (`skill-parse:<directory>`).
+ *
+ * Emits one `DoctorCheck` per registry failure (one per skill whose
+ * SKILL.md frontmatter did not parse). All checks fail — the skill
+ * is unusable, so the doctor surfaces it. The message echoes the
+ * parse error so the operator can locate the broken metadata.
+ */
+function run({ registry }) {
+    return registry.failures.map((failure) => ({
+        id: `skill-parse:${failure.directory}`,
+        ok: false,
+        message: `Skill ${failure.directory} has invalid metadata: ${failure.message}`
+    }));
+}
+export const check = {
+    name: 'skill-parse',
+    run
+};

package/dist/services/doctor/doctor-service/checks/skill-presence.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Check: skill presence current + freshness
+ * (`skill-presence:current` and `skill-presence:freshness`).
+ *
+ * Two checks sharing one read of the `presence` context field.
+ *   - `skill-presence:current` is informational: passes when the
+ *     presence is wired, with a message describing the active
+ *     skill / mode / gate / setAt. When no presence is wired, it
+ *     also passes (absence is the common case outside peaks-qa
+ *     flows).
+ *   - `skill-presence:freshness` is the operational gate: fails
+ *     when the presence's `setAt` is older than the freshness
+ *     threshold (default 24h) OR when `setAt` is unparsable. When
+ *     no presence is wired it passes trivially ("nothing to age-
+ *     check").
+ *
+ * Both checks share the presence signal computed once in
+ * `index.ts`; the legacy monolithic function probed it inline.
+ */
+import type { DoctorCheckPlugin } from '../types.js';
+export declare const check: DoctorCheckPlugin;