| 1 | # TUI-DOG-008 — reference-state matrix |
| 2 | |
| 3 | > **2026-07-13 overnight update.** The color grammar and several motion gaps |
| 4 | > below were closed on the same dirty lane: |
| 5 | > live/done pairing now matches the implemented release grammar (seafoam `#4fd1c5` = live work, |
| 6 | > working green `#9bd66f` = settled ✓; the old sky-blue working / |
| 7 | > teal-success inversion is gone); waiting/approval read coral and failed |
| 8 | > reads rose; the whale mark carries the seafoam spout + ivory eye; ambient |
| 9 | > fish are two sky-blue shades so teal stays exclusively "live"; the ombre |
| 10 | > shimmer runs on the ~90 s ambient cadence and provably freezes on |
| 11 | > waiting/approval/failed; completion takes the one-shot 800 ms field |
| 12 | > brightness breath; and a first-class `ShellPhase::Verifying` renders the |
| 13 | > metered braille tick (distinct from the working bubble) for live |
| 14 | > test/check runs. Hunter's live eyeball remains the acceptance gate — the |
| 15 | > "Still needs Hunter eyeball" list below still applies, now with the new |
| 16 | > color grammar and verifying tick added to it. |
| 17 | |
| 18 | Dated receipt: 2026-07-12 |
| 19 | Lane: `codex/underwater-tui-20260711` @ worktree `codewhale-underwater-tui` |
| 20 | Reference basis: current TUI implementation plus real-terminal release QA. |
| 21 | Private design prototypes are intentionally not part of this public receipt. |
| 22 | Scope: visual metamorphosis / shell grammar (not Fleet, keybinding, or hitbox siblings) |
| 23 | |
| 24 | Status values: `implemented` | `partial` | `missing` |
| 25 | A hierarchy design aid is retained in the private workspace archive (not |
| 26 | acceptance proof). No dogfood reinstall on this pass. Ownership is code truth; |
| 27 | Hunter eyeball remains the acceptance gate. |
| 28 | |
| 29 | ### Focused tests run (2026-07-12) |
| 30 | |
| 31 | - `tui::phase_strip::tests::*` — 2 passed |
| 32 | - `tui::composer_chrome::tests::*` — 4 passed |
| 33 | - `composer_height_uses_quiet_rule_when_panel_is_not_needed` — passed (quiet baseline now 4) |
| 34 | - `underwater::tests::phase_markers_make_motion_and_attention_explicit` — passed |
| 35 | - `cargo check -p codewhale-tui --bin codewhale-tui` — clean at time of check |
| 36 | (siblings concurrently dirty other modules; do not treat full-suite green) |
| 37 | |
| 38 | ## State matrix |
| 39 | |
| 40 | | State | Release interaction contract | Status | Owning modules | Notes / gap | |
| 41 | | --- | --- | --- | --- | --- | |
| 42 | | **idle** | Whale empty water; roomy `❯` hint; quiet `idle` phase; ambient fish only in empty water | **partial** | `underwater.rs`, `ocean.rs`, `widgets` ambient, `composer_chrome.rs` | Empty-state whale + fish exist. Composer baseline was a cramped 1-line quiet rule; chrome policy now reserves multi-line breathing room and sheds padding before content at compact heights. Ambient life still needs live PTY proof under `env -u NO_COLOR`. | |
| 43 | | **typing** | Fish flee; `›` / draft phase; composer owns attention | **partial** | `underwater.rs` (`ShellPhase::Typing`), `composer_ui.rs`, `widgets::ComposerWidget` | Phase + flee-on-engage exist. Focus/shortcut ownership is sibling TUI-DOG-002/003 — not claimed here. | |
| 44 | | **working** | Ledger: prompt → short narration → settled `✓` receipts → **one** live row; phase band **above** `❯`; quiet composer | **partial → landing** | `phase_strip.rs`, `active_cell.rs`, `history` tool cells, `widgets::ChatWidget` | Before this pass: phase was the bottom footer under the composer (the 2026-07-12 audit had the order reversed). Now live phases place the strip above the composer. Ledger density/narration still needs Hunter eyeball; remove any remaining classic sidebar status echo in classic-only path. | |
| 45 | | **tool receipt** | Settled rows dim; live mark only on the active tool | **partial** | `active_cell.rs`, `history.rs`, `tool_routing.rs` | One active cell + settled flush is correct ownership. Visual “settled vs live” contrast and the single live mark need real-terminal comparison. | |
| 46 | | **workers open** | Top/side work surface: Tasks/To-do rows with open/stop; one focus owner | **partial** | `work_surface/*` | Surface + placements exist. Selection/scroll/Stop arm are sibling TUI-DOG-004/005/006. | |
| 47 | | **waiting for user** | Coral still `◆` / `?`; ambient frozen; phase above composer | **partial → landing** | `phase_strip.rs`, `underwater.rs` | Marker/color/stillness typed. Placement now follows the live-phase-above-composer rule. Attention band copy still needs real-terminal review. | |
| 48 | | **approval** | Modal/approval owns the decision; shell phase coral | **partial** | `approval.rs`, `widgets::ApprovalWidget`, `phase_strip.rs` | Approval modal exists; phase maps from `ModalKind`. Not a visual parity claim for the card itself. | |
| 49 | | **failed** | Coral `✕`; persists until acknowledged; no jitter | **partial** | `underwater.rs`, `phase_strip.rs` | Marker + sticky failed phase exist. Persistence-until-ack UX needs live confirm. | |
| 50 | | **done** | One `finishing → ✓ done` breath; then stable; composer bottom | **partial → landing** | `underwater.rs` completion breath, `phase_strip.rs` | Footer-only exhale exists. With phase-above placement, completion now sits on the strip above `❯`, not under it. | |
| 51 | |
| 52 | ## Layout grammar (this pass) |
| 53 | |
| 54 | | Concern | Before | After (this issue) | |
| 55 | | --- | --- | --- | |
| 56 | | Live phase vs composer | Composer above; phase footer always bottom | Idle/typing: composer above, quiet phase below. Working/waiting/approval/failed/done: **phase strip above**, composer is the final bottom object | |
| 57 | | Composer baseline | Min rows only when enclosed panel; empty → ~1 content row | `composer_chrome` always budgets density min rows when height allows; compact sheds padding/chrome before content | |
| 58 | | Phase ownership | `underwater::render_footer` only | `phase_strip` owns placement + band; underwater footer remains the render entry for classic/compat callers | |
| 59 | | Duplicate facts | Classic footer/sidebar can restyle the same busy label | Ocean path: phase strip owns phase/cost/detail keys; header owns route/ctx; work surface owns Tasks/To-do | |
| 60 | |
| 61 | ## Module map |
| 62 | |
| 63 | | Module | Role | |
| 64 | | --- | --- | |
| 65 | | `crates/tui/src/tui/phase_strip.rs` | Phase placement + band render (above/below composer) | |
| 66 | | `crates/tui/src/tui/composer_chrome.rs` | Roomier baseline, padding-shed-before-content | |
| 67 | | `crates/tui/src/tui/underwater.rs` | `ShellPhase`, markers, header/empty water | |
| 68 | | `crates/tui/src/tui/ocean.rs` | Ombre/flat treatment + ambient ink | |
| 69 | | `crates/tui/src/tui/work_surface/` | Tasks / To-do / workers strip & rails | |
| 70 | | `crates/tui/src/tui/active_cell.rs` | One live tool group | |
| 71 | | `crates/tui/src/tui/ui.rs` | Layout wiring only (preserve dirty Fleet hunks) | |
| 72 | |
| 73 | ## Still needs Hunter eyeball |
| 74 | |
| 75 | 1. Working turn reads as a ledger (not a dashboard) at 80×24 and 100×32. |
| 76 | 2. Phase strip sits directly above `❯` while a turn is live; idle keeps quiet phase under the prompt. |
| 77 | 3. Composer feels roomy at comfortable density and does not collapse to a one-line afterthought at 60×16 / 40×12 (padding sheds first). |
| 78 | 4. State change is legible with `low_motion` on (markers/color/placement carry meaning; braille is enhancement only). |
| 79 | 5. No duplicate “working” facts between strip, transcript, and work surface. |
| 80 | |
| 81 | ## Conflict notes |
| 82 | |
| 83 | - Dirty Fleet files (`fleet/profile.rs`, `fleet/roster.rs`, Fleet identity hunks in `ui.rs`) are untouched by this issue. |
| 84 | - Siblings own TUI-DOG-001–007 / 009–011. Do not merge their selection/keybinding work into this receipt. |
| 85 | - A prior internal audit claimed footer-below-composer as finished; live dogfood |
| 86 | (TUI-DOG-008) overrides that for acceptance. |
| 87 | - No push / commit / install on this pass. |
| 88 |