Re-record 127 stale baselines and delete the tolerance shield

.okf/build/index.md

@@ -1,7 +1,7 @@
 # Build & Test
 
 * [Hugo build pipeline](hugo-build.md) - bin/hugo-build with the 8 course validators; also the PurgeCSS cold-start race and the minified-unquoted-attribute audit-tool trap
-* [Test gates](test-gates.md) - the local suites, when each is a commit blocker, the 0.0001 default tolerance, the SECTION_CONFIGS shield, why a green run never refreshes a baseline, and why below-fold content is invisible at any tolerance, bin/record-baselines for accepting only the baselines you meant to move, and why a deleted source file still serves from every local _dest/ tree, plus the NULL CHANGE - a diff that passes every gate and alters nothing - and what `okf_validate` actually guards (shape, not truth; error-only conformance) with the two-spec trap
+* [Test gates](test-gates.md) - the local suites, when each is a commit blocker, the 0.0001 default tolerance, why the SECTION_CONFIGS shield was deleted and what measuring it cost, why a green run never refreshes a baseline, and why below-fold content is invisible at any tolerance, bin/record-baselines for accepting only the baselines you meant to move, and why a deleted source file still serves from every local _dest/ tree, plus the NULL CHANGE - a diff that passes every gate and alters nothing - and what `okf_validate` actually guards (shape, not truth; error-only conformance) with the two-spec trap
 * [CI gates](ci-gates.md) - what GitHub Actions enforces: build, unit, path-scoped link check (visual regression is report-only), and what gates a PR never sees
 * [Template PDFs](pdf-templates.md) - regenerating the downloadable course PDFs
 * [Classes only on &lt;th&gt; get purged](hugo-stats-th-classes.md) - Hugo 0.165 writeStats records no class attrs on `<th>`, so PurgeCSS deletes those rules from the production bundle while dev builds look fine and the visual gate stays green; also two sibling false-greens on the /next/ rail (site-scripts in a landing baseof, computed `resources.Get` paths defeating the orphan guard)

.okf/build/test-gates.md

@@ -88,32 +88,39 @@ genuinely new features**. This is the policy for what you ACCEPT, distinct from
 the mechanical default that decides whether the suite even reports a diff.
 
 That default is **0.0001** (`DEFAULT_SCREENSHOT_CONFIG`,
-`test/support/screenshot_section_config.rb:29`), lowered from 0.02 on 2026-08-21.
+`test/application_system_test_case.rb`), lowered from 0.02 on 2026-08-21.
 Both halves still hold: the accept-policy is unchanged, and individual calls
 may still pin their own tolerance (~30 do, mostly 0.03 - e.g.
 `test/system/blog_special_content_test.rb:136`), which the default never
 overrides. What changed is the floor for calls that pin NOTHING.
 
-**`SECTION_CONFIGS` is now a deliberate temporary shield, not configuration.**
-Its 7 keys all held 0.02, which equalled the old default - so the table was a
-silent no-op for as long as it existed. Lowering the default made it
-load-bearing: it now holds ~22 section screenshots at the OLD tolerance while
-their drift is unmeasured. It is kept ON PURPOSE and deleted once those are
-measured and re-recorded. Its keys match the tail after `/_`, which is easy to
-misread: `services/_technologies` hits the `technologies` key (0.02), while
-`services/_testimonials-header` does NOT hit `testimonials` and gets the
-default - one string, not a prefix. Both the table and the rule live in
-`test/support/screenshot_section_config.rb`, apart from
-`ApplicationSystemTestCase` so they can be unit-tested without booting Hugo,
-Capybara, or that file's dirty-fixtures `abort`; the near-miss above is pinned
-in `test/unit/screenshot_section_config_test.rb`.
+**`SECTION_CONFIGS` is GONE (deleted 2026-08-21), and its exit condition was
+met by measurement, not by judgement.** It existed for one day as a temporary
+shield holding ~22 section screenshots at the old 0.02 while their drift was
+unmeasured. Measured on the full macOS system suite, both sides in the same
+environment: **shield in place 48 failing screenshots, shield emptied 50** -
+a cost of exactly **+2**, `desktop/services/_use-cases` (0.017498) and
+`desktop/services/_technologies` (0.013838). Both were then classified and
+re-recorded, so the table was deleted along with `screenshot_config_for`,
+`extract_section_key`, `test/support/screenshot_section_config.rb` and its
+unit test. `DEFAULT_SCREENSHOT_CONFIG` survives as a plain constant on
+`ApplicationSystemTestCase`; there is no per-section tolerance table any more,
+and a call that needs slack pins its own tolerance.
+
+The deleted table's keys matched the tail after `/_`, which mattered because
+it was easy to misread: `services/_technologies` hit the `technologies` key
+(0.02) while `services/_testimonials-header` did NOT hit `testimonials` and
+got the default - one string, not a prefix. That subtlety is only recorded
+here now; nothing in the tree implements it.
 
 Why 0.0001: on a 1920x1080 capture, 0.02 means ~41,472 pixels must differ
 before the assertion fails. A one-cell copy edit measures 0.0004 (844 px), so
 the gate was blind to it by 50x - and passed, which is worse than failing
 (see the fossilization bullet below). Measured run-to-run noise on a static
-page is 0.0, so the floor only has to clear zero; 0.0001 (~207 px) fails that
-copy edit and goes green again when it is reverted. The noise claim is
+page is ~1e-6, not 0 (three runs of `services/_technologies`: 0.013838252,
+0.013838252, 0.013837770 - about 2 px of 2,073,600), so the floor has to clear
+that; 0.0001 (~207 px) sits 100x above it, fails that copy edit, and goes green
+again when it is reverted. The noise claim is
 checkable without re-running the copy edit: two independent runs of the same
 test reported difference_levels identical to 16 decimal places (0.6893909143518518
 for `services/_footer` every time), and 2 of the 7 screenshots stayed GREEN at
@@ -141,8 +148,28 @@ shield deletion, and they are exactly the two whose names happen to hit a
 SECTION_CONFIGS key. The two changes look like one line and one dead constant,
 but they move different screenshots.
 
-All of these are the #540 dark-surface recolour: real stale-baseline
-detections, not machine drift, and not caused by the tolerance change.
+All are real stale-baseline detections, not machine drift, and none is caused
+by the tolerance change.
+
+**Correction (2026-08-21, from the re-record that measured them):** an earlier
+version of this section attributed all five to the #540 dark-surface recolour.
+Only the two big ones are. `_footer` and `_cta-contact_us` are #540
+(`rgb(0,0,0)` -> `rgb(20,17,15)` is 97-99% of their changed pixels). The three
+small ones - `_testimonials-header`, `_use-cases`, `_technologies` - contain
+**0.13% or less** of that transition. They are a **1-pixel vertical offset**
+from #528's eyebrow consolidation, which touched `services-critical.css` and
+`content-block.css` and re-recorded only the two sections that exceeded 0.02;
+everything below the eyebrow on /services/ shifted 1px, passed under the old
+default, and fossilized. Measured, not inferred: realigning baseline to
+candidate by one pixel drops the residual to **exactly 0.0000 in several
+bands** and collapses the non-blend suspect count by orders of magnitude
+(`blog/index/_pagination`: 32,652 px at dy=0 -> 106 at dy=-1). It does NOT
+reach zero page-wide - a sub-pixel shift re-rasterizes glyphs rather than
+translating them, so `services/_use-cases` still differs in 22,895 px after
+the best realignment. Content is identical on inspection; position moved. The
+lesson is the one this file already teaches - a plausible cause that matches
+the loudest diffs will happily absorb the quiet ones that have a different
+cause entirely.
 
 # Below the fold is invisible to the gate at ANY tolerance
 
@@ -208,6 +235,24 @@ Minitest under `test/`, driven by `Rakefile` (`Rake::TestTask`).
   frontmatter is set, and adds it to the ratchet. The script self-reports slack
   (`post-visuals: floor is loose, lower FLOOR to N`) - obey it: `FLOOR` dropped
   78 -> 72 on 2026-08-20 on the script's own prompt.
+- **Screen a CI re-record with the gate's own instrument** (2026-08-21).
+  `FORCE_SCREENSHOT_UPDATE` rewrites every baseline, so a CI record commit is
+  much larger than the real change set - the 2026-08-21 Linux record touched
+  83 files. Do not screen it by eye or by file size. Compute the libvips
+  **dE00 fraction above `perceptual_threshold = 2.0`** (what
+  `difference_level` actually measures) for each file and compare against the
+  0.0001 default: files above it would FAIL the gate, so the rewrite is real
+  and dropping them leaves CI red; files at exactly 0 are encoder churn and
+  should be reverted. That split was 77 keep / 6 drop, and it needs no
+  judgement call.
+
+  **Neither OS baseline set is a subset of the other**, so never infer one
+  from the other. Earlier PRs re-recorded only the OS they ran on: #528
+  committed `macos/mobile/services.png` and left `linux/mobile/services.png`
+  stale (still carrying the shift), while `linux/.../inline_style_post` was
+  already current from a post-#520 CI record when macOS was 25% stale. The
+  Linux record here was legitimately BROADER than the macOS one (77 vs 50).
+
 - **`FORCE_SCREENSHOT_UPDATE=1` re-records EVERYTHING** (2026-08-14). On
   `bin/dtest` it also disables the `git checkout -- .../linux` guard that
   normally discards sub-tolerance Rosetta drift, so a run rewrites all 45
@@ -271,7 +316,7 @@ Minitest under `test/`, driven by `Rakefile` (`Rake::TestTask`).
   record: 356 runs, 6329 assertions, 0 failures (run 32347402944). Note the
   governing tolerance for these is **0.03**, set per-call at
   `test/system/blog_special_content_test.rb:136` - NOT the
-  `DEFAULT_SCREENSHOT_CONFIG` in `test/support/screenshot_section_config.rb:29`,
+  `DEFAULT_SCREENSHOT_CONFIG` in `test/application_system_test_case.rb`,
   which only applies when a call omits an explicit tolerance.
 
 - **Content-only diffs skip the visual suites entirely** (Paul 2026-07-31).

.okf/log.md

@@ -66,6 +66,88 @@ set BASE_URL or the browser silently loads the LIVE site's CSS. The shared
 mobile table-clip defect (all three pilots, column 2 off-edge without
 affordance) is deliberately deferred to the winner's graft round - fixing it
 three times buys nothing.
+## 2026-08-21 - the macOS suite is green again: 50 baselines re-recorded, and the shield deleted on a measurement
+
+The macOS visual suite had been red on master since #540. It is green now:
+**79 runs, 218 assertions, 0 failures; 134 screenshots compared, no failures.**
+
+**What was stale, and why.** Two mechanics compose into fossilization: a
+capture overwrites the baseline PNG, then a PASSING run restores the git-HEAD
+image back over it. So any change small enough to pass leaves the baseline
+showing the OLD render, permanently. #540 was large enough to FAIL and simply
+was not re-recorded; #520 and #528 were not, and had been accumulating quietly
+under the old 0.02 default. Lowering the default to 0.0001 (#560) is what
+finally surfaced the quiet ones.
+
+**50 baselines re-recorded, every one classified before it was accepted** -
+by baseline-vs-candidate pixel transitions, never by difference_level:
+
+| n | class | evidence |
+|---|---|---|
+| 42 | #540 dark-surface recolour | `rgb(0,0,0)` -> `rgb(20,17,15)` is 94-100% of changed px |
+| 3 | #520 `description` backfill | template renders it as a grey lead; rendered text matches the frontmatter string verbatim |
+| 2 | #552 course module eyebrow | ruby eyebrow above the H1 shifts the page down |
+| 3 | #528 eyebrow consolidation | 1px vertical offset; realigning by one pixel gives residual **exactly 0.0000** in several bands |
+
+The DOMINANT cause of every file is explained, so nothing was withheld as a
+suspected regression. Independent review (opus, own instruments, exact
+transition count over all 50) reproduced the 42/3/2/3 split and agreed
+file-by-file. It also found what the classification does not name: three files
+carry a SECONDARY 1px displacement on top of the recolour, and two mobile files
+carry #540's sibling `--ruby-on-ink` token change. All position-or-token only,
+content identical - which is why no baseline is wrong, and why "zero
+unexplained" is the wrong phrase for "every dominant cause identified".
+
+**`SECTION_CONFIGS` is deleted, on a measurement rather than a judgement.**
+Its stated exit condition was "delete once the shielded screenshots are
+measured and re-recorded", so it was measured both ways in the same
+environment: **shield in place 48 failing screenshots, shield emptied 50**.
+Cost of deletion: **+2**, both on /services/, both the #528 1px offset, both
+re-recorded. Gone with it: `screenshot_config_for`, `extract_section_key`,
+`test/support/screenshot_section_config.rb` and its unit test.
+`DEFAULT_SCREENSHOT_CONFIG` survives as a plain constant on
+`ApplicationSystemTestCase`.
+
+**A correction to this bundle, found by doing the work.** test-gates said all
+five failing `/services/` screenshots were the #540 recolour. Only two are;
+the three small ones carry **0.13% or less** of the black->ink transition and
+are #528's 1px shift instead. A plausible cause that fits the loudest diffs
+will absorb the quiet ones that have a different cause - which is why the
+transition histogram, not the difference_level, is the classifier.
+
+**And one instrument error, caught by this bundle's own rule.** The first
+transition script loaded each baseline from a reused temp filename; libvips
+caches operations by filename, so runs 2..n silently re-compared image 1. It
+reported `services/_footer`'s baseline as a pure-black frame - a dramatic,
+completely false finding. A brightness audit over all 155 tracked macOS
+baselines refuted it in one pass (darkest mean 69/255, none below 1.0). The
+rewritten script carries a permanent control: an unchanged baseline
+(`desktop/vibe_code_rescue`) must report exactly 0 changed pixels, and does.
+"Test the instrument against a case where the answer is known" earned its
+keep here.
+
+**The Linux leg, and a screening rule worth reusing.** Recorded through CI on
+the branch (`gh workflow run test.yml --ref <branch> -f screenshots=true -f
+update-baselines=true`), never locally - local ARM Docker plants false drift.
+`FORCE_SCREENSHOT_UPDATE` rewrites EVERYTHING, so the bot commit touched 83
+files and had to be screened. Screen it with **the gate's own instrument**,
+not by eye or by file size: compute the libvips dE00 fraction above
+`perceptual_threshold = 2.0` for each file and compare it to the 0.0001
+default. That splits 83 into **77 keep** (would fail the gate, so the rewrite
+is real) and **6 drop** (difference_level exactly 0 - pure encoder churn).
+
+The Linux set being BROADER than the macOS one (77 vs 50) looks wrong and is
+not: earlier PRs re-recorded only one OS. #528 committed
+`macos/mobile/services.png` and left its `linux/` twin stale, so that file
+still carries a visible #528 shift on Linux; conversely
+`linux/.../inline_style_post` barely moves because Linux was re-recorded after
+#520 while macOS was 25% stale. **Neither OS baseline set is a subset of the
+other** - do not reason about one from the other.
+
+Run-to-run noise, measured across three runs of `services/_technologies`:
+0.013838252, 0.013838252, 0.013837770 - about **2 px of 2,073,600** (~1e-6),
+comfortably under the 0.0001 floor. The earlier claim that noise is exactly
+0.0 was very nearly right and is now stated as what was actually observed.
 
 ## 2026-08-21 - register pilot B, and the two ways a second pilot breaks the first pilot's gates
 

docs/20-29-testing-qa/20.10-test-coverage-gap-analysis-reference.md

@@ -427,8 +427,10 @@ with any content ratchet - assert structure, per 20.05.
    test holding the same list.
 4. **FIXED 2026-08-21 — screenshot tolerance was 2%**, so a four-word link
    change (~0.24% of frame) passed and never re-recorded the baseline. Default
-   is now 0.0001 (`test/support/screenshot_section_config.rb`); mechanism,
-   remaining blind axes, and the section-shield are in `.okf/build/test-gates.md`.
+   is now 0.0001 (`test/application_system_test_case.rb`); mechanism and the
+   remaining blind axes are in `.okf/build/test-gates.md`. The section-tolerance
+   shield that briefly held ~22 screenshots at the old default is gone - its
+   drift was measured and re-recorded on 2026-08-21.
 5. **`content/clients/**` is not covered** by the marketing ratchet and still
    carries "to the next level" in two case-study excerpts. The exclusion is
    commented in the test rather than implied.

test/application_system_test_case.rb

@@ -10,7 +10,6 @@
 require "support/setup_capybara"
 require "support/setup_snap_diff"
 require "support/hugo_helpers"
-require "support/screenshot_section_config"
 
 # Every system-test run REWRITES the committed baseline PNGs in place
 # (snap_diff design: working tree = candidate, git HEAD = baseline). Starting
@@ -74,7 +73,13 @@ class ApplicationSystemTestCase < Minitest::Test
   include CapybaraScreenshotDiff::Minitest::Assertions
   include NavigationHelpers
 
-  include ScreenshotSectionConfig
+  # Floor for calls that pin no tolerance of their own. 0.02 let ~41,472 pixels
+  # of a 1920x1080 frame change before failing, so real diffs passed green and
+  # the baseline fossilized. Measured run-to-run noise is ~1e-6 (three runs of
+  # services/_technologies: 0.013838252 twice, then 0.013837770 - about 2 px of
+  # 2,073,600), so the floor only has to clear that: 0.0001 is ~207 px. Calls
+  # needing real slack (font-swap, animation) still pin their own tolerance.
+  DEFAULT_SCREENSHOT_CONFIG = {tolerance: 0.0001}.freeze
 
   private
 
@@ -96,8 +101,7 @@ def assert_screenshot(name, **options)
     # resolves instantly once fonts are cached, so warm sessions pay ~0.
     page.evaluate_async_script("var done = arguments[0]; document.fonts.ready.then(function() { done(true) })")
 
-    section_config = screenshot_config_for(name)
-    final_options = section_config.merge(options)
+    final_options = DEFAULT_SCREENSHOT_CONFIG.merge(options)
 
     # skip_area CSS selectors resolve via Capybara `all(sel, visible: true)`
     # INSIDE the gem, which waits default_max_wait_time (5s) for EVERY selector