@jwilger/pi-development-system 0.17.0 → 0.19.0

package/extensions/development-system.ts

@@ -14,6 +14,7 @@ import { registerRedFirstGuard } from "../src/gates/red-first-guard.ts";
 import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts";
 import { registerTestGuard } from "../src/gates/test-guard.ts";
 import { createJevHolder } from "../src/jev/holder.ts";
+import { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
 import { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
 import { createModelsTool, registerModelsCommand } from "../src/state/models-command.ts";
@@ -103,6 +104,14 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
   pi.registerTool(createModelsTool());
   pi.registerTool(createRouteTaskTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
+  const reviewDeps = {
+    state,
+    jev: (ctx: ExtensionContext) => jevHolder.forContext(ctx),
+    exec: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) =>
+      pi.exec(command, args, options),
+  } satisfies Parameters<typeof createReviewStartTool>[0];
+  pi.registerTool(createReviewStartTool(reviewDeps));
+  pi.registerTool(createReviewRecordTool(reviewDeps));
   registerModelsCommand(pi);
   piSubagent(pi);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/prompts/devsys-review.md

@@ -0,0 +1,10 @@
+---
+description: Run a fresh-context review round on the active slice and record the result
+argument-hint: "[slice] [diffRange]"
+---
+Review the work in progress with the code-review skill.
+
+1. Call `devsys_review_start` (slice and diff range: $ARGUMENTS; omit either to use the active slice and `HEAD`).
+2. Run the `agent_spawn` payload it returns, unchanged.
+3. Pass the reviewer's packet verbatim to `devsys_review_record`.
+4. Report `review: N/R clean` and the next action. If the next action is `fix-findings`, list each blocking and should-fix finding with its `path:line`.

package/skills/code-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: code-review
+description: How to review a slice before it is committed in this development system - fresh-context reviewer per round, Jev-chosen lenses, the review packet format, what resets the clean streak, and driving rounds with devsys_review_start and devsys_review_record. Use before committing a slice, when asked to review, or when interpreting reviewer findings.
+---
+
+# Code review
+
+Every slice is reviewed by a **fresh-context reviewer** before it is committed.
+The reviewer has not seen your reasoning, so it judges the diff, not your intent.
+Review is a soft gate (`review.unsatisfied`): skipping it needs a recorded departure.
+
+## Run a round
+
+1. `devsys_review_start` (slice defaults to the active slice; `diffRange` defaults
+   to `HEAD`: everything uncommitted, untracked files included). It computes the
+   diff digest, lets Jev choose lenses, and returns an exact `agent_spawn` payload.
+2. Run that `agent_spawn` unchanged. The reviewer is a top-level agent, not a
+   child of this conversation, so it does not inherit your context.
+3. Pass the reviewer's packet, verbatim, to `devsys_review_record` with the
+   `diffDigest` the start reply gave (`packets: [...]`; all lens packets of one
+   round in one call). A packet is recorded once, in the round its header names;
+   if the diff changed since the start, the round is refused: start again.
+4. Read the reply: `review: N/R clean` and `next:`.
+   - `fix-findings`: fix every blocking and should-fix finding, then start a new round.
+   - `review`: the streak is short (or the diff changed with findings); start another round.
+   - `stale-diff`: the diff changed after a satisfied review; one more round.
+   - `done`: commit.
+
+## The packet
+
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
+
+A malformed packet is rejected with the reason; ask the reviewer to resend it.
+The verdict must agree with the findings.
+
+## Severity and the clean streak
+
+- **blocking**: a demonstrable defect or a broken non-negotiable.
+- **should-fix**: a real defect or missing test with a realistic trigger.
+- **nit**: style or report-only. Nits never reset the streak; they go to
+  `docs/decisions/followups.md`.
+- **false-positive**: refuted; ignored.
+
+Jev may raise a finding's severity when it is at least 0.8 confident; it never
+lowers a blocking or should-fix finding (it only suggests, in the reply, and you
+re-check it yourself). A round is clean when it has no blocking or should-fix findings.
+The default is three consecutive clean rounds (`review.required_clean_rounds`).
+Only real findings reset the count; a changed diff alone does not, so a small fix
+commit keeps the clean rounds already earned unless findings come back.
+
+## Rules of thumb
+
+- Fix the findings before the next round. Do not argue a finding away; if it is
+  wrong, the reviewer or Jev marks it a false positive with evidence.
+- Do not widen a review into an audit of the tree. The reviewer reads the diff and
+  what it depends on.
+- Never edit the packet to make it pass.

package/src/context/status.ts

@@ -1,3 +1,4 @@
+import { reviewLabel, reviewOf } from "../core/review-flow.ts";
 import type { DevsysState } from "../core/types.ts";
 
 export const STATUS_KEY = "devsys";
@@ -12,8 +13,18 @@ const ciLabel = (state: DevsysState): string | undefined => {
   return `ci ${ci.status}${sha}`;
 };
 
+const activeReview = (state: DevsysState): string | undefined => {
+  const review = state.activeSlice === undefined ? undefined : reviewOf(state, state.activeSlice);
+  return review === undefined ? undefined : reviewLabel(review);
+};
+
 export const renderStatusLine = (state: DevsysState, jevModel?: string): string =>
-  [`devsys: ${state.phase}`, `jev ${jevLabel(state, jevModel)}`, ciLabel(state)]
+  [
+    `devsys: ${state.phase}`,
+    `jev ${jevLabel(state, jevModel)}`,
+    ciLabel(state),
+    activeReview(state)?.replace("review: ", "review ").replace(" clean", ""),
+  ]
     .filter((part) => part !== undefined)
     .join(" · ");
 
@@ -26,4 +37,5 @@ export const renderStatus = (state: DevsysState, jevModel?: string): string =>
     `- open departures: ${state.openDepartures.length}`,
     `- jev: ${jevLabel(state, jevModel)}`,
     `- ci: ${ciLabel(state)?.slice(3) ?? "unknown"}`,
+    ...(activeReview(state) === undefined ? [] : [`- ${activeReview(state)}`]),
   ].join("\n");

package/src/core/review-flow.ts

@@ -0,0 +1,166 @@
+import {
+  cleanStreak,
+  type Finding,
+  nextAction,
+  type ReviewState,
+  type Severity,
+} from "./review.ts";
+import type { ReviewPacket } from "./review-packet.ts";
+import type { DevsysState, SliceRef } from "./types.ts";
+
+/** Pure helpers around review state; the tools in src/review do the I/O. */
+
+export const reviewOf = (state: DevsysState, slice: SliceRef): ReviewState | undefined =>
+  state.reviews?.find((r) => r.slice === slice);
+
+export const upsertReview = (state: DevsysState, review: ReviewState): DevsysState => {
+  const others = (state.reviews ?? []).filter((r) => r.slice !== review.slice);
+  return { ...state, reviews: [...others, review] };
+};
+
+export const reviewLabel = (review: ReviewState): string =>
+  `review: ${cleanStreak(review)}/${review.required} clean`;
+
+/**
+ * Why a commit on this slice lacks a satisfied review, or `undefined` when the review is complete
+ * on the diff as it is now (the `review.unsatisfied` soft gate is raised from this).
+ */
+export type DiffNow = {
+  readonly digest: string;
+  readonly files?: Readonly<Record<string, string>>;
+};
+
+/** Every file in the current diff was in the last round's diff, byte for byte: a part of what was reviewed. */
+const coveredByLastRound = (review: ReviewState, now: DiffNow): boolean => {
+  const reviewed = review.rounds.at(-1)?.files;
+  if (reviewed === undefined || now.files === undefined) return false;
+  return Object.entries(now.files).every(([path, digest]) => reviewed[path] === digest);
+};
+
+export function reviewGap(state: DevsysState, slice: SliceRef, now: DiffNow): string | undefined {
+  const review = reviewOf(state, slice);
+  if (review === undefined || review.rounds.length === 0) {
+    return `no review has been recorded for slice ${slice}`;
+  }
+  switch (nextAction(review, now.digest)) {
+    case "done":
+      return undefined;
+    case "fix-findings":
+      return `the last review round of slice ${slice} has blocking or should-fix findings still to fix`;
+    case "stale-diff":
+      // Committing a reviewed change in parts leaves a smaller diff made only of reviewed files.
+      if (coveredByLastRound(review, now)) return undefined;
+      return `the diff has changed since slice ${slice} was last reviewed; review it again`;
+    case "review":
+      return `slice ${slice} has ${cleanStreak(review)}/${review.required} clean review rounds`;
+  }
+}
+
+/** A unified diff cut into one text per file, keyed by the file's new path. */
+export function splitDiffByFile(diff: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  let path: string | undefined;
+  let lines: string[] = [];
+  const flush = () => {
+    if (path !== undefined) out[path] = lines.join("\n");
+  };
+  for (const line of diff.split("\n")) {
+    const header = /^diff --git a\/.* b\/(.*)$/.exec(line);
+    if (header !== null) {
+      flush();
+      path = header[1] ?? line;
+      lines = [];
+    }
+    lines.push(line);
+  }
+  flush();
+  return out;
+}
+
+/** Packets from several lens reviewers in one round become one round of findings. */
+export function combinePackets(packets: readonly ReviewPacket[]): {
+  lenses: string[];
+  findings: Finding[];
+} {
+  const lenses = [...new Set(packets.flatMap((p) => p.lenses))];
+  const findings = packets.flatMap((packet, p) =>
+    packet.findings.map((f) => ({ ...f, id: `${f.id}.${p + 1}` })),
+  );
+  return { lenses, findings };
+}
+
+/** Jev confidence needed before its severity replaces the reviewer's. */
+export const SEVERITY_ADOPT_CONFIDENCE = 0.8;
+
+const counts = (severity: Severity): boolean =>
+  severity === "blocking" || severity === "should-fix";
+
+/**
+ * Take Jev's severity only when it is confident and different, and never to lower a finding that
+ * counts (blocking/should-fix) to one that does not: Jev reads a clipped diff, the reviewer read
+ * the code. That disagreement is reported as a suggestion and the reviewer's severity stands.
+ */
+export function adoptSeverity(
+  finding: Finding,
+  judged: { severity: Severity; confidence: number } | undefined,
+): { finding: Finding; note?: string } {
+  if (
+    judged === undefined ||
+    judged.confidence < SEVERITY_ADOPT_CONFIDENCE ||
+    judged.severity === finding.severity
+  ) {
+    return { finding };
+  }
+  const confidence = judged.confidence.toFixed(2);
+  if (counts(finding.severity) && !counts(judged.severity)) {
+    return {
+      finding,
+      note: `${finding.id}: Jev suggests ${judged.severity} instead of ${finding.severity} (confidence ${confidence}); the reviewer's severity stands, re-check the finding yourself`,
+    };
+  }
+  return {
+    finding: { ...finding, severity: judged.severity },
+    note: `${finding.id}: Jev moved severity ${finding.severity} → ${judged.severity} (confidence ${confidence})`,
+  };
+}
+
+const where = (f: Finding): string =>
+  f.path === undefined ? "" : ` \`${f.path}${f.line === undefined ? "" : `:${f.line}`}\``;
+
+/** The nits of a round, as a section for docs/decisions/followups.md. */
+export function renderFollowups(
+  slice: SliceRef,
+  round: number,
+  findings: readonly Finding[],
+): string | undefined {
+  const nits = findings.filter((f) => f.severity === "nit");
+  if (nits.length === 0) return undefined;
+  const lines = nits.map((f) => `- ${f.lens}${where(f)} — ${f.summary}`);
+  return `\n## From ${slice} review round ${round}\n\n${lines.join("\n")}\n`;
+}
+
+/** The task text for a fresh reviewer: slice, lenses, how to see the diff, and the packet to return. */
+export function reviewerTask(input: {
+  slice: SliceRef;
+  round: number;
+  lenses: readonly string[];
+  diffRange: string;
+}): string {
+  const lenses = input.lenses.join(", ");
+  return [
+    `Review slice ${input.slice}, round ${input.round}, through these lenses: ${lenses}.`,
+    `See the change with \`git diff ${input.diffRange}\` (and \`git diff --stat ${input.diffRange}\`), plus any untracked files listed by \`git status --short\` (git diff does not show them; read them directly). Read the callers, callees and tests it depends on, no more.`,
+    "Do not modify files; report demonstrable defects with a realistic trigger and the smallest local repair.",
+    "Return exactly the review packet from your instructions, with exactly this header (slice and round must not change):",
+    "",
+    `## Review — ${input.slice} — round ${input.round} — lenses: ${lenses}`,
+    "### Sources inspected",
+    "- <path:line ranges>",
+    "### Findings",
+    "- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>",
+    "### Verdict",
+    "no-blocking | blocking",
+    "",
+    "Severity: blocking = demonstrable defect or broken non-negotiable; should-fix = real defect or missing test with a realistic trigger; nit = style or report-only. Zero findings is a valid result.",
+  ].join("\n");
+}

package/src/core/review-packet.ts

@@ -0,0 +1,111 @@
+import { type Finding, SEVERITIES, type Severity } from "./review.ts";
+import { isParseError, type ParseError, parseError } from "./types.ts";
+
+export type ReviewPacket = {
+  readonly slice: string;
+  readonly round: number;
+  readonly lenses: ReadonlyArray<string>;
+  readonly sources: ReadonlyArray<string>;
+  readonly findings: ReadonlyArray<Finding>;
+  readonly verdict: "no-blocking" | "blocking";
+};
+
+const SEP = "[—–-]";
+const HEADER = new RegExp(
+  `^##\\s+Review\\s+${SEP}\\s+(.+?)\\s+${SEP}\\s+round\\s+(\\S+)\\s+${SEP}\\s+lenses:\\s*(.*)$`,
+  "m",
+);
+const FINDING = /^-\s*\[([^\]]+)\]\s+(\S+)\s+(?:`([^`]+)`\s+)?[—–-]\s+(.+)$/;
+
+const section = (text: string, name: string): string | undefined => {
+  const match = new RegExp(`^###\\s+${name}\\s*$`, "im").exec(text);
+  if (match === null) return undefined;
+  const rest = text.slice(match.index + match[0].length);
+  const next = /^###?\s/m.exec(rest);
+  return next === null ? rest : rest.slice(0, next.index);
+};
+
+const isSeverity = (value: string): value is Severity =>
+  (SEVERITIES as readonly string[]).includes(value);
+
+const locate = (target: string | undefined): { path?: string; line?: number } => {
+  if (target === undefined) return {};
+  const m = /^(.*?):(\d+)(?:-\d+)?$/.exec(target);
+  return m === null ? { path: target } : { path: m[1] ?? target, line: Number(m[2]) };
+};
+
+function parseFinding(line: string, lens: string[], index: number): Finding | ParseError {
+  const m = FINDING.exec(line);
+  if (m === null) {
+    return parseError(
+      `unparseable finding "${line}": expected "- [severity] <lens> \`path:line\` — <summary> — <why>"`,
+    );
+  }
+  const severity = m[1] ?? "";
+  if (!isSeverity(severity)) {
+    return parseError(
+      `unknown severity "${severity}": use blocking, should-fix, nit or false-positive`,
+    );
+  }
+  const findingLens = m[2] ?? "";
+  if (!lens.includes(findingLens)) lens.push(findingLens);
+  return {
+    id: `${findingLens}-${index}`,
+    severity,
+    ...locate(m[3]),
+    summary: (m[4] ?? "").trim(),
+    lens: findingLens,
+  };
+}
+
+/** Parse the reviewer packet of plan Appendix A. Strict about structure, tolerant of dash style. */
+export function parseReviewPacket(text: string): ReviewPacket | ParseError {
+  const header = HEADER.exec(text);
+  if (header === null) {
+    return parseError('missing packet header "## Review — <slice> — round <n> — lenses: <a, b>"');
+  }
+  const round = Number(header[2]);
+  if (!Number.isInteger(round) || round < 1) {
+    return parseError(`round "${header[2]}" is not a positive integer`);
+  }
+  const lenses = (header[3] ?? "")
+    .split(",")
+    .map((l) => l.trim())
+    .filter((l) => l !== "");
+  const verdictText = section(text, "Verdict")?.trim().split(/\s+/)[0]?.toLowerCase();
+  if (verdictText !== "no-blocking" && verdictText !== "blocking") {
+    return parseError(
+      'missing or invalid verdict: end the packet with "### Verdict" then no-blocking or blocking',
+    );
+  }
+  const findings: Finding[] = [];
+  const lines = (section(text, "Findings") ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l !== "" && !/^-?\s*none\.?$/i.test(l));
+  for (const [i, line] of lines.entries()) {
+    const finding = parseFinding(line, lenses, i + 1);
+    if (isParseError(finding)) return finding;
+    findings.push(finding);
+  }
+  const hasBlocking = findings.some(
+    (f) => f.severity === "blocking" || f.severity === "should-fix",
+  );
+  if (hasBlocking !== (verdictText === "blocking")) {
+    return parseError(
+      `verdict "${verdictText}" contradicts the findings: blocking/should-fix findings mean "blocking", otherwise "no-blocking"`,
+    );
+  }
+  const sources = (section(text, "Sources inspected") ?? "")
+    .split("\n")
+    .map((l) => l.replace(/^-\s*/, "").trim())
+    .filter((l) => l !== "");
+  return {
+    slice: (header[1] ?? "").trim(),
+    round,
+    lenses,
+    sources,
+    findings,
+    verdict: verdictText,
+  };
+}

package/src/core/review.ts

@@ -0,0 +1,178 @@
+import { type ParseError, parseError, type SliceRef } from "./types.ts";
+
+/** Severity of one review finding. Only blocking and should-fix make a round unclean. */
+export type Severity = "blocking" | "should-fix" | "nit" | "false-positive";
+
+export const SEVERITIES: readonly Severity[] = ["blocking", "should-fix", "nit", "false-positive"];
+
+export type Finding = {
+  readonly id: string;
+  readonly severity: Severity;
+  readonly path?: string;
+  readonly line?: number;
+  readonly summary: string;
+  readonly lens: string;
+};
+
+export type ReviewRound = {
+  readonly n: number;
+  readonly lenses: ReadonlyArray<string>;
+  readonly findings: ReadonlyArray<Finding>;
+  readonly reviewedAt: string;
+  /** Digest of the diff the round reviewed (see `digestOf` in src/review/digest.ts). */
+  readonly diffDigest: string;
+  /** Per-file digests of the reviewed diff, so a commit of part of it is still covered. */
+  readonly files?: Readonly<Record<string, string>>;
+};
+
+export type ReviewState = {
+  readonly slice: SliceRef;
+  readonly rounds: ReadonlyArray<ReviewRound>;
+  /** Consecutive clean rounds needed (config `review.required_clean_rounds`, at least `min_rounds`). */
+  readonly required: number;
+};
+
+export type ReviewAction = "review" | "fix-findings" | "done" | "stale-diff";
+
+export const isClean = (round: ReviewRound): boolean =>
+  round.findings.every((f) => f.severity !== "blocking" && f.severity !== "should-fix");
+
+/**
+ * Trailing clean rounds. Real findings reset it; a changed diff alone does not, so a trivial fix
+ * commit keeps the clean rounds already earned unless findings reappear (decision D11).
+ */
+export function cleanStreak(state: ReviewState): number {
+  let streak = 0;
+  for (let i = state.rounds.length - 1; i >= 0; i--) {
+    const round = state.rounds[i];
+    if (round === undefined || !isClean(round)) break;
+    streak += 1;
+  }
+  return streak;
+}
+
+export const isSatisfied = (state: ReviewState): boolean =>
+  state.rounds.length > 0 && cleanStreak(state) >= state.required;
+
+/** What the coordinator should do next, given the digest of the diff as it is now. */
+export function nextAction(state: ReviewState, diffDigestNow: string): ReviewAction {
+  const last = state.rounds.at(-1);
+  if (last === undefined) return "review";
+  if (!isClean(last)) return last.diffDigest === diffDigestNow ? "fix-findings" : "review";
+  if (!isSatisfied(state)) return "review";
+  return last.diffDigest === diffDigestNow ? "done" : "stale-diff";
+}
+
+export const startReview = (slice: SliceRef, required: number): ReviewState => ({
+  slice,
+  required,
+  rounds: [],
+});
+
+export const addRound = (state: ReviewState, round: Omit<ReviewRound, "n">): ReviewState => ({
+  ...state,
+  rounds: [...state.rounds, { ...round, n: state.rounds.length + 1 }],
+});
+
+/** Review lenses Jev can select (plan I6.2). A lens applies at probability ≥ LENS_THRESHOLD. */
+export const LENSES = [
+  "security",
+  "concurrency",
+  "types",
+  "tests",
+  "api-contract",
+  "data-migration",
+  "ux",
+  "performance",
+] as const;
+export type Lens = (typeof LENSES)[number];
+export const LENS_THRESHOLD = 0.5;
+
+/** Lenses that apply when Jev is offline: the ones every change deserves. */
+export const DEFAULT_LENSES: ReadonlyArray<Lens> = ["types", "tests"];
+
+export const selectLenses = (probabilities: Readonly<Record<Lens, number>>): Lens[] =>
+  LENSES.filter((lens) => probabilities[lens] >= LENS_THRESHOLD);
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+function parseFinding(input: unknown): Finding | ParseError {
+  if (!isRecord(input)) return parseError("finding must be an object");
+  const { id, severity, lens, summary, path, line } = input;
+  if (typeof id !== "string" || typeof lens !== "string" || typeof summary !== "string") {
+    return parseError("finding needs string id, lens and summary");
+  }
+  if (!SEVERITIES.includes(severity as Severity)) {
+    return parseError(`unknown severity: ${String(severity)}`);
+  }
+  if (path !== undefined && typeof path !== "string")
+    return parseError("finding path must be a string");
+  if (line !== undefined && typeof line !== "number")
+    return parseError("finding line must be a number");
+  return {
+    id,
+    lens,
+    summary,
+    severity: severity as Severity,
+    ...(path !== undefined ? { path } : {}),
+    ...(line !== undefined ? { line } : {}),
+  };
+}
+
+function parseFiles(input: unknown): Record<string, string> | undefined | null {
+  if (input === undefined) return undefined;
+  if (!isRecord(input)) return null;
+  const out: Record<string, string> = {};
+  for (const [path, digest] of Object.entries(input)) {
+    if (typeof digest !== "string") return null;
+    out[path] = digest;
+  }
+  return out;
+}
+
+function parseRound(input: unknown): ReviewRound | ParseError {
+  if (!isRecord(input)) return parseError("round must be an object");
+  const { n, lenses, findings, reviewedAt, diffDigest } = input;
+  if (typeof n !== "number" || typeof reviewedAt !== "string" || typeof diffDigest !== "string") {
+    return parseError("round needs number n and string reviewedAt and diffDigest");
+  }
+  if (!Array.isArray(lenses) || !lenses.every((l) => typeof l === "string")) {
+    return parseError("round lenses must be an array of strings");
+  }
+  if (!Array.isArray(findings)) return parseError("round findings must be an array");
+  const parsed: Finding[] = [];
+  for (const raw of findings) {
+    const finding = parseFinding(raw);
+    if ("kind" in finding) return finding;
+    parsed.push(finding);
+  }
+  const files = parseFiles(input.files);
+  if (files === null) return parseError("round files must map paths to digest strings");
+  return {
+    n,
+    lenses: lenses as string[],
+    findings: parsed,
+    reviewedAt,
+    diffDigest,
+    ...(files === undefined ? {} : { files }),
+  };
+}
+
+/** Boundary parse for a persisted review (one slice's rounds). */
+export function parseReviewState(input: unknown): ReviewState | ParseError {
+  if (!isRecord(input)) return parseError("review must be an object");
+  const { slice, required, rounds } = input;
+  if (typeof slice !== "string" || slice === "") return parseError("review slice must be a string");
+  if (typeof required !== "number" || !Number.isInteger(required) || required < 1) {
+    return parseError("review required must be an integer of at least 1");
+  }
+  if (!Array.isArray(rounds)) return parseError("review rounds must be an array");
+  const parsed: ReviewRound[] = [];
+  for (const raw of rounds) {
+    const round = parseRound(raw);
+    if ("kind" in round) return round;
+    parsed.push(round);
+  }
+  return { slice: slice as SliceRef, required, rounds: parsed };
+}

package/src/core/types.ts

@@ -1,3 +1,5 @@
+import type { ReviewState } from "./review.ts";
+
 /** Pure domain types for the development system. No I/O lives here. */
 
 export type ParseError = { readonly kind: "parse-error"; readonly message: string };
@@ -82,6 +84,8 @@ export type DevsysState = {
   readonly ci?: CiState;
   readonly profiles?: ReadonlyArray<Profile>;
   readonly lastTestRun?: TestRun;
+  /** One review record per slice (see src/core/review.ts). */
+  readonly reviews?: ReadonlyArray<ReviewState>;
 };
 
 export const initialState = (): DevsysState => ({

package/src/gates/commit-guard.ts

@@ -13,9 +13,11 @@ import {
   parseConventionalCommit,
 } from "../core/commit-message.ts";
 import type { Exec } from "../core/exec.ts";
+import { reviewGap } from "../core/review-flow.ts";
 import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
 import { judgeCommit, MIX_THRESHOLD, RATIONALE_FLOOR } from "../jev/questions/commit.ts";
+import { snapshotDiff } from "../review/digest.ts";
 import type { SessionState } from "../state/session-state.ts";
 import { departureUse } from "./departure-use.ts";
 
@@ -36,6 +38,7 @@ const gateId = (id: string): GateId => {
 
 const RATIONALE = gateId("commit.rationale");
 const MIXED = gateId("commit.mixed-change");
+const REVIEW = gateId("review.unsatisfied");
 
 const readMessageFile = (cwd: string, path: string): string | undefined => {
   try {
@@ -115,11 +118,33 @@ async function jevNeeds(
   return needs;
 }
 
+/** While work is in flight, committing needs the slice review satisfied on the diff as it is now. */
+async function reviewNeeds(deps: CommitGuardDeps, ctx: ExtensionContext): Promise<Need[]> {
+  const { phase, activeSlice } = deps.state.get();
+  if ((phase !== "implementing" && phase !== "reviewing") || activeSlice === undefined) return [];
+  const snap = await snapshotDiff(deps.exec, ctx.cwd, "HEAD");
+  // An unreadable diff cannot be compared; the gate asks for a departure rather than guessing.
+  const gap = reviewGap(
+    deps.state.get(),
+    activeSlice,
+    snap.ok ? { digest: snap.value.digest, files: snap.value.files } : { digest: "unknown" },
+  );
+  return gap === undefined ? [] : [{ gate: REVIEW, why: gap }];
+}
+
+const reviewReason = (need: Need): string =>
+  `${need.gate}: ${need.why}. Each slice is reviewed by a fresh-context reviewer before it is committed. ` +
+  "Run devsys_review_start, spawn the reviewer it describes, record the packet with devsys_review_record " +
+  "and repeat until the review is satisfied. If skipping review is deliberate call devsys_record_departure " +
+  `with gate "${need.gate}", what you are doing instead, why, and the cost if wrong; then retry.`;
+
 const blockReason = (need: Need): string =>
-  `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
-  "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
-  `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
-  "instead, why, and the cost if wrong; then retry.";
+  need.gate === REVIEW
+    ? reviewReason(need)
+    : `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
+      "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
+      `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
+      "instead, why, and the cost if wrong; then retry.";
 
 const forbiddenReason = (found: readonly string[]): string =>
   `commit.forbidden-trailer: this commit carries an AI attribution (${found.join("; ")}). ` +
@@ -162,7 +187,7 @@ export function registerCommitGuard(deps: CommitGuardDeps): void {
     if (forbidden.length > 0) return { block: true, reason: forbiddenReason(forbidden) };
 
     const known = messages.flatMap((m) => (m === undefined ? [] : [m]));
-    const all: Need[] = [];
+    const all: Need[] = await reviewNeeds(deps, ctx);
     // A -F file that cannot be read now (written by this same command, or stdin) cannot be checked.
     if (extractions.some((e, i) => e.kind === "file" && messages[i] === undefined)) {
       all.push({

package/src/jev/questions/review.ts

@@ -0,0 +1,125 @@
+import type { ClassifierBoolQuestion, ClassifierChoiceQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import { LENSES, type Lens, SEVERITIES, type Severity } from "../../core/review.ts";
+import type { Jev, JevError } from "../client.ts";
+
+const lensQuestion = (instructions: string, yes: string, no: string): ClassifierBoolQuestion => ({
+  type: "bool",
+  instructions,
+  criteria: { true: yes, false: no },
+});
+
+export const LENS_QUESTIONS: Readonly<Record<Lens, ClassifierBoolQuestion>> = {
+  security: lensQuestion(
+    "Does the change in `diffSample` (stat in `diffStat`) touch authentication, authorisation, secrets, cryptography, input parsing from untrusted sources, shell or SQL construction, file paths from users, or network exposure?",
+    "It handles untrusted input, credentials, permissions or external exposure",
+    "It does not touch any security-relevant surface",
+  ),
+  concurrency: lensQuestion(
+    "Does the change introduce or alter concurrency: threads, async ordering, locks, shared mutable state, retries with side effects, queues, or race-prone file or process handling?",
+    "Ordering, sharing or timing between concurrent actors matters to correctness",
+    "The code is sequential and has no shared mutable state at risk",
+  ),
+  types: lensQuestion(
+    "Does the change add or alter domain types, parsing of external input, error types, state machines or public function signatures where illegal states could become representable?",
+    "It models domain data, parses input, or changes types or errors",
+    "It changes no types, parsing or error handling",
+  ),
+  tests: lensQuestion(
+    "Does the change alter behaviour that tests should pin, or alter tests themselves (added, edited, loosened, skipped or deleted)?",
+    "Behaviour or tests changed and test adequacy deserves a look",
+    "Docs, formatting or configuration only; no behaviour or tests changed",
+  ),
+  "api-contract": lensQuestion(
+    "Does the change alter a public interface: exported functions, CLI flags, tool schemas, file formats, configuration keys, wire formats or documented behaviour that other code or users rely on?",
+    "Something other code or users depend on changed shape or meaning",
+    "Only internals changed; no external contract is affected",
+  ),
+  "data-migration": lensQuestion(
+    "Does the change alter persisted data shape: schemas, stored entries, migrations, serialised formats, or how existing stored data is read?",
+    "Existing stored data must still be read, migrated or preserved correctly",
+    "No persisted data shape changes",
+  ),
+  ux: lensQuestion(
+    "Does the change alter what a person sees or does: messages, prompts, commands, output formats, error text, documentation of workflow, or interaction flow?",
+    "A human-facing message, flow or output changed",
+    "Nothing a person reads or interacts with changed",
+  ),
+  performance: lensQuestion(
+    "Does the change alter work done per request, per item or per run: loops over large inputs, I/O in hot paths, caching, polling, or algorithmic complexity?",
+    "Cost grows with input size or call frequency in a way that matters",
+    "No meaningful change to time or memory behaviour",
+  ),
+};
+
+export const SEVERITY_QUESTION: ClassifierChoiceQuestion = {
+  type: "choice",
+  instructions:
+    "Given the review `finding` and the surrounding `diffContext`, how severe is it? Judge by the consequence of shipping it, and by whether the reviewer showed a realistic triggering input. A finding with no demonstrated trigger, or one the code already guards against, is a false positive.",
+  criteria: {
+    blocking:
+      "A demonstrable defect or broken principle: wrong behaviour, data loss, security hole, or a defeated safeguard on a realistic input",
+    "should-fix":
+      "A real defect or missing test with a realistic trigger, but limited impact or easy workaround",
+    nit: "Style, naming, a contrived trigger, or a suggestion with no demonstrated impact",
+    "false-positive": "The claim is wrong or the code already handles the case",
+  },
+};
+
+const DIFF_SAMPLE_MAX = 8000;
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+export type LensInput = {
+  diffStat: string;
+  diffSample: string;
+  profiles: readonly string[];
+};
+
+/** Probability per lens that it applies. One narrow question per lens, asked together. */
+export async function judgeLenses(
+  jev: Jev,
+  input: LensInput,
+): Promise<Result<Record<Lens, number>, JevError>> {
+  const asked = await jev.ask(
+    {
+      diffStat: clip(input.diffStat, 2000),
+      diffSample: clip(input.diffSample, DIFF_SAMPLE_MAX),
+      profiles: input.profiles.slice(0, 5).map((p) => clip(p, 40)),
+    },
+    LENS_QUESTIONS,
+  );
+  if (!asked.ok) return asked;
+  const out = {} as Record<Lens, number>;
+  for (const lens of LENSES) {
+    const answer = asked.value[lens];
+    if (answer?.type !== "bool" || !Number.isFinite(answer.probability)) {
+      return err({ kind: "provider", message: `missing or malformed answer for lens ${lens}` });
+    }
+    out[lens] = answer.probability;
+  }
+  return ok(out);
+}
+
+export type SeverityInput = { finding: string; diffContext: string };
+
+export async function judgeSeverity(
+  jev: Jev,
+  input: SeverityInput,
+): Promise<Result<{ severity: Severity; confidence: number }, JevError>> {
+  const asked = await jev.ask(
+    { finding: clip(input.finding, 2000), diffContext: clip(input.diffContext, 6000) },
+    { severity: SEVERITY_QUESTION },
+  );
+  if (!asked.ok) return asked;
+  const answer = asked.value.severity;
+  if (answer?.type !== "choice") {
+    return err({ kind: "provider", message: "missing severity answer" });
+  }
+  const label = SEVERITIES.find((s) => s === answer.choice);
+  if (label === undefined) {
+    return err({ kind: "provider", message: `unknown severity label "${answer.choice}"` });
+  }
+  return ok({ severity: label, confidence: answer.confidence });
+}

package/src/review/digest.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import type { Exec } from "../core/exec.ts";
+import { err, ok, type Result } from "../core/result.ts";
+import { splitDiffByFile } from "../core/review-flow.ts";
+
+/** A short, stable identity for some text. Pure. */
+export const digestOf = (text: string): string =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
+
+export type DiffSnapshot = {
+  /** Identity of everything reviewed: the tracked diff plus the content of untracked files. */
+  digest: string;
+  /** Per-file digests, tracked and untracked, keyed by path. */
+  files: Record<string, string>;
+  stat: string;
+  sample: string;
+};
+
+const MAX_UNTRACKED = 200;
+
+/**
+ * The change in `range` (default `HEAD`: everything not yet committed) with its digest. `git diff`
+ * leaves out untracked files, so for a range that includes the work tree they are listed and
+ * content-hashed too; otherwise a new file would be committed unreviewed.
+ */
+export async function snapshotDiff(
+  exec: Exec,
+  cwd: string,
+  range: string,
+): Promise<Result<DiffSnapshot, string>> {
+  try {
+    const [diff, stat, others] = await Promise.all([
+      exec("git", ["diff", range], { cwd, timeout: 15_000 }),
+      exec("git", ["diff", "--stat", range], { cwd, timeout: 15_000 }),
+      range === "HEAD"
+        ? exec("git", ["ls-files", "--others", "--exclude-standard"], { cwd, timeout: 15_000 })
+        : Promise.resolve({ code: 0, stdout: "", stderr: "" }),
+    ]);
+    if (diff.code !== 0) return err(diff.stderr.trim() || `git diff ${range} failed`);
+    const untracked = others.code === 0 ? others.stdout.split("\n").filter((p) => p !== "") : [];
+    const files: Record<string, string> = {};
+    for (const [path, text] of Object.entries(splitDiffByFile(diff.stdout))) {
+      files[path] = digestOf(text);
+    }
+    if (untracked.length > 0) {
+      const shown = untracked.slice(0, MAX_UNTRACKED);
+      const hashes = await exec("git", ["hash-object", "--", ...shown], { cwd, timeout: 15_000 });
+      const lines = hashes.code === 0 ? hashes.stdout.split("\n").filter((l) => l !== "") : [];
+      for (const [i, path] of shown.entries()) files[path] = `new:${lines[i] ?? "unhashed"}`;
+    }
+    const names = Object.keys(files).sort();
+    const untrackedStat = untracked.map((p) => ` ${p} (untracked)`).join("\n");
+    return ok({
+      digest: digestOf(names.map((p) => `${p}\0${files[p]}`).join("\n")),
+      files,
+      stat: [stat.stdout.trimEnd(), untrackedStat].filter((p) => p !== "").join("\n"),
+      sample: diff.stdout.slice(0, 16_000),
+    });
+  } catch (cause) {
+    return err(cause instanceof Error ? cause.message : String(cause));
+  }
+}

package/src/review/review-tools.ts

@@ -0,0 +1,288 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { Exec } from "../core/exec.ts";
+import { resolveSlot } from "../core/models.ts";
+import {
+  addRound,
+  DEFAULT_LENSES,
+  type Finding,
+  nextAction,
+  type ReviewState,
+  selectLenses,
+  startReview,
+} from "../core/review.ts";
+import {
+  adoptSeverity,
+  combinePackets,
+  renderFollowups,
+  reviewerTask,
+  reviewLabel,
+  reviewOf,
+  upsertReview,
+} from "../core/review-flow.ts";
+import { parseReviewPacket, type ReviewPacket } from "../core/review-packet.ts";
+import { isParseError, type SliceRef } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeLenses, judgeSeverity } from "../jev/questions/review.ts";
+import { CONFIG_FILE, loadConfig } from "../state/config.ts";
+import { availableModels } from "../state/models-command.ts";
+import type { SessionState } from "../state/session-state.ts";
+import { snapshotDiff } from "./digest.ts";
+
+export type ReviewToolDeps = {
+  state: SessionState;
+  jev: (ctx: ExtensionContext) => Jev;
+  exec: Exec;
+  now?: () => Date;
+};
+
+const reply = (payload: string, isError = false) => ({
+  content: [{ type: "text" as const, text: payload }],
+  details: undefined,
+  isError,
+});
+
+const sliceOf = (given: string | undefined, state: SessionState): SliceRef | undefined => {
+  const slice = given?.trim() || state.get().activeSlice;
+  return slice === undefined || slice === "" ? undefined : (slice as SliceRef);
+};
+
+const NO_SLICE =
+  "no slice: pass `slice`, or start work on a slice first (there is no active slice)";
+
+const StartParameters = Type.Object({
+  slice: Type.Optional(
+    Type.String({ description: "Slice being reviewed; defaults to the active slice." }),
+  ),
+  diffRange: Type.Optional(
+    Type.String({
+      description: "Git revision range to review; defaults to HEAD (all uncommitted changes).",
+    }),
+  ),
+});
+
+/** One path segment is at most 64 chars (src/subagents/orch/paths.ts); keep room for round and attempt. */
+const pathSafe = (slice: string): string =>
+  slice
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+
+/** `devsys_review_start`: Jev picks lenses for the diff; the reply carries the agent_spawn payload for a fresh reviewer. */
+export function createReviewStartTool(
+  deps: ReviewToolDeps,
+): ToolDefinition<typeof StartParameters> {
+  return {
+    name: "devsys_review_start",
+    label: "Start review round",
+    description:
+      "Begin a review round for a slice: computes the diff digest, chooses review lenses, and returns the agent_spawn payload for a fresh-context reviewer. Run that spawn, then pass the reviewer's packet to devsys_review_record.",
+    promptSnippet: "Start a fresh-context review round for a slice",
+    parameters: StartParameters,
+    exposure: "direct",
+    async execute(
+      _id,
+      params: Static<typeof StartParameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      const slice = sliceOf(params.slice, deps.state);
+      if (slice === undefined) return reply(NO_SLICE, true);
+      const config = await loadConfig(ctx.cwd);
+      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
+      const range = params.diffRange?.trim() || "HEAD";
+      const snap = await snapshotDiff(deps.exec, ctx.cwd, range);
+      if (!snap.ok) return reply(`cannot read the diff for ${range}: ${snap.error}`, true);
+      if (snap.value.stat.trim() === "")
+        return reply(`the diff for ${range} is empty; nothing to review`, true);
+
+      const judged = await judgeLenses(deps.jev(ctx), {
+        diffStat: snap.value.stat,
+        diffSample: snap.value.sample,
+        profiles: deps.state.get().profiles ?? [],
+      });
+      const selected = judged.ok ? selectLenses(judged.value) : [];
+      const lenses = selected.length > 0 ? selected : [...DEFAULT_LENSES];
+      const basis = judged.ok
+        ? selected.length > 0
+          ? "Jev chose the lenses."
+          : "Jev found no specific lens; using the defaults."
+        : `Jev unavailable (${judged.error.kind}); using the default lenses.`;
+
+      const required = Math.max(
+        config.value.review.requiredCleanRounds,
+        config.value.review.minRounds,
+      );
+      const existing = reviewOf(deps.state.get(), slice) ?? startReview(slice, required);
+      const review: ReviewState = { ...existing, required };
+      deps.state.update((s) => upsertReview(s, review));
+      const action = nextAction(review, snap.value.digest);
+      if (action === "done") {
+        return reply(
+          `${reviewLabel(review)}. Review of ${slice} is already satisfied on this diff; nothing to run.`,
+        );
+      }
+
+      const round = review.rounds.length + 1;
+      const resolved = resolveSlot(
+        config.value.models,
+        "reviewer",
+        availableModels(ctx.modelRegistry),
+      );
+      const spawn = {
+        // A fresh path per attempt: a failed spawn must not leave a thread that blocks the retry.
+        path: `/review-${pathSafe(slice)}-r${round}-${(deps.now?.() ?? new Date()).getTime().toString(36)}`,
+        type: "reviewer",
+        task: reviewerTask({ slice, round, lenses, diffRange: range }),
+        ...(resolved.ok ? { model: resolved.value.model } : {}),
+        thinkingLevel: "high",
+        wait: true,
+      };
+      return reply(
+        [
+          `${reviewLabel(review)}; round ${round}; diff ${snap.value.digest}. ${basis}`,
+          `lenses: ${lenses.join(", ")}`,
+          `Spawn the reviewer with agent_spawn using exactly this payload, then pass its packet to devsys_review_record with diffDigest "${snap.value.digest}":`,
+          JSON.stringify(spawn),
+        ].join("\n"),
+      );
+    },
+  };
+}
+
+const RecordParameters = Type.Object({
+  slice: Type.Optional(
+    Type.String({ description: "Slice reviewed; defaults to the active slice." }),
+  ),
+  packets: Type.Array(Type.String(), {
+    description: "Reviewer packets, verbatim markdown: one per lens reviewer, all for one round.",
+  }),
+  diffRange: Type.Optional(
+    Type.String({ description: "The range that was reviewed; defaults to HEAD." }),
+  ),
+  diffDigest: Type.String({
+    description:
+      "The diff digest devsys_review_start reported for this round; the round is refused if the diff has changed since.",
+  }),
+});
+
+async function adjusted(
+  deps: ReviewToolDeps,
+  ctx: ExtensionContext,
+  findings: readonly Finding[],
+  diffContext: string,
+): Promise<{ findings: Finding[]; notes: string[] }> {
+  const out: Finding[] = [];
+  const notes: string[] = [];
+  for (const f of findings) {
+    const judged = await judgeSeverity(deps.jev(ctx), {
+      finding: `[${f.severity}] ${f.lens} ${f.path ?? ""}${f.line === undefined ? "" : `:${f.line}`} — ${f.summary}`,
+      diffContext,
+    });
+    const next = adoptSeverity(f, judged.ok ? judged.value : undefined);
+    out.push(next.finding);
+    if (next.note !== undefined) notes.push(next.note);
+  }
+  return { findings: out, notes };
+}
+
+/** `devsys_review_record`: parse packets, let Jev adjust severities, record the round, file the nits. */
+export function createReviewRecordTool(
+  deps: ReviewToolDeps,
+): ToolDefinition<typeof RecordParameters> {
+  return {
+    name: "devsys_review_record",
+    label: "Record review round",
+    description:
+      "Record one review round from the reviewer's packet(s): parses findings, lets Jev adjust severity when confident, files nits in docs/decisions/followups.md, and returns the clean-round count and the next action.",
+    promptSnippet: "Record a reviewer packet as a review round",
+    parameters: RecordParameters,
+    exposure: "direct",
+    async execute(
+      _id,
+      params: Static<typeof RecordParameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      const slice = sliceOf(params.slice, deps.state);
+      if (slice === undefined) return reply(NO_SLICE, true);
+      if (params.packets.length === 0)
+        return reply("no packets: pass the reviewer's packet markdown in `packets`", true);
+      const packets: ReviewPacket[] = [];
+      for (const [i, raw] of params.packets.entries()) {
+        const parsed = parseReviewPacket(raw);
+        if (isParseError(parsed))
+          return reply(`packet ${i + 1} is malformed: ${parsed.message}`, true);
+        packets.push(parsed);
+      }
+      const config = await loadConfig(ctx.cwd);
+      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
+      const snap = await snapshotDiff(deps.exec, ctx.cwd, params.diffRange?.trim() || "HEAD");
+      if (!snap.ok) return reply(`cannot read the diff: ${snap.error}`, true);
+
+      if (params.diffDigest !== snap.value.digest) {
+        return reply(
+          `the diff changed since the review started (reviewed ${params.diffDigest}, now ${snap.value.digest}); the reviewer did not see the current code. Run devsys_review_start again.`,
+          true,
+        );
+      }
+      const required = Math.max(
+        config.value.review.requiredCleanRounds,
+        config.value.review.minRounds,
+      );
+      const before = reviewOf(deps.state.get(), slice) ?? startReview(slice, required);
+      const expected = before.rounds.length + 1;
+      const wrong = packets.findIndex((p) => p.round !== expected || p.slice !== slice);
+      if (wrong !== -1) {
+        return reply(
+          `packet ${wrong + 1} is for slice "${packets[wrong]?.slice}" round ${packets[wrong]?.round}; this is round ${expected} of slice "${slice}". A packet is recorded once, in the round it was written for; ask the reviewer for a packet with the right header.`,
+          true,
+        );
+      }
+
+      const merged = combinePackets(packets);
+      const { findings, notes } = await adjusted(deps, ctx, merged.findings, snap.value.sample);
+      const review = addRound(
+        { ...before, required },
+        {
+          lenses: merged.lenses,
+          findings,
+          reviewedAt: (deps.now?.() ?? new Date()).toISOString(),
+          diffDigest: snap.value.digest,
+          files: snap.value.files,
+        },
+      );
+
+      // File the nits first: if this fails nothing is recorded and a retry cannot count the round twice.
+      const followups = renderFollowups(slice, review.rounds.length, findings);
+      if (followups !== undefined) {
+        try {
+          const dir = join(ctx.cwd, "docs", "decisions");
+          await mkdir(dir, { recursive: true });
+          await appendFile(join(dir, "followups.md"), followups);
+        } catch (cause) {
+          return reply(
+            `could not write docs/decisions/followups.md (${cause instanceof Error ? cause.message : String(cause)}); the round was not recorded, retry`,
+            true,
+          );
+        }
+      }
+      deps.state.update((s) => upsertReview(s, review));
+      const counts = (sev: Finding["severity"]) =>
+        findings.filter((f) => f.severity === sev).length;
+      return reply(
+        [
+          `Round ${review.rounds.length} recorded: ${counts("blocking")} blocking, ${counts("should-fix")} should-fix, ${counts("nit")} nit, ${counts("false-positive")} false-positive.`,
+          reviewLabel(review),
+          ...notes,
+          `next: ${nextAction(review, snap.value.digest)}`,
+        ].join("\n"),
+      );
+    },
+  };
+}

package/src/state/session-state.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { parseDeparture } from "../core/departure.ts";
+import { parseReviewState, type ReviewState } from "../core/review.ts";
 import {
   CI_STATUSES,
   type CiState,
@@ -65,11 +66,32 @@ function parseTestRun(input: unknown): TestRun | ParseError {
   return { at, exitCode, summary };
 }
 
+function parseReviews(input: unknown): ReviewState[] | ParseError {
+  if (!Array.isArray(input)) return parseError("reviews must be an array");
+  const out: ReviewState[] = [];
+  for (const raw of input) {
+    const review = parseReviewState(raw);
+    if (isParseError(review)) return review;
+    out.push(review);
+  }
+  return out;
+}
+
 /** Boundary parse for persisted state: the only place state is cast from `unknown`. */
 export function parseDevsysState(input: unknown): DevsysState | ParseError {
   if (!isRecord(input)) return parseError("devsys state must be an object");
-  const { phase, sizing, activeSlice, openDepartures, jev, lastPushAt, ci, profiles, lastTestRun } =
-    input;
+  const {
+    phase,
+    sizing,
+    activeSlice,
+    openDepartures,
+    jev,
+    lastPushAt,
+    ci,
+    profiles,
+    lastTestRun,
+    reviews,
+  } = input;
   if (!PHASES.includes(phase as Phase)) return parseError(`unknown phase: ${String(phase)}`);
   if (!JEV.includes(jev as JevStatus)) return parseError(`unknown jev status: ${String(jev)}`);
   if (!Array.isArray(openDepartures)) return parseError("openDepartures must be an array");
@@ -94,6 +116,8 @@ export function parseDevsysState(input: unknown): DevsysState | ParseError {
   if (isParseError(parsedProfiles)) return parsedProfiles;
   const parsedRun = lastTestRun === undefined ? undefined : parseTestRun(lastTestRun);
   if (isParseError(parsedRun)) return parsedRun;
+  const parsedReviews = reviews === undefined ? undefined : parseReviews(reviews);
+  if (isParseError(parsedReviews)) return parsedReviews;
   return {
     phase: phase as Phase,
     jev: jev as JevStatus,
@@ -104,6 +128,7 @@ export function parseDevsysState(input: unknown): DevsysState | ParseError {
     ...(parsedCi !== undefined ? { ci: parsedCi } : {}),
     ...(parsedProfiles !== undefined ? { profiles: parsedProfiles } : {}),
     ...(parsedRun !== undefined ? { lastTestRun: parsedRun } : {}),
+    ...(parsedReviews !== undefined ? { reviews: parsedReviews } : {}),
   };
 }