@namewta/speculo 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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/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-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 或构建命令及结果。]