dev-playbooks-cn 1.0.0

package/skills/devbooks-delivery-workflow/references//344/272/244/344/273/230/351/252/214/346/224/266/345/267/245/344/275/234/346/265/201.md

@@ -0,0 +1,256 @@
+# 交付验收工作流（Design → Plan → Trace → Verify）
+
+> 本文件为“开发作战手册”的流程骨架，面向单人/AI 代理式开发。
+
+目录约定（协议无关）：
+- 当前真理源：`<truth-root>/`
+- 单次变更包：`<change-root>/<change-id>/`（proposal/design/tasks/specs delta/verification/evidence）
+- 归档：把 delta 合并进 `<truth-root>/`，并把变更包移入归档区（如果你的上下文协议提供 archive 命令，优先用命令）
+
+> 目标：让“完成交付”具备可执行、可追溯、可争议处理的客观判据，避免出现“测试全绿但编码计划仍大量未完成”的失真状态。
+
+---
+
+## 0) 角色隔离与测试完整性（强制）
+
+- Test Owner 与 Coder 必须独立对话/独立实例；允许并行但不得共享上下文。
+- Test Owner 只基于设计/规格产出 tests/verification，并先跑出 **Red** 基线；失败证据记录到 `<change-root>/<id>/evidence/`（推荐用 `change-evidence.sh <id> -- <test-command>` 采集落盘）。
+- Coder 只按 tasks 实现并跑闸门；**禁止修改 tests/**。如需调整测试，必须交还 Test Owner 决策与改动。
+
+## 0.1) 结构质量闸门（强制）
+
+- 若出现“代理指标驱动”的要求（行数/文件数/机械拆分/命名格式），必须评估对内聚/耦合/可测试性的影响。
+- 触发风险信号时必须“停线”：记录为决策问题并回到 Design/Proposal 处理，不得直接执行。
+- 质量闸门优先级：复杂度、耦合度、依赖方向、变更频率、测试质量 > 代理指标。
+
+## 1) `tests/` 里可以放什么？
+
+`tests/` 的本质是**可执行的验收锚点（Executable Acceptance Anchors）**：任何能被机器稳定判定 Pass/Fail 的东西，都可以（也应该）进入自动化链路。
+
+### 1.1 推荐放在 `tests/` 的内容（强约束/可回归）
+
+1. **自动化测试（Behavior / Contract）**
+   - 单元测试（unit）：纯逻辑、无 IO
+   - 集成测试（integration）：多组件协作，但尽量使用 fake/mocked 依赖
+   - 端到端测试（e2e）：最小关键链路（可离线）
+   - 契约测试（contract）：schema、事件信封、API 输入输出形状、向后兼容等
+2. **架构适配函数（Architecture Fitness Functions）**
+   - 依赖方向、分层边界、禁止循环依赖、模块职责边界等（本质上也是“测试”，只是验证结构而非行为）
+
+### 1.2 不推荐直接放在 `tests/` 的内容（但可以被自动化执行）
+
+3. **静态检查（Static Analysis / SAST / Type Check）**
+   - 这类通常以 `ruff/mypy/eslint/tsc/bandit/semgrep` 等“命令”形态存在，更适合在 CI 的独立步骤或 `scripts/` 中运行。
+   - 也可以“包一层”让它在 `pytest` 中失败（例如跑命令并断言退出码），但要谨慎：会拖慢测试、让输出不如原生工具清晰、并可能与 IDE/CI 并行策略冲突。
+
+### 1.3 不应放在 `tests/` 的内容（不是机器可判定）
+
+4. **明确的人工验收步骤（Manual Acceptance）**
+   - 例如 UI 编排/可用性、交互路径、视觉/文案一致性、产品体验等。
+   - 这些应以**清单（checklist）/验收脚本**放在“本次变更包”的验证文档中（例如 `<change-root>/<id>/verification.md`），并在追溯矩阵里作为“人工锚点”记录责任人和结论；仅当它属于对外公开的用户/运维文档时，才同步到 `docs/`。
+
+结论：**自动化测试 + 架构适配函数**天然适合放进 `tests/`；**静态检查**更推荐独立跑；**人工验收**不应放在 `tests/`。
+
+对外 docs vs 开发使用说明（你的偏好）：
+- `docs/` 建议只放“项目对外说明/用户可见说明”
+- “开发使用说明/AI 工作流/验收追溯/人工验收清单”优先放在变更包里（例如 `<change-root>/<id>/verification.md`），避免污染对外文档
+
+---
+
+## 2) 验收方式的 MECE 划分（所有可用于“交付验收”的方式）
+
+用“谁来当裁判（Oracle）”作为 MECE 维度，可把所有验收方式完整覆盖且互斥：
+
+### A. 机器裁判（Automated / Deterministic）
+
+> 判据由机器给出，稳定可重复，最终输出为 Pass/Fail。
+
+- 动态测试：unit/contract/integration/e2e/snapshot/golden-master/property-based
+- 架构适配函数：依赖方向、边界、分层、禁止循环、禁用包引用等
+- 静态检查：lint、type check、SAST、依赖/许可证/secret 扫描、schema 校验、API breaking change 检测
+- 构建与发布校验：build、打包、镜像构建、迁移脚本校验、配置/模板渲染校验
+- 自动化运行时校验：smoke test、健康检查、最小回放、离线回归包 determinism（前提是环境可控）
+
+### B. 人工裁判 + 工具证据（Hybrid / Evidence-Assisted）
+
+> 工具产出客观证据，但是否通过仍需要人判断/签字。
+
+- 性能/成本基准：benchmark 结果、成本报表、容量评估（通常需要阈值讨论与取舍）
+- 安全评审：扫描结果的 triage、威胁建模复核（不是“0 告警=通过”这么简单）
+- 可观测性验收：仪表盘/告警规则检查、SLO 报表评审（证据客观，但是否达标需解释上下文）
+- UX 视觉/交互证据：截图对比、录像、埋点漏斗（证据在，是否满意仍是主观决策）
+
+### C. 纯人工裁判（Manual / Judgment-Based）
+
+> 主要依赖人类判断，难以完全形式化为机器判据。
+
+- UI/交互验收、内容与信息架构评审、可用性走查
+- 产品/业务验收：需求理解、边界条件、例外处理是否“符合预期”
+- 合规/流程验收：权限、审计、合规文本、法务条款、发布流程签核
+
+你原来的“四类”：自动化测试 / 架构适配函数 / 静态检查 / 人工验收步骤，是对 A 与 C 的一个实用切分；严格 MECE 的“裁判视角”会把它扩展成 A/B/C 三类，覆盖面更完整，也更不易争议。
+
+---
+
+## 3) 测试应该基于设计文档还是编码计划？
+
+### 3.1 默认原则（推荐）
+
+- **对外可感知的需求/约束**：测试应来自**设计文档（Design Doc）**，因为设计文档错误率更低、且是“what”的权威来源。
+- **编码计划（Implementation Plan）**负责“how”：拆任务、排顺序、选方案、选模块、落地步骤。它不应成为对外行为的唯一裁判。
+
+## 4) 适用于大型项目的 DoD（Definition of Done，MECE）
+
+每次变更必须至少声明覆盖到哪些闸门；缺失项必须写原因与补救计划：
+
+- A. 行为（Behavior）：unit/integration/e2e（按项目类型取最小集）
+- B. 契约（Contract）：OpenAPI/Proto/Schema/事件 envelope + contract tests
+- C. 结构（Structure）：架构适配函数（依赖方向/分层/禁止循环/模块边界）
+- D. 静态与安全（Static/Security）：lint/typecheck/build + SAST/secret scan
+- E. 证据（Evidence，按需）：截图/录像/报告（UI、性能、安全 triage）
+
+## 5) “推翻旧设计/旧测试”如何优雅处理（当前真理 vs 历史）
+
+- 权威定义：`<truth-root>/` 是“当前真理”；历史变更包是审计记录
+- 新变更推翻旧行为：在新变更包中更新 specs 与 tests，并在 proposal 中标注 `Supersedes/Breaking`；不要回改历史归档来“统一口径”
+
+### 3.2 什么时候可以用“编码计划生成测试”？
+
+只有在以下条件同时满足时才建议：
+
+- 该计划条目属于**纯工程实现约束**（例如“必须有幂等键”“必须有迁移脚本”“必须有架构边界约束”），且不会改变设计的对外语义；
+- 或者你愿意把它升级为**规范**：把计划条目提炼成 ADR/设计补充，进入设计文档的“验收标准”，再写测试。
+
+否则，“用编码计划写测试”容易导致：**计划写错 → 测试也跟着错 → 代码在错误的目标上自洽全绿（False Green）**。
+
+结论：**设计文档是验收真理源（Golden Truth）**；编码计划可以驱动“工程约束类”测试，但要么升级进设计验收，要么明确标注为“工程内部验收”。
+
+---
+
+## 4) 追溯矩阵（Traceability Matrix）：把“完成”变成可计算
+
+追溯矩阵解决两个关键问题：
+
+1. “这条计划到底怎么验收？”（每个计划项必须绑定一个验收锚点）
+2. “测试全绿为什么还没做完？”（因为有计划项没锚点、或锚点是人工/混合未完成）
+
+### 4.1 最小字段模板（可复制到任意版本/任意项目）
+
+| Design AC ID | 设计验收点（原文/摘要） | Plan ID | 验收方式(A/B/C) | 验收锚点（测试ID/命令/Checklist） | 状态 | 备注 |
+|---|---|---|---|---|---|---|
+| AC-01 | … | MP1.3 | A | T0014-I-05 / `pytest ...` | DONE | … |
+
+### 4.2 DoD（Definition of Done）
+
+- **Plan ID 只有在其绑定的验收锚点为 PASS（或人工签核为通过）时，才允许标记 DONE。**
+- 任何未绑定锚点的 Plan 项，状态只能是：`UNSCOPED / DEFERRED / TODO(缺锚点)`，不能被"测试全绿"自动宣告完成。
+
+### 4.3 端到端正确性检查清单（End-to-End Correctness Checklist）
+
+> 确保从需求 → 设计 → 测试 → 实现 → 归档的完整追溯链不断裂。
+
+**阶段间传递检查（必须逐条验证）**：
+
+| 检查点 | 验证问题 | 失败时行动 |
+|--------|----------|------------|
+| **proposal → design** | 设计是否覆盖所有提案目标？是否遗漏 Non-goals 边界？ | 补充设计、回退到 proposal 修订 |
+| **design → specs** | 对外行为/契约变化是否都有对应的 spec delta？ | 补 spec delta |
+| **design → tasks** | 任务是否覆盖所有 AC？是否有"无来源"的任务？ | 补 AC 映射、或将任务升级进设计 |
+| **tasks → tests** | 每个 AC 是否有对应的测试？测试是否基于设计而非实现？ | 补测试、检查测试来源 |
+| **tests → code** | 代码是否通过所有测试？是否有"改测试迁就代码"的行为？ | 修复代码、恢复测试原貌 |
+| **code → archive** | 归档前是否包含所有证据？specs 是否已合并到真理源？ | 补证据、运行 spec gardener |
+
+**追溯完整性检查**：
+
+- [ ] 每个 AC 都能追溯到：`AC-xxx → Requirement/Scenario → Test IDs → Evidence`
+- [ ] 没有"孤儿测试"（测试存在但无对应 AC 或设计来源）
+- [ ] 没有"孤儿任务"（任务存在但无对应设计来源）
+- [ ] 没有"无证据的 DONE"（标记完成但无测试通过或人工签核证据）
+
+**归档前最终检查**：
+
+```bash
+# 建议运行以下检查（如有脚本支持）
+change-check.sh <change-id> --mode strict --project-root "$(pwd)" --change-root <change-root> --truth-root <truth-root>
+```
+
+- [ ] 所有 A 类验收锚点（tests/静态检查/build）通过
+- [ ] 所有 B/C 类验收锚点（人工/混合）已签核并有证据
+- [ ] 追溯矩阵无 `TODO(缺锚点)` 状态
+- [ ] `evidence/` 目录包含 Red 基线证据和 Green 通过证据
+
+---
+
+## 5) 标准流程（固化版）
+
+### Step 0：确定本次交付范围（强制）
+
+- 选择要交付的 Phase/里程碑（MVP/Beta/Prod）
+- 明确非目标（Non-goals）
+- 产物：设计文档中的范围声明 + 版本号
+
+### Step 1：创建设计文档（Design Doc）
+
+- 写清楚：目标、非目标、关键决策、验收标准（Acceptance Criteria）
+- 把“对外语义/不可变约束（invariants）”写成可测试语言
+
+### Step 2：创建编码计划（Implementation Plan）
+
+- 任务分解为可执行的 Plan 项（例如 `MPx.y`）
+- 每个 Plan 项必须声明：
+  - Deliverables（交付物）
+  - 影响范围（模块/文件）
+  - 验收方式（A/B/C）与候选验收锚点（测试ID/命令/Checklist）
+
+### Step 3：建立追溯矩阵（Traceability Matrix）
+
+- 将**设计验收点（AC）**逐条映射到：Plan 项 + 验收锚点
+- 发现两类缺口立即处理：
+  1. **设计有验收点但无锚点** → 补测试/补静态检查/补 checklist
+  2. **计划有任务但无设计来源** → 选择：降级为 DEFERRED，或升级进设计（ADR）再验收
+
+### Step 4：编写/更新验收锚点（Verification Anchors）
+
+- 产出 A 类锚点（机器裁判）：根据设计验收点补齐/更新 `tests/`、架构适配函数、静态检查/构建校验命令（不绑定具体实现细节）。
+- 若是重构/迁移/存量系统：优先补 **Snapshot/Golden Master** 测试作为安全网。
+- 产出 B/C 类锚点（非机器）：将无法稳定自动化的验收项写入 checklist，并定义“证据要求”（截图/录像/看板链接/日志等）。
+- 同源隔离：验收锚点只从设计/规格抽取，不参考编码计划（避免“按计划出题、按计划答题”的自证闭环）。
+- 回填追溯矩阵：把每条设计验收点与 Plan 项对应的锚点 ID/路径补齐，确保后续能按锚点客观宣告 DONE。
+
+### Step 5：实现（Implementation）
+
+- 编码执行以**编码计划**为主线：按 Plan 项（如 `MPx.y`）阅读“交付物/影响范围/约束/实现要点”，完成具体实现。
+- Coder 禁止修改 tests/；如测试不合理或需要更新，只能反馈给 Test Owner。
+- 追溯矩阵作为“任务筛选 + 验收看板”：优先选择**已绑定验收锚点**的 Plan 项推进；任何“无锚点”的 Plan 项先补锚点/回写设计/延期（否则无法客观宣告 DONE）。
+- 开发循环：按编码计划实现 → 运行该 Plan 项对应的 A 类锚点（tests/命令）→ 修复 → 直到锚点 PASS（再把 Plan 与矩阵状态同步更新）。
+
+### Step 6：全量验收（Verification）
+
+- 运行本次范围内所有 A 类锚点（全套 tests + 静态检查 + build 校验）
+- 静态检查优先使用机器可读输出（json/xml），便于机械式修复与可追溯存档。
+- 执行 B/C 类：按 checklist 逐条勾选并记录证据（截图/录像/报表/签字）
+- 可读性/依赖/坏味道审查（Reviewer）：使用 `devbooks-code-review` Skill 输出审查意见
+
+### Step 7：关账与沉淀（Close-out）
+
+- 更新追溯矩阵状态（DONE/BLOCKED/DEFERRED）
+- 更新编码计划的进度表（只以锚点结果为准）
+- 更新价值流与度量口径：把本次“价值信号/排队点/稳定性指标”的证据链接写回 `verification.md`（建议落到 `evidence/`）
+- 若发现“计划错误/设计遗漏”：在下一版本修正 Design Doc / ADR，而不是靠口头约定
+- 活文档修剪（Spec Gardening）：
+  - 使用 `devbooks-spec-gardener` Skill 执行
+  - 去重合并：合并相似/重叠的 spec，避免追加式堆叠
+  - 目录整理：按业务能力整理到 `<truth-root>/<capability>/`
+  - 删除过时：被新功能替代的 spec 必须删除
+  - 可选自动检查：`guardrail-check.sh <change-id>`（脚本位于本 Skill 的 `scripts/guardrail-check.sh`）
+
+---
+
+## 6) 目录落点示例（便于对照）
+
+- 设计文档：`<change-root>/<change-id>/design.md`
+- 编码计划：`<change-root>/<change-id>/tasks.md`
+- 规格 delta：`<change-root>/<change-id>/specs/<capability>/spec.md`
+- 验证与追溯：`<change-root>/<change-id>/verification.md`（包含测试计划、追溯矩阵、MANUAL-* 清单与证据要求）
+- 可执行验收：`tests/`（包含 contract/unit/integration/e2e 与架构适配函数）
+- 归档：把 delta 合并进 `<truth-root>/`，并归档变更包

package/skills/devbooks-delivery-workflow/references//345/216/237/345/236/213-/347/224/237/344/272/247/345/217/214/350/275/250/346/250/241/345/274/217.md

@@ -0,0 +1,168 @@
+# 原型-生产双轨模式（Prototype-Production Dual Track）
+
+> 来源：《人月神话》第11章"未雨绸缪" — "第一个开发的系统并不合用...为舍弃而计划，无论如何，你一定要这样做。"
+
+## 核心理念
+
+**原型轨道**用于快速验证技术可行性，产出"可抛弃的第一版"。
+**生产轨道**用于交付高质量代码，以测试/闸门为完成判据。
+
+两条轨道**物理隔离**，通过显式的"提升"流程衔接。
+
+---
+
+## 何时使用原型轨道
+
+| 场景 | 信号 | 建议 |
+|------|------|------|
+| 技术不确定 | "不知道这个库能不能用" / "不确定性能够不够" | ✅ 原型 |
+| 第一次做 | "第一次做这类功能" / "预期会重写" | ✅ 原型 |
+| 探索行为 | "需要观察 API 的实际返回值" | ✅ 原型 |
+| 需求明确 | 设计已确定、AC 已定义 | ❌ 直接生产轨道 |
+| 小修小补 | Bug 修复、配置调整 | ❌ 直接生产轨道 |
+
+---
+
+## 双轨模式流程图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Proposal 阶段                              │
+│  proposal.md（共用）                                              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+              ┌───────────────┴───────────────┐
+              │                               │
+              ▼                               ▼
+    ┌─────────────────┐             ┌─────────────────┐
+    │   原型轨道       │             │   生产轨道       │
+    │   (Prototype)    │             │   (Production)   │
+    ├─────────────────┤             ├─────────────────┤
+    │ prototype/src/   │             │ design.md        │
+    │ prototype/       │             │ tasks.md         │
+    │   characterization/│           │ verification.md  │
+    │ PROTOTYPE.md     │             │ tests/**         │
+    ├─────────────────┤             ├─────────────────┤
+    │ 表征测试         │             │ 验收测试         │
+    │ (记录实际行为)    │             │ (验证设计意图)    │
+    │ 无 Red 基线要求   │             │ 必须 Red 基线    │
+    └────────┬────────┘             └────────┬────────┘
+             │                                │
+             │                                │
+             ▼                                │
+    ┌─────────────────┐                       │
+    │ 学习 & 决策      │                       │
+    │ 提升 or 丢弃?    │                       │
+    └────────┬────────┘                       │
+             │                                │
+     ┌───────┴───────┐                        │
+     ▼               ▼                        │
+  [提升]          [丢弃]                      │
+     │               │                        │
+     ▼               ▼                        │
+prototype-promote.sh  删除 prototype/         │
+     │               └─────────────────────►──┤
+     │                                        │
+     └────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │   归档阶段       │
+                    │   (Archive)      │
+                    └─────────────────┘
+```
+
+---
+
+## 表征测试 vs 验收测试
+
+| 维度 | 验收测试（Acceptance Test） | 表征测试（Characterization Test） |
+|------|---------------------------|----------------------------------|
+| **目的** | 断言"应该是什么" | 断言"实际是什么" |
+| **来源** | 设计文档 / AC-xxx | 运行观察 |
+| **基线** | 必须先 Red | 初始就是 Green |
+| **轨道** | 生产轨道 | 原型轨道 |
+| **用途** | 验证设计意图 | 记录行为快照 |
+| **CI** | 进入主流程 | 标记跳过 / 隔离 |
+
+### 表征测试命名约定
+
+```
+# Python
+test_characterize_<behavior>.py
+@pytest.mark.characterization
+
+# TypeScript/JavaScript
+*.characterization.test.ts
+describe.skip('characterization: <behavior>')
+```
+
+---
+
+## 角色隔离（不变）
+
+原型模式下，角色隔离原则与生产轨道**完全一致**：
+
+| 角色 | 职责 | 禁止 |
+|------|------|------|
+| Test Owner | 产出表征测试 | 不得与 Coder 共享上下文 |
+| Coder | 产出原型代码 | 禁止修改 characterization/ |
+
+---
+
+## 原型提升检查清单
+
+运行 `prototype-promote.sh <change-id>` 前，必须完成：
+
+- [ ] 创建生产级 `design.md`（从原型学习中提炼 What/Constraints/AC-xxx）
+- [ ] Test Owner 产出验收测试 `verification.md`（替代表征测试）
+- [ ] 完成 `prototype/PROTOTYPE.md` 中的提升检查清单
+- [ ] 在 `prototype/PROTOTYPE.md` 的"学习记录"中写明技术发现
+
+---
+
+## 原型丢弃检查清单
+
+如果决定丢弃原型：
+
+- [ ] 记录学习到的关键洞察到 `proposal.md` 的 Decision Log
+- [ ] 删除 `prototype/` 目录
+- [ ] 可选：保留部分洞察到 `<truth-root>/_meta/lessons-learned/`
+
+---
+
+## 脚本参考
+
+| 脚本 | 用途 | 示例 |
+|------|------|------|
+| `change-scaffold.sh --prototype` | 创建原型骨架 | `change-scaffold.sh feat-001 --prototype` |
+| `prototype-promote.sh` | 提升原型到生产轨道 | `prototype-promote.sh feat-001` |
+
+---
+
+## 常见问题
+
+### Q: 原型代码可以直接用于生产吗？
+
+**不可以**。原型代码物理隔离在 `prototype/src/`，禁止直接落到仓库 `src/`。必须通过 `prototype-promote.sh` 显式提升。
+
+### Q: 表征测试进入 CI 吗？
+
+**不进入**。表征测试使用 `@characterization` 标记，默认跳过。提升时会归档到 `tests/archived-characterization/`。
+
+### Q: 原型模式下需要写 design.md 吗？
+
+**原型阶段不需要**。原型结束后，如果决定提升，再从原型学习中提炼生产级 `design.md`。
+
+### Q: 可以跳过原型直接做生产吗？
+
+**可以**。如果需求明确、技术方案确定，直接走生产轨道（A/B/C/D 阶段）。
+
+---
+
+## 参考文献
+
+- 《人月神话》第11章"未雨绸缪"
+- Michael Feathers,《修改代码的艺术》— Characterization Tests
+- Martin Fowler, "Is High Quality Software Worth the Cost?"

package/skills/devbooks-delivery-workflow/references//345/217/230/346/233/264/351/252/214/350/257/201/344/270/216/350/277/275/346/272/257/346/250/241/346/235/277.md

@@ -0,0 +1,133 @@
+# verification.md 模板（变更包内）
+
+> 推荐路径：`<change-root>/<change-id>/verification.md`
+>
+> 目标：把“完成定义”落到可执行锚点与证据上，并提供 `AC-xxx -> Requirement/Scenario -> Test IDs -> Evidence` 的追溯。
+
+---
+
+## 元信息
+
+- Change ID：`<change-id>`
+- 状态：`Draft | Ready | Done | Archived`
+- 关联：
+  - Proposal：`<change-root>/<change-id>/proposal.md`
+  - Design：`<change-root>/<change-id>/design.md`
+  - Tasks：`<change-root>/<change-id>/tasks.md`
+  - Spec deltas：`<change-root>/<change-id>/specs/**`
+- 维护者：`<you>`
+- 更新时间：`YYYY-MM-DD`
+- Test Owner（独立对话）：`<session/agent>`
+- Coder（独立对话）：`<session/agent>`
+- Red 基线证据：`<change-root>/<change-id>/evidence/`
+
+---
+
+========================
+A) 测试计划指令表
+========================
+
+### 主线计划区 (Main Plan Area)
+
+- [ ] TP1.1 `<一句话目标>`
+  - Why：
+  - Acceptance Criteria（引用 AC-xxx / Requirement）：
+  - Test Type：`unit | contract | integration | e2e | fitness | static`
+  - Non-goals：
+  - Candidate Anchors（Test IDs / commands / evidence）：
+
+### 临时计划区 (Temporary Plan Area)
+
+- （留空/按需）
+
+### 断点区 (Context Switch Breakpoint Area)
+
+- 上次进度：
+- 当前阻塞：
+- 下一步最短路径：
+
+---
+
+========================
+B) 追溯矩阵（Traceability Matrix）
+========================
+
+> 建议按 AC-xxx 为主键；如果你维护了 Requirements/Scenarios 规格条目，可同时列出对应项。
+
+| AC | Requirement/Scenario | Test IDs / Commands | Evidence / MANUAL-* | Status |
+|---|---|---|---|---|
+| AC-001 | `<capability>/Requirement...` | `TEST-...` / `pnpm test ...` | `MANUAL-001` / link | TODO |
+
+---
+
+========================
+C) 执行锚点（Deterministic Anchors）
+========================
+
+### 1) 行为（Behavior）
+
+- unit：
+- integration：
+- e2e：
+
+### 2) 契约（Contract）
+
+- OpenAPI/Proto/Schema：
+- contract tests：
+
+### 3) 结构（Structure / Fitness Functions）
+
+- 分层/依赖方向/禁止循环：
+
+### 4) 静态与安全（Static/Security）
+
+- lint/typecheck/build：
+- SAST/secret scan：
+- 报告格式：`json|xml`（优先机器可读）
+- 质量闸门：复杂度/重复度/依赖规则（如有）
+
+---
+
+========================
+D) MANUAL-* 清单（人工/混合验收）
+========================
+
+> 只收录“无法稳定自动化”的验收项；每条必须写清证据要求。
+
+- [ ] MANUAL-001 `<验收项>`
+  - Pass/Fail 判据：
+  - Evidence（截图/录像/链接/日志）：
+  - 责任人/签字：
+
+---
+
+========================
+E) 风险与降级（可选）
+========================
+
+- 风险：
+- 降级策略：
+- 回滚策略：
+
+========================
+F) 结构质量守门记录（可选）
+========================
+
+> 若本次变更涉及“代理指标驱动”的要求或潜在结构风险，请记录决策与替代闸门。
+
+- 冲突点：
+- 评估影响（内聚/耦合/可测试性）：
+- 替代闸门（复杂度/耦合/依赖方向/测试质量）：
+- 决策与授权：
+
+========================
+G) 价值流与度量（可选，但必须显式填“无”）
+========================
+
+> 目的：把“交付更快/更稳/更有价值”的判断落到可观测口径；避免只看局部写码速度。
+
+- 目标价值信号：`<填“无”或写明指标/看板/日志/业务事件>`
+- 价值流瓶颈假设（哪里会堵）：`<填“无”或写明 PR review / tests / 发布 / 手工验收 的排队点>`
+- 交付与稳定性指标（可选 DORA）：`<填“无”或写明 Lead Time / Deploy Frequency / Change Failure Rate / MTTR 的观测口径>`
+- 观测窗口与触发点：`<填“无”或写明上线后多久、观察哪些告警/报表>`
+- Evidence：`<填“无”或写明链接/截图/报表路径（建议落到 evidence/）>`