peaks-cli 1.3.0 → 1.3.1

package/README.md

@@ -1,36 +1,35 @@
 # Peaks
 
-Peaks 是一组跑在 Claude Code 里的 **技能（SKILL）家族** ——把项目治理、工作流规划、受控执行、QA 验证、变更追踪组织成可复用的工程流程。
-CLI 是这些技能在背后调用的引擎，负责「门禁 + JSON 契约 + 不可逆动作」。
+[English](./README-en.md) | **简体中文**
 
-> **一句话定位**：你**用技能（SKILL）工作**，CLI 只是技能用来在 hook、CI、结构化判断等场景下提供机器层保障的底层。
+[![npm version](https://img.shields.io/npm/v/peaks-cli.svg)](https://www.npmjs.com/package/peaks-cli)
+[![GitHub repo](https://img.shields.io/badge/GitHub-SquabbyZ%2Fpeaks--cli-181717?logo=github)](https://github.com/SquabbyZ/peaks-cli)
 
-## 安装
-
-```bash
-npm install -g peaks-cli
-```
+Peaks 是一个**跨 AI IDE 的工作流门禁 CLI + 技能家族**——把项目治理、工作流规划、受控执行、QA 验证、变更追踪组织成可复用的工程流程。CLI 是跨 IDE 稳定的核心（门禁 + JSON 契约 + 不可逆动作），技能 / 钩子 / 配置按各 IDE 的原生格式承载。
 
-安装后，Peaks 会把内置的 8 个 `peaks-*` 技能注册到 Claude Code，会话里直接通过技能名调用即可。
+> **支持的 IDE**：
+> - ✅ **Claude Code**（当前实现）：11 个 `peaks-*` 技能 + `.claude/settings.json` PreToolUse hook
+> - 🚧 **Trae**（适配中）：用 Trae 的原生配置承载相同的角色 / 状态机 / 门禁
+> - 📋 **Codex / Cursor / Qoder / 通义灵码 等**（路线图）
 
-## 本地开发（从源码跑 CLI）
+> **产品定位**：你**用技能工作**，CLI 是跨 IDE 的质量保障层。
+>
+> 我们的目标：让 LLM 在每个环节里自由判断与决策；peaks 在流程边界上提供可审计的 SOP 护栏，把项目级记忆和使用经验沉淀下来——AI IDE 和 LLM 在你的项目上用得越久就越懂它。
 
-仓库自带 `peaks` CLI 源码。开发模式用 `tsx` 直接跑 `src/cli/index.ts`，所以**首次克隆后 `node_modules/` 里不会有 `chalk` / `ora` / `terminal-kit` 等运行时依赖**——直接 `tsx src/cli/index.ts` 会报 `ERR_MODULE_NOT_FOUND: chalk`。先执行一次 `pnpm install` 把依赖补齐，再验证：
+## 安装
 
 ```bash
-pnpm install
-pnpm exec tsx src/cli/index.ts --version   # 应打印 1.2.9
-pnpm exec tsx src/cli/index.ts <cmd>       # 与全局 `peaks <cmd>` 行为一致
+npm install -g peaks-cli
 ```
 
-热重载开发循环可用 `pnpm dev:watch`。
+安装后，Peaks 会把内置的 11 个 `peaks-*` 技能注册到已适配的 AI IDE（当前：Claude Code），会话里直接通过技能名调用即可。
 
 ## 5 分钟上手
 
-在 Claude Code 对话里，**直接对 Claude 说「用 X 技能做 Y」** 即可，技能会接管剩下的所有流程：
+在已适配的 AI IDE 对话里，**直接对 AI 说「用 X 技能做 Y」** 即可，技能会接管剩下的所有流程：
 
 ```text
-peaks-solo 用全自动模式治理 /path/to/your-project
+peaks-solo 帮我给登录页加 OAuth 回调      # 第一次显性用 peaks-solo；项目根 = IDE 当前 cwd
 peaks-prd  为会员邀请功能整理产品目标、非目标和验收标准
 peaks-rd   分析这次重构的最小实现切片和风险
 peaks-qa   为这次改动设计测试和回归验证清单
@@ -40,14 +39,22 @@ peaks-txt  为当前模块生成上下文胶囊，保留关键决策
 peaks-sop  帮我把"内容发布"流程变成带门禁的 SOP
 ```
 
-第一次使用？照这 4 步走：
+第一次使用？分两层：**你做 2 步，peaks 接管剩下**。
+
+**你需要做的（2 步）**：
+
+1. 在项目目录里打开已适配的 AI IDE：`cd /path/to/your-project && <你的 IDE 命令，如 claude>`——让 IDE 知道项目根在哪
+2. 在 IDE 里对 AI 说：**`peaks-solo 帮我做 X`**（X = 需求描述，如"给登录页加 OAuth 回调"）
+   - LLM 会按任务和项目推荐模式；想直接定可以写 `peaks-solo 全自动做 X` / `peaks-solo swarm X` / `peaks-solo strict X`
 
-1. 在 Claude Code 里对 Claude 说：**`peaks-solo 分析 /path/to/your-project`**
-2. 技能会自动跑：`peaks workspace init` → `peaks scan archetype` → 生成 `.peaks/<session-id>/rd/project-scan.md`
-3. 接着说你要做的需求，技能会按 PRD → RD → UI → QA → SC → TXT 的顺序把流程走完
-4. 工作流结束时，技能会把所有中间产物留在 `.peaks/<session-id>/`，并把"该记住的事实"写进 `.peaks/memory/`
+**之后 peaks 会自动**：
 
-想要随时确认状态？让 Claude 跑一下：
+- 跑 `peaks workspace init`（首次会创建 `.peaks/`）→ `peaks scan archetype` → 生成 `.peaks/<session-id>/rd/project-scan.md`
+- 复杂任务按 PRD → RD → UI → QA → SC → TXT 协调；简单任务直接走 solo 全自动，无需分阶段
+- 工作流进行中可用 `peaks-solo-status` 看看当前到哪了；中断后用 `peaks-solo-resume` 继续
+- 工作流结束时把所有中间产物留在 `.peaks/<session-id>/`，并把"该记住的事实"写进 `.peaks/memory/`
+
+想要随时确认状态？让 AI 跑一下：
 
 ```bash
 peaks -V                # 版本号
@@ -69,28 +76,44 @@ peaks project dashboard --project . --json   # 当前项目 dashboard
 | `peaks-sc` | 变更追踪、commit 边界、artifact 留存、回滚证据 | 影响范围记录、回滚证据、变更控制 |
 | `peaks-txt` | 上下文胶囊、决策记录、知识压缩 | 模块理解、关键决策留存、复盘 |
 | `peaks-sop` | **把你的工作流变成带门禁的 SOP**（不是研发专属） | 内容发布、合规清单、数据 pipeline、运维 runbook、个人流程 |
+| `peaks-solo-resume` | **继续刚才没做完的切片**——一键检测 in-flight slice 的最深已完成 gate，省 3-5k token | 「继续完成刚才为完成的」「resume the unfinished slice」 |
+| `peaks-solo-status` | **看一眼现在到哪了**——5-CLI snapshot 表格（presence + session + dashboard + request + memory） | 「现在到哪了」「show me the dashboard」 |
+| `peaks-solo-test` | **跑项目测试**——从 `package.json` 探测测试工具（vitest / jest / mocha / pytest / ...），用项目原生命令跑并汇总 pass/fail | 「跑测试」「run the tests」 |
+
+### 两种基本用法
 
-### 三个常用工作流
+**1. 让 `peaks-solo` 编排（最常用）**
 
-**新功能（端到端）**
+`peaks-solo` 是产品入口，**绝大多数场景都用它**——告诉它做什么，剩下 PRD / UI / RD / QA / SC / TXT 的链路它自己协调。**默认模式不写死**：LLM 根据任务复杂度和项目状态主动推荐 assisted / full-auto / swarm / strict 中的一种；想自己指定时再显式标注：
 
 ```text
-peaks-prd  →  peaks-ui（如果涉及 UI）  →  peaks-rd  →  peaks-qa  →  peaks-sc
+peaks-solo 帮我做 X              # 默认（不写死，LLM 按任务和项目推荐）；X = 需求描述；项目路径走 IDE 当前 cwd
+peaks-solo 全自动做 X            # 显式 full-auto：端到端跑完
+peaks-solo swarm 模式做 X        # 显式 swarm：最大化子代理并行（适合大任务）
+peaks-solo strict 模式做 X       # 显式 strict：最严格门禁
 ```
 
-**重构既有项目**
+3 个 `peaks-solo-*` 包装技能是 solo 的轻量变体（不算单独角色）：
 
-```text
-peaks-txt（先压缩现状）  →  peaks-prd（明确目标）  →
-peaks-rd（拆最小切片）   →  peaks-qa（回归矩阵）  →
-peaks-solo（编排执行）   →  peaks-sc（变更证据）
-```
+- `peaks-solo-resume` —— 继续刚才没做完的切片
+- `peaks-solo-status` —— 看看现在到哪了
+- `peaks-solo-test` —— 跑项目测试
 
-**修 bug**
+**2. 直接调用单个角色技能（进阶）**
 
-```text
-peaks-rd（复现 + 根因）  →  peaks-qa（失败用例 + 验收）  →  改代码（先补失败测试）  →  peaks-sc
-```
+只有当你只想做工作流的**一个阶段**（比如只写 PRD、只做架构分析、只跑回归），不想走 full pipeline 时，才单独调这些：
+
+| 技能 | 你用它做什么 | 什么时候才需要 |
+|---|---|---|
+| `peaks-prd` | 写 / 改 PRD（目标、非目标、行为保留、验收标准） | 想自己定义需求，不走 solo 整流程 |
+| `peaks-rd` | 架构分析 + 最小切片规划 + 风险 | 只想拿一份技术分析，不要写代码 |
+| `peaks-qa` | 测试用例 + 回归矩阵 + 验收证据 | 只想补测试，不走完整 solo |
+| `peaks-ui` | 视觉方向 + 交互方案 + 设计系统约束 | 只做 UI 设计，不带实现 |
+| `peaks-sc` | 影响范围 + commit 边界 + 留存策略 | 只想记录变更，不触发整流程 |
+| `peaks-txt` | 上下文胶囊 + 决策记录 | 只想压缩知识，不走整流程 |
+| `peaks-sop` | 把任意工作流（不只是开发）变成带门禁的 SOP | 想定义 / 注册自己的 SOP |
+
+**3 个 solo 包装 + 7 个角色技能 + 1 个 solo 编排 = 11 个技能家族。** 日常使用中，1 个（`peaks-solo`）覆盖 ≥90% 的需求。
 
 ## 怎么用：技能优先，CLI 是门禁
 
@@ -108,8 +131,11 @@ Peaks 里的 `peaks <cmd>` CLI **不是日常使用的主要入口**。它的存
 
 ```bash
 peaks workspace init --project <repo> --json       # 创建 .peaks/ 工作区（每个 session 一次）
+peaks workspace reconcile --project <repo> --json  # 4-tier heuristic 重新指向 canonical session，干掉孤儿 dir（默认 dry-run，--apply 才删）
 peaks scan archetype --project <repo> --json       # 探测项目原型（greenfield/legacy-frontend/...）
+peaks scan libraries --project <repo> --json       # 枚举依赖 + 解析 major，支持 monorepo
 peaks request init/show/transition                 # PRD/RD/QA/SC 的请求状态机
+peaks session list/info/title/rotate               # session 元数据；rotate 丢弃绑定让下次 peaks 自动重生成
 peaks sop init/lint/check/advance/register         # 你的自定义 SOP 生命周期
 peaks hooks install --project <repo>               # 装门禁的 PreToolUse hook
 peaks project dashboard --project <repo> --json    # 整个项目一眼看完
@@ -161,16 +187,6 @@ peaks hooks install --project <repo>   # 显式 opt-in：装一条 PreToolUse
 
 > **两层定义、执行按项目**：SOP 定义（`sop.json` + `SKILL.md`）可以放在**全局** `~/.peaks/sops/`（个人跨项目复用）或**仓库** `<repo>/.peaks/sops/`（随仓库提交、团队共享；`peaks sop init/register --project <repo>`）。**仓库层优先**于全局层。运行态（当前阶段、历史）按项目落在 `<project>/.peaks/sop-state/<sop-id>/`。
 
-## 工程结构（了解 peaks-cli 本身）
-
-```text
-skills/        # 8 个 SKILL.md（peaks-solo / -prd / -rd / -qa / -ui / -sc / -txt / -sop）
-src/cli/       # CLI 引擎（commands/、services/、hooks/、memory/、sop/、scan/、...）
-bin/peaks.js   # 入口
-docs/          # 设计文档
-openspec/      # 内部 OpenSpec 变更提案
-```
-
 ## 许可
 
 MIT License，详见 [LICENSE](LICENSE)。

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

@@ -1,7 +1,7 @@
 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';
+import { applyHookInstall, PEAKS_HOOK_ENTRIES, planHookInstall, readHookStatus, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
 function resolveScope(options) {
     return options.global ? 'global' : 'project';
 }
@@ -11,10 +11,10 @@ function resolveProjectRoot(scope, project) {
 export function registerHooksCommands(program, io) {
     const hooks = program
         .command('hooks')
-        .description('Manage the Peaks gate-enforcement PreToolUse hook in .claude/settings.json');
+        .description('Manage the Peaks PreToolUse hooks in .claude/settings.json: (1) Bash→peaks gate enforce (SOP gate), (2) Task→peaks progress start (auto-spawn sub-agent progress terminal). Both are installed / removed together.');
     addJsonOption(hooks
         .command('install')
-        .description('Install the un-bypassable SOP gate hook (project scope by default)')
+        .description(`Install all peaks-managed PreToolUse hooks (${PEAKS_HOOK_ENTRIES.map((e) => e.matcher).join(', ')}) into the target .claude/settings.json. Idempotent: re-runs are no-ops. 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) => {
@@ -23,14 +23,26 @@ export function registerHooksCommands(program, io) {
         try {
             if (options.dryRun === true) {
                 const plan = planHookInstall(scope, projectRoot);
-                printResult(io, ok('hooks.install', { ...plan, applied: false, dryRun: true }), options.json);
+                printResult(io, ok('hooks.install', {
+                    ...plan,
+                    applied: false,
+                    dryRun: true,
+                    entries: PEAKS_HOOK_ENTRIES.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+                }, [], [`would install ${PEAKS_HOOK_ENTRIES.length} peaks-managed hook entries`]), 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']
+                ? [
+                    'Restart Claude Code (or reload the window) so the PreToolUse hooks take effect',
+                    `Installed: ${PEAKS_HOOK_ENTRIES.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`
+                ]
                 : [];
-            printResult(io, ok('hooks.install', { ...result, dryRun: false }, [], nextActions), options.json);
+            printResult(io, ok('hooks.install', {
+                ...result,
+                dryRun: false,
+                entries: PEAKS_HOOK_ENTRIES.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+            }, [], nextActions), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);
@@ -40,7 +52,7 @@ export function registerHooksCommands(program, io) {
     });
     addJsonOption(hooks
         .command('uninstall')
-        .description('Remove the Peaks gate-enforcement hook from .claude/settings.json')
+        .description('Remove all peaks-managed PreToolUse hooks (gate-enforce + progress-start) from the target .claude/settings.json. Third-party hooks are preserved.')
         .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);
@@ -57,14 +69,17 @@ export function registerHooksCommands(program, io) {
     });
     addJsonOption(hooks
         .command('status')
-        .description('Report whether the Peaks gate hook is installed')
+        .description('Report which peaks-managed PreToolUse hooks are installed (gate-enforce + progress-start).')
         .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);
+            printResult(io, ok('hooks.status', {
+                ...status,
+                entries: PEAKS_HOOK_ENTRIES.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+            }), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);

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

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { platform } from 'node:os';
 import chalk from 'chalk';
 import ora from 'ora';
-import { clearSpawnRecord, phaseAutoClosesSpawn, readSpawnRecord, readSubAgentProgress, resolveProgressProjectRoot, subAgentProgressPath, subAgentSpawnPath, writeSpawnRecord, writeSubAgentProgress } from '../../services/progress/progress-service.js';
+import { clearSpawnRecord, isRecentSpawn, phaseAutoClosesSpawn, readSpawnRecord, readSubAgentProgress, resolveProgressProjectRoot, subAgentProgressPath, subAgentSpawnPath, writeSpawnRecord, writeSubAgentProgress } from '../../services/progress/progress-service.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
@@ -156,12 +156,36 @@ export function registerProgressCommands(program, io) {
         .command('start')
         .description('Auto-spawn a new terminal running `peaks progress watch` for this project. Called by the LLM at the first phase transition; the user can close the new terminal at any time.')
         .option('--project <path>', 'target project root (defaults to git root or cwd)')
-        .option('--reason <text>', 'human-readable reason for the auto-spawn, recorded in the response data')).action(async (options) => {
+        .option('--reason <text>', 'human-readable reason for the auto-spawn, recorded in the response data')
+        .option('--quiet', 'suppress human-readable output (the Task-tool PreToolUse hook uses this to keep the LLM context clean)')).action(async (options) => {
         try {
             const projectRoot = options.project !== undefined
                 ? options.project
                 : resolveProgressProjectRoot(undefined, process.cwd());
             const canonical = resolveCanonicalProjectRoot(projectRoot);
+            // Idempotency check: when the Task-tool PreToolUse hook fires
+            // `peaks progress start` on every Task call, a fresh terminal
+            // should NOT be spawned if a watch window was already opened for
+            // this session within the last 5 minutes. The user closes the
+            // window deliberately; we honor that until the record ages out.
+            const recent = isRecentSpawn(canonical);
+            if (recent.recent) {
+                if (options.quiet !== true) {
+                    // Non-hook path: keep the human feedback (so an LLM running
+                    // peaks progress start manually understands the no-op).
+                }
+                printResult(io, ok('progress.start', {
+                    projectRoot: canonical,
+                    spawned: false,
+                    idempotent: true,
+                    reason: recent.reason,
+                    ageMs: recent.ageMs,
+                    note: 'a recent spawn record exists; the watch window is presumed open. Re-run after 5 min (TTL) or `peaks progress close` to force a fresh spawn.'
+                }, [], recent.reason === 'recent-spawn'
+                    ? []
+                    : ['run `peaks progress close` to clear the stale record and force a fresh spawn']), options.json);
+                return;
+            }
             const currentPlatform = platform();
             const peaksBin = process.argv[1] ?? 'peaks';
             const reasonSuffix = options.reason !== undefined ? ` — ${options.reason}` : '';

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

@@ -45,6 +45,11 @@ export function registerRequestCommands(program, io) {
             };
             if (options.sessionId !== undefined) {
                 serviceOptions.sessionId = options.sessionId;
+                // Back-compat: pre-1.3.0 the `--session-id <scope>` flag also
+                // set the on-disk dir name. Preserve that by passing the same
+                // value as the explicit change-id; the service still records
+                // the session binding separately in the artifact body.
+                serviceOptions.changeId = options.sessionId;
             }
             if (options.apply === true) {
                 serviceOptions.apply = true;

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

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

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

@@ -0,0 +1,42 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { sliceCheck } from '../../services/slice/slice-check-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerSliceCommands(program, io) {
+    const slice = program.command('slice').description('Run slice-level checks (TDD micro-cycle boundary, see ' +
+        'skills/peaks-solo/references/micro-cycle.md). `peaks slice check` bundles ' +
+        'tsc + vitest + 3-way review fan-out + gate verify-pipeline. ' +
+        'Boundaries only; do NOT run inside a micro-cycle.');
+    addJsonOption(slice
+        .command('check')
+        .description('Boundary check for a slice (post-micro-cycle, pre-peaks-qa). ' +
+        'Runs 4 stages in order: typecheck → unit-tests → review-fanout → ' +
+        'gate-verify-pipeline. Each stage reports pass / fail / skipped. ' +
+        'Exit 0 only if every stage passes or is skipped.')
+        .option('--project <path>', 'target project root', '.')
+        .option('--rid <rid>', 'request id; defaults to the active current-change binding')
+        .option('--refresh-fanout', 're-run the 3-way review fan-out (peaks-rd) even if the review files already exist', false)
+        .option('--skip-tests', 'skip the unit-test stage (e.g. docs-only slices)', false)).action(async (options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const result = await sliceCheck({
+                projectRoot,
+                ...(options.rid ? { rid: options.rid } : {}),
+                refreshFanout: options.refreshFanout === true,
+                skipTests: options.skipTests === true
+            });
+            const warnings = [];
+            if (result.stages.some((s) => s.status === 'fail')) {
+                warnings.push(`${result.stages.filter((s) => s.status === 'fail').length} of ${result.stages.length} stages failed. 边界 NOT ready — fix the failures and re-run, or proceed at your own risk.`);
+            }
+            printResult(io, ok('slice.check', result, warnings, result.nextActions), options.json ?? false);
+            if (!result.boundaryReady) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('slice.check', 'SLICE_CHECK_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path is a peaks repo, --rid is correct, and .peaks/_runtime/current-change is valid']), options.json ?? false);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -312,13 +312,13 @@ export function registerWorkflowCommands(program, io) {
         .description('Verify the complete rd→qa pipeline was followed for a request')
         .requiredOption('--rid <rid>', 'request identifier')
         .requiredOption('--project <path>', 'project root path')
-        .requiredOption('--session-id <id>', 'session identifier')
+        .option('--change-id <id>', 'change-id hint (when omitted, the on-disk change-id is resolved from the RD/QA artifact itself)')
         .option('--type <type>', 'request type: feature, bugfix, refactor, docs, config, chore', 'feature')).action(async (options) => {
         try {
             const result = await verifyPipeline({
                 projectRoot: options.project,
                 rid: options.rid,
-                sessionId: options.sessionId,
+                ...(options.changeId ? { changeId: options.changeId } : {}),
                 ...(options.type ? { requestType: options.type } : {})
             });
             const exitOk = result.complete ? 0 : 1;
@@ -328,7 +328,7 @@ export function registerWorkflowCommands(program, io) {
             process.exitCode = exitOk;
         }
         catch (error) {
-            printResult(io, fail('workflow.verify-pipeline', 'VERIFY_FAILED', getErrorMessage(error), {}, ['Check that --project, --rid, and --session-id are correct']), options.json);
+            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);
             process.exitCode = 1;
         }
     });

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

@@ -1,3 +1,66 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+type HooksDecision = 'installed' | 'skipped';
 export declare function registerWorkspaceCommands(program: Command, io: ProgramIO): void;
+/**
+ * Outcome of the first-time "install peaks hooks" decision attached to
+ * `peaks workspace init`. Reported in the response data so the LLM and
+ * the human both see what happened.
+ */
+export type FirstTimeHooksInstallOutcome = {
+    /** The decision recorded (or already on file) in the sticky marker. */
+    decision: HooksDecision;
+    /**
+     * What the install path actually did this call.
+     *   - first-decision: we recorded a brand-new sticky marker (and may have installed)
+     *   - reinstalled:    the marker said installed but the hooks were missing — we re-applied
+     *   - marker-honored: the marker already existed; we did not touch the hooks
+     *   - already-installed: the hooks were already present and the marker does not exist yet
+     *                          (we write a fresh marker to lock in the answer for next time)
+     */
+    action: 'first-decision' | 'reinstalled' | 'marker-honored' | 'already-installed';
+    scope: 'project' | 'global';
+    /**
+     * Why the action was the way it was (e.g. "stdin-not-tty", "user-answered-no",
+     * "marker-installed-hooks-missing"). Surfaced for forensics.
+     */
+    reason?: string;
+};
+export type ResolveFirstTimeHooksInstallOptions = {
+    projectRoot: string;
+    /**
+     * Explicit mode from the --install-hooks flag. When omitted, the default
+     * is "ask" in TTY mode and "auto" otherwise (see `defaultMode` logic).
+     */
+    explicitMode?: 'ask' | 'auto' | 'skip' | undefined;
+    /**
+     * Whether the caller is in --json mode. In --json mode we never prompt
+     * (the LLM cannot answer an interactive question) — we silently treat
+     * "ask" as "auto" and proceed.
+     */
+    jsonMode: boolean;
+};
+/**
+ * Resolve the first-time "install peaks hooks" decision for this project.
+ * Decision tree:
+ *
+ *   1. Read the sticky marker.
+ *      - Marker present:
+ *        - marker.decision === 'installed' AND hooks are present → action: marker-honored, no side effects
+ *        - marker.decision === 'installed' AND hooks are MISSING   → re-install, action: reinstalled
+ *        - marker.decision === 'skipped'                            → action: marker-honored, no install
+ *      - Marker absent:
+ *        - hooks already present → write a fresh 'installed' marker, action: already-installed
+ *        - otherwise:
+ *          - explicit --install-hooks=auto  → install + marker, action: first-decision
+ *          - explicit --install-hooks=skip  → marker only, action: first-decision
+ *          - explicit --install-hooks=ask OR default in TTY:
+ *              - jsonMode → silently auto-install (LLM cannot answer), action: first-decision
+ *              - TTY      → prompt; on yes install + marker, on no marker-only
+ *          - default in non-TTY → auto-install, action: first-decision
+ *
+ * Project scope is the only supported scope here; global scope is reserved
+ * for explicit `peaks hooks install --global` invocations.
+ */
+export declare function resolveFirstTimeHooksInstall(options: ResolveFirstTimeHooksInstallOptions): Promise<FirstTimeHooksInstallOutcome>;
+export {};