@namewta/speculo 0.1.0

package/speculo/commands/status.md

@@ -0,0 +1,51 @@
+---
+id: status
+type: command
+name: Global Status
+description: 按需聚合全局工作流状态（替代物理 STATUS.json）
+keywords: [status, 状态, 进度]
+---
+
+# Status 命令
+
+## 归档路径模式
+
+可选产物归档至：`../.speculo/commands/<YYYY-MM-DD>-status-<topic>/`
+（若仅是回显报告、不需要持久化时可不归档）
+
+## 调用的 skills
+
+无
+
+## 执行步骤
+
+1. 读取已存在的 `../.speculo/<cat>-status.json`，当前内置分类至少包括 `dev` 与 `doc`。缺失时报告缺失路径，并建议按 `docs/adopting.md` 重新运行 `speculo init`，或创建空索引 `{"active":[]}`。
+2. 对每个索引的 `active[]` 条目，读取 `../.speculo/<cat>/<change>/.status.json`。读取失败时把该 change 标记为 `broken-index`，不要擅自删除索引项。
+3. 扫描 `../.speculo/<cat>/*/.status.json`，找出 `change_status: completed` 且尚未位于 `../.speculo/archive/` 的待归档 change。
+4. 聚合输出：
+   - 各分类 active 数量、completed 待归档数量、broken-index 数量
+   - 最近更新的 5 个 change（按 `updated_at` 倒序）
+   - 当前可能阻塞项：`phase_history` 最后一项为 `blocked`，或 `updated_at` 超过 14 天未变化
+   - 推荐下一步：优先处理 broken-index，其次处理 blocked，再推荐继续最近 active change 的 `current_phase`
+5. 用户要求持久化快照时，把报告写入 `../.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`；否则只在对话中返回。
+
+## 产物模板（snapshot.md，可选）
+
+> **服务命令：** `status.md`
+> **产物文件名：** `snapshot.md`
+
+```markdown
+# Status Snapshot
+
+## 快照时间
+[TODO: ISO 8601 时间戳。]
+
+## 分类汇总
+[TODO: 按分类列出 active 数量、completed 待归档数量和 broken-index 数量]
+
+## 最近活跃 Changes
+[TODO: 列出最近 5 个更新的 change + 分类 + 当前 phase]
+
+## 可能僵尸 Changes
+[TODO: 超过 N 天未更新的 change 清单]
+```

package/speculo/commands/write-a-skill.md

@@ -0,0 +1,46 @@
+---
+id: write-a-skill
+type: command
+name: Write A Skill
+description: 创建或审查新的 Speculo skill 草稿
+keywords: [skill, create, write, 技能]
+---
+
+# Write A Skill 命令
+
+## 归档路径模式
+
+产物归档至：`../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/`
+
+## 调用的 skills
+
+- `../skills/speculo-write/SKILL.md` — 用户要求创建、审查或改进可复用 skill 时读取；该 skill 自带 skill authoring 规范。
+
+## 执行步骤
+
+1. 读取 `../skills/speculo-write/SKILL.md`，并按其 `references/skill-authoring-sop.md` 内化 skill 规范。
+2. 先收集技能用途、触发条件、输入输出、脚本需求和示例需求。
+3. 写文件前列出将创建或修改的路径，并等待用户明确确认。
+4. 用户确认后，按 Speculo 契约创建 `../skills/<name>/SKILL.md` 及可选 `references/`、`scripts/`、`examples/`。
+5. 把设计摘要、影响路径和验证结果写入 `../.speculo/commands/<YYYY-MM-DD>-write-a-skill-<topic>/report.md`。
+
+## 产物模板（report.md）
+
+> **服务命令：** `write-a-skill.md`
+> **产物文件名：** `report.md`
+
+```markdown
+# Write A Skill Report
+
+## 技能目标
+[TODO: 描述新 skill 的任务、触发条件和使用者。]
+
+## 影响路径
+[TODO: 列出本次创建或修改的路径。]
+
+## 用户确认
+[TODO: 记录用户确认创建或修改文件的原始内容摘要。]
+
+## 验证结果
+[TODO: 记录 frontmatter、自包含性、渐进披露和脚本检查结果。]
+```

package/speculo/skills/caveman/SKILL.md

@@ -0,0 +1,38 @@
+---
+id: caveman
+type: skill
+name: Caveman
+description: 启用或关闭超压缩沟通模式以降低 token 消耗；当用户要求 caveman mode、少 token、极简技术表达，或调用 command/caveman 时使用。
+---
+
+# Caveman
+
+## 何时使用
+
+当用户要求 `caveman mode`、`talk like caveman`、`use caveman`、少 token、极简表达、`be brief`，或调用对应 command 时使用。
+
+当用户要求 `stop caveman`、`normal mode` 或明确恢复正常表达时关闭。
+
+## 输入
+
+- 用户对沟通模式的启用、关闭或保持要求
+- 当前对话中的技术事实、风险和下一步动作
+- 需要原样保留的代码、命令、错误信息或用户引用
+
+## 输出
+
+- 保留技术准确性的压缩回复风格
+- 必要时对安全风险、不可逆操作或多步骤顺序使用完整清晰表达
+- 不产生 `.speculo/` 或 `.status.json` 持久化产物
+
+## 执行步骤
+
+1. 判定用户是在启用、关闭还是检查 caveman mode。
+2. 启用后跨轮保持，直到用户明确关闭。
+3. 使用 `references/compression-rules.md` 的压缩规则、例外和示例。
+4. 原样保留代码块、命令、错误信息和需要精确引用的文本。
+5. 遇到安全警告、不可逆操作确认、易误读的多步骤序列或用户反复澄清时，暂时退出压缩表达；清晰部分结束后恢复。
+
+## 渐进披露
+
+- `references/compression-rules.md`：启用 caveman mode 或判断何时暂时退出压缩表达时读取。

package/speculo/skills/caveman/references/compression-rules.md

@@ -0,0 +1,102 @@
+# Caveman Compression Rules
+
+## 持久性
+
+一旦触发，每次回复都保持激活。多轮对话后不回退，不漂移回普通表达。
+
+如果不确定是否仍激活，就继续保持。只有当用户说 `stop caveman`、`normal mode` 或等价指令时才关闭。
+
+## 压缩规则
+
+去除：
+
+- 冠词和不影响含义的连接词
+- 填充词，如 just、really、basically、actually、simply
+- 客套话，如 sure、certainly、of course、happy to
+- 模糊化表达和不必要的铺垫
+
+优先使用：
+
+- 句子片段
+- 短同义词，例如用 `big` 而不是 `extensive`
+- 常见技术缩写，例如 DB、auth、config、req、res、fn、impl
+- 箭头表示因果关系，例如 `X -> Y`
+- 一个词能说清时不用两个词
+
+保持精确：
+
+- 技术术语不降级
+- 代码块不改写
+- 错误信息原样引用
+- 不为了短而省略关键前提、风险或边界
+
+## 输出模式
+
+默认句式：
+
+```text
+[东西] [动作] [原因]。[下一步]。
+```
+
+不要：
+
+```text
+Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by...
+```
+
+要：
+
+```text
+Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:
+```
+
+## 示例
+
+用户问：为什么 React 组件重新渲染？
+
+回答：
+
+```text
+内联对象属性 -> 新引用 -> 重新渲染。用 `useMemo`。
+```
+
+用户问：解释数据库连接池。
+
+回答：
+
+```text
+连接池 = 复用数据库连接。跳过握手 -> 高负载下更快。
+```
+
+## 自动清晰度例外
+
+遇到以下情况暂时退出 caveman mode：
+
+- 安全警告
+- 不可逆操作的确认
+- 片段顺序可能导致误读的多步骤序列
+- 用户要求澄清或重复提问
+
+清晰部分完成后恢复 caveman mode。
+
+示例：
+
+```md
+**警告：** 这将永久删除 `users` 表中的所有行，且无法撤销。
+
+    DROP TABLE users;
+
+恢复 caveman mode。先确认备份存在。
+```
+
+也可以在实际回复中使用 SQL fence：
+
+````md
+**警告：** 这将永久删除 `users` 表中的所有行，且无法撤销。
+
+```sql
+DROP TABLE users;
+```
+
+恢复 caveman mode。先确认备份存在。
+````

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

@@ -0,0 +1,53 @@
+---
+id: github-npm-ops
+type: skill
+name: GitHub npm Ops
+description: GitHub 仓库运营与 npm 发布原子能力；用于 issue/PR/CI/security 治理、release.yml 配置、npm provenance 发布、tag 发版、三端验证和失败恢复。
+---
+
+# GitHub npm Ops
+
+## 何时使用
+
+当 command 或 workflow 需要处理 GitHub 仓库运营、CI 排障、安全告警、npm 包发布、GitHub Release、release notes 注入、tag 触发发布或发布失败恢复时使用。
+
+## 输入
+
+- GitHub 仓库上下文、目标分支、目标版本号或待处理 issue / PR / run id
+- npm 包信息：`package.json`、包名、版本、发布分支、是否 scoped
+- 发布流水线文件：通常是 `.github/workflows/release.yml`
+- CHANGELOG 类文档路径，默认优先识别 `CHANGELOG.md` 或 `CHANGELOGS.md`
+- 可选：调用方 workflow 提供的 `.speculo/dev/docs-sync-state.json` 与 docs-sync 报告
+
+## 输出
+
+- 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/` 或 `.status.json`。
+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 处理时读取。

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

@@ -0,0 +1,178 @@
+# 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/speculo/skills/github-npm-ops/references/failure-recovery.md

@@ -0,0 +1,132 @@
+# 失败回滚与恢复剧本
+
+> 命令正文给出 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 或 CHANGELOGS.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. 抽取 CHANGELOG 段落作为 Release notes
+awk -v v="X.Y.Z" '
+  $0 ~ "^## \\["v"\\]" { found=1; print; next }
+  found && /^## \[/ { exit }
+  found && /^---[[:space:]]*$/ { next }
+  found { print }
+' CHANGELOGS.md > /tmp/notes.md
+
+# 2. 手动创建 GitHub Release
+gh release create vX.Y.Z \
+  --title "Release vX.Y.Z" \
+  --notes-file /tmp/notes.md \
+  --latest
+
+# 3. 三端再次校验
+npm view <pkg> version          # 应 == X.Y.Z
+gh release view vX.Y.Z --json body,isDraft,isPrerelease
+```
+
+**错误码映射**：通常是基础设施层错误（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，由其追加到 `.speculo/.config/LESSONS.md`（本 skill 不直接写 `.speculo/`）。
+
+---
+
+## 场景共性：何时触发 P9（反重复失败原则）
+
+> 反重复失败原则：同根因连续失败时，必须先声明新尝试与上次的差异。
+
+- **同根因连续失败 ≥ 2 次** → 必须先停手，**书面声明**本次重试与上次的差异
+- 未声明差异即重试 → 触发 `E010_repeatedFailurePattern`，`npm-cicd-release` 命令应主动暂停，等待用户输入差异声明
+
+例：场景 C 中 NPM_TOKEN 失效连续两次 fail，第二次失败后必须先确认 token 已真正更新（粘贴新 token 的尾 4 位摘要 / GitHub Secrets 更新时间），再继续。
+
+---
+
+## 与 github-ops skill 的关系
+
+本文件是发布编排视角下的失败恢复入口；更细粒度的失败案例（如 EUSAGE / E422 / provenance 错误码、package.json 字段错误）见 `troubleshooting-playbook.md`。
+
+| 失败位置 | 看本文件 | 看 github-ops troubleshooting-playbook |
+|---------|---------|---------------------------------------|
+| Phase 1–6 编排逻辑层面 | ✅ | ❌ |
+| release.yml 内部步骤的具体错误码 | ❌ | ✅ |
+| npm 错误码（E403 / E404 / E422 / EUSAGE） | ❌ | ✅ |