@namewta/speculo 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

package/speculo/skills/worktree-isolation/SKILL.md

@@ -0,0 +1,59 @@
+---
+id: worktree-isolation
+type: skill
+name: Worktree Isolation
+description: 在独立 git worktree 中隔离推进一个 change 的原子能力；当 dev workflow 需要为某个 change 建立隔离分支与 .worktree/ 工作树、审查整条 change 分支树的全部 commit、或在收尾时把分支合并回原分支并清理时使用。默认不启用，仅在用户显式请求隔离时由调用方读取。
+---
+
+# Worktree Isolation
+
+## 何时使用
+
+当 dev workflow 需要把一个 change 与原分支**物理隔离**地推进时使用。三个典型触发：
+
+- **建立隔离环境**（grill / change 创建）：为当前 change 新建独立分支与 `.worktree/<change>/` 工作树，代码与所有 Speculo 产物都落在 change 分支上，不污染原分支。
+- **审查整条分支树**（review）：审查必须覆盖 change 分支相对原分支的**全部 commit**，而不只是工作区 diff。
+- **合并回收**（finalize）：收尾验证通过后，把 change 分支合并回原分支，并清理 worktree 与分支。
+
+**默认不启用。** 只有用户**显式请求**隔离（“用 worktree / 隔离这个 change”）时，调用方才读取并执行本 skill；未请求时调用方完全不加载本 skill，既有流程零行为变化。
+
+## 输入
+
+- 当前 git 仓库与**当前分支**（启用隔离时即记为 base 分支）
+- 当前 change 目录名（`YYYY-MM-DD-<kebab>`）与其分类 `<cat>`（dev | doc | ops）
+- 用户的隔离意图（是否显式请求）
+- 仓库 `.gitignore`
+
+本 skill 自带全部隔离程序，**不外读仓库 `docs/`**。
+
+## 输出
+
+- git 状态变更：隔离分支、`.worktree/<change>/` 工作树、合并与清理结果
+- **供调用方持久化的状态字段集**（本 skill 不写 `.speculo/`，由调用方 workflow 写入同一 change 的 `.status.json`）：
+
+  | 字段 | 类型 | 含义 |
+  |------|------|------|
+  | `worktree_enabled` | bool | 是否启用隔离 |
+  | `base_branch` | string | 原分支（启用隔离时的当前分支） |
+  | `change_branch` | string | 隔离分支，固定 `speculo/<cat>/<change>` |
+  | `worktree_path` | string | 工作树路径，固定 `.worktree/<change>` |
+  | `worktree_status` | string | created \| active \| merged \| removed |
+
+- 可归档摘要：base / change 分支、worktree 路径、合并与清理结论、残留风险
+
+## 执行步骤
+
+1. **判定可隔离性**：确认 (a) 在 git 仓库内，(b) 工作区干净或变更可接受，(c) 目标项目 `.speculo/` 被 git 跟踪（产物需随分支合并）。任一不满足 → **不创建**，向调用方报告原因并降级为非 worktree 模式。
+2. **命名**：base = 当前分支；`change_branch = speculo/<cat>/<change>`；`worktree_path = .worktree/<change>`。
+3. **创建**：见 `references/create-worktree.md`。完成后返回 `base_branch / change_branch / worktree_path` 与 `worktree_status: active` 供调用方写入。
+4. **隔离推进**：此后该 change 的全部工作（代码 + `.speculo/<cat>/<change>/` 产物）都在 `worktree_path` 内、`change_branch` 上进行。
+5. **审查全树**（review 时）：见 `references/audit-branch-tree.md`，覆盖 `base..change_branch` 的每个 commit。
+6. **合并回收**（finalize 时）：见 `references/merge-and-cleanup.md`，合并回 base、删分支、删 worktree。
+
+**破坏性步骤**（合并、删分支、删 worktree）必须先列计划、经用户确认再执行；合并冲突即停、不强推。
+
+## 渐进披露
+
+- `references/create-worktree.md`：建立隔离分支与 `.worktree/` 工作树时读取（grill / change 创建）。
+- `references/audit-branch-tree.md`：审查 change 分支树相对 base 的全部 commit 时读取（review）。
+- `references/merge-and-cleanup.md`：把 change 分支合并回原分支并清理时读取（finalize）。

package/speculo/skills/worktree-isolation/references/audit-branch-tree.md

@@ -0,0 +1,32 @@
+# 审查 change 分支树
+
+worktree 模式下，review 必须覆盖 change 分支相对 base 的**全部 commit**，而不只是工作区 diff。调用方：`dev/R` review 的 setup 阶段。
+
+## 输入
+
+- change 的 `.status.json`：`base_branch`、`change_branch`、`worktree_status`
+- 当前 git 仓库
+
+## 步骤
+
+1. 读取 `base_branch` 与 `change_branch`。worktree 模式下 fixed point 默认取 `base_branch`，无需另问用户（用户另行指定时以用户为准）。
+2. 列出分支树全部 commit：
+
+   ```bash
+   git log <base_branch>..<change_branch> --oneline
+   ```
+
+3. 取全量 diff 作为审查范围：
+
+   ```bash
+   git diff <base_branch>...<change_branch>
+   ```
+
+4. 按 commit 数与 diff 规模定分批策略；**每个 commit 都要纳入审查范围**，不得只看最新工作区状态。
+5. 把 fixed point（= `base_branch`）、diff 命令、commit 列表交给调用方写入 `review_fixed_point`、`review_diff_command` 等字段。
+
+## 边界
+
+- 不替换用户显式指定的 fixed point。
+- 不遗漏任何 commit；clean-review 声明须确认已覆盖 `base..change_branch` 全部 commit。
+- 不写 `.speculo/` 或 `.status.json`。

package/speculo/skills/worktree-isolation/references/create-worktree.md

@@ -0,0 +1,39 @@
+# 创建隔离 worktree
+
+为当前 change 建立独立分支与 `.worktree/<change>/` 工作树。调用方：`dev/01` grill 的 Worktree Setup 阶段（条件）。
+
+## 前置
+
+1. 在 git 仓库内，工作区干净或变更可接受。
+2. 目标项目 `.speculo/` 被 git 跟踪——隔离模型要求 change 产物随分支合并回 base。若 `.speculo/` 被 `.gitignore` 忽略，**不隔离**，报告原因并降级。
+3. 确保 `.gitignore` 含 `.worktree/`；缺失则提示调用方补上（worktree 工作树不应被 base 分支跟踪）。
+
+## 命名
+
+- base 分支 = 启用隔离时的当前分支（`git rev-parse --abbrev-ref HEAD`）
+- change 分支 = `speculo/<cat>/<change>`
+- worktree 路径 = `.worktree/<change>`
+
+## 步骤
+
+1. 记录 base 分支名。
+2. 确认 change 分支与 worktree 路径均不存在；已存在则停止并报告冲突，不覆盖、不复用。
+3. 创建分支与工作树：
+
+   ```bash
+   git worktree add -b speculo/<cat>/<change> .worktree/<change>
+   ```
+
+4. 在工作树内初始化该 change 的 Speculo 产物目录 `.speculo/<cat>/<change>/` 与 `.status.json`（由调用方按持久化契约写入）。
+5. 提示调用方：此后所有工作在 `.worktree/<change>/` 内、`speculo/<cat>/<change>` 分支上进行。
+
+## 返回给调用方
+
+- `base_branch`、`change_branch`、`worktree_path`
+- `worktree_status: active`
+
+## 边界
+
+- 不写 `.speculo/` 或 `.status.json`；字段值返回给调用方 workflow 写入。
+- 分支或工作树已存在时不覆盖、不复用，停止报告。
+- 非 git 仓库 / 工作区不可用 / `.speculo/` 未被跟踪时降级为非 worktree 模式。

package/speculo/skills/worktree-isolation/references/merge-and-cleanup.md

@@ -0,0 +1,43 @@
+# 合并回收与清理
+
+finalize 验证通过后，把 change 分支合并回原分支并清理 worktree。调用方：`dev/04` finalize 的 Merge Back & Cleanup 阶段（条件）。**全程破坏性，须先列计划、经用户确认。**
+
+## 前置
+
+- `verification_status: verified`（未通过不得合并）
+- change 的最终产物（`completion-verification.md`、`completion-summary.md` 等）已在 `change_branch` 上提交
+- 读取 `base_branch`、`change_branch`、`worktree_path`
+
+## 步骤
+
+1. **列计划并确认**：展示将要合并的分支、目标 base、待删除的分支与工作树，等待用户明确确认。未确认只输出计划，不动手。
+2. **合并回 base**：
+
+   ```bash
+   git switch <base_branch>
+   git merge --no-ff speculo/<cat>/<change>
+   ```
+
+   - 合并冲突 → **停止**，报告冲突文件，交回用户解决，不强推、不 `--force`。
+   - 合并成功 → 置 `worktree_status: merged`。合并后 base 分支已包含代码与 `.speculo/<cat>/<change>/` 产物。
+3. **清理工作树与分支**：
+
+   ```bash
+   git worktree remove .worktree/<change>
+   git branch -d speculo/<cat>/<change>
+   ```
+
+   - 完成后置 `worktree_status: removed`。
+4. **移交归档**：清理后归档在 base 分支进行（change 目录已随合并到达 base），由调用方 finalize 的归档阶段执行。
+
+## 失败处理
+
+- 合并失败：保留 worktree 与分支，报告冲突，不清理。
+- `git worktree remove` 失败（工作树有未提交改动）：报告并停止，不 `--force`，除非用户明确要求。
+- 不回滚已成功的合并，除非用户明确要求。
+
+## 边界
+
+- `verification_status` 非 `verified` 不合并。
+- 未获用户确认不执行任何合并 / 删除 / 移除。
+- 不写 `.speculo/` 或 `.status.json`；`worktree_status` 由调用方写入。

package/speculo/workflows/dev/00-INDEX.md

@@ -17,9 +17,10 @@ keywords: [dev, 开发, workflow, index, 状态]
 | `dev/01` | `01-grill-with-docs/01-grill-with-docs.md` | 领域术语、CONTEXT、ADR 与方案拷问 |
 | `dev/02` | `02-prd/02-prd.md` | zoom-out 全景理解与 PRD 综合 |
 | `dev/03` | `03-tdd/03-tdd.md` | 垂直切片 TDD 实现 |
+| `dev/04` | `04-finalize/04-finalize.md` | 完成前验证、状态收尾与归档 |
 | `dev/I` | `I-to-issues/I-to-issues.md` | 垂直切片 issue 分解，可嵌入其他 dev workflow |
 | `dev/H` | `H-diagnose/H-diagnose.md` | hotfix / bug / 性能回退诊断 |
-| `dev/R` | `R-review/R-review.md` | Standards / Spec 双维度 diff 审查 |
+| `dev/R` | `R-review/R-review.md` | Spec / Engineering / Standards 三维度 diff 审查 |
 | `dev/D` | `D-docs-sync/D-docs-sync.md` | 基于 git diff 同步 README、CHANGELOG、AGENTS 等对外文档 |
 
 ## 进入协议
@@ -29,14 +30,16 @@ keywords: [dev, 开发, workflow, index, 状态]
 3. 若没有 active change，按用户意图创建新的 change 目录，并初始化 `.status.json` 与 `../../.speculo/dev-status.json`。
 4. 推荐入口时优先使用用户显式别名；没有别名时按执行模式推荐。
 5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件、模板和被调用 skill wrapper。
+6. **Worktree 隔离（可选，默认 off）**：仅当用户**显式请求**隔离时，新 change 在 `dev/01` 的 Phase 0 经 `../../skills/worktree-isolation/SKILL.md` 建立隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树，并把 `base_branch`、`change_branch` 记入 `.status.json`。扫描 active changes 时，对 `worktree_enabled` 为真者可结合 `git worktree list` 核对工作树是否存在。
 
 ## 执行模式
 
-- `full`：`dev/01` -> `dev/02` -> `dev/I` -> `dev/03`。
+- `full`：`dev/01` -> `dev/02` -> `dev/I` -> `dev/03` -> `dev/04`。
 - `planning-only`：`dev/01` -> `dev/02` -> `dev/I`，不进入实现。
 - `implementation-only`：已有 PRD、issue 或明确任务时，从 `dev/03` 开始。
 - `hotfix`：Bug、异常、性能回退时，从 `dev/H` 开始；修复阶段可嵌入 `dev/03` 的 TDD 回归循环。
 - `review`：已有 fixed point 或用户要求审查时，从 `dev/R` 开始。
+- `finalize`：实现完成、需要完成前验证与状态收尾归档时，从 `dev/04` 开始。
 - `docs-sync`：需要基于 git 差异刷新对外文档时，从 `dev/D` 开始。
 
 ## 状态汇报
@@ -46,6 +49,7 @@ keywords: [dev, 开发, workflow, index, 状态]
 - active change 数量与每个 change 的 `current_phase`
 - 最近更新的 change，按 `updated_at` 倒序
 - `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
+- worktree 模式 change 额外汇报 `base_branch` / `change_branch` / `worktree_status`
 - 推荐下一步入口和原因
 
 ## 完成与状态更新

package/speculo/workflows/dev/01-grill-with-docs/01-grill-with-docs.md

@@ -38,8 +38,25 @@ keywords: [grill, context, adr, 术语, 决策]
 
 需要格式约定时读取同目录 `CONTEXT-FORMAT.md` 或 `ADR-FORMAT.md`。项目 CONTEXT 或 ADR 的创建、修改必须写入 `.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
 
+### Worktree 隔离（条件）
+
+**默认不启用。** 仅当用户**显式请求**把本 change 隔离推进（“用 worktree / 隔离这个 change / 不污染当前分支”）时，才进入下方 Phase 0，并读取 `../../../skills/worktree-isolation/SKILL.md` 的「创建」渐进披露执行隔离。
+
+- 用户未请求隔离时，**不读取**该 skill，跳过 Phase 0，按既有流程在当前分支推进，行为零变化。
+- 启用后，本 change 的代码与全部 Speculo 产物都落在隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树内，原分支不被污染；状态里记录 `base_branch` 与 `change_branch`，供 review、finalize 跨阶段跟进。
+- 隔离前置不满足（非 git 仓库 / 工作区不净 / `.speculo/` 未被 git 跟踪）时由该 skill 降级为非 worktree 模式并报告，不强行创建。
+
 ## 阶段
 
+### 0. Worktree Setup — 隔离环境建立（条件，仅 worktree 模式）
+- 规范：`../../../skills/worktree-isolation/SKILL.md`（读其 `references/create-worktree.md`）
+- 模板：无
+- 产物：隔离分支 `speculo/dev/<change>`、`.worktree/<change>/` 工作树，以及 `.status.json` 的 worktree 字段
+- 完成准则：
+  - 用户未请求隔离时本 phase 标记 `skipped`，不读取该 skill
+  - 启用时分支与工作树已创建，且后续工作均切入 `.worktree/<change>/`
+  - `.status.json` 写入 `worktree_enabled`、`base_branch`、`change_branch`、`worktree_path`，`worktree_status: active`
+
 ### 1. Context Scan — 上下文扫描
 - 规范：`grill-context-scan.md`
 - 模板：`../_templates/grill-context-map-template.md`
@@ -72,8 +89,17 @@ keywords: [grill, context, adr, 术语, 决策]
 - `decision_status` (open | resolved | blocked) — 决策澄清状态
 - `adr_candidates` (array) — ADR 候选清单
 
+仅当用户请求 worktree 隔离（Phase 0）时追加，字段定义见 `../../../skills/worktree-isolation/SKILL.md` 的输出契约：
+
+- `worktree_enabled` (bool) — 是否启用隔离
+- `base_branch` (string) — 原分支
+- `change_branch` (string) — 隔离分支 `speculo/dev/<change>`
+- `worktree_path` (string) — `.worktree/<change>`
+- `worktree_status` (created | active | merged | removed) — 隔离生命周期状态，本 workflow 写到 `active`
+
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - phase 完成后更新 `updated_at`、产物路径和扩展字段。
+- 启用 worktree 隔离时，Phase 0 完成后写入 worktree 字段并置 `worktree_status: active`；未启用时 Phase 0 记 `skipped`，不写 worktree 字段。
 - 本 workflow 完成后不自动完成 change；默认移交 `../02-prd/02-prd.md` 或按用户要求停止。

package/speculo/workflows/dev/04-finalize/04-finalize.md

@@ -0,0 +1,133 @@
+---
+id: dev/finalize
+category: dev
+name: Finalize & Archive
+description: 在用证据证明 change 真正完成后，改变其状态并归档；没有新鲜验证证据不许宣称完成
+keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
+---
+
+# Finalize & Archive 工作流执行指引
+
+本工作流是 `dev/04` 入口，是开发主线的收尾环节（`dev/01` → `dev/02` → `dev/I` → `dev/03` → `dev/04`）。它在 change 的实现完成后，**先用证据证明"真的完成了"，再改变状态并归档**。
+
+## 内置指引
+
+### 核心原则
+
+> 在没有验证的情况下宣称工作完成，这不是高效，而是不诚实。**始终用证据支撑结论。**
+
+### 铁律
+
+```
+没有新鲜的验证证据，不许宣称完成
+```
+
+如果你在本次推进中没有运行验证命令，就不能声称测试通过、构建成功或需求满足。对这条规则敷衍了事，就等于违背了它的精神。
+
+### 门控函数
+
+在把 change 标记为 completed 之前，对每个结论执行：
+
+```
+1. 确定：什么命令能证明这个结论？
+2. 运行：执行完整命令（重新运行，完整执行）
+3. 阅读：完整输出，检查退出码，统计失败数
+4. 验证：输出是否支持这个结论？
+   - 否 → 用证据说明实际状态，置 blocked
+   - 是 → 带证据陈述结论
+5. 只有这时：才能做出结论
+跳过任何一步 = 说谎，不是验证
+```
+
+### 常见失败模式
+
+| 结论 | 需要 | 不够格 |
+|------|------|--------|
+| 测试通过 | 测试命令输出：0 failures | 之前的运行、"应该会通过" |
+| Linter 无报错 | Linter 输出：0 errors | 部分检查、推断 |
+| 构建成功 | 构建命令：exit 0 | linter 通过、日志看起来没问题 |
+| Bug 已修复 | 测试原始症状：通过 | 代码改了，假设已修复 |
+| 回归有效 | 红-绿循环已验证 | 测试只通过了一次 |
+| 代理已完成 | VCS diff 显示变更 | 代理报告"成功" |
+| 需求已满足 | 逐项核对清单 | 测试通过 |
+
+### 红线 —— 停下来
+
+出现以下任一情况，**不得进入归档**，回到验证：
+
+- 使用"应该""大概""似乎"
+- 验证前就表达满意（"太好了""完美""搞定"）
+- 即将归档却没有新鲜验证
+- 信任代理的成功报告而未独立核对 VCS diff
+- 依赖部分验证或上一轮的旧结果
+
+### 何时使用
+
+当一个 change 的实现（`dev/03` 或 hotfix 修复）已结束，用户要把它**收尾、标记完成并归档**时使用。也可在 `dev/R` 审查通过后衔接进入。
+
+### 与 `archive` 命令的关系
+
+- 本工作流（`dev/04`）面向**单个当前 change** 的引导式收尾：先验证、改状态、再归档。
+- `../../../commands/archive.md` 面向**批量**归档多个已 `completed` 的 change。两者共用同一套破坏性归档安全契约（先列清单、用户确认、不覆盖）。
+
+## 阶段
+
+### 1. Completion Verification — 完成前验证（门控）
+- 规范：`completion-gate.md`
+- 模板：`../_templates/completion-verification-template.md`
+- 产物：`completion-verification.md`
+- 完成准则：
+  - 每条完成结论都有**本次运行**的命令与输出证据
+  - 已对照来源（PRD / issue / slices / 用户任务）逐项核对需求清单
+  - 无调试残留与推测性功能
+  - `completion-verification.md` 无残留 `[TODO:]`
+  - `.status.json` 的 `verification_status` 为 `verified` 或 `blocked`
+
+### 2. Merge Back & Cleanup — 合并回原分支与清理（条件，仅 worktree 模式）
+- 规范：`../../../skills/worktree-isolation/SKILL.md`（读其 `references/merge-and-cleanup.md`）
+- 模板：无
+- 产物：合并后的 base 分支、移除的 `.worktree/<change>/` 工作树与隔离分支
+- 完成准则：
+  - 非 worktree 模式本 phase 标记 `skipped`，不读取该 skill
+  - `verification_status: verified` 且用户确认后才执行（破坏性）
+  - change 分支已合并回 `base_branch`（冲突即停、不强推），置 `worktree_status: merged`
+  - `.worktree/<change>/` 工作树与隔离分支已清理，置 `worktree_status: removed`
+
+### 3. Finalize & Archive — 状态收尾与归档
+- 规范：`finalize-archive.md`
+- 模板：`../_templates/completion-summary-template.md`
+- 产物：`completion-summary.md`，以及归档动作
+- 完成准则：
+  - `verification_status` 为 `verified`（`blocked` 时不得归档）
+  - worktree 模式下，归档在 `base_branch` 上进行（change 目录已随 Phase 2 合并到达 base）
+  - `change_status` 先置 `completed`，再随归档置 `archived`
+  - change 目录已移动到 `.speculo/archive/dev/<YYYY-MM>/<change>/`
+  - 已从 `.speculo/dev-status.json` 的 `active[]` 移除该 change
+  - `completion-summary.md` 无残留 `[TODO:]`
+
+## 依赖
+
+- 软依赖：`../03-tdd/03-tdd.md` 或 `../R-review/R-review.md`，scope: same-change
+- 硬依赖：无；但归档要求当前 change 通过完成前验证
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/04`
+- `verification_commands` (array) — 本次运行的验证命令及结果摘要
+- `requirements_checklist` (array) — 逐项需求核对结果，每项含来源引用与 satisfied | missing | partial
+- `verification_status` (verified | blocked) — 完成前验证结论
+- `archived` (boolean) — 是否已完成归档
+- `archive_path` (string|null) — 归档目标路径
+- `worktree_status` (created | active | merged | removed) — 仅 worktree 模式；本工作流在 Phase 2 推进到 `merged` → `removed`（字段定义见 `../../../skills/worktree-isolation/SKILL.md`）
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- 完成验证后写入 `verification_commands`、`requirements_checklist`、`verification_status`。
+- 验证为 `blocked` 时停在本工作流，回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复，不归档。
+- 验证为 `verified` 且用户确认后：
+  - **worktree 模式**：先执行 Phase 2，自动把 change 分支合并回 `base_branch` 并清理工作树与隔离分支（`worktree_status: merged` → `removed`，冲突即停），再在 base 分支上归档；非 worktree 模式跳过 Phase 2。
+  - 置 `change_status: completed` → 执行归档 → 置 `change_status: archived`、`archived: true`、写 `archive_path`，并从 `.speculo/dev-status.json` 移除。
+- 如有可沉淀经验，在用户或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。

package/speculo/workflows/dev/04-finalize/completion-gate.md

@@ -0,0 +1,40 @@
+# Completion Verification Phase（门控）
+
+本阶段是归档前的门控。**没有本次运行的验证证据，不许进入下一阶段。**
+
+## 输入
+
+- 当前 change 目录：`.speculo/dev/<change>/` 下的实现产物（`implementation-log.md`、`verification.md` 等）
+- 来源：PRD、issue、slices、诊断结论或用户明确任务
+- 项目的测试 / 类型检查 / lint / 构建命令
+- 变更 diff（VCS）
+
+## 产物
+
+- `.speculo/dev/<change>/completion-verification.md`，由 `../_templates/completion-verification-template.md` 填写
+
+## 填写引导
+
+按 `04-finalize.md` 的门控函数，对每个完成结论"确定命令 → 运行 → 读输出 → 验证 → 才下结论"。
+
+1. **运行验证命令**：跑与变更相关的测试、类型检查、lint、构建。逐条记录**命令、退出码、通过/失败计数**。无法运行的命令记录原因，对应结论不得声称通过。
+2. **逐项核对需求**：重读来源（PRD / issue / slices / 用户任务），建立需求清单，逐项标 `satisfied | missing | partial` 并引用来源；测试通过不能替代需求核对。
+3. **回归证据**（若本 change 修了 bug）：确认回归测试经过红-绿验证（写 → 通过 → 回退修复必须失败 → 恢复 → 通过），而不是只通过一次。
+4. **代理产物核对**（若部分工作委派给子代理）：检查 VCS diff 验证实际变更，不信任代理的"成功"报告。
+5. **调试残留检查**：搜索临时日志、DEBUG 标记、一次性脚本、推测性 / 未启用功能并清理。
+6. **下结论**：全部结论均有新鲜证据支撑 → `verification_status: verified`；任一关键项缺证据或失败 → `verification_status: blocked`，并写明实际状态与缺口。
+
+## 边界
+
+- 不夸大、不用"应该""大概""似乎"等措辞；信心 ≠ 证据。
+- 不依赖上一轮的旧结果或部分检查。
+- `blocked` 时不进入归档；回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复后重跑本阶段。
+- 不修改 `.speculo/.config/RULES.md` 或用户未授权的项目规则文档。
+
+## 完成准则
+
+- `completion-verification.md` 记录了每条结论的命令与输出证据
+- 需求清单逐项核对完成，含来源引用
+- 调试残留已清理或明确说明
+- `completion-verification.md` 无残留 `[TODO:]`
+- `.status.json` 写入 `verification_commands`、`requirements_checklist`、`verification_status`

package/speculo/workflows/dev/04-finalize/finalize-archive.md

@@ -0,0 +1,55 @@
+# Finalize & Archive Phase
+
+本阶段把通过验证的 change 收尾并归档。**归档是破坏性目录移动，必须先列清单、经用户确认才执行。**
+
+## 输入
+
+- `.speculo/dev/<change>/completion-verification.md`，且 `verification_status: verified`
+- 当前 change 的 `.status.json`
+- 顶层索引 `.speculo/dev-status.json`
+
+## 产物
+
+- `.speculo/dev/<change>/completion-summary.md`，由 `../_templates/completion-summary-template.md` 填写
+- 归档动作：change 目录移动到 `.speculo/archive/dev/<YYYY-MM>/<change>/`
+
+## 填写引导
+
+### 前置门控
+
+1. 确认 `verification_status: verified`。若为 `blocked`，**停止**，不收尾、不归档，回到验证或修复。
+   - **Worktree 模式**：本阶段前应已完成 `04-finalize.md` 的 Phase 2 Merge Back & Cleanup（`worktree_status: removed`），change 目录已随合并到达 `base_branch`，归档在 base 分支上对该目录执行。若 `worktree_status` 仍非 `removed`，先回 Phase 2 合并清理，再进入归档。
+
+### 状态收尾
+
+2. 写 `completion-summary.md`：交付边界、关键变更、验证证据指针（指向 `completion-verification.md`）、遗留事项。
+3. 把当前 change `.status.json` 的 `change_status` 置为 `completed`。
+4. 如有可沉淀经验，在用户或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
+
+### 归档（破坏性，需确认）
+
+本步与 `../../../commands/archive.md` 共用同一安全契约；此处作用域仅限**当前单个 change**：
+
+5. 列出归档计划：源路径 `.speculo/dev/<change>/`、目标路径 `.speculo/archive/dev/<YYYY-MM>/<change>/`、`updated_at`、最后 phase、是否仍在 `dev-status.json` 的 `active[]`。
+6. 向用户展示计划并等待明确确认。**没有确认时只输出计划，不移动目录、不改索引。**
+7. 若目标归档路径已存在，标记冲突并停止，不覆盖。
+8. 用户确认后执行：
+   - 创建 `.speculo/archive/dev/<YYYY-MM>/`
+   - 移动 change 目录到 `.speculo/archive/dev/<YYYY-MM>/<change>/`
+   - 从 `.speculo/dev-status.json` 的 `active[]` 删除该 change
+   - 把（已随目录移动的）`.status.json` 的 `change_status` 置为 `archived`，写 `archived: true`、`archive_path`
+9. 若移动失败，停止后续动作，报告已完成与未完成项；不要回滚已成功的移动，除非用户明确要求。
+
+## 边界
+
+- `verification_status` 非 `verified` 时不得归档。
+- 未获用户确认时不执行任何破坏性移动或索引修改。
+- 不覆盖已存在的归档目标。
+- 批量归档多个 change 时改用 `../../../commands/archive.md`。
+
+## 完成准则
+
+- `completion-summary.md` 无残留 `[TODO:]`
+- change 目录已位于 `.speculo/archive/dev/<YYYY-MM>/<change>/`
+- `.speculo/dev-status.json` 的 `active[]` 已移除该 change
+- `.status.json` 的 `change_status: archived`，`archived: true`，`archive_path` 已写入

package/speculo/workflows/dev/R-review/R-review.md

@@ -2,13 +2,13 @@
 id: dev/R-review
 category: dev
 name: Review
-description: 从固定比较点开始，按 Standards 与 Spec 两个维度审查当前 diff
-keywords: [review, diff, standards, spec, pr, 审查]
+description: 从固定比较点开始，按 Spec、Engineering、Standards 三个独立维度审查当前 diff，并给出带严重度的裁决
+keywords: [review, diff, spec, engineering, standards, security, solid, pr, 审查]
 ---
 
 # Review 工作流执行指引
 
-本工作流是 `dev/R` 入口，用于审查 `HEAD` 与用户提供的固定点之间的 diff。审查结果必须分成两个并行维度：Standards 与 Spec，避免一个维度掩盖另一个维度。
+本工作流是 `dev/R` 入口，用于审查 `HEAD` 与用户提供的固定点之间的 diff。审查以**资深工程师视角**进行，结果必须分成三个**互相独立、互不掩盖**的维度，每条 finding 带严重度，最后给出整体裁决。
 
 ## 内置指引
 
@@ -16,49 +16,79 @@ keywords: [review, diff, standards, spec, pr, 审查]
 
 当用户想审查分支、PR、进行中的变更，或要求 `review since <fixed-point>` 时使用。
 
-### 输入
+### 三个审查维度
 
-- 固定比较点：commit SHA、分支名、tag、`main`、`HEAD~5` 等
-- 当前 change 目录：`.speculo/dev/<change>/`
-- 可发现的标准来源：`.speculo/.config/RULES.md`、`.speculo/.config/context/`、`.speculo/.config/adr/`、`AGENTS.md`、`CONTRIBUTING.md`、配置文件等
-- spec 来源：当前 change 的 PRD、slices、用户提供路径、commit message 中引用的 issue 或其他规格文档
+三个维度是三种独立的"镜头"，**不合并、不重排、不让一个维度的结论掩盖另一个**：
 
-### 输出
+| 维度 | 问题 | 关注 |
+|------|------|------|
+| **Spec** | 做对了吗？ | 是否忠实实现来源 issue / PRD / spec：缺失需求、范围蔓延、看似实现但有问题的需求 |
+| **Engineering** | 做好了吗？ | 不依赖成文规则的工程质量：SOLID 与架构、安全与可靠性、错误处理、性能、边界、死代码 |
+| **Standards** | 合规吗？ | 是否违反仓库**已记录**的标准：RULES、ADR、CONTRIBUTING、lint / 格式 / 类型配置 |
 
-- `.speculo/dev/<change>/review-sources.md`
-- `.speculo/dev/<change>/review-report.md`
-- Standards 与 Spec 两个分区的 findings，不合并、不重排
+若缺少 spec，Spec 维度跳过并报告 `no spec available`；若仓库无成文标准，Standards 维度报告检查范围并说明覆盖空白。Engineering 维度始终执行。
+
+### 严重度模型
+
+每条 finding 必须标注严重度：
+
+| 级别 | 名称 | 含义 | 动作 |
+|------|------|------|------|
+| **P0** | Critical | 安全漏洞、数据丢失风险、正确性 bug | 必须阻断合并 |
+| **P1** | High | 逻辑错误、显著 SOLID 违背、性能回退、关键需求缺失 | 合并前应修复 |
+| **P2** | Medium | 代码异味、可维护性隐患、轻微 SOLID 违背、范围蔓延 | 本 PR 修或建后续项 |
+| **P3** | Low | 风格、命名、小建议 | 可选改进 |
 
 ### 执行原则
 
-用户说的任何东西都是固定点。若用户没有指定固定点，先询问固定点；拿到前不要继续。
+- 用户说的任何东西都是固定点。若用户没有指定固定点，先询问；拿到前不要继续。
+- 比较命令使用三点语法：`git diff <fixed-point>...HEAD`，同时记录 `git log <fixed-point>..HEAD --oneline`。
+- **Worktree 模式**：若当前 change 为 worktree 隔离模式（`.status.json` 的 `worktree_enabled` 为真），fixed point 默认取 `base_branch`，且审查必须完整覆盖 change 分支树 `base_branch..change_branch` 的**每一个 commit**，不能只看最新工作区状态。此时读取 `../../../skills/worktree-isolation/SKILL.md` 的 `references/audit-branch-tree.md`；非 worktree 模式不读取该 skill。
+- **Review-first**：本工作流默认只产出审查结论，**不修改代码**；除非用户在看到 findings 后明确授权修复。
+- **诚实优先**：无法覆盖的区域要显式声明（见 `review-verdict.md` 的 clean-review 要求），不得用"看起来没问题"代替实际检查。
+- 机器已强制的标准（lint / 类型 / 格式）只记录来源，不重复人工检查工具已覆盖的内容。
+- 如果环境支持并行子代理，三个维度应并行执行；如果不支持，按三个独立上下文顺序执行，并在报告中保持分离。
 
-比较命令使用三点语法：`git diff <fixed-point>...HEAD`。同时记录 `git log <fixed-point>..HEAD --oneline`。
+### 渐进披露（Engineering 维度深度清单）
 
-Standards 维度检查 diff 是否违反仓库已记录标准；Spec 维度检查 diff 是否忠实实现来源 issue、PRD 或 spec。若缺少 spec，Spec 维度跳过并报告 `no spec available`。
+进入 Engineering 维度审查时，按需读取同目录清单：
 
-如果环境支持并行子代理，Standards 与 Spec 审查应并行执行；如果不支持，按两个独立上下文顺序执行，并在报告中保持分离。
+- `solid-checklist.md`：检查 SOLID 违背与架构异味、给重构启发式时读取。
+- `security-checklist.md`：检查安全漏洞、竞态、密钥、密码学与运行时风险时读取。
+- `code-quality-checklist.md`：检查错误处理、性能 / 缓存、边界条件时读取。
+- `removal-checklist.md`：识别死代码与删除候选、产出删除 / 推迟计划时读取。
 
 ## 阶段
 
-### 1. Review Setup — 固定点与来源收集
+### 1. Review Setup — 固定点、范围与来源收集
 - 规范：`review-setup.md`
 - 模板：`../_templates/review-sources-template.md`
 - 产物：`review-sources.md`
 - 完成准则：
-  - 已记录 fixed point、diff 命令、commit 列表
-  - 已列出 standards 来源和 spec 来源，或记录 spec 缺失
+  - 已记录 fixed point、diff 命令、commit 列表、diff 规模与分批策略
+  - 已列出 standards 来源与 spec 来源，或记录各自缺失
+  - 已标识关键路径（auth / 支付 / 数据写入 / 网络）
   - `review-sources.md` 无残留 `[TODO:]`
 
-### 2. Two-Axis Review — 双维度审查
-- 规范：`review-two-axis.md`
+### 2. Multi-Axis Review — 三维度审查
+- 规范：`review-axes.md`
 - 模板：`../_templates/review-report-template.md`
 - 产物：`review-report.md`
 - 完成准则：
-  - Standards 与 Spec 分区独立呈现
-  - 每条 finding 有文件/行或 hunk 依据，以及对应标准或 spec 引用
+  - Spec / Engineering / Standards 分区独立呈现，不合并、不重排
+  - 每条 finding 带严重度（P0–P3）、文件/行或 hunk 依据，以及对应 spec / 清单 / 标准引用
   - `review-report.md` 无残留 `[TODO:]`
 
+### 3. Verdict & Next Steps — 裁决与后续确认
+- 规范：`review-verdict.md`
+- 模板：`../_templates/review-verdict-template.md`
+- 产物：`review-verdict.md`
+- 完成准则：
+  - 给出整体裁决（APPROVE / REQUEST_CHANGES / COMMENT）与严重度汇总
+  - 完成 clean-review 声明：检查了什么、未覆盖什么、残留风险
+  - 已向用户给出后续选项，未经确认不实施修复
+  - `review-verdict.md` 无残留 `[TODO:]`
+
 ## 依赖
 
 - 软依赖：`../02-prd/02-prd.md` 或 `../I-to-issues/I-to-issues.md`，scope: same-change
@@ -71,12 +101,16 @@ Standards 维度检查 diff 是否违反仓库已记录标准；Spec 维度检
 - `dev_entry` (string) — 固定为 `dev/R`
 - `review_fixed_point` (string) — 用户提供的比较点
 - `review_diff_command` (string) — 实际使用的 diff 命令
+- `review_axes` (array) — 实际执行的维度，取值自 `spec` | `engineering` | `standards`
 - `standards_sources` (array) — Standards 审查读取的规则来源
 - `spec_sources` (array) — Spec 审查读取的规格来源
-- `review_status` (collecting | reviewing | completed | blocked) — 审查状态
+- `severity_summary` (object) — 各严重度 finding 计数：`{ "p0": n, "p1": n, "p2": n, "p3": n }`
+- `review_verdict` (approve | request_changes | comment | null) — 整体裁决
+- `review_status` (collecting | reviewing | judged | completed | blocked) — 审查状态
 
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 完成 setup 后写入 fixed point、diff 命令和来源清单。
-- 完成报告后更新 `review_status`，但不自动完成 change；是否进入修复或收尾由用户决定。
+- 完成 setup 后写入 fixed point、diff 命令、`review_axes` 和来源清单。
+- 完成报告后更新 `severity_summary`，置 `review_status: judged`。
+- 完成裁决后写入 `review_verdict`，置 `review_status: completed`；但不自动完成 change —— 是否进入修复（`../03-tdd/03-tdd.md`）、收尾归档（`../04-finalize/04-finalize.md`）或其他动作由用户决定。