Skip to content

Spec2Contract TUI

Grzegorz Nowak edited this page Sep 30, 2026 · 1 revision

Spec-to-contracts — TUI (book ↔ in-tests contracts)

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.

Junction rows

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 — ⚠️ no test yet 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 🧭 - — ⚠️ no test yet 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 — ⚠️ no test yet 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 — ⚠️ no test yet 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).

Empty surfaces in this area

  • PB-TUI-05 — Empty notebook 📒 0 placeholder: a test updating indicators on an empty notebook and asserting the dim 📒 0 status would seal it.
  • PB-TUI-07 — Unset topic 🧭 - placeholder: a test updating indicators with activeNotebookTopic null 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.)

Area coverage summary

Claims Junction rows ✅ ◐ ⚠️
45 46 29 13 4

Clone this wiki locally