@namewta/speculo 0.1.7 → 0.1.9

package/{speculo → template}/skills/speculo-retro/SKILL.md

@@ -23,9 +23,9 @@ description: 复盘 Speculo commands/workflows 使用过程中的痛点、问题
 ## 输入
 
 - 当前对话上下文：本次会话用了哪些 command / workflow、卡在哪、绕了什么弯、重复了哪些动作
-- `.speculo/commands/<run>/` 下的历史命令产物（report、snapshot、handoff）
-- `.speculo/<cat>/<change>/` 下的 change 产物与 `.status.json`（`phase_history` 里的 `revisited`、`blocked`、长时间停滞都是摩擦信号）
-- `.speculo/.config/LESSONS.md`（已沉淀的教训，用于去重与佐证）
+- `speculo/.speculo/commands/<run>/` 下的历史命令产物（report、snapshot、handoff）
+- `speculo/.speculo/<cat>/<change>/` 下的 change 产物与 `.status.json`（`phase_history` 里的 `revisited`、`blocked`、长时间停滞都是摩擦信号）
+- `speculo/.speculo/.config/LESSONS.md`（已沉淀的教训，用于去重与佐证）
 - 可选：调用方提供的已存在 issue 列表或目标仓库上下文，用于跨提案去重
 - 本 skill 自带分析与 issue 起草规范，已内化到 `references/`，分析时**不外读仓库 `docs/`**
 
@@ -35,11 +35,11 @@ description: 复盘 Speculo commands/workflows 使用过程中的痛点、问题
 - 提案清单，按优先级倒序排列
 - 被合并或丢弃的低信号项说明（哪些重复、哪些更适合记入 `LESSONS.md` 而非提 issue）
 - 每条标注「建议提 issue」或「仅记教训」的处置建议
-- 全部以**返回内容**形式交给调用方写入其声明的 `.speculo/...` 路径；本 skill 不挑选持久化位置
+- 全部以**返回内容**形式交给调用方写入其声明的 `speculo/.speculo/...` 路径；本 skill 不挑选持久化位置
 
 ## 执行步骤
 
-1. **收集信号** —— 按 `references/friction-taxonomy.md` 的来源清单，扫描对话上下文、`.speculo/` 产物与 `LESSONS.md`，列出原始摩擦点。
+1. **收集信号** —— 按 `references/friction-taxonomy.md` 的来源清单，扫描对话上下文、`speculo/.speculo/` 产物与 `LESSONS.md`，列出原始摩擦点。
 2. **归类与去重** —— 按 taxonomy 把每个摩擦点归到类型（bug / friction / missing-capability / doc-gap / ergonomics），合并语义重复项。
 3. **深度分析** —— 对每条做根因判断（是 asset 设计、持久化契约、文档还是工具问题），评估影响面与发生频率，按 `references/friction-taxonomy.md` 的优先级评分。
 4. **过滤噪声** —— 只保留高信号、可行动项；低信号或一次性项标注为丢弃，或归入「仅记教训」。

package/{speculo → template}/skills/speculo-retro/references/friction-taxonomy.md

@@ -7,14 +7,14 @@
 按以下顺序采集原始摩擦点，每条记录**证据出处**（文件路径或对话节点），后续起草 issue 时要引用：
 
 1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
-2. **命令产物** —— `.speculo/commands/<run>/` 下的 `report.md`、`snapshot.md`、`handoff.md`：里面记录的「验证失败原因」「未完成」「阻塞点」是一手摩擦。
-3. **change 状态机** —— `.speculo/<cat>/<change>/.status.json` 的 `phase_history`：
+2. **命令产物** —— `speculo/.speculo/commands/<run>/` 下的 `report.md`、`snapshot.md`、`handoff.md`：里面记录的「验证失败原因」「未完成」「阻塞点」是一手摩擦。
+3. **change 状态机** —— `speculo/.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`：已记录但尚未转成改进项的教训，用于去重与佐证频率。
+5. **沉淀教训** —— `speculo/.speculo/.config/LESSONS.md`：已记录但尚未转成改进项的教训，用于去重与佐证频率。
 6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离 `persistence-contract`：路径散落、缺字段、命名不合 `YYYY-MM-DD-<kebab>` 都是 bug 信号。
 
 ## 摩擦类型分类

package/{speculo → template}/skills/speculo-retro/references/issue-drafting-sop.md

@@ -14,7 +14,7 @@
   "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"],
+  "evidence":     ["证据出处，例 speculo/.speculo/dev/<change>/.status.json#phase_history"],
   "disposition":  "file-issue | record-lesson | drop",
   "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
 }
@@ -49,7 +49,7 @@
 [一句话说清痛点 / 不符合预期的行为。]
 
 ## 证据
-[引用具体出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
+[引用具体出处：对话节点、`speculo/.speculo/...` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
 
 ## 根因
 [判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
@@ -74,4 +74,4 @@
 
 ## 交接契约
 
-本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `.speculo/commands/<run>/report.md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。
+本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `speculo/.speculo/commands/<run>/report.md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。

package/{speculo → template}/skills/speculo-write/SKILL.md

@@ -9,7 +9,7 @@ description: 创建或改造 Speculo workflows、skills、commands 的原子能
 
 ## 何时使用
 
-当任务是新增、迁移、融合或改造 Speculo 的 `workflows/`、`skills/`、`commands/`、配套模板、引用资料或 `.speculo/` 状态骨架时使用。
+当任务是新增、迁移、融合或改造 Speculo 的 `workflows/`、`skills/`、`commands/`、配套模板、引用资料或 `speculo/.speculo/` 状态骨架时使用。
 
 典型触发：
 
@@ -21,7 +21,7 @@ description: 创建或改造 Speculo workflows、skills、commands 的原子能
 ## 输入
 
 - 用户目标、成功标准、目标受众、约束和参考项目路径
-- 现有同类资产：`speculo/workflows/<cat>/`、`speculo/skills/`、`speculo/commands/`
+- 现有同类资产：`template/workflows/<cat>/`、`template/skills/`、`template/commands/`
 - 外部源材料：旧技能、参考 workflow、临时目录、README 索引、脚本、模板
 
 本 skill 自带全部 Speculo 规范，已内化到下方 `references/`，**编写时不外读仓库 `docs/`**。
@@ -30,7 +30,7 @@ description: 创建或改造 Speculo workflows、skills、commands 的原子能
 
 - 合规的 Speculo workflow、skill 或 command 资产
 - 必要的 `references/`、workflow phase 文件、workflow `_templates/` 或 command 内联模板
-- 必要的 `.speculo/` 初始骨架或状态索引更新建议
+- 必要的 `speculo/.speculo/` 初始骨架或状态索引更新建议
 - 文档、测试和残留路径检查清单
 
 ## 执行步骤
@@ -50,4 +50,4 @@ description: 创建或改造 Speculo workflows、skills、commands 的原子能
 - `references/command-authoring-sop.md`：创建单步 command、调用 skill、设计归档产物时读取。
 - `references/persistence-contract-sop.md`：需要 `.status.json` schema、目录命名、frontmatter 最小集或写入责任时读取。
 - `references/migration-sop.md`：从 `temp/skills`、参考项目或旧 workflow 迁移能力时读取。
-- `references/validation-checklist.md`：提交前检查 frontmatter、路径、模板、`.speculo/`、测试和旧路径残留时读取。
+- `references/validation-checklist.md`：提交前检查 frontmatter、路径、模板、`speculo/.speculo/`、测试和旧路径残留时读取。

package/{speculo → template}/skills/speculo-write/references/asset-selection-sop.md

@@ -11,7 +11,7 @@
 选择 workflow，当能力满足任一条件：
 
 - 多阶段交付，需要 phase 文件、产物模板和 `.status.json`
-- 产物属于一次 change，需要写 `.speculo/<cat>/<change>/`
+- 产物属于一次 change，需要写 `speculo/.speculo/<cat>/<change>/`
 - 会跨多轮对话推进，或需要 `current_phase`、`phase_history`
 - 是业务流程、开发流程、文档流程或运维流程
 
@@ -28,7 +28,7 @@
 - 是 command 或 workflow 可复用的原子能力
 - 复制到其他项目仍能工作
 - 需要 `references/` 渐进披露
-- 不拥有独立持久化根目录；文件型持久化由调用方提供 `.speculo/...` 目标路径，或返回内容给调用方写入
+- 不拥有独立持久化根目录；文件型持久化由调用方提供 `speculo/.speculo/...` 目标路径，或返回内容给调用方写入
 - 是工具集成、领域知识、决策 SOP 或可复用操作手册
 
 ### 做 Command
@@ -37,7 +37,7 @@
 
 - 单步动作或短流程
 - 不需要 phase 状态机
-- 产物只归档到 `.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
+- 产物只归档到 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
 - 可以调用 skill，但不需要 workflow 的 change 生命周期
 
 ### 做组合
@@ -49,7 +49,7 @@
 ## 反例
 
 - 不要把多阶段、有状态的流程塞进 skill。
-- 不要让 skill 自行选择 `.speculo/`、`temp/`、系统临时目录或项目根目录作为持久化位置。
+- 不要让 skill 自行选择 `speculo/.speculo/`、`temp/`、系统临时目录或项目根目录作为持久化位置。
 - 不要为一次性命令创建 workflow。
 - 不要把 workflow-only 方法保留为根 skill，除非会被多个入口复用。
 

package/{speculo → template}/skills/speculo-write/references/command-authoring-sop.md

@@ -5,7 +5,7 @@
 command 是单个 Markdown 文件：
 
 ```text
-speculo/commands/<name>.md
+template/commands/<name>.md
 ```
 
 只要需要多阶段状态机、多个子规范或跨天交付，就升级为 workflow。
@@ -36,10 +36,10 @@ command 正文包含：
 产物路径默认：
 
 ```text
-.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/
+speculo/.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 规范位置。
+在 command 文件中写路径时，使用 `speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`。命令产物禁止写入 `temp/`、系统临时目录、项目根目录或其它非 Speculo 规范位置。
 
 ## 调用 Skill
 
@@ -90,7 +90,7 @@ command 产物模板内联在文件末尾。模板占位符使用 `[TODO: ...]`
 - README 内置入口列表
 - CLI tests 是否需要断言复制该 command
 - 是否需要新增 command 调用的 skill
-- 归档路径是否位于 `.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`
+- 归档路径是否位于 `speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`
 - 被调用 skill 是否没有自选 `temp/`、系统临时目录或项目根目录作为持久化位置
 
-`.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`。
+`speculo/.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`。

package/{speculo → template}/skills/speculo-write/references/migration-sop.md

@@ -36,12 +36,12 @@
 
 把旧路径改成当前 Speculo 路径：
 
-- change 产物：`.speculo/<cat>/<change>/`
-- command 产物：`.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
-- 项目规则：`.speculo/.config/RULES.md`
-- 项目经验：`.speculo/.config/LESSONS.md`
-- 项目上下文：`.speculo/.config/context/`
-- 项目 ADR：`.speculo/.config/adr/`
+- change 产物：`speculo/.speculo/<cat>/<change>/`
+- command 产物：`speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
+- 项目规则：`speculo/.speculo/.config/RULES.md`
+- 项目经验：`speculo/.speculo/.config/LESSONS.md`
+- 项目上下文：`speculo/.speculo/.config/context/`
+- 项目 ADR：`speculo/.speculo/.config/adr/`
 
 不要创建新的项目根 state 文件，除非当前规范明确允许。
 
@@ -85,8 +85,8 @@
 迁移完成后同步：
 
 - 分类 `00-INDEX.md`
-- `.speculo/<cat>-status.json` 初始骨架
-- `.speculo/archive/<cat>/.gitkeep`
+- `speculo/.speculo/<cat>-status.json` 初始骨架
+- `speculo/.speculo/archive/<cat>/.gitkeep`
 - 项目若有 docs quick reference / architecture / adopting 等索引，按需更新
 - CLI tests 的 asset copying 断言
 

package/{speculo → template}/skills/speculo-write/references/persistence-contract-sop.md

@@ -3,6 +3,15 @@
 `.status.json` schema、目录命名、frontmatter 最小集与写入责任的内化规范。
 本文把 Speculo 持久化契约内化进本 skill，编写资产时**不读仓库 `docs/`**。
 
+> # ⚠️ 持久化铁律
+>
+> **Speculo 框架的所有运行时产物，必须且只能存放在 `speculo/.speculo/` 目录中。**
+>
+> - Workflow 产物 → `speculo/.speculo/<cat>/<change>/`
+> - Command 产物 → `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
+> - Skill **不自行持久化** → 由调用方写入 `speculo/.speculo/...` 或返回内容
+> - **绝对禁止** → `temp/`、系统临时目录、项目根目录的裸 `.speculo/`
+
 ## 命名铁律
 
 > ⚠️ **所有 change 目录、command 产物目录、归档路径必须以 `YYYY-MM-DD-` 开头。无一例外。**
@@ -53,11 +62,11 @@
 
 `<cat>` 只能是 `dev`、`doc`、`ops`。
 
-命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
+命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
 
 ## `.status.json` 元字段（框架强制）
 
-每个 change 的状态写在 `.speculo/<cat>/<change>/.status.json`：
+每个 change 的状态写在 `speculo/.speculo/<cat>/<change>/.status.json`：
 
 ```jsonc
 {
@@ -84,7 +93,7 @@ workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行
 ## 顶层索引 schema（薄）
 
 ```jsonc
-// .speculo/<cat>-status.json
+// speculo/.speculo/<cat>-status.json
 {
   "active": [
     { "name": "string", "current_phase": "string", "updated_at": "string, ISO 8601" }
@@ -93,7 +102,7 @@ workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行
 ```
 
 - 归档后变更**必须从 active 段移除**。
-- 索引可重建：扫 `.speculo/<cat>/*/.status.json` 即可重建。
+- 索引可重建：扫 `speculo/.speculo/<cat>/*/.status.json` 即可重建。
 - 全局 `STATUS.json` **不物理存在**。
 
 ## Frontmatter 最小集
@@ -145,27 +154,27 @@ description: <一句话>    # 必填
 
 | 文件 | 用户可写 | AI 可写 |
 |------|---------|---------|
-| `.speculo/.config/RULES.md` | ✅ | ❌ |
-| `.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 需要生成持久化文件时，必须使用调用方 command / workflow 声明的 `.speculo/...` 规范目标路径，或返回内容由调用方写入。禁止 skill 自行选择 `temp/`、系统临时目录、项目根目录或额外 state 文件作为持久化位置。
+| `speculo/.speculo/.config/RULES.md` | ✅ | ❌ |
+| `speculo/.speculo/.config/LESSONS.md` | ⚠️ 可追加 | ✅ workflow 末尾追加 |
+| `speculo/.speculo/.config/context/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
+| `speculo/.speculo/.config/adr/*` | ⚠️ 用户确认后 | ✅ 仅在用户确认后写入 |
+| `speculo/.speculo/commands/<command-run>/*` | ⚠️ | ✅ command 按内联模板写入 |
+| `speculo/.speculo/<cat>/<change>/*.md` | ⚠️ | ✅ |
+| `speculo/.speculo/<cat>/<change>/.status.json` | ❌ | ✅ |
+| `speculo/.speculo/*-status.json` | ❌ | ✅ |
+| `speculo/.speculo/dev/docs-sync-state.json` | ❌ | ✅ `dev/D-docs-sync` 原子写入 |
+
+**skill 不拥有独立持久化根目录**：skill 需要生成持久化文件时，必须使用调用方 command / workflow 声明的 `speculo/.speculo/...` 规范目标路径，或返回内容由调用方写入。禁止 skill 自行选择 `temp/`、系统临时目录、项目根目录或额外 state 文件作为持久化位置。
 
 ## 新分类骨架
 
 新增 `<cat>` 分类时初始化：
 
-- `.speculo/<cat>-status.json`（`{ "active": [] }`）
-- `.speculo/<cat>/.gitkeep`
-- `.speculo/archive/<cat>/.gitkeep`
+- `speculo/.speculo/<cat>-status.json`（`{ "active": [] }`）
+- `speculo/.speculo/<cat>/.gitkeep`
+- `speculo/.speculo/archive/<cat>/.gitkeep`
 
-项目级长期资料放 `.speculo/.config/`（`RULES.md`、`LESSONS.md`、`context/`、`adr/`），不要新增项目根 state 文件。
+项目级长期资料放 `speculo/.speculo/.config/`（`RULES.md`、`LESSONS.md`、`context/`、`adr/`），不要新增项目根 state 文件。
 
 ## 命名校验清单
 

package/{speculo → template}/skills/speculo-write/references/skill-authoring-sop.md

@@ -27,7 +27,7 @@
 skill 放在：
 
 ```text
-speculo/skills/<name>/SKILL.md
+template/skills/<name>/SKILL.md
 ```
 
 目录名用 lowercase kebab-case。整个 skill 目录必须**自包含**：复制到任何项目、只读 `SKILL.md` 即可判断是否使用、需要哪些输入、产生什么输出，不依赖本仓库的 `docs/` 或任何外部文件。
@@ -173,16 +173,16 @@ reference 文件用 kebab-case，**按任务而非来源**命名（`workflow-aut
 
 skill **禁止自行选择**持久化位置，包括：
 
-- `.speculo/<cat>/<change>/`
-- `.speculo/commands/`
-- `.speculo/*-status.json`
+- `speculo/.speculo/<cat>/<change>/`
+- `speculo/.speculo/commands/`
+- `speculo/.speculo/*-status.json`
 - `.status.json`
 - `temp/`、系统临时目录或项目根目录
 
 如果某能力需要生成文件型持久化产物，必须满足其一：
 
 - 调用方 workflow / command 声明规范目标路径，skill 只写入该路径。
-- skill 返回内容、摘要和建议文件名，由调用方写入 `.speculo/...`。
+- skill 返回内容、摘要和建议文件名，由调用方写入 `speculo/.speculo/...`。
 
 无论哪种方式，持久化产物都不得落到 `temp/`、系统临时目录、项目根目录或其它非 Speculo 规范位置。完整写入责任表见 `persistence-contract-sop.md`。
 
@@ -195,7 +195,7 @@ skill **禁止自行选择**持久化位置，包括：
 - [ ] `SKILL.md` 含五个固定章节，整体精简（细节已外移）
 - [ ] reference 单层引用，按任务命名
 - [ ] **自包含**：不引用 `docs/` 或仓库外文件
-- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `.speculo/...` 路径
+- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `speculo/.speculo/...` 路径
 - [ ] 没有 README / INSTALLATION / CHANGELOG 等冗余文件
 - [ ] 没有时效性信息、旧项目路径、旧工具名或绝对路径绑定
 - [ ] 术语一致、含具体示例、引用只有一层深度

package/{speculo → template}/skills/speculo-write/references/validation-checklist.md

@@ -2,7 +2,7 @@
 
 ## 结构检查
 
-- [ ] 新 asset 路径符合 `speculo/workflows/`、`speculo/skills/` 或 `speculo/commands/` 约定
+- [ ] 新 asset 路径符合 `template/workflows/`、`template/skills/` 或 `template/commands/` 约定
 - [ ] workflow 入口文件名与目录名一致
 - [ ] skill 入口命名为 `SKILL.md`
 - [ ] command 是单个 `.md` 文件
@@ -33,24 +33,24 @@
 - [ ] 输入、输出、执行步骤清晰
 - [ ] 大段细节放入 `references/`
 - [ ] 自包含：不引用 `docs/` 或仓库外文件，复制后只读 `SKILL.md` 即可用
-- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `.speculo/...` 路径
-- [ ] 如果需要持久化，明确归档到 `.speculo/commands/`、`.speculo/<cat>/<change>/` 或 `.speculo/.config/` 的哪类规范位置
+- [ ] skill 没有自选持久化目录；文件型产物由调用方写入或写入调用方声明的 `speculo/.speculo/...` 路径
+- [ ] 如果需要持久化，明确归档到 `speculo/.speculo/commands/`、`speculo/.speculo/<cat>/<change>/` 或 `speculo/.speculo/.config/` 的哪类规范位置
 
 ## Command 检查
 
-- [ ] 归档路径位于 `.speculo/commands/`
+- [ ] 归档路径位于 `speculo/.speculo/commands/`
 - [ ] 调用 skill 使用相对路径
 - [ ] 被调用 skill 没有把持久化产物写到 `temp/`、系统临时目录或项目根目录
 - [ ] 破坏性操作要求用户确认
 - [ ] 产物模板内联且使用 `[TODO: ...]`
 
-## `.speculo/` 检查
+## `speculo/.speculo/` 检查
 
-- [ ] 新分类有 `.speculo/<cat>-status.json`
-- [ ] 新分类有 `.speculo/<cat>/.gitkeep`
-- [ ] 新分类有 `.speculo/archive/<cat>/.gitkeep`
-- [ ] 项目级长期上下文写入 `.speculo/.config/context/`
-- [ ] 项目级 ADR 写入 `.speculo/.config/adr/`
+- [ ] 新分类有 `speculo/.speculo/<cat>-status.json`
+- [ ] 新分类有 `speculo/.speculo/<cat>/.gitkeep`
+- [ ] 新分类有 `speculo/.speculo/archive/<cat>/.gitkeep`
+- [ ] 项目级长期上下文写入 `speculo/.speculo/.config/context/`
+- [ ] 项目级 ADR 写入 `speculo/.speculo/.config/adr/`
 - [ ] 没有新增项目根 state 文件
 
 ## 文档与测试

package/{speculo → template}/skills/speculo-write/references/workflow-authoring-sop.md

@@ -2,12 +2,12 @@
 
 ## 入口结构
 
-workflow 放在 `speculo/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`ops`。
+workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`ops`。
 
 目录和入口文件必须同名：
 
 ```text
-speculo/workflows/<cat>/<entry>/<entry>.md
+template/workflows/<cat>/<entry>/<entry>.md
 ```
 
 主线 workflow 使用数字前缀，如 `01-grill-with-docs`。横向 workflow 使用字母前缀，如 `H-diagnose`、`R-review`、`D-docs-sync`。
@@ -61,7 +61,7 @@ phase 文件只放该阶段执行所需内容，不重复入口文件的全局
 模板放在：
 
 ```text
-speculo/workflows/<cat>/_templates/
+template/workflows/<cat>/_templates/
 ```
 
 命名：
@@ -84,28 +84,28 @@ speculo/workflows/<cat>/_templates/
 workflow 产物写入：
 
 ```text
-.speculo/<cat>/<change>/
+speculo/.speculo/<cat>/<change>/
 ```
 
 当前 change 的状态写入：
 
 ```text
-.speculo/<cat>/<change>/.status.json
+speculo/.speculo/<cat>/<change>/.status.json
 ```
 
 顶层 active 索引写入：
 
 ```text
-.speculo/<cat>-status.json
+speculo/.speculo/<cat>-status.json
 ```
 
 项目级规则、经验、上下文和 ADR 使用：
 
 ```text
-.speculo/.config/RULES.md
-.speculo/.config/LESSONS.md
-.speculo/.config/context/
-.speculo/.config/adr/
+speculo/.speculo/.config/RULES.md
+speculo/.speculo/.config/LESSONS.md
+speculo/.speculo/.config/context/
+speculo/.speculo/.config/adr/
 ```
 
 不要把新状态放到项目根目录。`.status.json` 元字段、顶层索引 schema 和写入责任表见 `persistence-contract-sop.md`。
@@ -115,8 +115,8 @@ workflow 产物写入：
 新增 workflow 后检查：
 
 - 对应分类的 `00-INDEX.md` 是否需要新增别名
-- `.speculo/<cat>-status.json` 和 `.speculo/<cat>/.gitkeep` 是否存在
-- `.speculo/archive/<cat>/.gitkeep` 是否存在
+- `speculo/.speculo/<cat>-status.json` 和 `speculo/.speculo/<cat>/.gitkeep` 是否存在
+- `speculo/.speculo/archive/<cat>/.gitkeep` 是否存在
 - 项目若有 `docs/quick-reference.md` 等入口索引，是否需要新增条目
 - CLI tests 是否需要断言复制新入口
 

package/{speculo → template}/skills/worktree-isolation/SKILL.md

@@ -43,10 +43,10 @@ description: 在独立 git worktree 中隔离推进一个 change 的原子能力
 
 ## 执行步骤
 
-1. **判定可隔离性**：确认 (a) 在 git 仓库内，(b) 工作区干净或变更可接受，(c) 目标项目 `.speculo/` 被 git 跟踪（产物需随分支合并）。任一不满足 → **不创建**，向调用方报告原因并降级为非 worktree 模式。
+1. **判定可隔离性**：确认 (a) 在 git 仓库内，(b) 工作区干净或变更可接受，(c) 目标项目 `speculo/.speculo/` 被 git 跟踪（产物需随分支合并）。任一不满足 → **不创建**，向调用方报告原因并降级为非 worktree 模式。
 2. **命名**：base = 当前分支；`change_branch = speculo/<cat>/<change>`；`worktree_path = .worktree/<change>`。
 3. **创建**：见 `references/create-worktree.md`。完成后返回 `base_branch / change_branch / worktree_path` 与 `worktree_status: active` 供调用方写入。
-4. **隔离推进**：此后该 change 的全部工作（代码 + `.speculo/<cat>/<change>/` 产物）都在 `worktree_path` 内、`change_branch` 上进行。
+4. **隔离推进**：此后该 change 的全部工作（代码 + `speculo/.speculo/<cat>/<change>/` 产物）都在 `worktree_path` 内、`change_branch` 上进行。
 5. **审查全树**（review 时）：见 `references/audit-branch-tree.md`，覆盖 `base..change_branch` 的每个 commit。
 6. **合并回收**（finalize 时）：见 `references/merge-and-cleanup.md`，合并回 base、删分支、删 worktree。
 

package/{speculo → template}/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/<cat>/<change>/.status.json`。
+- 不自行选择持久化目录；审查字段由调用方写入 `speculo/.speculo/<cat>/<change>/.status.json`。

package/{speculo → template}/skills/worktree-isolation/references/create-worktree.md

@@ -5,7 +5,7 @@
 ## 前置
 
 1. 在 git 仓库内，工作区干净或变更可接受。
-2. 目标项目 `.speculo/` 被 git 跟踪——隔离模型要求 change 产物随分支合并回 base。若 `.speculo/` 被 `.gitignore` 忽略，**不隔离**，报告原因并降级。
+2. 目标项目 `speculo/.speculo/` 被 git 跟踪——隔离模型要求 change 产物随分支合并回 base。若 `speculo/.speculo/` 被 `.gitignore` 忽略，**不隔离**，报告原因并降级。
 3. 确保 `.gitignore` 含 `.worktree/`；缺失则提示调用方补上（worktree 工作树不应被 base 分支跟踪）。
 
 ## 命名
@@ -24,7 +24,7 @@
    git worktree add -b speculo/<cat>/<change> .worktree/<change>
    ```
 
-4. 在工作树内初始化该 change 的 Speculo 产物目录 `.speculo/<cat>/<change>/` 与 `.status.json`（由调用方按持久化契约写入）。
+4. 在工作树内初始化该 change 的 Speculo 产物目录 `speculo/.speculo/<cat>/<change>/` 与 `.status.json`（由调用方按持久化契约写入）。
 5. 提示调用方：此后所有工作在 `.worktree/<change>/` 内、`speculo/<cat>/<change>` 分支上进行。
 
 ## 返回给调用方
@@ -34,6 +34,6 @@
 
 ## 边界
 
-- 不自行选择持久化目录；字段值返回给调用方 workflow 写入 `.speculo/<cat>/<change>/.status.json`。
+- 不自行选择持久化目录；字段值返回给调用方 workflow 写入 `speculo/.speculo/<cat>/<change>/.status.json`。
 - 分支或工作树已存在时不覆盖、不复用，停止报告。
-- 非 git 仓库 / 工作区不可用 / `.speculo/` 未被跟踪时降级为非 worktree 模式。
+- 非 git 仓库 / 工作区不可用 / `speculo/.speculo/` 未被跟踪时降级为非 worktree 模式。

package/{speculo → template}/skills/worktree-isolation/references/merge-and-cleanup.md

@@ -19,7 +19,7 @@ finalize 验证通过后，把 change 分支合并回原分支并清理 worktree
    ```
 
    - 合并冲突 → **停止**，报告冲突文件，交回用户解决，不强推、不 `--force`。
-   - 合并成功 → 置 `worktree_status: merged`。合并后 base 分支已包含代码与 `.speculo/<cat>/<change>/` 产物。
+   - 合并成功 → 置 `worktree_status: merged`。合并后 base 分支已包含代码与 `speculo/.speculo/<cat>/<change>/` 产物。
 3. **清理工作树与分支**：
 
    ```bash
@@ -40,4 +40,4 @@ finalize 验证通过后，把 change 分支合并回原分支并清理 worktree
 
 - `verification_status` 非 `verified` 不合并。
 - 未获用户确认不执行任何合并 / 删除 / 移除。
-- 不自行选择持久化目录；`worktree_status` 由调用方写入 `.speculo/<cat>/<change>/.status.json`。
+- 不自行选择持久化目录；`worktree_status` 由调用方写入 `speculo/.speculo/<cat>/<change>/.status.json`。

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

@@ -8,9 +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/` 或其他任何非规范位置。**
 
-> **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。详见 `../../docs/persistence-contract.md` §0。
+本文件是 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`，仅汇报不自动操作。
 
 ## 入口别名
 
@@ -27,10 +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 目录，**目录名必须为 `YYYY-MM-DD-<kebab-name>`**（使用当前日期，`<kebab-name>` 从用户意图提取），并初始化 `.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` 核对工作树是否存在。

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

@@ -19,14 +19,14 @@ 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>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-user-auth`）
+- `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 候选
 - 需要用户进一步决策的问题，每次只问一个
 
@@ -38,7 +38,7 @@ keywords: [grill, context, adr, 术语, 决策]
 
 每次只问一个问题，等待用户对当前问题的反馈后再继续。如果某个问题可以通过探索代码库来回答，就直接探索代码库。
 
-需要格式约定时读取同目录 `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 隔离（条件）
 
@@ -46,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 模式并报告，不强行创建。
 
 ## 阶段
 
@@ -73,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