@prismer/runtime 2.0.8 → 2.2.55

package/apc/skills/release-rollback/SKILL.md

@@ -0,0 +1,214 @@
+---
+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 行的替身）：
+
+```bash
+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`）
+
+```bash
+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`）—— 真写账本
+
+```bash
+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
+
+```bash
+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`）。
+
+**路径是钉死的**（判据要回读它）：
+
+```bash
+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` 指向 `to.tag`。
+
+**不许**：无上一好版本时硬返绿；把 staged 计划当已回滚；手改 ledger/ref 绕审批。
+
+## Checklist
+
+- [ ] dry-run 拿到 plan（from→to）+ staged，再带 `--approved` 执行
+- [ ] green 后读回 ledger 确认 current→pulled、上一好版本→current
+- [ ] 跑了单条账本负控，确认 blocked + plan.ok:false（回滚 skill 的命根子）
+- [ ] 给了 `--mirror` 时用 `git ls-remote` 核验 release-current 重指
+
+## 审批门（doc03 §1）
+
+本 skill 收口 doc03 §1 审批点 **「回滚」**（release-rollback 执行前）。dry-run 出计划，**真回滚前必须建人审批并停手**：
+
+1. **出示 dry-run 证据**（审批人看到的）：回滚目标版本（`plan.from.version → plan.to.version`）+ 影响面（`plan.next[]`，01 §2）。无上一好版本 → `blocked`（`plan.ok:false`），无审批可建。
+2. **建真 cloud 审批**（真路径 = `human-approval` built-in skill 的 CLI）——把上面证据装进请求：
+
+   ```bash
+   cloud approval request-human --task-id "$PRISMER_TASK_ID" \
+     --action "回滚 <plan.from.version> → <plan.to.version>（test）" \
+     --context "部署后回归红；回滚计划 from→to + 影响面见 dry-run 回执" \
+     --risk "OTA 账本翻 pulled/current + manifest 指针回退；回滚后建 bug task 回 bugfix 入口"
+   ```
+
+   返回 `approvalId`；**建完即停手本轮**（human-approval 铁律：平台在人裁决后重派）。
+3. **block**：未 approve 前 `staged`（exit 3），账本不改；无上一好版本 → `blocked`（负控注入点，绝不空转返绿）。
+4. **post-approval = M5 real-remote**：真 OTA `action:'rollback'`/`pulled` + 真 manifest 指针回退 + 服务端校验 `approvalId`，属 **M5 real-remote**，本机替身（本地 JSON ledger + bare mirror）不触真远端、不冒充已回滚。
+
+## PKF 直写（研发回环 · doc07 §B2 写入点①）
+
+**产出时机**：回滚收口（green/staged/blocked）后，把这次回滚的结论**直写成一张 PKF 记忆页**（pageType=`decision`，ReleaseCard 语义 apc/09 §1）——同一页既是回审批人侧的富报告，也是可召回的事故/发版记录。回滚后的事故根因复盘另走 memory skill 的 CONSTRUCT→PLACE→WRITE，两条边并存（doc07 §B1）。这条直写是账本真副作用之外的一次投影。
+
+**语法照 `pkf-writing` skill**——本 skill 不再内嵌语法骨架（frontmatter / typed link / 数据块写法都在那边）。写入面**不新造**：code agent 走 `prismer memory write`（SS-14 §4.3 appendix；hermes 侧是 native `memory_write`）。
+
+**声明**（doc10 §2.5 格式，报告末尾一行）：
+
+```
+PKF: prismer://workspace/<ws>/memory/<path>
+```
+
+写入面不可达时如实声明 `PKF: none — 写入面不可达（<哪一条>）`，**绝不允许**为了满足规则而假装写了。
+
+**回读**：声明后必须回读该页（`pkf_read` / memory read），确认**真实存在、正文非空**且与结论一致（回滚天然带 `contradicts`——指向被 `pulled` 版本当初的发版决策页；无上一好版本（blocked）时如实写 `plan.ok=false` 与 reason，**绝不**在页里粉饰成"已回滚"）；typed link 的 `prismer://` 目标必须**真实存在**（validator 规则 2c/4 挡 `invalid-prismer-host`），无对应页就删该 link 行、宁缺勿造伪目标；写入自动挂 INDEX 反孤儿锚（SS-14 §4.2），优先 edit 既有页而非 dump 新叶（PLACE 治理照走）。
+
+<!-- APC-ACK:v1 -->
+
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+
+执行本 skill 的**第一步**，先落一条调用回执：
+
+```bash
+cloud skill ack release-rollback --task "$PRISMER_TASK_ID"
+```
+
+**按退出码分流**（这条命令的退出码是承重信息，禁止用 `||` 兜底、`; true`、
+`set +e` 或重定向把它抹掉）：
+
+| exit | 含义 | 你要做的 |
+| --- | --- | --- |
+| `0` | 回执已落库（`im_task_logs.action='skill_ack'`） | 继续执行本 skill |
+| `3` | **无 task 上下文**——本次运行没有 task，产不出回执 | 继续执行本 skill；但本次运行**没有回执**，任何报告里都不得声称已 ack |
+| `4` | 你不是该 task 的 assignee，服务端拒绝 | 停下并上报：回执只能由执行该 task 的 agent 产生 |
+| `1` | 其它失败（网络 / 服务端） | 重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」 |
+
+回执只证明本 skill **被调度**，不证明**执行正确**——效果证明由本 skill 自己的
+acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。
+
+<!-- /APC-ACK:v1 -->

package/apc/skills/release-rollback/skill.json

@@ -0,0 +1,230 @@
+{
+  "schemaVersion": 1,
+  "slug": "release-rollback",
+  "name": "Release Rollback",
+  "description": "Roll a release back for real: 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)/staged(3)/blocked(1).",
+  "category": "release",
+  "version": "1.0.0",
+  "license": "MIT",
+  "compatibility": ["claude-code"],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": ["cloud"],
+      "capabilities": []
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Dry-run a rollback plan, apply it after approval, read the ledger back, and prove the no-good-version block",
+      "prompt": "Roll a release back using the local substitute ledger, prove the approval gate, and prove the negative control. The `apc` CLI is NOT on PATH — invoke it as `npx tsx sdk/apc/bin/apc.ts <subcommand>` from the repo root (its --json stdout is pure JSON). Use the PINNED paths below — the ledger is read back off disk by the criteria, so a different path scores red. Steps: (1) SEED — write `.e2e-tmp/apc-release-rollback/ledger.json` with three entries where 2.0.5/2.0.6 are status superseded and 2.0.7 is status current (each entry has version, tag, status, ts). (2) DRY-RUN — run `npx tsx sdk/apc/bin/apc.ts release rollback --ledger <abs>/.e2e-tmp/apc-release-rollback/ledger.json --json` WITHOUT --approved; confirm decision=staged (exit 3), applied=false and read plan.from.version → plan.to.version (2.0.7 → 2.0.6). (3) APPLY — rerun WITH `--approved local-token`; confirm decision=green (exit 0) and applied=true, then READ THE LEDGER BACK off disk (`cat`) and confirm 2.0.7 is now pulled and 2.0.6 is now current — the ledger file, not the chat message, is the oracle. (4) NEGATIVE CONTROL — write a SEPARATE single-entry ledger at `.e2e-tmp/apc-release-rollback/ledger-single.json` with only 2.0.7 status current, run rollback against it, and confirm decision=blocked (exit 1) with plan.ok=false and a reason like 'no previous good version' — this proves rollback goes red when there is nothing to roll back to. Do NOT run the apply against the single-entry ledger, and do NOT re-run the apply after step 3 (it would flip the ledger a second time and the read-back would no longer match the product you pasted).\n\n--- YOUR REPORT MUST USE THIS MACHINE-CHECKED OUTPUT CONTRACT. All three products are re-parsed, the exit code is re-derived from `decision`, and `plan.next` is compared FIELD BY FIELD against the ledger file that is actually on disk. Narrating an applied rollback that the file does not hold FAILS:\n\n```\nRUN-AT: <ISO-8601 wall time of the APPLY run, e.g. 2026-07-25T23:32:11.000Z>\nPLAN-FROM: 2.0.7\nPLAN-TO: 2.0.6\nSTAGED-APPLIED: false\nSTAGED-EXIT: 3\nAPPLIED: true\nROLLED-TO: 2.0.6\nAPPLY-EXIT: 0\nNEG-DECISION: blocked\nNEG-PLAN-OK: false\nNEG-EXIT: 1\n```\n\nfollowed by the THREE raw `--json` products, each verbatim in its own fenced json block (dry-run, apply, negative control).\n\nHARD RULES: paste each product UNEDITED. `STAGED-EXIT`/`APPLY-EXIT`/`NEG-EXIT` are a pure function of `decision` (green→0, staged→3, blocked→1). The apply product's `plan.next` must DEEP-EQUAL `.e2e-tmp/apc-release-rollback/ledger.json` as it sits on disk right now, and `RUN-AT` must sit next to that file's mtime — an `applied:true` whose ledger never flipped, or a stale ledger from an earlier run, is red.",
+      "expectedArtifacts": [
+        "three raw `apc release rollback --json` products (dry-run / apply / negative control) pasted verbatim",
+        "`PLAN-FROM`/`PLAN-TO`/`APPLIED`/`ROLLED-TO` equal to the products' fields, and every `*-EXIT` derived from its decision",
+        "ledger read-back: `plan.next` deep-equals `.e2e-tmp/apc-release-rollback/ledger.json` on disk (current→pulled, last-good→current)",
+        "`RUN-AT` contemporaneous with that ledger file's mtime — the write really happened at that moment",
+        "negative control: single-entry ledger → decision=blocked + plan.ok=false + a real reason + applied=false"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "the approval gate is real: unapproved is staged(3) with applied=false and a well-formed plan (from→to) — an unapproved rollback may not touch the ledger",
+          "type": "structured",
+          "checker": "json-claim",
+          "args": {
+            "equals": {
+              "decision": "staged",
+              "verb": "rollback",
+              "applied": false,
+              "approved": false,
+              "plan.ok": true
+            },
+            "require": ["plan.from.version", "plan.to.version", "plan.next", "ledgerPath"],
+            "types": {
+              "plan.next": "array"
+            },
+            "declaredLines": {
+              "PLAN-FROM": "plan.from.version",
+              "PLAN-TO": "plan.to.version",
+              "STAGED-APPLIED": "applied"
+            },
+            "derivedLines": {
+              "STAGED-EXIT": {
+                "from": "decision",
+                "map": {
+                  "green": "0",
+                  "staged": "3",
+                  "blocked": "1"
+                }
+              }
+            },
+            "implications": [
+              {
+                "if": {
+                  "path": "approved",
+                  "equals": false
+                },
+                "then": {
+                  "path": "applied",
+                  "equals": false
+                }
+              },
+              {
+                "if": {
+                  "path": "decision",
+                  "equals": "staged"
+                },
+                "then": {
+                  "path": "blockers",
+                  "empty": true
+                }
+              }
+            ]
+          },
+          "match": "<structured:json-claim:staged>",
+          "required": true
+        },
+        {
+          "label": "the apply really landed: the approved product says applied=true AND its plan.next deep-equals the release ledger as it sits on disk (2.0.7→pulled, 2.0.6→current), with the file written at the moment the run claims",
+          "type": "structured",
+          "checker": "json-claim",
+          "args": {
+            "equals": {
+              "decision": "green",
+              "verb": "rollback",
+              "applied": true,
+              "approved": true,
+              "plan.ok": true
+            },
+            "require": ["plan.next", "plan.to.version", "ledgerPath"],
+            "types": {
+              "plan.next": "array"
+            },
+            "declaredLines": {
+              "APPLIED": "applied",
+              "ROLLED-TO": "plan.to.version"
+            },
+            "derivedLines": {
+              "APPLY-EXIT": {
+                "from": "decision",
+                "map": {
+                  "green": "0",
+                  "staged": "3",
+                  "blocked": "1"
+                }
+              }
+            },
+            "implications": [
+              {
+                "if": {
+                  "path": "decision",
+                  "equals": "green"
+                },
+                "then": {
+                  "path": "blockers",
+                  "empty": true
+                }
+              }
+            ],
+            "fileEquals": {
+              "plan.next": {
+                "file": ".e2e-tmp/apc-release-rollback/ledger.json",
+                "json": true
+              }
+            },
+            "freshArtifacts": {
+              "timestampLine": "RUN-AT",
+              "paths": [".e2e-tmp/apc-release-rollback/ledger.json"],
+              "skewMinutes": 20
+            }
+          },
+          "match": "<structured:json-claim:applied>",
+          "required": true
+        },
+        {
+          "label": "the negative control really fired: a ledger with no previous good version yields plan.ok=false + blocked + applied=false + a stated reason — rollback goes red instead of spinning green",
+          "type": "structured",
+          "checker": "json-claim",
+          "args": {
+            "equals": {
+              "plan.ok": false,
+              "verb": "rollback",
+              "decision": "blocked",
+              "applied": false
+            },
+            "require": ["plan.reason", "blockers", "ledgerPath"],
+            "types": {
+              "plan.reason": "string",
+              "blockers": "array"
+            },
+            "declaredLines": {
+              "NEG-DECISION": "decision",
+              "NEG-PLAN-OK": "plan.ok"
+            },
+            "derivedLines": {
+              "NEG-EXIT": {
+                "from": "decision",
+                "map": {
+                  "green": "0",
+                  "staged": "3",
+                  "blocked": "1"
+                }
+              }
+            },
+            "implications": [
+              {
+                "if": {
+                  "path": "plan.ok",
+                  "equals": false
+                },
+                "then": {
+                  "path": "applied",
+                  "equals": false
+                }
+              },
+              {
+                "if": {
+                  "path": "plan.ok",
+                  "equals": false
+                },
+                "then": {
+                  "path": "blockers",
+                  "nonEmpty": true
+                }
+              },
+              {
+                "if": {
+                  "path": "plan.ok",
+                  "equals": false
+                },
+                "then": {
+                  "path": "mirrorRepointed",
+                  "equals": false
+                }
+              }
+            ]
+          },
+          "match": "<structured:json-claim:negative-control>",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": ["local-filesystem", "git-remote"],
+    "humanApprovalRequiredFor": [
+      "applying a rollback (approval gate; local substitute is --approved token, real approvalId = M5)"
+    ]
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/apc/01-release-control-plane.md",
+      "docs/apc/05-devchain-gaps-and-skills.md",
+      "sdk/apc/cli/release-rollback.ts",
+      "sdk/apc/cli/release-common.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-07-24T00:00:00Z"
+  }
+}

package/apc/skills/release-tag/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: release-tag
+description: Cut a release tag behind a real tier gate and cloud approval readback. The approval, task, approved commit, and resulting tag are bound; self-approval and HEAD drift fail closed. Prod prefixes remain refused.
+license: MIT
+scope: coding
+compatibility:
+  - claude-code
+allowed-tools:
+  - Bash
+metadata:
+  category: release
+---
+
+# release-tag
+
+发版打 tag（`apc/01` §2 release-tag，收口步 6）。它把**测试→上线的焊点**焊死：**没有 tier 全绿 / baseline 无新红的结构化证据，审批请求根本不创建、tag 绝不 push**。tier 门跑真 `run.ts` 读真退出码；tag 名按 `<channel>-<target>-YYYYMMDD-vX.Y.Z` 算；审批通过后 `git tag && push` 到**本地 bare mirror 替身**（真 GitLab push + pipeline 轮询 = M5）。
+
+**什么时候用**：`release-preflight` 绿 + `release-db-config-sync` 无阻塞之后，要把一个 test 版本推上 CI。
+
+## 承重纪律（发版 skill 的命根子，先记死）
+
+- **prod 前缀 tag 必拒**（不变量 2 · 两人闸）。四个映射 `APP_ENV=prod` 的前缀——`k8s-prod-*` / `desktop-prod-*` / `prod-*` / `ali-k8s-prod-*`——**先于一切 git / tier 动作硬拒**，本 verb 不做任何 git 动作。**别试 prod**：真 prod 红线由 GitLab protected tags（P-1，运维配置）落地，本 skill 只护到"不替你打 prod tag"。要发 prod = 人走 M5 路径。
+- **`--tier` 必须显式传，没有默认值**。`TD`（桌面冒烟）在 `apps/desktop/e2e/smoke/` 无 spec 时会自动 `skipped-with-note`（`passed:0/failed:0`），单独拿它当发版门是一道**不可能红**的空门——之前 SKILL 范例全不带 `--tier` 让 agent 照抄默认值正是这么踩的坑（`apc/12` §0.12）。**选一个会真执行断言的层**，例如 `--tier=T0,T1`；prod 前缀路径（下方触发）例外——它先于 tier 门拒绝，不需要 `--tier`。
+- **tier 绿是 push 的硬前置，"绿"必须是真跑过用例**。tier 红 / `env_blocked` / **空跑**（该轮所有 tier 的 `passed+failed` 合计为 0，即一个用例都没真执行）⇒ `blocked`，审批请求不创建、tag 不 push。**不许**放松 tier、挑能绿的层、或拿一个恰好全 skip 的层骗过门。
+- **审批门不可跳**。tier 绿但未审批 = `staged`（dry-run：出 tag + tier 证据，不 push）。批准路径必须同时传 `--task <taskId> --approved <approvalId>`；CLI 从 cloud 读回批件和 task，校验 `approved` / `release_tag` / task 绑定 / 非自批，且两者 metadata 的 commit SHA 必须一致。随机 token 不再能放行。
+- **tag 打获批 commit，不打 HEAD**。并行工作使 HEAD 漂移也不得把未审内容带入 tag；获批 SHA 不在 repo 则 fail-closed。
+
+## Anti-pattern（直接判红）
+
+- ❌ **给 `--target prod` 或手拼 prod 前缀 tag** 想让 skill 打 prod。命中即 blocked，别绕。
+- ❌ **tier `blocked` 时先打 tag 再补测试**。焊点就是不让这发生。
+- ❌ **拿到 `staged` 就以为发版完成**。staged 是"等审批"，tag 还没 push。
+- ❌ **用 `git tag` + 裸 `git push origin`** 手工绕过本 verb，跳过 tier 门和审批门。
+
+## 工具契约（签名以此为准）
+
+> `apc` **不在 PATH**——在仓库根用 `npx tsx sdk/apc/bin/apc.ts <sub>`。
+
+| 命令 | 作用 | 退出码 |
+| --- | --- | --- |
+| `npx tsx sdk/apc/bin/apc.ts release tag [--channel k8s\|desktop] [--target test\|prod] [--version X.Y.Z] --tier=<tiers> [--task <taskId> --approved <approvalId>] [--json]` | prod 人闸 → tier 门 → cloud 批件/task/commit 他证 → 把获批 SHA push 到本地 bare mirror | `0` green（pushed）· `3` staged（tier 绿待审批）· `1` blocked（tier 红 / 他证失败 / prod 拒 / push 失败）· `2` 用法错 |
+
+`--tier` **没有默认值**（`--target prod` 路径除外——它先于 tier 门拒绝）；不传直接 usage 错 exit 2。选一个会真执行断言的层，例如 `--tier=T0,T1`——**别用 `--tier=TD`** 当唯一层：无桌面冒烟 spec 时它是空门。
+
+`--json` 字段（**名以此为准**）：
+
+- 顶层：`{ verb:'tag', decision, tag, target, channel, tier, approved, approvalId, taskId, commitSha, pushed, mirror, blockers:[], notes:[] }`
+- `tag`：算出的 tag 名（如 `k8s-test-20260724-v2.0.7`）；`--version` 缺省读 `/VERSION`
+- `tier`：`{ tier, exitCode, envBlocked, regressions, emptyRun }`（prod 拒时 `exitCode:-1`，因为压根没跑到 tier；`emptyRun:true` = 该轮所有 tier 的 `passed+failed` 合计为 0，一个用例都没真跑，即便 `exitCode` 是 0 也判 `blocked`）
+- `mirror`：push 目标（默认 `.dev-stack/apc-bare-origin.git` bare 替身）
+
+## Workflow
+
+### 1. dry-run：算 tag + 过 tier 门（不带 `--approved`）
+
+```bash
+npx tsx sdk/apc/bin/apc.ts release tag --channel k8s --target test --tier=T0,T1 --json > /tmp/tag-dry.json; T=$?
+echo "tag(dry) exit=$T"
+```
+
+- `decision:staged`（exit 3）+ tier 绿 → 拿到 `tag` 名，进审批。
+- `decision:blocked`（exit 1）→ 读 `tier`/`blockers`；tier 红 / 空跑（`tier.emptyRun:true`）就停手回 bugfix，别往下走。
+- 忘了 `--tier` → exit 2 用法错，不是"用了默认 TD"——没有默认值。
+
+### 2. 审批后 push（cloud 批件 + task 绑定）
+
+```bash
+# approval 必须是 cloud 中已被另一个人批准的 release_tag 记录，并且与 task 携带同一 commit SHA
+npx tsx sdk/apc/bin/apc.ts release tag --channel k8s --target test --tier=T0,T1 \
+  --task "$PRISMER_TASK_ID" --approved "$APPROVAL_ID" --json > /tmp/tag.json; T=$?
+echo "tag(push) exit=$T"
+```
+
+- `decision:green`（exit 0）+ `approved:true` + `pushed:true` → tag 已落 bare mirror；必须用 `git rev-parse refs/tags/<tag>^{commit}` 核验结果等于产物的 `commitSha`。
+
+### 3. prod 一律拒（验证人闸，不是要发 prod）
+
+```bash
+npx tsx sdk/apc/bin/apc.ts release tag --channel k8s --target prod --json; echo "prod exit=$?"
+# 预期：decision=blocked, exit 1, blockers 含 "prod 人闸"，无任何 git 动作
+# 注意：这条命令没带 --tier ——prod 人闸先于 tier 门开火，压根不需要它
+```
+
+## Failure / 边界
+
+- push 失败（bare mirror 不存在 / git 错误）→ `blocked` + `blockers` 含真 git stderr。bare 替身由 `apc env up --safe` 拉起。
+- 本机替身：push 只到 **本地 bare mirror**，**不推 GitLab**；cloud approval/task/commit 他证已是真路径。真 GitLab push + pipeline 轮询仍是 M5（诚实 ⬜）。
+
+## 输出契约（机器判据按这个复算，别自由发挥格式）
+
+本 skill 的判据**不是**「报告里出现了 `staged` / `prod` 这些字」，而是：**重解析你贴的三份 `--json` 产物**、**从 `decision` 反推退出码**、**用只读 git plumbing 回读 bare mirror 的 ref 库**、**用 tier 门自己写的副产物给这次运行定时**（`structured-criteria.ts` 的 `json-claim` + `git-claim-readback`）。
+
+先在**隔离沙箱**里搭演示（**绝不在共享工作树打 tag/push**）：
+
+```bash
+mkdir -p .e2e-tmp/apc-release-tag && git init -q --bare .e2e-tmp/apc-release-tag/mirror.git
+mkdir -p .e2e-tmp/apc-release-tag/work && cd .e2e-tmp/apc-release-tag/work
+git init -q -b main && echo demo > f.txt && git add f.txt && git commit -qm init
+git remote add mirror "$REPO/.e2e-tmp/apc-release-tag/mirror.git"
+```
+
+> `--repo` / `--mirror` **必须传绝对路径**——verb 内部会把相对 `--repo` 再解析一次（`git -C <rel>` 又在 `cwd=<rel>` 下跑），相对路径必失败。
+
+报告必须带下面这组行 + **三份原样 JSON**：
+
+```
+RUN-AT: <审批那次运行的 ISO-8601 墙钟时间>
+STAGED-TAG: <dry-run 产物的 tag>
+STAGED-PUSHED: false
+STAGED-EXIT: 3
+TAG-NAME: <审批产物的 tag>
+TIER-EXIT: 0
+TAG-EXIT: 0
+PROD-TAG: <verb 算出并拒掉的 k8s-prod-… tag>
+PROD-DECISION: blocked
+GIT-REPO: .e2e-tmp/apc-release-tag/work
+GIT-TAG: <tag> | remote: mirror | sha: <该 tag 在 mirror 上解析出的 commit sha>
+GIT-REFUSED-TAG: <k8s-prod-… tag> | remote: mirror
+```
+
+紧跟着把三次 `--json` 的 stdout **一字不改**贴进三个 fenced json 块（dry-run → 审批 → prod）。
+
+判据会判红的情况（任一）：
+
+- 没有可解析的 fenced JSON（只有散文「tag 打好了」）；
+- `STAGED-EXIT` / `TAG-EXIT` 不是从 `decision` 推出来的那个（green→0 · staged→3 · blocked→1）——**退出码是 decision 的函数，不是措辞**；
+- 审批产物 `decision:green` 却 `tier.exitCode != 0` / `tier.regressions` 非空 / `blockers` 非空——**tier 绿是 push 的硬前置**；
+- dry-run 产物 `approved:false` 却 `pushed:true`——**审批门被跳**；
+- prod 产物不是 `blocked` + `pushed:false` + `tier.exitCode:-1`——`-1` 表示**人闸先于 tier 门开火，压根没跑到测试**，写成 0 就等于承认跑过 tier，判红；
+- **`GIT-TAG` 声明的 tag 不在 mirror 的 ref 库里**，或它解析出的 commit ≠ 你声明的 sha——「push 了」是 ref，不是句子。**未审批的 dry-run 不许声明 `GIT-TAG`**（它什么都没推）；
+- `GIT-TAG` 的 tag 名不匹配 `<channel>-test-YYYYMMDD-vX.Y.Z`，或它本身命中 prod 前缀；
+- **`GIT-REFUSED-TAG` 竟然在 mirror 上**——那不是拒绝，是推上去了；
+- `GIT-REPO` 不在 `.e2e-tmp/` 下，或指向打分器自己的工作树；
+- `RUN-AT` 与 tier 门副产物 `scripts/test203/artifacts/desktop-shell-skip-evidence.txt` 的 mtime **差超过 20 分钟**——tier 门没真跑，磁盘上就没有这一刻的痕迹。
+
+**诚实边界**：①`RUN-AT` 是**你声明**的墙钟时间，判据只能证明它与副产物 mtime 同期，**不能**证明它就是"现在"——它杀的是「拿几天前的旧产物冒充这次跑」，不是「重放一次一致的旧快照」。②tier 副产物路径是**按本 sample task 钉的 TD 层**，换 tier 必须同步换 args。③判据不证明 mirror 上那个 commit 的内容对，只证明 tag 真在、真指向你声明的 sha。
+
+## 产出（副作用 oracle，报告里必须给）
+
+1. **decision + 真退出码**：`green`/`staged`/`blocked` ⇄ `0`/`3`/`1`。
+2. **算出的 tag 名**：`<channel>-<target>-YYYYMMDD-vX.Y.Z` 全字打印。
+3. **tier 门证据**：`tier.exitCode` + regressions（tier 红时列出）——证明"没绿不 push"。
+4. **push 副作用**：green 时 `pushed:true` + mirror 路径（`git ls-remote` 可核验真 tag ref）。
+5. **prod 拒证据**：`--target prod` → `blocked` + exit 1 + "prod 人闸" blocker + **零 git 动作**（不是聊天里说"prod 不能发"）。
+
+**不许**：把 `staged` 当发版完成；试图打 prod tag；绕过 verb 手工 tag/push；tier 红仍 push。
+
+## Checklist
+
+- [ ] 先 dry-run 拿到 tag 名 + tier 绿证据，再带 `--approved` push
+- [ ] green 时确认 `pushed:true` + 记录 mirror；用 `git ls-remote` 复核 tag ref
+- [ ] 演示 prod 前缀被拒（blocked/exit 1/零 git 动作），没试图绕
+- [ ] tier 红 / env_blocked 时停手，没有放松 tier 或先 tag 后测
+
+## PKF 直写（研发回环 · doc07 §B2 写入点①）
+
+**产出时机**：tag 收口（green/staged/blocked）后，把这次打 tag 的结论**直写成一张 PKF 记忆页**（pageType=`decision`，ReleaseCard 语义 apc/09 §1）——同一页既是回审批人侧的富报告，也是可召回的发版记录。经验教训另走 memory skill 的 CONSTRUCT→PLACE→WRITE，两条边并存（doc07 §B1）。这条直写是投影，不改 prod 人闸 / tier 门 / 审批门任何一步。
+
+**语法照 `pkf-writing` skill**——本 skill 不再内嵌语法骨架（frontmatter / typed link / 数据块写法都在那边）。写入面**不新造**：code agent 走 `prismer memory write`（SS-14 §4.3 appendix；hermes 侧是 native `memory_write`）。
+
+**声明**（doc10 §2.5 格式，报告末尾一行）：
+
+```
+PKF: prismer://workspace/<ws>/memory/<path>
+```
+
+写入面不可达时如实声明 `PKF: none — 写入面不可达（<哪一条>）`，**绝不允许**为了满足规则而假装写了。
+
+**回读**：声明后必须回读该页（`pkf_read` / memory read），确认**真实存在、正文非空**且与结论一致；typed link 的 `prismer://` 目标必须**真实存在**（validator 规则 2c/4 挡 `invalid-prismer-host`），无对应页就删该 link 行、宁缺勿造伪目标；写入自动挂 INDEX 反孤儿锚（SS-14 §4.2），优先 edit 既有页而非 dump 新叶（PLACE 治理照走）。
+
+<!-- APC-ACK:v1 -->
+
+## 调用回执（APC 平台方运营纪律 · 自动注入，勿手改）
+
+执行本 skill 的**第一步**，先落一条调用回执：
+
+```bash
+cloud skill ack release-tag --task "$PRISMER_TASK_ID"
+```
+
+**按退出码分流**（这条命令的退出码是承重信息，禁止用 `||` 兜底、`; true`、
+`set +e` 或重定向把它抹掉）：
+
+| exit | 含义 | 你要做的 |
+| --- | --- | --- |
+| `0` | 回执已落库（`im_task_logs.action='skill_ack'`） | 继续执行本 skill |
+| `3` | **无 task 上下文**——本次运行没有 task，产不出回执 | 继续执行本 skill；但本次运行**没有回执**，任何报告里都不得声称已 ack |
+| `4` | 你不是该 task 的 assignee，服务端拒绝 | 停下并上报：回执只能由执行该 task 的 agent 产生 |
+| `1` | 其它失败（网络 / 服务端） | 重试一次；仍失败则继续执行，并在结果里显式标注「回执缺失」 |
+
+回执只证明本 skill **被调度**，不证明**执行正确**——效果证明由本 skill 自己的
+acceptanceCriteria 副作用断言承担（apc/04 §2 层 1 诚实标注）。
+
+<!-- /APC-ACK:v1 -->