@next-generation-collective/factory 0.0.0-stage → 0.3.1

package/lib/config.js

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { normaliseAgent } from "./agents.js";
+
+export const FACTORY_DIR = ".factory";
+export const CONFIG_FILE = "factory.config.json";
+
+export function paths(root) {
+  const dir = join(root, FACTORY_DIR);
+  return {
+    root,
+    dir,
+    config: join(root, CONFIG_FILE),
+    state: join(dir, "state.json"),
+    evidence: join(dir, "evidence"),
+    lastVerify: join(dir, "last-verify.json"),
+    prompts: join(dir, "prompts"),
+    roles: join(dir, "roles"),
+    templates: join(dir, "templates"),
+    idea: join(dir, "idea.txt"),
+    report: join(dir, "report.md"),
+  };
+}
+
+export function ensure(root) {
+  const p = paths(root);
+  for (const dir of [p.dir, p.evidence, p.prompts, p.roles, p.templates]) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return p;
+}
+
+export function defaultConfig(root) {
+  return {
+    name: basename(root),
+    kind: "other",
+    whoDepends: [],
+    neverBreak: "",
+    personalData: "unknown",
+    agent: {
+      command: "claude",
+      args: ["-p", "--permission-mode", "acceptEdits"],
+    },
+    spec: {
+      active: null,
+      required: true,
+    },
+    checks: {
+      budgetKb: 1500,
+      maxFileKb: 700,
+      timeoutMinutes: 10,
+    },
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function readConfig(root) {
+  const base = defaultConfig(root);
+  const file = paths(root).config;
+  if (!existsSync(file)) return base;
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return base;
+  }
+  return {
+    ...base,
+    ...raw,
+    agent: raw.agent ? normaliseAgent(raw.agent) : base.agent,
+    spec: { ...base.spec, ...(raw.spec ?? {}) },
+    checks: { ...base.checks, ...(raw.checks ?? {}) },
+  };
+}
+
+export function writeConfig(root, config) {
+  ensure(root);
+  writeFileSync(paths(root).config, `${JSON.stringify(config, null, 2)}\n`);
+  return config;
+}
+
+export function readState(root) {
+  const file = paths(root).state;
+  if (!existsSync(file)) return { lastVerify: null };
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return { lastVerify: null };
+  }
+}
+
+export function writeState(root, patch) {
+  const next = { ...readState(root), ...patch };
+  ensure(root);
+  writeFileSync(paths(root).state, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}

package/lib/detect.js

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const WEB = new Set([
+  "next", "nuxt", "svelte", "sveltekit", "astro", "remix", "vite", "react",
+  "react-dom", "vue", "angular", "@angular/core", "solid-js", "gatsby",
+]);
+
+const API = new Set(["express", "fastify", "koa", "hono", "@hapi/hapi", "nest", "@nestjs/core"]);
+
+const BUILD_DIRS = ["dist", "build", "out", ".next/static", "public/build"];
+
+// .next/static is left behind by `next dev` too; only a production build writes BUILD_ID.
+export function buildOutputDirs(root, base = "") {
+  return BUILD_DIRS.filter((name) => {
+    const dir = join(root, base, name);
+    if (!existsSync(dir)) return false;
+    return name !== ".next/static" || existsSync(join(root, base, ".next", "BUILD_ID"));
+  }).map((name) => (base ? `${base}/${name}` : name));
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function jsPackageManager(root) {
+  if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock"))) return "bun";
+  return "npm";
+}
+
+function pythonPackageManager(root) {
+  if (existsSync(join(root, "uv.lock"))) return "uv";
+  if (existsSync(join(root, "poetry.lock"))) return "poetry";
+  return "pip";
+}
+
+function pythonTestCommand(root, pm) {
+  if (pm === "uv") return "uv run pytest -q";
+  if (pm === "poetry") return "poetry run pytest -q";
+  const windows = process.platform === "win32";
+  const venv = windows ? join(".venv", "Scripts", "python") : join(".venv", "bin", "python");
+  if (existsSync(join(root, venv)) || existsSync(join(root, `${venv}.exe`))) return `${venv} -m pytest -q`;
+  return `${windows ? "python" : "python3"} -m pytest -q`;
+}
+
+function isPlaceholder(script) {
+  return !script || /no test specified|no build specified/i.test(script);
+}
+
+// One package: what kind of project it is, from its package.json or language files.
+function detectOne(dir, pkg) {
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const has = (name) => Boolean(deps[name]);
+
+  if (has("expo")) return { kind: "mobile", framework: "expo", language: "javascript" };
+  if (has("react-native")) return { kind: "mobile", framework: "react-native", language: "javascript" };
+  if (has("next")) return { kind: "web", framework: "next", language: "javascript" };
+  if (has("nuxt")) return { kind: "web", framework: "nuxt", language: "javascript" };
+  if (has("@angular/core")) return { kind: "web", framework: "angular", language: "typescript" };
+  if (has("svelte") || has("sveltekit")) return { kind: "web", framework: "svelte", language: "javascript" };
+  if (has("astro")) return { kind: "web", framework: "astro", language: "javascript" };
+  if ([...WEB].some(has)) return { kind: "web", framework: [...WEB].find(has), language: "javascript" };
+  if ([...API].some(has)) return { kind: "api", framework: [...API].find(has), language: "javascript" };
+  if (pkg) return { kind: pkg.bin ? "cli" : "script", framework: null, language: "javascript" };
+
+  if (existsSync(join(dir, "index.html"))) return { kind: "web", framework: "static", language: "html" };
+  if (existsSync(join(dir, "pyproject.toml")) || existsSync(join(dir, "requirements.txt"))) {
+    return { kind: "script", framework: "python", language: "python" };
+  }
+  if (existsSync(join(dir, "go.mod"))) return { kind: "api", framework: "go", language: "go" };
+  if (existsSync(join(dir, "Cargo.toml"))) return { kind: "script", framework: "rust", language: "rust" };
+  return { kind: "other", framework: null, language: null };
+}
+
+function workspacePatterns(root, pkg) {
+  const fromPkg = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
+  if (Array.isArray(fromPkg)) return fromPkg;
+  const pnpm = join(root, "pnpm-workspace.yaml");
+  if (!existsSync(pnpm)) return [];
+  return [...readFileSync(pnpm, "utf8").matchAll(/^\s*-\s*["']?([^"'\n#]+?)["']?\s*$/gm)].map((m) => m[1]);
+}
+
+// Expands "apps/*" and "packages/web" style patterns. Deeper globs are skipped.
+export function findWorkspaces(root, pkg) {
+  const found = [];
+  for (const pattern of workspacePatterns(root, pkg)) {
+    if (pattern.startsWith("!")) continue;
+    const clean = pattern.replace(/\/+$/, "");
+    if (clean.endsWith("/*") && !clean.slice(0, -2).includes("*")) {
+      const base = clean.slice(0, -2);
+      if (!isDir(join(root, base))) continue;
+      for (const name of readdirSync(join(root, base)).sort()) {
+        const rel = `${base}/${name}`;
+        if (existsSync(join(root, rel, "package.json"))) found.push(rel);
+      }
+    } else if (!clean.includes("*") && existsSync(join(root, clean, "package.json"))) {
+      found.push(clean);
+    }
+  }
+  return [...new Set(found)];
+}
+
+const PRIMARY_ORDER = ["mobile", "web", "api", "cli", "script"];
+
+export function detectStack(root) {
+  const pkg = existsSync(join(root, "package.json")) ? readJson(join(root, "package.json")) : null;
+  const scripts = pkg?.scripts ?? {};
+
+  const workspaces = findWorkspaces(root, pkg).map((path) => {
+    const wpkg = readJson(join(root, path, "package.json"));
+    return { path, pkg: wpkg, ...detectOne(join(root, path), wpkg) };
+  });
+
+  const own = detectOne(root, pkg);
+  let primary = null;
+  if (workspaces.length) {
+    for (const kind of PRIMARY_ORDER) {
+      primary = workspaces.find((w) => w.kind === kind);
+      if (primary) break;
+    }
+    primary = primary ?? workspaces[0];
+  }
+
+  const base = primary ?? own;
+  const language = base.language;
+  const packageManager =
+    language === "python" ? pythonPackageManager(root)
+      : language === "go" ? "go"
+        : language === "rust" ? "cargo"
+          : language ? jsPackageManager(root) : null;
+
+  let testCommand = null;
+  let buildCommand = null;
+  let commandCwd = null;
+  const primaryScripts = primary?.pkg?.scripts ?? {};
+
+  if (!isPlaceholder(scripts.test)) testCommand = `${packageManager} test`;
+  else if (primary && !isPlaceholder(primaryScripts.test)) {
+    testCommand = `${packageManager} test`;
+    commandCwd = primary.path;
+  } else if (language === "python") {
+    const hasTests = ["tests", "test", "pytest.ini"].some((name) => existsSync(join(root, name)));
+    if (hasTests) testCommand = pythonTestCommand(root, packageManager);
+  } else if (language === "go") testCommand = "go test ./...";
+  else if (language === "rust") testCommand = "cargo test";
+
+  if (!isPlaceholder(scripts.build)) buildCommand = `${packageManager} run build`;
+  else if (primary && !isPlaceholder(primaryScripts.build)) {
+    buildCommand = `${packageManager} run build`;
+    commandCwd = commandCwd ?? primary.path;
+  } else if (language === "go") buildCommand = "go build ./...";
+  else if (language === "rust") buildCommand = "cargo build";
+
+  const buildDirs = buildOutputDirs(root);
+  if (primary) buildDirs.push(...buildOutputDirs(root, primary.path));
+
+  return {
+    kind: base.kind,
+    framework: base.framework,
+    language,
+    packageManager,
+    testCommand,
+    buildCommand,
+    commandCwd,
+    buildDirs,
+    hasPackageJson: Boolean(pkg),
+    workspaces: workspaces.map(({ path, kind, framework }) => ({ path, kind, framework })),
+    primary: primary?.path ?? null,
+  };
+}

package/lib/fixes.js

@@ -0,0 +1,90 @@
+// The first run offers to fix the top problem it found, so a person sees the whole
+// factory work on their own project. Only problems with a clear, small, checkable fix are
+// offered; personal-data and offline findings are for a person to judge.
+
+function find(results, id) {
+  return results.find((result) => result.id === id);
+}
+
+export function pickFix(results) {
+  const secrets = find(results, "secrets");
+  if (secrets?.status === "fail") {
+    const hit = secrets.details.find((detail) => /:\d+\s{2}/.test(detail));
+    if (hit) {
+      const where = hit.split(/\s{2}/)[0];
+      return {
+        id: "secret",
+        requires: ["secrets"],
+        problem: `A credential is written in the code at ${where}`,
+        title: "move a credential out of the code",
+        job:
+          `Move the credential at ${where} out of the code. Read it from an environment variable instead, ` +
+          "named for what it is for, and add that name with an empty value to .env.example. Never print, " +
+          "log or copy the value, and never put it in the spec, the plan, a test or a commit message. " +
+          "Note for the person that the old value must be changed (rotated), because it is in the git history.",
+      };
+    }
+    if (secrets.details.some((detail) => detail.includes(".env is tracked by git"))) {
+      return {
+        id: "env",
+        requires: ["secrets"],
+        problem: ".env, which holds secrets, is tracked by git",
+        title: "stop tracking .env in git",
+        job:
+          "Stop tracking .env in git (git rm --cached .env, keeping the file on disk), add .env to " +
+          ".gitignore, and add a .env.example with the variable names only, never the values. Note for " +
+          "the person that every value in it must be changed (rotated), because it is in the git history.",
+      };
+    }
+  }
+
+  const proof = find(results, "test-proof");
+  if (proof?.status === "fail") {
+    const empty = proof.details.find((detail) => /no assertion/.test(detail));
+    if (empty) {
+      const file = empty.split(":")[0];
+      return {
+        id: "assertions",
+        requires: ["tests", "test-proof"],
+        problem: `The tests in ${file} never check anything`,
+        title: "make the tests in one file prove something",
+        job:
+          `Make the tests in ${file} prove something. Each test should check the outcome (the data ` +
+          "written, the value returned, the record read back), not only that the code ran or what the " +
+          "screen says. Run the tests and show that each new check fails if the code it covers is broken.",
+      };
+    }
+    if (/No tests found/.test(proof.summary)) {
+      return {
+        id: "first-test",
+        requires: ["tests", "test-proof"],
+        problem: "This project has no automated tests, so nothing can be proven",
+        title: "add the first automated test",
+        job:
+          "Add the first automated test for the most important thing this project does, with the usual " +
+          "test tool for its stack. Add a test command to the project if it has none, so " +
+          '"factory verify --deep" can run it. The test checks an outcome, not a label on the screen.',
+      };
+    }
+  }
+  return null;
+}
+
+// A few lines a person can paste to their team. File names and line numbers only, never
+// a value.
+export function fixSummary({ project, fix, run, approval, diffStat, review }) {
+  const proved = run.results.filter((result) => result.kind === "proven" && result.status === "pass");
+  const notChecked = run.results.filter((result) => result.status === "na" || result.status === "not-run");
+  const lines = [
+    `factory: ${project}`,
+    `Found: ${fix.problem}.`,
+    `Fixed: ${fix.title}${approval ? `, approved by ${approval.approvedBy}` : ""}.`,
+  ];
+  if (diffStat) lines.push(`Changed: ${diffStat}`);
+  if (proved.length) lines.push(`Proved by: ${proved.map((result) => result.title.toLowerCase()).join(", ")}.`);
+  if (review) lines.push(`Review: ${review.summary}.`);
+  if (review?.unproven?.length) lines.push(`For a person to check: ${review.unproven.join("; ")}`);
+  if (notChecked.length) lines.push(`Not checked: ${notChecked.map((result) => result.title.toLowerCase()).join(", ")}.`);
+  lines.push("Made with factory: npx @next-generation-collective/factory");
+  return `${lines.join("\n")}\n`;
+}

package/lib/interview.js

@@ -0,0 +1,64 @@
+export const QUESTIONS = [
+  {
+    key: "problem",
+    q: "What is wrong today? One sentence.",
+    hint: "the problem, not the solution",
+  },
+  {
+    key: "who",
+    q: "Who feels it, and what do they do instead right now?",
+    hint: "the person, not the department",
+  },
+  {
+    key: "outcome",
+    q: "How will you know it works? Name one result you can check.",
+    hint: "the booking exists, the message arrives, the file is in storage",
+  },
+  {
+    key: "never",
+    q: "What must never break while we change this?",
+    hint: "the thing you would be called about",
+  },
+  {
+    key: "people",
+    q: "Who else sees or depends on this?",
+    hint: "a second account, an admin, a client, a funder",
+  },
+  {
+    key: "states",
+    q: "Which situations worry you?",
+    hint: "offline, slow, two people at once, no permission, small screen",
+  },
+  {
+    key: "out",
+    q: "What is out of scope for this change?",
+    hint: "what we are deliberately not doing",
+  },
+];
+
+// Asks each question in turn. Only "problem" must be answered; the rest may be skipped.
+export async function askList(rl, questions, { log = () => {} } = {}) {
+  const answers = {};
+  for (const item of questions) {
+    log("");
+    log(item.q);
+    if (item.hint) log(`(${item.hint})`);
+    let answer = "";
+    while (!answer) {
+      answer = (await rl.question("> ")).trim();
+      if (!answer) {
+        if (item.key === "problem") {
+          log("One sentence is enough. The spec needs a problem.");
+          continue;
+        }
+        break;
+      }
+    }
+    answers[item.key] = answer;
+  }
+  return answers;
+}
+
+export function askQuestions(rl, options = {}) {
+  return askList(rl, QUESTIONS, options);
+}

package/lib/journeys.js

@@ -0,0 +1,222 @@
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { presetName } from "./agents.js";
+
+const WINDOWS = process.platform === "win32";
+const LOCAL = /^(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])$/i;
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// MCP servers that drive a browser: in the project (.mcp.json, .claude/settings.json) and
+// in Claude Code's own config (~/.claude.json: for every project, and for this one). Only
+// names are read, never their settings' values.
+export function browserServers(root, home = homedir()) {
+  const found = new Map();
+  const add = (servers) => {
+    for (const [name, settings] of Object.entries(servers ?? {})) {
+      const text = `${name} ${JSON.stringify(settings ?? {})}`;
+      const browser = /chrome|chromium/i.test(text) ? "chrome" : /firefox/i.test(text) ? "firefox" : null;
+      if (browser && !found.has(name)) found.set(name, { name, browser });
+    }
+  };
+  add(readJson(join(root, ".mcp.json"))?.mcpServers);
+  add(readJson(join(root, ".claude", "settings.json"))?.mcpServers);
+  const user = readJson(join(home, ".claude.json"));
+  add(user?.projects?.[resolve(root)]?.mcpServers);
+  add(user?.mcpServers);
+  return [...found.values()];
+}
+
+// Which tool the agent uses to work the app like a person, and what it may run.
+export function pickDriver(root, analysis, config, { home } = {}) {
+  if (config.journeys?.enabled === false) return { driver: null, reason: "journeys.enabled is false in factory.config.json" };
+  const kind = analysis.stack.kind;
+  if (kind === "web") {
+    if (analysis.drivers.includes("playwright")) return { driver: "playwright", tools: ["Bash(npx playwright:*)"] };
+    const servers = browserServers(root, home);
+    const pick = servers.find((server) => server.browser === "chrome") ?? servers.find((server) => server.browser === "firefox");
+    if (pick) return { driver: `${pick.browser}-devtools-mcp`, server: pick.name, tools: [`mcp__${pick.name}`] };
+    return {
+      driver: null,
+      reason: "No browser tool found. Add the Chrome DevTools or Firefox DevTools MCP server to your agent, or Playwright to the project",
+    };
+  }
+  if (kind === "mobile") {
+    if (analysis.drivers.includes("maestro")) return { driver: "maestro", tools: ["Bash(maestro:*)", "Bash(./scripts/e2e.sh:*)"] };
+    return { driver: null, reason: "No Maestro flows found (.maestro/); phone journeys need Maestro and a running simulator" };
+  }
+  return { driver: null, reason: "Not a website or phone app" };
+}
+
+// The agent that walks the journeys. Claude Code is given exactly the driver's tools;
+// other agents need agent.journeys set to a command that can drive the browser.
+export function journeyAgent(config, info) {
+  if (config.agent.journeys) return { ...config, agent: { ...config.agent.journeys } };
+  if (presetName(config.agent.command) !== "claude") return null;
+  return { ...config, agent: { ...config.agent, args: [...(config.agent.args ?? []), "--allowedTools", ...info.tools] } };
+}
+
+export function appUrlAllowed(url, config) {
+  try {
+    return LOCAL.test(new URL(url).hostname) || config.checks?.allowRemoteApp === true;
+  } catch {
+    return false;
+  }
+}
+
+// How to start the app: the dev or start script through the package manager, so local
+// binaries are on the path.
+export function startCommand(root, stack) {
+  for (const base of ["", stack.primary].filter((b) => b !== null && b !== undefined)) {
+    const scripts = readJson(join(root, base, "package.json"))?.scripts ?? {};
+    const pm = stack.packageManager ?? "npm";
+    if (scripts.dev) return { command: `${pm} run dev`, cwd: base || null };
+    if (scripts.start) return { command: `${pm} run start`, cwd: base || null };
+  }
+  return null;
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function httpUp(url) {
+  const probe = "fetch(process.argv[1]).then((r) => process.exit(r.status < 500 ? 0 : 1), () => process.exit(1))";
+  return spawnSync(process.execPath, ["-e", probe, url], { timeout: 5000, stdio: "ignore" }).status === 0;
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// A port nothing is using, so the app under test never collides with one already running
+// (a person's own dev server is often on 3000).
+export function freePort() {
+  const script = 'const s=require("net").createServer();s.listen(0,"127.0.0.1",()=>{process.stdout.write(String(s.address().port));s.close()})';
+  const run = spawnSync(process.execPath, ["-e", script], { encoding: "utf8", timeout: 5000 });
+  const port = Number.parseInt(run.stdout, 10);
+  return Number.isFinite(port) ? port : 4317;
+}
+
+const LOCAL_URL = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]):\d+/g;
+
+// Starts the app in the background on its own port, writing its output to logFile, and
+// waits until it answers. It trusts only the address this app prints, or the port it was
+// given; an address that already answered before the app started belongs to something
+// else, and is never used.
+export function startApp(root, { command, cwd }, { logFile, url = null, timeoutSeconds = 60 } = {}) {
+  if (url && httpUp(url)) {
+    return {
+      error: `something is already answering at ${url}, perhaps another copy of the app. Stop it, or change checks.appUrl`,
+      stop: () => {},
+    };
+  }
+  const port = freePort();
+  const fd = openSync(logFile, "w");
+  const child = spawn(command, {
+    cwd: cwd ? join(root, cwd) : root,
+    shell: true,
+    detached: !WINDOWS,
+    stdio: ["ignore", fd, fd],
+    env: { ...process.env, BROWSER: "none", PORT: String(port) },
+  });
+  closeSync(fd);
+  child.unref();
+
+  const stop = () => {
+    try {
+      if (WINDOWS) spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+      else process.kill(-child.pid, "SIGTERM");
+    } catch {}
+  };
+
+  const ours = `http://localhost:${port}`;
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  while (Date.now() < deadline) {
+    if (!alive(child.pid)) return { error: "the app stopped before it answered", stop };
+    const printed = [...readFileSync(logFile, "utf8").matchAll(LOCAL_URL)].map((m) => m[0].replace("0.0.0.0", "localhost"));
+    const candidates = [...new Set([url, ...printed, ours].filter(Boolean))];
+    const answering = candidates.find((candidate) => httpUp(candidate));
+    if (answering) return { url: answering, port, stop };
+    sleep(1000);
+  }
+  stop();
+  return { error: `the app did not answer within ${timeoutSeconds} seconds`, stop };
+}
+
+function rows(text) {
+  return String(text)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("|") && !/^\|[\s|:-]+\|$/.test(line))
+    .map((line) =>
+      line
+        .slice(1, -1)
+        .split("|")
+        .map((cell) => cell.trim()),
+    )
+    .filter((cells) => cells.length >= 4 && !/^check$/i.test(cells[0]));
+}
+
+const result = (status, summary, details = [], evidence = []) => ({
+  id: "journeys",
+  title: "Used the app",
+  kind: "proven",
+  status,
+  summary,
+  details,
+  evidence,
+});
+
+export function journeysResultNa(reason) {
+  return result("na", reason);
+}
+
+export function journeysResultNotRun(reason, details = [], evidence = []) {
+  return result("not-run", reason, details, evidence);
+}
+
+// Every journey marked PASS must point at a screenshot (or, for Maestro, an output file)
+// that exists. A claim with no picture is not proof.
+export function checkJourneys(root, dir) {
+  const file = join(dir, "journeys.md");
+  const shown = (path) => path.replace(`${root}/`, "");
+  if (!existsSync(file)) return result("fail", "No journeys recorded: the agent did not write journeys.md");
+  const all = rows(readFileSync(file, "utf8"));
+  if (!all.length) return result("fail", "journeys.md has no journeys in its table", [], [shown(file)]);
+  if (all.every((cells) => /^skip$/i.test(cells[3]))) return result("na", "Nothing a person sees changed", [], [shown(file)]);
+
+  const problems = [];
+  let passed = 0;
+  for (const [check, , saw, verdict, picture = ""] of all) {
+    if (/^skip$/i.test(verdict)) continue;
+    if (/^fail$/i.test(verdict)) {
+      problems.push(`${check}: FAIL. ${saw}`);
+      continue;
+    }
+    const path = picture.replace(/^`|`$/g, "");
+    const full = isAbsolute(path) ? path : existsSync(join(root, path)) ? join(root, path) : join(dir, path);
+    let ok = false;
+    try {
+      ok = Boolean(path) && statSync(full).size > 0;
+    } catch {}
+    if (/^pass$/i.test(verdict) && ok) passed++;
+    else problems.push(`${check}: marked ${verdict || "nothing"} with no screenshot at ${path || "(none given)"}`);
+  }
+
+  if (problems.length) return result("fail", `${problems.length} ${problems.length === 1 ? "journey" : "journeys"} not proven`, problems, [shown(file)]);
+  return result("pass", `${passed} ${passed === 1 ? "journey" : "journeys"} worked, each with a screenshot`, [], [shown(file)]);
+}