@namewta/speculo 0.1.21 → 0.2.0

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -0,0 +1,50 @@
+# Workflow 范围契约
+
+docs-sync 必须遵循每个 workflow 的 `WORKFLOW.md`、持久化声明与确认规则。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
+
+## 发现
+
+1. 从 `speculo/workflows/*/WORKFLOW.md` 发现已安装 workflow。
+2. 每个包必须有匹配的 `speculo/.speculo/<workflow>/` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
+3. 读取 `<runtime-context>`、`<persistence>`、固定 archive 和所有 `consumers` 包含 `docs-sync` 的 store。
+4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
+
+## Sidecar v1
+
+每个已安装 workflow 首次 docs-sync 都创建：
+
+```json
+{
+  "schema_version": 1,
+  "workflow": "example",
+  "manifest_path": "speculo/.speculo/example/docs-sync.json",
+  "project_targets": [],
+  "state_targets": [],
+  "scope_revision": 1,
+  "scope_confirmed_at": "ISO-8601"
+}
+```
+
+目标使用 `{ "path": "...", "kind": "file | directory" }`：
+
+- `project_targets` 使用项目相对路径，记录该 workflow 负责维护的项目文档。
+- `state_targets` 使用 workflow 状态根相对路径，只能位于 `consumers` 包含 `docs-sync` 的已声明 store。
+- Directory 目标递归覆盖其中已跟踪的 Markdown、MDX、reStructuredText 和 AsciiDoc；其他格式必须作为 file 明确列出。
+- 禁止绝对路径、反斜杠、`..`、项目根目录、无界 glob、`.git`、固定 `status.json/changes/archive` 和 sidecar 自身。
+
+## 首次确认与修订
+
+1. Bootstrap 同时展示全局候选，以及每个 workflow 的 project/state 候选、来源和风险。
+2. 用户一次确认后写入全局 state 与全部 sidecar；没有候选的 workflow 也写空清单。
+3. 一个目标只能归属全局或一个 workflow；重叠、父子目录交叉或同一路径多 owner 必须先消歧。
+4. 后续新增、扩大、移除或转移目标必须再次展示完整新范围；确认后增加 `scope_revision` 并更新时间。
+5. 首次确认只授予范围内常规创建和改写，不授权整文件/目录删除或受保护知识写入。
+
+## Archive 与知识
+
+- 固定 archive 始终可作为只读证据；优先读取本次区间新增或变更、且与受影响模块或术语相关的高信号产物。
+- 归档中的稳定决策、术语、经验和文档漂移信号只提炼结论并保留来源路径，不复制大段正文。
+- `existing-only` store 永远只读。RULES/policy、ADR、CONTEXT、语义冲突和任何知识文件删除均进入 `propose-only`，按目标 workflow 规则取得逐次确认。
+- 不跨 workflow 搬运知识；共享结论必须先确认唯一归属。
+
+完成标准：所有已安装 workflow 都有有效 sidecar；每个有效目标都有唯一 owner、声明边界和确认记录；所有受保护动作均未越权。

package/template/skills/github-npm-ops/SKILL.md

@@ -2,52 +2,27 @@
 id: github-npm-ops
 type: skill
 name: GitHub npm Ops
-description: GitHub 仓库运营与 npm 发布原子能力；用于 issue/PR/CI/security 治理、release.yml 配置、npm provenance 发布、tag 发版、三端验证和失败恢复。
+description: 提供 GitHub issue/PR/CI/security 治理与 npm provenance 发布、验证和失败恢复原子能力。
 ---
 
 # GitHub npm Ops
 
-## 何时使用
+## 输入
 
-当 command 或 workflow 需要处理 GitHub 仓库运营、CI 排障、安全告警、npm 包发布、GitHub Release、release notes 注入、tag 触发发布或发布失败恢复时使用。
+- 仓库、目标分支、issue/PR/run id 或目标版本。
+- package metadata、release workflow、CHANGELOG 和可选 docs-sync state。
 
-## 输入
+## 分支
 
-- GitHub 仓库上下文、目标分支、目标版本号或待处理 issue / PR / run id
-- npm 包信息：`package.json`、包名、版本、发布分支、是否 scoped
-- 发布流水线文件：通常是 `.github/workflows/release.yml`
-- CHANGELOG 类文档路径，默认优先识别 `CHANGELOG.md` 或 `CHANGELOGS.md`
-- 可选：调用方 workflow 提供的 `speculo/.speculo/dev/docs-sync-state.json` 与 docs-sync 报告
+1. **Issue/PR**：读取 `references/issue-pr-triage.md`；完成标准是分类、去重、标签和外部写入计划均有证据。
+2. **CI/Security**：读取 `references/ci-and-security-ops.md`；完成标准是失败或告警根因可复现，修复动作与验证分离。
+3. **发布预检**：读取 `references/preflight-checklist.md`、`references/package-json-checklist.md` 和 `references/publish-detection.md`；完成标准是分支、认证、版本、tag、流水线和发布目标均已判定。
+4. **发布实施**：按需读取 `references/release-pipeline.md`、`references/workflow-yaml-reference.md`、`references/version-bump-flow.md`、`references/release-notes-injection.md` 和 `references/setup-npm-token.md`；完成标准是版本/CHANGELOG 同 commit、tag 精确指向该 commit，外部动作均已确认。
+5. **失败恢复**：读取 `references/failure-recovery.md` 与具体错误时的 `references/troubleshooting-playbook.md`；完成标准是已判定 npm 是否上传，并选择可重试同 tag、补后续动作或必须 bump 中唯一分支。
 
 ## 输出
 
-- GitHub issue / PR / CI / security 的操作建议或执行结果
-- npm 发布前置检查结论
-- release.yml 配置、tag 发版步骤、三端验证结果
-- 失败恢复路径：可重试同 tag、只补 GitHub Release、或必须 bump 新版本
-- 调用方可归档的发布摘要、风险、验证命令和后续动作
-
-## 执行步骤
-
-1. 先判定任务类型：日常治理、发布基础设施搭建、正式发版、失败恢复。
-2. 发布类任务先执行只读前置检查：分支、工作区、远端、`gh auth`、Node/包管理器、`release.yml`、tag 冲突、docs-sync state。
-3. 需要同步对外文档时，交给调用方读取 `../workflows/dev/D-docs-sync/D-docs-sync.md`；本 skill 不自行选择持久化目录，只把结果交给调用方写入其声明的 `speculo/.speculo/...` 规范路径。
-4. 正式发版必须保证 release commit 同时包含版本 bump 与 CHANGELOG 迁移，并且 tag 精确指向 release commit。
-5. release workflow 必须包含 tag/package version 校验、质量闸、可选 npm publish、CHANGELOG release notes 注入、GitHub Release 创建。
-6. 发布完成后做三端验证：workflow success、GitHub Release 非 draft 且正文非空、如流水线包含 npm publish 则 `npm view` 版本与 dist-tag 一致。
-7. 失败恢复先判断 npm 是否已成功上传；一旦 npm 已上传，同版本号不可重发，只能补后续动作或 bump 新版本。
-
-## 渐进披露
-
-- `references/release-pipeline.md`：执行正式 npm/GitHub release 编排时读取。
-- `references/preflight-checklist.md`：发布前只读检查或 dry-run 时读取。
-- `references/publish-detection.md`：判断 release workflow 是否实际发布 npm 包时读取。
-- `references/package-json-checklist.md`：检查 npm 包元数据、bin、files、provenance 相关字段时读取。
-- `references/setup-npm-token.md`：配置或排查 `NPM_TOKEN`、2FA bypass、scope 权限时读取。
-- `references/workflow-yaml-reference.md`：创建或修复 `.github/workflows/release.yml` 时读取。
-- `references/release-notes-injection.md`：Release 正文为空、需要从 CHANGELOG 注入 release notes 时读取。
-- `references/version-bump-flow.md`：执行版本 bump、release commit、tag、push 时读取。
-- `references/failure-recovery.md`：发布编排失败、需要判断是否能重试同 tag 时读取。
-- `references/troubleshooting-playbook.md`：npm/GitHub Actions 具体错误码排障时读取。
-- `references/issue-pr-triage.md`：issue / PR 分诊、标签、社区响应时读取。
-- `references/ci-and-security-ops.md`：CI 失败、安全告警、Dependabot / secret scanning 处理时读取。
+- 操作建议或经确认后的执行结果、风险和验证证据。
+- 发布后三端验证：workflow success、GitHub Release 非 draft 且正文非空、需要发布 npm 时 registry 版本/dist-tag 一致。
+
+本 skill 不推进 docs-sync state，也不自行选择报告或 workflow knowledge 路径。

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

@@ -109,7 +109,7 @@ git push origin vX.Y.Z
 #    在 [X.Y.(Z+1)] 段落开头加一句 "supersedes vX.Y.Z due to <根因>"
 ```
 
-**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方 workflow，由其追加到 `speculo/.speculo/.config/LESSONS.md`（本 skill 不自行选择持久化目录）。
+**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方，由其按所属 workflow 规则写入声明的 lessons/knowledge store（本 skill 不自行选择 workflow 或持久化目录）。
 
 ---
 

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

@@ -16,7 +16,7 @@
 | 7 | 包管理器 | `pnpm --version` (或 `npm` / `yarn`) | 版本 ≥ 仓库 lockfile 隐含版本 | 安装匹配版本；不要随意切换包管理器 |
 | 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 |
+| 10 | docs-sync state | `test -f speculo/.speculo/commands/docs-sync/state.json && jq . speculo/.speculo/commands/docs-sync/state.json` | schema v4、scope 已确认，baseline 可解析 | 不存在/未确认 → 走 docs-sync command bootstrap；旧 schema → 先迁移并确认范围；损坏 → 阻塞修复 |
 | 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 到下一版本 |
 
 ## 失败处理总策略

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

@@ -88,7 +88,7 @@ GitHub Release 的正文(body)**事后可改**(tag 不可改、npm 包不可改
 
 ### 3.1 命令行(推荐)
 
-`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
+`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `speculo/.speculo/commands/<command>/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`。
 
 ```bash
 VERSION="0.0.10"

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

@@ -1,11 +1,11 @@
 # npm + GitHub Release 编排
 
-把一次 npm 包发布拆成可验证的单向流水线：前置检查 -> 普通改动 commit -> docs-sync -> release commit -> tag -> workflow 监控 -> 三端验证 -> docs-sync 基线推进。
+把一次 npm 包发布拆成可验证的单向流水线：前置检查 -> 普通改动 commit -> docs-sync -> release commit -> tag -> workflow 监控 -> 三端验证 -> docs-sync 记录 release 节点。
 
 ## 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 必须由调用方按 `../../../commands/docs-sync.md` 执行；输入起点来自最后修改 state 文件的 commit，终点是运行前清洁后的 HEAD，并写入 `last_range`。
 - tag 必须精确指向 release commit，即包含 `package.json` version bump 与 CHANGELOG 迁移的 commit；禁止指向后续 docs / state commit。
 - npm 已成功上传后，同一 version 不可重发；不要通过删 tag 或 unpublish 试图覆盖。
 
@@ -18,7 +18,7 @@
 - Node 与包管理器满足仓库声明
 - `.github/workflows/release.yml` 存在
 - 已确定 `PUBLISH_TO_NPM=true | false`
-- `speculo/.speculo/dev/docs-sync-state.json` 存在且可解析；不存在时转 `dev/D-docs-sync` 首次运行流程
+- `speculo/.speculo/commands/docs-sync/state.json` 存在且可解析；不存在时转 docs-sync command 的首次 bootstrap
 - 目标 tag `vX.Y.Z` 不存在，除非正在执行明确的失败恢复
 
 任一项不通过就停止，输出修复建议。
@@ -32,10 +32,10 @@
 
 ## Phase 2 — Docs Sync
 
-- 由调用方执行 `../../../workflows/dev/D-docs-sync/D-docs-sync.md`。
-- 只修改 tracked assets 中需要同步的文档或知识资产。
+- 由调用方执行 `../../../commands/docs-sync.md`。
+- 只修改全局 state 与 workflow sidecar 已确认范围中需要同步的文档或知识资产。
 - CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
-- 本阶段不推进 docs-sync state 到 release commit；最终基线推进放到 Phase 6。
+- 本阶段由 docs-sync 自动提交文档、报告与 state；最终 release commit 仍在 Phase 3 创建，发布后再由 Phase 6 记录为新输入终点。
 
 ## Phase 3 — 版本 bump + release commit + tag
 
@@ -86,15 +86,15 @@ npm view "<package-name>" dist-tags
 
 判定 version 与 `dist-tags.latest` 均为 `X.Y.Z`。
 
-## Phase 6 — 推进 docs-sync 基线
+## Phase 6 — 记录 release 输入节点
 
-仅当 Phase 1-5 全绿时执行。本 skill 不自行选择持久化目录；把基线推进交给调用方的 release workflow 或 `../../../workflows/dev/D-docs-sync/D-docs-sync.md`，只向其提供以下取值：
+仅当 Phase 1-5 全绿时执行。再次调用 `../../../commands/docs-sync.md`，并确认运行前 `HEAD` 等于 `RELEASE_COMMIT_SHA`：
 
-- `last_sync_sha` 推进到 `RELEASE_COMMIT_SHA`。
-- `previous_sync_sha` 使用推进前的 `last_sync_sha`。
-- `synced_assets` 使用 Phase 2 实际修改的资产列表；空同步为 `[]`。
+- state 的 `last_range.to_sha` 必须等于 `RELEASE_COMMIT_SHA`。
+- `last_range.from_sha` 来自最后修改旧 state 的 commit，或迁移期 explicit baseline。
+- docs-sync 写入 release 后报告/state commit；tag 继续精确指向 release commit，不移动。
 
-调用方把 state 推进作为 release tag 之后的普通 docs commit，tag 不移动；写入机制（原子写、schema 校验）由 D-docs-sync workflow 负责。
+本 skill 不直接改 state 或 workflow sidecar；原子写入、范围检查和本地 commit 均由 docs-sync command 负责。
 
 ## 完成报告
 
@@ -104,5 +104,5 @@ npm view "<package-name>" dist-tags
 - workflow run id 与结论
 - GitHub Release 检查结果
 - npm 检查结果或跳过原因
-- docs-sync state old/new baseline
+- docs-sync `last_range` 与 state-file baseline commit
 - 失败恢复或后续建议

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

@@ -18,7 +18,7 @@ git tag --sort=-version:refname | head -3
 head -30 CHANGELOGS.md
 ```
 
-任意一项异常先解决再发版:工作区不干净 → 先提交或暂存;`[Unreleased]` 为空 → 先做 docs-sync。
+任意一项异常先解决再发版：工作区不干净 → 先提交，或调用 docs-sync 按其清洁契约处理；`[Unreleased]` 为空 → 先做 docs-sync。禁止用 stash 隐藏待发布改动。
 
 ## 1. 维护 CHANGELOG
 
@@ -46,7 +46,7 @@ head -30 CHANGELOGS.md
  - [0.0.9](https://github.com/owner/repo/releases/tag/v0.0.9)
 ```
 
-完整 CHANGELOG 契约见 `../../../workflows/dev/D-docs-sync/changelog-contract.md`。
+完整 CHANGELOG 契约见 `../../docs-sync/references/changelog-contract.md`。
 
 ## 2. bump package.json
 
@@ -180,7 +180,7 @@ git push origin v0.0.10
 
 npm 已上线 → **不要**改版本号,只补后续动作。
 
-下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `speculo/.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`。
+下面的 `notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留发布摘要或 release notes，由调用方写入 `speculo/.speculo/commands/<command>/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`。
 
 ```bash
 notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"

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

@@ -0,0 +1,29 @@
+---
+id: knowledge-prune
+type: skill
+name: Knowledge Prune
+description: dry-run 审计 workflow 声明的知识与策略 namespace，返回可安全删除、合并或改写的候选清单。
+---
+
+# Knowledge Prune
+
+默认只分析，不自行写报告或修改文件。调用方负责 runtime context、用户确认和持久化。
+
+## 输入
+
+- `runtime-context` 返回的 workflow/state 根。
+- `WORKFLOW.md#persistence` 中 role 为 knowledge、policy 或 legacy-knowledge 的 namespace。
+- 用户确认状态：`dry-run | confirmed`。
+
+## 流程
+
+1. 读取 `references/audit-rules.md`，仅扫描已声明且真实存在的 namespace。
+2. 为每个候选收集当前代码、文档、active change、archive 和交叉引用证据。
+3. 按 `delete | merge | rewrite | keep | needs-confirmation` 返回候选；dry-run 到此完成。
+4. confirmed 模式重新验证真实路径包含关系，再逐项执行用户批准的动作并返回结果。
+
+完成标准：每个候选都有来源、证据和风险；未确认时文件系统未发生变化；本 skill 未自行选择报告路径。
+
+## 渐进披露
+
+- `references/audit-rules.md`：生成候选、判定保护项或执行确认后的修改时读取。

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

@@ -0,0 +1,24 @@
+# Knowledge Prune Audit Rules
+
+## 扫描范围
+
+1. 读取目标 workflow 的 `<persistence>`，选择 role 为 `knowledge | policy | legacy-knowledge` 且真实存在的 store。
+2. `create="lazy"` 但不存在的 store 记为 `missing`，不为审计而创建；`existing-only` store 只读。
+3. 扫描代码、文档、active changes 和 archive 中对 ADR、CONTEXT、LESSONS、RULES 及具体文件名的引用。
+
+## 候选
+
+- 指向不存在知识文件的引用。
+- 已 superseded、超过 30 天且无 active 引用的 ADR。
+- 只含占位符、模板说明或空内容的长期知识文件。
+- 当前代码、文档和 archive 均无证据支撑的领域术语。
+- 重复、过时、仅适用单次 change 或已被规则/ADR 吸收的经验。
+
+## 保护规则
+
+- 仍被代码、文档、archive 或 active change 引用的内容归入 `keep`。
+- RULES、术语冲突、ADR/CONTEXT 改写和 existing-only legacy store 一律归入 `needs-confirmation`。
+- 删除前解析真实路径，确认仍位于目标 workflow state root 和已声明 store 内。
+- 不跨 workflow 合并知识，不修改 docs-sync state。
+
+完成标准：所有已声明且存在的知识 store 均已扫描，每个候选恰好属于一个分组。

package/template/skills/runtime-context/SKILL.md

@@ -0,0 +1,43 @@
+---
+id: runtime-context
+type: skill
+name: Runtime Context
+description: 解析 Speculo 项目根、资产根和 workflow 状态根，向 command/workflow/skill 返回经过边界校验的统一路径上下文。
+---
+
+# Runtime Context
+
+从项目根注册表和 workflow XML 声明构造一次运行所需的全部路径。调用方持有持久化责任；本 skill 只解析和验证路径。
+
+## 输入
+
+- 当前工作目录或用户指定的项目目录。
+- workflow id，以及对应 `WORKFLOW.md` 中的 `<runtime-context>` 和 `<persistence>`。
+- 可选 change 名称和 command id。
+
+## 流程
+
+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 复用；后续调用不得重新猜测路径。
+
+## 输出
+
+```text
+project_root
+workflow_root
+state_root
+changes_root
+archive_root
+change_root?
+commands_root
+skills_root
+vendor_roots[]
+```
+
+完成标准：所有返回路径均为项目根相对路径、位于声明根内且对应静态资产真实存在；本 skill 未创建任何运行时产物。
+
+## 渐进披露
+
+- `references/path-resolution.md`：定位根注册表、解析 XML 根别名或检查路径越界时读取。

package/template/skills/runtime-context/references/path-resolution.md

@@ -0,0 +1,32 @@
+# Path Resolution
+
+## 根定位
+
+1. 从当前工作目录向上寻找 `speculo/.speculo/workspace.json`。
+2. 第一个命中的目录是 `project_root`；同时命中多个候选或用户指定目录与候选不一致时停止并澄清。
+3. `workspace.json#path_base` 必须为 `project-root`，所有 roots 必须是 POSIX 风格相对路径。
+
+## Workflow 绑定
+
+读取 workflow 的 `<runtime-context>`：
+
+- `base` 必须引用 `workspace.json#roots` 中已有根。
+- `path` 不能是绝对路径，不能包含 `..` 或反斜杠。
+- `workflow` 和 `state` 必须分别解析到 `speculo/workflows/<workflow>` 与 `speculo/.speculo/<workflow>`。
+- vendor 可声明零个或多个具名根，例如 `vendor:matt-pocock`。
+
+固定派生规则：
+
+```text
+changes_root = state_root/changes
+archive_root = state_root/archive
+change_root = changes_root/<change>
+```
+
+## 边界检查
+
+- 解析后执行真实路径包含检查；符号链接逃逸与不存在的静态引用均阻塞。
+- `<artifact root="change">` 只能落在当前 change。
+- `<artifact root="state">` 只能落在 `<persistence>` 声明的额外命名空间。
+- command 报告只能落在 `state/commands/<command>/`，skill 不自行选择路径。
+- raw vendor skill 未经 workflow runtime context 激活时，不承诺 Speculo 持久化边界。

package/template/skills/speculo-retro/SKILL.md

@@ -2,51 +2,27 @@
 id: speculo-retro
 type: skill
 name: Speculo Retro
-description: 复盘 Speculo commands/workflows 使用过程中的痛点、问题与值得优化的地方，深度分析后产出去重、分级、根因化、可直接转成 GitHub issue 的规范化改进提案；当用户要求总结 Speculo 使用体验、收集框架反馈或把使用痛点整理成 issue 时使用。
+description: 从 Speculo 使用证据中提取、去重、分级和根因化摩擦，返回可直接转成 GitHub issue 的提案。
 ---
 
 # Speculo Retro
 
-## 何时使用
-
-当用户想复盘「用 Speculo 的 commands 或 workflows 时遇到的痛点、问题、值得优化的地方」，并希望把这些摩擦整理成规范化、可行动的框架反馈或 issue 时使用。
-
-典型触发：
-
-- “总结一下这次用 Speculo 踩的坑 / 卡点”
-- “把使用痛点整理成可以提的 issue”
-- “复盘 dev workflow 哪里别扭、哪里值得优化”
-- “收集 Speculo 框架反馈”
-
-本 skill 只负责**分析与规范化产出内容**：它去重、分级、根因化并起草 issue-ready 提案，把结果返回给调用方。它**不自行写文件、不调用 `gh`、不发布 issue**；落盘与提交由调用方 command / workflow 负责。
-
 ## 输入
 
-- 当前对话上下文：本次会话用了哪些 command / workflow、卡在哪、绕了什么弯、重复了哪些动作
-- `speculo/.speculo/commands/<run>/` 下的历史命令产物（report、snapshot、handoff）
-- `speculo/.speculo/<cat>/<change>/` 下的 change 产物与 `.status.json`（`phase_history` 里的 `revisited`、`blocked`、长时间停滞都是摩擦信号）
-- `speculo/.speculo/.config/LESSONS.md`（已沉淀的教训，用于去重与佐证）
-- 可选：调用方提供的已存在 issue 列表或目标仓库上下文，用于跨提案去重
-- 本 skill 自带分析与 issue 起草规范，已内化到 `references/`，分析时**不外读仓库 `docs/`**
-
-## 输出
+- 当前对话与本次使用的 commands/workflows。
+- `commands/<command>/*.md` 报告、active change 状态、archive 和 workflow 声明的 lessons/knowledge store。
+- 可选已有 issues，用于语义去重。
 
-- 规范化复盘结论：每条 = 一个去重、分级、根因化的改进提案，字段对齐 GitHub issue（标题、类型/标签、证据、问题、建议改动、验收、受影响 asset）
-- 提案清单，按优先级倒序排列
-- 被合并或丢弃的低信号项说明（哪些重复、哪些更适合记入 `LESSONS.md` 而非提 issue）
-- 每条标注「建议提 issue」或「仅记教训」的处置建议
-- 全部以**返回内容**形式交给调用方写入其声明的 `speculo/.speculo/...` 路径；本 skill 不挑选持久化位置
+## 流程
 
-## 执行步骤
+1. 读取 `references/friction-taxonomy.md`，穷尽扫描可用证据并列出原始摩擦。完成标准：每项都有来源路径或对话节点。
+2. 按 bug、friction、missing-capability、doc-gap、ergonomics 归类，合并同一根因。完成标准：每项只属于一个根因簇，合并关系可追溯。
+3. 评估影响与频率，过滤一次性噪声；低信号项标为丢弃或仅记教训。完成标准：每项都有优先级和处置理由。
+4. 读取 `references/issue-drafting-sop.md`，生成 issue-ready 提案并与已有 issue 去重。完成标准：标题、证据、问题、建议、验收、影响资产和去重结论齐全。
 
-1. **收集信号** —— 按 `references/friction-taxonomy.md` 的来源清单，扫描对话上下文、`speculo/.speculo/` 产物与 `LESSONS.md`，列出原始摩擦点。
-2. **归类与去重** —— 按 taxonomy 把每个摩擦点归到类型（bug / friction / missing-capability / doc-gap / ergonomics），合并语义重复项。
-3. **深度分析** —— 对每条做根因判断（是 asset 设计、持久化契约、文档还是工具问题），评估影响面与发生频率，按 `references/friction-taxonomy.md` 的优先级评分。
-4. **过滤噪声** —— 只保留高信号、可行动项；低信号或一次性项标注为丢弃，或归入「仅记教训」。
-5. **起草提案** —— 按 `references/issue-drafting-sop.md` 把每条规范化成 issue-ready 提案，并对照调用方提供的已存在 issue 做跨提案去重。
-6. **返回结论** —— 把结构化提案清单、丢弃项与处置建议返回调用方；不自行写文件、不调用 `gh`。
+## 输出
 
-## 渐进披露
+- 按优先级排序的 `file-issue | lesson-only | discard | duplicate` 提案。
+- 合并/丢弃说明和调用方执行 `gh` 所需字段。
 
-- `references/friction-taxonomy.md`：确定信号来源、给摩擦点归类、按影响 × 频率评优先级、过滤噪声时读取。
-- `references/issue-drafting-sop.md`：把改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成给调用方 / `gh` 的交接字段时读取。
+本 skill 不写文件、不调用外部 API；command 负责报告、确认和 issue 创建。

package/template/skills/speculo-retro/references/friction-taxonomy.md

@@ -7,14 +7,14 @@
 按以下顺序采集原始摩擦点，每条记录**证据出处**（文件路径或对话节点），后续起草 issue 时要引用：
 
 1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
-2. **命令产物** —— `speculo/.speculo/commands/<run>/` 下的 `report.md`、`snapshot.md`、`handoff.md`：里面记录的「验证失败原因」「未完成」「阻塞点」是一手摩擦。
-3. **change 状态机** —— `speculo/.speculo/<cat>/<change>/.status.json` 的 `phase_history`：
+2. **命令产物** —— `speculo/.speculo/commands/<command>/*.md`：其中记录的验证失败、未完成和阻塞点是一手摩擦。
+3. **change 状态机** —— `speculo/.speculo/<workflow>/changes/<change>/.status.json` 的 `phase_history`：
    - `revisited` —— phase 被迫回退，通常意味着流程设计或前置产物有缺口
    - `blocked` —— 卡点，记录阻塞原因
    - `skipped` —— phase 被跳过，可能是冗余或不适用
    - `updated_at` 长期停滞 —— 流程让人不想推进
 4. **change 产物正文** —— `prd.md`、`tdd-*.md`、`slices.md`、`diagnosis.md` 中显式写下的「待澄清」「风险」「TODO」。
-5. **沉淀教训** —— `speculo/.speculo/.config/LESSONS.md`：已记录但尚未转成改进项的教训，用于去重与佐证频率。
+5. **沉淀教训** —— 各 workflow 声明的 lessons/knowledge store：已记录但尚未转成改进项的教训，用于去重与佐证频率。
 6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离 `persistence-contract`：路径散落、缺字段、命名不合 `YYYY-MM-DD-<kebab>` 都是 bug 信号。
 
 ## 摩擦类型分类

package/template/skills/speculo-retro/references/issue-drafting-sop.md

@@ -13,8 +13,8 @@
   "priority":     "priority:critical | priority:high | priority:medium | priority:low",
   "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
   "body":         "string, 见正文结构",
-  "affected":     ["相对路径，例 speculo/commands/archive.md"],
-  "evidence":     ["证据出处，例 speculo/.speculo/dev/<change>/.status.json#phase_history"],
+  "affected":     ["相对路径，例 speculo/commands/finalize.md"],
+  "evidence":     ["证据出处，例 speculo/.speculo/<workflow>/changes/<change>/.status.json#phase_history"],
   "disposition":  "file-issue | record-lesson | drop",
   "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
 }
@@ -74,4 +74,4 @@
 
 ## 交接契约
 
-本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `speculo/.speculo/commands/<run>/report.md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。
+本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `speculo/.speculo/commands/retro/<YYYY-MM-DD>-<scope>-<topic>[-NN].md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。

package/template/skills/worktree-isolation/SKILL.md

@@ -2,58 +2,22 @@
 id: worktree-isolation
 type: skill
 name: Worktree Isolation
-description: 在独立 git worktree 中隔离推进一个 change 的原子能力；当 dev workflow 需要为某个 change 建立隔离分支与 .worktree/ 工作树、审查整条 change 分支树的全部 commit、或在收尾时把分支合并回原分支并清理时使用。默认不启用，仅在用户显式请求隔离时由调用方读取。
+description: 在独立 git worktree 中创建、审查、合并和清理 Speculo workflow change。
 ---
 
 # Worktree Isolation
 
-## 何时使用
+仅在用户明确要求 worktree 隔离时调用；调用方提供 runtime context 和当前 change。
 
-当 dev workflow 需要把一个 change 与原分支**物理隔离**地推进时使用。三个典型触发：
+## 状态字段
 
-- **建立隔离环境**（grill / change 创建）：为当前 change 新建独立分支与 `.worktree/<change>/` 工作树，代码与所有 Speculo 产物都落在 change 分支上，不污染原分支。
-- **审查整条分支树**（review）：审查必须覆盖 change 分支相对原分支的**全部 commit**，而不只是工作区 diff。
-- **合并回收**（finalize）：收尾验证通过后，把 change 分支合并回原分支，并清理 worktree 与分支。
+`worktree_enabled`、`base_branch`、`change_branch`、`worktree_path`、`worktree_status` 由调用方写入当前 change `.status.json`。
 
-**默认不启用。** 只有用户**显式请求**隔离（“用 worktree / 隔离这个 change”）时，调用方才读取并执行本 skill；未请求时调用方完全不加载本 skill，既有流程零行为变化。
+## 流程
 
-## 输入
+1. 确认 git 仓库、工作区状态和 `speculo/.speculo/` 跟踪策略；任一条件不满足时返回不可隔离原因。完成标准：创建前状态和降级选择清晰。
+2. 固定 `change_branch=speculo/<workflow>/<change>`、`worktree_path=.worktree/<change>`，读取 `references/create-worktree.md`。完成标准：分支、工作树和返回状态均真实存在。
+3. 所有代码和 change 产物在该工作树推进；review 时读取 `references/audit-branch-tree.md`。完成标准：审查覆盖 `base..change_branch` 全部 commit。
+4. Finalize 时读取 `references/merge-and-cleanup.md`，展示合并、删分支和删 worktree 计划并等待确认。完成标准：变更已进入 base、工作树/分支状态与 `.status.json` 一致，或明确 blocked。
 
-- 当前 git 仓库与**当前分支**（启用隔离时即记为 base 分支）
-- 当前 change 目录名（`YYYY-MM-DD-<kebab>`）与其分类 `<cat>`（dev | doc | person | ops）
-- 用户的隔离意图（是否显式请求）
-- 仓库 `.gitignore`
-
-本 skill 自带全部隔离程序，**不外读仓库 `docs/`**。
-
-## 输出
-
-- git 状态变更：隔离分支、`.worktree/<change>/` 工作树、合并与清理结果
-- **供调用方持久化的状态字段集**（本 skill 不自行选择持久化目录，由调用方 workflow 写入同一 change 的 `.status.json`）：
-
-  | 字段 | 类型 | 含义 |
-  |------|------|------|
-  | `worktree_enabled` | bool | 是否启用隔离 |
-  | `base_branch` | string | 原分支（启用隔离时的当前分支） |
-  | `change_branch` | string | 隔离分支，固定 `speculo/<cat>/<change>` |
-  | `worktree_path` | string | 工作树路径，固定 `.worktree/<change>` |
-  | `worktree_status` | string | created \| active \| merged \| removed |
-
-- 可归档摘要：base / change 分支、worktree 路径、合并与清理结论、残留风险
-
-## 执行步骤
-
-1. **判定可隔离性**：确认 (a) 在 git 仓库内，(b) 工作区干净或变更可接受，(c) 目标项目 `speculo/.speculo/` 被 git 跟踪（产物需随分支合并）。任一不满足 → **不创建**，向调用方报告原因并降级为非 worktree 模式。
-2. **命名**：base = 当前分支；`change_branch = speculo/<cat>/<change>`；`worktree_path = .worktree/<change>`。
-3. **创建**：见 `references/create-worktree.md`。完成后返回 `base_branch / change_branch / worktree_path` 与 `worktree_status: active` 供调用方写入。
-4. **隔离推进**：此后该 change 的全部工作（代码 + `speculo/.speculo/<cat>/<change>/` 产物）都在 `worktree_path` 内、`change_branch` 上进行。
-5. **审查全树**（review 时）：见 `references/audit-branch-tree.md`，覆盖 `base..change_branch` 的每个 commit。
-6. **合并回收**（finalize 时）：见 `references/merge-and-cleanup.md`，合并回 base、删分支、删 worktree。
-
-**破坏性步骤**（合并、删分支、删 worktree）必须先列计划、经用户确认再执行；合并冲突即停、不强推。
-
-## 渐进披露
-
-- `references/create-worktree.md`：建立隔离分支与 `.worktree/` 工作树时读取（grill / change 创建）。
-- `references/audit-branch-tree.md`：审查 change 分支树相对 base 的全部 commit 时读取（review）。
-- `references/merge-and-cleanup.md`：把 change 分支合并回原分支并清理时读取（finalize）。
+破坏性 git 动作逐项确认；冲突时停止并返回现状，不强推。

package/template/skills/worktree-isolation/references/audit-branch-tree.md

@@ -1,6 +1,6 @@
 # 审查 change 分支树
 
-worktree 模式下，review 必须覆盖 change 分支相对 base 的**全部 commit**，而不只是工作区 diff。调用方：`dev/R` review 的 setup 阶段。
+worktree 模式下，review 必须覆盖 change 分支相对 base 的**全部 commit**，而不只是工作区 diff。由当前 workflow 的 review route 调用。
 
 ## 输入
 
@@ -29,4 +29,4 @@ worktree 模式下，review 必须覆盖 change 分支相对 base 的**全部 co
 
 - 不替换用户显式指定的 fixed point。
 - 不遗漏任何 commit；clean-review 声明须确认已覆盖 `base..change_branch` 全部 commit。
-- 不自行选择持久化目录；审查字段由调用方写入 `speculo/.speculo/<cat>/<change>/.status.json`。
+- 不自行选择持久化目录；审查字段由调用方写入 `speculo/.speculo/<workflow>/changes/<change>/.status.json`。

package/template/skills/worktree-isolation/references/create-worktree.md

@@ -1,6 +1,6 @@
 # 创建隔离 worktree
 
-为当前 change 建立独立分支与 `.worktree/<change>/` 工作树。调用方：`dev/01` grill 的 Worktree Setup 阶段（条件）。
+为当前 workflow change 建立独立分支与 `.worktree/<change>/` 工作树。调用方只有在用户显式启用隔离时执行。
 
 ## 前置
 
@@ -11,7 +11,7 @@
 ## 命名
 
 - base 分支 = 启用隔离时的当前分支（`git rev-parse --abbrev-ref HEAD`）
-- change 分支 = `speculo/<cat>/<change>`
+- change 分支 = `speculo/<workflow>/<change>`
 - worktree 路径 = `.worktree/<change>`
 
 ## 步骤
@@ -21,11 +21,11 @@
 3. 创建分支与工作树：
 
    ```bash
-   git worktree add -b speculo/<cat>/<change> .worktree/<change>
+   git worktree add -b speculo/<workflow>/<change> .worktree/<change>
    ```
 
-4. 在工作树内初始化该 change 的 Speculo 产物目录 `speculo/.speculo/<cat>/<change>/` 与 `.status.json`（由调用方按持久化契约写入）。
-5. 提示调用方：此后所有工作在 `.worktree/<change>/` 内、`speculo/<cat>/<change>` 分支上进行。
+4. 在工作树内初始化该 change 的 Speculo 产物目录 `speculo/.speculo/<workflow>/changes/<change>/` 与 `.status.json`（由调用方按持久化契约写入）。
+5. 提示调用方：此后所有工作在 `.worktree/<change>/` 内、`speculo/<workflow>/<change>` 分支上进行。
 
 ## 返回给调用方
 
@@ -34,6 +34,6 @@
 
 ## 边界
 
-- 不自行选择持久化目录；字段值返回给调用方 workflow 写入 `speculo/.speculo/<cat>/<change>/.status.json`。
+- 不自行选择持久化目录；字段值返回给调用方 workflow 写入 `speculo/.speculo/<workflow>/changes/<change>/.status.json`。
 - 分支或工作树已存在时不覆盖、不复用，停止报告。
 - 非 git 仓库 / 工作区不可用 / `speculo/.speculo/` 未被跟踪时降级为非 worktree 模式。