/release-rollback

name: release-rollback
description: Roll a release back for real when post-deploy regression goes red — apc release rollback flips the current version to pulled and the last good version back to current in the release ledger, and (with --mirror) repoints the bare mirror ref. Behind an approval gate; with no previous good version it BLOCKS instead of spinning green. green(0) applied · staged(3) plan awaiting approval · blocked(1) nothing to roll back to.
license: MIT
scope: coding
compatibility:
  - claude-code
allowed-tools:
  - Bash
metadata:
  category: release

release-rollback

上线后回归红时的**真回滚**（`apc/01` §2 release-rollback，收口步 10）。它落两个真副作用：

1. **release 账本回退**：把当前 `current` 版本翻 `pulled`、上一好版本翻回 `current`（真写 JSON ledger，可读回核验）。 2. **版本指针回退**（给了 `--mirror`）：把 bare mirror 的 `refs/heads/release-current` 重指到上一好 tag 的 commit（真 git 副作用，`git ls-remote` 可核验）。

**什么时候用**：`release-verify`（部署后回归）红了，需要把 fleet 退回上一个好版本。回滚后应建 bug task 回 bugfix 入口。

承重纪律（发版 skill 的命根子，先记死）

• **审批门不可跳**。未审批 = `staged`（出回滚计划 dry-run，不执行）。本机替身以 `--approved <token>` 非空为门（真 approvalId 服务端校验 = M5）。审批人看到的是**回滚计划**（from→to 版本 + 影响面），不是"agent 说要回滚了"。
• **无上一好版本 → `blocked`，绝不空转返绿**。账本只有一条、或更早的都已 `pulled` ⇒ 无从回滚 ⇒ blocked（exit 1）。这是本 verb 的**负控注入点**：一个"回滚"skill 若在没东西可回滚时也返绿，就是开卷考试。
• **prod 不做**。本 skill 是 test 环境的回滚；prod 回滚走人 + M5 路径。

Anti-pattern（直接判红）

• ❌ **无上一好版本时硬造一个"回滚成功"**。planRollback `ok:false` 就是 blocked，别放松。
• ❌ **拿到 `staged`（计划）就以为已回滚**。staged 是"等审批"，账本还没改。
• ❌ **手工改 ledger JSON / `git update-ref`** 绕过 verb 的审批门和 plan 计算。

工具契约（签名以此为准）

> `apc` **不在 PATH**——在仓库根用 `npx tsx sdk/apc/bin/apc.ts <sub>`。

| 命令 | 作用 | 退出码 | | --- | --- | --- | | `npx tsx sdk/apc/bin/apc.ts release rollback [--ledger <path>] [--mirror <bare>] [--approved <token>] [--json]` | 算回滚计划 → 审批门 → 写账本回退（+ 可选 mirror ref 重指） | `0` green（applied）· `3` staged（计划待审批）· `1` blocked（无上一好版本） |

`--json` 字段（**名以此为准**）：

• 顶层：`{ verb:'rollback', decision, ledgerPath, plan, approved, applied, mirrorRepointed, blockers:[], notes:[] }`
• `plan`：`{ ok:true, from:{version,tag,status}, to:{version,tag,status}, next:[...] }` **或** `{ ok:false, reason }`
• ledger 条目形状：`{ version, tag, status:'current'|'pulled'|'superseded', ts }`（`current` 唯一）

Workflow

1. 备好 release 账本（本机替身）

账本记录发过的版本序列，当前版本 `status:'current'`。本机替身用一份 JSON（真 release-status 行的替身）：

cat > /tmp/apc-rollback-ledger.json <<'JSON'
[
  { "version": "2.0.5", "tag": "k8s-test-20260720-v2.0.5", "status": "superseded", "ts": "2026-07-20T00:00:00Z" },
  { "version": "2.0.6", "tag": "k8s-test-20260722-v2.0.6", "status": "superseded", "ts": "2026-07-22T00:00:00Z" },
  { "version": "2.0.7", "tag": "k8s-test-20260724-v2.0.7", "status": "current",    "ts": "2026-07-24T00:00:00Z" }
]
JSON

2. dry-run：出回滚计划（不带 `--approved`）

npx tsx sdk/apc/bin/apc.ts release rollback --ledger /tmp/apc-rollback-ledger.json --json > /tmp/rb-dry.json; R=$?
echo "rollback(dry) exit=$R"
# 预期：decision=staged (exit 3)，plan.ok=true，plan.from=2.0.7 → plan.to=2.0.6

3. 审批后执行（带 `--approved`）—— 真写账本

npx tsx sdk/apc/bin/apc.ts release rollback --ledger /tmp/apc-rollback-ledger.json --approved "$APPROVAL_TOKEN" --json > /tmp/rb.json; R=$?
echo "rollback(apply) exit=$R"
# 预期：decision=green (exit 0)，applied=true；读回 ledger：2.0.7→pulled，2.0.6→current

给了 `--mirror <bare>` 还会把 `refs/heads/release-current` 重指到 `to.tag`（`git ls-remote` 可核）。

4. 负控：无上一好版本 → blocked

echo '[{"version":"2.0.7","tag":"k8s-test-20260724-v2.0.7","status":"current","ts":"2026-07-24T00:00:00Z"}]' > /tmp/rb-single.json
npx tsx sdk/apc/bin/apc.ts release rollback --ledger /tmp/rb-single.json --json; echo "single exit=$?"
# 预期：decision=blocked (exit 1)，plan.ok=false，reason="无上一好版本可回退"

Failure / 边界

• 账本无 `current` / 无上一好版本 → `blocked`（真拒，非空转）。
• 本机替身：账本 = 本地 JSON（站位真 release-status 行）；mirror ref = bare 替身；审批 = `--approved` 非空。真 OTA `action:'rollback'`/`pulled` + 真 manifest 指针回退 + 服务端 approvalId = M5。
• 回滚后建 bug task 回 bugfix 入口——真 task 创建 = M5 / S10 observability（本 skill 只在 `notes` 提示）。

输出契约（机器判据按这个复算，别自由发挥格式）

本 skill 的判据**不是**「报告里出现了 `pulled` / `current` 这些字」，而是：**重解析你贴的三份 `--json` 产物**、**从 `decision` 反推退出码**、并把 apply 产物的 `plan.next` 与**磁盘上那份账本文件逐字段深比**（`json-claim` 的 `fileEquals` + `freshArtifacts`）。

**路径是钉死的**（判据要回读它）：

mkdir -p .e2e-tmp/apc-release-rollback
# 三条账本：2.0.5/2.0.6 superseded、2.0.7 current
$EDITOR .e2e-tmp/apc-release-rollback/ledger.json
# 负控用另一份，单条 current
$EDITOR .e2e-tmp/apc-release-rollback/ledger-single.json

报告必须带这组行 + **三份原样 JSON**（dry-run → apply → 负控）：

RUN-AT: <apply 那次运行的 ISO-8601 墙钟时间>
PLAN-FROM: 2.0.7
PLAN-TO: 2.0.6
STAGED-APPLIED: false
STAGED-EXIT: 3
APPLIED: true
ROLLED-TO: 2.0.6
APPLY-EXIT: 0
NEG-DECISION: blocked
NEG-PLAN-OK: false
NEG-EXIT: 1

判据会判红的情况（任一）：

• 没有可解析的 fenced JSON；
• 任一 `*-EXIT` 不是从对应 `decision` 推出来的（green→0 · staged→3 · blocked→1）；
• dry-run 产物 `approved:false` 却 `applied:true`——**审批门被跳**；
• **apply 产物的 `plan.next` 与 `.e2e-tmp/apc-release-rollback/ledger.json` 磁盘内容不深等**——`applied:true` 而账本没翻，就是宣称了一个没发生的副作用；
• `RUN-AT` 与那份账本文件的 mtime 差超过 20 分钟——**拿上一次 apply 的旧账本冒充这次**；
• 负控产物不是 `plan.ok:false` + `blocked` + `applied:false` + `mirrorRepointed:false` + 有 `plan.reason`——**没有上一好版本时必须红，不许空转返绿**。

> ⚠️ **别重复 apply**：第 3 步之后再跑一次 apply 会把账本二次翻转，你贴的产物就不再等于磁盘上的账本，判据会红——这不是判据的毛病，是「报告描述的那次写入已经被后一次覆盖」的如实结论。负控**必须**用另一份 `ledger-single.json`。

**诚实边界**：判据能证明「账本现在正是产物声称写成的样子、且写入时间与你声明的运行同期」，**不能**证明这次写入是 verb 干的而不是你手工 `cat >` 出来的——没有哪个本地产物是不可伪造的。它杀的是廉价伪造（编计划、叙述已 apply、拿旧账本顶包）。真 release 状态行（服务端账本）落地 = M5。

产出（副作用 oracle，报告里必须给）

1. **decision + 真退出码**：`green`/`staged`/`blocked` ⇄ `0`/`3`/`1`。 2. **回滚计划**：`plan.from.version → plan.to.version`（ok:true 时），或 `plan.reason`（ok:false）。 3. **账本真副作用**（green 时）：读回 ledger 确认 `current`→`pulled`、上一好版本→`current`；不是聊天里说"已回滚"。 4. **负控证据**：单条账本 → `blocked` + `plan.ok:false` + reason，**证明没东西可回滚时它会红**。 5. **mirror 重指**（给了 `--mirror`）：`mirrorRepointed:true` + `git ls-remote` 核验 `release-current`