peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/skills/skill-presence-service.js

@@ -0,0 +1,474 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { findProjectRoot } from '../config/config-safety.js';
+import { ensureMemoryBootstrap } from '../memory/project-memory-service.js';
+import { getSessionMeta } from '../session/session-manager.js';
+export const VALID_SKILL_PRESENCE_MODES = [
+    'full-auto',
+    'assisted',
+    'swarm',
+    'strict'
+];
+export function isSkillPresenceMode(value) {
+    return VALID_SKILL_PRESENCE_MODES.includes(value);
+}
+/**
+ * The current outer session id, exposed to Bash tool calls via the
+ * `PEAKS_OUTER_SESSION_ID` environment variable. Stamping it onto the
+ * presence file lets the read-only status line tell whether the recorded
+ * skill belongs to the live session (show it) or a previous one
+ * (render idle). Falls back to `CLAUDE_CODE_SESSION_ID` for Claude Code
+ * so existing Claude Code users get the field populated without any
+ * configuration; other harnesses that want a presence stamp can set
+ * either variable.
+ */
+function getCurrentOuterSessionId() {
+    const peaks = process.env.PEAKS_OUTER_SESSION_ID;
+    if (typeof peaks === 'string' && peaks.length > 0)
+        return peaks;
+    const claude = process.env.CLAUDE_CODE_SESSION_ID;
+    if (typeof claude === 'string' && claude.length > 0)
+        return claude;
+    return undefined;
+}
+// As of slice 2026-06-05-peaks-runtime-layer the orchestrator's
+// active-skill marker lives under `.peaks/_runtime/active-skill.json`.
+// The legacy `.peaks/.active-skill.json` path is preserved as a
+// read-only fallback for one minor release so older CLI versions (or
+// trees that have not been migrated by `peaks workspace reconcile`)
+// keep working without a forced re-init.
+const PRESENCE_FILE = join('.peaks', '_runtime', 'active-skill.json');
+const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
+const SESSION_FILE = join('.peaks', '_runtime', 'session.json');
+const SESSION_FILE_LEGACY = '.peaks/.session.json';
+function resolveProjectRoot(override) {
+    if (override)
+        return resolve(override);
+    return findProjectRoot(process.cwd()) ?? process.cwd();
+}
+function resolvePresencePath(projectRootOverride) {
+    return resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE);
+}
+/**
+ * Back-compat read for the active-skill marker. Prefers the new
+ * canonical `.peaks/_runtime/active-skill.json`; falls back to the
+ * legacy `.peaks/.active-skill.json` for one minor release.
+ *
+ * Returns the parsed SkillPresence object, or null when neither
+ * file is present / valid. The legacy file is never written by
+ * current code — only the new path receives writes.
+ */
+function readSkillPresenceBackCompat(projectRootOverride) {
+    const presencePath = resolvePresencePath(projectRootOverride);
+    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
+    const pathToRead = existsSync(presencePath) ? presencePath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.skill !== 'string' || parsed.skill.length === 0) {
+            return null;
+        }
+        return { presence: parsed, path: pathToRead };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Resolve the active peaks session id from
+ * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
+ * Returns `null` when no session is bound.
+ *
+ * Public export: callers like `peaks sub-agent dispatch` use this
+ * to auto-resolve `--session-id` when the LLM driver forgets to
+ * pass the flag, so dispatch records land in the right
+ * `.peaks/_sub_agents/<sid>/` tree instead of an `unknown-sid`
+ * fallback (slice 2026-06-26-unknown-sid-fallback-fix).
+ */
+export function getCurrentSessionId(projectRootOverride) {
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const sessionPath = resolve(projectRoot, SESSION_FILE);
+    const legacyPath = resolve(projectRoot, SESSION_FILE_LEGACY);
+    // Back-compat window: prefer the new canonical path; fall back to the
+    // legacy `.peaks/.session.json` for one minor release.
+    const pathToRead = existsSync(sessionPath) ? sessionPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(pathToRead, 'utf8'));
+        return typeof data.sessionId === 'string' && data.sessionId.length > 0
+            ? data.sessionId
+            : null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Look up the outer-session-id that was bound to the *current* peaks
+ * session, i.e. the one written to the per-session
+ * `.peaks/_runtime/<sid>/session.json` by `ensureSession`/`initWorkspace`. This
+ * is the source of truth for "which outer session owns the
+ * in-flight peaks session".
+ *
+ * Returns `null` if no peaks session is bound yet, or if the bound
+ * session has no recorded outer session id (legacy sessions predating
+ * the outer-session contract).
+ */
+function getBoundOuterSessionId(projectRootOverride) {
+    const sessionId = getCurrentSessionId(projectRootOverride);
+    if (sessionId === null)
+        return undefined;
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    const meta = getSessionMeta(projectRoot, sessionId);
+    if (meta === null)
+        return undefined;
+    return typeof meta.outerSessionId === 'string' && meta.outerSessionId.length > 0
+        ? meta.outerSessionId
+        : undefined;
+}
+/**
+ * Snapshot of the previous peaks session's outer session id, read
+ * straight off the active-skill marker *before* we overwrite it.
+ * Used to detect "the LLM just opened a fresh outer session" — if
+ * the previously-recorded outer session id differs from the one we
+ * are about to stamp, the user probably closed the previous outer
+ * session and is now driving peaks from a new one.
+ *
+ * As of slice 018 (auto-roll on outer-mismatch), the actual rotation
+ * is `ensureSessionWithRotation`'s job, not this one. The presence
+ * service still emits the structured `outerSessionMismatch` field on
+ * the presence envelope (useful for the statusline to render a stale
+ * marker and for the QA / log consumers to know an outer-session swap
+ * happened), but it no longer carries the implicit "ask the user"
+ * promise — `peaks-code`'s Step 0 no longer needs to surface an
+ * AskUserQuestion, because the rotation already fired by the time the
+ * skill is invoked.
+ *
+ * `getPreviousOuterSessionId` keeps its read-side role: it powers the
+ * informational `outerSessionMismatch` field below and the legacy
+ * `claudeSessionId` back-compat. Reads from
+ * `.peaks/_runtime/active-skill.json` first; falls back to the
+ * legacy `.peaks/.active-skill.json` for one minor release.
+ */
+function getPreviousOuterSessionId(projectRootOverride) {
+    const result = readSkillPresenceBackCompat(projectRootOverride);
+    if (result === null)
+        return undefined;
+    const parsed = result.presence;
+    if (typeof parsed.outerSessionId === 'string' && parsed.outerSessionId.length > 0) {
+        return parsed.outerSessionId;
+    }
+    // Legacy field name. Honour it on the read side so v1.2.x
+    // presence files do not show as a false mismatch.
+    if (typeof parsed.claudeSessionId === 'string' && parsed.claudeSessionId.length > 0) {
+        return parsed.claudeSessionId;
+    }
+    return undefined;
+}
+export function exportSkillPresence(projectRootOverride) {
+    return resolvePresencePath(projectRootOverride);
+}
+// ============================================================================
+// Slice 020 — caller-keyed active-skill marker (D6).
+// ============================================================================
+//
+// Today's per-project active-skill marker (`.peaks/_runtime/active-skill.json`)
+// races when multiple Claude Code windows (or different platforms) drive the
+// same project concurrently. Slice 020 introduces a per-caller file at
+// `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Two callers
+// bound to the same peak session never clobber each other.
+//
+// The single-file marker is RETAINED for one minor release as read-only
+// back-compat (M1, M4). The new write path is `setSkillPresenceForCaller`;
+// the legacy `setSkillPresence` is now a thin wrapper that synthesises a
+// legacy callerId from `process.env.CLAUDE_CODE_SESSION_ID` (or
+// `projectRoot` for the truly-anonymous case) and delegates.
+/**
+ * Write the per-caller active-skill marker to
+ * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6). Returns
+ * the written presence with the `callerId` field set.
+ *
+ * The caller is responsible for resolving the `callerId` (via
+ * `resolveCallerId` from `src/services/session/resolve-caller-id.ts`)
+ * and the `peakSessionId` (via `getCallerBinding` then reading
+ * `peakSessionId`, OR via `ensureSession` for the first-time case).
+ */
+export function setSkillPresenceForCaller(projectRootOverride, callerId, peakSessionId, skill, mode, gate) {
+    const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
+    const now = new Date().toISOString();
+    const presence = {
+        skill,
+        ...(validatedMode ? { mode: validatedMode } : {}),
+        ...(gate ? { gate } : {}),
+        ...(peakSessionId ? { sessionId: peakSessionId } : {}),
+        ...(callerId ? { outerSessionId: callerId } : {}),
+        setAt: now,
+        lastHeartbeat: now
+    };
+    const presencePath = getActiveSkillFileForCallerPath(resolveProjectRoot(projectRootOverride), peakSessionId, callerId);
+    const presenceDir = dirname(presencePath);
+    if (!existsSync(presenceDir)) {
+        mkdirSync(presenceDir, { recursive: true });
+    }
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: bring the memory store into existence for
+    // fresh projects. Same fail-open contract as the legacy path.
+    ensureMemoryBootstrap(resolveProjectRoot(projectRootOverride));
+    return presence;
+}
+/**
+ * Compute the per-caller active-skill file path. Re-exported for test
+ * ergonomics; canonical path lives in
+ * `src/services/session/caller-binding-service.ts` but inlined here to
+ * avoid a circular import (`caller-binding-service` reads
+ * `skill-presence-service` for the `setCallerBinding` integration in
+ * future slices; the inverse import would deadlock).
+ */
+function getActiveSkillFileForCallerPath(projectRoot, peakSessionId, callerId) {
+    return resolve(projectRoot, '.peaks', '_runtime', peakSessionId, `active-skill-${callerId}.json`);
+}
+export function setSkillPresence(skill, mode, gate, projectRootOverride) {
+    const validatedMode = mode && isSkillPresenceMode(mode) ? mode : undefined;
+    const sessionId = getCurrentSessionId(projectRootOverride);
+    const outerSessionId = getCurrentOuterSessionId();
+    const previousOuterSessionId = getPreviousOuterSessionId(projectRootOverride);
+    const now = new Date().toISOString();
+    // v2.15.0 slice 002 repair: always write `outerSessionId` (even
+    // as `''`) when no harness env var is set. Without this, the JSON
+    // envelope omits the key entirely, which makes downstream staleness
+    // detection unreliable (consumers can't tell "no signal" from
+    // "stale-missing-key"). Presence-shape consumers should treat
+    // `outerSessionId === ''` as "no signal", matching the
+    // `getCurrentOuterSessionId()` resolution contract.
+    const presence = {
+        skill,
+        ...(validatedMode ? { mode: validatedMode } : {}),
+        ...(gate ? { gate } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        outerSessionId: outerSessionId ?? '',
+        setAt: now,
+        lastHeartbeat: now
+    };
+    // Outer-session-mismatch detection. Fires only when:
+    //   (a) we have a *current* outer session id (i.e. some harness is
+    //       driving peaks right now — PEAKS_OUTER_SESSION_ID or
+    //       CLAUDE_CODE_SESSION_ID is set), AND
+    //   (b) the previous presence write recorded a *different* outer
+    //       session id (or none), AND
+    //   (c) the current peaks session is bound to a different outer
+    //       session id (or no outer session id is bound).
+    //
+    // The combination of (b) and (c) is what tells us "this is a
+    // genuine outer-session swap, not a transient env-var change".
+    // When only (b) fires (current bound session was started in this
+    // same outer session), no mismatch is reported — that is the
+    // common reconnect case.
+    if (outerSessionId !== undefined) {
+        const boundOuterSessionId = getBoundOuterSessionId(projectRootOverride);
+        const outerChanged = previousOuterSessionId !== outerSessionId;
+        const boundOuterMatches = boundOuterSessionId === outerSessionId;
+        // Suppress the false-positive where neither side ever recorded
+        // an outer session id. Two unknowns are not a swap — they are
+        // simply "no outer-session signal available yet". Only report
+        // a mismatch when at least one side has a recorded outer id.
+        const hasOuterSignal = previousOuterSessionId !== undefined || boundOuterSessionId !== undefined;
+        if (hasOuterSignal && outerChanged && !boundOuterMatches && sessionId !== null) {
+            presence.outerSessionMismatch = {
+                ...(previousOuterSessionId !== undefined ? { previous: previousOuterSessionId } : {}),
+                current: outerSessionId,
+                boundSessionId: sessionId,
+                ...(boundOuterSessionId !== undefined ? { boundOuterSessionId } : {})
+            };
+        }
+    }
+    const presencePath = resolvePresencePath(projectRootOverride);
+    const presenceDir = dirname(presencePath);
+    if (!existsSync(presenceDir)) {
+        mkdirSync(presenceDir, { recursive: true });
+    }
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    // Skill-activation side effect: ensure `.peaks/memory/` and a full-shape
+    // empty `index.json` exist for the project. This is the user-facing fix
+    // for "stock projects never get a memory directory or index". Every peaks
+    // skill starts with `peaks skill presence:set peaks-<role>`, so doing the
+    // bootstrap here means the very first skill invocation in a fresh project
+    // (or in a stock project that pre-dates the memory layer) brings the
+    // memory store into existence. The helper is fail-open, so a failure here
+    // does not block presence from being written.
+    const projectRoot = resolveProjectRoot(projectRootOverride);
+    ensureMemoryBootstrap(projectRoot);
+    return presence;
+}
+export function getSkillPresence(projectRootOverride) {
+    const result = readSkillPresenceBackCompat(projectRootOverride);
+    if (result === null)
+        return null;
+    const { presence, path: presencePath } = result;
+    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
+        const currentSessionId = getCurrentSessionId(projectRootOverride);
+        if (currentSessionId && presence.sessionId !== currentSessionId) {
+            try {
+                unlinkSync(presencePath);
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                // best effort
+            }
+            return null;
+        }
+    }
+    return presence;
+}
+export function checkStalePresence(opts) {
+    const result = readSkillPresenceBackCompat(opts?.projectRootOverride);
+    // `opts?.currentOuter === undefined` is the omitted-key case. A
+    // falsy string `''` is an explicit "no signal" (used by tests to
+    // simulate a CLI run with no harness env vars).
+    const current = opts && 'currentOuter' in opts
+        ? opts.currentOuter
+        : getCurrentOuterSessionId();
+    if (result === null) {
+        return {
+            stale: true,
+            reason: 'no-presence',
+            presence: null,
+            currentOuterSessionId: current,
+            recordedOuterSessionId: undefined
+        };
+    }
+    const recorded = result.presence.outerSessionId;
+    // Suppress false-positives when NEITHER side recorded an outer
+    // session id (legacy project, no harness signal). Two unknowns
+    // are not a swap — they are "no signal available yet".
+    const hasSignal = (recorded !== undefined && recorded.length > 0)
+        || (current !== undefined && current.length > 0);
+    if (!hasSignal) {
+        return {
+            stale: false,
+            reason: null,
+            presence: result.presence,
+            currentOuterSessionId: current,
+            recordedOuterSessionId: recorded
+        };
+    }
+    if (recorded === current) {
+        return {
+            stale: false,
+            reason: null,
+            presence: result.presence,
+            currentOuterSessionId: current,
+            recordedOuterSessionId: recorded
+        };
+    }
+    return {
+        stale: true,
+        reason: 'outer-session-mismatch',
+        presence: result.presence,
+        currentOuterSessionId: current,
+        recordedOuterSessionId: recorded
+    };
+}
+/**
+ * Slice 002 (v2.15.0) — auto-clear stale presence on session
+ * rotation (AC-1).
+ *
+ * Called from `peaks workspace init` immediately after a successful
+ * `outer-session-mismatch` rotation. When the previous session's
+ * presence is still on disk under the OLD outer session id,
+ * clearing it prevents peaks-code Step 1 from picking up a stale
+ * `mode` field that the user never explicitly chose.
+ *
+ * Only clears when:
+ *   - the recorded outer session id does NOT match the current outer
+ *     session id (i.e. the presence IS stale), AND
+ *   - the recorded outer session id matches the just-rotated-out
+ *     session id (i.e. we're clearing exactly the old binding, not a
+ *     user-explicitly-set mode from another live outer session).
+ *
+ * Returns `{ cleared, reason }` so callers can surface the outcome
+ * in the JSON envelope and audit log. Pure: no env-var reads, all
+ * inputs are passed explicitly so the call site (init command) can
+ * decide what the "rotated-out" id was.
+ */
+export function clearStalePresenceOnRotation(opts) {
+    const result = readSkillPresenceBackCompat(opts.projectRootOverride);
+    if (result === null) {
+        return { cleared: false, reason: 'no-presence' };
+    }
+    const recorded = result.presence.outerSessionId;
+    const current = opts.currentOuterSessionId;
+    // If the recorded outer id matches the new (current) outer id,
+    // this presence is NOT stale — the user just reconnected from
+    // the same outer session after rotation. Leave it alone.
+    if (recorded === current && recorded !== undefined) {
+        return {
+            cleared: false,
+            reason: 'not-stale',
+            ...(recorded !== undefined ? { recordedOuter: recorded } : {})
+        };
+    }
+    // If we have a recorded outer id AND it does NOT match the
+    // rotated-out session id, the user explicitly set this presence
+    // from a DIFFERENT outer session that is still live. Do NOT clear
+    // — would destroy user intent.
+    if (opts.rotatedOutSessionId !== null &&
+        recorded !== undefined &&
+        recorded !== opts.rotatedOutSessionId) {
+        return {
+            cleared: false,
+            reason: 'recorded-by-different-outer',
+            recordedOuter: recorded
+        };
+    }
+    // Stale by outer-mismatch (either recorded === undefined and
+    // current is set, or recorded !== current). Clear it.
+    const cleared = clearSkillPresence(opts.projectRootOverride);
+    return {
+        cleared,
+        reason: cleared ? 'outer-session-mismatch' : 'clear-failed',
+        ...(recorded !== undefined ? { recordedOuter: recorded } : {})
+    };
+}
+export function touchSkillHeartbeat(projectRootOverride) {
+    const result = readSkillPresenceBackCompat(projectRootOverride);
+    if (result === null)
+        return null;
+    const { presence, path: presencePath } = result;
+    if (typeof presence.sessionId === 'string' && presence.sessionId.length > 0) {
+        const currentSessionId = getCurrentSessionId(projectRootOverride);
+        if (currentSessionId && presence.sessionId !== currentSessionId) {
+            try {
+                unlinkSync(presencePath);
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                // best effort
+            }
+            return null;
+        }
+    }
+    presence.lastHeartbeat = new Date().toISOString();
+    writeFileSync(presencePath, JSON.stringify(presence, null, 2), 'utf8');
+    return presence;
+}
+export function clearSkillPresence(projectRootOverride) {
+    // Clear both the new canonical path and the legacy path, so a stale
+    // presence marker from a prior CLI version cannot resurrect after
+    // a fresh `clear`.
+    const presencePath = resolvePresencePath(projectRootOverride);
+    const legacyPath = resolve(resolveProjectRoot(projectRootOverride), PRESENCE_FILE_LEGACY);
+    let cleared = false;
+    for (const p of [presencePath, legacyPath]) {
+        if (!existsSync(p))
+            continue;
+        try {
+            unlinkSync(p);
+            cleared = true;
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // best effort
+        }
+    }
+    return cleared;
+}

package/dist/services/skills/skill-registry.js

@@ -0,0 +1,67 @@
+import { join } from 'node:path';
+import { listDirectories, pathExists, readText } from '../../shared/fs.js';
+import { parseFrontmatter } from '../../shared/frontmatter.js';
+import { skillsDir } from '../../shared/paths.js';
+function getLoadFailureMessage(error) {
+    return error instanceof Error ? error.message : 'Unable to parse skill metadata';
+}
+export async function loadSkillRegistry(baseDir = skillsDir) {
+    if (!(await pathExists(baseDir))) {
+        return { skills: [], failures: [] };
+    }
+    const directories = await listDirectories(baseDir);
+    const skills = [];
+    const failures = [];
+    for (const directory of directories) {
+        // LLM-internal skills (bees) live under `bee/` per spec 2026-07-05.
+        // Recurse one level into `bee/`; treat each child as a separate skill.
+        if (directory === 'bee') {
+            const subEntries = await listDirectories(join(baseDir, 'bee'));
+            for (const subDir of subEntries) {
+                const skillPath = join(baseDir, 'bee', subDir, 'SKILL.md');
+                if (!(await pathExists(skillPath))) {
+                    continue;
+                }
+                try {
+                    const frontmatter = parseFrontmatter(await readText(skillPath));
+                    // `directory` is the on-disk skill folder name; for bees that is the
+                    // basename of the bee child, NOT `bee/<name>` (keeps the
+                    // doctor skill-name-matches-directory invariant working).
+                    skills.push({
+                        name: frontmatter.name,
+                        description: frontmatter.description,
+                        directory: subDir,
+                        skillPath
+                    });
+                }
+                catch (error) {
+                    failures.push({ directory: subDir, skillPath, message: getLoadFailureMessage(error) });
+                }
+            }
+            continue;
+        }
+        const skillPath = join(baseDir, directory, 'SKILL.md');
+        if (!(await pathExists(skillPath))) {
+            continue;
+        }
+        try {
+            const frontmatter = parseFrontmatter(await readText(skillPath));
+            skills.push({
+                name: frontmatter.name,
+                description: frontmatter.description,
+                directory,
+                skillPath
+            });
+        }
+        catch (error) {
+            failures.push({ directory, skillPath, message: getLoadFailureMessage(error) });
+        }
+    }
+    return {
+        skills: skills.sort((left, right) => left.name.localeCompare(right.name)),
+        failures: failures.sort((left, right) => left.directory.localeCompare(right.directory))
+    };
+}
+export async function listSkills(baseDir = skillsDir) {
+    return (await loadSkillRegistry(baseDir)).skills;
+}

package/dist/services/skills/skill-runbook-service.js

@@ -0,0 +1,128 @@
+import { dirname, join } from 'node:path';
+import * as path from 'node:path';
+import { readText } from '../../shared/fs.js';
+import { loadSkillRegistry } from './skill-registry.js';
+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/,
+    /peaks\s+workspace\s+reconcile[^\n]*--apply/
+];
+const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
+const PEAKS_COMMAND_LINE_PATTERN = /^\s*peaks\s+\w/;
+function extractRunbookSection(body) {
+    // Find a `## Default runbook` heading at the start of a line, then capture
+    // the section body up to the next `## ` heading or end of input.
+    //
+    // Implementation note: we avoid a regex with a multiline `(?=\n## |$)`
+    // lookahead because the `m` flag turns `$` into "end of any line" in
+    // JavaScript, which would let the lazy capture stop at the first `\n`.
+    // Instead, we (a) use the regex only to locate the heading, then (b)
+    // manually scan forward for the next `## ` heading or end of input.
+    const headingRe = /^## Default runbook[^\n]*(?:\n|$)/m;
+    const headingMatch = headingRe.exec(body);
+    if (headingMatch === null)
+        return null;
+    const startAfter = headingMatch.index + headingMatch[0].length;
+    const rest = body.slice(startAfter);
+    // Find the next `## ` heading at the start of a line.
+    const nextHeadingRe = /^## /m;
+    const nextMatch = nextHeadingRe.exec(rest);
+    const end = nextMatch === null ? rest.length : nextMatch.index;
+    return rest.slice(0, end);
+}
+/**
+ * Load the runbook section, falling back to `references/runbook.md` if the
+ * SKILL.md only has a pointer section. This supports skills (notably
+ * `peaks-code`) that extracted their 150-line bash runbook to a sibling
+ * reference to keep SKILL.md under the 800-line cap. The CLI
+ * `peaks skill runbook` command uses the same fallback so a human
+ * reviewer sees the full runbook regardless of where it lives.
+ *
+ * Strategy: prefer the LONGER of the two sections. A short pointer section
+ * in SKILL.md (~ 1-2 lines) is treated as a "this runbook is in the
+ * reference" marker; a long inline section (>= the reference length) is
+ * treated as the canonical runbook. This avoids the false positive where
+ * the pointer section's regex match returns a non-null but content-poor
+ * string.
+ */
+async function loadRunbookSection(skillPath, body) {
+    const inline = extractRunbookSection(body);
+    const skillDir = dirname(skillPath);
+    // Try multiple reference filenames. Convention: each skill may name its
+    // runbook file `runbook.md` (the generic name, used by peaks-code), or
+    // `<role>-runbook.md` (the role-suffixed name, used by peaks-rd → rd-runbook.md,
+    // peaks-qa → qa-runbook.md, etc.). Prefer the longest extracted section.
+    const refCandidates = [
+        join(skillDir, 'references', 'runbook.md'),
+        join(skillDir, 'references', `${path.basename(skillDir).replace(/^peaks-/, '')}-runbook.md`)
+    ];
+    let bestRef = null;
+    for (const refPath of refCandidates) {
+        try {
+            const refBody = await readText(refPath);
+            const refSection = extractRunbookSection(refBody);
+            if (refSection === null)
+                continue;
+            if (bestRef === null || refSection.length > bestRef.length) {
+                bestRef = refSection;
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // candidate not present or unreadable; try the next one
+        }
+    }
+    const refSection = bestRef;
+    if (inline === null)
+        return refSection;
+    if (refSection === null)
+        return inline;
+    return inline.length >= refSection.length ? inline : refSection;
+}
+function findDestructiveApplyLines(section) {
+    const lines = section.split(/\r?\n/);
+    return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
+}
+function findPeaksCommandLines(section) {
+    return section
+        .split(/\r?\n/)
+        .filter((line) => PEAKS_COMMAND_LINE_PATTERN.test(line))
+        .map((line) => line.trim());
+}
+export async function inspectSkillRunbook(name, baseDir) {
+    const registry = await loadSkillRegistry(baseDir);
+    const skill = registry.skills.find((entry) => entry.name === name);
+    if (skill === undefined) {
+        throw new Error(`Skill "${name}" not found under skills directory`);
+    }
+    const body = await readText(skill.skillPath);
+    const section = await loadRunbookSection(skill.skillPath, body);
+    if (section === null) {
+        return {
+            name: skill.name,
+            directory: skill.directory,
+            hasRunbook: false,
+            peaksCommandCount: 0,
+            peaksCommandLines: [],
+            destructiveApplyLines: [],
+            hasAuthorizationNote: false,
+            ok: false
+        };
+    }
+    const peaksCommandLines = findPeaksCommandLines(section);
+    const destructiveApplyLines = findDestructiveApplyLines(section);
+    const hasAuthorizationNote = AUTHORIZATION_KEYWORDS_PATTERN.test(section);
+    const ok = destructiveApplyLines.length === 0 || hasAuthorizationNote;
+    return {
+        name: skill.name,
+        directory: skill.directory,
+        hasRunbook: true,
+        peaksCommandCount: peaksCommandLines.length,
+        peaksCommandLines,
+        destructiveApplyLines,
+        hasAuthorizationNote,
+        ok
+    };
+}