@namewta/speculo 0.2.0 → 0.2.1

package/package.json

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

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,7 +18,7 @@ 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，空范围也保留。
 4. 由 skill 收集精确 commit 区间、archive 与声明 store 证据，整份审计命中文档并执行新增、更新、删除段落、合并或保留。整文件/目录删除和受保护知识仍逐次确认。

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>` 声明的 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 状态以及 workflow 声明的 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/runtime-context/SKILL.md

@@ -18,9 +18,17 @@ description: 解析 Speculo 项目根、资产根和 workflow 状态根，向 co
 ## 流程
 
 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 根别名，解析 `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,6 +6,12 @@
 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>`：
@@ -23,9 +29,12 @@ 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 不自行选择路径。

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/WORKFLOW.md

@@ -84,13 +84,24 @@ keywords: [matt-pocock, engineering, productivity, grilling, tdd, review]
   <phase id="select-change" order="1">
     <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
     <artifact root="state" path="status.json" />
-    <completion>已选择唯一 active change，或原子创建新 change 与 .status.json。</completion>
+    <completion>已选择唯一 active change，或原子创建新 change（名称 = `YYYY-MM-DD-&lt;kebab-topic&gt;`，日期前缀自动生成，格式不匹配则阻塞）与 .status.json。</completion>
   </phase>
-  <phase id="route" order="2">
+  <phase id="init-config" order="2">
+    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
+    <artifact root="speculo" path="config.json" />
+    <when>speculo/config.json 存在时读取；不存在时以默认值静默降级。</when>
+    <completion>config 已解析并纳入 runtime context，后续所有 phase 可引用 config.language / config.defaults 等字段。</completion>
+  </phase>
+  <phase id="init-vendor" order="3">
+    <skill root="skills" path="runtime-context/SKILL.md" activation="required" />
+    <when>workflow 声明了 vendor root；对每个解析后的 vendor root 执行存在性验证。</when>
+    <completion>所有 vendor root 均已通过存在性验证并纳入 skill 搜索范围；缺失 vendor 目录时返回明确错误。</completion>
+  </phase>
+  <phase id="route" order="4">
     <skill root="vendor:matt-pocock" path="engineering/ask-matt/SKILL.md" activation="required" />
     <completion>已根据用户意图选择一个 route；歧义时一次只澄清一个决策。</completion>
   </phase>
-  <phase id="lazy-config" order="3">
+  <phase id="lazy-config" order="5">
     <instructions root="workflow" path="routes/setup.md" />
     <when>目标 route 依赖尚未配置的 tracker、triage 或 domain 文档。</when>
     <completion>只补齐目标 route 必需的私有 namespace。</completion>