门禁系统 (Gates)

在 Atlas 中，“代码写完了”从来不是靠开发者或 Agent 的自述，而是取决于一套机器对账门禁（Hard Gates）。

---

门禁架构全景图

                ┌──────────────────────────────────┐
                │ 走查单确认门 (人侧: UI 旅程拍板)   │
                └─────────────────┬────────────────┘
                                  ▼
                ┌──────────────────────────────────┐
                │ 环间独立审查门 (机器: 拦截 Critical)│
                └─────────────────┬────────────────┘
                                  ▼
   [实现阶段] ──► ┌──────────────────────────────────┐
                │ 实例 ⑤ 实现审查门 (只读进程 diff 审查)│
                └─────────────────┬────────────────┘
                                  ▼
                ┌──────────────────────────────────┐
                │ 双向对账门 (testid 实然 ⇔ 应然集合) │
                └─────────────────┬────────────────┘
                                  ▼
                ┌──────────────────────────────────┐
                │ impact 对账门 (预测影响面 ⇔ git diff)│
                └─────────────────┬────────────────┘
                                  ▼
                             [收口归档]

---

门禁输出四态与退出码纪律

atlas check 逐门一行输出（格式：ok|FAIL|WARN|SKIP <名称> <一句摘要>）。FAIL 是唯一置退出码 1 的失败态，任一门 FAIL 即阻断流水线；而 SKIP 则是防「永久红门」与「静音门」的关键机制——把「还没走到这一步」与「判了不通过」彻底解耦：

取值	退出码	含义	关键纪律
ok	0	走到判据且通过	——
FAIL	1	判据硬阻断（如缺少必填字段、用例语法错误、集合不相等）	任一 FAIL 即流水线阻断退出，不得掩盖或绕过
WARN	0	判据不置红，但必须在总览里显式可见（如结构语义列留空、影响面多报）	不影响退出码，但不允许被就地静默掉
SKIP	0	没走到这一步（前置未声明，如 app_base_url 为空、结构环未跑）	不是通过、也不是失败，必须带明细原因

💡 “三态前置”的真实意图：源码纪律（3509 §B110）强调 生成物最新 具有三态语义：未就绪（SKIP）≠ 生成物过期（WARN）≠ 生成失败（FAIL）。前置缺失只会如实给出 SKIP + 原因，既不报假红，也绝不当成绿灯放行。

---

核心对账门禁详解

💡 核心对账门禁（代表性节选）：机器侧全量总账见 .atlas/shared/gates.md；运行 atlas check 时会聚合执行全部登记校验器。

1. testid 双向集合对账门 (validate_testids.py)

• 断言：用例分片中声明的应然 testid: 清单，与前端源码中真实扫描出的 data-testid 按页面双向集合严格相等；
• 前端代码漏写了必要埋点 ──► FAIL；
• 前端代码多写了无用埋点 ──► FAIL；
• 只有集合完全相等才允许放行，杜绝测试代码与前端实现脱节。

2. 实例 ⑤：实现代码独立审查门（防漏审；机制与对账门已定形，外部执行器接入中，见 shared/gates.md）

• 运行机制：需求实现完成后、归档收口前，由独立的外部只读进程执行 git diff 审查（Fresh Context 隔离；契约与转换器见 scripts/cli_review_convert.py）；
• 应审 N / 实审 M 严格对账：
  • 实测证明：大模型在审查数十个文件的大 Diff 时，会悄悄跳过文件（静默少审）；
  • 审查器启动时先提取预审文件数 N，审查结束后统计给出 findings 的文件数 M。一旦 M < N，不论结论多好一律报红拦截！
  • 发现任何 Critical 级缺陷，一票否决收口。

3. 后端/全栈测试用例 ⇔ AC 跨语言对账门 (validate_ac_alignment.py)

• 校验后端与全栈测试用例中挂载的验收标记（如 @pytest.mark.ac("AC-xxx")）与 PRD 声明的 AC 集合严格对齐；
• 防止核心业务逻辑在实现后漏测或假挂载，支持 advisory 预警与 enforce 硬阻断模式。

4. impact 影响面预测对账门 (impact_reconcile.py)

• 在需求规划阶段，模型通过代码图谱和 AST 预测本次改动的影响面文件集合；
• 在任务收口归档时，将该预测集合与真实的 git diff --name-only 产生的文件列表进行自动差集比对；
• 持续暴露出模型的盲区，防止漏测边缘修改。

5. 设计档案豁免对账门 (validate_design_exemptions.py)

• 前端视觉设计若要豁免某条检测规则（例如色彩对比度特殊定制），必须在 product/design.md 登记 detect:<rule-id>；
• 校验器要求设计档案里的豁免列表与 .impeccable/config.json 中的实际忽略规则双向严格相等；
• 关掉报警必须有台账，有台账必须改配置，杜绝无台账的私自关闭。

6. 装配版本完整性门 (.atlas/VERSION)

• 目标项目中的装配态与 Atlas 源包内容摘要实时哈希比对；
• 源包升级或本地改动脱节时，自动亮出 WARN，防止跨项目版本漂移。