@namewta/speculo 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

package/speculo/.speculo/.config/RULES.md

@@ -7,3 +7,5 @@
 ## Rules
 
 - [TODO: 添加项目必须遵守的规则。]
+- 所有 Speculo change 目录必须以 `YYYY-MM-DD-<kebab-name>` 命名（例：`2026-06-12-user-auth`）。详见 `speculo/docs/persistence-contract.md` §0。
+- 所有 Speculo command 产物目录必须以 `YYYY-MM-DD-<cmd-name>-<topic>` 命名。

package/speculo/skills/speculo-write/references/persistence-contract-sop.md

@@ -3,6 +3,46 @@
 `.status.json` schema、目录命名、frontmatter 最小集与写入责任的内化规范。
 本文把 Speculo 持久化契约内化进本 skill，编写资产时**不读仓库 `docs/`**。
 
+## 命名铁律
+
+> ⚠️ **所有 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 目录名中的日期提取。
+
 ## 目录命名
 
 | 类别 | 模式 | 例 |
@@ -89,6 +129,7 @@ description: <一句话>    # 必填
 ```markdown
 > **服务工作流：** `<相对路径>`
 > **产物文件名：** `<filename>`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # <标题>
 
@@ -125,3 +166,18 @@ description: <一句话>    # 必填
 - `.speculo/archive/<cat>/.gitkeep`
 
 项目级长期资料放 `.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/workflows/dev/00-INDEX.md

@@ -10,6 +10,8 @@ keywords: [dev, 开发, workflow, index, 状态]
 
 本文件是 dev 分类的导航入口。进入时先读取 `../../.speculo/dev-status.json`，再按其中 active change 读取 `../../.speculo/dev/<change>/.status.json`，根据用户意图推荐下一步。
 
+> **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。详见 `../../docs/persistence-contract.md` §0。
+
 ## 入口别名
 
 | 别名 | 入口 | 用途 |
@@ -26,8 +28,9 @@ keywords: [dev, 开发, workflow, index, 状态]
 ## 进入协议
 
 1. 若用户未指定 change，扫描 `../../.speculo/dev-status.json` 和 `../../.speculo/dev/*/.status.json`，列出 active changes。
+   - **命名校验**：扫描时仅处理符合 `YYYY-MM-DD-<kebab-name>` 格式的目录。不符合的目录标记为 `malformed`，单独列出路径并提示用户修复或手动清理，不自动删除或重命名。
 2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
-3. 若没有 active change，按用户意图创建新的 change 目录，并初始化 `.status.json` 与 `../../.speculo/dev-status.json`。
+3. 若没有 active change，按用户意图创建新的 change 目录，**目录名必须为 `YYYY-MM-DD-<kebab-name>`**（使用当前日期，`<kebab-name>` 从用户意图提取），并初始化 `.status.json` 与 `../../.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` 核对工作树是否存在。
@@ -47,6 +50,7 @@ keywords: [dev, 开发, workflow, index, 状态]
 输出 dev 状态时至少包含：
 
 - active change 数量与每个 change 的 `current_phase`
+- malformed 目录清单（不符合 `YYYY-MM-DD-<kebab-name>` 格式的目录）
 - 最近更新的 change，按 `updated_at` 倒序
 - `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
 - worktree 模式 change 额外汇报 `base_branch` / `change_branch` / `worktree_status`

package/speculo/workflows/dev/01-grill-with-docs/01-grill-with-docs.md

@@ -21,7 +21,7 @@ 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 目录：`.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-user-auth`）
 
 ### 输出
 
@@ -30,6 +30,8 @@ keywords: [grill, context, adr, 术语, 决策]
 - 已确认的术语、决策、开放问题和 ADR 候选
 - 需要用户进一步决策的问题，每次只问一个
 
+（`<change>` 为当前 change 目录名，格式 `YYYY-MM-DD-<kebab-name>`）
+
 ### 执行原则
 
 针对计划的每个方面不断向用户提问，直到达成共识。沿着设计树的每条分支逐一展开，逐个解决决策之间的依赖关系。对于每个问题，给出推荐答案。

package/speculo/workflows/dev/02-prd/02-prd.md

@@ -10,6 +10,8 @@ keywords: [prd, zoom-out, 需求, 计划]
 
 本工作流用于把已知上下文综合为当前 Speculo change 内的 overview 和 PRD。zoom-out 全景理解与 PRD 综合能力已内置在本 workflow 目录中。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。产物写入 `.speculo/dev/<change>/`。
+
 ## 内置指引
 
 ### Zoom Out
@@ -22,6 +24,8 @@ keywords: [prd, zoom-out, 需求, 计划]
 
 PRD 只写入 `.speculo/dev/<change>/prd.md`，overview 只写入 `.speculo/dev/<change>/overview.md`。不写项目根下的任意规划文档，不默认发布外部 issue。只有 tracker 已配置且用户明确要求时，才进入外部发布动作。
 
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
+
 ## 阶段
 
 ### 1. Zoom Out — 全景理解

package/speculo/workflows/dev/03-tdd/03-tdd.md

@@ -32,7 +32,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 ## 阶段
 
-> **产物目录：** 本工作流所有产物写入 `.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。
+> **产物目录：** 本工作流所有产物写入 `.speculo/dev/<change>/tdd/<phase-id>/`（见下「TDD 产物目录与阶段标识」）。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-user-auth`）。
 
 ### 1. TDD Plan — 行为与接口计划
 - 规范：`tdd-plan.md`
@@ -64,6 +64,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 ## TDD 产物目录与阶段标识
 
 - 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / slices 等产物分离，便于多阶段并行与回溯。
+- `<change>` 为当前 change 目录名（`YYYY-MM-DD-<kebab-name>`）。
 - `<phase-id>` 标识：
   - change 来自**多阶段 slices** 时，用 slices 阶段标识（与 slices `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
   - change 为**单阶段**（无 slices 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。

package/speculo/workflows/dev/04-finalize/04-finalize.md

@@ -10,6 +10,8 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 
 本工作流是 `dev/04` 入口，是开发主线的收尾环节（`dev/01` → `dev/02` → `dev/I` → `dev/03` → `dev/04`）。它在 change 的实现完成后，**先用证据证明"真的完成了"，再改变状态并归档**。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。归档目标为 `.speculo/archive/dev/<YYYY-MM>/<change>/`，`<YYYY-MM>` 从 change 目录名中的日期提取。
+
 ## 内置指引
 
 ### 核心原则

package/speculo/workflows/dev/D-docs-sync/D-docs-sync.md

@@ -23,7 +23,7 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 - `.speculo/dev/docs-sync-state.json`
 - 当前 git `HEAD`
 - state 中的 `tracked_docs` 列表
-- 当前 change 目录：`.speculo/dev/<change>/`
+- 当前 change 目录：`.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-docs-sync`）
 
 ### 输出
 
@@ -31,6 +31,8 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 - 更新后的 tracked docs
 - 更新后的 `.speculo/dev/docs-sync-state.json`
 
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
+
 ### 渐进披露
 
 - `readme-contract.md`：更新 README 类文档时读取。

package/speculo/workflows/dev/H-diagnose/H-diagnose.md

@@ -19,7 +19,7 @@ keywords: [diagnose, hotfix, bug, debug, performance, 回归]
 ### 输入
 
 - 用户描述的失败现象、日志、复现步骤或性能症状
-- 当前 change 目录：`.speculo/dev/<change>/`
+- 当前 change 目录：`.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-fix-login-bug`）
 - 可运行的测试、脚本、服务或其他反馈循环
 
 ### 输出
@@ -29,6 +29,8 @@ keywords: [diagnose, hotfix, bug, debug, performance, 回归]
 - 诊断记录、假设列表、插桩结果、修复与回归验证结论
 - 若缺少可信反馈循环，输出已尝试方法和需要用户提供的材料
 
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
+
 ### 执行原则
 
 完整诊断循环为：复现 -> 最小化 -> 假设 -> 插桩 -> 修复 -> 回归测试。仅在明确合理时才跳过阶段。

package/speculo/workflows/dev/I-to-issues/I-to-issues.md

@@ -18,7 +18,7 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 - PRD、计划、设计记录、bug 诊断结论或当前对话上下文
 - 用户明确提供的 issue tracker 配置和标签词汇表（如果存在）
-- 当前 change 目录：`.speculo/dev/<change>/`
+- 当前 change 目录：`.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-user-auth`）
 
 ### 输出
 
@@ -26,6 +26,8 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 - 垂直切片清单、依赖关系、HITL/AFK 标记和验收标准
 - 可选的外部 issue 引用
 
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
+
 ### 垂直切片规则
 
 - 每个切片交付一条贯穿所有层（schema、API、UI、测试）的窄但完整的路径。

package/speculo/workflows/dev/R-review/R-review.md

@@ -10,6 +10,8 @@ keywords: [review, diff, spec, engineering, standards, security, solid, pr, 审
 
 本工作流是 `dev/R` 入口，用于审查 `HEAD` 与用户提供的固定点之间的 diff。审查以**资深工程师视角**进行，结果必须分成三个**互相独立、互不掩盖**的维度，每条 finding 带严重度，最后给出整体裁决。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-review-auth-module`）。审查产物写入 `.speculo/dev/<change>/`。
+
 ## 内置指引
 
 ### 何时使用

package/speculo/workflows/dev/_templates/completion-summary-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../04-finalize/04-finalize.md`
 > **产物文件名：** `completion-summary.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Completion Summary
 

package/speculo/workflows/dev/_templates/completion-verification-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../04-finalize/04-finalize.md`
 > **产物文件名：** `completion-verification.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Completion Verification
 

package/speculo/workflows/dev/_templates/diagnosis-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../H-diagnose/H-diagnose.md`
 > **产物文件名：** `diagnosis.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Diagnosis
 

package/speculo/workflows/dev/_templates/docs-sync-report-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../D-docs-sync/D-docs-sync.md`
 > **产物文件名：** `docs-sync-report.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Docs Sync Report
 

package/speculo/workflows/dev/_templates/grill-context-map-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../01-grill-with-docs/01-grill-with-docs.md`
 > **产物文件名：** `context-map.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Context Map
 

package/speculo/workflows/dev/_templates/grill-decision-log-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../01-grill-with-docs/01-grill-with-docs.md`
 > **产物文件名：** `decision-log.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Decision Log
 

package/speculo/workflows/dev/_templates/issues-slices-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../I-to-issues/I-to-issues.md`
 > **产物文件名：** `slices.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Vertical Slices
 

package/speculo/workflows/dev/_templates/prd-overview-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../02-prd/02-prd.md`
 > **产物文件名：** `overview.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Overview
 

package/speculo/workflows/dev/_templates/prd-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../02-prd/02-prd.md`
 > **产物文件名：** `prd.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # PRD
 

package/speculo/workflows/dev/_templates/regression-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../H-diagnose/H-diagnose.md`
 > **产物文件名：** `regression.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Regression
 

package/speculo/workflows/dev/_templates/review-report-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../R-review/R-review.md`
 > **产物文件名：** `review-report.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Review Report
 

package/speculo/workflows/dev/_templates/review-sources-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../R-review/R-review.md`
 > **产物文件名：** `review-sources.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Review Sources
 

package/speculo/workflows/dev/_templates/review-verdict-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../R-review/R-review.md`
 > **产物文件名：** `review-verdict.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Review Verdict
 

package/speculo/workflows/dev/_templates/tdd-log-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../03-tdd/03-tdd.md`
 > **产物文件名：** `tdd/<phase-id>/implementation-log.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Implementation Log
 

package/speculo/workflows/dev/_templates/tdd-plan-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../03-tdd/03-tdd.md`
 > **产物文件名：** `tdd/<phase-id>/tdd-plan.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # TDD Plan
 

package/speculo/workflows/dev/_templates/tdd-verification-template.md

@@ -1,5 +1,6 @@
 > **服务工作流：** `../03-tdd/03-tdd.md`
 > **产物文件名：** `tdd/<phase-id>/verification.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # Verification
 

package/speculo/workflows/doc/00-INDEX.md

@@ -10,6 +10,8 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 
 本文件是 doc 分类的导航入口。进入时先读取 `../../.speculo/doc-status.json`，再按其中 active change 读取 `../../.speculo/doc/<change>/.status.json`，根据用户意图推荐横向 workflow。
 
+> **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-article-draft`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。详见 `../../docs/persistence-contract.md` §0。
+
 ## 入口别名
 
 | 别名 | 入口 | 用途 |
@@ -24,8 +26,9 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 ## 进入协议
 
 1. 若用户未指定 change，扫描 `../../.speculo/doc-status.json` 和 `../../.speculo/doc/*/.status.json`，列出 active changes。
+   - **命名校验**：扫描时仅处理符合 `YYYY-MM-DD-<kebab-name>` 格式的目录。不符合的目录标记为 `malformed`，单独列出路径并提示用户修复或手动清理，不自动删除或重命名。
 2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
-3. 若没有 active change，按用户意图创建新的 doc change 目录，并初始化 `.status.json` 与 `../../.speculo/doc-status.json`。
+3. 若没有 active change，按用户意图创建新的 doc change 目录，**目录名必须为 `YYYY-MM-DD-<kebab-name>`**（使用当前日期，`<kebab-name>` 从用户意图提取），并初始化 `.status.json` 与 `../../.speculo/doc-status.json`。
 4. 推荐入口时优先使用用户显式别名；没有别名时按用户意图推荐一个横向 workflow。
 5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件和模板。
 
@@ -43,6 +46,7 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 输出 doc 状态时至少包含：
 
 - active change 数量与每个 change 的 `current_phase`
+- malformed 目录清单（不符合 `YYYY-MM-DD-<kebab-name>` 格式的目录）
 - 每个 change 的当前文档路径、素材路径和最近写入时间
 - `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
 - 推荐下一步入口和原因

package/speculo/workflows/doc/B-writing-beats/B-writing-beats.md

@@ -10,6 +10,8 @@ keywords: [beats, narrative, article, writing, 叙事, 文章]
 
 本工作流用于把文章塑造成一段由 beat 组成的旅程。用户从原始素材中选择起始 beat；执行者只写当前 beat，然后给出下一步转向选项，直到文章自然结束。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-article-notes`）。产物写入 `.speculo/doc/<change>/`。
+
 ## 内置指引
 
 ### 何时使用
@@ -20,7 +22,7 @@ keywords: [beats, narrative, article, writing, 叙事, 文章]
 
 - 用户提供的原始素材 Markdown 路径，或同 change 的 `fragments.md`
 - 当前文章文件：默认 `.speculo/doc/<change>/article.md`
-- 当前 doc change 目录：`.speculo/doc/<change>/`
+- 当前 doc change 目录：`.speculo/doc/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-article-notes`）
 
 ### 输出
 

package/speculo/workflows/doc/E-edit-article/E-edit-article.md

@@ -10,6 +10,8 @@ keywords: [edit, article, revise, clarity, draft, 编辑, 修订]
 
 本工作流用于编辑已有文章草稿。先按标题和信息依赖确认章节顺序，再逐节重写，提升清晰度、连贯性和流畅度。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-edit-article`）。产物写入 `.speculo/doc/<change>/`。
+
 ## 内置指引
 
 ### 何时使用
@@ -20,7 +22,7 @@ keywords: [edit, article, revise, clarity, draft, 编辑, 修订]
 
 - 用户提供的文章草稿路径，或 `.speculo/doc/<change>/article.md`
 - 用户明确的发布目标、语气偏好或约束
-- 当前 doc change 目录：`.speculo/doc/<change>/`
+- 当前 doc change 目录：`.speculo/doc/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-edit-article`）
 
 ### 输出
 

package/speculo/workflows/doc/F-writing-fragments/F-writing-fragments.md

@@ -10,6 +10,8 @@ keywords: [fragments, ideate, raw material, writing, 写作素材]
 
 本工作流用于在强加结构之前发展想法。它围绕用户想写的主题持续追问，捕捉 fragment，并把素材追加到当前 doc change 的 `fragments.md`。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-collect-ideas`）。产物写入 `.speculo/doc/<change>/`。
+
 ## 内置指引
 
 ### 何时使用
@@ -20,7 +22,7 @@ keywords: [fragments, ideate, raw material, writing, 写作素材]
 
 - 用户给出的主题、初始 prompt 或已有素材
 - 用户在会话中补充的主张、小场景、锋利句子、半成形想法
-- 当前 doc change 目录：`.speculo/doc/<change>/`
+- 当前 doc change 目录：`.speculo/doc/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-collect-ideas`）
 
 ### 输出
 

package/speculo/workflows/doc/M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md

@@ -20,6 +20,8 @@ keywords: [毛泽东, 毛选, 教员, 矛盾分析, 战略, 组织, 认知模型
 
 **局限**：聚焦思维方法论的迁移，不评判政治立场；涉及 1949 年后争议历史只取思维方法论侧面并标注边界。
 
+> **目录命名：** `<change>` 必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-mao-strategy-consult`）。产物写入 `.speculo/doc/<change>/`。
+
 ## 内置指引
 
 ### 角色扮演规则
@@ -97,7 +99,7 @@ keywords: [毛泽东, 毛选, 教员, 矛盾分析, 战略, 组织, 认知模型
 
 ## 阶段
 
-> **产物目录：** 本工作流所有产物写入 `.speculo/doc/<change>/`。下文产物路径均相对该 change 目录。
+> **产物目录：** 本工作流所有产物写入 `.speculo/doc/<change>/`。下文产物路径均相对该 change 目录。**`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`**（例：`2026-06-12-mao-strategy-consult`）。
 
 ### 1. 激活与问诊 — Activate
 - 规范：`activate.md`
@@ -187,12 +189,12 @@ keywords: [毛泽东, 毛选, 教员, 矛盾分析, 战略, 组织, 认知模型
 | 表达风格要全量句式/比喻库/范式 | `references/research/14-voice-and-dialogue.md` |
 | 要引用原文金句、查篇目编号映射 | `references/research/15-quote-bank.md` |
 
-## 外挂知识库（可选）
+## 内置知识库
 
-本工作流可挂载《毛泽东选集》全文数字化版本（开源库 [weiyinfu/MaoZeDongAnthology](https://github.com/weiyinfu/MaoZeDongAnthology)），用于检索原文、精确引用。
+本工作流内置《毛泽东选集》全文数字化版本（229 篇，编号 000–228），位于工作流目录下的 `books/`，无需联网即可检索原文、精确引用。
 
-**路径发现**（按序尝试）：环境变量 `$MAOXUAN_KB_PATH` → `~/MaoZeDongAnthology/` → `./MaoZeDongAnthology/` → `../MaoZeDongAnthology/`。均未命中则静默跳过，仅用内置框架。
+**知识库路径**：`./books/`（即本工作流目录下的 `books/` 子目录）。
 
-**知识库结构**：文章原文 `src/NNN-标题.md`（229 篇，编号 000–228），层级目录 `src/目录.md`。
+**知识库结构**：文章原文 `books/src/NNN-标题.md`（229 篇，编号 000–228），层级目录 `books/src/目录.md`，卷次索引 `books/README.md`。
 
 **引用纪律**：引金句必带篇目名与编号；区分逐字原文（加引号）与概括转述（标注"转述/大意"）；建国后争议文本只引方法论句并附边界提示。