Code review surface

Status: v0.1.0 — Draft. Promoted from the GitHub Primer parity scan (metadocsstack #092). Source: GitHub PR review flow.

R1 — Composition

The surface composes:

• a specs/components/diff-viewer.kmd (the file changes);
• inline comment threads anchored to diff lines (R2);
• a review decision control (R3);
• a PR header carrying the PR specs/components/state-label.kmd.

R2 — Comment threads

• A thread is anchored to a line or line-range (anchor owned by

  diff-viewer R5) and holds 1..n comments in time order.

• Each thread has a resolved / unresolved state; resolving collapses

  it but keeps it retrievable. Resolution is reversible.

• A comment supports markdown (specs/kmd/format.kmd) including

  suggestions; authors can edit/delete their own per product permissions.

R3 — Review decision (batched)

• Line comments are added to a pending review (a draft batch), not

  posted individually, so the author receives one coherent review.

• Submitting the review requires one decision verb:
  • Comment — feedback, no approval signal;
  • Approve — endorses merging;
  • Request changes — blocks until re-review.
• The decision + batched comments post atomically. The three verbs are

  the closed set (no custom verbs).

R4 — Review state on the PR

• The aggregate review state (approved / changes-requested / review-

  required) feeds merge eligibility and renders in the PR header.

• A "request changes" review keeps the PR blocked until the reviewer

  re-reviews; "approve" satisfies the review requirement.

• This surface presents state; branch-protection rules that consume it

  live in Koder Flow backend (out of scope).

R5 — Errors & conflicts

• Submitting a review on a stale diff (head moved) surfaces a clear,

  recoverable message (specs/errors/user-facing-messages.kmd) and re-anchors or flags outdated threads rather than losing them.

• A failed submit never drops the pending batch (draft survives).

R6 — Accessibility & i18n

• Threads are keyboard-reachable from their diff line and announced with

  their resolved/unresolved state.

• The decision control is a real radio/button group; the destructive-ish

  "Request changes" is not the default focus.

• All chrome (verbs, "Pending", "Resolved", counts) is translatable per

  specs/i18n/contract.kmd; user content is never machine-translated.

Não-escopo

• Diff rendering itself (specs/components/diff-viewer.kmd).
• Branch protection / required-reviewers rules (Flow backend).
• Suggested-change application mechanics (separate follow-up).
• Code-owner auto-assignment (Flow backend).