docs: specify session summary redesign
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user