@jwilger/pi-development-system 0.83.0 → 0.85.0

package/src/review/lens-review-tool.ts

@@ -0,0 +1,205 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { resolveSlot } from "../core/models.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeProductLenses } from "../jev/questions/product-lenses.ts";
+import {
+  judgeSolutionDetail,
+  SOLUTION_DETAIL_THRESHOLD,
+} from "../jev/questions/solution-detail.ts";
+import { lintBrief } from "../planning/brief-lint.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 {
+  lensPayloads,
+  lensReviewScript,
+  PRODUCT_LENSES,
+  type ProductLens,
+  type ReviewRound,
+  reviewPath,
+  selectProductLenses,
+  synthesisTemplate,
+} from "./lens-review.ts";
+
+export type LensReviewDeps = {
+  state: SessionState;
+  jev: (ctx: ExtensionContext) => Jev;
+  now: () => Date;
+};
+
+const DEFAULT_BRIEF = "docs/product/brief.md";
+
+const Parameters = Type.Object({
+  brief: Type.Optional(
+    Type.String({ description: `Path of the brief to review; defaults to ${DEFAULT_BRIEF}.` }),
+  ),
+  round: Type.Optional(
+    Type.Number({
+      description: "1 = independent review (default); 2 = peer exchange after round 1 was written.",
+    }),
+  ),
+});
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+type Choice = { lenses: readonly ProductLens[]; basis: string };
+
+/** All five for a `product`; for anything else Jev picks, and an offline or empty answer means all five. */
+async function chooseLenses(
+  deps: LensReviewDeps,
+  ctx: ExtensionContext,
+  brief: string,
+): Promise<Choice> {
+  if (deps.state.get().sizing === "product") {
+    return { lenses: PRODUCT_LENSES, basis: "sizing is product: all five lenses." };
+  }
+  const judged = await judgeProductLenses(deps.jev(ctx), { brief });
+  if (!judged.ok) {
+    return {
+      lenses: PRODUCT_LENSES,
+      basis: `Jev unavailable (${judged.error.kind}); using all five lenses.`,
+    };
+  }
+  const picked = selectProductLenses(judged.value);
+  return picked.length === 0
+    ? { lenses: PRODUCT_LENSES, basis: "Jev found no specific lens; using all five lenses." }
+    : { lenses: picked, basis: "Jev chose the lenses for this brief." };
+}
+
+/** Warnings about solution-level detail in the brief: regex markers plus, when none match, Jev's read. Never an error. */
+async function briefLint(
+  deps: LensReviewDeps,
+  ctx: ExtensionContext,
+  brief: string,
+): Promise<string[]> {
+  const found = lintBrief(brief);
+  if (found.length > 0) {
+    return found.map((f) => `- line ${f.line}: \`${f.match}\` (${f.kind}) — ${f.message}`);
+  }
+  const judged = await judgeSolutionDetail(deps.jev(ctx), { brief });
+  return judged.ok && judged.value >= SOLUTION_DETAIL_THRESHOLD
+    ? [
+        "- the brief prescribes the solution (tables, endpoints, classes or libraries) rather than the outcome; record that in an ADR (devsys_adr_new) or the architecture notes",
+      ]
+    : [];
+}
+
+/** The date of the newest `docs/product/reviews/<date>-round1.md`, if any. */
+function latestRound1Date(cwd: string): string | undefined {
+  try {
+    return readdirSync(join(cwd, "docs/product/reviews"))
+      .flatMap((name) => /^(\d{4}-\d{2}-\d{2})-round1\.md$/.exec(name)?.[1] ?? [])
+      .sort()
+      .pop();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The lenses that wrote round 1, from its `## <lens> — round 1` headings; empty when none parse. */
+function round1Lenses(cwd: string, date: string): ProductLens[] {
+  try {
+    const body = readFileSync(join(cwd, reviewPath(date, 1)), "utf8");
+    return PRODUCT_LENSES.filter((lens) => `\n${body}`.includes(`\n## ${lens} — round 1`));
+  } catch {
+    return [];
+  }
+}
+
+const parseRound = (given: number | undefined): ReviewRound | undefined => {
+  const round = given ?? 1;
+  return round === 1 || round === 2 ? round : undefined;
+};
+
+/**
+ * `devsys_lens_review`: the plan for a product-lens review round. Returns a codemode script as the
+ * primary form (the packets go to a file, not into the coordinator's context) and the fresh
+ * `agent_spawn` payloads as the fallback.
+ */
+export function createLensReviewTool(deps: LensReviewDeps): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_lens_review",
+    label: "Lens review",
+    description:
+      "Plan a product-lens review of a brief: the five Cagan/Torres/Pichler/Perri/Rumelt lens agents, as a codemode script that writes their packets to docs/product/reviews/<date>-round<n>.md and returns only verdict lines, plus the agent_spawn payloads as a fallback. Round 2 is the peer exchange.",
+    promptSnippet: "Plan a product-lens review of the brief",
+    parameters: Parameters,
+    async execute(
+      _id,
+      params: Static<typeof Parameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      const round = parseRound(params.round);
+      if (round === undefined) {
+        return reply("round must be 1 (independent) or 2 (peer exchange)", true);
+      }
+      const briefPath = params.brief?.trim() || DEFAULT_BRIEF;
+      let brief: string;
+      try {
+        brief = await readFile(resolve(ctx.cwd, briefPath), "utf8");
+      } catch {
+        return reply(
+          `cannot read the brief at ${briefPath}; write it first (product-planning skill)`,
+          true,
+        );
+      }
+      const today = deps.now().toISOString().slice(0, 10);
+      // Round 2 pairs with the newest round 1 on disk, which may be from an earlier day.
+      const date = round === 2 ? latestRound1Date(ctx.cwd) : today;
+      if (date === undefined) {
+        return reply(
+          "round 2 reads a round1 review (docs/product/reviews/<date>-round1.md), and none exists yet; run round 1 first",
+          true,
+        );
+      }
+      const config = await loadConfig(ctx.cwd);
+      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
+      const resolved = resolveSlot(config.value.models, "lens", availableModels(ctx.modelRegistry));
+      const earlier = round === 2 ? round1Lenses(ctx.cwd, date) : [];
+      // Both ask Jev; run them together so a hung provider costs one timeout, not two.
+      const [{ lenses, basis }, lint] = await Promise.all([
+        earlier.length > 0
+          ? { lenses: earlier, basis: "round 2 asks the lenses that wrote round 1." }
+          : chooseLenses(deps, ctx, brief),
+        briefLint(deps, ctx, brief),
+      ]);
+      const payloads = lensPayloads({
+        lenses,
+        briefPath,
+        round,
+        date,
+        suffix: deps.now().getTime().toString(36),
+        model: resolved.ok ? resolved.value.model : undefined,
+      });
+      const file = reviewPath(date, round);
+      const script = lensReviewScript({ payloads, file, round });
+      return reply(
+        [
+          `Lens review, round ${round}, of ${briefPath}. ${basis}`,
+          `lenses: ${lenses.join(", ")}; packets go to ${file}`,
+          ...(lint.length > 0 ? ["Brief lint (warnings; the review still runs):", ...lint] : []),
+          "Run this with the codemode tool, unchanged. It spawns the lens agents, waits, writes the packets and returns only a verdict per lens and the path:",
+          "```js",
+          script,
+          "```",
+          `Fallback if codemode is unavailable: call agent_spawn once per payload below (all with wait:false), agent_wait on each, and write the packets to the file yourself, each under a heading '## <lens> — round ${round}' (round 2 reads those headings to find who wrote round 1).`,
+          JSON.stringify(payloads),
+          round === 1
+            ? "After round 2, write the synthesis with this template:"
+            : `Then write ${reviewPath(date, "synthesis")} with this template:`,
+          synthesisTemplate(date),
+        ].join("\n"),
+      );
+    },
+  };
+}

package/src/review/lens-review.ts

@@ -0,0 +1,168 @@
+/**
+ * Product-lens review (plan I9.3): five fresh lens agents read the brief independently (round 1),
+ * then answer each other (round 2), and the coordinator synthesises. This module is pure: it builds
+ * the prompts, the `agent_spawn` payloads and the codemode script; the tool in
+ * `lens-review-tool.ts` supplies the date, models and lens choice.
+ */
+
+export const PRODUCT_LENSES = ["cagan", "torres", "pichler", "perri", "rumelt"] as const;
+export type ProductLens = (typeof PRODUCT_LENSES)[number];
+
+/** A lens applies at or above this probability (same cut-off as the code-review lenses). */
+const PRODUCT_LENS_THRESHOLD = 0.5;
+
+export const GUARDRAIL =
+  "Agreement among agents is useful critique, not customer evidence. A finding that rests on opinion rather than data says so.";
+
+export type ReviewRound = 1 | 2;
+
+export const reviewPath = (date: string, kind: ReviewRound | "synthesis"): string =>
+  `docs/product/reviews/${date}-${kind === "synthesis" ? "synthesis" : `round${kind}`}.md`;
+
+export const selectProductLenses = (
+  probabilities: Readonly<Record<ProductLens, number>>,
+): ProductLens[] => PRODUCT_LENSES.filter((lens) => probabilities[lens] >= PRODUCT_LENS_THRESHOLD);
+
+const PACKET = [
+  "## Review — <artifact> — round <n> — lenses: <lens>",
+  "### Sources inspected",
+  "- <path:line ranges>",
+  "### Findings",
+  "- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>",
+  "### Verdict",
+  "no-blocking | blocking",
+].join("\n");
+
+type LensTaskInput = {
+  lens: ProductLens;
+  briefPath: string;
+  round: ReviewRound;
+  /** Where round 1 was written; round 2 reads the peers' findings there. */
+  round1Path: string;
+};
+
+const ROUND_ONE =
+  "This is round 1 and it is independent: judge the artifact through your own lens and do not look at other lenses' output.";
+
+const roundTwo = (round1Path: string): string =>
+  `This is round 2, a peer exchange: read the round 1 packets in \`${round1Path}\`. For each peer finding, say whether you agree, disagree or would reword it, and why, from your own lens. Raise anything the exchange made newly visible. Do not repeat your own round 1 findings.`;
+
+/** The task text one lens agent receives. */
+function lensTask(input: LensTaskInput): string {
+  return [
+    `You are the ${input.lens} lens. Review \`${input.briefPath}\` and any artifact it links (decision register, follow-ups, terminology, journeys, ADRs).`,
+    input.round === 1 ? ROUND_ONE : roundTwo(input.round1Path),
+    GUARDRAIL,
+    "Cite `path:line` for every finding. Do not edit files.",
+    `Answer with exactly this packet (round ${input.round}), then a **Not verified** list and a **Route** line saying where each finding should go (decision register, follow-ups, interview question, ignore):`,
+    PACKET,
+  ].join("\n\n");
+}
+
+export type SpawnPayload = {
+  path: string;
+  type: string;
+  task: string;
+  thinkingLevel: "high";
+  wait: false;
+  model?: string;
+};
+
+export type PayloadInput = {
+  lenses: readonly ProductLens[];
+  briefPath: string;
+  round: ReviewRound;
+  date: string;
+  /** Makes the agent paths fresh: a failed spawn must not leave a thread that blocks the retry. */
+  suffix: string;
+  model?: string | undefined;
+};
+
+/** One fresh `agent_spawn` payload per lens, each of its own `lens-*` agent type. */
+export function lensPayloads(input: PayloadInput): SpawnPayload[] {
+  const round1Path = reviewPath(input.date, 1);
+  return input.lenses.map((lens) => ({
+    path: `/lens-r${input.round}-${lens}-${input.suffix}`,
+    type: `lens-${lens}`,
+    task: lensTask({ lens, briefPath: input.briefPath, round: input.round, round1Path }),
+    thinkingLevel: "high" as const,
+    wait: false as const,
+    ...(input.model === undefined ? {} : { model: input.model }),
+  }));
+}
+
+export type ScriptInput = {
+  payloads: readonly SpawnPayload[];
+  file: string;
+  round: ReviewRound;
+};
+
+/**
+ * The codemode script: spawn every lens detached, wait for all, write the packets to one file and
+ * return only a verdict line per lens plus the path, so the packets never enter the coordinator's context.
+ */
+export function lensReviewScript(input: ScriptInput): string {
+  const lenses = input.payloads.map((p) => ({ path: p.path, lens: p.type.replace(/^lens-/, "") }));
+  return `// @options: {"timeout_ms": 1800000}
+const payloads = ${JSON.stringify(input.payloads)};
+const lenses = ${JSON.stringify(lenses)};
+const file = ${JSON.stringify(input.file)};
+await Promise.allSettled(payloads.map((p) => tools.agent_spawn({ ...p, wait: false })));
+const packets = await Promise.all(
+  lenses.map(async ({ path, lens }) => {
+    try {
+      await tools.agent_wait({ path, timeoutMs: 1500000 });
+      // agent_output returns one page at a time; the verdict is at the end, so read every page.
+      let packet = "";
+      let offset = 0;
+      for (let page = 0; page < 20; page++) {
+        const raw = String(await tools.agent_output({ path, offset, limit: 16000 }));
+        let text = raw;
+        let next = null;
+        try {
+          const record = JSON.parse(raw);
+          if (record && typeof record.text === "string") {
+            text = record.text;
+            next = typeof record.nextOffset === "number" ? record.nextOffset : null;
+          }
+        } catch {}
+        packet += text;
+        if (next === null) break;
+        offset = next;
+      }
+      const found = /###\\s*Verdict\\s*\\n+\\s*(no-blocking|blocking)/i.exec(packet);
+      return { lens, packet, verdict: found ? found[1].toLowerCase() : "no verdict" };
+    } catch (e) {
+      return { lens, packet: "", verdict: "no packet (" + (e && e.message ? e.message : String(e)) + ")" };
+    }
+  }),
+);
+const body = packets
+  .map((r) => "## " + r.lens + " — round ${input.round}\\n\\n" + (r.packet || "_" + r.verdict + "_"))
+  .join("\\n\\n");
+await tools.write({ path: file, content: "# Lens review — round ${input.round}\\n\\n" + body + "\\n" });
+return packets.map((r) => r.lens + ": " + r.verdict).join("\\n") + "\\nwritten: " + file;
+`;
+}
+
+/** The synthesis the coordinator writes after round 2: dispositions by id, then ONE next question. */
+export function synthesisTemplate(date: string): string {
+  return [
+    `# Lens review synthesis — ${date}`,
+    "",
+    `> ${GUARDRAIL}`,
+    "",
+    "Sources: round 1 and round 2 review files in this directory.",
+    "",
+    "| R-id | Finding | Lenses | Disposition | Route |",
+    "| --- | --- | --- | --- | --- |",
+    "| R1 | <finding, one sentence> | <lenses that raised or backed it> | adopt / defer / reject — <why> | decision register / follow-ups / interview / ignore |",
+    "",
+    "## Interview agenda",
+    "",
+    "Ask the user one question next — the one whose answer removes the most risk from the R-table: <question>",
+    "",
+    "Everything else waits in follow-ups until the answer is in.",
+    "",
+  ].join("\n");
+}

package/src/review/review-tools.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import type { Exec } from "../core/exec.ts";
+import { afterReviewRound } from "../core/lifecycle.ts";
 import { resolveSlot } from "../core/models.ts";
 import type { Lens } from "../core/review.ts";
 import {
@@ -181,6 +182,7 @@ async function startRound(
   const existing = reviewOf(deps.state.get(), p.slice) ?? startReview(p.slice, required);
   const review: ReviewState = { ...existing, required };
   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);
   if (refusal !== undefined) return refusal;
 
@@ -345,6 +347,7 @@ async function recordRound(
     },
   );
   deps.state.update((s) => upsertReview(s, review));
+  deps.state.update((s) => afterReviewRound(s, nextAction(review, p.snap.digest), p.slice));
   return reply(recordSummary(review, findings, notes, p));
 }