docs(plans): terminal app follow-up brief after row 55

Filbert N10-N12 and Dewey's round 3 survivors: a narrow-terminal decideShown guard test, a way out in the hidden decide box, a U+18D08 width test, a cut-box Esc back test, and the README row count as an example. Owner Darkwing; reviewers Dewey and Filbert. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-11 16:02:16 -05:00
parent 3634d06ec8
commit 1e71d74670
1 changed files with 84 additions and 0 deletions
@@ -0,0 +1,84 @@
+# Terminal app follow-up after row 55 (2026-10-11)
+
+Status: written by Sage, lead. It follows `docs/plans/BRIEF-TEMPLATE.md`
+and amends no section of the design-implementation brief. One row.
+
+## Terminal app follow-up: narrow-terminal guard test, hidden-box way out and width tests
+
+### Problem
+
+Row 55 (#1544) shipped the full-screen terminal app (`mosaic`). Dewey
+(comment 27308) and Filbert (comment 27309) approved round 3 on manifest
+59f1b9b4 and left notes, none blocking. Darkwing listed the same ones.
+
+- Filbert N10, Dewey survivor `r3-shown-no-min`. Nothing tests the
+  `cols >= MIN_COLS` half of `decideShown` in
+  `packages/cli/src/screens.mjs`. Without it, every cli test passes, yet
+  on a tall terminal under 40 columns the decide box fits at `cols - 2`
+  while `draw()` shows the too-small screen, and `y` sends
+  `{"choice":"yes"}`. Dewey reproduced that at 39x33, 39x40, 39x60, 36x60
+  and 30x80. Filbert found the box fits at 39x29, 35x31 and 30x35. The
+  existing test's sizes (30x24, 80x9) are too short for the box to fit,
+  so they can't catch the mutant. The code is right today; the test is
+  missing.
+- Filbert N12, Dewey's note. The hidden box says "Too small to show this
+  decision." and "Any key answers No." but not what to do next. Under the
+  box, the status line still says "You will see the decision again and
+  confirm with y.", which is false while the box is hidden.
+- Filbert N11. U+18D08, the end of the U+17000 range, has no character in
+  the width test (mutant `n9-17000-end-off` survives).
+- Dewey survivor `cut-drops-choice`. No test checks that a help or detail
+  box cut to fit keeps its `Esc back` line.
+- Dewey's README note. `packages/cli/README.md` says a gated decision with
+  a task needs 29 rows at 40 columns. That holds for a plain decision; a
+  longer one needs 31 or 32. The rule is right; the number is an example
+  and should read as one.
+
+### Owner and reviewer
+
+Owner: Darkwing, after their rows 58 and 61. Reviewers: Dewey and Filbert.
+
+### Files owned
+
+- `packages/cli/src/screens.mjs`, the hidden box's text only
+- `packages/cli/src/app.mjs`, the status line while the decide box is
+  hidden only
+- `packages/cli/tests/app.test.mjs`
+- `packages/cli/README.md`
+
+### What ships
+
+- A test that opens a gated decision at sizes under 40 columns where the
+  decide box would fit (at least 39x40 and 30x80; a sweep of 30-39
+  columns at 33-60 rows is better) and asserts the frame is the
+  too-small screen and `y` sends nothing. Mutant `shown-no-min-cols`
+  (`r3-shown-no-min`) fails it.
+- The hidden box adds one line naming the way out, along the lines of
+  "Make the terminal bigger, or use mosaic decide <id> <choice>." While
+  the box is hidden, the status line doesn't promise a `y` confirmation.
+  A test pins both.
+- The width test checks a character at U+18D08. Mutant
+  `n9-17000-end-off` fails it.
+- A test that cuts a help or detail box to fit and asserts `Esc back`
+  stays on screen. Mutant `cut-drops-choice` fails it.
+- The README states the 40-column row count as an example for a plain
+  decision, not a fixed requirement.
+- The packet reruns the four named mutants against the candidate and
+  lists them killed.
+
+### Out of scope
+
+`width()` counting per code point (a ZWJ emoji measures wider than the
+terminal shows it). That is the safe direction, as the README says, and
+`wrap` already breaks between graphemes. `throw-swallowed`: a write that
+fails exactly once is not worth a test (Filbert's call, and Dewey rated it
+harmless). The rule that `y` resolves only while `decideShown()` is true
+stays as row 55 shipped it. No behavior change beyond the hidden box's
+text and status line, unless a new test finds a defect; then the packet
+says so.
+
+### Gate
+
+Dewey and Filbert approve on the row's issue naming the candidate
+manifest. The cli and queue node suites and every `scripts/test-*.sh`
+green on Sage's gate rerun.