@andyqiu/codeforge 0.3.13 → 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/scripts/postinstall.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * scripts/postinstall.mjs — npm postinstall 自动全局安装入口
+ *
+ * 设计意图（ADR: npm-postinstall-auto-global）：
+ *   - npm install -g @andyqiu/codeforge 完成后自动等效 `codeforge install --global`
+ *   - 本地 install / devDep install / pnpm·yarn·bun 全局安装 → fail-closed 不触发
+ *   - 任何失败均 exit 0，绝不阻断包管理器主流程
+ *
+ * 包管理器矩阵（详见 ADR Decision 段）：
+ *   npm  -g  ✅  唯一保证注入 npm_config_global=true 的包管理器 → 触发安装
+ *   pnpm     ❌  v11+ 官方声明不传递 npm_config_*；fail-closed + stderr 提示
+ *   yarn     ❌  classic/berry 均不传递 npm_config_*；fail-closed + stderr 提示
+ *   bun      ❌  行为未文档化；fail-closed + stderr 提示
+ *   unknown  ❌  无 user_agent 信号；静默 exit 0
+ *
+ * 短路条件（任一命中即静默 exit 0）：
+ *   - CODEFORGE_SKIP_POSTINSTALL=1   用户/CI 显式禁用
+ *   - CI=true 且未设 CODEFORGE_POSTINSTALL_IN_CI=1   避免污染 CI ~/.config
+ *   - 未支持的 process.platform（仅 linux/darwin/win32 通过）
+ */
+
+import { spawnSync } from "node:child_process"
+import * as path from "node:path"
+import * as url from "node:url"
+
+const __filename = url.fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const REPO_ROOT = path.resolve(__dirname, "..")
+
+// ────────────────────────────────────────────────────────────────────
+// 工具函数
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * 解析 npm_config_user_agent，识别包管理器。
+ * 所有主流包管理器都设此变量，格式形如：
+ *   "npm/10.0.0 node/v20.0.0 linux x64 workspaces/false"
+ *   "pnpm/9.0.0 npm/? node/v20.0.0 linux x64"
+ *   "yarn/1.22.0 npm/? node/v18.0.0 linux x64"
+ *   "bun/1.0.0 npm/? node/v20.0.0 linux x64"
+ */
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent || ""
+  if (ua.startsWith("npm/")) return "npm"
+  if (ua.startsWith("pnpm/")) return "pnpm"
+  if (ua.startsWith("yarn/")) return "yarn"
+  if (ua.startsWith("bun/")) return "bun"
+  return "unknown"
+}
+
+function warn(msg) {
+  // 写 stderr 避免污染期望干净 stdout 的脚本
+  process.stderr.write(`[codeforge postinstall] ${msg}\n`)
+}
+
+function exitOk(reason) {
+  // 调试/测试可读：CODEFORGE_POSTINSTALL_DEBUG=1 时打印短路原因到 stderr
+  if (process.env.CODEFORGE_POSTINSTALL_DEBUG === "1") {
+    process.stderr.write(`[codeforge postinstall] skip: ${reason}\n`)
+  }
+  process.exit(0)
+}
+
+// ────────────────────────────────────────────────────────────────────
+// 主流程（全局 try/catch 兜底，任何异常 → exit 0）
+// ────────────────────────────────────────────────────────────────────
+
+try {
+  // ── 短路 S1: 用户/CI 显式禁用 ──
+  if (process.env.CODEFORGE_SKIP_POSTINSTALL === "1") {
+    exitOk("CODEFORGE_SKIP_POSTINSTALL=1")
+  }
+
+  // ── 短路 S2: CI 环境默认跳过 ──
+  if (process.env.CI === "true" && process.env.CODEFORGE_POSTINSTALL_IN_CI !== "1") {
+    exitOk("CI=true (set CODEFORGE_POSTINSTALL_IN_CI=1 to opt in)")
+  }
+
+  // ── 短路 S3: 未支持平台 ──
+  const supportedPlatforms = ["linux", "darwin", "win32"]
+  if (!supportedPlatforms.includes(process.platform)) {
+    exitOk(`unsupported platform: ${process.platform}`)
+  }
+
+  // ── 主决策 ──
+  const pm = detectPackageManager()
+  const isGlobal = process.env.npm_config_global === "true"
+
+  // D1: npm + global → 触发安装
+  if (pm === "npm" && isGlobal) {
+    const cli = path.join(REPO_ROOT, "bin", "codeforge.mjs")
+    const args = [cli, "install", "--global", "--skip-build"]
+    const env = { ...process.env, CODEFORGE_FROM_POSTINSTALL: "1" }
+    const r = spawnSync(process.execPath, args, {
+      stdio: "inherit",
+      env,
+    })
+    if (r.status !== 0) {
+      warn(
+        `自动全局安装失败（exit code ${r.status ?? "unknown"}）。` +
+          `请手动执行：codeforge install --global`,
+      )
+    }
+    // 无论成功失败，都 exit 0，不阻断 npm
+    process.exit(0)
+  }
+
+  // D2: 识别为 pnpm/yarn/bun → fail-closed + 用户可见提示
+  if (pm === "pnpm" || pm === "yarn" || pm === "bun") {
+    warn(
+      `检测到使用 ${pm}，无法自动确定是否为全局安装；` +
+        `如果你刚才跑的是 \`${pm} global add\` / \`add -g\`，` +
+        `请手动执行：codeforge install --global`,
+    )
+    process.exit(0)
+  }
+
+  // D3: 其它（npm 但非 global / unknown pm / 无 user_agent）→ 静默 exit 0
+  exitOk(`no-op (pm=${pm}, global=${isGlobal})`)
+} catch (e) {
+  // 任何未捕获异常都不向 npm 抛错
+  warn(`unexpected error: ${e && e.message ? e.message : String(e)}`)
+  process.exit(0)
+}

package/skills/weighted-dimensions/SKILL.md

@@ -100,9 +100,16 @@ weighted_score = 0.8×0.30 + 0.5×0.25 + 0.3×0.20 + 0.6×0.15 + 0.2×0.10
 
 **Functional 常见打分依据**：
 - 0.0：只说了"做个东西"，完全不知道做什么
+- 0.2：有隐约方向但目标群体/核心输出不明（如"做个管理工具"）
+- 0.4：目标群体 + 核心使用场景已清晰，但核心功能边界还未明确（如"给老板看指标的看板"，知道谁用/做什么，但不知道哪些指标/什么展示形式）
 - 0.5：知道大方向（"做个导出"），但不知道输出形式、流程
 - 1.0：输入输出明确，核心流程可描述，用户能说出 Job
 
+> **初轮信息密度校准**（方案 A 补充）：Phase A 初轮评分反映的是**信息密度**，不是需求质量高低。
+> 用户首轮说出「目标群体 + 核心 Job」即可给 0.4，不要因为细节不足降到 0.2。
+> 0.2 应保留给真正「只有一个动词、连做什么都不清楚」的极端情形。
+> 典型校准案例：「做看板让老板看指标」= 目标群体（老板）+ 核心输出（看板/指标）已给出 → Functional ≥ 0.4。
+
 **Edge Cases 常见打分依据**：
 - 0.0：完全没讨论过边界
 - 0.5：讨论了 1-2 个正常 happy path，无异常路径

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