docs(batch5): land closing-review doc corrections

Author: Aparencia

docs/superpowers/plans/2026-09-12-frontend-redesign-batch5-view-layer.md

@@ -1569,6 +1569,9 @@ cd ..; node scripts/docs-check.mjs; node scripts/check-command-registry.mjs
 | 8 | Rust | — | — | **未跑**（逐字见下） | `raw/rust-zero-change.txt` |
 
 **门禁 5 的「既有用例一条不少」比对结论**：`node …/tmp/t0/compare-perfile.mjs <本次 JSON 绝对路径> --frozen` ⇒ **exit 0**。基准指纹逐字 = **166 行 · sha256 `AD789A809C5F2E59`（全串 `AD789A809C5F2E59EBEABF4DFE3967E60B4B50979AFCDFD7292D6088B2D91C18`）· 1608 用例 · HEAD `2559a3fd` · 采集 2026-09-12 21:08/21:12 +08:00**；候选 = **184 文件 / 1770 用例** ⇒ **`LOST=0 SHRUNK=0 GROWN=4 ADDED=18`**。**闭合核算**：`166 + 18 = 184` ✅ · `1608 + 24(GROWN 增量) + 138(ADDED 用例和) = 1770` ✅。
+
+> ⚠️ **数字更正（Minor-3；上一行原文一字未改，只在此追加 —— 删除行 0 纪律）**：上一行闭合式的**两个分量标签标错**，正确读数 = **`1608 + 13(GROWN 增量) + 149(ADDED 用例和) = 1770` ✅**。逐条：**13** = `3 + 3 + 4 + 3`（下一行 GROWN 四件的增量 `6−3` · `9−6` · `10−6` · `43−40`）；**149** = 再下一行 **ADDED 18 件自己那份清单**的用例数之和 `8+4+2+17+2+12+10+13+11+9+6+11+5+14+6+5+5+9`。**两条总数原本就对**（`13 + 149 = 162 = 24 + 138` ⇒ `1608 + 162 = 1770` ✅ · `166 + 18 = 184` ✅）⇒ 这是**同一节内的转录错位**，不是用例面差异。复现：`node tmp/fix18/verify-facts.mjs`；收口评审 §Minor-3；同款更正见 `v0.22` 测试面原行紧后。
+
 - **GROWN=4**：`ui/primitives/navHeight.consumption.test.ts` 3→6 · `ui/primitives/Modal.scroll-lock.test.tsx` 6→9 · `ui/primitives/style-contract.test.ts` 6→10 · `utils/colorPalette.test.ts` 40→43。
 - **ADDED=18（逐个用例数）**：`useNotesDeepLink.test.ts`(8) · `SessionDetailPanel.test.tsx`(4) · `NotesPage.groupFilter.test.tsx`(2) · `views/architecture.guard.test.ts`(17) · `views/architecture.slots.test.ts`(2) · `views/registry.test.ts`(12) · `views/registryResolution.test.ts`(10) · `views/useViewMemory.test.ts`(13) · `NotesReadingColumn.views.test.tsx`(11) · `SessionDetailHeader.test.tsx`(9) · `SessionScreenCards.test.tsx`(6) · `SessionViewHost.test.tsx`(11) · `surfaceTagRegistry.test.ts`(5) · `ViewSwitcher.test.tsx`(14) · `SessionCardFlowView.test.tsx`(6) · `SessionProofView.test.tsx`(5) · `SessionTriTrackView.test.tsx`(5) · `noteViews.test.tsx`(9)。
 - ⚠️ **仪器口径（必记）**：`numTotalTestFiles` **不存在** —— vitest **4.1.11** 的 JSON 顶层键只有 `numTotalTestSuites, numPassedTestSuites, numFailedTestSuites, numPendingTestSuites, numTotalTests, numPassedTests, numFailedTests, numPendingTests, numTodoTests, snapshot, startTime, success, testResults`（`hasOwnProperty` = false、`typeof` = `undefined`）⇒ **文件数一律用 `testResults.length`**。
@@ -1788,6 +1791,8 @@ cd ..; node scripts/docs-check.mjs; node scripts/check-command-registry.mjs
 
 **逐条（22 条；每条给「哪一步 · 为什么 · 代价 · 谁批准/依据」）**
 
+> ↳ **收口评审补登（2026-09-12；本节 22 条原文一字未改）**：下表 **#23–#29** 是**收口评审**（`batch5-closing-review.md`）回来后的追加行，覆盖 **Important-1**（`surfaceRatchet` 登记制判据语义修正）与 **Minor-1/2/3/5/6**。**⚠️ 口径**：本节全部改动都是**纯追加**（守本批一贯的「**原文保留 + 删除行 0**」纪律）⇒ 凡涉及**既有行里数字写错**的（Minor-1/2/3），**不修改原行**，而是在**原行紧邻处**追加「⚠️ 数字更正」行；各落点逐一列在 #27/#28 的「谁批准」格。
+
 | # | 偏差 | 为什么 | 代价 / 读数 | 谁批准（依据） |
 |---:|---|---|---|---|
 | 1 | **拆件产物从 1 个变 3 个**（`SessionRawView` + `SessionViewHost` + `SessionAuxBlocks`） | C9 的「主文件 ≤150」在只抽一个 `SessionRawView` 时**达不到**（逐块行数实测见 Task 2 Step 2 的四步抽件） | 多 2 个文件的行数账（157 / 136 / 127）；**没有为凑数而拆**（三者各有独立职责） | 计划 §规模与预算 §1 的注已预告「T18 需如实登记」 |
@@ -1812,6 +1817,13 @@ cd ..; node scripts/docs-check.mjs; node scripts/check-command-registry.mjs
 | 20 | **贴边表 13 格中 2 格与实测不同**（`textBaseline.ts` 声明 **299** → 实测 **297**（**机理未判定**）· `loadingRatchet.test.ts` 声明 **299** → 实测 **181**（**已归因**：批 4 收口拆出 `loadingScan.ts` **101 行**）） | 计划贴边表取的是批 4 中途时点值 | **不为补数字去 `checkout`**（禁）⇒ 如实写「1 格已归因、1 格机理未判定」 | 派发书逐字 + T18-A 的 U-1 |
 | 21 | **`architecture.slots.test.ts` 声明 95 → 实测 100** | **收口提交 `b4edf8e4` 自己**（`+6/−1`） | 时点值 vs 终态值之差 | T18-A 实测（`git show --numstat` 逐字 `6 1`） |
 | 22 | **`useViewMemory` 预算 ≤70 → 实测 70（顶格余量 0）** | C5 的预算上限恰为 70 | **顶格**：任何后续 +1 行都会**越过预算**（但仍 ≤300） | 计划 §规模与预算（如实登记） |
+| 23 | **`surfaceRatchet` 判据语义修正 = 新增调用点登记制**（T15a `cc49b09c`，5 文件 **+388/−83**；台账 §二十二 ④ 用词「**必须**」进本节） | 计划写「标签数 == `FROZEN_SURFACE_TAG_TOTAL` 常数」⇒ **任何新视图用 `<Surface>` 必然红**（T9 实测被迫改用 token 变量绕开） | **判据语义**：⑦ 标签数 `=== 14` 硬等于 → **`=== Σ登记值`**（等价 —— Σ 被 3 条锁钉在 14）· 总数 → **`Σ登记值 == FROZEN ∧ Σ实测 == FROZEN`**（等价）· **新增的牙**：**逐文件 ≤ / ==**（legacy 行 `实测 ≤ 登记值`、新登记行 `实测 == 登记值`）· **表自洽 + 锚**（`{entries:9, file:TaskConversationView.tsx, value:3}` **三查**）**+ `legacy 和锁`**（`SURFACE_TAG_FROZEN_LEGACY_COUNT = 14`）· **未登记 = 0 + 防僵尸**。**唯一新通道**：新文件用 `<Surface>` **当且仅当同一次提交**里登记 `{file, count(恰等于实测), reason(≥12 字)}`（不带 `legacy`）+ **抬高** `FROZEN_SURFACE_TAG_TOTAL` 到新 Σ + **同步锚**。**四条堵漏**：① `legacy 和锁`（禁「降一个 legacy 值腾地方」）② 总数对既有 9 文件实测是**紧上界** ③ 新条目**恰等于**实测 ④ 未登记 = 0 + 防僵尸。**读数**：`FROZEN 14 = Σ登记 14 = Σ实测 14` · `SURFACE_TAG_REGISTRY.length` **9** = 锚 entries **9** · `legacy 和锁 14` · **本批新登记 0 条**（通道已开；M5「合法登记」变异实测 **30/30 全绿**证明通道可用）。**行数代价**：`surfaceRatchet.test.ts` **287 → 261** · `surfaceBaseline.ts` **261**（加完锚 + 常数）· `surfaceResidual.ts` **81 → 184** · **因 300 行硬限被迫从 3 路径扩到 5 文件** ⇒ 析出 **新 `surfaceScan.ts`（80）** + **新 `surfaceTagRegistry.test.ts`（145）**（`surfaceRatchet.test.ts` 加完新牙实测 **391 > 300**，`line-limits` 当场红）。**未动任何 `ui/primitives/**` 生产代码** | 台账 §二十二 ④「**必须进「与计划的偏差」或「判据修正」节**」+ §二十三；`task-15a-report.md`；收口评审 **Important-1** |
+| 24 | **计划 Task 11 V2 的「改动只含 3 项」→ 实测 4 项** | V2 逐字写「改动只含：① 3 个样式属性 ② 文件头注释 ③ 1 个 import（`zIndex`）」；实测多第 **4** 项 = **新增 `data-testid="session-header"`**（1 个属性）—— 计划**自己的 D2** 逐字要求 `getByTestId("session-header")`，而该锚点此前**全仓 0 命中** ⇒ 不新增则 D2 写不出来 | **纯加法**：既有两个锚点（`session-title-input` / `session-rename-open`）**一字未改** · props 6 字段**一字未动** · `invoke` 调用点与时机 **0 diff** · **零新增棘轮计数**；`SessionDetailHeader.test.tsx` **改前 5 passed / 4 failed → 改后 9/9**（改前 4 红逐字 = `Unable to find an element by: [data-testid="session-header"]`） | 台账 §二十二 ⑥ + §二十一 ①；T11 报告 §9 第 1 条；`plan:1007`（D2）/ `plan:1021`（V2）；收口评审 **Minor-5 之 ①** |
+| 25 | **计划 Task 11 Step 2 的「只加这三个属性」实为 4 个** | 计划**同一段的 bullet 自己列了 4 条**：`position` · `top` · `zIndex` · `background`（防正文透出）⇒ 属计划文本的**计数笔误**，按 bullet 逐条执行 | `SessionDetailHeader.tsx` **161 → 176**（预算 ≤180）；`position: "sticky"` · `top: "var(--ed-space-4, 4px)"`（token 来源 = `ui/tokens.css:51`，**不新增 token**）· `zIndex("raised")` = 10 · `background: "var(--ed-bg-canvas)"`；改后 **9/9** | 台账 §二十二 ⑦ + §二十一 ②；T11 报告 §9 第 2 条；`plan:1010`；收口评审 **Minor-5 之 ②** |
+| 26 | **计划 Task 11 D3 的变异体期望「写裸 `zIndex: 10` ⇒ 红」在 DOM 口径做不到** | `zIndex("raised")`（= 10）与**裸等值 `10`** 产出**逐字节相同**的 DOM `style` 属性 ⇒ **DOM 级判据原理上不可分辨**「档位来源」；该性质的牙由**既有源码级仪器** `ui/zIndex.guard.test.ts`（「不得新增裸数字 z-index」+ 例外注册表与源码逐行对拍）提供 | **双仪器口径并列登记（缺一不可）**：等值裸 `10` 变异（`t11-d3b`，两仪器同跑）⇒ **14 passed / 2 failed**，而 D3 **保持绿**、红的 **2** 条**全部**来自 `zIndex.guard`；另补**不等值**变异 `100`（`t11-d3a`）⇒ **8 passed / 1 failed，只有 D3 红** ⇒ 证明 D3 有真牙。**未编造弱判据**（该口径已写进测试文件头） | 台账 §二十二 ⑧ + §二十一 ③；T11 报告 §4.1/§9 第 3 条；`plan:1008`；收口评审 **Minor-5 之 ③** |
+| 27 | **`views/**` 生产/测试拆分写反 + 最大行数报小** | 收口回写按 `tmp/t18/measurements.md` §9 B1 的**要点行**逐字转抄，而该要点行自己写错（**生产/测试数写反**（写作 9+8，实为 8+9）· **最大行数报小**（写作 273，实为 295））——**同文件 §6.2 的表里本来就是正确的 295** | 实为 **8 生产 + 9 测试**（原行同句只列 **8** 个生产件 ⇒ 原句**句内自相矛盾**）；最大 **295 = `views/note/noteViews.test.tsx`（余量 5）**、次大 **273 = `views/session/SessionCardFlowView.test.tsx`**；`total 17` / `全部 ≤300` 两条原本就成立 | 复现：`node tmp/fix18/verify-facts.mjs` ⇒ `{total:17, prod:8, test:9, over300:[], max:{noteViews.test.tsx,295}, second:{SessionCardFlowView.test.tsx,273}}`；**落点 = 本表 #6 原行**（更正见本行）+ **`v0.22` 交付面原行紧后**追加的「⚠️ 数字更正（Minor-1/2）」行 + **`v0.22` 过程纠正 ⑪ 原行紧后**追加的同类行 ⇒ **共 3 处 `docs/**`**；收口评审 **Minor-1 / Minor-2** |
+| 28 | **测试面闭合式的两个分量标错**（GROWN 增量写作 24、ADDED 用例和写作 138） | 转录错位；**两条总数 `1608 + 162 = 1770` 与 `166 + 18 = 184` 原本就对** | 更正为 **13**（`3 + 3 + 4 + 3`，逐件见 §二 的 GROWN 清单）与 **149**（计划 §二 **自己的** ADDED 18 件用例数清单之和 `8+4+2+17+2+12+10+13+11+9+6+11+5+14+6+5+5+9`）⇒ `1608 + 13 + 149 = 1770` **恒等式自洽** | 复现：`node tmp/fix18/verify-facts.mjs` ⇒ `GROWN 增量 = 13`、`ADDED 用例和 = 149`；**落点 = 本计划 §二 门禁 5 原行紧后**追加的「⚠️ 数字更正（Minor-3）」行 + `v0.22` 测试面原行紧后同款行（**共 2 处 `docs/**`**）；收口评审 **Minor-3** |
+| 29 | **历史注释数值更正（`SPLIT_MOVES` 的 T2 注释；HEAD 无活体影响）** | 被 `5f39cefe` 删掉的注释写「守恒：新家 **2** + 源文件今日 0 == 基线 `components/SessionDetailPanel.tsx` 的 **2**（原 **3** = 这 2 + `SessionRefineSection` 迁走的 1）」——**三个数字一致地各多 1**，真值 = **新家 1 / 基线 1 / 原 2**（注释算术自洽 `2+0=2`、`3=2+1`，**结论也相同**） | **活体影响 = 0**（该注释已随条目删除、只存在于 git 历史）；**不改源码、不 amend 历史**（改历史注释须 rewrite 历史，违反只读纪律）⇒ 只在本表留痕。实测：`FROZEN_NATIVE_BUTTON_BY_FILE["components/SessionDetailPanel.tsx"]` 在 `2559a3fd`…`b7fbb4a9` **每一提交都 = 1**（从来不是 2）；`SessionViewHost.tsx` 的裸 `<button>` 实测 **1**（`0bf849d2`/`f193808d`/`d48fca57` 三提交同值）⇒ `5f39cefe` 起 = **0**；T10 的提交信息与本表 #12 用的都是正确的 `1 → 0`/`393 → 392` | 复现：`git show 5f39cefe -- app/src/ui/primitives/nativeButtonBaseline.ts`（`-` 侧逐字）+ `node tmp/fix18/probe-split-history-fix18.mjs`；收口评审 **Minor-6**（其原文修法即「**不改**、只留痕」） |
 
 **控制方前提错误的 6 例（记控制方账上；引用时按本表口径）**
 

docs/superpowers/specs/2026-09-11-frontend-redesign-design.md

@@ -465,6 +465,7 @@
 > - **两个终态清单分别由守卫对拍**：`FROZEN_VIEW_KEYS` 与 `keysFor()` 双向对拍（`app/src/views/registry.test.ts` **12 用例**）· `registry[0].key === "raw"` 且默认视图**无 `load`**（`app/src/views/architecture.guard.test.ts` **17 用例** + `architecture.slots.test.ts` **2 用例**，共 **19 passed**）。
 > - **上表第 4 行「依赖方向」在本批的机器判据**：`views/**` 8 个生产文件对 `@tauri-apps` 的**裸子串 0 / 声明级 0**（阳性对照 `components/session-detail/SessionScreenCards.tsx` **裸 1 / 声明级 1** ⇒ 仪器有牙）；`views/**` 首屏静态可达 = **0**（TS-API 口径 66 文件，工具口径 91 = 源 77 + CSS 14，双口径并列）。
 > - **出处**：批 5 计划 §收口回写 §一 · `.superpowers/sdd/2026-09-12-frontend-redesign-batch5-view-layer/tmp/t18/measurements.md` §1.2/§2.2（该目录 gitignored，不入库）。
+> - **印样数据契约（`proof` 视图；规格未给 ⇒ 批 5 T8 定，登记在此；收口评审 Minor-4 落位）**：props = `Pick<SessionViewSlot,"detail"|"imageUrl">`（**type-only**、其余 8 槽一个不接 ⇒ **结构上不可能取数/交互**；也不许自己 import `convertFileSrc`）；**DOM 锚点** = `data-testid="session-proof-view"`（根，空态分支也在）· 每张 `data-proof-sheet={first_seen_ms}` · `figure[data-proof-figure]`（图注位**恒在**，有图/无图两条分支都渲染）· `div[data-proof-body]`（正文区）；**不复用** `SessionScreenCard`（两形态只共用数据语义，代码真源是那张卡）。**七条语义（F1–F7）**：**F1 重叠谓词 = 半开区间** `seg.start_ms < last && seg.end_ms > first`（零宽屏 `first === last` **归一为点** `[first, first+1)`；**首尾相接不算重叠**；与 `useSessionDetailData` 的「屏 → OCR 块」同源）· **F2** 跨屏段在**两张印张上都出现**（重叠归属而非切分归属；与任何屏都不重叠的段**不出现在本视图** ——「原文不丢」由默认原文视图承载，见 §7.3①）· **F3** 段序 = `start_ms` 升序、并列时 `id` 升序（**先复制再排序**，不原地改 props 数组）· **F4** `<img>` 仅在 `image_ref !== null` **且** `imageUrl(ref) !== null` 时渲染（且 `imageUrl` **只在 `image_ref !== null` 时被调用** —— 计划漏了「ref 非空但解析不出」这一支，否则渲染 `src={null}` = 碎图）· **F5 两槽位锚点**（台账口径的「两槽位锚点」= 上面的 `figure[data-proof-figure]` / `div[data-proof-body]`；计划只锚了根与印张 ⇒ 没有这两个边界，P2「图注位保留」/P3「正文按区间归属」只能退化成「整篇 `textContent` 包含」的弱判据）· **F6** 序号 = `screen_id ?? index + 1`（与容器 `SessionScreenCards` 逐字同源）· **F7** `detail.screens.length === 0` ⇒ 走 `EmptyState`（`testId="session-proof-empty"`，标题「本会话无画面要点」，说明指向原文视图；**根 `data-testid` 仍在**）。**出处**：`task-8-report.md` §2.1–§2.3（逐条理由 + props 表）· `progress.md` §二十（契约原文）—— 两者都在 `.superpowers/**`（gitignored、不入库）⇒ **本行即该契约在仓库内的持久记录**。**判据侧**：`views/session/SessionProofView.test.tsx` 5 用例（P1–P5 各带变异体 M1–M8）+ 只读判据 P4 与 `nativeButton.ratchet` ①② 双红；`SessionProofView.tsx` **168 行**。
 
 ### 7.3 三条硬约束