diff --git a/docs/superpowers/specs/2026-07-23-session-summary-layout-design.md b/docs/superpowers/specs/2026-07-23-session-summary-layout-design.md new file mode 100644 index 00000000..d7affd6a --- /dev/null +++ b/docs/superpowers/specs/2026-07-23-session-summary-layout-design.md @@ -0,0 +1,108 @@ +# Session view resizing and summary layout + +**Date:** 2026-07-23 +**Status:** Approved design, pending implementation + +## Goal + +Make the read-only session view easier to inspect by allowing the document panel to +occupy up to half of the available application width and by presenting the persisted +session outcome in task-oriented order. + +## Session panel resizing + +- Add a dedicated vertical separator between `SessionDocumentsPanel` and the area to + its right. It must not reuse or interfere with the Model activity separator. +- On desktop, pointer dragging can resize the session panel from its minimum usable + width up to exactly 50% of the measured application container. +- Preserve at least 512 px for the area to the right when the container is too narrow + for a 50/50 split. +- Support keyboard resizing with arrow keys, `Home`, and `End`, expose the current + bounds through separator ARIA attributes, and persist the chosen width in local + storage under a session-panel-specific key. +- On layouts where a desktop split is not usable, do not show an interactive divider. + +## Summary document contract + +The harness remains the source of truth for ordering and semantic projection. Both +filesystem and repository-backed snapshots must produce the same ordered document +bundle: + +1. Original question. +2. Final SQL. +3. Data preview. +4. Revised question. +5. Assumptions. +6. Memories. +7. Remaining useful technical documents, such as schema linking and validation + details not already represented by the preview. + +Missing artifacts are omitted without changing the relative order of those present. + +### Final SQL + +- Render the persisted `sql_final` artifact immediately after the original question. +- Show an always-available copy button with an accessible label. +- Copy the exact SQL text to the clipboard and provide visible success/failure + feedback without modifying the SQL. + +### Preview + +- Derive the preview from the persisted validation report produced during finalization; + do not rerun the SQL when opening a session. +- Present the preview as its own Markdown/table document immediately after Final SQL. +- Keep execution metadata that belongs to the preview, while excluding unrelated + validation-report sections from this position. + +### Revised question and assumptions + +- Split the persisted `question` artifact at its Assumptions heading. +- Render the rewritten question as real Markdown, with heading and list structure + preserved, after the preview. +- Render assumptions as their own Markdown section immediately after the rewritten + question. If there are no assumptions, omit the section. + +### Memories and decision filtering + +- Build one memory list from effective ledger decisions. +- List approved entries first (`memory_promoted`), followed by declined entries + (`memory_promotion_declined` and legacy `memory_rejected` where present). +- Each entry exposes a human-readable subject and detail/rationale; raw decision-type + chips are not shown in the memory list. +- Remove these decisions from the generic Decisions document because they are shown + in Memories. +- Never render `phase_approved`, `table_approved`, `table_promoted`, or + `column_promoted` in the session summary. +- Other meaningful decision types may remain in the generic Decisions document. + +## Component boundaries + +- `harness/tht/session/store.py`: pure projection helpers for question sections, + preview extraction, decision filtering/grouping, and ordered document construction. +- `frontend/src/shell/SessionDocumentsPanel.tsx`: rendering only; receives the ordered + documents and adds the session-panel resize width. +- A session-panel-specific resize hook owns measurement, bounds, pointer/keyboard + behavior, and persistence. Shared pure resize math may be reused from the activity + panel where doing so does not couple their state. +- `SqlViewer` owns the SQL copy control so every Final SQL rendering has the same + accessible behavior. + +## Failure handling + +- Malformed Markdown or legacy decision lines degrade within the existing per-document + error boundary and do not blank the session panel. +- Clipboard rejection leaves the SQL visible and reports that copying failed. +- A validation report without a preview heading produces no Preview document. +- Legacy sessions with a combined revised-question/assumptions artifact are split at + read time; their persisted content is never rewritten. + +## Testing + +- Harness tests pin identical ordering for filesystem and snapshot document builders, + preview/question splitting, decision suppression, and approved-before-declined + memory ordering. +- Frontend tests pin session-panel resizing to the 50% bound, pointer and keyboard + behavior, exact section order, formatted revised-question Markdown, the unified + memory list, hidden decision types, and clipboard success/failure behavior. +- Run the full harness suite, full frontend suite, TypeScript check, production build, + Ruff, Pi gate tests, and `git diff --check` before completion.