Merge remote-tracking branch 'origin/main' into auto/frame-blend-draw-path

docs/agents/PLAYTEST-2026-09-02-menus.md

@@ -143,6 +143,83 @@ authored premise is in trouble. **Answer F4 before building on `shared`.**
 
 ---
 
+## F5 — Ⓐ: does the animation SNAP, or accelerate? **A human cannot tell.**
+
+Follow-up from the same human, and the honesty in it is the useful part:
+
+> *"I think the animation speeds up to the finished state. So it is not a snap in
+> the sense of a cut, but rather becoming much quicker — which however feels
+> instant too, so it is difficult to discern by a human. It might also actually
+> snap/cut to the finished state, but appear as a quick animation… Similar to how
+> videos work by quickly playing distinct frames. So I cannot tell certainly
+> which it is. Upon multiple attempts it does look more like a snap. Decoder
+> still should verify."*
+
+**This is a question the oracle-by-eye cannot answer, and it is being handed over
+as such rather than guessed.** A three-frame acceleration and a one-frame cut are
+indistinguishable to a person; they are trivially distinguishable to an
+instrument. Two independent routes, and they should agree:
+
+1. **Per-frame capture.** Press Ⓐ mid-build-in and read the submitted alphas
+   frame by frame. An acceleration shows **intermediate values**; a cut shows
+   one transition and none. This is a counting question — see
+   [`TEMPORAL-VERIFICATION.md`](TEMPORAL-VERIFICATION.md), and note that the eye
+   failing here is exactly why.
+2. **The code.** Whatever Ⓐ does to the clock is a store somewhere: does it
+   assign the target time, or raise a rate multiplier? A snap and a speed-up are
+   different instructions, and the image says which.
+
+⚠️ The human's *"looks more like a snap on multiple attempts"* is a **prior, not
+a result.** Do not let it stand in for the measurement, and say so if the
+measurement disagrees with it.
+
+## F6 — 🔴 The title's sweeping glow starts TOO EARLY in the port
+
+> *"…blue geometric lines (like on a PCB, straight lines and rectangular or 45°
+> turns). These have a white glow moving on them as an animation. In the game
+> this animation only starts when the plate is shown — basically the animation
+> starts the same as the 'insert' of the plate. In the port it already starts
+> before the plate arrives."*
+
+**The elements are `ptloop01` and `ptloop02`** — already known to this corpus as
+the sweeps whose leaf *"sweeps a 400 px quad whose left edge travels
+−639…1521"*, and whose free-running on the settled title is a ❌ entry in
+`REFUTED.md` (they **do** free-run). Nothing there says **when they start**, and
+that is the whole of this finding.
+
+### 📌 A lead, from the exported declaration — MINE, unverified, check it first
+
+`title.json` gives `ptloop01` and `ptloop02` keyframes at:
+
+```
+t = 0, 70, 100, 238, 250
+```
+
+and the plate reaches full alpha at **`t = 236`**. They are not alone: `pteff02`
+has a key at exactly **236**, and `ptlogo_back2eff` and `ptcopyright` at **238**.
+**236–238 is a synchronisation point in the declared data**, and the human has
+just reported a behaviour change at that instant.
+
+So the first question is cheap: **is the sweep's motion declared to begin at 238,
+with the port instead free-running the leaf from t=0?** If so this is a decode
+question with a decoded answer, and nothing needs authoring.
+
+⚠️ **Two reasons not to take that lead as the answer.** The `238…250` pair looks
+just as much like an **exit ramp** — `ptcopyright` and `ptlogo_back2eff` use
+exactly that shape and they are certainly not starting anything. And the sweep
+lives in a **nested `.rat` leaf** with its own three keyframes, so the parent's
+envelope and the leaf's motion are different timelines. Which of the two the
+human is watching is the thing to establish.
+
+### Why this one is worth prioritising
+
+It bears directly on **F4 and on `clock: "shared"`**. If a title element does not
+begin moving until the plate arrives, then either the declared data says so — in
+which case the shared clock survives and our reading of the keyframes is wrong —
+or something at the plate's arrival **starts** it, which is a mechanism nobody
+has proposed. Either answer constrains the clock question that F4 is also
+probing.
+
 ## H3 — the plate delay is ACCEPTED
 
 > *"Delay feels the same. Cannot verify it is exact same, but is sufficient."*

docs/agents/PROTOCOL.md

@@ -188,6 +188,45 @@ asking X"** rather than approximating. An approximation from the wrong agent
 arrives with no classification attached and is indistinguishable from a
 measurement a month later.
 
+## Work in units a human can check in a minute
+
+**Set by the human, 2026-09-02, from what actually worked.** The splash bug had
+sat through a whole milestone. Scoped to *one* question — *does it animate?* — it
+was found, fixed, verified and signed off in a day.
+
+> *"I think attacking the 'whole' mission was too big for them to handle. Split
+> the given missions and tasks into even smaller tasks which they can tackle and
+> give to a human for feedback."*
+
+So: **a milestone is not a unit of work. It is a bag of them.** Before starting,
+split it, and pick one.
+
+A unit is right-sized when it ends in something **a person can judge in under a
+minute without reading anything**. Not "P6 audio" — *"the confirm SFX is no
+longer louder than the music; listen once."* Not "the title screen" — *"the glow
+starts when the plate appears; watch one boot."*
+
+Each unit, written down **before** the work:
+
+* **the question**, as one sentence a non-expert could answer;
+* **what the human looks at**, and what pass and fail each look like;
+* **what it does NOT cover** — the neighbouring thing you are deliberately not
+  fixing, so nobody reads a narrow pass as a broad one.
+
+Then: **do that one, hand it over, and stop.** Do not run ahead into the next
+unit while the first is unverified — an unverified fix underneath a second change
+is how a regression becomes two-variable and unattributable.
+
+⚠️ **The bar is a HUMAN check, not a green tool.** Three instruments passed a
+frozen screen. A tool answers *did my change do what I intended*; only the person
+answers *is it right*. When a unit needs a look, say so plainly and say what to
+look at — an ask that is buried in a document nobody opens is not an ask.
+
+📌 And this bounds the writing, which has been the other failure: the retro found
+`DECISIONS.md` past 13 000 lines while the gate did not move. **A unit's record
+is proportional to the unit.** If explaining it takes longer than doing it, the
+unit was too big or the writing is doing something other than explaining.
+
 ## Publishing
 
 * Commit to `auto/<topic>`; a human merges.

docs/agents/decoder-loop.md

@@ -1,6 +1,40 @@
 You are the **Decoder**. Answer the open questions the Godot menu port is
 blocked on, one at a time.
 
+## 🔴🔴 SOLE FOCUS, 2026-09-02: **THE TITLE'S ANIMATION TIMING — F5 and F6, nothing else**
+
+**Work only these two.** Not the pipeline, not the audio mix, not the repeat
+rate — they stay queued in
+[`PLAYTEST-2026-09-02-menus.md`](PLAYTEST-2026-09-02-menus.md).
+
+> *"Let's have the agents focus on this item and only this only."*
+
+**F6 first** — it is the one with a lead. A human reports that the title's
+sweeping white glow (**`ptloop01` / `ptloop02`**, the blue PCB-like lines) **only
+starts when the plate appears** in the real game, while the port starts it
+earlier. `title.json` declares those elements at `t = 0, 70, 100, 238, 250` and
+the plate reaches full alpha at **`t = 236`** — with `pteff02` keyed at exactly
+236 and `ptlogo_back2eff`/`ptcopyright` at 238. **236–238 is a synchronisation
+point in the declared data and a human just reported a behaviour change there.**
+⚠️ `238…250` may equally be an **exit ramp** (`ptcopyright` uses that shape and
+starts nothing), and the sweep lives in a nested `.rat` leaf with its own
+timeline. Establish which of the two the human is watching.
+
+**F5 second** — does Ⓐ **snap** the title to finished, or **accelerate** it? The
+human says they cannot tell, and is right that they cannot: a three-frame
+acceleration and a one-frame cut look identical to an eye. Two routes, and they
+should agree: a **per-frame capture** (an acceleration shows intermediate alphas,
+a cut shows none) and **the code** (assigning a target time and raising a rate
+multiplier are different instructions). Their *"looks more like a snap"* is a
+**prior, not a result** — say so if the measurement disagrees.
+
+### And split it before you start
+
+**Read the new "Work in units a human can check in a minute" section of
+[`PROTOCOL.md`](PROTOCOL.md).** The human's diagnosis is that whole missions have
+been too big to hold. Break even F6 down, write the question and the
+look-at-this-and-you-will-see before working, do one, hand it over, stop.
+
 ## ✅ THE LOGO SPLASHES ARE DONE — signed off by the human, 2026-09-02
 
 > *"Looks good! Cannot notice any obvious difference from the actual game.

docs/agents/port-loop.md

@@ -1,5 +1,34 @@
 You are the **Port**. Build the Godot menu shell, one milestone at a time.
 
+## 🔴🔴 SOLE FOCUS, 2026-09-02: **THE TITLE'S ANIMATION TIMING — F5 and F6, nothing else**
+
+**Work only these.** Not the repeat rate, not the audio mix, not P7 — they stay
+queued in
+[`../agents/PLAYTEST-2026-09-02-menus.md`](../agents/PLAYTEST-2026-09-02-menus.md).
+
+> *"Let's have the agents focus on this item and only this only."*
+
+**F6 — the title's sweeping white glow starts too early here.** A human watching
+the real game reports that the glow travelling along the blue PCB-like lines
+(**`ptloop01` / `ptloop02`**) **only begins when the plate appears**; the port
+starts it before. **This is the Decoder's to establish and yours to implement** —
+do not choose a start time. What you *can* do now without an answer: determine
+exactly **what your renderer currently uses** to start that sweep, so that when
+the answer lands the change is one line and not an investigation.
+
+**F5 — does Ⓐ snap or accelerate the title?** The Decoder is measuring it. Until
+they answer, **do not implement Ⓐ#2** — a snap and a speed-up are different
+behaviours and picking one is exactly the guessing that has cost this project.
+
+### And split it before you start
+
+**Read the new "Work in units a human can check in a minute" section of
+[`PROTOCOL.md`](PROTOCOL.md).** The human's diagnosis is that whole missions have
+been too big to hold — the splash sat through a milestone, then took a day once
+scoped to *does it animate?*. Break the work down, write the question and what
+the human should look at **before** working, do one unit, hand it over, and stop.
+Do not stack a second change on an unverified first.
+
 ## ✅ THE LOGO SPLASHES ARE DONE — signed off by the human, 2026-09-02
 
 > *"Looks good! Cannot notice any obvious difference from the actual game.