@prismer/runtime 2.0.7 → 2.2.55

package/apc/skills/release-db-config-sync/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: release-db-config-sync
+description: Compute the remote DB migration + Nacos config diff before a test release — apc release db-config-sync really spawns sync-test-migrations.ts --dry-run (never a stub) and diffs Nacos key dumps, stopping at the write boundary. green(0) no diff · staged(3) pending migrations/missing keys await approval · blocked(1) real script failed. Diff only, never writes the remote.
+license: MIT
+scope: coding
+compatibility:
+  - claude-code
+allowed-tools:
+  - Bash
+metadata:
+  category: release
+---
+
+# release-db-config-sync
+
+发版前算清**远端 DB 迁移**与 **Nacos 配置**的差异（`apc/01` §2 db-config-sync，收口步 3/4）。这是治 **R3**（"DB sync 走桩、`writes:0` 换马甲冒充已同步"）的真机制：它**真 spawn** `scripts/ops/sync-test-migrations.ts --dry-run`——真解析凭证、真连库、真算迁移计划——退出码由真脚本决定，**绝不注入桩**。Nacos 侧对两份 key dump 算真差集。**dry-run 永不写库、不写真 Nacos**——止于写入边界，真 apply 走审批后的远端路径。
+
+**什么时候用**：`release-preflight` 绿之后、`release-tag` 之前，确认远端 test 环境的迁移账本和配置 key 都对齐了才发版。
+
+## 承重纪律（先记死）
+
+- **事故红线（memory / `apc/01` 开头）**：prod 曾因 Navicat 结构 diff 绕过迁移账本灌库出事故（丢回填 / 半应用）。**一切 DB sync 必须走账本，diff 工具只做审计不做写入。** 本 skill 就是账本路径的收口——**绝不教你拿 Navicat / 裸 SQL 去改远端**。
+- **本 skill 只 dry-run**：算差异、出计划、停在写入边界。真 apply（把 pending 迁移打进 test RDS、把缺失 key 补进 Nacos）是**审批后**的远端动作（本机替身口径下 = M5），不由本 skill 执行。
+- **别把桩当验过**：本机替身下 Nacos fetch 未接线时，key-diff 会**诚实标 `skipped`**（真路径 = M5）。看到 `skipped` 就照实报 ⬜，别写成"配置已核对无差异"。
+
+## Anti-pattern（直接判红）
+
+- ❌ **迁移 dry-run 报 `blocked`（真脚本失败 / 缺凭证）时，改用别的路径灌库**绕过去。真脚本 exit 非 0 = 连不上 / 缺 `REMOTE_MYSQL_*`，是要修的前置，不是要绕的门。
+- ❌ **有 pending 迁移（`staged`）就当没事发版**。`staged`（exit 3）意味着远端账本落后，未审批 apply 前不该 tag。
+- ❌ **key-diff `skipped` 说成"已核对"**。没给 dump 文件就是没比，别冒充。
+
+## 工具契约（签名以此为准）
+
+> `apc` **不在 PATH**——在仓库根用 `npx tsx sdk/apc/bin/apc.ts <sub>`。
+
+| 命令 | 作用 | 退出码 |
+| --- | --- | --- |
+| `npx tsx sdk/apc/bin/apc.ts release db-config-sync [--ref <dump>] [--cur <dump>] [--json]` | 真跑 `sync-test-migrations.ts --dry-run`（本机替身指向本地 replica，永不写远端）+ 对两份 Nacos dump 算 key 差集 | `0` green（无差异）· `3` staged（有 pending / 缺 key）· `1` blocked（真脚本失败 / 缺凭证） |
+
+`--json` 字段（**名以此为准**）：
+
+- 顶层：`{ verb:'db-config-sync', decision, migration, keyDiff, blockers:[], staged:[] }`
+- `migration`：`{ exitCode, pending:[<sql文件名>], stderr }`（`exitCode` 是真脚本退出码；`pending` 是真脚本 fs 枚举 ⇄ `_migrations` 账本比对得出的待同步迁移）
+- `keyDiff`：`{ status:'skipped', reason }` **或** `{ status:'computed', missing:[], extra:[], common }`（`missing` = 目标环境缺的 key，需补齐；`extra` 不阻塞，仅报告）
+
+## Workflow
+
+### 1. 跑迁移 dry-run + key-diff
+
+```bash
+# 只算迁移（不给 dump 时 key-diff 诚实 skipped）：
+npx tsx sdk/apc/bin/apc.ts release db-config-sync --json > /tmp/dbsync.json; D=$?
+echo "db-config-sync exit=$D"
+```
+
+要一并算 Nacos key-diff，先用 `dump-nacos-namespace.ts` 产出两份 dump（基准 / 目标现状），再传 `--ref`/`--cur`：
+
+```bash
+npx tsx sdk/apc/bin/apc.ts release db-config-sync --ref /tmp/nacos-ref.env --cur /tmp/nacos-cur.env --json
+```
+
+### 2. 按 decision 分流
+
+| decision | exit | 含义 | 你要做的 |
+| --- | --- | --- | --- |
+| `green` | `0` | 无 pending 迁移 + key 无缺失 | 放行 |
+| `staged` | `3` | 有 pending 迁移 / 目标环境缺 key | 列出 `migration.pending` + `keyDiff.missing`；**审批后**走远端 apply（`sync-test-migrations.ts` 去 `--dry-run` / Nacos 补 key），不得抢跑 |
+| `blocked` | `1` | 真脚本 exit 非 0（连库失败 / 缺 `REMOTE_MYSQL_*`） | 读 `migration.stderr`，修凭证/连通性——这是前置，别绕开账本自己灌库 |
+
+## Failure / 边界
+
+- 缺 `REMOTE_MYSQL_*` → 真脚本 `throw` → 本 verb `blocked`。这是**真行为非桩**（正是"调真脚本"的证据），如实报，修凭证后重跑。
+- 本机 MySQL 挂（colima 损坏）时对不可达 replica 跑，真脚本会 fs 枚举全量 pending——**真脚本真行为**，但"真实差异（部分已 applied）"需活 replica，属 M5 边界。
+- key-diff 未给 dump → `skipped`（真 Nacos fetch = M5）。**诚实标 ⬜，不冒充已验。**
+
+## 输出契约（机器判据按这个复算，别自由发挥格式）
+
+本 skill 的判据**不是**「报告里出现了 `pending` / `nacos` 这些字」，而是：**重解析你贴的两份 `--json` 产物**、**从 `decision` 反推退出码**、并把 `migration.pending[]` 里的**每一个文件名逐个 stat 回 `src/im/sql/`**（`structured-criteria.ts` 的 `json-claim`）。
+
+本 sample task 钉的是**两次真跑**：一次接通本地 replica（站位远端 test RDS），一次**抽掉 `REMOTE_MYSQL_*` 的负控**——负控是这条用例自带的、必须变红的注入点。
+
+```bash
+# 1) 连通跑（本地 replica 站位远端 test RDS）
+REMOTE_MYSQL_HOST=127.0.0.1 REMOTE_MYSQL_PORT=3307 REMOTE_MYSQL_USER=… REMOTE_MYSQL_PASSWORD=… \
+REMOTE_MYSQL_DATABASE=prismer_cloud npx tsx sdk/apc/bin/apc.ts release db-config-sync --json
+# 2) 负控：不带 REMOTE_MYSQL_*，真脚本 throw
+npx tsx sdk/apc/bin/apc.ts release db-config-sync --json
+```
+
+报告必须带这组行 + **两份原样 JSON**：
+
+```
+MIGRATION-EXIT: 0
+KEYDIFF: <keyDiff.status —— skipped | computed>
+RUN-EXIT: <decision green→0 | staged→3 | blocked→1>
+NEG-MIGRATION-EXIT: 1
+NEG-DECISION: blocked
+NEG-RUN-EXIT: 1
+```
+
+判据会判红的情况（任一）：
+
+- 没有可解析的 fenced JSON；
+- `MIGRATION-EXIT` / `KEYDIFF` 与产物字段不一致——**把 skipped 的 key-diff 说成"已核对"正是这条抓的**；
+- `RUN-EXIT` 不是从 `decision` 推出来的那个；
+- **`migration.pending[]` 里任何一个文件名在 `src/im/sql/` 下不存在**——这份清单是真脚本枚举 `src/im/sql/*.sql` ⇄ 目标库 `_migrations` 账本算出来的，没真跑就得**编**两百多个文件名，编一个就红；
+- **把 `pending[]` 截断成「…还有 200 条」**——判据读的是数组，截断即缺项；
+- 负控产物不是 `migration.exitCode != 0` + `decision:blocked` + `blockers` 非空 + `pending` **空**——一个能扛过自己凭证故障的迁移计划是编的；
+- `decision:green` 却 `pending` 非空 / `decision:staged` 却 `staged[]` 空。
+
+**诚实边界**：①判据**证明不了** `pending[]` 的语义正确（哪些真该 apply），只证明每个名字是磁盘上真存在的迁移文件 + 计数自洽。②「未写远端 DB / 真 Nacos」这一条**没有结构化事实可断**（dry-run 的本质就是没有副作用），因此仍保留为**关键词判据**——它是本 skill 唯一还靠措辞的判据，写清楚这点比假装它有牙重要。③接不通 replica 时本 sample task 无法演示，此时判据红是**如实结论**（不是 SUT 红，是本机环境没给到前置）。
+
+## 产出（副作用 oracle，报告里必须给）
+
+1. **decision + 真退出码**：`green`/`staged`/`blocked` ⇄ `0`/`3`/`1`（读回核对）。
+2. **迁移计划**：`migration.exitCode` + `pending[]`（列真 sql 文件名，非"若干条"）。
+3. **key-diff**：`computed` 时给 `missing`/`extra` 计数；`skipped` 时**原样报 skipped + reason**。
+4. **是否停在 dry-run 边界**：明确本 skill **没有**写远端库 / 没有写真 Nacos。
+
+**不许**：把桩 / `skipped` 当已验；有 pending 迁移还发版；绕过账本用裸 SQL / Navicat 灌远端。
+
+## Checklist
+
+- [ ] 跑了 `apc release db-config-sync --json`，记录 `decision` + 真退出码
+- [ ] 列出了 `migration.pending` 的真文件名（有则 staged，审批后才 apply）
+- [ ] key-diff 是 computed 就给 missing/extra 计数，是 skipped 就照实标 ⬜
+- [ ] 明确本步只 dry-run，没写远端；blocked 时报了真 stderr 而非绕过
+
+## 审批门（doc03 §1）
+
+本 skill 收口 doc03 §1 审批点 **「远端 DB/配置写」**（触发：db-config-sync 应用前）。dry-run 停在写入边界，**真 apply 前必须建人审批并停手**：
+
+1. **出示 dry-run 证据**（审批人看到的，非 agent 自述）：迁移 dry-run 计划（`migration.pending[]` 真 sql 文件名）+ Nacos key-diff 报告（`keyDiff.missing/extra`；`skipped` 就照实标 ⬜）。
+2. **建真 cloud 审批**（真路径 = `human-approval` built-in skill 的 CLI）——把上面证据装进请求：
+
+   ```bash
+   cloud approval request-human --task-id "$PRISMER_TASK_ID" \
+     --action "apply 远端迁移 + 补 Nacos key（test）" \
+     --context "pending 迁移: <migration.pending>；key-diff missing: <keyDiff.missing>（dry-run 计划见回执）" \
+     --risk "写 test RDS 账本 + Nacos；红线：绕账本灌库曾致 prod 半应用事故（apc/01 开头）"
+   ```
+
+   返回 `approvalId`；**建完即停手本轮**（human-approval 铁律：平台在人裁决后重派，别同轮往下执行）。
+3. **block**：未 approve 前 `staged`（exit 3），dry-run 边界不写远端。
+4. **post-approval = M5 real-remote**：真 apply（`sync-test-migrations.ts` 去 `--dry-run` 打进 test RDS / Nacos 补 key）+ 服务端校验 `approvalId` 已 approved，属 **M5 real-remote**，本机替身不执行、不冒充已 apply。
+
+## PKF 直写（研发回环 · doc07 §B2 写入点①）
+
+**产出时机**：db-config-sync 出 decision 后，把这次远端迁移/配置差异的结论**直写成一张 PKF 记忆页**（pageType=`decision`，ReleaseCard 语义 apc/09 §1）——同一页既是回审批人侧的富报告，也是可召回的发版记录。Navicat 绕账本这类事故教训另走 memory skill 的 CONSTRUCT→PLACE→WRITE，两条边并存（doc07 §B1）。这条直写是 dry-run 边界之外的一次投影，不写远端。
+
+**语法照 `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），确认**真实存在、正文非空**且与结论一致（key-diff `skipped` 就在页里照实标 ⬜、别写成"已核对无差异"）；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-db-config-sync --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-db-config-sync/skill.json

@@ -0,0 +1,109 @@
+{
+  "schemaVersion": 1,
+  "slug": "release-db-config-sync",
+  "name": "Release DB Config Sync",
+  "description": "Compute the remote DB migration + Nacos config diff before a test release: apc release db-config-sync really spawns sync-test-migrations.ts --dry-run (never a stub) and diffs Nacos key dumps, stopping at the write boundary. green(0)/staged(3)/blocked(1). Diff only, never writes the remote.",
+  "category": "release",
+  "version": "1.0.0",
+  "license": "MIT",
+  "compatibility": ["claude-code"],
+  "runtime": {
+    "kind": "text-workflow",
+    "requires": {
+      "env": [],
+      "bins": ["cloud"],
+      "capabilities": []
+    }
+  },
+  "sampleTasks": [
+    {
+      "title": "Dry-run the remote migration plan and Nacos key diff, plus the missing-credential negative control",
+      "prompt": "Compute the remote DB + config diff for a test release WITHOUT writing anything remote, and prove the credential 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). Steps: (1) CONNECTED RUN — point the local replica credentials at the stand-in test RDS (`REMOTE_MYSQL_HOST=127.0.0.1 REMOTE_MYSQL_PORT=3307 REMOTE_MYSQL_USER=… REMOTE_MYSQL_PASSWORD=… REMOTE_MYSQL_DATABASE=prismer_cloud`) and run `npx tsx sdk/apc/bin/apc.ts release db-config-sync --json`, capturing stdout and the REAL exit code. The verb really spawns `scripts/ops/sync-test-migrations.ts --dry-run` — `migration.exitCode` is that script's own exit code and `migration.pending[]` is the real `src/im/sql/*.sql` ⇄ `_migrations` ledger difference, so every filename in it is a real file under `src/im/sql/`. Read `decision` (green|staged|blocked) and `keyDiff` (either {status:'skipped',reason} or {status:'computed',missing,extra,common}). (2) NEGATIVE CONTROL — rerun the SAME command with the `REMOTE_MYSQL_*` vars UNSET; the real script throws, `migration.exitCode` is 1, `migration.pending[]` is empty and the decision is blocked. This is the injected fault that must turn the verb red — do NOT route around the migration ledger to make it green. (3) Report both runs, the decision→exit mapping (green→0, staged→3, blocked→1), the pending .sql filenames (apply happens only AFTER approval, = M5), and the keyDiff status honestly — if it is 'skipped' say skipped, never claim config was checked when no dump was diffed. State explicitly that this step is dry-run only and wrote nothing to the remote DB or real Nacos.\n\n--- YOUR REPORT MUST USE THIS MACHINE-CHECKED OUTPUT CONTRACT. Both products are re-parsed, the exit code is re-derived from `decision`, and EVERY filename in `migration.pending[]` is stat'ed under `src/im/sql/`. Narrating an outcome the product does not carry FAILS:\n\n```\nMIGRATION-EXIT: 0\nKEYDIFF: <keyDiff.status — skipped | computed>\nRUN-EXIT: <0 if decision green | 3 if staged | 1 if blocked>\nNEG-MIGRATION-EXIT: 1\nNEG-DECISION: blocked\nNEG-RUN-EXIT: 1\n```\n\nfollowed by BOTH raw `--json` products, each verbatim in its own fenced json block (connected run first, then the credential-fault run).\n\nHARD RULES: paste both products UNEDITED — do NOT truncate `migration.pending[]` to \"…and 200 more\"; the whole list is re-read off disk and an invented or abbreviated filename is red. `RUN-EXIT` is a pure function of `decision`. A blocked run must carry a non-empty `blockers[]` and an EMPTY `migration.pending[]` — a plan that survives its own credential fault is a fabricated plan.",
+      "expectedArtifacts": [
+        "both raw `apc release db-config-sync --json` products (connected + credential-fault) pasted verbatim and untruncated",
+        "`MIGRATION-EXIT` / `KEYDIFF` / `RUN-EXIT` equal to the connected product's fields",
+        "`migration.pending[]` = real `src/im/sql/*.sql` filenames (every one re-stat'ed on disk)",
+        "`NEG-*` lines: the credential fault really turns the verb blocked with an empty plan",
+        "explicit statement that nothing was written to the remote DB / real Nacos (dry-run boundary)"
+      ],
+      "acceptanceCriteria": [
+        {
+          "label": "the connected run's plan is real: the sync script exited 0, every filename in migration.pending[] is a real file under src/im/sql/, the prose exit code is derived from the decision, and the keyDiff status is reported as the product actually has it",
+          "type": "structured",
+          "checker": "json-claim",
+          "args": {
+            "equals": { "migration.exitCode": 0, "verb": "db-config-sync" },
+            "require": ["decision", "migration.pending", "keyDiff.status", "blockers", "staged"],
+            "types": { "migration.pending": "array", "blockers": "array", "staged": "array" },
+            "allowed": {
+              "decision": ["green", "staged", "blocked"],
+              "keyDiff.status": ["skipped", "computed"]
+            },
+            "declaredLines": { "MIGRATION-EXIT": "migration.exitCode", "KEYDIFF": "keyDiff.status" },
+            "derivedLines": {
+              "RUN-EXIT": { "from": "decision", "map": { "green": "0", "staged": "3", "blocked": "1" } }
+            },
+            "implications": [
+              {
+                "if": { "path": "decision", "equals": "green" },
+                "then": { "path": "migration.pending", "empty": true }
+              },
+              { "if": { "path": "decision", "equals": "staged" }, "then": { "path": "staged", "nonEmpty": true } }
+            ],
+            "filesExist": { "path": "migration.pending", "dir": "src/im/sql", "min": 1 }
+          },
+          "match": "<structured:json-claim:connected>",
+          "required": true
+        },
+        {
+          "label": "the negative control really fired: with the credentials removed the REAL sync script exits non-zero, the decision is blocked with a non-empty blocker, and the migration plan is EMPTY — a plan that survives its own credential fault would be fabricated",
+          "type": "structured",
+          "checker": "json-claim",
+          "args": {
+            "equals": { "migration.exitCode": 1, "verb": "db-config-sync", "decision": "blocked" },
+            "require": ["migration.stderr", "blockers"],
+            "types": { "migration.stderr": "string", "blockers": "array" },
+            "declaredLines": { "NEG-MIGRATION-EXIT": "migration.exitCode", "NEG-DECISION": "decision" },
+            "derivedLines": {
+              "NEG-RUN-EXIT": { "from": "decision", "map": { "green": "0", "staged": "3", "blocked": "1" } }
+            },
+            "implications": [
+              {
+                "if": { "path": "decision", "equals": "blocked" },
+                "then": { "path": "migration.pending", "empty": true }
+              },
+              { "if": { "path": "decision", "equals": "blocked" }, "then": { "path": "blockers", "nonEmpty": true } }
+            ]
+          },
+          "match": "<structured:json-claim:credential-fault>",
+          "required": true
+        },
+        {
+          "label": "affirms the dry-run boundary — nothing written to remote DB / real Nacos",
+          "match": "(dry[- ]?run|not\\s+writ|never\\s+writ|no\\s+writ|wrote\\s+nothing|write\\s+boundary|未写|不写)[\\s\\S]{0,80}(remote|nacos|db|库|远端|apply)|(remote|nacos|远端)[\\s\\S]{0,40}(not\\s+writ|dry[- ]?run|unchanged)",
+          "type": "regex",
+          "flags": "i",
+          "required": true
+        }
+      ]
+    }
+  ],
+  "security": {
+    "dataAccess": ["local-filesystem", "remote-database-readonly", "nacos-config-readonly"],
+    "humanApprovalRequiredFor": [
+      "applying pending migrations to the remote test RDS (dry-run only here; apply is post-approval)",
+      "writing missing keys to real Nacos (never done by this skill)"
+    ]
+  },
+  "provenance": {
+    "sourceKind": "inline-spec",
+    "sourceRefs": [
+      "docs/apc/01-release-control-plane.md",
+      "docs/apc/05-devchain-gaps-and-skills.md",
+      "sdk/apc/cli/release-db-config-sync.ts",
+      "scripts/ops/sync-test-migrations.ts"
+    ],
+    "authoredBy": "prismer-platform",
+    "authoredAt": "2026-07-24T00:00:00Z"
+  }
+}

package/apc/skills/release-ota-promote/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: release-ota-promote
+description: Publish signed Electron UI/daemon bundles to a local OTA feed with atomic manifest switch and digest readback, while dry-running the K8s drain_respawn rollout. Prod is refused before writes; feed publication is not client apply.
+license: MIT
+scope: coding
+compatibility:
+  - claude-code
+allowed-tools:
+  - Bash
+metadata:
+  category: release
+---
+
+# release-ota-promote
+
+把一份 runtime OTA 沿**双通道**下发（`apc/01` §2 ota-promote，收口步 7/8/11）。这是**线 3 admin fleet 下发**，交付模式治 **doc01 #8**（"promote 用了线 1 kill1 而非线 3 drain_respawn"）：
+
+- **K8s daemon 通道**：交付 **drain_respawn**（排空在飞 task → 优雅 `exit(0)` → supervisor respawn → boot-OTA 换版，用户**无感/无中断**）。正规落点 = admin fleet rollout endpoint `POST /api/admin/runtime-releases/rollout`（`src/im/api/admin.ts`）→ 给每个目标 daemon 下发 `runtime.update.apply` 帧 → daemon **arm drain_respawn**。本 verb **不再 spawn 线 1 `kill 1` 的 `runtime-ota.ts`**（那会打断在飞 task），而是**构造这条 drain_respawn rollout 请求**。本机替身**只 dry-run 出请求、不真 POST**（真 POST 需 approvalId + release row + 在线 daemon = M5）。
+- **桌面 feed 通道**：本机替身**未接线**——诚实标 ⬜（铁律 4）。缺①桌面本地 feed 基座（`apc/05` §3，P0-4 未落）②本机禁写真 Nacos manifest（= M5）。
+
+**什么时候用**：一个新 runtime 版本发布后，要让 fleet 里的 daemon 采用它。
+
+## 承重纪律（发版 skill 的命根子，先记死）
+
+- **prod OTA 必拒**（不变量 2）。`--env prod` **先于任何 OTA 动作硬拒**，不做任何下发。**别试 prod**：真 prod promote = M5。
+- **交付模式 = `drain_respawn`，绝非 `kill1`**。线 3 fleet 下发必须排空在飞后再 respawn（`kill 1` 会打断用户在飞 task，那是线 1，仅 dev/紧急）。`k8s.directive` 必须是 `drain_respawn`。
+- **不宣称 `drain_respawn` 已执行**。本机替身**只 dry-run 出 rollout 请求（`k8s.posted:false`），不真 POST**（= M5：approvalId + release row + 在线 daemon）。照实报"已构造 drain_respawn 请求，未真下发"，**绝不说"已 drain_respawn 下发"**。
+- **桌面 feed 走真文件副作用**。传 `--desktop-feed-dir` 与 UI/daemon builder metadata；verb 先校验 size + SHA-512，复制版本化 bundle，最后原子切 `manifest.json`，再从磁盘回读摘要。只有 `desktop.status:'applied'` + `readback.verified:true` 才能宣称 feed 已发布。
+- **feed 已发布 ≠ Electron 已应用**。客户端 `check → stage → apply` 需要另取运行态证据，不得从文件写入外推。
+
+## Anti-pattern（直接判红）
+
+- ❌ **`--env prod`** 想 promote prod。命中即 blocked，别绕。
+- ❌ **把交付模式报成 `kill1` / 线 1 `kubectl exec kill 1`**。本 verb 是线 3，交付 `drain_respawn`；报 kill1 = 把在飞打断当成了正规下发。
+- ❌ **把 `k8s.posted:false` 的 dry-run 说成"已 drain_respawn 下发/已 POST"**，或把本地 feed 已发布说成"Electron 已更新"。
+
+## 工具契约（签名以此为准）
+
+> `apc` **不在 PATH**——在仓库根用 `npx tsx sdk/apc/bin/apc.ts <sub>`。
+
+| 命令 | 作用 | 退出码 |
+| --- | --- | --- |
+| `npx tsx sdk/apc/bin/apc.ts release ota-promote [--env dev\|test\|prod] [--json]` | K8s 通道构造 drain_respawn rollout 请求（落点 admin fleet rollout endpoint，本机替身 dry-run 不 POST）+ 桌面通道 ⬜；prod 硬拒 | `0` green（真 rollout 完成，仅 M5）· `1` blocked（本机 dry-run 边界 / 桌面未接线 / prod 拒） |
+
+`--json` 字段（**名以此为准**）：
+
+- 顶层：`{ verb:'ota-promote', decision, env, deliveryMode, k8s, desktop, blockers:[], notes:[] }`
+- `k8s`：`{ channel:'admin-fleet-rollout', endpoint, directive:'drain_respawn', frame:'runtime.update.apply', request:{channel,version,target}, posted:false, boundary }`（`directive` = 交付模式，**必须 drain_respawn**；`posted:false` = 本机替身未真 POST）
+- `desktop`：成功时 `{ status:'applied', deliveryMode:'local-file-feed', plan:{manifestPath,...}, readback:{verified:true,...}, boundary }`；校验/写入/回读失败时 `{status:'blocked', blockers:[...]}`。
+- `deliveryMode`：`'drain_respawn（线 3 admin fleet rollout · 本机替身 dry-run）'`——**不是** kill1
+
+## Workflow
+
+### 1. K8s 通道（构造 drain_respawn rollout 请求）
+
+```bash
+npx tsx sdk/apc/bin/apc.ts release ota-promote --env dev --json > /tmp/ota.json; O=$?
+echo "ota-promote exit=$O"
+```
+
+- 读 `k8s.directive`——必须是 `drain_respawn`（线 3，排空在飞后 respawn），**不是** `kill1`。
+- 读 `k8s.posted`——`false` = 本机替身**只 dry-run 出请求、未真 POST**（真 POST = M5）。
+- 本机替身 → `decision:blocked`（exit 1）+ blocker 说明"真 admin rollout POST = M5"。**如实报**，这是本机替身边界（release-common.ts 本机替身边界），不冒充已下发。
+
+### 2. 桌面通道（诚实 ⬜）
+
+使用隔离目录与现有已签名 builder metadata 发布并回读：
+
+```bash
+npx tsx sdk/apc/bin/apc.ts release ota-promote --env dev \
+  --desktop-feed-dir .e2e-tmp/apc-ota-feed \
+  --desktop-ui-meta apps/desktop/dist-ui/ui.manifest.json \
+  --desktop-daemon-meta apps/desktop/dist-ui/daemon.manifest.json --json
+```
+
+核验 `desktop.status=applied` 、`desktop.readback.verified=true`，并独立检查 `desktop.plan.manifestPath` 及版本化 bundle 存在。
+
+### 3. prod 一律拒（验证人闸）
+
+```bash
+npx tsx sdk/apc/bin/apc.ts release ota-promote --env prod --json; echo "prod exit=$?"
+# 预期：decision=blocked, exit 1, k8s.skipped=true, blockers 含 "prod 人闸"
+```
+
+## Failure / 边界
+
+- 本机替身 → K8s 通道 dry-run 出 drain_respawn 请求但不真 POST → `blocked`。这是**预期的真行为**（本机替身边界），不是 skill 的红。
+- 桌面通道 = ⬜（feed 基座未落 + 本机禁写真 Nacos）。
+- 真 drain_respawn fleet 下发（真 POST admin rollout endpoint + approvalId + release row + 在线 daemon）= M5；本 verb 只把交付模式**纠正为 drain_respawn** 并 dry-run 出请求。
+
+## 输出契约（机器判据按这个复算，别自由发挥格式）
+
+本 skill 的判据**不是**「报告里出现了 `drain_respawn` 这个词」——旧判据正是一条 `match:"drain[\s_-]?respawn"`，一份宣称 `posted:true`、`decision:green`、"fleet 已换版"的**纯编造**报告在它下面满分。新判据**重解析你贴的两份 `--json` 产物**，把 `k8s.channel/directive/frame/posted` 逐字段钉死、从 `decision` 反推退出码、并把 rollout body 的 `version` 与磁盘上真 `/VERSION` 比对（`json-claim`）。
+
+报告必须带这组行 + **两份原样 JSON**（`--env dev` 在前，`--env prod` 在后）：
+
+```
+DIRECTIVE: drain_respawn
+POSTED: false
+DESKTOP: applied
+DESKTOP-VERIFIED: true
+RUN-EXIT: 1
+PROD-DECISION: blocked
+PROD-K8S-SKIPPED: true
+PROD-RUN-EXIT: 1
+```
+
+判据会判红的情况（任一）：
+
+- 没有可解析的 fenced JSON；
+- `k8s.directive` 不是 `drain_respawn`（写成 **`kill1`** 直接红——线 1 会打断在飞 task，把它当交付模式正是本 verb 存在的理由）、或 `k8s.channel != admin-fleet-rollout`、`k8s.frame != runtime.update.apply`；
+- **`k8s.posted != false`**，或 `posted:false` 却 `decision:green`——**什么都没 POST，就不许把任何东西报成已下发**；
+- `desktop.status != applied` 或 `desktop.readback.verified != true`，或把 feed 发布冒充为 Electron 客户端已 apply；
+- `DIRECTIVE` / `POSTED` / `DESKTOP` 与产物字段不一致，或 `RUN-EXIT` 不是 `decision` 推出来的；
+- rollout body 的 `k8s.request.version` **不等于磁盘上 `/VERSION`**；
+- prod 产物不是 `blocked` + **`k8s.skipped:true`**（连 rollout 请求都没构造）+ `blockers` 非空。
+
+**诚实边界**：桌面通道有真文件副作用与摘要回读；K8s 通道仍只构造请求、不 POST。因此顶层仍应 `blocked`，直到真 admin rollout 产生送达证据。
+
+## 产出（副作用 oracle，报告里必须给）
+
+1. **decision + 真退出码**：`green`/`blocked` ⇄ `0`/`1`。
+2. **交付模式证据**：`k8s.directive:'drain_respawn'`（线 3，非 kill1）+ `k8s.frame:'runtime.update.apply'` + `k8s.channel:'admin-fleet-rollout'`。
+3. **本机替身边界**：`k8s.posted:false`（未真 POST）+ blocker 说明真 POST = M5。
+4. **桌面 feed 真回读**：`desktop.status:'applied'` + `readback.verified:true` + manifest/bundle 路径。
+5. **prod 拒证据**：`--env prod` → blocked + exit 1 + "prod 人闸" + K8s 通道 skipped。
+
+**不许**：把交付报成 kill1；把 dry-run（`posted:false`）说成已 drain_respawn 下发；把 feed 发布说成 Electron 已 apply；试 prod。
+
+## Checklist
+
+- [ ] 跑了 `apc release ota-promote --env dev --json`，`k8s.directive` = `drain_respawn`（非 kill1）
+- [ ] `k8s.posted:false` 时如实报"已构造 drain_respawn 请求、未真 POST（= M5）"，没冒充已下发
+- [ ] 桌面 feed 照实报 applied + readback.verified + manifestPath，没冒充 Electron 已 apply
+- [ ] delivery 明确是 drain_respawn（线 3 admin fleet rollout），没报成 kill1
+- [ ] 演示 `--env prod` 被拒（blocked/exit 1），没试 prod
+
+## 审批门（doc03 §1）
+
+本 skill 收口 doc03 §1 **两个**审批点：**「OTA promote/下发」**（ota-promote ga/rollout 前）与 **「桌面通道发布」**（桌面 bundle/manifest 指针更新前，收口步 11）。dry-run 停在下发边界，**真下发前必须建人审批并停手**：
+
+1. **出示双通道证据**（审批人看到的）：K8s = dry-run request + target/version；桌面 = 已原子发布的 manifest + bundle 签名/摘要回读。
+2. **建真 cloud 审批**（真路径 = `human-approval` built-in skill 的 CLI）——把上面证据装进请求：
+
+   ```bash
+   cloud approval request-human --task-id "$PRISMER_TASK_ID" \
+     --action "OTA rollout runtime <version>（drain_respawn，test fleet）" \
+     --context "target daemon: <k8s.request.target>；版本分布见 dry-run 回执；桌面通道 manifest 指针 diff / 签名摘要（未接线 ⬜）" \
+     --risk "线 3 fleet 下发；drain_respawn 排空在飞后 respawn（非 kill1 打断在飞 task）"
+   ```
+
+   返回 `approvalId`；**建完即停手本轮**（human-approval 铁律：平台在人裁决后重派）。
+3. **block**：桌面 feed 可已验证，但 `k8s.posted:false` 仍使顶层 `blocked`（exit 1）。
+4. **post-approval = M5 real-remote**：真 POST `/api/admin/runtime-releases/rollout`（消费 `approvalId` + release row + 在线 daemon）属 **M5 real-remote**，本机替身不执行、不冒充已下发。
+
+## PKF 直写（研发回环 · doc07 §B2 写入点①）
+
+**产出时机**：ota-promote 出 decision 后，把这次 OTA 下发的结论**直写成一张 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），确认**真实存在、正文非空**且与结论一致（`k8s.posted=false` 就照实标未下发，桌面仅标 feed 发布与回读，**绝不**写成"已 drain_respawn 下发"或"Electron 已 apply"）；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-ota-promote --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 -->