sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
031073fc46663a6117d51ab9dfc9dd0cb9c8afdd
paperclip-harness/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md

22 KiB
Raw Blame History

type, id, title, status, source_of_truth, freshness, last_reviewed, tags
type id title status source_of_truth freshness last_reviewed tags
observation observation.paperclip-harness.tmp-repository-structure-and-configuration-patterns tmp repository structure and configuration patterns active false current 2026-11-10
pack/paperclip-harness
agent-memory/observation
autolearn
rich-discovery
repo/tmp

tmp repository structure and configuration patterns

Structural/configuration observations (2026-11-10 01:47:01)

That notification is the failed Explore agent finishing late — the one that returned nothing because claude-haiku-4.5 404s. Nothing new in it; I did that reading myself.

Meanwhile I did what you asked next: the interface spec and the mockups.

docs/UI-LAYOUT.md

It opens with the only four questions the interface is allowed to answer — what is the state of the work, what is happening now, what needs me, what do I do about it — then a table pinning every fact to its one owner:

shown read from never
tasks, status, assignee company issue list a folder name
blockers issues/{id}/diagnostics/blockers, per task the list
thread issues/{id}/comments a copy
run state issues/{id}/runs a log we write
cost issues/{id}/cost-summary our arithmetic
what changed git in the task's worktree a stored diff
folder, machine, session, watched task .harness/harness.toml Paperclip

Then a table per pane: what it must show and which keys it may use, with h j k l z n reserved for TUIOS and a bare Esc free.

Three layouts, live in your session

They are running now on workspaces 6, 7, 8 (mock-A, mock-B, mock-C), and as images:

/tmp/mockups/A.png  /tmp/mockups/B.png  /tmp/mockups/C.png
  • A — one page each. What exists today. Whole width per page, works at 80 columns. Costs a keystroke to look at the tree while replying.
  • B — cockpit: tree beside conversation. Tree 34% left, thread and reply box right, ⤷ markers under each task showing what it waits on. Log and diff one workspace away.
  • C — cockpit with the change visible. Tree 28%, thread top right, diff bottom right — a claim and the code behind it in one glance. Needs width; below ~120 columns the diff half is unreadable.

Recommendation in the doc: C, falling back to B, falling back to A, chosen by the pane's actual width — 150+, 110–149, 80–109, and the "too small" screen below 80×24. The person gets as much as the terminal can carry, never a layout pretending to have room it does not.

Two decisions I need from you

  1. Is the diff its own pane, or the bottom half of the log? A separate pane never squeezes the log for a long diff, but costs a workspace. C only works if the diff can share a page with the reply.
  2. Does the tree drive the other panes? My proposal: enter on a task writes watching = AUD-163 into the project's harness.toml and asks TUIOS to switch to the reply page; the reply, log and diff panes watch that file and reload when it changes. One fact, one owner, no message bus — but it means a file is the hand-off, so say if you would rather each pane be told directly.

Also still open from earlier: whether the four screens stay four workspaces or become two.

Say which layout you want, and I will build it — starting with the width-driven choice, since that is what makes it survive being used in a small pane.

Source paths observed

  • tmp/pi-subagents-1000/home-sam-paseo-projects-paperclip-harness/01a1c288-74f9-75ae-ba9a-a501d66bc3b5/tasks/87e640dd-8043-41e.output
  • home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md
  • tmp/mockups/A.txt
  • tmp/mockups/B.txt
  • tmp/mockups/C.txt
  • tmp/mockups/A.png
  • tmp/mockups/B.png
  • tmp/mockups/C.png

Evidence

  • Confidence: 82%
  • Reason: Captured factual repo structure/configuration patterns from rich discovery

Related

Related learned memories

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

Update (2026-11-10 02:26:18)

Structural/configuration observations (2026-11-10 02:26:18)

Taken, and folded into docs/UI-LAYOUT.md (now 440 lines, committed as 5b82900).

The four-panel rule is gone

A workspace holds what the work in it needs. Four side by side is a good default because more than four stops being readable, but a workspace that needs a fifth thing has three allowed answers — a tab, a tool panel that closes when done, or TUIOS's zoom. Tabs are specified as first-class: same frame, same footer, same focus marker, switched with [ and ] while the panel has focus, and named with words rather than numbers.

The only rule left is that everything in a workspace helps answer the same question. If it does not, it belongs in another workspace.

Your first point, in plain words

I meant exactly what you said: choosing a task changes what the other panels show. Pick a task in the tree, and the summary, the thread, the run log, the diff and the worktree facts all switch to it. Nothing has to be typed twice.

The spec now leads with that sentence. The mechanism is described after it, in one short paragraph: the chosen task is remembered as one line in the project's own .harness/harness.toml, the other panels re-read when it changes, and the choice survives a restart or a lost pane. If a chosen task is deleted, the panels fall back to the most active task instead of showing an error.

Glyphs: you are wrong about one thing, and it matters

Measured just now on this machine:

  • starship is not installed and there is no ~/.config/starship.toml.
  • No Nerd Font is present — fc-list | grep -i nerd returns nothing.
  • TUIOS offers four glyph sets: ascii, default, heavy, unicode. default is active and uses ordinary Unicode: ╭ ╮ ✕ ▎ ● › ….

So Starship-style icons would draw empty boxes today. The spec says: use TUIOS's default set with ascii as the fallback, and if you want the Starship look, installing a Nerd Font is a system change to do deliberately first, then we pick a glyph set. Tell me if you want that and I will prepare it.

Hunk and Lazygit: yes, and they are installed

They were already in your own product statement — "We need a page where we can interact with the Gitea and similar. Hunk, LazyGit etc." — and both are present: lazygit in the system packages, hunk as a flake input at /etc/profiles/per-user/sam/bin/hunk.

They are now specified as tool panels: opened with t in the current workspace, they take focus when they open, run the real program rather than a copy, and give focus back to exactly where it was when closed. Also available this way: a shell, git log and git diff for the task's branch, and the review as it runs.

Two arrangements I added, because they are what you actually do

  • Reading a claim and its code — task tree left, thread upper right, diff lower right. The only place a claim and the change behind it are on screen at once.
  • Deciding — Needs you on the left, the task it concerns beside it, so a decision and its evidence never sit on different workspaces.

Zoom stays TUIOS's own key; we rely on it rather than reimplementing it, and the same is true of switching workspaces.

Next

I build the Board workspace first, and the visual language with it — frame, focus, tab strip, footer hints, stale marker, rows and badges — so the look is settled once instead of drifting screen by screen. Then I put it in your session and you look at it before I start the second workspace. Say go.

Source paths observed

  • etc/profiles/per-user/sam/bin/hunk
  • run/current-system/sw/bin/lazygit
  • run/current-system/sw/bin/git
  • home/sam/.local/bin/ocr
  • etc/nixos/configuration.nix
  • etc/nixos/flake.nix
  • home/sam/.config/tuios/glyphs

Evidence

  • Confidence: 82%
  • Reason: Captured factual repo structure/configuration patterns from rich discovery

Related learned memories

Update (2026-11-10 03:01:16)

Bugs found and fixed in paperclip-harness (committed 4e3c955):

  • If the worktree folder was removed, git rev-parse --abbrev-ref HEAD returns exit status 128; the change tab now says "the task's folder … no longer exists" instead of showing raw exit code.
  • Table columns looked ragged because styled text was being padded by bytes. Rule: pad plain text first, apply colour after.

Caution on tuios set-config: tuios set-config theme catppuccin_mocha fails with "set_config came from host nixos-desktop and would change this machine, not the session". Using it on the live session risks changing the machine config rather than the session. Set theme in ~/.config/tuios/config.toml instead; new sessions pick it up, but the running session needs a restart.

Screenshots saved: /tmp/mockups/board-live.png, /tmp/mockups/work-live.png.

Other note: the font rebuild is still the user's to run: sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop.

Evidence

  • Confidence: 80%
  • Reason: Concrete discoveries/pitfalls for future agents.

Update (2026-11-10 03:01:16)

Structural/configuration observations (2026-11-10 03:01:16)

Three things answered, and the Work workspace is built.

Vim keys: yes, as aliases

j and k now move in both the Board and Work screens, and h and l switch tabs. They are aliases, not the primary keys, because whether they reach the program depends on TUIOS's mode: in window-management mode TUIOS keeps h j k l z n, and in terminal mode the program gets them. Use whichever arrives, and the footer says ↑↓ or j k so nobody has to guess. Arrow keys stay the primary path.

The theme confusion, cleared up

You changed something and it worked; I checked the wrong thing. tuios look is a saved appearance bundle, and "no look is applied" says nothing about the theme. The real answer was in ~/.config/tuios/config.toml:

theme = ''

So the config had no theme, which is why this session's chrome looked default. I have now set it:

theme = 'catppuccin_mocha'

New sessions pick it up. The running one needs a restart, and tuios set-config theme catppuccin_mocha refused with "set_config came from host nixos-desktop and would change this machine, not the session", so I left that alone rather than fight it. Our program is drawn in Catppuccin Mocha with a Latte variant (-theme light), so once the session restarts the chrome and the panels will match.

Styling changes

  • The board now reads at a glance: group headings are a label, a rule and a count (DONE───────── 6), rows are two lines, content sits one column inside the frame.
  • Three-column layout above 140 columns (tasks, chosen task, needs you), two columns below, so a wide terminal is used instead of wasted.
  • The Work screen has a tab bar, coloured run states, and diff lines coloured by kind — additions green, deletions red, hunk headers blue.
  • The footer shows only keys that apply in the current panel, and focus is a rounded bright edge plus ·focus·.

Work workspace

One screen, three tabs, tested on real data:

  • runs — a column table of every run with what woke it, start, end and duration, then the activity list with times in local time.
  • change — the task's worktree, branch, base, commits, changed-file counts, then the diff.
  • facts — folder, branch, base, status and cost.

It follows the Board without being told: the chosen task lives in the project's .harness/harness.toml, and the Work panel re-reads it every five seconds. I watched it switch from AUD-160 to AUD-165 after only that file changed, then show 520bc2d AUD-165: add cleanup.sh and the actual diff.

Two real bugs found by using it: a git that fails because the folder was removed now says "the task's folder … no longer exists" instead of a raw exit code, and a table whose columns were ragged because styled text was being padded by bytes — pad the plain text first, colour it second.

Screenshots: /tmp/mockups/board-live.png and /tmp/mockups/work-live.png. Committed as 4e3c955.

Still to do

The reply and new-task panels still use the older plain look — they need the same frame, tab bar and footer before the set is consistent. That is the next piece, and it is small because the frame already exists.

And the font rebuild is still yours to run:

sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop

Source paths observed

  • home/sam/paseo/projects/paperclip-harness/bin/harness
  • tmp/pc-sandbox-2026-11-10/.paperclip/worktrees/AUD-165-review-gate-pro
  • tmp/pc-sandbox-2026-11-10/.paperclip/worktrees/AUD-165-review-gate-
  • tmp/mockups/C.png
  • tmp/mockups/work-live.png
  • .config/tuios/config.toml
  • tmp/mockups/board-live.png

Evidence

  • Confidence: 82%
  • Reason: Captured factual repo structure/configuration patterns from rich discovery

Related learned memories

Reference in New Issue View Git Blame Copy Permalink