@chenguangyao/devflow-kit 0.1.43

package/skills/verify/references/self-test-guide.md

@@ -0,0 +1,240 @@
+# verify / self-test-guide
+
+self-test 的 AC 证据书写规则、L1/L2/L3 深度要求、反模式。
+
+---
+
+## 什么是 self-test
+
+> **自测**:由**实现者**(或 QA / tester)按 requirement.md 的 F-ID + tests.md 的 AC,**逐项手工验证**并留证据,证明"声明实现的功能真的按验收标准工作"。
+
+self-test 和自动化单元 / 集成测试**不等价**:
+
+| 维度 | 自动化测试 | self-test |
+| --- | --- | --- |
+| 目标 | 防回归 | 证明 AC 被实现 |
+| 颗粒度 | 细(方法级) | 粗(用户可见的业务层) |
+| 频率 | CI 每次跑 | 每次 change 跑一次 |
+| 运行方 | 机器 | 人 |
+| 输出 | 绿 / 红 | AC 证据清单 |
+
+---
+
+## 什么时候 self-test 必须写
+
+| level | self-test 必须? | 深度要求 |
+| --- | --- | --- |
+| L1 | 可选(简单 bug fix 可跳过) | 最少 1 条 AC 证据 |
+| L2 | **必须** | 每个 F-ID 至少核验 1 条关键 AC;全部 AC 至少 80% 留证据 |
+| L3 | **必须** | 每条 AC 独立核验,100% 留证据 |
+
+---
+
+## self-test 的结构
+
+见 [`report-templates.md`](report-templates.md) 的 self-test 模板。核心是 **每条 AC 一个 section**:
+
+```markdown
+## F-<ID>: <功能名>
+
+### AC<n>: <原 AC 文字>
+
+- **执行方式**: <手段>
+- **执行时间**: <ISO>
+- **输入**: <链接 / 内联>
+- **期望**: <复述期望>
+- **实际**: <实际观察> ✅ | ❌
+- **证据**: <截图 / 日志 / 数据链接>
+```
+
+---
+
+## 每个字段的填写规则
+
+### 执行方式
+
+不要只写"postman"。写:
+
+- 工具(postman / curl / 浏览器 / 脚本 / 其他)
+- 路径("登录 → 后台 → 活动管理 → 发放")
+- 关键参数("并发 10 / 批量 1000 / 特殊用户 X")
+
+好例:
+
+```
+postman 批量调用 /api/v1/coupons/batch-grant,body 使用 reports/evidence/input-1k.json;
+并发 10(postman runner),连续 5 轮
+```
+
+坏例:
+
+```
+按规格执行
+```
+
+### 输入
+
+不要描述,链接:
+
+- 文件附件:`reports/evidence/F-01-AC1-input.json`
+- 截图:`reports/evidence/F-01-AC1-input.png`
+- 如果是 DB 数据:贴建表 SQL / INSERT / 以及数据快照
+
+如果输入有敏感信息(真实用户数据)→ 脱敏后留证据,原始数据不进 repo。
+
+### 期望
+
+复述 AC 原文,不改意思。若 AC 是 GWT 格式,这里写 Then。
+
+### 实际
+
+**实打实写观察到什么**,不要"pass" / "OK"一笔带过。
+
+好例:
+
+```
+response.status = 200
+response.body.grantedCount = 1000
+response.body.failedCount = 0
+response.body.batchId = "b_20260424_14321"
+duration = 3.2s
+DB `coupon_log` 查询:select count(*) where batch_id = 'b_20260424_14321' → 1000
+```
+
+坏例:
+
+```
+pass ✅
+```
+
+### 证据
+
+至少一份,可以是:
+
+- 屏幕截图(`reports/screenshots/`)
+- 响应体 JSON(`reports/evidence/`)
+- 日志 snippet(`reports/logs/`)
+- DB 查询结果(导出 CSV / 截图)
+- 录屏(`reports/videos/`,不进 repo 但留外部链接)
+
+**不要**嵌入超 1MB 图片到 md,用链接。
+
+---
+
+## AC 不满足怎么办
+
+### 完全不满足
+
+- 填 "**实际**" 为实际差距,标 ❌
+- 标题改 `### AC<n>: ... ❌ FAIL`
+- `reports/test-report.md#self-test` section status → partial 或 fail
+- finalize 会拒绝,回退 apply
+
+### 部分满足(功能可用但边缘 case 漏)
+
+- 证据里写清"满足 A / B / C 三条 sub-AC,遗漏 D"
+- frontmatter status = partial
+- 产出 concern,orchestrator 决策:是否降级 scope / 回退 apply / 接受
+
+### 满足但非精确一致
+
+- 实际 response.grantedCount = 1000,但 granted_at 字段没写时间戳
+- 这种"附加字段"问题:标 ✅ WITH CONCERN,在 concerns 里独立列出
+
+---
+
+## L1 / L2 / L3 的深度
+
+### L1 (简单 bug fix)
+
+样例 change: 修复金额计算浮点数精度问题。
+
+self-test 只要核心 AC:
+
+```markdown
+## 修复:金额 19.99 + 19.99 = 39.98(原 39.979999...)
+
+- **执行方式**:执行脚本 `node test-amount.js`
+- **输入**:多组金额
+- **期望**:所有组都精确到 2 位小数
+- **实际**:39.98,4.21,100.00(10 组全对)
+- **证据**:`reports/evidence/l1-fix.log`
+```
+
+### L2 (新功能 / 中型修改)
+
+每个 F-ID 至少核验 1 条关键 AC,异常分支抽样核验(不要求每条 AC 都有独立 section,但关键的都要有)。
+
+### L3 (大改 / 系统级)
+
+**每条 AC 独立 section**,全覆盖。包括:
+
+- Happy path
+- 每个已定义的异常分支
+- 每个 NFR(性能 / 并发 / 可用性)都有对应测试
+- 跨系统集成场景
+
+L3 的 self-test 经常 30-60 个 AC,要 1-2 天跑完,这是正常的。
+
+---
+
+## 协同 vs 独跑
+
+- **实现者自跑**:最基础,覆盖所有 AC
+- **第二人复跑**(L3 推荐):另一工程师或 QA 按同样的 self-test 章节独立跑一次,填独立证据
+- **QA 结构化测试**(L3 强推):QA 按 tests.md 设计更完整的 case(超出 AC),self-test 引用 QA 报告链接即可
+
+---
+
+## 反模式
+
+### "通过了"式 self-test
+
+```markdown
+## F-01
+- AC1: pass ✅
+- AC2: pass ✅
+- AC3: pass ✅
+```
+
+finalize 会拒绝。证据不足等于没做。
+
+### 时间戳造假
+
+verify 开始时间戳(frontmatter `ts`)明显晚于最后一次代码 commit 才可信。用"测试执行时间"补:"**执行时间**"字段不能早于 commit。
+
+### 截图造假
+
+用 OS 自带截图工具 + 窗口时间戳,或用 dev tool / postman 截图(有明确时间)。过于裁剪的截图不可信。
+
+### 只测 Happy Path
+
+edge-case-catalog 里的 8 个维度至少扫到 3-4 个(L2)/ 8 个(L3)。
+
+### 用单测跑通就写 self-test pass
+
+单测证明"代码路径正确",不等于"业务 AC 满足"。self-test 必须在集成环境、真实数据、端到端路径上跑。
+
+### AC 没满足也标 pass
+
+- 测出 bug → 先回退 apply 修,再重跑 self-test
+- 不能"pass 先过,bug 后修" → 这就是典型 review 拦不住、上线炸的原因
+
+---
+
+## 和 tests.md 的关系
+
+- tests.md 是**独立的测试设计**,可以比 AC 多(为了覆盖率)
+- self-test 只需覆盖 AC 这一核心子集;tests.md 里"衍生场景"的 TC 不必都跑 self-test,但要有自动化 / 集成测试覆盖
+- finalize 时会 cross-check:self-test 里声明 pass 的 AC 必须真在 tests.md 里对应上
+
+---
+
+## 工具建议
+
+- 截图:原生 OS 工具 + 时间戳水印
+- API 验证:Postman / Hoppscotch / curl + jq
+- DB 验证:DBeaver / TablePlus 查询结果截图 + SQL 原文
+- 前端 UX 验证:DevTools Network + Console + Screenshot
+
+所有工具产出**导出到 `reports/evidence/`**,不依赖"我本地有截图"。

package/skills/verify/references/verify-rollback-map.md

@@ -0,0 +1,247 @@
+# verify / verify-rollback-map
+
+verify 失败时回退到哪个 phase,及审计格式。
+
+---
+
+## 核心原则
+
+verify 拦到的是**事实问题**(测试 fail、NFR 不达、AC 未满足):
+
+- 不在 verify 阶段"修",回退到有能力修的 phase
+- 每次回退留审计(iterations[] 加一条)
+- 修复后必须重回 verify 重跑全部必需 report
+
+---
+
+## 回退决策表
+
+| 失败类型 | 根因层次 | 回退到 |
+| --- | --- | --- |
+| 单元测试红 | 代码 bug | apply |
+| 集成测试红(组件间契约问题) | 代码 bug(常)/ 设计误区(偶) | apply(首先)→ 如几轮修不好回 tech-spec |
+| E2E 红(整条链路问题) | 代码 / 配置 / 部署 | apply(先排) |
+| Smoke 红(核心用户路径) | 代码 / UX | apply |
+| Self-test AC 未满足 | 代码未实现 / 实现跑偏 | apply |
+| Self-test 发现 AC 本身含糊 | 需求问题 | requirement-analysis |
+| perf 不达 NFR,代码可优化 | 代码性能 | apply |
+| perf 不达 NFR,架构瓶颈 | 架构设计 | tech-spec |
+| perf 不达 NFR,NFR 定得过严 | 需求层面 | requirement-analysis(调 NFR) |
+| Regression 红(本次无关) | 历史遗留 | 不阻塞,但记 ISSUE 和 concern |
+| 安全 / 合规扫描红 | 代码 / 设计 / 依赖 | 看具体条目 |
+| Flaky test | 测试本身 / 环境 | test-spec 修测试,或本次审计跳过 |
+
+---
+
+## 决策细则
+
+### "测试红,代码 bug" → apply
+
+```
+devflow verify --state fail --reason="unit-test T-12 失败:null pointer"
+devflow apply --task 12 --resume   # or 新 task 修
+# 修完后
+devflow verify                     # 重新运行,或只跑 devflow test unit
+```
+
+iterations[] 加一条:
+
+```json
+{
+  "id": 2,
+  "triggeredAt": "verify:unit-test",
+  "rollbackTo": "apply",
+  "reason": "unit-test T-12 nullpointer 异常分支未处理",
+  "affectedTasks": ["T-12"],
+  "durationMinutes": 45
+}
+```
+
+### "perf 不达标,架构问题" → tech-spec
+
+**判定"架构问题 vs 代码问题"**:
+
+- 代码问题:profiler 能定位到 hot spot,优化算法 / 数据结构 / 连接池能解
+- 架构问题:单机瓶颈、需要拆分、需要缓存 / 队列、需要分片
+
+架构问题 → 回退 tech-spec:
+
+- 更新 design.md 的"技术方案"和"关键决策"
+- 加一个 ADR 记"为什么原设计不够"
+- 重新 plan / apply / verify
+
+### "AC 含糊 / 原 NFR 定得不切实际" → requirement-analysis
+
+verify 执行时发现:
+
+- AC 某条执行时才发现两种可能的解读(因歧义)
+- 压测发现 P99 ≤ 50ms 根本不可能(理论下界都 100ms),NFR 定得不切实际
+
+这属于需求问题:
+
+```bash
+devflow verify --state fail --reason="NFR P99≤50ms 不可达,技术下界 80ms"
+devflow requirement-analysis --round-3 --reason="调 NFR"
+```
+
+新一轮 Q&A 后,NFR 修改为"P99 ≤ 150ms"(或增加资源预算换低延迟)。
+
+### "回归测试红,和本次无关" → 审计跳过
+
+```bash
+# 本次 slug 没动这块代码
+devflow verify --accept-regression-fail --reason="regression T-foo 早于本 slug 1 周就挂,已有 ISSUE-123,不阻塞"
+```
+
+- state.json 记录 "accepted_regression_fail"
+- 报告 frontmatter status = partial,或 regression-test.md 单独 fail(不影响整体 finalize)
+- ISSUE 要真实存在(review 会核对)
+
+### "Self-test AC 未满足,实现 scope 有漏"
+
+具体看漏得多严重:
+
+| 漏的程度 | 处置 |
+| --- | --- |
+| 1-2 条次要 AC(可延期) | 申请 scope 调整,回 requirement 砍 scope 或加迭代 |
+| 核心 AC 漏 | 回 apply 补 |
+| 大半 AC 漏 | 回 plan(plan 本身漏了)或 tech-spec(设计就不完整) |
+
+---
+
+## 审计格式
+
+每次 verify 失败,`state.json` 加一条 iteration:
+
+```json
+{
+  "iterations": [
+    {
+      "id": 3,
+      "triggeredAt": "verify:perf-test",
+      "rollbackTo": "tech-spec",
+      "reason": "P99=320ms 不达 NFR=200ms,profiler 显示数据库连接池瓶颈",
+      "evidence": "reports/perf-test.md#结果",
+      "affectedTasks": [],
+      "affectedDocs": ["design.md", "delta/coupon-batch-grant.md"],
+      "resolvedAt": null
+    }
+  ]
+}
+```
+
+修好后 `resolvedAt` 填入时间戳。
+
+---
+
+## 反模式
+
+### "测试挂了再跑两次就过"
+
+禁止。测试挂了要修,不是"多跑几次碰运气"。真 flaky 要 quarantine 并 ISSUE。
+
+### "perf 差一点点,在 verify 里微调 NFR"
+
+禁止。NFR 是 requirement 的一部分,调 NFR 必须走 requirement-analysis。
+
+### "跳过 perf 直接 deliver"
+
+verify 硬闸拦住。要跳过必须 `--accept-missing-nfr` 并给 justification + 补偿计划(canary 验证 / 上线后监控加强)。
+
+### "self-test AC 3 条漏,写 partial 但 finalize 接受"
+
+finalize 里 status=partial 默认会阻止 deliver。orchestrator 审计后可以**有条件**放行(如果漏的 AC 被明确标记为"P2,下迭代"),但必须在 state 里记。
+
+---
+
+## 回退后的重跑规则
+
+修复后不能只跑挂的那条报告:
+
+| 修复影响范围 | 需要重跑 |
+| --- | --- |
+| 1 个方法的 bug(apply T-N) | T-N 所在模块的 unit + smoke |
+| 多模块修复 | unit + integration + smoke |
+| 架构级(tech-spec revise) | 全套必需报告 |
+| 数据 / DDL 修复 | integration + e2e + self-test |
+| 性能优化 | perf + smoke(确认没退化功能) |
+
+**原则**:越上游的回退,重跑越全。
+
+---
+
+## verify.md 的聚合结构
+
+```markdown
+# 验证汇总 — <slug>
+
+## 结论
+
+**状态**: completed | rolled-back | blocked
+**最终结论**: ready for deliver
+
+## 报告清单
+
+| 类型 | 状态 | 链接 | 关键指标 |
+| --- | --- | --- | --- |
+| unit | pass | [reports/test-report.md#unit](reports/test-report.md#unit) | 243/243, cov 86% |
+| integration | pass | [reports/test-report.md#integration](reports/test-report.md#integration) | 52/52 |
+| e2e | pass | [reports/test-report.md#e2e](reports/test-report.md#e2e) | 18/18 |
+| smoke | pass | [reports/test-report.md#smoke](reports/test-report.md#smoke) | 成功路径已打通 |
+| self-test | pass | [reports/test-report.md#self-test](reports/test-report.md#self-test) | 12/12 AC |
+| perf | pass | [reports/test-report.md#perf](reports/test-report.md#perf) | P99=180ms / NFR=200ms |
+
+## 本次迭代
+
+- 迭代 #1: verify → apply(T-12 nullpointer 修复)
+- 迭代 #2: verify → tech-spec(perf P99 超标,加连接池)
+- 迭代 #3: verify 通过
+
+## 残留 concern
+
+- REG-04 在 regression 套件红,与本 slug 无关,追踪 ISSUE-789
+
+## 下一步
+
+`devflow deliver`
+```
+
+---
+
+## 和 orchestrator 的交互
+
+verify finalize 后产出 STATUS block:
+
+```
+---STATUS---
+result: DONE
+verifyStatus: pass
+nextAction: devflow deliver
+---END_STATUS---
+```
+
+verify fail 且回退:
+
+```
+---STATUS---
+result: NEEDS_INPUT
+verifyStatus: fail
+rollbackTo: apply
+rollbackReason: unit-test T-12 nullpointer
+nextAction: devflow apply --task 12 --resume
+---END_STATUS---
+```
+
+orchestrator 根据 rollbackTo 自动切换 phase,不需用户干预(用户可接管或跳过)。
+
+---
+
+## 最大反模式:verify 阶段偷偷改 design.md / plan.md
+
+verify 不允许写回上游产物。想改 → 走回退流程。直接改会导致:
+
+- archive 时 spec delta 和实际行为不一致
+- 下一个 slug 的 requirement / design 基于错误 spec 展开
+- 审计链断裂,事后难追溯
+
+**verify 只产出 reports/ + verify.md,不动任何上游 md**。

package/src/cli/commands/_helpers.js

@@ -0,0 +1,108 @@
+'use strict';
+const fsSync = require('fs');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const change = require('../../core/change.js');
+const state = require('../../core/state.js');
+const workflow = require('../../core/workflow.js');
+const workflowCheck = require('../../core/workflow-check.js');
+const templates = require('../../templates/index.js');
+
+async function resolveSlug(root, flags = {}, positional = []) {
+  if (!fsSync.existsSync(paths.devflowDir(root))) {
+    log.error('not a devflow project. run "devflow init" first.');
+    return null;
+  }
+  const slug = flags.slug || positional[0] || (await change.getCurrent(root));
+  if (!slug) {
+    log.error('no change found. run "devflow ingest <input>" or "devflow new <slug>".');
+    return null;
+  }
+  return slug;
+}
+
+async function loadStateOrFail(root, slug) {
+  try { return await state.read(root, slug); }
+  catch (e) {
+    log.error(`cannot read state for ${slug}: ${e.message}`);
+    return null;
+  }
+}
+
+async function writePhaseArtifact(root, slug, st, name, templateFile, vars) {
+  const tpl = await templates.load(templateFile);
+  const body = templates.render(tpl, {
+    slug,
+    title: st.title || slug,
+    date: new Date().toISOString().slice(0, 10),
+    ...vars,
+  });
+  if (await change.hasArtifact(root, slug, name)) {
+    log.warn(`${name} already exists (skipping write; edit manually).`);
+    return false;
+  }
+  const file = await change.writeArtifact(root, slug, name, body);
+  log.ok(`${name}: ${file}`);
+  return true;
+}
+
+function blockWorkflowStep(root, st, slug, stepId, commandName) {
+  try {
+    workflow.assertStepAllowed(st.workflow, stepId);
+    return false;
+  } catch (e) {
+    if (e.code === 'WORKFLOW_NOT_CONFIRMED') {
+      log.error(`${commandName} blocked: change workflow is not confirmed.`);
+      log.dim(`run: devflow flow card --slug=${slug} --json`);
+      log.dim(`script preflight: devflow flow check --slug=${slug} --json`);
+      log.dim(`then, if ok=true: devflow flow confirm --slug=${slug}`);
+      const result = workflowCheck.checkWorkflow(root, slug, st);
+      if (result.ok && result.confirmationCard) renderWorkflowConfirmationCard(result.confirmationCard);
+      process.exitCode = 1;
+      return true;
+    }
+    if (e.code === 'WORKFLOW_STEP_BLOCKED') {
+      log.error(`${commandName} blocked by workflow gate: currentStep=${e.currentStep}, requested=${stepId}.`);
+      log.dim(`run the current workflow step first, or inspect: devflow flow explain --slug=${slug}`);
+      process.exitCode = 1;
+      return true;
+    }
+    throw e;
+  }
+}
+
+function completeWorkflowStep(st, stepId) {
+  if (!st.workflow) return false;
+  return workflow.completeStep(st.workflow, stepId);
+}
+
+function printWorkflowSelectionGuidance(slug) {
+  log.dim(`workflow picker: devflow flow picker --slug=${slug} --json`);
+  log.dim(`selection:       devflow flow apply-selection --slug=${slug} --selection='<json>' --json`);
+  log.dim(`card:            devflow flow card --slug=${slug} --json`);
+  log.dim(`check:           devflow flow check --slug=${slug} --json`);
+  log.dim(`confirm:         devflow flow confirm --slug=${slug}`);
+}
+
+function renderWorkflowConfirmationCard(card) {
+  log.raw(card.title || '确认本次 workflow');
+  if (card.question) log.raw(`question: ${card.question}`);
+  const activeSteps = (card.steps || [])
+    .filter((step) => step.status !== 'disabled')
+    .map((step) => step.id);
+  log.raw(`steps: ${activeSteps.join(' -> ') || '-'}`);
+  if (card.primaryAction) log.raw(`confirm: ${card.primaryAction.command}`);
+  for (const action of card.secondaryActions || []) {
+    log.raw(`${action.id}: ${action.command}`);
+  }
+}
+
+module.exports = {
+  resolveSlug,
+  loadStateOrFail,
+  writePhaseArtifact,
+  blockWorkflowStep,
+  completeWorkflowStep,
+  printWorkflowSelectionGuidance,
+  renderWorkflowConfirmationCard,
+};