{"id":"review-deck","repo":"mentalfl0w/review-deck","url":"https://github.com/mentalfl0w/review-deck","name":"review-deck","description":"Human-in-the-loop code review workspace for Paseo with inline file comments and project-level AI processing.","categories":["productivity","code-review","git"],"platforms":[],"caveats":["Requires Paseo 0.8.x (currently beta)."],"images":["https://raw.githubusercontent.com/mentalfl0w/review-deck/ecff1bd2d3f568cbceb549ba58f5f50ded77bda8/images/review-deck.png"],"themes":[],"health":{"manifestValid":true,"hasReadme":true,"hasLicense":true,"hasTests":true,"hasTypecheckScript":true,"updatedRecently":true},"scannedAt":"2026-10-15T12:34:22.790Z","addedAt":"2026-09-10T08:38:57+03:00","version":"2.1.0","security":{"status":"passed","blockingFindings":0,"advisoryFindings":0,"scannedAt":"2026-10-15T12:14:24.405Z","commit":"ecff1bd2d3f568cbceb549ba58f5f50ded77bda8"},"author":"mentalfl0w","license":"MIT","paseoVersionRequirement":">=0.10.0","descriptionNodes":[{"type":"text","text":"Human-in-the-loop code review workspace for Paseo with inline file comments and project-level AI processing."}],"caveatNodes":[[{"type":"text","text":"Requires Paseo 0.8.x (currently beta)."}]],"manifest":{"id":"review-deck","description":"Human-in-the-loop code review workspace for Paseo","requirements":{"paseo":">=0.10.0"}},"repoMeta":{"stars":1,"defaultBranch":"main","pushedAt":"2026-10-11T03:22:59Z"},"owner":{"login":"mentalfl0w","avatarUrl":"https://avatars.githubusercontent.com/u/30333935?v=4"},"installNotesHtml":"<p>Review Deck requires Paseo 0.10.0 or newer (<code>>=0.10.0</code>). Installing from npm requires Paseo 0.11.0 or newer.</p>\n<p>Install the published npm package:</p>\n<pre><code class=\"language-sh\">paseo plugin install npm:@mentalfl0w/review-deck@2.1.0\npaseo plugin ls\n</code></pre>\n<p>To install directly from GitHub instead:</p>\n<pre><code class=\"language-sh\">paseo plugin install git:https://github.com/mentalfl0w/review-deck.git\n</code></pre>\n<p>Open the panel from the Command Center (<strong>⌘K</strong> on macOS, <strong>Ctrl+K</strong> on Windows/Linux) with <strong>Open Review Deck</strong> — or, from inside an Agent, use <strong>Open Review Deck for this Agent</strong> or the <strong><code>/review-deck</code></strong> slash command for the Agent-bound deck.</p>\n<p>The plugin depends on an existing Paseo workspace and Agent. No additional model configuration is required — models are configured in the Paseo Agent settings, and Review Deck uses the model of the Agent you select.</p>","limitationsNotesHtml":"<ul>\n<li><strong>Unfinished comments remain queued.</strong> Only an explicit <code>COMPLETED</code> outcome from the matching Batch turn clears a comment; missing, malformed, duplicate, conflicting, stale, ambiguous, or mismatched-turn outcomes remain pending. Review Deck persists a send intent and stable message id before dispatch. A successful <code>send()</code> acknowledgment or exact timeline message proves delivery, not completion. The SDK exposes no stable rejection discriminator, so every <code>send()</code> failure is conservatively treated as unknown and never retried automatically. Timeline evidence can recover delivery; <code>unknown</code> or <code>accepted</code> batches without a proven Turn retain their claims across restarts. Active v1 batches without delivery identity are never auto-linked, failed, or released by Turn/Archive events; explicit release is required and may duplicate work. Only a prepared batch with no persisted send attempt gets a two-minute grace, released after a successful refresh shows the Agent is not running or initializing. A proven Turn can be released as unresolved after it stops; Archive events resolve only new batches whose delivery state proves they are not in flight. Status/timeline lookup failure or a null Agent snapshot keeps the claim. The Agent's claim is not independent verification, so review the resulting diff before accepting it.</li>\n<li><strong>AI Review recovery is bounded.</strong> After reload, a running review resumes only when its labeled child still matches the stored parent/workspace and is not archived. Ru…</li>\n</ul>","readmeText":"# Review Deck\n\nA **human-in-the-loop review plugin for Paseo**. When an Agent finishes a change in a Paseo workspace (worktree), reviewing the result across many files is awkward — you have to keep viewing diffs, annotate them, feed your feedback back to an Agent, and clean up afterwards. Review Deck turns a Git changeset into a **navigable review workspace**: browse files and hunks, leave comments right next to the exact diff, collect them in a project queue, and route each workspace's comments to an Agent in that same workspace.\n\n![Review Deck — human-in-the-loop review workspace for Paseo](images/review-deck.png)\n\n## The problem\n\nAfter an Agent works in a Paseo workspace, the changes are spread across many files, hunks, and commits. A careful human review means:\n\n- **Seeing** what changed — file by file, hunk by hunk\n- **Annotating** the exact diff with notes and decisions\n- **Feeding back** those comments to an Agent that can act on them\n- **Cleaning up** once the feedback has been handled\n\nReview Deck never treats AI as the final decision. AI-reported facts and inferences, local Rule signals, human notes, and executed-command evidence are distinct; none automatically resolves a Finding.\n\n## Main capabilities\n\n| Capability | What it does |\n|---|---|\n| File-first review UI | Navigate changed files and hunks with the exact diff shown next to the change details; wide layout shows file list and file details side by side, compact layout drills down |\n| Inline comments | Select exact diff lines (click / Shift-click on desktop, two taps in compact layouts) or keep a hunk-level anchor; comments follow safe re-anchors across snapshots |\n| Project comments queue | The top queue aggregates every saved comment for the current project, grouped by workspace, scope, and file |\n| AI processing | Group project comments by workspace and submit each group to an Agent in that workspace. Only explicit `COMPLETED` outcomes remove comments; stale, failed, and unresolved comments stay queued |\n| Agent-targeted Review Deck | Open Review Deck from an Agent's Command Center item, `/review-deck`, or Composer Pill; the Agent is preselected, and all of these open the same workspace-scoped tab |\n| Paseo-native entries | Workspace Header badges prioritize actionable pending comments, then stale/ambiguous comments, then unread AI findings; the native popover shows review progress, queue state, active reviews, and Deck/Queue actions. Agent Composer Pill menus open the Deck or Queue in that same workspace tab, review current changes with AI, or submit that workspace's comments; run/submit actions are gated by workspace, Agent, diff, and batch state. |\n| Review timelines | `review-deck-batch` rows update by stable id from submitted/running to completed/partial/failed. AI-review rows summarize completion, finding/high-risk counts, and token usage. Both contain status metadata only — never findings, comment text/IDs, file paths, patches, or cwd. |\n| Review defaults | Interface language (Auto follows the browser/device preferred language; selecting 中文 or English localizes the settings form, Header status popover, and Pill action labels), diff layout (Auto / Unified / Split), reviewer strategy and Provider / Model / Thinking, cache, token-usage display, and the default Economical / Balanced / Deep preset. Settings are host-scoped under **Settings → Plugins → Review Deck** |\n| AI review & explain | Explain a hunk, review one file, or review the current target. The preset sets risk coverage and default depth; Targeted / Full can override patch context per run. Reviewers use Read-only/Plan where available; Codex falls back to provider options that force a read-only sandbox and on-request approvals. Providers with no documented safe mode (the current Pi catalog exposes none) fail closed. Codex/OpenCode receive Paseo `outputSchema`; other providers use Markdown fallback. Structured findings may include executable + argv verification suggestions; free-form `suggestedCheck` text is never executed. |\n| Finding to Queue | A human can edit a Rule or structured AI Finding into a normal project comment. The server rechecks the current target and unique Hunk anchor; an existing comment is never overwritten |\n| Verification | Interactive Terminal remains separate. Captured mode accepts approved tools after exact-command confirmation; output is a ≤32 KiB memory-only tail. Original/observed fingerprints flag persistent drift, but change-and-restore can evade comparison. POSIX group kill cannot reach escaped descendants. macOS only; Linux/Windows fail closed |\n| Browser Preview | Configure an HTTP(S) preview URL per project and Host in **More**. **Open Preview** uses Paseo's workspace browser where `navigation.openBrowser` is available; it never falls back to an external browser. |\n| Scope | Review the working tree, staged changes, a branch, or specific commits |\n| Safe hunk rejection | Reject a hunk by reversing its patch — only when the workspace still matches the reviewed snapshot, so unrelated work is never overwritten |\n| File-level actions | Mark a whole file reviewed in one tap, ask an Agent to explain a whole file, or revert all of a file's changes at once — comment-anchored hunks are skipped automatically |\n| Bilingual UI | English and 中文 (Chinese) |\n\n```mermaid\nflowchart TB\n    A[Open Review Deck] --> B[Choose project / workspace]\n    B --> C[Browse changed files]\n    C --> D[Write one file-level comment per file]\n    D --> E{More files to review?}\n    E -- yes --> C\n    E -- no --> F[Project comments queue]\n    F --> G[Group comments by workspace]\n    G --> H{Eligible Agent in workspace?}\n    H -- yes --> I[Select an Agent for each workspace group]\n    H -- no --> J[Leave comments pending]\n    I --> K[Send one ReviewBatch per workspace]\n    K --> L[Agent reports COMMENT OUTCOMES]\n    L --> M[Remove COMPLETED comments only]\n    L --> N[Keep STALE / FAILED / UNRESOLVED comments]\n    L -.-> O[Update the same timeline row]\n```\n\n## Architecture\n\nReview Deck is a Paseo **0.10.0+** plugin using the v0.8 runtime-entry format: root `index.client.tsx` and `index.server.ts` entries sit above the React Native panel, typed RPC contracts, and server service layer.\n\nReview state uses a versioned v2 envelope at `~/.paseo/review-deck/reviews.json`; ReviewBatch state uses a separate strict v2 envelope at `~/.paseo/review-deck/review-batches.json`.\n\nA valid v1 ReviewBatch store migrates only after its exact bytes are preserved in a non-overwritable read-only `.v1.bak`. Damaged data or conflicting backups fail closed.\n\nTransient AI Review run metadata uses a strict v1 store at `~/.paseo/review-deck/runs.json`; it stores target/request identity only, never prompts, patches, or review text.\n\nAI review cache uses a version-2 envelope with v1 byte-preserving migration, a 30-day TTL, and a 256-entry cap.\n\nCaptured process metadata lives in a separate strict v1 `process-verification-runs.json` store with a 30-day TTL and 256-run cap. Output is bounded and never persisted.\n\nGit access is centralized behind one runner with fingerprint-checked safety.\n\n```mermaid\nflowchart LR\n    subgraph panel[\"client/ — React Native panel\"]\n        Panel[\"ReviewDeckPanel\"]\n        Hooks[\"hooks/ — scope · snapshot · actions<br/>agent review · comments · file view · line selection\"]\n        UI[\"components/ — file navigator · file detail · hunk card<br/>diff view · file view · anchor issues\"]\n        Panel --> Hooks\n        Panel --> UI\n    end\n\n    subgraph shared[\"shared/ — contracts\"]\n        RPC[\"zod schemas + defineRpc contracts<br/>fingerprints · comments · ReviewBatch\"]\n    end\n\n    subgraph server[\"server/ — service layer\"]\n        Svc[\"ReviewService\"]\n        Anchor[\"AnchorEngine\"]\n        Git[\"GitRunner\"]\n        Parse[\"DiffParser · FindingDetector · rules\"]\n        Store[\"StateStore\"]\n        AiCache[\"AiReviewCacheStore\"]\n        BatchStore[\"ReviewBatchStore\"]\n        ProcessSvc[\"ProcessVerificationService\"]\n        ProcessRunner[\"ProcessRunner · direct argv · bounded tail\"]\n        ProcessStore[\"ProcessVerificationStore\"]\n        Svc --> Anchor\n        Svc --> Git\n        Svc --> Parse\n        Svc --> Store\n        Svc --> AiCache\n        Svc --> BatchStore\n        Svc --> ProcessSvc\n        ProcessSvc --> ProcessRunner\n        ProcessSvc --> ProcessStore\n    end\n\n    ClientEntry[\"index.client.tsx (repo root)<br/>panels · Command Center · /review-deck<br/>timeline · settings · header / composer entries\"]\n    ServerEntry[\"index.server.ts (repo root)<br/>creates ReviewService · registers<br/>RPCs + turn hooks · starts maintenance\"]\n    Agents[\"Paseo Agents\"]\n    Repo[(\"workspace repo\")]\n    State[(\"reviews.json · v2\")]\n    Batches[(\"review-batches.json · v2\")]\n\n    BatchStore --> Batches\n    ClientEntry --> Panel\n    Panel -- \"useRpc\" --> RPC\n    RPC --> ServerEntry\n    ServerEntry --> Svc\n    Git -- \"git -C <cwd>\" --> Repo\n    Store --> State\n    Svc -- \"workspace ReviewBatch · explanation · review\" --> Agents\n```\n\n\n- **index.client.tsx** is the Paseo 0.10 client runtime entry — it registers one workspace-scoped Review Deck tab, Command Center items, `/review-deck`, handoff / batch / AI-review timeline renderers, Review defaults, a workspace status popover, and subscription-backed Agent composer menus. Header, Agent, Queue, targeted-review, and timeline entry points reuse that tab.\n- **index.server.ts** is the Paseo 0.10 server runtime entry — it retains the settings handle, constructs `ReviewService`, registers RPC and `agent.turn_started` / `agent.turn_ended` lifecycle handlers, and starts maintenance; cleanup removes both hooks and stops maintenance.\n- **client/** owns presentation and intent only — every mutation goes through an RPC.\n- **shared/review.ts** is the single source of truth for review RPC request/response shapes (zod), imported by both sides.\n- **shared/review-batch.ts** defines ReviewBatch state and the strict `review-deck-batch` v1 timeline payload. The stable timeline item id replaces one row as status changes; the data includes only workspace ID, status, outcome counts, and timestamps.\n- **shared/review-handoff.ts** retains the version-1 `review-deck-handoff` renderer for older timeline rows; its content-minimal payload records only a positive comment count and ISO submission timestamp.\n- **shared/review-activity.ts** defines metadata-only workspace indicators, the on-demand working-tree summary, per-workspace read marking, and the strict `review-deck-ai-review` timeline payload. Badge refresh never parses Git; detailed block counts load only when the Header Popover opens.\n- **`server/`** composes small, injectable classes: `GitRunner` wraps Git invocations with output limits and pins parsed diff headers to canonical `a/` and `b/` prefixes; `StateStore` validates and atomically migrates the v2 review envelope; `ReviewBatchStore` persists batch transitions in a strict versioned envelope; `DiffParser` provides the shared single-hunk body parser; `AnchorEngine` resolves anchors without auto-selecting ambiguity; and `ReviewService` orchestrates Git review and Agent batches.\n- **Verification Terminal** opens an interactive workspace terminal after explicit confirmation. The user inspects output in Paseo; Review Deck does not infer command success or persist terminal output in v2.0.\n\n- **Agent updates are event-driven.** One owned agent subscription feeds the panel registry and composer pills; workspace activity and agent updates trigger fingerprint-only snapshot checks, with a 60-second fallback.\n- **Damaged review state fails closed.** Legacy files migrate automatically; invalid JSON or schema data surfaces an error and is never replaced with an empty store.\n\nRequires **Paseo 0.10.0 or newer** (`>=0.10.0`).\n\n## Usage\n\n1. **Open the panel.** In a workspace Header, the **Review** button may be icon-only or inside the compact-layout overflow menu. A live Agent's Composer shows a **Review** Pill beside Tasks/Subagents. The Command Center and `/review-deck` also open it. These entry points reuse one Review Deck tab per workspace.\n2. **Pick a project and workspace.** Use the pickers at the top of the panel. Selecting a project or workspace brings that workspace to the Paseo foreground.\n3. **Browse and select the change.** Work through the changed files; each file shows its hunks with the exact diff next to the change details. Click a line number to select it; Shift-click extends a range on desktop, while compact layouts use two taps.\n4. **Leave a comment.** Save a comment against the selected line range, or leave the selection empty to keep the hunk-level anchor.\n5. **Watch the queue.** The project comments queue at the top summarizes all saved comments for the current project.\n6. **Submit workspace batches.** The queue groups comments by workspace. An Agent-launched Review Deck preselects that Agent; otherwise one freshly verified idle Agent bound to the exact workspace is selected. Running or initializing Agents remain visible but cannot receive comment batches. Workspaces without an eligible Agent stay queued.\n7. **Track outcomes and delivery.** Comments remain queued until the matching Agent turn reports explicit `COMPLETED` outcomes. Each send has a stable message id; an ambiguous send remains claimed and is never retried automatically. A confirmed duplicate-risk action can release a stranded claim for a user-confirmed retry.\n8. **Tune the defaults.** Under **Settings → Plugins → Review defaults**, choose the panel language (Auto / 中文 / English) and the default diff layout (Auto / Unified / Split); these host-scoped settings apply everywhere Review Deck opens.\n9. **Run a verification command.** Review the structured executable and arguments, then confirm. Review Deck opens an interactive terminal in the current workspace; inspect its output in Paseo. v2.0 does not mark pass/fail automatically.\n10. **Preview the project.** On Electron, open **More → Browser Preview**, set the project's HTTP(S) URL, then choose **Open Preview**. The URL is saved per project on the current Host.\n\n## Limitations\n\n- **Unfinished comments remain queued.** Only an explicit `COMPLETED` outcome from the matching Batch turn clears a comment; missing, malformed, duplicate, conflicting, stale, ambiguous, or mismatched-turn outcomes remain pending. Review Deck persists a send intent and stable message id before dispatch. A successful `send()` acknowledgment or exact timeline message proves delivery, not completion. The SDK exposes no stable rejection discriminator, so every `send()` failure is conservatively treated as unknown and never retried automatically. Timeline evidence can recover delivery; `unknown` or `accepted` batches without a proven Turn retain their claims across restarts. Active v1 batches without delivery identity are never auto-linked, failed, or released by Turn/Archive events; explicit release is required and may duplicate work. Only a prepared batch with no persisted send attempt gets a two-minute grace, released after a successful refresh shows the Agent is not running or initializing. A proven Turn can be released as unresolved after it stops; Archive events resolve only new batches whose delivery state proves they are not in flight. Status/timeline lookup failure or a null Agent snapshot keeps the claim. The Agent's claim is not independent verification, so review the resulting diff before accepting it.\n- **AI Review recovery is bounded.** After reload, a running review resumes only when its labeled child still matches the stored parent/workspace and is not archived. Runs past the one-hour metadata TTL, missing children, archived children, or prompt/schema-version mismatches are abandoned. The UI's active poll loop has a separate five-minute wait cap. `runs.json` stores metadata only; review content stays in the Agent timeline or optional cache.\n- **Workspace routing is fail-closed.** A batch is bound to one workspace and one Agent in that workspace. Legacy c"}