peaks-loop 4.0.0-beta.7 → 4.0.0-beta.9

package/README.md

@@ -1,106 +1,227 @@
-# Peaks Loop
+<div align="center">
 
-[English](./README-en.md) | **简体中文**
+# peaks-loop
 
-[![npm](https://img.shields.io/npm/v/peaks-loop?style=flat-square&logo=npm)](https://www.npmjs.com/package/peaks-loop)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
-[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+### 你说话,它替你跑完一整条工程流水线 —— 不止写代码,跑两次就沉淀成本地战术。
+
+[![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
+[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+
+[English](./README-en.md) · **简体中文**
+
+</div>
 
 <p align="center">
-  <a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">
-    <img src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/out/zh-closing-960.png" alt="peaks-loop demo (点击播放)" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);">
-  </a>
+  <img
+    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.gif"
+    alt="peaks-loop 30 秒演示(前 18 秒 · install + 斜杠命令 + 5 域 + 沉淀成 bee)"
+    width="92%"
+    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
+  />
   <br>
-  <sub>👆 点击图片播放 60s 演示</sub>
+  <sub>👆 18s 循环 GIF(<a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo.mp4">完整 30s mp4 下载</a> · 13MB · 480p)</sub>
 </p>
 
+---
+
 ## 它是什么
 
-### loop engineering 的工程实现
+peaks-loop 是一个 **Loop Engineering 结晶系统**,不是工作流工具 —— 你跑过的工作里,沉淀下来的不是「流程」,是一套**可被 karpathy 风格工程化、又被 darwin 风格独立验证**的 Loop Engineering 方法资产。**Loop engineering 结晶系统** 的工程实现见 [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)。
 
-**peaks-loop 是你的 Loop Engineering 结晶系统 —— 不是工作流工具。** 它从真实完成的工作里把 loop engineering 资产结晶出来,只通过被验证的改进让它们进化。你只用自然语言和选择操作系统,所有结构化操作由 LLM 代办。
+| 资产层 | 角色 | 一句话 |
+| --- | --- | --- |
+| **Loop Engineering 资产** | 方法系统,一等公民 | 回答「为什么有这条 loop、何时触发、怎样算成功、如何改进」 |
+| **Bee 资产** | 可执行体,一等公民 | Loop Engineering 资产的可执行体,蜂群里的每只 bee |
+| **Workflow Trace (执行轨迹)** | 证据,**不是**主资产 | 不可变的单次执行记录,供结晶与评估反查,不是用户对外的产品 |
+| **Evolution Evaluation (反漂移)** | 反漂移闸门,强制项 | 每次改进都要有独立上下文的评估者 + 反方怀疑者,过了才留,不过就回滚 |
 
-产品遵循四层资产模型与 karpathy × darwin 双层纪律,两者缺一不可:
+- **工程化每条规则 = karpathy 风格 · 验证每次改进 = darwin 风格** —— 两条缺一不可。砍掉 karpathy,原则没人写清;砍掉 darwin,改得对不对没人验。这一对是 co-equal 的双层结构,不是先后两步。
+- `/peaks-code` 是 **code-domain** 长任务 Loop Engineering 编排器,不是通用编排器;非代码域(`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`)都是独立的 `peaks-*` 蜂,不是 `peaks-code` 的子类。
+- 跑两次稳定就沉淀成本地战术(bee);跑翻车的会让你重定义。bee 跟着你的口味长。
 
-- **四层资产模型**:Loop Engineering 资产(方法体系,一等公民)+ Bee 资产(可执行体,一等公民)+ Workflow Trace(执行轨迹,只作证据,不作资产)+ Evolution Evaluation(反漂移闸门,变更必经)。
-- **karpathy × darwin 双层纪律**:karpathy 工程化每一条规则(failure modes + imperative→declarative rewrite + self-check + out-of-scope);darwin 校验每一次改进(单对象 + 单维度 + 独立上下文评估 + ratchet 防回退)。两层是平行的伙伴,谁都不是谁的子集 —— 详见 `.peaks/standards/loop-engineering-guidelines.md` 与上游参考 `multica-ai/andrej-karpathy-skills`、`alchaincyf/darwin-skill`。
-- **post-run crystallization**:`loop_release` 与 `bee_release` 只在一次真实任务跑完后才写入;pre-run 永远是 scratch。沉淀触发支持四种,user explicit 优先级最高。
-- **Human-NL-Choice-Only**:你只说话或选择,LLM 替你跑 CLI;禁止手写 JSON / manifest / form field。
+---
 
-### peaks-code 是 code-domain 唯一的入口
+## 30 秒上手
 
-`peaks-code` 是 loop engineering 在 **代码域** 的长任务编排器,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。它**不是通用编排器** —— 研究 / 内容 / 产品等其他域各自是独立的 `peaks-*` 技能,复用同一份 Loop Engineering 准则。详见 Loop Engineering 设计 `docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 + RL-8,以及 sediment 设计 `docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`。
+```bash
+npm i -g peaks-loop
+```
 
-召之即来,事完收队,**不跳步,不半截扔给你**。它不是新发明一个 AI CLI,而是架在你已有的 Claude Code / Codex / Copilot 之上,把它们都调成同一支团队,只对你这一个开发者的口味。
+装好之后,在你已经用的 **Claude Code** 或 **Z Code** 对话框里发一条**显式命令**(必须以斜杠开头,才会触发 peaks-loop):
 
-### peaks-solo 是分诊员(新增,4.0.0-beta.5)
+```
+/peaks-code 帮我熟悉下当前的项目
+```
 
-如果**你不知道该用哪个 peaks-* 技能**,直接用 `/peaks-solo` 描述你的诉求就行。它会替你分诊:有合适的 leaf 就透明转交,没合适的就自己规划 + 跑(deep-search / WebSearch / Bash / Edit markdown),跑完回头问你要不要沉淀。`/peaks-code` / `/peaks-content` / `/peaks-doctor` 等老入口照常可用,**0 breaking**。
+剩下的就交给 peaks-loop —— 它会按这条命令的语义判断该走哪一域,用对应的编排器拆工序,一道门一道门跑,**坏在哪道停在哪道**,中间不会扔半截给你。
 
-**每一步都有强退出条件**:审计不通过就停,QA 没过就停,任何一道门失败 = 全流程停。你不必追着它催、也不必替它补,它跑完一道再交你拍板,拍完再走下一道。
+其他常用的显式命令:
 
-#### 门禁不是装饰 —— 5439 tests passed · 19 skipped · 0 failed
+```
+/peaks-content                 帮我把今天这篇推文写完发出
+/peaks-doctor                  帮我体检一下这个仓库
+/peaks-issue-fix-orchestrator  帮我把 upstream 的 30 个 open issue 修一批
+/peaks-sop                     帮我把团队的发布流程沉淀成 SOP
+/peaks-solo                    这套打法以后还会用,沉淀成本地战术
+/peaks-solo                    按上次那样再跑一次
+```
 
-每一行代码都过自己的门:测试套件 5,420 个用例真挡得住事,不是装饰。门禁不是写给用户看的,是写给自己看的。
+<sub>📦 其他 AI 编程工具适配中,欢迎共建 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues) 提适配请求 / PR。</sub>
 
-#### 做这个项目的只有一个人,工程师口味:
+不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
 
-- **极客精神。**
-- **你跟 AI 之间只该用自然语言讲话,没有 CLI 表面给你。**
-- **单测覆盖率和门禁审计真挡得住事,不是装饰。**
-- **严于律己,宽以待人 —— 自己写的代码过自己的门,使用者随便怎么说都能跑通。**
-- **AI 使用水平的下限平权:你不需要懂 prompt engineering,就跟说话一样用。**
+---
 
-这套项目级硬规则也写进了 `~/.peaks/memory/`,不是口号,是被工具链守住的红线。
+## 它能为你做什么
 
-## 装了你有什么战术角色
+代码、内容、项目健康、issue 修复、自定义工作流 —— **4.x 已经覆盖五条域**,每条域都有专门编排器,按"门禁不通过就停"的纪律一条一条跑。
 
-先给你上的是 `peaks-code`,主官。它是 peaks-loop 默认入口,管 PRD、RD、QA、UI、SC、TXT 这一长串工序的主调度,也是你日常跟 peaks-loop 说话时最常打交道的那个角色。
+| 域 | 你发这条命令 | 它会做什么 |
+| --- | --- | --- |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 帮我实现这个功能` | PRD → RD → 实现 → QA → UI → 切片,跑完交你拍板 |
+| 💻 **代码域 (code-domain) only** | `/peaks-code 这个 bug 帮我修一下` | 复现 → 改 → review → 测试,同日 ship |
+| 📝 **内容** | `/peaks-content 帮我把这篇推文写出来再发` | 草稿 → 编辑 → 调性检查 → 发布 → 归档,中间不跳步 |
+| 🩺 **项目健康** | `/peaks-doctor 帮我体检一下这个仓库` | 红线审计 + L3 doctor 检查 + 转 OpenSpec,坏在哪道停在哪道 |
+| 🐛 **批量修 issue** | `/peaks-issue-fix-orchestrator 帮我把 upstream 的 30 个 open issue 修一批` | 调研 → 分类 → 参考 PR → 逐个修复 + commit + PR 草稿 |
+| 📋 **自定义工作流** | `/peaks-sop 帮我把团队的发布流程沉淀成 SOP` | 自然语言描述 → 自动生成 + 校验 + 注册成可执行的 SOP |
+| 🔁 **跑过一次再来** | `/peaks-solo 按上次那样再跑一次` | 调出你已经沉淀好的战术,自动复跑 |
+| 🆕 **接手陌生仓库** | `/peaks-code 这是新仓库,先带我过一遍` | 摸清结构、识别风险点、给一个上手顺序 |
+| 🧠 **沉淀自己的打法** | `/peaks-solo 这套打法以后还会用,沉淀一下` | 变成你本地常驻的战术,下次说"跑那只"就行 |
 
-它能做的:
-- 写长任务代码(端到端需求 → PRD → 实现 → QA),一道门一道门跑,坏在哪道停在哪道
-- 修 bug 当天发,改完顺手过审 + 测试,不是改完就完
-- 帮你做 / 接 / 拆长跑的需求,把一个模糊需求一路剥到能落地的实现
+每一条路,**一条斜杠命令**就能开跑。
 
-它一句话能扛完的活,你都不必开第二个终端。它对测试覆盖率、审计门、卡点阻断一视同仁:跑不到位的活不交付,跑歪的活直接退回重跑。
+---
 
-它既是装好就立刻能用的那个入口,也是后面要长出来的内建角色的调度口;它内部有一套连续审计、QA 闸口、review 验收,默认打开,你想关哪一道才需要单独说。
+## 为什么大家会选它
 
-其他内置 loop engineering,敬请期待。
+- **自然语言即界面** —— 你不学 CLI、不背命令。**用一条斜杠命令(比如 `/peaks-code xxx`)** 显式触发到对应编排器,后面说什么都行。LLM 替你跟 peaks-loop 跑命令。
+- **门禁真挡事,不是装饰** —— 5,439 个测试用例、QA 闸口、review 验收默认全开。**审计不通过就停,QA 没过就停**。
+- **跑过的事会变成本地战术(bee)** —— 沉淀下来的 loop engineering 落到你本地的 `~/.peaks/` 池子里,跑两次稳定就自动晋升;跑翻车的会让你重新定义。**下次说"跑那只"整套流程自动就位**,你那几只战术会跟着你的口味长。
+- **搭在你已经用的工具上** —— 不是新发明一个 AI CLI,而是架在 **Claude Code** 和 **Z Code** 之上。不抢你的 shell、不抢你的 prompt、不抢你的 IDE。其他工具适配中,欢迎共建。
+- **你拍板,它执行** —— 影响资产的决策都给你选;其余的它自己跑。**0 学习成本,1 分钟上手。**
 
-## 你也能沉淀自己的 loop engineering
+---
 
-跑过一次还想跑,说一句话让它永久驻场。
+## 装上以后的几道闸门
 
-你沉淀的是 loop engineering(战术套路),不是简单的 skill(动作招式)。下次说"跑那只",整套流程自动就位。
+| 闸门 | 默认状态 | 用来挡什么 |
+| --- | --- | --- |
+| 单元测试 / 集成测试 | ✅ 开 | 代码层面的回归 |
+| 代码审计 (lint / prose / type) | ✅ 开 | 写法与意图漂移 |
+| 安全扫描 | ✅ 开 | 凭据、SSRF、注入、危险 IO |
+| QA 复核 | ✅ 开 | 任务级闸门,坏在哪道停在哪道 |
+| review 验收 | ✅ 开 | 改完不立刻出门,review 通过才出门 |
 
-它落到你本地的一个池子里,只对你生效。命名、复用、迭代都是你说了算:跑过两遍稳定的会被抬高,跑翻车的会让你重新定。决策影响资产的,你拍板。
+**所有闸门默认开,你想关哪一道才需要单独说。**
 
-这套机制关键不是"工具给你造了多少只 bee",而是你那几只 bee 一直在跟着你的口味长 —— 你提一句,它长一点。
+---
 
-## 上号
+## 当前状态 · 4.x 正式版
 
-```bash
-npm i -g peaks-loop
-```
+| | |
+| --- | --- |
+| **最新版本** | [`4.0.0-beta.7`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x 正式版筹备中 |
+| **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测) |
+| **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
+| **测试套件** | 5,439 passed · 19 skipped · 0 failed |
+| **适配 IDE** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder(适配中,欢迎共建) |
+| **依赖运行时** | Node ≥ 20 |
+| **License** | MIT |
 
-装完一句话接活。
+---
 
-## 顺便说一句
+## 强烈推荐 · 四个项目组合起来用
 
-这个仓库以前叫 [`peaks-cli`](https://github.com/SquabbyZ/peaks-cli),现在叫 `peaks-loop`。
+> **0 学习成本。** 这是组合起来用最大的好处 —— 不只是效果俱佳,更是因为这四个项目的**接口对齐到了"自然语言"**,你只需要说一句话,谁替你跑命令、按什么闸门、按什么战术手册,完全不用你记。
 
-里面的技能从 `peaks-code`(单角色)演化到 `peaks-code`(带门禁的代码域).两边都还在,只是分工不同:`peaks-code` 如今是给单任务跑流程用的那个老入口,`peaks-code` 接管了端到端的主路径。
+<p align="center">
+  <a href="https://github.com/affaan-m/ECC">
+    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/Egonex-AI/Understand-Anything">
+    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/obra/superpowers">
+    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
+  </a>
+</p>
 
-事情一直没换过:你说话,它替你排工程门禁,坏哪道停哪道,你来拍板。
+| 角色 | 项目 | 一句话 |
+| --- | --- | --- |
+| **结晶与门禁** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← 你在这里 | loop engineering 结晶系统,装上就有 PRD/RD/QA/UI/SC/TXT 一整条工程链 + 沉淀 |
+| **战术手册** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | everything-claude-code:Claude Code 上能拿到的最好用的战术、技能、SOP 集合 |
+| **代码理解** | [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | 任意仓库,一句话读懂 —— 让 LLM 真正"理解"项目,而不是猜 |
+| **流程与纪律** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review 等流程纪律,每条都自带硬退出条件 |
 
-你只需要把这一个仓库装好,后面每次跑新需求,都有现成的战术角色等你点。
+**用起来就一句话**:把上面三个仓库都 clone 到本地,peaks-loop 装上,剩下的交给 LLM —— 它会按需取用、按纪律守门、按战术落地、按需求沉淀。
+
+### 致敬
+
+peaks-loop 的两条工程脊柱直接来自这两个项目:
+
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — 把"工程化每一条规则"刻进我们的方法层。
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — 把"演化校验每一次改进"刻进我们的反漂移闸门。
+
+---
+
+## FAQ
+
+<details>
+<summary><b>它跟 Claude Code / Z Code 是什么关系?</b></summary>
+
+它是**搭在上面**,不是替换。peaks-loop 不抢你的 shell、不抢你的 prompt、不抢你的 IDE。它在 Claude Code / Z Code 这两个一等公民适配里跑,你照常用。**其他 AI 编程工具适配中,欢迎共建** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)。
+
+</details>
+
+<details>
+<summary><b>我需要记 CLI 命令吗?</b></summary>
+
+不需要。你只用自然语言或选选项,LLM 替你跑命令。**所有 CLI 命令对外隐藏,对 LLM 开放**。
+
+</details>
+
+<details>
+<summary><b>沉淀下来的战术会一直留在本地吗?</b></summary>
+
+会。沉淀落在你本地的池子里,只对你生效。命名、复用、迭代都是你说了算;跑翻车的会让你重新定义。
+
+</details>
+
+<details>
+<summary><b>它会自己改我的代码吗?</b></summary>
+
+改,但过门禁。**审计不通过 = 不出门**,**QA 没过 = 不出门**,**review 不通过 = 不出门**。它替你跑,但每道门都给你审。
+
+</details>
+
+<details>
+<summary><b>跟 3.x 比,4.x 有什么不同?</b></summary>
+
+**最大的不同:从"代码专用"扩成"多域编排系统"。** 4.x 不再只是写代码 —— 新增了 `peaks-content`(内容生产)、`peaks-doctor`(项目健康)、`peaks-issue-fix-orchestrator`(批量修 issue)、`peaks-sop`(自定义 SOP)四条域编排链,加上 `peaks-solo` 分诊员按你说话自动判断该走哪一域。再加 9 个 IDE 适配、结晶系统重命名、post-run crystallization 机制、5,439 tests 通过。完整变更 → [`CHANGELOG.md`](./CHANGELOG.md)。
+
+</details>
 
 ---
 
-MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ)
+## 链接
 
 - 全部技能清单 → [`skills/`](./skills/)
-- 设计文档 → [`docs/`](./docs/)
 - 更新日志 → [`CHANGELOG.md`](./CHANGELOG.md)
 - 提问 → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- 致敬: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
+- 组合推荐: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
+- 沉淀设计 → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
+- Loop Engineering 结晶设计 → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
+
+---
+
+<div align="center">
+
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · 中文版 · [English version](./README-en.md)
+
+</div>

package/bin/peaks.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import '../dist/src/cli/index.js';
+import '../dist/cli/index.js';

package/dist/cli/commands/_cli-error-envelope.d.ts

@@ -0,0 +1,19 @@
+export type EnvelopeMapping = {
+    code: 'INVALID_GOAL';
+    nextActions: readonly string[];
+} | {
+    code: 'INVALID_PROVIDERS';
+    nextActions: readonly string[];
+} | {
+    code: 'INTERNAL_ERROR';
+    nextActions: readonly string[];
+};
+/**
+ * Map a thrown error into an envelope code + nextActions hint. Pure
+ * function — no IO, no state. Safe to call from any CLI handler.
+ *
+ * @param error - any value that may have been thrown (we only inspect
+ *                `.message` for goal-validation; everything else is
+ *                routed by class).
+ */
+export declare function mapServiceError(error: unknown): EnvelopeMapping;

package/dist/cli/commands/_cli-error-envelope.js

@@ -0,0 +1,50 @@
+// Slice 015 — single source of truth for translating a thrown error from
+// the service layer (createRdSwarmPlan, createTechPlan, etc.) into a CLI
+// envelope code + user-facing nextActions.
+//
+// Lives under src/cli/commands/ (private to the CLI surface; underscore
+// prefix marks it as not-an-exported-CLI-subcommand per the project
+// convention). Used by every CLI handler that wraps a service call in a
+// try/catch — currently the four catches in workflow-commands.ts.
+//
+// Pre-slice behavior: all four catches emitted a fixed `INVALID_GOAL`
+// envelope code, regardless of the actual error class. Provider-config
+// failures (`ProviderNotConfiguredError`) were silently re-labelled as
+// "invalid goal", hiding real config issues behind a misleading hint.
+//
+// Post-slice behavior: the helper routes errors into one of three envelope
+// codes based on the runtime error class/message. The CLI catch sites
+// become data-only — they call the helper, then format the envelope.
+import { ProviderNotConfiguredError } from '../../services/config/model-routing.js';
+// Slice 015 risk A: goal-validation uses a substring match on the error
+// message thrown by `validatePlanningInput`. If validatePlanningInput's
+// message wording changes in a future slice, this branch silently
+// degrades into INTERNAL_ERROR. Mitigated by the helper's unit test
+// pinning the literal substring.
+// Slice 015 — match the goal-validation throw message. The current
+// `validatePlanningInput` literal is `"Goal must be non-empty"` (capital
+// G, "non-empty" with hyphen). The regex tolerates common wording
+// variations (`must be non-empty`, `must not be empty`, case-insensitive)
+// so a future message tweak still routes correctly; the unit test below
+// pins the *current* literal substring so any wording change fails loudly.
+const GOAL_VALIDATION_MESSAGE_RE = /goal.{0,4}(must be non-empty|must not be empty)/i;
+/**
+ * Map a thrown error into an envelope code + nextActions hint. Pure
+ * function — no IO, no state. Safe to call from any CLI handler.
+ *
+ * @param error - any value that may have been thrown (we only inspect
+ *                `.message` for goal-validation; everything else is
+ *                routed by class).
+ */
+export function mapServiceError(error) {
+    if (error instanceof ProviderNotConfiguredError) {
+        return {
+            code: 'INVALID_PROVIDERS',
+            nextActions: ['Configure provider model: peaks config provider <id> set --model <id>'],
+        };
+    }
+    if (error instanceof Error && GOAL_VALIDATION_MESSAGE_RE.test(error.message)) {
+        return { code: 'INVALID_GOAL', nextActions: ['Use a non-empty goal'] };
+    }
+    return { code: 'INTERNAL_ERROR', nextActions: ['See errorId for trace'] };
+}

package/dist/{src/cli → cli}/commands/core/skill-command.js

@@ -198,12 +198,15 @@ export function registerSkillCommand(program, io) {
     addJsonOption(skill
         .command('presence:clear')
         .description('Clear the active Peaks skill presence indicator and update project context')
-        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action((options) => {
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')).action(async (options) => {
         const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         const removed = clearSkillPresence(options.project);
-        // Auto-update project context so future sessions have up-to-date history
+        // Auto-update project context so future sessions have up-to-date history.
+        // Slice 2026-07-15-project-scan-bootstrap: generateProjectContext now also
+        // bootstraps `.peaks/project-scan/` (idempotent). Await the async
+        // signature; failure is still non-fatal so we don't block the clear.
         try {
-            generateProjectContext(projectRoot);
+            await generateProjectContext(projectRoot);
         }
         catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
             // non-fatal: context update failure should not block presence clear

package/dist/{src/cli → cli}/commands/project-commands.js

@@ -50,9 +50,9 @@ export function registerProjectCommands(program, io) {
     });
     addJsonOption(project
         .command('context')
-        .description('Generate or read persistent project context for cross-session Peaks understanding')
+        .description('Generate or read persistent project context for cross-session Peaks understanding. Generates BOTH `.peaks/PROJECT.md` (session history) AND `.peaks/project-scan/project-scan.md` (tech stack + archetypes) — see `peaks workspace init` for the full 5-template boot (G4b/AC9).')
         .requiredOption('--project <path>', 'target project root')
-        .option('--read', 'read existing PROJECT.md without regenerating')).action((options) => {
+        .option('--read', 'read existing PROJECT.md without regenerating')).action(async (options) => {
         try {
             if (options.read) {
                 const content = readProjectContext(options.project);
@@ -63,11 +63,16 @@ export function registerProjectCommands(program, io) {
                 printResult(io, ok('project.context', { exists: true, path: `${options.project}/.peaks/PROJECT.md`, content }), options.json);
                 return;
             }
-            const result = generateProjectContext(options.project);
+            const result = await generateProjectContext(options.project);
             printResult(io, ok('project.context', {
                 path: result.path,
                 sessionCount: result.sessionCount,
-                content: result.content
+                content: result.content,
+                // Slice 2026-07-15-project-scan-bootstrap (G1 + G2): the
+                // context command also bootstraps the project-scan tree.
+                // The envelope surfaces write counts + duration so the LLM
+                // (and the user) see what landed.
+                projectScan: result.projectScan
             }), options.json);
         }
         catch (error) {

package/dist/{src/cli → cli}/commands/runtime-commands.js

@@ -93,7 +93,7 @@ async function runCompact(projectRoot, viaId, force, io, asJson) {
         try {
             registry.load(registryFile);
         }
-        catch {
+        catch { // TODO(g2): vendor-neutrality — corrupt adapter registry must NOT block peaks runtime
             // Treat corrupt registry as empty — vendor-neutrality: a corrupt
             // .peaks/runtime/adapters.json must NOT block peaks runtime.
             // We still try the built-in path below.

package/dist/{src/cli → cli}/commands/workflow-commands.js

@@ -15,6 +15,11 @@ import { verifyPipeline } from '../../services/workflow/pipeline-verify-service.
 import { applySkip, detectCallerKind } from '../../services/workflow/workflow-skip-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isRecommendationWorkflow, printResult } from '../cli-helpers.js';
+// Slice 015 — typed error → envelope code routing. Used by the four
+// catch sites below (tech.plan / workflow.route / workflow.autonomous /
+// swarm.plan) so provider-config errors surface as `INVALID_PROVIDERS`
+// instead of being silently re-labelled `INVALID_GOAL`.
+import { mapServiceError } from './_cli-error-envelope.js';
 // Plan 1 / Task 9 — auto-build peaks-context before peaks-rd runs.
 import { buildContext } from '../../services/context/context-builder.js';
 // Plan 1 / Task 10 — production fetcher (replaces mockFetcher).
@@ -125,7 +130,8 @@ function runTechPlan(io, options) {
         printResult(io, ok('tech.plan', plan), options.json);
     }
     catch (error) {
-        printResult(io, fail('tech.plan', 'INVALID_GOAL', getErrorMessage(error), {}, ['Use a non-empty goal']), options.json);
+        const mapping = mapServiceError(error);
+        printResult(io, fail('tech.plan', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
         process.exitCode = 1;
     }
 }
@@ -171,7 +177,8 @@ function runWorkflowRoute(io, options) {
         printResult(io, ok('workflow.route', plan), options.json);
     }
     catch (error) {
-        printResult(io, fail('workflow.route', 'INVALID_GOAL', getErrorMessage(error), {}, ['Use a non-empty goal']), options.json);
+        const mapping = mapServiceError(error);
+        printResult(io, fail('workflow.route', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
         process.exitCode = 1;
     }
 }
@@ -207,7 +214,8 @@ function runAutonomousWorkflow(io, options) {
         printResult(io, ok('workflow.autonomous', plan), options.json);
     }
     catch (error) {
-        printResult(io, fail('workflow.autonomous', 'INVALID_GOAL', getErrorMessage(error), {}, ['Use a non-empty goal']), options.json);
+        const mapping = mapServiceError(error);
+        printResult(io, fail('workflow.autonomous', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
         process.exitCode = 1;
     }
 }
@@ -252,7 +260,8 @@ async function runSwarmPlan(io, options) {
         printResult(io, ok('swarm.plan', plan), options.json);
     }
     catch (error) {
-        printResult(io, fail('swarm.plan', 'INVALID_GOAL', getErrorMessage(error), {}, ['Use a non-empty goal']), options.json);
+        const mapping = mapServiceError(error);
+        printResult(io, fail('swarm.plan', mapping.code, getErrorMessage(error), {}, [...mapping.nextActions]), options.json);
         process.exitCode = 1;
     }
 }

package/dist/{src/cli → cli}/commands/workspace/init-command.d.ts

@@ -56,6 +56,24 @@ export type WorkspaceInitOptions = {
      * `executeProjectStandardsInit({ projectRoot, apply: true })`.
      */
     initStandards?: boolean;
+    /**
+     * Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC9 / AC10):
+     * commander-style `--no-project-scan-bootstrap` opt-out. Default
+     * (no flag) leaves this `undefined` (treated as `true`). Pass the
+     * flag to set `options.projectScanBootstrap === false`, which the
+     * caller reads as `=== false` to skip the bootstrap call.
+     */
+    projectScanBootstrap?: boolean;
+    /**
+     * Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC10):
+     * `--force-project-scan-templates` flag. Default (no flag)
+     * leaves this `undefined`. Pass the flag to set
+     * `options.forceProjectScanTemplates === true`, which forces the
+     * bootstrap service to overwrite the 4 bundled audit/business
+     * templates even when they already exist (sediment is preserved
+     * otherwise).
+     */
+    forceProjectScanTemplates?: boolean;
 };
 /**
  * Outcome of the first-time "install peaks hooks" decision attached to

package/dist/{src/cli → cli}/commands/workspace/init-command.js

@@ -28,6 +28,7 @@ import { clearStalePresenceOnRotation } from '../../../services/skills/skill-pre
 import { fail, ok } from '../../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
 import { hasStandardsCheckedMarker, markStandardsChecked } from '../../../services/standards/missing-standards-detector.js';
+import { bootstrapProjectScan } from '../../../services/prd/project-scan-bootstrap-service.js';
 import { readDecisionMarker, writeDecisionMarker, promptYesNo } from './helpers.js';
 export function registerWorkspaceInitCommand(workspace, io) {
     addJsonOption(workspace
@@ -44,7 +45,9 @@ export function registerWorkspaceInitCommand(workspace, io) {
         return value;
     })
         .option('--no-claude-hooks', 'do NOT materialize .claude/settings.local.json (slice 2.0.1-bug3 fact-forcing bypass). Default: hooks installed so tool calls inside .peaks/** are not blocked by the [Fact-Forcing Gate].')
-        .option('--init-standards', 'slice 2026-06-16-peaks-code-auto-scaffold: when the consumer project\'s .claude/rules/ is missing or empty, auto-apply `peaks standards init --project <path> --apply` after emitting the diagnostic. Default: diagnostic only (no write).')).action(async (options) => {
+        .option('--init-standards', 'slice 2026-06-16-peaks-code-auto-scaffold: when the consumer project\'s .claude/rules/ is missing or empty, auto-apply `peaks standards init --project <path> --apply` after emitting the diagnostic. Default: diagnostic only (no write).')
+        .option('--no-project-scan-bootstrap', 'slice 2026-07-15-project-scan-bootstrap: skip the bootstrap of .peaks/project-scan/{project-scan.md + 4 audit/business templates} that runs after init succeeds. Default: bootstrap runs (idempotent: existing files are kept unless --force-project-scan-templates is also passed).')
+        .option('--force-project-scan-templates', 'slice 2026-07-15-project-scan-bootstrap (AC10): overwrite the 4 audit/business templates under .peaks/project-scan/ (business-knowledge.md, security-template.md, perf-template.md, audit-output-schema.md) even when they already exist. Default: skip existing files (sediment-preserved).', false)).action(async (options) => {
         try {
             // Resolve the session id. Two paths:
             //   - explicit --session-id: use it as the requested binding target
@@ -116,6 +119,44 @@ export function registerWorkspaceInitCommand(workspace, io) {
                 // also run `executeProjectStandardsInit({ apply: true })`.
                 initStandards: options.initStandards === true
             });
+            // Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC9):
+            // After the workspace dir is initialized, also bootstrap the
+            // `.peaks/project-scan/` artifact tree (project-scan.md + 4
+            // bundled audit/business templates). Idempotent — when the user
+            // re-runs `workspace init`, the existing files are kept (their
+            // sediment is user-authored). Pass `--no-project-scan-bootstrap`
+            // to skip, or `--force-project-scan-templates` to overwrite the
+            // 4 bundled templates anyway.
+            let projectScanEnvelope = null;
+            let projectScanError = null;
+            if (options.projectScanBootstrap === false) {
+                // Explicit opt-out. The envelope stays null; the JSON
+                // response carries `projectScan: { skipped: true, ... }` so
+                // callers can distinguish "skipped by flag" from "skipped by
+                // idempotency".
+                projectScanEnvelope = {
+                    created: false,
+                    skipped: true,
+                    templatesBooted: 0,
+                    templatesSkipped: 0,
+                    projectScanPath: `${projectRoot}/.peaks/project-scan/project-scan.md`,
+                    durationMs: 0
+                };
+            }
+            else {
+                try {
+                    projectScanEnvelope = await bootstrapProjectScan({
+                        projectRoot,
+                        ...(options.forceProjectScanTemplates === true ? { forceTemplates: true } : {})
+                    });
+                }
+                catch (error) {
+                    // Don't fail init over a project-scan issue — the workspace
+                    // is already initialized and the user has the JSON envelope.
+                    // Surface the failure as a warning so the LLM can decide.
+                    projectScanError = getErrorMessage(error);
+                }
+            }
             const nextActions = [];
             if (report.previousSessionId !== null && report.bound) {
                 nextActions.push(`Replaced prior session binding "${report.previousSessionId}" with "${report.sessionId}".`);
@@ -208,6 +249,13 @@ export function registerWorkspaceInitCommand(workspace, io) {
                 nextActions.push(`Wrote .peaks/.claude-settings-template.json (action: written) — ` +
                     'the offline recovery anchor is now in place for future manual recoveries.');
             }
+            // Slice 2026-07-15-project-scan-bootstrap (G2): surface the
+            // bootstrap outcome. The envelope carries the write counts and
+            // duration so the LLM (and the human) see what landed. The
+            // nextAction only fires when the project-scan tree is fresh —
+            // idempotent re-runs are silent to keep the nextAction list
+            // scannable.
+            // (deferred until after warningsForEnvelope is declared below)
             // First-time hooks install decision. Sticky-marker at
             // .peaks/.peaks-init-hooks-decision.json records the user's answer
             // (or the auto-decision) so subsequent inits for new sessions in the
@@ -250,6 +298,20 @@ export function registerWorkspaceInitCommand(workspace, io) {
                     `wrote ${report.standardsApplied.writtenFiles.length} file(s), ` +
                     `kept ${report.standardsApplied.skippedFiles.length} existing file(s).`);
             }
+            // Slice 2026-07-15-project-scan-bootstrap (G2): surface the
+            // bootstrap outcome. The envelope carries the write counts and
+            // duration so the LLM (and the human) see what landed. The
+            // nextAction only fires when the project-scan tree is fresh —
+            // idempotent re-runs are silent to keep the nextAction list
+            // scannable.
+            if (projectScanError !== null) {
+                warningsForEnvelope.push(`project-scan bootstrap failed: ${projectScanError}`);
+            }
+            else if (projectScanEnvelope !== null && projectScanEnvelope.created) {
+                nextActions.push(`Bootstrapped .peaks/project-scan/ (project-scan.md + 4 audit/business templates) — ` +
+                    `${projectScanEnvelope.templatesBooted} file(s) written, ${projectScanEnvelope.templatesSkipped} preserved. ` +
+                    `Run \`peaks scan archetype --project ${projectRoot}\` and \`peaks scan libraries --project ${projectRoot}\` next to refresh the scan.`);
+            }
             // Write the once-per-session marker AFTER the envelope is built
             // (so subsequent inits skip the warning even on rapid back-to-back
             // calls).
@@ -269,7 +331,14 @@ export function registerWorkspaceInitCommand(workspace, io) {
                     action: hooksOutcome.action,
                     scope: hooksOutcome.scope,
                     ...(hooksOutcome.reason !== undefined ? { reason: hooksOutcome.reason } : {})
-                }
+                },
+                // Slice 2026-07-15-project-scan-bootstrap (G2): envelope
+                // for the .peaks/project-scan/ bootstrap. Always present
+                // (even when skipped / errored) so downstream readers can
+                // rely on the shape.
+                ...(projectScanEnvelope !== null
+                    ? { projectScan: { ...projectScanEnvelope, ...(projectScanError !== null ? { error: projectScanError } : {}) } }
+                    : {})
             }, warningsForEnvelope, nextActions), options.json);
         }
         catch (error) {