@jwilger/pi-development-system 0.18.0 → 0.20.0

package/package.json

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

package/skills/code-review/SKILL.md

@@ -12,12 +12,14 @@ Review is a soft gate (`review.unsatisfied`): skipping it needs a recorded depar
 ## 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.
+   to `HEAD`: everything uncommitted, untracked files included). It computes the
+   diff digest, lets Jev choose lenses, and returns an exact `agent_spawn` payload.
 2. Run that `agent_spawn` unchanged. The reviewer is a top-level agent, not a
    child of this conversation, so it does not inherit your context.
-3. Pass the reviewer's packet, verbatim, to `devsys_review_record`
-   (`packets: [...]`; one packet per lens reviewer if you split them).
+3. Pass the reviewer's packet, verbatim, to `devsys_review_record` with the
+   `diffDigest` the start reply gave (`packets: [...]`; all lens packets of one
+   round in one call). A packet is recorded once, in the round its header names;
+   if the diff changed since the start, the round is refused: start again.
 4. Read the reply: `review: N/R clean` and `next:`.
    - `fix-findings`: fix every blocking and should-fix finding, then start a new round.
    - `review`: the streak is short (or the diff changed with findings); start another round.
@@ -47,8 +49,9 @@ The verdict must agree with the findings.
   `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.
+Jev may raise a finding's severity when it is at least 0.8 confident; it never
+lowers a blocking or should-fix finding (it only suggests, in the reply, and you
+re-check it yourself). A round is clean when it has no blocking or should-fix findings.
 The default is three consecutive clean rounds (`review.required_clean_rounds`).
 Only real findings reset the count; a changed diff alone does not, so a small fix
 commit keeps the clean rounds already earned unless findings come back.

package/src/core/review-flow.ts

@@ -25,27 +25,59 @@ export const reviewLabel = (review: ReviewState): string =>
  * 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 {
+export type DiffNow = {
+  readonly digest: string;
+  readonly files?: Readonly<Record<string, string>>;
+};
+
+/** Every file in the current diff was in the last round's diff, byte for byte: a part of what was reviewed. */
+const coveredByLastRound = (review: ReviewState, now: DiffNow): boolean => {
+  const reviewed = review.rounds.at(-1)?.files;
+  if (reviewed === undefined || now.files === undefined) return false;
+  return Object.entries(now.files).every(([path, digest]) => reviewed[path] === digest);
+};
+
+export function reviewGap(state: DevsysState, slice: SliceRef, now: DiffNow): string | undefined {
   const review = reviewOf(state, slice);
   if (review === undefined || review.rounds.length === 0) {
     return `no review has been recorded for slice ${slice}`;
   }
-  switch (nextAction(review, digestNow)) {
+  switch (nextAction(review, now.digest)) {
     case "done":
       return undefined;
     case "fix-findings":
       return `the last review round of slice ${slice} has blocking or should-fix findings still to fix`;
     case "stale-diff":
+      // Committing a reviewed change in parts leaves a smaller diff made only of reviewed files.
+      if (coveredByLastRound(review, now)) return undefined;
       return `the diff has changed since slice ${slice} was last reviewed; review it again`;
     case "review":
       return `slice ${slice} has ${cleanStreak(review)}/${review.required} clean review rounds`;
   }
 }
 
+/** A unified diff cut into one text per file, keyed by the file's new path. */
+export function splitDiffByFile(diff: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  let path: string | undefined;
+  let lines: string[] = [];
+  const flush = () => {
+    if (path !== undefined) out[path] = lines.join("\n");
+  };
+  for (const line of diff.split("\n")) {
+    // Git quotes unusual paths ("b/na\303\257ve.md"); strip the quotes rather than lose the section.
+    const header = /^diff --git "?a\/.*?"? "?b\/(.*?)"?$/.exec(line);
+    if (header !== null) {
+      flush();
+      path = header[1] ?? line;
+      lines = [];
+    }
+    lines.push(line);
+  }
+  flush();
+  return out;
+}
+
 /** Packets from several lens reviewers in one round become one round of findings. */
 export function combinePackets(packets: readonly ReviewPacket[]): {
   lenses: string[];
@@ -61,7 +93,14 @@ export function combinePackets(packets: readonly ReviewPacket[]): {
 /** 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. */
+const counts = (severity: Severity): boolean =>
+  severity === "blocking" || severity === "should-fix";
+
+/**
+ * Take Jev's severity only when it is confident and different, and never to lower a finding that
+ * counts (blocking/should-fix) to one that does not: Jev reads a clipped diff, the reviewer read
+ * the code. That disagreement is reported as a suggestion and the reviewer's severity stands.
+ */
 export function adoptSeverity(
   finding: Finding,
   judged: { severity: Severity; confidence: number } | undefined,
@@ -73,9 +112,16 @@ export function adoptSeverity(
   ) {
     return { finding };
   }
+  const confidence = judged.confidence.toFixed(2);
+  if (counts(finding.severity) && !counts(judged.severity)) {
+    return {
+      finding,
+      note: `${finding.id}: Jev suggests ${judged.severity} instead of ${finding.severity} (confidence ${confidence}); the reviewer's severity stands, re-check the finding yourself`,
+    };
+  }
   return {
     finding: { ...finding, severity: judged.severity },
-    note: `${finding.id}: Jev moved severity ${finding.severity} → ${judged.severity} (confidence ${judged.confidence.toFixed(2)})`,
+    note: `${finding.id}: Jev moved severity ${finding.severity} → ${judged.severity} (confidence ${confidence})`,
   };
 }
 
@@ -104,9 +150,9 @@ export function reviewerTask(input: {
   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.`,
+    `See the change with \`git diff ${input.diffRange}\` (and \`git diff --stat ${input.diffRange}\`), plus any untracked files listed by \`git status --short\` (git diff does not show them; read them directly). Read the callers, callees and tests it depends on, no more.`,
     "Do not modify files; report demonstrable defects with a realistic trigger and the smallest local repair.",
-    "Return exactly the review packet from your instructions:",
+    "Return exactly the review packet from your instructions, with exactly this header (slice and round must not change):",
     "",
     `## Review — ${input.slice} — round ${input.round} — lenses: ${lenses}`,
     "### Sources inspected",

package/src/core/review.ts

@@ -21,6 +21,8 @@ export type ReviewRound = {
   readonly reviewedAt: string;
   /** Digest of the diff the round reviewed (see `digestOf` in src/review/digest.ts). */
   readonly diffDigest: string;
+  /** Per-file digests of the reviewed diff, so a commit of part of it is still covered. */
+  readonly files?: Readonly<Record<string, string>>;
 };
 
 export type ReviewState = {
@@ -118,6 +120,17 @@ function parseFinding(input: unknown): Finding | ParseError {
   };
 }
 
+function parseFiles(input: unknown): Record<string, string> | undefined | null {
+  if (input === undefined) return undefined;
+  if (!isRecord(input)) return null;
+  const out: Record<string, string> = {};
+  for (const [path, digest] of Object.entries(input)) {
+    if (typeof digest !== "string") return null;
+    out[path] = digest;
+  }
+  return out;
+}
+
 function parseRound(input: unknown): ReviewRound | ParseError {
   if (!isRecord(input)) return parseError("round must be an object");
   const { n, lenses, findings, reviewedAt, diffDigest } = input;
@@ -134,7 +147,16 @@ function parseRound(input: unknown): ReviewRound | ParseError {
     if ("kind" in finding) return finding;
     parsed.push(finding);
   }
-  return { n, lenses: lenses as string[], findings: parsed, reviewedAt, diffDigest };
+  const files = parseFiles(input.files);
+  if (files === null) return parseError("round files must map paths to digest strings");
+  return {
+    n,
+    lenses: lenses as string[],
+    findings: parsed,
+    reviewedAt,
+    diffDigest,
+    ...(files === undefined ? {} : { files }),
+  };
 }
 
 /** Boundary parse for a persisted review (one slice's rounds). */

package/src/gates/commit-guard.ts

@@ -124,7 +124,11 @@ async function reviewNeeds(deps: CommitGuardDeps, ctx: ExtensionContext): Promis
   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");
+  const gap = reviewGap(
+    deps.state.get(),
+    activeSlice,
+    snap.ok ? { digest: snap.value.digest, files: snap.value.files } : { digest: "unknown" },
+  );
   return gap === undefined ? [] : [{ gate: REVIEW, why: gap }];
 }
 

package/src/review/digest.ts

@@ -1,31 +1,93 @@
 import { createHash } from "node:crypto";
 import type { Exec } from "../core/exec.ts";
 import { err, ok, type Result } from "../core/result.ts";
+import { splitDiffByFile } from "../core/review-flow.ts";
 
-/** A short, stable identity for a diff's text. Pure. */
-export const digestOf = (diff: string): string =>
-  createHash("sha256").update(diff).digest("hex").slice(0, 16);
+/** A short, stable identity for some text. Pure. */
+export const digestOf = (text: string): string =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
 
-export type DiffSnapshot = { digest: string; stat: string; sample: string };
+export type DiffSnapshot = {
+  /** Identity of everything reviewed: the tracked diff plus the content of untracked files. */
+  digest: string;
+  /** Per-file digests, tracked and untracked, keyed by path. */
+  files: Record<string, string>;
+  stat: string;
+  sample: string;
+};
 
-/** The diff for `range` (default: everything not yet committed, `HEAD`), with its digest. */
+const MAX_UNTRACKED = 200;
+
+/**
+ * The change in `range` (default `HEAD`: everything not yet committed) with its digest. `git diff`
+ * leaves out untracked files, so for a range that includes the work tree they are listed and
+ * content-hashed too; otherwise a new file would be committed unreviewed.
+ */
 export async function snapshotDiff(
   exec: Exec,
   cwd: string,
   range: string,
 ): Promise<Result<DiffSnapshot, string>> {
   try {
-    const [diff, stat] = await Promise.all([
-      exec("git", ["diff", range], { cwd, timeout: 15_000 }),
-      exec("git", ["diff", "--stat", range], { cwd, timeout: 15_000 }),
+    // Plain, parseable output whatever the user's git config says: an external diff driver or
+    // forced colour removes the `diff --git` headers the per-file digests are cut from.
+    const plain = ["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-color"];
+    const [diff, stat, others] = await Promise.all([
+      exec("git", [...plain, "--full-index", "--no-renames", range], { cwd, timeout: 15_000 }),
+      exec("git", [...plain, "--stat", range], { cwd, timeout: 15_000 }),
+      range === "HEAD"
+        ? exec("git", ["ls-files", "--others", "--exclude-standard"], { cwd, timeout: 15_000 })
+        : Promise.resolve({ code: 0, stdout: "", stderr: "" }),
     ]);
     if (diff.code !== 0) return err(diff.stderr.trim() || `git diff ${range} failed`);
+    if (others.code !== 0) return err(others.stderr.trim() || "git ls-files --others failed");
+    const listed = others.stdout.split("\n").filter((p) => p !== "");
+    // A nested repository is listed as `dir/` and has no blob to hash.
+    const nested = listed.filter((p) => p.endsWith("/"));
+    const untracked = listed.filter((p) => !p.endsWith("/"));
+    if (untracked.length > MAX_UNTRACKED) {
+      return err(
+        `${untracked.length} untracked files (more than ${MAX_UNTRACKED}); commit or ignore some so they can be reviewed`,
+      );
+    }
+    const files: Record<string, string> = {};
+    for (const [path, text] of Object.entries(splitDiffByFile(diff.stdout))) {
+      files[path] = fileDigest(text);
+    }
+    if (diff.stdout.trim() !== "" && Object.keys(files).length === 0) {
+      return err("could not read the diff: no per-file sections were found");
+    }
+    if (untracked.length > 0) {
+      const hashes = await exec("git", ["hash-object", "--", ...untracked], {
+        cwd,
+        timeout: 15_000,
+      });
+      const lines = hashes.stdout.split("\n").filter((l) => l !== "");
+      if (hashes.code !== 0 || lines.length !== untracked.length) {
+        return err(hashes.stderr.trim() || "git hash-object could not hash every untracked file");
+      }
+      for (const [i, path] of untracked.entries()) files[path] = `new:${lines[i]}`;
+    }
+    const names = Object.keys(files).sort();
+    const untrackedStat = [
+      ...untracked.map((p) => ` ${p} (untracked)`),
+      ...nested.map((p) => ` ${p} (nested repository, not reviewable)`),
+    ].join("\n");
     return ok({
-      digest: digestOf(diff.stdout),
-      stat: stat.stdout,
+      digest: digestOf(names.map((p) => `${p}\0${files[p]}`).join("\n")),
+      files,
+      stat: [stat.stdout.trimEnd(), untrackedStat].filter((p) => p !== "").join("\n"),
       sample: diff.stdout.slice(0, 16_000),
     });
   } catch (cause) {
     return err(cause instanceof Error ? cause.message : String(cause));
   }
 }
+
+const NEW_FILE = /^new file mode .*\nindex 0+\.\.([0-9a-f]+)/m;
+
+/** A new file digests as its blob, the same form an untracked file gets, so `git add` changes nothing. */
+const fileDigest = (section: string): string => {
+  const blob = NEW_FILE.exec(section)?.[1];
+  return blob === undefined ? digestOf(section) : `new:${blob}`;
+};

package/src/review/review-tools.ts

@@ -63,7 +63,13 @@ const StartParameters = Type.Object({
   ),
 });
 
-const pathSafe = (slice: string): string => slice.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+/** One path segment is at most 64 chars (src/subagents/orch/paths.ts); keep room for round and attempt. */
+const pathSafe = (slice: string): string =>
+  slice
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
 
 /** `devsys_review_start`: Jev picks lenses for the diff; the reply carries the agent_spawn payload for a fresh reviewer. */
 export function createReviewStartTool(
@@ -128,7 +134,8 @@ export function createReviewStartTool(
         availableModels(ctx.modelRegistry),
       );
       const spawn = {
-        path: `/review-${pathSafe(slice)}-r${round}`,
+        // A fresh path per attempt: a failed spawn must not leave a thread that blocks the retry.
+        path: `/review-${pathSafe(slice)}-r${round}-${(deps.now?.() ?? new Date()).getTime().toString(36)}`,
         type: "reviewer",
         task: reviewerTask({ slice, round, lenses, diffRange: range }),
         ...(resolved.ok ? { model: resolved.value.model } : {}),
@@ -139,7 +146,7 @@ export function createReviewStartTool(
         [
           `${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:",
+          `Spawn the reviewer with agent_spawn using exactly this payload, then pass its packet to devsys_review_record with diffDigest "${snap.value.digest}":`,
           JSON.stringify(spawn),
         ].join("\n"),
       );
@@ -157,6 +164,10 @@ const RecordParameters = Type.Object({
   diffRange: Type.Optional(
     Type.String({ description: "The range that was reviewed; defaults to HEAD." }),
   ),
+  diffDigest: Type.String({
+    description:
+      "The diff digest devsys_review_start reported for this round; the round is refused if the diff has changed since.",
+  }),
 });
 
 async function adjusted(
@@ -214,30 +225,60 @@ export function createReviewRecordTool(
       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);
+      if (params.diffDigest !== snap.value.digest) {
+        return reply(
+          `the diff changed since the review started (reviewed ${params.diffDigest}, now ${snap.value.digest}); the reviewer did not see the current code. Run devsys_review_start again.`,
+          true,
+        );
+      }
       const required = Math.max(
         config.value.review.requiredCleanRounds,
         config.value.review.minRounds,
       );
       const before = reviewOf(deps.state.get(), slice) ?? startReview(slice, required);
+      const expected = before.rounds.length + 1;
+      const wrong = packets.findIndex((p) => p.round !== expected || p.slice !== slice);
+      if (wrong !== -1) {
+        return reply(
+          `packet ${wrong + 1} is for slice "${packets[wrong]?.slice}" round ${packets[wrong]?.round}; this is round ${expected} of slice "${slice}". A packet is recorded once, in the round it was written for; ask the reviewer for a packet with the right header.`,
+          true,
+        );
+      }
+
+      const merged = combinePackets(packets);
+      const { findings, notes } = await adjusted(deps, ctx, merged.findings, snap.value.sample);
+      // File the nits first: if this fails nothing is recorded and a retry cannot count the round twice.
+      const followups = renderFollowups(slice, expected, findings);
+      let reviewed = snap.value;
+      if (followups !== undefined) {
+        try {
+          const dir = join(ctx.cwd, "docs", "decisions");
+          await mkdir(dir, { recursive: true });
+          await appendFile(join(dir, "followups.md"), followups);
+        } catch (cause) {
+          return reply(
+            `could not write docs/decisions/followups.md (${cause instanceof Error ? cause.message : String(cause)}); the round was not recorded, retry`,
+            true,
+          );
+        }
+        // The file is part of the work tree, so writing it changed the diff. The round covers the
+        // reviewed code plus its own follow-up note; otherwise `done` would be stale on arrival.
+        const after = await snapshotDiff(deps.exec, ctx.cwd, params.diffRange?.trim() || "HEAD");
+        if (!after.ok)
+          return reply(`cannot read the diff after filing follow-ups: ${after.error}`, true);
+        reviewed = after.value;
+      }
       const review = addRound(
         { ...before, required },
         {
           lenses: merged.lenses,
           findings,
           reviewedAt: (deps.now?.() ?? new Date()).toISOString(),
-          diffDigest: snap.value.digest,
+          diffDigest: reviewed.digest,
+          files: reviewed.files,
         },
       );
       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(
@@ -245,7 +286,7 @@ export function createReviewRecordTool(
           `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)}`,
+          `next: ${nextAction(review, reviewed.digest)}`,
         ].join("\n"),
       );
     },