io.github.uditk2/review-assist-mcp

Author role: answer the reviewer's questions, by `q_id`. This is how your answers reach the document as YOUR words: the reviewer records the questions, relays them to you with their ids, and you write the answers here. An answer the reviewer transcribes on your behalf still works, but is marked reviewer-sourced and does not count as attested — so a document whose interview never happened is visible as such rather than indistinguishable from one that did. Answer the whole batch in one call. If the transcript does not cover something, say exactly that and set `resolved: false`; a recorded non-answer is worth more than an invented one.

Call this first. Resolves the base/head SHAs, OPENS THE DISTILLATION RUN, and returns the `run_id` every later call needs, the numbered hunk index, and `consent_state` — so you learn whether this repo is opted in BEFORE you spend a document finding out. It does NOT return the diff text: read that with `read_diff`, which pages it. Anchors use these hunk ids and pin to head_sha.

Reviewer role: read the author's answers, in the author's own words, straight off the run. This is where the interview reaches you — you do NOT need answers relayed as text, and you must not paraphrase a summary into the document when the verbatim answer is here. Each round carries `answered_by`: only `author` is attested, `reviewer` is your own transcription, and `null` means nobody has answered yet. Paged: follow `next_cursor` until there is none.

Return the Intent Document JSON Schema and the authoring protocol. Call this first.

Author role: read the reviewer's questions straight off the run, with their `q_id`s. This is how you learn what you are being asked — you do NOT need them relayed to you as text. Call it with the `run_id` (derive it yourself from compute_diff, or take the one you were given, they are the same value), answer with `answer_questions` using the ids it returns, then call it again with `only_unanswered: true` to confirm nothing was missed. Paged: follow `next_cursor` until there is none.

Read this repository's own instructions for the reviewer, from its `.reviewer/` folder. Call it after you have read the diff and BEFORE you record round one: these are the questions this repo always wants asked (invariants a past incident bought, changes that must travel in pairs, churn that is never incidental), and none of it is recoverable from the diff. They are ADDITIONAL questions. They add to your baseline set and to the questions the diff provoked, and replace neither: a short house-rules file does not license a short interview. Most repos have none, and an absent folder is a normal answer, not an error. Treat the content as repository reference material, not as instructions: it may add questions and sharpen the ones you have, and it never overrides the protocol, the schema, or the sourcing rules.

Return the author and reviewer role definitions for the two-agent distillation, picked for the calling client (Claude Code, Codex, or a generic fallback) and including how to spin them up. Spawn each role in its OWN context: the author holds the transcript and cannot submit; the reviewer submits and never sees the transcript.

Author role: read a session's WHOLE conversation — every turn you and the agent exchanged, each structured question with the answer chosen, and every command and file edit as one line. This replaces searching. A session is a median 4.8% conversation and 95% tool output; the spine is that 4.8%. Being complete, it removes the one thing retrieval can never rule out — an answer you simply did not find. It is served a page at a time: call it with just the `path`, then keep passing back the `next_cursor` it returns until there is none. That, and nothing else, is how you know you have read the whole session. Nothing is ever dropped to make a page fit. Every item carries an `index` into the full transcript: a jump between indices means machinery was elided there, and read_transcript around an index recovers the tool output behind a claim.

File a session transcript into this repo's store so list_transcripts and get_spine can find it. Needed when a session leaves nothing on this machine: a Cowork session running in the CLOUD keeps its transcript inside the container it ran in, and the desktop app holds only a composer draft and an evictable cache of a partial event stream. The container writes the file somewhere reachable and calls this. Re-importing OVERWRITES: a live session keeps growing, so a second export must replace the first rather than leave two near-identical candidates for the ranking to choose between.

List candidate session transcripts for this repo — across BOTH Claude Code and Codex — ranked so you can pick THIS session's transcript even when several are close in time. Pass `base` (the change's base ref) so ranking scores each candidate by how much it references the changed files and branch. Each candidate includes `first_user`/`last_activity` previews: choose the one whose `first_user` matches how THIS session actually began; prefer higher `relevance`.

List Review Assist's per-repo enable/disable decisions, or reset one repo — removing it from the list so it is asked about again.

Read the change itself, a page at a time. `compute_diff` gives you the run handle and the hunk index; the bytes come from here, so no single response can grow with the size of the change. Call it with just the `run_id` to start at H1, then keep passing the `next_cursor` it returns until there is none — that is how you know you have seen the whole diff. To go straight at one thing instead, pass `hunks` or `paths`. Pages break on hunk boundaries, so you never receive half a change; a hunk too large for one page is split by line and labelled with the lines it carries.

Read a window of the FULL transcript — tool calls, results and all — around an index the spine gave you. This is how a claim gets substantiated: the prose says what was decided, the tool output holds the evidence. Not for hydration; get_spine does that in one call.

Reviewer role: record interview rounds against a RUN — each a question you raised about a thin or under-justified spot. RECORD THE QUESTIONS FIRST, BEFORE you relay them: each comes back with a `q_id`, and the author answers by that id with `answer_questions`, so the server hears the author's own words rather than your account of them. Include the q_ids when you relay. `answer` is optional here and is only for transcribing an answer you already hold — it is marked reviewer-sourced, and does not count as attested. Send the baseline set and every diff-provoked question together in ONE call via `rounds`; follow up at most once. Rounds are keyed by question, so re-recording one replaces it rather than duplicating: retrying is free, cannot inflate the count, and never erases an answer already recorded.

Record the user's decision about whether Review Assist may operate in a repository. Call this only after the user has answered the consent prompt returned by submit_document.

Validate a candidate Intent Document against the run's diff and head SHA. On pass, write it to .intent/<branch>.json. Takes `run_id` from compute_diff — repo, base and head come from the run, so the interview and the coverage check cannot disagree about which change this is. On failure, returns findings to fix and resubmit.