fix(slark-cicd): document handoff recovery

Refs REQ-20260825-0006

skills-dev/slark-cicd-plugin/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slark-cicd
-description: Slark 仓库 staging、生产和 Desktop 安装包的端到端 CI/CD 可执行 runbook。覆盖本地预推快检、PR 与内网 ci/internal-gate 门禁、合并 origin/main、staging 真机预验、审批式生产发布，以及在 m5max 构建签名、公证并上传 macOS/Windows Desktop 包到 OSS。当用户要在 slark（qiudl/qiu-slark）里发布/上线、部署到生产或 staging、发布 Desktop 安装包、盯 CI/合并 PR、复现或验证运行时行为、或排查发布链/推送路由问题时使用。
+description: Slark 仓库 staging、生产和 Desktop 安装包的端到端 CI/CD 可执行 runbook。覆盖本地预推快检、PR 与内网 ci/internal-gate 门禁、合并 origin/main、生产前强制 staging 验收、审批式生产发布，以及在 m5max 构建签名、公证并上传 macOS/Windows Desktop 包到 OSS。当用户要在 slark（qiudl/qiu-slark）里发布/上线、部署到生产或 staging、发布 Desktop 安装包、盯 CI/合并 PR、复现或验证运行时行为、或排查发布链/推送路由问题时使用。
 ---
 
 # Slark CI/CD runbook
@@ -17,6 +17,9 @@ description: Slark 仓库 staging、生产和 Desktop 安装包的端到端 CI/C
 - 生产发布只接受**最新 `origin/main` 的精确 40 位 SHA**；`HEAD != origin/main` 会被 `deploy.sh` 拒绝。
 - 生产发布必须在**普通 clone** 中执行，且 `.git` 必须是目录；`release-prod.sh` / `deploy.sh` 会拒绝
   `.git` 为指针文件的 git worktree。不要污染现有 checkout：主目录脏或被占用时，新建干净的临时 clone。
+- **生产发布前必须先发布并验收 staging，不得跳过**：同一最新 `origin/main` 精确 SHA 必须先完成迁移演练、
+  staging 正式部署、隔离检查和需求功能验收。把证据报告给用户后，必须再次取得明确的生产确认；开始 staging
+  前获得的生产授权不能替代这次确认。未通过、未完成或用户未确认时停止，不得执行生产发布命令。
 - 审批式部署，永不自动：亲手敲的 `sudo`/`rm -rf`/`dd`/`curl|sh`/包安装是 `destructive`（NEVER_AUTO），
   **每次都要人审**；命中审批闸就**等人批**，绝不绕过、绝不把这些 key 加进 auto-approve 白名单。
 - staging 与生产硬隔离：staging 脚本带生产 IP 拒运行护栏、不 push origin、不反向 rsync。
@@ -31,7 +34,7 @@ description: Slark 仓库 staging、生产和 Desktop 安装包的端到端 CI/C
 
 ## 选择链路
 
-- 「发布/上线/部署生产」→ 生产发布链：阶段 1→2→4→5。
+- 「发布/上线/部署生产」→ 生产发布链：阶段 1→2→3（同 SHA staging 验收）→ 人工确认 →4→5。
 - 「Desktop/桌面版打包、发布、上传 OSS」→ 阶段 1→2 后走 `docs/desktop-oss-release.md` 的 m5max 双平台链路。
 - 「盯 CI/合并 PR」→ 阶段 1→2（用 babysit 心态循环到 green + mergeable + 评论收口）。
 - 「复现/验证运行时行为、别碰生产」→ staging 预验链（阶段 3，可独立随时跑）。
@@ -70,7 +73,12 @@ git push origin --delete <feature-branch>            # 删远端
 git branch -D <feature-branch>                       # 删本地（先切走）
 ```
 
-## 阶段 3：staging 真机预验（可选，随时）
+## 阶段 3：staging 真机预验（生产前强制，也可独立运行）
+
+生产候选必须使用最新 `origin/main` 的同一精确 SHA。先执行迁移演练，再正式部署；随后完成隔离检查和本次需求的
+功能验收。验收不能只看通用 health：凡需求涉及真实集成（如飞书 OAuth），staging 缺少对应 provider/凭据时必须
+明确标为未完成并停止生产链，除非用户在看到该限制后明确接受。完成后报告目标实例、SHA、Server/Daemon revision、
+迁移演练、健康、隔离和功能结果，并等待用户再次确认是否进入生产。
 
 ### 3.1 当前权威路径：Slark 独立 staging
 
@@ -125,6 +133,9 @@ routed-remote 要 `network=enabled` 必须同时满足：① agent `workspace_ac
 
 ## 阶段 4：生产发布（审批式）
 
+**前置门禁**：阶段 3 已对同一 SHA 完成 staging 部署和验收，证据已报告，且用户在报告之后明确确认生产发布。
+缺任一项即停止；不得把 PR 合并授权、较早的生产授权或单纯的“继续”视为验收后确认。
+
 **唯一姿势**：从干净的普通 clone 发布最新 `origin/main`（`HEAD == origin/main` 精确 SHA）。staging 可用
 独立 worktree，但生产脚本为保证同步与发布边界，会拒绝 worktree；不要在用户已有脏 checkout 中清理或发布。
 
@@ -147,6 +158,17 @@ pnpm release:prod            # = release-prod.sh → deploy.sh --backend --no-in
 - 命中审批闸（发布/sudo）→ **等人批**；不要绕。脚本内部 SSH 载荷子进程的 sudo 不触发闸。
 - 普通工作 clone 发布完切回原分支：`git checkout <branch>`；一次性发布 clone 可保留作审计，清理时用可恢复方式。
 
+### HANDOFF_BLOCKED 恢复入口
+
+发布准备遇到 `HANDOFF_BLOCKED`、handoff manifest=`failed_closed` 或命令状态不确定时，停止发布切换；禁止靠重跑
+发布脚本、直接改表或默认 replay 来“解卡”。先把 manifest、命令、execution、lease/outbox 和审计证据做只读盘点，
+再让用户明确授权每条记录的 reconciliation action/outcome 及是否允许继续发布。恢复细节见
+[references/production-handoff-recovery.md](references/production-handoff-recovery.md)；仅遇到该类事故时读取。
+
+`COMMAND_AUTHORITY_CHANGED` 是有效并发护栏，不是可忽略错误：重新读取当前 authority/transport/execution generation，
+确认期间没有新活动，再在原授权范围内幂等续办。若发现新工作、活跃 lease/outbox 或无法解释的副作用，立即停止并
+重新请求决策。
+
 ## 阶段 5：发布后核查
 
 ```bash
@@ -154,7 +176,12 @@ scripts/verify-deploy.sh    # 健康(前端/api/health=200)、bundle、server/da
 ```
 
 预期 `✓ deploy verification passed: server=<sha> daemon=<sha>` 且 `<sha> == origin/main`，舰队 `online ≥ 发布前`。
-镜像落后告警（默认 `--no-mirror`）非阻断，需补推按告警的幂等命令（需 Bitwarden session）；镜像仅单向 fast-forward。
+完成前还要独立复核 governed release 账本为 `succeeded/complete`、四组件实际 SHA 均为目标 SHA、租约已释放、
+新 handoff manifest=`verified`；若本次处理过旧 manifest，还要核对其全部 case 已达授权终态且 replay 数为 0。
+
+默认生产包装器使用 `--no-mirror`：构建 daemon candidate binary 用于运行态验证不等于上传镜像资产。镜像落后告警
+在该模式下是预期的非阻断结果；不得未经单独授权补传镜像。交付说明要明确国内安装器可能回退 upstream，避免把
+本地构建、生产 daemon 更新和镜像上传混为一谈。
 
 ## Desktop m5max 双平台发布
 
@@ -194,6 +221,11 @@ scripts/git-release-governance.sh status
 | cohost Server 已更新但 daemon 仍是旧 SHA | 用 `--profile daemon up -d daemon-staging` 更新 daemon；核对两容器 revision 后才算完成 |
 | cohost daemon 启动即退出/fatal | 看 `docker logs slark_daemon_staging`；修复凭据/环境或版本契约，禁止用旧 daemon 冒充验收通过 |
 | verify 失败 SHA 不符 | 部署到了旧码，重发 |
+| `HANDOFF_BLOCKED` / manifest=`failed_closed` | 停止切换并读取 handoff recovery 参考；只读盘点后取得逐项 action/outcome 授权，禁止默认 replay |
+| reconciliation 返回 `COMMAND_AUTHORITY_CHANGED` | 查当前 generation 与新活动；无新活动才在原授权内幂等续办，有变化则停止重新决策 |
+| `--no-mirror` 后提示镜像落后 | 预期非阻断；报告 upstream fallback，未经单独授权不上传镜像 |
+| 生产授权已给但 staging 尚未验收 | 先完成同 SHA staging 全量验收，报告证据并重新等用户确认；不得沿用较早授权 |
+| staging 缺少需求依赖的真实集成配置 | 将对应验收标为未完成并停止生产链；补齐配置后重验，或让用户基于明确限制作决定 |
 
 ## ai-proj 流程（强制）