From 3d31243317de1c10bb9cda9e69cc7346bb65c3ba Mon Sep 17 00:00:00 2001 From: Sam Date: Tue, 10 Nov 2026 21:00:42 +1100 Subject: [PATCH] Findings: per-agent skills API, memory stack, MOUSE-1 policy, the old office scaffold, the dashboard endpoint --- .../20-context/paperclip-harness.md | 42 +++++++ .../packs/paperclip-harness/20-context/tmp.md | 87 ++++++++++++++ ...layout-md-and-three-live-layout-mockups.md | 34 ++++++ ...per-project-notes-skills-via-replace-no.md | 54 +++++++++ ...ry-structure-and-configuration-patterns.md | 87 ++++++++++++++ ...arness-functional-smoke-test-end-to-end.md | 107 +++++++++++++++++ .../70-runbooks/tmp-deployment-operations.md | 103 +++++++++++++++++ .../rich-discovery-tmp-2026-11-10-07-35-38.md | 106 +++++++++++++++++ .pi/settings.json | 3 +- docs/PLAN-INTERFACE.md | 109 ++++++++++++++++++ 10 files changed, 731 insertions(+), 1 deletion(-) create mode 100644 .pi/memory-vault/packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38.md diff --git a/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md b/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md index eb14d36..d59a7bc 100644 --- a/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md +++ b/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md @@ -178,3 +178,45 @@ TUIOS panes get a smaller PATH than the user shell — health checks should look - session: [[packs/paperclip-harness/80-sessions/paperclip-harness-reverted-pane-split-interface-gap-discover|Paperclip-harness — reverted pane split, interface gap discovery, and PLAN-INTERFACE roadmap]] - session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-10-05-41-48|Rich discovery: home 2026-11-10 05:41:48]] - context: [[packs/paperclip-harness/20-context/home|home]] + + +--- + +## Update (2026-11-10 07:35:38) + +paperclip-harness is a TUIOS-based Go control plane for Paperclip, living at /home/sam/paseo/projects/paperclip-harness (harness binary: bin/harness; also bin/office, bin/board, bin/merge). + +Workspaces (TUIOS pages) observed in a running session `tuios list-windows -s paperclip-harness`: shell, board, agents, reply, new, project, work, repair, plus additional shell panes. `R` from Repair>repair recreates the eight workspaces. + +Workspace / pane map (from assistant's answers): +- Agents>agents: agent roster, runs, log; 4th tab = per-agent settings (role, job title, model, monthly budget, heartbeat). `enter` edits field in place, `esc` cancels, `p` pause, `P` resume, `w` wake. Each save is ONE PATCH merged into the agent's existing config (changing model does not wipe folder/instructions). Spend is displayed in Project>costs, Board>board, Work>work — budget is SET per agent on the agents settings tab; there is no company-level spend control yet. +- New task>new: the only place to create tasks. Board>board: assign/blocker/dependent management. Work>work: diffs; Work>review: verdict. Repair>repair: diagnostics (checks control-plane reply, project file, harness binary, git, go, ocr, tuios, lazygit, hunk, Nerd Font count). +- Project>costs shows spend; proposal to add a spend-by-day chart there using Go (not TML) via tuios.dev/plot library. + +Paperclip API surfaces used: GET /api/agents/{id}/skills and POST /api/agents/{id}/skills/sync with `add`, `remove`, `replace` (the `replace` operation matches the rule that sub-agents get only the skills their job needs). + +Paperclip data model: companies → projects → tasks → agents → runs. Paperclip "workspace" = a project's code folder (git worktree a task runs in); TUIOS "workspace" = a page — do not conflate. + +Artifacts in Paperclip = work products attached to a task: uploaded file, pull request, preview URL, commit, branch. Nothing in the TUI displays them yet; home would be a Work>artifacts tab. + +Project config: each project folder has .harness/harness.toml and .harness/NOTES.md (the agreed place for freeform per-project notes, explicitly not tasks). + +Multi-machine context: known hosts referenced as .13, .27, .51 (e.g. office, nixos-desktop). Existing tool stack on the machine includes ocr, tuios, lazygit, hunk, yazi, nvim, fzf, go. + +TUIOS plugin libraries called out: PLOT, LOOM, TML, GO (prefer Go for in-TUI panels since the panels are already Go and data is in memory). + +## Evidence + +- Confidence: 90% +- Reason: Rich, evidence-backed component overview: workspace list, pane roles, API endpoints, data model, per-project config files, and host topology. + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md b/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md index cedd35b..1586072 100644 --- a/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md +++ b/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md @@ -681,3 +681,90 @@ Ready to discuss modifications whenever you are. - session: [[packs/paperclip-harness/80-sessions/paperclip-harness-tui-repair-session-border-overflow-review-|paperclip-harness TUI repair session: border overflow, review tab, tool panes]] - session: [[packs/paperclip-harness/80-sessions/rich-discovery-using-workspace-pane-from-here-on-2026-11-10-|Rich discovery: using-workspace-pane-from-here-on 2026-11-10 07:06:26]] - observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|using-workspace-pane-from-here-on repository structure and configuration patterns]] + + +--- + +## Update (2026-11-10 07:35:38) + +## Rich discovery update (2026-11-10 07:35:38) + +Both bugs fixed, and here are direct answers. + +## Fixed + +**Repair>repair** — the icon sample row is gone. + +**ocr closed instantly.** Two causes, both real: a tool pane is started with a smaller PATH than your shell, so `ocr` was "command not found", and even when it ran, a review with nothing to look at exits in a second. Tool panes now get `~/.local/bin`, `~/.nix-profile/bin`, the system profile and your per-user profile on PATH, and the ocr entry ends with a "press enter to close" line. It now runs and stays: + +``` +[ocr] 1 file(s) changed, reviewing 1 in /tmp/pc-sandbox-2026-11-10 +[ocr] ▶ code_search search_text=harness … +``` + +The chooser also gained `g` and `G`, which is what led me to open a second shell pane while testing. + +## Where settings are + +**`Agents>agents`, fourth tab, settings.** Role, job title, model, monthly budget, heartbeat. `enter` edits a field in place, `esc` cancels, `p`/`P`/`w` pause, resume, wake. Each save is one PATCH merged into that agent's existing config, so changing the model does not wipe its folder or instructions — I verified that by reading the record back. + +**Spend** is shown, not set, in `Project>costs`, `Board>board` and `Work>work`. The budget lives on the agent, so it is edited per agent on that settings tab. There is no company-level spend control on any screen yet. + +## Your questions, answered plainly + +**Skills.** Not in the interface. Paperclip has `GET /api/agents/{id}/skills` and `POST …/skills/sync` with `add`, `remove`, `replace` — so a read-only skills row is cheap, a full editor is a later step. Your rule (sub-agents get only what their job needs) maps exactly onto `replace`. + +**Where to add work.** `New task>new`. And my answer on Tuxedo is **no** for tasks: a second place that writes tasks is a second owner for the same fact, which is the fault that sank the last attempt. If you want notes, put them in the project's own `.harness/NOTES.md` and let Tuxedo read it per project — notes are not tasks, and nothing else should claim they are. + +**`office --host` from another machine.** Not implemented, and it should not be faked. Sessions are created by you: `tuios new --host nixos-desktop "new test project"`, then `bin/office ` inside it on the machine that owns the folder. Driving `.27` from `.13` needs ssh plus a remote `bin/board` — a deliberate step, not an accident. + +**Switching projects.** Not built. Proposal: a small local registry of adopted projects (id, folder, host, session) filled by `bin/office`, and a `Project>projects` tab that lists them and switches by rewriting the current folder's `.harness/harness.toml`. A project on another machine shows as `on .27` rather than pretending it can be opened from here. + +**Artifacts** are Paperclip work products attached to a task — an uploaded file, a pull request, a preview URL, a commit, a branch. Nothing shows them yet; their home is a `Work>artifacts` tab. + +**"Workspaces" in Paperclip** do not exist. Paperclip has companies → projects → tasks → agents → runs. What Paperclip calls a workspace is a project's code folder, the git worktree a task runs in. Our *workspace* is TUIOS's word for a page. + +**Charts.** Use Go, not TML: the panels are already Go and the data is in memory. `tuios.dev/plot` gives a spend-by-day chart in `Project>costs` for a few dozen lines. + +**Mouse-1/Switch** are still not installed on this machine. + +## Functional tests — the list I propose + +1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`. +2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, then runs, then its log. +3. Let it finish; read the diff in `Work>work`, the verdict in `Work>review`. +4. Merge with `bin/merge`, confirm the verify command passes on `main`. +5. Open the blocker's dependent task and confirm it can now proceed. +6. `R` from `Repair>repair` and confirm the eight workspaces come back. +7. Set an agent's model in `Agents>agents` and confirm it applies to the *next* run only. + +Committed as `7b12b45`. Say go and I run that list end to end and report each result. + +## Source paths observed + +- `paseo/projects/new_test_projects` +- `tuios.dev/docs/libraries/plot` +- `home/sam/paseo/projects/paperclip-harness/bin/harness` +- `run/current-system/sw/bin/git` +- `home/sam/.nix-profile/bin/go` +- `home/sam/.local/bin/ocr` +- `etc/profiles/per-user/sam/bin/tuios` +- `run/current-system/sw/bin/lazygit` +- `etc/profiles/per-user/sam/bin/hunk` +- `tmp/pc-sandbox-2026-11-10/.gitignore` + +## Evidence + +- Confidence: 84% +- Reason: Update component/repository context with detailed discovered structure and configuration + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md b/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md index d180cbe..6cd2828 100644 --- a/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md +++ b/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md @@ -337,3 +337,37 @@ Status: 8 workspaces, 23 panels, nothing missing from docs/WORKSPACES.md. Tool p - session: [[packs/paperclip-harness/80-sessions/paperclip-harness-tui-repair-session-border-overflow-review-|paperclip-harness TUI repair session: border overflow, review tab, tool panes]] - session: [[packs/paperclip-harness/80-sessions/rich-discovery-using-workspace-pane-from-here-on-2026-11-10-|Rich discovery: using-workspace-pane-from-here-on 2026-11-10 07:06:26]] - observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|using-workspace-pane-from-here-on repository structure and configuration patterns]] + + +--- + +## Update (2026-11-10 07:35:38) + +Commit 7b12b45 (message: "Drop the icon sample row; give tool panes a working PATH and a reason to stay open; answer the open questions"). + +Deliverables: +- Repair>repair: removed the icon sample row (the user's explicit request). +- ocr tool pane: two root causes fixed — (a) tool panes launched with a smaller PATH than the user's shell so `ocr` was command-not-found; tool panes now include ~/.local/bin, ~/.nix-profile/bin, system profile and per-user profile on PATH; (b) ocr exits immediately when there is nothing to review; added a "press enter to close" trailer so the pane stays open. +- Tool chooser gained `g` and `G` keys (led to opening a second shell pane while testing). +- Verified in Repair>repair: all eight checks pass (control plane reply, project file, harness binary, git, go, ocr, tuios, lazygit, hunk, Nerd Font 384 files). +- ocr now runs and logs (`[ocr] 1 file(s) changed, reviewing 1 in /tmp/pc-sandbox-2026-11-10 …`). + +Not yet done: end-to-end functional test list (pending user go-ahead); skills read-only row; Work>artifacts tab; Project>projects switcher; spend chart. + +Also field-verified that per-agent settings PATCH merges into existing config (changing model did not wipe folder/instructions, confirmed by reading the record back). + +## Evidence + +- Confidence: 90% +- Reason: Completed, verified work with commit hash, root causes, and known follow-ups. + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no.md b/.pi/memory-vault/packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no.md new file mode 100644 index 0000000..043bee3 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no.md @@ -0,0 +1,54 @@ +--- +type: decision +id: decision.paperclip-harness.task-entry-dedup-and-per-project-notes-skills-via-replace-no +title: Task entry/dedup and per-project notes; skills via replace; no fake remote office +status: active +source_of_truth: false +freshness: current +last_reviewed: 2026-11-10 +tags: + - pack/paperclip-harness + - agent-memory/decision + - decision + - paperclip-harness + - tuxedo + - skills + - project-switching + - multi-machine +--- + +# Task entry/dedup and per-project notes; skills via replace; no fake remote office + +Decisions made this turn in paperclip-harness: + +1. Tasks have exactly one creation point: New task>new. Tuxedo (the notes-ish surface) is REJECTED as a task writer — a second writer for the same fact is the failure mode that sank the prior attempt. Freeform notes go to the project's own .harness/NOTES.md and can be read per-project; notes are not tasks. + +2. Skills are managed via Paperclip's /api/agents/{id}/skills (GET) and …/skills/sync (POST, ops: add/remove/replace). A read-only skills row is cheap to ship; full editor is later. `replace` is how the "sub-agents get only what their job needs" rule is enforced. + +3. `office --host "..."` cross-machine start is NOT implemented and will not be faked. Correct flow: `tuios new --host nixos-desktop "new test project"`, then `bin/office ` inside it on the machine that owns the folder. Driving .27 from .13 needs ssh + remote bin/board as an explicit step. + +4. Project switching is not built. Proposal (not yet implemented): a small local registry of adopted projects keyed by (id, folder, host, session), filled by bin/office, surfaced as a Project>projects tab that switches by rewriting the current folder's .harness/harness.toml. Projects on other machines display as `on .27` instead of pretending to be openable locally. + +5. Charting in-TUI uses Go, not TML, because panels are already Go and hold data in memory; tuios.dev/plot gives a spend-by-day chart in Project>costs in a few dozen lines. + +Consequences/caveats: no company-level spend control yet; Tuxedo has an open scope question; Mouse-1/Switch not installed on this machine; skills editor, project switching, and Work>artifacts tab are all proposals. + +## Evidence + +- Confidence: 85% +- Reason: Explicit architectural/business-rule decisions with rationale and not-yet-built caveats that a future agent must respect. + +## Related + +- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]] + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md b/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md index b6d1e00..34f0946 100644 --- a/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md +++ b/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md @@ -1217,3 +1217,90 @@ Ready to discuss modifications whenever you are. - session: [[packs/paperclip-harness/80-sessions/paperclip-harness-tui-repair-session-border-overflow-review-|paperclip-harness TUI repair session: border overflow, review tab, tool panes]] - session: [[packs/paperclip-harness/80-sessions/rich-discovery-using-workspace-pane-from-here-on-2026-11-10-|Rich discovery: using-workspace-pane-from-here-on 2026-11-10 07:06:26]] - observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|using-workspace-pane-from-here-on repository structure and configuration patterns]] + + +--- + +## Update (2026-11-10 07:35:38) + +## Structural/configuration observations (2026-11-10 07:35:38) + +Both bugs fixed, and here are direct answers. + +## Fixed + +**Repair>repair** — the icon sample row is gone. + +**ocr closed instantly.** Two causes, both real: a tool pane is started with a smaller PATH than your shell, so `ocr` was "command not found", and even when it ran, a review with nothing to look at exits in a second. Tool panes now get `~/.local/bin`, `~/.nix-profile/bin`, the system profile and your per-user profile on PATH, and the ocr entry ends with a "press enter to close" line. It now runs and stays: + +``` +[ocr] 1 file(s) changed, reviewing 1 in /tmp/pc-sandbox-2026-11-10 +[ocr] ▶ code_search search_text=harness … +``` + +The chooser also gained `g` and `G`, which is what led me to open a second shell pane while testing. + +## Where settings are + +**`Agents>agents`, fourth tab, settings.** Role, job title, model, monthly budget, heartbeat. `enter` edits a field in place, `esc` cancels, `p`/`P`/`w` pause, resume, wake. Each save is one PATCH merged into that agent's existing config, so changing the model does not wipe its folder or instructions — I verified that by reading the record back. + +**Spend** is shown, not set, in `Project>costs`, `Board>board` and `Work>work`. The budget lives on the agent, so it is edited per agent on that settings tab. There is no company-level spend control on any screen yet. + +## Your questions, answered plainly + +**Skills.** Not in the interface. Paperclip has `GET /api/agents/{id}/skills` and `POST …/skills/sync` with `add`, `remove`, `replace` — so a read-only skills row is cheap, a full editor is a later step. Your rule (sub-agents get only what their job needs) maps exactly onto `replace`. + +**Where to add work.** `New task>new`. And my answer on Tuxedo is **no** for tasks: a second place that writes tasks is a second owner for the same fact, which is the fault that sank the last attempt. If you want notes, put them in the project's own `.harness/NOTES.md` and let Tuxedo read it per project — notes are not tasks, and nothing else should claim they are. + +**`office --host` from another machine.** Not implemented, and it should not be faked. Sessions are created by you: `tuios new --host nixos-desktop "new test project"`, then `bin/office ` inside it on the machine that owns the folder. Driving `.27` from `.13` needs ssh plus a remote `bin/board` — a deliberate step, not an accident. + +**Switching projects.** Not built. Proposal: a small local registry of adopted projects (id, folder, host, session) filled by `bin/office`, and a `Project>projects` tab that lists them and switches by rewriting the current folder's `.harness/harness.toml`. A project on another machine shows as `on .27` rather than pretending it can be opened from here. + +**Artifacts** are Paperclip work products attached to a task — an uploaded file, a pull request, a preview URL, a commit, a branch. Nothing shows them yet; their home is a `Work>artifacts` tab. + +**"Workspaces" in Paperclip** do not exist. Paperclip has companies → projects → tasks → agents → runs. What Paperclip calls a workspace is a project's code folder, the git worktree a task runs in. Our *workspace* is TUIOS's word for a page. + +**Charts.** Use Go, not TML: the panels are already Go and the data is in memory. `tuios.dev/plot` gives a spend-by-day chart in `Project>costs` for a few dozen lines. + +**Mouse-1/Switch** are still not installed on this machine. + +## Functional tests — the list I propose + +1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`. +2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, then runs, then its log. +3. Let it finish; read the diff in `Work>work`, the verdict in `Work>review`. +4. Merge with `bin/merge`, confirm the verify command passes on `main`. +5. Open the blocker's dependent task and confirm it can now proceed. +6. `R` from `Repair>repair` and confirm the eight workspaces come back. +7. Set an agent's model in `Agents>agents` and confirm it applies to the *next* run only. + +Committed as `7b12b45`. Say go and I run that list end to end and report each result. + +## Source paths observed + +- `paseo/projects/new_test_projects` +- `tuios.dev/docs/libraries/plot` +- `home/sam/paseo/projects/paperclip-harness/bin/harness` +- `run/current-system/sw/bin/git` +- `home/sam/.nix-profile/bin/go` +- `home/sam/.local/bin/ocr` +- `etc/profiles/per-user/sam/bin/tuios` +- `run/current-system/sw/bin/lazygit` +- `etc/profiles/per-user/sam/bin/hunk` +- `tmp/pc-sandbox-2026-11-10/.gitignore` + +## Evidence + +- Confidence: 82% +- Reason: Captured factual repo structure/configuration patterns from rich discovery + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end.md b/.pi/memory-vault/packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end.md new file mode 100644 index 0000000..aab25fa --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end.md @@ -0,0 +1,107 @@ +--- +type: runbook +id: runbook.paperclip-harness.paperclip-harness-functional-smoke-test-end-to-end +title: Paperclip-harness functional smoke test (end-to-end) +status: active +source_of_truth: false +freshness: current +last_reviewed: 2026-11-10 +tags: + - pack/paperclip-harness + - agent-memory/runbook + - paperclip-harness + - runbook + - testing + - tuios + - troubleshooting +--- + +# Paperclip-harness functional smoke test (end-to-end) + +Trigger: after changes to paperclip-harness, run the agreed end-to-end functional test list before shipping. + +Procedure: +1. Create a task in New task>new with a blocker and a verify command; confirm it appears in Board>board. +2. Assign it in Board>board, then watch it in Agents>agents — roster, then runs, then its log. +3. Let it finish; read the diff in Work>work, and the verdict in Work>review. +4. Merge with `bin/merge`; confirm the verify command passes on `main`. +5. Open the blocker's dependent task and confirm it can now proceed. +6. Press `R` in Repair>repair and confirm the eight workspaces come back. +7. Set an agent's model in Agents>agents and confirm it applies to the *next* run only. + +Prereqs: a running paperclip-harness TUIOS session (session name `paperclip-harness`), tools check all green on Repair>repair, ocr and other tools on PATH. + +Troubleshooting (learned this turn): a tool pane may launch with a smaller PATH than the user's shell, so tools appear "command not found" (ocr); and some tools exit immediately when they have nothing to do — a "press enter to close" trailer keeps the pane open. `tuios list-windows -s paperclip-harness` enumerates pane names when capture-pane fails. + +## Detailed procedure from completed turn + +Both bugs fixed, and here are direct answers. + +## Fixed + +**Repair>repair** — the icon sample row is gone. + +**ocr closed instantly.** Two causes, both real: a tool pane is started with a smaller PATH than your shell, so `ocr` was "command not found", and even when it ran, a review with nothing to look at exits in a second. Tool panes now get `~/.local/bin`, `~/.nix-profile/bin`, the system profile and your per-user profile on PATH, and the ocr entry ends with a "press enter to close" line. It now runs and stays: + +``` +[ocr] 1 file(s) changed, reviewing 1 in /tmp/pc-sandbox-2026-11-10 +[ocr] ▶ code_search search_text=harness … +``` + +The chooser also gained `g` and `G`, which is what led me to open a second shell pane while testing. + +## Where settings are + +**`Agents>agents`, fourth tab, settings.** Role, job title, model, monthly budget, heartbeat. `enter` edits a field in place, `esc` cancels, `p`/`P`/`w` pause, resume, wake. Each save is one PATCH merged into that agent's existing config, so changing the model does not wipe its folder or instructions — I verified that by reading the record back. + +**Spend** is shown, not set, in `Project>costs`, `Board>board` and `Work>work`. The budget lives on the agent, so it is edited per agent on that settings tab. There is no company-level spend control on any screen yet. + +## Your questions, answered plainly + +**Skills.** Not in the interface. Paperclip has `GET /api/agents/{id}/skills` and `POST …/skills/sync` with `add`, `remove`, `replace` — so a read-only skills row is cheap, a full editor is a later step. Your rule (sub-agents get only what their job needs) maps exactly onto `replace`. + +**Where to add work.** `New task>new`. And my answer on Tuxedo is **no** for tasks: a second place that writes tasks is a second owner for the same fact, which is the fault that sank the last attempt. If you want notes, put them in the project's own `.harness/NOTES.md` and let Tuxedo read it per project — notes are not tasks, and nothing else should claim they are. + +**`office --host` from another machine.** Not implemented, and it should not be faked. Sessions are created by you: `tuios new --host nixos-desktop "new test project"`, then `bin/office ` inside it on the machine that owns the folder. Driving `.27` from `.13` needs ssh plus a remote `bin/board` — a deliberate step, not an accident. + +**Switching projects.** Not built. Proposal: a small local registry of adopted projects (id, folder, host, session) filled by `bin/office`, and a `Project>projects` tab that lists them and switches by rewriting the current folder's `.harness/harness.toml`. A project on another machine shows as `on .27` rather than pretending it can be opened from here. + +**Artifacts** are Paperclip work products attached to a task — an uploaded file, a pull request, a preview URL, a commit, a branch. Nothing shows them yet; their home is a `Work>artifacts` tab. + +**"Workspaces" in Paperclip** do not exist. Paperclip has companies → projects → tasks → agents → runs. What Paperclip calls a workspace is a project's code folder, the git worktree a task runs in. Our *workspace* is TUIOS's word for a page. + +**Charts.** Use Go, not TML: the panels are already Go and the data is in memory. `tuios.dev/plot` gives a spend-by-day chart in `Project>costs` for a few dozen lines. + +**Mouse-1/Switch** are still not installed on this machine. + +## Functional tests — the list I propose + +1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`. +2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, then runs, then its log. +3. Let it finish; read the diff in `Work>work`, the verdict in `Work>review`. +4. Merge with `bin/merge`, confirm the verify command passes on `main`. +5. Open the blocker's dependent task and confirm it can now proceed. +6. `R` from `Repair>repair` and confirm the eight workspaces come back. +7. Set an agent's model in `Agents>agents` and confirm it applies to the *next* run only. + +Committed as `7b12b45`. Say go and I run that list end to end and report each result. + +## Evidence + +- Confidence: 85% +- Reason: Repeatable test checklist and the PATH/instant-exit troubleshooting are durable and reusable.; enriched with final-answer detail because persistence should be reusable + +## Related + +- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]] + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md b/.pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md new file mode 100644 index 0000000..0800867 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md @@ -0,0 +1,103 @@ +--- +type: runbook +id: runbook.paperclip-harness.tmp-deployment-operations +title: tmp deployment operations +status: active +source_of_truth: false +freshness: current +last_reviewed: 2026-11-10 +tags: + - pack/paperclip-harness + - agent-memory/runbook + - autolearn + - rich-discovery + - deployment-runbook +--- + +# tmp deployment operations + +## Deployment/runbook details discovered (2026-11-10 07:35:38) + +Both bugs fixed, and here are direct answers. + +## Fixed + +**Repair>repair** — the icon sample row is gone. + +**ocr closed instantly.** Two causes, both real: a tool pane is started with a smaller PATH than your shell, so `ocr` was "command not found", and even when it ran, a review with nothing to look at exits in a second. Tool panes now get `~/.local/bin`, `~/.nix-profile/bin`, the system profile and your per-user profile on PATH, and the ocr entry ends with a "press enter to close" line. It now runs and stays: + +``` +[ocr] 1 file(s) changed, reviewing 1 in /tmp/pc-sandbox-2026-11-10 +[ocr] ▶ code_search search_text=harness … +``` + +The chooser also gained `g` and `G`, which is what led me to open a second shell pane while testing. + +## Where settings are + +**`Agents>agents`, fourth tab, settings.** Role, job title, model, monthly budget, heartbeat. `enter` edits a field in place, `esc` cancels, `p`/`P`/`w` pause, resume, wake. Each save is one PATCH merged into that agent's existing config, so changing the model does not wipe its folder or instructions — I verified that by reading the record back. + +**Spend** is shown, not set, in `Project>costs`, `Board>board` and `Work>work`. The budget lives on the agent, so it is edited per agent on that settings tab. There is no company-level spend control on any screen yet. + +## Your questions, answered plainly + +**Skills.** Not in the interface. Paperclip has `GET /api/agents/{id}/skills` and `POST …/skills/sync` with `add`, `remove`, `replace` — so a read-only skills row is cheap, a full editor is a later step. Your rule (sub-agents get only what their job needs) maps exactly onto `replace`. + +**Where to add work.** `New task>new`. And my answer on Tuxedo is **no** for tasks: a second place that writes tasks is a second owner for the same fact, which is the fault that sank the last attempt. If you want notes, put them in the project's own `.harness/NOTES.md` and let Tuxedo read it per project — notes are not tasks, and nothing else should claim they are. + +**`office --host` from another machine.** Not implemented, and it should not be faked. Sessions are created by you: `tuios new --host nixos-desktop "new test project"`, then `bin/office ` inside it on the machine that owns the folder. Driving `.27` from `.13` needs ssh plus a remote `bin/board` — a deliberate step, not an accident. + +**Switching projects.** Not built. Proposal: a small local registry of adopted projects (id, folder, host, session) filled by `bin/office`, and a `Project>projects` tab that lists them and switches by rewriting the current folder's `.harness/harness.toml`. A project on another machine shows as `on .27` rather than pretending it can be opened from here. + +**Artifacts** are Paperclip work products attached to a task — an uploaded file, a pull request, a preview URL, a commit, a branch. Nothing shows them yet; their home is a `Work>artifacts` tab. + +**"Workspaces" in Paperclip** do not exist. Paperclip has companies → projects → tasks → agents → runs. What Paperclip calls a workspace is a project's code folder, the git worktree a task runs in. Our *workspace* is TUIOS's word for a page. + +**Charts.** Use Go, not TML: the panels are already Go and the data is in memory. `tuios.dev/plot` gives a spend-by-day chart in `Project>costs` for a few dozen lines. + +**Mouse-1/Switch** are still not installed on this machine. + +## Functional tests — the list I propose + +1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`. +2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, then runs, then its log. +3. Let it finish; read the diff in `Work>work`, the verdict in `Work>review`. +4. Merge with `bin/merge`, confirm the verify command passes on `main`. +5. Open the blocker's dependent task and confirm it can now proceed. +6. `R` from `Repair>repair` and confirm the eight workspaces come back. +7. Set an agent's model in `Agents>agents` and confirm it applies to the *next* run only. + +Committed as `7b12b45`. Say go and I run that list end to end and report each result. + +## Source paths observed + +- `paseo/projects/new_test_projects` +- `tuios.dev/docs/libraries/plot` +- `home/sam/paseo/projects/paperclip-harness/bin/harness` +- `run/current-system/sw/bin/git` +- `home/sam/.nix-profile/bin/go` +- `home/sam/.local/bin/ocr` +- `etc/profiles/per-user/sam/bin/tuios` +- `run/current-system/sw/bin/lazygit` +- `etc/profiles/per-user/sam/bin/hunk` +- `tmp/pc-sandbox-2026-11-10/.gitignore` + +## Evidence + +- Confidence: 83% +- Reason: Extracted repeatable deploy/configuration procedure from rich discovery + +## Related + +- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]] + +## Related learned memories + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38.md b/.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38.md new file mode 100644 index 0000000..496c083 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38.md @@ -0,0 +1,106 @@ +--- +type: session +id: session.paperclip-harness.rich-discovery-tmp-2026-11-10-07-35-38 +title: Rich discovery: tmp 2026-11-10 07:35:38 +status: active +source_of_truth: false +freshness: current +last_reviewed: 2026-11-10 +tags: + - pack/paperclip-harness + - agent-memory/session + - autolearn + - rich-discovery + - repo/tmp +--- + +# Rich discovery: tmp 2026-11-10 07:35:38 + +Sanitized rich discovery snapshot captured automatically from the completed turn. + + +## Source paths observed + +- `paseo/projects/new_test_projects` +- `tuios.dev/docs/libraries/plot` +- `home/sam/paseo/projects/paperclip-harness/bin/harness` +- `run/current-system/sw/bin/git` +- `home/sam/.nix-profile/bin/go` +- `home/sam/.local/bin/ocr` +- `etc/profiles/per-user/sam/bin/tuios` +- `run/current-system/sw/bin/lazygit` +- `etc/profiles/per-user/sam/bin/hunk` +- `tmp/pc-sandbox-2026-11-10/.gitignore` + +## Final answer snapshot + +Both bugs fixed, and here are direct answers. + +## Fixed + +**Repair>repair** — the icon sample row is gone. + +**ocr closed instantly.** Two causes, both real: a tool pane is started with a smaller PATH than your shell, so `ocr` was "command not found", and even when it ran, a review with nothing to look at exits in a second. Tool panes now get `~/.local/bin`, `~/.nix-profile/bin`, the system profile and your per-user profile on PATH, and the ocr entry ends with a "press enter to close" line. It now runs and stays: + +``` +[ocr] 1 file(s) changed, reviewing 1 in /tmp/pc-sandbox-2026-11-10 +[ocr] ▶ code_search search_text=harness … +``` + +The chooser also gained `g` and `G`, which is what led me to open a second shell pane while testing. + +## Where settings are + +**`Agents>agents`, fourth tab, settings.** Role, job title, model, monthly budget, heartbeat. `enter` edits a field in place, `esc` cancels, `p`/`P`/`w` pause, resume, wake. Each save is one PATCH merged into that agent's existing config, so changing the model does not wipe its folder or instructions — I verified that by reading the record back. + +**Spend** is shown, not set, in `Project>costs`, `Board>board` and `Work>work`. The budget lives on the agent, so it is edited per agent on that settings tab. There is no company-level spend control on any screen yet. + +## Your questions, answered plainly + +**Skills.** Not in the interface. Paperclip has `GET /api/agents/{id}/skills` and `POST …/skills/sync` with `add`, `remove`, `replace` — so a read-only skills row is cheap, a full editor is a later step. Your rule (sub-agents get only what their job needs) maps exactly onto `replace`. + +**Where to add work.** `New task>new`. And my answer on Tuxedo is **no** for tasks: a second place that writes tasks is a second owner for the same fact, which is the fault that sank the last attempt. If you want notes, put them in the project's own `.harness/NOTES.md` and let Tuxedo read it per project — notes are not tasks, and nothing else should claim they are. + +**`office --host` from another machine.** Not implemented, and it should not be faked. Sessions are created by you: `tuios new --host nixos-desktop "new test project"`, then `bin/office ` inside it on the machine that owns the folder. Driving `.27` from `.13` needs ssh plus a remote `bin/board` — a deliberate step, not an accident. + +**Switching projects.** Not built. Proposal: a small local registry of adopted projects (id, folder, host, session) filled by `bin/office`, and a `Project>projects` tab that lists them and switches by rewriting the current folder's `.harness/harness.toml`. A project on another machine shows as `on .27` rather than pretending it can be opened from here. + +**Artifacts** are Paperclip work products attached to a task — an uploaded file, a pull request, a preview URL, a commit, a branch. Nothing shows them yet; their home is a `Work>artifacts` tab. + +**"Workspaces" in Paperclip** do not exist. Paperclip has companies → projects → tasks → agents → runs. What Paperclip calls a workspace is a project's code folder, the git worktree a task runs in. Our *workspace* is TUIOS's word for a page. + +**Charts.** Use Go, not TML: the panels are already Go and the data is in memory. `tuios.dev/plot` gives a spend-by-day chart in `Project>costs` for a few dozen lines. + +**Mouse-1/Switch** are still not installed on this machine. + +## Functional tests — the list I propose + +1. Create a task in `New task>new` with a blocker and a verify command; see it in `Board>board`. +2. Assign it in `Board>board`, then watch it in `Agents>agents` — roster, then runs, then its log. +3. Let it finish; read the diff in `Work>work`, the verdict in `Work>review`. +4. Merge with `bin/merge`, confirm the verify command passes on `main`. +5. Open the blocker's dependent task and confirm it can now proceed. +6. `R` from `Repair>repair` and confirm the eight workspaces come back. +7. Set an agent's model in `Agents>agents` and confirm it applies to the *next* run only. + +Committed as `7b12b45`. Say go and I run that list end to end and report each result. + +## 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 + +- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]] +- runbook: [[packs/paperclip-harness/70-runbooks/paperclip-harness-functional-smoke-test-end-to-end|Paperclip-harness functional smoke test (end-to-end)]] +- decision: [[packs/paperclip-harness/50-decisions/task-entry-dedup-and-per-project-notes-skills-via-replace-no|Task entry/dedup and per-project notes; skills via replace; no fake remote office]] +- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|paperclip-harness commit 7b12b45: fixed repair icon row + ocr pane closing; answered settings/skills/projects questions]] +- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-07-35-38|Rich discovery: tmp 2026-11-10 07:35:38]] +- context: [[packs/paperclip-harness/20-context/tmp|tmp]] +- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|tmp deployment operations]] +- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]] diff --git a/.pi/settings.json b/.pi/settings.json index a83bff0..be9ee0f 100644 --- a/.pi/settings.json +++ b/.pi/settings.json @@ -10,7 +10,8 @@ "skills": [ "skills/obsidian-cli", "skills/npm-security", - "skills/system-architect" + "skills/system-architect", + "skills/nixos-workflow" ] } ] diff --git a/docs/PLAN-INTERFACE.md b/docs/PLAN-INTERFACE.md index aaa0015..7b5903f 100644 --- a/docs/PLAN-INTERFACE.md +++ b/docs/PLAN-INTERFACE.md @@ -201,3 +201,112 @@ a second language and a second round trip. Worth doing once the functional tests **Mouse-1 and Switch.** Still not installed on this machine. Unchanged from the earlier note: they would serve cheap repeatable judgement, later, after they are installed and measured. + +--- + +# Findings for the next round of decisions, 2026-11-10 + +Everything below was measured on this machine. Nothing here is proposed without saying so. + +## Skills per agent — the API already models it + +`GET /api/agents/{id}/skills` returns, for each agent: + +``` +mode: "persistent" +desiredSkills: ["paperclipai/paperclip/paperclip"] +entries: [ + { key: "company//obsidian-cli", runtimeName: "obsidian-cli--b74ae42966", + desired: false, managed: true, state: "stale", + sourcePath: "…/instances/default/skills//obsidian-cli", + targetPath: "/home/sam/.pi/agent/skills/obsidian-cli--b74ae42966" } +] +``` + +So Paperclip already models exactly what is wanted: a desired set per agent, a managed set +actually installed, and a state (`stale` today for `obsidian-cli` on `Builder`, which is +worth fixing on its own). `POST /api/agents/{id}/skills/sync` with `add`, `remove` or +`replace` sets the desired set; `replace` is the operation that means "this agent gets these +and nothing else", which is how a sub-agent's context is kept small. + +Company level, there is more: `GET/POST /api/companies/{id}/skills` (the catalog), +`/skills/{id}/versions`, `/skills/{id}/audit`, and `GET/PUT /api/companies/{id}/skill-policy` +with `/skill-policy/evaluate`, which is a company-wide rule about which skills may be used. + +Proposed in the interface: `Agents>agents` settings tab gains two rows — **skills** (the +desired set, read-only at first, with `add`/`remove` later) and **skill source** (company +catalog or the agent's own). A full skill browser is a later screen, not a panel. + +## Memory — three different things wearing one word + +| What | State here | What it does | +|---|---|---| +| **engram** | installed, `engram v1.16.1`, MCP server mode, no pi MCP entry yet | persistent memory for agents, over HTTP or MCP | +| **headroom** | running, `headroom-proxy v0.24.0`, healthy at `192.168.20.13:8787`, memory backend **disabled**, compression enabled | compresses prompts on the way out; it is a proxy, not a store | +| **pi memctx** | in use in this session | the memory gateway that injects notes into a prompt | + +They are not alternatives: engram stores, headroom compresses, memctx injects. For agents, +the only lever Paperclip gives us is per-agent configuration — `adapterConfig` (the folder, +the model, the instructions bundle) and `runtimeConfig` — so memory is set per agent by +pointing that agent at the proxy or the storage it should use, not by a global switch. + +Proposed: a **memory** row in `Agents>agents` settings showing which of the three that agent +uses, read from its adapter configuration; and nothing more until one agent has been run +both ways and the difference measured. + +## MOUSE-1 + +- `MOUSE_API_KEY` **is** set in `~/.config/environment.d/10-secrets.conf` (name checked, value + never printed). `JEV_API_KEY` is set as well. +- No `mouse`, `mouse1`, `jev` or `switch` binary is installed. +- The previous project already wrote the policy, in + `~/paseo/projects/tuios_coding_harness/plan/*`: MOUSE-1 is **"triage only: label, score, + route, escalate. Never a gate, never a permit"**, and explicitly ruled out for deciding a + merge or allowing a tool call, because a cheap classifier that fails open on a network + error turns a green run into a lie. + +That policy is right and should be adopted unchanged. Its place in this interface, if it is +added: `Board>board` needs-you could be ordered by a MOUSE-1 score, and `Work>review` could +use it to pre-sort findings. Never the merge, never an approval. + +## Lazygit + +Already wired: `t` in `Board>board` or `Work>work`, then choose Lazygit. It opens beside the +pane, in the same workspace, and `q` closes it. Hunk, Yazi, Neovim, fzf, a shell and ocr are +in the same chooser. + +## The old `office` command, and what ours is missing + +The previous project's `office` does four things, in order: + +1. makes the folder and remembers the host in `/.harness/host`; +2. runs `new-project` to write the project scaffold — `settings.toml`, one file per role, + `verify.sh`, the per-screen notes — **writing only what is missing, never overwriting**; +3. refuses to continue if the TUIOS session does not exist, and prints the exact + `tuios new ` line to run; +4. runs its `board` to build or repair the pages, then prints how to attach. + +Ours does 1, 3 and 4 (with a different file: `.harness/harness.toml`). It does **not** do 2: +there is no scaffold, no per-role file, no `verify.sh`, no page notes. That is a real gap and +the cheapest useful one to close. + +## Dashboard — the API already answers it + +`GET /api/companies/{id}/dashboard` returns 1.8 KB: + +``` +agents: {active: 6, running: 0, paused: 0, error: 0} +tasks: {open: 8, inProgress: 0, blocked: 4, done: 147} +costs: {monthSpendCents: 11, monthBudgetCents: 0, monthUtilizationPercent: 0} +pendingApprovals: 0 +budgets: {activeIncidents: 0, pendingApprovals: 0, pausedAgents: 0, pausedProjects: 0} +runActivity: [14 entries] +``` + +That is a whole dashboard in one call, and it is cheap enough to poll. Proposal: a +`Project>overview` panel showing those four blocks and a sparkline of `runActivity`, drawn in +Go with `tuios.dev/plot` rather than embedding Paperclip's web dashboard. + +## Not doing + +Artifacts, as instructed. Nothing about them will be added.