peaks-cli 1.1.2 → 1.2.1

package/README.md

@@ -10,13 +10,25 @@ npm install -g peaks-cli
 
 安装后，Peaks 会把内置 skills 注册到 Claude Code，你可以在对话里直接调用。
 
-验证安装：
+验证安装，跑这三条：
 
 ```bash
-peaks --help
-peaks skill list --json
+peaks -V           # prints the version
+peaks                # shows a quickstart with installed-skill count
+peaks doctor         # checks skills, config, env in one glance
 ```
 
+## 80 秒上手
+
+1. `peaks` 看一眼有哪些东西
+2. `peaks doctor` 确认环境 OK
+3. `peaks sop init --id my-flow --apply` 创建你的第一个 SOP 骨架
+4. 编辑 `~/.peaks/sops/my-flow/sop.json` 写上你的流程和门禁
+5. `peaks sop register --id my-flow` 注册它
+6. 声明 guard 把不可逆动作绑到 phase，`peaks hooks install` 装上强制 hook
+
+然后让 Claude 在对话里改文件、打算跑被 guard 的命令——它会被当场拦住。详见 [自定义 SOP](#自定义-sop用户自创流程门禁) 一节。如果用自然语言描述流程更顺手，直接用 `peaks-sop` 技能，它全程走上面的 CLI 链。
+
 ## 使用 Skills
 
 在 Claude Code 对话里，直接用 `skill名称 + 自然语言描述` 发起工作流：
@@ -79,6 +91,88 @@ peaks doctor --json
 peaks skill doctor --json
 ```
 
+## 自定义 SOP（用户自创流程门禁）
+
+除了内置的 `peaks-*` 技能家族，你还能用 `peaks sop` 命令族定义**自己的 SOP**：一组有序阶段（phases）加上绑定在阶段上的门禁（gates）。门禁不通过，就推不进对应阶段——把"流程不丢环节"落到你自己的工作流上。
+
+**这是一个通用的流程门禁工具，不限于研发。** 凡是"有先后阶段、进入下一步前必须满足某些可检查条件"的流程都适用——内容发布、合规/审批清单、数据校验管线、入职流程、运维 runbook、个人可重复流程……研发发布只是其中一个例子，往往非研发场景更有价值。
+
+> 更顺手的用法：直接用 **`peaks-sop` 技能**——在对话里用自然语言描述你的流程，由 LLM 帮你生成、调试、注册 SOP，无需手写 JSON 或记命令。下面的 CLI 是它底层调用的引擎。
+
+### 不可绕过的门禁（杀手锏）
+
+CI 只能在**合并时**拦，`CLAUDE.md` 里的规矩靠 agent **自觉**。Peaks 能做到 CI 和提示词都做不到的事：在**对话流程中途、面向 agent 本身**把不可逆动作摁住。
+
+给某个 phase 声明 **guard**（把一个 Bash 命令绑到该 phase），再装一个 PreToolUse hook：
+
+```bash
+# sop.json 里：把「发布」绑定到 git push，并要求正文无 TODO
+#   "gates":  [{ "id":"no-todo","phase":"publish",
+#               "check":{ "type":"grep","file":"posts/current.md","pattern":"TODO","absent":true } }]
+#   "guards": [{ "phase":"publish","bash":"git +push" }]
+peaks hooks install --project .        # 显式 opt-in，只写一条 PreToolUse 条目
+```
+
+此后 agent 正文里还留着 TODO 却想 `git push` 时，Claude Code 收到 `permissionDecision:"deny"`，命令**在任何权限检查之前被拦下——连 `--dangerously-skip-permissions` 都绕不过**。满足门禁后自动放行；紧急情况用 `peaks gate bypass --sop <id> --phase <phase> --reason "<原因>"` 一次性放行（每项目每 SOP 有上限、记原因）。
+
+强制层**故障即放行**（fail-open）：Peaks 自身任何内部错误都放行命令，绝不会卡死你的 Claude Code，只有真实门禁失败才拦。装 hook 是显式用户命令，skill 自己永不写 `settings.json`。`peaks hooks status` / `peaks hooks uninstall` 管理它。
+
+**团队强制**：把 SOP 用 `peaks sop init/register --project <repo>` 落到**仓库里**（`<repo>/.peaks/sops/`，随仓库提交）。队友 clone 后——哪怕全局 `~/.peaks` 是空的——装上 hook 就被同一套门禁强制。SOP 定义分两层:仓库层(团队共享、随 PR 评审)优先，全局层(你个人跨项目复用)兜底。只放在全局的 SOP 只对你本机生效。
+
+**两层定义、执行按项目**：SOP 定义（`sop.json` + 可注册的 `SKILL.md`）可放在**全局** `~/.peaks/sops/`（个人跨项目复用，`init`/`lint`/`register` 默认层）或**仓库** `<repo>/.peaks/sops/`（随仓库提交、团队共享，加 `--project <repo>`）；同 id 时**仓库层优先**。运行态（当前阶段、历史）始终按项目落在 `<project>/.peaks/sop-state/<sop-id>/`，各项目独立进度。`check`/`advance` 带 `--project`（默认当前目录）指定对哪个项目执行、用哪层定义。
+
+```bash
+# 1. 创建 SOP 骨架到 ~/.peaks/sops（默认预览不落盘，--apply 才写入）
+peaks sop init --id team-release --name "Team Release" --apply --json
+
+# 2. 校验 manifest（门禁 id 唯一、阶段合法、check 字段完整）
+peaks sop lint --id team-release --json
+
+# 3. 注册进全局门禁注册表（--dry-run 预览）
+peaks sop register --id team-release --json
+
+# 4. 列出注册表里所有自定义门禁（内置 peaks-* 门禁永不出现）
+peaks sop registry --json
+
+# 5. 评估单个门禁（在某项目下，返回 pass / fail / blocked）
+peaks sop check --id team-release --gate changelog --project . --json
+
+# 6. 推进到某阶段——门禁须全过、且不能跳级，否则被真正阻断
+peaks sop advance --id team-release --to ship --project . --json
+```
+
+`sop.json` 示例：
+
+```json
+{
+  "id": "team-release",
+  "name": "Team Release",
+  "phases": ["draft", "review", "ship"],
+  "gates": [
+    { "id": "changelog", "phase": "ship", "check": { "type": "file-exists", "path": "CHANGELOG.md" } },
+    { "id": "no-fixme", "phase": "review", "check": { "type": "grep", "file": "src/index.ts", "pattern": "FIXME", "absent": true } },
+    { "id": "tests", "phase": "ship", "check": { "type": "command", "run": ["npm", "test"] } }
+  ]
+}
+```
+
+门禁 check 支持三类：
+
+| 类型 | 字段 | 含义 |
+|------|------|------|
+| `file-exists` | `path` | 文件存在 → pass |
+| `grep` | `file` + `pattern`（+ `absent`） | 文件内匹配到正则 → pass；加 `absent: true` 则反转——匹配不到才 pass（表达「不准有 X」，纯文本、免 `--allow-commands`、跨平台） |
+| `command` | `run`（参数数组）+ `expectExitZero` | 运行命令并按退出码判定 |
+
+「不准有 TODO / 占位符 / 遗留项」这类最常见的诉求，优先用 `grep` + `absent: true`，不必动用 `command` 门禁。
+
+安全约束：
+- `command` 类门禁运行用户定义的命令，**默认拒绝**，必须显式加 `--allow-commands` 才会评估；命令以参数数组执行（无 shell、无注入面）、有超时上限、工作目录锁定项目根。
+- `file-exists` / `grep` 的路径锁在项目根内，越界路径返回 `blocked`。
+- 有副作用的命令（init/register/advance）都支持 `--dry-run` 预览且不落盘。
+- `advance` 还会校验**阶段顺序**：可停留当前阶段、可回退，但不能越过下一个阶段跳级，跳级返回 `SOP_PHASE_SKIP`。
+- 被门禁阻断或被判跳级时，可用 `--allow-incomplete --reason "<原因>"` 显式绕过（同时绕过门禁与顺序校验）；assisted/strict 模式下还需 `--confirm`，且每个项目内每个 SOP 的绕过次数有上限。
+
 ## 许可
 
 MIT License，详见 [LICENSE](LICENSE)。

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

@@ -19,7 +19,20 @@ export function registerCoreAndArtifactCommands(program, io) {
         const result = report.summary.ok
             ? ok('doctor', report)
             : fail('doctor', 'DOCTOR_FAILED', 'One or more doctor checks failed', report, ['Fix failed checks and rerun peaks doctor']);
-        printResult(io, result, options.json);
+        if (options.json === true) {
+            printResult(io, result, true);
+        }
+        else {
+            // Human-readable: one line per check, green/red indicators, no JSON.
+            for (const check of report.checks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            io.stdout(`\n  ${report.summary.passed} passed, ${report.summary.failed} failed`);
+            if (!report.summary.ok) {
+                io.stderr(`\nDOCTOR_FAILED: ${report.summary.failed} check(s) failed. Fix them and rerun peaks doctor.`);
+            }
+        }
         if (!report.summary.ok) {
             process.exitCode = 1;
         }
@@ -27,13 +40,44 @@ export function registerCoreAndArtifactCommands(program, io) {
     const skill = program.command('skill').description('Manage Peaks skills');
     addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md')).action(async (options) => {
         const skills = await listSkills();
-        printResult(io, ok('skill.list', { skills }), options.json);
+        if (options.json === true) {
+            printResult(io, ok('skill.list', { skills }), true);
+        }
+        else {
+            const sorted = [...skills].sort((a, b) => {
+                if (a.name === 'peaks-sop')
+                    return -1;
+                if (b.name === 'peaks-sop')
+                    return 1;
+                if (a.name === 'peaks-solo')
+                    return -1;
+                if (b.name === 'peaks-solo')
+                    return 1;
+                return a.name.localeCompare(b.name);
+            });
+            for (const skill of sorted) {
+                io.stdout(`  ${skill.name.padEnd(14)}${skill.description}`);
+            }
+            io.stdout(`\n  Invoke any skill by typing its name in conversation (e.g. \`peaks-sop\`).`);
+        }
     });
     addJsonOption(skill.command('doctor').description('Run skill-related doctor checks')).action(async (options) => {
         const report = await runDoctor();
         const skillChecks = report.checks.filter((check) => check.id.startsWith('skill'));
         const failed = skillChecks.filter((check) => !check.ok).length;
-        printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0 }), options.json);
+        if (options.json === true) {
+            printResult(io, ok('skill.doctor', { checks: skillChecks, ok: failed === 0 }), true);
+        }
+        else {
+            for (const check of skillChecks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            io.stdout(`\n  ${skillChecks.length - failed} passed, ${failed} failed`);
+            if (failed > 0) {
+                io.stderr('\nOne or more skill checks failed.');
+            }
+        }
         if (failed > 0) {
             process.exitCode = 1;
         }

package/dist/src/cli/commands/gate-commands.d.ts

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

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

@@ -0,0 +1,103 @@
+import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production reads stdin. */
+async function readHookPayload() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    if (override !== undefined) {
+        return override;
+    }
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    return new Promise((resolveStdin) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolveStdin(data));
+        process.stdin.on('error', () => resolveStdin(data));
+    });
+}
+function emitDeny(io, reason) {
+    // The exact, verified PreToolUse decision shape. permissionDecision:"deny"
+    // blocks the tool call before Claude Code's permission checks (un-bypassable).
+    io.stdout(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason
+        }
+    }));
+}
+export function registerGateCommands(program, io) {
+    const gate = program.command('gate').description('SOP gate enforcement (PreToolUse hook handler and bypass)');
+    addJsonOption(gate
+        .command('enforce')
+        .description('PreToolUse hook handler: deny a Bash command guarded by an unsatisfied SOP gate')
+        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')).action(async (options) => {
+        // Trust red line: this runs on (potentially) every Bash call. Any failure to
+        // decide must FAIL-OPEN (allow), never block the user's Claude Code.
+        try {
+            const raw = await readHookPayload();
+            let command;
+            let toolName;
+            if (raw.trim().length > 0) {
+                const payload = JSON.parse(raw);
+                toolName = payload.tool_name;
+                command = payload.tool_input?.command;
+            }
+            if (toolName !== 'Bash' || typeof command !== 'string' || command.trim().length === 0) {
+                // Not a guarded surface — allow (no output = normal permission flow).
+                if (options.json === true) {
+                    printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
+                }
+                return;
+            }
+            const decision = await enforceBashCommand(options.project, command);
+            if (decision.decision === 'deny') {
+                emitDeny(io, decision.reason);
+                if (options.json === true) {
+                    io.stderr(JSON.stringify(ok('gate.enforce', decision)));
+                }
+                return;
+            }
+            if (decision.warnings && decision.warnings.length > 0) {
+                for (const warning of decision.warnings) {
+                    io.stderr(warning);
+                }
+            }
+            if (options.json === true) {
+                io.stderr(JSON.stringify(ok('gate.enforce', decision)));
+            }
+            // allow: emit nothing on stdout → normal permission flow.
+        }
+        catch (error) {
+            // Fail-open: a bug in enforcement must not brick Claude Code.
+            io.stderr(`gate enforce: internal error, allowing command (${getErrorMessage(error)})`);
+        }
+    });
+    addJsonOption(gate
+        .command('bypass')
+        .description('Record a one-shot bypass so the next guarded Bash command is allowed once')
+        .requiredOption('--sop <id>', 'SOP id whose guard to bypass')
+        .requiredOption('--phase <phase>', 'phase whose gate to bypass')
+        .requiredOption('--reason <text>', 'justification recorded for the bypass')
+        .option('--project <path>', 'project whose run-state holds the token (default: current directory)', '.')).action((options) => {
+        try {
+            if (options.reason.trim().length === 0) {
+                printResult(io, fail('gate.bypass', 'BYPASS_REASON_REQUIRED', '--reason must not be empty', { sop: options.sop, phase: options.phase }, ['Provide --reason "<why>"']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = recordGateBypass(options.project, options.sop, options.phase, options.reason);
+            printResult(io, ok('gate.bypass', { sop: options.sop, phase: options.phase, count: result.count }, [], ['The next guarded Bash command for this transition will be allowed once']), options.json);
+        }
+        catch (error) {
+            const code = error instanceof GateBypassError ? error.code : 'GATE_BYPASS_FAILED';
+            printResult(io, fail('gate.bypass', code, getErrorMessage(error), { sop: options.sop, phase: options.phase }, ['Satisfy the gate instead of bypassing']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/hooks-commands.d.ts

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

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

@@ -0,0 +1,75 @@
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { applyHookInstall, planHookInstall, readHookStatus, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+function resolveProjectRoot(scope, project) {
+    return scope === 'project' ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd()) : undefined;
+}
+export function registerHooksCommands(program, io) {
+    const hooks = program
+        .command('hooks')
+        .description('Manage the Peaks gate-enforcement PreToolUse hook in .claude/settings.json');
+    addJsonOption(hooks
+        .command('install')
+        .description('Install the un-bypassable SOP gate hook (project scope by default)')
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--dry-run', 'show what would change without writing')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        try {
+            if (options.dryRun === true) {
+                const plan = planHookInstall(scope, projectRoot);
+                printResult(io, ok('hooks.install', { ...plan, applied: false, dryRun: true }), options.json);
+                return;
+            }
+            const result = applyHookInstall(scope, projectRoot);
+            const nextActions = result.applied
+                ? ['Restart Claude Code (or reload the window) so the gate hook takes effect']
+                : [];
+            printResult(io, ok('hooks.install', { ...result, dryRun: false }, [], nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.install', 'HOOKS_INSTALL_FAILED', message, { scope, applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('uninstall')
+        .description('Remove the Peaks gate-enforcement hook from .claude/settings.json')
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        try {
+            const result = removeHookInstall(scope, projectRoot);
+            printResult(io, ok('hooks.uninstall', result), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(hooks
+        .command('status')
+        .description('Report whether the Peaks gate hook is installed')
+        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = resolveProjectRoot(scope, options.project);
+        try {
+            const status = readHookStatus(scope, projectRoot);
+            printResult(io, ok('hooks.status', status), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('hooks.status', 'HOOKS_STATUS_FAILED', message, { scope }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -146,7 +146,7 @@ export function registerRequestCommands(program, io) {
             // Restrict --allow-incomplete in assisted/strict modes: require --confirm
             if (options.allowIncomplete === true && options.forceConfirm !== true) {
                 const { getSkillPresence } = await import('../../services/skills/skill-presence-service.js');
-                const presence = getSkillPresence();
+                const presence = getSkillPresence(options.project);
                 if (presence?.mode === 'assisted' || presence?.mode === 'strict') {
                     if (options.confirm !== true) {
                         printResult(io, fail('request.transition', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${presence.mode} mode`, { role, requestId, mode: presence.mode }, ['Add --confirm to proceed non-interactively, or run in an interactive terminal.']), options.json);

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

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

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

@@ -0,0 +1,215 @@
+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 '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.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; --project merges in the repo layer)')
+        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops)')).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;
+        }
+    });
+}

package/dist/src/cli/index.js

@@ -5,6 +5,18 @@ createProgram().parseAsync(process.argv).catch((error) => {
     if (error instanceof CommanderError && error.code === 'commander.version') {
         return;
     }
+    // exitOverride() also throws for help; suppress those — the text already went
+    // to stdout/stderr, the error envelope confuses newcomers. --help is success
+    // (exit 0); a bad command/option is an error (exit 1).
+    if (error instanceof CommanderError) {
+        if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
+            return;
+        }
+        if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {
+            process.exitCode = 1;
+            return;
+        }
+    }
     console.error(JSON.stringify({
         ok: false,
         command: 'cli',