# Contributing to @thejrsoft/subway-protocol

> v1.7.8 落地的协议方 release process 守则。
> 配套设备端 catalog `docs/wire-emit-codes.md` + `docs/release-ops.md` 月度 review SOP + `docs/release-ops/escape-hatch-spec.md` escape hatch 细节。

---

## Release Process — 强制流程（per protocol-version-coevolution skill）

每次 SUFFIX_RULES / EXPLICIT_META / wire schema 变更**必须**走完整 Round 1-N 流程，由 prepublishOnly hook `check:consumer-ack` 强制：

```
Round 1 (设备端): device-team-audit-of-v<X.Y.Z>.md (or device-team-<topic>-audit-v<X.Y.Z>.md)
   ↓
Round 2 (协议方): protocol-team-reply-to-<topic>-v<X.Y.Z>.md
   ↓
Round 3-N (设备端 → 协议方 多轮 ack/reply 直到对齐)
   ↓
Round N+ final (设备端): device-team-final-ack-v<X.Y.Z>.md  OR  device-team-ack-of-protocol-reply-<topic>-v<X.Y.Z>.md
   ↓
Phase 4: implement + commit + npm publish (此时 prepublishOnly check:consumer-ack 验证 ack 文档存在)
   ↓
Phase 5: v<X.Y.Z>-release-notice-for-device.md
   ↓
Phase 6: 三端 npm install + docker rebuild + 测试机部署
   ↓
Round 8: device-team-audit-of-v<X.Y.Z>.md (post-publish audit)
```

## Before Modifying SUFFIX_RULES / EXPLICIT_META — Cross-check 守则

**强制 cross-check**：每次改 `src/code-meta.ts` 的 SUFFIX_RULES / EXPLICIT_META 前：

1. 打开 `docs/wire-emit-codes.md`（设备端 catalog mirror）
2. 查 §10 当前 SUFFIX_RULES 优先级总览
3. 验证：
   - 新增 SUFFIX 长后缀**必须**排在短后缀之前（避免 shadow）
   - 新增 SUFFIX 不漏覆盖设备端任何 terminal pattern (§1-§7)
   - 新增 SUFFIX 不误判 non-terminal pattern (§4-§5 进度 code)
4. 验证：catalog §11 历史教训表里的 wire code 仍能正确派生（避免回归）

**底层逻辑**: v1.7.0/v1.7.5/v1.7.6/v1.7.7 三轮"对称侧补完"漏洞模式根因——协议方仓库不含设备端代码、无法 grep ground truth。本守则 + catalog mirror 是手动 gate；prepublishOnly `check:consumer-ack` hook 是工具卡。

## Escape Hatch — `SKIP_CONSUMER_ACK=1`

仅在以下场景使用：

- **pure process fix**（不涉及 wire schema 变更，如修文档 typo、refactor 测试不动行为）
- **紧急 hotfix**（已经有设备端口头确认但 ack 文档还没写完）

每次使用：

### 1. CHANGELOG.md 自首

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

### ⚠️ Process: SKIP_CONSUMER_ACK used

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

**理由**: <填写具体理由，如 "纯文档修订，无 wire schema 变更" / "紧急 hotfix">
**审计**: 见 `scripts/escape-hatch-audit.jsonl`（本次 release timestamp 条目）
**事后补救**: <如 "本版无 schema 变更，无需 consumer ack" / "已补 consumer 通知，下次走完整流程">

### Fix
...
```

### 2. 审计日志

`scripts/check-consumer-ack.sh` 自动写入 `scripts/escape-hatch-audit.jsonl` 一行：
```json
{"timestamp":"<ISO 8601 UTC>","version":"<X.Y.Z>","action":"ESCAPE_HATCH_USED","user":"<git email>","ci":"<true|false>"}
```

### 3. 月度 Review

参见 `docs/release-ops.md` 月度 escape hatch review SOP + 健康阈值。

## 实施清单（每次 cycle 进 Phase 4 前自检）

- [ ] `src/code-meta.ts` SUFFIX_RULES / EXPLICIT_META 改动已 cross-check `docs/wire-emit-codes.md`
- [ ] `src/index.ts` `PROTOCOL_VERSION` 常量已 bump（schema 行为有变化时）
- [ ] `package.json` version 已 bump
- [ ] `CHANGELOG.md` 已加新版本 entry
- [ ] 新增 `src/__tests__/<topic>.test.ts` 测试
- [ ] `npm run build` + `npm test` + `npm run check:protocol-version` + `npm run check:dead-spec` 全过
- [ ] `claude-docs/discussions/` 已有当前版本的 consumer ack 文档（`device-team-(final-)?ack-(of-protocol-reply-<topic>-)?v<X.Y.Z>.md`）
- [ ] `npm publish` 时 `prepublishOnly` 第 5 stage `check:consumer-ack` 通过（PASS 写入 audit log）
- [ ] Phase 5 release notice 已写
- [ ] Phase 6 三端 pin bump + 部署

---

## 参考资料

- skill source: `~/.claude/skills/protocol-version-coevolution/`
- 历史 cycle 档案: `claude-docs/discussions/`
- 设备端 catalog: `docs/wire-emit-codes.md` (mirror of `claude-docs/wire-emit-codes.md`)
- escape hatch spec: `docs/release-ops/escape-hatch-spec.md`
- 月度 review SOP: `docs/release-ops.md`