@jwilger/pi-development-system 0.83.0 → 0.84.0

package/README.md

@@ -19,8 +19,13 @@ Everything the system offers is reachable without remembering a command. Describ
 plain words: when a prompt asks for new work, a fix or a review, the system adds a guideline
 naming the tool to use (`devsys_intake`, `devsys_review_start`). A `devsys` tool always shows
 what the current phase expects. When you say a slice is finished with no review round recorded,
-it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`)
-are shortcuts to the same tools.
+it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`,
+`/devsys-lens-review`, `/devsys-adr`) are shortcuts to the same tools.
+
+Product planning has a skill (`product-planning`: brief, decision register, follow-ups,
+terminology, journeys). `devsys_lens_review` plans a review of the brief by five product lenses and
+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`.
 
 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

package/extensions/development-system.ts

@@ -27,9 +27,11 @@ import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts
 import { registerTestGuard } from "../src/gates/test-guard.ts";
 import { createJevHolder } from "../src/jev/holder.ts";
 import { createJudgeTools } from "../src/jev/judge-tools.ts";
+import { createAdrNewTool } from "../src/planning/adr-tool.ts";
 import { createBeginWorkTool } from "../src/planning/begin-tool.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
 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 { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
@@ -174,6 +176,10 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   }
   pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
+  pi.registerTool(createAdrNewTool({ now: () => new Date() }));
+  pi.registerTool(
+    createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),
+  );
   pi.registerTool(createIntakeTool({ pi, state, jev: (ctx) => jevHolder.forContext(ctx) }));
   const reviewDeps = {
     state,

package/package.json

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

package/prompts/devsys-adr.md

@@ -0,0 +1,12 @@
+---
+description: Record a hard-to-reverse technical decision as the next numbered ADR
+argument-hint: "<decision title>"
+---
+Record an architecture decision with the product-planning skill.
+
+1. Call `devsys_adr_new` with the title: $ARGUMENTS. It creates `docs/adr/NNNN-<slug>.md` from the template and returns the path.
+2. Fill in Context (the forces and the problem), Decision (stated plainly), Consequences (positive and negative), Alternatives (each with why it was rejected) and Revisit when (a concrete condition), then link related ADRs and plan sections.
+3. Set the status to `accepted` only when the user has agreed; leave it `proposed` otherwise.
+4. Report the path and a one-line summary of the decision.
+
+Use an ADR for a boundary, dependency, data format or protocol that is hard to reverse. Product decisions belong in the decision register instead.

package/prompts/devsys-lens-review.md

@@ -0,0 +1,12 @@
+---
+description: Run the five product lenses over the brief and record the packets
+argument-hint: "[brief path] [round 1|2]"
+---
+Review the product brief with the product-planning skill.
+
+1. Call `devsys_lens_review` (brief path and round: $ARGUMENTS; omit either for `docs/product/brief.md` and round 1).
+2. Run the codemode script it returns, unchanged. It spawns the lens agents, waits, writes the packets to `docs/product/reviews/<date>-round<n>.md` and returns only a verdict per lens and the path. If codemode is unavailable, use the `agent_spawn` payloads it lists.
+3. Read the review file, not the agents' full output. Report each lens verdict and the findings with their `path:line`.
+4. After round 2, write the synthesis (R-table and a one-question agenda) from the template in the reply, then ask the user that one question.
+
+Agreement among agents is useful critique, not customer evidence.

package/skills/product-planning/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: product-planning
+description: Plan a product or capability before building it - discovery interview, brief, decision register, follow-ups, terminology, journey inventory, lens review and ADRs. Use when sizing says capability or product, when asked for a brief or a discovery interview, when an answer must be recorded as a decision, or when a plan needs a product review.
+---
+
+# Product planning
+
+Planning here finds out what is worth building. It is not a spec for code. The artifacts are a small set of
+linked documents; each has one job and a template under `references/`.
+
+| Artifact | Job | Template |
+|---|---|---|
+| Brief | The one narrative: outcome, customers, four risks, assumptions, scope, non-goals | [brief](references/brief.md) |
+| Decision register | The spine: D (decisions), Q (questions), F (scheduling and exclusions) | [decisions](references/decisions.md) |
+| Follow-ups | P items and R review findings: not lost, not now | [followups](references/followups.md) |
+| Terminology | One meaning per word | [terminology](references/terminology.md) |
+| Journeys | J items: a user, actions, an outcome | [journeys](references/journeys.md) |
+
+Put them under `docs/product/` (`brief.md`, `decisions.md`, `followups.md`, `terminology.md`, `journeys.md`).
+Copy a template only when the work needs that artifact: `capability` work gets a short brief and journeys,
+`product` work gets the lot. Skipping one is a recorded departure (`artifact.skipped`).
+
+## The interview loop
+
+Quote this rule and follow it exactly:
+
+> Update docs after each answer, ask one next question, yield.
+
+1. Ask one question. Make it the most decision-relevant open Q item.
+2. Stop. Wait for the answer. Do not ask a second question or guess ahead.
+3. Record the answer as a D-item in the register, in the owner's words, and add a dated line to the interview log.
+4. Edit the brief **only where the answered question touches it**. Bump its version. Nothing else changes.
+5. Ask the next question and yield again.
+
+Every answer becomes a D-item, including "no" and "not now" (a Deferred item with a revisit point).
+
+## Do not over-edit the brief
+
+The commonest failure is an agent that rewrites the brief between answers. It misframed the team, moved the
+timing boundary, let later-phase ideas leak in and relocated the business case, and the owner had to find and
+undo each one. So:
+
+- An edit is limited to the answered question. If you notice something else that is wrong, add a Q item, do not fix it silently.
+- Ideas for later go to follow-ups. Nothing speculative goes in the brief.
+- Show the brief diff after each answer so the owner can see exactly what moved.
+- The owner owns judgements about the domain; you own process and where things are filed.
+
+## Outcome, risks, assumptions
+
+- Open with an **outcome** (direction plus target), not a feature. State the problem to solve, not the solution to build.
+- Assess the four risks (value, usability, feasibility, viability). "Unassessed" is a legal, recorded state.
+- Write assumptions specifically; the smaller the assumption, the smaller the test. Test the riskiest first
+  (critical to success, least evidence). Compare at least two solutions, and record why when you only had one.
+- Say whether the work builds to learn (disposable, fewer gates) or builds to earn (full gates). That is a decision, never an inference.
+
+## Deferral is not exclusion
+
+Postponing the details of a capability does not remove it from scope. Only an explicit scope decision does.
+A deferred item records who deferred it, why, the interim constraint and when to revisit. A non-goal is
+something we decided not to do.
+
+## Journeys
+
+Cut the backlog from journeys, not features. A journey passes if it tells the story of a user performing a
+set of actions to achieve an outcome. Decide journeys before generating tasks; feature-shaped backlogs had to
+be thrown away and redone.
+
+## Lens review
+
+Run `devsys_lens_review` (or `/devsys-lens-review`) on the brief when the outcome, scope or risks are settled
+enough to be wrong in an interesting way. Five fresh agents read it, each through one lens (Cagan, Torres,
+Pichler, Perri, Rumelt). Round one is independent; round two is a peer exchange; you then synthesise an R table
+and a one-question agenda, and the interview loop resumes. **Agreement among agents is useful critique, not
+customer evidence.** Record rejected recommendations in the register instead of dropping them.
+
+## Decisions that need an ADR
+
+A decision about how the code is built that is hard to reverse (a boundary, a dependency, a data format, a
+protocol) gets an ADR through `devsys_adr_new`. Product decisions stay in the register. Do not write an ADR
+for something the register already holds, or the other way round.
+
+## Status words
+
+Everything produced here is "proposed" or "advisory" until a person approves a specific revision. Say
+"readiness" for declared checks, "approval" for a person's decision on a named revision, and never let one
+stand in for the other.

package/skills/product-planning/references/brief.md

@@ -0,0 +1,48 @@
+# Brief: <product or change name>
+
+- **Context:** <which product or process this brief is about>
+- **Status:** v0.1 · <date> · links: [decisions](decisions.md), [follow-ups](followups.md)
+- **Not an authorisation:** this brief records what is understood so far. It does not approve building anything.
+
+## Outcome
+
+One sentence: the change in customer behaviour or business result we want, with a direction and a target
+(for example "first-session success from 22% to 25%"). An output ("ship X") is not an outcome.
+
+## Customers and the problem
+
+Who has the problem, what they do today, and the evidence for it (link the source, date it). Say plainly what
+is evidence and what is belief.
+
+## Four risks
+
+| Risk | What could be wrong | Evidence so far | Cheapest test |
+|---|---|---|---|
+| Value | Nobody wants or uses it | unassessed | |
+| Usability | People cannot work it out | unassessed | |
+| Feasibility | We cannot build it | unassessed | |
+| Viability | It does not work for the business | unassessed | |
+
+"Unassessed" is a legal state. Writing it is better than guessing.
+
+## Assumptions
+
+Each assumption is specific, tagged with a risk category and a test status. Riskiest first (critical to
+success, little evidence). Every assumption gets a D-item in the register once answered.
+
+| ID | Assumption | Category | Test status |
+|---|---|---|---|
+| A01 | | desirability / viability / feasibility / usability / ethical | untested |
+
+## Scope
+
+What the first release does, in the customer's words.
+
+## Non-goals
+
+Things we have decided not to do. Only an explicit scope decision belongs here.
+**Deferral is not exclusion:** an item that is merely later goes to [follow-ups](followups.md), not here.
+
+## Open questions
+
+Pointers only (Q-ids in [decisions](decisions.md)). The question text lives in the register, not the brief.

package/skills/product-planning/references/decisions.md

@@ -0,0 +1,33 @@
+# Decision register
+
+The referential spine: every brief, review and journey cites these ids.
+
+## Closure rules
+
+- **Resolved:** the owner answered or accepted it.
+- **Deferred:** postponed to a later phase. State who decided, why, the interim constraint and the revisit
+  point. Deferring the specification does not defer the capability; only an explicit scope decision does.
+- **Open:** not yet answered.
+- Superseding keeps the old row and points at the new one (`D06 → D56`). Rows are never deleted.
+
+## Decisions (D)
+
+| ID | Decision | Status | Source |
+|---|---|---|---|
+| D01 | | Resolved | <answer, date> |
+
+## Questions (Q)
+
+| ID | Question | Status | Needed for closure |
+|---|---|---|---|
+| Q01 | | Open | |
+
+## Scheduling, conditional scope and exclusions (F)
+
+| ID | Item | Disposition | Rationale | Revisit when |
+|---|---|---|---|---|
+| F01 | | true exclusion / conditional / scheduled | | |
+
+## Interview log
+
+One dated bullet per answer: the question, the answer in the owner's words, and "Recorded as D<nn>".

package/skills/product-planning/references/followups.md

@@ -0,0 +1,16 @@
+# Planning follow-ups
+
+Where "do not lose it, do not do it now" goes. **Scheduled planning work is not an MVP exclusion.**
+
+| ID | Question or work | Appropriate phase | Revisit when | Decision refs |
+|---|---|---|---|---|
+| P01 | | modelling / design / architecture / pilot / commercial | | D01 |
+
+## Review findings (R)
+
+Findings from a lens review and where each was routed (decision register, follow-up, interview question,
+rejected). A rejected recommendation is recorded with the reason, never silently dropped.
+
+| ID | Finding | Route | Disposition |
+|---|---|---|---|
+| R01 | | | |

package/skills/product-planning/references/journeys.md

@@ -0,0 +1,14 @@
+# Journey inventory
+
+A journey passes this test: **it tells the story of a user performing a set of actions to achieve an outcome.**
+A feature, a screen or a technical layer does not pass it. Do this before cutting any backlog.
+
+| ID | User and starting need | Actions | Outcome |
+|---|---|---|---|
+| J01 | | | |
+
+## Per journey
+
+- Alternative outcomes (what happens when it goes wrong).
+- The decision ids it rests on.
+- Approval is of a specific revision, recorded with person and date; drafting is not approval.

package/skills/product-planning/references/terminology.md

@@ -0,0 +1,10 @@
+# Terminology
+
+Words used in the brief, register and journeys, each with one meaning. Label a document with the sense of a
+word it uses when the word has more than one.
+
+| Term | Meaning | Not to be confused with |
+|---|---|---|
+| Deferred item | Scheduled to a later phase | Exclusion |
+| Readiness | Declared checks pass | Human approval of a specific revision |
+| Lens | An advisory reviewing perspective | A review by the person it is named for |

package/src/gates/commit-guard.ts

@@ -17,6 +17,7 @@ import { resolveGit } from "../core/git-invocations.ts";
 import { DECISION_LOG, reviewGap } from "../core/review-flow.ts";
 import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
+import { ARCHITECTURE_THRESHOLD, judgeArchitectureShaping } from "../jev/questions/architecture.ts";
 import { judgeCommit, MIX_THRESHOLD, RATIONALE_FLOOR } from "../jev/questions/commit.ts";
 import { snapshotDiff } from "../review/digest.ts";
 import type { SessionState } from "../state/session-state.ts";
@@ -40,6 +41,13 @@ const gateId = (id: string): GateId => {
 const RATIONALE = gateId("commit.rationale");
 const MIXED = gateId("commit.mixed-change");
 const REVIEW = gateId("review.unsatisfied");
+const ADR_MISSING = gateId("adr.missing");
+
+/** A new `docs/adr/NNNN-*.md` among the pending changes; editing an older ADR is not recording a new decision. */
+const addsAdr = (diff: string): boolean =>
+  /^diff --git a\/docs\/adr\/\d{4}-\S+\.md b\/\S+\n(?:new file mode|rename from |similarity index)/m.test(
+    diff,
+  );
 
 const readMessageFile = (cwd: string, path: string): string | undefined => {
   try {
@@ -72,25 +80,85 @@ const stagesEverything = (command: string): boolean =>
     command,
   );
 
+/**
+ * The pathspecs a `git add` in the command stages new files under: `.` for `-A` with no path, else the named
+ * paths. Empty when nothing in the command can add an untracked file (`-u` stages only tracked files, `-n` nothing).
+ */
+const addedPathspecs = (command: string): string[] =>
+  [...command.matchAll(/\bgit\s+add\b([^;&|\n]*)/g)].flatMap((m) => {
+    const words = (m[1] ?? "")
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((w) => w.replace(/^(["'])(.*)\1$/, "$2")); // `git add "docs/adr/0005-x.md"` names the same file
+    if (words.some((w) => ["-u", "--update", "-n", "--dry-run"].includes(w))) return [];
+    const paths = words.filter((w) => !w.startsWith("-"));
+    if (paths.length === 0) return words.some((w) => w === "-A" || w === "--all") ? ["."] : [];
+    return paths.map((p) => p.replace(/^\.\//, "").replace(/\/$/, "") || ".");
+  });
+
+type PendingDiff = { stat: string; diff: string; untrackedAdr: boolean };
+
 /** What is about to be committed: the staged changes, or every tracked change when the commit stages them itself. */
 async function pendingDiff(
   exec: Exec,
   cwd: string,
   command: string,
-): Promise<{ stat: string; diff: string } | undefined> {
+): Promise<PendingDiff | undefined> {
   try {
-    const base = stagesEverything(command) ? ["diff", "HEAD"] : ["diff", "--cached"];
-    const [stat, diff] = await Promise.all([
+    const widened = stagesEverything(command);
+    const specs = addedPathspecs(command);
+    // Fixed prefixes and no external driver: `addsAdr` reads the headers, and git config can change them.
+    const fixed = ["--no-ext-diff", "--no-color", "--src-prefix=a/", "--dst-prefix=b/"];
+    const base = widened ? ["diff", ...fixed, "HEAD"] : ["diff", ...fixed, "--cached"];
+    const [stat, diff, untracked] = await Promise.all([
       exec("git", [...base, "--stat"], { cwd, timeout: 10_000 }),
       exec("git", base, { cwd, timeout: 10_000 }),
+      // `git diff HEAD` leaves out files git does not track yet, such as a new module or an ADR just created.
+      specs.length > 0
+        ? exec("git", ["ls-files", "--others", "--exclude-standard", "--", ...new Set(specs)], {
+            cwd,
+            timeout: 10_000,
+          })
+        : Promise.resolve(undefined),
     ]);
-    if (stat.code !== 0 || diff.code !== 0 || diff.stdout.trim() === "") return undefined;
-    return { stat: stat.stdout, diff: diff.stdout };
+    if (stat.code !== 0 || diff.code !== 0) return undefined;
+    const added = untracked?.code === 0 ? untracked.stdout.trim() : "";
+    if (diff.stdout.trim() === "" && added === "") return undefined;
+    return {
+      stat:
+        added === ""
+          ? stat.stdout
+          : // First, because Jev clips the stat: a long list of tracked files must not push new files out of view.
+            `New files this commit adds (untracked):\n${added}\n\n${stat.stdout}`,
+      diff: diff.stdout,
+      untrackedAdr: /^docs\/adr\/\d{4}-\S+\.md$/m.test(added),
+    };
   } catch {
     return undefined;
   }
 }
 
+/** Non-negotiable 9 as a soft gate: the judgement is probabilistic, so a departure can answer it. */
+async function adrNeeds(
+  deps: CommitGuardDeps,
+  ctx: ExtensionContext,
+  pending: PendingDiff,
+): Promise<Need[]> {
+  if (addsAdr(pending.diff) || pending.untrackedAdr) return [];
+  const judged = await judgeArchitectureShaping(deps.jev(ctx), {
+    diffStat: pending.stat,
+    diff: pending.diff,
+  });
+  if (!judged.ok || judged.value < ARCHITECTURE_THRESHOLD) return [];
+  return [
+    {
+      gate: ADR_MISSING,
+      why: "Jev reads this diff as an architecture-shaping decision (a boundary, dependency, data format or protocol) and it adds no ADR",
+    },
+  ];
+}
+
 async function jevNeeds(
   deps: CommitGuardDeps,
   ctx: ExtensionContext,
@@ -100,13 +168,13 @@ async function jevNeeds(
 ): Promise<Need[]> {
   const pending = await pendingDiff(deps.exec, ctx.cwd, command);
   if (pending === undefined) return [];
-  const judged = await judgeCommit(deps.jev(ctx), {
-    message,
-    diffStat: pending.stat,
-    diff: pending.diff,
-  });
-  if (!judged.ok) return [];
-  const needs: Need[] = [];
+  // Both ask Jev; run them together so a hung provider costs one timeout, not two.
+  const [judged, adr] = await Promise.all([
+    judgeCommit(deps.jev(ctx), { message, diffStat: pending.stat, diff: pending.diff }),
+    adrNeeds(deps, ctx, pending),
+  ]);
+  const needs: Need[] = adr;
+  if (!judged.ok) return needs;
   if (bodyPresent && judged.value.rationale < RATIONALE_FLOOR) {
     needs.push({ gate: RATIONALE, why: "Jev reads the body as restating what changed, not why" });
   }
@@ -247,13 +315,22 @@ const reviewReason = (need: Need): string =>
   "and repeat until the review is satisfied. If skipping review is deliberate call devsys_record_departure " +
   `with gate "${need.gate}", what you are doing instead, why, and the cost if wrong; then retry.`;
 
-const blockReason = (need: Need): string =>
-  need.gate === REVIEW
-    ? reviewReason(need)
-    : `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
-      "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
-      `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
-      "instead, why, and the cost if wrong; then retry.";
+const adrReason = (need: Need): string =>
+  `${need.gate}: ${need.why}. Hard-to-reverse decisions are recorded as an ADR in the same change. ` +
+  "Call devsys_adr_new with the decision's title, fill in the ADR and stage it. If this diff is not " +
+  `architecture-shaping, call devsys_record_departure with gate "${need.gate}", what you are doing instead, ` +
+  "why, and the cost if wrong; then retry.";
+
+const commitReason = (need: Need): string =>
+  `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
+  "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
+  `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
+  "instead, why, and the cost if wrong; then retry.";
+
+function blockReason(need: Need): string {
+  if (need.gate === REVIEW) return reviewReason(need);
+  return need.gate === ADR_MISSING ? adrReason(need) : commitReason(need);
+}
 
 const forbiddenReason = (found: readonly string[]): string =>
   `commit.forbidden-trailer: this commit carries an AI attribution (${found.join("; ")}). ` +

package/src/jev/questions/architecture.ts

@@ -0,0 +1,43 @@
+import type { ClassifierBoolQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { Jev, JevError } from "../client.ts";
+
+/** At or above this, a diff with no ADR in it is flagged (gate `adr.missing`). */
+export const ARCHITECTURE_THRESHOLD = 0.7;
+
+export type ArchitectureInput = { diffStat: string; diff: string };
+
+const DIFF_CLIP = 8000;
+
+export const ARCHITECTURE_QUESTION: ClassifierBoolQuestion = {
+  type: "bool",
+  instructions:
+    "Read `diffStat` and `diff`. Does this change make an architecture-shaping decision that is hard to reverse: a new module boundary or layer, a new runtime dependency, a persisted data format or schema, a public protocol or interface contract, or a change to how components communicate?",
+  criteria: {
+    true: "The diff introduces or changes a boundary, dependency, data format or protocol that later code will build on and that would be costly to undo",
+    false:
+      "The diff is a bug fix, local refactor, test, documentation, formatting or feature work inside existing boundaries that is easy to change later",
+  },
+};
+
+// Bound the text before redacting (redaction cost grows with run length); keep margin so a secret at the cut is still seen whole.
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+/** The probability that the diff shapes the architecture. */
+export async function judgeArchitectureShaping(
+  jev: Jev,
+  input: ArchitectureInput,
+): Promise<Result<number, JevError>> {
+  const asked = await jev.ask(
+    { diffStat: clip(input.diffStat, 2000), diff: clip(input.diff, DIFF_CLIP) },
+    { architecture: ARCHITECTURE_QUESTION },
+  );
+  if (!asked.ok) return asked;
+  const answer = asked.value.architecture;
+  if (answer?.type !== "bool") {
+    return err({ kind: "provider", message: "missing architecture answer" });
+  }
+  return ok(answer.probability);
+}

package/src/jev/questions/product-lenses.ts

@@ -0,0 +1,64 @@
+import type { ClassifierBoolQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import { PRODUCT_LENSES, type ProductLens } from "../../review/lens-review.ts";
+import type { Jev, JevError } from "../client.ts";
+
+const lensQuestion = (instructions: string, yes: string, no: string): ClassifierBoolQuestion => ({
+  type: "bool",
+  instructions,
+  criteria: { true: yes, false: no },
+});
+
+/** One narrow question per product lens: does this lens have something to say about the brief? */
+export const PRODUCT_LENS_QUESTIONS: Readonly<Record<ProductLens, ClassifierBoolQuestion>> = {
+  cagan: lensQuestion(
+    "Read the `brief`. Does it commit to building a product or feature while leaving a value, usability, feasibility or viability risk unnamed or untested? A trivial copy, rename or maintenance change carries no such risk.",
+    "It proposes something to build and names no test or evidence for at least one of those risks",
+    "The change is trivial, or the brief names its risks and a test or evidence for them",
+  ),
+  torres: lensQuestion(
+    "Read the `brief`. Does it claim what customers need or want without citing discovery evidence (interviews, observed behaviour, usage data)? A brief that makes no customer claim does not count.",
+    "It asserts customer needs, demand or behaviour with no discovery evidence cited",
+    "Customer claims are backed by cited evidence, or the brief makes no customer claim",
+  ),
+  pichler: lensQuestion(
+    "Read the `brief`. Does it lack a measurable goal or metric that ties the work to a product vision or strategy? A trivial copy, rename or maintenance change needs none.",
+    "It proposes substantial work with no measurable goal or metric tied to a vision",
+    "It names a measurable goal or metric, or the change is trivial",
+  ),
+  perri: lensQuestion(
+    "Read the `brief`. Does it define success as shipping features or deliverables rather than as a measurable change for customers or the business? A typo fix, rename, dependency upgrade or other maintenance change is not a product bet and always answers false.",
+    "A product bet whose success is framed as delivering a list of features or a launch date, with no outcome measure",
+    "Success is a measurable outcome, or the change is maintenance (typo, rename, upgrade, refactor)",
+  ),
+  rumelt: lensQuestion(
+    "Read the `brief`. Does it state goals or ambitions without a diagnosis of the real challenge, a guiding policy and coherent actions? A trivial copy, rename or maintenance change needs no strategy.",
+    "It lists goals, ambitions or features with no diagnosis of the challenge and no guiding policy",
+    "It diagnoses the challenge and sets a policy and actions, or the change is trivial",
+  ),
+};
+
+const BRIEF_CLIP = 8000;
+
+// Bound the text before redacting (redaction cost grows with run length); keep margin so a secret at the cut is still seen whole.
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+/** Probability per product lens that it applies to the brief. */
+export async function judgeProductLenses(
+  jev: Jev,
+  input: { brief: string },
+): Promise<Result<Record<ProductLens, number>, JevError>> {
+  const asked = await jev.ask({ brief: clip(input.brief, BRIEF_CLIP) }, PRODUCT_LENS_QUESTIONS);
+  if (!asked.ok) return asked;
+  const out = {} as Record<ProductLens, number>;
+  for (const lens of PRODUCT_LENSES) {
+    const answer = asked.value[lens];
+    if (answer?.type !== "bool" || !Number.isFinite(answer.probability)) {
+      return err({ kind: "provider", message: `missing or malformed answer for lens ${lens}` });
+    }
+    out[lens] = answer.probability;
+  }
+  return ok(out);
+}

package/src/jev/questions/solution-detail.ts

@@ -0,0 +1,43 @@
+import type { ClassifierBoolQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { Jev, JevError } from "../client.ts";
+
+/** At or above this, the brief is reported as carrying solution-level detail (a warning only). */
+export const SOLUTION_DETAIL_THRESHOLD = 0.7;
+
+export type SolutionDetailInput = { brief: string };
+
+const BRIEF_CLIP = 8000;
+
+export const SOLUTION_DETAIL_QUESTION: ClassifierBoolQuestion = {
+  type: "bool",
+  instructions:
+    "Read `brief`, a product brief. Does it specify the solution rather than the problem: named database tables or columns, API endpoints, class or module names, framework or library choices, or step-by-step implementation design?",
+  criteria: {
+    true: "The brief prescribes how the system is built (tables, endpoints, classes, libraries, internal design) instead of, or in addition to, the outcome, users and risks",
+    false:
+      "The brief describes outcomes, users, journeys, constraints and risks in product terms; any technical mention is a stated constraint or a name the users themselves use",
+  },
+};
+
+// Bound the text before redacting (redaction cost grows with run length); keep margin so a secret at the cut is still seen whole.
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+/** The probability that the brief contains solution-level detail. */
+export async function judgeSolutionDetail(
+  jev: Jev,
+  input: SolutionDetailInput,
+): Promise<Result<number, JevError>> {
+  const asked = await jev.ask(
+    { brief: clip(input.brief, BRIEF_CLIP) },
+    { solution: SOLUTION_DETAIL_QUESTION },
+  );
+  if (!asked.ok) return asked;
+  const answer = asked.value.solution;
+  if (answer?.type !== "bool") {
+    return err({ kind: "provider", message: "missing solution-detail answer" });
+  }
+  return ok(answer.probability);
+}

package/src/planning/adr-tool.ts

@@ -0,0 +1,70 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { adrFileName, nextAdrNumber, parseAdrTitle, renderAdr } from "./adr.ts";
+
+const Parameters = Type.Object({
+  title: Type.String({ description: "The decision, in a few words (one line)." }),
+});
+
+const ADR_DIR = "docs/adr";
+const TEMPLATE = "0000-template.md";
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+const message = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/**
+ * `devsys_adr_new`: the next numbered ADR, filled from `docs/adr/0000-template.md`. Numbering and the
+ * file name are mechanical, so the model writes the decision and not the paperwork.
+ */
+export function createAdrNewTool(deps: { now: () => Date }): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_adr_new",
+    // pi runs a turn's tool calls in parallel; two calls would read the same directory and pick the same number.
+    executionMode: "sequential",
+    label: "New ADR",
+    description:
+      "Create the next numbered ADR in docs/adr from its template and return the path to fill in. Use for a hard-to-reverse technical decision (a boundary, dependency, data format or protocol); product decisions go in the decision register.",
+    promptSnippet: "Create the next ADR from the template",
+    parameters: Parameters,
+    async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const title = parseAdrTitle(params.title);
+      if (!title.ok) return reply(title.error.message, true);
+      const dir = join(ctx.cwd, ADR_DIR);
+      let template: string;
+      try {
+        template = await readFile(join(dir, TEMPLATE), "utf8");
+      } catch {
+        return reply(
+          `${ADR_DIR}/${TEMPLATE} is missing, so there is nothing to start from; add the template first.`,
+          true,
+        );
+      }
+      try {
+        const number = nextAdrNumber(await readdir(dir));
+        const name = adrFileName(number, title.value);
+        const date = deps.now().toISOString().slice(0, 10);
+        await mkdir(dir, { recursive: true });
+        // `wx`: fail rather than overwrite an ADR with the same file name (calls from other sessions).
+        await writeFile(
+          join(dir, name),
+          renderAdr(template, { number, title: title.value, date }),
+          {
+            flag: "wx",
+          },
+        );
+        return reply(
+          `Created ${ADR_DIR}/${name} (status proposed). Fill in Context, Decision, Consequences, Alternatives and Revisit when. Leave the status proposed until the user agrees, then set it to accepted.`,
+        );
+      } catch (e) {
+        return reply(`could not create the ADR: ${message(e)}`, true);
+      }
+    },
+  };
+}

package/src/planning/adr.ts

@@ -0,0 +1,46 @@
+import { err, ok, type Result } from "../core/result.ts";
+import { type ParseError, parseError } from "../core/types.ts";
+
+/** `0004-prompt-cache-safe-channels.md` → 4. The template is `0000` and the README has no number. */
+const NUMBERED = /^(\d{4})-.+\.md$/;
+
+/** One more than the highest ADR number present; gaps are not filled, so a number is never reused. */
+export function nextAdrNumber(fileNames: readonly string[]): number {
+  const numbers = fileNames.flatMap((name) => {
+    const digits = NUMBERED.exec(name)?.[1];
+    return digits === undefined ? [] : [Number.parseInt(digits, 10)];
+  });
+  return Math.max(0, ...numbers) + 1;
+}
+
+export const slugify = (title: string): string =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+/** A one-line title with something to slug from; a line break could add lines to the document. */
+export function parseAdrTitle(input: string): Result<string, ParseError> {
+  const title = input.trim();
+  if (/[\r\n]/.test(title)) return err(parseError("an ADR title is a single line"));
+  if (slugify(title) === "") {
+    return err(parseError("an ADR title needs at least one letter or digit"));
+  }
+  return ok(title);
+}
+
+const adrNumberText = (n: number): string => String(n).padStart(4, "0");
+
+export const adrFileName = (n: number, title: string): string =>
+  `${adrNumberText(n)}-${slugify(title)}.md`;
+
+export type AdrInput = { number: number; title: string; date: string };
+
+/** The template with its heading, status and date filled in; the sections are left for the author. */
+export function renderAdr(template: string, input: AdrInput): string {
+  // Function replacers: a title is data, so `$&` and `$1` in it must not act as replacement patterns.
+  return template
+    .replace(/^# ADR NNNN: .*$/m, () => `# ADR ${adrNumberText(input.number)}: ${input.title}`)
+    .replace(/^- \*\*Status:\*\* .*$/m, () => "- **Status:** proposed")
+    .replace(/^- \*\*Date:\*\* .*$/m, () => `- **Date:** ${input.date}`);
+}

package/src/planning/brief-lint.ts

@@ -0,0 +1,71 @@
+/**
+ * Brief lint (plan I9.5): a brief states the outcome, the people and the risks; endpoints, tables and
+ * class names are solution detail that belongs in an ADR or the architecture. This is the
+ * deterministic half (regex markers); the Jev half lives in `src/jev/questions/solution-detail.ts`.
+ * Findings are warnings: a brief may legitimately quote a constraint that looks technical.
+ */
+
+type BriefFindingKind = "endpoint" | "table" | "class" | "path";
+
+export type BriefFinding = {
+  kind: BriefFindingKind;
+  /** 1-based line in the brief. */
+  line: number;
+  /** The text that matched. */
+  match: string;
+  message: string;
+};
+
+type Rule = { kind: BriefFindingKind; pattern: RegExp; what: string };
+
+const RULES: readonly Rule[] = [
+  {
+    kind: "endpoint",
+    pattern: /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/[\w\-/{}:.]+/g,
+    what: "an HTTP endpoint",
+  },
+  {
+    kind: "table",
+    pattern: /\bCREATE\s+TABLE\b|`\w+`\s+table\b|\btable\s+`\w+`/gi,
+    what: "a database table",
+  },
+  {
+    kind: "class",
+    pattern:
+      /\b(?:(?:class|interface)\s+[A-Z]\w+|[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)*(?:Service|Repository|Controller|Gateway|Manager|Handler|Factory|Client))\b/g,
+    what: "a class or service name",
+  },
+  {
+    kind: "path",
+    pattern: /\b(?:src|lib|test|app|packages)\/[\w\-./]+\.\w+/g,
+    what: "a source file path",
+  },
+];
+
+const advice = (what: string): string =>
+  `${what} is solution detail; keep the brief to outcome, users and risks and record this in an ADR (devsys_adr_new) or the architecture notes`;
+
+/** The brief with fenced code blocks blanked, keeping line numbers: an example in a fence is quoted, not specified. */
+function withoutFences(text: string): string[] {
+  let inFence = false;
+  return text.split("\n").map((line) => {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      return "";
+    }
+    return inFence ? "" : line;
+  });
+}
+
+export function lintBrief(text: string): BriefFinding[] {
+  return withoutFences(text).flatMap((line, i) =>
+    RULES.flatMap((rule) =>
+      [...line.matchAll(rule.pattern)].map((m) => ({
+        kind: rule.kind,
+        line: i + 1,
+        match: m[0],
+        message: advice(rule.what),
+      })),
+    ),
+  );
+}

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");
+}