@jwilger/pi-development-system 0.86.0 → 0.88.0

package/README.md

@@ -27,6 +27,10 @@ terminology, journeys). `devsys_lens_review` plans a review of the brief by five
 writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
 a commit that shapes the architecture without one is stopped by the soft gate `adr.missing`.
 
+A reviewer subagent hands over its result with `devsys_submit_review` (typed arguments; a result that
+contradicts itself or is for the wrong round is refused with an error id), and `devsys_review_record`
+reads it. A markdown packet is still accepted (ADR 0006).
+
 Event modelling has a skill (`event-modelling`: three slice patterns, Given/When/Then, completeness).
 `devsys_event_model_check` validates a directory of slice files (schema v1) and renders the swimlane
 Markdown or a Mermaid diagram; each profile's `gwt-tests` reference turns scenarios into failing tests.
@@ -40,6 +44,10 @@ in `local-only` mode; CI is not awaited), and `devsys_finish_slice` closes it ex
 reason, abandons it. A plan's increments each end in a push, so each increment is its own slice: the
 next one starts with `devsys_intake`.
 
+`devsys_intake` does not interrupt autonomous work: Jev's size is used when Jev is at least 50%
+confident, and the user is asked to pick only when it is less sure (or unavailable). A size decided up
+front, such as in a goal's planning, is passed as `size` and skips the sizing question entirely (a `fix` still asks whether to waive review).
+
 With `codemode` enabled (`"defaultTools": ["+codemode"]` in pi settings), rarely used tools are
 reached through scripts and the `judge_*` Jev wrappers exist for scripts only; without codemode
 the rarely used tools are declared directly and the wrappers are absent.

package/agents/reviewer.md

@@ -18,6 +18,7 @@ tools:
     - find
     - ls
     - agent_update
+    - devsys_submit_review
     - agent_pause
 ---
 
@@ -41,7 +42,7 @@ Do not modify files. bash is not a sandbox: use it only for read-only inspection
 
 ## Output
 
-Use exactly this packet; the coordinator parses it.
+Submit your result by calling `devsys_submit_review` (slice and round exactly as the task gives them): it checks the call and refuses a self-contradicting one with an error id, which you correct and resubmit. After it accepts, end with one short line. Only when that tool is not available, return exactly this packet instead; the coordinator parses it.
 
 ```markdown
 ## Review — <slice> — round <n> — lenses: <a, b>

package/extensions/development-system.ts

@@ -35,6 +35,8 @@ import { createFinishSliceTool, registerSliceClose } from "../src/planning/slice
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
 import { createLensReviewTool } from "../src/review/lens-review-tool.ts";
 import { createReviewRecordTool, createReviewStartTool } from "../src/review/review-tools.ts";
+import { createSubmissionStore } from "../src/review/submissions.ts";
+import { createSubmitReviewTool } from "../src/review/submit-tool.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";
@@ -186,13 +188,16 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),
   );
   pi.registerTool(createIntakeTool({ pi, state, jev: (ctx) => jevHolder.forContext(ctx) }));
+  const submissions = createSubmissionStore();
   const reviewDeps = {
     state,
+    submissions,
     jev: (ctx: ExtensionContext) => jevHolder.forContext(ctx),
     exec,
   } satisfies Parameters<typeof createReviewStartTool>[0];
   pi.registerTool(createReviewStartTool(reviewDeps));
   pi.registerTool(createReviewRecordTool(reviewDeps));
+  pi.registerTool(createSubmitReviewTool({ state, submissions }));
   registerModelsCommand(pi);
   piSubagent(pi);
 

package/package.json

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

package/prompts/devsys-plan.md

@@ -9,4 +9,4 @@ Write the plan for the current work with the work-intake-and-slicing skill.
 3. Write each task so that someone who sees only that task could finish it. Never write `TBD`.
 4. Run `devsys_task_check` on every task record you wrote and fix each one until it says ready. Split any that come back too-big.
 5. Stop and ask the user to review the plan before any implementation starts. Do not start a goal yet: a goal tool may continue on its own and begin implementing before the review.
-6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the increment is built; it does nothing if the work is already implementing). A push of a clean, reviewed tree closes the slice, so each later increment starts with `devsys_intake`. Then, if a `create_goal` tool exists in this session, call it with the objective "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.
+6. Only after the user approves the plan: call `devsys_begin_work` (so the review and red-first gates are on while the increment is built; it does nothing if the work is already implementing). A push of a clean, reviewed tree closes the slice, so each later increment starts with `devsys_intake`. Then, if a `create_goal` tool exists in this session, call it with the objective (name each increment's size in it, so every later `devsys_intake` passes `size` and nobody is asked to size it; a `fix` still asks the user whether to waive review) "complete docs/plan/<slug>.md honouring its Constraints and Progress checklist, one increment at a time, stopping after each increment's Release step". Otherwise tell the user the plan path so they can start a goal on it. Do not depend on any goal tool's file format.

package/prompts/devsys-review.md

@@ -6,5 +6,5 @@ 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`; only the `HEAD` range clears the commit gate).
 2. Run the `agent_spawn` payload it returns, unchanged.
-3. Pass the reviewer's packet verbatim to `devsys_review_record` with the same `slice`, `diffDigest` and `diffRange` the start reply gave.
+3. The reviewer submits its result with `devsys_submit_review`; call `devsys_review_record` with the same `slice`, `diffDigest` and `diffRange` the start reply gave (no packets needed). Only if the reviewer returned a markdown packet instead, pass it verbatim in `packets`.
 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/prompts/devsys-start.md

@@ -5,7 +5,7 @@ argument-hint: "<what you want done>"
 Start new work with the work-intake-and-slicing skill.
 
 1. Call `devsys_intake` with `request` set to: $ARGUMENTS (if empty, ask the user what they want done first).
-2. Show the user the proposed size and artifacts. The tool asks them to confirm or change the size.
+2. Show the user the size and artifacts. Jev sizes the work and intake proceeds without asking when it is at least 50% confident; only a less confident Jev makes the tool ask the user to pick. If the size is already decided (say, in a goal's or plan's up-front planning), pass it as `size` and nobody is asked to size it (a `fix` still asks whether to waive review).
 3. Produce the planning artifacts first (brief, decision register, journeys, event model, architecture, lens review, in that order, whichever are recommended), then the task record. `review` and `adr-if-needed` are not written up front: review happens on the finished slice, and an ADR when a decision needs one. To skip one, call `devsys_record_departure` with gate `artifact.skipped:<artifact>` and the reason; do not skip silently. The event model and architecture are recommendations, never gates.
 4. For `capability` and `product` the phase stays `planning` while you produce the artifacts and the plan. The single point where it changes is the user approving the whole plan: then call `devsys_begin_work` so the review and red-first gates switch on (it does nothing if already implementing).
-5. For a confirmed `fix` the user is also asked whether to skip fresh-context review (it is logged if they say yes; if no, the slice needs its review rounds). For `fix` and `change` the phase is already `implementing`: write the task record, then work it test-first.
+5. For a `fix` the user is also asked (when a user is present) whether to skip fresh-context review (it is logged if they say yes; if no, the slice needs its review rounds). For `fix` and `change` the phase is already `implementing`: write the task record, then work it test-first.

package/skills/code-review/SKILL.md

@@ -17,11 +17,13 @@ Review is a soft gate (`review.unsatisfied`): skipping it needs a recorded depar
    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
-   `slice` and `diffDigest` the start reply gave, and the same `diffRange` if you gave one
-   (`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.
+3. The reviewer submits its result with `devsys_submit_review` (typed arguments; a
+   self-contradicting or wrong-round result is refused to the reviewer with an error id).
+   Call `devsys_review_record` with the `slice` and `diffDigest` the start reply gave, and
+   the same `diffRange` if you gave one; it reads the submitted results of the round. If a
+   reviewer returned a markdown packet instead, pass it verbatim in `packets: [...]` (all
+   lens packets of one round in one call). A result is recorded once, in the round it
+   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
      (starting again on an unchanged diff is refused).
@@ -29,7 +31,9 @@ Review is a soft gate (`review.unsatisfied`): skipping it needs a recorded depar
    - `stale-diff`: the diff changed after a satisfied review; one more round.
    - `done`: commit.
 
-## The packet
+## The result
+
+The fields of `devsys_submit_review` mirror this packet; the markdown form is the fallback (ADR 0006).
 
 ```markdown
 ## Review — <slice> — round <n> — lenses: <a, b>

package/skills/work-intake-and-slicing/SKILL.md

@@ -16,7 +16,7 @@ Ask these in order and stop at the first yes:
 3. Does it change existing behaviour in one area? That is a `change`.
 4. Otherwise it is a `fix`.
 
-`/devsys-start` proposes a size with Jev and asks you to confirm. If you disagree, change it; the size is a judgement, not a rule.
+`/devsys-start` sizes the work with Jev and proceeds when Jev is at least 50% confident, saying so; below that it asks you to pick. If the size is already decided (a goal's planning, a plan's increment), pass it as `size` and nobody is asked to size it (a `fix` still asks whether to waive review). If you disagree with a size, change it; it is a judgement, not a rule.
 
 ## Artifacts follow size
 

package/src/context/phase-guide.ts

@@ -12,7 +12,7 @@ export function phaseGuide(phase: Phase): string {
     case "implementing":
       return "Implementing one slice. Write a failing test first, make it pass with the least code, run the tests and read the result before claiming anything. Push when the slice is complete and reviewed: a push of a clean tree closes it (devsys_finish_slice closes it explicitly).";
     case "reviewing":
-      return "Reviewing. Call devsys_review_start for a fresh-context review, pass its packet and diffDigest to devsys_review_record, fix every blocking and should-fix finding (red-first still applies), and repeat until the review is satisfied; then the slice moves to delivering.";
+      return "Reviewing. Call devsys_review_start for a fresh-context review, give its diffDigest to devsys_review_record (the reviewer submits through devsys_submit_review), fix every blocking and should-fix finding (red-first still applies), and repeat until the review is satisfied; then the slice moves to delivering.";
     case "delivering":
       return "Delivering. The review is satisfied. Commit with a rationale, push, and release; a push of a clean tree closes the slice (devsys_finish_slice closes it explicitly, or abandons it with a reason). Editing source reopens implementing. A red trunk (CI) is repaired first.";
     default:

package/src/context/status.ts

@@ -14,9 +14,8 @@ const ciLabel = (state: DevsysState): string | undefined => {
 };
 
 const activeReview = (state: DevsysState): string | undefined => {
-  // Without an active slice (before /devsys-start exists) show the most recent review instead of nothing.
-  const review =
-    state.activeSlice === undefined ? state.reviews?.at(-1) : reviewOf(state, state.activeSlice);
+  // No active slice, no review: a closed slice's last count would only mislead the next one.
+  const review = state.activeSlice === undefined ? undefined : reviewOf(state, state.activeSlice);
   return review === undefined ? undefined : reviewLabel(review);
 };
 

package/src/core/review-flow.ts

@@ -19,8 +19,9 @@ export const upsertReview = (state: DevsysState, review: ReviewState): DevsysSta
   return { ...state, reviews: [...others, review] };
 };
 
+/** Capped at the requirement: extra clean rounds (after a late change) are not progress past "done". */
 export const reviewLabel = (review: ReviewState): string =>
-  `review: ${cleanStreak(review)}/${review.required} clean`;
+  `review: ${Math.min(cleanStreak(review), review.required)}/${review.required} clean`;
 
 /**
  * Why a commit on this slice lacks a satisfied review, or `undefined` when the review is complete
@@ -175,7 +176,8 @@ export function reviewerTask(input: {
     `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 ls-files --others --exclude-standard\` (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):",
+    `Report your result by calling devsys_submit_review with slice "${input.slice}", round ${input.round}, lenses ${JSON.stringify(input.lenses)}, your sources, your findings (lens, severity, path, line, summary) and the verdict. If it refuses, for example with verdict-contradicts-findings or wrong-round, correct the call and submit again; when it accepts, end with one short line.`,
+    "Only if devsys_submit_review is not available, return the review packet from your instructions instead, with exactly this header (slice and round must not change):",
     "",
     `## Review — ${input.slice} — round ${input.round} — lenses: ${lenses}`,
     "### Sources inspected",

package/src/core/review-submission.ts

@@ -0,0 +1,60 @@
+import type { Finding, Severity } from "./review.ts";
+import type { ReviewPacket } from "./review-packet.ts";
+
+/** A reviewer's result as it arrives from the typed submit tool (see ADR 0006). */
+export type Submission = {
+  readonly slice: string;
+  readonly round: number;
+  readonly lenses: ReadonlyArray<string>;
+  readonly sources: ReadonlyArray<string>;
+  readonly findings: ReadonlyArray<{
+    readonly lens: string;
+    readonly severity: Severity;
+    readonly path?: string | undefined;
+    readonly line?: number | undefined;
+    readonly summary: string;
+  }>;
+  readonly verdict: "no-blocking" | "blocking";
+};
+
+/** Why a submission was refused: a stable kebab-case id and a message the reviewer can act on. */
+export type SubmitError = {
+  readonly id: "verdict-contradicts-findings" | "finding-lens-not-listed";
+  readonly message: string;
+};
+
+const counts = (f: { severity: Severity }): boolean =>
+  f.severity === "blocking" || f.severity === "should-fix";
+
+/** The packet a submission stands for, or the refusal. The schema has already checked its shape. */
+export function packetFromSubmission(input: Submission): ReviewPacket | SubmitError {
+  const unlisted = input.findings.find((f) => !input.lenses.includes(f.lens));
+  if (unlisted !== undefined) {
+    return {
+      id: "finding-lens-not-listed",
+      message: `a finding names lens "${unlisted.lens}" but the packet's lenses are ${input.lenses.join(", ")}; list every lens you used in \`lenses\``,
+    };
+  }
+  if (input.findings.some(counts) !== (input.verdict === "blocking")) {
+    return {
+      id: "verdict-contradicts-findings",
+      message: `verdict "${input.verdict}" contradicts the findings: blocking/should-fix findings mean "blocking", otherwise "no-blocking"`,
+    };
+  }
+  const findings: Finding[] = input.findings.map((f, i) => ({
+    id: `${f.lens}-${i + 1}`,
+    severity: f.severity,
+    ...(f.path === undefined ? {} : { path: f.path }),
+    ...(f.line === undefined ? {} : { line: f.line }),
+    summary: f.summary,
+    lens: f.lens,
+  }));
+  return {
+    slice: input.slice,
+    round: input.round,
+    lenses: input.lenses,
+    sources: input.sources,
+    findings,
+    verdict: input.verdict,
+  };
+}

package/src/planning/intake-tool.ts

@@ -13,13 +13,27 @@ import type { Jev } from "../jev/client.ts";
 import { judgeSizing } from "../jev/questions/sizing.ts";
 import { appendDecision } from "../state/decision-log.ts";
 import type { SessionState } from "../state/session-state.ts";
-import { phaseFor, proposeArtifacts, renderProposal, sliceSlug, uniqueSlice } from "./intake.ts";
+import {
+  decideSize,
+  phaseFor,
+  proposeArtifacts,
+  renderProposal,
+  type SizeDecision,
+  sliceSlug,
+  uniqueSlice,
+} from "./intake.ts";
 
 const Parameters = Type.Object({
   request: Type.String({ description: "What the user asked for, in their words." }),
   repoSummary: Type.Optional(
     Type.String({ description: "One or two sentences on the repository, if known." }),
   ),
+  size: Type.Optional(
+    Type.String({
+      description:
+        "fix, change, capability or product, when the size is already decided (for example during a goal's up-front planning). Skips Jev's sizing question and the user's.",
+    }),
+  ),
 });
 
 const SIZES: readonly Sizing[] = ["fix", "change", "capability", "product"];
@@ -62,6 +76,9 @@ async function declinedToReplace(
   const { activeSlice, phase } = before;
   const inFlight = phase === "implementing" || phase === "reviewing" || phase === "delivering";
   if (activeSlice === undefined || !inFlight) return undefined;
+  if (!ctx.hasUI) {
+    return `Slice "${activeSlice}" is still ${phase}; replacing it needs the user's yes, and there is no UI to ask. Intake cancelled; slice "${activeSlice}" is unchanged.`;
+  }
   const go = await ctx.ui.confirm(
     "Slice already in flight",
     `Slice "${activeSlice}" is still ${phase}. Its uncommitted or unpushed changes would ship under the new slice's rules. Start new work anyway?`,
@@ -69,6 +86,28 @@ async function declinedToReplace(
   return go ? undefined : `Intake cancelled; slice "${activeSlice}" is unchanged.`;
 }
 
+type Chosen = { readonly sizing: Sizing } | { readonly stop: string; readonly isError: boolean };
+
+/** A decided size passes through; an undecided one asks the user (headless: stops with the proposal). */
+async function chooseSize(
+  ctx: ExtensionContext,
+  decision: SizeDecision,
+  proposalFor: (size: Sizing) => ReturnType<typeof proposeArtifacts>,
+): Promise<Chosen> {
+  if (decision.kind === "decided") return { sizing: decision.size };
+  const { basis, proposed } = decision;
+  const proposal = renderProposal({ sizing: proposed, basis, proposal: proposalFor(proposed) });
+  if (!ctx.hasUI) {
+    return { stop: `${proposal}\nHeadless: proposal only, not applied.`, isError: false };
+  }
+  const picked = await ctx.ui.select(`Size this work (${basis})`, sizeChoices(proposed));
+  if (picked === undefined) {
+    return { stop: `${proposal}\nIntake cancelled; nothing changed.`, isError: false };
+  }
+  const parsed = parseSizing(picked);
+  return isParseError(parsed) ? { stop: parsed.message, isError: true } : { sizing: parsed };
+}
+
 const waiverNote = (sizing: Sizing, departed: string | undefined): string => {
   if (departed !== undefined)
     return `\nRecorded in ${departed}: you waived fresh-context review for this fix.`;
@@ -108,7 +147,7 @@ async function fixWithoutReview(
   return path;
 }
 
-/** `devsys_intake`: Jev proposes a size and artifact set; the user confirms; state moves to the first phase. */
+/** `devsys_intake`: Jev (or the caller) sizes the work; only a doubtful Jev asks the user; state moves to the first phase. */
 export function createIntakeTool(deps: {
   pi: ExtensionAPI;
   state: SessionState;
@@ -119,36 +158,39 @@ export function createIntakeTool(deps: {
     label: "Start work",
     description:
       "Size a request (fix, change, capability, product) and list the planning artifacts that size needs. " +
-      "The user confirms the size; then phase, sizing and the active slice are set. Call at the start of any non-trivial work.",
+      "Jev sizes the work and the user is asked only when Jev is under 50% confident; pass `size` when it is already decided. Then phase, sizing and the active slice are set. Call at the start of any non-trivial work.",
     promptSnippet: "Size new work and propose the planning artifacts it needs",
     parameters: Parameters,
     exposure: "model-only",
     async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
       const request = params.request.trim();
       if (request === "") return reply("request must not be empty", true);
-      const judged = await judgeSizing(deps.jev(ctx), {
-        request,
-        repoSummary: params.repoSummary ?? "",
-      });
-      const proposedSize: Sizing = judged.ok ? judged.value.sizing : "change";
-      const basis = judged.ok
-        ? `Jev judged ${judged.value.sizing} (confidence ${judged.value.confidence.toFixed(2)}).`
-        : `Jev unavailable (${judged.error.kind}); defaulted to change.`;
-      const artifactNeed = judged.ok ? judged.value.artifactNeed : {};
+      const given = params.size === undefined ? undefined : parseSizing(params.size.trim());
+      if (given !== undefined && isParseError(given)) return reply(given.message, true);
+      const judged =
+        given === undefined
+          ? await judgeSizing(deps.jev(ctx), { request, repoSummary: params.repoSummary ?? "" })
+          : undefined;
+      const decision = decideSize(
+        given,
+        judged?.ok ? judged.value : undefined,
+        judged?.ok === false ? judged.error.kind : "not asked",
+      );
+      const artifactNeed = judged?.ok ? judged.value.artifactNeed : {};
       const proposalFor = (size: Sizing) => proposeArtifacts(size, artifactNeed);
-      const proposal = renderProposal({
-        sizing: proposedSize,
-        basis,
-        proposal: proposalFor(proposedSize),
-      });
-      if (!ctx.hasUI) return reply(`${proposal}\nHeadless: proposal only, not applied.`);
-      const picked = await ctx.ui.select(`Size this work (${basis})`, sizeChoices(proposedSize));
-      if (picked === undefined) return reply(`${proposal}\nIntake cancelled; nothing changed.`);
-      const sizing = parseSizing(picked);
-      if (isParseError(sizing)) return reply(sizing.message, true);
+      const chosen = await chooseSize(ctx, decision, proposalFor);
+      if ("stop" in chosen) return reply(chosen.stop, chosen.isError);
+      const { sizing } = chosen;
       const before = deps.state.get();
       const keep = await declinedToReplace(ctx, before);
-      if (keep !== undefined) return reply(`${proposal}\n${keep}`);
+      if (keep !== undefined) {
+        const proposal = renderProposal({
+          sizing,
+          basis: decision.basis,
+          proposal: proposalFor(sizing),
+        });
+        return reply(`${proposal}\n${keep}`);
+      }
       const slice = uniqueSlice(sliceSlug(request), slicesInUse(before)) as SliceRef;
       deps.state.update((s) => ({
         ...s,
@@ -156,9 +198,14 @@ export function createIntakeTool(deps: {
         sizing,
         activeSlice: slice,
       }));
-      const waived = sizing === "fix" ? await askToWaiveReview(ctx, request, slice) : false;
+      const waived =
+        sizing === "fix" && ctx.hasUI ? await askToWaiveReview(ctx, request, slice) : false;
       const departed = waived ? await fixWithoutReview(deps, ctx, slice) : undefined;
-      const final = renderProposal({ sizing, basis, proposal: proposalFor(sizing) });
+      const final = renderProposal({
+        sizing,
+        basis: decision.basis,
+        proposal: proposalFor(sizing),
+      });
       const note = waiverNote(sizing, departed);
       return reply(`${final}\nPhase: ${phaseFor(sizing)}. Active slice: ${slice}.${note}`);
     },

package/src/planning/intake.ts

@@ -71,3 +71,36 @@ export const renderProposal = (input: {
   );
   return lines.join("\n");
 };
+
+/** Jev confidence below this asks the human; at or above it intake proceeds with Jev's size. */
+const ASK_BELOW = 0.5;
+
+export type SizeDecision =
+  | { readonly kind: "decided"; readonly size: Sizing; readonly basis: string }
+  | { readonly kind: "ask"; readonly proposed: Sizing; readonly basis: string };
+
+/**
+ * Pure: who sizes the work. A size given up front (the caller, e.g. a goal's planning, already
+ * decided) wins; otherwise Jev decides when it is confident enough; only a doubtful or missing
+ * judgement asks the human, with Jev's size (or `change`) as the proposal.
+ */
+export function decideSize(
+  given: Sizing | undefined,
+  judged: { readonly sizing: Sizing; readonly confidence: number } | undefined,
+  unavailable: string,
+): SizeDecision {
+  if (given !== undefined) {
+    return { kind: "decided", size: given, basis: `Size given up front: ${given}.` };
+  }
+  if (judged === undefined) {
+    return {
+      kind: "ask",
+      proposed: "change",
+      basis: `Jev unavailable (${unavailable}); defaulted to change.`,
+    };
+  }
+  const said = `Jev judged ${judged.sizing} (confidence ${judged.confidence.toFixed(2)})`;
+  return judged.confidence >= ASK_BELOW
+    ? { kind: "decided", size: judged.sizing, basis: `${said}; proceeding without asking.` }
+    : { kind: "ask", proposed: judged.sizing, basis: `${said}, too unsure to proceed alone.` };
+}

package/src/review/review-tools.ts

@@ -30,11 +30,14 @@ 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";
+import type { SubmissionStore } from "./submissions.ts";
 
 export type ReviewToolDeps = {
   state: SessionState;
   jev: (ctx: ExtensionContext) => Jev;
   exec: Exec;
+  /** Results reviewers submitted with `devsys_submit_review`, read by `devsys_review_record`. */
+  submissions: SubmissionStore;
   now?: () => Date;
 };
 
@@ -55,6 +58,9 @@ const sliceOf = (given: string | undefined, state: SessionState): SliceRef | und
 const NO_SLICE =
   "no slice: pass `slice`, or start work on a slice first (there is no active slice)";
 
+const NO_RESULT = (slice: string, round: number): string =>
+  `no result for round ${round} of "${slice}": the reviewer submits it with devsys_submit_review before you record, or you pass its packet markdown in \`packets\``;
+
 const StartParameters = Type.Object({
   slice: Type.Optional(
     Type.String({ description: "Slice being reviewed; defaults to the active slice." }),
@@ -120,6 +126,7 @@ function spawnPayload(input: {
 }
 
 type Reply = ReturnType<typeof reply>;
+const replyText = (r: Reply): string => r.content.map((c) => c.text).join("\n");
 type Config = Extract<Awaited<ReturnType<typeof loadConfig>>, { ok: true }>["value"];
 type Snapshot = Extract<Awaited<ReturnType<typeof snapshotDiff>>, { ok: true }>["value"];
 type Prepared = { slice: SliceRef; config: Config; range: string; snap: Snapshot };
@@ -181,6 +188,8 @@ async function startRound(
   const required = requiredRounds(p.config);
   const existing = reviewOf(deps.state.get(), p.slice) ?? startReview(p.slice, required);
   const review: ReviewState = { ...existing, required };
+  // A new round only sees what reviewers submit after it began.
+  deps.submissions.clear(p.slice);
   deps.state.update((s) => upsertReview(s, review));
   deps.state.update((s) => afterReviewRound(s, nextAction(review, p.snap.digest), p.slice));
   const refusal = startRefusal(review, p);
@@ -200,7 +209,7 @@ async function startRound(
     [
       `${reviewLabel(review)}; round ${round}; diff ${p.snap.digest}. ${basis}`,
       `lenses: ${lenses.join(", ")}`,
-      `Spawn the reviewer with agent_spawn using exactly this payload, then pass its packet to devsys_review_record with slice "${p.slice}", diffDigest "${p.snap.digest}"${rangeArg}:`,
+      `Spawn the reviewer with agent_spawn using exactly this payload, then call devsys_review_record with slice "${p.slice}", diffDigest "${p.snap.digest}"${rangeArg}. The reviewer submits its result with devsys_submit_review, so pass no packets (only a markdown packet the reviewer returned instead goes in packets):`,
       JSON.stringify(spawn),
     ].join("\n"),
   );
@@ -214,7 +223,7 @@ export function createReviewStartTool(
     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.",
+      "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 call devsys_review_record (the reviewer submits its result with devsys_submit_review).",
     promptSnippet: "Start a fresh-context review round for a slice",
     parameters: StartParameters,
     exposure: "model-only",
@@ -243,9 +252,12 @@ 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.",
-  }),
+  packets: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Reviewer packets, verbatim markdown, for a reviewer that could not call devsys_submit_review. Results submitted through that tool for this round are read without being passed.",
+    }),
+  ),
   diffRange: Type.Optional(
     Type.String({ description: "The range that was reviewed; defaults to HEAD." }),
   ),
@@ -275,15 +287,22 @@ async function adjusted(
   return { findings: out, notes };
 }
 
+const lensKey = (p: ReviewPacket): string => [...p.lenses].sort().join("\u0000");
+
+/** Submitted results win over a markdown packet for the same lenses (a reviewer that did both). */
+function mergeResults(
+  markdown: readonly ReviewPacket[],
+  submitted: readonly ReviewPacket[],
+): { packets: ReviewPacket[]; dropped: number } {
+  const taken = new Set(submitted.map(lensKey));
+  const kept = markdown.filter((m) => !taken.has(lensKey(m)));
+  return { packets: [...kept, ...submitted], dropped: markdown.length - kept.length };
+}
+
 /** Parses every packet, or the reply naming the first malformed one. */
 function parsePackets(
   raw: readonly string[],
 ): { ok: true; value: ReviewPacket[] } | { ok: false; reply: Reply } {
-  if (raw.length === 0)
-    return {
-      ok: false,
-      reply: reply("no packets: pass the reviewer's packet markdown in `packets`", true),
-    };
   const packets: ReviewPacket[] = [];
   for (const [i, text] of raw.entries()) {
     const parsed = parseReviewPacket(text);
@@ -359,7 +378,7 @@ export function createReviewRecordTool(
     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, and returns the clean-round count and the next action.",
+      "Record one review round from the reviewer's submitted result (or markdown packets): reads findings, lets Jev adjust severity when confident, and returns the clean-round count and the next action.",
     promptSnippet: "Record a reviewer packet as a review round",
     parameters: RecordParameters,
     exposure: "direct",
@@ -370,9 +389,23 @@ export function createReviewRecordTool(
       _onUpdate,
       ctx: ExtensionContext,
     ) {
-      if (sliceOf(params.slice, deps.state) === undefined) return reply(NO_SLICE, true);
-      const packets = parsePackets(params.packets);
-      if (!packets.ok) return packets.reply;
+      const slice = sliceOf(params.slice, deps.state);
+      if (slice === undefined) return reply(NO_SLICE, true);
+      const round = (reviewOf(deps.state.get(), slice)?.rounds.length ?? 0) + 1;
+      const markdown = parsePackets(params.packets ?? []);
+      if (!markdown.ok) {
+        return deps.submissions.forRound(slice, round).length === 0
+          ? markdown.reply
+          : reply(
+              `${replyText(markdown.reply)}. A submitted result for round ${round} is waiting: omit \`packets\` to record it.`,
+              true,
+            );
+      }
+      const { packets, dropped } = mergeResults(
+        markdown.value,
+        deps.submissions.forRound(slice, round),
+      );
+      if (packets.length === 0) return reply(NO_RESULT(slice, round), true);
       const prepared = await prepare(
         deps,
         ctx,
@@ -386,7 +419,14 @@ export function createReviewRecordTool(
           true,
         );
       }
-      return recordRound(deps, ctx, prepared.value, packets.value);
+      const recorded = await recordRound(deps, ctx, prepared.value, packets);
+      if (recorded.isError === true) return recorded;
+      deps.submissions.clear(slice);
+      return dropped === 0
+        ? recorded
+        : reply(
+            `${replyText(recorded)}\nNote: ${dropped} markdown packet(s) for lenses already submitted were dropped; the submitted result is the one recorded.`,
+          );
     },
   };
 }

package/src/review/submissions.ts

@@ -0,0 +1,38 @@
+import type { ReviewPacket } from "../core/review-packet.ts";
+
+/** Reviewer results submitted through `devsys_submit_review`, waiting for `devsys_review_record`. */
+export type SubmissionStore = {
+  /**
+   * Keep a packet. One for the same slice and round that shares a lens replaces the earlier one
+   * (a corrected resubmission); packets for disjoint lenses (parallel lens reviewers) are all kept.
+   */
+  put(packet: ReviewPacket): void;
+  forRound(slice: string, round: number): ReviewPacket[];
+  /** Drop every packet of a slice, when a new round starts or one is recorded. */
+  clear(slice: string): void;
+};
+
+const sameRound = (a: ReviewPacket, b: ReviewPacket): boolean =>
+  a.slice === b.slice && a.round === b.round;
+
+const sharesLens = (a: ReviewPacket, b: ReviewPacket): boolean =>
+  a.lenses.some((lens) => b.lenses.includes(lens));
+
+/** In memory on purpose (ADR 0006): a round takes minutes and a lost submission is visible. */
+export function createSubmissionStore(): SubmissionStore {
+  let packets: ReviewPacket[] = [];
+  return {
+    put(packet) {
+      packets = [
+        ...packets.filter((p) => !(sameRound(p, packet) && sharesLens(p, packet))),
+        packet,
+      ];
+    },
+    forRound(slice, round) {
+      return packets.filter((p) => p.slice === slice && p.round === round);
+    },
+    clear(slice) {
+      packets = packets.filter((p) => p.slice !== slice);
+    },
+  };
+}

package/src/review/submit-tool.ts

@@ -0,0 +1,85 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { SEVERITIES } from "../core/review.ts";
+import { reviewOf } from "../core/review-flow.ts";
+import { packetFromSubmission } from "../core/review-submission.ts";
+import type { SliceRef } from "../core/types.ts";
+import type { SessionState } from "../state/session-state.ts";
+import type { SubmissionStore } from "./submissions.ts";
+
+export const SubmitParameters = Type.Object({
+  slice: Type.String({ description: "The slice you were asked to review, exactly as given." }),
+  round: Type.Integer({ minimum: 1, description: "The round number you were asked to review." }),
+  lenses: Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 1,
+    description: "Every lens you reviewed through.",
+  }),
+  sources: Type.Array(Type.String(), {
+    description: "What you inspected (path:line ranges), and what you checked and refuted.",
+  }),
+  findings: Type.Array(
+    Type.Object({
+      lens: Type.String({ minLength: 1, description: "One of `lenses`." }),
+      severity: Type.Union(SEVERITIES.map((s) => Type.Literal(s))),
+      path: Type.Optional(Type.String({ description: "File the finding is about." })),
+      line: Type.Optional(Type.Integer({ minimum: 1 })),
+      summary: Type.String({
+        minLength: 1,
+        description: "One sentence: the defect, why it matters, and the smallest repair.",
+      }),
+    }),
+    { description: "Empty when there is nothing to report." },
+  ),
+  verdict: Type.Union([Type.Literal("no-blocking"), Type.Literal("blocking")], {
+    description: "`blocking` when any finding is blocking or should-fix, otherwise `no-blocking`.",
+  }),
+});
+
+export type SubmitDeps = { state: SessionState; submissions: SubmissionStore };
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+function submit(deps: SubmitDeps, params: Static<typeof SubmitParameters>) {
+  const state = deps.state.get();
+  const slice = params.slice as SliceRef;
+  const review = reviewOf(state, slice);
+  if (review === undefined && state.activeSlice !== slice) {
+    return reply(
+      `unknown-slice: "${params.slice}" is neither the active slice nor under review; use the slice name exactly as given in your task`,
+      true,
+    );
+  }
+  const expected = (review?.rounds.length ?? 0) + 1;
+  if (params.round !== expected) {
+    return reply(
+      `wrong-round: this is for round ${params.round}, but round ${expected} of "${params.slice}" is the one being reviewed; use the round number from your task`,
+      true,
+    );
+  }
+  const packet = packetFromSubmission(params);
+  if ("id" in packet) return reply(`${packet.id}: ${packet.message}`, true);
+  deps.submissions.put(packet);
+  return reply(
+    `submitted: ${params.slice} round ${params.round}, lenses ${params.lenses.join(", ")}, verdict ${params.verdict}, ${params.findings.length} finding(s). End with one short line.`,
+  );
+}
+
+/** `devsys_submit_review`: a reviewer hands over its packet as validated arguments (ADR 0006). */
+export function createSubmitReviewTool(deps: SubmitDeps): ToolDefinition<typeof SubmitParameters> {
+  return {
+    name: "devsys_submit_review",
+    label: "Submit review result",
+    description:
+      "For reviewer subagents only: submit your review result as structured arguments. A result that contradicts itself or is for another round is refused with an error id; fix it and submit again. Then end with one short line.",
+    promptSnippet: "Submit a review result (reviewer subagents)",
+    parameters: SubmitParameters,
+    exposure: "direct",
+    execute(_id, params: Static<typeof SubmitParameters>) {
+      return Promise.resolve(submit(deps, params));
+    },
+  };
+}