peaks-cli 1.3.8 → 1.4.0

package/dist/src/cli/commands/skill-scope-commands.js

@@ -0,0 +1,305 @@
+/**
+ * `peaks skill scope` CLI surface (slice 025.1).
+ *
+ * Four subcommands (mutually exclusive):
+ * - `--detect` — dry-run; prints the relevance matrix, never touches files.
+ * - `--apply`  — writes the source-of-truth + IDE-native config.
+ * - `--show`   — reads the source-of-truth + native config back.
+ * - `--reset`  — removes the source-of-truth + IDE-native config.
+ *
+ * Exit code matrix (tech-doc §6.3):
+ *   0  success
+ *   1  uncaught error
+ *   2  invalid usage (missing/incompatible flags)
+ *   3  source-of-truth written but adapter returned NOT_SUPPORTED
+ *   4  adapter failure other than NOT_SUPPORTED
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectSkillScope, } from '../../services/skill-scope/detect.js';
+import { resolveActiveAdapter, getScopeAdapter } from '../../services/skill-scope/registry.js';
+import { ideCompanionFilePath, readIdeCompanion, readSourceOfTruth, removeIfExists, scopeFilePath, writeSourceOfTruth, } from '../../services/skill-scope/source-of-truth.js';
+import { ALWAYS_RELEVANT_SKILLS } from '../../services/skill-scope/types.js';
+import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const VALID_ACTIONS = ['detect', 'apply', 'show', 'reset'];
+const VALID_IDES = ['claude-code', 'trae', 'codex', 'cursor', 'qoder', 'tongyi-lingma'];
+function isValidIde(value) {
+    return VALID_IDES.includes(value);
+}
+/**
+ * G6: enforce the peaks-* allowlist. Re-adds any peak-* skill that is
+ * missing from the allowlist, and removes any peak-* skill from the
+ * denylist. The list is the same one declared in `types.ts`.
+ */
+function enforcePeaksAllowlist(allowlist) {
+    const set = new Set(allowlist);
+    for (const name of ALWAYS_RELEVANT_SKILLS) {
+        if (name.startsWith('peaks-'))
+            set.add(name);
+    }
+    return [...set];
+}
+function stripPeaksFromDenylist(denylist) {
+    return denylist.filter((name) => !name.startsWith('peaks-'));
+}
+/**
+ * Determine the IDE. Caller-supplied `--ide` wins; otherwise the registry
+ * probes the project root.
+ */
+async function resolveIde(projectRoot, override) {
+    if (override !== undefined) {
+        if (!isValidIde(override)) {
+            throw new Error(`Unknown IDE: ${override}. Valid: ${VALID_IDES.join(', ')}`);
+        }
+        return { ide: override, isFallback: false };
+    }
+    const resolved = await resolveActiveAdapter(projectRoot);
+    return { ide: resolved.adapter.ide, isFallback: resolved.isFallback };
+}
+/**
+ * Stable timestamp (no millisecond jitter) for the `generatedAt` field.
+ * `Date.now()` would still be deterministic per-run; we keep the natural
+ * one to ensure `generatedAt` matches what the user sees on disk.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Run the --detect subcommand. */
+async function runDetect(input) {
+    try {
+        const result = await detectSkillScope({ projectRoot: input.project });
+        const envelope = ok('skill.scope.detect', result);
+        const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : JSON.stringify(result, null, 2);
+        return { exitCode: 0, envelope, stdout, stderr: '' };
+    }
+    catch (error) {
+        const envelope = fail('skill.scope.detect', 'DETECT_FAILED', getErrorMessage(error), null);
+        return { exitCode: 1, envelope, stdout: '', stderr: envelope.message ?? 'detect failed' };
+    }
+}
+/** Build the final ScopeConfig (applies G6 enforcement + override). */
+function buildScopeConfig(args) {
+    const strict = args.strict;
+    const detected = args.detected;
+    // Build allowlist from detected.relevant + (in loose) borderline.
+    const allowFromDetect = detected.skills
+        .filter((s) => s.relevance === 'relevant' || (!strict && s.relevance === 'borderline'))
+        .map((s) => s.name);
+    const merged = args.allowOverride !== undefined ? [...args.allowOverride, ...allowFromDetect] : allowFromDetect;
+    const enforced = enforcePeaksAllowlist(merged);
+    // Denylist: irrelevant skills (strict + loose both), minus anything in allowlist.
+    const denyFromDetect = detected.skills
+        .filter((s) => s.relevance === 'irrelevant' && !enforced.includes(s.name))
+        .map((s) => s.name);
+    const finalDeny = stripPeaksFromDenylist(denyFromDetect);
+    return {
+        generatedAt: nowIso(),
+        ide: args.ide,
+        strict,
+        allowlist: enforced,
+        denylist: finalDeny,
+        skills: detected.skills,
+        signals: detected.projectSignals,
+    };
+}
+/** Run the --apply subcommand. */
+async function runApply(input) {
+    // 1. Detect the scope.
+    const detected = await detectSkillScope({ projectRoot: input.project });
+    // --strict wins when both flags are passed. Default is --loose per PRD.
+    const isStrict = input.strict === true && input.loose !== true;
+    const loose = !isStrict;
+    const { ide, isFallback } = await resolveIde(input.project, input.ide);
+    const adapter = getScopeAdapter(ide);
+    const config = buildScopeConfig({
+        ide,
+        strict: isStrict,
+        detected,
+        ...(input.overrideAllowlist !== undefined ? { allowOverride: input.overrideAllowlist } : {}),
+    });
+    // 2. Write the source-of-truth first (atomic). Test seam: simulate failure.
+    let writtenFiles = [];
+    let sourceWritten = false;
+    try {
+        if (input.simulateSourceOfTruthWriteFailure) {
+            throw new Error('simulated source-of-truth write failure');
+        }
+        const file = await writeSourceOfTruth(input.project, config);
+        writtenFiles.push(file);
+        sourceWritten = true;
+    }
+    catch (error) {
+        const envelope = fail('skill.scope.apply', 'WRITE_FAILED', getErrorMessage(error), { ide, sourceWritten: false }, ['Fix filesystem permissions on the project root and retry']);
+        return { exitCode: 4, envelope, stdout: '', stderr: envelope.message ?? 'write failed' };
+    }
+    // 3. Call the adapter. Stub adapters return notSupported=true; we surface it.
+    const adapterInput = {
+        allowlist: config.allowlist,
+        denylist: config.denylist,
+        strict: config.strict,
+        projectRoot: input.project,
+        sourceConfig: config,
+        shadowFallback: input.shadowFallback === true,
+    };
+    let result;
+    try {
+        result = await adapter.applyScope(adapterInput);
+    }
+    catch (error) {
+        // Roll back the source-of-truth on adapter failure.
+        await removeIfExists(scopeFilePath(input.project));
+        const envelope = fail('skill.scope.apply', 'ADAPTER_FAILED', getErrorMessage(error), { ide, sourceWritten: false, writtenFiles: [] }, ['Inspect the adapter error and retry']);
+        return { exitCode: 4, envelope, stdout: '', stderr: envelope.message ?? 'adapter failed' };
+    }
+    // The stub adapter also writes the canonical skills.json — that's
+    // already on disk from step 2, so its second write is a no-op update.
+    const finalWrittenFiles = [...writtenFiles, ...result.writtenFiles];
+    const envelope = ok('skill.scope.apply', {
+        ide,
+        isFallback,
+        strict: isStrict,
+        loose,
+        allowlist: config.allowlist,
+        denylist: config.denylist,
+        signals: config.signals,
+        writtenFiles: finalWrittenFiles,
+        usedShadowStub: result.usedShadowStub,
+        notSupported: result.notSupported,
+        strippedFromDenylist: result.strippedFromDenylist ?? [],
+        error: result.error,
+    });
+    const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : JSON.stringify(envelope.data, null, 2);
+    if (result.notSupported) {
+        // Stub adapter: NOT_SUPPORTED → exit 3, write error to stderr.
+        const stderr = `${result.error?.code ?? 'NOT_SUPPORTED'}: ${result.error?.message ?? 'not supported'}`;
+        return { exitCode: 3, envelope, stdout, stderr };
+    }
+    return { exitCode: 0, envelope, stdout, stderr: '' };
+}
+/** Run the --show subcommand. */
+async function runShow(input) {
+    const source = await readSourceOfTruth(input.project);
+    const { ide } = await resolveIde(input.project, input.ide);
+    const companionPath = ideCompanionFilePath(input.project, ide);
+    const companion = await readIdeCompanion(input.project, ide);
+    // For Claude Code, the native config is `.claude/settings.local.json`.
+    const nativeSettingsPath = join(input.project, '.claude', 'settings.local.json');
+    const nativeExists = existsSync(nativeSettingsPath);
+    let native = companion;
+    if (nativeExists) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            native = JSON.parse(await readFile(nativeSettingsPath, 'utf8'));
+        }
+        catch {
+            native = null;
+        }
+    }
+    const data = {
+        ide,
+        source,
+        native,
+        nativeSettingsPath: nativeExists ? '.claude/settings.local.json' : null,
+        companionPath: existsSync(companionPath) ? companionPath : null,
+    };
+    const envelope = ok('skill.scope.show', data);
+    const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : JSON.stringify(data, null, 2);
+    return { exitCode: 0, envelope, stdout, stderr: '' };
+}
+/** Run the --reset subcommand. */
+async function runReset(input) {
+    const { ide } = await resolveIde(input.project, input.ide);
+    const adapter = getScopeAdapter(ide);
+    const resetResult = await adapter.resetScope({ projectRoot: input.project });
+    const sourceFile = scopeFilePath(input.project);
+    const sourceRemoved = await removeIfExists(sourceFile);
+    const allRemoved = [...resetResult.removedFiles, ...(sourceRemoved ? [sourceFile] : [])];
+    const envelope = ok('skill.scope.reset', {
+        ide,
+        removedFiles: allRemoved,
+    });
+    // Always include the canonical source-of-truth path in the human-readable
+    // summary, even if it didn't exist (so the user knows what was targeted).
+    const displayFiles = allRemoved.length > 0 ? allRemoved : [sourceFile, join(input.project, '.claude', 'settings.local.json')];
+    const summary = `removed: ${displayFiles.join(', ')}`;
+    const stdout = input.json === true ? JSON.stringify(envelope, null, 2) : summary;
+    return { exitCode: 0, envelope, stdout, stderr: '' };
+}
+/**
+ * Programmatic entry point for `peaks skill scope`. Used by the CLI shim
+ * AND by the unit tests.
+ */
+export async function runSkillScopeCommand(input) {
+    if (!VALID_ACTIONS.includes(input.subcommand)) {
+        const envelope = fail('skill.scope', 'INVALID_USAGE', `Unknown action: ${input.subcommand}`, null);
+        return { exitCode: 2, envelope, stdout: '', stderr: envelope.message ?? 'invalid usage' };
+    }
+    switch (input.subcommand) {
+        case 'detect': return runDetect(input);
+        case 'apply': return runApply(input);
+        case 'show': return runShow(input);
+        case 'reset': return runReset(input);
+    }
+}
+/**
+ * Register the `peaks skill scope` subcommand on the `skill` command group.
+ * Mutually-exclusive flags: exactly one of --detect / --apply / --show / --reset.
+ */
+export function registerSkillScopeCommands(program, io) {
+    // Find the existing 'skill' subcommand if any.
+    let skillCmd = program.commands.find((c) => c.name() === 'skill');
+    if (skillCmd === undefined) {
+        skillCmd = program.command('skill').description('Manage Peaks skills');
+    }
+    const scope = skillCmd
+        .command('scope')
+        .description('Per-project skill scoping: detect, apply, show, reset');
+    addJsonOption(scope
+        .option('--detect', 'dry-run: print the relevance matrix')
+        .option('--apply', 'apply the scope (writes source-of-truth + IDE config)')
+        .option('--show', 'show the currently applied scope')
+        .option('--reset', 'remove the scope config')
+        .option('--project <path>', 'target project root (defaults to cwd)', process.cwd())
+        .option('--strict', '--apply: only `relevant` skills in the allowlist')
+        .option('--loose', '--apply: `relevant` + `borderline` in the allowlist (default)')
+        .option('--ide <name>', 'force a specific IDE adapter (overrides auto-detect)')
+        .option('--shadow-fallback', '--apply: Claude Code uses shadow stubs for the denylist')).action(async (options) => {
+        const flags = [options.detect, options.apply, options.show, options.reset].filter(Boolean).length;
+        if (flags !== 1) {
+            const envelope = fail('skill.scope', 'INVALID_USAGE', 'Exactly one of --detect / --apply / --show / --reset is required', null, ['Pass exactly one action flag']);
+            printResult(io, envelope, options.json === true);
+            process.exitCode = 2;
+            return;
+        }
+        const subcommand = options.detect
+            ? 'detect'
+            : options.apply
+                ? 'apply'
+                : options.show
+                    ? 'show'
+                    : 'reset';
+        const result = await runSkillScopeCommand({
+            subcommand,
+            project: options.project ?? process.cwd(),
+            ...(options.strict !== undefined ? { strict: options.strict } : {}),
+            ...(options.loose !== undefined ? { loose: options.loose } : {}),
+            ...(options.ide !== undefined ? { ide: options.ide } : {}),
+            ...(options.shadowFallback !== undefined ? { shadowFallback: options.shadowFallback } : {}),
+            ...(options.json !== undefined ? { json: options.json } : {}),
+        });
+        if (options.json === true) {
+            if (result.envelope !== null)
+                printResult(io, result.envelope, true);
+        }
+        else {
+            if (result.stdout.length > 0)
+                io.stdout(result.stdout);
+            if (result.stderr.length > 0)
+                io.stderr(result.stderr);
+        }
+        if (result.exitCode !== 0) {
+            process.exitCode = result.exitCode;
+        }
+    });
+}

package/dist/src/cli/commands/workflow-commands.js

@@ -329,7 +329,7 @@ export function registerWorkflowCommands(program, io) {
             process.exitCode = exitOk;
         }
         catch (error) {
-            printResult(io, fail('workflow.verify-pipeline', 'VERIFY_FAILED', getErrorMessage(error), {}, ['Check that --project and --rid are correct; --change-id is optional (resolved from the artifact otherwise)']), options.json);
+            printResult(io, fail('workflow.verify-pipeline', 'VERIFY_FAILED', getErrorMessage(error), { acceptedForm: 'none', gateC: 'fail' }, ['Check that --project and --rid are correct; --change-id is optional (resolved from the artifact otherwise)']), options.json);
             process.exitCode = 1;
         }
     });

package/dist/src/cli/commands/workflow-plan-commands.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `peaks workflow plan <read|refresh|detect-trigger>` — slice 025 CLI.
+ *
+ * Three subcommands under the existing `peaks workflow` verb:
+ * - `read <security|perf> --project <repo> --json`
+ * - `refresh <security|perf> --project <repo> [--apply] --json`
+ * - `detect-trigger --project <repo> --rid <rid> [--refresh] --json`
+ *
+ * CLI justification (per dev-preference rules):
+ * - `read`           (2) JSON-gated — slice workflow reads plan hash.
+ * - `refresh`        (3) destructive write needs explicit `--apply`.
+ * - `detect-trigger` (2) JSON-gated — slice workflow needs the verdict.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+declare function runPlanRead(io: ProgramIO, options: {
+    type: string;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}): void;
+declare function runPlanRefresh(io: ProgramIO, options: {
+    type: string;
+    project?: string;
+    sessionId?: string;
+    apply?: boolean;
+    json?: boolean;
+}): void;
+declare function runPlanDetectTrigger(io: ProgramIO, options: {
+    project?: string;
+    rid?: string;
+    sessionId?: string;
+    refresh?: boolean;
+    json?: boolean;
+}): void;
+export declare function registerWorkflowPlanCommands(program: Command, io: ProgramIO): void;
+export { runPlanRead as _runPlanRead };
+export { runPlanRefresh as _runPlanRefresh };
+export { runPlanDetectTrigger as _runPlanDetectTrigger };

package/dist/src/cli/commands/workflow-plan-commands.js

@@ -0,0 +1,163 @@
+import { fail, getErrorMessage } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { readPlan } from '../../services/workflow/plan-reader.js';
+import { refreshPlan } from '../../services/workflow/plan-refresher.js';
+import { detectTrigger } from '../../services/workflow/plan-trigger-detector.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const VALID_TYPES = ['security', 'perf'];
+// F-1 (slice 025 security): reject session ids that look like path
+// traversal payloads. Canonical pattern is YYYY-MM-DD-<slug>.
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+// F-1 (slice 025 security): reject rids that contain path separators,
+// null bytes, or traversal sequences.
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isPlanType(value) {
+    return VALID_TYPES.includes(value);
+}
+function isValidSessionId(value) {
+    return SESSION_ID_PATTERN.test(value);
+}
+function isValidRequestId(value) {
+    return REQUEST_ID_PATTERN.test(value);
+}
+function resolveSessionId(io, command, projectRoot, explicit, asJson) {
+    if (explicit !== undefined && explicit.length > 0) {
+        if (!isValidSessionId(explicit)) {
+            printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: explicit }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
+            process.exitCode = 1;
+            return null;
+        }
+        return explicit;
+    }
+    const sid = getSessionId(projectRoot);
+    if (sid === null || sid === undefined) {
+        printResult(io, fail(command, 'NO_ACTIVE_SESSION', 'No active session — pass --session-id explicitly or run peaks workspace init', { projectRoot }, ['Run peaks workspace init or pass --session-id <YYYY-MM-DD-slug>']), asJson === true);
+        process.exitCode = 1;
+        return null;
+    }
+    // Defensive: even active-session resolution must satisfy the pattern.
+    if (!isValidSessionId(sid)) {
+        printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: sid }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
+        process.exitCode = 1;
+        return null;
+    }
+    return sid;
+}
+function resolveProjectRoot(projectArg) {
+    if (projectArg === undefined || projectArg === '') {
+        return findProjectRoot(process.cwd()) ?? process.cwd();
+    }
+    return projectArg;
+}
+function runPlanRead(io, options) {
+    if (!isPlanType(options.type)) {
+        printResult(io, fail('workflow.plan.read', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.read', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = readPlan({ type: options.type, project: projectRoot, sessionId });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.read', 'READ_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root with a peaks session']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+function runPlanRefresh(io, options) {
+    if (!isPlanType(options.type)) {
+        printResult(io, fail('workflow.plan.refresh', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.refresh', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = refreshPlan({
+            type: options.type,
+            project: projectRoot,
+            sessionId,
+            apply: options.apply === true
+        });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.refresh', 'REFRESH_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and the session exists']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+function runPlanDetectTrigger(io, options) {
+    if (options.rid === undefined || options.rid === '') {
+        printResult(io, fail('workflow.plan.detect-trigger', 'MISSING_RID', 'Missing --rid', null, ['Pass --rid <request-id>']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    if (!isValidRequestId(options.rid)) {
+        printResult(io, fail('workflow.plan.detect-trigger', 'INVALID_RID', 'request id must match [A-Za-z0-9][A-Za-z0-9._-]*', { rid: options.rid }, ['Pass --rid <alphanumeric.request-id>']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.detect-trigger', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = detectTrigger({
+            project: projectRoot,
+            rid: options.rid,
+            sessionId,
+            ...(options.refresh === true ? { manualOverride: true } : {})
+        });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.detect-trigger', 'DETECT_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and --rid is set']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowPlanCommands(program, io) {
+    let workflowCmd = program.commands.find((c) => c.name() === 'workflow');
+    if (workflowCmd === undefined) {
+        workflowCmd = program.command('workflow').description('Plan workflow routing dry-run graphs');
+    }
+    const plan = workflowCmd
+        .command('plan')
+        .description('Read, refresh, or detect-trigger for security / perf plans (slice 025)');
+    addJsonOption(plan
+        .command('read')
+        .description('Read the project-level plan envelope (exists, path, hash, refreshedAt)')
+        .requiredOption('--type <type>', 'plan type: security or perf')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')).action((options) => {
+        runPlanRead(io, options);
+    });
+    addJsonOption(plan
+        .command('refresh')
+        .description('Regenerate the plan (deterministic, idempotent; --apply to write)')
+        .requiredOption('--type <type>', 'plan type: security or perf')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')
+        .option('--apply', 'write the plan to disk (default is dry-run preview)')).action((options) => {
+        runPlanRefresh(io, options);
+    });
+    addJsonOption(plan
+        .command('detect-trigger')
+        .description('Detect whether a plan refresh is warranted for the slice diff')
+        .requiredOption('--rid <rid>', 'request identifier')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')
+        .option('--refresh', 'force triggered=true (manual override)')).action((options) => {
+        runPlanDetectTrigger(io, options);
+    });
+}
+// Re-export for tests that need a programmatic entry point.
+export { runPlanRead as _runPlanRead };
+export { runPlanRefresh as _runPlanRefresh };
+export { runPlanDetectTrigger as _runPlanDetectTrigger };

package/dist/src/cli/program.js

@@ -14,6 +14,7 @@ import { registerPerfCommands } from './commands/perf-commands.js';
 // surfaced via `peaks sub-agent dispatch|heartbeat|share`.
 import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
+import { registerRetrospectiveCommands } from './commands/retrospective-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
 import { registerSliceCommands } from './commands/slice-commands.js';
@@ -26,6 +27,8 @@ import { registerHooksCommands } from './commands/hooks-commands.js';
 import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
+import { registerSkillScopeCommands } from './commands/skill-scope-commands.js';
+import { registerWorkflowPlanCommands } from './commands/workflow-plan-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
     const program = new Command();
@@ -90,6 +93,7 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerPerfCommands(program, io);
     registerProjectCommands(program, io);
     registerRequestCommands(program, io);
+    registerRetrospectiveCommands(program, io);
     registerScanCommands(program, io);
     registerShadcnCommands(program, io);
     registerSliceCommands(program, io);
@@ -105,5 +109,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);
     registerWorkspaceCommands(program, io);
+    // Slice 025: peaks skill scope — per-project multi-IDE skill scoping.
+    registerSkillScopeCommands(program, io);
+    // Slice 025: peaks workflow plan — security/perf plan/result split CLI.
+    registerWorkflowPlanCommands(program, io);
     return program;
 }

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

@@ -44,6 +44,43 @@ export type WorkspaceLayoutInspection = {
     perChangeIdDirs?: string[];
 };
 export type WorkspaceLayoutProbe = () => WorkspaceLayoutInspection;
+/**
+ * 2026-06-10 — `gateguard-fact-force` (a third-party PreToolUse hook,
+ * NOT peaks-cli) 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;
 export type DoctorOptions = {
     schemasBaseDir?: string;
     skillsBaseDir?: string;
@@ -59,6 +96,8 @@ export type DoctorOptions = {
     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;
 };
 /**
  * Pure helper extracted from `defaultWorkspaceInitializedProbe` so tests can
@@ -99,4 +138,5 @@ export declare function inspectWorkspaceLayout(opts: {
     dotfileScanner?: (root: string) => string[];
     perChangeIdScanner?: (root: string) => string[];
 }): WorkspaceLayoutInspection;
+export declare function collectGateguardEntries(probe: GateguardProbeResult): GateguardHookLocation[];
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;