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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Next-Gen Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @next-generation-collective/factory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**It checks the work before it says done, and it remembers every mistake.**
+
+A command that works with the AI coding tool you already use: Claude Code, Codex, Gemini
+CLI or OpenCode. It plans each change with you, has your AI build it, runs your tests, uses
+the app like a person, has a separate AI session review it, and reports only what it proved.
+
+A [Next-Gen Collective](https://github.com/next-generation-collective) tool. Node 20 or newer.
+
+## Try it
+
+```bash
+cd your-project
+npx @next-generation-collective/factory
+```
+
+In about a second it shows what your project can prove: credentials in the code, tests
+that check nothing, no tests at all, and more. No account, no questions, nothing written
+into your project. If it finds a problem and you have an AI tool installed, it offers to
+fix it: you approve a short plan first.
+
+Give it a job:
+
+```bash
+npx @next-generation-collective/factory "add a booking form that survives a reload"
+```
+
+Or install it:
+
+```bash
+npm install -g @next-generation-collective/factory
+factory
+```
+
+## A job, step by step
+
+1. **Spec from your code.** Every screen state and how each check will be proven. Guesses
+   are marked `Assumed:`. It asks nothing, except two questions for login, money or
+   personal data.
+2. **Your approval**, recorded with a fingerprint. Editing the spec later makes it stale.
+3. **Plan, tasks, build.** Your AI may edit files in the project, not run commands.
+4. **The factory's checks**: your tests and build, secrets, tests that prove nothing, and
+   more. Failures go back to the builder.
+5. **Using the app** in Chrome or Firefox (or Playwright, or Maestro), a screenshot per check.
+6. **An independent review** by a separate session, a verdict for every acceptance check.
+7. **The report**: what passed, what a person must look at, what was not checked.
+
+Nothing is committed for you.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `factory` | What the project can prove; then offers to fix the top problem |
+| `factory "..."` | A job, from spec to review |
+| `factory approve [name]` | Read what matters in a spec, then approve it |
+| `factory build` | Plan, build, check, use the app, review (resumes where it stopped) |
+| `factory verify [--deep] [--app] [--json]` | The checks alone |
+| `factory review [--base=ref]` | The independent review alone |
+| `factory report` | A one-page handover |
+| `factory status`, `factory doctor` | The state of things; what was detected |
+| `factory lesson new` | Turn a real failure into a dated lesson |
+
+Exit codes: `0` nothing proven wrong; `1` a proven failure, or a command could not do its
+job; `2` no agent found (the prompt is saved in `.factory/prompts/`).
+
+## Honest limits
+
+It cannot prove your software is correct, and it never says "bug-free", "secure" or
+"compliant". It does not set up a phone simulator. Screenshots show what the AI saw on
+your machine. The reviewer is an AI too; what it cannot prove is marked for a person.
+
+Full guide, limits and security notes:
+<https://github.com/next-generation-collective/factory>
+
+## Licence
+
+MIT.

package/bin/factory.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from "../lib/cli.js";
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((error) => {
+    console.error(error?.stack ?? error);
+    process.exit(1);
+  });

package/lib/agent.js

@@ -0,0 +1,121 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { AGENT_ORDER, PRESETS } from "./agents.js";
+import { ensure } from "./config.js";
+
+const WINDOWS = process.platform === "win32";
+const SAFE_COMMAND = /^[A-Za-z0-9._:/\\ ()-]+$/;
+const INLINE_LIMIT = 30000;
+const probes = new Map();
+
+// factory.config.json is trusted like a package.json script, but a command name with
+// shell syntax in it is refused, because Windows runs agents through the shell.
+export function safeCommand(command) {
+  return typeof command === "string" && SAFE_COMMAND.test(command);
+}
+
+function quoteForWindows(arg) {
+  if (/^[A-Za-z0-9._:/\\=@+-]+$/.test(arg)) return arg;
+  return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`;
+}
+
+// Windows: an .exe starts directly; a .cmd or .bat (how npm installs claude, codex and
+// gemini) needs the shell, so its path is quoted. Elsewhere, start it directly.
+function launch(command) {
+  if (!WINDOWS) return { file: command, shell: false };
+  let full = command;
+  if (!/[\\/]/.test(command)) {
+    const exts = /\.[a-z]+$/i.test(command) ? [""] : (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";");
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+      const hit = exts.map((ext) => join(dir, command + ext)).find((candidate) => existsSync(candidate));
+      if (hit) {
+        full = hit;
+        break;
+      }
+    }
+  }
+  if (/\.(?:cmd|bat)$/i.test(full)) return { file: quoteForWindows(full), shell: true };
+  return { file: full, shell: false };
+}
+
+function probe(command) {
+  if (!probes.has(command)) {
+    const { file, shell } = launch(command);
+    const run = spawnSync(file, ["--version"], {
+      encoding: "utf8",
+      timeout: 10000,
+      stdio: ["ignore", "pipe", "ignore"],
+      shell,
+    });
+    const first = String(run.stdout ?? "").trim().split("\n")[0];
+    probes.set(command, run.status === 0 ? first || "found" : null);
+  }
+  return probes.get(command);
+}
+
+export function agentVersion(config) {
+  const command = config?.agent?.command;
+  return safeCommand(command) ? probe(command) : null;
+}
+
+export function agentAvailable(config) {
+  return agentVersion(config) != null;
+}
+
+// The first coding agent installed on this machine, with its preset, or null.
+export function detectAgent() {
+  for (const name of AGENT_ORDER) {
+    if (probe(name) != null) return { ...PRESETS[name], args: [...PRESETS[name].args] };
+  }
+  return null;
+}
+
+export function agentInvocation(args, prompt, promptFile) {
+  const list = (args ?? []).map(String);
+  const inline = list.some((arg) => arg.includes("{prompt}"));
+  const usesFile = list.some((arg) => arg.includes("{promptFile}"));
+  return {
+    args: list.map((arg) => arg.replaceAll("{promptFile}", promptFile ?? "").replaceAll("{prompt}", prompt)),
+    stdin: inline || usesFile ? null : prompt,
+    inline,
+  };
+}
+
+export function runAgent(root, prompt, config, promptFile) {
+  const command = config.agent.command;
+  if (!safeCommand(command)) {
+    console.error(`Refusing to run agent.command "${command}": use the program's name or path only.`);
+    return false;
+  }
+
+  const call = agentInvocation(config.agent.args, prompt, promptFile);
+  if (call.inline && WINDOWS) {
+    console.error("{prompt} in agent.args does not work on Windows. Remove it and the prompt goes on stdin.");
+    return false;
+  }
+  if (call.inline && prompt.length > INLINE_LIMIT) {
+    console.error(
+      `Warning: the prompt is ${prompt.length} characters on the command line. Remove {prompt} from agent.args to send it on stdin.`,
+    );
+  }
+
+  const { file, shell } = launch(command);
+  const options = { cwd: root, shell, maxBuffer: 64 * 1024 * 1024 };
+  if (call.stdin != null) {
+    options.input = call.stdin;
+    options.stdio = ["pipe", "inherit", "inherit"];
+  } else {
+    options.stdio = "inherit";
+  }
+  const args = shell ? call.args.map(quoteForWindows) : call.args;
+  const run = spawnSync(file, args, options);
+  return run.status === 0;
+}
+
+export function savePrompt(root, name, prompt) {
+  const p = ensure(root);
+  const file = join(p.prompts, `${name}.md`);
+  writeFileSync(file, prompt);
+  return file;
+}

package/lib/agents.js

@@ -0,0 +1,42 @@
+// How each coding agent takes a prompt. No placeholder in args means the prompt goes on
+// stdin; {promptFile} is the saved prompt's path; {prompt} puts the text itself in an
+// argument (kept for custom configs, but Windows cuts command lines off at 32 KB).
+// Each preset may edit files inside the project and nothing more; it cannot run shell
+// commands on its own (the factory runs the checks). To let an agent run commands, add
+// its own flags to agent.args in factory.config.json.
+export const PRESETS = {
+  // claude -p reads the prompt from stdin; acceptEdits allows edits, not commands.
+  claude: { command: "claude", args: ["-p", "--permission-mode", "acceptEdits"] },
+  // codex exec reads stdin when no prompt is given; workspace-write keeps writes in the project.
+  codex: { command: "codex", args: ["exec", "-s", "workspace-write"] },
+  // gemini -p appends its text to what arrives on stdin; auto_edit allows edits only.
+  gemini: { command: "gemini", args: ["--approval-mode", "auto_edit", "-p", "Follow the instructions above exactly."] },
+  opencode: {
+    command: "opencode",
+    args: ["run", "--file", "{promptFile}", "Read the attached file and follow it exactly."],
+  },
+};
+
+export const AGENT_ORDER = ["claude", "codex", "gemini", "opencode"];
+
+const LEGACY_CLAUDE = [JSON.stringify(["-p", "{prompt}"]), JSON.stringify(["-p"])];
+
+export function presetName(command) {
+  const name = String(command ?? "")
+    .split(/[\\/]/)
+    .pop()
+    .toLowerCase()
+    .replace(/\.(?:cmd|exe|bat)$/, "");
+  return PRESETS[name] ? name : null;
+}
+
+// Fills in args for a known agent when the config names only the command, and moves
+// configs written by 0.2.0 (claude -p {prompt}) and early 0.3.0 (claude -p) to the preset.
+export function normaliseAgent(agent) {
+  const command = agent?.command ?? PRESETS.claude.command;
+  const preset = presetName(command);
+  let args = agent?.args;
+  if (!Array.isArray(args)) args = preset ? PRESETS[preset].args : [];
+  if (preset === "claude" && LEGACY_CLAUDE.includes(JSON.stringify(args))) args = PRESETS.claude.args;
+  return { ...agent, command, args: [...args] };
+}

package/lib/analyse.js

@@ -0,0 +1,252 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { detectStack } from "./detect.js";
+import { browserServers } from "./journeys.js";
+import { listSpecs } from "./spec.js";
+import { isTestFile, plural, rel, walk } from "./util.js";
+
+const NOTABLE = [
+  "expo", "react-native", "next", "nuxt", "astro", "svelte", "vue", "@angular/core", "react",
+  "@supabase/supabase-js", "firebase", "drizzle-orm", "prisma", "@prisma/client", "mongoose",
+  "express", "hono", "fastify", "@nestjs/core", "tailwindcss", "stripe",
+];
+const PY_NOTABLE = ["django", "fastapi", "flask", "sqlalchemy", "pydantic", "pytest"];
+const TEMPLATE_README = /turborepo starter|create react app|create-next-app|expo app|vite \+ react|next\.js app|bootstrapped with/i;
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+const count = plural;
+
+function underPrefix(prefix) {
+  return (path) => !prefix || path === prefix || path.startsWith(`${prefix}/`);
+}
+
+// Screens a person can open: Next.js pages, Expo Router files, React Native screens.
+function countScreens(relFiles, stack) {
+  const inPrimary = underPrefix(stack.primary);
+  const code = relFiles.filter((path) => /\.[cm]?[jt]sx?$/.test(path) && !isTestFile(path) && inPrimary(path));
+  if (stack.kind === "web") {
+    return code.filter(
+      (path) =>
+        /(?:^|\/)app\/(?:.+\/)?page\.[cm]?[jt]sx?$/.test(path) ||
+        (/(?:^|\/)pages\/.+/.test(path) && !/(?:^|\/)pages\/(?:_app|_document|_error|api\/)/.test(path)),
+    ).length;
+  }
+  if (stack.kind === "mobile") {
+    return code.filter(
+      (path) =>
+        /(?:^|\/)screens\/[^/]+\.[jt]sx?$/.test(path) ||
+        /(?:^|\/)screens\/[^/]+\/index\.[jt]sx?$/.test(path) ||
+        /(?:^|\/)app\/(?:[^/]+\/)*[^_+/][^/]*\.[jt]sx?$/.test(path),
+    ).length;
+  }
+  return 0;
+}
+
+function migrationInfo(root, stack) {
+  const bases = ["", ...stack.workspaces.map((w) => `${w.path}/`)];
+  const found = [];
+  for (const base of bases) {
+    for (const name of ["supabase/migrations", "migrations", "db/migrations", "prisma/migrations", "drizzle"]) {
+      const dir = `${base}${name}`;
+      if (!existsSync(join(root, dir))) continue;
+      try {
+        const files = readdirSync(join(root, dir)).filter((file) => /\.(?:sql|ts|js|prisma)$/.test(file));
+        if (files.length) found.push(`${dir} (${files.length})`);
+      } catch {}
+    }
+    if (existsSync(join(root, `${base}prisma`, "schema.prisma"))) found.push(`${base}prisma/schema.prisma`);
+  }
+  return found;
+}
+
+function envKeys(root, stack) {
+  const bases = ["", ...stack.workspaces.map((w) => `${w.path}/`)];
+  const keys = new Set();
+  for (const base of bases) {
+    for (const name of [".env.example", ".env.sample", ".env.template"]) {
+      const file = join(root, `${base}${name}`);
+      if (!existsSync(file)) continue;
+      for (const match of readFileSync(file, "utf8").matchAll(/^([A-Z0-9_]+)\s*=/gm)) keys.add(match[1]);
+    }
+  }
+  return [...keys];
+}
+
+function authFiles(relFiles) {
+  return relFiles
+    .filter((file) => /(?:^|[\\/_-])(?:auth|login|session|supabase)[^\\/]*\.[cm]?[jt]sx?$/i.test(file) && !isTestFile(file))
+    .slice(0, 6);
+}
+
+function packageDrivers(deps) {
+  const known = [
+    ["@playwright/test", "playwright"],
+    ["playwright", "playwright"],
+    ["puppeteer", "puppeteer"],
+    ["cypress", "cypress"],
+    ["webdriverio", "webdriverio"],
+    ["selenium-webdriver", "selenium"],
+  ];
+  const found = [];
+  for (const [dep, label] of known) {
+    if (deps.includes(dep) && !found.includes(label)) found.push(label);
+  }
+  return found;
+}
+
+function mcpBrowsers(root) {
+  const found = [];
+  for (const name of [".mcp.json", join(".claude", "settings.json")]) {
+    const file = join(root, name);
+    if (!existsSync(file)) continue;
+    let text = readFileSync(file, "utf8");
+    try {
+      text = JSON.stringify(JSON.parse(text));
+    } catch {}
+    if (/(?:chrome|chromium)/i.test(text)) found.push("chrome-devtools-mcp");
+    if (/firefox/i.test(text)) found.push("firefox-devtools-mcp");
+    if (/(?:safari|webkit)/i.test(text)) found.push("safari");
+  }
+  return found;
+}
+
+function drivers(root, deps, stack) {
+  const found = [];
+  const bases = ["", ...stack.workspaces.map((w) => `${w.path}/`)];
+  for (const base of bases) {
+    if (["playwright.config.ts", "playwright.config.js"].some((name) => existsSync(join(root, `${base}${name}`)))) {
+      found.push("playwright");
+    }
+    if (["cypress.config.ts", "cypress.config.js"].some((name) => existsSync(join(root, `${base}${name}`)))) {
+      found.push("cypress");
+    }
+  }
+  found.push(...packageDrivers(deps), ...mcpBrowsers(root));
+  if (bases.some((base) => [".maestro", "maestro"].some((name) => existsSync(join(root, `${base}${name}`))))) {
+    found.push("maestro");
+  }
+  return [...new Set(found)];
+}
+
+function readmeLine(root, stack) {
+  for (const base of ["", stack.primary ? `${stack.primary}/` : null].filter((b) => b !== null)) {
+    const file = ["README.md", "readme.md", "README"].map((name) => join(root, `${base}${name}`)).find((f) => existsSync(f));
+    if (!file) continue;
+    const line = readFileSync(file, "utf8")
+      .split("\n")
+      .map((item) => item.trim())
+      .find((item) => item && !item.startsWith("#") && !item.startsWith("<") && !item.startsWith("!["));
+    if (line && !TEMPLATE_README.test(line)) return line.slice(0, 160);
+  }
+  return "";
+}
+
+function describeStack(stack) {
+  const name = (w) => (w.kind === "api" && w.framework ? `${w.framework} api` : w.framework ?? w.kind);
+  if (stack.workspaces.length) {
+    const ordered = [...stack.workspaces].sort((a, b) => (b.path === stack.primary) - (a.path === stack.primary));
+    const kinds = [...new Set(ordered.filter((w) => w.kind !== "script").map(name))];
+    const paths = stack.workspaces.map((w) => w.path);
+    const shown = paths.length > 4 ? `${paths.slice(0, 4).join(", ")}, and ${paths.length - 4} more` : paths.join(", ");
+    return `${kinds.join(" + ") || "javascript"} (monorepo: ${shown}${stack.packageManager ? `, ${stack.packageManager}` : ""})`;
+  }
+  const what = stack.framework ?? stack.kind;
+  const language = stack.language && stack.language !== stack.framework ? ` / ${stack.language}` : "";
+  return `${what}${language}${stack.packageManager ? `, ${stack.packageManager}` : ""}`;
+}
+
+function notableLibraries(root, stack, pkg) {
+  const primaryPkg = stack.primary ? readJson(join(root, stack.primary, "package.json")) : null;
+  const deps = new Set(
+    [pkg, primaryPkg].flatMap((p) => Object.keys({ ...(p?.dependencies ?? {}), ...(p?.devDependencies ?? {}) })),
+  );
+  const found = NOTABLE.filter((name) => deps.has(name));
+  if (stack.language === "python") {
+    const text = ["pyproject.toml", "requirements.txt"]
+      .map((name) => join(root, name))
+      .filter((file) => existsSync(file))
+      .map((file) => readFileSync(file, "utf8").toLowerCase())
+      .join("\n");
+    found.push(...PY_NOTABLE.filter((name) => new RegExp(`\\b${name}\\b`).test(text)));
+  }
+  return found.length ? found : [...deps].slice(0, 8);
+}
+
+export function analyseProject(root) {
+  const stack = detectStack(root);
+  const pkg = existsSync(join(root, "package.json")) ? readJson(join(root, "package.json")) : null;
+  const files = walk(root);
+  const relFiles = files.map((file) => rel(root, file).split("\\").join("/"));
+  const screens = countScreens(relFiles, stack);
+  const tests = relFiles.filter(isTestFile);
+  const specs = listSpecs(root);
+  const migrations = migrationInfo(root, stack);
+  const env = envKeys(root, stack);
+  const auth = authFiles(relFiles);
+  const allDeps = [pkg, ...stack.workspaces.map((w) => readJson(join(root, w.path, "package.json")))].flatMap((p) =>
+    Object.keys({ ...(p?.dependencies ?? {}), ...(p?.devDependencies ?? {}) }),
+  );
+  const availableDrivers = drivers(root, allDeps, stack);
+  const readme = readmeLine(root, stack);
+  const libraries = notableLibraries(root, stack, pkg);
+
+  const scripts = pkg?.scripts ?? {};
+  const primaryScripts = stack.primary ? readJson(join(root, stack.primary, "package.json"))?.scripts ?? {} : {};
+  const startCommand =
+    scripts.dev ??
+    scripts.start ??
+    primaryScripts.dev ??
+    primaryScripts.start ??
+    (stack.framework === "expo" ? "npx expo start" : null);
+
+  const label = describeStack(stack);
+  const counts = [count(files.length, "file")];
+  if (stack.kind === "web" || stack.kind === "mobile") counts.push(stack.kind === "web" ? count(screens, "page") : count(screens, "screen"));
+  counts.push(count(tests.length, "test file"));
+  if (specs.length) counts.push(count(specs.length, "spec"));
+
+  const run = [
+    startCommand && `Start: ${startCommand}`,
+    stack.testCommand && `Tests: ${stack.testCommand}${stack.commandCwd ? ` (in ${stack.commandCwd})` : ""}`,
+    stack.buildCommand && `Build: ${stack.buildCommand}`,
+  ].filter(Boolean);
+
+  // Short form, for the first run.
+  const summary = [label, counts.join(", ")];
+  if (run.length) summary.push(run.join("   "));
+  const data = [migrations.length && `Data: ${migrations.join(", ")}`, env.length && `Env keys: ${env.length} (names only)`].filter(Boolean);
+  if (data.length) summary.push(data.join("   "));
+  const usable = [...new Set([...availableDrivers, ...browserServers(root).map((server) => `${server.browser}-devtools-mcp`)])];
+  if (usable.length && (stack.kind === "web" || stack.kind === "mobile")) summary.push(`Can use the app with: ${usable.join(", ")}`);
+
+  // Long form, for the agent's brief.
+  const lines = [label, counts.join(", "), ...run];
+  if (libraries.length) lines.push(`Libraries: ${libraries.slice(0, 12).join(", ")}`);
+  if (migrations.length) lines.push(`Data: ${migrations.join(", ")}`);
+  if (auth.length) lines.push(`Auth: ${auth.join(", ")}`);
+  if (env.length) lines.push(`Env keys: ${env.slice(0, 15).join(", ")} (names only)`);
+  if (availableDrivers.length) lines.push(`Drivers: ${availableDrivers.join(", ")}`);
+  if (readme) lines.push(`README: ${readme}`);
+
+  return {
+    stack,
+    label,
+    summary,
+    lines,
+    brief: lines.join("\n"),
+    empty: files.length === 0,
+    screens,
+    tests,
+    specs,
+    env,
+    drivers: availableDrivers,
+    startCommand,
+  };
+}

package/lib/approval.js

@@ -0,0 +1,72 @@
+// What a person needs to read before approving a spec: the decisions left to them, every
+// guess the AI made, which states were covered, and the checks that will prove it.
+
+export function section(text, heading) {
+  const lines = String(text).split("\n");
+  const start = lines.findIndex((line) => new RegExp(`^##\\s+${heading}\\b`, "i").test(line.trim()));
+  if (start === -1) return "";
+  const body = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^##\s/.test(line)) break;
+    body.push(line);
+  }
+  return body.join("\n").trim();
+}
+
+export function assumedLines(text) {
+  return String(text)
+    .split("\n")
+    .map((line) => line.trim().replace(/^[-*]\s+/, ""))
+    .filter((line) => /^Assumed:/i.test(line) && !/\[anything decided/i.test(line));
+}
+
+export function coveredLine(text) {
+  return (
+    String(text)
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => /^Covered:/i.test(line) && !line.includes("[the states")) ?? ""
+  );
+}
+
+const NONE = /^(?:none\.?|n\/a\.?|-|\[.*\])$/i;
+
+export function approvalView(text) {
+  const open = section(text, "Open questions");
+  const checks = section(text, "Acceptance checks");
+  const assumed = assumedLines(text);
+  const covered = coveredLine(text);
+  const out = [];
+
+  if (open && !NONE.test(open)) out.push("Decide these first", indent(open), "");
+  if (assumed.length) out.push("The AI assumed", ...assumed.map((line) => `  ${line}`), "");
+  if (covered) out.push(`  ${covered}`, "");
+  if (checks) out.push("How it will be proven", indent(checks), "");
+
+  if (!out.length) {
+    const lines = String(text).split("\n");
+    out.push(...lines.slice(0, 32));
+    if (lines.length > 32) out.push(`... ${lines.length - 32} more lines`);
+  }
+  return out.join("\n").trimEnd();
+}
+
+function indent(block) {
+  return block
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+// Jobs where the code cannot know who else is affected or what must never break.
+const GUARDED =
+  /\b(?:log ?in|sign[ -]?in|sign[ -]?up|signup|password|auth\w*|payments?|pay|card|money|price|billing|checkout|personal|privacy|location|phone|e-?mail|other users?|block\w*|delete account|permissions?)\b/i;
+
+export function guardedTopics(line) {
+  return GUARDED.test(String(line));
+}
+
+export const GUARDED_QUESTIONS = [
+  { key: "people", q: "Who else sees or depends on this?", hint: "a second account, an admin, a client" },
+  { key: "never", q: "What must never break while we change this?", hint: "the thing you would be called about" },
+];