@namewta/speculo 0.1.7 → 0.1.9

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,7 +10,7 @@ keywords: [prd, zoom-out, 需求, 计划]
 
 本工作流用于把已知上下文综合为当前 Speculo change 内的 overview 和 PRD。zoom-out 全景理解与 PRD 综合能力已内置在本 workflow 目录中。
 
-> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。产物写入 `.speculo/dev/<change>/`。
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。产物写入 `speculo/.speculo/dev/<change>/`。
 
 ## 内置指引
 
@@ -22,7 +22,7 @@ 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

@@ -30,9 +30,19 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - `interface-design.md`：设计可测试公共接口时读取。
 - `refactoring.md`：进入重构阶段时读取。
 
+### 消费 slices 切片契约
+
+多阶段 change 从 `slices.md` 接手时，每个 TDD 阶段对应一个切片，须读取并守护该切片契约（见 `../I-to-issues/issues-slices.md`）：
+
+- **保留/不动**：把切片的「保留/不动」清单当作实现硬约束——冻结常量 / 共享依赖 / 邻近功能一律不碰。
+- **关键核实结论与行号现场核对**：切片记录的行号为*近似*，实现时一律以现场代码为准、不照搬。
+- **验收切片**：Finish 阶段运行切片的「验收切片」；删除型切片须含残留扫描（`grep` 0 命中）并留证。
+- **横切铁律**：遵守 §4 横切关注点（契约先行、删缓存可重建、数据安全冻结等）。
+- **存疑即问**：计划阶段遇未决分支，按 `../I-to-issues/issues-slices.md`「存疑时的提问协议」一次一问、带推荐、逐步锁定。
+
 ## 阶段
 
-> **产物目录：** 本工作流所有产物写入 `.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-user-auth`）。
+> **产物目录：** 本工作流所有产物写入 `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 +73,7 @@ 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`。
@@ -72,7 +82,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
@@ -85,7 +95,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/template/workflows/dev/03-tdd/tdd-finish.md

@@ -0,0 +1,34 @@
+# Finish Phase
+
+## 输入
+
+- `implementation-log.md`
+- 项目验证命令和变更 diff
+- `03-tdd.md` 中的内置 TDD 指引和同目录 `refactoring.md`
+
+## 产物
+
+- `speculo/.speculo/dev/<change>/tdd/<phase-id>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
+
+## 填写引导
+
+1. 运行与变更相关的测试、类型检查、lint 或构建命令。
+2. **运行本切片「验收切片」**：执行切片记录的验收命令/步骤；**删除型切片须做残留扫描**（`grep -rn "<符号>" <范围>` 应 0 命中），记录证据。
+3. **核对「保留/不动」未被破坏**：确认实现未触碰切片冻结的常量 / 共享依赖 / 邻近功能。
+4. 记录无法运行的命令和阻塞原因。
+5. 搜索临时调试标记、一次性脚本和推测性实现。
+6. 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「phase 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 slices 则跳过）。
+7. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `speculo/.speculo/.config/LESSONS.md`。
+
+## 边界
+
+- 不自动归档 change；归档由 `commands/archive.md` 负责。
+- 不修改 `speculo/.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
+
+## 完成准则
+
+- 本切片「验收切片」已运行通过（删除型切片含残留扫描 `grep` 0 命中），并在 `verification.md` 留证
+- 「保留/不动」清单经核对未被破坏
+- 多阶段 slices：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 slices 则不适用）
+- `verification.md` 无残留 `[TODO:]`
+- `.status.json` 的 `implementation_status` 为 `verified` 或 `blocked`

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 自治创建
 
 ## 填写引导
@@ -18,13 +18,14 @@
 3. GREEN：写最少实现使当前测试通过。
 4. REFACTOR：只在绿色状态下整理设计。
 5. 每轮记录测试名、失败信号、实现摘要、重构摘要和验证命令。
-6. 每轮检查：测试描述行为而非实现；测试只使用公共接口；测试能经受内部重构；代码是当前测试的最少实现；没有添加推测性功能。
+6. 每轮检查：测试描述行为而非实现；测试只使用公共接口；测试能经受内部重构；代码是当前测试的最少实现；没有添加推测性功能；**未触碰本切片「保留/不动」清单**；引用代码以现场为准（不照搬切片行号）。
 
 ## 边界
 
 - 不预实现未来切片。
 - 不使用内部实现细节作为主要断言。
 - 不在 RED 状态下重构。
+- 不触碰本切片「保留/不动」清单（冻结常量 / 共享依赖 / 邻近功能）。
 
 ## 完成准则
 

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

@@ -3,12 +3,13 @@
 ## 输入
 
 - `prd.md`、`slices.md`、`diagnosis.md` 或用户明确任务
+- 多阶段：本阶段对应切片的 **保留/不动**、**关键核实结论**、**验收切片** 与 §4 横切铁律（`slices.md`）
 - 项目测试命令、现有测试样式和公共接口
-- `03-tdd.md` 中的内置 TDD 指引和同目录辅助文档
+- `03-tdd.md` 中的内置 TDD 指引（含「消费 slices 切片契约」）和同目录辅助文档
 
 ## 产物
 
-- `.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 产物目录与阶段标识」）
 
 ## 填写引导
 
@@ -18,6 +19,7 @@
 4. 拆出第一个 tracing slice，避免水平切片。
 5. 探索代码库时使用项目领域术语表，确保测试名称和接口词汇与项目语言一致，并尊重触及区域的 ADR。
 6. 写任何代码前确认接口变更、优先测试的行为、deep module 机会、可测试接口设计和行为列表。
+7. **承载切片契约**：把本阶段对应切片的 **保留/不动** 与 **关键核实结论** 记入计划作为实现约束；切片行号为近似、以现场代码为准（现场核对）；存疑分支按 `../I-to-issues/issues-slices.md`「存疑时的提问协议」一次一问、带推荐、逐步锁定。
 
 ## 边界
 
@@ -27,5 +29,6 @@
 ## 完成准则
 
 - 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 slices 须与 `<phase>` 的 `id` 一致）
+- 多阶段：已记录本切片 **保留/不动** 约束与 **现场核对** 结论
 - `tdd-plan.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `planned`

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

@@ -10,7 +10,7 @@ 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/archive/dev/<YYYY-MM>/<change>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。归档目标为 `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
 
 ## 内置指引
 
@@ -103,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:]`
 
 ## 依赖
@@ -132,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,22 @@ 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>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-docs-sync`）
+- 当前 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>`）
 
@@ -45,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`
@@ -70,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 已原子写入
@@ -86,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) — 本次实际修改的文档
@@ -95,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`
 
 ## 填写引导
 

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

@@ -1,6 +1,6 @@
 # state 文件 Schema（docs-sync 持久化状态）
 
-**默认存储位置**：`.speculo/dev/docs-sync-state.json`
+**默认存储位置**：`speculo/.speculo/dev/docs-sync-state.json`
 
 本 workflow 在首次运行时会按默认路径创建；后续读写均以同一路径为准。不要把 docs-sync state 放到仓库根目录。
 
@@ -9,7 +9,7 @@
 - docs-sync workflow **唯一**的跨 change 持久化状态
 - 每次成功同步后原子化写入
 - 必须跟随仓库提交到 git（作为同步基线的事实来源）
-- **不放在 workflow 资产目录内**：workflow 目录是只读知识资产，状态属于项目 `.speculo/`
+- **不放在 workflow 资产目录内**：workflow 目录是只读知识资产，状态属于项目 `speculo/.speculo/`
 
 **初始化模板**：`../_templates/docs-sync-state-template.json`
 
@@ -45,7 +45,7 @@
 {
   "schema_version": 1,
   "skill": "docs-sync",
-  "state_path": ".speculo/dev/docs-sync-state.json",
+  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
   "tracked_docs": [],
   "last_sync_sha": null,
   "last_sync_short": null,
@@ -64,7 +64,7 @@
 {
   "schema_version": 1,
   "skill": "docs-sync",
-  "state_path": ".speculo/dev/docs-sync-state.json",
+  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
   "tracked_docs": ["README.md", "CHANGELOG.md"],
   "last_sync_sha": "2d16d7a4d7f5da165c565b9aa3265824be133214",
   "last_sync_short": "2d16d7a",
@@ -83,7 +83,7 @@
 {
   "schema_version": 1,
   "skill": "docs-sync",
-  "state_path": ".speculo/dev/docs-sync-state.json",
+  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
   "tracked_docs": ["README.md", "CHANGELOG.md"],
   "last_sync_sha": "abc1234def5678...",
   "last_sync_short": "abc1234",
@@ -102,7 +102,7 @@
 {
   "schema_version": 1,
   "skill": "docs-sync",
-  "state_path": ".speculo/dev/docs-sync-state.json",
+  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
   "tracked_docs": ["README.md", "CHANGELOG.md"],
   "last_sync_sha": "ffe9876abc5432...",
   "last_sync_short": "ffe9876",
@@ -126,7 +126,7 @@
 
 读取 state 文件时按以下降级链处理：
 
-1. 文件不存在 → 首次运行流程：复制 `../_templates/docs-sync-state-template.json` 到 `.speculo/dev/docs-sync-state.json`，基线设为当前 HEAD，请用户确认 `tracked_docs`
+1. 文件不存在 → 首次运行流程：复制 `../_templates/docs-sync-state-template.json` 到 `speculo/.speculo/dev/docs-sync-state.json`，基线设为当前 HEAD，请用户确认 `tracked_docs`
 2. JSON 解析失败 → 报错退出，要求用户手动修复或删除
 3. `schema_version > 1` → 报错退出，提示技能版本过旧
 4. `last_sync_sha` 不是 40 字符十六进制且不为 `null` → 视为损坏，回退到首次运行
@@ -152,4 +152,4 @@
 - 不要手动编辑 `last_sync_sha`（除非在修复损坏状态）
 - 不要把敏感信息、机器信息、用户信息写入
 - 不要让 `total_syncs` 回退
-- 不要把 state 文件放回 workflow 资产目录——它属于项目 `.speculo/` 状态，不属于 framework 资产
+- 不要把 state 文件放回 workflow 资产目录——它属于项目 `speculo/.speculo/` 状态，不属于 framework 资产