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

package/lib/util.js

@@ -0,0 +1,109 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, extname } from "node:path";
+
+const SKIP_DIRS = new Set([
+  ".git",
+  ".factory",
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "vendor",
+  "Pods",
+  ".expo",
+  ".turbo",
+  ".venv",
+  "venv",
+  "__pycache__",
+  "target",
+  ".idea",
+  ".vscode",
+]);
+
+const SKIP_EXT = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip", ".gz",
+  ".tar", ".mp4", ".mov", ".mp3", ".wav", ".woff", ".woff2", ".ttf", ".eot",
+  ".so", ".dylib", ".dll", ".exe", ".class", ".jar", ".lock", ".map",
+]);
+
+const SKIP_FILES = new Set([
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lockb",
+  "composer.lock",
+]);
+
+const MAX_BYTES = 1024 * 1024;
+
+export function walk(root, { skipDirs = SKIP_DIRS } = {}) {
+  const files = [];
+  const visit = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) visit(full);
+      } else if (entry.isFile()) {
+        if (SKIP_FILES.has(entry.name)) continue;
+        if (!SKIP_EXT.has(extname(entry.name).toLowerCase())) files.push(full);
+      }
+    }
+  };
+  visit(root);
+  return files;
+}
+
+export function readText(file) {
+  try {
+    if (statSync(file).size > MAX_BYTES) return null;
+    const text = readFileSync(file, "utf8");
+    return text.includes("\u0000") ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+export function isTestFile(file) {
+  const name = file.split(/[\\/]/).pop();
+  return (
+    /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(name) ||
+    /^test_.*\.py$/.test(name) ||
+    /_test\.(?:py|go)$/.test(name) ||
+    /[\\/]__tests__[\\/].*\.[cm]?[jt]sx?$/.test(file)
+  );
+}
+
+// Forward slashes on every machine, so reports and committed evidence read the same.
+export function rel(root, file) {
+  return (relative(root, file) || file).split("\\").join("/");
+}
+
+export const colors = {
+  enabled: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+  paint(code, text) {
+    return this.enabled ? `\u001b[${code}m${text}\u001b[0m` : String(text);
+  },
+  green: (t) => colors.paint("32", t),
+  red: (t) => colors.paint("31", t),
+  yellow: (t) => colors.paint("33", t),
+  dim: (t) => colors.paint("2", t),
+  bold: (t) => colors.paint("1", t),
+};
+
+// 1,695 on every machine, whatever the locale data Node was built with.
+export function formatCount(n) {
+  return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+export function plural(n, word) {
+  return `${formatCount(n)} ${word}${n === 1 ? "" : "s"}`;
+}

package/lib/verify.js

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { colors, rel } from "./util.js";
+import { ensure, paths, readConfig, writeState } from "./config.js";
+import { detectStack } from "./detect.js";
+import { runChecks } from "./checks.js";
+import { SPECS_DIR } from "./spec.js";
+
+export function label(result) {
+  if (result.status === "na") return "N/A";
+  if (result.status === "not-run") return "NOT RUN";
+  if (result.status === "pass") return result.kind === "flagged" ? "OK" : "PASS";
+  return result.kind === "flagged" ? "LOOK" : "FAIL";
+}
+
+export function paintLabel(result) {
+  const text = label(result).padEnd(8);
+  if (result.status === "fail" && result.kind === "proven") return colors.red(text);
+  if (result.status === "fail") return colors.yellow(text);
+  if (result.status === "pass") return colors.green(text);
+  return colors.dim(text);
+}
+
+// Where a spec's proof lives: in the spec folder, committed with the code. Without an
+// active spec there is nowhere shared to put it, so it stays in .factory/.
+export function specEvidenceDir(root, config) {
+  const name = config?.spec?.active;
+  if (!name || !existsSync(join(root, SPECS_DIR, name))) return null;
+  return join(root, SPECS_DIR, name, "evidence");
+}
+
+// save: false computes the result and writes nothing into the project. Command logs from
+// a deep pass go to the system temp folder instead.
+export function verify(root, { deep = false, config, save = true } = {}) {
+  const cfg = config ?? readConfig(root);
+  const detected = detectStack(root);
+  const stack = { ...detected };
+  if (stack.kind === "other" && cfg.kind && cfg.kind !== "other") stack.kind = cfg.kind;
+  const p = paths(root);
+  const logDir = save ? ensure(root).evidence : null;
+  const results = runChecks(root, { deep, config: cfg, stack, logDir });
+  const ok = !results.some((result) => result.kind === "proven" && result.status === "fail");
+  const at = new Date().toISOString();
+  const result = {
+    at,
+    deep,
+    ok,
+    project: cfg.name,
+    kind: stack.kind,
+    results,
+  };
+  if (!save) return { ...result, saved: false, jsonFile: null, mdFile: null };
+
+  const stamp = at.replace(/[:.]/g, "-");
+  const jsonFile = join(p.evidence, `verify-${stamp}.json`);
+  let mdFile = join(p.evidence, `verify-${stamp}.md`);
+  const specDir = specEvidenceDir(root, cfg);
+  const stored = { ...result, jsonFile: rel(root, jsonFile), mdFile: rel(root, mdFile) };
+
+  if (specDir) {
+    mkdirSync(specDir, { recursive: true });
+    mdFile = join(specDir, "verify-latest.md");
+    stored.mdFile = rel(root, mdFile);
+    writeFileSync(join(specDir, "verify-latest.json"), `${JSON.stringify(stored, null, 2)}\n`);
+  }
+
+  writeFileSync(jsonFile, `${JSON.stringify(stored, null, 2)}\n`);
+  writeFileSync(join(p.evidence, `verify-${stamp}.md`), renderEvidence(root, stored));
+  if (specDir) writeFileSync(mdFile, renderEvidence(root, stored));
+  writeFileSync(p.lastVerify, `${JSON.stringify(stored, null, 2)}\n`);
+  writeState(root, { lastVerify: at, lastOk: ok });
+
+  return {
+    ...stored,
+    saved: true,
+    jsonFile,
+    mdFile,
+    jsonRel: stored.jsonFile,
+    mdRel: stored.mdFile,
+  };
+}
+
+export function renderEvidence(root, run) {
+  const lines = [
+    `# Verification: ${run.project}`,
+    "",
+    `${new Date(run.at).toLocaleString()}: ${run.deep ? "deep pass (tests and build run)" : "fast pass"}`,
+    "",
+    "| Check | Result | Kind | What it found |",
+    "|---|---|---|---|",
+    ...run.results.map(
+      (result) => `| ${result.title} | ${label(result)} | ${result.kind} | ${result.summary} |`,
+    ),
+    "",
+    "## Details",
+    "",
+  ];
+
+  for (const result of run.results) {
+    lines.push(`### ${result.title}: ${label(result)}`, "");
+    if (!result.details.length) lines.push(result.summary, "");
+    else {
+      for (const detail of result.details) lines.push(`- ${detail}`);
+      lines.push("");
+    }
+    if (result.evidence.length) {
+      lines.push(`Evidence: ${result.evidence.map((file) => `[${file}](${file})`).join(", ")}`, "");
+    }
+  }
+
+  lines.push(
+    "## What this does not prove",
+    "",
+    "- It does not prove the software is correct or free of bugs.",
+    "- It does not prove compliance with POPIA or any other law.",
+    "- It does not know whether the design is good or the words are clear.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+export function formatResults(root, run, { header = true } = {}) {
+  const lines = header
+    ? [colors.bold(`factory verify: ${run.project}`) + colors.dim(`  ${run.deep ? "deep pass" : "fast pass"}`), ""]
+    : [];
+  const width = Math.max(...run.results.map((result) => result.title.length));
+
+  for (const result of run.results) {
+    lines.push(`  ${paintLabel(result)} ${result.title.padEnd(width)}   ${result.summary}`);
+    if (result.status === "fail" && result.kind === "proven" && result.details.length > 1) {
+      for (const detail of result.details.slice(0, 4)) lines.push(colors.dim(`             ${detail}`));
+    }
+  }
+
+  const failed = run.results.filter((result) => result.kind === "proven" && result.status === "fail");
+  const look = run.results.filter((result) => result.kind === "flagged" && result.status === "fail");
+
+  lines.push("");
+  if (failed.length) {
+    lines.push(colors.red(`NOT DONE: ${failed.length} ${failed.length === 1 ? "check" : "checks"} failed.`));
+  } else {
+    lines.push(colors.green("PASSED: the checks that ran found no proven problem."));
+  }
+  if (look.length) lines.push(colors.yellow(`${look.length} ${look.length === 1 ? "thing" : "things"} for a person to look at.`));
+  if (run.jsonFile) lines.push(colors.dim(`Evidence: ${rel(root, run.mdFile ?? run.jsonFile)}`));
+
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@next-generation-collective/factory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Checks the work you build with AI, proves it works, and learns from every builder. Built in the open, in Africa.",
+  "type": "module",
+  "bin": {
+    "factory": "bin/factory.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "template",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/next-generation-collective/factory.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/next-generation-collective/factory#readme",
+  "bugs": {
+    "url": "https://github.com/next-generation-collective/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "software-factory",
+    "ai-agents",
+    "verification",
+    "proof",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/template/constitution.md

@@ -0,0 +1,204 @@
+# Software Factory Constitution
+
+Every spec, plan and task list in this repo is checked against these rules. They were
+distilled from real delivery runs. Principle VI uses a reuse ladder.
+
+## Core Principles
+
+### I. Design before code
+No code is written until a spec says what problem it solves, for whom, and how we will know
+it works. Larger work also needs a design document: problem, constraints, approaches
+considered, the choice and why, risks, and how success is measured.
+
+### II. The data model is the hardest thing to change
+Features can be rewritten in a week. A wrong schema with real people's data in it lasts
+years. Every plan that stores data states the schema, what each index is for, and what
+would be painful to change once real people are in it.
+
+### III. Personal data and credentials come first
+Personal data is regulated: POPIA in South Africa, the local equivalent elsewhere. A plan
+that touches it states who can reach it, with what rights, and where the secret lives.
+Credentials live in your secret manager and nowhere else: never in code, specs, config
+files or chat. Security fixes on exposed personal data
+outrank all other work.
+
+### IV. "Closed" means verified
+Work is closed when it is fixed, written up and off the list. A fix with no check proving
+it works is not closed. Every task list ends with the step that proves the outcome.
+
+### V. Every incident gets a Correction of Error
+When something breaks or is found exposed, write a Correction of Error: what happened,
+timeline, who was affected, five whys to the real cause, and actions with named owners.
+No blame, no hedging.
+
+### VI. Build the least that works
+Every plan and every task stops at the first rung that holds:
+
+1. Does this need to exist? If not, skip it.
+2. Is it already in the target repo? Reuse it.
+3. Does the language's standard library do it? Use it.
+4. Does the platform (browser, phone, database) do it natively? Use it.
+5. Is a dependency already installed that does it? Use it.
+6. Has an open-source project already solved it, under a licence we may use? Adopt or
+   adapt it. Run `/find-existing` and record the result in the spec's `reuse.md`.
+7. Can it be one line? Make it one line.
+8. Only then: write the minimum that works.
+
+Read the code the change touches before choosing a rung. Validation at trust boundaries,
+data-loss handling, security and accessibility are never cut to make code smaller.
+A plan that writes a substantial new component must point to a `reuse.md` showing why
+rungs 1 to 6 failed. Code with no licence, or a GPL/AGPL licence, is never reused without
+the user's explicit agreement.
+
+### VII. Every state is designed, and every "done" is tested
+Quality is decided in the spec, not discovered in QA. For each screen or feature a spec
+says what the user sees and can do in each of these states, or marks it "not applicable"
+with a reason:
+
+| State | The question the spec answers |
+|---|---|
+| Loading | What shows while waiting? Nothing that later turns out wrong |
+| Empty | What shows when there is nothing yet, and what can the user do next? |
+| Error | What does a failure say, and how does the user retry? Never a misleading message |
+| Offline / slow | What happens with no network or a very slow one? |
+| No permission | What happens when location, camera or notifications are refused? |
+| Dark mode | Is every text readable (contrast at least 4.5:1)? |
+| Tapped twice | Can a double tap send twice, pay twice or open two copies? |
+| Back / cancel | Where does Back go? Does cancelling leave anything half-done? |
+| Small screen | Does it fit the smallest supported phone without hiding actions? |
+| Screen reader | Does every control have a label that says what it does? |
+
+Anything one account does that another account can see also answers two shared states
+(how to check them: `kit/expo-supabase-maestro/TWO-ACCOUNT.md`):
+
+| State | The question the spec answers |
+|---|---|
+| Other person | For each action (block, unsend, change photo, type, hide), what does the other account see, and how fast? Checked from a second account, not the one that acted |
+| Setting semantics | For each toggle: is it stored on the server or on this phone, and who does it affect (me, the people I talk to, everyone)? Checked from the other account. A setting that changes what others see lives on the server |
+
+A spec with an unanswered state does not go to planning. Every acceptance criterion
+becomes an automated check (a unit test or an end-to-end flow), written with the code,
+and the feature is done when its checks pass automatically on every change. Before
+handing work to a person, the AI runs the app, tries the hard states above, and records
+what it saw (screenshots or test output) in the spec's folder.
+
+### VIII. Test against reality
+Tests exercise the code that ships, against the real backend, with dedicated test
+accounts that real users never meet (placed far away, clearly named "(Test)", passwords
+only in an untracked file). No demo-data layer inside production code: it rewrites real
+behaviour and lets tests pass without testing the fix.
+- Every test starts from a known state: reset the test data before each journey and
+  confirm which account is signed in. Never trust what an earlier test left behind.
+- Check the test setup before trusting a result. A failure is first classified as
+  "app" or "test" with evidence (screenshot, log, timing), then fixed where it belongs.
+- Before planning any database change, inspect the live database. The repo's migration
+  files are not proof of what is deployed.
+- Before telling a person what they will see, check it on their device or account.
+- **Assert the outcome, not the app's claim.** A journey passes when the result exists on
+  the other side: the message arrived, the push was delivered, the file is in storage, the
+  other account sees the change. "Sending…" on screen proves nothing.
+- **A flow that taps a mutating action ends with an outcome assertion.** After Send,
+  Block, Delete, Accept or Save, the flow checks the result: the item is in (or gone
+  from) a list, or a script signed in as the other account sees the change. A screen
+  title alone is not an outcome. `kit/expo-supabase-maestro/scripts/lint-outcome-flows.mjs`
+  flags the flows that break this.
+- **Simulated people behave like real ones.** A test helper that plays another person goes
+  through the same server calls the app makes (including notifications), never straight
+  to the database.
+- **What only a real phone can show gets its own list, prepared by the AI:** cold start
+  with nothing cached, push notifications, camera and microphone, fonts and text fitting
+  on the smallest phone, the compass or heading (turn the phone slowly through north and
+  compare with the iOS Compass app), the photo picker (a photo arrives whole, with no
+  forced crop), and the splash screen on a cold start on the smallest supported phone.
+  The AI sets each one up and states the expected result; the person only looks. Each
+  item leaves a screen recording in the spec's `evidence/` folder.
+
+### IX. Every run makes the factory better
+After each spec, record what went wrong and what went right in `LESSONS.md`, and turn
+each repeatable lesson into a rule here, a trap in "Known traps" below, or a tool in
+`kit/`. A lesson that only lives in someone's memory will be relearned the hard way.
+
+### X. Expected baseline
+People judge an app against the apps they already use. A chat with no way to start a
+new line feels broken, even if every feature the spec named works. So every spec lists
+the features users expect from apps of its category and marks each one:
+
+- **In scope**: built and tested in this spec.
+- **Hidden**: not built, and nothing on screen suggests it exists.
+- **Out**: not built and not hidden (it never had a button), with a reason and the spec
+  that will take it.
+
+Every row has a reason. Starting points, by category:
+
+| Category | Users expect |
+|---|---|
+| Chat | New line in the message box; unsend or delete your own message; reply to a message; typing indicator; tap a photo to see it full screen; photos sent whole, never force-cropped; shared media shows photos and videos, not voice notes |
+| Profiles | A photo gallery, not one photo; your changes reach other people promptly |
+| Settings | Privacy toggles change what **others** see, not only what this phone shows |
+| Sign-up | Nothing asked twice (no name screens when sign-in already gave the name); dates picked, not typed; photos not force-cropped |
+| Safety | Block works in both directions and from every place the person appears; unblock from the same places |
+
+The list grows with each run: a baseline item testers report becomes a row here.
+
+## Known traps
+
+Checked in every plan and every review. Each one cost real time once.
+
+| Trap | Why it bites | Do instead |
+|---|---|---|
+| Calling the backend inside an auth state-change callback (Supabase `onAuthStateChange`) | The auth lock is still held, so the call waits forever: sign-out froze | Defer with `setTimeout(..., 0)`; give cleanup steps a time limit |
+| Creating stores, clients or objects on every render | Effects that depend on them re-run every render: the chat screen froze | Create once per key (`useMemo`, module cache) |
+| Copying a store's value once into derived state | The copy never updates: contacts sorted under "U" | Read the live value |
+| Location or proximity queries without an upper limit | Anyone can scan a wide area and locate people | Cap distances on the server; review every location query for privacy |
+| State flags written to one place and read from another | The app "never knew it was offline" | Unit-test the setter and the reader together |
+| Local dev servers and long test runs | Background processes stop at their time limit mid-run | Restart before long runs; runners check the server first |
+| Adding a new kind of upload (voice, video, files) without checking the storage bucket | A production bucket only allowed images, so voice notes failed for every user for months; its write rules also let anyone overwrite anyone's files | When a feature uploads, test the live bucket: the file type is accepted, and a second account cannot overwrite or delete it |
+| Testing an over-the-air update on a newer development build than the one in the App Store | The update needed a native package the store build lacked, crashed on launch and rolled back; real users never got it | Before any OTA publish, compare native dependencies and the Expo fingerprint against the **store** build; test on that build or ship a new store build |
+| Push tokens saved per phone with a "one account per phone" rule, but nothing removes the old account's row (sign-out, expired session, older app versions) | The next account's save fails silently; the phone keeps the old account's notifications, so people see pushes for messages they sent themselves | The account that registers a phone takes it over on the server (trigger or function), not only on sign-out in the app; test with two accounts on one phone |
+| A visible button or menu item whose action does nothing (a "Reply" with no handler) | It is a lie on screen: the person taps, nothing happens, and they stop trusting every other button (release 2.1.0) | Hide it until it works; a review checks every menu item has a handler that is passed in |
+| Long cache times (`offlineFirst`, `staleTime` of minutes, a 24-hour persisted cache) on **another person's** data | Their updates never reach you: a friend's new photos showed, then disappeared for viewers (release 2.1.0) | Your own data may cache; other people's data refetches on focus or listens for changes. Test: A changes it, B (with the old value cached) sees it within N seconds |
+| A server migration written but never applied | The app ships assuming rules that are not live: blocking was one-sided for every user (migration 0007, 2026-10-12) | Each migration a release needs is a task; the release is blocked until `check-migrations.mjs` passes against the live database |
+| A "fix" shipped without the device check it needed | The splash text was "fixed" on the simulator and still cut off on phones (release 2.1.0) | A fix on the device-only list counts as not fixed until its screen recording is in `evidence/` |
+| Fixing a bug only where it was reported | The same mistake often lives in a sibling: a copy, a parallel type, another code path. Builder and reviewer both missed one in the bench pilot, and the maintainers' real fix covered it (2026-10-09) | Name the root cause in one sentence, search the codebase for the same pattern, fix or report every copy; the reviewer checks this too (review rule R7) |
+
+## Launch Readiness
+
+Nothing that real people use goes live until a plan answers four questions: what metric
+says it is working, what alarms when it is not, who responds, and where the runbook is.
+
+## Release gate
+
+Nothing goes to a store while either of these is open:
+
+1. **Server work.** Any task that touches the server (a migration, a policy, an edge
+   function, a storage rule, a setting) is `[ ]` or `[~]`. "Written" is not done:
+   `check-migrations.mjs` (or the matching check) must pass against the live database.
+2. **Outside testers.** One TestFlight (or internal testing) round with at least three
+   people outside the team, on their own phones, before each store release. Their notes
+   are saved in the spec's `evidence/` folder, and anything they find is fixed or
+   recorded as known before release.
+
+## Workflow
+
+- Specs live in `specs/` in this repo. Code lives in the repo the spec names, listed in
+  `repos.md`. Every spec states its target repo.
+- Plans use the existing stack of the target repo.
+- Anything a partner, funder or the public will see follows the organisation's brand and
+  design rules.
+- Every build sent to a store gets an annotated git tag on its exact commit, pushed the
+  same day, following the repo's own pattern (for example `v2.1.0-I45`, where A = Android build and I = iOS build).
+- **One spec, one reviewable slice per pull request.** A stacked pull request says its
+  base in its title or first line ("Stacked on #28") and targets the parent branch, not
+  `main`, so its diff shows only its own change. Merge from the bottom of the stack up.
+- CI turns on Biome's `noExcessiveCognitiveComplexity` as an error for **changed files
+  only** (recipe in `kit/expo-supabase-maestro/README.md`). Old files are fixed when they
+  are next touched.
+- Dates are written YYYY-MM-DD. Spelling is British/South African.
+
+## Governance
+
+This constitution sits under the organisation's own house rules. Where they disagree,
+the house rules win. Changes are made with `/speckit-constitution`, and the reason is
+recorded as a decision in the organisation's decision log.
+
+**Version**: 0.3.0 (draft, awaiting team agreement; VIII, IX and Known traps added from Run 1; X, the shared states, release gate and pull request rules added after release 2.1.0 tester feedback) | **Ratified**: not yet | **Last Amended**: 2026-10-12

package/template/lesson.md

@@ -0,0 +1,20 @@
+# A short title
+
+- Date: YYYY-MM-DD
+- South Africa specific: no
+
+## What went wrong
+
+One or two sentences. What the software did, and what the person got instead.
+
+## How to spot it
+
+What someone would see, or what they would have to try, to notice this.
+
+## The check
+
+The check that catches it, or a plain description of one.
+
+## Real example
+
+Where this happened, and what it cost.

package/template/plan.md

@@ -0,0 +1,52 @@
+# Plan: [what changes]
+
+- Spec: `specs/[NNN-name]/spec.md` (approved)
+- Date: [YYYY-MM-DD]
+
+## Summary
+
+[The approach in three sentences: what changes, where, and why this way.]
+
+## What already exists, and what is reused
+
+Walk the reuse ladder in the constitution and stop at the first rung that holds.
+
+| Need | Rung | What is used | Why |
+|---|---|---|---|
+| | already in the repo / standard library / platform / installed package / open source / new code | | |
+
+## Data
+
+[Tables or fields added or changed, every index and what it is for, and what would be
+painful to change once real people's data is in it. "No data changes" is an answer.]
+
+## Who can read and write it
+
+[Each thing stored: who can read it, who can write it, and how that is enforced (a server
+rule, not only the app). Where any secret lives.]
+
+## Personal data
+
+[What personal data is touched, why, where it is stored and for how long. "None" is an
+answer.]
+
+## One check per acceptance check
+
+| Acceptance check | Kind | Command or file |
+|---|---|---|
+| AC1 | unit / journey / device-only | |
+
+## Files
+
+- `path/to/file`: [what changes]
+
+## Risks
+
+- [What could go wrong, and how the tasks put it first.]
+
+## Constitution check
+
+- [ ] Every state in the spec is answered, or n/a with a reason
+- [ ] Every acceptance check has a check above
+- [ ] No secret in a file; personal data stated
+- [ ] Known traps read; none applies, or the plan says how it is avoided

package/template/review-rules.md

@@ -0,0 +1,88 @@
+<!--
+The per-check verdict (section "Every acceptance check") is adapted from Otta,
+https://github.com/wiselancer/otta-plugin (agents/qa.md and agents/reviewer.md),
+MIT licence, Copyright (c) wiselancer. See THIRD-PARTY.md.
+-->
+
+# Review rules
+
+You are reviewing a change you did not write. You have not seen the builder's reasoning
+and you should not guess it. Read the actual change, not a summary of it.
+
+Assume the change is broken until evidence says otherwise.
+
+## Every finding
+
+- Cites one rule below and one `file:line`.
+- Says how to prove it: the test, command or observation that would show the problem.
+- Is one of: **must fix** (the change is wrong or unsafe), **should fix** (it works but
+  will hurt soon), **fine** (noted, no action).
+- If you cannot prove it, drop it. A false alarm costs more than a missed nit.
+
+## The rules
+
+| Rule | Send it back when |
+|---|---|
+| R1 Claim without proof | Something is said to work and nothing shows it: no test, no output, no record read back |
+| R2 Control that does nothing | A button, link, menu item or setting has no handler, or its handler does not do what its label says |
+| R3 State not handled | Loading, empty, error, offline, no permission, tapped twice or back is reachable and does something wrong or nothing at all |
+| R4 Secret or personal data leaked | A key, token or password is in a file, a log, a test or an error message; personal data is logged, cached too long or sent somewhere the spec did not say |
+| R5 Another person's data | One account can read, change or delete another account's data, or sees it after it should be gone |
+| R6 Test that proves nothing | A test checks a label, a toast or "Sending..." instead of the result; a test would still pass with the feature removed; tests were deleted or skipped |
+| R7 The same mistake elsewhere | The root cause, named in one sentence, also lives in a copy, a sibling type or another code path that the change did not fix |
+
+Also check the Known traps in `.factory/constitution.md` against the files this change
+touches.
+
+Judge the working tree as it is. The builder may edit files but may not run commands; the
+factory runs the tests, build and checks and records them (below, and in the evidence
+folder). So do not send work back because something is not staged or committed, or because
+a proof file that needs a command is missing: committing is the person's job after your
+review. If a check can only be proven by a command nobody ran, mark it UNPROVEN and say
+which command a person should run.
+
+## Every acceptance check
+
+For each `- [ ] ... Proof:` line in the spec, decide PASS, FAIL or UNPROVEN.
+
+- PASS needs evidence that would not exist without this change: a test that fails when the
+  change is reverted, the factory's own check results below, a file you read, a screenshot
+  of the result.
+- FAIL means the change does not do it, or the evidence shows it is wrong. "Close enough"
+  is FAIL.
+- UNPROVEN means the proof needs something you cannot do here (a command you may not run, a
+  live system, a real phone) and nothing else shows it. Say exactly what a person must do
+  to check it. Do not use UNPROVEN to avoid reading the code.
+- List anything the spec asked for that the change does not do (**missing**), and anything
+  the change does that the spec did not ask for (**extra**).
+
+## Write this file, and nothing else
+
+`{{reviewFile}}`
+
+```
+# Review
+
+| # | Severity | Where | Rule | What is wrong | How to prove it |
+|---|---|---|---|---|---|
+| 1 | must fix | src/a.ts:12 | R5 | ... | ... |
+
+## Acceptance checks
+
+| Check | Verdict | Evidence |
+|---|---|---|
+| AC1 | PASS | test "stores the booking" in test/booking.test.ts fails when the insert is removed |
+| AC2 | UNPROVEN | needs `git log` over the history; a person runs the command in the spec |
+
+Missing: none
+Extra: none
+
+VERDICT: approve
+```
+
+The last line is `VERDICT: approve` or `VERDICT: send back`. Send it back when there is
+any must-fix finding, any FAIL, or anything missing. UNPROVEN alone does not send it back;
+it is reported to the person.
+
+You may read any file. Write only the review file above: do not change the code, the spec,
+the tests or anything else. The factory checks this.