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>
7.5 KiB
7.5 KiB
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)
- 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).
- Place: a Match view under the Tasks tab; the Tasks tab carries a badge with the number of waiting cards.
- 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.
- Marks: a right-click on a code line (a long press on touch) opens a short comment field; the mark stays on the card.
- 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.
- 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 verifyagainst 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. - Source: the existing hub review queue (
approval.py) and the operator rows stay the source of truth. A thinkvb-matchskill (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. - 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
staleand cannot be accepted until it is added again. - 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.
- 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
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 equalsgit diff --cachedand whose hash equalsgit write-tree;match.py listshows it andmatch.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
staleand 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 verifyaccepts 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 verifyagainst 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.