peaks-cli 1.2.5 → 1.2.7

package/README.md

@@ -1,6 +1,9 @@
 # Peaks
 
-Peaks 是一个面向 Claude Code 的 CLI 工具和技能族，把项目治理、工作流规划、受控执行、QA 验证、变更追踪组织成可复用的工程流程。
+Peaks 是一组跑在 Claude Code 里的 **技能（SKILL）家族** ——把项目治理、工作流规划、受控执行、QA 验证、变更追踪组织成可复用的工程流程。
+CLI 是这些技能在背后调用的引擎，负责「门禁 + JSON 契约 + 不可逆动作」。
+
+> **一句话定位**：你**用技能（SKILL）工作**，CLI 只是技能用来在 hook、CI、结构化判断等场景下提供机器层保障的底层。
 
 ## 安装
 
@@ -8,170 +11,153 @@ Peaks 是一个面向 Claude Code 的 CLI 工具和技能族，把项目治理
 npm install -g peaks-cli
 ```
 
-安装后，Peaks 会把内置 skills 注册到 Claude Code，你可以在对话里直接调用。
-
-验证安装，跑这三条：
+安装后，Peaks 会把内置的 8 个 `peaks-*` 技能注册到 Claude Code，会话里直接通过技能名调用即可。
 
-```bash
-peaks -V           # prints the version
-peaks                # shows a quickstart with installed-skill count
-peaks doctor         # checks skills, config, env in one glance
-```
+## 5 分钟上手
 
-## 80 秒上手
+在 Claude Code 对话里，**直接对 Claude 说「用 X 技能做 Y」** 即可，技能会接管剩下的所有流程：
 
-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
+```text
+peaks-solo 用全自动模式治理 /path/to/your-project
+peaks-prd  为会员邀请功能整理产品目标、非目标和验收标准
+peaks-rd   分析这次重构的最小实现切片和风险
+peaks-qa   为这次改动设计测试和回归验证清单
+peaks-ui   设计登录页的交互和视觉方案
+peaks-sc   记录这次变更的影响范围、artifact 留存和 commit 边界
+peaks-txt  为当前模块生成上下文胶囊，保留关键决策
+peaks-sop  帮我把"内容发布"流程变成带门禁的 SOP
+```
 
-然后让 Claude 在对话里改文件、打算跑被 guard 的命令——它会被当场拦住。详见 [自定义 SOP](#自定义-sop用户自创流程门禁) 一节。如果用自然语言描述流程更顺手，直接用 `peaks-sop` 技能，它全程走上面的 CLI 链。
+第一次使用？照这 4 步走：
 
-## 使用 Skills
+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/`
 
-在 Claude Code 对话里，直接用 `skill名称 + 自然语言描述` 发起工作流：
+想要随时确认状态？让 Claude 跑一下：
 
-```text
-peaks-solo 使用全自动模式治理 /path/to/your-project
-peaks-prd 为会员邀请功能整理产品目标、非目标和验收标准
-peaks-rd 分析这次重构的最小实现切片和风险
-peaks-qa 为这次改动设计测试和回归验证清单
-peaks-ui 设计登录页面的交互和视觉方案
-peaks-sc 记录这次变更的影响范围、artifact 留存和 commit 边界
-peaks-txt 为当前模块生成上下文胶囊，保留关键决策
+```bash
+peaks -V                # 版本号
+peaks                   # 当前 quickstart + 已安装技能数
+peaks doctor --json     # 环境/技能/配置一键体检
+peaks skill doctor --json
+peaks project dashboard --project . --json   # 当前项目 dashboard
 ```
 
-按任务选择对应技能：
+## 技能家族速查
 
-| 技能 | 用途 | 典型场景 |
+| 技能 | 你用它做什么 | 典型场景 |
 |------|------|----------|
-| `peaks-solo` | 端到端编排入口 | 全流程开发、从需求到上线 |
-| `peaks-prd` | 产品目标、非目标、验收标准 | 需求整理、重构目标定义 |
-| `peaks-ui` | UI/UX、交互和视觉约束 | 页面设计、交互方案、原型 |
-| `peaks-rd` | 研发分析、重构规划、执行契约 | 工程分析、最小实现切片、风险评估 |
-| `peaks-qa` | 测试、覆盖率、回归验证 | 测试设计、回归矩阵、验收检查 |
-| `peaks-sc` | 变更追踪、commit 边界、artifact 留存 | 影响范围记录、回滚证据 |
-| `peaks-txt` | 上下文胶囊、决策记录、知识压缩 | 模块理解、关键决策留存 |
-
-### 常用工作流
-
-**从零到一的新功能：**
-
-1. `peaks-prd` 输出功能目标、用户价值、验收标准和非目标
-2. `peaks-rd` 找到最小实现切片和受影响模块
-3. `peaks-ui` 补充交互和视觉方案（UI 相关任务）
-4. `peaks-qa` 定义新增测试和回归测试
-5. `peaks-solo` 端到端编排执行
+| `peaks-solo` | **端到端编排入口**。从需求到上线的全流程，自动协调 `prd/rd/ui/qa/sc/txt` | 全流程开发、从产品文档/PRD 开始到上线、跨多个子任务的批量迭代 |
+| `peaks-prd` | 把模糊的产品意图变成**可验收的 PRD**：目标、非目标、行为保留、验收标准 | 需求整理、PRD 撰写、重构目标定义 |
+| `peaks-rd` | 工程分析 + 重构规划 + 执行契约（覆盖门、规格、风险） | 工程分析、最小实现切片、风险评估、重构规划 |
+| `peaks-ui` | UI/UX 交互和视觉约束、视觉方向、设计系统约束 | 页面设计、交互方案、原型、UI 回归 |
+| `peaks-qa` | 测试设计 + 覆盖率 + 回归验证 + 验收证据 | 测试用例、回归矩阵、验收检查、浏览器 E2E |
+| `peaks-sc` | 变更追踪、commit 边界、artifact 留存、回滚证据 | 影响范围记录、回滚证据、变更控制 |
+| `peaks-txt` | 上下文胶囊、决策记录、知识压缩 | 模块理解、关键决策留存、复盘 |
+| `peaks-sop` | **把你的工作流变成带门禁的 SOP**（不是研发专属） | 内容发布、合规清单、数据 pipeline、运维 runbook、个人流程 |
 
-**既有项目重构：**
+### 三个常用工作流
 
-1. `peaks-txt` 生成上下文胶囊，理解当前模块
-2. `peaks-prd` 明确重构目标、非目标和验收标准
-3. `peaks-rd` 分析项目结构、测试、脚本、关键模块和风险
-4. `peaks-qa` 定义回归矩阵和覆盖率门禁
-5. `peaks-solo` 端到端编排执行
-6. `peaks-sc` 记录 impact、retention、boundary
+**新功能（端到端）**
 
-**修 bug：**
+```text
+peaks-prd  →  peaks-ui（如果涉及 UI）  →  peaks-rd  →  peaks-qa  →  peaks-sc
+```
 
-1. 先复现或定位 bug
-2. `peaks-rd` 生成 root cause、修复策略和回归风险
-3. `peaks-qa` 定义失败用例和验收条件
-4. 先补失败测试，再做最小修复
-5. `peaks-sc` 记录影响范围和边界
+**重构既有项目**
 
-### 环境检查
+```text
+peaks-txt（先压缩现状）  →  peaks-prd（明确目标）  →
+peaks-rd（拆最小切片）   →  peaks-qa（回归矩阵）  →
+peaks-solo（编排执行）   →  peaks-sc（变更证据）
+```
 
-使用 skill 之前，建议先确认环境：
+**修 bug**
 
-```bash
-peaks doctor --json
-peaks skill doctor --json
+```text
+peaks-rd（复现 + 根因）  →  peaks-qa（失败用例 + 验收）  →  改代码（先补失败测试）  →  peaks-sc
 ```
 
-## 自定义 SOP（用户自创流程门禁）
+## 怎么用：技能优先，CLI 是门禁
 
-除了内置的 `peaks-*` 技能家族，你还能用 `peaks sop` 命令族定义**自己的 SOP**：一组有序阶段（phases）加上绑定在阶段上的门禁（gates）。门禁不通过，就推不进对应阶段——把"流程不丢环节"落到你自己的工作流上。
+Peaks 里的 `peaks <cmd>` CLI **不是日常使用的主要入口**。它的存在有三个理由，全都是机器层保障：
 
-**这是一个通用的流程门禁工具，不限于研发。** 凡是"有先后阶段、进入下一步前必须满足某些可检查条件"的流程都适用——内容发布、合规/审批清单、数据校验管线、入职流程、运维 runbook、个人可重复流程……研发发布只是其中一个例子，往往非研发场景更有价值。
+1. **不可逆动作的显式 opt-in**（例如 `peaks sop init --apply`、`peaks openspec archive --apply`）—— 这一刀不能靠 LLM"自觉"挥下。
+2. **结构化 JSON 契约**（`peaks request show ... --json`、`peaks scan archetype ... --json`）—— 让技能读回一个可机读的判决，作为下游决策的输入。
+3. **hook / CI / 脚本场景下能被程序化调用**（`peaks hooks install`、`peaks gate enforce`）—— 这层机器保障在对话里你看不到，但它把"必须满足门禁才能做 X"这件事从纸面规则变成可执行规则。
 
-> 更顺手的用法：直接用 **`peaks-sop` 技能**——在对话里用自然语言描述你的流程，由 LLM 帮你生成、调试、注册 SOP，无需手写 JSON 或记命令。下面的 CLI 是它底层调用的引擎。
+技能和 CLI 的关系可以记成一句话：**技能 = 流程的大脑**；**CLI = 流程的骨节**。
 
-### 不可绕过的门禁（杀手锏）
+### 你**会**用到的几条 CLI 命令
 
-CI 只能在**合并时**拦，`CLAUDE.md` 里的规矩靠 agent **自觉**。Peaks 能做到 CI 和提示词都做不到的事：在**对话流程中途、面向 agent 本身**把不可逆动作摁住。
-
-给某个 phase 声明 **guard**（把一个 Bash 命令绑到该 phase），再装一个 PreToolUse hook：
+虽然主要工作在技能里完成，但这些 CLI 命令在技能驱动下你也会经常看到被调用，概念上知道有它们就够了：
 
 ```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 条目
+peaks workspace init --project <repo> --json       # 创建 .peaks/ 工作区（每个 session 一次）
+peaks scan archetype --project <repo> --json       # 探测项目原型（greenfield/legacy-frontend/...）
+peaks request init/show/transition                 # PRD/RD/QA/SC 的请求状态机
+peaks sop init/lint/check/advance/register         # 你的自定义 SOP 生命周期
+peaks hooks install --project <repo>               # 装门禁的 PreToolUse hook
+peaks project dashboard --project <repo> --json    # 整个项目一眼看完
+peaks project memories --project <repo> --json     # 读取 .peaks/memory/ 里的历史决策
 ```
 
-此后 agent 正文里还留着 TODO 却想 `git push` 时，Claude Code 收到 `permissionDecision:"deny"`，命令**在任何权限检查之前被拦下——连 `--dangerously-skip-permissions` 都绕不过**。满足门禁后自动放行；紧急情况用 `peaks gate bypass --sop <id> --phase <phase> --reason "<原因>"` 一次性放行（每项目每 SOP 有上限、记原因）。
+完整命令列表跑 `peaks --help` 即可。
 
-强制层**故障即放行**（fail-open）：Peaks 自身任何内部错误都放行命令，绝不会卡死你的 Claude Code，只有真实门禁失败才拦。装 hook 是显式用户命令，skill 自己永不写 `settings.json`。`peaks hooks status` / `peaks hooks uninstall` 管理它。
+## 自定义 SOP（把你的流程变成带门禁的工作流）
 
-**团队强制**：把 SOP 用 `peaks sop init/register --project <repo>` 落到**仓库里**（`<repo>/.peaks/sops/`，随仓库提交）。队友 clone 后——哪怕全局 `~/.peaks` 是空的——装上 hook 就被同一套门禁强制。SOP 定义分两层:仓库层(团队共享、随 PR 评审)优先，全局层(你个人跨项目复用)兜底。只放在全局的 SOP 只对你本机生效。
+> **技能入口**：`peaks-sop` 技能
+> 告诉 Claude "帮我把『内容发布』做成一个 SOP"，它会引导你定义阶段、设定门禁、调试、注册，全程不用手写 JSON。
 
-**两层定义、执行按项目**：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`（默认当前目录）指定对哪个项目执行、用哪层定义。
+内置的 `peaks-*` 技能家族解决"开箱即用"的需求。但很多工作流是**领域特定的、有先后阶段、进入下一步前必须满足某些可检查条件**的——这种流程用 SOP（Standard Operating Procedure）来表达。
 
-```bash
-# 1. 创建 SOP 骨架到 ~/.peaks/sops（默认预览不落盘，--apply 才写入）
-peaks sop init --id team-release --name "Team Release" --apply --json
+`peaks-sop` 技能可以把任何这样的流程变成**带门禁的工作流**：
+
+| 领域 | 阶段举例 | 门禁思路 |
+|------|---------|---------|
+| 内容 / 发布 | draft → edit → publish | `file-exists` 草稿；`grep` 没有 `TODO`/`TKTK`；`command` 跑字数/拼写检查 |
+| 合规 / 审批 | prepare → review → sign-off | `file-exists` `approval.md`；`grep` 包含 "Approved" |
+| 数据 pipeline | raw → cleaned → validated | `command` 跑校验脚本，退出码 0 |
+| 运维 / 入职 | request → provision → done | `file-exists` 每个清单产物；`command` 校验配置 |
+| 研发发布（典型但非唯一） | draft → review → ship | `file-exists` CHANGELOG；`grep` 源码里没有 `FIXME`；`command` 跑测试 |
+| 个人流程 | 任何"不要忘步骤 X"的流程 | 把"判断"重新物化成一个文件/文本/退出码 |
 
-# 2. 校验 manifest（门禁 id 唯一、阶段合法、check 字段完整）
-peaks sop lint --id team-release --json
+### 门禁类型
 
-# 3. 注册进全局门禁注册表（--dry-run 预览）
-peaks sop register --id team-release --json
+| 类型 | 含义 | 例子 |
+|------|------|------|
+| `file-exists` | 文件存在 → pass | `CHANGELOG.md` 存在 |
+| `grep`（含 `absent`） | 文件内正则匹配 → pass；加 `absent: true` 反转（"不准有 X"） | "正文里没有 `TODO`" |
+| `command` | 跑命令并按退出码判定（默认拒绝，需 `--allow-commands`） | 跑 `npm test` |
 
-# 4. 列出注册表里所有自定义门禁（内置 peaks-* 门禁永不出现）
-peaks sop registry --json
+### 杀手锏：不可绕过的门禁
 
-# 5. 评估单个门禁（在某项目下，返回 pass / fail / blocked）
-peaks sop check --id team-release --gate changelog --project . --json
+CI 只能在**合并时**拦，`CLAUDE.md` 里的规则靠 agent **自觉**。SOP 能做到 CI 和提示词都做不到的事：**在对话中途、面向 agent 本身**把不可逆动作摁住。
 
-# 6. 推进到某阶段——门禁须全过、且不能跳级，否则被真正阻断
-peaks sop advance --id team-release --to ship --project . --json
+```jsonc
+// sop.json
+"guards": [ { "phase": "publish", "bash": "git +push" } ]
 ```
 
-`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"] } }
-  ]
-}
+```bash
+peaks hooks install --project <repo>   # 显式 opt-in：装一条 PreToolUse 规则
 ```
 
-门禁 check 支持三类：
+之后 agent 在 `publish` 阶段的门禁没全过时还想 `git push`，Claude Code 会收到 `permissionDecision: "deny"`，**在任何权限检查之前就被拦下——连 `--dangerously-skip-permissions` 都绕不过**。满足门禁后自动放行；紧急情况用 `peaks gate bypass --sop <id> --phase <phase> --reason "<原因>"` 一次性放行（每个项目每个 SOP 有上限、记原因）。
 
-| 类型 | 字段 | 含义 |
-|------|------|------|
-| `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 的绕过次数有上限。
+> **两层定义、执行按项目**：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 变更提案
+```
 
 ## 许可
 

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

@@ -1,5 +1,6 @@
 import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
 import { ensureSession } from '../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerWorkspaceCommands(program, io) {
@@ -18,15 +19,26 @@ export function registerWorkspaceCommands(program, io) {
             //   - omitted: defer to ensureSession(), which reuses an existing
             //     binding or auto-generates a fresh one. The init then writes
             //     .session.json so the binding sticks.
+            //
+            // Before that: canonicalise the project root. If the user (or the
+            // LLM via "$(pwd)") passed a sub-directory of a real git repo
+            // (e.g. prompt-project/prompt-project/ inside the outer
+            // prompt-project/.git), promote the path to the git root. Without
+            // this, peaks would build a parallel .peaks/ tree under the
+            // nested sub-folder and silently break the project-binding model
+            // (the same regression that produced prompt-project/.peaks/ in
+            // the 5/27-5/29 sessions). When startPath is not inside any
+            // git repo, the helper falls through to the cwd verbatim.
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
             let sessionId;
             if (options.sessionId !== undefined && options.sessionId.length > 0) {
                 sessionId = options.sessionId;
             }
             else {
-                sessionId = await ensureSession(options.project);
+                sessionId = await ensureSession(projectRoot);
             }
             const report = await initWorkspace({
-                projectRoot: options.project,
+                projectRoot,
                 sessionId,
                 allowSessionRebind: options.allowSessionRebind === true
             });

package/dist/src/services/config/config-safety.d.ts

@@ -2,6 +2,32 @@ export declare function getUserConfigPath(): string;
 export declare function isInsidePath(childPath: string, parentPath: string): boolean;
 export declare function findProjectRoot(startPath: string): string | null;
 export declare function resolveProjectRootForConfig(startPath: string): string;
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export declare function resolveCanonicalProjectRoot(startPath: string): string;
 export declare function getProjectConfigPath(projectRoot: string | null): string | null;
 export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
 export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;

package/dist/src/services/config/config-safety.js

@@ -1,4 +1,5 @@
 import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
@@ -89,6 +90,81 @@ export function resolveProjectRootForConfig(startPath) {
     }
     return pkgRoot ?? start;
 }
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export function resolveCanonicalProjectRoot(startPath) {
+    const start = resolve(startPath);
+    const gitRoot = resolveProjectRootFromGit(start);
+    if (gitRoot !== null) {
+        return gitRoot;
+    }
+    // Non-git fallback: walk the heuristic up to the home boundary.
+    // We do NOT call realpathSync on the heuristic result because the
+    // heuristic may legitimately return a path through a symlink that
+    // the caller passed in (no canonicalisation needed in that case).
+    const heuristicRoot = findProjectRoot(start);
+    if (heuristicRoot !== null) {
+        return heuristicRoot;
+    }
+    return start;
+}
+function resolveProjectRootFromGit(startPath) {
+    // execFileSync (not execSync) so a malicious `startPath` cannot
+    // inject argv into the spawned git invocation. The child only
+    // receives `startPath` as the cwd, never as a flag.
+    let rawRoot;
+    try {
+        const stdout = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: startPath,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0)
+            return null;
+        rawRoot = resolve(trimmed);
+    }
+    catch {
+        // git not on PATH, startPath is not in a repo, or some other
+        // benign failure — fall through to the heuristic.
+        return null;
+    }
+    // On macOS, /tmp is a symlink to /private/tmp; git returns the
+    // realpath. If the caller passed a path through the symlink, the
+    // two strings won't match byte-for-byte even though they refer
+    // to the same directory. realpathSync the git root and the
+    // startPath through the same lens so callers get a canonical
+    // answer that compares equal to the path they passed in.
+    try {
+        return realpathSync(rawRoot);
+    }
+    catch {
+        return rawRoot;
+    }
+}
 export function getProjectConfigPath(projectRoot) {
     if (!projectRoot)
         return null;

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

@@ -1,5 +1,5 @@
 import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, MiniMaxProviderConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
-export { resolveProjectRootForConfig } from './config-safety.js';
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 export declare function isConfigLayer(value: string): value is ConfigLayer;
 export declare function isSensitiveConfigPath(path: string): boolean;
 export declare function containsSensitiveConfigValue(value: unknown): boolean;

package/dist/src/services/config/config-service.js

@@ -3,8 +3,8 @@ import { dirname, isAbsolute, resolve } from 'node:path';
 import { DEFAULT_CONFIG } from './config-types.js';
 import { stablePath } from '../../shared/path-utils.js';
 import { findProjectRoot, getProjectBootstrapConfigPath, getProjectConfigPath, getUserConfigPath, isInsidePath, readConfigFileSafely, resolveProjectRootForConfig, validateArtifactWorkspaceMarkerPath, validateArtifactWorkspaceRoot, validateProjectBootstrapConfigPathForWrite, validateUserConfigPathForWrite, writeConfigFileSafely, writeProjectConfigFile, writeUserConfigFile } from './config-safety.js';
-// Re-export resolveProjectRootForConfig for external consumers
-export { resolveProjectRootForConfig } from './config-safety.js';
+// Re-export resolveProjectRootForConfig and resolveCanonicalProjectRoot for external consumers
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 function readJsonFile(path, validateBeforeRead, errorMessage = 'Config path must stay inside the config root') {
     if (!path || !existsSync(path))
         return null;

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.5";
+export declare const CLI_VERSION = "1.2.7";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.5";
+export const CLI_VERSION = "1.2.7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-solo/SKILL.md

@@ -1065,4 +1065,4 @@ Do not run upstream installer flows, mutate agent settings, or commit `.codegrap
 
 **MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
 
-Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`.
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`. For an informational mapping of peaks artefact paths to the A2A (Agent2Agent) protocol's Task / Artifact / Part / Message / AgentCard vocabulary (no A2A implementation, just a shared naming layer), see `references/a2a-artifact-mapping.md`.

package/skills/peaks-solo/references/a2a-artifact-mapping.md

@@ -0,0 +1,115 @@
+# A2A artifact mapping (informational)
+
+> Reference for `peaks-solo` and any other peaks skill that produces durable artefacts in `.peaks/<session-id>/`. Maps peaks's on-disk artefact vocabulary onto the A2A (Agent2Agent) protocol's vocabulary so a future peaks consumer (e.g. an external LLM agent or a downstream peaks-cli extension) can read peaks output without having to learn a brand-new schema. This is a **documentation mapping**, not a protocol implementation: peaks-cli does not speak A2A over HTTP, does not host an AgentCard endpoint, and does not advertise its capabilities via A2A's discovery mechanism. It only uses A2A's *concepts* as a shared naming layer.
+
+## 1. Why this reference exists
+
+The A2A protocol (https://a2acn.com) defines five core concepts: **AgentCard**, **Task**, **Artifact**, **Message**, and **Part**. peaks-cli's session workspace is a parallel vocabulary that grew up independently: `prd/requests/<rid>.md`, `rd/tech-doc.md`, `qa/test-cases/<rid>.md`, etc. The two vocabularies are *not* identical (A2A is HTTP-shaped, peaks is filesystem-shaped), but the A2A concepts are close enough that aligning peaks artefact names with A2A terms in this reference:
+
+- gives an external consumer a single translation table instead of two schemas to learn,
+- lets a peaks operator talk about "the artifact" or "the task" in mixed conversations without losing precision,
+- documents what peaks output is **not** (no SSE streaming, no remote AgentCard), so the limits are explicit.
+
+This is the kind of borrowing that costs zero code and earns some interoperability. It is **not** an integration: peaks-cli does not implement A2A, does not run an A2A server, and does not depend on the a2a-protocol package. Adopting A2A concepts here is the same as adopting any other shared nomenclature (UML, OpenTelemetry, etc.): it improves the conversation, nothing more.
+
+## 2. Concept-to-path mapping
+
+The mapping below uses peaks's own paths verbatim. Each row also notes where peaks **diverges** from A2A, so a reader does not assume parity.
+
+| A2A concept | peaks artefact | Path (under `.peaks/<session-id>/`) | Notes |
+|---|---|---|---|
+| **AgentCard** (capability advertisement) | `peaks-skill-output-style` + `.peaks/.active-skill.json` | `.peaks/.active-skill.json`, `.peaks/.session.json` | peaks is a *local* tool, not a service. The "card" is the active-skill file plus a peek at `.peaks/PROJECT.md` for human-readable history. There is no `/.well-known/agent-card.json` endpoint. |
+| **Task** (stateful unit of work) | `peaks request` state machine for a single `<rid>` | `.peaks/<sid>/{prd,rd,qa,ui,sc}/requests/<rid>.md` (the request artefact); `.peaks/<sid>/<role>/session.json` (per-session metadata) | peaks's task lifecycle is `prd:confirmed-by-user → handed-off`, then per role `draft → spec-locked → implemented → qa-handoff`, then `qa:running → verdict-issued`. The full state graph is enforced by `peaks request transition`. A2A's Task object is JSON; peaks's task is **a set of files with a `state` field per role**. |
+| **Artifact** (immutable output) | `rd/tech-doc.md`, `rd/code-review.md`, `rd/security-review.md`, `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md`, `sc/handoff.md` | as listed | peaks's artefacts are *append-once*, not strictly immutable: a `qa/test-reports/<rid>.md` may be re-emitted on repair cycles. The convention is "newest write wins; the file at the end of the workflow is the truth", which is close enough to A2A's immutable-Artifact semantics for translation purposes. |
+| **Message** (non-artifact communication) | `peaks skill presence` heartbeat + transition `--reason` notes | `.peaks/.active-skill.json` (`lastHeartbeat`), transition notes in `.peaks/<sid>/<role>/requests/<rid>.md` | peaks does **not** separate Messages from Artifacts at the storage layer; a "message" is anything that is not the artefact body (the `<!-- peaks-memory:start -->` markers, the `state` field, the `--reason` text on a transition). Treat these as inline metadata of the artefact, not as separate objects. |
+| **Part** (atomic content unit) | Markdown sections within an artefact, frontmatter fields | inline within the artefact | peaks's Artifacts are single Markdown files, so the "Part" concept maps to a heading or a frontmatter field. A `Part`'s `kind` in A2A terms is `text` (the prose), `file` (a `<!-- peaks-memory:start -->` block as a structured chunk), or `data` (the frontmatter). A2A's `form` / `iframe` / video `Part` kinds are not produced by peaks. |
+
+## 3. Field-level mapping (A2A Part ↔ peaks frontmatter)
+
+A2A `Part` has `kind` and `metadata` (free-form) plus `content` (typed by kind). peaks's per-artifact frontmatter carries a subset:
+
+```yaml
+---
+name: <slug>            # used in memory extraction; not a 1:1 A2A field
+description: <title>     # roughly the A2A Artifact.description
+metadata:
+  type: <kind>          # A2A Artifact.kind equivalent
+  sourceArtifact: <rel> # A2A Artifact.source / provenance equivalent
+---
+```
+
+A consumer reading a peaks artefact and translating it to A2A can populate:
+
+- `Artifact.name` ← peaks `name`
+- `Artifact.description` ← peaks `description` (or the first H1)
+- `Artifact.kind` ← peaks `metadata.type`
+- `Artifact.parts[0]` ← the body text (A2A `Part{kind: "text"}`)
+- `Artifact.metadata.sourcePath` ← peaks `metadata.sourceArtifact`
+- `Artifact.metadata.sessionId` ← from `.peaks/.session.json`
+
+The mapping is not 100% lossless: A2A's `Part` can carry structured forms or file references, peaks cannot. That is the explicit *non-goal* of this mapping; it would be over-claiming to assert parity where there is none.
+
+## 4. State-graph mapping (A2A Task ↔ peaks request)
+
+A2A's Task object has a small set of states (typically: `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`). peaks's per-role request state machine is richer and per-role:
+
+| Role | peaks states (in order) | Closest A2A Task state |
+|---|---|---|
+| `prd` | `draft` → `confirmed-by-user` → `handed-off` | `submitted` → `working` → `input-required` (for the confirm gate) |
+| `rd` | `draft` → `spec-locked` → `implemented` → `qa-handoff` | `working` |
+| `qa` | `draft` → `running` → `verdict-issued` (verdict is `pass` / `return-to-rd` / `blocked`) | `working` → `completed` (pass) / `input-required` (return-to-rd) / `failed` (blocked) |
+| `ui` | `draft` → `direction-locked` → `handed-off` | `working` → `completed` |
+| `sc` | `draft` → `recorded` | `working` → `completed` |
+
+A consumer translating peaks states to A2A should:
+
+- collapse peaks's multi-role state machine to a *single* A2A Task state by taking the most progressed of any role,
+- use the A2A `input-required` state to model **any** gate where peaks is waiting for a human (`confirmed-by-user`, `--confirm`, AskUserQuestion for a login wall, etc.),
+- emit `completed` only when QA verdict is `pass` and SC has recorded the change,
+- emit `failed` on `blocked` QA verdict or `blocked` handoff.
+
+## 5. Worked example: a feature slice from start to finish
+
+A user runs `peaks-solo` for a "add user authentication" feature. Mapping the resulting files to A2A concepts:
+
+```
+.peaks/<sid>/prd/requests/001.md      → A2A Artifact (kind=proposal)
+.peaks/<sid>/ui/requests/001.md       → A2A Artifact (kind=design-direction)
+.peaks/<sid>/ui/design-draft.md       → A2A Artifact (kind=visual-spec)
+.peaks/<sid>/rd/tech-doc.md           → A2A Artifact (kind=implementation-plan)
+.peaks/<sid>/qa/test-cases/001.md     → A2A Artifact (kind=test-cases)
+.peaks/<sid>/rd/code-review.md        → A2A Artifact (kind=review, status=fixed)
+.peaks/<sid>/rd/security-review.md    → A2A Artifact (kind=security-review)
+.peaks/<sid>/qa/test-reports/001.md    → A2A Artifact (kind=test-report, verdict=pass)
+.peaks/<sid>/qa/security-findings.md  → A2A Artifact (kind=security-findings)
+.peaks/<sid>/qa/performance-findings.md → A2A Artifact (kind=performance-findings)
+.peaks/<sid>/sc/handoff.md            → A2A Artifact (kind=change-record)
+.peaks/<sid>/txt/handoff.md           → A2A Artifact (kind=handoff-capsule)
+.peaks/<sid>/system/sub-agent-*.json  → A2A Message (sub-agent presence markers)
+.peaks/<sid>/sc/swarm-plan.json       → A2A Message (the dispatch plan)
+.peaks/memory/*.md                    → A2A Artifact (kind=project-memory, persists across sessions)
+```
+
+A consumer wanting to render a single "feature" object in A2A terms picks the `test-reports/001.md` (verdict=pass) as the terminal Artifact and the rest as supporting Parts or sibling Artifacts. The mapping is intentionally loose: peaks's value is that *all of these files exist*, not that they fit A2A's object model exactly.
+
+## 6. What peaks does NOT provide
+
+To keep the mapping honest, peaks-cli **does not** currently provide the following A2A primitives, and consumers should not expect them:
+
+- A2A **AgentCard** served over HTTP at `/.well-known/agent-card.json`. peaks-cli is a local CLI; its "card" is the on-disk `.peaks/.active-skill.json` plus `peaks skill doctor --json`.
+- A2A **streaming** responses (SSE / WebSocket). peaks commands are synchronous and return a single JSON envelope.
+- A2A **identity / auth** (OAuth, OIDC, mTLS). peaks assumes local-machine trust.
+- A2A **cross-vendor discovery**. peaks has no A2A registry entry; it has `peaks mcp list --json` for MCP-compatible capabilities.
+- A2A **Task delegation across the network**. peaks's "sub-agent" is a Claude Code `Task` tool call in the same process, not a remote A2A server.
+
+These are *deliberate* omissions. peaks-cli solves a different problem (a local workflow-gating CLI for Claude Code), and adopting A2A's networking surface would add weight without addressing peaks's actual failure modes (which are around LLM bypassing gates, not around inter-agent discovery).
+
+## 7. When to re-evaluate
+
+Re-open this mapping in any of the following cases:
+
+- a peaks user reports a real need to share workflow state with a non-peaks agent (e.g. an Autogen / LangChain agent that wants to read a peaks handoff capsule);
+- peaks-cli ships a hosted / multi-user mode where AgentCard-style discovery becomes useful;
+- the A2A protocol stabilises on a thin `Artifact` JSON schema that matches peaks's on-disk shape close enough to make translation a one-liner rather than a reference doc.
+
+Until one of those fires, this reference doc is the entire A2A surface area of peaks-cli. Adding more is over-engineering.