@namewta/speculo 0.1.20 → 0.1.21

package/package.json

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

package/template/commands/archive.md

@@ -35,7 +35,7 @@ keywords: [archive, 归档, 清理]
    - **待归档：** 源路径、目标路径、当前分类、`updated_at`、最后 phase、是否仍在 `<cat>-status.json active[]`。
    - **broken-change：** 缺少 `.status.json` 的 change 目录路径。
    - **冲突：** 目标路径已存在的 change。
-4. 向用户展示清单并等待明确确认。没有确认时只输出计划，不移动目录、不改索引。对于 `broken-change`，提示用户需先通过对应 workflow 入口（`dev/AGENTS.md`、`doc/AGENTS.md` 或 `person/AGENTS.md`）补建 `.status.json`，或将 `change_status` 手动置为 `completed` 后再归档。
+4. 向用户展示清单并等待明确确认。没有确认时只输出计划，不移动目录、不改索引。对于 `broken-change`，提示用户需先通过对应 workflow 入口（`../workflows/dev/AGENTS.md`、`../workflows/doc/AGENTS.md` 或 `../workflows/person/AGENTS.md`）补建 `.status.json`，或将 `change_status` 手动置为 `completed` 后再归档。
 5. 用户确认后逐项执行（仅对待归档项）：
    - 创建 `speculo/.speculo/archive/<cat>/<YYYY-MM>/`
    - 移动 change 目录到 `speculo/.speculo/archive/<cat>/<YYYY-MM>/<change-name>/`

package/template/commands/handoff.md

@@ -25,7 +25,7 @@ keywords: [handoff, 交接, summary, resume]
 ## 执行步骤
 
 1. 读取 `../skills/handoff/SKILL.md`。
-2. 按 `../skills/handoff/SKILL.md` 要求，生成脱敏交接文档。
+2. 按 `../skills/handoff/SKILL.md` 要求，生成脱敏交接正文与 `<topic>` 建议。
 3. 创建规范命令产物目录 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`。
 4. 把交接正文写入 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
 5. 删除 API key、密码、PII 和其他敏感信息；不要复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文。

package/template/commands/status.md

@@ -54,5 +54,5 @@ keywords: [status, 状态, 进度]
 [TODO: 列出最近 5 个更新的 change + 分类 + 当前 phase]
 
 ## 可能僵尸 Changes
-[TODO: 超过 N 天未更新的 change 清单]
+[TODO: 超过 14 天未更新的 change 清单]
 ```

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

@@ -12,18 +12,12 @@ description: dry-run 审计 .config 中可安全删除或合并的过期知识
 ## 何时使用
 
 - 用户要求"清理 .config"、"prune 配置"、"审计 ADR/CONTEXT/LESSONS 过期项"
-- 用户要求"看看哪些知识资产可以删"、"检查过期的 ADR"
 - 被 `commands/config-prune.md` 或 `workflows/dev/D-docs-sync` 等调用方委托执行审计
 - 本 skill 只负责分析与生成候选清单，不自行删除文件、不自行写报告；持久化由调用方负责
 
 ## 输入
 
-- `.config` 资产路径：`speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`；缺失路径记录为 `missing`，不自动创建
-- 仓库引用扫描命令：
-  ```bash
-  rg -n "ADR-[0-9]{4}|[0-9]{4}-[a-z0-9-]+\\.md|CONTEXT|LESSONS|RULES" .
-  ```
-  排除 `node_modules/`、`dist/`、`.git/` 等生成或依赖目录
+- `.config` 资产路径：`speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`
 - 用户确认状态（dry-run 或 confirmed）
 
 ## 输出
@@ -34,33 +28,17 @@ description: dry-run 审计 .config 中可安全删除或合并的过期知识
 
 ## 执行步骤
 
-1. 读取 `speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`；缺失路径记录为 `missing`，不自动创建。
-2. 扫描当前仓库引用：
-   ```bash
-   rg -n "ADR-[0-9]{4}|[0-9]{4}-[a-z0-9-]+\\.md|CONTEXT|LESSONS|RULES" .
-   ```
-   排除 `node_modules/`、`dist/`、`.git/` 等生成或依赖目录。
-3. 生成 dry-run 候选，至少包含：
-   - 指向不存在 ADR 的正文引用或索引行。
-   - 标记为 superseded 且超过 30 天、无活跃引用的 ADR。
-   - 只含 `.gitkeep`、TODO、空占位或模板说明的长期知识文件。
-   - CONTEXT 中当前代码、文档和归档均无证据支撑的术语。
-   - LESSONS 中重复、过期、只适用单次任务或已被 RULES/ADR 吸收的经验。
-4. 按 `delete | merge | rewrite | keep | needs-confirmation` 分组输出完整清单；每个候选必须包含来源、证据和风险。
-5. 如果用户没有明确确认，停止在 dry-run 候选清单。
-6. 用户确认后，只执行确认清单中的操作：
-   - 删除文件前再次检查路径仍位于 `speculo/.speculo/.config/`。
-   - 修改 `RULES.md` 前必须确认具体条目；不能批量隐式改规则。
-   - 执行后列出实际改动和跳过项。
+1. 读取 `references/audit-rules.md`，按其中扫描范围与候选类型执行审计。
+2. 如果用户没有明确确认，停止在 dry-run 候选清单。
+3. 用户确认后，按 `references/audit-rules.md`「确认后执行」节操作。
 
 ## 边界
 
 - 不删除仍被代码、文档、归档或 active change 引用的 ADR / CONTEXT。
-- 不把低信号归档内容写回长期知识资产。
-- 不自动解决领域术语冲突；冲突项交给 `../workflows/dev/M-domain-modeling/M-domain-modeling.md`。
-- 不修改 docs-sync state；由 `../workflows/dev/D-docs-sync/D-docs-sync.md` 推进基线。
+- 不自动解决领域术语冲突；冲突项交给 `../../workflows/dev/M-domain-modeling/M-domain-modeling.md`。
+- 不修改 docs-sync state；由 `../../workflows/dev/D-docs-sync/D-docs-sync.md` 推进基线。
 - 不自行选择持久化位置；文件型产物由调用方写入规范路径。
 
 ## 渐进披露
 
-无 `references/`；本 skill 的完整执行规则已在入口中。
+- `references/audit-rules.md`：执行 dry-run 审计或确认后清理时读取。

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

@@ -0,0 +1,38 @@
+# Config Prune 审计规则
+
+dry-run 候选生成与分组规则。`config-prune` skill 入口为调度器，执行审计时读取本文件。
+
+## 扫描范围
+
+1. 读取 `speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`；缺失路径记录为 `missing`，不自动创建。
+2. 扫描当前仓库引用：
+   ```bash
+   rg -n "ADR-[0-9]{4}|[0-9]{4}-[a-z0-9-]+\\.md|CONTEXT|LESSONS|RULES" .
+   ```
+   排除 `node_modules/`、`dist/`、`.git/` 等生成或依赖目录。
+
+## 候选类型
+
+至少包含以下 dry-run 候选：
+
+- 指向不存在 ADR 的正文引用或索引行。
+- 标记为 superseded 且超过 30 天、无活跃引用的 ADR。
+- 只含 `.gitkeep`、TODO、空占位或模板说明的长期知识文件。
+- CONTEXT 中当前代码、文档和归档均无证据支撑的术语。
+- LESSONS 中重复、过期、只适用单次任务或已被 RULES/ADR 吸收的经验。
+
+## 分组输出
+
+按 `delete | merge | rewrite | keep | needs-confirmation` 分组；每个候选必须包含来源、证据和风险。
+
+## 确认后执行
+
+- 删除文件前再次检查路径仍位于 `speculo/.speculo/.config/`。
+- 修改 `RULES.md` 前必须确认具体条目；不能批量隐式改规则。
+- 执行后列出实际改动和跳过项。
+
+## 边界
+
+- 不删除仍被代码、文档、归档或 active change 引用的 ADR / CONTEXT。
+- 术语冲突交给 `../../workflows/dev/M-domain-modeling/M-domain-modeling.md`。
+- docs-sync state 由 `../../workflows/dev/D-docs-sync/D-docs-sync.md` 推进。

package/template/skills/github-npm-ops/references/failure-recovery.md

@@ -124,11 +124,11 @@ git push origin vX.Y.Z
 
 ---
 
-## 与 github-ops skill 的关系
+## 与 github-npm-ops skill 的关系
 
 本文件是发布编排视角下的失败恢复入口；更细粒度的失败案例（如 EUSAGE / E422 / provenance 错误码、package.json 字段错误）见 `troubleshooting-playbook.md`。
 
-| 失败位置 | 看本文件 | 看 github-ops troubleshooting-playbook |
+| 失败位置 | 看本文件 | 看 github-npm-ops troubleshooting-playbook |
 |---------|---------|---------------------------------------|
 | Phase 1–6 编排逻辑层面 | ✅ | ❌ |
 | release.yml 内部步骤的具体错误码 | ❌ | ✅ |

package/template/skills/github-npm-ops/references/issue-pr-triage.md

@@ -70,7 +70,7 @@
 
 **转为 discussion**
 
-> This is more of a usage question than a bug, moving to [Discussions](link) where the community can chime in.
+> This is more of a usage question than a bug, moving to Discussions where the community can chime in.
 
 ### 大批量分诊节奏
 

package/template/skills/github-npm-ops/references/preflight-checklist.md

@@ -14,7 +14,7 @@
 | 5 | gh 仓库权限 | `gh repo view --json viewerCanAdminister` | `viewerCanAdminister == true` 或至少 push 权限 | 联系仓库管理员；或 fork 后申请 PR 流程 |
 | 6 | Node 版本 | `node --version` | ≥ `package.json#engines.node` | `nvm use` / `fnm use` / 升级本机 Node |
 | 7 | 包管理器 | `pnpm --version` (或 `npm` / `yarn`) | 版本 ≥ 仓库 lockfile 隐含版本 | 安装匹配版本；不要随意切换包管理器 |
-| 8 | release.yml 存在 | `test -f .github/workflows/release.yml` | 文件存在 | 转 `github-ops` skill 的 `references/workflow-yaml-reference.md` 先落该文件 |
+| 8 | release.yml 存在 | `test -f .github/workflows/release.yml` | 文件存在 | 转 `github-npm-ops` skill 的 `references/workflow-yaml-reference.md` 先落该文件 |
 | 9 | release.yml 形态 | 见 [publish-detection.md](publish-detection.md) | 输出 `PUBLISH_TO_NPM=true` 或 `false` | 见 publish-detection 文档的判定矩阵 |
 | 10 | docs-sync state | `test -f speculo/.speculo/dev/docs-sync-state.json && jq . speculo/.speculo/dev/docs-sync-state.json` | 解析成功且 `last_sync_sha != null` | 不存在 → 走 `dev/D-docs-sync` workflow 的「首次运行」分支；存在但损坏 → 修复 JSON |
 | 11 | tag 名称冲突 | `git rev-parse vX.Y.Z 2>/dev/null` | 退出码非 0（tag 不存在） | 同 tag 已存在：先确认是否真的失败需要重发；若是则 `git tag -d` + `git push origin :refs/tags/vX.Y.Z`，否则 bump 到下一版本 |
@@ -23,7 +23,7 @@
 
 - 探测项 1–3、6–7：本机环境问题，提示用户人工修复后重跑命令
 - 探测项 4–5：GitHub 权限问题，给出对应的 `gh` 命令
-- 探测项 8：基础设施缺失，明确转交 `github-ops` skill 而不是在本命令里现写 release.yml
+- 探测项 8：基础设施缺失，明确转交 `github-npm-ops` skill 而不是在本命令里现写 release.yml
 - 探测项 9：影响 Phase 5 的分支选择，**不阻塞**命令执行（仅决定后续是否做 npm view 校验）
 - 探测项 10：影响 Phase 2 是否进入 docs-sync 主流程
 - 探测项 11：直接关系到能否打 tag，必须在 Phase 0 阶段就排除
@@ -34,6 +34,6 @@ Phase 0 只做**只读探测**，不调用任何 skill 的 SOP：
 
 - `git-commit-template` skill 只在 Phase 1 被引用
 - `docs-sync` skill 只在 Phase 2 / Phase 6 被引用
-- `github-ops` skill 在 Phase 3 / 4 / 5 被引用
+- `github-npm-ops` skill 在 Phase 3 / 4 / 5 被引用
 
 如果 Phase 0 嗅探到的状态需要某个 skill 的修复 SOP（如 release.yml 缺失），明确转交，不要在本命令内复刻 skill 的内容。

package/template/skills/github-npm-ops/references/release-pipeline.md

@@ -5,7 +5,7 @@
 ## Iron Law
 
 - 禁止提交破坏构建的代码；release 前必须运行仓库声明的 lint / test / build 或等价质量闸。
-- docs-sync 必须由调用方按 `workflows/dev/D-docs-sync/D-docs-sync.md` 执行，基于 `speculo/.speculo/dev/docs-sync-state.json#last_sync_sha..HEAD` 的 git diff。
+- docs-sync 必须由调用方按 `../../../workflows/dev/D-docs-sync/D-docs-sync.md` 执行，基于 `speculo/.speculo/dev/docs-sync-state.json#last_sync_sha..HEAD` 的 git diff。
 - tag 必须精确指向 release commit，即包含 `package.json` version bump 与 CHANGELOG 迁移的 commit；禁止指向后续 docs / state commit。
 - npm 已成功上传后，同一 version 不可重发；不要通过删 tag 或 unpublish 试图覆盖。
 
@@ -32,7 +32,7 @@
 
 ## Phase 2 — Docs Sync
 
-- 由调用方执行 `workflows/dev/D-docs-sync/D-docs-sync.md`。
+- 由调用方执行 `../../../workflows/dev/D-docs-sync/D-docs-sync.md`。
 - 只修改 tracked assets 中需要同步的文档或知识资产。
 - CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
 - 本阶段不推进 docs-sync state 到 release commit；最终基线推进放到 Phase 6。
@@ -88,7 +88,7 @@ npm view "<package-name>" dist-tags
 
 ## Phase 6 — 推进 docs-sync 基线
 
-仅当 Phase 1-5 全绿时执行。本 skill 不自行选择持久化目录；把基线推进交给调用方的 release workflow 或 `workflows/dev/D-docs-sync/D-docs-sync.md`，只向其提供以下取值：
+仅当 Phase 1-5 全绿时执行。本 skill 不自行选择持久化目录；把基线推进交给调用方的 release workflow 或 `../../../workflows/dev/D-docs-sync/D-docs-sync.md`，只向其提供以下取值：
 
 - `last_sync_sha` 推进到 `RELEASE_COMMIT_SHA`。
 - `previous_sync_sha` 使用推进前的 `last_sync_sha`。

package/template/skills/handoff/SKILL.md

@@ -2,7 +2,7 @@
 id: handoff
 type: skill
 name: Handoff
-description: 将当前对话压缩成交接文档；当用户需要另一个 agent、另一个会话或 command/handoff 接手继续工作时使用。
+description: 将当前对话压缩成脱敏交接正文与元数据；当用户需要另一个 agent、另一个会话或 command/handoff 接手继续工作时使用。
 ---
 
 # Handoff
@@ -22,29 +22,52 @@ description: 将当前对话压缩成交接文档；当用户需要另一个 age
 
 ## 输出
 
-- 保存到规范命令产物目录的脱敏交接文档：`speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`
-- 文档路径、主题目录名和命名依据
+- 脱敏交接正文（Markdown），供调用方写入规范命令产物目录
+- 建议的 `<topic>` 目录名（kebab-case）与命名依据
 - 3-5 条极简摘要
 - 推荐技能清单
 
-## 命名与位置
+**本 skill 不自行创建目录、不写盘。** 持久化由 `commands/handoff.md` 独占负责。
+
+## 命名建议
 
-- 交接文档必须写入调用方命令产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
 - `<YYYY-MM-DD>` 使用当前日期。
 - `<topic>` 从用户目标、项目名、变更名或下一次会话重点提取，使用小写 kebab-case；无法判断时使用 `session`。
-- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
-- 禁止写入 `temp/`、系统临时目录、仓库根目录临时文件或其他非 Speculo 规范位置。
+- 安装后的目标路径为 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/handoff.md`。
 
 ## 执行步骤
 
 1. 收集当前目标、背景、已做工作、关键文件、验证结果、剩余风险和下一步。
 2. 删除 API key、密码、token、个人身份信息和其他敏感内容。
 3. 不复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文；改用路径、URL 或 commit 引用。
-4. 添加 `推荐技能` 部分，列出下一个 agent 应优先读取或调用的技能。
-5. 创建 `speculo/.speculo/commands/<YYYY-MM-DD>-handoff-<topic>/`，并把交接文档写入其中的 `handoff.md`。
-6. 返回文档路径、主题目录名、3-5 条极简摘要和推荐技能清单。
+4. 添加 `## 推荐技能` 部分，列出下一个 agent 应优先读取或调用的 skill。
+5. 按下方结构组织脱敏正文，连同 `<topic>` 建议、摘要和推荐技能清单返回给调用方。
+
+## 正文结构
+
+```markdown
+# Handoff
+
+## 目标
+[概括当前任务目标和用户下一步重点。]
+
+## 已完成
+[列出已完成工作、关键决策和重要文件路径。]
+
+## 未完成
+[列出下一步、阻塞点和剩余风险。]
+
+## 验证
+[记录已运行命令、结果和未运行原因。]
+
+## 推荐技能
+[列出下一个 agent 推荐读取的 skill。]
+
+## 摘要
+[用 3-5 条概括交接内容，不复制敏感信息。]
+```
 
 ## references/ 与 scripts/
 
 - 无 `references/` 子文档；该 skill 的完整执行规则在本入口中。
-- 无 `scripts/`；直接按本文件步骤整理和写入交接文档。
+- 无 `scripts/`；直接按本文件步骤整理交接正文并返回。

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

@@ -34,7 +34,7 @@
 | Skill 目录（如 `caveman/`） | 框架资产，非运行时产物 |
 | Command 文件（如 `archive.md`） | 框架资产，非运行时产物 |
 | 模板文件（`_templates/`） | 框架资产，非运行时产物 |
-| `.config/`、`adr/`、`context/` | 项目配置目录 |
+| `.config/`、`adr/`、`context/` | 项目配置目录，非产物目录 |
 
 ### 反例
 
@@ -60,10 +60,56 @@
 | 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`。
+`<cat>` 只能是 `dev`、`doc`、`person`。`ops` 是预留分类，只有骨架和 workflow 分类同时落地后才能加入枚举。
 
 命令产生的持久化报告、快照、handoff 和一次性操作记录必须统一写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd-name>-<topic>/`。`temp/`、系统临时目录和项目根目录只允许作为不保留的执行中间位置，禁止作为 Speculo 持久化产物位置。
 
+## Change 初始化铁律
+
+> ⚠️ **每个 change 目录创建时必须同时完成以下三项写入，缺一不可。未完成初始化的 change 视为 `broken-change`，`status` 与 `archive` 命令将报告并跳过。**
+
+### 初始化顺序
+
+按以下顺序原子执行，前一步失败时停止后续并报告：
+
+1. **创建 change 目录** —— `speculo/.speculo/<cat>/<YYYY-MM-DD>-<kebab-name>/`。
+2. **写入 `.status.json`** —— 在 change 目录下创建 `.status.json`，填入最小必填字段。
+3. **更新 `<cat>-status.json`** —— 在 `speculo/.speculo/<cat>-status.json` 的 `active[]` 中追加该 change 的索引条目。
+
+### `.status.json` 最小初始化模板
+
+```jsonc
+{
+  "name": "<YYYY-MM-DD>-<kebab-name>",
+  "category": "dev | doc | person",
+  "change_status": "active",
+  "execution_mode": "待 workflow 首次进入时填写",
+  "created_at": "<ISO 8601，当前时间>",
+  "updated_at": "<ISO 8601，与 created_at 相同>",
+  "current_phase": "00-init",
+  "phase_history": [
+    {
+      "phase": "00-init",
+      "entered_at": "<ISO 8601>",
+      "completed_at": "<ISO 8601>",
+      "status": "completed"
+    }
+  ]
+}
+```
+
+### `<cat>-status.json` 追加条目模板
+
+```jsonc
+{
+  "name": "<YYYY-MM-DD>-<kebab-name>",
+  "current_phase": "00-init",
+  "updated_at": "<ISO 8601>"
+}
+```
+
+`active[]` 支持同分类多 change 并发。创建 change 时必须逐项确认目录名、`.status.json`、索引条目和时间戳均已写入。
+
 ## `.status.json` 元字段（框架强制）
 
 每个 change 的状态写在 `speculo/.speculo/<cat>/<change>/.status.json`：
@@ -71,7 +117,7 @@
 ```jsonc
 {
   "name":           "string, change 目录名",
-  "category":       "string, dev | doc | person | ops",
+  "category":       "string, dev | doc | person",
   "change_status":  "string, active | completed | archived",
   "execution_mode": "string, 由 workflow 自治声明的命名预设",
   "created_at":     "string, ISO 8601",
@@ -82,13 +128,15 @@
       "phase":        "string, phase id",
       "entered_at":   "string, ISO 8601",
       "completed_at": "string|null, ISO 8601",
-      "status":       "string, pending | in-progress | completed | skipped | revisited"
+      "status":       "string, pending | in-progress | completed | skipped | revisited | blocked"
     }
   ]
 }
 ```
 
-workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行者写入**同一份** `.status.json`，不另开文件。
+workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行者写入**同一份** `.status.json`，不另开文件。`current_phase` 必须使用 workflow 入口声明的稳定机器 id（kebab-case），不是人类可读标题。首个 workflow 进入 change 时必须写入 `execution_mode`。
+
+`change_status: completed` 只允许负责最终交付边界的收尾 workflow（当前为 `dev/04-finalize`）写入；`change_status: archived` 只允许 `archive` 命令或收尾 workflow 的归档步骤写入。其他 workflow 只能维护自己的扩展字段。
 
 ## 顶层索引 schema（薄）
 
@@ -101,6 +149,7 @@ workflow 自治字段在入口正文 `## 状态扩展字段` 声明，由执行
 }
 ```
 
+- Change 创建时**必须**在 `active[]` 追加索引条目。
 - 归档后变更**必须从 active 段移除**。
 - 索引可重建：扫 `speculo/.speculo/<cat>/*/.status.json` 即可重建。
 - 全局 `STATUS.json` **不物理存在**。
@@ -112,7 +161,7 @@ Frontmatter **仅承载发现元数据**（这是什么、叫什么、关于什
 ```yaml
 # workflow
 id: <category>/<name>   # 必填，全局唯一
-category: dev|doc|person|ops   # 必填
+category: dev|doc|person       # 必填；ops 为预留分类，未在模板骨架落地
 name: <人类可读名>       # 必填
 description: <一句话>    # 必填
 keywords: [...]         # 可选
@@ -138,7 +187,6 @@ description: <一句话>    # 必填
 ```markdown
 > **服务工作流：** `<相对路径>`
 > **产物文件名：** `<filename>`
-> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
 # <标题>
 
@@ -176,6 +224,35 @@ description: <一句话>    # 必填
 
 项目级长期资料放 `speculo/.speculo/.config/`（`RULES.md`、`LESSONS.md`、`context/`、`adr/`），不要新增项目根 state 文件。
 
+## Workflow Agents
+
+当 workflow 的 phase 适合隔离执行、并行审查或反自证验证时，可在该 workflow 目录下创建：
+
+```text
+template/workflows/<cat>/<entry>/agents/<name>-agent.md
+```
+
+Agent 文件是框架资产，不是运行时产物；frontmatter 最小集为：
+
+```yaml
+---
+id: <cat>/<entry>/<agent-name>
+type: agent
+name: <人类可读名>
+description: <一句话说明该 agent 何时用于隔离执行>
+---
+```
+
+正文必须包含：
+
+- `## 使命`：单一 phase 或审查轴。
+- `## 输入契约`：当前 change 路径、`current_phase`/`phase-id`、上游产物。
+- `## 执行规范`：用相对路径引用同目录 phase 文件、模板、skill；不得复制大段规范正文。
+- `## 产物与状态`：产物路径和 `.status.json` 扩展字段写入责任。
+- `## 边界`：不越过本 phase、不改无关文件、不写 `change_status`。
+
+Workflow 入口若提供 agents，必须在 `## 阶段` 中列出对应 agent 相对路径。Agent 只可写它声明的 phase 产物和状态扩展字段；最终 `change_status` 仍由收尾 workflow 或 `archive` 命令负责。
+
 ## 命名校验清单
 
 ### 创建时
@@ -184,6 +261,8 @@ description: <一句话>    # 必填
 - [ ] command 产物目录名匹配 `^\d{4}-\d{2}-\d{2}-[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$`
 - [ ] 日期部分使用**当前日期**（`YYYY-MM-DD`）
 - [ ] `<kebab-name>` 从用户意图中提取
+- [ ] `.status.json` 已写入且包含全部最小必填字段
+- [ ] `<cat>-status.json` 的 `active[]` 已追加索引条目
 
 ### 扫描时
 

package/template/skills/speculo-write/references/workflow-authoring-sop.md

@@ -4,7 +4,7 @@ phase 的切分、完成准则与措辞遵循 `authoring-quality-levers.md` 的
 
 ## 入口结构
 
-workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`person`、`ops`。
+workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`person`。`ops` 是预留分类，只有 `.speculo` 骨架和 workflow 分类同时落地后才能启用。
 
 目录和入口文件必须同名：
 
@@ -41,10 +41,12 @@ keywords: [<关键词>]
 
 阶段条目必须写清：
 
+- 稳定 phase id（kebab-case，用于 `current_phase`）
 - 规范 phase 文件
 - 模板路径
 - 产物文件名
 - 完成准则
+- 可选 agent 文件（若该 phase 支持隔离执行）
 
 ## Phase 文件
 
@@ -58,6 +60,35 @@ phase 文件不需要 frontmatter。每个 phase 文件写清：
 
 phase 文件只放该阶段执行所需内容，不重复入口文件的全局说明。
 
+## Workflow Agents
+
+适合隔离执行、并行审查或反自证验证的 phase 可以创建：
+
+```text
+template/workflows/<cat>/<entry>/agents/<name>-agent.md
+```
+
+Agent 文件需要 frontmatter：
+
+```yaml
+---
+id: <cat>/<entry>/<agent-name>
+type: agent
+name: <人类可读名>
+description: <一句话说明该 agent 何时用于隔离执行>
+---
+```
+
+正文必须包含：
+
+- `## 使命`
+- `## 输入契约`
+- `## 执行规范`
+- `## 产物与状态`
+- `## 边界`
+
+Agent 引用同目录 phase 文件、模板和 skill，不复制大段规范正文。Agent 只可写它声明的 phase 产物和 `.status.json` 扩展字段，不写 `change_status`。入口 `## 阶段` 必须列出对应 agent 相对路径。
+
 ## 模板
 
 模板放在：
@@ -112,6 +143,8 @@ speculo/.speculo/.config/adr/
 
 不要把新状态放到项目根目录。`.status.json` 元字段、顶层索引 schema 和写入责任表见 `persistence-contract-sop.md`。
 
+`current_phase` 使用入口 `## 阶段` 声明的稳定 phase id；首个 workflow 进入 change 时写入 `execution_mode`。只有收尾 workflow 或 `archive` 命令可写 `change_status: completed | archived`，普通 workflow 只写自治状态字段。
+
 ## 索引与文档同步
 
 新增 workflow 后检查：

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

@@ -32,7 +32,7 @@ PRD 只写入 `speculo/.speculo/dev/<change>/prd.md`，overview 只写入 `specu
 
 ### 1. Zoom Out — 全景理解
 - 规范：`prd-zoom-out.md`
-- 模板：`../_templates/prd-overview-template.md`
+- 模板：`../_templates/overview-template.md`
 - 产物：`overview.md`
 - 完成准则：
   - 已说明相关模块、调用者、边界和未知点

package/template/workflows/dev/02-prd/prd-zoom-out.md

@@ -8,7 +8,7 @@
 
 ## 产物
 
-- `speculo/.speculo/dev/<change>/overview.md`，由 `../_templates/prd-overview-template.md` 填写
+- `speculo/.speculo/dev/<change>/overview.md`，由 `../_templates/overview-template.md` 填写
 
 ## 填写引导