release-rollback

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