diff --git a/docs/CM95_S52_剩余26个根因统一修复_Codex任务_v1.md b/docs/CM95_S52_剩余26个根因统一修复_Codex任务_v1.md new file mode 100644 index 0000000..cd1d0f5 --- /dev/null +++ b/docs/CM95_S52_剩余26个根因统一修复_Codex任务_v1.md @@ -0,0 +1,721 @@ +# CM95 S-52 剩余 26 个根因统一修复 Codex 任务 v1 + +## 1. 任务性质 + +这是一次 **统一修复任务**,不是新的审计任务,也不是继续拆成多个独立 Codex 任务。 + +当前已完成: + +- OpenCPN Code-First S-52 等价审计; +- 206 条 branch 审计; +- 120 FAIL / 86 NOT_PROVEN; +- 120 FAIL 已归并为 38 个 Root Cause; +- Batch 1 已修复并提交 12 个低风险局部根因: + - RC-012 + - RC-022 + - RC-023 + - RC-024 + - RC-025 + - RC-026 + - RC-029 + - RC-030 + - RC-031 + - RC-032 + - RC-034 + - RC-035 +- Batch 1 提交: + - `f3047a3f06d2eac3f603dcb54646a60fdead2354` + - `fix: align local S-52 CSP decisions with OpenCPN` + +本任务必须在 **同一次 Codex 工作流程中** 继续处理剩余 26 个根因: + +- 25 个已确认代码根因; +- 1 个证据不足根因 RC-021。 + +不得把本任务退化为“只写规划”“只写报告”“只修一两个 RC 后停止”。 + +--- + +## 2. 仓库与固定基线 + +仓库: + +`/root/sourceserver/cm95` + +分支: + +`main` + +本任务开始基线至少应包含: + +`f3047a3f06d2eac3f603dcb54646a60fdead2354` + +OpenCPN 固定参考: + +`docs/外部参考/OpenCPN源码基线_f7211b4e/` + +OpenCPN commit: + +`f7211b4e1874c453e37a7f190aa191c55a25c32e` + +主要审计输入: + +- `docs/报告/CM95_S52_OpenCPN渲染流程对照审计报告_v2.md` +- `docs/CM95_S52_语义守恒与运行时能力审计标准_v2.md` +- `build/audits/cm95_s52_opencpn_code_first_equivalence_v2.json` + +当前 Production Plan ID: + +`57e72826db1d3e3e69f0b3b084bef4fb9469b5edc47dc0030fc2ec3e46adecf9` + +当前正式 release: + +`cm95-d1-62a85bd40d3a-57e72826db1d` + +--- + +## 3. 最高优先级约束 + +1. OpenCPN 固定源码是 Source of Truth。 +2. 修的是 **完整 Rule Chain 等价性**,不是只让画面“看起来接近”。 +3. 不得通过删除审计、放宽 Gate、改 FAIL 定义、跳过分支来获得 PASS。 +4. 不得把 PREVIEW_ONLY 直接改成 IMPLEMENTED,除非对应 runtime consumer 确实完成并有可执行 witness。 +5. 不得为了 DANGER53 发明 OpenCPN 中不存在的图形资源。 +6. 不得修改与本任务无关的数据库/importer/Linux 环境文件。 +7. 当前工作区已有无关未提交修改,必须在开始前记录 SHA-256,并在每个阶段结束后确认未变化。 +8. 不得使用 `git add .`。 +9. 所有阶段必须显式 stage 任务相关文件。 +10. 无法证明时保守保留 FAIL / NOT_PROVEN,不允许猜测。 +11. 截图只可作为最终视觉回归,不得作为主要逻辑验收依据。 +12. 不要每修一个小点就做一次完整 5064 PBF 重扫;需要全量重建/重扫时集中到最终集成阶段一次完成。 + +--- + +## 4. 剩余 26 个 Root Cause + +### RC-001 +**Python hazard resolvers return incomplete ordered nested instruction chains** + +- Layer: NESTED_CSP_CHAIN +- Risk: MEDIUM +- 影响约 49 FAIL +- 目标: + - OBSTRN04/WRECKS02 恢复完整有序 nested suffix; + - QUAPNT01; + - OBJNAM TX; + - SOUNDG; + - WRECKS tail; + - 正确顺序守恒。 +- 注意:Wk TX / WRECKS07 的 Python 生成能力已存在,不要重复归因。 + +### RC-002 +**Scalar presentation hints do not preserve the executable mixed-opcode chain** + +- Layer: INSTRUCTION_IR +- Risk: HIGH +- 影响约 20 FAIL +- 目标: + - 建立可执行、有序、带参数的 Rule Chain / Runtime Rule IR; + - 不能继续只依赖 first-per-kind scalar hints; + - initial Lookup + CSP composition 必须守恒; + - Web/runtime 可消费该 IR。 + +### RC-003 +**Point hazard runtime emits one main symbol and depth text instead of the full chain** + +- Layer: RUNTIME_EXECUTOR +- Risk: HIGH +- 影响约 26 FAIL +- 目标: + - Point hazard 执行完整 ordered chain; + - 不再只执行一个 SY + 普通 depth text; + - 支持 TX、nested Q、Wk/WRECKS07 等。 + +### RC-004 +**Hazard runtime rejects line and area geometries before portrayal** + +- Layer: RUNTIME_EXECUTOR +- Risk: HIGH +- 影响约 23 FAIL +- 目标: + - hazard runtime 支持 Point / Line / Area; + - LS / LC / AC / AP / SY / TX / SOUNDG 按顺序执行。 + +### RC-005 +**Style compiler executes only the first LS despite a preserved line sequence** + +- Layer: STYLE_COMPILER +- Risk: MEDIUM +- 影响约 1 FAIL +- 目标: + - 多 LS 顺序执行; + - QUALIN radar double-line 等组合不得丢失。 + +### RC-006 +**LS style translation collapses DOTT to a solid stroke** + +- Layer: STYLE_COMPILER +- Risk: MEDIUM +- 影响约 10 FAIL +- 目标: + - SOLD / DASH / DOTT 语义分离; + - 不能把 DOTT 退化成 solid。 + +### RC-007 +**SOUNDG runtime substitutes ordinary text for the ordered sounding glyph renderer** + +- Layer: RUNTIME_EXECUTOR +- Risk: HIGH +- 影响约 34 FAIL +- 目标: + - 实现真正 SOUNDG glyph composition; + - 支持 digit glyph、fraction/depth placement、quality/swept marks; + - standalone SOUNDG02 与 hazard nested SOUNDG03 共用。 + +### RC-008 +**SOUNDG decisions have no feet/fathoms conversion and unit-specific rounding** + +- Layer: MARINER_STATE +- Risk: MEDIUM +- 影响约 2 FAIL +- 目标: + - metres / feet / fathoms; + - safety depth 阈值同步转换; + - 单位特定 rounding 与 glyph 选择一致。 + +### RC-009 +**Missing DANGER53 causes whole hazard feature rejection instead of resource fallback** + +- Layer: RESOURCE_CONTRACT +- Risk: MEDIUM +- 影响约 1 FAIL +- 目标: + - DANGER53 缺失仍按 upstream resource missing 处理; + - 不得发明 DANGER53; + - 不能因此丢弃该 feature 的其他有效 ordered instructions。 + +### RC-010 +**Runtime wreck isolated-danger decision ignores QUASOU containing 7** + +- Layer: CSP_DECISION +- Risk: MEDIUM +- 影响约 3 FAIL +- 目标: + - runtime WRECKS 与 Python/OpenCPN 相同处理 QUASOU=7 guard。 + +### RC-011 +**Wreck no-depth decision invents a symbol when required attributes are absent** + +- Layer: CSP_DECISION +- Risk: MEDIUM +- 影响约 1 FAIL +- 目标: + - 保留 CATWRK/WATLEV source presence; + - 缺必要属性时不得发明 main symbol; + - Python 与 runtime 统一。 + +### RC-013 +**Python UDWHAZ DisplayBase promotion also changes display priority** + +- Layer: RENDER_ORDER_PRIORITY +- Risk: HIGH +- 影响约 2 FAIL +- 目标: + - DisplayBase category 与 display priority 解耦; + - 固定 upstream 中 UDWHAZ 不应顺带改变 DPRI。 + +### RC-014 +**Runtime UDWHAZ does not propagate the DisplayBase category side effect** + +- Layer: RUNTIME_EXECUTOR +- Risk: HIGH +- 影响约 2 FAIL +- 目标: + - runtime side effect 独立于是否输出 symbol; + - dry WATLEV 抑制 symbol 时仍保持正确 category side effect。 + +### RC-015 +**Runtime DEPARE uses invalid supplied depth ranges without normalization** + +- Layer: CSP_DECISION +- Risk: LOW +- 影响约 1 FAIL +- 目标: + - runtime 与 Python 相同处理 DRVAL2 <= DRVAL1。 + +### RC-016 +**Runtime DRGARE fill path omits the dredged-area pattern and boundary suffix** + +- Layer: RUNTIME_EXECUTOR +- Risk: MEDIUM +- 影响约 1 FAIL +- 目标: + - AC + AP(DRGARE01) + LS(DASH,1,CHGRF) 完整执行。 + +### RC-017 +**DEPCNT safe-line generation bypasses SAFECD/SAFECN lookup instructions** + +- Layer: NORMALIZATION_LOOKUP +- Risk: MEDIUM +- 影响约 2 FAIL +- 目标: + - 优先执行 SAFECD/SAFECN Lookup INST; + - fixed LS 只作为 lookup 缺失时 fallback。 + +### RC-018 +**Runtime DEPCNT ignores quality-dependent dashed line selection** + +- Layer: CSP_DECISION +- Risk: MEDIUM +- 影响约 2 FAIL +- 目标: + - QUAPOS 2..9 → DASH; + - runtime 与 resolver 一致。 + +### RC-019 +**Safe DEPCNT side effects omit DisplayBase and SCAMIN override** + +- Layer: MARINER_STATE +- Risk: HIGH +- 影响约 2 FAIL +- 目标: + - safe contour 正确传播 DisplayBase; + - SCAMIN override; + - 不额外改变 DPRI。 + +### RC-020 +**DEPCNT nonzero unsupported QUAPOS falls through to an unwanted solid line** + +- Layer: CSP_DECISION +- Risk: LOW +- 影响约 1 FAIL +- 目标: + - absent/zero QUAPOS 与 unsupported nonzero 分离; + - unsupported nonzero 不输出错误 solid line。 + +### RC-021 +**UNKNOWN_ROOT_CAUSE: normal non-safe DEPCNT FAIL lacks branch-specific evidence** + +- Layer: EVIDENCE_GAP +- Risk: UNKNOWN +- 影响 1 FAIL +- 目标: + - 建立 branch-specific executable witness; + - 若当前实现等价,则修正该 branch 的审计状态; + - 若 witness 找到真实缺陷,则在本任务中新增最小 RC 说明并修复; + - 不得为了清零 FAIL 强行改判。 + +### RC-027 +**RESARE OP is materialized as a priority change absent in the fixed upstream parser** + +- Layer: RENDER_ORDER_PRIORITY +- Risk: HIGH +- 影响约 18 FAIL +- 目标: + - 对固定 upstream 基线,OP 不得产生 upstream parser 不存在的 priority side effect; + - 保留 raw instruction 事实但不要错误改变 DPRI。 + +### RC-028 +**RESARE boundary mode is frozen at materialization instead of being reselected** + +- Layer: MARINER_STATE +- Risk: MEDIUM +- 影响约 20 FAIL +- 目标: + - symbolized/plain boundary mode 在 runtime/setting change 时可重选; + - 不冻结为构建时 profile。 + +### RC-033 +**LIGHTS label emission lacks previous-position/description state** + +- Layer: MARINER_STATE +- Risk: HIGH +- 影响约 10 FAIL +- 目标: + - 同位置同描述抑制重复; + - 同位置不同描述使用正确 offset; + - 状态只影响 label emission,不破坏 light geometry/arc。 + +### RC-036 +**LIGHTS height description ignores the selected height unit** + +- Layer: MARINER_STATE +- Risk: MEDIUM +- 影响约 1 FAIL +- 目标: + - metres/feet; + - feet 使用 HEIGHT / 0.3048 rounding; + - 与 OpenCPN LitDSN 语义一致。 + +### RC-037 +**CA canvas renderer does not execute scale-dependent arc metrics and width** + +- Layer: RUNTIME_EXECUTOR +- Risk: HIGH +- 影响约 5 FAIL +- 目标: + - 使用 s52_arc_width; + - scale/SCAMIN-dependent radius/width; + - bearing/pan/zoom/resize 后保持正确; + - 不回退成固定 CSS px/mm。 + +### RC-038 +**Resolved CSP text bypasses structured text-hint materialization** + +- Layer: PRESENTATION_MATERIALIZATION +- Risk: MEDIUM +- 影响约 6 FAIL +- 目标: + - resolved CSP TX/TE 进入结构化 text operands; + - 保留 placement、font、offset、color、group; + - 与 ordered Rule IR 兼容。 + +--- + +## 5. 统一实施顺序 + +这是一个总任务,但内部必须按依赖顺序推进。 + +### 阶段 A:有序 Rule Chain 与 Presentation Contract + +优先处理: + +- RC-001 +- RC-002 +- RC-038 +- RC-013 +- RC-027 + +目标: + +1. 完整 ordered chain 可表达; +2. initial Lookup + CSP expansion 不丢顺序; +3. TX/TE、SY、LS、LC、AC、AP、CA、OP/side effect 能保持参数; +4. category、priority、SCAMIN 等 side effect 与 drawing opcode 分离; +5. 不再由 first-per-kind scalar 字段承担完整执行语义。 + +完成后建立临时 witness: + +- OBSTRN; +- WRECKS; +- RESARE; +- UDWHAZ; +- CSP-generated TX。 + +### 阶段 B:Lookup / CSP / Mariner 语义 + +处理: + +- RC-008 +- RC-010 +- RC-011 +- RC-015 +- RC-017 +- RC-018 +- RC-019 +- RC-020 +- RC-028 +- RC-036 +- RC-021 + +RC-021 在本阶段必须先得到结论。 + +完成后建立临时 witness: + +- SOUNDG units; +- WRECKS QUASOU/presence; +- DEPARE bad range; +- DEPCNT SAFECD/SAFECN + QUAPOS + category/SCAMIN; +- RESARE runtime boundary mode; +- LIGHTS height units; +- DC-OUT-ZERO-NORMAL。 + +### 阶段 C:Generic Runtime Rule Executor + +处理: + +- RC-003 +- RC-004 +- RC-005 +- RC-006 +- RC-009 +- RC-014 +- RC-016 + +目标: + +1. Point / Line / Area 都能执行 ordered rules; +2. 多 SY、多 LS、TX、LC、AC、AP 不丢; +3. DOTT/DASH/SOLD 分离; +4. resource missing fail-closed 但不丢整个 chain; +5. side effect 可独立执行; +6. DRGARE suffix 完整。 + +不得在 Web runtime 再复制一套与 Python 不同的 OBSTRN/WRECKS 业务判断;应优先消费统一 IR/运行时事实。 + +### 阶段 D:Specialized Renderer / Stateful Renderer + +处理: + +- RC-007 +- RC-033 +- RC-037 + +目标: + +- SOUNDG glyph renderer; +- LIGHTS previous-position/description state; +- CA scale-aware renderer。 + +这三项属于专用渲染能力,但必须挂在统一 Rule Executor / IR 上,不建立第三套业务规则。 + +--- + +## 6. 允许修改范围 + +根据实际依赖,允许修改以下范围内与 26 RC 直接相关的文件: + +- `src/cm95pbf/csp.py` +- `src/cm95pbf/presentation.py` +- `src/cm95pbf/s52.py` +- 与 ordered rule/runtime facts 直接相关的 `src/cm95pbf/` 文件 +- `tools/cm95_s52_style_compiler.py` +- `tools/cm95_s52_runtime_capability_audit.py` +- 与本任务 Gate/审计输出直接相关的 S-52 audit 工具 +- `config/s52/` 下 runtime capability / contract 配置 +- `web/kyushu_compare.html` +- 必要的 S-52 PBF/runtime contract 定义 +- 本任务产生的中文报告与机器审计 JSON + +如果需要修改 PBF schema / runtime contract: + +1. 先说明为什么 RC-002/side effect 无法在现有 schema 中守恒; +2. 只做最小必要变化; +3. 更新 schema/version/consumer; +4. 最终阶段统一做一次 production rebuild / release audit; +5. 不为局部 RC 单独重复全量 5064 PBF。 + +--- + +## 7. 禁止修改范围 + +除非某个 Root Cause 有直接证据要求,否则不得修改: + +- CM93 importer 数据库逻辑; +- MySQL 导入; +- Linux setup; +- 与 S-52 无关的 README; +- 与本任务无关的 production/importer 工具; +- NavSea; +- 任何与 CM95 S-52 portrayal 无关的模块。 + +--- + +## 8. 每阶段验证 + +每个阶段结束必须: + +1. 用临时 `/tmp` witness 精确验证本阶段 RC; +2. 检查语法/静态结构; +3. 运行现有相关非破坏性审计工具; +4. 对照 OpenCPN 固定源码; +5. 确认原工作区无关 SHA-256 未变化; +6. 记录哪些 branch 已具备重新判定条件; +7. 不得只凭函数实现“看起来正确”就关闭 FAIL。 + +阶段性提交允许,但必须显式 stage,仅包含本阶段任务文件。 + +建议提交信息: + +- 阶段 A:`feat: preserve ordered S-52 runtime rule chains` +- 阶段 B:`fix: align S-52 lookup and mariner semantics` +- 阶段 C:`feat: execute ordered S-52 runtime rules` +- 阶段 D:`feat: complete S-52 sounding lights and arc runtime` + +如实际文件耦合使阶段不能独立提交,可合并提交,但最终完成报告中必须按阶段列出修改。 + +--- + +## 9. 最终统一回归 + +所有代码根因处理完成后,必须重新执行 Code-First 等价审计。 + +至少重新验证: + +- OPENCPN_FLOW_EQUIVALENCE +- CSP_BRANCH_EQUIVALENCE +- NESTED_CSP_CALL_GRAPH +- INSTRUCTION_SEQUENCE_EQUIVALENCE +- RUNTIME_OPCODE_COVERAGE +- REAL_DATA_BRANCH_COVERAGE +- RESOURCE_DEPENDENCY_EQUIVALENCE +- MARINER_DEPENDENCY_EQUIVALENCE +- RENDER_ORDER_EQUIVALENCE +- RENDER_CHAIN_CONSERVATION + +必须重新生成 branch 状态统计。 + +禁止直接用: + +`120 - “预计减少值”` + +作为新 FAIL 数。 + +新 FAIL 数必须来自重新运行后的实际 branch audit。 + +--- + +## 10. Production / PBF 全量重建策略 + +只有在以下情况之一发生时,最终阶段才做 production rebuild: + +- ordered Rule IR 新字段进入 PBF; +- runtime facts contract 改变; +- presentation materialization 输出发生发布数据变化; +- style compiler 需要新的 PBF property; +- release Gate 需要验证新 contract。 + +若只改 Web runtime 且交付数据不变,则不得为了形式重复完整 production rebuild。 + +若确需全量: + +- 只在全部 26 RC 实施结束后集中执行一次; +- 完整 5064 PBF 扫描只做一次; +- 记录 decode error、branch signature、resource contract、presentation conservation。 + +--- + +## 11. RC-021 特殊规则 + +RC-021 不能按普通代码 Bug 处理。 + +必须为: + +`DC-OUT-ZERO-NORMAL` + +建立 branch-specific witness。 + +允许结果: + +### A. 当前代码正确 + +则: + +- 记录 witness; +- 将该 branch 从 FAIL 修正为合适状态; +- 说明原 v2 FAIL 为什么属于证据归因错误; +- 不修改无关产品代码。 + +### B. 找到真实缺陷 + +则: + +- 创建最小新增 Root Cause 标识; +- 记录机制; +- 在本任务中修复; +- witness 后再更新 branch 状态。 + +不得为了让剩余 FAIL 归零而直接改成 PASS。 + +--- + +## 12. 最终正式输出 + +本任务完成后生成: + +1. `docs/报告/CM95_S52_剩余26个根因统一修复报告_v1.md` +2. `build/audits/cm95_s52_remaining_26_root_cause_fix_v1.json` +3. 更新后的 Code-First 等价审计机器结果(使用现有同主题版本策略递增,不覆盖历史 v2) +4. 如审计标准本身因新 IR/contract 需要补充,则同主题版本递增;如果标准没变,不新建重复文档。 + +报告至少包含: + +- 起始 HEAD; +- 最终 HEAD; +- OpenCPN commit; +- 26 RC 逐项状态; +- RC-021 最终结论; +- 修改文件列表; +- 阶段 A/B/C/D 提交; +- 每阶段 witness; +- 是否改 PBF contract; +- 是否 production rebuild; +- 是否完整扫描 5064 PBF; +- 最终 PASS / FAIL / NOT_PROVEN 数; +- 仍未解决的 branch; +- 仍未解决的 Root Cause; +- Target Portrayal 最终状态。 + +--- + +## 13. 工作区保护 + +当前已有无关工作区修改。 + +开始前: + +1. `git status --short` +2. 对所有已有 modified/untracked 路径记录 SHA-256; +3. 排除本任务 MD 自身。 + +每阶段结束: + +- 重算 SHA-256; +- 无关文件必须完全一致。 + +最终提交前: + +- `git diff --cached --name-only` +- `git diff --cached --stat` +- `git diff --cached --check` + +严禁把已有无关工作区修改提交。 + +--- + +## 14. 完成条件 + +只有同时满足以下条件才允许报告“完成”: + +- [ ] 25 个已确认代码 Root Cause 都有实际修复或有明确阻塞证据; +- [ ] RC-021 已完成 branch-specific witness; +- [ ] 统一 ordered Rule Chain/IR 不再丢 mixed opcode; +- [ ] Point/Line/Area hazard runtime 不再只支持 Point; +- [ ] SOUNDG 不再以普通 text 代替 glyph chain; +- [ ] 多 LS 与 DOTT 可正确执行; +- [ ] UDWHAZ / DEPCNT / RESARE category/priority/SCAMIN side effect 与 upstream 对齐; +- [ ] runtime boundary mode 可重新选择; +- [ ] LIGHTS stateful label 与 height unit 对齐; +- [ ] CA scale-aware; +- [ ] resource missing 不导致 whole-chain 丢失; +- [ ] 重新运行 Code-First branch audit; +- [ ] 新 FAIL/PASS/NOT_PROVEN 数来自实际 audit; +- [ ] 原无关工作区 SHA-256 未变化; +- [ ] 所有任务相关 commit 已 push 到 `origin/main`。 + +如果仍有 FAIL: + +- 明确列 branch_id; +- 明确对应 RC; +- 明确为什么本任务不能安全解决; +- 不得声称 Target Portrayal PASS。 + +--- + +## 15. 最终 Git 收尾 + +最终阶段必须: + +1. 显式 stage 任务相关文件; +2. 不使用全量 add; +3. 检查 staged; +4. commit; +5. push `origin/main`; +6. 确认 `HEAD == origin/main`; +7. 最终回复给出: + - final HEAD; + - 各阶段 commit; + - push 状态; + - 26 RC 状态; + - 新 branch audit 统计; + - Target Portrayal 状态。