@namewta/speculo 0.1.6 → 0.1.8

package/{speculo → template}/workflows/dev/00-INDEX.md

@@ -8,7 +8,11 @@ keywords: [dev, 开发, workflow, index, 状态]
 
 # Dev Workflow Index
 
-本文件是 dev 分类的导航入口。进入时先读取 `../../.speculo/dev-status.json`，再按其中 active change 读取 `../../.speculo/dev/<change>/.status.json`，根据用户意图推荐下一步。
+> ⚠️ **持久化铁律：本文件及所有 dev workflow 的全部产物，必须且只能写入 `speculo/.speculo/dev/<change>/`。绝对禁止写入项目根目录的 `.speculo/`、`temp/` 或其他任何非规范位置。**
+
+本文件是 dev 分类的导航入口。进入时先读取 `speculo/.speculo/dev-status.json`，再按其中 active change 读取 `speculo/.speculo/dev/<change>/.status.json`，根据用户意图推荐下一步。
+
+> **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。
 
 ## 入口别名
 
@@ -25,9 +29,10 @@ keywords: [dev, 开发, workflow, index, 状态]
 
 ## 进入协议
 
-1. 若用户未指定 change，扫描 `../../.speculo/dev-status.json` 和 `../../.speculo/dev/*/.status.json`，列出 active changes。
+1. 若用户未指定 change，扫描 `speculo/.speculo/dev-status.json` 和 `speculo/.speculo/dev/*/.status.json`，列出 active changes。
+   - **命名校验**：扫描时仅处理符合 `YYYY-MM-DD-<kebab-name>` 格式的目录。不符合的目录标记为 `malformed`，单独列出路径并提示用户修复或手动清理，不自动删除或重命名。
 2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
-3. 若没有 active change，按用户意图创建新的 change 目录，并初始化 `.status.json` 与 `../../.speculo/dev-status.json`。
+3. 若没有 active change，按用户意图创建新的 change 目录，**目录名必须为 `YYYY-MM-DD-<kebab-name>`**（使用当前日期，`<kebab-name>` 从用户意图提取），并初始化 `.status.json` 与 `speculo/.speculo/dev-status.json`。
 4. 推荐入口时优先使用用户显式别名；没有别名时按执行模式推荐。
 5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件、模板和被调用 skill wrapper。
 6. **Worktree 隔离（可选，默认 off）**：仅当用户**显式请求**隔离时，新 change 在 `dev/01` 的 Phase 0 经 `../../skills/worktree-isolation/SKILL.md` 建立隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树，并把 `base_branch`、`change_branch` 记入 `.status.json`。扫描 active changes 时，对 `worktree_enabled` 为真者可结合 `git worktree list` 核对工作树是否存在。
@@ -47,6 +52,7 @@ keywords: [dev, 开发, workflow, index, 状态]
 输出 dev 状态时至少包含：
 
 - active change 数量与每个 change 的 `current_phase`
+- malformed 目录清单（不符合 `YYYY-MM-DD-<kebab-name>` 格式的目录）
 - 最近更新的 change，按 `updated_at` 倒序
 - `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
 - worktree 模式 change 额外汇报 `base_branch` / `change_branch` / `worktree_status`

package/{speculo → template}/workflows/dev/01-grill-with-docs/01-grill-with-docs.md

@@ -19,24 +19,26 @@ keywords: [grill, context, adr, 术语, 决策]
 ### 输入
 
 - 用户提出的计划、需求、设计或变更意图
-- `.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
-- `.speculo/.config/context/CONTEXT.md`、`.speculo/.config/context/CONTEXT-MAP.md`、`.speculo/.config/adr/` 和相关代码
-- 当前 change 目录：`.speculo/dev/<change>/`
+- `speculo/.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
+- `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md`、`speculo/.speculo/.config/adr/` 和相关代码
+- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-user-auth`）
 
 ### 输出
 
-- `.speculo/dev/<change>/context-map.md`
-- `.speculo/dev/<change>/decision-log.md`
+- `speculo/.speculo/dev/<change>/context-map.md`
+- `speculo/.speculo/dev/<change>/decision-log.md`
 - 已确认的术语、决策、开放问题和 ADR 候选
 - 需要用户进一步决策的问题，每次只问一个
 
+（`<change>` 为当前 change 目录名，格式 `YYYY-MM-DD-<kebab-name>`）
+
 ### 执行原则
 
 针对计划的每个方面不断向用户提问，直到达成共识。沿着设计树的每条分支逐一展开，逐个解决决策之间的依赖关系。对于每个问题，给出推荐答案。
 
 每次只问一个问题，等待用户对当前问题的反馈后再继续。如果某个问题可以通过探索代码库来回答，就直接探索代码库。
 
-需要格式约定时读取同目录 `CONTEXT-FORMAT.md` 或 `ADR-FORMAT.md`。项目 CONTEXT 或 ADR 的创建、修改必须写入 `.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
+需要格式约定时读取同目录 `CONTEXT-FORMAT.md` 或 `ADR-FORMAT.md`。项目 CONTEXT 或 ADR 的创建、修改必须写入 `speculo/.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
 
 ### Worktree 隔离（条件）
 
@@ -44,7 +46,7 @@ keywords: [grill, context, adr, 术语, 决策]
 
 - 用户未请求隔离时，**不读取**该 skill，跳过 Phase 0，按既有流程在当前分支推进，行为零变化。
 - 启用后，本 change 的代码与全部 Speculo 产物都落在隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树内，原分支不被污染；状态里记录 `base_branch` 与 `change_branch`，供 review、finalize 跨阶段跟进。
-- 隔离前置不满足（非 git 仓库 / 工作区不净 / `.speculo/` 未被 git 跟踪）时由该 skill 降级为非 worktree 模式并报告，不强行创建。
+- 隔离前置不满足（非 git 仓库 / 工作区不净 / `speculo/.speculo/` 未被 git 跟踪）时由该 skill 降级为非 worktree 模式并报告，不强行创建。
 
 ## 阶段
 
@@ -71,7 +73,7 @@ keywords: [grill, context, adr, 术语, 决策]
 - 产物：`decision-log.md`
 - 完成准则：
   - 关键决策均有结论、推荐答案或开放问题
-  - 需要写入 `.speculo/.config/context/` 或 `.speculo/.config/adr/` 的内容已获用户确认，或记录为候选
+  - 需要写入 `speculo/.speculo/.config/context/` 或 `speculo/.speculo/.config/adr/` 的内容已获用户确认，或记录为候选
   - `decision-log.md` 无残留 `[TODO:]`
 
 ## 依赖

package/{speculo → template}/workflows/dev/01-grill-with-docs/ADR-FORMAT.md

@@ -1,10 +1,10 @@
 # ADR 格式
 
-本辅助文档只定义项目 ADR 的写法。默认产物仍写入 `.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建项目 ADR。
+本辅助文档只定义项目 ADR 的写法。默认产物仍写入 `speculo/.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建项目 ADR。
 
-ADR 存放在 `.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。
+ADR 存放在 `speculo/.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。
 
-`.speculo/.config/adr/` 目录由 Speculo 初始化提供；如果目标项目缺失该目录，按需创建。
+`speculo/.speculo/.config/adr/` 目录由 Speculo 初始化提供；如果目标项目缺失该目录，按需创建。
 
 ## 模板
 
@@ -26,7 +26,7 @@ ADR 存放在 `.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slu
 
 ## 编号
 
-扫描 `.speculo/.config/adr/` 找到已有的最大编号，然后加一。
+扫描 `speculo/.speculo/.config/adr/` 找到已有的最大编号，然后加一。
 
 ## 何时提议创建 ADR
 

package/{speculo → template}/workflows/dev/01-grill-with-docs/CONTEXT-FORMAT.md

@@ -1,6 +1,6 @@
 # CONTEXT.md 格式
 
-本辅助文档只定义项目术语表的写法。默认产物仍写入 `.speculo/dev/<change>/context-map.md` 和 `.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建或更新 `.speculo/.config/context/CONTEXT.md` / `.speculo/.config/context/CONTEXT-MAP.md`。
+本辅助文档只定义项目术语表的写法。默认产物仍写入 `speculo/.speculo/dev/<change>/context-map.md` 和 `speculo/.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建或更新 `speculo/.speculo/.config/context/CONTEXT.md` / `speculo/.speculo/.config/context/CONTEXT-MAP.md`。
 
 ## 结构
 
@@ -36,9 +36,9 @@ _避免使用_：Client、buyer、account
 
 ## 单上下文与多上下文仓库
 
-**单上下文（大多数仓库）：** `.speculo/.config/context/CONTEXT.md` 记录项目级术语表。
+**单上下文（大多数仓库）：** `speculo/.speculo/.config/context/CONTEXT.md` 记录项目级术语表。
 
-**多上下文：** `.speculo/.config/context/CONTEXT-MAP.md` 列出所有上下文、它们的位置以及它们之间的关系：
+**多上下文：** `speculo/.speculo/.config/context/CONTEXT-MAP.md` 列出所有上下文、它们的位置以及它们之间的关系：
 
 ```md
 # 上下文映射
@@ -58,8 +58,8 @@ _避免使用_：Client、buyer、account
 
 技能会自动推断适用哪种结构：
 
-- 如果 `.speculo/.config/context/CONTEXT-MAP.md` 存在，读取它以查找上下文
-- 如果只有 `.speculo/.config/context/CONTEXT.md`，则为单上下文
-- 如果都不存在，在第一个术语确定时按需创建 `.speculo/.config/context/CONTEXT.md`
+- 如果 `speculo/.speculo/.config/context/CONTEXT-MAP.md` 存在，读取它以查找上下文
+- 如果只有 `speculo/.speculo/.config/context/CONTEXT.md`，则为单上下文
+- 如果都不存在，在第一个术语确定时按需创建 `speculo/.speculo/.config/context/CONTEXT.md`
 
 当存在多个上下文时，推断当前主题与哪个上下文相关。如果不确定，就问。

package/template/workflows/dev/01-grill-with-docs/grill-context-scan.md

@@ -0,0 +1,30 @@
+# Context Scan Phase
+
+## 输入
+
+- 用户提出的计划、需求、设计或问题
+- `speculo/.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
+- `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md`、`speculo/.speculo/.config/adr/` 和相关代码
+- 本 workflow 入口文件中的内置领域拷问指引
+
+## 产物
+
+- `speculo/.speculo/dev/<change>/context-map.md`，由 `../_templates/grill-context-map-template.md` 填写
+
+## 填写引导
+
+1. 先探索仓库事实，不向用户询问可从文件中确认的问题。
+2. 记录存在的领域术语来源、ADR 来源、关键模块和调用者。
+3. 标出缺失的术语表、缺失 ADR 或与用户描述冲突的代码事实。
+4. 只记录事实和待确认项，不在本阶段做方案裁决。
+5. 若 `speculo/.speculo/.config/context/CONTEXT-MAP.md` 存在，先读取它以判断涉及哪个上下文；若只有 `speculo/.speculo/.config/context/CONTEXT.md`，按单上下文处理；若都不存在，只记录“缺少术语表”，不在本阶段创建。
+
+## 边界
+
+- 不直接修改 `speculo/.speculo/.config/context/` 或 `speculo/.speculo/.config/adr/`；修改动作留到 Decision Grill 阶段确认后执行。
+- 不创建实现计划或 PRD。
+
+## 完成准则
+
+- `context-map.md` 无残留 `[TODO:]`
+- 已列出下一阶段必须追问的最高优先级问题

package/{speculo → template}/workflows/dev/01-grill-with-docs/grill-decision.md

@@ -2,15 +2,15 @@
 
 ## 输入
 
-- `.speculo/dev/<change>/context-map.md`
+- `speculo/.speculo/dev/<change>/context-map.md`
 - 用户当前方案或目标
 - 本 workflow 入口文件中的内置领域拷问指引
 - 同目录 `CONTEXT-FORMAT.md`、`ADR-FORMAT.md`
 
 ## 产物
 
-- `.speculo/dev/<change>/decision-log.md`，由 `../_templates/grill-decision-log-template.md` 填写
-- 可选：经用户确认后更新 `.speculo/.config/context/CONTEXT.md`、`.speculo/.config/context/CONTEXT-MAP.md` 或 `.speculo/.config/adr/*.md`
+- `speculo/.speculo/dev/<change>/decision-log.md`，由 `../_templates/grill-decision-log-template.md` 填写
+- 可选：经用户确认后更新 `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md` 或 `speculo/.speculo/.config/adr/*.md`
 
 ## 填写引导
 
@@ -18,8 +18,8 @@
 2. 每次只问一个会改变决策树的问题，并给出推荐答案。
 3. 对术语冲突、代码现实冲突和 ADR 候选直接指出。
 4. 用户确认后，把决策写入 `decision-log.md`。
-5. 只有用户明确同意时，才把术语写入 `.speculo/.config/context/` 或创建 `.speculo/.config/adr/` 下的 ADR。
-6. 当用户使用的术语与 `.speculo/.config/context/` 中已有定义冲突时，立即指出冲突并要求在当前问题中消解。
+5. 只有用户明确同意时，才把术语写入 `speculo/.speculo/.config/context/` 或创建 `speculo/.speculo/.config/adr/` 下的 ADR。
+6. 当用户使用的术语与 `speculo/.speculo/.config/context/` 中已有定义冲突时，立即指出冲突并要求在当前问题中消解。
 7. 当用户使用含混或一词多义的术语时，提议一个精确的规范术语。
 8. 当讨论领域关系时，用具体场景压力测试边界情况。
 9. 当用户描述某个东西如何运作时，检查代码是否一致；若矛盾，直接指出。
@@ -29,7 +29,7 @@
 
 - 不输出 PRD；PRD 由 `../02-prd/02-prd.md` 负责。
 - 不把未确认的 ADR 候选写成正式 ADR。
-- 不修改 `.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
+- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
 
 ## 完成准则
 

package/{speculo → template}/workflows/dev/02-prd/02-prd.md

@@ -10,6 +10,8 @@ keywords: [prd, zoom-out, 需求, 计划]
 
 本工作流用于把已知上下文综合为当前 Speculo change 内的 overview 和 PRD。zoom-out 全景理解与 PRD 综合能力已内置在本 workflow 目录中。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。产物写入 `speculo/.speculo/dev/<change>/`。
+
 ## 内置指引
 
 ### Zoom Out
@@ -20,7 +22,9 @@ keywords: [prd, zoom-out, 需求, 计划]
 
 当 dev workflow 已完成足够上下文探索，需要把当前对话和代码理解沉淀成 PRD 时使用。不要重复访谈已明确的信息；综合当前对话、代码库事实、领域术语、ADR、模块候选和测试目标。
 
-PRD 只写入 `.speculo/dev/<change>/prd.md`，overview 只写入 `.speculo/dev/<change>/overview.md`。不写项目根下的任意规划文档，不默认发布外部 issue。只有 tracker 已配置且用户明确要求时，才进入外部发布动作。
+PRD 只写入 `speculo/.speculo/dev/<change>/prd.md`，overview 只写入 `speculo/.speculo/dev/<change>/overview.md`。不写项目根下的任意规划文档，不默认发布外部 issue。只有 tracker 已配置且用户明确要求时，才进入外部发布动作。
+
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
 
 ## 阶段
 

package/{speculo → template}/workflows/dev/02-prd/prd-synthesis.md

@@ -2,13 +2,13 @@
 
 ## 输入
 
-- `.speculo/dev/<change>/overview.md`
+- `speculo/.speculo/dev/<change>/overview.md`
 - 可选的 `context-map.md`、`decision-log.md`、用户故事或 issue
 - `02-prd.md` 中的 PRD Synthesis 内置指引
 
 ## 产物
 
-- `.speculo/dev/<change>/prd.md`，由 `../_templates/prd-template.md` 填写
+- `speculo/.speculo/dev/<change>/prd.md`，由 `../_templates/prd-template.md` 填写
 
 ## 填写引导
 

package/{speculo → template}/workflows/dev/02-prd/prd-zoom-out.md

@@ -8,7 +8,7 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/overview.md`，由 `../_templates/prd-overview-template.md` 填写
+- `speculo/.speculo/dev/<change>/overview.md`，由 `../_templates/prd-overview-template.md` 填写
 
 ## 填写引导
 

package/{speculo → template}/workflows/dev/03-tdd/03-tdd.md

@@ -32,7 +32,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 ## 阶段
 
-> **产物目录：** 本工作流所有产物写入 `.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。
+> **产物目录：** 本工作流所有产物写入 `speculo/.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-user-auth`）。
 
 ### 1. TDD Plan — 行为与接口计划
 - 规范：`tdd-plan.md`
@@ -63,7 +63,8 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 ## TDD 产物目录与阶段标识
 
-- 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / slices 等产物分离，便于多阶段并行与回溯。
+- 本工作流所有产物集中在 `speculo/.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / slices 等产物分离，便于多阶段并行与回溯。
+- `<change>` 为当前 change 目录名（`YYYY-MM-DD-<kebab-name>`）。
 - `<phase-id>` 标识：
   - change 来自**多阶段 slices** 时，用 slices 阶段标识（与 slices `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
   - change 为**单阶段**（无 slices 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。
@@ -71,7 +72,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - 目录形如：
 
 ```text
-.speculo/dev/<change>/tdd/
+speculo/.speculo/dev/<change>/tdd/
 ├── phase0-node-base/
 │   ├── tdd-plan.md
 │   ├── implementation-log.md
@@ -84,7 +85,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 ## phase 阶段状态（XML 契约）
 
-多阶段 change（`.speculo/dev/<change>/slices.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
+多阶段 change（`speculo/.speculo/dev/<change>/slices.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
 
 ```xml
 <phase id="phase0-node-base" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>

package/{speculo → template}/workflows/dev/03-tdd/tdd-finish.md

@@ -8,7 +8,7 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/tdd/<phase-id>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
+- `speculo/.speculo/dev/<change>/tdd/<phase-id>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
 
 ## 填写引导
 
@@ -16,12 +16,12 @@
 2. 记录无法运行的命令和阻塞原因。
 3. 搜索临时调试标记、一次性脚本和推测性实现。
 4. 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「phase 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 slices 则跳过）。
-5. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
+5. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。
 
 ## 边界
 
 - 不自动归档 change；归档由 `commands/archive.md` 负责。
-- 不修改 `.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
+- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
 
 ## 完成准则
 

package/{speculo → template}/workflows/dev/03-tdd/tdd-loop.md

@@ -8,7 +8,7 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/tdd/<phase-id>/implementation-log.md`，由 `../_templates/tdd-log-template.md` 填写
+- `speculo/.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 → template}/workflows/dev/03-tdd/tdd-plan.md

@@ -8,7 +8,7 @@
 
 ## 产物
 
-- `.speculo/dev/<change>/tdd/<phase-id>/tdd-plan.md`，由 `../_templates/tdd-plan-template.md` 填写（`<phase-id>` 见 `03-tdd.md`「TDD 产物目录与阶段标识」）
+- `speculo/.speculo/dev/<change>/tdd/<phase-id>/tdd-plan.md`，由 `../_templates/tdd-plan-template.md` 填写（`<phase-id>` 见 `03-tdd.md`「TDD 产物目录与阶段标识」）
 
 ## 填写引导
 

package/{speculo → template}/workflows/dev/04-finalize/04-finalize.md

@@ -10,6 +10,8 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 
 本工作流是 `dev/04` 入口，是开发主线的收尾环节（`dev/01` → `dev/02` → `dev/I` → `dev/03` → `dev/04`）。它在 change 的实现完成后，**先用证据证明"真的完成了"，再改变状态并归档**。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。归档目标为 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
+
 ## 内置指引
 
 ### 核心原则
@@ -101,8 +103,8 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
   - `verification_status` 为 `verified`（`blocked` 时不得归档）
   - worktree 模式下，归档在 `base_branch` 上进行（change 目录已随 Phase 2 合并到达 base）
   - `change_status` 先置 `completed`，再随归档置 `archived`
-  - change 目录已移动到 `.speculo/archive/dev/<YYYY-MM>/<change>/`
-  - 已从 `.speculo/dev-status.json` 的 `active[]` 移除该 change
+  - change 目录已移动到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
+  - 已从 `speculo/.speculo/dev-status.json` 的 `active[]` 移除该 change
   - `completion-summary.md` 无残留 `[TODO:]`
 
 ## 依赖
@@ -130,5 +132,5 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 - 验证为 `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。
-  - 置 `change_status: completed` → 执行归档 → 置 `change_status: archived`、`archived: true`、写 `archive_path`，并从 `.speculo/dev-status.json` 移除。
-- 如有可沉淀经验，在用户或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
+  - 置 `change_status: completed` → 执行归档 → 置 `change_status: archived`、`archived: true`、写 `archive_path`，并从 `speculo/.speculo/dev-status.json` 移除。
+- 如有可沉淀经验，在用户或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。

package/{speculo → template}/workflows/dev/04-finalize/completion-gate.md

@@ -4,14 +4,14 @@
 
 ## 输入
 
-- 当前 change 目录：`.speculo/dev/<change>/` 下的实现产物（多阶段在 `tdd/<phase-id>/` 下的 `implementation-log.md`、`verification.md` 等）
+- 当前 change 目录：`speculo/.speculo/dev/<change>/` 下的实现产物（多阶段在 `tdd/<phase-id>/` 下的 `implementation-log.md`、`verification.md` 等）
 - 来源：PRD、issue、slices、诊断结论或用户明确任务
 - 项目的测试 / 类型检查 / lint / 构建命令
 - 变更 diff（VCS）
 
 ## 产物
 
-- `.speculo/dev/<change>/completion-verification.md`，由 `../_templates/completion-verification-template.md` 填写
+- `speculo/.speculo/dev/<change>/completion-verification.md`，由 `../_templates/completion-verification-template.md` 填写
 
 ## 填写引导
 
@@ -29,7 +29,7 @@
 - 不夸大、不用"应该""大概""似乎"等措辞；信心 ≠ 证据。
 - 不依赖上一轮的旧结果或部分检查。
 - `blocked` 时不进入归档；回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复后重跑本阶段。
-- 不修改 `.speculo/.config/RULES.md` 或用户未授权的项目规则文档。
+- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未授权的项目规则文档。
 
 ## 完成准则
 

package/{speculo → template}/workflows/dev/04-finalize/finalize-archive.md

@@ -4,14 +4,14 @@
 
 ## 输入
 
-- `.speculo/dev/<change>/completion-verification.md`，且 `verification_status: verified`
+- `speculo/.speculo/dev/<change>/completion-verification.md`，且 `verification_status: verified`
 - 当前 change 的 `.status.json`
-- 顶层索引 `.speculo/dev-status.json`
+- 顶层索引 `speculo/.speculo/dev-status.json`
 
 ## 产物
 
-- `.speculo/dev/<change>/completion-summary.md`，由 `../_templates/completion-summary-template.md` 填写
-- 归档动作：change 目录移动到 `.speculo/archive/dev/<YYYY-MM>/<change>/`
+- `speculo/.speculo/dev/<change>/completion-summary.md`，由 `../_templates/completion-summary-template.md` 填写
+- 归档动作：change 目录移动到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
 
 ## 填写引导
 
@@ -24,19 +24,19 @@
 
 2. 写 `completion-summary.md`：交付边界、关键变更、验证证据指针（指向 `completion-verification.md`）、遗留事项。
 3. 把当前 change `.status.json` 的 `change_status` 置为 `completed`。
-4. 如有可沉淀经验，在用户或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
+4. 如有可沉淀经验，在用户或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。
 
 ### 归档（破坏性，需确认）
 
 本步与 `../../../commands/archive.md` 共用同一安全契约；此处作用域仅限**当前单个 change**：
 
-5. 列出归档计划：源路径 `.speculo/dev/<change>/`、目标路径 `.speculo/archive/dev/<YYYY-MM>/<change>/`、`updated_at`、最后 phase、是否仍在 `dev-status.json` 的 `active[]`。
+5. 列出归档计划：源路径 `speculo/.speculo/dev/<change>/`、目标路径 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`、`updated_at`、最后 phase、是否仍在 `dev-status.json` 的 `active[]`。
 6. 向用户展示计划并等待明确确认。**没有确认时只输出计划，不移动目录、不改索引。**
 7. 若目标归档路径已存在，标记冲突并停止，不覆盖。
 8. 用户确认后执行：
-   - 创建 `.speculo/archive/dev/<YYYY-MM>/`
-   - 移动 change 目录到 `.speculo/archive/dev/<YYYY-MM>/<change>/`
-   - 从 `.speculo/dev-status.json` 的 `active[]` 删除该 change
+   - 创建 `speculo/.speculo/archive/dev/<YYYY-MM>/`
+   - 移动 change 目录到 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
+   - 从 `speculo/.speculo/dev-status.json` 的 `active[]` 删除该 change
    - 把（已随目录移动的）`.status.json` 的 `change_status` 置为 `archived`，写 `archived: true`、`archive_path`
 9. 若移动失败，停止后续动作，报告已完成与未完成项；不要回滚已成功的移动，除非用户明确要求。
 
@@ -50,6 +50,6 @@
 ## 完成准则
 
 - `completion-summary.md` 无残留 `[TODO:]`
-- change 目录已位于 `.speculo/archive/dev/<YYYY-MM>/<change>/`
-- `.speculo/dev-status.json` 的 `active[]` 已移除该 change
+- change 目录已位于 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`
+- `speculo/.speculo/dev-status.json` 的 `active[]` 已移除该 change
 - `.status.json` 的 `change_status: archived`，`archived: true`，`archive_path` 已写入

package/{speculo → template}/workflows/dev/D-docs-sync/D-docs-sync.md

@@ -14,22 +14,24 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 
 ### Iron Law
 
-禁止在不读取 `.speculo/dev/docs-sync-state.json` 的 `last_sync_sha` 与当前 `HEAD` 之间 diff 的情况下修改任何对外文档。
+禁止在不读取 `speculo/.speculo/dev/docs-sync-state.json` 的 `last_sync_sha` 与当前 `HEAD` 之间 diff 的情况下修改任何对外文档。
 
 如果 diff 为空，或只有文档自身变动，直接报告无需同步或空同步，并按规则推进 state；不要触碰无关文档。
 
 ### 输入
 
-- `.speculo/dev/docs-sync-state.json`
+- `speculo/.speculo/dev/docs-sync-state.json`
 - 当前 git `HEAD`
 - state 中的 `tracked_docs` 列表
-- 当前 change 目录：`.speculo/dev/<change>/`
+- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-docs-sync`）
 
 ### 输出
 
-- `.speculo/dev/<change>/docs-sync-report.md`
+- `speculo/.speculo/dev/<change>/docs-sync-report.md`
 - 更新后的 tracked docs
-- 更新后的 `.speculo/dev/docs-sync-state.json`
+- 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
+
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
 
 ### 渐进披露
 
@@ -43,7 +45,7 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 ### 1. State Read — 读取同步状态
 - 规范：`docs-sync-state.md`
 - 模板：`../_templates/docs-sync-state-template.json`
-- 产物：`.speculo/dev/docs-sync-state.json`
+- 产物：`speculo/.speculo/dev/docs-sync-state.json`
 - 完成准则：
   - 已确定 `LAST_SYNC_SHA` 和 `HEAD_SHA`
   - 首次运行时已初始化 state 并要求用户确认 `tracked_docs`
@@ -68,7 +70,7 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 ### 4. State Write — 验证与写回状态
 - 规范：`docs-sync-finish.md`
 - 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`.speculo/dev/docs-sync-state.json`
+- 产物：`speculo/.speculo/dev/docs-sync-state.json`
 - 完成准则：
   - 已运行项目级校验或记录无法运行原因
   - state 已原子写入
@@ -84,7 +86,7 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 本工作流需在同 change 的 `.status.json` 追加：
 
 - `dev_entry` (string) — 固定为 `dev/D`
-- `docs_sync_state_path` (string) — 固定为 `.speculo/dev/docs-sync-state.json`
+- `docs_sync_state_path` (string) — 固定为 `speculo/.speculo/dev/docs-sync-state.json`
 - `docs_sync_range` (string) — `<LAST_SYNC_SHA>..HEAD`
 - `tracked_docs` (array) — 本次纳入同步的文档
 - `synced_docs` (array) — 本次实际修改的文档
@@ -93,5 +95,5 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 ## 完成与状态更新
 
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 只有验证完成后才原子写回 `.speculo/dev/docs-sync-state.json`。
+- 只有验证完成后才原子写回 `speculo/.speculo/dev/docs-sync-state.json`。
 - 本 workflow 不自动完成 change；用户要求仅同步文档时，可在报告完成后把 `change_status` 置为 `completed`。

package/{speculo → template}/workflows/dev/D-docs-sync/docs-sync-diff.md

@@ -2,13 +2,13 @@
 
 ## 输入
 
-- `.speculo/dev/docs-sync-state.json`
+- `speculo/.speculo/dev/docs-sync-state.json`
 - `LAST_SYNC_SHA`
 - 当前 `HEAD`
 
 ## 产物
 
-- `.speculo/dev/<change>/docs-sync-report.md`，由 `../_templates/docs-sync-report-template.md` 填写或追加
+- `speculo/.speculo/dev/<change>/docs-sync-report.md`，由 `../_templates/docs-sync-report-template.md` 填写或追加
 
 ## 填写引导
 

package/{speculo → template}/workflows/dev/D-docs-sync/docs-sync-finish.md

@@ -3,14 +3,14 @@
 ## 输入
 
 - 更新后的 tracked docs
-- `.speculo/dev/docs-sync-state.json`
-- `.speculo/dev/<change>/docs-sync-report.md`
+- `speculo/.speculo/dev/docs-sync-state.json`
+- `speculo/.speculo/dev/<change>/docs-sync-report.md`
 - 当前 `HEAD`
 
 ## 产物
 
-- 更新后的 `.speculo/dev/docs-sync-state.json`
-- 完整的 `.speculo/dev/<change>/docs-sync-report.md`
+- 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
+- 完整的 `speculo/.speculo/dev/<change>/docs-sync-report.md`
 
 ## 填写引导
 
@@ -18,7 +18,7 @@
 2. 如果所有差异都无需文档修改，仍把 `last_sync_sha` 推进到当前 `HEAD`，并把 `synced_docs` 置为 `[]`。
 3. 如果修改了文档，验证通过后再推进 state。
 4. 写回 state 时按 `state-json-schema.md` 字段顺序，2 空格缩进，尾部换行。
-5. 原子化写入：先写 `.speculo/dev/docs-sync-state.json.tmp`，再 rename。
+5. 原子化写入：先写 `speculo/.speculo/dev/docs-sync-state.json.tmp`，再 rename。
 6. 按 report 模板向用户报告范围、改动文档、新基线和验证命令。
 
 ## 边界

package/{speculo → template}/workflows/dev/D-docs-sync/docs-sync-state.md

@@ -2,19 +2,19 @@
 
 ## 输入
 
-- `.speculo/dev/docs-sync-state.json`
+- `speculo/.speculo/dev/docs-sync-state.json`
 - `git rev-parse HEAD`
 - `../_templates/docs-sync-state-template.json`
 
 ## 产物
 
-- `.speculo/dev/docs-sync-state.json`
-- `.speculo/dev/<change>/docs-sync-report.md`
+- `speculo/.speculo/dev/docs-sync-state.json`
+- `speculo/.speculo/dev/<change>/docs-sync-report.md`
 
 ## 填写引导
 
-1. 设置 `STATE_FILE=".speculo/dev/docs-sync-state.json"`。
-2. 若 state 文件不存在，复制 `../_templates/docs-sync-state-template.json` 为骨架，把 `state_path` 设为 `.speculo/dev/docs-sync-state.json`。
+1. 设置 `STATE_FILE="speculo/.speculo/dev/docs-sync-state.json"`。
+2. 若 state 文件不存在，复制 `../_templates/docs-sync-state-template.json` 为骨架，把 `state_path` 设为 `speculo/.speculo/dev/docs-sync-state.json`。
 3. 读取 `last_sync_sha` 和当前 `HEAD`。
 4. 若 `tracked_docs` 为空，列出候选文档，请用户确认后写入 state；本次不修改对外文档。
 5. 若 `last_sync_sha` 为 `null`，把当前 `HEAD` 建为初始基线；本次不修改对外文档。

package/{speculo → template}/workflows/dev/D-docs-sync/docs-sync-update.md

@@ -2,7 +2,7 @@
 
 ## 输入
 
-- `.speculo/dev/<change>/docs-sync-report.md`
+- `speculo/.speculo/dev/<change>/docs-sync-report.md`
 - state 中的 `tracked_docs`
 - git 差异素材
 - 按需读取的 contract 文件
@@ -10,7 +10,7 @@
 ## 产物
 
 - 更新后的 tracked docs
-- `.speculo/dev/<change>/docs-sync-report.md`
+- `speculo/.speculo/dev/<change>/docs-sync-report.md`
 
 ## 填写引导