diff --git a/docs/plans/2026-10-11_terminal-app-follow-up.md b/docs/plans/2026-10-11_terminal-app-follow-up.md new file mode 100644 index 000000000..245e42fe3 --- /dev/null +++ b/docs/plans/2026-10-11_terminal-app-follow-up.md @@ -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 ." 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.