[Docs] (Disaggregated): the four index documents keep only summaries, and every phase's detail lives in its own notes/<phase>/README.md

- ROADMAP, MEASUREMENTS and ARCHITECTURE are rewritten as summaries (333 KB of index text -> 84 KB).
  ROADMAP's phase table is one line per phase plus a link; MEASUREMENTS keeps headline numbers under
  its old §1-§13 numbering (plus §14-§16 for P6.5, P7 and P12); ARCHITECTURE keeps every decided rule
  under the same §1-§17 / appendix numbering, so the `ARCHITECTURE.md §N` references in code still
  land, and §17 becomes an index of the phase landing shapes.
- CURRENT_STAGE_PROGRESS now describes the current stage (the P12 on-screen-server subset) and absorbs
  CURRENT_STAGE_STATUS, which is removed. The P7 status tables, the P6 closing snapshot and the P6.5
  first-wave snapshot move to notes/p7, notes/p6 and notes/p65.
- Each phase gets notes/<phase>/README.md: a short summary, then the verbatim material that left
  the index documents (its ROADMAP row, its MEASUREMENTS section with subsection numbers kept, its
  ARCHITECTURE §17 part, milestones) and a file index. P8-P11 and P13 get their planned scope;
  the full open-question list moves to notes/OPEN-QUESTIONS.md.
- The phase reports that sat at the top level move into their phase folders with unchanged names:
  P5D-INPROC-PERFORMANCE, P5E-RUNAHEAD, P5F-WIRE-COMPLETENESS, P6-SPAWN-PLAN, P6-CONTRACT-DRAFT,
  P6-ENDSTATE-REVIEW. Their relative links, CONTRACT-P6.md's links to them and one tool docstring
  are updated; notes/README.md maps every old path and section number to its new place.
- 71 files under notes/recovered/ that were byte-identical copies of phase-folder files are removed.
- Corrections made while condensing: the server process reads Transport as Spawn (CONTRACT-P6 §3.1
  amended the old "child forces monolith" rule); both backends now publish kCapRunAheadApply;
  MOBILEGL_IPC_RESPAWN is a named refusal and MOBILEGL_IPC_IDLE_EXIT_S is not parsed; the Redmi
  pin row is in tools/device_bench/pin_device.sh.

check_doc_citations over docs/Disaggregated/*.md: 0 problems. No relative link is newly broken.
This commit is contained in:
2026-09-24 22:21:09 +00:00
parent 1fb18d9e73
commit 43b5cfa94e
111 changed files with 2645 additions and 20434 deletions
+53 -30
View File
@@ -1,46 +1,69 @@
# 工作笔记(原 `~/w7/notes/`)
# 阶段笔记(notes)
这一层是 MGPipe 各阶段的**工作笔记原件**:包计划(`BRIEF-*.md`)、契约草稿、集成者逐条裁定
(`INTEGRATOR-DECISIONS-*.md`)、只读审计、普查、设备记录、包任务书(`TASK-*.md`)与阶段报告。
这一层放**各阶段的全部细节**:每个阶段一个目录,目录里的 `README.md` 是该阶段的**汇总**(摘要、阶段表原行、逐门实测、落地形状、当时的进度页),其余文件是那个阶段的原始工作笔记——包计划(`BRIEF-*.md` / `TASK-*.md`)、契约草稿、集成者逐条裁定(`INTEGRATOR-DECISIONS-*.md`)、只读审计与普查、包报告、设备记录与证据。上层四份索引([`../ROADMAP.md`](../ROADMAP.md)、[`../ARCHITECTURE.md`](../ARCHITECTURE.md)、[`../MEASUREMENTS.md`](../MEASUREMENTS.md)、[`../CURRENT_STAGE_PROGRESS.md`](../CURRENT_STAGE_PROGRESS.md))只留摘要并链到这里。
它们此前只存在于一台机器的 `~/w7/notes/` 下。上层那几份文档(`ROADMAP.md`、
`CURRENT_STAGE_PROGRESS.md`、`MEASUREMENTS.md` …)**大量引用它们**——裁定编号、审计行号、
逐门数字的出处几乎全在这里。一份引用了几百次、却只存在于本地未跟踪目录的记录,等于没有记录。
所以整体移进仓库。
## 按阶段
## 路径映射
| 阶段 | 汇总 | 重要文件 |
|---|---|---|
| P0 卫生、度量、门、骨架 | [`p0/`](p0/README.md) | `BRIEF-P0.md`、`p0-device-findings.md` |
| P0.5 值头与制品头 | [`p05/`](p05/README.md) | `BRIEF-P05.md`、`p05-results/` |
| P1 `PipeInputs` + verify | [`p1/`](p1/README.md) | `BRIEF-P1.md`、`P1-LANE-FINDINGS.md` |
| P2 渲染状态 CSO | [`p2/`](p2/README.md) | `BRIEF-P2.md`、`INTEGRATOR-DECISIONS.md`、`ab/`、`bench/` |
| P3a 句柄 wave 1 | [`p3a/`](p3a/README.md) | `BRIEF-P3A.md`、`INTEGRATOR-DECISIONS.md` |
| P4a 句柄 wave 2 | [`p4a/`](p4a/README.md) | `BRIEF-P4A.md`、`INTEGRATOR-DECISIONS.md`、`ab-redmi/` |
| P5 传输 + inproc | [`p5/`](p5/README.md) | `BRIEF-P5.md`、`PACKAGE-PREAMBLE.md`、`p5-results/` |
| P5b verb 迁移 | [`p5b/`](p5b/README.md) | `BRIEF-P5B.md`、`p5b-results/p5b-close-codex-review.md` |
| P5c 共享内存读点归零 | [`p5c/`](p5c/README.md) | `p5c-audit-v1.md` |
| P5d inproc 性能 | [`p5d/`](p5d/README.md) | `P5D-INPROC-PERFORMANCE.md`(报告)、`RESULTS-P5D-R3.md` |
| P5e run-ahead | [`p5e/`](p5e/README.md) | `P5E-RUNAHEAD.md`(报告)、`INTEGRATOR-DECISIONS-P5E.md`(ID-80..136)、`TASK-*.md` |
| P5f 一切状态上 wire | [`p5f/`](p5f/README.md) | `P5F-WIRE-COMPLETENESS.md`(计划)、`close-report.md`、`magma-runahead.md`、`HANDOFF-CI-INPROC-20260920.md` |
| P6 spawn transport | [`p6/`](p6/README.md) | `P6-SPAWN-PLAN.md`、`P6-CONTRACT-DRAFT.md`、`P6-ENDSTATE-REVIEW.md`、`a6-audit-v1.md`、`gate7-device-ab.md` |
| P6.5 两轴传输 + 跨机 | [`p65/`](p65/README.md) | `evidence-index.md`、`validation-status.md`、`code-review-findings.md` |
| P3b / P4b Espryt 深化 | [`p34b/`](p34b/README.md) | `espryt-d1.md` … `espryt-d3.md` |
| P7 Magma 全量迁移(含 Ph) | [`p7/`](p7/README.md) | `PLAN-PH-P34B-P7.md`、`INTEGRATOR-DECISIONS-P7.md`(ID-P7-1..63)、`HANDOFF-2026-09-23.md`、`device-window-*/`;审查稿在 [`handoff/`](handoff/) |
| **P12**(当前)server 自有屏幕窗口 | [`p12/`](p12/README.md) | `PLAN-P12.md`、`INTEGRATOR-DECISIONS-P12.md`、`device/` |
| P8 / P9 / P10 / P11 / P13(待排) | [`p8/`](p8/README.md)、[`p9/`](p9/README.md)、[`p10/`](p10/README.md)、[`p11/`](p11/README.md)、[`p13/`](p13/README.md) | 目前只有路线图上的完整范围与出口门 |
```
~/w7/notes/<phase>/<file>.md → docs/Disaggregated/notes/<phase>/<file>.md
```
跨阶段:[`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md)(开放问题全文,编号稳定);[`handoff/`](handoff/)(P7 的集成者审查稿,路径被 P7 交接文档引用,保持原位);[`recovered/`](recovered/)(从失败的 workflow 运行里捞回的 P0–P2 期材料,`wf1` 设计定稿前的计划草案、`wf2` P0、`wf3` P0.5、`wf4` P1、`wf5` P2;与阶段目录逐字节重复的副本已于 2026-09-24 删除,只留独有的)。
上层文档里凡写作 `~/w7/notes/...` 的 `.md` 引用,都按这条规则读。
## 旧引用怎么找
## 移进来的是什么,没移的是什么
**2026-09-24 整理时移动的文件**(旧笔记、代码注释与契约里仍按旧名引用它们,文件名没变):
| 旧位置 | 新位置 |
|---|---|
| `docs/Disaggregated/P5D-INPROC-PERFORMANCE.md` | [`p5d/P5D-INPROC-PERFORMANCE.md`](p5d/P5D-INPROC-PERFORMANCE.md) |
| `docs/Disaggregated/P5E-RUNAHEAD.md` | [`p5e/P5E-RUNAHEAD.md`](p5e/P5E-RUNAHEAD.md) |
| `docs/Disaggregated/P5F-WIRE-COMPLETENESS.md` | [`p5f/P5F-WIRE-COMPLETENESS.md`](p5f/P5F-WIRE-COMPLETENESS.md) |
| `docs/Disaggregated/P6-SPAWN-PLAN.md`、`P6-CONTRACT-DRAFT.md`、`P6-ENDSTATE-REVIEW.md` | [`p6/`](p6/README.md) 同名文件 |
| `docs/Disaggregated/CURRENT_STAGE_STATUS.md` | 并入 [`../CURRENT_STAGE_PROGRESS.md`](../CURRENT_STAGE_PROGRESS.md);其中 P7 的出口门 / 已落地 / 真机三节在 [`p7/README.md`](p7/README.md),P12 部分在 [`p12/README.md`](p12/README.md) |
| 旧 `CURRENT_STAGE_PROGRESS.md` 的 P6.5 第一波与 P6 收官快照 | [`p65/README.md`](p65/README.md)、[`p6/README.md`](p6/README.md) |
**按编号引用的旧章节**(小节编号在新位置原样保留):
| 旧引用 | 现在在 |
|---|---|
| `MEASUREMENTS.md` §1 / §2 / §3 / §4 / §5 | [`p0`](p0/README.md) / [`p1`](p1/README.md) / [`p2`](p2/README.md) / [`p3a`](p3a/README.md) / [`p4a`](p4a/README.md) 的"实测"节 |
| `MEASUREMENTS.md` §6 / §7 / §8 / §9 | [`p5`](p5/README.md) / [`p5b`](p5b/README.md) / [`p5c`](p5c/README.md) / [`p5d`](p5d/README.md) |
| `MEASUREMENTS.md` §10 / §11 / §12 / §13 | [`p5e`](p5e/README.md)(§10、§11)/ [`p6`](p6/README.md) / [`p34b`](p34b/README.md) |
| `ARCHITECTURE.md` §17.1–§17.4 / §17.5 / §17.6 / §17.7 | [`p5`](p5/README.md) / [`p5b`](p5b/README.md) / [`p5c`](p5c/README.md) / [`p5e`](p5e/README.md) 的"落地形状"节(上层 §17 留一张索引表) |
| `ROADMAP.md` 阶段表某行、"P5c 计划与审计"、"立即的下一项:P6.5 第一波"、债务表、开放问题 | 对应阶段 `README.md` 的"阶段表行"节;[`p5c`](p5c/README.md);[`p65`](p65/README.md);[`p5b`](p5b/README.md) 末节;[`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md) |
| `ARCHITECTURE.md:NNN`、`MEASUREMENTS.md:NNN` 这类**行号**引用 | 指向写下它时的那个版本,今天已不对应;按上下文所说的节去找,或 `git show <当时的头>:docs/Disaggregated/<文件>` |
| `~/w7/notes/<phase>/<file>.md` | `docs/Disaggregated/notes/<phase>/<file>.md`(这些笔记原先只存在于一台机器的 `~/w7/notes/`) |
## 收录规则
| | |
|---|---|
| **移进来了** | 全部 `.md`,415 份,约 11 MB,目录结构原样保留 |
| **没有移** | 脚本(`.sh` / `.py`)、运行日志(`.log` / `.out` / `.err`)、普查与门的结果数据(`.json` / `.txt` / `.tsv`)、补丁、APK 与 `.idsig`、`nm` 转储 |
| **收录** | 全部 `.md` 笔记,以及阶段自己决定入库的小脚本、判读工装与证据摘要(如 `p7/device-window-*/`、`p12/device/`、`p12/gate/`) |
| **不收录** | 大体积、随每次运行重新产生、只在产生它的机器上有意义的证据数据:完整运行日志、APK 与 `.idsig`、`nm` 转储、设备 logcat。上层文档引用它们时给的是路径,不是内容 |
没移的那些仍在 `~/w7/notes/` 与各构建树下。它们是**证据数据**而不是文档:体积大、随每次运行
重新产生、且多数只在产生它的那台机器上有意义(绝对路径、设备序列号、构建目录)。上层文档引用
它们时给的是路径,不是内容。
## 两个需要知道的例外
1. **P6 的包计划已提升为正式文档**:原 `~/w7/notes/p6/BRIEF-P6.md` 现在是
[`../P6-SPAWN-PLAN.md`](../P6-SPAWN-PLAN.md),本目录不再保留副本,避免两份同源文档各自漂移。
契约草稿同理,见 [`../P6-CONTRACT-DRAFT.md`](../P6-CONTRACT-DRAFT.md)。
2. **`recovered/`** 是从失败的 workflow 运行里捞回来的材料(`wf1`…`wf5`),与同名阶段目录
**可能重复**,保留是因为其中几份是当时唯一的完整版本。查阶段记录请先看阶段目录。
新阶段开工时建 `notes/<阶段>/`,把计划、裁定与报告都放进去;阶段收官时补齐该目录的 `README.md` 汇总,上层索引只加一行摘要。
## 不受 citation lint 管
CI 的文档引用 lint 只吃 `docs/Disaggregated/*.md`(非递归,`.github/workflows/test.yml`),
**本目录不在其中,这是有意的**:这些笔记的 `file:line` 是写在各自当时的代码头上的,拿今天的
HEAD 去解析必然大面积失败,而那不是错误——那是它们作为历史记录的正确状态。要核对某份笔记的
引用,用它自己声明的那个 revision:
CI 的文档引用 lint 只检查 `docs/Disaggregated/*.md`(非递归,`.github/workflows/test.yml`),**本目录不在其中,这是有意的**:笔记里的 `file:line` 写在各自当时的代码头上,拿今天的 HEAD 解析必然大面积失败——那是它们作为历史记录的正确状态。要核对某份笔记的引用,用它自己声明的那个 revision:
```bash
python3 scripts/check_doc_citations.py --rev <当时的头> docs/Disaggregated/notes/<phase>/<file>.md