@namewta/speculo 0.2.16 → 0.3.0

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/`、系统临时目录或工作区内其他非规范位置。
 
 ## 内容要求
 
@@ -37,10 +39,10 @@ speculo/.speculo/commands/handoff/<YYYY-MM-DD>-<scope>-<topic>[-NN].md
 
 文档中所有文件/文件夹引用必须使用**项目根目录**的相对路径。
 
-- ✅ `cde-base/cde-modules/cde-gba/cde-gba-universal/`
-- ✅ `sql/current/other_domain.sql`
-- ✅ `speculo/.speculo/specdev/changes/2026-07-21-gba-info-json-extension/spec.md`
+- ✅ `src/modules/auth/`
+- ✅ `scripts/migrate/2024-add-index.sql`
+- ✅ `speculo/.speculo/specdev/changes/<YYYY-MM-DD>-<topic>/spec.md`
 - ❌ `../../specdev/changes/...` — 相对于 handoff 文件，脱离目录后不可定位
-- ❌ `cde-base` — 裸名，无法判断是目录/文件/子模块
+- ❌ `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]` 段落（半角中括号）**

package/template/skills/github-npm-ops/references/version-bump-flow.md

@@ -15,14 +15,14 @@ git log origin/main..HEAD --oneline
 git tag --sort=-version:refname | head -3
 
 # 4. CHANGELOG 顶部 [Unreleased] 段落已写好本次内容
-head -30 CHANGELOGS.md
+head -30 CHANGELOG.md
 ```
 
 任意一项异常先解决再发版：工作区不干净 → 先提交，或调用 docs-sync 按其清洁契约处理；`[Unreleased]` 为空 → 先做 docs-sync。禁止用 stash 隐藏待发布改动。
 
 ## 1. 维护 CHANGELOG
 
-`CHANGELOGS.md` 顶部必须始终保留 `[Unreleased]` 段落。新版本发布时:
+`CHANGELOG.md` 顶部必须始终保留 `[Unreleased]` 段落。新版本发布时:
 
 1. 把 `[Unreleased]` 内容**整段迁移**到新建的 `## [X.Y.Z] — YYYY-MM-DD` 标题下
 2. 重新插入空的 `[Unreleased]` 段落
@@ -67,10 +67,10 @@ npm version 0.0.10 --no-git-tag-version
 
 ## 3. release commit(原子提交)
 
-把 `package.json` + `CHANGELOGS.md` 一并提交,使用 Conventional Commits 的 `chore(release):` 前缀。
+把 `package.json` + `CHANGELOG.md` 一并提交,使用 Conventional Commits 的 `chore(release):` 前缀。
 
 ```bash
-git add package.json CHANGELOGS.md
+git add package.json CHANGELOG.md
 git commit -m "chore(release): v0.0.10" \
            -m "迁移 [Unreleased] 段落到 0.0.10:<一两句关键变更摘要>"
 ```
@@ -129,33 +129,13 @@ gh run list --workflow release.yml --limit 3 \
 6. Run tests
 7. Build
 8. **Verify bin entry**
-9. **Extract release notes from CHANGELOGS.md** ← v1.1.0 新增
+9. **Extract release notes from CHANGELOG.md** ← v1.1.0 新增
 10. **Publish to npm**
 11. **Create GitHub Release**
 
 ## 7. 三端验证
 
-```bash
-# 1. npm 包已上线(CDN 30–60 秒延迟)
-npm view @scope/pkg version
-npm view @scope/pkg dist-tags
-
-# 2. GitHub Release 存在 + 正文非空
-gh release view v0.0.10 --json name,tagName,isDraft,isPrerelease,body \
-  --jq '{name, tagName, isDraft, isPrerelease, body_length: (.body | length), body_preview: (.body | .[0:200])}'
-
-# 3. workflow conclusion=success 且所有步骤 success
-gh run view <run-id> --json conclusion,jobs \
-  --jq '{conclusion, steps: [.jobs[].steps[] | {name, conclusion}]}'
-```
-
-任一缺失视为发布残次品:
-
-| 缺失项 | 修复 |
-|--------|------|
-| npm 包查不到 | 等 60 秒再查;仍无 → 看 workflow `Publish to npm` 步骤日志 |
-| Release 正文为空 / 仅一行 Full Changelog | 跑 [release-notes-injection.md](release-notes-injection.md) §3 的事后修复 |
-| workflow `Extract release notes` 失败 | CHANGELOG 标题与 tag 不匹配,核对 `## [X.Y.Z]` 是否存在 |
+完整命令与判定见 [release-pipeline.md](release-pipeline.md) Phase 5（`npm view` / `gh release view` / `gh run view`）。任一缺失视为发布残次品；Release 正文为空时按 [release-notes-injection.md](release-notes-injection.md) 事后修复。
 
 ## 8. 失败回滚
 
@@ -187,7 +167,7 @@ notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
 trap 'rm -f "$notes_file"' EXIT
 
 # 抽取 CHANGELOG 段落
-awk -v v="0.0.10" '...' CHANGELOGS.md > "$notes_file"
+awk -v v="0.0.10" '...' CHANGELOG.md > "$notes_file"
 
 # 手动创建 GitHub Release
 gh release create v0.0.10 --notes-file "$notes_file" --latest
@@ -213,7 +193,7 @@ npm view @scope/pkg@0.0.10 version
 ```bash
 # bump 到下一个补丁
 npm version 0.0.11 --no-git-tag-version
-git add package.json CHANGELOGS.md
+git add package.json CHANGELOG.md
 git commit -m "chore(release): v0.0.11"
 git push origin main
 git tag v0.0.11

package/template/skills/github-npm-ops/references/workflow-yaml-reference.md

@@ -52,7 +52,7 @@ jobs:
       - name: Verify bin entry
         run: node scripts/verify-bin.mjs
 
-      - name: Extract release notes from CHANGELOGS.md
+      - name: Extract release notes from CHANGELOG.md
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
           awk -v v="$VERSION" '
@@ -60,11 +60,11 @@ jobs:
             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
 
       - name: Publish to npm
@@ -173,10 +173,10 @@ permissions:
 
 CLI 包专有：确认 `dist/cli/index.js` 存在、有 shebang、可执行。防止 tsconfig 出问题导致产物不完整。
 
-### Extract release notes from CHANGELOGS.md
+### Extract release notes from CHANGELOG.md
 
 ```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" '
@@ -184,11 +184,11 @@ CLI 包专有：确认 `dist/cli/index.js` 存在、有 shebang、可执行。
       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::..." >&2
-      echo "See [CHANGELOGS.md](...) for details." > release-notes.md
+      echo "See [CHANGELOG.md](...) for details." > release-notes.md
     fi
 ```
 

package/template/skills/writing-great-skills/SKILL.md

@@ -1,4 +1,6 @@
 ---
+id: writing-great-skills
+type: skill
 name: writing-great-skills
 description: 编写和编辑高质量 skills 的参考指南 — 使 skill 行为可预测的词汇和原则。
 disable-model-invocation: true

package/template/workflows/person/M-mao-zedong-cognitive-os/_templates/mao-consultation-output-template.md

@@ -0,0 +1,32 @@
+# 咨询输出：<问题一句话概括>
+
+<!-- 由 deliver 阶段整合四阶段产物填写。保持教员第一人称，正文为连贯的咨询答复。 -->
+
+## 答复
+
+<!-- 连贯的第一人称咨询答复正文。五拍论证节奏可辨识：
+拍1【破题】用定义或反问点出根本问题 → 拍2【切割】"不是A而是B"剥掉表象 →
+拍3【定向】抓主要矛盾分清主次 → 拍4【点睛】落一句比喻/古语/史例 → 拍5【收尾】给方法+给信心 -->
+
+<正文>
+
+<!-- 收尾四动作（必须齐全，融入正文结尾）：
+1. 给方向——点明主要矛盾与战略判断
+2. 给步骤——2–3 步具体行动，"一仗一仗打"
+3. 给检验——如何验证，"做了再看"
+4. 给信心——战略乐观，承认"道路是曲折的" -->
+
+## 内在张力
+
+<!-- 若答复涉及以下张力（理论与实践 / 群众路线与精英决策 / 持久与速决 / 团结与斗争），逐条坦诚标注处理方式；无则写"无"。 -->
+
+- <张力名称>：<本次答复中如何处理>
+
+## 引用索引
+
+<!-- 每条引用一行。逐字直引加引号；概括转述标"转述"。篇目编号对应 books/src/NNN-*.md。 -->
+
+| 引用 | 篇目 | 形式 |
+|------|------|------|
+| "<金句原文>" | 《篇目名》(NNN) | 直引 |
+| <概括内容> | 《篇目名》 | 转述 |