@kunlv/atdc 1.0.0

package/prompts/5-done.md

@@ -0,0 +1,227 @@
+# prompts/5-done · 归档 + 写记忆
+
+---
+
+## 🔴 Step -1：规则加载
+
+```
+Read @atdc/reference/memory.md → 跨 session 记忆协议（Step 3 写入格式所需）
+```
+
+---
+
+## Step 0.5：Learn Checkpoint — promotion rule 终检
+
+> 此时 change 已完成，所有测试已通过，操作路径已完整验证——正是晋升 golden path 的最佳时机。
+
+检查当前 change 是否在 4-verify.md Step 3.5 中触发了 `/atdc:learn --auto`：
+- 已触发 → 确认 learn 结果已写入（skill 或 memory），继续 Step 0.6
+- 未触发 → 执行以下终检：
+
+```bash
+# 检查 .progress.json 中是否有失败记录
+python3 -c "
+import json
+with open('openspec/changes/<name>/.progress.json') as f:
+    d = json.load(f)
+if d.get('failedAt') or d.get('failedReason'):
+    print('HAS_FAILURES')
+else:
+    print('CLEAN')
+"
+```
+
+- `HAS_FAILURES` → 自动触发 `/atdc:learn --auto`（静默），沉淀失败模式到 `.errors-log.md`
+- `CLEAN` → 静默跳过
+
+### 0.6：Harness 门禁 + Ponytail 收尾
+
+> **🔒 Harness 加固**：若项目已安装 harness 层（存在 `hooks/flow-archive.sh`），
+> 推荐使用 `atdc archive <name>` 一键完成 sync + move + state update。
+> 该命令自动调用 phase guard 验证前置条件，失败则 `[HARD STOP]`。
+>
+> 若未安装 harness，则手动执行以下 Step 1-2。
+
+```bash
+# Ponytail 收尾扫描 — 归档前看看整个项目还剩多少可优化模式
+atdc ponytail scan --warn 2>/dev/null || echo "[Ponytail scan skipped]"
+```
+
+> 扫描结果写入本次 change 的记忆条目，供下次 session 恢复时参考。
+
+---
+
+## Step 1：Sync delta specs
+
+> **💡 省钱提示**：归档阶段涉及 spec 合并和记忆写入，输出约 1-3K token。输出量不大，可跳过切模型。
+
+### Step 1a：记录完成事件 + 采集 AI Draft 指标
+
+```bash
+atdc evidence record <name> done --phase=archive
+atdc evidence metrics <name> --commit
+atdc evidence canvas <name>
+```
+
+> 这会在 `.evidence/` 下记录 final metrics snapshot、生成 Canvas HTML，标记 done 事件。
+> Canvas 路径：`openspec/changes/<name>/.evidence/canvas.html`
+
+将 `openspec/changes/<name>/specs/` 下的变更合并到主 spec：
+
+```bash
+# 对每个 openspec/changes/<name>/specs/<module>/spec.md
+# 检查 openspec/specs/<module>/spec.md 是否存在：
+#   存在 → 将 delta 内容追加合并（保留原有内容，追加新增需求）
+#   不存在 → 直接复制：cp openspec/changes/<name>/specs/<module>/spec.md openspec/specs/<module>/spec.md
+```
+
+无 delta specs 则跳过。
+
+---
+
+## Step 2：标记完成并归档目录
+
+```bash
+# 将 .progress.json 的 status 更新为 completed
+if [ -f "openspec/changes/<name>/.progress.json" ]; then
+  python3 -c "
+import json, sys
+with open('openspec/changes/<name>/.progress.json') as f: d = json.load(f)
+d['status'] = 'completed'
+d['currentStep'] = 'archived'
+with open('openspec/changes/<name>/.progress.json', 'w') as f: json.dump(d, f, indent=2)
+"
+fi
+
+# 🔴 更新 phase 为 archive（触发 evidence PostToolUse hook）
+python3 -c "
+import json
+with open('openspec/changes/<name>/.phase-state.json') as f: d = json.load(f)
+d['phase'] = 'archive'
+d['archived'] = True
+with open('openspec/changes/<name>/.phase-state.json','w') as f: json.dump(d,f,indent=2)
+"
+
+mkdir -p openspec/changes/archive
+mv openspec/changes/<name> openspec/changes/archive/<name>
+```
+
+**归档命名规则**：保持 change 名称原样，不加日期前缀。
+
+---
+
+## Step 3：写入跨 session 记忆（不得跳过）
+
+从归档目录读取 proposal.md 和 design.md，提取关键决策，用**压缩格式**写入（控制在 5-8 行以内）。
+
+**类型图标选择**：从以下选一个最匹配的，放在 header 前缀：
+- 🟢 feature（新功能）| 🔴 bugfix（修 bug）| 🟤 decision（架构决策，默认）| 🟡 refactor（重构）| ⚖️ tradeoff（明确取舍）| ⚠️ gotcha（发现坑）| 🧠 learned-skill（self-learning 自动沉淀）
+
+```bash
+_PROJ=$(basename "$(git worktree list 2>/dev/null | head -1 | awk '{print $1}')" 2>/dev/null || basename "$PWD")
+MEMORY_DIR="$HOME/.atdc/memory/$_PROJ"
+mkdir -p "$MEMORY_DIR"
+cat >> "$MEMORY_DIR/.memory.md" << EOF
+
+## 🟤 [$(date +%Y-%m-%d)] <change-name>  | ~150t
+done: <一句话描述完成的内容>
+decided: <核心技术决策，关键词即可>
+rejected: <排除的方案及原因，无则删此行>
+open: <未解决假设，无则删此行>
+EOF
+```
+
+**格式说明**：
+- `🟤` 替换为对应类型图标
+- `~150t` 为 token 估算（按内容约 100-200）
+- `rejected:` 和 `open:` 如无内容则删除整行（不留空行）
+- 总行数控制在 5-8 行（含 header）
+
+写完输出：`✓ 已写入项目记忆 ~/.atdc/memory/<项目名>/.memory.md`
+
+---
+
+## Step 3.5（可选）：生成交接文档
+
+压缩记忆适合 AI 快速恢复上下文，但人类接手者可能需要更多细节。
+
+> 是否需要生成完整交接文档（包含决策上下文、关键文件路径、未解决问题）？
+> - 说 `handoff` → 生成 `docs/handoffs/<change-name>.md`：
+>   格式参考 `templates/handoff.md`：
+>   - 做了什么（Why + What，不是 How）
+>   - 关键决策 + 排除方案
+>   - 受影响模块清单
+>   - 未解决的假设 / 技术债
+>   - 下次从哪里继续
+> - 说 `继续` → 跳过，继续归档
+
+---
+
+## Step 4：自动裁剪记忆（超过 20 条时）
+
+```bash
+MEMORY_FILE="$MEMORY_DIR/.memory.md"
+ARCHIVE_FILE="$MEMORY_DIR/.memory-archive.md"
+
+COUNT=$(grep -c "^## " "$MEMORY_FILE" 2>/dev/null || echo 0)
+
+if [ "$COUNT" -gt 20 ]; then
+  OVERFLOW=$((COUNT - 20))
+
+  # 找到第 OVERFLOW+1 条记录的起始行号（即保留部分的开头）
+  KEEP_FROM=$(grep -n "^## " "$MEMORY_FILE" | awk -F: "NR==$((OVERFLOW + 1)) {print \$1}")
+
+  # 将最旧的 OVERFLOW 条追加到归档文件（时间倒序：新内容在前）
+  OVERFLOW_CONTENT=$(head -n $((KEEP_FROM - 1)) "$MEMORY_FILE")
+  if [ -f "$ARCHIVE_FILE" ]; then
+    # 追加到归档文件头部（最新归档在最前）
+    echo -e "$OVERFLOW_CONTENT\n$(cat $ARCHIVE_FILE)" > "$ARCHIVE_FILE"
+  else
+    echo "$OVERFLOW_CONTENT" > "$ARCHIVE_FILE"
+  fi
+
+  # 只保留最新 20 条
+  tail -n +$KEEP_FROM "$MEMORY_FILE" > "$MEMORY_FILE.tmp"
+  mv "$MEMORY_FILE.tmp" "$MEMORY_FILE"
+
+  echo "✓ 记忆裁剪完成：移出 $OVERFLOW 条到 .memory-archive.md，保留最新 20 条"
+fi
+```
+
+---
+
+## Step 5：可选知识沉淀
+
+检查本次 change 是否涉及值得沉淀的知识（复杂 bug 修复、架构决策、新领域概念）：
+
+```bash
+# 检查 docs/solutions/ 是否已存在
+ls docs/solutions/ 2>/dev/null || echo "[docs/solutions/ 不存在]"
+```
+
+如果本次 change 涉及以下任一情况，提示用户：
+
+```
+💡 本次 change 涉及 <复杂问题解决/架构决策/新领域概念>，
+   建议运行 /atd compound 将知识沉淀到 docs/solutions/。
+
+   说"沉淀"立即执行，或跳过继续。
+```
+
+不涉及则跳过此步。
+
+---
+
+## Step 6：归档完成
+
+输出：
+```
+✅ change <name> 归档完成
+
+归档位置：openspec/changes/archive/<name>/
+记忆更新：~/.atdc/memory/<项目名>/.memory.md
+
+下一个 change 可直接说需求，@atdc/GO.md 会自动路由。
+
+📝 本次 change 已归档。是否生成技术分享文章？输入 `/atdc:article` 即可。
+```