# 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 ` 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 ` 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.