peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/sop-advance-command.js

@@ -0,0 +1,160 @@
+// src/cli/commands/sop-advance-command.ts
+//
+// `peaks sop advance` — advance a SOP to a phase, enforcing the gate-bypass
+// policy. Split out of `sop-commands.ts`; every refusal code, message, `data`
+// field, next-action string and exit code is unchanged.
+import { mkdirSync } from 'node:fs';
+import { advanceSop, SopAdvanceError, SopGateBlockedError, SopPhaseSkipError } from '../../services/sop/sop-advance-service.js';
+import { sopStateDir } from '../../services/sop/sop-paths.js';
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+import { isBypassLimitReached, MAX_BYPASSES_PER_SESSION, recordBypass } from '../../services/mode/bypass-tracker.js';
+import { addJsonOption, getErrorMessage } from '../cli-helpers.js';
+import { printSopFailure, printSopOk } from './sop-command-shared.js';
+/**
+ * The bypass policy `request transition` also runs: a bypass needs a reason,
+ * and in assisted/strict mode (resolved from the target project) it needs an
+ * explicit `--confirm` and counts against the per-SOP bypass cap.
+ *
+ * Returns false when a refusal envelope was printed and the caller must stop.
+ */
+function enforceBypassPolicy(io, options) {
+    if (options.allowIncomplete !== true)
+        return true;
+    if (options.reason === undefined || options.reason.trim().length === 0) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.advance',
+            code: 'BYPASS_REASON_REQUIRED',
+            message: '--allow-incomplete requires --reason explaining why the gates are skipped',
+            data: { id: options.id, to: options.to },
+            nextActions: ['Add --reason "<short justification>" or satisfy the gates']
+        });
+        return false;
+    }
+    if (options.forceConfirm === true)
+        return true;
+    const presence = getSkillPresence(options.project);
+    if (presence?.mode !== 'assisted' && presence?.mode !== 'strict')
+        return true;
+    if (options.confirm !== true) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.advance',
+            code: 'ALLOW_INCOMPLETE_RESTRICTED',
+            message: `--allow-incomplete requires --confirm in ${presence.mode} mode`,
+            data: { id: options.id, mode: presence.mode },
+            nextActions: ['Add --confirm to bypass non-interactively']
+        });
+        return false;
+    }
+    // The bypass counter is keyed to the per-project SOP run-state dir (not a
+    // session); the shared cap constant is reused. Keying it per-project means a
+    // bypass in one project never consumes another project's budget. The state
+    // dir may not exist yet (no successful advance has written state.json), so
+    // ensure it before the counter writes its file.
+    const bypassRoot = sopStateDir(options.project, options.id);
+    mkdirSync(bypassRoot, { recursive: true });
+    if (isBypassLimitReached(bypassRoot)) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.advance',
+            code: 'BYPASS_LIMIT_REACHED',
+            message: `gate bypass limit reached (${MAX_BYPASSES_PER_SESSION} bypasses per SOP)`,
+            data: { id: options.id, limit: MAX_BYPASSES_PER_SESSION },
+            nextActions: ['Satisfy the gates instead of bypassing']
+        });
+        return false;
+    }
+    // A dry-run preview must not consume a bypass.
+    if (options.dryRun !== true) {
+        recordBypass(bypassRoot);
+    }
+    return true;
+}
+/** The three typed refusals `advanceSop` can raise, then the generic one. */
+function emitAdvanceError(io, options, error) {
+    if (error instanceof SopGateBlockedError) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.advance',
+            code: error.code,
+            message: error.message,
+            data: { id: options.id, to: options.to, blockedGates: error.blockedGates },
+            nextActions: [
+                'Satisfy the blocking gates, or bypass with --allow-incomplete --reason "<why>"'
+            ]
+        });
+        return;
+    }
+    if (error instanceof SopPhaseSkipError) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.advance',
+            code: error.code,
+            message: error.message,
+            data: {
+                id: options.id,
+                to: options.to,
+                fromPhase: error.fromPhase,
+                expectedNext: error.expectedNext
+            },
+            nextActions: [
+                `Advance to "${error.expectedNext}" first, or bypass with --allow-incomplete --reason "<why>"`
+            ]
+        });
+        return;
+    }
+    printSopFailure(io, {
+        json: options.json,
+        command: 'sop.advance',
+        code: error instanceof SopAdvanceError ? error.code : 'SOP_ADVANCE_FAILED',
+        message: getErrorMessage(error),
+        data: { id: options.id, to: options.to },
+        nextActions: ['Verify the SOP id and phase with peaks sop lint']
+    });
+}
+async function runSopAdvance(io, options) {
+    try {
+        if (!enforceBypassPolicy(io, options))
+            return;
+        const advanceOptions = {
+            projectRoot: options.project,
+            id: options.id,
+            toPhase: options.to
+        };
+        if (options.allowCommands === true)
+            advanceOptions.allowCommands = true;
+        if (options.allowIncomplete === true)
+            advanceOptions.allowIncomplete = true;
+        if (options.reason !== undefined)
+            advanceOptions.reason = options.reason;
+        if (options.dryRun === true)
+            advanceOptions.dryRun = true;
+        const result = await advanceSop(advanceOptions);
+        printSopOk(io, {
+            json: options.json,
+            command: 'sop.advance',
+            data: result,
+            nextActions: result.applied
+                ? []
+                : ['Gates passed; re-run without --dry-run to record the advance']
+        });
+    }
+    catch (error) {
+        emitAdvanceError(io, options, error);
+    }
+}
+export function registerSopAdvanceCommand(sop, io) {
+    addJsonOption(sop
+        .command('advance')
+        .description('Advance a SOP to a phase; gates guarding that phase must pass (or be explicitly bypassed)')
+        .requiredOption('--id <sop-id>', 'SOP id')
+        .requiredOption('--to <phase>', 'phase to advance into')
+        .option('--project <path>', 'project whose run-state advances (default: current directory)', '.')
+        .option('--allow-commands', 'permit evaluating command-type gates')
+        .option('--allow-incomplete', 'bypass the phase gates AND phase-order check (requires --reason)')
+        .option('--reason <text>', 'justification recorded when bypassing gates')
+        .option('--confirm', 'skip interactive confirmation for a bypass in assisted/strict mode')
+        .option('--force-confirm', 'bypass mode-enforced confirmation (use with caution)')
+        .option('--dry-run', 'evaluate gates without recording the advance in state.json')).action((options) => runSopAdvance(io, options));
+}

package/dist/cli/commands/sop-check-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSopCheckCommand(sop: Command, io: ProgramIO): void;

package/dist/cli/commands/sop-check-command.js

@@ -0,0 +1,44 @@
+// src/cli/commands/sop-check-command.ts
+//
+// `peaks sop check` — evaluate a single SOP gate. Split out of
+// `sop-commands.ts`; the verb name, its options, its envelope fields and its
+// next-action strings are unchanged.
+import { checkGate, SopCheckError } from '../../services/sop/sop-check-service.js';
+import { addJsonOption, getErrorMessage } from '../cli-helpers.js';
+import { printSopFailure, printSopOk } from './sop-command-shared.js';
+async function runSopCheck(io, options) {
+    try {
+        const checkOptions = {
+            projectRoot: options.project,
+            id: options.id,
+            gateId: options.gate
+        };
+        if (options.allowCommands === true) {
+            checkOptions.allowCommands = true;
+        }
+        printSopOk(io, {
+            json: options.json,
+            command: 'sop.check',
+            data: await checkGate(checkOptions)
+        });
+    }
+    catch (error) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.check',
+            code: error instanceof SopCheckError ? error.code : 'SOP_CHECK_FAILED',
+            message: getErrorMessage(error),
+            data: { id: options.id, gateId: options.gate },
+            nextActions: ['Verify the SOP id and gate id with peaks sop lint']
+        });
+    }
+}
+export function registerSopCheckCommand(sop, io) {
+    addJsonOption(sop
+        .command('check')
+        .description('Evaluate a single SOP gate (returns pass / fail / blocked)')
+        .requiredOption('--id <sop-id>', 'SOP id')
+        .requiredOption('--gate <gate-id>', 'gate id within the SOP')
+        .option('--project <path>', 'project the gate evaluates against (default: current directory)', '.')
+        .option('--allow-commands', 'permit evaluating command-type gates')).action((options) => runSopCheck(io, options));
+}

package/dist/cli/commands/sop-command-shared.d.ts

@@ -0,0 +1,23 @@
+import { type ProgramIO } from '../cli-helpers.js';
+/** The `--project` / `--json` pair every verb in this family declares. */
+export type SopBaseOptions = {
+    project?: string;
+    json?: boolean;
+};
+/** The fields a family success envelope carries. */
+export type SopOutcome = {
+    readonly json: boolean | undefined;
+    readonly command: string;
+    readonly data: unknown;
+    readonly nextActions?: readonly string[];
+};
+/** The fields a family failure envelope carries. */
+export type SopFailure = SopOutcome & {
+    readonly code: string;
+    readonly message: string;
+    readonly data: Record<string, unknown>;
+};
+/** Print the family's success envelope. */
+export declare function printSopOk(io: ProgramIO, outcome: SopOutcome): void;
+/** Print the family's failure envelope and mark the process failed. */
+export declare function printSopFailure(io: ProgramIO, failure: SopFailure): void;

package/dist/cli/commands/sop-command-shared.js

@@ -0,0 +1,18 @@
+// src/cli/commands/sop-command-shared.ts
+//
+// What every `peaks sop *` verb emits: the success envelope and the failure
+// envelope, both with the family's `ok`/`fail` shape and the `--json` switch.
+// Split out of `sop-commands.ts`; no envelope field or exit code changed.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+/** Print the family's success envelope. */
+export function printSopOk(io, outcome) {
+    printResult(io, ok(outcome.command, outcome.data, [], [...(outcome.nextActions ?? [])]), outcome.json ?? false);
+}
+/** Print the family's failure envelope and mark the process failed. */
+export function printSopFailure(io, failure) {
+    printResult(io, fail(failure.command, failure.code, failure.message, failure.data, [
+        ...(failure.nextActions ?? [])
+    ]), failure.json ?? false);
+    process.exitCode = 1;
+}

package/dist/cli/commands/sop-commands.d.ts

@@ -1,3 +1,17 @@
+/**
+ * `peaks sop` — author and validate user-defined SOP skills.
+ *
+ *   - `peaks sop init`       — scaffold a SOP (manifest + SKILL.md)
+ *   - `peaks sop lint`       — validate the manifest
+ *   - `peaks sop register`   — record the SOP's gates in the gate registry
+ *   - `peaks sop registry`   — list registered SOPs and gates
+ *   - `peaks sop check`      — evaluate one gate
+ *   - `peaks sop advance`    — advance to a phase, enforcing the bypass policy
+ *
+ * Registration order is the user's reading order and is what the whole-registry
+ * render pins; each verb's implementation lives beside this file, one module
+ * per verb, over the shared envelope helpers in `sop-command-shared.ts`.
+ */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerSopCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/sop-commands.js

@@ -1,243 +1,29 @@
-import { mkdirSync } from 'node:fs';
-import { initSop, lintSop } from '../../services/sop/sop-service.js';
-import { registerSop, readRegistry, SopRegisterError } from '../../services/sop/sop-registry-service.js';
-import { checkGate, SopCheckError } from '../../services/sop/sop-check-service.js';
-import { advanceSop, SopAdvanceError, SopGateBlockedError, SopPhaseSkipError } from '../../services/sop/sop-advance-service.js';
-import { sopStateDir } from '../../services/sop/sop-paths.js';
-import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
-import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/**
+ * `peaks sop` — author and validate user-defined SOP skills.
+ *
+ *   - `peaks sop init`       — scaffold a SOP (manifest + SKILL.md)
+ *   - `peaks sop lint`       — validate the manifest
+ *   - `peaks sop register`   — record the SOP's gates in the gate registry
+ *   - `peaks sop registry`   — list registered SOPs and gates
+ *   - `peaks sop check`      — evaluate one gate
+ *   - `peaks sop advance`    — advance to a phase, enforcing the bypass policy
+ *
+ * Registration order is the user's reading order and is what the whole-registry
+ * render pins; each verb's implementation lives beside this file, one module
+ * per verb, over the shared envelope helpers in `sop-command-shared.ts`.
+ */
+import { registerSopInitCommand } from './sop-init-command.js';
+import { registerSopLintCommand } from './sop-lint-command.js';
+import { registerSopRegisterCommand } from './sop-register-command.js';
+import { registerSopRegistryCommand } from './sop-registry-command.js';
+import { registerSopCheckCommand } from './sop-check-command.js';
+import { registerSopAdvanceCommand } from './sop-advance-command.js';
 export function registerSopCommands(program, io) {
     const sop = program.command('sop').description('Author and validate user-defined SOP skills');
-    addJsonOption(sop
-        .command('init')
-        .description('Scaffold a user-authored SOP (manifest + SKILL.md); global by default, --project commits it into a repo')
-        .requiredOption('--id <sop-id>', 'SOP id (lowercase kebab, e.g. team-release)')
-        .option('--name <name>', 'human-readable SOP name (defaults to the id)')
-        .option('--apply', 'write the SOP files (default: preview only)')
-        .option('--project <path>', 'scaffold into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action(async (options) => {
-        try {
-            const initOptions = { id: options.id };
-            if (options.name !== undefined) {
-                initOptions.name = options.name;
-            }
-            if (options.apply === true) {
-                initOptions.apply = true;
-            }
-            if (options.project !== undefined) {
-                initOptions.projectRoot = options.project;
-            }
-            const result = await initSop(initOptions);
-            // Side-effecting scaffold returns explicit next steps so the user doesn't
-            // have to recall the runbook: applied → edit then lint; preview → apply.
-            const nextActions = result.applied
-                ? [
-                    `Edit ${result.manifestPath} to define your real phases and gates`,
-                    `peaks sop lint --id ${result.id} --json`
-                ]
-                : [`Re-run with --apply to write ${result.manifestPath}`];
-            printResult(io, ok('sop.init', result, [], nextActions), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('sop.init', 'SOP_INIT_FAILED', getErrorMessage(error), { id: options.id }, [
-                'Check the SOP id before retrying'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(sop
-        .command('lint')
-        .description('Validate a SOP manifest (id namespace, phases, gate ids, check fields)')
-        .requiredOption('--id <sop-id>', 'SOP id to lint')
-        .option('--allow-commands', 'permit command-type gates (they run shell-less processes)')
-        .option('--project <path>', 'lint the project-layer SOP (<path>/.peaks/sops) instead of global')).action(async (options) => {
-        try {
-            const lintOptions = { id: options.id };
-            if (options.allowCommands === true) {
-                lintOptions.allowCommands = true;
-            }
-            if (options.project !== undefined) {
-                lintOptions.projectRoot = options.project;
-            }
-            const result = await lintSop(lintOptions);
-            if (result === null) {
-                printResult(io, fail('sop.lint', 'SOP_NOT_FOUND', `No SOP found for id "${options.id}"`, { id: options.id }, ['Run peaks sop init --id <sop-id> --apply first']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, result.ok
-                ? ok('sop.lint', result)
-                : fail('sop.lint', 'SOP_LINT_FAILED', `${result.findings.filter((f) => f.severity === 'error').length} lint error(s) in SOP "${options.id}"`, result, ['Fix the reported findings, then re-run peaks sop lint']), options.json);
-            if (!result.ok) {
-                process.exitCode = 1;
-            }
-        }
-        catch (error) {
-            printResult(io, fail('sop.lint', 'SOP_LINT_ERROR', getErrorMessage(error), { id: options.id }, [
-                'Check the SOP id before retrying'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(sop
-        .command('register')
-        .description('Validate a SOP and record its gates in the gate registry (global, or --project for the repo)')
-        .requiredOption('--id <sop-id>', 'SOP id to register')
-        .option('--allow-commands', 'permit command-type gates when validating')
-        .option('--dry-run', 'preview the registration without writing registry.json')
-        .option('--project <path>', 'register into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action(async (options) => {
-        try {
-            const registerOptions = { id: options.id };
-            if (options.allowCommands === true) {
-                registerOptions.allowCommands = true;
-            }
-            if (options.dryRun === true) {
-                registerOptions.dryRun = true;
-            }
-            if (options.project !== undefined) {
-                registerOptions.projectRoot = options.project;
-            }
-            const result = await registerSop(registerOptions);
-            printResult(io, ok('sop.register', result, [], result.applied ? [] : ['Re-run without --dry-run to write registry.json']), options.json);
-        }
-        catch (error) {
-            const code = error instanceof SopRegisterError ? error.code : 'SOP_REGISTER_FAILED';
-            printResult(io, fail('sop.register', code, getErrorMessage(error), { id: options.id }, [
-                'Run peaks sop lint to see why the SOP is not registrable'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(sop
-        .command('registry')
-        .description('List registered SOPs and gates (global; merges in the cwd project layer by default)')
-        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops) (default: current directory)', '.')).action(async (options) => {
-        try {
-            const registry = await readRegistry(options.project);
-            printResult(io, ok('sop.registry', registry), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('sop.registry', 'SOP_REGISTRY_FAILED', getErrorMessage(error), {}, [
-                'The global registry may be corrupted; inspect ~/.peaks/sops/registry.json'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(sop
-        .command('check')
-        .description('Evaluate a single SOP gate (returns pass / fail / blocked)')
-        .requiredOption('--id <sop-id>', 'SOP id')
-        .requiredOption('--gate <gate-id>', 'gate id within the SOP')
-        .option('--project <path>', 'project the gate evaluates against (default: current directory)', '.')
-        .option('--allow-commands', 'permit evaluating command-type gates')).action(async (options) => {
-        try {
-            const checkOptions = {
-                projectRoot: options.project,
-                id: options.id,
-                gateId: options.gate
-            };
-            if (options.allowCommands === true) {
-                checkOptions.allowCommands = true;
-            }
-            const result = await checkGate(checkOptions);
-            printResult(io, ok('sop.check', result), options.json);
-        }
-        catch (error) {
-            const code = error instanceof SopCheckError ? error.code : 'SOP_CHECK_FAILED';
-            printResult(io, fail('sop.check', code, getErrorMessage(error), { id: options.id, gateId: options.gate }, [
-                'Verify the SOP id and gate id with peaks sop lint'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(sop
-        .command('advance')
-        .description('Advance a SOP to a phase; gates guarding that phase must pass (or be explicitly bypassed)')
-        .requiredOption('--id <sop-id>', 'SOP id')
-        .requiredOption('--to <phase>', 'phase to advance into')
-        .option('--project <path>', 'project whose run-state advances (default: current directory)', '.')
-        .option('--allow-commands', 'permit evaluating command-type gates')
-        .option('--allow-incomplete', 'bypass the phase gates AND phase-order check (requires --reason)')
-        .option('--reason <text>', 'justification recorded when bypassing gates')
-        .option('--confirm', 'skip interactive confirmation for a bypass in assisted/strict mode')
-        .option('--force-confirm', 'bypass mode-enforced confirmation (use with caution)')
-        .option('--dry-run', 'evaluate gates without recording the advance in state.json')).action(async (options) => {
-        try {
-            // Bypass policy mirrors `request transition`: a bypass needs a reason, and
-            // in assisted/strict mode (resolved from the target project) it needs an
-            // explicit --confirm and counts against the per-SOP bypass cap.
-            if (options.allowIncomplete === true &&
-                (options.reason === undefined || options.reason.trim().length === 0)) {
-                printResult(io, fail('sop.advance', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why the gates are skipped', { id: options.id, to: options.to }, ['Add --reason "<short justification>" or satisfy the gates']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (options.allowIncomplete === true && options.forceConfirm !== true) {
-                const presence = getSkillPresence(options.project);
-                if (presence?.mode === 'assisted' || presence?.mode === 'strict') {
-                    if (options.confirm !== true) {
-                        printResult(io, fail('sop.advance', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${presence.mode} mode`, { id: options.id, mode: presence.mode }, ['Add --confirm to bypass non-interactively']), options.json);
-                        process.exitCode = 1;
-                        return;
-                    }
-                    // The bypass counter is keyed to the per-project SOP run-state dir (not
-                    // a session); the shared cap constant is reused. Keying it per-project
-                    // means a bypass in one project never consumes another project's budget.
-                    const bypassRoot = sopStateDir(options.project, options.id);
-                    // The per-project state dir may not exist yet (no successful advance has
-                    // written state.json), so ensure it before the counter writes its file.
-                    mkdirSync(bypassRoot, { recursive: true });
-                    if (isBypassLimitReached(bypassRoot)) {
-                        printResult(io, fail('sop.advance', 'BYPASS_LIMIT_REACHED', `gate bypass limit reached (${MAX_BYPASSES_PER_SESSION} bypasses per SOP)`, { id: options.id, limit: MAX_BYPASSES_PER_SESSION }, ['Satisfy the gates instead of bypassing']), options.json);
-                        process.exitCode = 1;
-                        return;
-                    }
-                    // A dry-run preview must not consume a bypass.
-                    if (options.dryRun !== true) {
-                        recordBypass(bypassRoot);
-                    }
-                }
-            }
-            const advanceOptions = {
-                projectRoot: options.project,
-                id: options.id,
-                toPhase: options.to
-            };
-            if (options.allowCommands === true)
-                advanceOptions.allowCommands = true;
-            if (options.allowIncomplete === true)
-                advanceOptions.allowIncomplete = true;
-            if (options.reason !== undefined)
-                advanceOptions.reason = options.reason;
-            if (options.dryRun === true)
-                advanceOptions.dryRun = true;
-            const result = await advanceSop(advanceOptions);
-            printResult(io, ok('sop.advance', result, [], result.applied ? [] : ['Gates passed; re-run without --dry-run to record the advance']), options.json);
-        }
-        catch (error) {
-            if (error instanceof SopGateBlockedError) {
-                printResult(io, fail('sop.advance', error.code, error.message, { id: options.id, to: options.to, blockedGates: error.blockedGates }, ['Satisfy the blocking gates, or bypass with --allow-incomplete --reason "<why>"']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (error instanceof SopPhaseSkipError) {
-                printResult(io, fail('sop.advance', error.code, error.message, {
-                    id: options.id,
-                    to: options.to,
-                    fromPhase: error.fromPhase,
-                    expectedNext: error.expectedNext
-                }, [
-                    `Advance to "${error.expectedNext}" first, or bypass with --allow-incomplete --reason "<why>"`
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const code = error instanceof SopAdvanceError ? error.code : 'SOP_ADVANCE_FAILED';
-            printResult(io, fail('sop.advance', code, getErrorMessage(error), { id: options.id, to: options.to }, [
-                'Verify the SOP id and phase with peaks sop lint'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
+    registerSopInitCommand(sop, io);
+    registerSopLintCommand(sop, io);
+    registerSopRegisterCommand(sop, io);
+    registerSopRegistryCommand(sop, io);
+    registerSopCheckCommand(sop, io);
+    registerSopAdvanceCommand(sop, io);
 }

package/dist/cli/commands/sop-init-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSopInitCommand(sop: Command, io: ProgramIO): void;

package/dist/cli/commands/sop-init-command.js

@@ -0,0 +1,51 @@
+// src/cli/commands/sop-init-command.ts
+//
+// `peaks sop init` — scaffold a user-authored SOP (manifest + SKILL.md).
+// Split out of `sop-commands.ts`; the verb name, its options, its envelope
+// fields and its next-action strings are unchanged.
+import { initSop } from '../../services/sop/sop-service.js';
+import { addJsonOption, getErrorMessage } from '../cli-helpers.js';
+import { printSopFailure, printSopOk } from './sop-command-shared.js';
+async function runSopInit(io, options) {
+    try {
+        const initOptions = { id: options.id };
+        if (options.name !== undefined) {
+            initOptions.name = options.name;
+        }
+        if (options.apply === true) {
+            initOptions.apply = true;
+        }
+        if (options.project !== undefined) {
+            initOptions.projectRoot = options.project;
+        }
+        const result = await initSop(initOptions);
+        // Side-effecting scaffold returns explicit next steps so the user doesn't
+        // have to recall the runbook: applied → edit then lint; preview → apply.
+        const nextActions = result.applied
+            ? [
+                `Edit ${result.manifestPath} to define your real phases and gates`,
+                `peaks sop lint --id ${result.id} --json`
+            ]
+            : [`Re-run with --apply to write ${result.manifestPath}`];
+        printSopOk(io, { json: options.json, command: 'sop.init', data: result, nextActions });
+    }
+    catch (error) {
+        printSopFailure(io, {
+            json: options.json,
+            command: 'sop.init',
+            code: 'SOP_INIT_FAILED',
+            message: getErrorMessage(error),
+            data: { id: options.id },
+            nextActions: ['Check the SOP id before retrying']
+        });
+    }
+}
+export function registerSopInitCommand(sop, io) {
+    addJsonOption(sop
+        .command('init')
+        .description('Scaffold a user-authored SOP (manifest + SKILL.md); global by default, --project commits it into a repo')
+        .requiredOption('--id <sop-id>', 'SOP id (lowercase kebab, e.g. team-release)')
+        .option('--name <name>', 'human-readable SOP name (defaults to the id)')
+        .option('--apply', 'write the SOP files (default: preview only)')
+        .option('--project <path>', 'scaffold into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action((options) => runSopInit(io, options));
+}

package/dist/cli/commands/sop-lint-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSopLintCommand(sop: Command, io: ProgramIO): void;