dev-playbooks-cn 1.0.0

package/skills/devbooks-delivery-workflow/scripts/verify-npm-package.sh

@@ -0,0 +1,123 @@
+#!/bin/bash
+# verify-npm-package.sh - Verify npm package structure
+#
+# Verify AC-011 ~ AC-016
+
+set -uo pipefail  # Remove -e, handle errors manually
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+PASSED=0
+FAILED=0
+
+check() {
+    local name="$1"
+    local result="$2"
+    if [[ "$result" == "0" ]]; then
+        echo -e "${GREEN}✅ $name${NC}"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "${RED}❌ $name${NC}"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+echo "=== npm Package Verification ==="
+echo ""
+
+# Use an isolated npm cache to avoid permission issues in CI/dev environments.
+NPM_CACHE_DIR="$(mktemp -d 2>/dev/null || mktemp -d -t 'devbooks-npm-cache')"
+cleanup() {
+    rm -rf "$NPM_CACHE_DIR"
+}
+trap cleanup EXIT
+
+# AC-011: CLI entry exists and is executable
+# Note: Design changed to `devbooks init` instead of `create-devbooks`
+echo "AC-011: Checking CLI entry..."
+if [[ -f "bin/devbooks.js" ]] && [[ -x "bin/devbooks.js" ]]; then
+    check "AC-011: CLI entry exists and is executable" "0"
+else
+    check "AC-011: CLI entry exists and is executable" "1"
+fi
+
+# AC-012: package.json exists and is valid
+echo "AC-012: Checking package.json..."
+if [[ -f "package.json" ]] && node -e '
+  const fs = require("fs");
+  const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  const hasName = typeof pkg.name === "string" && pkg.name.trim().length > 0;
+  const bin = pkg.bin;
+  const normalize = (p) => (typeof p === "string" && p.startsWith("./")) ? p.slice(2) : p;
+  const hasBin = (() => {
+    if (typeof bin === "string") return normalize(bin) === "bin/devbooks.js";
+    if (!bin || typeof bin !== "object") return false;
+    return Object.values(bin).some(v => typeof v === "string" && normalize(v) === "bin/devbooks.js");
+  })();
+  process.exit(hasName && hasBin ? 0 : 1);
+' >/dev/null 2>&1; then
+    check "AC-012: package.json exists and is valid" "0"
+else
+    check "AC-012: package.json exists and is valid" "1"
+fi
+
+# AC-013: templates/ directory exists
+echo "AC-013: Checking templates/ directory..."
+if [[ -d "templates" ]]; then
+    check "AC-013: templates/ directory exists" "0"
+else
+    check "AC-013: templates/ directory exists" "1"
+fi
+
+# AC-014: Skills count is correct (21 devbooks-* Skills)
+echo "AC-014: Checking Skills count..."
+skill_count=$(ls -d skills/devbooks-* 2>/dev/null | wc -l | tr -d ' ')
+if [[ "$skill_count" -ge 20 ]]; then
+    check "AC-014: Skills count is correct ($skill_count)" "0"
+else
+    check "AC-014: Skills count is correct ($skill_count, expected >= 20)" "1"
+fi
+
+# AC-015: Packaging is controlled (files whitelist or .npmignore)
+echo "AC-015: Checking packaging control..."
+has_files_whitelist="1"
+if [[ -f "package.json" ]] && node -e '
+  const fs = require("fs");
+  const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  const files = pkg.files;
+  const ok = Array.isArray(files) && files.length > 0;
+  process.exit(ok ? 0 : 1);
+' >/dev/null 2>&1; then
+    has_files_whitelist="0"
+fi
+if [[ "$has_files_whitelist" == "0" || -f ".npmignore" ]]; then
+    check "AC-015: packaging is controlled" "0"
+else
+    check "AC-015: packaging is controlled" "1"
+fi
+
+# AC-016: npm pack does not include project change packages (exclude template directory)
+# Note: templates/dev-playbooks/changes/ is user project template, should be included
+#       dev-playbooks/changes/ is project development change package, should be excluded
+echo "AC-016: Checking npm pack output..."
+pack_output="$(npm --cache "$NPM_CACHE_DIR" pack --dry-run --ignore-scripts 2>&1 || true)"
+if echo "$pack_output" | grep "changes/" | grep -v "templates/" | grep -q "changes/"; then
+    check "AC-016: npm pack does not include changes/" "1"
+else
+    check "AC-016: npm pack does not include changes/" "0"
+fi
+
+echo ""
+echo "=== Results ==="
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some checks failed${NC}"
+    exit 1
+fi

package/skills/devbooks-delivery-workflow/scripts/verify-openspec-free.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# verify-openspec-free.sh - Verify OpenSpec references are cleared
+#
+# Verify AC-001 ~ AC-004
+
+set -uo pipefail  # Remove -e, handle errors manually
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+PASSED=0
+FAILED=0
+
+check() {
+    local name="$1"
+    local result="$2"
+    if [[ "$result" == "0" ]]; then
+        echo -e "${GREEN}✅ $name${NC}"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "${RED}❌ $name${NC}"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+echo "=== OpenSpec Cleanup Verification ==="
+echo ""
+
+# AC-001: No OpenSpec references (exclude legitimate references)
+echo "AC-001: Checking OpenSpec references..."
+# Exclude legitimate references:
+# - backup, changes, .git: history/work directories
+# - migrate-from-openspec.sh: migration script
+# - verify-*.sh: verification scripts
+# - c4.md: architecture documentation (records historical changes)
+# - specs/config-protocol/spec.md: rule definition document
+# - specs/slash-commands/spec.md: historical record document
+ref_count=$(grep -rn "openspec\|OpenSpec" . --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.js" 2>/dev/null | grep -v backup | grep -v changes | grep -v "\.git" | grep -v "DEVBOOKS-EVOLUTION-PROPOSAL.md" | grep -v "migrate-from-openspec.sh" | grep -v "tests/" | grep -v "verify-openspec-free.sh" | grep -v "verify-all.sh" | grep -v "c4.md" | grep -v "specs/config-protocol/spec.md" | grep -v "specs/slash-commands/spec.md" | wc -l | tr -d ' ') || ref_count=0
+if [[ "$ref_count" == "0" ]]; then
+    check "AC-001: OpenSpec references cleared" "0"
+else
+    check "AC-001: OpenSpec references cleared ($ref_count remaining)" "1"
+fi
+
+# AC-002: setup/openspec deleted
+echo "AC-002: Checking setup/openspec directory..."
+if [[ ! -d "setup/openspec" ]]; then
+    check "AC-002: setup/openspec deleted" "0"
+else
+    check "AC-002: setup/openspec deleted" "1"
+fi
+
+# AC-003: .claude/commands/openspec deleted
+echo "AC-003: Checking .claude/commands/openspec directory..."
+if [[ ! -d ".claude/commands/openspec" ]]; then
+    check "AC-003: .claude/commands/openspec deleted" "0"
+else
+    check "AC-003: .claude/commands/openspec deleted" "1"
+fi
+
+# AC-004: dev-playbooks/specs/openspec-integration deleted
+echo "AC-004: Checking dev-playbooks/specs/openspec-integration directory..."
+if [[ ! -d "dev-playbooks/specs/openspec-integration" ]]; then
+    check "AC-004: dev-playbooks/specs/openspec-integration deleted" "0"
+else
+    check "AC-004: dev-playbooks/specs/openspec-integration deleted" "1"
+fi
+
+echo ""
+echo "=== Results ==="
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some checks failed${NC}"
+    exit 1
+fi

package/skills/devbooks-delivery-workflow/scripts/verify-slash-commands.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# verify-slash-commands.sh - Verify Slash command definitions
+#
+# Verify AC-001 (24 commands) and AC-002 (command to Skill 1:1 mapping)
+
+set -uo pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+PASSED=0
+FAILED=0
+
+check() {
+    local name="$1"
+    local result="$2"
+    if [[ "$result" == "0" ]]; then
+        echo -e "${GREEN}✅ $name${NC}"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "${RED}❌ $name${NC}"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+check_skill_mapping() {
+    local cmd="$1"
+    local expected_skill="$2"
+    local file="$COMMANDS_DIR/$cmd.md"
+    if [[ -f "$file" ]]; then
+        if grep -q "skill: $expected_skill" "$file"; then
+            check "AC-002: $cmd.md → $expected_skill" "0"
+        else
+            check "AC-002: $cmd.md → $expected_skill (skill metadata mismatch)" "1"
+        fi
+    fi
+}
+
+echo "=== Slash Command Verification (21 core + 3 backward compatible = 24 commands) ==="
+echo ""
+
+COMMANDS_DIR="templates/claude-commands/devbooks"
+
+# AC-001: Check command count (24 = 21 core + 3 backward compatible)
+echo "AC-001: Checking command count..."
+cmd_count=$(ls "$COMMANDS_DIR"/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [[ "$cmd_count" -eq 24 ]]; then
+    check "AC-001: Command count is 24 (21 core + 3 backward compatible)" "0"
+else
+    check "AC-001: Command count is 24 (actual: $cmd_count)" "1"
+fi
+
+echo ""
+echo "=== Checking 21 command file existence ==="
+
+# 21 command files list
+COMMANDS=(
+    "router"
+    "proposal"
+    "challenger"
+    "judge"
+    "debate"
+    "design"
+    "backport"
+    "plan"
+    "spec"
+    "gardener"
+    "test"
+    "test-review"
+    "code"
+    "review"
+    "delivery"
+    "c4"
+    "impact"
+    "entropy"
+    "federation"
+    "bootstrap"
+    "index"
+)
+
+for cmd in "${COMMANDS[@]}"; do
+    if [[ -f "$COMMANDS_DIR/$cmd.md" ]]; then
+        check "AC-011~AC-031: $cmd.md exists" "0"
+    else
+        check "AC-011~AC-031: $cmd.md exists" "1"
+    fi
+done
+
+echo ""
+echo "=== AC-002: Checking command to Skill mapping ==="
+
+# Command -> Skill mapping check
+check_skill_mapping "router" "devbooks-router"
+check_skill_mapping "proposal" "devbooks-proposal-author"
+check_skill_mapping "challenger" "devbooks-proposal-challenger"
+check_skill_mapping "judge" "devbooks-proposal-judge"
+check_skill_mapping "debate" "devbooks-proposal-debate-workflow"
+check_skill_mapping "design" "devbooks-design-doc"
+check_skill_mapping "backport" "devbooks-design-backport"
+check_skill_mapping "plan" "devbooks-implementation-plan"
+check_skill_mapping "spec" "devbooks-spec-contract"
+check_skill_mapping "gardener" "devbooks-spec-gardener"
+check_skill_mapping "test" "devbooks-test-owner"
+check_skill_mapping "test-review" "devbooks-test-reviewer"
+check_skill_mapping "code" "devbooks-coder"
+check_skill_mapping "review" "devbooks-code-review"
+check_skill_mapping "delivery" "devbooks-delivery-workflow"
+check_skill_mapping "c4" "devbooks-c4-map"
+check_skill_mapping "impact" "devbooks-impact-analysis"
+check_skill_mapping "entropy" "devbooks-entropy-monitor"
+check_skill_mapping "federation" "devbooks-federation"
+check_skill_mapping "bootstrap" "devbooks-brownfield-bootstrap"
+check_skill_mapping "index" "devbooks-index-bootstrap"
+
+echo ""
+echo "=== AC-008: Checking backward compatible commands ==="
+
+# Backward compatible commands list
+COMPAT_COMMANDS=("apply" "archive" "quick")
+
+for cmd in "${COMPAT_COMMANDS[@]}"; do
+    if [[ -f "$COMMANDS_DIR/$cmd.md" ]]; then
+        if grep -q "backward-compat: true" "$COMMANDS_DIR/$cmd.md"; then
+            check "AC-008: $cmd.md exists and marked as backward compatible" "0"
+        else
+            check "AC-008: $cmd.md exists but missing backward-compat marker" "1"
+        fi
+    else
+        check "AC-008: $cmd.md exists" "1"
+    fi
+done
+
+echo ""
+echo "=== Results ==="
+echo "Passed: $PASSED"
+echo "Failed: $FAILED"
+
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}All passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some checks failed${NC}"
+    exit 1
+fi

package/skills/devbooks-delivery-workflow/templates/handoff.md

@@ -0,0 +1,50 @@
+# 角色交接记录 / Role Handoff Record
+
+## 交接信息 / Handoff Metadata
+
+- **变更ID**: <change-id>
+- **交出角色**: <Test Owner / Design Owner / Planner / ...>
+- **接收角色**: <Coder / Reviewer / ...>
+- **交接时间**: <YYYY-MM-DD HH:MM>
+- **对话/实例ID**: <session-id>
+
+## 交接内容 / Handoff Content
+
+### 已完成产物 / Completed Deliverables
+
+- [ ] `design.md` - 设计文档已产出并通过评审
+- [ ] `tasks.md` - 编码计划已产出
+- [ ] `verification.md` - 验收测试已定义
+- [ ] `tests/**` - 测试代码已实现
+- [ ] Red 基线已记录到 `evidence/red-baseline/`
+
+### 上下文信息 / Context Information
+
+> 请填写接收角色需要了解的关键信息
+
+- **当前状态**: <简述当前进展>
+- **关键决策**: <需要了解的重要决策>
+- **已知问题**: <可能遇到的问题或风险>
+- **参考文档**: <其他需要阅读的文档>
+
+### 剩余工作 / Remaining Work
+
+> 请列出接收角色需要完成的工作
+
+1. <待完成项 1>
+2. <待完成项 2>
+
+## 确认签名 / Confirmation Signatures
+
+> 交接完成后，双方在此签名确认
+
+- [ ] **交出方确认**: 我确认已完成上述产物，信息准确完整
+- [ ] **接收方确认**: 我确认已收到交接内容，理解当前状态和待完成工作
+
+---
+
+## 附注 / Notes
+
+> 可选：其他需要记录的信息
+
+<填写附加说明或留空>

package/skills/devbooks-design-backport/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: devbooks-design-backport
+description: devbooks-design-backport：把实现过程中发现的新约束/冲突/缺口回写到 design.md（保持设计为黄金真理），并标注决策与影响。用户说"回写设计/补充设计文档/Design Backport/设计与实现不一致/需要澄清约束"等时使用。
+tools:
+  - Glob
+  - Grep
+  - Read
+  - Write
+  - Edit
+---
+
+# DevBooks：回写设计文档（Design Backport）
+
+## 前置：配置发现（协议无关）
+
+- `<truth-root>`：当前真理目录根
+- `<change-root>`：变更包目录根
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
+4. `project.md`（如存在）→ template 协议，使用默认映射
+5. 若仍无法确定 → **停止并询问用户**
+
+**关键约束**：
+- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
+- 禁止猜测目录根
+- 禁止跳过规则文档阅读
+
+## 执行方式
+
+1) 先阅读并遵守：`_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+2) 严格按完整提示词执行：`references/回写设计文档提示词.md`。
+
+---
+
+## 上下文感知
+
+本 Skill 在执行前自动检测上下文，识别需要回写的内容。
+
+检测规则参考：`skills/_shared/context-detection-template.md`
+
+### 检测流程
+
+1. 检测 `design.md` 是否存在
+2. 检测实现过程中是否有新发现（冲突/约束/缺口）
+3. 对比设计与实现的差异
+
+### 本 Skill 支持的模式
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| **冲突回写** | 发现设计与实现冲突 | 记录冲突点和解决方案 |
+| **约束回写** | 发现新的实现约束 | 补充约束条件到设计 |
+| **缺口回写** | 发现设计未覆盖的场景 | 补充遗漏的设计决策 |
+
+### 检测输出示例
+
+```
+检测结果：
+- design.md：存在
+- 发现内容：2 个新约束，1 个设计冲突
+- 运行模式：约束回写 + 冲突回写
+```
+
+---
+
+## MCP 增强
+
+本 Skill 不依赖 MCP 服务，无需运行时检测。
+
+MCP 增强规则参考：`skills/_shared/mcp-enhancement-template.md`
+

package/skills/devbooks-design-backport/references//345/233/236/345/206/231/350/256/276/350/256/241/346/226/207/346/241/243/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,196 @@
+# 回写设计文档提示词
+
+> **角色设定**：你是设计演进领域的**最强大脑**——融合了 Michael Nygard（架构决策记录）、Martin Fowler（演进式设计）、Kent Beck（渐进式改进）的智慧。你的设计同步必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+# 提示词：当编码计划超出设计文档范围时，回写设计文档（Design Backport）
+
+
+
+> 使用场景：你发现“编码计划（tasks/plan）”中出现了“设计文档（design/spec）”未包含的新约束/新概念/新验收口径，导致“计划驱动实现”与“设计驱动验收”出现漂移。
+
+产物落点（目录约定，协议无关）：
+- 设计文档通常位于：`<change-root>/<change-id>/design.md`
+- 编码计划通常位于：`<change-root>/<change-id>/tasks.md`
+- 规格 delta 通常位于：`<change-root>/<change-id>/specs/<capability>/spec.md`
+- 当前真理源位于：`<truth-root>/`（不要试图回写/篡改历史归档来“统一口径”；用新的变更包更新当前真理）
+
+> 目标：把“应该成为设计的一部分”的内容回写进设计文档，降低后续测试、实现、验收的分歧。
+
+
+
+---
+
+
+
+## 可回写到设计文档的内容（What can be backported）
+
+
+
+只有当计划内容满足以下任一条件时，才适合回写到设计文档（属于 **Design-level**）：
+
+
+
+1. **对外语义或用户可感知行为**
+
+- 新增/修改关键用户流程（例如显式状态机、异步会话、可取消/可超时）
+
+- 对外契约（API 输入输出形状、错误语义、必填字段、兼容窗口）
+
+2. **系统级不可变约束（Invariants / Red Lines）**
+
+- 成本/资源上限（例如禁止 N² LLM 调用、`max_llm_calls` 硬上限、预算触发降级）
+
+- 可靠性/安全红线（例如多租户隔离默认开启、外部不可信边界、注入默认隔离）
+
+3. **核心数据契约与演进策略（Contracts & Evolution）**
+
+- `schema_version`、事件信封必需字段、幂等键原则、兼容策略（DLQ/迁移/回放）
+
+- “什么必须能回放/可审计/可追溯”的最低标准
+
+4. **跨阶段治理策略（Cross-cutting Concerns）**
+
+- 观测指标、SLO/KPI、告警与运营策略
+
+- 生命周期/保留策略（Valid/Quarantine/Garbage 的策略与目的）
+
+- 灰度/回滚路径与功能开关（Feature Flags）
+
+5. **关键取舍与决策（Decisions）**
+
+- 选择 A 而非 B 的原因、替代方案、风险、降级策略
+
+- 新增/修改“非目标（Non-goals）”或“开放问题（Open Questions）”
+
+
+
+---
+
+
+
+## 不应回写到设计文档的内容（What must NOT be backported）
+
+
+
+以下内容属于 **Implementation-level**，不应直接写入设计文档（除非你要把它升级为正式设计决策）：
+
+
+
+- 具体文件路径、类名/函数名、表名/字段名的实现细节（除非它是稳定的架构边界且必须对齐）
+
+- PR 切分建议、任务执行顺序、脚本/命令的临时实现步骤
+
+- 过细的算法伪代码（可回写“输入/输出/不变量/复杂度上限/降级策略”，避免把代码写进设计）
+
+- 仅为某次实现方便的技巧性约束（没有长期价值或不可被验证）
+
+
+
+---
+
+
+
+## 冲突处理规则（Plan vs Design）
+
+
+
+- **设计文档优先（Design is the Golden Truth）**：若编码计划与设计冲突，不要直接用计划覆盖设计。
+
+- 允许两种处理方式：
+
+1) **提案式回写**：把计划内容作为 “Proposed Design Change（提案）” 写入设计文档，并明确需要决策/确认；
+
+2) **降级/延期**：将计划条目标记为 `DEFERRED/UNSCOPED`，直到设计明确后再进入实施。
+
+- 回写时必须显式标注：这是“新增设计决策/补充约束”，并说明原因与影响范围。
+
+
+
+---
+
+
+
+## 输出要求（你要产出的东西）
+
+
+
+1. **对比清单**：列出“计划超出设计”的候选条目（按 Plan ID 分组），并给出分类：`Design-level / Implementation-level / Out-of-scope`。
+
+2. **设计回写补丁**：将所有 `Design-level` 内容以最小改动写回设计文档，放到最合适的章节（例如：非目标/设计原则/风险与降级/契约/里程碑/关键决策汇总）。
+
+3. **追溯更新**：对每条回写的设计内容，明确其验收方式（A/B/C）与验收锚点，并要求同步更新：
+   - 追溯矩阵（优先更新本次变更的 `<change-root>/<change-id>/verification.md`；如需对外公开再同步到 `docs/`）
+   - 非机器验收清单（优先更新 `<change-root>/<change-id>/verification.md` 中的 `MANUAL-*` 条目；如需对外公开再同步到 `docs/`）
+   - 如需新增/更新自动化锚点：列出对应的测试/静态检查建议（tests/命令/marker）
+
+
+
+---
+
+
+
+## 可直接复制使用的提示词（Prompt）
+
+
+
+```text
+
+你是“设计文档编辑器（Design Doc Editor）”。你的目标是把编码计划中超出设计文档范围、但属于设计层的内容，回写到设计文档中，使其成为可追溯、可验收的设计约束。
+
+
+
+输入：
+
+- 设计文档：`<change-root>/<change-id>/design.md`（或你提供的等价路径）
+
+- 编码计划：`<change-root>/<change-id>/tasks.md`（或你提供的等价路径）
+
+
+
+任务：
+
+1) 通读编码计划，找出所有“设计文档没有覆盖或表述不足”的条目（按 MP/章节聚类）。
+
+2) 对每条候选内容做分类：
+
+- Design-level（应回写到设计）：影响对外语义/用户流程/系统红线/数据契约/演进策略/运维治理/关键决策
+
+- Implementation-level（不回写）：实现细节、文件路径、PR 切分、执行顺序、伪代码细节
+
+- Out-of-scope（不回写且应延期）：不在本次范围或属于未来阶段但未被设计确认
+
+3) 仅对 Design-level 内容，回写到设计文档：
+
+- 放到最合适的现有章节；必要时新增小节，但不要重构整篇文档
+
+- 以“设计约束/决策”的口吻描述，避免实现细节
+
+- 如与原设计冲突：不要直接改写原结论；新增“Proposed Design Change/开放问题”并说明原因、影响、需要决策点
+
+- 更新设计文档头部的“更新时间”（如存在）
+
+4) 输出：
+
+- A) 候选清单与分类结果（按 Plan ID）
+
+- B) 对设计文档的最小补丁（只包含新增/修改的段落）
+
+- C) 追溯与锚点更新清单（按优先级排序）：
+  - 需要新增/更新哪些 tests/静态检查（A 类锚点）
+  - 需要新增/更新哪些人工/混合验收条目（B/C 类锚点，优先落到 `<change-root>/<change-id>/verification.md`）
+  - 需要如何更新追溯矩阵（优先落到 `<change-root>/<change-id>/verification.md`）
+
+
+
+限制：
+
+- 不要把文件路径、类名/函数名、DB 表名等实现细节写进设计文档（除非它是稳定架构边界且必须暴露）
+
+- 不要把大段伪代码写进设计文档；可以写不变量、复杂度上限、降级策略
+
+- 语言保持与设计文档一致（中文为主，必要时英文术语括号解释）
+
+```