@andyqiu/codeforge 0.3.14 → 0.4.0

package/review-profiles/plan-only.md

@@ -0,0 +1,67 @@
+# Review Profile: plan_only（方案文档审阅）
+
+<!-- ADR:reviewer-multi-profile -->
+
+> 适用：`review_target=plan_only`，审 planner 输出的方案 markdown（`plans/*.md`）。
+> 本 profile **替代**通用 code.md 清单（方案审阅与代码审阅维度不同）。
+
+## 适用场景
+
+- codeforge 派 planner 出方案后，自动派 reviewer 审方案（ADR:full-chain-auto-review-gating）
+- 用户手动 `/review plan_only`
+- workflow `feature-dev.yaml` 第 2 步「审方案」
+
+**不审什么**：不审代码 diff，只审 `plans/*.md`。pending 列表里若混杂代码 diff，**仅审 plan 文件**并在 Review Summary 标注「跳过 N 个非方案文件」。
+
+## 审阅维度（7 维度，按优先级，逐项过）
+
+| # | 维度 | 权重 | 检查清单 | 反例（必拒） |
+|---|---|---|---|---|
+| 1 | 需求覆盖完整性 | P0 | 每个 PRD/需求点是否有对应实现步骤？有无遗漏的 edge case（边界值 / 异常路径 / 失败回滚）？走 spec 路径时每个 `AC-x` / `PRE-x` 是否在 ADR-Draft Decision 段被引用？ | 需求说「失败要 retry 3 次」方案没提；spec `AC-2` 在 Decision 段没出现 |
+| 2 | 架构合理性 | P0 | 模块边界是否清晰（职责单一）？依赖方向是否合理（无下层依赖上层）？有无引入循环依赖？跨模块的接口契约是否明确？ | 方案让 `lib/` 反向 import `agents/`；新模块同时职责「写存储+发 webhook+解析配置」 |
+| 3 | ADR 覆盖 | P0 | 是否为**关键决策点**创建/引用了 ADR（新增 plugin / workflow / command / tool / agent）？现有 ADR 是否有冲突（如 ADR-A 说禁止 X，方案又用了 X）？ADR-Draft 三段（Context / Options / Decision）是否齐全？ | 新建 plugin 没 ADR；方案与 ADR:apply-hard-gate 冲突未说明 |
+| 4 | Phase 拆分合理性 | P1 | Phase 之间有无强依赖未声明（B Phase 依赖 A 但未注明）？单 Phase 是否过大（涉及 > 50 行改动建议再拆）？Phase 顺序是否反映依赖关系？ | 一个 Phase 改 200 行；Phase 2 实际依赖 Phase 3 结果 |
+| 5 | 接口稳定性 | P1 | 对外接口是否有破坏性变更（公开 API / CLI flag / 配置 schema）？是否需要迁移策略（旧调用方如何过渡）？是否需要 deprecation warning？ | 改 cli flag 名字没迁移路径；改 KH schema 没数据迁移脚本 |
+| 6 | 风险评估完整性 | P1 | 方案是否列了 ≥ 2 条风险？技术风险 / 时间风险 / 依赖风险各一句话标注？每条风险是否有 mitigation？ | 风险表只写「无明显风险」；列了风险没 mitigation |
+| 7 | 可回滚性 | P1 | 改动失败时能否快速回滚？有无 schema 变更 / 数据迁移这种不可逆操作？是否需要 feature flag？ | 改 KH schema 没 rollback 脚本；删旧字段没保留窗口期 |
+
+## 强制章节检查（机审清单 — 等价章节可接受）
+
+按 `docs/agent-templates/planner.md` 模板核对，**允许等价章节命名**：
+
+- [ ] **需求理解**（标题包含「需求」/「理解」/「目标」之一即可，≤ 5 行）
+- [ ] **项目上下文**（标题含「上下文」/「背景」/「现状」之一）
+- [ ] **需求溯源**（仅走 spec 路径强制；标题含「溯源」/「needs」/「acceptance」/「AC」之一）
+- [ ] **实现方案**（标题含「方案」/「实现」/「设计」之一；必须包含 ≥ 3 个子节，分别覆盖：涉及文件、步骤、测试）
+- [ ] **风险与缓解**（标题含「风险」；表格 ≥ 2 行；列名含「缓解」/「mitigation」/「应对」之一）
+- [ ] **ADR-Draft**（标题字面量 `ADR-Draft`，**这一项不放宽**——Context / Options Considered / Decision 三段齐全）
+
+**判定原则**：
+- 章节**内容覆盖**才是关键，**不死磕标题字面量**
+- 仅 `ADR-Draft` 标题保持字面量约束（让 `adr-check` 工具能机械 grep）
+- 任一**内容覆盖**缺失 → REQUEST_CHANGES，反馈格式：「方案缺 X 内容（等价章节也接受，但当前章节内未覆盖）」
+
+## 输出格式调整
+
+`## File-by-File` 改为「方案章节-by-章节」：
+
+```
+## 章节-by-章节
+
+### `## 需求理解`
+- ✓ 复述准确
+
+### `## 实现方案 > ### 步骤`
+- ⚠ Step 3 未声明依赖 Step 2 的输出
+- ✗ Step 5 改了 lib/x.ts 但 `### 涉及文件` 未列出
+
+### `## ADR-Draft`
+- ✗ Decision 段没有引用 `AC-2`（走 spec 路径必须引用）
+```
+
+REQUEST_CHANGES 时必须给「方案哪段」具体修改意见（不是「整体觉得不够」笼统话）。
+
+## 失败回退
+
+- pending 不含 `plans/*.md` → 报「未找到方案文件」，不要硬出审阅
+- 方案 < 20 行（trivial 改动）→ 给 APPROVE 但备注「方案过短，可考虑省略本次 review」

package/workflows/feature-dev.yaml

@@ -2,20 +2,25 @@
 # feature-dev.yaml — CodeForge 第一个真实工作流
 #
 # 触发：用户输入 /ship
-# 流程：planner → coder → reviewer → apply
+# 流程：planner → 审方案 → coder → reviewer → apply
 # 关键步骤（write/apply）默认要求人工审批（除非 autonomy=full）
 # ──────────────────────────────────────────────────────────────
 
 name: feature-dev
-# ADR:workflow-on-decision-branching — 跨 step 反馈循环上限（reviewer→coder REQUEST_CHANGES 反复 goto 兜底）
-max_loops: 3
+# ADR:workflow-on-decision-branching + ADR:full-chain-auto-review-gating
+#   — 跨 step 反馈循环上限。
+#   原 3 是「reviewer→coder REQUEST_CHANGES」单层循环；
+#   新增「reviewer→planner」方案 review 循环后，整体循环层数增加，
+#   max_loops 提升到 5 给两类回退路径足够预算。
+max_loops: 5
 version: 1.0.0
 description: |
   完整的"从需求到落地"流程。串联三个核心 agent：
     1. planner 出方案（自动 smart_search + repo-map）
-    2. coder 按方案 stage 改动到 .codeforge/pending/
-    3. reviewer 审阅 + 跑测试
-    4. 用户审批 → apply 落地工作区 → 自动沉淀经验回 KH
+    2. reviewer 审方案（plan_only，REQUEST_CHANGES 回 planner 重写）
+    3. coder 按方案 stage 改动到 .codeforge/pending/
+    4. reviewer 审代码 + 跑测试
+    5. 用户审批 → apply 落地工作区 → 自动沉淀经验回 KH
 
 trigger: /ship
 
@@ -36,6 +41,31 @@ steps:
         on_error: skip   # KH 不可用不阻塞主流程（C18 同精神）
     on_error: abort
 
+  # ADR:full-chain-auto-review-gating — 软层 Phase 1，方案 review 门控
+  - name: 审方案
+    agent: reviewer
+    description: 审 planner 输出的方案（plans/*.md）合理性，通过后才派 coder 执行
+    inject_context:
+      review_target: plan_only
+      focus:
+        - 需求覆盖
+        - 设计合理性
+        - 风险评估
+        - 涉及文件清单
+    actions:
+      - tool: pending-changes
+        args:
+          action: list
+          status: pending
+        on_error: skip
+    on_decision:
+      APPROVE: continue
+      REQUEST_CHANGES:
+        action: goto
+        target: 规划              # 回 planner 改方案，max_loops=5 兜底
+      BLOCK: abort                # 严重设计问题终止 workflow
+    on_error: abort
+
   - name: 执行
     agent: coder
     description: 严格按方案 stage 改动；测试失败立刻停下汇报
@@ -65,7 +95,7 @@ steps:
       APPROVE: continue           # 进入"落地" step
       REQUEST_CHANGES:
         action: goto
-        target: 执行              # 回到 coder 实现 step（max_loops=3 兜底）
+        target: 执行              # 回到 coder 实现 step（max_loops=5 兜底）
       BLOCK: abort                # 严重问题终止 workflow
     on_error: abort