From 9e7bca6de92fbcbc07349357523a3df0479ccb31 Mon Sep 17 00:00:00 2001 From: Sylpheed port agent Date: Sun, 30 Aug 2026 18:10:22 +0000 Subject: [PATCH] port: three live-but-undocumented flags, and a dead instruction I wrote while fixing them Their newest class -- the instruction is dead AND the working one is undocumented -- inverts last iteration's sweep. I checked documented->parsed; the reverse is parsed->documented, and it enumerates, so it completes rather than samples. Eighteen flags parsed, fifteen documented, three live and undocumented: --film-interval and --skip-at (used by verify-dwell, in no usage example) and --no-hold, which plays a screen past its rest instead of clamping each element at its hold, documented in DECISIONS.md and absent from the header a reader consults. A capability that exists only in an 11000-line record does not exist to anyone reading the interface. Then I documented it wrong in the same command. I wrote the example as --screen=title --no-hold --time=6 and tested it: the renders are byte-identical because --time sets frozen and pose_at tests 'holding and not frozen', so an explicit instant makes --no-hold inert. Without --time the pair differs by max 253. I wrote a dead instruction inside the commit fixing dead instructions, and it only failed to ship because I ran the example rather than trusting that a parsed flag works -- the gap I had named one iteration earlier. Strongest evidence yet for their ranking: a wrong description costs a reader's belief, a wrong instruction hands them a null result that looks like a finding. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01N7FiFFFwbvG2uxdcEh8HyF --- docs/port/DECISIONS.md | 40 +++++++++++++++++++++++++++++++++++++++- port/scripts/boot.gd | 18 ++++++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/port/DECISIONS.md b/docs/port/DECISIONS.md index a4d32f8b..f3920e7a 100644 --- a/docs/port/DECISIONS.md +++ b/docs/port/DECISIONS.md @@ -9,7 +9,7 @@ dies, which is what this file is for. -213 sections. Search this before re-deriving anything. +214 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) @@ -224,6 +224,7 @@ dies, which is what this file is for. * [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) +* [Live-but-undocumented flags — and I wrote a dead instruction while fixing dead instructions](#live-but-undocumented-flags--and-i-wrote-a-dead-instruction-while-fixing-dead-instructions) ## P0 — the exporter, 2026-08-28 @@ -11274,3 +11275,40 @@ while real — are the cheap kind. 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. + +## Live-but-undocumented flags — and I wrote a dead instruction while fixing dead instructions + +Their newest class is one step past a stale instruction: **the instruction is dead +*and* the working one is undocumented.** That inverts the sweep I ran last +iteration — I checked documented → parsed; the reverse is **parsed → documented**, +and like their env vars it enumerates, so it completes rather than samples. + +Eighteen flags parsed, fifteen documented, **three live and undocumented**: + +| flag | | +|---|---| +| `--film-interval` | used by `verify-dwell`, in no usage example | +| `--skip-at` | same | +| **`--no-hold`** | plays a screen **past its rest** instead of clamping each element at its hold — documented in `DECISIONS.md` and **absent from the header a reader consults** | + +📌 `--no-hold` is the one that matters: **a capability that exists only in an +11 000-line record is, to anyone reading the interface, a capability that does not +exist.** + +### 🔴 And then I documented it wrong, in the same command + +I wrote the example as `--screen=title --no-hold --time=6` and tested it. **The +two renders are byte-identical — the flag no-ops.** `--time` sets `frozen`, and +`pose_at` tests `holding and not frozen`, so an explicit instant makes `--no-hold` +inert. Without `--time` the same pair differs by **max 253**. + +**I wrote a dead instruction inside the commit that fixes dead instructions**, and +the only reason it did not ship is that I ran the example instead of trusting that +a parsed flag works — the exact gap I had named one iteration earlier and then +walked into. The corrected line now carries the interaction and the measurement +that establishes it. + +⚠️ This is the strongest evidence yet for their ranking. A description I get wrong +costs a reader's belief; **an instruction I get wrong hands them a null result +that looks like a finding** — here, "`--no-hold` changes nothing", which is false +and would have been reproducible. diff --git a/port/scripts/boot.gd b/port/scripts/boot.gd index 7def26db..8332ad5f 100644 --- a/port/scripts/boot.gd +++ b/port/scripts/boot.gd @@ -7,6 +7,24 @@ # godot --path port -- --screen=main_menu # godot --path port -- --screen=main_menu --capture=/tmp/godot.png # godot --path port -- --screen=main_menu --time=0.5 --capture=/tmp/at-half.png +# godot --path port -- --screen=title --no-hold +# # play PAST the rest instead of clamping +# # each element at its own hold. +# # ⚠️ NOT with `--time`: that sets `frozen`, +# # and `pose_at` tests `holding and not +# # frozen`, so an explicit instant makes +# # `--no-hold` a no-op. Verified: identical +# # renders with `--time`, max 253 different +# # without it. +# godot --path port -- --boot --film=/tmp/b --film-interval=0.1 +# # frame cadence for --film (default 0.25) +# godot --path port -- --boot --skip-at=1 # press (A) at 1 s to skip a movie +# +# 🔴 THESE THREE WERE LIVE AND UNDOCUMENTED. `--no-hold` is documented in +# DECISIONS.md and was absent from the block a reader actually consults; +# `--film-interval` and `--skip-at` are used by `tools/port/verify-dwell` and +# appeared nowhere else. A capability that exists only in the record is, to +# anyone reading the interface, a capability that does not exist. # godot --path port -- --screen=main_menu --pose=rest --capture=/tmp/rest.png # godot --path port -- --screen=title --overlay=press_start --time=4 # godot --path port -- --boot # the whole boot sequence