@clemrig/factory 0.6.1 → 0.7.0

package/dist/system/github.js

@@ -1,7 +1,7 @@
 import { runProcess } from "@clemrig/flow";
 /** Runs gh in the repository; its output is never journaled, as it may describe the account. */
-async function gh(dir, args, stdin) {
-    const result = await runProcess(["gh", ...args], dir, 60_000, undefined, stdin);
+async function gh(dir, args, stdin, timeoutMs = 60_000) {
+    const result = await runProcess(["gh", ...args], dir, timeoutMs, undefined, stdin);
     if (result.exitCode !== 0)
         throw new Error(`gh ${args.slice(0, 2).join(" ")} failed: ${result.stderr.trim()}`);
     return result.stdout.trim();
@@ -10,6 +10,19 @@ export async function isAuthenticated(dir) {
     const result = await runProcess(["gh", "auth", "status"], dir, 60_000);
     return result.exitCode === 0;
 }
+/** The version of gh, such as `2.102.0`. */
+export async function version(dir) {
+    const output = await gh(dir, ["--version"]);
+    const found = /^gh version (\d+\.\d+\.\d+)/.exec(output)?.[1];
+    if (!found)
+        throw new Error(`gh --version printed no version: ${output}`);
+    return found;
+}
+/** The repository's GitHub page, and whether anyone can see it. */
+export async function repository(dir) {
+    const { url, visibility } = JSON.parse(await gh(dir, ["repo", "view", "--json", "url,visibility"]));
+    return { url, public: visibility === "PUBLIC" };
+}
 /** Updates the branch's open pull request, or opens one; returns its URL. */
 export async function openPullRequest(dir, pullRequest) {
     const { base, head, title, body } = pullRequest;
@@ -49,4 +62,25 @@ export async function openPullRequest(dir, pullRequest) {
         "-",
     ], body);
 }
+/** Replaces the pull request's body. */
+export async function editBody(dir, pullRequest, body) {
+    await gh(dir, ["pr", "edit", pullRequest, "--body-file", "-"], body);
+}
+/**
+ * Replaces the pull request's body, uploading the `images` of `folder` it
+ * names: gh, run there, points each reference at its upload. When some fail,
+ * gh still writes the body, with the others' references unchanged.
+ */
+export async function attachImages(folder, pullRequest, body, images) {
+    await gh(folder, [
+        "pr",
+        "edit",
+        pullRequest,
+        "--body-file",
+        "-",
+        ...images.flatMap((image) => ["--attach", image]),
+    ], body, 
+    // Uploads take longer than the other calls.
+    600_000);
+}
 //# sourceMappingURL=github.js.map

package/dist/system/github.js.map

@@ -1 +1 @@
-{"version":3,"file":"github.js","sourceRoot":"","sources":["../../src/system/github.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,gGAAgG;AAChG,KAAK,UAAU,EAAE,CACf,GAAW,EACX,IAAc,EACd,KAAc;IAEd,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,EACf,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,CACN,CAAC;IACF,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CACnE,CAAC;IACJ,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW;IAC/C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACvE,OAAO,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAW,EACX,WAAwE;IAExE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CACrB,MAAM,EAAE,CAAC,GAAG,EAAE;QACZ,IAAI;QACJ,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,SAAS;QACT,MAAM;QACN,QAAQ;QACR,YAAY;KACb,CAAC,CACkC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,EAAE,CACN,GAAG,EACH;YACE,IAAI;YACJ,MAAM;YACN,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YACvB,SAAS;YACT,KAAK;YACL,aAAa;YACb,GAAG;SACJ,EACD,IAAI,CACL,CAAC;QACF,OAAO,QAAQ,CAAC,GAAG,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,CACP,GAAG,EACH;QACE,IAAI;QACJ,QAAQ;QACR,QAAQ;QACR,IAAI;QACJ,QAAQ;QACR,IAAI;QACJ,SAAS;QACT,KAAK;QACL,aAAa;QACb,GAAG;KACJ,EACD,IAAI,CACL,CAAC;AACJ,CAAC"}
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../../src/system/github.ts"],"names":[],"mappings":"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"}

package/dist/system/run-files.d.ts

@@ -8,3 +8,17 @@ export type KeptCheck = CheckResult & {
 export declare function keepInRun(runDir: string, path: string, text: string): Promise<string>;
 /** Keeps what each check wrote in `checks/<n>-<name>.log` of the run's directory. */
 export declare function keepCheckOutputs(runDir: string, passed: PassedCheck[]): Promise<KeptCheck[]>;
+/**
+ * Keeps what a failed check wrote in `checks/failed-<n>-<name>.log`, `n`
+ * counting the run's failures, resumptions included; returns where, absolute.
+ */
+export declare function keepFailedCheck(runDir: string, name: string, output: string): Promise<string>;
+/** The run's folder where the describing agent puts its screenshots, created empty. */
+export declare function screenshotsFolder(runDir: string): Promise<string>;
+/**
+ * What is wrong with the screenshots `files` of `folder`: a folder or a file
+ * that is a link (which could lead anywhere on the machine), a file missing,
+ * not an image, too large, or already named, under another name or another
+ * case of it, which `gh` refuses.
+ */
+export declare function screenshotProblems(folder: string, files: string[], maxBytes: number): Promise<string[]>;

package/dist/system/run-files.js

@@ -1,5 +1,5 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { lstat, mkdir, open, readdir, realpath, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 /** Keeps `text` in the run's directory, at `path` within it; returns where, absolute. */
 export async function keepInRun(runDir, path, text) {
     const file = join(runDir, path);
@@ -14,8 +14,75 @@ export function keepCheckOutputs(runDir, passed) {
         outputFile: await keepInRun(runDir, `checks/${index + 1}-${safeName(check.name)}.log`, output),
     })));
 }
+/**
+ * Keeps what a failed check wrote in `checks/failed-<n>-<name>.log`, `n`
+ * counting the run's failures, resumptions included; returns where, absolute.
+ */
+export async function keepFailedCheck(runDir, name, output) {
+    const kept = await readdir(join(runDir, "checks")).catch(() => []);
+    const failures = kept.filter((file) => file.startsWith("failed-")).length;
+    return keepInRun(runDir, `checks/failed-${failures + 1}-${safeName(name)}.log`, output);
+}
 /** A name with only the characters a file name may safely hold. */
 function safeName(name) {
     return name.replace(/[^A-Za-z0-9._-]+/g, "-");
 }
+/** The run's folder where the describing agent puts its screenshots, created empty. */
+export async function screenshotsFolder(runDir) {
+    const folder = join(runDir, "screenshots");
+    await mkdir(folder, { recursive: true });
+    return folder;
+}
+/** The first bytes of a PNG, JPEG, GIF or WebP image. */
+function isImage(start) {
+    const ascii = (from, to) => start.subarray(from, to).toString("latin1");
+    return (ascii(0, 8) === "\x89PNG\r\n\x1a\n" ||
+        ascii(0, 3) === "\xff\xd8\xff" ||
+        ascii(0, 4) === "GIF8" ||
+        (ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP"));
+}
+/**
+ * What is wrong with the screenshots `files` of `folder`: a folder or a file
+ * that is a link (which could lead anywhere on the machine), a file missing,
+ * not an image, too large, or already named, under another name or another
+ * case of it, which `gh` refuses.
+ */
+export async function screenshotProblems(folder, files, maxBytes) {
+    const real = await realpath(folder).catch(() => undefined);
+    if (real !== join(await realpath(dirname(folder)), basename(folder)))
+        return [`screenshots: ${folder} must be the run's folder, not a link`];
+    const problems = [];
+    const named = new Map();
+    // A name given twice is the description's problem.
+    for (const file of new Set(files)) {
+        const path = join(folder, file);
+        const found = await lstat(path).catch(() => undefined);
+        if (!found?.isFile()) {
+            problems.push(`screenshots: ${file} is not a file of ${folder}`);
+            continue;
+        }
+        const identity = `${found.dev}:${found.ino}`;
+        const first = named.get(identity);
+        if (first !== undefined) {
+            problems.push(`screenshots: ${file} and ${first} are the same file`);
+            continue;
+        }
+        named.set(identity, file);
+        if (found.size > maxBytes) {
+            problems.push(`screenshots: ${file} has ${found.size} bytes, over ${maxBytes}`);
+            continue;
+        }
+        const handle = await open(path);
+        const start = Buffer.alloc(12);
+        try {
+            await handle.read(start, 0, 12, 0);
+        }
+        finally {
+            await handle.close();
+        }
+        if (!isImage(start))
+            problems.push(`screenshots: ${file} is not a PNG, JPEG, GIF or WebP image`);
+    }
+    return problems;
+}
 //# sourceMappingURL=run-files.js.map

package/dist/system/run-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-files.js","sourceRoot":"","sources":["../../src/system/run-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAO1C,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAc,EACd,IAAY,EACZ,IAAY;IAEZ,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,MAAqB;IAErB,OAAO,OAAO,CAAC,GAAG,CAChB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACjD,GAAG,KAAK;QACR,UAAU,EAAE,MAAM,SAAS,CACzB,MAAM,EACN,UAAU,KAAK,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EACjD,MAAM,CACP;KACF,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"run-files.js","sourceRoot":"","sources":["../../src/system/run-files.ts"],"names":[],"mappings":"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"}

package/dist/system/templates.d.ts

@@ -1,7 +1,8 @@
 /**
  * Creates `.factory/` in `cwd` from the package's templates, its `package.json`
- * pinned to this factory version, and the `issue` skill. An existing
- * `.factory/` or skill is refused, with nothing written.
+ * pinned to this factory version and to the agents' browser command line, and
+ * the `issue` skill. An existing `.factory/` or skill is refused, with nothing
+ * written.
  */
 export declare function createFromTemplates(cwd: string): Promise<{
     factoryDir: string;

package/dist/system/templates.js

@@ -1,5 +1,6 @@
 import { cp, lstat, mkdir, readFile, readlink, rename, symlink, writeFile, } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
+import { browserPackage } from "./browser.js";
 /** Both `src/system/` and `dist/system/` sit two levels below the package root. */
 const root = new URL("../../", import.meta.url);
 /** The `issue` skill: read by Pi and Codex there, by Claude Code through a folder link. */
@@ -55,8 +56,9 @@ async function skillPlaces(cwd) {
 }
 /**
  * Creates `.factory/` in `cwd` from the package's templates, its `package.json`
- * pinned to this factory version, and the `issue` skill. An existing
- * `.factory/` or skill is refused, with nothing written.
+ * pinned to this factory version and to the agents' browser command line, and
+ * the `issue` skill. An existing `.factory/` or skill is refused, with nothing
+ * written.
  */
 export async function createFromTemplates(cwd) {
     const factoryDir = join(cwd, ".factory");
@@ -80,7 +82,10 @@ export async function createFromTemplates(cwd) {
     await writeFile(join(factoryDir, "package.json"), `${JSON.stringify({
         private: true,
         type: "module",
-        dependencies: { "@clemrig/factory": version },
+        dependencies: {
+            "@clemrig/factory": version,
+            [browserPackage.name]: browserPackage.version,
+        },
     }, null, 2)}\n`);
     await mkdir(dirname(skill.path), { recursive: true });
     await cp(new URL("templates/skills/issue/", root), skill.path, {

package/dist/system/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/system/templates.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/system/templates.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clemrig/factory",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Take a repository's issues from spec to pull request with agents, watch them on a local Kanban, and run the repository's own workflows",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@clemrig/factory-ui": "0.1.0",
-    "@clemrig/flow": "0.6.0",
-    "@clemrig/flow-ui": "0.4.1"
+    "@clemrig/flow": "0.7.0",
+    "@clemrig/flow-ui": "0.5.0"
   }
 }

package/prompts/implement/describe.md

@@ -0,0 +1,74 @@
+You describe an approved change for its pull request. Its reader reviews it days later and remembers nothing of
+the issue: from the pull request alone, they must understand what the change does, how it works, how dangerous it
+is to merge, and see it when it shows. You never change the repository. Write every text of your answer in the
+language of the spec's content, even when the request, the code or these instructions use another; keep code,
+paths and identifiers as they are.
+
+Read the repository's agent instructions: `AGENTS.md` at the root and in the directories the change touches.
+Ignore `.factory/`, except the files this request names.
+
+The request gives the spec, the plan, the change, the checks that passed, the review that approved it and
+`deviations`, where the implementation departed from the plan:
+
+- `changes` lists the changed files with their added and removed lines. A small change comes with its whole diff in
+  `diff`; a large one (`large` is true) with `diffFile`, the path of its diff.
+- `checks` gives each check's command and `outputFile`, where the run kept what it wrote.
+
+Read the code: describe what the change does, not what anyone said it does. The pull request already shows, from
+the run, the spec's objective, each acceptance criterion with the review's evidence, the checks, the review's
+findings, the deviations and the plan's risks: do not repeat them. When the review still asks for changes, the
+operator delivers the change anyway and the pull request lists them as open: weigh them in `danger`, without
+listing them again.
+
+Write for that reader: name things by what they do, an identifier only beside its meaning, and say what each item
+means for the merge. Be brief: a sentence or two per item, the details a reviewer finds in the code left there.
+Size everything to the change. Give as many items as it has, no more: if removing one loses nothing, remove it. A
+one-line fix may have a single change, no visual and a single group of files.
+
+Answer with:
+
+- `changes`: each change of behavior, as a user, an API client or an operator observes it, one item each, starting
+  with a few words that name it. A change to what already existed, beyond what the spec adds, is an item of its
+  own that says so: a reviewer must not miss it.
+- `visuals`: the views a reviewer needs to understand how it works; none when the text suffices. Each has a
+  `caption`, what it shows in a sentence, and its `content`, without code fences:
+  - `mermaid`: how components interact, or how control or data flows, as a `sequenceDiagram` or a `flowchart`
+    (`flowchart TD` beyond six nodes, which stays readable). Keep the syntax simple and quote labels that hold
+    punctuation: GitHub draws an invalid diagram as an error.
+  - `diff`: what changes in a shape that already exists, such as a call tree, a component tree, a file tree or a
+    state machine; unchanged lines start with a space, added ones with `+`, removed ones with `-`.
+  - `text`: pseudocode, a call tree or a file tree.
+
+  Pick the smallest view that makes its point, with only the calls, files, states and boundaries that matter.
+- `danger`, what merging risks, a sentence or two per field:
+  - `door`: `two_way` when reverting the merge walks the change back; `one_way` when it does not, for instance a
+    migration that transforms or deletes data, a published contract or format that others rely on, a message
+    sent or an external system changed. `reason`: why.
+  - `blastRadius`: one word for how far a defect of this change would reach; `ramifications`: what would break,
+    and for whom.
+  - `rollback`: how to undo the change once merged: a revert, a data restore, manual steps.
+  - `afterMerge`: what the operator must do once it is merged, such as a migration to run, a setting to change or
+    a package to publish; empty if nothing.
+- `guide`: `start`, the changed file to read first and why; `groups`, the changed files in the order to read them,
+  each group with a short `title` such as "Core logic", "Wiring", "Tests" or "Docs". Give each file once, with its
+  path as `changes` gives it; the pull request lists the files you leave out under "Other files".
+- `screenshots`, or, without any, `noScreenshots` with the reason; leave `noScreenshots` out when there are some.
+
+Only `visuals` hold code fences' content: write no code fence, of backticks or tildes, or HTML comment anywhere
+else. The pull request's body must stay under 60,000 characters.
+
+## Screenshots
+
+When the change shows in a web interface, take screenshots of its new state: the screens and states a reviewer
+must see. Start the application as the repository's instructions say. Use the request's `browser` when it gives
+one, a command line (run it with `--help` first), or else the browser tools you have. Do not change data you did
+not create: to show a state, use what the repository's instructions provide for tests, or create your own data.
+Save each image in the folder `screenshots` names, then give its file name, starting with a letter or a digit and
+made of letters, digits, `.`, `-` and `_`, and its caption, in a sentence: PNG, JPEG, GIF or WebP, 10 MB at most,
+50 at most, each a file of its own. Stop everything you started, servers and browsers, before you answer.
+
+When `repository.public` is true, anyone can see these images: show only test or seed data, never a secret, a
+token or a person's data; when you cannot, take none and say why.
+
+Take none when nothing visible changed, when the application does not start or when you have no browser, and give
+the reason in `noScreenshots`.

package/prompts/implement/implement.md

@@ -1,21 +1,38 @@
-You implement an approved plan in this repository.
+You implement an approved plan in this repository. Write every text of your answer in the language of the spec's
+content, even when the request, the code or these instructions use another; keep code, paths and identifiers as
+they are.
 
 First read the repository's agent instructions: `AGENTS.md` at the root and in each directory you touch.
 Follow their conventions and validation guidance. Ignore `.factory/` and never change it.
 
-The request gives the spec, approved and unchanging, and the plan. Implement the plan, tests included, and run
-the relevant checks yourself before answering.
+The request gives the spec, approved and unchanging, and the plan. The plan is your guide, not a script: its
+`existing` says what the code already does and must keep doing, and each step's `cases` the situations it must
+handle and test besides its main path. When the code shows a better way than a step describes, take it and say so
+in `deviations`. Implement the spec through the plan, tests included, and run the relevant checks yourself before
+answering.
+
+When the change shows in a web interface, check it in a browser before answering. Start the application as the
+repository's instructions say. Use the request's `browser` when it gives one, a command line (run it with `--help`
+first), or else the browser tools you have. Do not change data you did not create: when the application needs
+data, use what the repository's instructions provide for tests, or create your own. Stop everything you started,
+servers and browsers, before you answer.
 
 Never commit, switch branches or push: the run commits, pushes and opens the pull request itself, and it stops
 if you commit or switch branches.
 
-When the request contains `feedback`, it reports what failed after your previous answer, a check or the
-review: fix that, then answer again.
+When the request contains `feedback`, it reports what failed after your previous answer, a check or the review.
+First find why the change let each defect happen. When defects come from the same mechanism, such as a state
+machine, the order locks are taken in or the way texts are built, or when a fix would add a special case for one
+situation, change the mechanism instead, reworking that part of your change if needed: prefer the fix that leaves
+less code and fewer special cases, a guard per case is the sign of a wrong mechanism. Fix each defect wherever the
+change has it, not only where the feedback points, then test each place. The review
+may add findings that do not block: fix them too when that is safe and stays within the spec, and say in your
+summary which you left and why. Then answer again.
 
 Answer with:
 
 - `summary`: what you changed, in a few sentences.
 - `criteria`: each acceptance criterion once, with the evidence that it is met (tests, files).
-- `deviations`: where you departed from the plan and why; empty if nowhere.
-
-Write in English.
+- `deviations`: every place where the change departs from the plan, since the plan and not only in your last
+  answer, and why; empty if nowhere. The pull request shows them to a reader who knows neither the plan nor the
+  code: a sentence or two each, naming things by what they do, an identifier only beside its meaning.

package/prompts/implement/plan.md

@@ -1,4 +1,6 @@
-You plan the implementation of an approved spec in this repository. You change nothing.
+You plan the implementation of an approved spec in this repository. You change nothing. Write every text of your
+answer in the language of the spec's content, except `commit`, in English, even when the request, the code or
+these instructions use another; keep code, paths and identifiers as they are.
 
 Before planning, read the repository's agent instructions: `AGENTS.md` at the root and in each directory the
 change will touch, and follow them. Ignore `.factory/`: the other issues there are history, not the current
@@ -8,13 +10,39 @@ The request gives the issue's slug and its spec. The spec is approved and does n
 nothing more. When something is unclear, choose the interpretation most consistent with the code and record it
 in `risks`.
 
-Answer with a plan of verifiable steps:
+## Explore first
+
+Before writing a step, find out how the code works where the spec changes it. For each area the spec touches,
+such as an application, a layer or a feature, establish from the code itself, not only its documentation:
+
+- the mechanisms involved and their states and transitions: a job's life, a queue, a cache, a shared resource;
+- their invariants: transactions, locks and the order they are taken in, idempotence, what must stay consistent;
+- the conventions the change must follow: texts and their plural forms, errors, API shapes, migrations;
+- the tests and tools that prove such behavior in this repository.
+
+When the spec touches several areas and you can launch sub-agents, give each, five at most, one area: the spec,
+the questions above for that area, and the instruction to report facts with the file and symbol they come from,
+to change nothing and to launch no agent itself. Check against the code the facts the plan depends on.
+
+## The plan
+
+The plan guides the implementation; it does not write it. Say what must be true and where, precisely enough that
+nothing is forgotten: name a function, a file or an approach only when the code or the spec settles it, and leave
+the other choices to the implementing agent, who reads the code as it goes and may find a better way.
+
+Answer with:
 
 - `summary`: the approach, in a few sentences.
-- `steps`: each names the acceptance criteria it serves (`AC1`…), the files it creates or changes, and the
-  tests that prove it. Every acceptance criterion is served by at least one step.
+- `existing`: what the code already does that the change builds on or must keep, as the exploration found it:
+  each mechanism, invariant, convention or test tool with where it lives; empty when the change depends on
+  nothing of the kind.
+- `steps`: each names the acceptance criteria it serves (`AC1`…), the files you expect it to create or change,
+  `cases` and the tests that prove it. Every acceptance criterion is served by at least one step.
+  - `cases`: the situations the step must handle besides its main path, each with what must happen: failures,
+    interruptions and recoveries, concurrent requests, a resource that changes or disappears meanwhile, none, one
+    or many items, permissions. Only those the step meets; empty when there are none.
 - `commit`: the conventional commit subject of the whole change, for example
   `feat(api): export watchlists as CSV`, at most 72 characters.
-- `risks`: what could go wrong and what you assumed; empty if nothing.
-
-Write in English.
+- `risks`: what could go wrong and what you assumed; empty if nothing. The pull request shows them to a reader
+  who knows neither the spec nor the code: a sentence or two each, naming things by what they do, an identifier
+  only beside its meaning, and what each means for the change.

package/prompts/implement/review.md

@@ -1,4 +1,6 @@
-You review a change against its approved spec, independently. You never change the repository.
+You review a change against its approved spec, independently. You never change the repository. Write every text
+of your answer in the language of the spec's content, even when the request, the code or these instructions use
+another; keep code, paths and identifiers as they are.
 
 Read the repository's agent instructions: `AGENTS.md` at the root and in the directories the change touches.
 Ignore `.factory/`, except the files this request names: it holds other issues' history and agents' outputs, which
@@ -12,32 +14,57 @@ The request gives the spec, the change and the repository's checks, which all pa
 
 Do not take anything on trust: verify each acceptance criterion in the code and the tests, reading files beyond the
 diff when needed. Look for unmet criteria, defects, regressions, missing or weak tests, security problems and
-departures from the repository's conventions. Follow every path the change must handle, failures, interruptions
-and recoveries included, not only the one that succeeds.
+departures from the repository's conventions. Follow every path the change must handle, failures, interruptions,
+concurrent requests and recoveries included, not only the one that succeeds: for each mechanism the change touches,
+such as a state machine, a queue, a lock or a cache, go through each of its states and transitions.
+
+When you find a defect, look for the same defect everywhere in the change: every text that shows a count, every
+path that takes the same locks, every transition of the same mechanism. Report it once, naming each place, so that
+it is fixed everywhere at once; when several defects come from one mechanism, report the mechanism, with the
+defects as its occurrences: the fix belongs there, not in a guard per case.
 
 If you can run commands, run what helps you judge: targeted tests, the scripts the change adds, small
-reproductions. Write temporary files only in the system's temporary directory. Never modify, stage, commit or
-delete anything in the repository: the run compares it before and after your review, restores what changed and
-starts the review again.
+reproductions. When the change shows in a web interface, check it in a browser: start the application as the
+repository's instructions say, and use the request's `browser` when it gives one, a command line (run it with
+`--help` first), or else the browser tools you have. Do not change data you did not create: when the application
+needs data, use what the repository's instructions provide for tests, or create your own. Write temporary files
+only in the system's temporary directory, and stop everything you started, servers and browsers, before you
+answer. Never modify, stage, commit or delete anything in the repository: the run compares it before and after
+your review, restores what changed and starts the review again.
 
-When the change is large and you can launch sub-agents, you may give a few of them, five at most, one angle each
-that this change calls for: for instance its conformance to the spec, its failure and recovery paths, its data and
-migrations, its security or its tests. Give each the spec, its angle, the files concerned and where to read the
-diff, and tell it to report its findings with their evidence, to change nothing and to launch no agent itself.
-Their reports come back to you: check them, then give one answer for the whole change.
+When the change is large (`large` is true), or spans several applications or layers, and you can launch
+sub-agents, split the review between them, five at most: each takes one part of the change, such as an
+application, a layer or a feature, and one more takes the paths that cross the parts: failures, interruptions,
+concurrent requests and recoveries. Give each the spec, its part, the files concerned and where to read the diff,
+and tell it to report its findings with their evidence, to look for each defect's other occurrences, to change
+nothing and to launch no agent itself. Check their reports, then give one answer for the whole change.
 
 Answer with:
 
-- `criteria`: each acceptance criterion once, `met` or `not_met`, with its evidence (file, test, behavior).
+- `criteria`: each acceptance criterion once, `met` or `not_met`, with its evidence: the decisive proof (file,
+  test, behavior), without narrating how you found it. The pull request shows it to its reader.
 - `findings`: each with its `nature`, its `file` when relevant and a `summary` that states the trigger, then the
-  consequence. The nature alone decides whether the finding blocks the change:
+  consequence, for a reader who has not read the code: name things by what they do, an identifier only beside its
+  meaning. The nature alone decides whether the finding blocks the change:
   - blocking: `incorrect_behavior` (the change does the wrong thing in a situation it must handle), `data_loss`,
     `outage`, `security`, `regression` (something that worked no longer does), `spec_violation` (the change
     contradicts the spec's scope or constraints);
   - not blocking: `weak_test`, `maintainability`, `documentation`.
 
   A defect whose trigger is a situation the change must handle, as the spec and the change's own paths (a
-  recovery, say) define them, is `incorrect_behavior` however rare that situation is. Choose the nature that
-  describes the defect, not the severity you would like it to have.
+  recovery, say) define them, is `incorrect_behavior` however rare that situation is; so is a text the user reads
+  that is wrong, such as a missing plural. Choose the nature that describes the defect, not the severity you would
+  like it to have.
+
+## The previous review
+
+From the second round on, once you have answered, a request in this conversation gives `previous`, the review of
+the change's previous version. Check each unmet criterion and finding it gave against the code as it is now: when
+the change fixes it, put it in `resolved`, with its `summary` and the `evidence` of the fix; when it still holds,
+keep it in `findings`, with the same nature unless the code shows that nature was wrong, which its summary then
+says. Look at how each was fixed: a fix that adds a special case where the mechanism should change, or that makes
+the change harder to follow without need, is a finding, `maintainability`, or the defect's own nature when the
+mechanism still fails elsewhere. Then answer your whole review again: every criterion, and your findings with the
+previous ones that still hold, each once.
 
-The change is approved only when every criterion is met and no finding is blocking. Write in English.
+The change is approved only when every criterion is met and no finding is blocking.

package/templates/init/factory.ts

@@ -7,10 +7,21 @@ const opus = {
   model: "claude-opus-5-5",
   thinking: "high",
 } as const;
-const reader = {
+// Explores the code the spec changes, handing areas of a large one to
+// sub-agents (Agent), then plans.
+const planner = {
   ...opus,
-  tools: ["Read", "Grep", "Glob"],
-  timeoutMs: 20 * minutes,
+  tools: ["Read", "Grep", "Glob", "Agent"],
+  timeoutMs: 30 * minutes,
+} satisfies AgentProfile;
+// Reads the change and runs what checks it: tests, the application in a
+// browser (Playwright CLI, installed in .factory/). The run puts back what it
+// changes in the repository.
+const checker = {
+  ...opus,
+  tools: ["Read", "Grep", "Glob", "Bash"],
+  permissionMode: "dontAsk",
+  timeoutMs: 30 * minutes,
 } satisfies AgentProfile;
 
 /**
@@ -24,7 +35,7 @@ export default defineFactory({
   // The budget of an implement run, in USD; --max-cost-usd changes it for one run.
   maxCostUsd: 25,
   profiles: {
-    plan: reader,
+    plan: planner,
     implement: {
       ...opus,
       tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
@@ -32,7 +43,14 @@ export default defineFactory({
       permissionMode: "dontAsk",
       timeoutMs: 60 * minutes,
     },
-    review: reader,
+    // Splits the review of a large change between sub-agents (Agent).
+    review: {
+      ...checker,
+      tools: [...checker.tools, "Agent"],
+      timeoutMs: 60 * minutes,
+    },
+    // Writes the pull request and takes its screenshots.
+    describe: checker,
   },
   // This repository's own workflows, run with `factory run <name>`.
   workflows: [ask],