@namewta/speculo 0.1.2 → 0.1.4

package/README.md

@@ -66,6 +66,7 @@ speculo update my-project
 - `commands/status.md`：聚合当前状态
 - `commands/archive.md`：归档 completed change
 - `commands/{caveman,grill-me,handoff,write-a-skill,scaffold-exercises}.md`：生产力命令
+- `commands/retro.md`：复盘 Speculo 使用痛点并经确认提改进 issue
 
 ## 开发
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

package/speculo/commands/archive.md

@@ -12,7 +12,14 @@ keywords: [archive, 归档, 清理]
 
 ## 归档路径模式
 
-产物归档至：`../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/`
+产物目录：`../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/`
+
+报告文件：`../.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从归档范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `changes`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-archive-<topic>/report.md`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 
 ## 调用的 skills
 

package/speculo/commands/caveman.md

@@ -10,7 +10,15 @@ keywords: [caveman, brief, tokens, 简洁]
 
 ## 归档路径模式
 
-可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/`
+可选产物目录：`../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/`
+
+模式报告：`../.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从用户请求提取，使用小写 kebab-case；无法判断时使用 `mode`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-caveman-<topic>/mode.md`。
+- 禁止把模式报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+
 （通常只改变对话风格，不需要持久化。）
 
 ## 调用的 skills

package/speculo/commands/grill-me.md

@@ -10,7 +10,14 @@ keywords: [grill, 追问, pressure-test, 方案]
 
 ## 归档路径模式
 
-可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/`
+可选产物目录：`../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/`
+
+报告文件：`../.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从被压力测试的计划或决策主题提取，使用小写 kebab-case；无法判断时使用 `decision`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-grill-me-<topic>/report.md`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 
 ## 调用的 skills
 

package/speculo/commands/handoff.md

@@ -10,7 +10,14 @@ keywords: [handoff, 交接, summary, resume]
 
 ## 归档路径模式
 
-可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`
+产物目录：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`
+
+交接文件：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从用户目标或交接主题提取，使用小写 kebab-case；无法判断时使用 `session`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
+- 禁止把交接文档写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 
 ## 调用的 skills
 
@@ -19,24 +26,35 @@ keywords: [handoff, 交接, summary, resume]
 ## 执行步骤
 
 1. 读取 `../skills/handoff/SKILL.md`。
-2. 按 source skill 要求，把交接文档保存到用户操作系统临时目录，而不是当前工作区。
-3. 删除 API key、密码、PII 和其他敏感信息。
-4. 若用户要求项目内留痕，只把交接文档路径、摘要和推荐技能写入 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/pointer.md`。
+2. 按 `../skills/handoff/SKILL.md` 要求，生成脱敏交接文档。
+3. 创建规范命令产物目录 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`。
+4. 把交接正文写入 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
+5. 删除 API key、密码、PII 和其他敏感信息；不要复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文。
+6. 返回 `handoff.md` 路径、3-5 条摘要和推荐技能清单。
 
-## 产物模板（pointer.md，可选）
+## 产物模板（handoff.md）
 
 > **服务命令：** `handoff.md`
-> **产物文件名：** `pointer.md`
+> **产物文件名：** `handoff.md`
 
 ```markdown
-# Handoff Pointer
+# Handoff
 
-## 临时文件路径
-[TODO: 记录操作系统临时目录中的交接文档路径。]
+## 目标
+[TODO: 概括当前任务目标和用户下一步重点。]
 
-## 摘要
-[TODO: 用 3-5 条概括交接内容，不复制敏感信息。]
+## 已完成
+[TODO: 列出已完成工作、关键决策和重要文件路径。]
+
+## 未完成
+[TODO: 列出下一步、阻塞点和剩余风险。]
+
+## 验证
+[TODO: 记录已运行命令、结果和未运行原因。]
 
 ## 推荐技能
 [TODO: 列出下一个 agent 推荐读取的 skill。]
+
+## 摘要
+[TODO: 用 3-5 条概括交接内容，不复制敏感信息。]
 ```

package/speculo/commands/retro.md

@@ -0,0 +1,68 @@
+---
+id: retro
+type: command
+name: Speculo Retro
+description: 复盘 Speculo commands/workflows 使用痛点，深度分析后经确认用 gh 提交改进 issue
+keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
+---
+
+# Retro 命令
+
+⚠️ **本命令在最后一步会通过 `gh` 向外部仓库创建 issue（外部写操作）。AI 必须先列出将要创建的 issue 清单与目标仓库并征求用户确认，确认前只输出计划，不调用 `gh`。**
+
+## 归档路径模式
+
+产物目录：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`
+
+报告文件：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从复盘范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+
+## 调用的 skills
+
+- `../skills/speculo-retro/SKILL.md` — 复盘 Speculo 使用痛点、深度分析并产出去重/分级/根因化的 issue-ready 提案时读取。
+- `../skills/github-npm-ops/SKILL.md` — 需要用 `gh` 去重（`gh issue list --search`）与创建 issue（`gh issue create`）时读取，其 `references/issue-pr-triage.md` 提供检索、标签体系与命令模板。
+
+## 执行步骤
+
+1. 读取 `../skills/speculo-retro/SKILL.md`，按其规范采集信号（对话上下文、`../.speculo/commands/`、`../.speculo/<cat>/<change>/.status.json`、`../.speculo/.config/LESSONS.md`）并深度分析。
+2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
+3. 创建规范命令产物目录 `../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`，把复盘结论写入 `report.md`。
+4. **解析目标仓库**：默认框架反馈上游 `NAMEWTA/Speculo`；用户在请求中显式指定其他 `owner/repo` 时覆盖默认。无论如何，在调用 `gh` 前回显解析到的 `owner/repo`，让用户确认或改正。
+5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
+6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标 `owner/repo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
+7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo <owner/repo> --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
+8. 把每条提案的最终 issue 编号/URL 回写进 `report.md` 的「提交结果」小节；返回 `report.md` 路径、3-5 条复盘摘要和已创建 issue 链接清单。
+
+## 产物模板（report.md）
+
+> **服务命令：** `retro.md`
+> **产物文件名：** `report.md`
+
+```markdown
+# Speculo Retro Report
+
+## 复盘范围
+[TODO: 本次复盘覆盖的 command / workflow 与时间/会话范围。]
+
+## 信号来源
+[TODO: 列出采集到的证据出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、LESSONS。]
+
+## 改进提案
+[TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / 建议改动 / 验收标准 / 受影响资产 / 去重结论。]
+
+## 丢弃与降级项
+[TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
+
+## 目标仓库
+[TODO: 解析到的 owner/repo 与用户确认结果。]
+
+## 用户确认记录
+[TODO: 记录用户对 issue 清单与目标仓库的确认原文摘要。]
+
+## 提交结果
+[TODO: 列出每条提案对应的 issue 编号/URL，或未提交原因（重复/失败/用户撤回）。]
+```

package/speculo/commands/scaffold-exercises.md

@@ -12,7 +12,14 @@ keywords: [exercises, scaffold, course, lint, 练习]
 
 ## 归档路径模式
 
-产物归档至：`../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/`
+产物目录：`../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/`
+
+报告文件：`../.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从章节、练习或课程主题提取，使用小写 kebab-case；无法判断时使用 `exercises`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-scaffold-exercises-<topic>/report.md`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 
 ## 调用的 skills
 

package/speculo/commands/status.md

@@ -10,7 +10,15 @@ keywords: [status, 状态, 进度]
 
 ## 归档路径模式
 
-可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-status-<topic>/`
+可选产物目录：`../.speculo/commands/<YYYY-MM-DD>-status-<topic>/`
+
+快照文件：`../.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从状态范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `snapshot`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`。
+- 禁止把状态快照写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+
 （若仅是回显报告、不需要持久化时可不归档）
 
 ## 调用的 skills

package/speculo/commands/write-a-skill.md

@@ -10,7 +10,14 @@ keywords: [skill, create, write, 技能]
 
 ## 归档路径模式
 
-产物归档至：`../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/`
+产物目录：`../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/`
+
+报告文件：`../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`
+
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从 skill 名称或用户主题提取，使用小写 kebab-case；无法判断时使用 `skill`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 
 ## 调用的 skills
 

package/speculo/skills/github-npm-ops/SKILL.md

@@ -31,7 +31,7 @@ description: GitHub 仓库运营与 npm 发布原子能力；用于 issue/PR/CI/
 
 1. 先判定任务类型：日常治理、发布基础设施搭建、正式发版、失败恢复。
 2. 发布类任务先执行只读前置检查：分支、工作区、远端、`gh auth`、Node/包管理器、`release.yml`、tag 冲突、docs-sync state。
-3. 需要同步对外文档时，交给调用方读取 `../workflows/dev/D-docs-sync/D-docs-sync.md`；本 skill 不直接写 `.speculo/` 或 `.status.json`。
+3. 需要同步对外文档时，交给调用方读取 `../workflows/dev/D-docs-sync/D-docs-sync.md`；本 skill 不自行选择持久化目录，只把结果交给调用方写入其声明的 `.speculo/...` 规范路径。
 4. 正式发版必须保证 release commit 同时包含版本 bump 与 CHANGELOG 迁移，并且 tag 精确指向 release commit。
 5. release workflow 必须包含 tag/package version 校验、质量闸、可选 npm publish、CHANGELOG release notes 注入、GitHub Release 创建。
 6. 发布完成后做三端验证：workflow success、GitHub Release 非 draft 且正文非空、如流水线包含 npm publish 则 `npm view` 版本与 dist-tag 一致。

package/speculo/skills/github-npm-ops/references/failure-recovery.md

@@ -37,18 +37,21 @@ git push origin vX.Y.Z
 **恢复**：**不要**重发 npm（同版本号永久不可重发），仅手动补 GitHub Release。
 
 ```bash
+notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
+trap 'rm -f "$notes_file"' EXIT
+
 # 1. 抽取 CHANGELOG 段落作为 Release notes
 awk -v v="X.Y.Z" '
   $0 ~ "^## \\["v"\\]" { found=1; print; next }
   found && /^## \[/ { exit }
   found && /^---[[:space:]]*$/ { next }
   found { print }
-' CHANGELOGS.md > /tmp/notes.md
+' CHANGELOGS.md > "$notes_file"
 
 # 2. 手动创建 GitHub Release
 gh release create vX.Y.Z \
   --title "Release vX.Y.Z" \
-  --notes-file /tmp/notes.md \
+  --notes-file "$notes_file" \
   --latest
 
 # 3. 三端再次校验
@@ -106,7 +109,7 @@ git push origin vX.Y.Z
 #    在 [X.Y.(Z+1)] 段落开头加一句 "supersedes vX.Y.Z due to <根因>"
 ```
 
-**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方 workflow，由其追加到 `.speculo/.config/LESSONS.md`（本 skill 不直接写 `.speculo/`）。
+**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方 workflow，由其追加到 `.speculo/.config/LESSONS.md`（本 skill 不自行选择持久化目录）。
 
 ---
 

package/speculo/skills/github-npm-ops/references/release-notes-injection.md

@@ -88,17 +88,20 @@ GitHub Release 的正文(body)**事后可改**(tag 不可改、npm 包不可改
 
 ### 3.1 命令行(推荐)
 
+`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
+
 ```bash
-# 一行命令:抽取 → 回填 → 清理
 VERSION="0.0.10"
+notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
+trap 'rm -f "$notes_file"' EXIT
+
 awk -v v="$VERSION" '
   $0 ~ "^## \\["v"\\]" { found=1; print; next }
   found && /^## \[/ { exit }
   found && /^---[[:space:]]*$/ { next }
   found { print }
-' CHANGELOGS.md > /tmp/notes.md && \
-  gh release edit "v$VERSION" --notes-file /tmp/notes.md && \
-  rm /tmp/notes.md
+' CHANGELOGS.md > "$notes_file" && \
+  gh release edit "v$VERSION" --notes-file "$notes_file"
 ```
 
 ### 3.2 GitHub UI
@@ -108,22 +111,24 @@ awk -v v="$VERSION" '
 ### 3.3 批量回填多个历史版本
 
 ```bash
+notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
+trap 'rm -f "$notes_file"' EXIT
+
 for v in 0.0.7 0.0.8 0.0.9; do
   awk -v ver="$v" '
     $0 ~ "^## \\["ver"\\]" { found=1; print; next }
     found && /^## \[/ { exit }
     found && /^---[[:space:]]*$/ { next }
     found { print }
-  ' CHANGELOGS.md > /tmp/notes.md
+  ' CHANGELOGS.md > "$notes_file"
 
-  if [ -s /tmp/notes.md ]; then
-    gh release edit "v$v" --notes-file /tmp/notes.md
+  if [ -s "$notes_file" ]; then
+    gh release edit "v$v" --notes-file "$notes_file"
     echo "✓ v$v"
   else
     echo "✗ v$v: CHANGELOG 中无对应段落,跳过"
   fi
 done
-rm -f /tmp/notes.md
 ```
 
 ## 4. 进阶:走 PR 流程的项目
@@ -195,17 +200,14 @@ changelog:
     VERSION="${GITHUB_REF_NAME#v}"
     EXTRACT='$0 ~ "^## \\["v"\\]" { found=1; print; next } found && /^## \[/ { exit } found && /^---[[:space:]]*$/ { next } found { print }'
 
-    awk -v v="$VERSION" "$EXTRACT" CHANGELOG.md > /tmp/en.md
-    awk -v v="$VERSION" "$EXTRACT" CHANGELOG-ZH.md > /tmp/zh.md
-
     {
-      cat /tmp/en.md
+      awk -v v="$VERSION" "$EXTRACT" CHANGELOG.md
       echo
       echo "---"
       echo
       echo "### 中文版本说明"
       echo
-      cat /tmp/zh.md
+      awk -v v="$VERSION" "$EXTRACT" CHANGELOG-ZH.md
     } > release-notes.md
 ```
 

package/speculo/skills/github-npm-ops/references/release-pipeline.md

@@ -88,7 +88,7 @@ npm view "<package-name>" dist-tags
 
 ## Phase 6 — 推进 docs-sync 基线
 
-仅当 Phase 1-5 全绿时执行。本 skill 不直接写 `.speculo/`；把基线推进交给调用方的 release workflow 或 `workflows/dev/D-docs-sync/D-docs-sync.md`，只向其提供以下取值：
+仅当 Phase 1-5 全绿时执行。本 skill 不自行选择持久化目录；把基线推进交给调用方的 release workflow 或 `workflows/dev/D-docs-sync/D-docs-sync.md`，只向其提供以下取值：
 
 - `last_sync_sha` 推进到 `RELEASE_COMMIT_SHA`。
 - `previous_sync_sha` 使用推进前的 `last_sync_sha`。

package/speculo/skills/github-npm-ops/references/troubleshooting-playbook.md

@@ -216,14 +216,16 @@ Full Changelog: v0.0.9...v0.0.10
 
 ```bash
 VERSION="0.0.10"
+notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
+trap 'rm -f "$notes_file"' EXIT
+
 awk -v v="$VERSION" '
   $0 ~ "^## \\["v"\\]" { found=1; print; next }
   found && /^## \[/ { exit }
   found && /^---[[:space:]]*$/ { next }
   found { print }
-' CHANGELOGS.md > /tmp/notes.md && \
-  gh release edit "v$VERSION" --notes-file /tmp/notes.md && \
-  rm /tmp/notes.md
+' CHANGELOGS.md > "$notes_file" && \
+  gh release edit "v$VERSION" --notes-file "$notes_file"
 ```
 
 **诊断**：

package/speculo/skills/github-npm-ops/references/version-bump-flow.md

@@ -180,15 +180,20 @@ git push origin v0.0.10
 
 npm 已上线 → **不要**改版本号,只补后续动作。
 
+下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
+
 ```bash
+notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
+trap 'rm -f "$notes_file"' EXIT
+
 # 抽取 CHANGELOG 段落
-awk -v v="0.0.10" '...' CHANGELOGS.md > /tmp/notes.md
+awk -v v="0.0.10" '...' CHANGELOGS.md > "$notes_file"
 
 # 手动创建 GitHub Release
-gh release create v0.0.10 --notes-file /tmp/notes.md --latest
+gh release create v0.0.10 --notes-file "$notes_file" --latest
 
 # 或编辑已有 Release(如果 action 半成品创建过空 Release)
-gh release edit v0.0.10 --notes-file /tmp/notes.md
+gh release edit v0.0.10 --notes-file "$notes_file"
 ```
 
 ### 8.3 publish 失败但 npm 上其实有了(罕见)

package/speculo/skills/handoff/SKILL.md

@@ -22,10 +22,18 @@ description: 将当前对话压缩成交接文档；当用户需要另一个 age
 
 ## 输出
 
-- 保存到用户操作系统临时目录的脱敏交接文档
-- 文档路径
+- 保存到规范命令产物目录的脱敏交接文档：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
+- 文档路径、主题目录名和命名依据
+- 3-5 条极简摘要
 - 推荐技能清单
-- 如调用方需要持久化，由调用方只归档文档路径和简短摘要
+
+## 命名与位置
+
+- 交接文档必须写入调用方命令产物目录：`../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从用户目标、项目名、变更名或下一次会话重点提取，使用小写 kebab-case；无法判断时使用 `session`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
+- 禁止写入 `temp/`、系统临时目录、仓库根目录临时文件或其他非 Speculo 规范位置。
 
 ## 执行步骤
 
@@ -33,9 +41,10 @@ description: 将当前对话压缩成交接文档；当用户需要另一个 age
 2. 删除 API key、密码、token、个人身份信息和其他敏感内容。
 3. 不复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文；改用路径、URL 或 commit 引用。
 4. 添加 `推荐技能` 部分，列出下一个 agent 应优先读取或调用的技能。
-5. 将交接文档保存到用户操作系统临时目录，不保存到当前工作区。
-6. 返回文档路径和极简摘要。
+5. 创建 `../.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`，并把交接文档写入其中的 `handoff.md`。
+6. 返回文档路径、主题目录名、3-5 条极简摘要和推荐技能清单。
 
-## 渐进披露
+## references/ 与 scripts/
 
-无额外文件。该 skill 的完整执行规则在本入口中。
+- 无 `references/` 子文档；该 skill 的完整执行规则在本入口中。
+- 无 `scripts/`；直接按本文件步骤整理和写入交接文档。

package/speculo/skills/scaffold-exercises/SKILL.md

@@ -33,7 +33,7 @@ description: 创建课程章节与练习目录骨架并验证 lint；当用户
 4. 为每个变体创建最小但非空的 `readme.md`。
 5. 运行 lint；按 `references/lint-and-git.md` 迭代修复，直到通过或记录阻塞。
 6. 仅在用户或调用方明确要求时提交 git。
-7. 不直接写 `.speculo/` 或 `.status.json`；需要归档时由调用方 command 或 workflow 负责。
+7. 不自行选择持久化目录；需要归档时，由调用方 command 或 workflow 写入其声明的 `.speculo/...` 规范路径。
 
 ## 渐进披露
 

package/speculo/skills/speculo-retro/SKILL.md

@@ -0,0 +1,52 @@
+---
+id: speculo-retro
+type: skill
+name: Speculo Retro
+description: 复盘 Speculo commands/workflows 使用过程中的痛点、问题与值得优化的地方，深度分析后产出去重、分级、根因化、可直接转成 GitHub issue 的规范化改进提案；当用户要求总结 Speculo 使用体验、收集框架反馈或把使用痛点整理成 issue 时使用。
+---
+
+# Speculo Retro
+
+## 何时使用
+
+当用户想复盘「用 Speculo 的 commands 或 workflows 时遇到的痛点、问题、值得优化的地方」，并希望把这些摩擦整理成规范化、可行动的框架反馈或 issue 时使用。
+
+典型触发：
+
+- “总结一下这次用 Speculo 踩的坑 / 卡点”
+- “把使用痛点整理成可以提的 issue”
+- “复盘 dev workflow 哪里别扭、哪里值得优化”
+- “收集 Speculo 框架反馈”
+
+本 skill 只负责**分析与规范化产出内容**：它去重、分级、根因化并起草 issue-ready 提案，把结果返回给调用方。它**不自行写文件、不调用 `gh`、不发布 issue**；落盘与提交由调用方 command / workflow 负责。
+
+## 输入
+
+- 当前对话上下文：本次会话用了哪些 command / workflow、卡在哪、绕了什么弯、重复了哪些动作
+- `.speculo/commands/<run>/` 下的历史命令产物（report、snapshot、handoff）
+- `.speculo/<cat>/<change>/` 下的 change 产物与 `.status.json`（`phase_history` 里的 `revisited`、`blocked`、长时间停滞都是摩擦信号）
+- `.speculo/.config/LESSONS.md`（已沉淀的教训，用于去重与佐证）
+- 可选：调用方提供的已存在 issue 列表或目标仓库上下文，用于跨提案去重
+- 本 skill 自带分析与 issue 起草规范，已内化到 `references/`，分析时**不外读仓库 `docs/`**
+
+## 输出
+
+- 规范化复盘结论：每条 = 一个去重、分级、根因化的改进提案，字段对齐 GitHub issue（标题、类型/标签、证据、问题、建议改动、验收、受影响 asset）
+- 提案清单，按优先级倒序排列
+- 被合并或丢弃的低信号项说明（哪些重复、哪些更适合记入 `LESSONS.md` 而非提 issue）
+- 每条标注「建议提 issue」或「仅记教训」的处置建议
+- 全部以**返回内容**形式交给调用方写入其声明的 `.speculo/...` 路径；本 skill 不挑选持久化位置
+
+## 执行步骤
+
+1. **收集信号** —— 按 `references/friction-taxonomy.md` 的来源清单，扫描对话上下文、`.speculo/` 产物与 `LESSONS.md`，列出原始摩擦点。
+2. **归类与去重** —— 按 taxonomy 把每个摩擦点归到类型（bug / friction / missing-capability / doc-gap / ergonomics），合并语义重复项。
+3. **深度分析** —— 对每条做根因判断（是 asset 设计、持久化契约、文档还是工具问题），评估影响面与发生频率，按 `references/friction-taxonomy.md` 的优先级评分。
+4. **过滤噪声** —— 只保留高信号、可行动项；低信号或一次性项标注为丢弃，或归入「仅记教训」。
+5. **起草提案** —— 按 `references/issue-drafting-sop.md` 把每条规范化成 issue-ready 提案，并对照调用方提供的已存在 issue 做跨提案去重。
+6. **返回结论** —— 把结构化提案清单、丢弃项与处置建议返回调用方；不自行写文件、不调用 `gh`。
+
+## 渐进披露
+
+- `references/friction-taxonomy.md`：确定信号来源、给摩擦点归类、按影响 × 频率评优先级、过滤噪声时读取。
+- `references/issue-drafting-sop.md`：把改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成给调用方 / `gh` 的交接字段时读取。

package/speculo/skills/speculo-retro/references/friction-taxonomy.md

@@ -0,0 +1,55 @@
+# Friction Taxonomy SOP
+
+复盘 Speculo 使用摩擦时的信号来源、分类法、优先级评分与噪声过滤规范。
+
+## 信号来源清单
+
+按以下顺序采集原始摩擦点，每条记录**证据出处**（文件路径或对话节点），后续起草 issue 时要引用：
+
+1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
+2. **命令产物** —— `.speculo/commands/<run>/` 下的 `report.md`、`snapshot.md`、`handoff.md`：里面记录的「验证失败原因」「未完成」「阻塞点」是一手摩擦。
+3. **change 状态机** —— `.speculo/<cat>/<change>/.status.json` 的 `phase_history`：
+   - `revisited` —— phase 被迫回退，通常意味着流程设计或前置产物有缺口
+   - `blocked` —— 卡点，记录阻塞原因
+   - `skipped` —— phase 被跳过，可能是冗余或不适用
+   - `updated_at` 长期停滞 —— 流程让人不想推进
+4. **change 产物正文** —— `prd.md`、`tdd-*.md`、`slices.md`、`diagnosis.md` 中显式写下的「待澄清」「风险」「TODO」。
+5. **沉淀教训** —— `.speculo/.config/LESSONS.md`：已记录但尚未转成改进项的教训，用于去重与佐证频率。
+6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离 `persistence-contract`：路径散落、缺字段、命名不合 `YYYY-MM-DD-<kebab>` 都是 bug 信号。
+
+## 摩擦类型分类
+
+每个摩擦点归且仅归一个**主类型**：
+
+| 类型 | 含义 | 典型表现 |
+|------|------|---------|
+| `bug` | 资产行为不符合契约或文档 | 产物写错位置、`.status.json` 缺字段、命令覆盖了用户改动 |
+| `friction` | 能用但别扭、步骤冗余、易错 | 反复手动改路径、phase 频繁 `revisited`、确认环节缺失 |
+| `missing-capability` | 缺一个本该有的 command/workflow/skill | 用户手动拼凑某个反复出现的流程 |
+| `doc-gap` | 文档缺失、过时或与实现不符 | 指引说一套、资产做另一套；找不到用法 |
+| `ergonomics` | 命名、触发词、措辞、可发现性 | description 区分度差、关键词命中不到、术语不一致 |
+
+## 优先级评分
+
+优先级 = **影响面 × 发生频率**，落到四档（复用 `github-npm-ops` 标签体系）：
+
+- 影响面：`broad`（影响所有使用者 / 破坏契约）｜`partial`（影响部分流程）｜`cosmetic`（轻微体验）
+- 发生频率：`recurring`（多次出现 / 多来源佐证）｜`occasional`｜`one-off`
+
+| 优先级 | 判定 |
+|--------|------|
+| `priority:critical` | 破坏契约、数据/产物丢失、覆盖用户改动 —— 无论频率 |
+| `priority:high` | `broad` 影响且 `recurring`，或显著阻塞主流程 |
+| `priority:medium` | `partial` 影响，或 `broad` 但仅 `occasional` |
+| `priority:low` | `cosmetic`，或 `one-off` 且有 workaround |
+
+## 噪声过滤规则
+
+不是每个摩擦点都该变成 issue。按以下规则收敛：
+
+- **合并** —— 语义重复的多条合成一条，频率累加（提升优先级佐证）。
+- **丢弃** —— 纯属本次会话一次性、不可复现、或已被其他提案覆盖的，标注「丢弃」并写明原因。
+- **降级为教训** —— 属于「用法/约定」而非「资产缺陷」的，建议记入 `LESSONS.md` 而非提 issue。
+- **可行动性闸门** —— 无法描述出「改哪个 asset、怎么改、怎么验收」的，先标 `needs-design`，不要凭空提模糊 issue。
+
+只把通过闸门、`priority:medium` 及以上、或 `recurring` 的高信号项推进到 issue 起草。

package/speculo/skills/speculo-retro/references/issue-drafting-sop.md

@@ -0,0 +1,77 @@
+# Issue Drafting SOP
+
+把通过过滤的改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成交给调用方 / `gh` 的交接字段。
+
+## 提案字段（issue-ready）
+
+每条提案产出以下结构化字段，调用方据此写报告并据此调 `gh`：
+
+```jsonc
+{
+  "title":        "string, 见标题规范",
+  "type":         "bug | enhancement | documentation | feature-request",
+  "priority":     "priority:critical | priority:high | priority:medium | priority:low",
+  "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
+  "body":         "string, 见正文结构",
+  "affected":     ["相对路径，例 speculo/commands/archive.md"],
+  "evidence":     ["证据出处，例 .speculo/dev/<change>/.status.json#phase_history"],
+  "disposition":  "file-issue | record-lesson | drop",
+  "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
+}
+```
+
+## 标题规范
+
+- 用祈使句描述「要改成什么」，不是「哪里坏了」：`命名` 区分度差 ❌ → `enhancement: 提升 command description 在系统提示里的区分度` ✅
+- 前缀对齐类型：`bug:` / `enhancement:` / `docs:` / `feature:`
+- 单行、可独立读懂、不超过约 70 字，含受影响的 asset 名。
+
+## 类型 → 标签映射
+
+复用 `../github-npm-ops/references/issue-pr-triage.md` 的标签体系，每条至少一个**类型**标签，外加**优先级**，可选**领域**：
+
+| 提案 type | issue 类型标签 |
+|-----------|---------------|
+| `bug` | `bug` |
+| `friction` | `enhancement` |
+| `missing-capability` | `feature-request` |
+| `doc-gap` | `documentation` |
+| `ergonomics` | `enhancement` |
+
+不确定改动方向的额外加 `needs-design`。
+
+## 正文结构
+
+每条 issue body 用固定小节，占位符填实，禁止空话：
+
+```markdown
+## 问题
+[一句话说清痛点 / 不符合预期的行为。]
+
+## 证据
+[引用具体出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
+
+## 根因
+[判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
+
+## 建议改动
+[改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
+
+## 验收标准
+[可验证的完成判据，例如断言、命名、契约符合点。]
+
+## 受影响资产
+[列出相关相对路径。]
+```
+
+## 去重
+
+起草后、交给调用方提交前，对每条做去重判定：
+
+1. 提取标题与根因的关键词。
+2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索（机制见 `../github-npm-ops/references/issue-pr-triage.md`）。
+3. 命中语义重复：把 `disposition` 设为 `drop` 或在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
+
+## 交接契约
+
+本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `.speculo/commands/<run>/report.md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。

package/speculo/skills/speculo-write/references/asset-selection-sop.md

@@ -28,7 +28,7 @@
 - 是 command 或 workflow 可复用的原子能力
 - 复制到其他项目仍能工作
 - 需要 `references/` 渐进披露
-- 不拥有持久化责任，不直接写 `.speculo/` 或 `.status.json`
+- 不拥有独立持久化根目录；文件型持久化由调用方提供 `.speculo/...` 目标路径，或返回内容给调用方写入
 - 是工具集成、领域知识、决策 SOP 或可复用操作手册
 
 ### 做 Command
@@ -49,7 +49,7 @@
 ## 反例
 
 - 不要把多阶段、有状态的流程塞进 skill。
-- 不要让 skill 直接写 `.speculo/`。
+- 不要让 skill 自行选择 `.speculo/`、`temp/`、系统临时目录或项目根目录作为持久化位置。
 - 不要为一次性命令创建 workflow。
 - 不要把 workflow-only 方法保留为根 skill，除非会被多个入口复用。
 

package/speculo/skills/speculo-write/references/command-authoring-sop.md

@@ -39,6 +39,8 @@ command 正文包含：
 .speculo/commands/<YYYY-MM-DD>-<command>-<topic>/
 ```
 
+在 command 文件中写相对路径时，使用 `../.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`。安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`。命令产物禁止写入 `temp/`、系统临时目录、项目根目录或其它非 Speculo 规范位置。
+
 ## 调用 Skill
 
 如需复用 skill，用相对路径列出：
@@ -47,7 +49,7 @@ command 正文包含：
 - `../skills/<name>/SKILL.md`：<何时读取>
 ```
 
-skill 输出归档到 command 产物目录。skill 自身不写 `.speculo/`。
+skill 输出如需持久化，归档到 command 产物目录。command 可以把 skill 返回内容写入该目录；若 skill 负责生成文件，command 必须显式提供规范目标路径。禁止 skill 默认写入 `temp/`、系统临时目录或项目根目录。
 
 ## 破坏性操作
 
@@ -68,7 +70,7 @@ command 产物模板内联在文件末尾。模板占位符使用 `[TODO: ...]`
 
 - status 快照
 - archive 报告
-- handoff pointer
+- handoff 文档
 - 一次性操作报告
 
 不适合 command 的产物：
@@ -88,5 +90,7 @@ command 产物模板内联在文件末尾。模板占位符使用 `[TODO: ...]`
 - README 内置入口列表
 - CLI tests 是否需要断言复制该 command
 - 是否需要新增 command 调用的 skill
+- 归档路径是否位于 `.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`
+- 被调用 skill 是否没有自选 `temp/`、系统临时目录或项目根目录作为持久化位置
 
 `.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`。

package/speculo/skills/speculo-write/references/persistence-contract-sop.md

@@ -13,6 +13,8 @@
 
 `<cat>` 只能是 `dev`、`doc`、`ops`。
 
+命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
+
 ## `.status.json` 元字段（框架强制）
 
 每个 change 的状态写在 `.speculo/<cat>/<change>/.status.json`：
@@ -106,11 +108,13 @@ description: <一句话>    # 必填
 | `.speculo/.config/LESSONS.md` | ⚠️ 可追加 | ✅ workflow 末尾追加 |
 | `.speculo/.config/context/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
 | `.speculo/.config/adr/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
+| `.speculo/commands/<command-run>/*` | ⚠️ | ✅ command 按内联模板写入 |
 | `.speculo/<cat>/<change>/*.md` | ⚠️ | ✅ |
 | `.speculo/<cat>/<change>/.status.json` | ❌ | ✅ |
 | `.speculo/*-status.json` | ❌ | ✅ |
+| `.speculo/dev/docs-sync-state.json` | ❌ | ✅ `dev/D-docs-sync` 原子写入 |
 
-**skill 不在此表**：skill 不直接写任何 `.speculo/` 或 `.status.json`，持久化由调用它的 workflow 或 command 负责。
+**skill 不拥有独立持久化根目录**：skill 需要生成持久化文件时，必须使用调用方 command / workflow 声明的 `.speculo/...` 规范目标路径，或返回内容由调用方写入。禁止 skill 自行选择 `temp/`、系统临时目录、项目根目录或额外 state 文件作为持久化位置。
 
 ## 新分类骨架
 

package/speculo/skills/speculo-write/references/skill-authoring-sop.md

@@ -165,19 +165,26 @@ reference 文件用 kebab-case，**按任务而非来源**命名（`workflow-aut
 - 旧目录布局
 - 旧 state 路径
 - 不符合 Speculo frontmatter 的元数据
-- 直接写 `.speculo/` 的行为描述
+- 脱离调用方的持久化路径、`temp/` 输出、项目根目录 state 和其它散落写入行为
 
 多个源技能融合为一个原子 skill 时：入口 `SKILL.md` 只留统一触发与主流程，源技能细节按主题拆进 `references/`，合并重复铁律并保留更严格者。
 
 ## 持久化边界
 
-skill **禁止**直接写：
+skill **禁止自行选择**持久化位置，包括：
 
 - `.speculo/<cat>/<change>/`
+- `.speculo/commands/`
 - `.speculo/*-status.json`
 - `.status.json`
+- `temp/`、系统临时目录或项目根目录
 
-如果某能力需要持久化，把写入责任交给调用它的 workflow 或 command，并在 skill 输出里提供可归档摘要。完整写入责任表见 `persistence-contract-sop.md`。
+如果某能力需要生成文件型持久化产物，必须满足其一：
+
+- 调用方 workflow / command 声明规范目标路径，skill 只写入该路径。
+- skill 返回内容、摘要和建议文件名，由调用方写入 `.speculo/...`。
+
+无论哪种方式，持久化产物都不得落到 `temp/`、系统临时目录、项目根目录或其它非 Speculo 规范位置。完整写入责任表见 `persistence-contract-sop.md`。
 
 ## 审查清单
 
@@ -188,7 +195,7 @@ skill **禁止**直接写：
 - [ ] `SKILL.md` 含五个固定章节，整体精简（细节已外移）
 - [ ] reference 单层引用，按任务命名
 - [ ] **自包含**：不引用 `docs/` 或仓库外文件
-- [ ] skill 不直接写 `.speculo/` 或 `.status.json`，持久化交给调用方
+- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `.speculo/...` 路径
 - [ ] 没有 README / INSTALLATION / CHANGELOG 等冗余文件
 - [ ] 没有时效性信息、旧项目路径、旧工具名或绝对路径绑定
 - [ ] 术语一致、含具体示例、引用只有一层深度

package/speculo/skills/speculo-write/references/validation-checklist.md

@@ -33,13 +33,14 @@
 - [ ] 输入、输出、执行步骤清晰
 - [ ] 大段细节放入 `references/`
 - [ ] 自包含：不引用 `docs/` 或仓库外文件，复制后只读 `SKILL.md` 即可用
-- [ ] skill 不直接写 `.speculo/` 或 `.status.json`
-- [ ] 如果需要持久化，明确由调用方 workflow 或 command 负责
+- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `.speculo/...` 路径
+- [ ] 如果需要持久化，明确归档到 `.speculo/commands/`、`.speculo/<cat>/<change>/` 或 `.speculo/.config/` 的哪类规范位置
 
 ## Command 检查
 
 - [ ] 归档路径位于 `.speculo/commands/`
 - [ ] 调用 skill 使用相对路径
+- [ ] 被调用 skill 没有把持久化产物写到 `temp/`、系统临时目录或项目根目录
 - [ ] 破坏性操作要求用户确认
 - [ ] 产物模板内联且使用 `[TODO: ...]`
 

package/speculo/skills/worktree-isolation/SKILL.md

@@ -29,7 +29,7 @@ description: 在独立 git worktree 中隔离推进一个 change 的原子能力
 ## 输出
 
 - git 状态变更：隔离分支、`.worktree/<change>/` 工作树、合并与清理结果
-- **供调用方持久化的状态字段集**（本 skill 不写 `.speculo/`，由调用方 workflow 写入同一 change 的 `.status.json`）：
+- **供调用方持久化的状态字段集**（本 skill 不自行选择持久化目录，由调用方 workflow 写入同一 change 的 `.status.json`）：
 
   | 字段 | 类型 | 含义 |
   |------|------|------|

package/speculo/skills/worktree-isolation/references/audit-branch-tree.md

@@ -29,4 +29,4 @@ worktree 模式下，review 必须覆盖 change 分支相对 base 的**全部 co
 
 - 不替换用户显式指定的 fixed point。
 - 不遗漏任何 commit；clean-review 声明须确认已覆盖 `base..change_branch` 全部 commit。
-- 不写 `.speculo/` 或 `.status.json`。
+- 不自行选择持久化目录；审查字段由调用方写入 `.speculo/<cat>/<change>/.status.json`。

package/speculo/skills/worktree-isolation/references/create-worktree.md

@@ -34,6 +34,6 @@
 
 ## 边界
 
-- 不写 `.speculo/` 或 `.status.json`；字段值返回给调用方 workflow 写入。
+- 不自行选择持久化目录；字段值返回给调用方 workflow 写入 `.speculo/<cat>/<change>/.status.json`。
 - 分支或工作树已存在时不覆盖、不复用，停止报告。
 - 非 git 仓库 / 工作区不可用 / `.speculo/` 未被跟踪时降级为非 worktree 模式。

package/speculo/skills/worktree-isolation/references/merge-and-cleanup.md

@@ -40,4 +40,4 @@ finalize 验证通过后，把 change 分支合并回原分支并清理 worktree
 
 - `verification_status` 非 `verified` 不合并。
 - 未获用户确认不执行任何合并 / 删除 / 移除。
-- 不写 `.speculo/` 或 `.status.json`；`worktree_status` 由调用方写入。
+- 不自行选择持久化目录；`worktree_status` 由调用方写入 `.speculo/<cat>/<change>/.status.json`。

package/speculo/workflows/dev/03-tdd/03-tdd.md

@@ -32,18 +32,21 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 ## 阶段
 
+> **产物目录：** 本工作流所有产物写入 `.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。
+
 ### 1. TDD Plan — 行为与接口计划
 - 规范：`tdd-plan.md`
 - 模板：`../_templates/tdd-plan-template.md`
-- 产物：`tdd-plan.md`
+- 产物：`tdd/<phase-id>/tdd-plan.md`
 - 完成准则：
   - 已确认公共接口、关键行为和测试优先级
+  - 已在产物顶部「阶段标识」段填写 `<phase-id>`
   - `tdd-plan.md` 无残留 `[TODO:]`
 
 ### 2. Slice Loop — 红绿重构循环
 - 规范：`tdd-loop.md`
 - 模板：`../_templates/tdd-log-template.md`
-- 产物：`implementation-log.md`
+- 产物：`tdd/<phase-id>/implementation-log.md`
 - 完成准则：
   - 每个切片都有 RED、GREEN、REFACTOR 和验证记录
   - `implementation-log.md` 无残留 `[TODO:]`
@@ -51,12 +54,50 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 ### 3. Finish — 验证与收尾
 - 规范：`tdd-finish.md`
 - 模板：`../_templates/tdd-verification-template.md`
-- 产物：`verification.md`
+- 产物：`tdd/<phase-id>/verification.md`
 - 完成准则：
   - 已运行相关测试或明确记录无法运行原因
   - 无调试残留和推测性功能
+  - 已把 roadmap 中该阶段 `<phase>` 状态由 `未开始` 置为 `已实现`（无 roadmap 则跳过，见「roadmap 阶段状态（XML 契约）」）
   - `verification.md` 无残留 `[TODO:]`
 
+## TDD 产物目录与阶段标识
+
+- 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / roadmap 等产物分离，便于多阶段并行与回溯。
+- `<phase-id>` 标识：
+  - change 来自**多阶段 roadmap** 时，用 roadmap 阶段标识（与 roadmap `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
+  - change 为**单阶段**（无 roadmap 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。
+- 每个阶段独立一套 `tdd-plan.md` / `implementation-log.md` / `verification.md`，互不覆盖；模板顶部「阶段标识」段记录该 `<phase-id>`。
+- 目录形如：
+
+```text
+.speculo/dev/<change>/tdd/
+├── phase0-node-base/
+│   ├── tdd-plan.md
+│   ├── implementation-log.md
+│   └── verification.md
+└── phase1-templates/
+    ├── tdd-plan.md
+    ├── implementation-log.md
+    └── verification.md
+```
+
+## roadmap 阶段状态（XML 契约）
+
+多阶段 roadmap（`.speculo/dev/<change>/roadmap.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
+
+```xml
+<phase id="phase0-node-base" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+```
+
+- `id`：阶段稳定标识，与 TDD 产物目录 `tdd/<phase-id>/` 同名。
+- `status` 枚举与责任方：
+  - `未开始` —— 创建 roadmap 文档时由作者初始化（所有阶段默认 `未开始`）。
+  - `已实现` —— 本工作流（`dev/03`）该阶段 Finish 验证通过后置入。
+  - `已验证` —— `dev/04`（`../04-finalize/04-finalize.md`）完成前验证通过后置入。
+- 本工作流只负责 `未开始 → 已实现` 这一跳；`dev/04` 负责 `已实现 → 已验证`。状态只前进不回退，除非该阶段被显式重做。
+- change 无 roadmap（单阶段直接任务）时本契约不适用，跳过状态翻转。
+
 ## 依赖
 
 - 软依赖：`../02-prd/02-prd.md` 或 `../I-to-issues/I-to-issues.md`，scope: same-change
@@ -68,13 +109,17 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 - `dev_entry` (string) — 固定为 `dev/03`
 - `embedded_guides` (array) — 包含 `tdd`
+- `tdd_phase_id` (string) — 当前 TDD 阶段标识，与产物目录 `tdd/<phase-id>/` 及 roadmap `<phase>` 的 `id` 一致
 - `slice_source` (prd | issues | diagnosis | user-request) — 切片来源
 - `red_green_refactor_cycles` (array) — 每轮 TDD 循环摘要
 - `verification_commands` (array) — 已运行或应运行的验证命令
 - `implementation_status` (planned | in-progress | verified | blocked) — 实现状态
 
+> 多阶段 change：上述自治字段按阶段命名空间记录在 `tdd_runs[<phase-id>]` 下（各含 `scope` / `artifacts`(指向 `tdd/<phase-id>/*.md`) / `red_green_refactor_cycles` / `verification_commands` / `implementation_status`），避免跨阶段互相覆盖。单阶段 change 可直接用平铺字段。
+
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 每完成一个切片，追加 `red_green_refactor_cycles`。
+- 每完成一个切片，追加 `red_green_refactor_cycles`（多阶段时写入 `tdd_runs[<phase-id>]`）。
+- Finish 验证通过后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 roadmap 则跳过）。
 - 全部用户要求的实现边界完成并验证后，可把 `change_status` 置为 `completed`，或移交 review/handoff command。

package/speculo/workflows/dev/03-tdd/tdd-finish.md

@@ -8,14 +8,15 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
+- `.speculo/dev/<change>/tdd/<phase-id>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
 
 ## 填写引导
 
 1. 运行与变更相关的测试、类型检查、lint 或构建命令。
 2. 记录无法运行的命令和阻塞原因。
 3. 搜索临时调试标记、一次性脚本和推测性实现。
-4. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
+4. 验证通过后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「roadmap 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 roadmap 则跳过）。
+5. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
 
 ## 边界
 
@@ -24,5 +25,6 @@
 
 ## 完成准则
 
+- 多阶段 roadmap：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 roadmap 则不适用）
 - `verification.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `verified` 或 `blocked`

package/speculo/workflows/dev/03-tdd/tdd-loop.md

@@ -8,8 +8,8 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/implementation-log.md`，由 `../_templates/tdd-log-template.md` 填写
-- 可选：`tasks/00-INDEX.md` 与 `tasks/TNN.md`，由 workflow 自治创建
+- `.speculo/dev/<change>/tdd/<phase-id>/implementation-log.md`，由 `../_templates/tdd-log-template.md` 填写
+- 可选：`tdd/<phase-id>/tasks/00-INDEX.md` 与 `tdd/<phase-id>/tasks/TNN.md`，由 workflow 自治创建
 
 ## 填写引导
 

package/speculo/workflows/dev/03-tdd/tdd-plan.md

@@ -8,7 +8,7 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/tdd-plan.md`，由 `../_templates/tdd-plan-template.md` 填写
+- `.speculo/dev/<change>/tdd/<phase-id>/tdd-plan.md`，由 `../_templates/tdd-plan-template.md` 填写（`<phase-id>` 见 `03-tdd.md`「TDD 产物目录与阶段标识」）
 
 ## 填写引导
 
@@ -26,5 +26,6 @@
 
 ## 完成准则
 
+- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 roadmap 须与 `<phase>` 的 `id` 一致）
 - `tdd-plan.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `planned`

package/speculo/workflows/dev/04-finalize/04-finalize.md

@@ -126,6 +126,7 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 完成验证后写入 `verification_commands`、`requirements_checklist`、`verification_status`。
+- 多阶段 roadmap：完成前验证为 `verified` 后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `已实现` 置为 `已验证`（承接 `../03-tdd/03-tdd.md`「roadmap 阶段状态（XML 契约）」的最后一跳；无 roadmap 则跳过）。
 - 验证为 `blocked` 时停在本工作流，回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复，不归档。
 - 验证为 `verified` 且用户确认后：
   - **worktree 模式**：先执行 Phase 2，自动把 change 分支合并回 `base_branch` 并清理工作树与隔离分支（`worktree_status: merged` → `removed`，冲突即停），再在 base 分支上归档；非 worktree 模式跳过 Phase 2。

package/speculo/workflows/dev/04-finalize/completion-gate.md

@@ -4,7 +4,7 @@
 
 ## 输入
 
-- 当前 change 目录：`.speculo/dev/<change>/` 下的实现产物（`implementation-log.md`、`verification.md` 等）
+- 当前 change 目录：`.speculo/dev/<change>/` 下的实现产物（多阶段在 `tdd/<phase-id>/` 下的 `implementation-log.md`、`verification.md` 等）
 - 来源：PRD、issue、slices、诊断结论或用户明确任务
 - 项目的测试 / 类型检查 / lint / 构建命令
 - 变更 diff（VCS）
@@ -37,4 +37,5 @@
 - 需求清单逐项核对完成，含来源引用
 - 调试残留已清理或明确说明
 - `completion-verification.md` 无残留 `[TODO:]`
+- 多阶段 roadmap：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 roadmap 则不适用）
 - `.status.json` 写入 `verification_commands`、`requirements_checklist`、`verification_status`

package/speculo/workflows/dev/_templates/tdd-log-template.md

@@ -1,8 +1,11 @@
 > **服务工作流：** `../03-tdd/03-tdd.md`
-> **产物文件名：** `implementation-log.md`
+> **产物文件名：** `tdd/<phase-id>/implementation-log.md`
 
 # Implementation Log
 
+## 阶段标识
+[TODO: 本阶段 `<phase-id>`（与同目录 `tdd-plan.md` 一致）。]
+
 ## 循环记录
 [TODO: 对每轮 RED/GREEN/REFACTOR 记录切片、行为、测试、实现摘要、重构摘要和验证结果。]
 

package/speculo/workflows/dev/_templates/tdd-plan-template.md

@@ -1,8 +1,11 @@
 > **服务工作流：** `../03-tdd/03-tdd.md`
-> **产物文件名：** `tdd-plan.md`
+> **产物文件名：** `tdd/<phase-id>/tdd-plan.md`
 
 # TDD Plan
 
+## 阶段标识
+[TODO: 本阶段 `<phase-id>`。多阶段 roadmap 须与 roadmap `<phase>` 的 `id` 一致（如 `phase0-node-base`）；单阶段 change 用描述性切片 slug。产物落 `tdd/<phase-id>/`。]
+
 ## 切片来源
 [TODO: 记录来自 PRD、slices、diagnosis 还是用户直接请求。]
 

package/speculo/workflows/dev/_templates/tdd-verification-template.md

@@ -1,8 +1,11 @@
 > **服务工作流：** `../03-tdd/03-tdd.md`
-> **产物文件名：** `verification.md`
+> **产物文件名：** `tdd/<phase-id>/verification.md`
 
 # Verification
 
+## 阶段标识
+[TODO: 本阶段 `<phase-id>`（与同目录 `tdd-plan.md` 一致）。]
+
 ## 已运行命令
 [TODO: 列出实际运行的测试、类型检查、lint 或构建命令及结果。]