Interface spec: workspaces grouped by question, tabs and tool panels, plain-language task selection
This commit is contained in:
Sam
97
.pi/memory-vault/packs/paperclip-harness/20-context/home.md
Normal file
97
.pi/memory-vault/packs/paperclip-harness/20-context/home.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
type: context
|
||||
id: context.paperclip-harness.home
|
||||
title: home
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/context
|
||||
- autolearn
|
||||
- rich-discovery
|
||||
- repo/home
|
||||
---
|
||||
|
||||
# home
|
||||
|
||||
## Rich discovery update (2026-11-10 02:04:26)
|
||||
|
||||
You are right to call it, and I will not push back on the substance: the last few turns drifted into proving commands rather than designing the thing. Here is the line I would hold, briefly — when a claim reaches you as "it works", it gets run once in TUIOS, because a spec built on an unproven assumption is the failure that cost you three restarts. One check per claim. Not exploratory testing. Everything else, spec first.
|
||||
|
||||
I have rewritten `docs/UI-LAYOUT.md` as the single interface document (348 lines, replacing the earlier layout note rather than adding a second one).
|
||||
|
||||
## How it is grouped
|
||||
|
||||
By what you are doing, not by which system the data came from:
|
||||
|
||||
| Workspace | Question it answers | Panels |
|
||||
|---|---|---|
|
||||
| **Board** | what is the state of the work, what needs me | Task tree · Task summary · Needs you |
|
||||
| **Work** | what is happening now, what changed | Run log · Diff · Worktree facts |
|
||||
| **Conversation** | what was said, what do I say back | Thread · Composer · Task header |
|
||||
| **Author** | what am I asking for, how will it be judged | Task form · Guidance · Preview |
|
||||
| **Project** | which folder, machine, limits, cost | Project facts · Costs · Settings |
|
||||
| **Repair** | is the layout sound, what broke | Layout map · Health · Log |
|
||||
|
||||
Six, not sixteen. Four panels maximum per workspace, and the shell workspace stays for the moments you need a prompt. More than four panels cannot be read at once, so a fifth thing becomes a view inside a panel or a new workspace.
|
||||
|
||||
## The interface items
|
||||
|
||||
Twenty-seven, each with a purpose, its Charmbracelet component, and its empty, loading and failed behaviour. The ones that matter most:
|
||||
|
||||
- **Panel frame** — rounded border and bright edge when focused, plus the word `focus` in the title, so focus never depends on colour alone.
|
||||
- **Footer key hints** — built from `help` and `key.Binding`, so a key that would do nothing is not shown.
|
||||
- **Stale marker** — the time of the last successful read, in the panel title. A wrong panel is visibly stale instead of quietly wrong.
|
||||
- **Blocker badge** — `waits on AUD-163`, read per task; when the blocker finishes but the task is still marked blocked the badge changes to `ready`, because that is our most confusing state.
|
||||
- **Needs-you card** — one per decision: a refused merge, a task waiting on an answer, a task ready but stuck. Each says what happened and the one key that acts.
|
||||
- **Composer** — `textarea`, Enter sends, Shift-Enter new line, stated in the footer because a text area normally does the opposite.
|
||||
- **Diff view** — file headers, hunks, line numbers, additions and deletions marked by a leading character as well as colour; a large diff says how many lines it left out and offers a key for all of it.
|
||||
- **Result receipt** — the server's own words on failure, never a paraphrase.
|
||||
- **Health row** — pass, fail, or **not run**, three states, because "not run" is not "pass".
|
||||
|
||||
Components: `list` for rows and decisions, `table` for figures, `viewport` for anything scrollable, `textarea` for the composer, `textinput` for single-line fields, `help` and `key` for the footer, `spinner` and `progress` for feedback. One honest note: there is no tabs component in this collection, so a view switcher inside a panel is Lipgloss and `help` styling, not a Bubbles widget.
|
||||
|
||||
## Styling
|
||||
|
||||
One theme with semantic roles (text, muted, accent, success, warning, error, surface) and a light and dark variant from the start. One cell of horizontal padding, one blank line between sections, no blank line between rows. Columns computed from the content in view, never a hardcoded width. Truncation always ends visibly and the full text is one key away. Only two things animate: the spinner and the selection cursor. No colour that does not mean a state.
|
||||
|
||||
## Sizes
|
||||
|
||||
Every panel declares a smallest useful size (the task tree needs 30 by 10, the diff 40 by 12, the form 50 by 14). Below it, the panel draws its own short message naming what it has and what it needs — never a broken layout, never a scrollbar to hide the problem. The workspace needs 80 by 24.
|
||||
|
||||
## Layout follows the width
|
||||
|
||||
150 columns and wider: tree beside summary with Needs you under the tree; run log beside diff. 110 to 149: two panels per workspace, the third becomes a tab inside the panel of the same kind. 80 to 109: one panel per workspace, full width, in the order Board, Work, Conversation, Author. Below 80 by 24: one message.
|
||||
|
||||
## Four decisions before I build
|
||||
|
||||
1. **Does the tree drive the other workspaces?** Proposal: Enter writes `watching = AUD-163` into the project's `.harness/harness.toml` and asks TUIOS to show Conversation; the other panels reload when that file changes. One fact, one owner, survives a restart.
|
||||
2. **Six workspaces, or fewer?** Fewer means switching views inside panels, which hides state.
|
||||
3. **Which glyph set?** Must be checked against the font on the machine you actually sit at, not assumed.
|
||||
4. **Diff: its own panel in Work, or a tab beside the run log?**
|
||||
|
||||
Answer those four and I will build Board first, in the order the document lists, with the styling system established before the second panel exists — so the look is settled once instead of drifting per screen.
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 84%
|
||||
- Reason: Update component/repository context with detailed discovered structure and configuration
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
type: context
|
||||
id: context.paperclip-harness.paperclip-harness-interface-spec-docs-ui-layout-md
|
||||
title: Paperclip Harness interface spec (docs/UI-LAYOUT.md)
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/context
|
||||
- paperclip-harness
|
||||
- ui-layout
|
||||
- bubbletea
|
||||
- lipgloss
|
||||
- spec
|
||||
---
|
||||
|
||||
# Paperclip Harness interface spec (docs/UI-LAYOUT.md)
|
||||
|
||||
`docs/UI-LAYOUT.md` (348 lines) is the single interface document for the Paperclip Harness Go TUI.
|
||||
|
||||
**Stack:** Go with Charmbracelet: Bubble Tea, Bubbles, Lipgloss. Available Bubbles components: list, table, viewport, textarea, textinput, help, key, spinner, progress, paginator, timer, stopwatch, filepicker, cursor. Note: there is NO tabs component in Bubbles; a view switcher inside a panel must be Lipgloss + help styling.
|
||||
|
||||
**Twenty-seven interface items**, each with purpose, Charmbracelet component, and empty/loading/failed behaviour. Key ones:
|
||||
- Panel frame: rounded border, bright edge when focused, plus the word `focus` in the title (focus never depends on colour alone).
|
||||
- Footer key hints: built from `help` and `key.Binding`; keys that would do nothing are not shown.
|
||||
- Stale marker: time of last successful read in the panel title, so a wrong panel is visibly stale.
|
||||
- Blocker badge: `waits on AUD-163`, read per task; when the blocker finishes but the task is still marked blocked the badge shows `ready`.
|
||||
- Needs-you card: one per decision (refused merge, task awaiting answer, ready-but-stuck task), says what happened and the one key that acts.
|
||||
- Composer: `textarea`, Enter sends, Shift-Enter new line, stated in footer.
|
||||
- Diff view: file headers, hunks, line numbers, additions/deletions marked by a leading character as well as colour; large diffs state how many lines were omitted and offer a key for all.
|
||||
- Result receipt: server's own words on failure, never paraphrased.
|
||||
- Health row: pass / fail / **not run** (three states; "not run" is not "pass").
|
||||
|
||||
**Styling:** one theme with semantic roles (text, muted, accent, success, warning, error, surface), light and dark variants from the start. One cell horizontal padding, one blank line between sections, none between rows. Columns computed from content, never hardcoded width. Truncation always visible with full text one key away. Only spinner and selection cursor animate. No colour without meaning a state.
|
||||
|
||||
**Sizes:** every panel declares a minimum useful size (task tree 30x10, diff 40x12, form 50x14); below it the panel draws its own short message naming what it has and what it needs, never a broken layout. Workspace minimum is 80x24.
|
||||
|
||||
**Responsive layout by width:** >=150 cols two/three panels side by side (tree beside summary with Needs you under tree; run log beside diff). 110-149: two panels per workspace, third becomes a tab inside the same-kind panel. 80-109: one panel per workspace full width in order Board, Work, Conversation, Author. Below 80x24: one message.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 90%
|
||||
- Reason: Rich discovery of the interface spec, component constraints, styling rules, and sizing/layout behaviour; anchors future implementation.
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -88,3 +88,30 @@ Say which layout you want, and I will build it — starting with the width-drive
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
|
||||
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Update (2026-11-10 02:04:26)
|
||||
|
||||
Rewrote `docs/UI-LAYOUT.md` (348 lines, commit b44bf73 "Interface specification: six workspaces, twenty-seven interface items, styling and keys") as the single interface document for the Paperclip Harness TUI, replacing the earlier layout note rather than adding a second one.
|
||||
|
||||
Deliverables: six workspaces, twenty-seven interface items each with purpose, Charmbracelet component, and empty/loading/failed behaviour, a semantic styling system, per-panel minimum sizes, and width-responsive layout rules.
|
||||
|
||||
Validation: discovered actual Bubbles/Lipgloss component availability by listing the vendored module sources (confirmed no tabs component) before writing the spec.
|
||||
|
||||
Follow-up: four open decisions (tree-driven navigation via `.harness/harness.toml` `watching` key, six vs fewer workspaces, glyph set verified against real font, diff panel placement) must be answered, then build Board first with the styling system established before the second panel.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 85%
|
||||
- Reason: Concrete completed deliverable with commit, path, and follow-ups.
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
type: decision
|
||||
id: decision.paperclip-harness.paperclip-harness-ui-six-workspaces-spec-first-four-panel-li
|
||||
title: Paperclip Harness UI: six workspaces, spec-first, four-panel limit
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/decision
|
||||
- paperclip-harness
|
||||
- tui
|
||||
- ui-design
|
||||
- workspaces
|
||||
- architecture
|
||||
---
|
||||
|
||||
# Paperclip Harness UI: six workspaces, spec-first, four-panel limit
|
||||
|
||||
The Paperclip Harness TUI is grouped by user activity, not data source, into six workspaces:
|
||||
|
||||
| Workspace | Question | Panels |
|
||||
|---|---|---|
|
||||
| Board | state of the work / what needs me | Task tree, Task summary, Needs you |
|
||||
| Work | what is happening / what changed | Run log, Diff, Worktree facts |
|
||||
| Conversation | what was said / reply | Thread, Composer, Task header |
|
||||
| Author | what am I asking / how judged | Task form, Guidance, Preview |
|
||||
| Project | folder, machine, limits, cost | Project facts, Costs, Settings |
|
||||
| Repair | layout sound / what broke | Layout map, Health, Log |
|
||||
|
||||
The shell workspace remains for moments needing a prompt.
|
||||
|
||||
Decision: maximum four panels per workspace (a fifth item becomes a view inside a panel or a new workspace). Spec-first workflow: every claim that "it works" is run once in TUIOS before relying on it, but no exploratory testing. The look/style system is established before the second panel exists so it does not drift per screen. Build order: Board first, in document order.
|
||||
|
||||
Rationale: more than four panels cannot be read at once; grouping by activity keeps related concerns together. Alternatives considered: fewer than six workspaces (rejected: switching views inside panels hides state).
|
||||
|
||||
Open questions before build: (1) does the tree drive other workspaces (proposal: Enter writes `watching = AUD-163` into the project's `.harness/harness.toml`, asks TUIOS to show Conversation, panels reload on file change); (2) six workspaces or fewer; (3) glyph set must be checked against the actual machine font, not assumed; (4) diff as its own panel in Work or a tab beside run log.
|
||||
|
||||
Review caveat: all of this is a specification, not yet implemented.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 90%
|
||||
- Reason: Explicit design decision with rationale, alternatives, and open questions; durable for future build work.
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -92,3 +92,84 @@ Say which layout you want, and I will build it — starting with the width-drive
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
|
||||
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Update (2026-11-10 02:04:26)
|
||||
|
||||
## Structural/configuration observations (2026-11-10 02:04:26)
|
||||
|
||||
You are right to call it, and I will not push back on the substance: the last few turns drifted into proving commands rather than designing the thing. Here is the line I would hold, briefly — when a claim reaches you as "it works", it gets run once in TUIOS, because a spec built on an unproven assumption is the failure that cost you three restarts. One check per claim. Not exploratory testing. Everything else, spec first.
|
||||
|
||||
I have rewritten `docs/UI-LAYOUT.md` as the single interface document (348 lines, replacing the earlier layout note rather than adding a second one).
|
||||
|
||||
## How it is grouped
|
||||
|
||||
By what you are doing, not by which system the data came from:
|
||||
|
||||
| Workspace | Question it answers | Panels |
|
||||
|---|---|---|
|
||||
| **Board** | what is the state of the work, what needs me | Task tree · Task summary · Needs you |
|
||||
| **Work** | what is happening now, what changed | Run log · Diff · Worktree facts |
|
||||
| **Conversation** | what was said, what do I say back | Thread · Composer · Task header |
|
||||
| **Author** | what am I asking for, how will it be judged | Task form · Guidance · Preview |
|
||||
| **Project** | which folder, machine, limits, cost | Project facts · Costs · Settings |
|
||||
| **Repair** | is the layout sound, what broke | Layout map · Health · Log |
|
||||
|
||||
Six, not sixteen. Four panels maximum per workspace, and the shell workspace stays for the moments you need a prompt. More than four panels cannot be read at once, so a fifth thing becomes a view inside a panel or a new workspace.
|
||||
|
||||
## The interface items
|
||||
|
||||
Twenty-seven, each with a purpose, its Charmbracelet component, and its empty, loading and failed behaviour. The ones that matter most:
|
||||
|
||||
- **Panel frame** — rounded border and bright edge when focused, plus the word `focus` in the title, so focus never depends on colour alone.
|
||||
- **Footer key hints** — built from `help` and `key.Binding`, so a key that would do nothing is not shown.
|
||||
- **Stale marker** — the time of the last successful read, in the panel title. A wrong panel is visibly stale instead of quietly wrong.
|
||||
- **Blocker badge** — `waits on AUD-163`, read per task; when the blocker finishes but the task is still marked blocked the badge changes to `ready`, because that is our most confusing state.
|
||||
- **Needs-you card** — one per decision: a refused merge, a task waiting on an answer, a task ready but stuck. Each says what happened and the one key that acts.
|
||||
- **Composer** — `textarea`, Enter sends, Shift-Enter new line, stated in the footer because a text area normally does the opposite.
|
||||
- **Diff view** — file headers, hunks, line numbers, additions and deletions marked by a leading character as well as colour; a large diff says how many lines it left out and offers a key for all of it.
|
||||
- **Result receipt** — the server's own words on failure, never a paraphrase.
|
||||
- **Health row** — pass, fail, or **not run**, three states, because "not run" is not "pass".
|
||||
|
||||
Components: `list` for rows and decisions, `table` for figures, `viewport` for anything scrollable, `textarea` for the composer, `textinput` for single-line fields, `help` and `key` for the footer, `spinner` and `progress` for feedback. One honest note: there is no tabs component in this collection, so a view switcher inside a panel is Lipgloss and `help` styling, not a Bubbles widget.
|
||||
|
||||
## Styling
|
||||
|
||||
One theme with semantic roles (text, muted, accent, success, warning, error, surface) and a light and dark variant from the start. One cell of horizontal padding, one blank line between sections, no blank line between rows. Columns computed from the content in view, never a hardcoded width. Truncation always ends visibly and the full text is one key away. Only two things animate: the spinner and the selection cursor. No colour that does not mean a state.
|
||||
|
||||
## Sizes
|
||||
|
||||
Every panel declares a smallest useful size (the task tree needs 30 by 10, the diff 40 by 12, the form 50 by 14). Below it, the panel draws its own short message naming what it has and what it needs — never a broken layout, never a scrollbar to hide the problem. The workspace needs 80 by 24.
|
||||
|
||||
## Layout follows the width
|
||||
|
||||
150 columns and wider: tree beside summary with Needs you under the tree; run log beside diff. 110 to 149: two panels per workspace, the third becomes a tab inside the panel of the same kind. 80 to 109: one panel per workspace, full width, in the order Board, Work, Conversation, Author. Below 80 by 24: one message.
|
||||
|
||||
## Four decisions before I build
|
||||
|
||||
1. **Does the tree drive the other workspaces?** Proposal: Enter writes `watching = AUD-163` into the project's `.harness/harness.toml` and asks TUIOS to show Conversation; the other panels reload when that file changes. One fact, one owner, survives a restart.
|
||||
2. **Six workspaces, or fewer?** Fewer means switching views inside panels, which hides state.
|
||||
3. **Which glyph set?** Must be checked against the font on the machine you actually sit at, not assumed.
|
||||
4. **Diff: its own panel in Work, or a tab beside the run log?**
|
||||
|
||||
Answer those four and I will build Board first, in the order the document lists, with the styling system established before the second panel exists — so the look is settled once instead of drifting per screen.
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 82%
|
||||
- Reason: Captured factual repo structure/configuration patterns from rich discovery
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
type: session
|
||||
id: session.paperclip-harness.rich-discovery-home-2026-11-10-02-04-26
|
||||
title: Rich discovery: home 2026-11-10 02:04:26
|
||||
status: active
|
||||
source_of_truth: false
|
||||
freshness: current
|
||||
last_reviewed: 2026-11-10
|
||||
tags:
|
||||
- pack/paperclip-harness
|
||||
- agent-memory/session
|
||||
- autolearn
|
||||
- rich-discovery
|
||||
- repo/home
|
||||
---
|
||||
|
||||
# Rich discovery: home 2026-11-10 02:04:26
|
||||
|
||||
Sanitized rich discovery snapshot captured automatically from the completed turn.
|
||||
|
||||
|
||||
## Source paths observed
|
||||
|
||||
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
|
||||
|
||||
## Final answer snapshot
|
||||
|
||||
You are right to call it, and I will not push back on the substance: the last few turns drifted into proving commands rather than designing the thing. Here is the line I would hold, briefly — when a claim reaches you as "it works", it gets run once in TUIOS, because a spec built on an unproven assumption is the failure that cost you three restarts. One check per claim. Not exploratory testing. Everything else, spec first.
|
||||
|
||||
I have rewritten `docs/UI-LAYOUT.md` as the single interface document (348 lines, replacing the earlier layout note rather than adding a second one).
|
||||
|
||||
## How it is grouped
|
||||
|
||||
By what you are doing, not by which system the data came from:
|
||||
|
||||
| Workspace | Question it answers | Panels |
|
||||
|---|---|---|
|
||||
| **Board** | what is the state of the work, what needs me | Task tree · Task summary · Needs you |
|
||||
| **Work** | what is happening now, what changed | Run log · Diff · Worktree facts |
|
||||
| **Conversation** | what was said, what do I say back | Thread · Composer · Task header |
|
||||
| **Author** | what am I asking for, how will it be judged | Task form · Guidance · Preview |
|
||||
| **Project** | which folder, machine, limits, cost | Project facts · Costs · Settings |
|
||||
| **Repair** | is the layout sound, what broke | Layout map · Health · Log |
|
||||
|
||||
Six, not sixteen. Four panels maximum per workspace, and the shell workspace stays for the moments you need a prompt. More than four panels cannot be read at once, so a fifth thing becomes a view inside a panel or a new workspace.
|
||||
|
||||
## The interface items
|
||||
|
||||
Twenty-seven, each with a purpose, its Charmbracelet component, and its empty, loading and failed behaviour. The ones that matter most:
|
||||
|
||||
- **Panel frame** — rounded border and bright edge when focused, plus the word `focus` in the title, so focus never depends on colour alone.
|
||||
- **Footer key hints** — built from `help` and `key.Binding`, so a key that would do nothing is not shown.
|
||||
- **Stale marker** — the time of the last successful read, in the panel title. A wrong panel is visibly stale instead of quietly wrong.
|
||||
- **Blocker badge** — `waits on AUD-163`, read per task; when the blocker finishes but the task is still marked blocked the badge changes to `ready`, because that is our most confusing state.
|
||||
- **Needs-you card** — one per decision: a refused merge, a task waiting on an answer, a task ready but stuck. Each says what happened and the one key that acts.
|
||||
- **Composer** — `textarea`, Enter sends, Shift-Enter new line, stated in the footer because a text area normally does the opposite.
|
||||
- **Diff view** — file headers, hunks, line numbers, additions and deletions marked by a leading character as well as colour; a large diff says how many lines it left out and offers a key for all of it.
|
||||
- **Result receipt** — the server's own words on failure, never a paraphrase.
|
||||
- **Health row** — pass, fail, or **not run**, three states, because "not run" is not "pass".
|
||||
|
||||
Components: `list` for rows and decisions, `table` for figures, `viewport` for anything scrollable, `textarea` for the composer, `textinput` for single-line fields, `help` and `key` for the footer, `spinner` and `progress` for feedback. One honest note: there is no tabs component in this collection, so a view switcher inside a panel is Lipgloss and `help` styling, not a Bubbles widget.
|
||||
|
||||
## Styling
|
||||
|
||||
One theme with semantic roles (text, muted, accent, success, warning, error, surface) and a light and dark variant from the start. One cell of horizontal padding, one blank line between sections, no blank line between rows. Columns computed from the content in view, never a hardcoded width. Truncation always ends visibly and the full text is one key away. Only two things animate: the spinner and the selection cursor. No colour that does not mean a state.
|
||||
|
||||
## Sizes
|
||||
|
||||
Every panel declares a smallest useful size (the task tree needs 30 by 10, the diff 40 by 12, the form 50 by 14). Below it, the panel draws its own short message naming what it has and what it needs — never a broken layout, never a scrollbar to hide the problem. The workspace needs 80 by 24.
|
||||
|
||||
## Layout follows the width
|
||||
|
||||
150 columns and wider: tree beside summary with Needs you under the tree; run log beside diff. 110 to 149: two panels per workspace, the third becomes a tab inside the panel of the same kind. 80 to 109: one panel per workspace, full width, in the order Board, Work, Conversation, Author. Below 80 by 24: one message.
|
||||
|
||||
## Four decisions before I build
|
||||
|
||||
1. **Does the tree drive the other workspaces?** Proposal: Enter writes `watching = AUD-163` into the project's `.harness/harness.toml` and asks TUIOS to show Conversation; the other panels reload when that file changes. One fact, one owner, survives a restart.
|
||||
2. **Six workspaces, or fewer?** Fewer means switching views inside panels, which hides state.
|
||||
3. **Which glyph set?** Must be checked against the font on the machine you actually sit at, not assumed.
|
||||
4. **Diff: its own panel in Work, or a tab beside the run log?**
|
||||
|
||||
Answer those four and I will build Board first, in the order the document lists, with the styling system established before the second panel exists — so the look is settled once instead of drifting per screen.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Confidence: 86%
|
||||
- Reason: Preserve full sanitized discovery detail from a rich investigation turn
|
||||
|
||||
## Related
|
||||
|
||||
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
|
||||
|
||||
## Related learned memories <!-- same-turn-2026-11-10 02:04:26 -->
|
||||
|
||||
- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Paperclip Harness UI: six workspaces, spec-first, four-panel limit]]
|
||||
- context: [[packs/paperclip-harness/20-context/paperclip-harness-interface-spec-docs-ui-layout-md|Paperclip Harness interface spec (docs/UI-LAYOUT.md)]]
|
||||
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote interface specification to docs/UI-LAYOUT.md]]
|
||||
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-02-04-26|Rich discovery: home 2026-11-10 02:04:26]]
|
||||
- context: [[packs/paperclip-harness/20-context/home|home]]
|
||||
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|home repository structure and configuration patterns]]
|
||||
@@ -20,8 +20,17 @@ defined in "Words we use".
|
||||
- **Fact** — a piece of truth with exactly one owner. Tasks, blockers, comments, runs,
|
||||
costs and worktrees belong to Paperclip.
|
||||
|
||||
A workspace holds at most **four** panels. More than four cannot be read at a glance on
|
||||
one screen, so a fifth thing to look at becomes a view inside a panel, or a new workspace.
|
||||
A workspace holds as many panels as the work in it needs. **Four side by side is a good
|
||||
default**, because more than four at once stops being readable — but it is not a rule.
|
||||
When a workspace needs a fifth thing, there are three honest choices, and all of them are
|
||||
allowed:
|
||||
|
||||
- **a tab** inside an existing panel, for another view of the same kind of content;
|
||||
- **a tool panel** that opens beside the others and closes again when it is done;
|
||||
- **zoom**, which is TUIOS's own key, for the moment a panel needs the whole screen.
|
||||
|
||||
The only rule is that everything in a workspace belongs to the same question. If a panel
|
||||
does not help with that question, it belongs in another workspace.
|
||||
|
||||
---
|
||||
|
||||
@@ -41,7 +50,7 @@ That gives six workspaces. They are deliberately fewer than the number of things
|
||||
show, because a person who cannot find the screen they need has gained nothing from more
|
||||
screens.
|
||||
|
||||
| Workspace | The question it answers | Panels (maximum four) |
|
||||
| Workspace | The question it answers | Panels (a good default set, not a limit) |
|
||||
|---|---|---|
|
||||
| **Board** | what is the state of the work, and what needs me | Task tree · Task summary · Needs you |
|
||||
| **Work** | what is happening now, and what changed | Run log · Diff · Worktree facts |
|
||||
@@ -53,6 +62,28 @@ screens.
|
||||
The **shell** workspace stays as it is: one pane with a prompt in the project folder, for
|
||||
the moments when the person needs a shell and should not have to leave.
|
||||
|
||||
Inside a workspace, panels are either **side by side** or **stacked as tabs**, and the
|
||||
person switches between tabs without leaving the workspace. A tab is not a second-class
|
||||
panel: it has the same frame, the same footer and the same focus marker as any other.
|
||||
|
||||
## Tools that open as panels
|
||||
|
||||
Several things the person needs already exist as good terminal programs, and wrapping them
|
||||
would be worse than opening them. Each opens in the current workspace, next to what is
|
||||
already there, and closes when it is done. This is the "many panels can simply be terminal
|
||||
tools" idea from the product statement, done deliberately rather than by accident.
|
||||
|
||||
| Tool | What it is for | Opens with |
|
||||
|---|---|---|
|
||||
| **Lazygit** | branches, commits, staging, history, in the project folder | `t` then choosing it |
|
||||
| **Hunk** | reading a pull request or a branch change as a review | `t` then choosing it |
|
||||
| **shell** | any command the panel does not cover | `t` then choosing it |
|
||||
| **git log and diff** | the task's branch without leaving the interface | `t` then choosing it |
|
||||
| **ocr** | the review of the current change, as it runs | `t` then choosing it |
|
||||
|
||||
Both Lazygit and Hunk are already installed on this machine, and Hunk is a flake input of
|
||||
the system configuration. Neither is ours to rebuild.
|
||||
|
||||
---
|
||||
|
||||
## The user interface items
|
||||
@@ -169,11 +200,33 @@ a bug.
|
||||
**26. Error state.** The failed thing, the exact message, and the one action that is still
|
||||
possible, such as retry or open the Repair workspace.
|
||||
|
||||
### Working with several panels
|
||||
|
||||
**28. Tab strip.** For a panel holding more than one view: a single line of named tabs
|
||||
with the current one marked, switched with `[` and `]` while the panel has focus.
|
||||
Implemented in Lipgloss and styled like the panel frame. A tab name is a word, never a
|
||||
number, so it survives being read aloud.
|
||||
|
||||
**29. Tool panel.** A panel that runs an existing terminal program — Lazygit, Hunk, a
|
||||
shell, a git command, or the running review. It opens on demand in the current workspace,
|
||||
takes focus when it opens, and gives focus back when it closes. It runs the real program,
|
||||
so it is not styled by us and does not pretend to be.
|
||||
|
||||
**30. Panel closer.** Every tool panel says how to close it in its own footer (`q` or
|
||||
`esc`), and closing it returns the workspace to exactly the arrangement it had before,
|
||||
with focus where it was.
|
||||
|
||||
### Icons
|
||||
|
||||
**27. Glyphs.** A small set used consistently: running, waiting, blocked, done, failed,
|
||||
unread. Taken from the glyph set TUIOS reports, with an ASCII fallback, and never the only
|
||||
carrier of meaning. Checked with `tuios list-glyphs` before use, not assumed.
|
||||
unread. Never the only carrier of meaning.
|
||||
|
||||
Measured on this machine, and this matters: TUIOS offers four glyph sets — `ascii`,
|
||||
`default`, `heavy` and `unicode` — and `default` is active. Starship is **not installed
|
||||
here**, and no Nerd Font is present (`fc-list` finds none), so an icon set that expects a
|
||||
patched font would draw empty boxes. Until a Nerd Font is installed deliberately, the
|
||||
interface uses TUIOS's `default` set, which is ordinary Unicode: `╭ ╮ ✕ ▎ ● › …`, with
|
||||
`ascii` as the fallback.
|
||||
|
||||
---
|
||||
|
||||
@@ -251,6 +304,8 @@ them. A bare Esc must stay free, because it closes a box.
|
||||
| Where | Key | Does |
|
||||
|---|---|---|
|
||||
| Any panel | Tab, Shift-Tab | move focus to the next or previous panel |
|
||||
| Any panel | [ and ] | previous or next tab, in a panel that has tabs |
|
||||
| Any panel | t | open a tool panel here: shell, Lazygit, Hunk, git, review |
|
||||
| Any panel | ? | show the keys for this panel |
|
||||
| Any panel | r | read again from Paperclip |
|
||||
| Any panel | q | leave this panel's program, returning the pane to its shell |
|
||||
@@ -270,7 +325,9 @@ them. A bare Esc must stay free, because it closes a box.
|
||||
| Destructive | typed word | confirm |
|
||||
|
||||
No key means two things in two panels. Where a panel needs a key that is taken, it uses a
|
||||
different one rather than overloading.
|
||||
different one rather than overloading. **Zoom is not ours**: `z` belongs to TUIOS, and the
|
||||
interface relies on it rather than reimplementing it. The same is true of switching
|
||||
workspaces: TUIOS does that, and the interface only shows where you are.
|
||||
|
||||
---
|
||||
|
||||
@@ -299,28 +356,53 @@ program never draws a broken layout and never invents a scrollbar to hide the pr
|
||||
The workspace itself needs 80 columns by 24 rows. Below that, the whole workspace shows one
|
||||
message naming the size it has and the size it needs.
|
||||
|
||||
Tabs change the arithmetic in a useful way: two panels tabbed into one cost the space of
|
||||
one panel, so a narrow workspace keeps its content by tabbing rather than by shrinking.
|
||||
That is why tabs are part of the design and not a workaround.
|
||||
|
||||
---
|
||||
|
||||
## Layout, once the panels are settled
|
||||
## How the panels sit together
|
||||
|
||||
The panels above do not fit in one workspace, and should not. Layout is chosen by the
|
||||
width of the terminal, so the person gets as much as their screen can carry and never a
|
||||
layout pretending to have room it does not.
|
||||
Layout follows the width of the terminal, so the person gets as much as their screen can
|
||||
carry and never a layout pretending to have room it does not.
|
||||
|
||||
- **150 columns and wider:** Board shows tree and summary side by side with Needs you under
|
||||
the tree. Work shows run log and diff side by side. Conversation shows thread above
|
||||
composer with the task header above both.
|
||||
- **110 to 149 columns:** two panels per workspace at most; the third becomes a view
|
||||
switched with a tab inside the panel that shares its kind of content.
|
||||
- **80 to 109 columns:** one panel per workspace at full width, in the order Board, Work,
|
||||
Conversation, Author.
|
||||
- **150 columns and wider:** Board shows the task tree and task summary side by side, with
|
||||
Needs you tabbed under the tree. Work shows the run log beside the diff. Conversation
|
||||
shows the thread above the composer, with the task header above both.
|
||||
- **110 to 149 columns:** at most two panels side by side; the third becomes a tab in the
|
||||
panel that holds the same kind of content.
|
||||
- **80 to 109 columns:** one panel at full width, with the others tabbed beside it, in the
|
||||
order the work happens: Board, Work, Conversation, Author.
|
||||
- **Below 80 by 24:** one message, nothing else.
|
||||
|
||||
The exact three candidate arrangements are drawn in the earlier note and are still valid
|
||||
for the wide case; what changes here is that the panels themselves are now defined, so the
|
||||
layout is a matter of which panels share a workspace rather than what a panel contains.
|
||||
Two arrangements we already know we want, because they are the moments the person is
|
||||
actually in:
|
||||
|
||||
---
|
||||
- **Reading a claim and its code.** Task tree on the left, thread on the upper right, diff
|
||||
on the lower right. The only arrangement where a claim and the change that backs it are
|
||||
on screen together.
|
||||
- **Deciding.** Needs you on the left with the task it concerns beside it, so the decision
|
||||
card and the evidence are never on different workspaces.
|
||||
|
||||
## What happens when you pick a task
|
||||
|
||||
Plainly: **choosing a task changes what the other panels show.** Pick a task in the task
|
||||
tree, and the summary, the thread, the run log, the diff and the worktree facts all switch
|
||||
to that task. Nothing else has to be typed, and no screen has to be told twice.
|
||||
|
||||
The rest is implementation, and it is written down only so the behaviour can be trusted:
|
||||
|
||||
- the chosen task is remembered in the project's own `.harness/harness.toml`, as one line
|
||||
naming its identifier;
|
||||
- the other panels re-read when that line changes, within about a second;
|
||||
- the choice survives a restart or a lost pane, because it is on disk and not in memory;
|
||||
- if the chosen task is ever deleted, the panels fall back to the most active task in the
|
||||
project rather than showing an error.
|
||||
|
||||
That is the whole mechanism. It is one line in one file, it is not a second copy of
|
||||
anything Paperclip owns, and it can be inspected with a text editor when something looks
|
||||
wrong.
|
||||
|
||||
## What is not in this version, deliberately
|
||||
|
||||
@@ -331,18 +413,27 @@ layout is a matter of which panels share a workspace rather than what a panel co
|
||||
- No settings for colours: one theme, two variants, no per-panel colour choices.
|
||||
- No dashboards of figures with nothing to act on: every number sits next to the thing it
|
||||
describes.
|
||||
- No replacement for Lazygit or Hunk: they open as tool panels.
|
||||
|
||||
---
|
||||
## Decided, and what is still open
|
||||
|
||||
## Decisions needed before building
|
||||
Decided by the person, 2026-11-10:
|
||||
|
||||
1. **Does the tree drive the other workspaces?** Proposal: pressing Enter writes the chosen
|
||||
task's identifier into the project's `.harness/harness.toml` as `watching`, and asks
|
||||
TUIOS to show the Conversation workspace. The other panels watch that file and reload
|
||||
when it changes. One fact, one owner, no message bus, and it survives a restart.
|
||||
2. **Six workspaces, or fewer?** The proposal is six. Fewer means more switching inside a
|
||||
panel, which costs a key and hides state.
|
||||
3. **Which glyph set?** Depends on the font in the terminal; must be checked with
|
||||
`tuios list-glyphs` on the machine the person actually uses.
|
||||
4. **Is the diff a panel or a view inside the Work workspace?** A panel never squeezes the
|
||||
run log; a view keeps the workspace count down.
|
||||
1. **Switching inside a workspace is wanted.** Tabs and zoom are part of the design, and a
|
||||
workspace may hold more than four panels when the work in it needs them.
|
||||
2. **Grouping matters more than panel count.** A workspace earns its place by answering one
|
||||
question well.
|
||||
3. **Picking a task updates the other panels.** That is the behaviour described above.
|
||||
4. **Lazygit and Hunk belong inside the interface**, as tool panels, not as things the
|
||||
person leaves for a shell.
|
||||
|
||||
Still open:
|
||||
|
||||
1. **Glyphs.** Measured: TUIOS has `ascii`, `default`, `heavy` and `unicode`; `default` is
|
||||
active. Starship is not installed here and no Nerd Font is present. So the interface
|
||||
uses the `default` set with an `ascii` fallback unless a Nerd Font is installed on
|
||||
purpose. If Starship's look is wanted, that is a system change first, then a glyph set.
|
||||
2. **Which panel wins when the terminal is narrow.** Proposal: the one that answers the
|
||||
workspace's question, with the rest tabbed rather than hidden.
|
||||
3. **The order of tabs** in each workspace. Proposal: the order in which the work happens —
|
||||
what it is, what it says, what it changed.
|
||||
|
||||
Reference in New Issue
Block a user