feat(smoke): every catalog row re-proves a falsifier on every smoke run

Falsifiers were proven once, by hand, in a PR body; nothing re-ran them, so a
check that lost its ability to fail stayed green forever.

Harness:
- catalog rows carry `falsifiers`: {"args": [...], "expect_exit": N}, or
  {"args": [...], "expect_sidecar_fail": true} where the post-exit sidecar
  check owns the contract (exit-pre-sidecar).
- run_example.py --expect-exit N / --expect-sidecar-fail; protocol.classify
  passes a falsifier only on exactly N (not 0, not another check's code, not
  1, never 77; a legal skip stays a skip).
- run_catalog.py runs each row's falsifiers after its happy path (all rows,
  all failures listed; --no-falsifiers for local iteration).
- summarize.py tables falsifiers separately; a falsifier PASS never counts
  toward the "at least one example passed" rule; any falsifier FAIL is red.
- check_smoke_catalog.py validates the schema (unknown keys rejected so a typo
  cannot silently disable a falsifier) and requires >=1 falsifier per row.
- blender-smoke.yml: weekly cron on 5.2 also runs the full showcase sweep
  (check_falsifier_targets.py --run); job timeout 45 -> 75 min.

Catalog: 142/142 rows seeded from README falsifier tables (78), exit-table rows
naming the flag (56) and 8 picked by hand. Four examples only had a
render-path visual falsify, so each gained a check-path flag reusing the same
defect: lightmap-uv-channel --overlap-islands (7), vertex-color-ao
--uniform-hemisphere (3), socket-attach-points --skip-mpi (3),
modular-kit-snap --seam-gap (5). tests/smoke/check_extension_template.py now
exits 3 (register) / 4 (unregister) and takes --skip-unregister (4). READMEs,
CLAUDE.md, CONTRIBUTING and docs/new-example-prompt.md document the field;
gallery pages regenerated for the four edited scripts.

Proof (local, .scratch/blender-5.2.1-windows-x64, 5.2.1 LTS):
- all 142 seeded falsifiers observed exiting exactly as declared (one, the
  sidecar falsifier, exits 0 and fails the sidecar check as declared).
- run_catalog on a 4-row sub-catalog: 4 happy PASS + 4 falsifier PASS.
- probe: anvil declared 8 instead of 9 -> "[FAIL] anvil [falsifier
  --skip-decimate]: falsifier exited 9, expected 8", exit 1.
- test_harness: 33 tests OK (exact-exit, exit-0, other-code, crash,
  forbidden codes, legal skip, sidecar falsifier, catalog wiring).

Closes #320

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/blender-smoke.yml

@@ -96,7 +96,7 @@ jobs:
     needs: resolve-matrix
     if: needs.resolve-matrix.result == 'success'
     runs-on: ubuntu-latest
-    timeout-minutes: 45
+    timeout-minutes: 75  # happy paths + one falsifier per catalog row (~2x the old run)
     strategy:
       fail-fast: false
       matrix:
@@ -346,6 +346,15 @@ jobs:
             --xvfb \
             --catalog tests/smoke/catalog.json
 
+      - name: Full showcase falsifier sweep (weekly, 5.2)
+        # The catalog runs one falsifier per row on every smoke run. The weekly
+        # cron also runs every falsifier in every showcase README table and
+        # asserts each lands on the exit it declares (~5 min).
+        if: ${{ github.event_name == 'schedule' && matrix.series == '5.2' }}
+        run: |
+          set -euo pipefail
+          python3 tests/check_falsifier_targets.py --run "$BLENDER"
+
       - name: Smoke summary
         if: ${{ always() && env.BLENDER != '' }}
         run: |

CLAUDE.md

@@ -176,8 +176,16 @@ The host runner is `tests/smoke/run_example.py`. Shipped examples are listed in
 - **Post-exit sidecar:** opt-in `--expect-sidecar PATH`. The example writes
   `$BDT_SMOKE_SIDECAR` (set by the runner). The harness asserts after Blender
   exits. Not a gallery still.
+- **Falsifiers in CI:** every catalog row carries `falsifiers`, at least one
+  `{"args": [...], "expect_exit": N}` (N not 0, 1 or 77) or, for a contract
+  the sidecar check owns, `{"args": [...], "expect_sidecar_fail": true}`.
+  `run_catalog.py` runs each after the row's happy path; it passes only on
+  exactly that exit. `tests/check_smoke_catalog.py` rejects a row without one
+  and any unknown key. The weekly cron also runs the full showcase sweep
+  (`tests/check_falsifier_targets.py --run`).
 - **Summary:** `tests/smoke/summarize.py` prints passed/skipped/failed. Zero
-  PASSes makes the job red even if every example skipped cleanly.
+  PASSes makes the job red even if every example skipped cleanly. Falsifier
+  runs are tabled separately and never count toward that PASS.
 
 ## Example-Run Process
 

CONTRIBUTING.md

@@ -114,7 +114,9 @@ budget conformance, never an API contract.
    exit-code table, and a falsifier that breaks one pipeline stage so a
    **named** budget fails.
 2. List the directory in `.cursor-plugin/plugin.json` `"showcase"` and add a
-   `tests/smoke/catalog.json` row. The runner takes opaque script paths.
+   `tests/smoke/catalog.json` row with at least one entry in `falsifiers`
+   (`{"args": ["--your-flag"], "expect_exit": N}`, matching the README
+   falsifier table). The runner takes opaque script paths.
 3. Add a `showcase/gallery.json` `pieces[]` entry, including an `alt`: one
    sentence saying what the still shows (the generator fails without it).
    Render a still, and run `python scripts/build_gallery.py`. Do not hand-edit `docs/gallery/` HTML.

docs/gallery/lightmap-uv-channel/index.html

@@ -72,20 +72,21 @@ <h1>Lightmap UV Channel</h1>
 <p><strong>Render as proof:</strong> the cart beside its enlarged UV1 atlas display — a slate face in a walnut frame on a plinth with a brass <code>UV1 LIGHTMAP</code> plate, a faint quarter grid marking the [0,1] square the bounds check holds — the Bed&#x27;s packed lightmap built from live UV data, so a change in the atlas moves the board geometry. The falsification variant (<code>--falsify</code>) translates the second-largest island onto the largest: a big emissive-red island visibly stacked over the atlas (15 SAT hits in the check probe). The render path also gates the asset itself through <code>examples/gallery_asset_quality.py</code> (naming, material variation, edge treatment — exit 11): 24 named parts, 5 materials, right-angle share 0.138. Wood, canvas and iron carry procedural grain, weave and pitting over Object coordinates; no check reads a material.</p>
 <h2 id="run">Run<a class="anchor" href="#run" aria-label="Link to this section">#</a></h2>
 <pre><code>blender --background --python lightmap_uv_channel.py --
+blender --background --python lightmap_uv_channel.py -- --overlap-islands   # falsifier: overlap scan reports the dragged island; exits 7
 blender --background --python lightmap_uv_channel.py -- --output atlas.png
 blender --background --python lightmap_uv_channel.py -- --falsify overlap.png</code></pre>
 <h2 id="exit-codes">Exit codes<a class="anchor" href="#exit-codes" aria-label="Link to this section">#</a></h2>
 <p>Per-script sequential checks. <code>9</code> is a valid check code; there is no rule against it. <code>10</code> is the shared framing helper. <code>11</code> is the shared asset-quality helper.</p>
-<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>UV layer names ≠ UV0 / UV1</td></tr><tr><td>4</td><td>UVMap / UV1 render/clone flags wrong after re-assert</td></tr><tr><td>5</td><td>Channel 0 (UV0) touched by the UV1 unwrap</td></tr><tr><td>6</td><td>UV1 loops outside <code>[0,1]</code></td></tr><tr><td>7</td><td>SAT overlap self-test failed, or UV1 triangle pairs overlap</td></tr><tr><td>8</td><td>Min island distance below margin</td></tr><tr><td>9</td><td>Part is not watertight</td></tr><tr><td>10</td><td>Gallery framing violation; also <code>--output</code> produced no file</td></tr><tr><td>11</td><td>Gallery asset-quality violation</td></tr></tbody></table></div>
-<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code> or <code>--falsify</code>.</p>
+<div class="table-wrap"><table><thead><tr><th scope="col">Code</th><th scope="col">Meaning</th></tr></thead><tbody><tr><td>0</td><td>Success</td></tr><tr><td>1</td><td>Uncaught exception (FATAL wrapper)</td></tr><tr><td>2</td><td>argparse / usage</td></tr><tr><td>3</td><td>UV layer names ≠ UV0 / UV1</td></tr><tr><td>4</td><td>UVMap / UV1 render/clone flags wrong after re-assert</td></tr><tr><td>5</td><td>Channel 0 (UV0) touched by the UV1 unwrap</td></tr><tr><td>6</td><td>UV1 loops outside <code>[0,1]</code></td></tr><tr><td>7</td><td>SAT overlap self-test failed, or UV1 triangle pairs overlap (<code>--overlap-islands</code> lands here)</td></tr><tr><td>8</td><td>Min island distance below margin</td></tr><tr><td>9</td><td>Part is not watertight</td></tr><tr><td>10</td><td>Gallery framing violation; also <code>--output</code> produced no file</td></tr><tr><td>11</td><td>Gallery asset-quality violation</td></tr></tbody></table></div>
+<p>The <code>blender-smoke</code> workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the <code>needs-5.1</code> PR label, or manual dispatch). Smoke does not pass <code>--output</code> or <code>--falsify</code>. Its catalog falsifier is <code>--overlap-islands</code> (expect exit 7): the same island drag as <code>--falsify</code>, applied before the SAT scan.</p>
     </section>
     <section class="detail-section src" id="source">
       <h2>Source</h2>
       <div class="src-meta">
         <code>examples/lightmap-uv-channel/lightmap_uv_channel.py</code>
-        <span>1019 lines &middot; <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/lightmap-uv-channel/lightmap_uv_channel.py">View on GitHub &rarr;</a></span>
+        <span>1030 lines &middot; <a href="https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/lightmap-uv-channel/lightmap_uv_channel.py">View on GitHub &rarr;</a></span>
       </div>
-      <div class="code" data-lines="1019">
+      <div class="code" data-lines="1030">
 <pre class="gutter" aria-hidden="true">1
 2
 3
@@ -1104,7 +1105,18 @@ <h2>Source</h2>
 1016
 1017
 1018
-1019</pre><pre class="code-lines"><span class="s">&quot;&quot;&quot;Lightmap UV channel — the second UV layer engines need for baked lighting.
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
+1030</pre><pre class="code-lines"><span class="s">&quot;&quot;&quot;Lightmap UV channel — the second UV layer engines need for baked lighting.
 
 Witnesses the two-channel UV contract a bake pipeline depends on, on an
 asset built to be reused (a market cart: bed, axle, two wheels, four posts,
@@ -1680,7 +1692,7 @@ <h2>Source</h2>
 <span class="c"># Check</span>
 <span class="c"># ---------------------------------------------------------------------------</span>
 
-<span class="k">def</span> check():
+<span class="k">def</span> check(overlap=<span class="k">False</span>):
     meshes = build_cart_meshes()
     fails = []
 
@@ -1721,6 +1733,8 @@ <h2>Source</h2>
         ob = bpy.data.objects.new(me.name, me)
         bpy.context.collection.objects.link(ob)
         author_uv1(ob)
+        <span class="k">if</span> overlap <span class="k">and</span> suffix == <span class="s">&quot;Bed&quot;</span>:
+            drag_second_island(me)  <span class="c"># falsifier: the SAT scan must report it</span>
 
         <span class="c"># re-fetch by name after CustomData-reallocating ops (see header)</span>
         layers = me.uv_layers
@@ -1881,6 +1895,23 @@ <h2>Source</h2>
     <span class="k">return</span> floor, wall
 
 
+<span class="k">def</span> drag_second_island(me):
+    <span class="s">&quot;&quot;&quot;Translate the mesh&#x27;s second-largest UV1 face onto the largest one&#x27;s
+    anchor, shape intact. Shared by --overlap-islands (check path, exit 7)
+    and --falsify (render path). Returns the dragged polygon index.&quot;&quot;&quot;</span>
+    layer = me.uv_layers[LAYER1]
+    polys = sorted(me.polygons, key=<span class="k">lambda</span> p: p.area, reverse=<span class="k">True</span>)
+    big, second = polys[<span class="n">0</span>], polys[<span class="n">1</span>]
+    anchor = tuple(layer.data[big.loop_indices[<span class="n">0</span>]].uv)
+    first = second.loop_indices[<span class="n">0</span>]
+    du = (anchor[<span class="n">0</span>] - layer.data[first].uv[<span class="n">0</span>],
+          anchor[<span class="n">1</span>] - layer.data[first].uv[<span class="n">1</span>])
+    <span class="k">for</span> li <span class="k">in</span> second.loop_indices:
+        u, v = layer.data[li].uv
+        layer.data[li].uv = (u + du[<span class="n">0</span>], v + du[<span class="n">1</span>])
+    <span class="k">return</span> second.index
+
+
 <span class="k">def</span> render_still(path, engine, falsify=<span class="k">False</span>):
     <span class="s">&quot;&quot;&quot;The cart beside its UV1 atlas board — island polygons built from the
     LIVE packed UVs, so a change in the atlas moves the board. Falsified:
@@ -1931,18 +1962,7 @@ <h2>Source</h2>
     <span class="c"># emissive red on the board (tiny-strip overlaps would not read)</span>
     dragged = set()
     <span class="k">if</span> falsify:
-        bed = meshes[<span class="s">&quot;Bed&quot;</span>]
-        layer = bed.uv_layers[LAYER1]
-        polys = sorted(bed.polygons, key=<span class="k">lambda</span> p: p.area, reverse=<span class="k">True</span>)
-        big, second = polys[<span class="n">0</span>], polys[<span class="n">1</span>]
-        anchor = tuple(layer.data[big.loop_indices[<span class="n">0</span>]].uv)
-        dragged.add(second.index)
-        first = second.loop_indices[<span class="n">0</span>]
-        du = (anchor[<span class="n">0</span>] - layer.data[first].uv[<span class="n">0</span>],
-              anchor[<span class="n">1</span>] - layer.data[first].uv[<span class="n">1</span>])
-        <span class="k">for</span> li <span class="k">in</span> second.loop_indices:
-            u, v = layer.data[li].uv
-            layer.data[li].uv = (u + du[<span class="n">0</span>], v + du[<span class="n">1</span>])
+        dragged.add(drag_second_island(meshes[<span class="s">&quot;Bed&quot;</span>]))
 
     <span class="c"># atlas board: the Bed&#x27;s live UV1 as flat island polygons mapped onto the</span>
     <span class="c"># board face — a change in the packed atlas moves the board geometry</span>
@@ -2087,6 +2107,9 @@ <h2>Source</h2>
     argv = sys.argv[sys.argv.index(<span class="s">&quot;--&quot;</span>) + <span class="n">1</span>:] <span class="k">if</span> <span class="s">&quot;--&quot;</span> <span class="k">in</span> sys.argv <span class="k">else</span> []
     p = argparse.ArgumentParser()
     p.add_argument(<span class="s">&quot;--output&quot;</span>, default=<span class="k">None</span>, help=<span class="s">&quot;optional: render a still PNG here&quot;</span>)
+    p.add_argument(<span class="s">&quot;--overlap-islands&quot;</span>, action=<span class="s">&quot;store_true&quot;</span>,
+                   help=<span class="s">&quot;falsifier: drag the Bed&#x27;s second-largest UV1 island onto &quot;</span>
+                        <span class="s">&quot;the largest before the overlap scan (exit 7)&quot;</span>)
     p.add_argument(<span class="s">&quot;--falsify&quot;</span>, default=<span class="k">None</span>,
                    help=<span class="s">&quot;optional: render the overlapping-atlas variant here&quot;</span>)
     p.add_argument(<span class="s">&quot;--engine&quot;</span>, default=<span class="s">&quot;eevee&quot;</span>, choices=(<span class="s">&quot;eevee&quot;</span>, <span class="s">&quot;cycles&quot;</span>),
@@ -2095,7 +2118,7 @@ <h2>Source</h2>
 
     print(<span class="s">f&quot;</span><span class="s">binary version: </span>{bpy.app.version}<span class="s"> (</span>{bpy.app.version_string}<span class="s">)</span><span class="s">&quot;</span>)
     bpy.ops.wm.read_factory_settings(use_empty=<span class="k">True</span>)
-    code = check()
+    code = check(overlap=args.overlap_islands)
     <span class="k">if</span> code:
         <span class="k">return</span> code