@kunlv/atdc 1.0.0

package/prompts/3-impl.md

@@ -0,0 +1,419 @@
+# prompts/3-impl · 执行
+
+从此文件读取后直接开始执行，无需用户再次确认。
+
+---
+
+## 🔴 Step -1：规则加载（不读 = 不得执行）
+
+**先 Read 以下 3 个文件，缺一不可。读完才进 Step 0。**
+
+```
+Read @atdc/reference/guards.md   → R1-R8 硬性拦截 + B5 Ponytail 8 级梯
+Read @atdc/reference/gates.md    → Gate 1-4 质量门禁
+Read @atdc/reference/tdd.md      → RED→GREEN→REFACTOR 完整循环
+Read @atdc/reference/risk.md     → 风险评分算法（R5/R7 所需）
+```
+
+> 以下所有 Step 引用的规则均来自上述 3 个文件。
+> 如果 Step 中提到 R5/B5/Gate 3 但未被加载到 context → 回退到 Step -1 重新加载。
+
+> **Token 节约原则**
+> - bash 命令加 `| grep -E "PASS|FAIL|ok|error"` 过滤噪声
+> - 找符号定义/调用方优先用 CodeGraph（`codegraph_search`/`codegraph_callers`），禁止 `grep -rn`
+> - 读文件用 `sed -n 'N,Mp'` 精确定位，不 `cat` 全文
+> - 大文件分析用 `ctx_execute_file`，不直接 Read
+
+---
+
+## Step 0：恢复断点
+
+```bash
+cat openspec/changes/<name>/.progress.json 2>/dev/null
+```
+
+- 存在且 `status != "completed"` → 报告进度（completedTasks / currentStep），询问"从断点继续 / 从头开始"
+- 不存在 → 创建初始 `.progress.json`：
+
+```json
+{
+  "change": "<name>",
+  "status": "in-progress",
+  "mode": "direct",
+  "currentStep": "gate-check",
+  "completedTasks": [],
+  "failedAt": null,
+  "failedReason": null,
+  "startedAt": "<ISO datetime>",
+  "updatedAt": "<ISO datetime>",
+  "traceability": [],
+  "gateResults": { "gate1": null, "gate2": null, "gate3": null, "gate4": null }
+}
+```
+
+同时确保 `.phase-state.json` phase 已推进到 build（1-spec 结束后应已到 build，如未推进则手动更新）：
+
+```bash
+python3 -c "
+import json
+with open('openspec/changes/<name>/.phase-state.json') as f: d = json.load(f)
+if d.get('phase') != 'build':
+    d['phase'] = 'build'
+    with open('openspec/changes/<name>/.phase-state.json','w') as f: json.dump(d,f,indent=2)
+"
+# PostToolUse hook 检测到 phase 变更为 build → 自动记录 phase_transition 事件
+```
+
+---
+
+## Step 1：R1 前置检查（硬性拦截）
+
+```bash
+ls openspec/changes/<name>/proposal.md openspec/changes/<name>/tasks.md openspec/changes/<name>/design.md 2>&1
+ls openspec/changes/<name>/specs/*/spec.md 2>&1
+```
+
+任一缺失 → 停止，输出缺少哪些文件，提示先补充再执行。
+
+> **🔒 Harness 加固**：R1 检查通过后，运行 `atdc guard build` 做脚本级硬性验证。
+> 该命令会再次确认 4 类文件完整性，不通过则 `[HARD STOP]` 并返回非 0，AI 不得跳过。
+
+### Step 1a：Evidence 系统初始化
+
+每次执行开始前，记录 intake 事件和初始 draft snapshot：
+
+```bash
+atdc evidence record <name> intake --phase=open --mode=<full/tweak/hotfix>
+atdc evidence metrics <name> --snapshot
+```
+
+> evidence 系统自动写入 `openspec/changes/<name>/.evidence/` 目录。
+
+### Step 1.5：Ponytail Guard（硬性拦截）
+
+> **复杂级 change** → 严格模式（发现 P0/P1 违规则 `[HARD STOP]`）
+> **标准级/简级** → 警告模式（输出建议，可跳过）
+
+```bash
+# 严格模式（默认用于复杂级）
+atdc ponytail guard --strict
+
+# 警告模式（用于简级/标准级）
+atdc ponytail guard --warn
+```
+
+> 发现 P0 违规（CRUD 模板 ≥10 / RPC 模板 ≥3 / DI 样板 ≥5）→ `[HARD STOP]`，必须先 `atdc ponytail fix` 修复再继续
+> 跳过检查：`PONYTAIL_SKIP=1 atdc guard build`（不推荐）
+
+> ⚠️ **CLI 不可用时的降级**：若 `which atdc` 返回空，Step 1.5 的 P0/P1 项目级扫描可跳过（无 CLI 无法执行），但 **Step 5b2 的 L4-L7 手动梯级检查不得跳过**。AI 必须通过 CodeGraph / grep 手动完成 5b2 的逐函数检查，不能因为 Step 1.5 跳过就把整套 Ponytail 标记为「已跳过」。
+
+---
+
+## Step 2：复杂度分级 + 执行模式选择
+
+### 2a. 复杂度评估
+
+统计 tasks.md 中 `### N.` 标题数量，并判断是否跨层改动（DB/缓存/路由/公共接口变更）：
+
+| 维度    | 简单  | 标准  | 复杂   |
+| ----- | --- | --- | ---- |
+| 任务数   | ≤ 1 | 2-5 | > 5  |
+| 跨层改动  | 无   | 无或有 | 有    |
+| 任务间依赖 | 无   | 有或无 | 有依赖链 |
+| 破坏性变更 | 无   | 无   | 有    |
+
+**分级规则**（从高到低匹配，命中即止）：
+- 命中任意 **复杂** 维度 → **复杂级**
+- 任务数 > 0 且全部命中 **简单** 维度 → **简级**
+- 其余 → **标准级**
+
+### 2b. 执行模式选择
+
+| 任务数       | 模式                               |
+| --------- | -------------------------------- |
+| ≤ 5       | 直通模式（tasks.md 即执行计划）             |
+| > 5       | 详细计划模式（先生成 bridge-manifest.json） |
+| 用户说"直通"   | 强制直通                             |
+| 用户说"详细计划" | 强制详细                             |
+
+### 2c. 各级别跳步规则
+
+根据复杂度级别，以下步骤可跳过：
+
+| 步骤 | 简级 | 标准级 | 复杂级 |
+|------|------|--------|--------|
+| Step 3 Gate 1 Spec 质量 | ⏭️ 跳过（1-spec 已验证） | ✅ 执行 | ✅ 执行 |
+| Step 4 Gate 2 追溯矩阵 | ⏭️ 跳过 | ✅ 执行 | ✅ 执行 |
+| Step 5d TDD | ⏭️ 跳过 | ✅ 执行 | ✅ 执行 |
+| Step 5b2 R6 SQL/缓存检查 | 按需（涉及 SQL/Redis 时执行） | ✅ 执行 | ✅ 执行 |
+| Step 6 C3 验证 | ✅ 编译 + Checklist | ✅ 全量验证 | ✅ 全量验证 |
+| Step 7 C2 人工 Review | ✅ 执行 | ✅ 执行 | ✅ 执行 |
+| Step 8 归档 | ✅ 执行 | ✅ 执行 | ✅ 执行 |
+
+> **简级说明**：≤1 个任务 + 无跨层改动 = 改动极小（如加字段、改文案），TDD 收益低于成本。
+> 但 C2（人工 review）和 C3（编译验证）不可跳过。
+
+宣布：`"检测到 N 个任务，复杂度：<简级/标准级/复杂级>，使用 <直通/详细计划> 模式，跳过：<步骤列表>"` 后继续。
+
+---
+
+## Step 3：Gate 1 — Spec 质量检查
+
+详细规则见 `@atdc/reference/gates.md`。
+
+扫描 `openspec/changes/<name>/specs/` 下所有 spec.md：
+- 弱需求（含 should/might/可能 而非 SHALL/MUST）
+- 缺 Given/When/Then 验收标准的场景
+- 缺 sad path 的 happy path
+- 缺边界场景（空值/超限/并发/降级）
+
+输出报告，有问题询问用户是否继续。
+
+---
+
+## Step 4：Gate 2 — 追溯矩阵
+
+生成 `openspec/changes/<name>/.progress.json` 的 `traceability` 字段，映射：
+`spec 需求 → task → 测试文件 → 实现文件`
+
+报告：需求遗漏 / 隐性需求 / 缺测试覆盖 / 野代码风险。
+
+---
+
+## Step 5：逐任务执行
+
+> 🔒 git-guardrails 检查（一次性提醒）：
+> ```bash
+> ls -la .git/hooks/pre-push 2>/dev/null && echo "✅ git-guardrails 已激活" || echo "⚠️ git-guardrails 未安装。建议运行：bash ~/atdc/install.sh"
+> ```
+
+每个任务按以下顺序执行：
+
+### 5a. R4 文件边界检查（执行前）
+
+确认任务有 `**Files**:` 字段且不为空。缺失则停止：
+```
+❌ [R4] 任务 N 缺少 Files 声明，请补充后继续。
+```
+
+### 5b0. 全景分析（可选，仅涉及陌生模块时触发）
+
+若本任务 `**Files**:` 涉及 ≥ 3 个文件，或包含 CONTEXT.md 中未记录的模块：
+> 本任务涉及 <N> 个模块（<列表>）。是否需要全景分析？
+> - 说 `zoom` → 执行 `/atdc:zoom-out`：
+>   1. 分析目标代码在系统架构中的位置
+>   2. 识别上下游依赖和间接影响
+>   3. 检查是否与 CONTEXT.md 中的模块边界一致
+> - 说 `继续` → 跳过，直接写代码
+
+> **触发条件**：`**Files**` > 2 个 或 涉及 CONTEXT.md 未记录的目录时显示。
+
+### 5b. 沿用抽象（写代码前）
+
+识别本任务需要实现的能力，**按优先级使用以下工具查找已有实现**：
+
+**1. Semble 语义搜索（推荐首选，直接返回代码片段）**：
+```
+/atdc:search "<描述你需要的功能>"
+```
+或用 MCP 工具直接调用 `mcp__semble__search`。Semble 理解自然语言语义，比关键词 grep 更精准，且直接返回代码片段（无需再 Read 文件）。
+
+**2. CodeGraph 结构化搜索（查调用关系、精确符号名）**：
+```
+codegraph_search "<关键词>"
+codegraph_callers "<FunctionName>"
+```
+
+**3. grep 降级兜底（仅前两者无结果时）**：
+```
+grep -rn "<关键词>" --include="*.go" . | grep -v "_test.go" | grep -v vendor
+```
+
+- 找到 → 沿用，SUMMARY.md 注明"沿用: <路径>"
+- 未找到 → 新建，SUMMARY.md 注明"新增抽象: <名称>"
+
+### 5b2. Ponytail 检查（每次新建文件/函数前，强制执行）
+
+> 🔴 **本步不依赖 atdc CLI，AI MUST 手动执行。即使 Step 1.5（CLI guard）因 atdc 未安装而跳过，本步也绝对不得跳过。**
+
+> 💡 **L2-L5 检测加速**：用 Semble search 快速验证"项目内有没有类似实现"。
+> 例：`semble search "filter by whitelist" .` → 直接返回已有 `filterByWhitelist` 代码块。
+> 语义搜索比逐一 grep 关键词高效 10x+。
+
+在 5b 找到已有实现后，再跑 Ponytail 8 级梯（详见 `@atdc/reference/guards.md` B5）。
+
+**强制规则**：
+- 每次 `write` 操作用到新文件 → 检查 8 级梯
+- 检测到同一模式出现 ≥3 次（参考 18 种模式速查表）→ **暂停，先提取泛型/公共模式**
+- 梯级通过 → 代码注释标注 `// Ponytail L{N}: <理由>`
+- 跳过梯级直接写代码 → Gate 3 不通过
+
+**L4 强制检查清单**（每次写新函数前必查）：
+1. `codegraph_search "<函数名关键词>"` — 是否有同名/同义函数已存在？
+2. `codegraph_callers "<依赖的接口>"` — 调用方是如何用的？是否有更优的调用模式（如 `WithContext` vs `Group`）？
+3. 新函数是否只是已有函数的薄封装？是 → 直接委托已有函数，不新建
+
+**代码注释规范**：
+```go
+// Ponytail L2: stdlib covers — use slices.Contains instead of custom Contains[T]
+// Ponytail L4: reuse existing — callLocalRPC[T] already defined
+// Ponytail L6: extracted generic — filterByWhitelist[T] covers 3 duplicates
+// Ponytail L7: minimal interface — OrderPayer has 2 methods, not 30-method IOrder
+```
+
+**自动扫描**（每次 git add 前）：
+```bash
+# 检查是否有 ≥10 个同构 CRUD
+codegraph_search "func.*Find.*ctx.Context" --kind=method | wc -l
+# 检查是否有 ≥5 个 Register  
+grep -rn "func Register" service/biz/ --include="*.go" | wc -l
+# 检查是否有 ≥3 个 RPC post
+grep -rn "httpclient.Post" service/rpc/ --include="*.go" | wc -l
+```
+
+### 5b3. R6 SQL 性能与缓存安全检查（写代码前）
+
+若任务涉及 SQL 查询或 Redis 写入（详见 `@atdc/reference/guards.md` R6），必须在写代码前执行检查：
+
+1. 识别任务中涉及的所有 SQL 操作和 Redis 写入点
+2. 逐项执行 R6-6a（慢查检查）和 R6-6b（大 Key 检查）
+3. 有风险 → 输出检查报告，**暂停等用户确认方案后继续**
+4. 无风险 → 继续
+
+### 5c. R5 破坏性变更检查（写代码前）
+
+若即将删除 ≥5 行 / 修改公共函数签名 / 删除接口：
+
+**1. CodeGraph 扫描直接调用方**：
+```
+codegraph_callers "<SymbolName>"
+codegraph_impact "<SymbolName>"
+```
+
+**2. Semble find_related 补盲区**（发现语义相似但无直接调用关系的关联代码）：
+```
+semble find-related <file> <line> .
+```
+> CodeGraph impact 只追踪调用边。接口语义变更（如返回值格式、错误码含义）可能影响无直接调用的下游。
+> Semble find_related 可发现这些语义关联的代码块。
+
+**3. grep 降级兜底**（仅前两者无结果时）：
+```
+grep -rn "<SymbolName>" --include="*.go" . | grep -v "_test.go" | grep -v vendor
+```
+
+展示引用列表 + Semble 发现的语义关联代码，等用户确认后才能继续。
+
+### 5d. R2 TDD（Gate 3）
+
+1. 先写 `_test.go`，测试函数含 `// Intent: <为什么这个行为重要>`
+2. 确认测试编译通过（RED）：`go build ./... 2>&1 | head -5`
+3. 写实现，测试通过（GREEN）：`go test ./<pkg>/... 2>&1 | grep -E "PASS|FAIL|ok"`
+4. 重构（REFACTOR）
+
+> ⚠️ RED 阶段测试失败重试 ≥ 2 次 → 不盲目猜测，自动切入诊断模式（遵循 `/atdc:diagnose` 6 阶段循环）：
+> 1. 复现：确认失败的测试命令和完整错误输出
+> 2. 最小化：隔离到最小失败单元（单个测试/单个函数）
+> 3. 假设：列出 ≥ 2 个可能的根因，按概率排序
+> 4. 插桩：在关键路径添加日志/断点验证假设
+> 5. 修复：确认根因后修复（仅改必要代码）
+> 6. 回归：运行全量相关测试确保不引入新问题
+>
+> 详见 `reference/diagnose-loop.md`。最多 3 轮诊断，3 轮后输出诊断报告并暂停等用户决策。
+
+### 5e. R4 越界检查（执行后）
+
+```bash
+git diff --name-only HEAD
+```
+对比实际修改文件 vs `**Files**:` 声明，有越界文件则停止等用户确认。
+
+### 5f. 更新进度
+
+```bash
+# 更新 .progress.json 的 completedTasks
+```
+
+### 5f2. 记录 Evidence 事件
+
+每完成一个任务后，记录 evidence 事件：
+
+```bash
+atdc evidence record <name> task_complete --phase=build --task=<task-id> --files="<changed-files>"
+```
+
+> evidence 事件自动写入 `openspec/changes/<name>/.evidence/events/`，供后续 Canvas 和度量使用。
+
+### 5g. Test Gap 快速检查（复杂级/标准级执行）
+
+每个任务完成后，对本次任务新增/修改的函数做轻量测试覆盖检查：
+
+```
+codegraph_callers "<NewOrModifiedFunction>"
+```
+
+检查返回的调用方中是否包含测试文件。**不阻塞执行**，仅记录到进度：
+
+```
+📊 Task N 测试覆盖：
+  ✅ loginHandler → TestLoginHandler
+  ❌ validateToken → 无测试调用方（建议补充）
+```
+
+简级任务跳过此步骤（参见 Step 2c 跳步规则）。
+
+---
+
+## Step 5.5：Harness 门禁（进入 C3 前）
+
+> **🔒 Harness 加固**：全部任务完成后、C3 验证前，运行 `atdc guard verify` 做脚本级硬性验证。
+> 该命令检查 tasks.md 无未勾选项 + verification_report 已设置，不通过则 `[HARD STOP]` 并返回非 0。
+> 此检查**不得跳过**，即使 AI 自认为全部完成也必须运行。
+
+### Step 5.5b：记录 Gate 检查证据
+
+```bash
+atdc evidence record <name> gate_check --phase=build --gate=guard_verify --result=passed
+```
+
+---
+
+## Step 6：C3 验证（Gate 4）
+
+逐条验证 tasks.md 的 `## Verification Checklist`：
+
+- 所有 SHALL/MUST 有对应实现和测试
+- `git diff --name-only` 对比追溯矩阵，无主变更需用户确认
+- 检查是否有绕过领域约束的直接操作（参考 AGENTS.md/CLAUDE.md）
+- 运行测试：`go test ./<pkg>/... 2>&1 | grep -E "PASS|FAIL|ok|SKIP"` （不用 -v，只看结论）
+
+验证失败 → 先诊断后修复（遵循 `/atdc:diagnose`）：
+1. 输出失败项的具体错误和上下文
+2. 按 6 阶段诊断循环定位根因（复现 → 最小化 → 假设 → 插桩 → 修复 → 回归）
+3. 针对性修复 → 重新验证
+4. 最多 3 轮诊断，3 轮后输出诊断报告并暂停等用户决策
+
+---
+
+## Step 7：C2 人工 Code Review
+
+暂停，输出：
+```
+🔍 C2 Code Review 等待审查：
+
+变更文件：
+<git diff --name-only 列表>
+
+Gate 4 结果：
+<无主变更列表 / 领域规则检查结果>
+
+请审查后回复"通过"或提出修改意见。
+```
+
+有修改意见 → 修复 → 重新展示，直到用户确认通过。
+
+---
+
+## Step 8：归档
+
+**Read `@atdc/prompts/5-done.md`**（其 Step -1 会加载 memory.md 规则），然后执行归档流程。

package/prompts/4-verify.md

@@ -0,0 +1,160 @@
+# prompts/4-verify · C3 验证
+
+---
+
+## 🔴 Step -1：规则加载（不读 = 不得执行）
+
+```
+Read @atdc/reference/risk.md → 风险评分算法（Step 0 评分所需）
+```
+
+> **Token 节约**：运行测试用 `go test ./<pkg>/... 2>&1 | grep -E "PASS|FAIL|ok"`，不加 `-v`
+
+---
+
+## Step 0：风险评级
+
+### 0a. 检查是否有 Review 报告
+
+```bash
+cat openspec/changes/<name>/review-report.md 2>/dev/null && echo "---EXISTS---" || echo "[无 review 报告]"
+```
+
+如有 review 报告，直接读取风险评分。
+
+### 0b. 无 Review 报告时自动计算风险评分
+
+### 0c. Ponytail 变更检查（检测新增过度工程化）
+
+```bash
+# 扫描本次变更是否引入新的过度工程化代码
+atdc ponytail scan --diff 2>/dev/null || echo "[Ponytail scan skipped]"
+```
+
+> 如果发现新增 P2 模式 → 记录到验证报告，建议在下次迭代修复
+> 如果发现新增 P0/P1 模式 → **暂停**，提醒用户当前 diff 在重复已有模式
+
+---
+
+```
+codegraph_impact "<SymbolName>" depth=2
+```
+
+按 `@atdc/reference/risk.md` 算出总分（4-12 分），确定风险等级：
+
+| 总分 | 等级 | 验证严格度 |
+|------|------|-----------|
+| 4-6 | 🟢 低风险 | 增量验证（只跑变更相关的测试） |
+| 7-9 | 🟡 中风险 | 标准验证（跑变更模块的全量测试） |
+| 10-12 | 🔴 高风险 | 全量验证（全量测试 + 受影响流程 E2E + 人工二次确认） |
+
+宣布：`"风险等级：🟢/🟡/🔴（<分数>/12），验证严格度：<增量/标准/全量>"`
+
+---
+
+## Step 1：逐条检查 Verification Checklist
+
+读取 `openspec/changes/<name>/tasks.md` 的 `## Verification Checklist`：
+
+```bash
+grep "- \[ \]" openspec/changes/<name>/tasks.md
+```
+
+对每条 SHALL/MUST：
+1. 找到对应实现文件，确认代码存在（优先用 `codegraph_search` 定位，而非 `grep`）
+2. 运行测试确认通过：`go test ./<pkg>/... 2>&1 | grep -E "PASS|FAIL|ok"`
+3. 打勾 `- [x]`
+
+**按风险等级调整测试范围**：
+- 🟢 低风险：只跑变更包的测试 `go test ./<changed-pkg>/...`
+- 🟡 中风险：跑变更模块及直接依赖模块的测试
+- 🔴 高风险：全量测试 `go test ./...`
+
+---
+
+## Step 2：Gate 4 — 实现一致性 + Test Gap
+
+```bash
+git diff --name-only HEAD
+```
+
+对比追溯矩阵（`.progress.json` 的 `traceability`）：
+- 不在矩阵中的变更文件 → 标为"无主变更"，列出等用户确认
+- 检查 AGENTS.md/CLAUDE.md 中的领域约束是否被绕过
+
+### 2a. Test Gap 最终检查
+
+对每个变更文件中的新增/修改函数：
+
+```
+codegraph_callers "<FunctionName>"
+```
+
+检查返回的调用方中是否包含测试文件。汇总 3-impl 执行中记录的覆盖情况：
+
+```
+📊 最终测试覆盖汇总
+
+✅ 已覆盖：N 个函数
+❌ 未覆盖：M 个函数（列出）
+
+🔴 高风险变更中未覆盖的函数必须补充测试。
+🟡 中风险变更中未覆盖的函数建议补充。
+🟢 低风险变更中未覆盖的函数可接受。
+```
+
+🔴 高风险 + 未覆盖 → **阻塞**，必须补充测试后才能继续。
+
+---
+
+## Step 3：报告
+
+```
+📋 C3 验证报告
+
+风险等级：🟢/🟡/🔴（<分数>/12）
+验证严格度：<增量/标准/全量>
+
+✅ 通过：N 条 SHALL/MUST
+❌ 未通过：
+  - [ ] <需求描述> → <原因>
+
+⚠️  无主变更：<文件列表>
+📊 测试覆盖：已覆盖 N / 未覆盖 M
+
+是否修复后重新验证？[是 / 跳过]
+```
+
+验证失败 → 自动修复 → 重新验证（最多 3 轮）。
+
+全部通过后：
+
+---
+
+## Step 3.5：Session Reflection — 检测 golden path
+
+> C3 验证刚完成，整个 change 的执行路径还 fresh。趁现在反思：**这次有没有学到值得沉淀的东西？**
+
+1. 检查 `.progress.json` 的 `failedAt` / `failedReason` 字段：
+   ```bash
+   python3 -c "
+   import json
+   with open('openspec/changes/<name>/.progress.json') as f:
+       d = json.load(f)
+   print('failedAt:', d.get('failedAt'))
+   print('failedReason:', d.get('failedReason'))
+   "
+   ```
+
+2. 若有失败记录 → 说明本次 change 涉及超过 2 次尝试的操作 → 触发 `/atdc:learn --auto`（静默模式，不交互）
+
+3. 无失败记录但涉及非显而易见操作 → 提示用户：
+   ```
+   💡 本次 change 执行过程中是否学到了值得沉淀的路径？
+      - 说"learn"或"/atdc:learn" → 手动触发 golden path 检测
+      - 说"继续" → 跳过，进入归档
+   ```
+
+4. 无特殊操作 → 静默跳过，然后 **Read `@atdc/prompts/5-done.md`** 进入归档。
+
+> 若触发 learn，完成后继续 **Read 5-done.md**。