# Escape Hatch Spec — `SKIP_CONSUMER_ACK=1`

> v1.7.8 落地版（含协议方 PARTIAL ACCEPT 决策）。
> 设备端原始建议见 `claude-docs/discussions/device-team-suggestion-escape-hatch-telemetry-v1.7.8.md`。
> 设备端 final ack（接受拆分）见 `claude-docs/discussions/device-team-final-ack-v1.7.8.md`。

---

## 0. 设计目标

`SKIP_CONSUMER_ACK=1` 是**异常事件**，应当极少使用。把"使用 escape hatch"信号化、可追踪化、可审查化，防止悄悄绕过成常规。

具体目标:
1. **输出高显著性** — escape 触发时操作员清楚知道正在跳过流程
2. **持久化记录** — 每次 escape 使用都写入审计日志（仓库内）
3. **CHANGELOG 自首** — release notes 自动反映 escape 历史
4. **趋势监控** — release maintainer 定期 review（见 `release-ops.md`）

---

## 1. PARTIAL ACCEPT 决策表（v1.7.8 落地范围）

| 设备端建议项 | 决策 | v1.7.8 实施 | 后续版本 |
|------------|------|------------|---------|
| 文档存在性检查（PASS path） | ✅ ACCEPT | 已落 | — |
| ALT_PATTERN（语义后缀 ack 文件支持） | ✅ ACCEPT | 已落 | — |
| `write_audit_entry()` jsonl 审计 | ✅ ACCEPT | 已落 | — |
| 远程 telemetry POST | 🟡 DEFER | — | v1.7.9 评估 |
| Escape hatch 触发分支 | ✅ ACCEPT | 已落 | — |
| 文本 warning banner | ✅ ACCEPT | 已落（纯文本，CI-friendly）| — |
| 颜色 ANSI escape codes | 🟡 DEFER | — | v1.7.9 |
| 3 秒倒计时（非 CI 环境） | 🟡 DEFER | — | v1.7.9 |
| 失败分支（FAILED_NO_ACK） | ✅ ACCEPT | 已落 | — |
| GHA release annotation | 🟡 DEFER | — | v1.8.0 评估 |
| 月度 review SOP | ✅ ACCEPT | 已落 `release-ops.md` | — |

---

## 2. 当前实施版本（v1.7.8 最小版）

实施文件 `scripts/check-consumer-ack.sh`，三分支:

### 2.1 PASS

```
ack doc 存在（标准 / final-ack / 语义后缀任一）
  → 输出 "✅ check:consumer-ack  found ack doc for v<X.Y.Z>"
  → write_audit_entry "PASS"
  → exit 0
```

### 2.2 ESCAPE_HATCH_USED

```
SKIP_CONSUMER_ACK=1 显式设置
  → write_audit_entry "ESCAPE_HATCH_USED"
  → 输出文本 warning banner（CI-friendly，无颜色无倒计时）
  → exit 0
```

Banner 内容包括：
- ⚠️ ESCAPE HATCH USED 标识
- 版本号
- 期望 ack 文件路径列表（让操作员知道下次应该补什么）
- 必需后续动作 3 条（CHANGELOG / audit / reason）
- Principle 5 + 月度 review 引用

### 2.3 FAILED_NO_ACK

```
ack doc 不存在 + 未设 escape hatch
  → 输出阻塞原因 + ack 文件期望路径 + escape hatch 用法
  → write_audit_entry "FAILED_NO_ACK"
  → exit 1（阻塞 publish）
```

---

## 3. Audit JSONL Format

`scripts/escape-hatch-audit.jsonl` 每行一条 JSON:

```json
{"timestamp":"<ISO 8601 UTC>","version":"<X.Y.Z>","action":"<ACTION>","user":"<git email>","ci":"<true|false>"}
```

**`action` 枚举**:
- `PASS` — ack 文档存在，正常 publish
- `ESCAPE_HATCH_USED` — 操作员显式 SKIP_CONSUMER_ACK=1
- `ESCAPE_HATCH_USED_RETROACTIVE` — 回溯标注历史违规（v1.7.7 cycle baseline）
- `FAILED_NO_ACK` — hook 阻塞 publish

**可选字段**:
- `note` — 描述（如 RETROACTIVE 条目引用 reply 文档）

---

## 4. CHANGELOG 自首 Template

每次 `ESCAPE_HATCH_USED` 必须在 CHANGELOG 中显式自首:

```markdown
## [X.Y.Z] - YYYY-MM-DD

### ⚠️ Process: SKIP_CONSUMER_ACK used

本版 publish 时跳过了 consumer ack 检查（escape hatch）。

**理由**: <填写具体理由>
**审计**: 见 `scripts/escape-hatch-audit.jsonl`（本次 release timestamp 条目）
**事后补救**: <填写补救动作>

### <其它正常 CHANGELOG sections>
```

---

## 5. 月度 Review

详见 `docs/release-ops.md`。

健康阈值速查：
- 月 0 次 = 正常 ✅
- 月 1 次 = OK ✅
- 月 2 次 = WARNING ⚠️ 触发 retro
- 月 ≥3 次 = BLOCK 🚫
- 累计 ≥5 次未 retro = hard stop 🚫

---

## 6. v1.7.9 + v1.8.0 + v2.x 后续路径

| 增强项 | 计划版本 | 备注 |
|--------|---------|------|
| 颜色 ANSI 高亮 banner | v1.7.9 | 仅非 CI 环境 |
| 3 秒倒计时（Ctrl+C 反悔机会） | v1.7.9 | 仅非 CI 环境 |
| 远程 telemetry POST (`PROTOCOL_TELEMETRY_URL` env) | v1.7.9 评估 | 需协议方 telemetry endpoint |
| GHA release page annotation（"⚠️ This release used escape hatch"） | v1.8.0 评估 | 需先有 release workflow（release-please / 类似）|
| `check-wire-emit-cross.sh` (catalog cross-check hook) | v1.8.0 | 配合方案 i mirror 同步 |
| `wire-emit-codes.json` 机器可读版 | v2.0.0 | 设备端 source-of-truth tool 实现 |

---

## 7. 参考

- 协议方 reply (v1.7.8 基础版规划): `claude-docs/discussions/protocol-team-reply-to-broadcast-gap-v1.7.8.md` §5.1
- 设备端建议原文: `claude-docs/discussions/device-team-suggestion-escape-hatch-telemetry-v1.7.8.md`
- 协议方 ack (PARTIAL ACCEPT 决策): `claude-docs/discussions/protocol-team-ack-of-escape-hatch-suggestion-v1.7.8.md`
- 设备端 final ack (接受拆分): `claude-docs/discussions/device-team-final-ack-v1.7.8.md`
- 月度 review SOP: `docs/release-ops.md`
- Contributing 守则: `CONTRIBUTING.md`