Merge branch 'worktree-watershed-plateaux'

docs/segmentation.md

@@ -303,6 +303,30 @@ up an artefact of the flow pass is fragile. The principled fix is a **lower-comp
 extra pass giving plateau pixels a gradient toward their nearest descending exit. Standard, cheap,
 and worth doing before the corpus work.
 
+*Attempted, and parked.* The pass exists — `plateau_init` seeds every pixel
+that has a strictly lower neighbour, `plateau_step` carries a breadth-first
+distance inward within a level set, and `flow` takes that distance as the
+second key of a lexicographic tie-break. Bindings, ping-pong and dispatch were
+all checked and are right. It is nonetheless a **measured no-op**: with a test
+comparing the labelling at one iteration against sixty-four, *zero* of 9216
+pixels change basin. That test is committed and ignored rather than deleted,
+because it is the thing that turned "we think this works" into a fact.
+
+Three explanations were tried and none of them was it. Exact float equality is
+certainly wrong — a gradient computed from 8-bit samples is never exactly
+equal across a region the eye calls flat — and a `LEVEL_EPS` tolerance now
+replaces `==` and `<` in all three comparisons; it did not change the outcome.
+Nor did the test image: a flat disc, a terraced disc and a constant-slope ramp
+all behave identically. Worth knowing for whoever picks this up: on a
+gradient-*magnitude* watershed, every flat region of the picture sits at
+gradient zero, which is the global minimum, and a plateau with no descending
+exit is a minimum — one basin by definition, with nothing for lower-completion
+to resolve. The plateaux that do have an exit are regions of constant non-zero
+gradient, which are rarer in a photograph than F1's phrasing suggests.
+
+`plateau_iterations` therefore defaults to **0**. The pass is off, costs
+nothing, and F1 stands open.
+
 **F2 — `cut_to(N)` is a visualisation, not the interaction.** A global cut by region count spends its
 budget wherever the saddles happen to be densest: at blur 5 the soft-edged disc's interior held a
 cluster of near-equal saddles and ate the budget, fragmenting at a level where everything else was