@namewta/speculo 0.2.1 → 0.2.3

package/README.md

@@ -67,14 +67,16 @@ After initialization, the target project gains the following AI agent-callable a
 
 ### 2 Workflow Packages
 
-| Workflow | Routes | Description |
-|---|---|---|
-| **matt-pocock** | 10 | Route-first composition of Matt Pocock native skills (engineering + productivity) |
-| **person** | 1 | Persona-methodology-based consulting workflow |
+| Workflow | Routes | Atomic coverage | Description |
+|---|---:|---|---|
+| **matt-pocock** | 10 | Complete vendor inventory | Route composition plus one-to-one access to every stable and experimental Matt Pocock SKILL |
+| **person** | 1 | None | Persona-methodology-based consulting workflow without synthetic skill wrappers |
+
+Every workflow ships a peer `PERSISTENCE.md` as its sole runtime contract. `WORKFLOW.md` and each `atomic-skills/<id>.md` entry load it first, so composed routes and direct atomic calls resolve the same state root, active change, namespaces, and confirmation boundaries.
 
 ### Vendor Skill Collections
 
-- **Matt Pocock skills** — Engineering (ask-matt, implement, wayfinder, tdd, code-review, diagnosing-bugs, prototyping, research, domain-modeling, codebase-design, triage, setup, to-spec, to-tickets, grill-with-docs, improve-codebase-architecture) and Productivity (grill-me, handoff, teach, writing-great-skills)
+- **Matt Pocock skills** — The complete stable and explicitly enabled `in-progress` inventory, preserved as read-only vendor sources behind workflow-owned atomic wrappers.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Workflow-packaged specification-driven development assets with install, update, and migration tooling.",
   "type": "module",
   "bin": {

package/template/.speculo/README.md

@@ -5,8 +5,8 @@
 ## 读取顺序
 
 1. 读取 `workspace.json`，以当前打开项目为 `project_root` 解析公共 roots。
-2. 读取 `../workflows/<workflow>/WORKFLOW.md` 的 `<runtime-context>` 与 `<persistence>`。
-3. 读取 `<workflow>/status.json`，再读取 `changes/<change>/.status.json` 和当前 route 产物。
+2. 从 `../workflows/<workflow>/WORKFLOW.md` 或 `atomic-skills/<id>.md` 进入，并首先读取同级 `PERSISTENCE.md` 的 `<runtime-context>`、`<persistence>` 与 change 启动协议。
+3. 读取 `<workflow>/status.json`，再读取 `changes/<change>/.status.json` 和当前 route/direct 产物。
 4. 历史 change 只从 `<workflow>/archive/YYYY-MM/<change>/` 读取。
 5. Command 报告位于 `commands/<command>/*.md`，command state 位于 `commands/<command>/state.json`。
 6. 首次 docs-sync 确认后读取 `<workflow>/docs-sync.json`；它分列该 workflow 的项目文档和私有 state 更新范围。
@@ -17,4 +17,4 @@
 - `docs-sync.json` 是 docs-sync command 拥有的延迟 sidecar，不进入 `_state`，也不授予越过 workflow 确认规则的权限。
 - `.config` 不是标准目录；只有 workflow 声明时才可使用。
 - Command 报告命名为 `<YYYY-MM-DD>-<scope>-<topic>[-NN].md`，禁止覆盖。
-- Skill 只使用调用方提供并完成边界校验的路径。
+- Atomic wrapper 可独立启动，但只使用 `PERSISTENCE.md` 解析并完成边界校验的路径；raw vendor SKILL 不直接选择持久化根。

package/template/commands/docs-sync.md

@@ -20,7 +20,7 @@ keywords: [docs-sync, readme, changelog, agents, documentation]
 
 1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/docs-sync/SKILL.md`，解析 command 路径、`speculo/config.json`（不存在时以默认值静默降级）和全部已安装 workflow/state 根。
 2. 按 skill 的 Git 契约检查 tracked、staged、unstaged 与 untracked 内容；安全且校验通过时显式暂存并创建 checkpoint，异常时无损阻塞。
-3. 读取全局 state、各 `WORKFLOW.md` 和 sidecar。首次运行统一展示全局与每个 workflow 的候选范围；用户确认后为所有已安装 workflow 创建 sidecar，空范围也保留。
+3. 读取全局 state、各 `WORKFLOW.md`、同级 `PERSISTENCE.md` 和 sidecar。首次运行统一展示全局与每个 workflow 的候选范围；用户确认后为所有已安装 workflow 创建 sidecar，空范围也保留。
 4. 由 skill 收集精确 commit 区间、archive 与声明 store 证据，整份审计命中文档并执行新增、更新、删除段落、合并或保留。整文件/目录删除和受保护知识仍逐次确认。
 5. 运行项目与文档校验，原子写入报告、state 和 sidecar，再显式暂存本次产物并创建同步或 no-op commit。
 6. 重新读取 Git、state、报告与 sidecar；只有工作区干净、节点可复现且所有文件已提交时完成。

package/template/commands/knowledge-prune.md

@@ -14,7 +14,7 @@ keywords: [knowledge, prune, rules, lessons, context, adr]
 
 ## 执行
 
-1. 读取 `../skills/runtime-context/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），选择 workflow 并解析其 `<persistence>` 声明的 knowledge/policy namespace。
+1. 读取 `../skills/runtime-context/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），选择 workflow 并解析其 `PERSISTENCE.md` 声明的 knowledge/policy namespace。
 2. 读取 `../skills/knowledge-prune/SKILL.md`，默认执行 dry-run，生成 `delete | merge | rewrite | keep | needs-confirmation` 清单。
 3. 将报告写入 command 专属目录；无用户确认时不删除、重命名或改写任何 namespace。
 4. 用户确认后再次执行路径包含检查，逐项操作并复查 git、引用和报告结果。

package/template/commands/retro.md

@@ -10,6 +10,8 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 ⚠️ **本命令在最后一步会通过 `gh` 向外部仓库创建 issue（外部写操作）。AI 必须先列出将要创建的 issue 清单与目标仓库并征求用户确认，确认前只输出计划，不调用 `gh`。**
 
+🔒 **目标仓库已写死：`NAMEWTA/Speculo`。** 本命令专为 Speculo 框架自身反馈而设计。不论 retro 在哪个项目仓库中被激活，issue 一律提交到 `NAMEWTA/Speculo`。不允许用户或 AI 覆盖此目标仓库。
+
 ## 归档路径模式
 
 报告文件：`speculo/.speculo/commands/retro/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`
@@ -25,13 +27,13 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 ## 执行步骤
 
-1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及 workflow 声明的 lessons/knowledge store。
+1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及各 `PERSISTENCE.md` 声明的 lessons/knowledge store。
 2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
 3. 创建 command 专属目录 `speculo/.speculo/commands/retro/`，把复盘结论写入带 scope 的 Markdown 报告。
-4. **解析目标仓库**：默认框架反馈上游 `NAMEWTA/Speculo`；用户在请求中显式指定其他 `owner/repo` 时覆盖默认。无论如何，在调用 `gh` 前回显解析到的 `owner/repo`，让用户确认或改正。
-5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
-6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标 `owner/repo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
-7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo <owner/repo> --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
+4. **目标仓库（写死，不可覆盖）**：本命令的 issue 目标仓库固定为 `NAMEWTA/Speculo`。无论 retro 在哪个项目仓库中被激活，`gh issue create` 的 `--repo` 参数一律使用 `NAMEWTA/Speculo`。用户和 AI 均不得指定其他仓库。
+5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo NAMEWTA/Speculo --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
+6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标仓库 `NAMEWTA/Speculo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
+7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo NAMEWTA/Speculo --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
 8. 把每条提案的最终 issue 编号/URL 回写进本次报告的「提交结果」小节；返回报告路径、3-5 条复盘摘要和已创建 issue 链接清单。
 
 ## 产物模板
@@ -64,10 +66,10 @@ generated_at: [TODO: ISO-8601]
 [TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
 
 ## 目标仓库
-[TODO: 解析到的 owner/repo 与用户确认结果。]
+`NAMEWTA/Speculo`（写死，不可覆盖）
 
 ## 用户确认记录
-[TODO: 记录用户对 issue 清单与目标仓库的确认原文摘要。]
+[TODO: 记录用户对 issue 清单的确认原文摘要。]
 
 ## 提交结果
 [TODO: 列出每条提案对应的 issue 编号/URL，或未提交原因（重复/失败/用户撤回）。]

package/template/skills/docs-sync/SKILL.md

@@ -16,7 +16,7 @@ description: 基于可复现 Git 区间、用户确认范围和 workflow 规则
 1. 读取 `references/git-state-contract.md`，清理并提交可验证的既有工作区改动，解析上次基线与本次输入节点。完成标准：输入工作区干净，或已无损阻塞。
 2. 读取 `references/workflow-scope-contract.md`，发现全部已安装 workflow，并解析全局范围与每个 workflow 的确认清单。完成标准：首次运行已统一确认范围，每个 workflow 状态根都有合法 sidecar。
 3. 读取 `references/document-lifecycle-contract.md`，把输入区间和 workflow 证据映射为 `add | update | delete | merge | keep | propose-only`。完成标准：每个受影响资产已整份审计，而非只追加新段落。
-4. 更新 README 时读取 `references/readme-contract.md`；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`。需要创建或重建多层代理手册树时改用 `../agents-md-builder/SKILL.md`。
+4. 更新 README 时读取 `references/readme-contract.md`（同步规则）与 `references/readme-writing-guide.md`（内容写作规范）；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`。需要创建或重建多层代理手册树时改用 `../agents-md-builder/SKILL.md`。
 5. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
 
 完成标准：项目文档与当前事实一致，过期和重复内容已删除或合并；报告可复现输入区间；state 与 sidecar 已提交；没有未确认的越权写入或遗留工作区改动。

package/template/skills/docs-sync/assets/report-template.md

@@ -30,7 +30,7 @@ generated_at: <ISO-8601>
 
 ## Workflow Sources
 
-[按 workflow 记录读取的 WORKFLOW、archive、声明 store 和受保护候选；空集合写 `[]`。]
+[按 workflow 记录读取的 WORKFLOW/PERSISTENCE、archive、声明 store 和受保护候选；空集合写 `[]`。]
 
 ## Synced Assets
 

package/template/skills/docs-sync/references/readme-contract.md

@@ -1,5 +1,7 @@
 # README 同步契约
 
+> **内容写作规范参见 [readme-writing-guide.md](./readme-writing-guide.md)。** 本契约定义 README 的同步规则、触发条件和多语言铁律；具体到九段式结构、每节写什么、怎么写，请使用写作指南。
+
 README 面向首次接触项目、正在判断是否采用以及准备立即试用的读者。保留项目既有语言和风格，不强塞不适用的标准章节。
 
 ## 事实顺序

package/template/skills/docs-sync/references/readme-writing-guide.md

@@ -0,0 +1,294 @@
+# README 写作指南
+
+README 面向首次接触项目的读者，需要在约 5 秒内回答三个问题：**这是什么、怎么用、值不值得用**。本指南定义 Speculo 项目的通用 README 结构与写作规范，供 `docs-sync` 及其他命令在生成或审计 README 时引用。
+
+> **同步规则参见 [readme-contract.md](./readme-contract.md)。** 本指南定义"写什么内容"（内容规范）；readme-contract.md 定义"何时同步、如何验证"（同步契约）。两者互补。
+
+## 九段式结构
+
+项目简单时合并相邻章节，README 很长时把 API、架构解释和贡献流程移到对应文档。以下九段覆盖从"吸引注意"到"引导参与"的完整认知漏斗。
+
+| # | 段落 | 用途 | 缺失后果 |
+|---|------|------|----------|
+| 1 | **Header** | 项目名 + 一句话定位 + 徽章栏 + 语言切换 | 读者不知道项目是否活跃、能否跨语言阅读 |
+| 2 | **About** | 价值主张 + 内容概览 + 独特卖点 | 读者无法快速判断项目是否解决他的问题 |
+| 3 | **Quick Start** | 前置条件 → 安装命令 → 预期输出 | 读者放弃尝试 |
+| 4 | **Project Structure** | ASCII 目录树 + 命名规范 | 读者不知道从哪里入手改代码 |
+| 5 | **How to Study / Use** | 分步学习或使用方法 | 读者不知道怎么消化内容 |
+| 6 | **Tech Stack** | 组件-包名-用途三列表 | 读者不知道需要什么依赖 |
+| 7 | **Contributing** | Fork → Branch → Convention → Test → PR | 潜在贡献者不知道流程而放弃 |
+| 8 | **License** | 类型 + LICENSE 文件链接 | 读者不确定能否合法使用 |
+| 9 | **Footer** | 社区链接 + 跨语言导航 | 读者不知道怎么联系或获取更多信息 |
+
+---
+
+### 1. Header
+
+**应包含：**
+- 项目名居中（`<h1 align="center">Project Name</h1>`）
+- 一句话 tagline —— 说明输入、输出或解决什么问题，删除空泛营销语
+- 徽章栏：License、语言版本、包管理器、Stars、PRs、CI 状态等
+- 语言切换链接：`[中文](./README-ZH.md)` ← → `[English](./README.md)`
+
+**不应包含：**
+- 超过一行的冗长描述（放到 About 段）
+- 失效或状态无价值的徽章
+
+**示例：**
+
+```markdown
+<h1 align="center">My Project</h1>
+<p align="center"><em>A one-line description of what it does.</em></p>
+<p align="center">
+  <a href="./README-ZH.md">中文</a>
+</p>
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
+  <img src="https://img.shields.io/badge/Python-3.10+-green.svg" alt="Python 3.10+">
+  <img src="https://img.shields.io/github/stars/owner/repo?style=flat" alt="Stars">
+</p>
+```
+
+---
+
+### 2. About
+
+**应包含：**
+- 一段清晰的价值主张：这个项目解决什么痛点、为谁解决
+- 内容/功能概览表（若为学习型仓库：模块列表；若为工具型：核心功能）
+- 1-3 个独特卖点（why this project over alternatives）
+
+**不应包含：**
+- 实现细节（放到项目结构或文档链接）
+- 安装步骤（放到 Quick Start）
+- 与其他项目逐行对比（冗长且容易过时）
+
+**示例（学习型仓库）：**
+
+```markdown
+## About
+
+My Project 是一套从零到生产就绪的 XYZ 学习路线，每个模块以"带注释的可运行脚本"而非教程形式呈现 — 代码即教材。
+
+| # | 模块 | 覆盖内容 |
+|---|------|----------|
+| 01 | Getting Started | 环境搭建、Hello World |
+| 02 | Core Concepts | 核心抽象与生命周期 |
+| ... | ... | ... |
+```
+
+---
+
+### 3. Quick Start
+
+**应包含：**
+- **前置条件**：运行时版本、系统依赖、必需的 API key 等
+- **一步安装命令**：`npx`、`git clone`、`pip install` 等，可复制粘贴
+- **预期输出**：读者执行后应该看到什么才算成功
+- 预计耗时在 60 秒以内
+
+**不应包含：**
+- 长篇背景解释
+- 多分支安装路径（初学者只需一条"最快路径"）
+
+**示例：**
+
+```markdown
+## Quick Start
+
+**前置条件：** Node.js >= 22、npm >= 10
+
+```bash
+npx my-package init
+```
+
+预期输出：
+
+```
+✔ Project initialized at ./my-project
+✔ 3 files created
+```
+```
+
+---
+
+### 4. Project Structure
+
+**应包含：**
+- ASCII 目录树（第一层级，不超过 2 层深度）
+- 关键命名规范说明（文件前缀、目录约定等）
+- 每个顶级目录的一句话用途
+
+**不应包含：**
+- 完整展开的文件树（冗长且随 commit 快速过时）
+- 每个文件的详细说明（放到各自模块的文档中）
+
+**示例：**
+
+```markdown
+## Project Structure
+
+```
+.
+├── src/            # 源代码
+├── tests/          # 测试（文件名 = test_<module>.py）
+├── docs/           # 详细文档
+├── scripts/        # 运维/CI 辅助脚本
+├── pyproject.toml  # 项目元数据与依赖
+└── README.md
+```
+
+命名规范：源文件使用 `snake_case.py`，测试文件使用 `test_` 前缀。
+```
+
+---
+
+### 5. How to Study / Use
+
+此节因项目类型而异：
+
+**学习型仓库：** 四步学习法
+```markdown
+## How to Study
+
+1. **选择模块** — 按编号顺序，每模块构建在前一模块之上
+2. **阅读注释** — 每个脚本包含详尽的中文注释，解释每行代码的"为什么"
+3. **运行脚本** — `python main-<NN>-<topic>.py`，观察输出
+4. **动手实验** — 修改参数、打破代码、修复它
+```
+
+**工具/库型仓库：**
+```markdown
+## Usage
+
+```python
+from mylib import Thing
+t = Thing(config)
+result = t.do("input")
+```
+
+详见 [docs/](./docs/)。
+```
+
+---
+
+### 6. Tech Stack
+
+**格式：** 组件-包名-用途三列表，按层或类别分组。
+
+**应包含：**
+- 核心运行时与框架
+- 关键依赖（用户需要知道的，不是全部 `node_modules`）
+
+**示例：**
+
+```markdown
+## Tech Stack
+
+| 组件 | 包名 | 用途 |
+|------|------|------|
+| Runtime | Python 3.10+ | 主运行环境 |
+| Package Manager | uv | 依赖管理与虚拟环境 |
+| LLM Framework | langchain | 大语言模型编排 |
+| Vector Store | chromadb | 嵌入式向量存储与检索 |
+```
+
+---
+
+### 7. Contributing
+
+**应包含：**
+- Fork → Branch → Convention → Test → PR 简洁流程
+- Commit 规范（如 Conventional Commits）
+- 在哪提 issue、讨论设计
+
+**不应包含：**
+- 完整的 CLA 法律文本（链接到 CONTRIBUTING.md）
+
+**示例：**
+
+```markdown
+## Contributing
+
+1. Fork 本仓库
+2. 从 `main` 分支创建功能分支：`git checkout -b feat/my-feature`
+3. 提交遵循 [Conventional Commits](https://www.conventionalcommits.org/)
+4. 确保现有测试通过并添加新测试
+5. 提交 PR 并描述改动原因
+
+欢迎提 issue 讨论新功能或报告 bug。
+```
+
+---
+
+### 8. License
+
+**格式：** 一句话 + LICENSE 文件链接。
+
+```markdown
+## License
+
+MIT © [Author] — 详见 [LICENSE](./LICENSE) 文件。
+```
+
+---
+
+### 9. Footer
+
+**应包含：**
+- 社区/联系链接（GitHub Discussions、Discord、Twitter 等）
+- 跨语言 README 跳转链接（与 Header 的徽章栏中的语言切换呼应）
+
+```markdown
+---
+
+<p align="center">
+  <a href="./README-ZH.md">中文文档</a>
+  &nbsp;·&nbsp;
+  <a href="https://github.com/owner/repo/discussions">Discussions</a>
+  &nbsp;·&nbsp;
+  <a href="https://github.com/owner/repo/issues">Report Bug</a>
+</p>
+```
+
+---
+
+## 双语言原则
+
+遵循 [readme-contract.md](./readme-contract.md) 中的铁律：
+
+- **`README.md` 始终为英文（EN）。** 与之配对的是 `README-ZH.md`，为一对一的中文翻译镜像。
+- 两文件顶部互相提供可点击跳转链接。
+- 结构完全对称，内容一一对应。标题顺序、命令、代码块、URL、表格字段保持对等；代码实体不翻译。
+- `README.md` 内容变更时，`README-ZH.md` 必须在同一次同步中完成对应更新。
+
+---
+
+## 与其他资产的关系
+
+| 资产 | 路径 | 关系 |
+|------|------|------|
+| readme-contract.md | `./readme-contract.md` | 同步规则与验证契约 —— 定义**何时更新**、触发条件、多语言铁律 |
+| document-lifecycle-contract.md | `./document-lifecycle-contract.md` | 文档生命周期 —— 定义**如何决定** add/update/delete/merge |
+| docs-sync SKILL.md | `../SKILL.md` | 编排 skill —— 调用本指南与 readme-contract.md 协同完成 README 审计 |
+| 项目文档创建与维护规范 | `temp/项目文档创建与维护规范.md` | 背景参考 —— 综合 50+ 来源的文档规范研究（非运行时依赖） |
+
+---
+
+## 验证清单
+
+生成或审计 README 时逐项检查：
+
+- [ ] Header 有项目名、tagline、徽章栏（至少 License + 语言版本）、语言切换链接
+- [ ] About 在 3 秒内回答"这个项目是做什么的"
+- [ ] Quick Start 可在 60 秒内完成并看到预期输出
+- [ ] 安装命令可复制粘贴执行
+- [ ] Project Structure 树与实际目录布局一致
+- [ ] Tech Stack 表与 `package.json` / `pyproject.toml` 等 manifest 文件中的核心依赖一致
+- [ ] Contributing 有可执行步骤
+- [ ] License 类型与实际 LICENSE 文件一致
+- [ ] Footer 有语言切换和社区链接
+- [ ] 无过期命令、路径、参数、徽章、链接
+- [ ] `README-ZH.md` 与 `README.md` 同步更新
+
+逐段删除测试：删掉后不影响采用决策或正确使用的内容应压缩、下沉或删除。

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -1,12 +1,12 @@
 # Workflow 范围契约
 
-docs-sync 必须遵循每个 workflow 的 `WORKFLOW.md`、持久化声明与确认规则。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
+docs-sync 必须遵循每个 workflow 的 `WORKFLOW.md` 与同级 `PERSISTENCE.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
 
 ## 发现
 
 1. 从 `speculo/workflows/*/WORKFLOW.md` 发现已安装 workflow。
 2. 每个包必须有匹配的 `speculo/.speculo/<workflow>/` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
-3. 读取 `<runtime-context>`、`<persistence>`、固定 archive 和所有 `consumers` 包含 `docs-sync` 的 store。
+3. 读取同级 `PERSISTENCE.md` 的 `<runtime-context>`、`<persistence>`、固定 archive 和所有 `consumers` 包含 `docs-sync` 的 store。
 4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
 
 ## Sidecar v1

package/template/skills/knowledge-prune/SKILL.md

@@ -12,7 +12,7 @@ description: dry-run 审计 workflow 声明的知识与策略 namespace，返回
 ## 输入
 
 - `runtime-context` 返回的 workflow/state 根。
-- `WORKFLOW.md#persistence` 中 role 为 knowledge、policy 或 legacy-knowledge 的 namespace。
+- `PERSISTENCE.md#persistence` 中 role 为 knowledge、policy 或 legacy-knowledge 的 namespace。
 - 用户确认状态：`dry-run | confirmed`。
 
 ## 流程

package/template/skills/knowledge-prune/references/audit-rules.md

@@ -2,7 +2,7 @@
 
 ## 扫描范围
 
-1. 读取目标 workflow 的 `<persistence>`，选择 role 为 `knowledge | policy | legacy-knowledge` 且真实存在的 store。
+1. 读取目标 workflow `PERSISTENCE.md` 的 `<persistence>`，选择 role 为 `knowledge | policy | legacy-knowledge` 且真实存在的 store。
 2. `create="lazy"` 但不存在的 store 记为 `missing`，不为审计而创建；`existing-only` store 只读。
 3. 扫描代码、文档、active changes 和 archive 中对 ADR、CONTEXT、LESSONS、RULES 及具体文件名的引用。
 

package/template/skills/runtime-context/SKILL.md

@@ -7,18 +7,18 @@ description: 解析 Speculo 项目根、资产根和 workflow 状态根，向 co
 
 # Runtime Context
 
-从项目根注册表和 workflow XML 声明构造一次运行所需的全部路径。调用方持有持久化责任；本 skill 只解析和验证路径。
+从项目根注册表和 workflow `PERSISTENCE.md` 构造一次运行所需的全部路径。调用方持有持久化责任；本 skill 只解析和验证路径。
 
 ## 输入
 
 - 当前工作目录或用户指定的项目目录。
-- workflow id，以及对应 `WORKFLOW.md` 中的 `<runtime-context>` 和 `<persistence>`。
+- workflow id，以及对应 `PERSISTENCE.md` 中的 `<runtime-context>` 和 `<persistence>`。
 - 可选 change 名称和 command id。
 
 ## 流程
 
 1. 按 `references/path-resolution.md` 向上定位 `speculo/.speculo/workspace.json`；找不到唯一项目根时返回 blocked。
-2. 读取注册表与 workflow 根别名，解析 `workflow/state/commands/skills/vendor`。
+2. 读取注册表与 workflow 的 `PERSISTENCE.md`，解析 `workflow/state/commands/skills/vendor`。
    - 对每个解析后的 vendor root 执行存在性验证：目标目录必须存在，否则返回明确错误信息指明缺失的具体路径，禁止静默跳过。
    - 任一路径越界或目标缺失时返回 blocked。
 3. 读取 `speculo/config.json`（若存在）；不存在时以默认值静默降级（`language: "en"`、`persistence.root_override: null`、`defaults.confirm_before_external_write: true`、`defaults.report_language: "en"`）。

package/template/skills/runtime-context/references/path-resolution.md

@@ -14,7 +14,7 @@
 
 ## Workflow 绑定
 
-读取 workflow 的 `<runtime-context>`：
+读取 workflow 同级 `PERSISTENCE.md` 的 `<runtime-context>`：
 
 - `base` 必须引用 `workspace.json#roots` 中已有根。
 - `path` 不能是绝对路径，不能包含 `..` 或反斜杠。
@@ -38,4 +38,4 @@ change_root = changes_root/<change>
 - `<artifact root="change">` 只能落在当前 change。
 - `<artifact root="state">` 只能落在 `<persistence>` 声明的额外命名空间。
 - command 报告只能落在 `state/commands/<command>/`，skill 不自行选择路径。
-- raw vendor skill 未经 workflow runtime context 激活时，不承诺 Speculo 持久化边界。
+- raw vendor SKILL 只通过同 workflow 的一对一 atomic wrapper 激活；wrapper 先加载 `PERSISTENCE.md`，嵌套 skill 名称继续解析到 wrapper。

package/template/skills/speculo-retro/SKILL.md

@@ -10,7 +10,7 @@ description: 从 Speculo 使用证据中提取、去重、分级和根因化摩
 ## 输入
 
 - 当前对话与本次使用的 commands/workflows。
-- `commands/<command>/*.md` 报告、active change 状态、archive 和 workflow 声明的 lessons/knowledge store。
+- `commands/<command>/*.md` 报告、active change 状态、archive 和 `PERSISTENCE.md` 声明的 lessons/knowledge store。
 - 可选已有 issues，用于语义去重。
 
 ## 流程

package/template/workflows/matt-pocock/PERSISTENCE.md

@@ -0,0 +1,80 @@
+# Matt Pocock Persistence
+
+本文件是 `matt-pocock` 的唯一运行契约。`WORKFLOW.md` 与 `atomic-skills/*.md` 只能引用本文件，不得复制 runtime roots、store、change 启动或副作用规则。无论从 workflow 还是 atomic wrapper 进入，都先读取项目根 `speculo/.speculo/workspace.json`，再执行本文件。
+
+## 运行时根
+
+```xml
+<runtime-context>
+  <root id="workflow" base="workflows" path="matt-pocock" />
+  <root id="state" base="state" path="matt-pocock" />
+  <root id="vendor:matt-pocock" base="vendor" path="matt-pocock" />
+</runtime-context>
+```
+
+## 持久化命名空间
+
+```xml
+<persistence root="state">
+  <store id="index" role="index" kind="file" path="status.json" create="initialize" />
+  <store id="changes" role="active" kind="directory" path="changes" create="initialize" />
+  <store id="archive" role="archive" kind="directory" path="archive" create="initialize" />
+  <store id="knowledge" role="knowledge" kind="directory" path="knowledge" create="lazy" consumers="docs-sync,retro,knowledge-prune" />
+  <store id="policy" role="policy" kind="directory" path="policy" create="lazy" consumers="docs-sync,knowledge-prune" />
+  <store id="integrations" role="integration" kind="directory" path="integrations" create="lazy" />
+  <store id="backlog" role="backlog" kind="directory" path="backlog" create="lazy" consumers="retro" />
+  <store id="legacy-config" role="legacy-knowledge" kind="directory" path=".config" create="existing-only" legacy="true" consumers="docs-sync,retro,knowledge-prune" />
+</persistence>
+```
+
+`status.json`、`changes/` 和 `archive/` 是固定骨架；lazy store 只在产生对应内容并确认长期归属时创建。已有 `.config/` 只读，不接收新内容。
+
+## 启动协议
+
+```xml
+<sequence>
+  <phase id="resolve-runtime" order="1">
+    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
+    <completion>workspace、config、workflow/state/vendor roots 均已解析并通过边界与存在性检查；同一运行已解析时复用结果。</completion>
+  </phase>
+  <phase id="select-change" order="2">
+    <artifact root="state" path="status.json" />
+    <completion>已选择用户指定或唯一 active change；没有 active change 时原子创建 `changes/YYYY-MM-DD-&lt;kebab-topic&gt;/.status.json` 并更新索引；多个候选时先消歧。</completion>
+  </phase>
+</sequence>
+```
+
+创建 change 时初始化 schema version 1、workflow/name/timestamps、`change_status: active`、空的 `route_history`、`skill_history` 与 `external_refs`。已有 change 缺少这些数组时按空数组读取，在下一次真实更新时补齐，不要求迁移。
+
+## 状态字段
+
+```xml
+<state-schema>
+  <field name="current_route" type="string|null" />
+  <field name="route_history" type="array" />
+  <field name="skill_history" type="array" />
+  <field name="external_refs" type="array" />
+  <field name="legacy_source" type="object|null" />
+</state-schema>
+```
+
+- route 调用维护 `current_route` 与 `route_history`；direct atomic 调用保持二者不变。
+- 每次 atomic wrapper 调用向 `skill_history` 追加 skill id、`direct|route` 模式、进入/完成时间、结果和真实的项目相对产物路径。
+- 外部系统结果只写入 `external_refs`；状态不保存派生绝对路径。
+
+## 路径分配
+
+1. route 的 `<artifact>` 指针优先，wrapper 使用调用方已声明路径。
+2. direct 调用没有 route 产物声明时，运行时文件由目标 skill 在当前 change 内按需新建；只强制 `change_root` 边界，不强制 `atomic-skills/<id>` 子目录。
+3. 项目代码、测试和用户明确要求的项目文档属于项目产物，可写入经确认的项目相对路径；同时把验证或结果指针记录到当前 change。
+4. 长期知识、规则和集成配置先在 change 中形成，经确认后才写入已声明的 lazy store。raw skill 中的 `CONTEXT.md`、ADR、`docs/agents/`、`.out-of-scope/` 等逻辑位置分别映射到 `knowledge`、`integrations` 或 `policy`，不在项目根自行创建私有运行状态。
+5. 临时原型、数据库、脚本和报告必须删除或吸收；保留的结论写入当前 change。raw skill 指向系统临时目录、当前目录或 `.scratch/` 时，同样受本规则约束。
+
+raw skill 内部提及另一个 `/skill` 时，解析到 `atomic-skills/<skill-id>.md`；只有该 wrapper 可以直接引用对应 vendor `SKILL.md`。
+
+## 副作用边界
+
+- 发布 issue、评论、标签，写 secret，启动后台 agent，提交代码，继续 merge/rebase，合并或删除 worktree 前，展示动作与目标并取得明确确认。
+- 已确认动作的结果、URL、commit 或失败状态写入 `external_refs`；敏感值不得写入 change 或状态。
+- vendor 内容保持只读；所有路径改写和确认规则由本文件提供。
+