diff --git a/docs/port/DECISIONS.md b/docs/port/DECISIONS.md index 72a58d7b..a4d32f8b 100644 --- a/docs/port/DECISIONS.md +++ b/docs/port/DECISIONS.md @@ -9,7 +9,7 @@ dies, which is what this file is for. -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) ## 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. diff --git a/port/scripts/screen_view.gd b/port/scripts/screen_view.gd index 2cd09860..e0a0b94d 100644 --- a/port/scripts/screen_view.gd +++ b/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`. diff --git a/tools/port/check-all b/tools/port/check-all index 7148aec9..dc219e9d 100755 --- a/tools/port/check-all +++ b/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. diff --git a/tools/port/verify-capture b/tools/port/verify-capture index 4f46bbdd..2e1dbe3e 100755 --- a/tools/port/verify-capture +++ b/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. # diff --git a/tools/port/verify-screen b/tools/port/verify-screen index fd1095d4..e670913a 100755 --- a/tools/port/verify-screen +++ b/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 .godot.png, .ref.png and .diff.png into # $OUT (default: a directory under /tmp) and prints, per screen, the largest