@jwilger/pi-development-system 0.16.0 → 0.18.0

package/agents/advisor.md

@@ -1,6 +1,5 @@
 ---
 name: advisor
-icon: ''
 description: "Read-only decision support for hard design, planning or trade-off questions: returns a recommendation, the alternatives considered, and the cost if the recommendation is wrong. Does not implement."
 thinkingLevel: high
 color: accent

package/agents/implementer.md

@@ -1,6 +1,5 @@
 ---
 name: implementer
-icon: ''
 description: "Implements exactly one task record test-first: failing test, minimal code, passing run, then reports Run/Expected evidence. Edits only the files the task names; stops and reports when the task is unclear or needs a decision."
 thinkingLevel: medium
 color: success

package/agents/lens-cagan.md

@@ -1,6 +1,5 @@
 ---
 name: lens-cagan
-icon: ''
 description: "Read-only product risk lens: value, usability, feasibility and viability risks; outcome versus output; whether the work builds to learn or builds to earn. Reviews planning and product artifacts as Cagan; advisory critique, never customer evidence."
 thinkingLevel: high
 color: accent

package/agents/lens-perri.md

@@ -1,6 +1,5 @@
 ---
 name: lens-perri
-icon: ''
 description: "Read-only anti-feature-factory lens: output versus outcome, roadmap-as-promises, escaping the build trap. Reviews planning and product artifacts as Perri; advisory critique, never customer evidence."
 thinkingLevel: high
 color: accent

package/agents/lens-pichler.md

@@ -1,6 +1,5 @@
 ---
 name: lens-pichler
-icon: ''
 description: "Read-only product-strategy and backlog lens: vision, goal-based roadmap, product-model coherence, decisions with owners. Reviews planning and product artifacts as Pichler; advisory critique, never customer evidence."
 thinkingLevel: high
 color: accent

package/agents/lens-rumelt.md

@@ -1,6 +1,5 @@
 ---
 name: lens-rumelt
-icon: ''
 description: "Read-only strategy-kernel lens: diagnosis, guiding policy, coherent actions; flags fluff, goals-as-strategy and bad strategy. Reviews planning and product artifacts as Rumelt; advisory critique, never customer evidence."
 thinkingLevel: high
 color: accent

package/agents/lens-torres.md

@@ -1,6 +1,5 @@
 ---
 name: lens-torres
-icon: ''
 description: "Read-only continuous-discovery lens: outcome at the root, one opportunity at a time, at least two solutions compared, assumptions made specific and tested. Reviews planning and product artifacts as Torres; advisory critique, never customer evidence."
 thinkingLevel: high
 color: accent

package/agents/reviewer.md

@@ -1,6 +1,5 @@
 ---
 name: reviewer
-icon: ''
 description: Fresh-context, non-mutating review of one slice's diff for demonstrable defects, with severity, path:line, and the smallest local repair; emits the devsys review packet. Not for implementing fixes or style quotas.
 thinkingLevel: high
 color: warning

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.16.0",
+  "version": "0.18.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,62 @@
+---
+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`, i.e. everything uncommitted). 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`
+   (`packets: [...]`; one packet per lens reviewer if you split them).
+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 move a finding's severity when it is at least 0.8 confident; the reply
+says what moved. 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,121 @@
+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 function reviewGap(
+  state: DevsysState,
+  slice: SliceRef,
+  digestNow: string,
+): 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, digestNow)) {
+    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":
+      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`;
+  }
+}
+
+/** 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;
+
+/** Take Jev's severity only when it is confident and different; say what moved so it is never silent. */
+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 };
+  }
+  return {
+    finding: { ...finding, severity: judged.severity },
+    note: `${finding.id}: Jev moved severity ${finding.severity} → ${judged.severity} (confidence ${judged.confidence.toFixed(2)})`,
+  };
+}
+
+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}\`). 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:",
+    "",
+    `## 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,156 @@
+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;
+};
+
+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 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);
+  }
+  return { n, lenses: lenses as string[], findings: parsed, reviewedAt, diffDigest };
+}
+
+/** 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,29 @@ 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 ? snap.value.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 +183,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,31 @@
+import { createHash } from "node:crypto";
+import type { Exec } from "../core/exec.ts";
+import { err, ok, type Result } from "../core/result.ts";
+
+/** A short, stable identity for a diff's text. Pure. */
+export const digestOf = (diff: string): string =>
+  createHash("sha256").update(diff).digest("hex").slice(0, 16);
+
+export type DiffSnapshot = { digest: string; stat: string; sample: string };
+
+/** The diff for `range` (default: everything not yet committed, `HEAD`), with its digest. */
+export async function snapshotDiff(
+  exec: Exec,
+  cwd: string,
+  range: string,
+): Promise<Result<DiffSnapshot, string>> {
+  try {
+    const [diff, stat] = await Promise.all([
+      exec("git", ["diff", range], { cwd, timeout: 15_000 }),
+      exec("git", ["diff", "--stat", range], { cwd, timeout: 15_000 }),
+    ]);
+    if (diff.code !== 0) return err(diff.stderr.trim() || `git diff ${range} failed`);
+    return ok({
+      digest: digestOf(diff.stdout),
+      stat: stat.stdout,
+      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,253 @@
+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).",
+    }),
+  ),
+});
+
+const pathSafe = (slice: string): string => slice.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+
+/** `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 = {
+        path: `/review-${pathSafe(slice)}-r${round}`,
+        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:",
+          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." }),
+  ),
+});
+
+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);
+
+      const merged = combinePackets(packets);
+      const { findings, notes } = await adjusted(deps, ctx, merged.findings, snap.value.sample);
+      const required = Math.max(
+        config.value.review.requiredCleanRounds,
+        config.value.review.minRounds,
+      );
+      const before = reviewOf(deps.state.get(), slice) ?? startReview(slice, required);
+      const review = addRound(
+        { ...before, required },
+        {
+          lenses: merged.lenses,
+          findings,
+          reviewedAt: (deps.now?.() ?? new Date()).toISOString(),
+          diffDigest: snap.value.digest,
+        },
+      );
+      deps.state.update((s) => upsertReview(s, review));
+
+      const followups = renderFollowups(slice, review.rounds.length, findings);
+      if (followups !== undefined) {
+        const dir = join(ctx.cwd, "docs", "decisions");
+        await mkdir(dir, { recursive: true });
+        await appendFile(join(dir, "followups.md"), followups);
+      }
+      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 } : {}),
   };
 }
 

package/src/subagents/VENDORED.md

@@ -39,4 +39,4 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 6. Empty scope (I5 review): `orch/runtime.ts` `availableScopedModels` treats an empty `/scoped-models` as no restriction (pi's meaning) instead of "matches nothing", because every devsys agent declares `models:` and would otherwise be unspawnable by default. Pinned models are also re-applied on resume (`resolveInitialSettings`), since a restored session may hold only inherited history.
-7. Bundled agents outside `src/subagents`: `agents/researcher.md` and `agents/reviewer.md` differ from upstream (devsys `models:` family lists; the reviewer's packet format); `agents/{advisor,implementer,lens-*}.md` are new. The agent file format itself is unchanged.
+7. Bundled agents outside `src/subagents`: `agents/researcher.md` (devsys `models:` family list) and `agents/reviewer.md` (devsys `models:` list and packet format; description rewritten; upstream `icon` and `modelSuggestions` removed) differ from upstream; `agents/{advisor,implementer,lens-*}.md` are new. The agent file format itself is unchanged.