sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Verification is optional and the agent's job; the form stays open with a receipt; panes fall back to a shell

Browse Source
This commit is contained in:
Sam
2026-11-11 11:28:11 +11:00
parent c9e027d0e3
commit 678c497064
8 changed files with 329 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
.pi/memory-vault/packs/paperclip-harness/20-context/home.md
View File

@@ -551,3 +551,91 @@ Committed as `77014d0` — documentation only, nothing in the running layout cha
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-pi-2026-11-10-21-03-21|Rich discovery: .pi 2026-11-10 21:03:21]]
- context: [[packs/paperclip-harness/20-context/home|.pi]]
- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|.pi deployment operations]]
---
## Update (2026-11-11 00:03:58)
## Rich discovery update (2026-11-11 00:03:58)
You are right about the guidance, and it is rewritten.
## What was wrong
Those lines were mine, and they were poetry instead of instructions:
- "A task that asks for two things cannot be judged, only argued about" — says nothing about what to type.
- "A command decides when work is finished, the agent does not" — misleading. The *agent* performs the work; the *command* decides whether it counts as finished. My sentence made it sound like the command does the work.
- "a boundary… which files will change… review becomes an autopsy" — you cannot know which files change before the work, and nobody should have to decode a metaphor.
**Rewritten as five concrete fields with an example each**, plus a glossary. It now reads:
```
Title
One sentence naming the change. It becomes the task title in Paperclip.
example: Add a CHANGELOG.md with an Unreleased section
Must finish first
The identifier of another task, for example AUD-171. Paperclip then records a real
blocker edge and will not let this task run before that one is done. Leave it empty
when nothing must come first.
example: AUD-171
Proves it is done
A shell command that exits 0 only when the work is right. It runs in the task's own
copy of the code. Leave it empty and the task will be accepted on the agent's word,
which is a weaker test.
example: test -s CHANGELOG.md or make test
```
## Your questions, directly
**What is a blocker?** Another task's identifier (`AUD-171`) in the "Must finish first" field. Paperclip stores it as a link between the two tasks. That is what a blocker is — a link, not prose. The old text said a sentence is not a blocker, which was true but useless; now the field says exactly what to put in it.
**How do I assign?** Two ways: type `yes` in "Assign to" on the form, or select the task in `Board>board` and press `a`. Either calls Paperclip and wakes the agent. That is all assign means.
**How do I merge?** `Shell>shell`, then `bin/merge <identifier>`, optionally with `--check` first. It rebases, runs the verify command, runs the review, merges, and re-runs the verify command on `main`.
**What is a dependent task?** The task that names another in "Must finish first". It waits. With the blocker finished, it may start; with the blocker unfinished, Paperclip holds it and the board shows `waits on AUD-171`.
**How do I change an agent?** `Agents>agents`, `]` four times to settings, then `enter` on a field: role, title, model, budget, heartbeat. `p` pauses, `P` resumes.
**Why couldn't you set an agent before the first test?** You can, at any time — before a run, between runs, while paused. What you cannot do is change the model of a run already in progress; that is why a change applies to the next run.
**Are the eight workspaces eight Pi agents?** No. Workspaces are TUIOS pages. The agents are six records in Paperclip (`researcher`, `System`, `Hub`, `Chief of Staff`, `Documenter`, `Builder`), all visible in `Agents>agents`.
## The test plan
`docs/TEST-PLAN.md` now has nine steps, each with the exact keys, the exact text to type, what you should see, and where to stop. It starts with a health check and one trivial task (`STATUS.md`, verified by `test -s STATUS.md`) so nothing can fail for an interesting reason. The full text is in the file; the shape is:
0. `Repair>repair` passes; `Agents>agents` shows six agents, `Builder` not paused.
1. `New task>new` — five fields, exact text given; expect `created AUD-1xx, handed to an agent`.
2. `Board>board` — the row moves todo → in progress → done; `Agents>agents` runs tab shows one `succeeded` run woken by `assignment`; `enter` opens its log.
3. `Work>work` — runs, then change (one file, one line), then facts, then review.
4. `Shell>shell` — `bin/merge AUD-1xx --check`, then `bin/merge AUD-1xx`, then `git log --oneline -3`.
5. Create a second task blocked on the first; expect it held until the blocker is done.
6. `Agents>agents` settings — change the model and the budget; pause and resume.
7. Skills tab — `space` turns a skill on for that agent alone; extensions tab — `space` writes its wrapper.
8. `Repair>repair` — press `R`; all eight workspaces return in order.
## On the cleanup pane
Agreed, and your concern is exactly right: **killing a TUIOS session does not touch the Pi session files.** They are separate stores — TUIOS sessions live in the daemon, Pi conversations are files in `~/.pi/paperclips`. So a cleanup pane can only ever remove panes, never history. The plan in `docs/SESSIONS.md` is a `Repair>cleanup` tab that lists sessions with age and pane count, marks attached ones and refuses them, and requires you to pick the ones to kill. Nothing deletes a `.jsonl`.
Committed as `c9e027d`.
## Source paths observed
- `home/sam/paseo/projects/paperclip-harness/docs/TEST-PLAN.md`
## Evidence
- Confidence: 84%
- Reason: Update component/repository context with detailed discovered structure and configuration
## Related learned memories <!-- same-turn-2026-11-11 00:03:58 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-root-2026-11-11-00-03-58|Rich discovery: root. 2026-11-11 00:03:58]]
- context: [[packs/paperclip-harness/20-context/home|root.]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|root. repository structure and configuration patterns]]

88
.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md
View File

@@ -2071,3 +2071,91 @@ All eight workspaces are running on the new build. Committed as `1f8731f`.
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-paperclipai-2026-11-10-22-15-52|Rich discovery: paperclipai 2026-11-10 22:15:52]]
- context: [[packs/paperclip-harness/20-context/paperclipai|paperclipai]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|paperclipai repository structure and configuration patterns]]
---
## Update (2026-11-11 00:03:58)
## Structural/configuration observations (2026-11-11 00:03:58)
You are right about the guidance, and it is rewritten.
## What was wrong
Those lines were mine, and they were poetry instead of instructions:
- "A task that asks for two things cannot be judged, only argued about" — says nothing about what to type.
- "A command decides when work is finished, the agent does not" — misleading. The *agent* performs the work; the *command* decides whether it counts as finished. My sentence made it sound like the command does the work.
- "a boundary… which files will change… review becomes an autopsy" — you cannot know which files change before the work, and nobody should have to decode a metaphor.
**Rewritten as five concrete fields with an example each**, plus a glossary. It now reads:
```
Title
One sentence naming the change. It becomes the task title in Paperclip.
example: Add a CHANGELOG.md with an Unreleased section
Must finish first
The identifier of another task, for example AUD-171. Paperclip then records a real
blocker edge and will not let this task run before that one is done. Leave it empty
when nothing must come first.
example: AUD-171
Proves it is done
A shell command that exits 0 only when the work is right. It runs in the task's own
copy of the code. Leave it empty and the task will be accepted on the agent's word,
which is a weaker test.
example: test -s CHANGELOG.md or make test
```
## Your questions, directly
**What is a blocker?** Another task's identifier (`AUD-171`) in the "Must finish first" field. Paperclip stores it as a link between the two tasks. That is what a blocker is — a link, not prose. The old text said a sentence is not a blocker, which was true but useless; now the field says exactly what to put in it.
**How do I assign?** Two ways: type `yes` in "Assign to" on the form, or select the task in `Board>board` and press `a`. Either calls Paperclip and wakes the agent. That is all assign means.
**How do I merge?** `Shell>shell`, then `bin/merge <identifier>`, optionally with `--check` first. It rebases, runs the verify command, runs the review, merges, and re-runs the verify command on `main`.
**What is a dependent task?** The task that names another in "Must finish first". It waits. With the blocker finished, it may start; with the blocker unfinished, Paperclip holds it and the board shows `waits on AUD-171`.
**How do I change an agent?** `Agents>agents`, `]` four times to settings, then `enter` on a field: role, title, model, budget, heartbeat. `p` pauses, `P` resumes.
**Why couldn't you set an agent before the first test?** You can, at any time — before a run, between runs, while paused. What you cannot do is change the model of a run already in progress; that is why a change applies to the next run.
**Are the eight workspaces eight Pi agents?** No. Workspaces are TUIOS pages. The agents are six records in Paperclip (`researcher`, `System`, `Hub`, `Chief of Staff`, `Documenter`, `Builder`), all visible in `Agents>agents`.
## The test plan
`docs/TEST-PLAN.md` now has nine steps, each with the exact keys, the exact text to type, what you should see, and where to stop. It starts with a health check and one trivial task (`STATUS.md`, verified by `test -s STATUS.md`) so nothing can fail for an interesting reason. The full text is in the file; the shape is:
0. `Repair>repair` passes; `Agents>agents` shows six agents, `Builder` not paused.
1. `New task>new` — five fields, exact text given; expect `created AUD-1xx, handed to an agent`.
2. `Board>board` — the row moves todo → in progress → done; `Agents>agents` runs tab shows one `succeeded` run woken by `assignment`; `enter` opens its log.
3. `Work>work` — runs, then change (one file, one line), then facts, then review.
4. `Shell>shell` — `bin/merge AUD-1xx --check`, then `bin/merge AUD-1xx`, then `git log --oneline -3`.
5. Create a second task blocked on the first; expect it held until the blocker is done.
6. `Agents>agents` settings — change the model and the budget; pause and resume.
7. Skills tab — `space` turns a skill on for that agent alone; extensions tab — `space` writes its wrapper.
8. `Repair>repair` — press `R`; all eight workspaces return in order.
## On the cleanup pane
Agreed, and your concern is exactly right: **killing a TUIOS session does not touch the Pi session files.** They are separate stores — TUIOS sessions live in the daemon, Pi conversations are files in `~/.pi/paperclips`. So a cleanup pane can only ever remove panes, never history. The plan in `docs/SESSIONS.md` is a `Repair>cleanup` tab that lists sessions with age and pane count, marks attached ones and refuses them, and requires you to pick the ones to kill. Nothing deletes a `.jsonl`.
Committed as `c9e027d`.
## Source paths observed
- `home/sam/paseo/projects/paperclip-harness/docs/TEST-PLAN.md`
## Evidence
- Confidence: 82%
- Reason: Captured factual repo structure/configuration patterns from rich discovery
## Related learned memories <!-- same-turn-2026-11-11 00:03:58 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-root-2026-11-11-00-03-58|Rich discovery: root. 2026-11-11 00:03:58]]
- context: [[packs/paperclip-harness/20-context/home|root.]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|root. repository structure and configuration patterns]]

107
.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-root-2026-11-11-00-03-58.md Normal file
View File

@@ -0,0 +1,107 @@
---
type: session
id: session.paperclip-harness.rich-discovery-root-2026-11-11-00-03-58
title: Rich discovery: root. 2026-11-11 00:03:58
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-11
tags:
- pack/paperclip-harness
- agent-memory/session
- autolearn
- rich-discovery
- repo/root
---
# Rich discovery: root. 2026-11-11 00:03:58
Sanitized rich discovery snapshot captured automatically from the completed turn.
## Source paths observed
- `home/sam/paseo/projects/paperclip-harness/docs/TEST-PLAN.md`
## Final answer snapshot
You are right about the guidance, and it is rewritten.
## What was wrong
Those lines were mine, and they were poetry instead of instructions:
- "A task that asks for two things cannot be judged, only argued about" — says nothing about what to type.
- "A command decides when work is finished, the agent does not" — misleading. The *agent* performs the work; the *command* decides whether it counts as finished. My sentence made it sound like the command does the work.
- "a boundary… which files will change… review becomes an autopsy" — you cannot know which files change before the work, and nobody should have to decode a metaphor.
**Rewritten as five concrete fields with an example each**, plus a glossary. It now reads:
```
Title
One sentence naming the change. It becomes the task title in Paperclip.
example: Add a CHANGELOG.md with an Unreleased section
Must finish first
The identifier of another task, for example AUD-171. Paperclip then records a real
blocker edge and will not let this task run before that one is done. Leave it empty
when nothing must come first.
example: AUD-171
Proves it is done
A shell command that exits 0 only when the work is right. It runs in the task's own
copy of the code. Leave it empty and the task will be accepted on the agent's word,
which is a weaker test.
example: test -s CHANGELOG.md or make test
```
## Your questions, directly
**What is a blocker?** Another task's identifier (`AUD-171`) in the "Must finish first" field. Paperclip stores it as a link between the two tasks. That is what a blocker is — a link, not prose. The old text said a sentence is not a blocker, which was true but useless; now the field says exactly what to put in it.
**How do I assign?** Two ways: type `yes` in "Assign to" on the form, or select the task in `Board>board` and press `a`. Either calls Paperclip and wakes the agent. That is all assign means.
**How do I merge?** `Shell>shell`, then `bin/merge <identifier>`, optionally with `--check` first. It rebases, runs the verify command, runs the review, merges, and re-runs the verify command on `main`.
**What is a dependent task?** The task that names another in "Must finish first". It waits. With the blocker finished, it may start; with the blocker unfinished, Paperclip holds it and the board shows `waits on AUD-171`.
**How do I change an agent?** `Agents>agents`, `]` four times to settings, then `enter` on a field: role, title, model, budget, heartbeat. `p` pauses, `P` resumes.
**Why couldn't you set an agent before the first test?** You can, at any time — before a run, between runs, while paused. What you cannot do is change the model of a run already in progress; that is why a change applies to the next run.
**Are the eight workspaces eight Pi agents?** No. Workspaces are TUIOS pages. The agents are six records in Paperclip (`researcher`, `System`, `Hub`, `Chief of Staff`, `Documenter`, `Builder`), all visible in `Agents>agents`.
## The test plan
`docs/TEST-PLAN.md` now has nine steps, each with the exact keys, the exact text to type, what you should see, and where to stop. It starts with a health check and one trivial task (`STATUS.md`, verified by `test -s STATUS.md`) so nothing can fail for an interesting reason. The full text is in the file; the shape is:
0. `Repair>repair` passes; `Agents>agents` shows six agents, `Builder` not paused.
1. `New task>new` — five fields, exact text given; expect `created AUD-1xx, handed to an agent`.
2. `Board>board` — the row moves todo → in progress → done; `Agents>agents` runs tab shows one `succeeded` run woken by `assignment`; `enter` opens its log.
3. `Work>work` — runs, then change (one file, one line), then facts, then review.
4. `Shell>shell` — `bin/merge AUD-1xx --check`, then `bin/merge AUD-1xx`, then `git log --oneline -3`.
5. Create a second task blocked on the first; expect it held until the blocker is done.
6. `Agents>agents` settings — change the model and the budget; pause and resume.
7. Skills tab — `space` turns a skill on for that agent alone; extensions tab — `space` writes its wrapper.
8. `Repair>repair` — press `R`; all eight workspaces return in order.
## On the cleanup pane
Agreed, and your concern is exactly right: **killing a TUIOS session does not touch the Pi session files.** They are separate stores — TUIOS sessions live in the daemon, Pi conversations are files in `~/.pi/paperclips`. So a cleanup pane can only ever remove panes, never history. The plan in `docs/SESSIONS.md` is a `Repair>cleanup` tab that lists sessions with age and pane count, marks attached ones and refuses them, and requires you to pick the ones to kill. Nothing deletes a `.jsonl`.
Committed as `c9e027d`.
## 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-11 00:03:58 -->
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-root-2026-11-11-00-03-58|Rich discovery: root. 2026-11-11 00:03:58]]
- context: [[packs/paperclip-harness/20-context/home|root.]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|root. repository structure and configuration patterns]]