@kunlv/atdc 1.0.0

package/reference/diagnose-loop.md

@@ -0,0 +1,66 @@
+# reference/diagnose-loop · 结构化调试方法论
+
+每个 Phase 对应 `/atd:diagnose` 的一个阶段，也由 `3-impl` 的 TDD 失败 / C3 验证失败自动引用。
+
+---
+
+## 6 阶段循环
+
+```
+复现(Reproduce) → 最小化(Minimise) → 假设(Hypothesise) → 插桩(Instrument) → 修复(Fix) → 回归测试(Regression-test)
+        ↑                                                                                          │
+        └────────────────────────── 失败则回退 ─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 各阶段判定标准
+
+| 阶段 | 通过标准 | 不通过则 |
+|------|---------|---------|
+| Reproduce | 有可重复的复现命令/步骤 | 继续收集信息 |
+| Minimise | 最小用例 ≤ 50 行 / ≤ 5 步 | 继续剥离 |
+| Hypothesise | ≥ 2 个有预测的假设 | 重新分析 |
+| Instrument | 插桩输出与某假设的预测一致 | 标记该假设为否定，验证下一个 |
+| Fix | 复现用例通过 + 全量测试通过 | 回到 Hypothesise |
+| Regression-test | 新增回归测试 + 相关测试套件通过 | 补充回归测试 |
+
+---
+
+## 自动切入规则（3-impl 内）
+
+触发条件：
+- TDD RED 阶段测试失败 ≥ 2 次（同一任务）
+- C3 验证失败
+
+切入后：
+- 从失败的测试命令/错误输出自动提取 Reproduce 信息
+- 不询问用户，直接从已有上下文开始
+- 最多 3 轮循环，3 轮后输出调试报告并暂停等用户决策
+
+---
+
+## 调试报告格式
+
+```
+🔬 调试报告 — <问题描述>
+
+已排除假设：
+- <假设1>：<排除原因>
+- <假设2>：<排除原因>
+
+剩余假设：
+- <假设3>：<为什么仍有可能>
+
+建议下一步：
+- <具体行动>
+```
+
+---
+
+## 原则
+
+- 禁止「试试改这里看看」的猜测式修复
+- 每次修改必须有明确的假设支撑
+- 修复后必须跑回归测试（不只是当前测试）
+- 不得引入 `// TODO`、`// FIXME`、`// HACK` 标记（除非用户明确同意）

package/reference/gates.md

@@ -0,0 +1,90 @@
+# reference/gates · 质量门禁
+
+4 个门禁在 3-impl.md 的 Step 3/4 和 Step 6 中自动触发。
+
+---
+
+## Gate 1：Spec 质量检查
+
+扫描 `openspec/changes/<name>/specs/` 下所有 spec.md。
+
+**弱需求检测**：
+- 含 `should`/`could`/`might`/`可能`/`尽量`/`应该`（非 SHALL/MUST 语境）→ 标为弱需求
+- 每条需求必须含 `SHALL` 或 `MUST`
+
+**验收标准检查**：
+- 每个 `Scenario:` 必须有 Given/When/Then 或可量化的预期结果
+
+**边界场景覆盖**：
+- 空值/null 输入
+- 超限/超大输入
+- 并发/竞态场景
+- 降级/容错场景
+
+**错误路径检查**：
+- 每个 happy path 是否有对应 sad path
+
+**报告格式**：
+```
+📋 Gate 1 Spec 质量报告
+  ✅ 强需求 (SHALL/MUST): N 条
+  ⚠️  弱需求: N 条 → [列表]
+  ⚠️  无验收标准: N 条 → [列表]
+  ⚠️  缺边界场景: N 个 → [列表]
+  ⚠️  缺错误路径: N 个 → [列表]
+
+继续执行？[是 / 修复后继续 / 跳过检查]
+```
+
+---
+
+## Gate 2：追溯矩阵
+
+读取 tasks.md + `openspec/changes/<name>/specs/`，生成映射写入 `.progress.json`：
+
+```json
+{
+  "traceability": [
+    {
+      "requirement": "REQ-001: 系统SHALL支持XXX",
+      "task": "Task 3",
+      "testFile": "path/to/xxx_test.go",
+      "implFile": "path/to/xxx.go"
+    }
+  ]
+}
+```
+
+**报告**：
+- spec 需求无对应 task → **需求遗漏**
+- task 无对应 spec 需求 → **隐性需求**（建议补 spec）
+- task 无测试文件 → **缺测试**（Gate 3 再检查）
+
+---
+
+## Gate 3：测试意图（执行中）
+
+每个测试函数必须包含：
+```
+// Intent: <为什么这个行为重要，而不仅是它做了什么>
+func TestXxx_Scenario(t *testing.T) { ... }
+```
+
+- 缺 `// Intent:` → 标为"无意图测试"
+- Intent 只重复函数名（"测试批量退款"）→ 标为"弱意图"，要求重写
+
+---
+
+## Gate 4：实现一致性（C3）
+
+```bash
+git diff --name-only HEAD
+```
+
+**功能蔓延检测**：
+- 对比 `traceability` 的 implFile 列表
+- 不在矩阵中的变更文件 → "无主变更"，列出等用户确认
+
+**领域规则检查**：
+- 读取 AGENTS.md/CLAUDE.md 中的约束
+- grep 检查变更文件是否绕过约束（如直接 DB 操作绕过分片路由）

package/reference/git-guardrails.md

@@ -0,0 +1,71 @@
+# reference/git-guardrails · Git 安全防护
+
+atd-code 内置 git hook 防护，拦截高风险操作。
+
+---
+
+## 安装
+
+`install.sh` 自动处理：
+
+```bash
+# install.sh 会执行：
+ln -sf ~/atd-code/hooks/guardrails.sh .git/hooks/pre-push
+```
+
+也可手动安装到已有项目：
+
+```bash
+ln -sf ~/atd-code/hooks/guardrails.sh .git/hooks/pre-push
+```
+
+卸载：
+
+```bash
+rm .git/hooks/pre-push
+# 恢复默认：
+# cp .git/hooks/pre-push.sample .git/hooks/pre-push
+```
+
+---
+
+## 拦截规则
+
+| 操作 | 行为 | 原因 |
+|------|------|------|
+| `git push` 到 main/master | ❌ 拦截 | 应通过 PR/MR 合并 |
+| `git push --force` 到 main/master | ❌ 拦截 | 不可逆破坏 |
+| `git push --delete` main/master | ❌ 拦截 | 不可逆破坏 |
+| WIP commit 推送 | ⚠️ 警告 | 建议 squash 后推送 |
+| `git stash` 后推送 | ⚠️ 提示 | 提醒检查是否有未完成工作 |
+
+非 main/master 分支的普通 push 不受影响。
+
+---
+
+## 自定义规则
+
+编辑 `hooks/guardrails.sh`，在 `# CUSTOM RULES` 标记处添加：
+
+```bash
+# 示例：禁止推送包含 TODO 的 commit
+if git log $remote_sha..$local_sha --oneline | grep -q "TODO"; then
+  echo "❌ commit 中包含 TODO，请处理后再推送"
+  exit 1
+fi
+```
+
+---
+
+## 在 atd-code 工作流中的位置
+
+- **安装**：一次性（install.sh），非流程步骤
+- **提醒**：`3-impl` 执行前检测 hook 是否存在；不存在则输出一次性提醒
+- **规则**：`guards.md` R7 记录为硬性规则
+
+---
+
+## 与其他 git 工具的兼容
+
+- 与 Husky pre-commit hook 不冲突（pre-push 和 pre-commit 是不同阶段）
+- 如项目已有自定义 pre-push hook，install.sh 会跳过并提示手动合并

package/reference/guards.md

@@ -0,0 +1,275 @@
+# reference/guards · 硬性拦截规则
+
+> 🔴 此文件是**可执行规则**，不是参考文档。
+> 以下每条规则中的 MUST / HARD STOP / 禁止 / 不得 均有强制执行效力。
+> 3-impl.md Step -1 已强制加载此文件。若未加载 → 回退重新加载。
+
+所有规则在执行阶段强制生效，不得跳过或绕过。
+
+---
+
+## R1 前置检查
+
+change 目录必须包含以下全部文件才能开始执行：
+
+| 文件 | 说明 |
+|------|------|
+| `proposal.md` | 背景、方案、排除选项 |
+| `design.md` | 模块、接口、数据流 |
+| `tasks.md` | 任务清单 + Verification Checklist |
+| `specs/*/spec.md` | 至少一个模块的 delta spec |
+
+change 目录位于 `openspec/changes/<name>/`，任一缺失 → 停止，不得用"先跳过"绕过。
+
+---
+
+## R2 TDD 强制
+
+每个任务写实现代码**之前**，必须：
+
+1. 创建对应测试文件（`_test.go` 或对应语言的测试文件）
+2. 每个测试函数包含 `// Intent: <为什么这个行为重要>`（不是描述做了什么）
+3. 测试编译通过后，才允许写实现
+
+跳过测试直接写实现 → 停止，必须补测试后继续。
+
+**完整循环**：RED（测试失败）→ GREEN（实现通过）→ REFACTOR（清理）→ 缺任何一步 = 任务未完成。
+
+---
+
+## R3 归档强制
+
+归档时**禁止**直接 `mv`/`cp` 目录到 archive，必须按顺序：
+
+1. 先将 `openspec/changes/<name>/specs/` 合并到 `openspec/specs/<module>/spec.md`
+2. 再 `mv openspec/changes/<name> openspec/changes/archive/<name>`
+
+---
+
+## R4 文件边界声明
+
+**执行前**：任务必须有 `**Files**:` 字段，缺失则停止。
+
+**执行后**：`git diff --name-only HEAD` 对比声明文件列表：
+- 有越界文件 → 停止，等用户确认接受或回滚
+- 声明文件完全未改动 → 询问任务是否真的完成
+
+---
+
+## R5 破坏性变更门槛
+
+触发条件（任一满足）：
+- 删除代码 ≥ 5 行
+- 修改公共函数/方法签名
+- 删除或重命名公共接口/结构体
+- **修改被 >5 个调用方依赖的公共符号**（通过 `codegraph_impact` 确认）
+
+必须先执行（**优先 CodeGraph，次选 grep**）：
+```
+# 首选
+codegraph_callers "<SymbolName>"
+codegraph_impact "<SymbolName>"
+
+# 次选（CodeGraph 无结果时）
+grep -rn "<SymbolName>" --include="*.go" . | grep -v "_test.go" | grep -v vendor
+```
+
+展示引用列表 + 引用数 + **风险评分**（按 `@atd-code/reference/risk.md` 计算，3-impl Step -1 已加载），等用户确认后才能动。
+
+高风险（blast radius >10 个调用方或跨 ≥3 模块）变更需**额外说明替代方案和回滚策略**。
+
+---
+
+## R6 SQL 性能与缓存安全检查
+
+触发条件（任务涉及以下**任一**操作时）：
+- 新增/修改 SQL 查询（包括 ORM 调用：Find/Count/Where/Group/Create/Update/Delete 等）
+- 写入 Redis 缓存（Set/SETNX/HSet/ZSet/SAdd/批量写入 Pipeline/MSet 等）
+
+### 6a. 慢查检查
+
+对涉及 SQL 的代码，必须结合上下文（表结构、索引定义、数据量、调用频率）判断：
+
+| 检查项 | 判定标准 |
+|--------|---------|
+| WHERE 列是否有索引 | 查表结构/索引定义，确认条件列是某索引的前缀列 |
+| N+1 查询 | 循环/遍历内逐条查询 DB，应改为批量 IN 或 JOIN |
+| IN list 规模 | IN (...) 的元素数量不可控或可能上千，应分批或改写 |
+| GROUP BY / ORDER BY | 是否有索引支撑，避免 filesort / temporary table |
+| 全表扫描风险 | WHERE 条件无索引前缀可用，或 OR 跨索引 |
+| 子查询性能 | 子查询是否可改为 JOIN，是否产生笛卡尔积 |
+
+发现问题 → 输出格式：
+```
+⚠️ [R6-6a] 潜在慢查风险
+  位置: <file:line>
+  SQL/ORM: <具体调用>
+  风险: <无索引 / N+1 / 大IN / 全表扫描等>
+  建议: <加索引 SQL / 改批量查询 / 分批等>
+```
+**暂停，等用户确认方案后继续。**
+
+### 6b. 大 Key 检查
+
+对涉及 Redis 写入的代码，必须检查：
+
+| 检查项 | 判定标准 |
+|--------|---------|
+| Value 大小 | 是否为未限制大小的结构（未分页的 List、大 Hash、大 JSON、未截断的字符串） |
+| TTL 合理性 | 缓存 Key 是否设置 TTL，TTL 是否过长（>24h 无业务理由） |
+| 批量写入量 | Pipeline/MSet 一次写入的 Key 数量是否过大（>1000） |
+| Key 命名规范 | 是否符合项目 Key 命名规范，避免冲突 |
+
+发现问题 → 输出格式：
+```
+⚠️ [R6-6b] 潜在大 Key 风险
+  位置: <file:line>
+  写入点: <具体调用>
+  风险: <Value 无限大 / 无 TTL / 批量过多等>
+  建议: <分片/压缩/设 TTL/分批等>
+```
+**暂停，等用户确认方案后继续。**
+
+### 不触发 R6 的情况
+
+以下场景**不需要** R6 检查（避免误拦截）：
+- 仅修改非 SQL/非 Redis 的业务逻辑代码
+- 仅修改常量、配置、日志、错误处理等
+- 查询已有稳定运行且未报慢查的只读接口（无新增/修改 WHERE 条件）
+
+---
+
+## R7 风险分级验证
+
+4-verify 阶段根据风险评分（按 `@atd-code/reference/risk.md` 计算）决定验证严格度：
+
+| 风险等级 | 验证要求 |
+|---------|---------|
+| 🟢 低风险（4-6 分） | 增量验证：只跑变更包的测试 + Verification Checklist |
+| 🟡 中风险（7-9 分） | 标准验证：跑变更模块的全量测试 + Test Gap 检查 |
+| 🔴 高风险（10-12 分） | 全量验证：全量测试 + Test Gap 检查 + 受影响流程 E2E + 人工二次确认 |
+
+### 风险评分来源
+
+优先级：
+1. `/atd review` 生成的 review 报告中的评分
+2. 4-verify Step 0 自动计算的评分
+3. 1-spec Phase 3 的预估评分（仅作参考，不作为最终依据）
+
+### 🔴 高风险的额外要求
+
+高风险变更在 4-verify 阶段必须：
+- 所有变更函数都有测试覆盖（Test Gap 检查无 ❌）
+- 受影响的用户流程有对应的集成测试或 E2E 测试
+- 输出变更影响范围报告供人工二次确认
+
+高风险 + Test Gap → **阻塞**，不允许跳过。
+
+---
+
+## B5 Ponytail 决策梯
+
+> 🔴 此规则为强制性自动检查，不得以"看起来不需要"为由跳过。
+> 💡 **L2-L5 检测加速**：用 `/atd:search "<query>"` 或 Semble MCP 查找已有实现模式。
+> 语义搜索例：`semble search "whitelist filter" .` → 直接返回相关代码块，比逐关键词 grep 快 10x+。
+> CodeGraph 结构化查询（callers/callees/impact）不受影响，继续使用。
+
+每个 task 新建文件/函数前，MUST 逐级检查并按以下格式标注代码注释：
+
+```go
+// Ponytail L{N}: <decision>
+```
+
+### 梯级
+
+**L1 需求必要性** — 对照 spec SHALL/MUST
+- 跳过条件：spec 未覆盖的"将来可能需要"功能
+- 不适用场景：事务一致性、数据完整性、鉴权逻辑
+
+**L2 语言/stdlib** — Go 内建能力
+- `slices.Contains` / `maps.Clone` / `cmp.Or` (Go 1.21+)
+- `time.Format` / `strconv` / `encoding/json` / `net/http`
+- `errors.Is` / `errors.As` / `fmt.Errorf("%w")` (Go 1.13+)
+- 优先用 CodeGraph 查找标准库用法：
+  ```
+  codegraph_search "<关键词>"
+  codegraph_callers "<FunctionName>"
+  ```
+
+**L3 已有依赖** — go.mod 里的依赖
+- `samber/lo` (functional) / `cenkalti/backoff` (retry)
+- `google/wire` (DI) / `gorm/gen` (codegen)
+- CodeGraph 无结果时才用 grep：
+  ```bash
+  grep -rn "<关键词>" --include="*.go" . | grep -v "_test.go" | grep -v vendor | head -20
+  ```
+
+**L4 项目已有模式** — `codegraph_context` 确认
+- CRUD → 复用 BaseModel 模式
+- RPC → 复用 callRPC 模式
+- Filter → 复用 `slices.Contains` / `lo.Filter`
+- DI → 复用容器
+- 错误处理 → 复用 middleware
+
+**L5 一行搞定** — 单个函数调用
+
+**L6 泛型消除** — 同一项目 ≥3 处相似代码
+- RPC 同构 → `callLocalRPC[T]`
+- CRUD 同构 → `BaseModel[T]`
+- Config Contains → `slices.Contains`
+- 白名单 filter → `filterByWhitelist[T]`
+- 检测到 ≥3 次重复 → **暂停，先提取泛型**
+
+**L7 最小接口** — interface ≤ 5 methods
+- 调用方只需 1-2 个方法 → 拆分为小接口（ISP 原则）
+
+**L8 不可省略** — 安全/性能边界（以下不得以 Ponytail 为由跳过）
+- R5: blast radius 检查（`codegraph_impact`）
+- R6: SQL 索引/N+1/IN 规模，Redis value 大小/TTL/批量
+- 事务边界、auth middleware、错误处理
+
+### 18 种后端可优化模式速查表
+
+| # | 优先级 | 模式 | 检测方式 | 梯级 | Ponytail 动作 |
+|---|--------|------|---------|------|-------------|
+| 1 | P0 | CRUD 模板重复 | `codegraph_search "func.*Find.*ctx" method > 10` | L6 | 提取 BaseModel[T] |
+| 2 | P0 | RPC 调用模板 | `grep "httpclient.Post" service/rpc/ > 3` | L6 | 提取 callLocalRPC[T] |
+| 3 | P1 | Service Locator DI | `grep "func Register" service/biz/ > 5` | L3 | 泛型 DI 容器 |
+| 4 | P1 | init() 碎片 | `find service/ -name "*_init.go" > 5` | L8 | 合并到统一 init |
+| 5 | P1 | 错误框架冗余 | `ls internal/errors/gerror/ > 3` | L2 | stdlib errors |
+| 6 | P1 | 白名单 filter 同构 | `codegraph_callers "BuildWhitelistExcludeSet" > 2` | L6 | 提取泛型 |
+| 7 | P2 | 自定义 Contains/Filter | `grep "func.*Contains\\[" utils/ > 0` | L2 | slices.Contains |
+| 8 | P2 | Time 工具函数 | `grep "TimeToString" utils/ > 0` | L2 | time.Format |
+| 9 | P2 | Phone 工具函数 | `grep "FormatPhoneNumber" utils/ > 0` | L3 | 直调 nyaruka/phonenumbers |
+| 10 | P2 | Config type 重复 | `grep "type Apollo.*Config \\[" rtconf/ > 5` | L6 | 合并通用 type |
+| 11 | P2 | BizError 重复 | `codegraph_callers "BizError" > 10` | L4 | 提取 middleware |
+| 12 | P2 | GenCURL | `codegraph_callers "GenCURL" > 0` | L2 | HTTP 库内建 |
+| 13 | P2 | getServerIP | `codegraph_search "getServerIP" > 0` | L2 | net.InterfaceAddrs |
+| 14 | P2 | Custom retry | `grep "retry" utils/ > 0` | L3 | cenkalti/backoff |
+| 15 | P2 | GORM tags 样板 | 手动审查 models/ | L8 | gorm/gen 或 sqlc |
+| 16 | P2 | 大 interface | `codegraph_node "IOrder" methods > 15` | L7 | 拆分小接口 |
+| 17 | P2 | WxPay 同构 | `grep "Wx.*Pay" pay_service.go > 1` | L6 | 合并+参数化 |
+| 18 | P2 | Convert/Map 重复 | `grep "convertTo" service/ > 3` | L6 | 提取 mapper |
+
+找到 → 沿用并标注 `// Ponytail L{N}: <理由>`
+未找到 → 新建并标注 `// Ponytail L{N}: new — N levels checked`
+
+主观判断"肯定没有"也必须查后确认，不得跳过梯级。
+
+---
+
+## R8 Git 安全防护
+
+git-guardrails hook 应在项目初始化时安装（`install.sh` 自动处理）。
+
+**已安装时**，以下操作被拦截：
+- 直接推送到 main/master 分支
+- force push 到 protected 分支
+- WIP commit 推送（警告）
+
+**未安装时**，`3-impl` 执行前输出一次性提醒：
+> ⚠️ git-guardrails 未安装。建议运行 `bash ~/atd-code/install.sh` 安装防护 hook。
+
+**手动安装**：`ln -sf ~/atd-code/hooks/guardrails.sh .git/hooks/pre-push`
+
+详见 `reference/git-guardrails.md`。

package/reference/learn.md

@@ -0,0 +1,100 @@
+# reference/learn · self-learning → atd 桥接协议
+
+---
+
+## 核心原则
+
+self-learning-skills 提供 detection（何时该沉淀），atd-code 提供 persistence（沉淀到哪里）。
+
+桥接层负责：**detection 触发 → 按类型路由到 atd 的 3 层记忆系统**。
+
+---
+
+## 3 层路由规则
+
+```
+self-learning detection 检测到 golden path
+        │
+        ├─ 单事实 / 一行纠正（env var 名、路径、一个 gotcha）
+        │   └─→ .memory.md（⚠️ gotcha 类型）
+        │
+        ├─ 失败模式 + 至少一个死路（超 2 次尝试才解决的问题）
+        │   └─→ .errors-log.md（🔴 bugfix pattern）
+        │       + .memory.md 中追加简记（交叉引用）
+        │
+        └─ 满足 promotion rule（3 条件全满足）
+            ├─ 验证通过（测试通过 / 命令退出 clean）
+            ├─ 命名了失败模式
+            └─ 排除了至少一个死路
+            │
+            └─→ 自动调用 add-command.py --from-learn
+                生成 /atd:<name> 命令（4 端） + prompt（含 what didn't work section）
+```
+
+---
+
+## Promotion rule（来自 self-learning）
+
+skill 是权威的——下次 session 无条件信任它。只有 **3 条全满足** 才晋升：
+
+1. **A passing check** — 路径已被验证（测试通过 / 命令退出 clean / build green）
+2. **A named failure pattern** — 能命名这个路径避免/诊断的失败模式
+3. **At least one ruled-out dead-end** — 至少一个具体被排除的尝试 + 原因
+
+缺任何一条 → 留 memory note，不晋升 skill。
+
+---
+
+## 写入格式
+
+### → .memory.md（gotcha / learned-skill）
+
+```markdown
+## 🧠 [YYYY-MM-DD] <skill-name>  | ~150t
+done: <一句话描述学到的流程>
+decided: <核心操作步骤，关键词>
+failure: <这个 skill 避免的失败模式>
+dead-end: <被排除的死路>
+```
+
+类型图标 `🧠` = learned-skill（新类型）。
+
+### → .errors-log.md（failure pattern）
+
+```markdown
+## [YYYY-MM-DD] <skill-name> / auto-harvest
+
+- **失败路径**: <尝试了什么，为什么不 work>
+- **成功路径**: <最终通过的路径>
+- **教训**: <一句话>
+- **关联 skill**: /atd:<name>
+```
+
+### → atd 命令（promotion 成功时）
+
+调用 `add-command.py --from-learn`，生成的 prompt 模板包含：
+
+- `## 执行步骤` — 操作流程
+- `## What didn't work` — 被排除的死路
+- `## 失败模式` — 这个 skill 避免的诊断
+- `## 验证方式` — passing check
+
+---
+
+## 检测触发时机
+
+| 触发点 | 位置 | 行为 |
+|--------|------|------|
+| Session 启动 | GO.md Step 0d | 注入 self-learning detection prompt（静默） |
+| C3 验证完成 | 4-verify.md Step 3.5 | 反思：本次 change 有没有值得沉淀的路径？ |
+| 归档前 | 5-done.md Step 0.5 | Learn checkpoint：检查 promotion rule |
+| 手动触发 | /atd:learn | 强制检测当前 session 的 golden path |
+| compound 扫描 | X-compound.md | 扫描未晋升的 harvested skill，提示晋升 |
+
+---
+
+## 安全红线
+
+- **绝不写入 secret value** — 只记录 env var 名 / MCP 工具名 / selector 函数
+- **promotion rule 严格执行** — "seemed to work" 不晋升
+- **skill 写入前 dedup** — 检查是否已有同名或相似 skill