@namewta/speculo 0.2.0 → 0.2.2

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.0",
+  "version": "0.2.2",
   "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/.speculo/workspace.json

@@ -2,6 +2,7 @@
   "schema_version": 1,
   "path_base": "project-root",
   "roots": {
+    "config": "speculo/config.json",
     "speculo": "speculo",
     "state": "speculo/.speculo",
     "commands": "speculo/commands",

package/template/commands/docs-sync.md

@@ -18,9 +18,9 @@ keywords: [docs-sync, readme, changelog, agents, documentation]
 
 ## 执行
 
-1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/docs-sync/SKILL.md`，解析 command 路径和全部已安装 workflow/state 根。
+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/finalize.md

@@ -18,7 +18,7 @@ keywords: [finalize, verify, complete, archive, 收尾]
 
 ### finalize-active
 
-1. 读取 `../skills/runtime-context/SKILL.md` 和 `../skills/change-lifecycle/SKILL.md`，解析 workflow 的固定 `changes/archive` 根。
+1. 读取 `../skills/runtime-context/SKILL.md` 和 `../skills/change-lifecycle/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级）和 workflow 的固定 `changes/archive` 根。
 2. 选择一个 active change，执行新鲜验证、需求核对和 worktree 预检；缺证据即 blocked。
 3. 展示验证证据、状态变化、归档目标和报告路径，等待用户明确确认。
 4. 确认后将 change 置为 completed，再移动到 archive，更新 `status.json#active`，复查目标和索引。

package/template/commands/knowledge-prune.md

@@ -14,7 +14,7 @@ keywords: [knowledge, prune, rules, lessons, context, adr]
 
 ## 执行
 
-1. 读取 `../skills/runtime-context/SKILL.md`，选择 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

@@ -25,7 +25,7 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 ## 执行步骤
 
-1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/speculo-retro/SKILL.md`，采集对话、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`，让用户确认或改正。

package/template/commands/status.md

@@ -8,8 +8,9 @@ keywords: [status, 状态, active, blocked]
 
 # Status 命令
 
-1. 扫描 `speculo/workflows/*/WORKFLOW.md`，得到已安装 workflow ids。
-2. 对每个 id 读取 `speculo/.speculo/<workflow>/status.json`，再读取 `changes/<change>/.status.json`。
-3. 报告 active 数量、current route/phase、最近更新时间、blocked/stale changes 与 malformed 目录。
-4. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
-5. 用户要求持久化时写入 `speculo/.speculo/commands/status/<YYYY-MM-DD>-workspace-<topic>[-NN].md`，并在报告中列出本次扫描的 workflow 选择。
+1. 读取 `../skills/runtime-context/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级）。
+2. 扫描 `speculo/workflows/*/WORKFLOW.md`，得到已安装 workflow ids。
+3. 对每个 id 读取 `speculo/.speculo/<workflow>/status.json`，再读取 `changes/<change>/.status.json`。
+4. 报告 active 数量、current route/phase、最近更新时间、blocked/stale changes 与 malformed 目录。
+5. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
+6. 用户要求持久化时写入 `speculo/.speculo/commands/status/<YYYY-MM-DD>-workspace-<topic>[-NN].md`，并在报告中列出本次扫描的 workflow 选择。

package/template/config.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "language": "zh-CN",
+  "persistence": {
+    "root_override": null
+  },
+  "defaults": {
+    "confirm_before_external_write": true,
+    "report_language": "zh-CN"
+  }
+}

package/template/skills/change-lifecycle/references/finalize-archive.md

@@ -4,7 +4,7 @@
 
 ## 共同预检
 
-- change 名称符合日期 kebab 规则，且 `.status.json` 可解析。
+- change 名称符合日期 kebab 规则（格式校验来源与 `runtime-context/SKILL.md` 第4步相同，创建时已保证；此处为冗余验证），且 `.status.json` 可解析。
 - 源位于 runtime context 的 `changes_root`，目标位于 `archive_root/<YYYY-MM>/<change>`。
 - 目标不存在，workflow `status.json` 与 change 状态一致。
 - worktree 模式已经合并回目标分支并清理，或调用方明确记录 blocked。

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/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,20 +7,28 @@ 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`；任一路径越界或目标缺失时返回 blocked。
-3. 读取固定状态骨架 `status.json/changes/archive`；选择 change 时派生 `change_root`，不把派生绝对路径写回状态。
-4. 返回 project-relative runtime context，供后续所有 skills 复用；后续调用不得重新猜测路径。
+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"`）。
+4. 读取固定状态骨架 `status.json/changes/archive`；选择 change 时派生 `change_root`，不把派生绝对路径写回状态。
+   - **Change 名称格式校验：** change 名称必须匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`（即 `YYYY-MM-DD-<kebab-topic>`）。
+   - 创建 change 时自动以当天日期为前缀（`YYYY-MM-DD-`），用户只需提供 topic 部分。
+   - 手动指定完整 change 名时，不匹配格式则阻塞并提示正确格式：`YYYY-MM-DD-<kebab-topic>`。
+   - 已有不带日期前缀的历史 change 标注为遗留，不阻塞但记录警告。
+   - 校验逻辑定义为单一来源（本步骤），归档端（`finalize-archive.md`）的日期 kebab 检查引用同一格式规则。
+5. 返回 project-relative runtime context，供后续所有 skills 复用；后续调用不得重新猜测路径。
 
 ## 输出
 
@@ -34,10 +42,13 @@ change_root?
 commands_root
 skills_root
 vendor_roots[]
+config?
 ```
 
-完成标准：所有返回路径均为项目根相对路径、位于声明根内且对应静态资产真实存在；本 skill 未创建任何运行时产物。
+`config` 字段包含已解析的 `{language, persistence: {root_override}, defaults: {confirm_before_external_write, report_language}}`。
+
+完成标准：所有返回路径均为项目根相对路径、位于声明根内且对应静态资产真实存在；vendor root 已通过存在性验证；change 名称已通过格式校验；本 skill 未创建任何运行时产物。
 
 ## 渐进披露
 
-- `references/path-resolution.md`：定位根注册表、解析 XML 根别名或检查路径越界时读取。
+- `references/path-resolution.md`：定位根注册表、解析 XML 根别名、config 定位与降级规则、change 名称格式约束或检查路径越界时读取。

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

@@ -6,9 +6,15 @@
 2. 第一个命中的目录是 `project_root`；同时命中多个候选或用户指定目录与候选不一致时停止并澄清。
 3. `workspace.json#path_base` 必须为 `project-root`，所有 roots 必须是 POSIX 风格相对路径。
 
+## Config 定位
+
+1. 在 `project_root` 下查找 `speculo/config.json`。
+2. 若存在，读取并解析其内容；若不存在，以默认值静默降级（`language: "en"`、`persistence.root_override: null`、`defaults.confirm_before_external_write: true`、`defaults.report_language: "en"`）。
+3. config 对象由 runtime-context 统一输出，后续调用方不得重新猜测路径或自行解析。
+
 ## Workflow 绑定
 
-读取 workflow 的 `<runtime-context>`：
+读取 workflow 同级 `PERSISTENCE.md` 的 `<runtime-context>`：
 
 - `base` 必须引用 `workspace.json#roots` 中已有根。
 - `path` 不能是绝对路径，不能包含 `..` 或反斜杠。
@@ -23,10 +29,13 @@ archive_root = state_root/archive
 change_root = changes_root/<change>
 ```
 
+**Change 名称格式约束：** `<change>` 必须匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$`（即 `YYYY-MM-DD-<kebab-topic>`）。创建 change 时自动以当天日期为前缀，用户只需提供 topic 部分。手动指定完整名称时，不匹配格式则阻塞并提示正确格式。此格式约束在创建时即强制执行，归档时的日期 kebab 检查作为冗余验证与此处共享同一校验来源。已有不带日期前缀的历史 change 在文档中标注为遗留，归档时不阻塞。
+
 ## 边界检查
 
 - 解析后执行真实路径包含检查；符号链接逃逸与不存在的静态引用均阻塞。
+- **Vendor root 存在性验证：** 解析后的每个 vendor root 必须验证目标目录存在；缺失时返回明确错误信息指明缺失的具体路径，禁止静默跳过。此规则与 workflow/state/commands/skills 根的验证同等生效。
 - `<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/vendor/matt-pocock/engineering/improve-codebase-architecture/HTML-REPORT.md

@@ -2,11 +2,13 @@
 
 架构审查渲染为一个独立的 HTML 文件，存放在操作系统临时目录中。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状的图表；手工构建的 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。混合使用两者 — 不要所有事情都依赖 Mermaid，否则会变得千篇一律。
 
+`{{config.defaults.report_language}}` 占位符由 runtime-context 输出的 `config` 对象填充，值来自 `speculo/config.json` 的 `defaults.report_language` 字段；若 config 文件不存在，默认值为 `"en"`。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状的图表；手工构建的 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。混合使用两者 — 不要所有事情都依赖 Mermaid，否则会变得千篇一律。
+
 ## 脚手架
 
 ```html
 <!doctype html>
-<html lang="en">
+<html lang="{{config.defaults.report_language}}">
   <head>
     <meta charset="utf-8" />
     <title>Architecture review — {{repo name}}</title>

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/SKILL.md

@@ -26,6 +26,7 @@ disable-model-invocation: true
 - `docs/adr/` 和所有 `src/*/docs/adr/` 目录
 - `docs/agents/` —— 此技能之前的输出是否已存在？
 - `.scratch/` —— 表示本地 markdown issue tracker 约定已在使用中的标志
+- `speculo/config.json` —— 全局配置文件是否已存在？若存在，读取其内容
 
 ### 2. 展示发现结果并询问
 
@@ -73,12 +74,22 @@ disable-model-invocation: true
 - **单上下文** —— 仓库根目录下一个 `CONTEXT.md` + `docs/adr/`。大多数仓库属于此类。
 - **多上下文** —— 根目录下 `CONTEXT-MAP.md` 指向各上下文的 `CONTEXT.md` 文件（通常为 mono repo）。
 
+**D 节 —— 语言与配置偏好。**
+
+> 解释：Speculo 使用 `speculo/config.json` 存储全局配置，包括 AI 与用户的交互语言、报告生成语言、以及持久化路径覆盖。其他 commands 和 workflows 在初始化时读取此文件以自动选择语言和确认策略。
+
+询问用户：
+
+- **交互语言** —— Speculo 与用户交互时使用的语言。选项：`zh-CN`（简体中文）、`en`（英文）。默认：`zh-CN`。
+- **报告语言** —— AI 生成产物（HTML 报告、Markdown 文档、issue 正文）的默认语言。默认与交互语言相同。
+
 ### 3. 确认并编辑
 
 向用户展示以下内容的草稿：
 
 - 要添加到 `CLAUDE.md` / `AGENTS.md`（根据第 4 步的选择规则决定编辑哪个文件）的 `## Agent skills` 块
 - `docs/agents/issue-tracker.md`、`docs/agents/triage-labels.md`、`docs/agents/domain.md` 的内容
+- `speculo/config.json` 的内容（若不存在则新建）
 
 让他们在写入之前编辑。
 
@@ -122,6 +133,24 @@ disable-model-invocation: true
 
 对于"其他"issue tracker，根据用户的描述从头编写 `docs/agents/issue-tracker.md`。
 
+如果 `speculo/config.json` 不存在，根据 D 节的用户选择创建：
+
+```jsonc
+{
+  "schema_version": 1,
+  "language": "<用户选择的交互语言>",
+  "persistence": {
+    "root_override": null
+  },
+  "defaults": {
+    "confirm_before_external_write": true,
+    "report_language": "<用户选择的报告语言>"
+  }
+}
+```
+
+如果 `speculo/config.json` 已存在，仅更新用户本次修改的字段，保留其他现有值。
+
 ### 5. 完成
 
 告诉用户配置已完成，以及哪些工程化技能现在将读取这些文件。提醒他们之后可以直接编辑 `docs/agents/*.md` —— 只有在需要切换 issue tracker 或从头重新配置时才需要重新运行此技能。

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/domain.md

@@ -2,50 +2,39 @@
 
 工程 skills 在探索代码库时应如何使用该仓库的领域文档。
 
-## 在探索之前，阅读这些
+## 布局：单上下文
 
-- **`CONTEXT.md`**（位于仓库根目录），或
-- **`CONTEXT-MAP.md`**（位于仓库根目录，如果存在的话）— 它指向每个上下文的一个 `CONTEXT.md`。阅读与主题相关的每一个。
-- **`docs/adr/`** — 阅读涉及你要工作区域的 ADR。在多上下文仓库中，还要检查 `src/<context>/docs/adr/` 以获取上下文范围的决策。
+```
+{state_root}/knowledge/
+├── CONTEXT.md                          ← 项目领域术语与概念（待 domain-modeling 创建）
+├── adr/                                ← 架构决策记录（待 domain-modeling 创建）
+│   └── NNNN-slug.md
+└── domain.md                           ← 本文件
+```
 
-如果这些文件都不存在，**静默继续**。不要标记它们的缺失；不要预先建议创建它们。`/domain-modeling` skill（通过 `/grill-with-docs` 和 `/improve-codebase-architecture` 到达）在术语或决策实际被确定时延迟创建它们。
+## 路径解析规则
 
-## 文件结构
+**本文件描述的路径均为相对于 `{state_root}/knowledge/` 的逻辑路径。** 实际写入时由 Speculo persistence 层映射到 `{state_root}/knowledge/` 命名空间下。
 
-单上下文仓库（大多数仓库）：
+- `CONTEXT.md` → `{state_root}/knowledge/CONTEXT.md`
+- `adr/` → `{state_root}/knowledge/adr/`
+- `{state_root}` 由 runtime-context 解析，默认为 `speculo/.speculo/<workflow>/`
 
-```
-/
-├── CONTEXT.md
-├── docs/adr/
-│   ├── 0001-event-sourced-orders.md
-│   └── 0002-postgres-for-write-model.md
-└── src/
-```
+Vendor skills（如 domain-modeling）描述的是通用项目布局（"仓库根目录下的 CONTEXT.md"），这是正确的通用行为。本文件作为 Speculo 适配层，负责将这些通用路径翻译到 Speculo 持久化命名空间内。当 vendor skill 指示"在仓库根目录创建 CONTEXT.md"时，实际写入路径为 `{state_root}/knowledge/CONTEXT.md`。
 
-多上下文仓库（根目录存在 `CONTEXT-MAP.md`）：
+## 在探索之前
 
-```
-/
-├── CONTEXT-MAP.md
-├── docs/adr/                          ← 系统级决策
-└── src/
-    ├── ordering/
-    │   ├── CONTEXT.md
-    │   └── docs/adr/                  ← 上下文特定决策
-    └── billing/
-        ├── CONTEXT.md
-        └── docs/adr/
-```
+- **`CONTEXT.md`**（位于 knowledge/ 命名空间内，由 domain-modeling skill 创建）—— 项目领域语言
+- **`adr/`** —— 涉及工作区域的 ADR
 
-## 使用术语表的词汇
+如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`domain-modeling` skill 在术语或决策实际被确定时延迟创建它们。
 
-当你的输出中命名了一个领域概念（在 issue 标题、重构提案、假设、测试名称中），使用 `CONTEXT.md` 中定义的术语。不要偏离到术语表明确避免的同义词。
+## 使用术语表的词汇
 
-如果你需要的概念尚未在术语表中，这是一个信号 — 要么你在发明项目不使用的语言（重新考虑），要么确实存在缺口（记录给 `/domain-modeling`）。
+输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到术语表明确避免的同义词。如果需要的新概念尚未在术语表中，记录给 `domain-modeling`。
 
 ## 标记 ADR 冲突
 
-如果你的输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
+如果输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
 
-> _与 ADR-0007（事件溯源订单）矛盾 — 但值得重新讨论，因为……_
+> _与 ADR-NNNN 矛盾 — 但值得重新讨论，因为……_

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 内容保持只读；所有路径改写和确认规则由本文件提供。
+