@jwilger/pi-development-system 0.87.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.

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.87.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-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/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/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/core/review-flow.ts

@@ -176,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/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));
+    },
+  };
+}