# Contributing

BRB = 平台无关 Core（27 纯核心模块，零 pi 依赖）+ Pi Host Adapter（唯一受支持宿主）。

## 环境

- Node ≥18（开发实测 node22）；系统 Node 16 不可用于 CDP/fetch 路径
- Pi（primary host）: `@earendil-works/pi-coding-agent`；Chrome/Edge + CDP 9222

## 测试

```bash
npm test            # 全套离线（协议/安全/恢复/onboarding/扫描/文档一致性）
npm run check:types # tsc --noEmit
```

## 架构规则（强制）

- **Core 不得 import Host**：核心模块不得依赖 pi/adapter 包；adapter 可以 import Core。
- **Adapter 必须薄**：一旦 adapter 开始重实现 delivery/recovery/binding，即抽象失败。
- **安全不变量变更需评审**：capability 门、交付对账、A17 affinity、fresh barrier、有界恢复、
  resend 策略——任何触碰这些的改动必须说明对全部 Host 的影响（见 docs/architecture/host-contract.md）。
- **内部文档**：BUGS 台账与 WIRE-SPEC 因测试权威依赖保留在根目录（MOVE_DEFERRED_BY_CONTRACT）；
  其余内部档案在 docs/internal/（不进 npm 包）。

## 提交约定

- 一个提交一个可回滚块；`npm test` 全绿才提交。
- 变更发布面（README 产品区 / SECURITY / CHANGELOG / package.json）需同步更新。