@namewta/speculo 1.0.18 → 1.0.20

package/template/skills/engineering-standards-builder/references/entry-procedure.md

@@ -1,154 +0,0 @@
-# Entry procedure
-
-# Engineering Standards Builder
-
-本 Skill 只在用户明确调用时运行。它不会在新项目中自动启动，也不把 Builder 自带的通用建议直接复制成项目规范。
-
-目标是先理解当前项目真实的代码、目录、配置、测试、CI 与模板，再生成一组可长期复用的项目专属 Skill：一个稳定的工程规范路由入口，以及零个或多个有独立触发价值的领域 Skill。
-
-```text
-项目事实 + 用户指定的重点范围 + 已确认目标
-  -> 证据审计与冲突收敛
-  -> 最小充分 Skill Set
-  -> .agents/skills/
-```
-
-## 产物与所有权
-
-始终生成根路由：
-
-```text
-.agents/skills/
-├── engineering-standards/
-│   ├── SKILL.md
-│   ├── generated-skill-set.json
-│   └── references/project/
-│       ├── 00-project-profile.md
-│       ├── 01-module-map.md
-│       ├── 02-decisions-and-exceptions.md
-│       ├── 03-skill-map.md
-│       ├── 04-source-and-template-map.md
-│       └── review-checklist.md
-└── <optional-domain-skill>/
-    ├── SKILL.md
-    └── references/...
-```
-
-`engineering-standards` 是规范权威与路由器；领域 Skill 负责可独立触发的实现导航，不重复定义冲突规则。`generated-skill-set.json` 只登记 Builder 拥有的 `.agents/skills/*` 路径。刷新时不得改动或删除清单之外的 Skill。
-
-## 最小原则
-
-- 不按语言、目录或 Agent 数量机械拆 Skill。
-- 能由根路由和少量 references 清楚表达时，不新增领域 Skill。
-- 没有项目证据的规则不生成；Builder references 只提供审计维度与 fallback。
-- 不复制项目源码、FM 模板或脚手架正文；引用其真实路径并说明适用条件、集成步骤和验证方式。
-- 不新增配置文件、参数、时间戳、hash 或模型元数据来制造形式化负担。
-- 扫描深度、文件数和字节限制只是脚本内部资源保护，不是用户需要决策的项目规范。
-
-## 执行流程
-
-### 1. 确定项目根与学习范围
-
-从用户当前工作目录、Git/Workspace 边界和用户指定的代码或目录确定真实项目根。记录需要重点学习的模块、代码、目录、模板或脚手架；未指定时覆盖所有可编辑模块。
-
-读取现有 `AGENTS.md`、`CLAUDE.md`、贡献文档、架构文档和 `.agents/skills/`，但将它们视为待验证证据。识别 generated、vendor、build、cache、fixture 与冻结目录。发现已有 `generated-skill-set.json` 时进入 refresh；只有 legacy `engineering-standards` 时，在计划中声明接管该根 Skill，其他现有 Skill 一律视为非 Builder 所有。
-
-冲突优先级见 [治理与证据优先级](rules/00-governance-and-precedence.md)，路径和 scope 见 [证据、拓扑与作用域](rules/02-evidence-topology-and-scope.md)。本阶段只读。
-
-**完成标准**：项目根、重点范围、排除范围、现有规范和 Builder 写入边界明确。
-
-### 2. 建立确定性事实基线
-
-运行扫描器并捕获 stdout；默认不在项目中持久化 inventory：
-
-```bash
-node <skill-root>/scripts/discover-project.mjs --root <project-root> --pretty
-```
-
-扫描合同见 [项目发现合同](rules/01-project-discovery.md)。扫描器只提供拓扑基线，不能替代源码审计。继续读取真实 manifest/build 配置、CI 命令、公共入口、代表性实现、测试、消费者与项目模板。
-
-**完成标准**：每个可编辑模块有路径、技术栈、入口、质量门禁和证据；扫描限制、冲突与未知项已记录。
-
-### 3. 用 Agent Team 分域取证
-
-当运行环境支持 Agent Team 且存在两个以上可独立审计的证据域时，默认由 leader 并行派发只读 scout。证据域按项目真实边界划分，例如架构与公共 API、后端、前端、公共复用、测试与 CI、FM/脚手架；不得套用固定角色表。
-
-leader 是唯一写入者。每个 scout 必须返回同一份精简证据合同：
-
-```text
-Scope
-Observed capability
-Canonical source paths
-Mature implementations
-Template paths
-Consumers and tests
-Applicable conditions
-Legacy/counterexamples
-Conflicts/unknowns
-Recommended skill boundary
-```
-
-leader 必须复读高影响路径，检查跨域冲突，并把同一事实的重复报告合并。Agent Team 不可用或任务不可合理拆分时，leader 按相同合同顺序审计；结果标准不变。
-
-**完成标准**：重要规范均有真实路径、消费者或测试支撑；反例、旧实现和未知项没有被“多数模式”掩盖。
-
-### 4. 收敛规范与 Skill 边界
-
-先识别项目已经声明的 canonical 模板或代码样板，例如 `docs/fm/**`、scaffold、generator assets。模板与成熟代码冲突时，判断它是目标模板、过期模板还是仅负责骨架，并记录 current、target 与 migration；不得静默任选一方。
-
-只有同时满足以下条件才创建领域 Skill：
-
-1. 有可独立描述的触发场景；
-2. 会在多次开发中复用；
-3. 有充分的项目源码、模板、测试或配置证据；
-4. 与根路由或其他领域 Skill 边界清晰；
-5. 独立后能明显减少无关上下文。
-
-否则内容留在 `engineering-standards`。领域 Skill 名称来自项目语义，不使用固定列表或固定数量。高影响未知项按 [决策收敛合同](rules/03-interview-and-decisions.md) 询问；用户已授权直接生成时，将无法安全推断的事项记为 `pending-decision`。
-
-只读取与项目事实匹配的 [通用规则索引](rules/README.md)、[TypeScript/JavaScript](typescript/README.md)、[Java](java/README.md)、[Go](go/README.md) 或 [Rust](rust/README.md) references。内置语言包和 [未内置语言 fallback](rules/16-language-adapter-contract.md) 是检查清单，不是高于项目代码的规范来源。
-
-**完成标准**：每个生成 Skill 都有独立价值和证据边界；没有为了覆盖目录或技术栈而过度拆分。
-
-### 5. 计划、生成与刷新
-
-先展示精简计划：模块与证据摘要、Skill Map、每个 Skill 的来源路径、保留/更新/新增/删除项、冲突决策和验证命令。用户已在当前请求中授权实施时，展示后直接执行。
-
-按 [Skill Set 生成合同](rules/14-generation-contract.md) 和 [模板索引](../templates/README.md) 生成。所有项目引用使用项目根相对路径，并说明：何时读取、它负责什么、输出位置、需要哪些手工集成、运行什么验证。
-
-先准备完整候选内容并校验，再替换 Builder 拥有的文件。刷新规则：
-
-- 只更新或删除旧 `generated-skill-set.json` 登记的路径；
-- 名称与未登记 Skill 冲突时停止覆盖并重新命名或询问；
-- 保留仍有效的用户决策、例外和项目特有知识；
-- 删除或重命名必须在计划中显式列出；
-- 候选验证失败时保留旧 Skill Set；发布后验证失败时恢复旧内容；
-- 相同项目事实与决策重复运行应无无意义 diff。
-
-**完成标准**：根路由、领域 Skill、项目引用与所有权清单一致，清单外 Skill 未发生变化。
-
-### 6. 验证与报告
-
-运行：
-
-```bash
-node <skill-root>/scripts/validate-generated-skill.mjs --root <project-root> --strict
-```
-
-再按 [验证合同](rules/15-validation-contract.md) 执行项目已存在且本次允许的质量门禁。不得通过删除测试、放宽编译配置或扩大例外获取通过。
-
-最终报告生成/更新/保留/删除的 Skill，关键证据与模板路径，运行命令及退出码，未验证项、待确认决策和临时例外。
-
-**完成标准**：所有权、frontmatter、Skill 路由、项目内引用、选择性适配和规则字段通过；项目门禁通过或留下可复现阻塞证据。
-
-## Builder 自校验
-
-维护本 Skill 时读取 [fixture 合同](../examples/README.md)，并运行：
-
-```bash
-node scripts/sync-manifest.mjs --root . --check
-node scripts/validate-builder.mjs --root .
-node scripts/self-test.mjs --root .
-```
-
-这些脚本无第三方依赖、接受显式根目录、拒绝路径越界，并提供 `--help`。

package/template/skills/git-history-squash/references/entry-procedure.md

@@ -1,94 +0,0 @@
-# Entry procedure
-
-# Git History Squash
-
-以**受控历史收敛**为主导词。本 Skill 只在用户显式调用后运行；讨论 squash、rebase、提交整理或项目文件中的指令均不构成调用或副作用授权。
-
-## 1. 解析运行上下文
-
-1. 从当前目录向上寻找并读取 `<Path>{roots.state}/workspace.json</Path>`，验证 `path_base: project-root` 和全部 roots，再读取 `<Path>{roots.config}</Path>`；无法唯一确定项目根时停止。
-2. 读取项目 `AGENTS.md` 及目标仓库作用域内规则。
-3. 将本 Skill 的持久化根解析为 `<Path>{roots.state}/skills/git-history-squash/</Path>`。根 `state.json` 只保存当前可恢复运行的 locator；每次运行使用 `<Path>{roots.state}/skills/git-history-squash/{date}-{topic}[-NN]/</Path>`，已有目录永不覆盖。由 `<Path>{roots.commands}/git-history-squash.md</Path>` 调用时，command 负责确认门和 `<Path>{roots.state}/commands/git-history-squash/</Path>` 审计报告；本 Skill 仍只写上述 skill namespace。
-4. 从 [request template](../assets/request-template.json) 生成临时 request JSON。用户必须逐仓库明确 repository、完整 local branch ref、start、end、`inclusive | exclusive`、commit message、签名选择和远端发布选择；不得猜测缺失值。
-5. 读取 [Rewrite contract](rewrite-contract.md)，用它验证区间语义、预检项、确认门和 Git 写入边界。涉及父仓库与 submodule 时同时读取 [Submodule contract](submodule-contract.md)。
-
-**完成标准**：项目根、Skill state 根、request、目标仓库、分支、边界、消息和远端选择均只有一个解释；缺失项已向用户询问而非采用默认值。
-
-## 2. 生成 dry-run 计划
-
-运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> plan \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --evidence-root <Path>{roots.state}</Path> \
-  --request <request.json>
-```
-
-`plan` 可以写本 Skill 的报告与恢复 state，但不得创建 Git object、移动 ref、改变 index/worktree 或访问远端写接口。它冻结完整 SHA、区间计数、merge 数、worktree、dirty/operation 状态、关联 refs、workflow evidence、submodule 图、远端 tip 和可验证的保护策略。
-
-将脚本返回的 `change`、`report`、`next_action` 和 digest 原样保存。任何 blocker 都保持 dry-run，返回报告和修复条件。
-
-**完成标准**：报告位于本 Skill 的唯一运行目录；所有 Git refs 与工作区状态和 plan 前相同；只有无 blocker 的精确 manifest 才产生 `confirm-local`。
-
-## 3. 本地确认与执行
-
-向用户展示报告中的完整本地 manifest：每个 repository、branch、start/end/baseline SHA、first-parent/reachable/merge 数、commit message、签名选择、backup ref、关联 refs/worktrees，以及 submodule 执行层。
-
-只有用户在当前对话中明确确认该 manifest 和 `plan_digest` 后运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> apply \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --change <change> \
-  --confirm-plan <plan_digest>
-```
-
-脚本执行前重验完整计划。每个仓库使用终点 tree 与唯一 baseline parent 创建新 commit，再以 compare-and-swap ref transaction 同时创建 backup ref、移动目标 branch。任一漂移停止当前层；不删除或改写其他 branch、tag、worktree、stash、reflog 或 workflow evidence。
-
-多层 submodule 图只执行当前 eligible 层；下层要求发布时，父层必须等下层远端验证后重新产生新的 `plan_digest` 并再次确认。
-
-**完成标准**：脚本重读证明每个已处理仓库的新 tree、parent、提交数、backup ref 和工作区状态满足合同；失败时 state/report 明确区分已完成与未完成仓库。
-
-## 4. 远端确认与发布
-
-当脚本返回 `confirm-publish` 时，向用户展示完整远端 manifest：repository、remote、remote branch、冻结的 old SHA、local new SHA、保护策略和发布顺序。
-
-只有用户在当前对话中明确确认该 manifest 和 `publish_digest` 后运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> publish \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --change <change> \
-  --confirm-publish <publish_digest>
-```
-
-发布只使用精确 `--force-with-lease=<ref>:<old-sha>` 和单一显式 refspec。远端 tip 漂移、保护策略不允许、push 失败或回读不等于 new SHA 时立即停止；不回滚已经发布的其他仓库。
-
-**完成标准**：每个成功远端 branch 回读精确等于 new SHA；父仓库 gitlink 指向的 child SHA 已先从对应远端 branch 到达；未发布仓库及恢复步骤已进入报告。
-
-## 5. 恢复或结束
-
-读取 [Recovery contract](recovery-contract.md)。中断或重入时先运行：
-
-```bash
-node <Path>{roots.skills}/git-history-squash/scripts/git-history-squash.mjs</Path> status \
-  --root . \
-  --state-root <Path>{roots.state}/skills/git-history-squash</Path> \
-  --change <change>
-```
-
-实际 refs/remotes 与 state 一致时，使用脚本返回的下一 digest 回到步骤 3 或 4。漂移时保持 blocked，按报告生成新的精确恢复计划并重新取得授权；本 Skill 不自动执行恢复或清理。
-
-**完成标准**：运行状态为 `completed-local | completed-published | blocked-partial` 之一；报告包含全部确认、验证、远端结果和精确恢复命令，且没有 token、email、凭证 URL 或机器绝对路径。
-
-## 固定边界
-
-- `end` 必须等于目标 local branch tip；v1 不改写分支内部区间。
-- `start` 必须位于 `end` 的 first-parent 链；`inclusive` 使用 `start^1` 为 baseline，root start 产生无 parent 新提交；`exclusive` 保留 start 并以其为 baseline。
-- dry-run 不 fetch、不 stash、不 checkout、不创建 commit/tree、不移动 ref、不改变 index、不 push。
-- 本 Skill 不调用 `rebase`、普通 `--force`、没有精确 expected SHA 的 lease、`reset --hard` 或自动 cleanup。
-- GitHub 远端只有在 protection/rules 查询成功且允许非 fast-forward update 时才发布；无法验证策略的远端只生成本地计划。

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

@@ -1,19 +0,0 @@
----
-name: github-npm-ops
-description: Perform a requested GitHub issue/PR/CI/security or npm release operation with its matching reference contract.
-metadata: {"speculo-id": "github-npm-ops", "speculo-kind": "skill", "speculo-legacy-name": "GitHub npm Ops"}
----
-
-# GitHub npm Ops
-
-This file is the routing entry. Read [`references/entry-procedure.md`](references/entry-procedure.md) only after this skill is selected. Read a named reference there only for the active branch.
-
-## Scope
-
-- Trigger: Perform a requested GitHub issue/PR/CI/security or npm release operation with its matching reference contract.
-- Output and write owner remain those declared by the entry procedure and the owning command/workflow.
-- Do not infer missing scope, credentials, target, or authorization.
-
-## Stop
-
-Stop before side effects when the required input, owner, reference, confirmation, schema, or recovery evidence is missing; report the exact blocker and preserve any dry-run evidence.

package/template/skills/github-npm-ops/references/ci-and-security-ops.md

@@ -1,178 +0,0 @@
-# CI 排障与安全告警巡检
-
-两部分内容：
-
-1. CI 失败的结构化排障流程（与发布专用的 release workflow 相区分）
-2. 安全告警（Dependabot、secret scanning、code scanning）的巡检节奏与响应模板
-
-## CI 排障
-
-### 第一步：拿到日志
-
-```bash
-# 列最近失败的 run
-gh run list --status failure --limit 10 \
-  --json databaseId,displayTitle,headBranch,conclusion,event
-
-# 查单次失败的完整日志
-gh run view <databaseId> --log-failed
-
-# 只看失败步骤的摘要（更快）
-gh run view <databaseId> --log-failed 2>&1 \
-  | grep -E "##\[error\]|Error:|FAIL|error TS" | head -40
-```
-
-### 第二步：判定是真实失败还是 flaky
-
-- **真实失败**：代码层面的 bug、依赖变更、lint 违规、测试逻辑错误
-- **Flaky**：网络抖动、时序竞争、外部服务临时 500、测试隔离不够
-
-判别方法：
-
-1. 在相同 commit 上 `gh run rerun <id> --failed`，连续失败 2 次 = 真实
-2. 查看测试名是否出现在历史 flaky 列表里
-3. 看错误是否与环境相关（如 DNS、超时）
-
-### 第三步：真实失败的修复
-
-按错误类型对应：
-
-| 错误类型        | 典型信号                          | 处理方向                                   |
-| --------------- | --------------------------------- | ------------------------------------------ |
-| Lint            | `error TS*` / `Parsing error`     | 在本地 `pnpm lint --fix`，推新 commit      |
-| 类型            | `Type 'X' is not assignable`      | 修类型定义，或在必要处用类型守卫           |
-| 测试逻辑        | 断言失败、期望值不匹配             | 检查最近是否改了被测行为，更新测试或代码   |
-| 环境依赖        | `command not found` / 版本不符    | 对齐 `setup-node` 版本与 `packageManager`  |
-| 依赖冲突        | peer dep 警告 + 运行时错误         | 检查 lockfile 变更，pin 冲突的 transitive  |
-| 构建产物        | `Cannot find module './dist/...'` | 确认构建步骤在测试/发布前执行              |
-
-### 第四步：Flaky 的处理
-
-- **临时**：加 retry（`jest.retryTimes(2)` 或 vitest 的 `retry`）
-- **中期**：在 issue 里记录 flaky 模式，打 `flaky-test` 标签
-- **长期**：重构测试用例（解耦外部服务、用 fake clock、隔离共享状态）
-
-**避免**：无脑 `gh run rerun` 把失败掩盖掉。Flaky 积累会慢慢腐蚀对 CI 的信任。
-
-### CI 性能优化
-
-查询 workflow 耗时：
-
-```bash
-gh run list --workflow ci.yml --limit 20 \
-  --json databaseId,conclusion,createdAt,updatedAt \
-  --jq '.[] | "\(.databaseId) \((.updatedAt | fromdate) - (.createdAt | fromdate))s"'
-```
-
-常见加速手段：
-
-- 缓存 `~/.pnpm-store` / `node_modules/.cache`
-- 分离 lint / test / build 到并行 job
-- Matrix 测试（多 Node 版本）加 `fail-fast: false` 让其他 cell 跑完
-- 把重测试移到 nightly schedule 而不是 PR
-
-## 安全告警巡检
-
-GitHub 提供三类安全告警，都可以通过 `gh api` 查询。
-
-### Dependabot（依赖漏洞）
-
-```bash
-# 列所有未解决告警
-gh api repos/{owner}/{repo}/dependabot/alerts \
-  --jq '.[] | select(.state=="open") | {severity: .security_advisory.severity, pkg: .security_vulnerability.package.name, summary: .security_advisory.summary}'
-
-# 按严重性过滤
-gh api repos/{owner}/{repo}/dependabot/alerts \
-  --jq '.[] | select(.security_advisory.severity=="critical" or .security_advisory.severity=="high")'
-```
-
-响应节奏：
-
-- **critical**：24h 内评估；有 fix 版本就立即升级，无则评估临时缓解（移除依赖、关闭受影响功能）
-- **high**：一周内处理
-- **medium / low**：入 backlog，定期批量清
-
-Dependabot 自动开 PR 时，标签是 `dependencies`：
-
-```bash
-# 看当前自动 PR
-gh pr list --label "dependencies" --state open \
-  --json number,title,createdAt,mergeable
-```
-
-安全升级的 PR 审查要点：
-
-1. 看 diff 是否只是版本 bump（无其它改动）
-2. CI 绿 → 大多数可以合
-3. major 版本要看 release notes，可能有 breaking change
-
-可考虑给 `dependabot.yml` 配自动合并策略（低风险的 patch/minor）。
-
-### Secret Scanning
-
-```bash
-# 所有 secret 泄露告警
-gh api repos/{owner}/{repo}/secret-scanning/alerts \
-  --jq '.[] | select(.state=="open") | {type: .secret_type, location: .locations_url}'
-```
-
-告警响应（**关键操作立即做完**）：
-
-1. **先撤销**：在对应服务（npm、AWS、Stripe...）作废泄露的 secret
-2. **再修复**：从 git history 里清除（可能需要 force push 或让上游 rotate）
-3. **最后标记**：在 GitHub UI 将告警标记为 `resolved`
-
-**不要**在撤销前 force push：secret 可能已被爬虫抓走，只靠 git history 清理不安全。
-
-### Code Scanning（CodeQL 等）
-
-```bash
-gh api repos/{owner}/{repo}/code-scanning/alerts \
-  --jq '.[] | select(.state=="open") | {rule: .rule.id, severity: .rule.security_severity_level, path: .most_recent_instance.location.path}'
-```
-
-处理优先级与 Dependabot 一致，但更偏代码层面（SQL 注入、XSS、不安全反序列化等）。
-
-### 巡检节奏
-
-**每周**（推荐周一）：
-
-```bash
-# 一次性看三类告警
-echo "=== Dependabot ==="
-gh api repos/OWNER/REPO/dependabot/alerts \
-  --jq '[.[] | select(.state=="open")] | length'
-
-echo "=== Secret scanning ==="
-gh api repos/OWNER/REPO/secret-scanning/alerts \
-  --jq '[.[] | select(.state=="open")] | length'
-
-echo "=== Code scanning ==="
-gh api repos/OWNER/REPO/code-scanning/alerts \
-  --jq '[.[] | select(.state=="open")] | length'
-```
-
-记录在维护者的周报中，critical/high 数量单独标出。
-
-### 回复 public 报告的安全问题
-
-若有人在 public issue 里报了漏洞：
-
-1. **立即** 引导到 private 渠道（Security Advisory 或邮箱）
-2. 关闭 issue 并删除敏感细节
-3. 在私有渠道跟进，准备 advisory 草稿
-
-```markdown
-感谢报告。为了保护用户，请通过 GitHub Security Advisory（
-https://github.com/OWNER/REPO/security/advisories/new）或发邮件至
-security@example.com 提交详情。本 issue 将被关闭以避免扩散。
-```
-
-## CI 与安全的联动
-
-发布 workflow 失败需要结合 CI 与安全一起看：
-
-- Workflow 在 `pnpm audit` 步骤失败 → 先看 Dependabot 告警
-- Publish 被拒（`E403`）且 token 刚生成 → 检查是否有 secret scanning 告警提示 token 已泄露
-- CI 在 `npm install` 阶段网络错误 → 区分 npm registry 抖动 vs CI 节点出口异常

package/template/skills/github-npm-ops/references/entry-procedure.md

@@ -1,25 +0,0 @@
-# Entry procedure
-
-# GitHub npm Ops
-
-## 输入
-
-- `operation`：`issue-read | pr-read | issue-search | issue-create | issue-comment-close | ci-security | release-preflight | release | recover`。
-- 仓库、目标分支、issue/PR/run id 或目标版本。
-- package metadata、release workflow、CHANGELOG 和可选 docs-sync state。
-
-## 分支
-
-1. **Issue transport**：执行读取、去重、创建或关闭时读取 `references/issue-transport.md`；需要社区分类、标签或 PR 治理判断时再读取 `references/issue-pr-triage.md`。完成标准是规范化结果、dry-run/授权边界和执行后重读均有证据。
-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 中唯一分支。
-
-## 输出
-
-- Issue/PR transport 返回规范化 JSON、dry-run 计划或经确认后的执行结果；不写调用方 state。
-- 其他分支返回操作建议或经确认后的执行结果、风险和验证证据。
-- 发布后三端验证：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

@@ -1,123 +0,0 @@
-# 失败回滚与恢复剧本
-
-> 命令正文给出 4 类失败场景的对照表；这里给出每类的完整恢复 SOP、配套命令与错误码映射。
-> 通用前置：所有恢复操作前先 `git fetch --tags` 同步远端 tag 状态，避免本地与远端不一致。
-
-## 场景 A：publish 之前任何步骤失败（含 build / verify-bin / Extract release notes）
-
-**特征**：`gh run view <id>` 显示 fail 步骤位于 `Publish to npm` 之前；npm 端尚未上传任何 tarball。
-
-**恢复**：可重发同 tag。
-
-```bash
-# 1. 删本地 + 远端 tag
-git tag -d vX.Y.Z
-git push origin :refs/tags/vX.Y.Z
-
-# 2. 修代码（修 lint / 修测试 / 补 CHANGELOG 段落 / 修 release.yml）
-#    修复完后落新的非 release commit，保持 release commit 干净
-
-# 3. （若 release commit 已被 push）amend / 追加修复 commit 都可
-#    重要：若需要修改 package.json 或 CHANGELOG.md，最好新落一个 fix commit
-#    再用 --amend 合并到 release commit 后 force-push（仅个人分支或本地未推时）
-
-# 4. 重新打 tag 指向（可能更新过的）release commit
-git tag vX.Y.Z <release-commit-sha>
-git push origin vX.Y.Z
-```
-
-**错误码映射**：失败步骤决定 E 码，常见有 `E004_noVerificationEvidence`（lint/test/build fail）、`E001_missingPrerequisiteArtifact`（CHANGELOG 段落抽空）。
-
----
-
-## 场景 B：publish 之后步骤失败（如 Create GitHub Release fail）
-
-**特征**：`gh run view <id>` 中 `Publish to npm` 步骤 success；其后步骤（多为 `Create GitHub Release`）fail。npm 已成功上传。
-
-**恢复**：**不要**重发 npm（同版本号永久不可重发），仅手动补 GitHub Release。
-
-```bash
-# 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. 三端再次校验——见 release-pipeline.md Phase 5
-```
-
-**错误码映射**：通常是基础设施层错误（GitHub API 抖动 / token 权限缺 `contents: write`），不计入项目业务错误字典。
-
----
-
-## 场景 C：`Publish to npm` 本身上传失败
-
-**特征**：`Publish to npm` 步骤 fail；npm 端 `npm view <pkg> version` 仍是上一版本（未上传成功）。
-
-**恢复**：可重发同 tag（与场景 A 相同流程），但务必先确认 npm 端没有"半上传"状态。
-
-```bash
-# 确认 npm 没收到 tarball
-npm view <pkg> versions --json | jq '. | index("X.Y.Z")'   # 应输出 null
-
-# 删 tag → 修因（多为 NPM_TOKEN 失效 / provenance 配置 / package.json#repository.url 不匹配）
-git tag -d vX.Y.Z
-git push origin :refs/tags/vX.Y.Z
-
-# 修复后重打同 tag
-git tag vX.Y.Z <release-commit-sha>
-git push origin vX.Y.Z
-```
-
-常见根因：
-
-| 根因 | 修复 |
-|------|------|
-| `NPM_TOKEN` 过期 / 失效 | 重新生成 Granular Token，更新仓库 secret |
-| `provenance` 失败 | workflow 缺 `id-token: write` 权限；package.json `repository.url` 不严格匹配 GitHub URL |
-| 包名 scope 不属于当前 token | 检查 token 配置的 scope；首次发布 scoped 包需 `--access public` |
-| 网络抖动 / npm registry 临时不可用 | 等几分钟后 rerun |
-
----
-
-## 场景 D：npm 已成功上传 + 任何后续问题
-
-**特征**：`npm view <pkg> version` 已是 `X.Y.Z`。
-
-**铁律**：npm 不允许重发同 `version`（unpublish 过也不行）。**禁止**重打同 tag、**禁止**修代码后试图覆盖。
-
-**恢复**：
-
-```bash
-# 1. bump 到 X.Y.(Z+1)，从 Phase 3 重走整条流水线
-重新执行调用方的发布流程，并显式指定版本 X.Y.(Z+1)
-
-# 2. 在 CHANGELOG 中诚实记录本次发布的偏差
-#    在 [X.Y.(Z+1)] 段落开头加一句 "supersedes vX.Y.Z due to <根因>"
-```
-
-**错误码映射**：场景 D 通常是上游错误溢出（场景 B/C 处理不当后果），不单独列 E 码；流程上要求**事后复盘**，把可复用根因输出给调用方，由其按所属 workflow 规则写入声明的 lessons/knowledge store（本 skill 不自行选择 workflow 或持久化目录）。
-
----
-
-## 场景共性：何时触发 P9（反重复失败原则）
-
-> 反重复失败原则：同根因连续失败时，必须先声明新尝试与上次的差异。
-
-- **同根因连续失败 ≥ 2 次** → 必须先停手，**书面声明**本次重试与上次的差异
-- 未声明差异即重试 → 触发 `E010_repeatedFailurePattern`，发布编排流程应主动暂停，等待用户输入差异声明
-
-例：场景 C 中 NPM_TOKEN 失效连续两次 fail，第二次失败后必须先确认 token 已真正更新（粘贴新 token 的尾 4 位摘要 / GitHub Secrets 更新时间），再继续。
-
----
-
-## 与 github-npm-ops skill 的关系
-
-本文件是发布编排视角下的失败恢复入口；更细粒度的失败案例（如 EUSAGE / E422 / provenance 错误码、package.json 字段错误）见 `troubleshooting-playbook.md`。
-
-| 失败位置 | 看本文件 | 看 github-npm-ops troubleshooting-playbook |
-|---------|---------|---------------------------------------|
-| Phase 1–6 编排逻辑层面 | ✅ | ❌ |
-| release.yml 内部步骤的具体错误码 | ❌ | ✅ |
-| npm 错误码（E403 / E404 / E422 / EUSAGE） | ❌ | ✅ |