RFD D72: Review Engine for Workspace Files
Summary
This RFD adds jp-review, a command plugin for reviewing workspace files with the assistant as a peer. A reviewer anchors comments and suggested edits to exact source ranges and submits them in passes; each pass runs one conversation turn in which the assistant edits the files and replies to every comment with a verdict. The plugin persists each review as a locked directory in the store and exposes every operation both as a jp review CLI subcommand and over a local HTTP API.
Terminology
- Review: a set of workspace files, their recorded versions, the comments on them, and the conversation in which passes run.
- Version: a snapshot of a review's files at a point in time, numbered sequentially from 1.
- Anchor: the target of a comment: a version, optionally a file in that version, and optionally a source range within that file.
- Comment: a remark with an anchor, its replies, and a status. A suggestion is a comment that includes replacement text for its anchored range.
- Pass: a batch of comments and replies submitted to the assistant, together with the turn that answers them.
- Verdict: the assistant's disposition on a comment:
accept,amend,decline,defer, orask.
Other review tools call a comment and its replies a thread; this RFD uses "comment" for both to avoid confusion with JP's conversation Thread.
Motivation
Reviewing what the assistant wrote is where a draft becomes a document worth keeping, yet review tooling is the weakest link in the workflow. Today, just review-file opens revdiff in the terminal, collects annotations, and pipes them into jp query under a triage persona. That workflow has four limitations:
- Line-only anchors. Annotating a three-word phrase in a wrapped paragraph can only target the entire line.
- No comment state. Annotations are sent as a single block of text and answered in free-form prose. Tracking which comments were accepted, declined, or left unanswered is up to the reviewer.
- No version history. Once the assistant edits the file, earlier comments point at shifted line numbers, and there is no built-in way to diff what a pass changed.
- Prompt-cache invalidation. Because the file is passed as an attachment, JP re-reads it on every turn and places it before the conversation events. Every edit the assistant makes mutates the prefix of subsequent requests and invalidates the provider's prompt cache.
A review is also a dialogue between peers. A reviewer's comment states a position, and the assistant should push back when it has grounds to disagree. Supporting that back-and-forth requires per-comment state tracking who said what and whether the point is resolved, which neither revdiff nor a plain chat transcript provides.
The same review engine should also support two future workflows without redesign: reviewing commits in a worktree before opening a pull request, and replying to specific passages of an assistant message. Both reduce to versioned text snapshots, range-anchored comments, and passes.
Design
Overview
| Component | Location | Role |
|---|---|---|
| Core | crates/plugins/command/review | Pure review domain model: carries anchors across versions and formats pass prompts. |
| Store | same crate | Reads and writes review state under an exclusive file lock. |
| Instructions | configuration file generated by jp review init | System instructions and tool configuration for review turns. |
| CLI | jp review ... | Terminal interface for interactive and scripted use. |
| Tools | plugin.command.review.reply, plugin.command.review.comment | Plugin tools the assistant calls to reply to or open comments. |
| Server | jp review serve | Local HTTP API for browser frontends, managing delegated turns. |
| Client | jp_plugin::client | Shared async plugin-protocol client extracted from jp-serve-web/jp-serve-chat. |
The on-disk store is the sole integration point between processes. The CLI, HTTP server, and tool invocations run as separate OS processes with no shared memory: the host spawns a fresh plugin process for each tool call and closes its stdin after init, so a tool cannot communicate with a running jp review serve process or issue host requests.
The review core operates on plain text and line/column coordinates, with no Markdown awareness. Both the core and the HTTP server convert positions to and from byte offsets with md_html::Lines (RFD 124), and the server renders files for browser views with md-html.
End-to-End Example
$ jp review start docs/rfd/drafts/D72-review-engine-for-workspace-files.md
R-1h4k2m9: 1 file, version 2 (version 1 is the base)
$ jp review comment R-1h4k2m9 \
--at docs/rfd/drafts/D72-review-engine-for-workspace-files.md:42:5-43:18 \
"This contradicts the Security paragraph."
R-1h4k2m9#1
$ jp review comment R-1h4k2m9 \
--at docs/rfd/drafts/D72-review-engine-for-workspace-files.md:60-64 \
--replace "A review is one file."
R-1h4k2m9#2
$ jp review comment R-1h4k2m9 "The motivation is too long."
R-1h4k2m9#3
$ jp review submit R-1h4k2m9 --only 1,2 -m "First half only."
Pass 1 on a new conversation, jp-c17629384710.
#1 accept Fixed: it binds to loopback, as the Security paragraph says.
#2 decline The longer wording names the failure case the short one drops.
Version 3: 1 file changed.Comment 3 remains in draft status for a later pass. Because the assistant rewrote the lines covered by comment 1, that comment stays anchored to version 2 alongside its reply. The reviewer can reply to comment 2 or mark it resolved.
Data Model
Version. A version maps each file in the review to its snapshot content. start records the current working-tree files as a version. When base is configured (see Configuration), start first runs the configured command for each file and records its output as version 1 (labelled base), so the initial diff shows changes relative to HEAD. The review engine does not invoke a version control system directly. submit records a new version before starting a pass if the working-tree files differ from the latest version (capturing manual edits made outside the review), and records another version when the turn completes (capturing the assistant's edits).
Anchor. An anchor specifies a version, an optional file path, and an optional range within that file. Omitting the file path anchors the comment to the review as a whole; omitting the range anchors it to the entire file. Positions use 1-based line:column coordinates with columns counted in Unicode code points. A line ends at \n, \r\n, or a \r not followed by \n. A column-qualified range is half-open ([start, end)), while a line-only range covers the specified lines in full. An anchor does not duplicate the covered text; the text is read from the referenced version.
Carrying anchors across versions. To project a comment onto a newer version, the core computes a line diff of the file between the anchor's version and the target version. If every line spanned by the anchor is unchanged, the anchor shifts to the corresponding line numbers in the target version with its column offsets intact. If any line in the range was modified or removed, the anchor remains on the last version where it resolved cleanly and is marked outdated in later versions. The engine never uses fuzzy text matching: an anchor either resolves to exact unchanged lines or is marked outdated. Projected positions are computed on read and never persisted.
Comment. A comment consists of an author, an anchor, a Markdown body, and an ordered list of replies. A suggestion attaches replacement text to a range anchor; an empty replacement string represents a deletion. The review engine never applies suggestions directly to workspace files; the assistant applies, amends, or declines them during a pass.
Both participants can create comments: the reviewer via the CLI or web UI, and the assistant via the review_comment tool during a pass.
A comment's status is derived from its history and pass state:
| Status | Meaning |
|---|---|
draft | Created by the reviewer and not yet submitted in a pass. |
open | Submitted and under discussion; awaiting a response from the other peer. |
resolved | Closed by the reviewer. |
Only the reviewer can resolve a comment. A reply written by the reviewer is held as a draft until the next pass is submitted. A comment opened by the assistant starts in open status, awaiting the reviewer's response.
Verdict. Every assistant reply to a reviewer comment must include a verdict:
| Verdict | Meaning |
|---|---|
accept | Agrees with the comment and makes the requested change. |
amend | Agrees with the underlying issue but makes a different change. |
decline | Makes no change and explains why. |
defer | Agrees the point is valid but out of scope; names where it was tracked (e.g. a ticket). |
ask | Asks a clarifying question before making a change. |
Pass. A pass records the version it was submitted against, the comments and replies included in the submission, an optional overall message for the pass, and the conversation ID in which the turn ran. Its terminal state is completed when the turn finishes normally, stopped when the turn is stopped or aborted, failed when the host returns a query error, or interrupted if the host process exited before recording an outcome.
Store
Each review lives in its own directory named after its ID (R- followed by a doc::id epoch identifier), allocated atomically by creating the directory:
<store>/
.epoch
1h4k2m9/
review.json
.lock
blobs/<sha256>review.json stores all review metadata: title, tracked file paths, version manifests, comments, replies, and passes. Every mutation acquires an exclusive lock on .lock, reads review.json, applies the change, writes the updated state to a temporary file, and atomically renames it over review.json. Readers never acquire the lock and always observe a complete file.
The locking mechanism is the same OS advisory lock (File::lock) that ticket::board uses on .board.lock: the lock file is never deleted, and the kernel releases the lock automatically if the holding process exits or crashes. The CLI, HTTP server, and plugin tools each hold the lock only for the duration of a single read-modify-write cycle, never across a running turn.
Holding the lock across the read and write lets mutations enforce state invariants: submit rejects concurrent passes on the same review, and review_reply rejects replies to withdrawn comments.
Every comment, reply, and pass records its author and timestamp. The reviewer's author name comes from user.name (resolved the same way as in jp rfd and jp ticket), while the assistant's author name comes from the assistant option. Comments are numbered sequentially starting at 1 within a review and referenced as R-1h4k2m9#2 (matching ticket comment syntax T-02wt0kx#1). Withdrawing a draft comment leaves its number retired so later comment IDs never shift.
File snapshots are content-addressed by SHA-256 under blobs/<sha256>. Each blob is written to disk before the review.json update that references it.
review.json also carries a monotonically increasing revision counter (used by frontends for long-polling or change detection) and a format version integer for future schema migrations.
Store location. The dir option configures the store path. Relative paths resolve against the workspace root so teams can commit reviews to version control if desired. When dir is unset, the store defaults to review/ inside the user-local workspace storage directory (paths.user_workspace in the plugin init payload). If a workspace has no user-local storage directory and dir is unset, commands fail with an error instructing the user to set plugins.command.review.options.dir.
Passes and the Conversation
submit sends the review's pending draft comments and replies (or the subset selected with --only, enabling staged reviews):
- Reject the submission if another pass on the review is still in progress.
- Record a new version if any tracked file in the working tree differs from the latest version.
- Project each pending comment onto that version. Any comment whose anchor is already outdated is sent with the excerpt from its original version and marked as outdated.
- Record the pass in
review.json. - Delegate a turn to the host via
query. - When the turn finishes, record a new version if the assistant modified any tracked files, and record the pass outcome.
Conversation binding. By default, the first pass starts a new conversation (query with new = true) titled after the review. Passing --id binds the review to an existing conversation instead, preserving the context of the conversation that produced the files. Subsequent passes reuse the conversation established by the first pass.
Config overlays from options.cfg and any --cfg flags passed to submit are forwarded in the query request's cfg list. On an existing conversation, the host records those overlays as a configuration delta that persists across later turns, matching jp query --cfg.
Pass prompt. The first pass in a conversation embeds the full contents of each tracked file, with line numbers, in the user message:
# Review R-1h4k2m9, pass 1
First half only.
## docs/rfd/drafts/D72-review-engine-for-workspace-files.md (version 2)
```
1 | # RFD D72: Review Engine for Workspace Files
2 |
[...]
```
## Comments
### R-1h4k2m9#1 at D72-review-engine-for-workspace-files.md:42:5-43:18
> the server binds to every interface by default
This contradicts the Security paragraph.
### R-1h4k2m9#2 at D72-review-engine-for-workspace-files.md:60-64, suggestion
```diff
-`review.json` is the whole review except the contents of its files [...]
+A review is one file.
```Later passes omit the full files. Instead, a subsequent pass message opens with a unified diff of any external edits made to the files since the previous pass ended, followed by the newly submitted comments and reviewer replies. Because each file enters the conversation history once and later passes only append messages, the provider's prompt cache remains valid across passes.
Every comment in the pass message includes the quoted excerpt from its anchored version. Line numbers match the files at the start of the turn; once the assistant begins editing a file, the quoted excerpt lets the assistant locate the target passage even after line numbers shift.
The pass message contains only review data; behavioral instructions live in configuration.
Instructions. All instructions governing how the assistant conducts a review live in workspace-owned files rather than inside the plugin binary:
- Tool definitions (
review_replyandreview_comment) document each tool, parameter, and verdict variant. - A configuration file (
review.toml) provides the system instructions: reply to every comment in the pass, evaluate each comment on its merits rather than treating it as an unconditional command, keep replies concise, and open new comments for issues the reviewer missed. It also enables both review tools.
jp review init DIR writes review.toml into DIR, just as jp review tools init DIR writes the tool definitions. Because review.toml is a standard JP configuration file referenced via options.cfg, the host loads it like any --cfg target, and projects can edit it, replace it, or layer a persona on top of it.
Turn execution. Delegated turns started by a plugin run headlessly (prepare_turn in jp_cli): terminal output is routed to a sink, tools that would normally prompt for interactive approval execute without prompting, and interrupts stop the turn. Consequently, the tool set enabled by the review's configuration is the primary boundary on what a pass can modify.
Tools
[conversation.tools.review_reply]
source = "plugin.command.review.reply"
[conversation.tools.review_comment]
source = "plugin.command.review.comment"jp review tools init DIR writes both tool definitions into DIR, matching jp rfd tools init and jp ticket tools init. Once generated, those files belong to the workspace.
review_reply posts an assistant reply to an existing comment:
| Parameter | Type | Meaning |
|---|---|---|
comment | string | Target comment ID as formatted in the pass prompt (e.g. R-1h4k2m9#2). |
verdict | enum | One of the five verdicts. Required when replying to a reviewer comment; rejected on assistant-opened. |
body | string | Markdown reply body. |
review_comment opens a new comment authored by the assistant:
| Parameter | Type | Meaning |
|---|---|---|
review | string | Target review ID (e.g. R-1h4k2m9). |
path | string, optional | Tracked file path. If omitted, the comment applies to the review as a whole. |
lines | string, optional | 1-based line or line range (42 or 42-45) in the current working-tree file. |
quote | string, optional | Exact substring within lines to narrow the anchor to columns; must occur there once. |
body | string | Markdown comment body. |
Because the assistant may edit files during a pass before calling review_comment, the tool first snapshots a new version if the working-tree files differ from the latest version, then anchors the new comment to that snapshot. If quote is provided, the tool resolves it to line:column coordinates when recording the comment. review_comment has no replacement-text parameter because the assistant can edit workspace files directly.
Each tool acquires the review lock, persists its update, and returns a single-line confirmation. A tool call fails with an actionable error message if:
- the review or comment ID does not exist, or the target comment is still an unsubmitted draft;
- the tool call's conversation ID does not match the review's conversation;
pathis not part of the review,linesfalls outside the file bounds, orquotedoes not match exactly once withinlines;bodyexceedsmax_charscharacters.
Enforcing max_chars in the tool guarantees the bound even when the model ignores prompt instructions. Because each tool call persists its update immediately, stopping a turn mid-pass preserves all replies and comments recorded up to that point.
Both tools write exclusively to the review store. When the store is configured inside the workspace, tool writes are validated against the tool call's workspace access policy (RFD 076), matching jp ticket. When the store lives in the default user-local workspace directory (outside the workspace tree), the tools write to it directly.
CLI
| Command | Description |
|---|---|
start FILE... [--title T] | Create a review and snapshot its initial version(s). |
ls, show ID [--version N] | List reviews, or display a review with comments projected to N. |
diff ID [--from N] [--to M] | Show the line diff between two versions. |
comment ID [--at ANCHOR] [--replace TEXT] [BODY] | Add a draft comment or suggestion. |
reply COMMENT BODY | Add a draft reply to an open comment. |
resolve COMMENT... | --accepted ID | Mark specific comments, or all accept-verdict comments, closed. |
submit ID [--only N,...] [-m BODY] [--id CONVERSATION] [--cfg ...] | Submit pending comments/replies and run a pass. |
close ID | Close a completed review. |
serve [--bind ADDR] [--port PORT] | Run the local HTTP server. |
init DIR | Generate the default review.toml configuration file. |
tools init DIR | Generate the review_reply and review_comment tool configs. |
All commands support structured JSON output via jp --format json.
submit runs the delegated turn in the foreground and streams each assistant reply and comment to the terminal as it is written to the store (since the delegated turn's own output stream is discarded). Pressing Ctrl-C stops the turn: the host routes the first interrupt to the running turn's interrupt handler, preserving the events and tool calls completed so far, and reports the outcome as stopped (see Pass Outcome Tracking). Any comments the assistant had not yet answered remain open.
jp review serve
jp review serve exposes the review operations over a JSON HTTP API and drives delegated turns initiated by browser clients. Like jp-serve-web, the server maintains a persistent plugin-protocol connection to the host so it can start turns with query and stop them with interrupt.
| Endpoint | Description |
|---|---|
GET /api/reviews | List all reviews. |
POST /api/reviews | Create a new review. |
GET /api/reviews/{id}?revision=N&version=V | Return the review if its revision exceeds N (or empty if unchanged) and active-pass status. |
GET /api/reviews/{id}/versions/{n}/file?path=P&format=html|text | Return a file at version n, either rendered with md-html or as raw text. |
GET /api/reviews/{id}/diff?from=N&to=M&path=P | Return the line diff between versions N and M. |
POST /api/reviews/{id}/comments | Create a draft comment or suggestion. |
PATCH, DELETE /api/reviews/{id}/comments/{n} | Update or withdraw a draft comment. |
POST /api/reviews/{id}/comments/{n}/replies | Add a draft reply. |
POST /api/reviews/{id}/comments/{n}/resolve | Resolve a comment. |
POST /api/reviews/{id}/passes | Submit a pass; returns once the delegated turn has started. |
POST /api/reviews/{id}/stop | Stop the active pass on the review. |
Browser clients track state changes by polling GET /api/reviews/{id} with their last seen revision. Because each review_reply tool call increments revision when it writes to review.json, assistant replies appear incrementally while the turn is still running. The server projects each comment's anchor onto the version named by version, the one the client displays (Anchors over HTTP).
Stopping a pass. POST /api/reviews/{id}/stop sends an interrupt request with action = "stop" for the review's conversation. The host applies the stop regardless of which phase the turn is in: before the provider request starts, during response streaming, between phases, or during tool execution (cancelling in-flight tools). The turn preserves all events committed up to that point, the host answers query with outcome = "stopped", and the server records the pass as stopped.
Graceful shutdown. When the server receives a shutdown message from the host, it stops accepting new HTTP requests, sends a stop interrupt for every in-flight pass, awaits each turn's query_complete response, records the post-turn file version and pass outcome, and replies with exit. This matches the shutdown sequence in jp-serve-chat.
The host waits up to plugins.command.review.shutdown_timeout_secs (defaulting to 5 seconds) for the plugin to exit before killing its process group. Once the plugin exits, the host stops any remaining delegated turns and aborts any turn still running 5 seconds later.
| Signal or event at the host | Behavior |
|---|---|
| Ctrl-C while a pass is running | The turn's interrupt handler sits above the plugin's on the signal stack, so the newest running turn stops (outcome = "stopped"). The server stays up. |
| Ctrl-C with no pass running | The host sends shutdown to the plugin. |
| SIGTERM, or a second Ctrl-C while a stop is in progress | The host sends shutdown to the plugin and runs the graceful shutdown sequence above. |
Shutdown exceeds shutdown_timeout_secs plus 7 seconds | The host terminates the plugin, aborts remaining turns, persists committed conversation events, and exits with status 130. |
| Third Ctrl-C, SIGQUIT, or SIGKILL | The host exits immediately; the plugin detects stdin EOF and exits. |
If the plugin is killed at its shutdown timeout or the host exits immediately (the last two rows), an in-flight pass may remain in review.json without a recorded outcome. When the next CLI command or server request reads that review and observes via read_events that the conversation is no longer locked, it reconciles the pass status to interrupted.
Security. Like jp-serve-web, jp review serve binds to 127.0.0.1 by default and has no authentication. Because any client that can reach the server can trigger a turn that edits workspace files without interactive approval, binding to a non-loopback address prints the same security warning as jp-serve-web. All state-changing HTTP methods (POST, PATCH, DELETE) reject cross-origin browser requests by checking Sec-Fetch-Site and comparing Origin against Host, preventing arbitrary web pages from issuing requests to loopback.
Rendering
The review core stores and diffs raw text. When a browser requests format=html on the file endpoint, the server renders the file with md-html (RFD 124): a Markdown file as Markdown, and any other file as preformatted text with each line in a span of its own. Either way, runs of text in the HTML carry the byte range of the source they came from (data-s and data-e), so a browser maps selections and highlights the same way for every file.
The response also includes the raw source text, so the frontend can show the source a selection covers before the reviewer writes a suggestion for it. Selecting the rendered words "is Abandoned" covers the source is **Abandoned, so replacing that range with plain words would leave the closing ** behind.
Anchors over HTTP
Browsers address text only by UTF-8 byte offsets into one version of a file, the positions md-html writes on the page, and never count lines or columns. The server converts between byte offsets and line:column positions with md_html::Lines, which the core also uses to read excerpts and resolve quote.
- A request that anchors a comment to a range names the version and file the range is in, and gives the range either as
range, in the form--attakes after the file path, or asbytes, a half-open byte range. The server rejects byte offsets outside the file or inside a character. GET /api/reviews/{id}returns each comment's anchor as stored, together with either its projection onto the version named byversion(the latest by default), as bothrangeandbytes, or a flag saying it is outdated there. A line-only range projects to the bytes from the start of its first line to the end of its last, without the line ending.
A comment anchored in version 2 carries this anchor when read with version=3:
{
"version": 2,
"path": "docs/rfd/drafts/D72-review-engine-for-workspace-files.md",
"range": "88:12-88:47",
"projected": { "version": 3, "range": "90:12-90:47", "bytes": [4113, 4148] }
}Byte ranges never reach review.json: an offset is only valid in the version it was read from, while projection moves anchors between versions by line.
Shared Protocol Client
Both jp-serve-web (client.rs) and jp-serve-chat (host.rs) currently maintain their own async client for the host-plugin stdio protocol, each implementing a reader task, request-ID correlation, a queue for multi-stage responses, and a shutdown signal that triggers on shutdown or stdin EOF. jp review serve needs the same client.
This RFD extracts the shared implementation into jp_plugin::client behind a client Cargo feature (so the host binary does not compile it) and migrates jp-serve-web, jp-serve-chat, and jp-review to use it. jp-serve-chat retains its thin Host trait wrapper for unit testing with mock hosts.
Pass Outcome Tracking
Both submit and jp review serve determine how a pass ended from the host's response to query. An error response records the pass as failed. A query_complete response carries an outcome field (finished, stopped, or aborted), which maps to completed (for finished) or stopped (for stopped and aborted).
The host reports outcome on query_complete from plugin protocol version 15 (T-1kyv4ex), so jp-review refuses to start under an older host. Without the field, a delegated turn stopped via Ctrl-C at the host terminal is indistinguishable from a turn that completed normally.
Configuration
[plugins.command.review]
# How long the host waits for the plugin to exit on shutdown, which is the
# time `jp review serve` has to stop its passes. A host setting, 5 by default.
shutdown_timeout_secs = 30
[plugins.command.review.options]
# Where reviews are stored. A relative path is inside the workspace.
# Unset: the user-local workspace directory.
dir = ".jp/reviews"
# Configurations a pass runs under, as `--cfg` takes them. The file
# `jp review init` writes is the usual first entry.
cfg = ["skill/review"]
# Prints the content a file is compared with when a review starts.
# `{path}` is the file, relative to the workspace root. Unset: no base version.
base = ["git", "show", "HEAD:./{path}"]
# The author written on the assistant's replies and comments.
assistant = "jp"
# The most characters a reply or comment the assistant writes may hold.
max_chars = 600All options are optional. base executes in the workspace root; if it exits non-zero for a file (for example, an untracked file), that file starts without a base version.
Drawbacks
- Passes edit files without interactive prompts. Delegated plugin turns auto-approve tool calls that would otherwise prompt at a terminal. Reviewers must rely on the review configuration's enabled tool set as the boundary on what a pass can do.
- Merge conflicts on committed stores. If two checkouts concurrently modify the same review in a git-tracked store, both rewrite
review.jsonand produce a merge conflict. Committing the review store is suited to single-checkout workflows on a given review. - Advisory file locking.
File::lockis not reliable across all network filesystems, where concurrent writers could overwrite each other's updates. - Unbounded store growth. Closing a review does not delete its directory or blobs from the store.
--idmutates the target conversation's configuration. Binding a review to an existing conversation applies the review'scfgoverlays to that conversation for subsequent turns. Because those overlays alter the system prompt, the first pass invalidates the existing conversation's prompt cache once.- Large initial pass message. The first pass message includes the full text of every tracked file with line numbers, which subsequent passes pay for as cached input tokens.
- Two coordinate systems over HTTP. Browsers address text by byte offsets and scripts by
line:column, so the API accepts and returns both, and a byte range is only valid in the version it was read from.
Alternatives
Keep revdiff, or adopt Plannotator
Both tools collect a batch of annotations for a single turn, without tracking comments across file versions or recording structured assistant verdicts per comment. Plannotator's interaction model (text selection, inline comment or suggestion, and margin cards) informs the planned browser frontend.
Store versions as git commit objects
Each version could be stored as a git commit under a private ref, delegating blob storage and diffing to git. However, JP and its plugins do not require a workspace to be a git repository. The review engine still needs self-contained snapshots to resolve anchors deterministically, and future git commit reviews can snapshot commit trees as versions labelled with their commit SHA.
Append-only record log
Storing each mutation as a numbered, write-once file and replaying the log on read would avoid taking a lock and preserve every intermediate state.
However, lockless appends cannot validate state invariants before writing: two concurrent submit commands could both append a pass, requiring deterministic conflict resolution during replay. A reader polling by sequence number could also observe a newly created file before its write completes, or skip past an earlier number that finishes writing later. Because versions, comments, replies, and passes are already append-oriented lists inside review.json, a single locked file (using the locking helper already proven in ticket::board) avoids all three issues.
Embed review instructions in the pass message
Including behavioral instructions in the first pass user message would avoid altering the system prompt (preserving the prompt cache when --id joins an existing conversation). However, hardcoding instructions in the pass message builder would bury prompt policy inside the plugin binary, requiring a plugin recompile to tune how the assistant reviews.
Quote-based anchors
Anchoring comments by storing a quoted substring and searching for it in later versions would survive line-shifting edits outside the quote. However, duplicate substrings are ambiguous, replacement suggestions require exact range boundaries, and fuzzy matching risks re-attaching a comment to unrelated text. Marking modified ranges as outdated and displaying them against their original version is predictable and exact.
Convert anchors in the browser
The file endpoint could return the raw source and leave the conversion between byte offsets and line:column positions to the frontend, so the HTTP API would use one coordinate system. The rules for lines and columns would then exist twice, in Rust for the CLI, tools, and pass prompts, and in JavaScript for the browser. The two would have to agree on details such as a lone \r line ending, a leading byte-order mark, and counting columns in code points, not UTF-16 units. Because anchors are persisted, a disagreement between the two puts a comment on the wrong text in review.json, and the pass that submits it quotes that text.
Structured output schema instead of review tools
query accepts a JSON schema, so a pass could require the assistant to return an array of verdicts as its final structured response. However, structured output is only produced at the very end of a turn: stopping a turn mid-pass would lose all verdicts completed so far, and any turn that ends without valid structured data fails as an error. Recording replies via tool calls persists each verdict immediately and lets the assistant interleave file edits, replies, and prose explanation.
Spawn a detached jp review submit per HTTP request
Other write endpoints in the documentation site spawn a short-lived jp subprocess per HTTP request, which works well for sub-second commands. A review pass can run for minutes, a turn started in an independent child process cannot be stopped over the parent's plugin protocol, and the child process would have to outlive the HTTP server that spawned it. Keeping a long-lived jp review serve connected to the host avoids all three problems.
Non-Goals
- Browser UI. This RFD defines the engine, CLI, tools, and HTTP API; the browser frontend is separate.
- Reviewing git commits. The data model supports commit snapshots, but no CLI command imports commits yet.
- Replying to assistant messages. The data model supports it, but conversation message review is deferred.
- Per-comment sub-conversations for discussions that outgrow a single review comment.
- Applying suggestions directly from the UI. Only the assistant applies or adapts suggestions during a pass.
- Concurrent passes on a single review.
- Concurrent writes to a single review across multiple git checkouts.
- Syncing with external forge pull requests (GitHub, GitLab).
Risks and Open Questions
- Retry backoff delays
stop. Until T-1jdkmmf lands, a turn sleeping in provider retry backoff only processes a stop interrupt after the current backoff sleep finishes (up to 75 seconds under default settings). A server shutdown during that window will exceedshutdown_timeout_secsand leave the passinterrupted. - Missing review tools in custom configurations.
submitdoes not verify that the active configuration enablesreview_replyandreview_comment. If a user overridescfgwithout enabling the review tools, the assistant will edit the files and reply in prose, leaving every comment inopenstatus. - Stale line numbers during
review_comment.review_commentinterpretslinesagainst the current working-tree file, whereas the assistant may cite line numbers from the pass prompt before its own edits shifted them. Passingquotecatches the mismatch; withoutquote, the comment can anchor to the wrong lines. - Concurrent user edits during a pass. The version recorded when a pass turn completes snapshots the working tree as it stands, attributing any manual edits the user saved while the turn was running to that pass.
max_charsdefault. The default limit of 600 characters per assistant reply or comment is an initial estimate and may need tuning in practice.
Implementation Plan
Phase 1: Core model and store
Implement the review domain model, anchor projection across versions, content-addressed blob storage, locked review.json persistence, and the non-turn CLI commands (start, ls, show, diff, comment, reply, resolve, and close). Extract the advisory file lock helper from ticket::board into doc so both crates share it. Convert positions with md_html::Lines, removing the qual:api marker from each of its methods as the core first calls it (T-1md6ywd). This phase runs no turns and is mergeable on its own.
Phase 2: Passes and review tools
Implement pass prompt formatting, submit, the review_reply and review_comment plugin tools, tools init, and init (review.toml generation). Depends on Phase 1. After this phase, the full review loop works end to end from the terminal.
Phase 3: Shared plugin protocol client
Extract the async plugin protocol client into jp_plugin::client and migrate jp-serve-web and jp-serve-chat to it with no behavioral change. Mergeable independently of Phases 1 and 2.
Phase 4: jp review serve
Implement the HTTP API, pass stopping, graceful shutdown, and reconciliation of interrupted passes. Add plain-text rendering to md-html (RFD 124) for files other than Markdown. Depends on Phases 2 and 3.