@namewta/speculo 0.1.20 → 0.2.0

package/template/workflows/dev/03-tdd/tests.md

@@ -1,61 +0,0 @@
-# 好测试与坏测试
-
-## 好测试
-
-**集成式**：通过真实接口测试，而不是 mock 内部组件。
-
-```typescript
-// 好：测试可观察的行为
-test("用户可以用有效购物车结算", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
-
-特征：
-
-- 测试用户/调用者关心的行为
-- 只使用公共 API
-- 能经受住内部重构
-- 描述「做什么」，而不是「怎么做」
-- 每个测试一个逻辑断言
-
-## 坏测试
-
-**实现细节测试**：与内部结构耦合。
-
-```typescript
-// 坏：测试实现细节
-test("checkout 调用了 paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-危险信号：
-
-- mock 内部协作者
-- 测试私有方法
-- 断言调用次数/顺序
-- 重构时测试坏了但行为没变
-- 测试名称描述的是「怎么做」而不是「做什么」
-- 通过外部手段验证而不是通过接口
-
-```typescript
-// 坏：绕过接口来验证
-test("createUser 保存到数据库", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// 好：通过接口验证
-test("createUser 使用户可被检索", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```

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

@@ -1,137 +0,0 @@
----
-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>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。归档目标为 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`，`<YYYY-MM>` 从 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 / 用户任务）逐项核对需求清单
-  - 无调试残留与推测性功能
-  - （如适用）实现期引入的新领域术语 / 架构决策已按 `../M-domain-modeling/M-domain-modeling.md` 沉淀到 CONTEXT / ADR（模型未漂移）；无新术语则不适用
-  - `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/.speculo/archive/dev/<YYYY-MM>/<change>/`
-  - 已从 `speculo/.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`。
-- 多阶段 slices：完成前验证为 `verified` 后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `已实现` 置为 `已验证`（承接 `../03-tdd/03-tdd.md`「phase 阶段状态（XML 契约）」的最后一跳；无 slices 则跳过）。
-- 验证为 `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/.speculo/dev-status.json` 移除。
-- 如有可沉淀经验，在用户或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。

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

@@ -1,41 +0,0 @@
-# Completion Verification Phase（门控）
-
-本阶段是归档前的门控。**没有本次运行的验证证据，不许进入下一阶段。**
-
-## 输入
-
-- 当前 change 目录：`speculo/.speculo/dev/<change>/` 下的实现产物（多阶段在 `tdd/<phase-id>/` 下的 `implementation-log.md`、`verification.md` 等）
-- 来源：PRD、issue、slices、诊断结论或用户明确任务
-- 项目的测试 / 类型检查 / lint / 构建命令
-- 变更 diff（VCS）
-
-## 产物
-
-- `speculo/.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/.speculo/.config/RULES.md` 或用户未授权的项目规则文档。
-
-## 完成准则
-
-- `completion-verification.md` 记录了每条结论的命令与输出证据
-- 需求清单逐项核对完成，含来源引用
-- 调试残留已清理或明确说明
-- `completion-verification.md` 无残留 `[TODO:]`
-- 多阶段 slices：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 slices 则不适用）
-- `.status.json` 写入 `verification_commands`、`requirements_checklist`、`verification_status`

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

@@ -1,55 +0,0 @@
-# Finalize & Archive Phase
-
-本阶段把通过验证的 change 收尾并归档。**归档是破坏性目录移动，必须先列清单、经用户确认才执行。**
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/completion-verification.md`，且 `verification_status: verified`
-- 当前 change 的 `.status.json`
-- 顶层索引 `speculo/.speculo/dev-status.json`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/completion-summary.md`，由 `../_templates/completion-summary-template.md` 填写
-- 归档动作：change 目录移动到 `speculo/.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/.speculo/.config/LESSONS.md`。
-
-### 归档（破坏性，需确认）
-
-本步与 `../../../commands/archive.md` 共用同一安全契约；此处作用域仅限**当前单个 change**：
-
-5. 列出归档计划：源路径 `speculo/.speculo/dev/<change>/`、目标路径 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`、`updated_at`、最后 phase、是否仍在 `dev-status.json` 的 `active[]`。
-6. 向用户展示计划并等待明确确认。**没有确认时只输出计划，不移动目录、不改索引。**
-7. 若目标归档路径已存在，标记冲突并停止，不覆盖。
-8. 用户确认后执行：
-   - 创建 `speculo/.speculo/archive/dev/<YYYY-MM>/`
-   - 移动 change 目录到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
-   - 从 `speculo/.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/.speculo/archive/dev/<YYYY-MM>/<change>/`
-- `speculo/.speculo/dev-status.json` 的 `active[]` 已移除该 change
-- `.status.json` 的 `change_status: archived`，`archived: true`，`archive_path` 已写入

package/template/workflows/dev/A-improve-architecture/A-improve-architecture.md

@@ -1,143 +0,0 @@
----
-id: dev/A-improve-architecture
-category: dev
-name: Improve Architecture
-description: 扫描代码库寻找深化机会，以可视化 HTML 报告呈现候选，再对选中方向深入质询并沉淀领域模型
-keywords: [architecture, deepening, deep-module, refactor, 架构, 深化, 接缝]
----
-
-# Improve Architecture 工作流执行指引
-
-本工作流是 `dev/A` 入口：浮现架构摩擦、提出**深化机会**（把浅模块转化为深模块的重构），目标是可测试性与 AI 可导航性。它**建立在共享设计词汇与项目领域模型之上**：
-
-- 架构词汇与原则（模块 / 接口 / 深度 / 接缝 / 适配器 / 杠杆 / 局部性；删除测试、「接口就是测试表面」、「一个适配器 = 假设接缝，两个 = 真实接缝」）统一引用 `../../../vendor/codebase-design/SKILL.md`（及 `DEEPENING.md`）。在每条建议中**严格使用**这些术语——不要偏离到「组件 / 服务 / API / 边界」。
-- 领域语言来自 `speculo/.speculo/.config/context/CONTEXT.md`（为好接缝命名）；`speculo/.speculo/.config/adr/` 中的 ADR 记录本工作流**不应重新争议**的决策。领域模型的主动维护见 `../M-domain-modeling/M-domain-modeling.md`。
-
-## 内置指引
-
-### 何时使用
-
-当用户想系统性发现并落实架构深化机会（让代码更可测试、对 AI 更可导航）时使用。也可由 `../H-diagnose/H-diagnose.md` 在修复后转入——当 Bug 根因涉及架构（没有好接缝、纠缠调用者、隐藏耦合）时。
-
-### 输入
-
-- 当前 git 仓库与待改进的代码区域
-- `speculo/.speculo/.config/context/CONTEXT.md` 领域词汇、触及区域的 `speculo/.speculo/.config/adr/` ADR
-- 设计词汇单一事实源 `../../../vendor/codebase-design/SKILL.md`、`DEEPENING.md`、`DESIGN-IT-TWICE.md`
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-deepen-order-intake`）
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/architecture-candidates.md` —— 结构化深化候选清单
-- `speculo/.speculo/dev/<change>/architecture-review.html` —— 可视化架构审查报告（前后对比图 + 推荐强度）
-- `speculo/.speculo/dev/<change>/architecture-design.md` —— 选中候选经质询后的接口设计与决策
-- 经用户确认后更新 `.config/context/`、`.config/adr/`（经 `../M-domain-modeling/`）
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-### 核心原则（引用 codebase-design）
-
-- **删除测试**：对任何疑似浅的模块，想象删除它——复杂性会集中（好信号，值得深化）还是只是移动？
-- **深度是接口的属性**：小接口 + 大量实现；深化 = 缩小接口、把复杂性吸收进实现。
-- **接缝纪律**：一个适配器 = 假设接缝，两个 = 真实接缝；不要为单一实现凭空切接缝。
-- 完整原则、依赖类别与「替换而非叠加」测试策略见 `../../../vendor/codebase-design/SKILL.md` 与 `DEEPENING.md`，本工作流不复制。
-
-### 渐进披露
-
-- `HTML-REPORT.md`：编写 `architecture-review.html` 时读取——完整 HTML 框架、图表模式与样式指南。
-
-### 独立使用
-
-本工作流**零硬依赖**，无需预先执行其他工作流即可独立进入（`dev/A`）。只需当前 git 仓库即可启动；缺 change 目录时按下「自初始化」创建；缺 CONTEXT / ADR 时按代码现状探索，不阻塞。
-
-### 缺少 change 目录时的自初始化
-
-若当前无对应 change 目录：
-
-1. 从用户意图提取 `<kebab-name>`（如 `deepen-order-intake`）
-2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
-3. 初始化 `.status.json`：
-   ```json
-   {
-     "dev_entry": "dev/A",
-     "current_phase": "1. Scan",
-     "phase_history": [],
-     "change_status": "active",
-     "embedded_guides": ["improve-architecture"],
-     "candidate_count": 0,
-     "selected_candidate": null,
-     "report_path": null,
-     "architecture_status": "scanning"
-   }
-   ```
-4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组追加该 change 目录名
-
-## 阶段
-
-> **持久化铁律**：所有产物（含 HTML 报告）写入 `speculo/.speculo/dev/<change>/`，**禁止写入 `temp/`、系统临时目录或项目根目录**。
-
-### 1. Scan — 探索深化候选
-- 规范：本入口「核心原则」+ `../../../vendor/codebase-design/SKILL.md`、`../../../vendor/codebase-design/DEEPENING.md`
-- 模板：无（候选条目结构见下「引导」第 4 步）
-- 产物：`architecture-candidates.md`
-- 引导：
-  1. 先读 `speculo/.speculo/.config/context/CONTEXT.md` 与触及区域的 `.config/adr/`。
-  2. 用 Agent 工具（`subagent_type=Explore`）有机地遍历代码库，注意摩擦：理解一个概念要在许多小模块间跳转？模块浅（接口几乎和实现一样复杂）？纯函数仅为可测试性而提取、真 bug 藏在其调用方式里（没有局部性）？紧耦合模块在接缝处泄漏？哪些区域难以通过当前接口测试？
-  3. 对每个疑似浅模块应用**删除测试**，保留「删除会集中复杂性」的候选。
-  4. 每个候选记录：**涉及文件**、**问题**（当前摩擦）、**解决方案**（通俗语言）、**收益**（用局部性 / 杠杆 / 测试改善表述）、**依赖类别**（进程内 / 本地可替换 / 端口与适配器 / mock）、**推荐强度**（强烈 / 值得探索 / 推测性）。
-  5. 与现有 ADR 冲突的候选，仅在摩擦真实到值得重审 ADR 时保留，并在条目中显式标注（如「与 ADR-0007 矛盾——但因……值得重新讨论」）。
-- 完成准则：
-  - 候选均用 codebase-design 词汇命名（不散用「组件 / 服务 / 边界」）
-  - 每个候选含文件、问题、解决方案、收益、依赖类别、推荐强度
-  - `architecture-candidates.md` 无残留 `[TODO:]`
-
-### 2. Report — 可视化架构审查报告
-- 规范：`HTML-REPORT.md`
-- 模板：无
-- 产物：`architecture-review.html`
-- 引导：
-  1. 按 `HTML-REPORT.md` 编写**自包含** HTML（Tailwind + Mermaid 走 CDN），每个候选一张卡片含**前后对比图**，结尾「首要推荐」段。
-  2. 写入 `speculo/.speculo/dev/<change>/architecture-review.html`（**不写临时目录**），用 OS 命令打开（macOS `open <path>`、Linux `xdg-open <path>`、Windows `start <path>`），并告知用户绝对路径。
-  3. 领域用 CONTEXT 词汇、架构用 codebase-design 词汇。
-  4. 此时不提接口设计；写入并打开后，询问用户：「这些候选你想探索哪一个？」
-- 完成准则：
-  - HTML 自包含、每个候选有前后对比图与推荐强度徽章、含首要推荐段
-  - 报告写入 change 目录并已为用户打开
-  - 已请用户选择候选
-
-### 3. Grill — 质询所选候选并沉淀
-- 规范：`../../../skills/grill-me/SKILL.md`（逐问压测）+ `../M-domain-modeling/M-domain-modeling.md`（内联沉淀）
-- 模板：无
-- 产物：`architecture-design.md`；经用户确认后更新 `.config/context/`、`.config/adr/`
-- 引导：
-  1. 用 `../../../skills/grill-me/SKILL.md` 与用户走设计树：约束、依赖、深化后模块形态、接缝后面是什么、哪些测试存活。
-  2. 决策结晶时按 `../M-domain-modeling/M-domain-modeling.md` 内联沉淀：深化模块用了 CONTEXT 没有的概念 → 加术语；锐化了模糊术语 → 更新 CONTEXT；用户以关键理由否决候选 → 按 ADR 三判据决定是否记 ADR（防止未来架构审查重复建议同一件事）。
-  3. 想探索深化模块的备选接口时，按 `../../../vendor/codebase-design/DESIGN-IT-TWICE.md` 的「设计两次」并行子代理模式。
-- 完成准则：
-  - 选中候选的接口、依赖策略与适配器、存活测试已记入 `architecture-design.md`
-  - 决策结晶处的术语 / ADR 已按 `../M-domain-modeling/` 沉淀（经用户确认）
-  - `architecture-design.md` 无残留 `[TODO:]`
-
-## 依赖
-
-- 硬依赖：无（零依赖横向工作流）
-- 软依赖：无。可独立进入；也可由 `../H-diagnose/H-diagnose.md` 修复后转入。建立在 `../../../vendor/codebase-design/`（设计词汇）与 `../M-domain-modeling/`（领域模型）之上；深化的实现落地交由 `../03-tdd/03-tdd.md`。
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/A`
-- `embedded_guides` (array) — 包含 `improve-architecture`
-- `candidate_count` (number) — 深化候选数量
-- `selected_candidate` (string|null) — 用户选中的候选
-- `report_path` (string|null) — `speculo/.speculo/dev/<change>/architecture-review.html`
-- `architecture_status` (scanning | reported | grilling | designed | blocked) — 工作流状态
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 报告生成后写入 `candidate_count`、`report_path`，置 `architecture_status: reported`。
-- 用户选定并质询后写入 `selected_candidate`，置 `architecture_status: designed`。
-- 写 `.config/context/` 或 `.config/adr/` 前必须经用户确认（经 `../M-domain-modeling/`）。
-- 本工作流不自动完成 change；深化的实现交由 `../03-tdd/03-tdd.md` 落地。

package/template/workflows/dev/A-improve-architecture/HTML-REPORT.md

@@ -1,123 +0,0 @@
-# HTML 报告格式
-
-架构审查以单个**自包含 HTML 文件**渲染，写入 `speculo/.speculo/dev/<change>/architecture-review.html`（由入口 `A-improve-architecture.md` Phase 2 规定，**不写临时目录**）。Tailwind 和 Mermaid 均从 CDN 加载。Mermaid 可靠地处理图形状图表；手写 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。两者混合使用——不要所有内容都依赖 Mermaid，否则会显得千篇一律。
-
-## 脚手架
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Architecture review — {{repo name}}</title>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
-    </script>
-    <style>
-      /* small custom layer for things Tailwind doesn't cover cleanly:
-         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
-      .seam { stroke-dasharray: 4 4; }
-      .leak { stroke: #dc2626; }
-      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
-    </style>
-  </head>
-  <body class="bg-stone-50 text-slate-900 font-sans">
-    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
-      <header>...</header>
-      <section id="candidates" class="space-y-10">...</section>
-      <section id="top-recommendation">...</section>
-    </main>
-  </body>
-</html>
-```
-
-## 页头
-
-仓库名称、日期和紧凑图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，深色粗框 = 深层模块。没有介绍段落——直接进入候选方案。
-
-## 候选卡片
-
-图表承担主要信息量。文字稀疏、平实，使用 `../../../vendor/codebase-design/SKILL.md` 的术语表词汇，不铺陈。
-
-每个候选方案为一个 `<article>`：
-
-- **标题**——简短，命名深化操作（例如「折叠订单接收流水线」）。
-- **徽章行**——推荐强度（`Strong` = 翡翠绿，`Worth exploring` = 琥珀色，`Speculative` = 石板灰），外加一个依赖类别标签（`in-process`、`local-substitutable`、`ports & adapters`、`mock`）。
-- **文件**——等宽字体列表，`font-mono text-sm`。
-- **Before / After 图表**——核心部分。两列并排。见下方模式。
-- **问题**——一句话。痛点是什么。
-- **解决方案**——一句话。改变了什么。
-- **收益**——项目符号，每条 ≤6 个字。例如「测试只需命中一个接口」「定价逻辑不再泄漏」「删除 4 个浅层包装器」。
-- **ADR 提示**（如适用）——琥珀色背景框中的一行说明。
-
-没有解释性段落。如果图表需要一段文字才能理解，那就重绘图表。
-
-## 图表模式
-
-选择适合候选方案的模式。混合使用。不要让每张图表看起来都一样——多样性本身就是目的之一。
-
-### Mermaid 图（依赖/调用流的常用工具）
-
-当要表达「X 调用 Y 调用 Z，看看这有多乱」时，使用 Mermaid `flowchart` 或 `graph`。用 Tailwind 风格的卡片包裹它，避免显得突兀。使用 classDef 将泄漏边着色为红色，将深层模块着色为深色。时序图适合表达「Before：6 次往返；After：1 次」。
-
-```html
-<div class="rounded-lg border border-slate-200 bg-white p-4">
-  <pre class="mermaid">
-    flowchart LR
-      A[OrderHandler] --> B[OrderValidator]
-      B --> C[OrderRepo]
-      C -.leak.-> D[PricingClient]
-      classDef leak stroke:#dc2626,stroke-width:2px;
-      class C,D leak
-  </pre>
-</div>
-```
-
-### 手写框线箭头图（当 Mermaid 布局不理想时）
-
-模块用带有边框和标签的 `<div>` 表示。箭头用绝对定位在相对容器上的内联 SVG `<line>` 或 `<path>` 元素表示。当你希望「After」图表呈现为一个粗边框的深层模块，内部变灰时，使用这种方式——Mermaid 无法渲染出正确的视觉重量。
-
-### 横截面图（适合展示分层浅度）
-
-堆叠水平条带（`h-12 border-l-4`）来展示调用经过的层级。Before：6 个薄层，每层几乎什么都不做。After：1 个粗条带，标注了合并后的职责。
-
-### 质量图（适合展示「接口与实现一样宽」）
-
-每个模块两个矩形——一个表示接口表面积，一个表示实现。Before：接口矩形几乎和实现矩形一样高（浅层）。After：接口矩形短，实现矩形高（深层）。
-
-### 调用图折叠
-
-Before：函数调用树，渲染为嵌套盒子。After：同一棵树折叠为一个盒子，内部现已内部化的调用在其中淡色显示。
-
-## 样式指南
-
-- 偏编辑风格，而非企业仪表盘风格。宽裕的留白。标题可选衬线字体（`font-serif` 与 stone/slate 配色搭配效果很好）。
-- 颜色克制：一种强调色（翡翠绿或靛蓝）加红色表示泄漏，琥珀色表示警告。
-- 图表高度保持在约 320px，以便 before/after 并排显示无需滚动。
-- 图表内模块标签使用 `text-xs uppercase tracking-wider`——它们应该呈现为示意图风格，而非 UI 风格。
-- 唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。报告其余部分是静态的——没有应用代码，除 Mermaid 自身渲染外没有交互性。
-
-## 首选推荐部分
-
-一张较大的卡片。候选方案名称，一句说明原因的话，锚链接指向其卡片。仅此而已。
-
-## 语气
-
-平实中文，简洁——但架构名词和动词直接来自 `../../../vendor/codebase-design/SKILL.md`。简洁不是偏离术语表的借口。
-
-**精确使用：** 模块（module）、接口（interface）、实现（implementation）、深度（depth）、深（deep）、浅（shallow）、接缝（seam）、适配器（adapter）、杠杆（leverage）、局部性（locality）。
-
-**绝不替换：** 组件 / 服务 / 单元（表示 module）· API / 签名（表示 interface）· 边界（表示 seam）· 层 / 包装器（表示 module，当你的意思是 module 时）。
-
-**符合风格的表述：**
-
-- 「订单接收模块是浅的——接口几乎和实现一样复杂。」
-- 「定价逻辑在接缝处泄漏。」
-- 「深化：一个接口，一处可测。」
-- 「两个适配器证明了接缝：生产用 HTTP，测试用内存。」
-
-**收益项目符号**用术语表词汇命名收益：「局部性：bug 集中在一个模块」「杠杆：一个接口，N 个调用点」「接口缩小，实现吸收包装器」。不要写「更易维护」或「更干净的代码」——这些词不在术语表中，不应出现。
-
-不模棱两可，不开场白，不写「值得注意的是……」。如果一句话可以变成项目符号，就变成项目符号。如果一个项目符号可以删掉，就删掉。如果一个词不在 `../../../vendor/codebase-design/SKILL.md` 术语表中，在发明新词之前先找一个术语表中有的词。