peaks-cli 1.3.9 → 1.4.0

package/dist/src/cli/commands/core-artifact-commands.js

@@ -5,12 +5,14 @@ import { getArtifactWorkspaceStatus, planArtifactSync } from '../../services/art
 import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../services/memory/project-memory-service.js';
 import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateResult } from '../../services/standards/project-standards-service.js';
 import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../services/standards/ide-aware-standards-service.js';
+import { migrateStandards } from '../../services/standards/migrate-service.js';
 import { listProfiles } from '../../services/profiles/profile-service.js';
 import { planProxyTest } from '../../services/proxy/proxy-service.js';
 import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { listSkills } from '../../services/skills/skill-registry.js';
 import { inspectSkillRunbook } from '../../services/skills/skill-runbook-service.js';
 import { setSkillPresence, clearSkillPresence, getSkillPresence, isSkillPresenceMode, touchSkillHeartbeat } from '../../services/skills/skill-presence-service.js';
+import { detectPresenceMarker } from '../../services/hooks/presence-marker-detector.js';
 import { getSessionId, getSessionMeta, rotateSessionBinding, setSessionMeta, setSessionTitle, listSessionMetas } from '../../services/session/session-manager.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -198,6 +200,16 @@ export function registerCoreAndArtifactCommands(program, io) {
             lastHeartbeat: updated.lastHeartbeat
         }), options.json);
     });
+    addJsonOption(skill
+        .command('detect-marker-loss')
+        .description('Detect whether the latest assistant message lost the Peaks-Cli status header while a peaks skill is still active (slice 028 detection primitive).')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--message <text>', 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)')).action((options) => {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const message = options.message ?? '';
+        const result = detectPresenceMarker({ project: projectRoot, latestAssistantMessage: message });
+        printResult(io, ok('skill.detect-marker-loss', result), options.json);
+    });
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
         .command('list')
@@ -449,6 +461,21 @@ export function registerCoreAndArtifactCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(standards
+        .command('migrate')
+        .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root')
+        .option('--apply', 'rewrite the legacy block in place; default is dry-run')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
+            printResult(io, ok('standards.migrate', result.data, [], result.data.nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('standards.migrate', 'STANDARDS_MIGRATE_FAILED', getErrorMessage(error), { file: null, foundOldBlock: false, wouldChange: false, applied: false, before: null, after: null, nextActions: [] }, [getErrorMessage(error)]), options.json);
+            process.exitCode = 1;
+        }
+    });
     const memory = program.command('memory').description('Manage project-local Peaks memory');
     addJsonOption(memory
         .command('extract')

package/dist/src/cli/commands/skill-scope-commands.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `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 { Command } from 'commander';
+import { type ResultEnvelope } from '../../shared/result.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type SkillScopeAction = 'detect' | 'apply' | 'show' | 'reset';
+export interface RunSkillScopeInput {
+    readonly subcommand: SkillScopeAction;
+    readonly project: string;
+    readonly strict?: boolean;
+    readonly loose?: boolean;
+    readonly ide?: string;
+    readonly shadowFallback?: boolean;
+    readonly json?: boolean;
+    /** Test seam: override the detected allowlist (CLI re-adds peaks-* per G6). */
+    readonly overrideAllowlist?: readonly string[];
+    /** Test seam: force the source-of-truth write to fail (simulates atomicity test). */
+    readonly simulateSourceOfTruthWriteFailure?: boolean;
+}
+export interface RunSkillScopeResult {
+    readonly exitCode: number;
+    readonly envelope: ResultEnvelope<unknown> | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Programmatic entry point for `peaks skill scope`. Used by the CLI shim
+ * AND by the unit tests.
+ */
+export declare function runSkillScopeCommand(input: RunSkillScopeInput): Promise<RunSkillScopeResult>;
+/**
+ * Register the `peaks skill scope` subcommand on the `skill` command group.
+ * Mutually-exclusive flags: exactly one of --detect / --apply / --show / --reset.
+ */
+export declare function registerSkillScopeCommands(program: Command, io: ProgramIO): void;

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

@@ -27,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();
@@ -107,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;
 }