@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/P-goal-plan/completion-control.md

@@ -0,0 +1,79 @@
+# Goal Plan 完成、证据与恢复控制
+
+## 1. Outcome and Authority
+
+Goal Plan 用紧凑摘要表达：
+
+- 业务或用户目标；
+- 目标受众或运营角色；
+- 所有计划 Ticket 完成后的可观察终态；
+- 关键约束；
+- 明确非目标；
+- 权威来源和冲突规则。
+
+不复制 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的完整用户故事。
+
+## 2. 整体 Definition of Done
+
+整体完成至少覆盖：
+
+- 所有计划内 Ticket 完成，cancelled 或 deferred 项有批准；
+- 所有 Spec 验收合同和外部符合性要求有 Evidence；
+- 项目类型检查、静态检查、测试、lint、构建和适用 CI 完成；仅 UI 交互受影响时由 Lead 完成 E2E；
+- 迁移、兼容、调用点清零、监控、回滚和不可逆批准完成；
+- 无未批准偏差和未处置高风险残余问题；
+- Ticket、Map、Goal Plan、Evidence 和状态一致。
+
+## 3. Gate 关闭仪式
+
+每个 Gate 关闭时：
+
+1. 汇总覆盖的 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`；
+2. 检查对应合同和参考符合性；
+3. 检查共享接口、数据、兼容、迁移和调用点；
+4. 运行里程碑级验证；仅 UI 交互受影响时由 Lead 运行最小 E2E；
+5. 审查失败分类、偏差、残余风险和恢复能力；
+6. 获取适用人工批准；
+7. 同步 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 和状态工件。
+
+## 4. 不可协商约束
+
+只记录跨多个 Ticket 且不可由实现者改变的规则，例如数据完整性、wire format 兼容、旧协议收缩条件、shared owner、安全要求、发布窗口、回滚演练和批准点。
+
+来源必须指向：
+
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`；
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
+- 具体 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
+- 外部 Url 标签；
+- `<Path>{roots.state}/specdev/config.json</Path>`。
+
+## 5. 偏差与暂停
+
+偏差等级和处理遵循 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`。
+
+跨 Ticket 偏差还必须明确：
+
+- 暂停哪些 Wave 或 Ticket；
+- 哪个 Gate 重新打开；
+- 哪些 Agent 需要重新基线；
+- 哪些 Evidence 失效；
+- 重新开始的条件。
+
+## 6. 风险与恢复
+
+每个高风险项写明：触发信号、事故半径、预防措施、检测方式、恢复动作、owner 和批准点。迁移或发布计划必须给出回滚不可行时的前向恢复方案。
+
+## 7. 进度与决策回报
+
+使用可核验状态，不使用主观百分比：
+
+```text
+WAVE_STATUS wave=<n> ready=<ids> active=<ids> done=<ids> blocked=<ids>
+GATE_STATUS gate=<name> state=open|closed evidence=<paths> risks=<summary>
+TICKET_STATUS id=<id> state=<state> evidence=<path> deviation=<none|id>
+BLOCKER id=<id> owner=<owner> needed=<decision-or-input> impact=<scope>
+DECISION id=<id> owner=<owner> status=pending|approved|rejected impact=<scope>
+```
+
+具体路径必须以完整 Path 标签 形式填写。

package/template/workflows/specdev/P-goal-plan/goal-plan-template.md

@@ -0,0 +1,105 @@
+---
+schema_version: 3
+artifact: goal-plan
+change: <YYYY-MM-DD-topic>
+status: draft
+modes: [coordination]
+ready_for_execution: false
+---
+
+# Goal Plan: <标题>
+
+- **Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **Tickets Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **Ticket 目录：** `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- **Evidence 目录：** `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+
+## 1. Outcome and Authority
+
+### Outcome
+
+### Non-goals
+
+### Authoritative Inputs
+
+| 优先级 | 来源 | 负责内容 | 冲突处理 |
+|---|---|---|---|
+| 1 | 用户最新明确决定 | 产品取舍与批准 | 更新真正拥有该决策的工件 |
+| 2 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 已接受架构决策 | 通过新决策替代 |
+| 3 | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | 外部行为、范围与验收 | 下游不得改写 |
+| 4 | `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` | 单 Ticket 契约 | Goal Plan 只编排 |
+| 5 | 当前代码事实 | 现状与可行性 | 冲突时触发偏差 |
+
+## 2. Execution Graph
+
+### DAG and Critical Path
+
+```text
+...
+```
+
+### Waves and Ownership
+
+| Wave | Ticket | 前置条件 | 项目写路径 | Shared owner | 集成点 |
+|---|---|---|---|---|---|
+
+### Ticket Quick Reference
+
+<!-- Ticket 较多或执行者需要时添加；数据从 Ticket 与 Tickets Map 提取。 -->
+
+| ID | Ticket | 行为产出 | Depth/Risk | Dependencies | Wave/Gate | Owner | Evidence |
+|---|---|---|---|---|---|---|---|
+| T-01 | `<Path>{roots.state}/specdev/changes/{change}/ticket/01-<name>.md</Path>` | ... | standard/medium | — | W0/G0 | lead | `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>` |
+
+## 3. Gates and Completion Evidence
+
+### Overall Definition of Done
+
+### Gates
+
+| Gate | 开启条件 | 关闭证据 | 阻塞范围 | Owner/批准人 | 失败恢复 |
+|---|---|---|---|---|---|
+
+### Contract and Reference Coverage
+
+| 合同或参考要求 | 覆盖 Ticket | 验证接缝 | Evidence | 状态 |
+|---|---|---|---|---|
+
+## 4. Execution and Integration Protocol
+
+### Dispatch Payload
+
+并行写代码时记录统一 `base_sha`，并为每个 Ticket 指定分支、`workspace_ref` 和 worktree owner。
+
+### Ticket Execution
+
+引用 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 和对应 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`，不复制 Ticket 全文。
+
+### Evidence Return and Integration
+
+Worker 将 Ticket 推进到 `review`，返回 Ticket ID 与状态、Evidence 路径、`workspace_ref`、commit 或 PR 引用，以及条件性 Lead E2E；Lead 负责集成、回归和 worktree 收尾。
+
+## 5. Constraints, Risk and Recovery
+
+### Non-negotiable Constraints
+
+### Migration or Release Sequence
+
+### Risks, Monitoring and Recovery
+
+### Deviation Control
+
+遵循 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`。
+
+## 6. Progress and Decisions
+
+### Current Status
+
+### Pending Decisions and Blockers
+
+### Reporting Format
+
+## Assumptions
+
+仅记录低影响、可逆且有验证方式的假设。高影响假设存在时，`ready_for_execution` 必须为 `false`。

package/template/workflows/specdev/P-goal-plan/orchestration-protocol.md

@@ -0,0 +1,115 @@
+# Goal Plan 编排协议
+
+本文件定义 DAG、Wave、Gate、路径所有权、Lead/Subagent、worktree、Evidence 返回和集成规则。
+
+## 1. DAG 与关键路径
+
+- 依赖权威来自 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` frontmatter 的 `blocked_by`；
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 是投影，不是第二套依赖真相；
+- 计算根节点、扇出、汇合点、关键路径、共享合同 owner 和最终收缩点；
+- 依赖只表示真实开始条件，不表示偏好、人员交接或“最好先做”；
+- 无法独立保持可验证状态的迁移批次必须有隔离集成策略和最终集成 Gate。
+
+## 2. Wave
+
+Wave 内 Ticket 必须同时满足：
+
+- `ready: true`；
+- 所有依赖已完成并有 Evidence；
+- 项目写路径不相交；
+- shared path 已由 owner 稳定；
+- 适用 Gate 已打开；
+- 基线和外部合同版本一致。
+
+最大并发从 `<Path>{roots.state}/specdev/config.json</Path>` 读取。并发上限是资源约束，不是强制填满的目标。
+
+## 3. Gate
+
+Gate 由可验证状态定义，不用“完成若干 Ticket”作为唯一条件。每个 Gate 必须写明：
+
+- 业务或工程状态；
+- 开启条件；
+- 关闭证据；
+- 阻塞范围；
+- owner 与批准人；
+- 失败时恢复动作。
+
+常见 Gate 包括共享合同稳定、首条垂直路径通过、迁移完成、旧调用点归零、发布就绪和观察期结束。名称按项目语义自定义。
+
+## 4. Shared path 与共享合同
+
+规则遵循 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`：
+
+1. 由专用 owner Ticket 或 Lead 修改共享路径；
+2. 形成可验证稳定基线；
+3. 下游消费者在新基线上重新运行 preflight；
+4. 才允许扇出并行；
+5. 共享契约需要变化时暂停消费者并修订上游，不通过多个 Agent 同时修改解决。
+
+## 5. Expand-contract
+
+标准顺序：
+
+1. **expand**：新旧形式并存，既有调用者继续工作；
+2. **migrate**：按可独立验证的影响范围分批迁移；
+3. **observe**：扫描旧调用点、旧数据或旧协议使用量；
+4. **contract**：收缩条件有证据后删除旧形式；
+5. **verify**：运行兼容、数据、回归、监控和回滚检查。
+
+收缩不得仅以“所有迁移 Ticket 已完成”为依据。
+
+## 6. Lead/Subagent
+
+Lead 负责基线、DAG、Wave、shared owner、Gate、Evidence 汇总和集成；不抢做已派发 Ticket 的实现。
+
+并行写代码且配置允许时，Lead 为每个 Ticket 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`：
+
+- 所有并行 Ticket 固定同一 `base_sha`，每个 Ticket 使用独立分支和 `workspace_ref`；
+- Lead 创建、恢复、集成和清理；Worker 只把状态推进到 `review`；
+- 只读调查和顺序执行不为形式创建 worktree。
+
+每个 Agent 的最小读取顺序：
+
+1. `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`；
+2. `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
+3. `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 中适用的 Wave、Gate 和硬约束；
+4. `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 中相关合同；
+5. `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 中相关条目；
+6. 项目级 Agent 指令和当前代码事实。
+
+不把完整历史对话、全部 Ticket 或无关研究塞入 Agent 上下文。
+
+## 7. 派单载荷
+
+派单必须包含：
+
+- Ticket ID 与 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
+- 基线 SHA、分支和 `workspace_ref`；
+- 项目写、只读和 shared 路径；
+- 已完成依赖及其 Evidence；
+- 合同 ID；
+- 适用 Wave、Gate 和跨 Ticket 约束；
+- 必须执行的验证矩阵；
+- 偏差升级方式和禁止修改事项。
+
+## 8. Evidence 返回与集成
+
+Agent 完成或阻塞时：
+
+1. 写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`；
+2. 同步 Ticket、Tickets Map、Goal Plan 和 change 状态；
+3. 向 Lead 返回 Ticket ID 与状态、Evidence 完整路径、`workspace_ref`、commit 或 PR 引用，以及仅在用户界面交互受影响时由 Lead 执行的待办 E2E。
+
+Lead 集成时：
+
+1. 读取 Ticket、Evidence、Goal Plan 和对应代码引用；
+2. 检查路径授权；
+3. 复跑定向验证；
+4. 合并或应用变更；
+5. 运行受影响回归；
+6. 仅当用户界面交互受影响时，由 Lead 运行最小 E2E；
+7. 按 dev-worktree Skill 更新或清理 worktree；
+8. 同步 Ticket、Map、Evidence 和 Goal Plan；
+9. 检查 Gate 是否可关闭。
+
+逻辑冲突返回契约和 owner 解决，不机械选择某一侧版本。

package/template/workflows/specdev/P-goal-plan/planning-modes.md

@@ -0,0 +1,70 @@
+# Goal Plan 规划模式与输入门禁
+
+本文件由 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 在上游验证和模式选择时加载。
+
+## 1. 必需输入门禁
+
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 设置 `ready_for_tickets: true`，或存在用户明确批准的等价权威目标。
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 与全部 Ticket 一致。
+- [ ] 所有计划执行的 Ticket 设置 `ready: true`。
+- [ ] Ticket ID、具体 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` 和 Map 行一致。
+- [ ] `blocked_by` 引用存在，DAG 无环。
+- [ ] Spec 验收合同全部 covered，或 deferred 项有批准、原因和后续归属。
+- [ ] 可能并行的 Ticket 项目写路径不相交，或已有 shared owner 与排序方案。
+- [ ] Deep Ticket 具备迁移、兼容、监控、回滚、收缩条件和批准点。
+- [ ] Ticket 与 Spec、ADR、代码事实不存在未处理冲突。
+
+## 2. 硬停止
+
+出现以下任一情况时停止：
+
+- 任一计划内 Ticket 未 Ready；
+- DAG 有环、缺失引用或依赖仅代表偏好；
+- 合同 uncovered 且未批准 deferred；
+- 并行候选写路径相交且无 owner 或顺序；
+- Ticket 改写了 Spec 的外部行为、范围或验收；
+- Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 的已接受决策冲突；
+- Deep Ticket 缺少关键迁移或恢复信息；
+- 当前代码事实使 Ticket 的核心行为、接口或验证不可执行；
+- 必需外部合同或参考权威不可获得。
+
+按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 返回真正拥有该决策的工件。
+
+## 3. 可组合模式
+
+### coordination
+
+适用于多 Wave、扇出/汇合、shared path 或 Lead/Subagent。重点是 DAG、owner、Evidence 返回、集成和状态同步。
+
+### migration
+
+适用于 expand-contract、数据迁移、协议迁移或兼容窗口。重点是扩展、分批迁移、收缩条件、数据核对、监控和回滚。
+
+### high-assurance
+
+适用于安全、隐私、资金、数据完整性、法规或不可逆操作。重点是独立审查、人工批准、Evidence 完整性和失败恢复。
+
+### reference-conformance
+
+适用于外部合同、标准、官方实现或指定兼容行为。重点是来源版本、符合性矩阵和冲突裁决。
+
+### release-coordination
+
+适用于发布窗口、跨团队依赖、部署顺序或运营交接。重点是环境前置条件、Gate、观察期和回退。
+
+模式可以组合。仅有线性低风险 Ticket 时不应为了形式生成重型 Goal Plan。
+
+## 4. 模式摘要
+
+写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 前形成：
+
+```text
+modes=<mode-list>
+tickets=<count>
+critical_path=<ticket-list>
+parallel_capacity=<n>
+shared_owners=<owner-map>
+gates=<gate-list>
+hard_stops=<none-or-list>
+adopted_assumptions=<low-impact-only>
+```

package/template/workflows/specdev/R-review-architecture/R-review-architecture.md

@@ -3,75 +3,138 @@ id: specdev/review-architecture
 type: workflow-entry
 workflow: specdev
 name: 架构审查
-description: 扫描代码仓寻找深层化机会——发现浅模块、接缝泄漏和局部性缺陷，以可视化 HTML 报告呈现候选方案，逐一访谈深化。
-keywords: [架构审查, 深化, 模块设计, 接缝, 重构, 可视化]
+description: 扫描与目标相关的代码区域，识别浅模块、接缝泄漏和局部性问题，以可视化报告呈现候选方案，并通过逐项访谈转化为可执行决策。
+keywords: [architecture, review, module depth, seams, locality, HTML, refactor]
 ---
 
 # 架构审查
 
-主动扫描代码仓发现架构摩擦，将其转化为可操作的深化方案——融合有机探索、可视化报告和访谈打磨。每一步引用内部子文件，不依赖外部 skill。
+本 work 保留并强化三项核心能力：从真实代码压力识别深层化机会、输出可视化 HTML 审查报告、与用户逐项访谈候选方案。它不以“更优雅”为由制造无目标重构，也不直接修改产品代码。
 
-在开始之前，读取当前变更的上下文与架构决策：
+## 输入与产物
 
-- **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- **永久 ADR** —— 已确认并提升的架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
-- **永久 CONTEXT** —— 已确认并提升的领域词汇表：`<Path>{roots.state}/specdev/context/</Path>`
+按存在情况读取：
 
-如果当前 change 尚不存在或其下无 CONTEXT.md、ADR.md，静默继续——架构审查常是新变更的起点，change 的创建在步骤 4 用户选定候选后进行。
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/adr/</Path>`
+- `<Path>{roots.state}/specdev/context/</Path>`
+- 当前代码、测试、依赖、近期变更和缺陷事实。
+
+产物：
+
+- 决策记录：`<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- 可视化报告：`<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
+
+模板：
+
+- `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>`
 
 ## 流程
 
-### 1. 建立基准
+### 1. 明确审查压力与范围
 
-读取 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 建立架构评估词汇——module、interface、depth、seam、adapter、leverage、locality 八个术语及其原则。读取 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>` 建立依赖分类（进程内/本地可替换/远程但自有/真正外部依赖）和接缝纪律基准。
+记录触发审查的业务目标、近期变更、缺陷、维护成本、性能或风险，不做无边界全仓巡检。明确：审查入口、相关调用路径、不审查范围和成功标准。
 
-**完成标准**：架构术语、删除测试、接缝纪律和依赖分类已加载；CONTEXT.md 领域术语和 ADR.md 已有决策已理解。
+用户明确要求全仓架构扫描时，可以扩展范围，但仍按领域、模块或调用链分批，避免在单次上下文中生成无证据的泛化结论。
 
-### 2. 探索摩擦
+### 2. 建立当前结构地图
 
-委托给 `<Path>{roots.workflows}/specdev/R-review-architecture/exploration-guide.md</Path>`。使用 Explore 子 Agent 有机遍历代码仓——不遵循僵化启发式，注意你在何处遇到摩擦：哪些模块是浅层的？哪些接缝存在泄漏？哪里缺乏局部性？哪些部分未经测试或难以测试？对每个可疑点应用删除测试。
+只读探索目标区域：
 
-探索中若发现候选方案与已有 ADR 矛盾，仅当摩擦足够真实、值得重新审视 ADR 时才标注——在报告中以警告框清晰标记。
+- 模块及其公共接口；
+- 信息隐藏与调用者负担；
+- 接缝、适配器和依赖类别；
+- 数据、控制和错误流；
+- 时间耦合、共享状态和跨目录跳转；
+- 测试接缝与变更热点；
+- 近期缺陷、重复 workaround 和高频共同修改路径。
 
-**完成标准**：代码仓已遍历，每个摩擦点已记录涉及文件、摩擦类型和删除测试结果。
+使用：
 
-### 3. 生成可视化报告
+- `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`
 
-委托给 `<Path>{roots.workflows}/specdev/R-review-architecture/html-report-template.md</Path>`。将探索发现渲染为自包含 HTML 文件，写入 OS 临时目录（`$TMPDIR` 或 `/tmp`），自动在浏览器中打开。每候选一张卡片：涉及文件、问题、方案、收益、before/after 图表、推荐强度（Strong / Worth exploring / Speculative）。报告结尾附最佳推荐。
+外部技术或模式不清楚时使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
-此时不提出接口。报告打开后询问用户："你想探索其中哪一个？"
+### 3. 识别候选深层化机会
 
-**完成标准**：HTML 报告已写入临时目录并已在浏览器中打开；用户已看到候选方案并做出选择。
+候选至少属于一种机制：
 
-### 4. 访谈深化循环
+- 浅模块把复杂性推给调用者；
+- 接缝泄漏导致多处了解同一协议或状态；
+- 局部性差导致一个行为修改跨越过多路径；
+- 依赖方向或生命周期不清导致测试与替换困难；
+- 时间耦合、共享状态或错误语义造成事故半径；
+- 缺少真正适配器导致 Mock 代替设计；
+- 宽重构压力需要 expand-contract。
 
-用户选择候选后，先绑定变更：按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议复用当前活跃 change 或创建新 change（topic 取自候选名）；新建时参照 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 步骤 1 初始化 `.status.json` 与三文件。
+每个候选必须有项目路径、调用或测试证据，并说明“不做”的实际后果。没有用户或工程收益、近期变化压力或风险降低的候选直接过滤。
 
-随后委托 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` 执行一次一问访谈——沿设计树推进：约束、依赖、深化模块的形状、接缝背后的内容、存留的测试。
+### 4. 设计替代方案
 
-访谈中按 grilling-protocol 与 domain-modeling-rules 维护三文件（LOG → CONTEXT → ADR）。
+每个保留候选至少比较：
 
-如需探索替代接口，启动 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。
+- 保持现状；
+- 最小深层化方案；
+- 一个具有实质差异的替代方案。
 
-用户以负载性理由拒绝候选时，提供 ADR 记录："要我将其记录为 ADR 吗？这样未来的架构审查不会重新建议它。"访谈共识达成后，移交 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行实现。
+比较调用者复杂度、接口稳定性、迁移、兼容、测试、回滚、路径影响和事故半径。局部接口存在多个可行设计时，可使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。
 
-**完成标准**：change 已绑定（复用或新建）；访谈共识已达成；LOG.md/CONTEXT.md/ADR.md 已同步；用户已确认进入实现或记录 ADR 排除候选。
+### 5. 生成 Markdown 与 HTML 报告
 
----
+使用 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`。
 
-## 子文件引用
+使用 `<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`。HTML 应包含：
+
+- 审查范围与结构地图；
+- 候选卡片和严重度；
+- 证据路径；
+- 方案对比；
+- 影响与迁移图；
+- 接受、延后、拒绝状态；
+- 指向 Markdown 决策记录的完整状态路径文本。
+
+不得依赖外部 CDN；报告应可作为单文件本地打开。
+
+### 6. 逐项访谈候选
 
-| 文件 | 内容 | 触发条件 |
-|------|------|---------|
-| `<Path>{roots.workflows}/specdev/R-review-architecture/exploration-guide.md</Path>` | 摩擦信号清单、删除测试应用规则、接缝评估标准、ADR 冲突检测规则 | 步骤 2「探索摩擦」进入时加载 |
-| `<Path>{roots.workflows}/specdev/R-review-architecture/html-report-template.md</Path>` | HTML 脚手架、6 种图表模式、样式指南、报告语言占位符 | 步骤 3「生成可视化报告」进入时加载 |
+按价值与风险排序，一次只讨论一个候选：
 
-## 依赖关系
+1. 说明证据和问题机制；
+2. 给出推荐方案与理由；
+3. 展示至少一个替代方案和保持现状的后果；
+4. 询问用户接受、调整、延后或拒绝；
+5. 将结论写回 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`；
+6. 架构级决定同步到 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`，讨论轨迹同步到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。
+
+不得一次抛出所有问题要求用户批量选择。
+
+### 7. 转化为执行工作
+
+只有被接受且有具体变更压力的提案才进入执行。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`：
+
+- 可独立降低后续实现难度的改进生成 Prefactor Ticket；
+- 常规垂直迁移生成 Standard Ticket；
+- 公共契约、数据、宽迁移或高风险改动生成 Deep Ticket 与 expand-contract；
+- 进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 完成正式拆分和 Ready 门禁。
+
+## 完成标准
+
+- 审查压力、范围和不审查范围明确；
+- 每个候选有代码事实、行为影响和不做后果；
+- 保留候选有至少两个实质方案与权衡；
+- Markdown 和无外部依赖的 HTML 报告均已生成；
+- 用户已逐项给出接受、调整、延后或拒绝结论；
+- 接受的架构决定已同步到 ADR；
+- 执行建议已转入 Ticket 治理，而不是直接修改代码。
+
+## 子文件引用
 
-- 依赖 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 提供架构术语——步骤 1 加载
-- 依赖 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>` 提供依赖分类和接缝纪律——步骤 1 加载
-- 依赖 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` 执行访谈——步骤 4 委托
-- 依赖 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护三文件——步骤 4 委托
-- 依赖 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>` 探索替代接口——步骤 4 按需启动
-- 依赖 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行实现——步骤 4 共识后移交
+- Markdown 模板：`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>`
+- HTML 模板：`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-report-template.html</Path>`
+- 提案转 Ticket：`<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`

package/template/workflows/specdev/R-review-architecture/architecture-review-report-template.html

@@ -0,0 +1,58 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SpecDev Architecture Review</title>
+  <style>
+    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+    body { max-width: 1180px; margin: 0 auto; padding: 32px; line-height: 1.55; }
+    header, section { margin-bottom: 28px; }
+    .meta, .card { border: 1px solid #8886; border-radius: 12px; padding: 16px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 16px; }
+    .badge { display: inline-block; border: 1px solid currentColor; border-radius: 999px; padding: 2px 9px; margin-right: 6px; font-size: 0.85rem; }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { border: 1px solid #8886; padding: 8px; text-align: left; vertical-align: top; }
+    code { overflow-wrap: anywhere; }
+    path::before { content: "<Path>"; }
+    path::after { content: "</Path>"; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Architecture Review: &lt;范围&gt;</h1>
+    <div class="meta">
+      <p>决策记录：<code><Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path></code></p>
+      <p>本报告：<code><Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path></code></p>
+    </div>
+  </header>
+  <section>
+    <h2>审查压力与结构地图</h2>
+    <p>&lt;填写触发目标、范围、模块、接口、数据流和变化热点。&gt;</p>
+  </section>
+  <section>
+    <h2>候选提案</h2>
+    <div class="grid">
+      <article class="card">
+        <h3>AR-001 · &lt;标题&gt;</h3>
+        <p><span class="badge">severity</span><span class="badge">status</span></p>
+        <p><strong>证据：</strong><code><Path>project/relative/path</Path></code></p>
+        <p><strong>问题机制：</strong>&lt;...&gt;</p>
+        <p><strong>实际影响：</strong>&lt;...&gt;</p>
+        <p><strong>推荐：</strong>&lt;...&gt;</p>
+      </article>
+    </div>
+  </section>
+  <section>
+    <h2>方案对比</h2>
+    <table>
+      <thead><tr><th>维度</th><th>保持现状</th><th>推荐方案</th><th>替代方案</th></tr></thead>
+      <tbody><tr><td>调用者复杂度</td><td></td><td></td><td></td></tr></tbody>
+    </table>
+  </section>
+  <section>
+    <h2>决策与下一步</h2>
+    <p>&lt;逐项记录 accepted / adjusted / deferred / rejected。&gt;</p>
+  </section>
+</body>
+</html>