项目规范
分支纪律、门禁、worktree 约定、测试分层。
分支纪律、自动化门禁矩阵、测试执行槽划分与决策留痕约束。遵守这些工程铁律，是维护代码库在重度开发下依然健康稳定的唯一保障。
分支纪律与 Worktree 约定
- 日常开发严格在
dev分支：严禁直接在master上提交改动。master为发布保护分支，仅在发版时通过scripts/release.sh由dev执行 fast-forward 合并。 - 分发裁剪 (Export-Ignore)：发版会自动通过
git archive打出纯净安装包。所有新增的测试、门禁脚本必须同步登记至.gitattributes的export-ignore，防止测试代码混入轻量安装包。 - 常驻 Worktree 物理外置：其他分支（如
gh-pages、promo等）常驻于与主仓平级的兄弟目录（如../claude-chat-mobile-gh-pages），物理上不在源码树内，杜绝搜索和工具扫描污染。
自动化测试执行槽 (S0–S7) 与防假绿
测试与门禁全部集中于 tests/ 目录下，分为清晰的八大执行槽（按「安全性依不依赖被测代码正确性」划分，详见 tests/README.md 与 docs/testing.md）：
| 执行槽 | 定义与内容 | 安全边界与隔离要求 |
|---|---|---|
| S0 静态 | 语法、import 边界、循环依赖、双向事件契约、i18n key、破坏性删除形态、分发裁剪、Swift typecheck | 纯静态扫描，不跑业务代码 |
| S1 决策与真磁盘 | 纯函数 + 一次性目录（mkdtemp）上的真实 fs / git / symlink / FIFO（tests/unit/ 与 tests/invariants/ 纯逻辑） | 不拉起 app.js、不 spawn Claude 进程 |
| S2 真 server + 假 CLI | 真实组装根，HTTP + Socket 接线（tests/integration/，CLAUDE_BIN 指向 fake-claude.sh） | 零真实模型回合 |
| S3 真浏览器 + 假后端 | 真实 app/public 前端，内存 Mock Server 仅模拟事件信封（tests/e2e/） | 零外部依赖，无真组装根 |
| S4 薄跨缝 | 真浏览器 → 真 server → 假 CLI（覆盖字段契约分叉） | 零真实模型回合 |
| S5 授权真 Claude | 真 CLI + 真 SDK + 隔离的 CCM_DATA_DIR / HOME（RUN_CLAUDE_INTEGRATION=1） | 需真 Token 与显式授权 |
| S6 变异 | 故意改坏源码再跑 S1（npm run mutate:docker） | 强制在 Docker 容器内跑，沙箱隔离 HOME |
| S7 Darwin | Swift 逻辑 + 桌面端 bundle 编译校验 | 唯一需在 macOS 宿主机跑的槽（容器无 swiftc） |
宿主机命令白名单约束 (guard-host-tests)宿主机仅允许直接执行白名单内的无害命令（
npm run lint、npm run check、npm run test:unit、npm run test:e2e）。任何拉起真实服务或执行卸载器的测试必须进 Docker 容器，物理切断对开发机家目录（~/.claude）造成破坏的可能。
代码决策留痕与 Git Commit 规范
根据工作宪法，开发会话会定期清理，而 Git 历史永久留存。重要架构取舍直接记录在 Commit Message 的 Trailer 中，不新增多余的设计文档：
feat(auth): 引入 IPv6 /64 分桶聚合限速机制
对同一 /64 子网的入向请求聚合至单桶，防御动态轮换 IPv6 绕过策略。
Constraint: 不引入外部 Redis，完全基于进程内 LRU Map 实现
Rejected: 按单一完整 IPv6 限速（极易被攻击者动态前缀绕过）
Tested: tests/unit/auth-rate-limit.test.mjs 注入单 IP 测试变红，/64 聚类通过
Not-tested: 超过 10 万并发连接下的内存极限水线