Repository navigation
Spec2Contract TUI
Grzegorz Nowak edited this page Sep 30, 2026
·
1 revision
This page maps the TUI area of the pi-schematic Product Book (left-space prefix
PB-TUI-nn, 45 rows) onto the existing in-repo tests. The contract families that carry
these claims are the status/indicator and snapshot suites (T44, T45), the nested-spawn
render/event suites (T03, T04, plus T01/T02), the Model Groups TUI suite (T23), the
notebook command/tool-render tests (T08), and the handoff/readonly command suites (T11,
T25, T43), with T22 covering Model Groups boot-validation notifications. Status marks
representation by an existing test, not test success.
| Claim ID | Assertion (terse) | Fixture(s) | Status | Notes |
|---|---|---|---|---|
| PB-TUI-01 | Status bar shows rounded ctx N% for a valid percentage |
T44, T45 | ✅ asserted | tui-indicators.test.ts — "updateIndicators sets context usage status with correct color tone" ([accent:42%]); render-snapshots.test.ts — "context indicator at 30% matches snapshot". Rounding of a fractional percent is not separately asserted. |
| PB-TUI-02 | Unavailable or malformed usage shows ctx --%
|
T44 | ✅ asserted | tui-indicators.test.ts — "updateIndicators handles null context usage" and "updateIndicators treats malformed percentages as unavailable" (NaN/Infinity/-1). |
| PB-TUI-03 | Context tone bands: dim <30, accent 30–49, warning 50–69, error ≥70 | T44, T45 | ◐ partly asserted | Missing: the below-30 dim band. tui-indicators.test.ts asserts accent ("…uses accent tone at 30-49% context"), warning ("…uses warning tone at 50-69% context"), error ("…uses error tone at 70%+ context"); no sub-30 case. |
| PB-TUI-04 | Nonempty notebook shows 📒 N
|
T44 | ✅ asserted | tui-indicators.test.ts — "updateIndicators shows notebook page count in status" (2 pages). |
| PB-TUI-05 | Empty notebook shows dim 📒 0
|
— | A test calling updateIndicators on empty notebookPages and asserting the notebook status is the dim 📒 0 placeholder would seal it. |
|
| PB-TUI-06 | Set notebook topic shows 🧭 <topic>
|
T44 | ✅ asserted | tui-indicators.test.ts — "updateIndicators shows active notebook topic when set" (exact 🧭 oauth). |
| PB-TUI-07 | Unset notebook topic shows dim 🧭 -
|
— | A test asserting the topic status is the dim 🧭 - placeholder when activeNotebookTopic is null would seal it. |
|
| PB-TUI-08 | Readonly adds warning-coloured 🔒 readonly; removed when off |
T44 | ◐ partly asserted | Missing: the warning tone. tui-indicators.test.ts — "updateIndicators shows readonly indicator when enabled" (lock emoji + "readonly") and "updateIndicators hides readonly indicator when disabled"; neither checks warning colour. |
| PB-TUI-09 | Valid usage ≥70% shows warning widget above editor | T44 | ✅ asserted | tui-indicators.test.ts — "updateIndicators uses error tone at 70%+ context" (widget shown) and "updateIndicators hides widget below 70% context" (cleared). |
| PB-TUI-10 | Active-topic widget: same topic → spawn, different topic → handoff | — | A test rendering updateIndicators with a set topic at ≥70% and asserting the widget text "same topic → spawn, different topic → handoff" would seal it. T46 watchdog nudges assert related guidance but not this widget branch. | |
| PB-TUI-11 | No-topic widget: handoff soon unless a topic can be assigned cleanly | — | A test rendering updateIndicators with activeNotebookTopic null at ≥70% and asserting "no active topic; handoff soon…" would seal it. |
|
| PB-TUI-12 |
/notebook <topic> sets human-owned topic, notifies, refreshes indicators |
T08, T09 | ✅ asserted | notebook.test.ts — "/notebook notifies with info on first set and warning on boundary change" (notification + STATUS_KEY_TOPIC refresh); topic.test.ts — "notebook_topic_set preserves human authority…".
|
| PB-TUI-13 | Bare /notebook no-ops when no UI is attached |
T08 | ✅ asserted | notebook.test.ts — "/notebook exits cleanly when headless". |
| PB-TUI-14 | TUI bare /notebook opens a selector headed with the current page count |
T08 | ✅ asserted | notebook.test.ts — "/notebook empty overlay renders empty state and closes on input" (Notebook (0 pages)). |
| PB-TUI-15 | Selector lists pages alphabetically, at most ten rows | T08 | ◐ partly asserted | Missing: the 10-row viewport cap. notebook.test.ts — "/notebook overlay sorts entries consistently" asserts alphabetical ordering only. |
| PB-TUI-16 | Empty selector says to use notebook_write, offers Escape to close |
T08 | ◐ partly asserted | Missing: the Escape affordance/footer. notebook.test.ts — "/notebook empty overlay renders empty state and closes on input" asserts the "(empty) — use notebook_write…" text and closes with "x", not Escape. |
| PB-TUI-17 | Nonempty selector advertises up/down navigation, Enter select, Escape close | T08 | ◐ partly asserted | Missing: the footer advertisement. notebook.test.ts — "/notebook selection previews the chosen entry" exercises Enter selection but does not assert the "↑↕ navigate • enter select • esc close" footer. |
| PB-TUI-18 | Selecting a page shows its body, truncated to 500 chars plus ...
|
T08 | ◐ partly asserted | Missing: the 500-char + "..." truncation branch. notebook.test.ts — "/notebook selection previews the chosen entry" asserts the body renders, but with a short body. |
| PB-TUI-19 | After a body is displayed, any key closes the overlay | T08 | ◐ partly asserted | Missing: the "any key"/"press any key to close" contract. notebook.test.ts — "/notebook selection previews the chosen entry" closes the body view with a second Enter only. |
| PB-TUI-20 |
/handoff with no direction shows Usage: /handoff <direction>
|
T11 | ✅ asserted | handoff.test.ts — "/handoff requires a direction". |
| PB-TUI-21 | Requested handoff shows waiting or ready status per eligibility | T11 | ✅ asserted | handoff.test.ts — "/handoff sets the handoff status indicator", "/handoff shows ready status when context is eligible", "handoff status becomes ready when later context becomes eligible". |
| PB-TUI-22 | Queued or running compaction uses 🤝 Handoff in progress
|
T11 | ◐ partly asserted | Missing: an assertion that the lifecycle actually sets this status on queue/start. handoff.test.ts uses the literal as a pre-seeded value on failure paths ("…re-engages the LLM after synchronous small-session rejection") but never asserts the tool sets it. |
| PB-TUI-23 |
/readonly toggles only while an attached UI is present |
T25 | ✅ asserted | readonly-mode.test.ts — "readonly toggle is a no-op in headless mode", "readonly toggle on blocks write, edit, handoff, and bash mutations". |
| PB-TUI-23 |
/readonly notifies whether readonly was enabled or disabled |
T43 | ◐ partly asserted | Missing: the toggle→notify wiring. notifications.test.ts asserts READONLY_ENABLED_STATUS / READONLY_DISABLED_NOTIFICATION copy ("all constants are non-empty strings", "summary constants use [readonly] prefix"), but readonly-mode.test.ts passes a no-op notify. |
| PB-TUI-24 |
Ctrl+Shift+R toggles readonly only while idle |
T25 | ✅ asserted | readonly-mode.test.ts — "readonly shortcut only toggles while idle". |
| PB-TUI-25 |
/model-groups opens its manager only in TUI; RPC receives /model-groups requires TUI mode
|
T22, T23 | ✅ asserted | model-groups-integration.test.ts — "root-recorded /model-groups rejects RPC and skips JSON/print before custom UI", "model groups untrusted root flow…publishes global-only state to TUI"; model-groups-tui.test.ts renders the manager. |
| PB-TUI-26 | Manager list shows boot-validation counts and degraded/unavailable/override/capability markers | T23 | ✅ asserted | model-groups-tui.test.ts — "model groups TUI list renders validation summary, health tags, add row, no Validate row, and confirmed D delete" (counts, project override, ⚠ degraded, ✗ unavailable); "model groups TUI renders modality labels, warnings, and stale override choices" (⚠ no common modalities, ⚠ stale modality override). |
| PB-TUI-27 | Manager adds a group and asks for confirmation before deleting a selected group | T23 | ✅ asserted | model-groups-tui.test.ts — "model groups TUI list renders validation summary, health tags, add row, no Validate row, and confirmed D delete" (+ Add group, Delete Model Group confirmation, delete only after confirm). |
| PB-TUI-28 | Add-model flow is provider → searchable model → thinking; picker only offers authenticated models | T23 | ✅ asserted | model-groups-tui.test.ts — "model groups TUI wizard renders provider/model/thinking steps and preserves state on add failure" (1/3 Provider, 2/3 Model, 3/3 Thinking); "model groups TUI Add-model picker shows capability chips per model" (excludes gpt-no-auth); "model groups TUI searchable Model step filters raw fields…". |
| PB-TUI-29 | Collapsed spawn call shows ≤3 prompt lines and an expansion hint |
T01, T45 | ✅ asserted | spawn.test.ts — "spawn renderCall shows prompt preview and optional routing controls" ("more lines"); render-snapshots.test.ts — "spawn call long prompt matches snapshot" (3 lines + "(4 more lines, to expand)"). |
| PB-TUI-30 | Collapsed live child view identifies model/group+model and thinking level | T03 | ✅ asserted | spawn-render.test.ts — "spawn result identity formats default routed and unknown fallback" (review → openai/gpt-routed • high, ✅ parent • low, rev? fallback → openai/parent • medium). |
| PB-TUI-31 | Running child view shows a real-time last-action summary (thinking / assistant text / tool) | T04, T03 | ✅ asserted | spawn-event.test.ts — "nested spawn live action tracks tool execution events" (thinking → live text → [bash]); spawn-render.test.ts — "collapsed nested spawn render shows preview and stats". |
| PB-TUI-32 | Collapsed child previews ≤5 lines of last assistant output and reports remaining | T03 | ✅ asserted | spawn-render.test.ts — "collapsed nested spawn render shows preview and stats" (lines one–five + "... 2 more lines"); "…keeps all text blocks from the last assistant message". |
| PB-TUI-33 | Child view includes token/cost stats when available | T03, T45 | ✅ asserted | spawn-render.test.ts — "collapsed nested spawn render shows preview and stats" (tok 12/34); render-snapshots.test.ts — "nested collapsed success matches snapshot" (tok 200/150 · 4t · $0.0450). |
| PB-TUI-34 | Expanded child view renders full message-component history indented by four spaces | T03, T45 | ✅ asserted | spawn-render.test.ts — "expanded nested spawn header stays within width after indent" (indented header, width-bounded); render-snapshots.test.ts — "nested expanded matches snapshot". |
| PB-TUI-35 | After a child's first render the parent owns the live view; disposing the parent aborts/cleans a live child | T01, T02, T04 | ✅ asserted | spawn.test.ts — "spawn renderResult transfers session ownership out of shared state"; spawn-lifecycle.test.ts — "resetState aborts a claimed child session after render ownership transfer"; spawn-event.test.ts — "nested spawn dispose aborts but does not dispose a claimed live child session" (abort + live-registry cleanup). |
| PB-TUI-36 | Re-render on width/expanded/showImages change; otherwise reuse cache | T03, T01 | ◐ partly asserted | Missing: width-change invalidation on a cached component. spawn-render.test.ts — "nested spawn render cache preserves stable output for identical params", "nested spawn clears cached render when showImages changes", "nested spawn rerenders when stats become unavailable"; spawn.test.ts — "nested spawn setExpanded and setShowImages no-op when value matches". |
| PB-TUI-37 | Bursty child streaming is batched on a ~30 FPS cadence | T04 | ✅ asserted | spawn-event.test.ts — "nested spawn coalesces same-turn child events into one parent invalidate", "nested spawn shared scheduler calls each distinct invalidate once per frame", "nested spawn rapid events collapse to last state", plus the frame-scheduler tests. |
| PB-TUI-38 | Malformed child events, missing tool defs, failed subscriptions degrade without crashing | T03, T04, T01 | ✅ asserted | spawn-render.test.ts — "spawn result ignores malformed route and stats fields", "nested spawn render is safe without details", "static no-output child error with empty details renders without fabricated identity"; spawn-event.test.ts — "nested spawn handleEvent recovers from malformed events", "handleEvent gracefully degrades with null message events"; spawn.test.ts — "nested spawn rebuildFromSession quietly tolerates missing tool definitions", "nested spawn attachSession recovers from subscribe throwing". |
| PB-TUI-39 | Inline notebook_write call shows page name and first-line preview |
T08 | ✅ asserted | notebook.test.ts — "notebook tool renderers expose stable call/result summaries" (notebook_write "entry-a": first line). |
| PB-TUI-40 | Completed notebook_write renders ✓ Saved "<name>" with preview; expanding lists page names |
T08 | ✅ asserted | notebook.test.ts — "notebook tool renderers expose stable call/result summaries" (Saved "entry-a": first line and expanded entries list containing entry-a). |
| PB-TUI-41 | Successful notebook_read renders ✓ "<name>" and reveals the body only when expanded |
T08 | ◐ partly asserted | Missing: the collapsed branch (body hidden). notebook.test.ts — "notebook tool renderers expose stable call/result summaries" renders with expanded: true and asserts the name and body; it does not assert absence when collapsed. |
| PB-TUI-42 | Missing notebook_read renders ✗ "<name>" not found
|
T08 | ◐ partly asserted | Missing: the renderResult not-found branch. notebook.test.ts — "notebook_read reports not found with current page names" asserts the execute() content text, not the ✗ … not found TUI render. |
| PB-TUI-43 |
notebook_index renders 📒 N page(s), expands to the list, and 📒 (empty) for none |
T08 | ◐ partly asserted | Missing: the empty render. notebook.test.ts — "notebook tool renderers expose stable call/result summaries" asserts 2 pages plus the expanded list; the empty-state test ("notebook tools show empty-state placeholders") checks execute() text, not the 📒 (empty) render. |
| PB-TUI-44 | Model Group config and boot-validation problems arrive as warning notifications | T22 | ✅ asserted | model-groups-integration.test.ts — "index session_start stores model group validation and notifies load and validation issues", "index session_start notifies empty-common and stale-override boot counts", "index session_start notifies corrupt/schema/unsupported load issues", "index session_start does not notify when load and validation issues are absent". |
| PB-TUI-45 | Child result capped at 2,000 lines or 50 KB with a truncation advisory | T01, T03 | ✅ asserted | spawn.test.ts — "truncateText respects line limit before byte limit" (2000 / 50*1024), "truncateText applies byte limit after line limit", "truncateText handles multi-byte boundaries correctly"; spawn-render.test.ts — "collapsed nested spawn render shows preview and stats" (· trunc advisory on the stats line). |
-
PB-TUI-05 — Empty notebook
📒 0placeholder: a test updating indicators on an empty notebook and asserting the dim📒 0status would seal it. -
PB-TUI-07 — Unset topic
🧭 -placeholder: a test updating indicators withactiveNotebookTopicnull and asserting the dim🧭 -status would seal it. - PB-TUI-10 — Active-topic high-usage widget guidance: a test rendering the ≥70% widget with a set topic and asserting the "same topic → spawn, different topic → handoff" wording would seal it.
- PB-TUI-11 — No-topic high-usage widget guidance: a test rendering the ≥70% widget with no active topic and asserting the "handoff soon unless you can assign one cleanly" wording would seal it.
(No whole-fixture gap beyond these rows: every other claim has at least one representing fixture.)
| Claims | Junction rows | ✅ | ◐ | |
|---|---|---|---|---|
| 45 | 46 | 29 | 13 | 4 |