first commit

tools/model-diagnostics/ModelDiagnosticVerifier/LESSONS.md

@@ -0,0 +1,109 @@
+# ModelDiagnosticVerifier Lessons
+
+This file records diagnosis failures and the rule that prevents repeating them.
+
+## Failure 2026-06-19: `装配体2.SLDASM` was wrongly diagnosed as problem
+
+Context:
+
+- `装配体2.SLDASM` is the textbook `b` pass case for the tight-fit sleeve disassembly rule.
+- The correct diagnosis is `pass` because the sleeve has an exposed axial push face, matching image example `b`.
+
+Root cause:
+
+- `SectionBrepExtractor` produced the important feature in `SketchGraph.Dimensions`, not in `SketchGraph.Relations`.
+- The verifier consumed section relations but ignored dimension-derived candidates.
+- Therefore `external_push_access` stayed incomplete and the final decision became `problem`.
+
+Corrected behavior:
+
+- `SketchGraph.Dimensions` is now read.
+- `exposed_sleeve_end_height_candidate` with role `exposed_push_face_candidate` can be promoted to model evidence.
+- The promoted evidence satisfies the `b_external_push_access` image 2D structure template.
+
+Promotion rule currently used:
+
+```text
+exposed_sleeve_end_height_candidate
++ target sketch edge belongs to a sleeve
++ height is meaningful
+=> exposed_axial_push_face
+=> outside_accessible_force_path
+=> owned_by(push_face, sleeve_material)
+=> force_direction_parallel_to_axis(push_face, sleeve_axis)
+=> can_push_or_strike(outside, push_face)
+=> adjacent_to_outside(push_face, outside)
+```
+
+## Rules To Prevent Repeating This Failure
+
+### 1. A model-side 2D structure instance is not only relations
+
+- A model-side 2D structure instance is not only relations.
+- It must also consume dimensions, roles, anchors, and candidate annotations when they are produced by the extractor.
+- A candidate can be promoted to pass evidence only through an explicit promotion rule.
+
+### 2. Candidate is not failure
+
+Failure pattern:
+
+- Treating an incomplete pass template as absent too early makes the final rule report `problem`.
+- In mechanical diagnosis, candidate evidence should remain visible in the result so the missing bridge can be debugged.
+
+Correct rule:
+
+- Keep `candidate`, `found`, and `missing` separate.
+- Only final decision uses `found`; debugging output must preserve candidates and missing relations.
+
+### 3. Image template relations must map to model evidence names
+
+Failure pattern:
+
+- Image template requires `external_push_access`.
+- Model evidence may expose lower-level facts such as `exposed_sleeve_end_height_candidate`.
+- If there is no mapping, the verifier appears to "not understand" a correct model.
+
+Correct rule:
+
+- Every pass evidence type needs a model-evidence promotion path.
+- Do not rely only on literal relation name equality.
+
+### 4. Merge duplicate sources before diagnosis
+
+Failure pattern:
+
+- When section evidence and structural evidence are both loaded, the same component or scene can appear twice.
+- Duplicate scenes make reports noisy and can mask which evidence actually caused a decision.
+
+Correct rule:
+
+- Merge components by component id.
+- Merge scenes by `(sceneType, target, host)`.
+- Preserve stronger confidence and union of evidence labels.
+
+### 5. Do not let encoding damage classification
+
+Failure pattern:
+
+- Some older code had mojibake Chinese tokens for component classification.
+- Correct Chinese names such as `套筒` can be missed if only garbled tokens remain.
+
+Correct rule:
+
+- Keep component category inference robust:
+  - use normal Chinese terms
+  - use English aliases
+  - prefer metadata from extractors when available
+  - avoid depending on name classification when B-rep evidence already identifies owner/category
+
+## Development Checklist For Each New Fault Rule
+
+Before trusting a new rule, check all items below.
+
+- Image side has a semantic rule and at least one image 2D structure template for every pass/problem example.
+- Each pass template lists both structure relations and required model evidence.
+- Every required model evidence item has a documented extraction or promotion path.
+- The model verifier consumes all extractor layers used by that path: components, contacts, section edges, section relations, dimensions, regions, roles, and annotations.
+- The report shows `found`, `candidate`, and `missing` for both model evidence and 2D structure relations.
+- Known positive and known negative examples are tested before generalizing the rule.
+- A `problem` result is not accepted until the missing evidence chain has been inspected.