feat(orchestrator): review staged work as match cards (requirement 012, phases A and B)

Requirement 012 plus its first two phases: the kvb-match skill (match.py add, list, show) feeds the existing review queue, /api/match serves the cards and local-only stale and snapshot posts, and payload files are read only as regular files under /tmp within the sandbox view and 64 KiB. The card at #tasks/match shows face, name, age in days, repository, branch, worktree and files that open while scrolling; right-click or long press marks a line, stale cards cannot be accepted. Accept, reject and the passkey release follow in phase C after the screenshot feedback. Tests run once on unify/skills-20261114 after the merge (operator order 2026-11-14).

🎯 Fix: 75 %
💥 Break: 8 %
💸 Tokens: 100 %
⏱️ Velocity: 100 %
🛡️ Security: 95 %
🏆 Score: 66
🚦 Gate: ⛔ fix 75 % < 90, break 8 % > 5; security 95 % < 100: ask the operator before the commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-14 21:36:40 +00:00
1 parent a2a03995cb
commit 8bc7209ed1
23 files changed
+1407 -15

No files matched your search

+149
View File
@@ -0,0 +1,149 @@
# 012 - Match Review
## User Story
As the operator, I want every waiting commit and operator command as a card
in one stack under Tasks, decide each with a swipe and release all decisions
with one passkey at the end, so that I review agent work fast without
terminal prompts.
## Decisions (operator-confirmed 2026-11-14; do not re-litigate)
1. **Cards**: staged commits (diff, score, gate) and operator commands with
their payload: the command, its directory, its reason and the content of
every file the command reads (an issue body, a script, a list file).
Rejected: staged commits only; decision rows as cards (they keep their own
pick view).
2. **Place**: a Match view under the Tasks tab; the Tasks tab carries a badge
with the number of waiting cards.
3. **Card layout**: on top the agent's face, below it the agent's name and
its age in days (since its first session), then repository, branch and
worktree; below them the affected files, each collapsed, opening one
after another while the card scrolls down and showing the diff (commits)
or the file content (command payloads) with line numbers.
4. **Marks**: a right-click on a code line (a long press on touch) opens a
short comment field; the mark stays on the card.
5. **Decide**: the green check at the bottom right, a swipe right or the
right arrow key accepts; the red cross at the bottom left, a swipe left or
the left arrow key rejects and opens a feedback popup prefilled with the
card's marks (file, line, comment), editable; a swipe up or the up arrow
key moves the card to the back of the stack. Nothing runs while the
operator swipes.
6. **Release**: after the last card, a list overview shows every decision
with a way to change it; one passkey signature over the list of card id,
tree or payload hash and decision releases them all. Accepted commits:
the agent checks the signature with `approval.py verify` against the
signed hash and commits. Accepted commands: the hub runs them as it runs
operator rows today. Rejections: a radio call with the feedback text goes
to the card's agent. Rejected: a passkey per card; a release button
without a passkey.
7. **Source**: the existing hub review queue (`approval.py`) and the operator
rows stay the source of truth. A thin `kvb-match` skill (`match.py add`,
`list`, `show`) lets an agent add a finished stage as a patch snapshot
(staged diff, tree hash, score) and shows the cards in a terminal.
Rejected: a second queue next to the reviews; a UI over the reviews only.
8. **Snapshot binding**: a card shows the patch or payload as it was when it
was added; when the agent's staged tree or a payload file changes
afterwards, the card shows `stale` and cannot be accepted until it is
added again.
9. **Gone rows**: a card whose review or operator row the server no longer
has leaves the stack on the next refresh; it never shows a 404.
10. **Responsive**: the view works at 390 px and on desktop, with touch
swipe and mouse drag. Reaching the hub from a phone is a separate
requirement.
## Approach
```mermaid
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> Q1
subgraph Q["🗂️ A · Queue and skill"]
Q1["🧩 match.py add, list, show over the review queue"] --> Q2["📦 Operator rows as cards with payload files"]
Q2 --> Q3["🔒 Snapshot hash, stale and gone detection"]
Q3 --> QT{"🧪 Unit tests green?"}
QT -- "🔴 no: fix" --> Q1
end
QT -- "🟢 yes" --> C1
subgraph C["🃏 B · Card"]
C1["🙂 Face, name, age, repository, branch, worktree"] --> C2["📜 Files open on scroll, diff with line numbers"]
C2 --> C3["🖱️ Right-click and long-press marks"]
C3 --> CT{"🧪 E2E at 1920, 1366, 390 green?"}
CT -- "🔴 no: fix" --> C1
CT -- "🟢 yes" --> CF{"💬 Operator feedback on screenshots?"}
CF -- "✏️ changes" --> C1
end
CF -- "👍 fits" --> D1
subgraph D["👉 C · Decide and release"]
D1["↔️ Swipe, buttons, arrow keys, later"] --> D2["📝 Feedback popup prefilled from marks"]
D2 --> D3["📋 List overview of all decisions"]
D3 --> D4["🔑 One passkey signature over ids, hashes, decisions"]
D4 --> D5["🚀 Commits verified and committed, commands run, calls sent"]
D5 --> DT{"🧪 Release and negative control green?"}
DT -- "🔴 no: fix" --> D1
DT -- "🟢 yes" --> DF{"💬 Operator feedback?"}
DF -- "✏️ changes" --> D1
end
DF -- "👍 fits" --> E1["🏁 Review, commit with operator OK, hand-over"]
```
## Acceptance Criteria
### Queue and skill
- [ ] `match.py add --repo <worktree>` in a worktree with staged changes adds
one card whose patch equals `git diff --cached` and whose hash equals
`git write-tree`; `match.py list` shows it and `match.py show <id>`
prints its patch.
- [ ] Every open operator row appears as a card with its command, directory,
reason and the content of each regular file its command names; a
symlink or a file over the size limit is shown as refused, not read.
- [ ] A card whose staged tree or payload file changed after it was added
shows `stale` and its accept is disabled.
- [ ] A card whose review or operator row the server no longer returns is
gone from the stack after the next refresh, without a page reload.
### Card
- [ ] A card shows the agent's face, name, age in days, repository, branch
and worktree, and the file list.
- [ ] Scrolling down a card opens its files one after another; each shows
its diff or content with line numbers.
- [ ] A right-click or a long press on a code line adds a mark with a
comment; the mark is shown at its line.
### Decide and release
- [ ] Swipe right, the check button and the right arrow record accept; swipe
left, the cross button and the left arrow open the feedback popup
prefilled with every mark of the card; swipe up and the up arrow move
the card to the back; no commit and no command runs before the
release.
- [ ] The list overview shows every decision and lets each be changed
before the release.
- [ ] The server refuses a release whose passkey signature does not cover
exactly the listed card ids, hashes and decisions, and refuses a
replayed signature.
- [ ] After a release, `approval.py verify` accepts an accepted commit only
at its signed tree hash; a changed index is refused.
- [ ] After a release, each accepted command runs once and its result is
shown; each rejected card's agent receives a radio call whose text
contains the feedback.
- [ ] The Tasks tab badge equals the number of waiting cards.
### Tests
- [ ] Unit: `match.py add`, `list`, `show`; the snapshot hash; stale and gone
detection; release signature verification for a valid, a tampered and
a replayed list; the feedback prefill from marks.
- [ ] Integration: `approval.py verify` against a released list; payload
extraction from operator rows, including a symlink and an oversized
file that are refused.
- [ ] E2E: Chromium and Firefox at 1920, 1366 and 390 px swipe through three
cards (a commit, a command, a stale card), mark a line, reject with
feedback, open the list overview and release through a virtual WebAuthn
authenticator; negative control: a decision changed after signing is
refused.
+1
View File
@@ -12,3 +12,4 @@ skill defines the format.
- [006 - Score Metric Overlays](006-score-metric-overlays.md)
- [007 - Resources View](007-resources-view.md)
- [008 - Home Dashboard](008-home-dashboard.md)
- [012 - Match Review](012-match-review.md)