# atlas 共享契约 — 全局规则

> atlas 三环（`structure` / `prd` / `e2e`）与 `apply` **共同遵守**的规则（原型环已移除，2026-09-27，`3508 §92`）。
> 正文只此一份；各环按路径引用 `.atlas/shared/global-rules.md`，**不得在环契约里复制**。

## 1. 跨项目（硬约束）

- atlas 核心、`shared/`、`rings/*/reference.md`、`templates/`、`validators/` **不得出现任何具体框架名**（语言框架、前端框架、ORM、构建器、桌面壳等一律不写）。
- 框架知识只有两个合法来源：目标项目的 `product/stack-profile.yaml` 与 `adapters/`。
- 违反即视为契约失败，与"跨项目通用"硬要求冲突。

## 2. 单一真相源

- 每类信息只有一个权威落点，登记见 `.atlas/shared/single-source.md`。
- 其余位置只能做**引用或索引**，不得复制正文；发现两处正文即判为漂移。

## 3. 不越界产出

- 每个环只产出本环契约规定的内容。
- 例：`structure` 环不得顺手写 PRD、用例或需求；其它环同理。**越界即失败。**

## 4. 幂等

- 脚本/适配器生成的区块用标记包裹：

  ```
  <!-- atlas:adapter <category>:begin -->
  ...由脚本生成，重跑覆盖...
  <!-- atlas:adapter <category>:end -->
  ```

- 重跑**只覆盖标记内**；标记外的内容由 agent 维护，原样保留。
- 首次生成时也要预置空标记区块，保证后续可自动化。

## 5. 占位符禁令

- 禁止出现 `TODO` / `待补充` / `TBD` / `待定` / `(To be filled)` / `[FIELD:]` / `视情况而定` / `后续补充` 等未完成字样。
- 写不出来就写「未发现」，并说明**取证范围**。
- 允许的例外由各环契约显式声明（如 `prd` 环的「待决策登记表」、`structure` 环 A 类的「待决策」小节）。

## 6. 取证

- 所有事实性结论必须能指向文件路径或命令输出。
- 无法取证的内容标注为**推断**，并说明依据与范围。
- **「门会咬」的证明要逐字节对拍**（2026-09-27 补，`3509 §B87` + `§B80`）：声称某道门有效时，必须走「**先证基线 GREEN** → 注入反事实 → RED → **逐字节还原** → GREEN」四段，且②**注入前断言字节确实改变**（否则锚点静默不匹配 ⇒ 得到「门不咬」的**假阴性**）、③ 需要分布式的变异先断言锚点**恰好命中 1 次**、④ 跑前清 `__pycache__` + `PYTHONDONTWRITEBYTECODE=1`（否则 `.pyc` 复用会造出「还原后仍红」的**假阳性**）。可复用工具：`scripts/mutation_proof.py`。

## 7. 用户确认门

以下动作**必须先获得用户明确确认**：

- 覆盖或删除已有产物文件。
- 生成或改写 `product/stack-profile.yaml`（技术栈画像影响后续所有环）。
- 在 `.trellis/workflow.md` 打补丁。
- 任何跨项目通用的模板 / 校验脚本 / 契约变更（属 atlas 包自身演进，不属于单项目任务）。

**独立审查不替代本门（2026-09-26 补）**：`shared/independent-review.md` 的「低风险 + 审查者独立结论一致 ⇒ 自动通过」**只适用于低风险侧**（可逆、只影响单个项目的 `product/` 产物、不动通用契约）；**本节四条一律人工** —— 审查者只**压缩阅读量**（把结论压成一行「已独立复核，同意 / 不同意，理由 X」），**不替代确认**。一句话：**审查者可以替人「读」，不能替人「签」**。

## 8. 取证与应然分离

- 从代码或旧实现读到的是**参考基线**，不是本产品的应然。
- 表述为「参考基线（取证：<路径>）」，不得直接写成结论。

## 9. 收口（收口必做）

- **收口步骤表**（人侧）= `.atlas/shared/closeout.md`；**门总账**（机器侧）= `.atlas/shared/gates.md`。两者均**当轮做完**，不得留到「下次顺手」。

## 10. 资产位置

- 包产物（契约、模板、适配器、校验器）由 `install.sh` 装配到 `<项目根>/.atlas/`。
- 项目产物（结构事实、PRD、E2E 用例）落在 `<项目根>/product/`，目录与 role 语义见 `.atlas/shared/layout.md`。
- 结构事实落 `<项目根>/.trellis/spec/structure/`（Trellis 路径注入层）；A（技术栈+启动，可选）与 H（测试/运行，条件）落项目根 `README.md`（受控例外，见 `layout.md` §1）。编码规范与 testid 约定**不在 structure 环产出**（testid 归 E2E 环）。

## 11. 产物生命周期（生 / 变 / 迁 / 死）

> `3509 §95` 定形：契约只写了产物「怎么生、怎么改」，没写「怎么迁、怎么死」—— 原型环退役（E1）是活标本：手工缝制、漏了四处（契约面 / 装配面 / 文档面 / 产物面，`3509 §B115`）。

| 态 | 契约位 |
|---|---|
| **生** | 首次认证门（各环的落笔门） |
| **变** | 增量覆盖语义（`apply/reference.md` §5；无需求卡修订见 §3.2） |
| **迁** | 真相源迁移 = **一等事件**：登记到 `shared/single-source.md` §3（迁移史）+ 迁移仪式 = **完备性对账**（新源 ⊇ 旧源迁移基线集），过了才算迁完 |
| **死** | 退役三件套（下节）+ 传播义务 |

### 退役三件套（硬）

1. **声明两档**：每个受影响项明确归入 **删除** / **失义**（产物或规则失去宿主但要求仍在）。**无冻结档**（2026-09-30 用户拍板，先例 = 原型目录 / design-tokens / `3507 AT`）：退役即删、历史归 git，工作树只读留档 = 漂移面。
2. **迁移与失义清单**：逐项覆盖七类面 —— **状态标签 / 输入链 / 门 / 校验器 / 模板 / 装配项 / 规则**。
   - **「规则」必须列入**（`3509 §107` 教训）：环删掉后，它承载的**规则**会失去宿主而没有任何检查会发现 —— 实例：`data-atlas-panel`（原原型环 §5.1 ⇒ 重新归位到 E2E 环 §4.1）、UI 文案纪律（原原型环 ⇒ PRD 环 §6）。失义项的处置只有两种：**归位**（写进新宿主的契约）或**明确作废**（写明理由）。
3. **传播义务**：**回灌完成前，退役不算结束**（防复活属退役本体，不是后续事项）—— 具体 = 源包改动 + 副本重装对账 + vault 同步 + `ATLAS-UPSTREAM` 登记四处齐全。

### 状态标签带纪元

- 流水线级变更定义**纪元**（当前唯一：**E1 = 原型退役**，`3508 §92`）；旧标签按映射表**转义**（`prototype-pass` → E0 历史终态，存量合法、不再产生；见 `rings/e2e/reference.md` §5.4）。
- 新增纪元时必须在 `3507` 记一节（背景 / 被否 / 连带）+ 在本节登记映射表。
- **机器判据**：环退役的**对称性**（`rings/<r>/` ⇔ `skills/atlas-<r>/`）由 `tests/test_install_selfcheck.py` 判据 5 守（先例见 `3508 §92` E1 原型退役）。

## 12. 成本预算（通则，`3509 §100`）

**「先量再动手」入契约**：凡改动**产物义务**（要写什么、写多少）或**审查宽度**（fan-out 单元数 / 轮次 / 抽样比例）之前，**先量当前成本与预期收益**；实测不足即不做。

- 先例：`3509 §70`（成本实测）/ `§72`（`O6` 环契约分层实测后可移动段 = 0/0/597 字符 ⇒ **不做**）/ `§100`（adopt 全量外推 ≈ 2000 行 ⇒ 改判为「开户最小集」）。
- 四处预算上限（各自宿主）：**审查并发 ≤ 4 + 429 退避 + 应审/实审对账**（`independent-review.md` §6 第 7/8/9 条）· **裁决每批 ≤ 10 条**（`apply/reference.md` §5.2）· **体量上限 9500 字符 ⇒ 拆分/精简评审**（`rings/structure/reference.md` §7 + `rings/prd/reference.md` §9）· **产出分级随 `apply` 模式**（`apply/reference.md` §1）。
- **超限不得静默**：任何预算击穿 = 流水线自身缺陷，登记为台账条目族「**预算击穿**」（与产品缺陷分写，`3509 §94`）。

## 13. 契约叙事分层（`3507 AX`）

- 规则正文只写**当前设计**：可执行判定 + **台账号锚（≤ 一行指路）**；事故经过 / 日期考据 / 被否方案 / 案例 ID 流水**不得在契约正文复述**——归台账（纪要卷），锚是唯一指路。
- **例外**：影响执行判断的机制原理（为何这样判 / 已知误报形态与对策）可留，但 ≤ 2 句、不带案例 ID 流水。
- **存量不整卷回写瘦身**（实测纯史叙事占比 ≈3–5%，低于 §12 动手线，`3508 §175`）；**触碰即压**：日后需求改到某节时，顺手把该节史叙事压成锚。

## 14. 产物落笔纪律（零反刍与读者中立，原 no-negative-echo 内化）

- **读者中立**：所有交付产物（包括需求卡、代码、注释、提交信息、PR 说明、文档）必须按**「读者从未看过工作过程与会话记录」**来写。
- **禁止反刍（No Negative Echo）**：会话中被否决的备选方案、被推翻的提议、中途反复纠正的过程，属于会话控制数据，**绝不得作为最终产物的特征反刍到命名、标签、代码注释、提交日志或交付正文**（严禁「此前曾尝试 X 失败，现改为 Y」或「针对某某历史纠偏做出的改动」式残留）。
- **正向陈述（Positive State）**：产物只陈述当前敲定的正向目标、既有客观事实与架构不变式。
- **例外场景**：仅在审查报告（`product/reviews/`）、历史台账/决策记录，或用户显式要求做方案对比审计时，才记录被否备选与权衡原因。

## 15. 流水线设计缺陷自感知上报契约（Pipeline Self-Reporting）

- **背景与定位**：Atlas 流水线必须在真实工程实战中持续演进。当开发过程中遇到**流水线本身的设计缺陷、规则阻断或交互卡点**时，模型严禁静默绕过、偷偷注释规则或假装完成，**必须主动结构化提炼并自动上报至云端设计池**。
- **零业务上下文（硬约束）**：上报的是**规则缺陷**，不是某个产品的现场——不写产品名、业务名词、真实数据、业务代码片段；业务背景只在会话内用于定位，落盘前一律抽象成形态。池子要的是可复用的**同根问题**，业务现场对它没有用（顺带也就没有把用户业务发进公开池这回事）。
- **触发上报的四类典型场景（不仅是异常崩溃，更是设计冲突）**：
  1. **结构性冲突（业务合理但被卡死）**：例如业务形态完全合情合理（如长业务累加链测试、特殊合法路由嵌套），但 Atlas 现有规则或提取器发生机械性冲突；
  2. **人机体感别扭（交互摩擦点）**：某流程导致用户反复重复操作、产生决策疲劳、或提示词诱导模型与人类反复来回扯皮；
  3. **底层假设破产**：底层依赖工具（如 AST 解析器、代码图谱、Playwright）在真实环境下的真实语义与 Atlas 既有契约假设不符；
  4. **用户显式纠偏**：用户在会话中明确指出“Atlas 这里的流程/设计/规则不合理”，或**直接要求“把这个上报一下”**（后者等于模型本轮漏认，见下条）。
- **模型自动执行协议**：
  1. 结构化提炼**三要素**：**【设计缺陷本体】**（哪条规则 / 哪个提取器 / 哪一步流程，在什么条件下冲突）、**【触发形态（抽象）】**（什么形状的用法撞上它，而非哪个产品）、**【建议解耦方向与备选方案】**；
  2. 自动调用 `atlas report` 命令行（或执行 `python3 .atlas/scripts/atlas_report.py`）将结构化记录静默上报；
  3. 上报后向用户明确说明已沉淀现场，并给出当前阶段的最优临时推进方案。
- **用户开口才算数 = 漏认**：用户主动要求上报时，说明本轮模型没自己认出来——照办之外，回头把同一轮的同类现场一并认一遍（上报带 `--trigger user`：池子里的来源分布就是本契约的体检表，全 `user` 即自动路径没在工作）。本契约的价值在**上游**感知，不在事后补录。
- **交付面（提醒靠这三处落地，不靠模型自发回忆）**：① 项目指针段（`patches/project-wiring/agent-pointer.md` → 目标仓库 `AGENTS.md`，会话内常在上下文）；② 宿主扩展的撞门提示（`extensions/pi.ts` 的 `turn_end`：机器门报非零时同段提示）；③ 收口扫描（`shared/closeout.md` 触发表「开发流程/宿主适配摩擦」行）。三处之外无机器门：**「这是不是流水线缺陷」是语义判断**，机器只能保证提醒出现在正确的时点。