port: sweep instructions above descriptions -- the silent class is clean, two loud hits

Their sharpening: a stale instruction manufactures a false confirmation, strictly
worse than a stale description that merely misleads. Applied to my instruction
surface, the documented invocations in tool and script headers.

All fifteen distinct flags across those examples are parsed, so nothing in my
headers can produce their failure mode by being inert. But 'parsed' is a proxy and
its gap is known -- --shots parses and does nothing on the --boot path -- so I ran
two documented examples end to end rather than trusting the grep, and both produce
a 1280x720 frame.

Two hits, both loud rather than silent: 11 references to tools/verify-capture and
tools/verify-screen, paths that do not exist since the tools are under tools/port/
(fixed in 4 files); and check-all claiming eleven tools where there are fourteen
(now states both so the sentence dates itself).

The distinction worth recording: mine fail loudly, theirs failed silently. A wrong
path announces itself; an inert environment variable returns a clean wrong result.
Both are stale instructions and only one manufactures evidence.

Honest limit: I tested the flag surface plus two examples end to end, not all
thirteen documented invocations -- the --boot ones take 156 s each. That is a
judgement about cost, not a claim of coverage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N7FiFFFwbvG2uxdcEh8HyF

docs/port/DECISIONS.md

@@ -9,7 +9,7 @@ dies, which is what this file is for.
 
 <!-- INDEX: generated by tools/port/index-decisions -- do not hand-edit -->
 
-212 sections. Search this before re-deriving anything.
+213 sections. Search this before re-deriving anything.
 
 * [P0 — the exporter, 2026-08-28](#p0--the-exporter-2026-08-28)
 * [P1 — Godot draws the screen, 2026-08-28](#p1--godot-draws-the-screen-2026-08-28)
@@ -223,6 +223,7 @@ dies, which is what this file is for.
 * [Their sharpened tell, applied to my tree: two descriptions the code below had already refuted](#their-sharpened-tell-applied-to-my-tree-two-descriptions-the-code-below-had-already-refuted)
 * [The grep found two more — and the reason is my correction *habit*, not my attention](#the-grep-found-two-more--and-the-reason-is-my-correction-habit-not-my-attention)
 * [Auditing headings — and my own index was amplifying the withdrawn ones](#auditing-headings--and-my-own-index-was-amplifying-the-withdrawn-ones)
+* [Ranking instructions above descriptions — swept, and the worst class is clean](#ranking-instructions-above-descriptions--swept-and-the-worst-class-is-clean)
 
 <!-- /INDEX -->
 ## P0 — the exporter, 2026-08-28
@@ -397,7 +398,7 @@ human sees the screen — but it is not what the numbers come from.
 
 ## P1 gate — the diff, and what it found
 
-`tools/verify-screen` renders every screen in the manifest both ways and reports
+`tools/port/verify-screen` renders every screen in the manifest both ways and reports
 the largest per-channel difference anywhere in the frame. Both renderers are held
 to the same inputs: the reference CLI built by `build-reference-cli` from the
 revision the exporter is **pinned** to (not `/reborn/target/`, which is a live
@@ -984,7 +985,7 @@ The correction comes from the human, via the RE agent, in their words: Reborn
 various files. It may very well be wrong." **The oracle is the Xenia Canary
 capture and the game.**
 
-So `tools/verify-screen` is a **consistency check between two decoders that
+So `tools/port/verify-screen` is a **consistency check between two decoders that
 share their assumptions**, and a regression detector. It is not a correctness
 check, and agreement in it is not evidence of correctness.
 
@@ -1008,7 +1009,7 @@ capture and catchable by nothing else:
 
 ### What changes
 
-* `tools/verify-screen` says all of this in its own header, calls the CLI the
+* `tools/port/verify-screen` says all of this in its own header, calls the CLI the
   **comparison** renderer, and a `DIFFERS` row now means "we moved apart, find
   out which of us moved" rather than "the port is wrong".
 * The correctness question moves to the captures. The RE agent has committed
@@ -3889,7 +3890,7 @@ the experiment are the same operation rather than two implementations that agree
 
 ## The correctness harness the docs promised for eight milestones did not exist
 
-`tools/port/verify-screen`, line 20, since P1: *"Use `tools/verify-capture` for
+`tools/port/verify-screen`, line 20, since P1: *"Use `tools/port/verify-capture` for
 the correctness question."* **There was no such file.** The port has had a harness
 comparing itself to `sylpheed-cli` — two renderers sharing its assumptions — and
 none comparing it to the game, while its own documentation said otherwise.
@@ -8756,7 +8757,7 @@ the wrong field name, and a fair metric pointed at the wrong frame.
 
 ### Wired so it cannot recur
 
-`tools/verify-capture` takes a fifth per-row field, a capture crop, because this
+`tools/port/verify-capture` takes a fifth per-row field, a capture crop, because this
 capture is a full 1280×720 display frame with the surface at +0+45 while every
 other capture in that directory is pre-cropped to 1279×675 — comparing it whole
 would score the port against a 45 px shift. With it, `title_jp` reads **RMSE
@@ -11233,3 +11234,43 @@ was making three withdrawn claims findable first.
 own framing: **"record" and "statement" want opposite orders, and a single block
 cannot be both without deciding which one leads.** That is more precise than
 calling the habit wrong — it isn't wrong, it is under-specified about ordering.
+
+## Ranking instructions above descriptions — swept, and the worst class is clean
+
+Their sharpening: **a stale instruction manufactures a false confirmation**, which
+is strictly worse than a stale description that merely misleads. Their example is
+a doc naming an environment variable removed with the record-layout fix — a reader
+sets something inert, gets default behaviour, and concludes the two readings
+agree. So: rank instructions above descriptions when sweeping.
+
+Applied to my tree, the instruction surface is the documented invocations in the
+tool and script headers. Fifteen distinct flags appear across them.
+
+✅ **All fifteen are parsed** — no silently ignored flag, so nothing in my headers
+can produce their failure mode by being inert.
+
+⚠️ **But "parsed" is a proxy and I know its gap**: `--shots` parses and does
+**nothing** on the `--boot` path, which I found two iterations ago. Parsing is not
+working. So I ran two documented examples end to end rather than trusting the
+grep — `--screen=main_menu --pose=rest --capture` and
+`--screen=title --overlay=press_start --time=4` — and both produce a 1280×720
+frame. (`--boot --shots` is not a documented combination, which is why the gap has
+not bitten a reader.)
+
+### Two hits, both of the *loud* kind
+
+| | |
+|---|---|
+| **11 references** to `tools/verify-capture` / `tools/verify-screen` | those paths do not exist; the tools are under `tools/port/`. Fixed in 4 files. |
+| `check-all`: *"There are **eleven** tools under `tools/port/`"* | there are **fourteen**. Now states both, so the sentence dates itself. |
+
+📌 **The distinction worth recording: mine fail loudly, theirs failed silently.** A
+wrong path errors out and announces itself; an inert environment variable returns
+a clean, wrong result. **Both are stale instructions and only one manufactures
+evidence.** That is the ranking their sharpening earns, and it means my two hits —
+while real — are the cheap kind.
+
+⚠️ And the honest limit on this sweep: I tested the **flag surface**, plus two
+examples end to end. I did not run all thirteen documented invocations. The `--boot`
+ones take 156 s each and I judged the flag-parse check plus two spot runs
+sufficient; that is a judgement about cost, not a claim of coverage.

port/scripts/screen_view.gd

@@ -7,7 +7,7 @@
 # authored and applied in exactly one place.
 #
 # REST reproduces what the export's `rest` field says, which is what
-# `sylpheed-cli screen render` draws. It is kept so `tools/verify-screen` can
+# `sylpheed-cli screen render` draws. It is kept so `tools/port/verify-screen` can
 # hold both renderers to the same assumption. The two modes DISAGREE on six
 # elements in this export, and the running game sides with the timeline -- see
 # `docs/DECISIONS.md`.

tools/port/check-all

@@ -3,7 +3,9 @@
 #
 #   tools/port/check-all
 #
-# There are eleven tools under `tools/port/` and nothing ran them together, so
+# There are fourteen tools under `tools/port/` (eleven when this was written --
+# the count is stated because it dates the sentence) and nothing ran them
+# together, so
 # each had to be remembered individually. That is the ninth instance of this
 # port's recurring shape -- something correct, documented and unexercised -- one
 # level up: the checks themselves were the thing nobody was running.

tools/port/verify-capture

@@ -5,7 +5,7 @@
 #   tools/port/verify-capture               # every screen with a capture
 #
 # THIS IS THE CORRECTNESS CHECK. `verify-screen` is the consistency one, and its
-# own header has pointed at this file since P1 -- `tools/verify-capture` -- while
+# own header has pointed at this file since P1 -- `tools/port/verify-capture` -- while
 # this file did not exist. The port has had a harness comparing two renderers
 # that share its assumptions, and none comparing it to the game.
 #

tools/port/verify-screen

@@ -27,14 +27,14 @@
 # concluded the port had drifted away from the game -- r +0.7462 against the
 # reference's +0.8727. Posed as it SHIPS, the same block scores **+0.9994**.
 # The conclusion was an artefact of the pose, and it was written up as a finding.
-# Correctness questions go to `tools/verify-capture`, which poses as shipped.
+# Correctness questions go to `tools/port/verify-capture`, which poses as shipped.
 #
 # So: a DIFFERS row means "we moved apart, go find out which of us moved". It
 # does not mean the port is wrong. Where a capture and this tool disagree, the
-# capture wins. Use `tools/verify-capture` for the correctness question.
+# capture wins. Use `tools/port/verify-capture` for the correctness question.
 #
-#   tools/verify-screen                 # every screen in the manifest
-#   tools/verify-screen main_menu title # named screens
+#   tools/port/verify-screen                 # every screen in the manifest
+#   tools/port/verify-screen main_menu title # named screens
 #
 # Writes <screen>.godot.png, <screen>.ref.png and <screen>.diff.png into
 # $OUT (default: a directory under /tmp) and prints, per screen, the largest