@namewta/speculo 0.1.6 → 0.1.8

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/template/skills/speculo-write/references/persistence-contract-sop.md

@@ -0,0 +1,192 @@
+# Persistence Contract SOP
+
+`.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-` 开头。无一例外。**
+
+不带日期的目录名是**无效的**。
+
+### 谁必须带日期
+
+| 必须带 | 规则 | 谁创建 |
+|--------|------|--------|
+| Change 目录 | `YYYY-MM-DD-<kebab-name>` | Workflow（AI 按用户意图创建） |
+| Command 产物目录 | `YYYY-MM-DD-<cmd-name>-<topic>` | Command（AI 执行命令时创建） |
+| 归档目标目录 | `archive/<cat>/<YYYY-MM>/<change-name>/` | `archive` 命令或 `dev/04` 工作流 |
+
+### 谁不需要带日期
+
+| 不需要带 | 原因 |
+|----------|------|
+| Workflow 阶段目录（如 `01-grill-with-docs/`） | 框架资产，非运行时产物 |
+| Skill 目录（如 `caveman/`） | 框架资产，非运行时产物 |
+| Command 文件（如 `archive.md`） | 框架资产，非运行时产物 |
+| 模板文件（`_templates/`） | 框架资产，非运行时产物 |
+| `.config/`、`adr/`、`context/` | 项目配置目录 |
+
+### 反例
+
+| ❌ 错误 | ✅ 正确 |
+|---------|---------|
+| `user-auth` | `2026-06-12-user-auth` |
+| `fix-bug` | `2026-06-12-fix-login-bug` |
+| `prd-draft` | `2026-06-12-prd-user-flow` |
+| `status-snapshot/` | `2026-06-12-status-snapshot/` |
+
+### AI 代理执行规则
+
+1. **创建 change 目录时**：必须从当前日期生成 `YYYY-MM-DD-<kebab-name>`，`<kebab-name>` 从用户意图提取。
+2. **创建 command 产物目录时**：必须从当前日期生成 `YYYY-MM-DD-<cmd-name>-<topic>`。
+3. **扫描已有 change 时**：不符合 `YYYY-MM-DD-<kebab-name>` 的目录视为 `malformed`，必须汇报用户。
+4. **归档时**：目标路径必须包含 `archive/<cat>/<YYYY-MM>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
+
+## 目录命名
+
+| 类别 | 模式 | 例 |
+|------|------|---|
+| Change 目录 | `YYYY-MM-DD-<kebab-name>` | `2026-05-28-user-auth` |
+| Command 产物目录 | `YYYY-MM-DD-<cmd-name>-<topic>` | `2026-05-28-debug-login-500` |
+| 归档目录 | `archive/<cat>/<YYYY-MM>/<change-name>/` | `archive/dev/2026-05/2026-05-20-payment-flow/` |
+
+`<cat>` 只能是 `dev`、`doc`、`ops`。
+
+命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
+
+## `.status.json` 元字段（框架强制）
+
+每个 change 的状态写在 `speculo/.speculo/<cat>/<change>/.status.json`：
+
+```jsonc
+{
+  "name":           "string, change 目录名",
+  "category":       "string, dev | doc | ops",
+  "change_status":  "string, active | completed | archived",
+  "execution_mode": "string, 由 workflow 自治声明的命名预设",
+  "created_at":     "string, ISO 8601",
+  "updated_at":     "string, ISO 8601",
+  "current_phase":  "string, 当前 phase id",
+  "phase_history": [
+    {
+      "phase":        "string, phase id",
+      "entered_at":   "string, ISO 8601",
+      "completed_at": "string|null, ISO 8601",
+      "status":       "string, pending | in-progress | completed | skipped | revisited"
+    }
+  ]
+}
+```
+
+workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行者写入**同一份** `.status.json`，不另开文件。
+
+## 顶层索引 schema（薄）
+
+```jsonc
+// speculo/.speculo/<cat>-status.json
+{
+  "active": [
+    { "name": "string", "current_phase": "string", "updated_at": "string, ISO 8601" }
+  ]
+}
+```
+
+- 归档后变更**必须从 active 段移除**。
+- 索引可重建：扫 `speculo/.speculo/<cat>/*/.status.json` 即可重建。
+- 全局 `STATUS.json` **不物理存在**。
+
+## Frontmatter 最小集
+
+Frontmatter **仅承载发现元数据**（这是什么、叫什么、关于什么）。phases / 模板 / 依赖 / 调用 skill / 状态扩展字段 / 入口协议一律写进 Markdown 正文，用相对路径链接与小标题做渐进披露。
+
+```yaml
+# workflow
+id: <category>/<name>   # 必填，全局唯一
+category: dev|doc|ops   # 必填
+name: <人类可读名>       # 必填
+description: <一句话>    # 必填
+keywords: [...]         # 可选
+
+# command
+id: <name>              # 必填，唯一
+type: command           # 必填，固定值
+name: <人类可读名>       # 必填
+description: <一句话>    # 必填
+keywords: [...]         # 可选
+
+# skill
+id: <name>              # 必填，唯一
+type: skill             # 必填，固定值
+name: <人类可读名>       # 必填
+description: <一句话>    # 必填
+```
+
+## Template 不需要 Frontmatter
+
+模板顶部用一段引用说明声明归属，占位符一律 `[TODO: ...]`：
+
+```markdown
+> **服务工作流：** `<相对路径>`
+> **产物文件名：** `<filename>`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
+
+# <标题>
+
+## <章节>
+[TODO: 具体填写指引]
+```
+
+## 相对路径强约束
+
+正文引用的 skill / template / 其它 workflow / phase 子文档**必须用相对路径**，禁止裸 id 或绝对路径。
+
+## 写入责任
+
+| 文件 | 用户可写 | AI 可写 |
+|------|---------|---------|
+| `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/.speculo/<cat>-status.json`（`{ "active": [] }`）
+- `speculo/.speculo/<cat>/.gitkeep`
+- `speculo/.speculo/archive/<cat>/.gitkeep`
+
+项目级长期资料放 `speculo/.speculo/.config/`（`RULES.md`、`LESSONS.md`、`context/`、`adr/`），不要新增项目根 state 文件。
+
+## 命名校验清单
+
+### 创建时
+
+- [ ] change 目录名匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`
+- [ ] command 产物目录名匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$`
+- [ ] 日期部分使用**当前日期**（`YYYY-MM-DD`）
+- [ ] `<kebab-name>` 从用户意图中提取
+
+### 扫描时
+
+- [ ] 仅处理符合日期命名规范的目录
+- [ ] 不符合规范的目录标记为 `malformed`，必须汇报
+- [ ] 不自动删除、重命名或忽略 malformed 目录

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`。