﻿# RFD D72: Review Engine for Workspace Files

- **Status**: Draft
- **Category**: Design
- **Authors**: Jean Mertz <git@jeanmertz.com>
- **Date**: 2026-11-11
- **Extends**: [RFD 116], [RFD 124]

## 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`, or `ask`.

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:

1. **Line-only anchors.** Annotating a three-word phrase in a wrapped paragraph
   can only target the entire line.
2. **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.
3. **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.
4. **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

```sh
$ 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](#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):

1. Reject the submission if another pass on the review is still in progress.
2. Record a new version if any tracked file in the working tree differs from the
   latest version.
3. 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.
4. Record the pass in `review.json`.
5. Delegate a turn to the host via `query`.
6. 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:

````markdown
# 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_reply` and `review_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

```toml
[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;
- `path` is not part of the review, `lines` falls outside the file bounds, or
  `quote` does not match exactly once within `lines`;
- `body` exceeds `max_chars` characters.

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](#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](#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 `--at` takes
  after the file path, or as `bytes`, 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 by `version` (the latest by
  default), as both `range` and `bytes`, 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`:

```json
{
  "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

```toml
[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 = 600
```

All 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.json` and produce
  a merge conflict.
  Committing the review store is suited to single-checkout workflows on a given
  review.
- **Advisory file locking.** `File::lock` is 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.
- **`--id` mutates the target conversation's configuration.** Binding a review
  to an existing conversation applies the review's `cfg` overlays 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 exceed `shutdown_timeout_secs` and
  leave the pass `interrupted`.
- **Missing review tools in custom configurations.** `submit` does not verify
  that the active configuration enables `review_reply` and `review_comment`.
  If a user overrides `cfg` without enabling the review tools, the assistant
  will edit the files and reply in prose, leaving every comment in `open`
  status.
- **Stale line numbers during `review_comment`.** `review_comment` interprets
  `lines` against the current working-tree file, whereas the assistant may cite
  line numbers from the pass prompt before its own edits shifted them.
  Passing `quote` catches the mismatch; without `quote`, 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_chars` default.** 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.

## References

- [RFD 072: Command Plugin System][RFD 072]
- [RFD 076: Tool Access Grants][RFD 076]
- [RFD 116: Shareable RFD, Ticket, and Site Tooling][RFD 116]
- [RFD 124: Source-Mapped Markdown Rendering][RFD 124]
- [Plannotator]

[Plannotator]: https://plannotator.ai/
[RFD 072]: ../072-command-plugin-system.md
[RFD 076]: ../076-tool-access-grants.md
[RFD 116]: ../116-shareable-rfd-ticket-and-site-tooling.md
[RFD 124]: ../124-source-mapped-markdown-rendering.md
