@namewta/speculo 0.2.15 → 0.3.0

package/template/canonical/canonical-specdev-wayfinder.md

@@ -1,30 +1,28 @@
 # 寻路
 
+> **配套上传建议**：本能力跨引用「设计访谈（带文档）」的访谈协议与领域建模规程。若在网页 AI 平台使用，建议同时上传 `canonical-specdev-grill-with-docs.md`。仓库：https://github.com/NAMEWTA/Speculo
+
 一个模糊的想法出现了 —— 太大而无法放入单个 agent 会话，且笼罩在迷雾中：从当前状态到**目标**的路径尚不可见。寻路（Wayfinding）就是找到那条路，而非冲向目标。此 work 在变更目录中绘制路径作为一张**共享地图**，然后逐个处理其 tickets，直到路径变得清晰。
 
 目标因工作而异，命名目标是绘制地图的第一步 —— 它塑造每个 ticket。目标可能是一份待移交和迭代的 spec、一个在规划开始前需锁定的决策、或是一个原地完成的变更（如数据结构迁移）。地图是领域无关的 —— 工程工作、课程内容，任何符合此形态的内容都可以。
 
 ## 规划，而非执行
 
-Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其 **Notes** 覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
+Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其「说明」章节覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
 
 ## 用名称引用
 
-每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的 Decisions-so-far —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
+每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的「已做出的决策」 —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
 
-在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的 Decisions-so-far 中以 `- [ticket 标题] —— 答案概括` 形式索引。
+在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的「已做出的决策」中以 `- [ticket 标题] —— 答案概括` 形式索引。
 
 ## 地图
 
-地图是变更目录下的单个 markdown 文件 ``map``，是规范的产物。其 tickets 是地图内的 task list items（`- [ ]` 格式）。如果工作范围跨多个变更，地图位于主变更目录下。
+地图是变更目录下的单个 markdown 文件 map.md，是规范的产物。其 tickets 是地图内的 task list items（`- [ ]` 格式）。如果工作范围跨多个变更，地图位于主变更目录下。
 
 地图是一个**索引**，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。
 
-**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞关系通过"被阻塞于"字段声明，以 ticket 标题引用。
-
-**前沿查询：** 前沿上的 tickets 是指：checkbox 未勾选（开放）、其"被阻塞于"中列出的所有 tickets 均已勾选（无阻塞）、且尚未被领取的 tickets。Agent 通过阅读地图文件本身即可识别前沿。
-
-**领取机制：** 当一个 agent 会话开始处理某个 ticket 时，它应在 `specdev/status.json` 的 `active` 数组中记录当前处理的 ticket 名称，以便并发会话跳过它。处理完成后从 `active` 中移除。`active` 中存在记录即为领取标记。
+**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞、领取与前沿的定义见下方「Tickets」节。
 
 ### 地图正文
 
@@ -84,19 +82,19 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 每个 ticket 携带一个类型标签 —— 以下之一：`research`、`prototype`、`grilling`、`task`（参见下方 [Ticket 类型](#ticket-类型)）。
 
-**领取机制：** 一个会话通过将其名称写入 `specdev/status.json` 的 `active` 数组来**领取**一个 ticket，在开始任何工作**之前**领取，以便并发会话跳过它。该记录*就是*领取标记：一个开放、未被领取的 ticket 是未被领取的。
+**领取机制：** 一个会话通过将其名称追加到 `specdev/status.json` 的当前 change 的 `active` 条目中的 `claimed_tickets` 数组来**领取**一个 ticket，在开始任何工作**之前**领取，以便并发会话跳过它。该记录*就是*领取标记：一个开放、未被领取的 ticket 是未被领取的。
 
 **阻塞关系：** 使用 ticket 标题在"被阻塞于"字段中声明依赖。这很关键，因为它使前沿在地图文件中*可视化*呈现 —— 人类无需额外工具就能看到哪些可以开始。当一个 ticket 的所有阻塞 tickets 都已勾选（已解决）时，该 ticket 是**未被阻塞的**；**前沿**是开放（未勾选）、未被阻塞、未被领取的 tickets —— 即已知的边界。
 
-**答案：** 不是正文的一部分 —— 它在解决时写入 ticket 的"答案"小节（参见[遍历地图](#遍历地图)）。解决 ticket 时创建的资产从 ticket 小节链接，而非粘贴进去。如果资产是文件，放置在 `specdev/changes/{change}/` 下，从 ticket 链接。
+**答案：** 不是正文的一部分 —— 它在解决时写入 ticket 的"答案"小节（参见[遍历地图](#遍历地图)）。解决 ticket 时创建的资产从 ticket 小节链接，而非粘贴进去。如果资产是文件，放置在变更目录下，从 ticket 链接。
 
 ## Ticket 类型
 
 每个 ticket 要么是 **HITL** —— 人在回路中，与一个代表自己发言的人类*一起*工作 —— 要么是 **AFK**，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。
 
-- **Research**（AFK）：阅读文档、第三方 API 或知识库等本地资源。创建一个 markdown 摘要作为链接资产。当需要当前工作目录之外的知识时使用。
-- **Prototype**（HITL）：通过制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
-- **Grilling**（HITL）：通过 ``grilling-protocol`` 访谈协议逐个问题进行对话。同时使用 ``domain-modeling-rules`` 维护领域模型。默认情况 —— 当不确定类型时选此。
+- **Research**（AFK）：调用 common/research skill 启动后台 Agent 针对一手来源调查问题，在 ticket 的答案中链接研究产出文件。当需要当前工作目录之外的知识时使用。
+- **Prototype**（HITL）：调用 common/prototype skill 制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
+- **Grilling**（HITL）：通过设计访谈（G-grill-with-docs）的访谈协议逐个问题进行对话。同时使用其领域建模规程维护领域模型。默认情况 —— 当不确定类型时选此。
 - **Task**（HITL 或 AFK）：在*决策*能够做出之前必须完成的手动工作 —— 没有需要决定、原型化或研究的内容，但讨论被阻塞直到完成。注册服务以便判断其 API、开通访问权限、移动数据以便看到其形态。这是唯一一个*执行*而非决策的类型 —— 它通过为决策解除阻塞来赢得其位置，而非通过交付目标。Agent 在可能的情况下独立驱动（AFK）；否则它交给人类一份精确的清单（HITL）。当工作完成时解决；答案记录已完成的工作以及后续 tickets 依赖的任何结果性事实（凭据位置、新 URL、行数）。
 
 ## 战争迷雾
@@ -110,7 +108,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 - **做成 ticket 当** 问题已经清晰 —— 即使它被阻塞，你尚不能行动。你能写出明确的"问题"段落。
 - **尚未明确当** 你还无法如此精确地表述它。不要将迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗糙，一个补丁可能在当前沿到达时升级为多个 tickets，或零个。
 
-**尚未明确**排除已决策的内容（Decisions-so-far）、已有的活跃 ticket 以及超出范围的内容（下一节）。
+**尚未明确**排除已决策的内容（「已做出的决策」）、已有的活跃 ticket 以及超出范围的内容（下一节）。
 
 ## 超出范围
 
@@ -128,7 +126,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 用户带着模糊的想法调用。
 
-1. **命名目标。** 运行一次 ``G-grill-with-docs`` 访谈会话，以确定此地图正在寻路的目标 —— spec、决策或变更。目标确定了范围，因此先确定它。使用 ``grilling-protocol`` 进行访谈，使用 ``domain-modeling-rules`` 维护领域模型。
+1. **命名目标。** 运行一次设计访谈（G-grill-with-docs）会话，以确定此地图正在寻路的目标 —— spec、决策或变更。目标确定了范围，因此先确定它。使用其访谈协议进行访谈，使用其领域建模规程维护领域模型。
 
    **完成标准**：目标已命名，范围边界已确定。
 
@@ -136,9 +134,9 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
    **完成标准**：前沿的开放决策和第一步已浮现；迷雾部分已识别并草拟。
 
-3. **创建地图**：写入 ``map``，填写 Destination 和 Notes，Decisions-so-far 为空，迷雾草拟进**尚未明确**。
+3. **创建地图**：写入变更目录下的 map.md，填写「目的地」和「说明」，「已做出的决策」为空，迷雾草拟进**尚未明确**。
 
-   **完成标准**：地图文件已创建，Destination、Notes、尚未明确、超出范围均已填写。
+   **完成标准**：地图文件已创建，目的地、说明、尚未明确、超出范围均已填写。
 
 4. **创建你现在能明确的 tickets** 作为地图文件内的小节 —— 然后在**第二遍**中连接阻塞边（tickets 需要首先有标题才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— **尚未明确**章节。
 
@@ -150,21 +148,21 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 用户带着一张地图（变更目录或 map.md 路径）调用。Ticket 是**可选的** —— 不提供时，你选择下一个决策，而非用户。
 
-1. **加载地图** —— 低分辨率视图（Destination、Notes、Decisions-so-far、尚未明确、超出范围），而非每个 ticket 的完整正文。
+1. **加载地图** —— 低分辨率视图（目的地、说明、已做出的决策、尚未明确、超出范围），而非每个 ticket 的完整正文。
 
    **完成标准**：地图的低分辨率视图已加载，当前状态已理解。
 
-2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket（开放、未被阻塞、未被领取）。**领取它**：在任何工作之前将 ticket 名称写入 `specdev/status.json` 的 `active` 数组。
+2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket。**领取它**（规则见上方「Tickets」节）。
 
    **完成标准**：一个前沿 ticket 已被选中并领取。
 
-3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用 Notes 块中指定的技能。如有疑问，使用 ``G-grill-with-docs`` 进行访谈。查阅 ``domain-modeling-rules`` 维护领域模型的一致性。
+3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用「说明」中指定的技能。根据 ticket 类型选择解决方式：**research** 调用 common/research skill；**grilling** 使用设计访谈（G-grill-with-docs）；**prototype** 调用 common/prototype skill；**task** 按问题描述执行。查阅设计访谈的领域建模规程维护领域模型。
 
    **完成标准**：ticket 的问题已解决，答案已记录。
 
-4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的 Decisions-so-far 中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `specdev/status.json` 的 `active` 数组中移除该 ticket。
+4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的「已做出的决策」中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `claimed_tickets` 中移除该 ticket（规则见上方「Tickets」节）。
 
-   **完成标准**：ticket checkbox 已勾选，Decisions-so-far 已更新，active 数组已清理。
+   **完成标准**：ticket checkbox 已勾选，「已做出的决策」已更新，领取标记已清除。
 
 5. **添加新浮现的 tickets** 作为地图文件内新的小节（先创建再连接阻塞边）；升级答案使任何变得可明确的迷雾，从**尚未明确**中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，**将其裁定为超出范围**而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets（勾选并注明无效原因）。
 
@@ -177,7 +175,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 当所有 tickets 已关闭（勾选）、迷雾已清空（尚未明确为空或仅剩无法继续分解的模糊项）、且通往目标的路径已清晰时，地图完成。向用户汇报：
 
 - 目的地是否已可抵达——路径上的每个步骤是否都已有明确的 ticket 或决策
-- Decisions-so-far 中的关键结论摘要
+- 「已做出的决策」中的关键结论摘要
 - 剩余的任何**尚未明确**项——它们是否阻碍行动，还是可作为实现细节处理
 - 建议的下一步行动（移交实现、开始执行、或重新划定目标）
 
@@ -187,14 +185,14 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 ## 子文件引用
 
-本入口为单文件 work，所有内容均已内联。以下引用供 work 内各阶段加载：
+本入口为单文件 work，所有内容均已内联。以下引用供 work 内各阶段加载（跨 workflow，不内联——建议配套上传设计访谈 canonical 文档）：
 
 | 文件 | 触发条件 |
 |------|----------|
-| ``G-grill-with-docs`` | 需要访谈以命名目标或解决 grilling 类型 ticket |
-| ``grilling-protocol`` | 进入具体访谈——一次一问，决策树遍历 |
-| ``domain-modeling-rules`` | 维护领域模型——术语精炼、决策记录 |
-| ``map`` | 地图持久化文件 |
+| 设计访谈（G-grill-with-docs）主入口 | 需要访谈以命名目标或解决 grilling 类型 ticket |
+| 设计访谈的访谈协议（grilling-protocol） | 进入具体访谈——一次一问，决策树遍历 |
+| 设计访谈的领域建模规程（domain-modeling-rules） | 维护领域模型——术语精炼、决策记录 |
+| 变更目录下的 map.md | 地图持久化文件 |
 
 状态追踪：
-- `specdev/status.json` —— `active` 数组记录当前领取的 ticket
+- `specdev/status.json` —— `active` 条目中的 `claimed_tickets` 数组记录当前领取的 ticket

package/template/commands/archive-and-consolidate.md

@@ -3,8 +3,8 @@ id: archive-and-consolidate
 type: command
 name: Archive and Consolidate
 description: >
-  归档已完成 change，从归档中提取知识合并到 _state/ 知识 store（ADR/、CONTEXT.md、DOMAIN.md、LESSONS.md、RULES.md），
-  并清理过时/重复知识。默认 dry-run，需用户确认后执行。取代 finalize 和 knowledge-prune 的归档与清理能力。
+  归档已完成 change，从归档中提取知识合并到 workflow 声明的知识 store（如 adr/、context/），
+  并清理过时/重复知识。默认 dry-run，需用户确认后执行。
 keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并, 清理, 收尾]
 ---
 
@@ -12,7 +12,7 @@ keywords: [archive, consolidate, knowledge, cleanup, adr, 归档, 知识合并,
 
 ## 报告
 
-统一写入：`speculo/.speculo/commands/archive-and-consolidate/<YYYY-MM-DD>-<workflow>-<scope>[-NN].md`。
+统一写入：`speculo/.speculo/commands/archive-and-consolidate/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
 
 报告必须记录：`mode`（dry-run 或 executed）、选中的 workflow、归档计划、合并计划、清理候选、用户确认状态和最终结果。
 

package/template/commands/docs-sync.md

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

package/template/commands/handoff.md

@@ -1,6 +1,9 @@
 ---
+id: handoff
+type: command
 name: handoff
 description: 将当前对话压缩为一份交接文档，供另一个 agent 接手继续工作。
+keywords: [handoff, 交接, 移交, 上下文压缩]
 argument-hint: "下一个会话将用于什么？"
 disable-model-invocation: true
 ---
@@ -20,8 +23,7 @@ speculo/.speculo/commands/handoff/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
 - **<topic>** — 从交接范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
 - **[-NN]** — 同日同 scope 同 topic 的多份报告，从 `-01` 开始递增；仅首份可省略后缀。
 
-> [!CAUTION]
-> **禁止**将命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+- 禁止将命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
 
 ## 内容要求
 
@@ -32,3 +34,15 @@ speculo/.speculo/commands/handoff/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
 清除任何敏感信息，如 API 密钥、密码或个人身份信息。
 
 如果用户传入了参数，将其视为对下一个会话重点内容的描述，并据此定制文档。
+
+## 路径引用规范
+
+文档中所有文件/文件夹引用必须使用**项目根目录**的相对路径。
+
+- ✅ `src/modules/auth/`
+- ✅ `scripts/migrate/2024-add-index.sql`
+- ✅ `speculo/.speculo/specdev/changes/<YYYY-MM-DD>-<topic>/spec.md`
+- ❌ `../../specdev/changes/...` — 相对于 handoff 文件，脱离目录后不可定位
+- ❌ `auth` — 裸名，无法判断是目录/文件/子模块
+
+例外：skills 名称属于逻辑标识而非文件路径，不适用此规则。

package/template/commands/retro.md

@@ -8,9 +8,7 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 
 # Retro 命令
 
-⚠️ **本命令在最后一步会通过 `gh` 向外部仓库创建 issue（外部写操作）。AI 必须先列出将要创建的 issue 清单与目标仓库并征求用户确认，确认前只输出计划，不调用 `gh`。**
-
-🔒 **目标仓库已写死：`NAMEWTA/Speculo`。** 本命令专为 Speculo 框架自身反馈而设计。不论 retro 在哪个项目仓库中被激活，issue 一律提交到 `NAMEWTA/Speculo`。不允许用户或 AI 覆盖此目标仓库。
+**外部写操作 + 目标仓库写死。** 本命令最后一步会通过 `gh` 向 `NAMEWTA/Speculo` 创建 issue——不论在哪个项目仓库中激活，目标仓库一律不可覆盖。确认前只输出计划，不调用 `gh`。
 
 ## 归档路径模式
 
@@ -30,11 +28,10 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
 1. 读取 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json` 与 `speculo/.speculo/workspace.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及各 `INDEX.md` 声明的知识 store。
 2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
 3. 创建 command 专属目录 `speculo/.speculo/commands/retro/`，把复盘结论写入带 scope 的 Markdown 报告。
-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 链接清单。
+4. **去重**：读取 `../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`，仅当用户明确要求才补提。
+5. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标仓库 `NAMEWTA/Speculo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
+6. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo NAMEWTA/Speculo --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
+7. 把每条提案的最终 issue 编号/URL 回写进本次报告的「提交结果」小节；返回报告路径、3-5 条复盘摘要和已创建 issue 链接清单。
 
 ## 产物模板
 
@@ -66,7 +63,7 @@ generated_at: [TODO: ISO-8601]
 [TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
 
 ## 目标仓库
-`NAMEWTA/Speculo`（写死，不可覆盖）
+`NAMEWTA/Speculo`
 
 ## 用户确认记录
 [TODO: 记录用户对 issue 清单的确认原文摘要。]

package/template/commands/status.md

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

package/template/skills/agents-md-builder/references/claude-redirect.md

@@ -2,17 +2,19 @@
 
 ## 规则
 
-每个 manifest 目录的 `CLAUDE.md` **有且只有一行**：
+每个 manifest 目录的 `CLAUDE.md` 是轻量重定向文件，内容固定为：
 
 ```
-读取同层级的AGENTS.md文档。
+# CLAUDE.md
+
+Speculo agent handbook: see [AGENTS.md](./AGENTS.md).
 ```
 
+此格式与 `../../docs-sync/references/agents-contract.md` 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是入口指针。
+
 ## 设计缘由
 
 - Claude Code 会读取 `CLAUDE.md` 获取项目/模块级指令。
-- 如果 `CLAUDE.md` 已有内容，不应覆盖。
-- 如果 `CLAUDE.md` 不存在，生成一行重定向。
 - 内容全部在 `AGENTS.md` 中，`CLAUDE.md` 只是入口指针。
 - 零维护成本：`AGENTS.md` 更新时不需要同步 `CLAUDE.md`。
 
@@ -20,8 +22,8 @@
 
 - 目录有 manifest 文件 → 生成 `CLAUDE.md`
 - 目录是 scripts-docs → 生成 `CLAUDE.md`
-- 目录已有 `CLAUDE.md` 且内容 > 1 行 → **不覆盖**，汇报用户
-- 目录已有 `CLAUDE.md` 且内容 = 1 行重定向 → 可覆盖（保持最新）
+- 目录已有多行非重定向 `CLAUDE.md` → 向用户确认后改写为重定向，原内容全量迁移到 `AGENTS.md`（处置与 agents-contract 一致）
+- 目录已有重定向 `CLAUDE.md` → 可覆盖（保持最新格式）
 
 ## 不生成 CLAUDE.md 的目录
 
@@ -32,12 +34,6 @@
 
 ## 文件格式
 
-```
-读取同层级的AGENTS.md文档。
-```
-
-- 无 frontmatter
-- 无标题
-- 无额外内容
-- 无换行（只有一行文本）
+- 三行：`# CLAUDE.md` 标题、空行、一句英文重定向
+- 无 frontmatter、无额外内容
 - 文件以换行符结尾（POSIX 约定）

package/template/skills/agents-md-builder/references/manifest-discovery.md

@@ -54,12 +54,7 @@
 
 1. **确定扫描起点**：`scan_root = root / target_subdir`，若未指定则为 `root`。
 2. **递归遍历**：从 `scan_root` 递归遍历所有子目录。
-3. **跳过忽略目录**：以下目录不进入、不扫描、不处理：
-   - `.git`、`node_modules`、`dist`、`target`、`.turbo`
-   - `coverage`、`__pycache__`、`.idea`、`.vscode`
-   - `build`、`out`、`.next`、`.nuxt`
-   - `vendor`、`bower_components`
-   - 任何在 `.gitignore` 中且非被跟踪的目录
+3. **跳过忽略目录**：见文末「忽略目录完整清单」；另跳过任何在 `.gitignore` 中且非被跟踪的目录。
 4. **检测 manifest**：对每个非忽略目录，检查是否存在任何 manifest 文件。
 5. **选择主 manifest**：按优先级选择。
 6. **应用过滤**：若用户指定了 `manifest_filter`，仅保留匹配该类型的目录。

package/template/skills/agents-md-builder/references/role-classification.md

@@ -19,8 +19,6 @@
 - 路径等于 `scan_root`
 - 通常包含 `.git`、顶层 CI 配置、workspace 声明等
 
-**模板**：`templates/repo-root-AGENTS.md`
-
 ### 优先级 2：`scripts-docs`
 
 **判定条件**：目录是特批的脚本/文档目录。
@@ -35,8 +33,6 @@
 - 必须显式说明“这是特批文档例外，不是 manifest 模块”
 - 必须区分“可执行脚本”“SQL 资产”“配置模板”“运行时数据目录”
 
-**模板**：`templates/scripts-docs-AGENTS.md`
-
 ### 优先级 3：`aggregator`
 
 **判定条件**：manifest 声明了子模块、子项目或 workspace 成员。
@@ -60,8 +56,6 @@
 - 必须写清“哪些问题必须进入哪个子模块继续调查”
 - 聚合层只说编排，不展开子模块实现
 
-**模板**：`templates/aggregator-AGENTS.md`
-
 ### 优先级 4：`runnable-app`
 
 **判定条件**：无子模块声明，但有明确的运行入口。
@@ -85,8 +79,6 @@
 - 必须写清内部依赖模块如何接入到当前应用
 - 不改写成叶子模块的膨胀版
 
-**模板**：`templates/runnable-app-AGENTS.md`
-
 ### 优先级 5：`contract-module`
 
 **判定条件**：无子模块、无运行入口，主要职责是暴露类型、契约、配置或依赖约束。
@@ -108,8 +100,6 @@
 - 没有 `src/` 时，显式说明这是约束层而非实现层
 - 不要误写成运行时代码模块
 
-**模板**：`templates/contract-module-AGENTS.md`
-
 ### 优先级 6：`capability-module`
 
 **判定条件**：以上都不匹配的其余所有 manifest 目录。
@@ -125,8 +115,6 @@
 - 必须写清内部依赖与上游消费方
 - 区分它是更偏能力模块、业务模块还是集成模块
 
-**模板**：`templates/capability-module-AGENTS.md`
-
 ## 角色判定流程图
 
 ```

package/template/skills/archive-and-consolidate/SKILL.md

@@ -119,7 +119,7 @@ description: >
 3. 显式标注所有破坏性动作（移动、删除、改写）。
 4. 报告摘要：待归档 change 数、待合并知识项数、待清理候选数、需确认项数。
 5. 呈现给用户并显式声明：**"未修改任何文件。此为 dry-run 计划，请确认后执行。"**
-6. dry-run 到此完成；调用方负责将报告写入 `commands_root/archive-and-consolidate/<YYYY-MM-DD>-<workflow>-<scope>[-NN].md`。
+6. dry-run 到此完成；调用方负责将报告写入 `commands_root/archive-and-consolidate/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`（`<scope>` 为目标 workflow 名，`<topic>` 为 change 名或 `batch`）。
 
 ### Step 7：执行已确认动作
 

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

@@ -20,7 +20,7 @@
 
 ## AGENTS 与 CLAUDE
 
-- **铁律：`AGENTS.md` 始终是唯一的权威代理手册。`CLAUDE.md` 永远只能是轻量重定向文件，内容固定为：**
+- `AGENTS.md` 是唯一的权威代理手册；`CLAUDE.md` 只能是轻量重定向，内容固定为：
 
   ```
   # CLAUDE.md
@@ -28,9 +28,9 @@
   Speculo agent handbook: see [AGENTS.md](./AGENTS.md).
   ```
 
-- 无论项目是单工具还是多工具、纯 Claude 还是跨平台，均不得将 `CLAUDE.md` 作为权威内容载体。所有代理指令、事实和规则必须写入 `AGENTS.md`。
-- 现有多行 `CLAUDE.md` 必须在此次同步中改写为重定向；改变权威来源、删除内容或创建符号链接前必须确认，但确定重定向后立即执行全量迁移。
-- 反之亦然：`AGENTS.md` 不得被缩减为指向 `CLAUDE.md` 的重定向。`AGENTS.md` 重定向到其他文件一律视为错误状态，必须修复。
+- 所有代理指令、事实和规则写入 `AGENTS.md`，不把 `CLAUDE.md` 当作权威内容载体。
+- 现有多行 `CLAUDE.md` 经用户确认后改写为重定向，原内容全量迁移到 `AGENTS.md`。
+- `AGENTS.md` 不得被缩减为指向 `CLAUDE.md` 的重定向——发现即修复。
 - Monorepo 使用就近手册覆盖；父级只导航，不复制子模块细节。
 
 ## 验证

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

@@ -18,7 +18,7 @@ git push origin :refs/tags/vX.Y.Z
 #    修复完后落新的非 release commit，保持 release commit 干净
 
 # 3. （若 release commit 已被 push）amend / 追加修复 commit 都可
-#    重要：若需要修改 package.json 或 CHANGELOGS.md，最好新落一个 fix commit
+#    重要：若需要修改 package.json 或 CHANGELOG.md，最好新落一个 fix commit
 #    再用 --amend 合并到 release commit 后 force-push（仅个人分支或本地未推时）
 
 # 4. 重新打 tag 指向（可能更新过的）release commit
@@ -37,26 +37,14 @@ git push origin vX.Y.Z
 **恢复**：**不要**重发 npm（同版本号永久不可重发），仅手动补 GitHub Release。
 
 ```bash
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-# 1. 抽取 CHANGELOG 段落作为 Release notes
-awk -v v="X.Y.Z" '
-  $0 ~ "^## \\["v"\\]" { found=1; print; next }
-  found && /^## \[/ { exit }
-  found && /^---[[:space:]]*$/ { next }
-  found { print }
-' CHANGELOGS.md > "$notes_file"
-
+# 1. 按 release-notes-injection.md 的抽取片段从 CHANGELOG.md 得到 notes_file
 # 2. 手动创建 GitHub Release
 gh release create vX.Y.Z \
   --title "Release vX.Y.Z" \
   --notes-file "$notes_file" \
   --latest
 
-# 3. 三端再次校验
-npm view <pkg> version          # 应 == X.Y.Z
-gh release view vX.Y.Z --json body,isDraft,isPrerelease
+# 3. 三端再次校验——见 release-pipeline.md Phase 5
 ```
 
 **错误码映射**：通常是基础设施层错误（GitHub API 抖动 / token 权限缺 `contents: write`），不计入项目业务错误字典。
@@ -118,7 +106,7 @@ git push origin vX.Y.Z
 > 反重复失败原则：同根因连续失败时，必须先声明新尝试与上次的差异。
 
 - **同根因连续失败 ≥ 2 次** → 必须先停手，**书面声明**本次重试与上次的差异
-- 未声明差异即重试 → 触发 `E010_repeatedFailurePattern`，`npm-cicd-release` 命令应主动暂停，等待用户输入差异声明
+- 未声明差异即重试 → 触发 `E010_repeatedFailurePattern`，发布编排流程应主动暂停，等待用户输入差异声明
 
 例：场景 C 中 NPM_TOKEN 失效连续两次 fail，第二次失败后必须先确认 token 已真正更新（粘贴新 token 的尾 4 位摘要 / GitHub Secrets 更新时间），再继续。
 

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

@@ -1,6 +1,6 @@
 # Phase 0 — 前置检测完整清单
 
-> 本文件是 `npm-cicd-release` 命令 Phase 0 的「展开形态」。命令正文只列出五项核心前置；这里给出 11 项完整探测、失败信号与建议修复。
+> 本文件是发布编排流程（[release-pipeline.md](release-pipeline.md)）Phase 0 的「展开形态」。编排正文只列出核心前置；这里给出 11 项完整探测、失败信号与建议修复。
 > 全部探测都是**只读**的，不会修改任何文件。任一项不通过 → 命令终止，输出修复建议；不要尝试自动跳过。
 
 ## 探测矩阵
@@ -28,12 +28,12 @@
 - 探测项 10：影响 Phase 2 是否进入 docs-sync 主流程
 - 探测项 11：直接关系到能否打 tag，必须在 Phase 0 阶段就排除
 
-## 与三个 skill 的边界
+## 与后续 Phase 的边界
 
-Phase 0 只做**只读探测**，不调用任何 skill 的 SOP：
+Phase 0 只做**只读探测**，不执行任何修复 SOP：
 
-- `git-commit-template` skill 只在 Phase 1 被引用
-- `docs-sync` skill 只在 Phase 2 / Phase 6 被引用
-- `github-npm-ops` skill 在 Phase 3 / 4 / 5 被引用
+- 提交与版本操作在 Phase 1 / Phase 3（见 [version-bump-flow.md](version-bump-flow.md)）
+- 文档同步在 Phase 2 / Phase 6（由调用方执行 `docs-sync` command）
+- 发布监控、验证与恢复在 Phase 4 / 5（见 [release-pipeline.md](release-pipeline.md)、[failure-recovery.md](failure-recovery.md)）
 
-如果 Phase 0 嗅探到的状态需要某个 skill 的修复 SOP（如 release.yml 缺失），明确转交，不要在本命令内复刻 skill 的内容。
+如果 Phase 0 嗅探到的状态需要某个修复 SOP（如 release.yml 缺失），明确转交对应 reference，不要在前置检测阶段现场修复。

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

@@ -13,18 +13,18 @@
 | 直 push main(无 PR 流程) | 仅 `Full Changelog: vA...vB` 一行 | 生成器没有 PR 可分类,只能给 compare 链接 |
 | 有 PR 但仓库没有 `.github/release.yml` | 全部 PR 都被塞进 "What's Changed" 一节 | 没有 label → 章节映射 |
 
-而仓库通常已经维护了 `CHANGELOGS.md`(Keep a Changelog 格式)。**正确做法是把 CHANGELOG 段落作为 Release 正文的事实来源**,自动生成器仅作为补充链接。
+而仓库通常已经维护了 `CHANGELOG.md`(Keep a Changelog 格式)。**正确做法是把 CHANGELOG 段落作为 Release 正文的事实来源**,自动生成器仅作为补充链接。
 
 ## 2. 注入方案
 
-核心思路:在 workflow 里加一步,从 `CHANGELOGS.md` 抽取当前 tag 对应的版本段落,写到 `release-notes.md`,再通过 `softprops/action-gh-release` 的 `body_path` 注入。
+核心思路:在 workflow 里加一步,从 `CHANGELOG.md` 抽取当前 tag 对应的版本段落,写到 `release-notes.md`,再通过 `softprops/action-gh-release` 的 `body_path` 注入。
 
 ### 2.1 完整 workflow 步骤
 
 加到 `Verify bin entry` 之后、`Publish to npm` 之前(也可以放 publish 之后,只要在 Create GitHub Release 之前):
 
 ```yaml
-- name: Extract release notes from CHANGELOGS.md
+- name: Extract release notes from CHANGELOG.md
   run: |
     VERSION="${GITHUB_REF_NAME#v}"
     awk -v v="$VERSION" '
@@ -32,11 +32,11 @@
       found && /^## \[/ { exit }
       found && /^---[[:space:]]*$/ { next }
       found { print }
-    ' CHANGELOGS.md > release-notes.md
+    ' CHANGELOG.md > release-notes.md
 
     if [ ! -s release-notes.md ]; then
-      echo "::warning::CHANGELOGS.md 中未找到 [$VERSION] 段落,回退到自动生成。"
-      echo "See [CHANGELOGS.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOGS.md) for details." > release-notes.md
+      echo "::warning::CHANGELOG.md 中未找到 [$VERSION] 段落,回退到自动生成。"
+      echo "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details." > release-notes.md
     fi
 
     echo "--- Release notes preview ---"
@@ -100,7 +100,7 @@ awk -v v="$VERSION" '
   found && /^## \[/ { exit }
   found && /^---[[:space:]]*$/ { next }
   found { print }
-' CHANGELOGS.md > "$notes_file" && \
+' CHANGELOG.md > "$notes_file" && \
   gh release edit "v$VERSION" --notes-file "$notes_file"
 ```
 
@@ -120,7 +120,7 @@ for v in 0.0.7 0.0.8 0.0.9; do
     found && /^## \[/ { exit }
     found && /^---[[:space:]]*$/ { next }
     found { print }
-  ' CHANGELOGS.md > "$notes_file"
+  ' CHANGELOG.md > "$notes_file"
 
   if [ -s "$notes_file" ]; then
     gh release edit "v$v" --notes-file "$notes_file"

package/template/skills/github-npm-ops/references/troubleshooting-playbook.md

@@ -210,23 +210,9 @@ Full Changelog: v0.0.9...v0.0.10
 
 **原因**：`softprops/action-gh-release@v2` 只设了 `generate_release_notes: true`，而 GitHub 自动生成器从 PR 标题 + label 抽取 changelog。直 push main 的仓库没有 PR 流量，生成器只剩 compare 链接可写。
 
-**修复（workflow 改造）**：在 Create GitHub Release 之前加一步从 `CHANGELOGS.md` 抽取段落，再用 `body_path` 注入。完整 YAML 见 [workflow-yaml-reference.md](workflow-yaml-reference.md) 的 `Extract release notes from CHANGELOGS.md` 步骤；模式说明见 [release-notes-injection.md](release-notes-injection.md)。
+**修复（workflow 改造）**：在 Create GitHub Release 之前加一步从 `CHANGELOG.md` 抽取段落，再用 `body_path` 注入。完整 YAML 见 [workflow-yaml-reference.md](workflow-yaml-reference.md) 的 `Extract release notes from CHANGELOG.md` 步骤；模式说明见 [release-notes-injection.md](release-notes-injection.md)。
 
-**修复（事后回填历史 Release，无需重发版）**：
-
-```bash
-VERSION="0.0.10"
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-awk -v v="$VERSION" '
-  $0 ~ "^## \\["v"\\]" { found=1; print; next }
-  found && /^## \[/ { exit }
-  found && /^---[[:space:]]*$/ { next }
-  found { print }
-' CHANGELOGS.md > "$notes_file" && \
-  gh release edit "v$VERSION" --notes-file "$notes_file"
-```
+**修复（事后回填历史 Release，无需重发版）**：按 [release-notes-injection.md](release-notes-injection.md) 抽取 CHANGELOG 段落，再 `gh release edit "v$VERSION" --notes-file "$notes_file"`。
 
 **诊断**：
 
@@ -247,7 +233,7 @@ gh run view <run-id> --json jobs \
 
 ```bash
 # 实际 CHANGELOG 标题
-grep '^## \[' CHANGELOGS.md | head -5
+grep '^## \[' CHANGELOG.md | head -5
 
 # 当前 tag 应当对应的标题
 echo "## [${GITHUB_REF_NAME#v}]"
@@ -303,5 +289,5 @@ npm deprecate @scope/my-cli@0.0.2 "Security issue, use 0.0.3+"
 6. [ ] Workflow 触发器是 `on.push.tags: ['v*']`，没写 branches
 7. [ ] `bin` 路径以 `./` 开头
 8. [ ] `files` 字段不排除构建产物
-9. [ ] **Workflow 包含 `Extract release notes from CHANGELOGS.md` 步骤，且 `Create GitHub Release` 设了 `body_path: release-notes.md`**
-10. [ ] **CHANGELOGS.md 顶部有当前版本对应的 `## [X.Y.Z]` 段落（半角中括号）**
+9. [ ] **Workflow 包含 `Extract release notes from CHANGELOG.md` 步骤，且 `Create GitHub Release` 设了 `body_path: release-notes.md`**
+10. [ ] **CHANGELOG.md 顶部有当前版本对应的 `## [X.Y.Z]` 段落（半角中括号）**