agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/stacks/_lib/common.sh

@@ -0,0 +1,3095 @@
+#!/usr/bin/env bash
+# Shared scaffolding helpers. Sourced by every stack's setup.sh.
+# Never hardcode a version here — always resolve from the registry.
+
+set -euo pipefail
+
+log()  { printf '  [+] %s\n' "$*"; }
+warn() { printf '  [!] %s\n' "$*" >&2; }
+die()  { printf '  [x] %s\n' "$*" >&2; exit 1; }
+
+# Read a JSONC file safely. Comment-stripping by regex is not safe here:
+# "@/*" in a tsconfig paths glob looks like the start of a block comment and
+# the "*/" inside "**/*.ts" looks like its end, so a regex silently deletes
+# the span between them and produces invalid JSON.
+JSONC_READ='
+function readJsonc(file) {
+  const raw = require("fs").readFileSync(file, "utf8");
+  let out = "", inStr = false, esc = false, i = 0;
+  while (i < raw.length) {
+    const c = raw[i], n = raw[i + 1];
+    if (inStr) {
+      out += c;
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === "\"") inStr = false;
+      i++; continue;
+    }
+    if (c === "\"") { inStr = true; out += c; i++; continue; }
+    if (c === "/" && n === "/") { while (i < raw.length && raw[i] !== "\n") i++; continue; }
+    if (c === "/" && n === "*") { i += 2; while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++; i += 2; continue; }
+    out += c; i++;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+}
+'
+
+# Latest version of a package, from the registry. Never from memory.
+resolve_latest() {
+  local pkg="$1" v
+  v="$(npm view "$pkg" version 2>/dev/null)" || die "cannot resolve $pkg"
+  [ -n "$v" ] || die "empty version for $pkg"
+  printf '%s' "$v"
+}
+
+# A create tool can fail and still exit 0 — create-hono drops into a prompt
+# and dies in a non-TTY, leaving an empty directory. Without this the rest of
+# the script happily builds a package.json from nothing and reports success.
+assert_scaffolded() { # dir
+  local dir="$1"
+  [ -d "$dir" ] || die "scaffold produced no directory at $dir"
+  [ -f "$dir/package.json" ] || die "scaffold left no package.json in $dir — the create tool failed"
+  [ "$(ls -A "$dir" | wc -l | tr -d ' ')" -gt 2 ] || die "scaffold left $dir essentially empty"
+  log "scaffold verified in $dir"
+}
+
+# Yarn 4 with the node-modules linker. PnP is not a default worth defending
+# here — it breaks Metro and a good deal of native tooling.
+setup_yarn() {
+  corepack enable >/dev/null 2>&1 || warn "corepack enable failed; yarn may resolve to a global install"
+  yarn set version stable >/dev/null 2>&1 || die "could not pin a yarn version"
+  printf 'nodeLinker: node-modules\n' > .yarnrc.yml
+  # The create tool may have left an npm lockfile behind.
+  rm -f package-lock.json
+
+  # Yarn 4 writes .yarn/install-state.gz on every install. A create tool's
+  # .gitignore predates yarn 4 and does not mention it, so it lands in the
+  # first commit and then churns a binary blob in every diff after it.
+  if ! grep -q '^\.yarn/\*' .gitignore 2>/dev/null; then
+    cat >> .gitignore <<'GI'
+
+# yarn 4
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+.pnp.*
+GI
+    log "yarn artefacts gitignored"
+  fi
+  log "yarn $(yarn --version) (node-modules linker)"
+}
+
+# package.json edits without npm. `npm pkg set` is npm-only, and without
+# --json it writes every value as a string — which silently disables numeric
+# thresholds.
+pkg_set() { # key.path=value ... ; value is parsed as JSON when it parses
+  node -e '
+    const fs = require("fs");
+    const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    for (const arg of process.argv.slice(1)) {
+      const i = arg.indexOf("=");
+      const path = arg.slice(0, i);
+      const raw = arg.slice(i + 1);
+      let val;
+      try { val = JSON.parse(raw); } catch { val = raw; }
+      const keys = path.split(".");
+      let node = p;
+      for (const k of keys.slice(0, -1)) { node[k] = node[k] || {}; node = node[k]; }
+      node[keys[keys.length - 1]] = val;
+    }
+    fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+  ' "$@"
+}
+
+# Newest version of a package that is old enough to clear yarn's supply-chain
+# age gate. Yarn 4 quarantines anything published inside npmMinimalAgeGate
+# (24h by default) — the window when a compromised publish is most dangerous.
+# That gate is worth keeping, so resolve around it instead of switching it off.
+resolve_settled() { # pkg
+  local pkg="$1" gate
+  gate="$(yarn config get npmMinimalAgeGate 2>/dev/null || echo 1440)"
+  case "$gate" in ''|*[!0-9]*) gate=1440 ;; esac
+  npm view "$pkg" time --json 2>/dev/null | node -e '
+    let s = "";
+    process.stdin.on("data", (d) => (s += d)).on("end", () => {
+      const gateMs = Number(process.argv[1]) * 60 * 1000;
+      const cutoff = Date.now() - gateMs;
+      let times;
+      try { times = JSON.parse(s); } catch { process.exit(1); }
+      const settled = Object.entries(times)
+        .filter(([v]) => !["created", "modified"].includes(v))
+        .filter(([v]) => !/-(alpha|beta|rc|next|canary|nightly|preview)/i.test(v))
+        .filter(([, t]) => Date.parse(t) < cutoff)
+        .map(([v]) => v);
+      if (!settled.length) process.exit(1);
+      // npm lists versions in publish order; the last settled one is newest.
+      process.stdout.write(settled[settled.length - 1]);
+    });
+  ' "$gate"
+}
+
+# Install packages at their current latest. Deliberately NOT pinned to an
+# exact version — the lockfile records what landed, and Dependabot moves it
+# forward. Pass an explicit range (e.g. "tailwindcss@3") only where a real
+# compatibility constraint exists, and say why.
+# Usage: add_latest [--dev] pkg[@range] [pkg...]
+add_latest() {
+  local dev="" specs=() pkg bare
+  [ "${1:-}" = "--dev" ] && { dev="-D"; shift; }
+  for pkg in "$@"; do
+    # A leading @ is a scope, not a version — "@vitest/browser" has no range.
+    bare="${pkg#@}"
+    case "$bare" in
+      *@*) specs+=("$pkg"); log "install ${pkg}" ;;
+      *)   specs+=("${pkg}@latest"); log "install ${pkg}@latest" ;;
+    esac
+  done
+
+  if yarn add $dev "${specs[@]}"; then
+    return 0
+  fi
+
+  # A fresh publish inside the age gate fails the whole batch. Fall back to
+  # the newest settled version per package rather than disabling the gate.
+  warn "install failed — retrying against versions past yarn's age gate"
+  local retry=() name settled
+  for pkg in "$@"; do
+    bare="${pkg#@}"
+    case "$bare" in
+      *@*) retry+=("$pkg"); continue ;;
+    esac
+    name="$pkg"
+    settled="$(resolve_settled "$name" || true)"
+    if [ -n "$settled" ]; then
+      retry+=("${name}@${settled}")
+      log "  ${name} -> ${settled} (newest past the gate)"
+    else
+      retry+=("${name}@latest")
+    fi
+  done
+  yarn add $dev "${retry[@]}" || die "could not install: ${retry[*]}"
+}
+
+# Expo pins React and React Native to what its SDK was built against, so a
+# plain "@latest" resolves versions the SDK rejects. `expo install` picks the
+# SDK-compatible version and falls back to latest when there is no pin, which
+# is what "current versions" actually means inside Expo.
+expo_install() {
+  local dev=""
+  [ "${1:-}" = "--dev" ] && { dev="--dev"; shift; }
+  log "expo install $*"
+  yarn expo install $dev "$@"
+}
+
+# TypeScript with the strictness the conventions require.
+setup_typescript() {
+  add_latest --dev typescript
+  node -e "$JSONC_READ"'
+    const fs = require("fs");
+    const f = "tsconfig.json";
+    const cfg = fs.existsSync(f) ? readJsonc(f) : {};
+    cfg.compilerOptions = {
+      ...(cfg.compilerOptions || {}),
+      strict: true,
+      noUncheckedIndexedAccess: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+    };
+    fs.writeFileSync(f, JSON.stringify(cfg, null, 2) + "\n");
+  '
+  # A solution-style config delegates to referenced files; flags set on it
+  # apply to nothing. Apply them where the sources actually are.
+  node -e "$JSONC_READ"'
+    const fs = require("fs");
+    const strict = {
+      strict: true,
+      noUncheckedIndexedAccess: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+    };
+    for (const f of ["tsconfig.app.json", "tsconfig.node.json"]) {
+      if (!fs.existsSync(f)) continue;
+      const cfg = readJsonc(f);
+      cfg.compilerOptions = { ...(cfg.compilerOptions || {}), ...strict };
+      fs.writeFileSync(f, JSON.stringify(cfg, null, 2) + "\n");
+      console.log("  [+] strict applied to " + f);
+    }
+  '
+  log "typescript: strict + noUncheckedIndexedAccess"
+}
+
+# Biome replaces ESLint and Prettier entirely. Remove whatever the
+# create tool installed, so two formatters never fight.
+setup_biome() {
+  add_latest --dev @biomejs/biome
+  npx biome init >/dev/null 2>&1 || true
+  # Whatever linter the create tool shipped goes — two linters means two sets
+  # of rules disagreeing. create-vite ships oxlint now, older ones eslint.
+  node -e '
+    const fs = require("fs");
+    const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    for (const d of ["eslint","prettier","eslint-config-prettier","oxlint",
+                     "eslint-plugin-react-hooks","eslint-plugin-react-refresh",
+                     "typescript-eslint","@eslint/js"]) {
+      if (p.devDependencies) delete p.devDependencies[d];
+      if (p.dependencies) delete p.dependencies[d];
+    }
+    fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+  '
+  rm -f .eslintrc .eslintrc.js .eslintrc.cjs .eslintrc.json eslint.config.js .oxlintrc.json \
+        .prettierrc .prettierrc.json prettier.config.js
+  pkg_set scripts.lint="biome check ." scripts.format="biome format --write ."
+
+  # Without tailwindDirectives biome hard-fails parsing `@theme`, and without
+  # the excludes it lints build output and static assets.
+  node -e "$JSONC_READ"'
+    const fs = require("fs");
+    const f = ["biome.json", "biome.jsonc"].find((x) => fs.existsSync(x));
+    if (!f) process.exit(0);
+    const c = readJsonc(f);
+    c.css = { ...(c.css || {}), parser: { ...((c.css || {}).parser || {}), tailwindDirectives: true } };
+    // Union, not replace: a create tool writes its own excludes (".next" for
+    // next, "node_modules" everywhere) and dropping them makes the first
+    // lint run walk build output.
+    // biome treats "!dist" and "!dist/**" as the same pattern, so compare
+    // them that way or the merged list carries both.
+    const key = (g) => g.replace(/\/\*\*$/, "");
+    const merged = new Map();
+    for (const g of [...((c.files || {}).includes || ["**"]),
+                     "**", "!public/**", "!dist/**", "!coverage/**", "!build/**"]) {
+      if (!merged.has(key(g))) merged.set(key(g), g);
+    }
+    c.files = { ...(c.files || {}), includes: [...merged.values()] };
+    fs.writeFileSync(f, JSON.stringify(c, null, 2) + "\n");
+  '
+  npx biome check --write . >/dev/null 2>&1 || true
+  log "biome installed, other linters removed, scaffold formatted"
+}
+
+# Component tests in a real browser, driven by Playwright.
+# Playwright's own CT package is still experimental — this is not.
+setup_vitest_browser() {
+  # vite is a REQUIRED peer of vitest (peerDependenciesMeta.vite.optional=false).
+  # create-vite supplies it; a Next.js app does not, and without it the runner
+  # dies at startup on "Cannot find package 'vite'".
+  add_latest --dev vite vitest @vitest/browser @vitest/browser-playwright playwright vitest-browser-react
+  npx playwright install chromium >/dev/null 2>&1 || warn "playwright browser install failed"
+  pkg_set scripts.test="vitest run --passWithNoTests" scripts.test:watch="vitest"
+
+  # Browser mode has to be configured, not just installed. Without this block
+  # the first component test fails on `document is not defined`.
+  if [ ! -f vitest.config.ts ]; then
+    cat > vitest.config.ts <<'VITEST'
+import { defineConfig } from "vitest/config";
+import { playwright } from "@vitest/browser-playwright";
+
+export default defineConfig({
+  test: {
+    browser: {
+      enabled: true,
+      // A factory, not the string "playwright" — the string form fails at
+      // startup on vitest 4.
+      provider: playwright(),
+      headless: true,
+      instances: [{ browser: "chromium" }],
+    },
+  },
+});
+VITEST
+    log "vitest browser mode configured"
+  fi
+  log "vitest + browser mode (playwright driver)"
+}
+
+# True end-to-end, separate from component tests.
+#
+# Component tests render one component in a browser. This starts the real
+# app — the built one, not the dev server — and drives it. It is the only
+# layer that sees a broken route, a bad environment variable, or a bundle
+# that does not boot.
+#
+# Usage: setup_playwright_e2e <server-command> <url>
+setup_playwright_e2e() {
+  local server_cmd="${1:?server command required}" url="${2:?url required}"
+  add_latest --dev @playwright/test
+  pkg_set scripts.test:e2e="playwright test"
+
+  if [ ! -f playwright.config.ts ]; then
+    cat > playwright.config.ts <<PW
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  // A flaky e2e suite is worse than none — it teaches people to re-run.
+  // Retry only on CI, where the cause is usually the runner and not the app.
+  retries: process.env.CI ? 2 : 0,
+  forbidOnly: !!process.env.CI,
+  reporter: process.env.CI ? "github" : "list",
+  use: {
+    baseURL: "${url}",
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+  // The built app, not the dev server. A dev server hides exactly the
+  // failures this layer exists to catch: a bad production bundle, a missing
+  // environment variable, a route that only resolves in development.
+  webServer: {
+    command: "${server_cmd}",
+    url: "${url}",
+    reuseExistingServer: !process.env.CI,
+    timeout: 180_000,
+  },
+});
+PW
+    log "playwright config (builds and serves the app)"
+  fi
+
+  # vitest's default include matches **/*.spec.ts, so it picks up the
+  # playwright specs, tries to bundle @playwright/test, and dies on its
+  # native fsevents dependency. The function that creates e2e/ is the one
+  # that has to keep the unit runner out of it.
+  if [ -f vitest.config.ts ] && ! grep -q "configDefaults" vitest.config.ts; then
+    node -e '
+      const fs = require("fs");
+      const f = "vitest.config.ts";
+      let s = fs.readFileSync(f, "utf8");
+      s = s.replace(
+        /import \{ defineConfig \} from "vitest\/config";/,
+        `import { configDefaults, defineConfig } from "vitest/config";`
+      );
+      const block = [
+        "    // e2e/ belongs to playwright. vitest would otherwise try to bundle",
+        "    // @playwright/test and fail on its native dependency.",
+        "    exclude: [...configDefaults.exclude, \"e2e/**\"],",
+      ].join("\n");
+      const i = s.indexOf("test: {");
+      if (i === -1) process.exit(0);
+      s = s.slice(0, i + "test: {".length) + "\n" + block + s.slice(i + "test: {".length);
+      fs.writeFileSync(f, s);
+    ' || warn "could not exclude e2e/ from vitest — do it by hand"
+    log "vitest excludes e2e/"
+  fi
+
+  mkdir -p e2e
+  if [ ! -f e2e/smoke.spec.ts ]; then
+    cat > e2e/smoke.spec.ts <<'SPEC'
+import { expect, test } from "@playwright/test";
+
+/**
+ * The highest-value single check on the web: the built app boots and renders.
+ *
+ * Nothing else in the gate sees this. Component tests mount one component in
+ * isolation, and a typecheck never loads the bundler — so a broken route, a
+ * missing environment variable or a bundle that throws on load all pass
+ * every other check and fail here.
+ */
+test("the app boots and renders something", async ({ page }) => {
+  const errors: string[] = [];
+  page.on("pageerror", (e) => errors.push(e.message));
+
+  const response = await page.goto("/");
+  expect(response?.status(), "the server answered").toBeLessThan(400);
+
+  // Not a screenshot and not a text match — either would need editing the
+  // day the copy changes. This asserts the document actually rendered.
+  await expect(page.locator("body")).toBeVisible();
+  expect(errors, "the page threw while loading").toEqual([]);
+});
+SPEC
+    log "e2e/smoke.spec.ts"
+  fi
+
+  cat > e2e/README.md <<'MD'
+# End-to-end
+
+Few, and about journeys rather than components. Each one costs a build and a
+browser, and a suite nobody trusts is worse than no suite at all.
+
+What belongs here:
+
+- the app boots (`smoke.spec.ts` — already written)
+- sign in, and stay signed in across a reload
+- the one flow the product exists for, start to finish
+- the failure path of that flow — the funnel that only records success
+  cannot tell you why people left
+
+What does not: anything a component test can answer, and anything asserted
+by a screenshot of text that will change.
+
+Query by role, never by test id — see `.claude/skills/web-testing/SKILL.md`.
+MD
+  log "playwright e2e (built app, smoke test written)"
+}
+
+# Pin Node so CI and local agree.
+setup_node_pin() {
+  local v="${1:-$(node -v | sed 's/^v//')}"
+  printf '%s\n' "$v" > .node-version
+  pkg_set "engines.node=>=${v%%.*}"
+  log "node pinned to $v"
+}
+
+# Coverage, as four gates rather than one number.
+#
+# A single global percentage stops measuring test quality the moment it
+# becomes a gate — it measures test quantity instead, and it counts a design
+# token file the same as the module wrapping the database driver.
+#
+# So: start the global thresholds at zero with autoUpdate on. The first run
+# writes the real numbers into this file and every run after it fails on a
+# drop. That is a ratchet, and it needs no arbitrary starting number.
+# The remaining gates — branch coverage of the changed lines, and 100% on the
+# modules that wrap a third-party library — live in scripts/diff-coverage.mjs
+# and in `thresholds` glob keys respectively.
+#
+# Additive on purpose: setup_vitest_browser may already have written a
+# config, and silently skipping would leave the gates unset while still
+# logging success.
+setup_coverage() {
+  # The reporters below write coverage/ into the app. create-next-app ignores
+  # it; create-hono and create-expo-app do not, so without this the first
+  # `git add -A` commits an HTML coverage report.
+  if ! grep -qE '^/?coverage' .gitignore 2>/dev/null; then
+    printf '\n# coverage output\ncoverage/\n' >> .gitignore
+  fi
+
+  add_latest --dev @vitest/coverage-v8
+
+  # Three steps, one command. The ratchet rewrites vitest.config.ts whenever
+  # coverage improves; the cap holds that floor below ratchet_ceiling, because
+  # autoUpdate otherwise records 100 on a small fully-covered app and turns the
+  # ratchet into a target nobody set; biome reformats what both of them wrote,
+  # since vitest writes with its own formatting and the next lint run rejects
+  # it. Leaving any of them out is a landmine for whoever runs lint next.
+  write_coverage_cap_script
+  local cov_root cap_rel
+  cov_root="$(git rev-parse --show-toplevel)"
+  cap_rel="$(node -e 'const p=require("path");process.stdout.write(p.relative(process.cwd(), process.argv[1]))' "$cov_root/scripts/coverage-cap.mjs")"
+  pkg_set scripts.test:coverage="vitest run --coverage --passWithNoTests && node ${cap_rel} && biome check --write vitest.config.ts"
+
+  if [ ! -f vitest.config.ts ]; then
+    cat > vitest.config.ts <<'VITEST'
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {},
+});
+VITEST
+  fi
+
+  node -e '
+    const fs = require("fs");
+    const f = "vitest.config.ts";
+    let s = fs.readFileSync(f, "utf8");
+    if (s.includes("coverage:")) process.exit(0);
+    const block = [
+      "    coverage: {",
+      "      provider: \"v8\",",
+      "      // json-summary and json feed scripts/diff-coverage.mjs; lcov is",
+      "      // what every external reporter reads.",
+      "      reporter: [\"text\", \"json\", \"json-summary\", \"lcov\"],",
+      "      // Every source file, not only the ones a test happened to load.",
+      "      // Without this a file nobody imports is invisible, and the",
+      "      // percentage flatters itself by measuring only what was already",
+      "      // being tested. Anything that genuinely should not count belongs",
+      "      // in exclude below — a deliberate, reviewable edit rather than a",
+      "      // test written to move a number.",
+      "      include: [\"src/**/*.{ts,tsx}\"],",
+      "      // Counted against nothing: these move the number without saying",
+      "      // anything about whether the code was checked.",
+      "      exclude: [",
+      "        \"**/*.d.ts\",",
+      "        \"**/*.test.*\",",
+      "        // Workbench catalogue entries, not shipped logic.",
+      "        \"**/*.fixture.*\",",
+      "        \"**/*.config.*\",",
+      "        \"**/index.ts\",",
+      "        \"**/design/tokens.*\",",
+      "        \"**/.{idea,git,cache,output,temp}/**\",",
+      "      ],",
+      "      thresholds: {",
+      "        // The ratchet. Starts at zero and is rewritten upward by vitest",
+      "        // whenever coverage improves; a drop fails the run. Commit the",
+      "        // updated numbers with the change that earned them.",
+      "        autoUpdate: true,",
+      "        lines: 0,",
+      "        functions: 0,",
+      "        branches: 0,",
+      "        statements: 0,",
+      "        // Seams — every module that wraps a third-party library. These",
+      "        // are what make a dependency bump turn the suite red, they are",
+      "        // small, and so 100% here is meaningful where a global 100% is",
+      "        // not.",
+      "        //",
+      "        // Live from day one, because the location is a convention rather",
+      "        // than something discovered later: anything wrapping a third",
+      "        // party lives in src/integrations/<provider>/. An empty or",
+      "        // absent directory matches nothing and passes.",
+      "        //",
+      "        // This asks that the code be exercised, not that a test file sit",
+      "        // beside it. An integration test that drives the wrapper through",
+      "        // a faked HTTP boundary satisfies it — no second test, no",
+      "        // duplicate assertion.",
+      "        \"src/integrations/**\": { 100: true },",
+      "      },",
+      "    },",
+    ].join("\n");
+    const i = s.indexOf("test: {");
+    if (i === -1) {
+      console.error("no test block in vitest.config.ts — coverage not applied");
+      process.exit(1);
+    }
+    s = s.slice(0, i + "test: {".length) + "\n" + block + s.slice(i + "test: {".length);
+    fs.writeFileSync(f, s);
+  ' || die "failed to write the coverage block"
+
+  write_diff_coverage_script
+  local root rel
+  root="$(git rev-parse --show-toplevel)"
+  rel="$(node -e 'const p=require("path");process.stdout.write(p.relative(process.cwd(), process.argv[1]))' "$root/scripts/diff-coverage.mjs")"
+  pkg_set scripts.test:coverage:diff="node $rel"
+  log "coverage: ratchet + diff gate (seam globs are added per app)"
+}
+
+setup_typecheck_script() {
+# -b is required: create-vite ships a solution-style tsconfig (files: [] +
+# references), and plain `tsc --noEmit` checks nothing at all against it.
+# `tsc -b --noEmit` is correct for both solution and flat configs.
+  pkg_set scripts.typecheck="tsc -b --noEmit"
+  log "typecheck script"
+}
+
+# The Orchestra verification gate assumes these exist. Fail loudly if not.
+assert_verification_scripts() {
+  local missing=()
+  # build is in here because the rule argues hardest for it and nothing else
+  # checked it existed. An app that genuinely cannot be built does not reach
+  # this function — the native stacks verify through their own verify.sh.
+  for s in typecheck test lint "test:coverage" build; do
+    node -e 'const s=require("./package.json").scripts||{};process.exit(s[process.argv[1]]?0:1)' "$s" || missing+=("$s")
+  done
+  [ ${#missing[@]} -eq 0 ] || die "missing scripts: ${missing[*]}"
+  log "verification scripts present"
+}
+
+# ── Repo-wide verification gate ───────────────────────────────────────────
+# Runs from the git root and covers every app, whatever language it is in.
+# Detection is by marker file, so adding a Python or Go app needs no edit
+# here beyond its own branch.
+write_verify_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/verify.sh" <<'VERIFY'
+#!/usr/bin/env bash
+# Repo-wide verification. Every app, in order, stop at the first failure.
+# This is the gate the pre-commit hook runs. Keep it fast enough to survive.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+fail() { printf '\n  [x] %s failed in %s\n' "$1" "$2" >&2; exit 1; }
+
+# Secrets first, and on what is about to be committed rather than the whole
+# tree — a leaked credential is compromised the moment it is pushed, and
+# rotating it is the only fix. CI scans the full history; this catches it one
+# step earlier, while it is still cheap.
+if command -v gitleaks >/dev/null 2>&1; then
+  printf '  \u2192 secrets\n'
+  gitleaks protect --staged --no-banner --redact || fail gitleaks secrets
+else
+  printf '  \u2192 secrets (gitleaks not installed \u2014 CI still scans; brew install gitleaks)\n'
+fi
+
+# The checks that used to be prose in the rules. See scripts/policy-check.mjs.
+if [ -f "$ROOT/scripts/policy-check.mjs" ]; then
+  printf '  \u2192 policy\n'
+  node "$ROOT/scripts/policy-check.mjs" || fail policy repo
+fi
+
+verify_one() {
+  local dir="$1" name; name="$(basename "$dir")"
+  printf '  → %s\n' "$name"
+  (
+    cd "$dir"
+    if [ -f package.json ]; then
+      # `yarn run`, not `yarn --silent`: yarn 4 parses a leading --silent as
+      # the command name and exits 1 with a syntax error, so every step of
+      # this gate failed for a reason that had nothing to do with the code.
+      yarn run --silent typecheck || fail typecheck "$name"
+      yarn run --silent lint      || fail lint "$name"
+      yarn run --silent test      || fail test "$name"
+    elif [ -f gradlew ]; then
+      ./gradlew --quiet lint test || fail gradle "$name"
+    elif [ -f project.yml ]; then
+      # Whichever simulator this Xcode actually ships, not a model name
+      # written down once — that fails on any machine with a different set,
+      # and the error names a device rather than the real problem.
+      #
+      # `generic/platform=iOS Simulator` is not an option here: it is valid
+      # for build and rejected by test, which needs somewhere to run.
+      sim="$(xcrun simctl list devices available -j 2>/dev/null \
+        | node -e '
+            let s = "";
+            process.stdin.on("data", (d) => (s += d)).on("end", () => {
+              try {
+                const all = Object.values(JSON.parse(s).devices).flat();
+                const pick = all.find((d) => /^iPhone/.test(d.name)) || all[0];
+                process.stdout.write(pick ? pick.udid : "");
+              } catch {}
+            });
+          ' 2>/dev/null)"
+      [ -n "$sim" ] || fail "no iOS simulator installed" "$name"
+      xcodebuild test -quiet -scheme "$name" -destination "id=$sim" \
+        || fail xcodebuild "$name"
+    elif [ -f pyproject.toml ]; then
+      ruff check . || fail ruff "$name"
+      mypy .       || fail mypy "$name"
+      pytest -q    || fail pytest "$name"
+    else
+      printf '    (no known marker — skipped)\n'
+    fi
+  )
+}
+
+# A workspaces root has a package.json but no typecheck/test/lint scripts of
+# its own. Treating it as a target rejects every commit in the repo until
+# somebody hand-edits this file.
+has_verify_scripts() {
+  [ -f "$1/package.json" ] || return 1
+  node -e '
+    const p = require(process.argv[1] + "/package.json");
+    const s = p.scripts || {};
+    process.exit(["typecheck","test","lint"].some((k) => s[k]) ? 0 : 1);
+  ' "$1" 2>/dev/null
+}
+
+targets=()
+if has_verify_scripts "$ROOT" || [ -f "$ROOT/pyproject.toml" ]; then
+  targets+=("$ROOT")
+fi
+for d in apps/*/ packages/*/; do
+  [ -d "$d" ] || continue
+  targets+=("$ROOT/${d%/}")
+done
+
+[ ${#targets[@]} -gt 0 ] || { echo "  nothing to verify"; exit 0; }
+for t in "${targets[@]}"; do verify_one "$t"; done
+printf '\n  [+] all checks passed\n'
+VERIFY
+  chmod +x "$root/scripts/verify.sh"
+  log "wrote scripts/verify.sh"
+}
+
+# Pre-commit gate. Uses husky when the repo root has a package.json;
+# otherwise git's own core.hooksPath — which is the same mechanism husky
+# configures, minus the dependency it cannot install without a root manifest.
+install_pre_commit_gate() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  write_verify_script
+  write_policy_check_script
+
+  # git-native rather than husky. husky wires itself from the `prepare`
+  # lifecycle, and yarn — which every stack here installs — does not run
+  # `prepare` for the root project, so the hook file was written and the
+  # hook never fired. An installed hook that never runs is worse than none,
+  # because it is believed. core.hooksPath needs no dependency and no
+  # lifecycle script, and it behaves the same under every package manager.
+  mkdir -p "$root/.githooks"
+  printf '#!/usr/bin/env sh\nbash scripts/verify.sh\n' > "$root/.githooks/pre-commit"
+  chmod +x "$root/.githooks/pre-commit"
+  ( cd "$root" && git config core.hooksPath .githooks )
+  log "pre-commit gate installed (core.hooksPath)"
+}
+
+
+# ── Freshness ─────────────────────────────────────────────────────────────
+# Everything below exists because a repo scaffolded today was born stale.
+
+# The newest published version of each package, filtered the way the rest of
+# this file filters: no prereleases, and nothing so fresh that yarn's
+# supply-chain age gate will quarantine it. One request per package, in
+# parallel, straight to the registry — `npm view` in a loop is minutes.
+# Prints "name<TAB>version" per line; a package it cannot resolve is omitted
+# rather than guessed.
+registry_latest() { # pkg ...
+  [ $# -gt 0 ] || return 0
+  local gate
+  gate="$(yarn config get npmMinimalAgeGate 2>/dev/null || echo 1440)"
+  case "$gate" in ''|*[!0-9]*) gate=1440 ;; esac
+  GATE_MINUTES="$gate" node -e '
+    const names = process.argv.slice(1);
+    const cutoff = Date.now() - Number(process.env.GATE_MINUTES) * 60 * 1000;
+    const pre = /-(alpha|beta|rc|next|canary|nightly|preview|experimental)/i;
+    const cmp = (a, b) => {
+      const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+      for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+      return 0;
+    };
+    Promise.all(names.map(async (name) => {
+      try {
+        const res = await fetch("https://registry.npmjs.org/" + name.replace("/", "%2f"));
+        if (!res.ok) return null;
+        const doc = await res.json();
+        const settled = Object.entries(doc.time || {})
+          .filter(([v]) => !["created", "modified"].includes(v))
+          .filter(([v]) => !pre.test(v) && /^\d+\.\d+\.\d+$/.test(v))
+          .filter(([, t]) => Date.parse(t) < cutoff)
+          .map(([v]) => v)
+          .sort(cmp);
+        const newest = settled[settled.length - 1];
+        return newest ? name + "\t" + newest : null;
+      } catch { return null; }
+    })).then((rows) => process.stdout.write(rows.filter(Boolean).join("\n") + "\n"));
+  ' "$@"
+}
+
+# A create tool bakes its own dependency versions into the package.json it
+# generates, and those were current on the day that template was published —
+# create-next-app ships "@types/node": "^20", create-expo-app ships jest 29.
+# Nothing else in these scripts touches them, so the repo is born stale and
+# dependabot opens a PR against a project that is an hour old.
+#
+# Bring every range the template left behind to what the registry serves now.
+# The prefix style is preserved deliberately: an exact pin stays exact, a
+# caret stays a caret. This changes the version, not the template's policy.
+#
+# Packages a framework pins on purpose are passed in as exclusions and a
+# trailing * matches a prefix. Where the framework — not the registry — is
+# the authority for the whole app, use assert_expo_sdk_aligned instead.
+#
+# Usage: refresh_scaffold_deps [pkg-to-skip ...]
+refresh_scaffold_deps() {
+  local skips="$*" names versions
+  names="$(SKIPS="$skips" node -e '
+    const p = require(process.cwd() + "/package.json");
+    const skips = (process.env.SKIPS || "").split(/\s+/).filter(Boolean);
+    const skipped = (n) => skips.some((s) => (s.endsWith("*") ? n.startsWith(s.slice(0, -1)) : n === s));
+    const out = [];
+    for (const field of ["dependencies", "devDependencies"]) {
+      for (const [name, range] of Object.entries(p[field] || {})) {
+        // Anything that is not a plain registry range belongs to someone
+        // else: workspace:, file:, link:, npm:, a git url, or a bare "*".
+        if (!/^[\^~>=]*\d/.test(range)) continue;
+        if (skipped(name)) continue;
+        out.push(name);
+      }
+    }
+    process.stdout.write(out.join(" "));
+  ')"
+  [ -n "$names" ] || { log "no template-shipped ranges to refresh"; return 0; }
+
+  # Read into an array rather than relying on unquoted word splitting — this
+  # file is sourced, and not every shell that sources it splits on IFS.
+  local pkgs=()
+  read -ra pkgs <<< "$names"
+  log "checking ${#pkgs[@]} template-shipped ranges against the registry"
+  versions="$(registry_latest "${pkgs[@]}")" || { warn "registry unreachable — ranges left as the template wrote them"; return 0; }
+
+  cp package.json .package.json.pre-refresh
+  LATEST="$versions" node -e '
+    const fs = require("fs");
+    const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    const latest = new Map(
+      (process.env.LATEST || "").split("\n").filter(Boolean).map((l) => l.split("\t"))
+    );
+    let changed = 0;
+    for (const field of ["dependencies", "devDependencies"]) {
+      for (const [name, range] of Object.entries(p[field] || {})) {
+        const next = latest.get(name);
+        if (!next) continue;
+        const prefix = (range.match(/^[\^~]/) || [""])[0];
+        const current = range.replace(/^[\^~>=]*/, "");
+        if (current === next) continue;
+        const majorFrom = current.split(".")[0], majorTo = next.split(".")[0];
+        p[field][name] = prefix + next;
+        changed++;
+        console.log(
+          "  [+] " + name + " " + range + " -> " + prefix + next +
+          (majorFrom !== majorTo ? "   (major)" : "")
+        );
+      }
+    }
+    fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+    process.exit(changed ? 0 : 3);
+  ' || { rm -f .package.json.pre-refresh; log "every range was already current"; return 0; }
+
+  if ! yarn install; then
+    warn "install failed after refreshing ranges — restoring what the template wrote"
+    mv .package.json.pre-refresh package.json
+    yarn install || die "could not restore the template's dependency ranges"
+    return 0
+  fi
+
+  # A major move can compile fine and still be wrong, but it cannot be right
+  # if it does not compile. Check before leaving it in place.
+  if node -e 'const s=require("./package.json").scripts||{};process.exit(s.typecheck?0:1)'; then
+    if ! yarn typecheck; then
+      warn "typecheck failed after refreshing ranges — restoring what the template wrote"
+      warn "the versions above are current; something in the scaffold does not accept them"
+      mv .package.json.pre-refresh package.json
+      yarn install || die "could not restore the template's dependency ranges"
+      return 0
+    fi
+  fi
+  rm -f .package.json.pre-refresh
+  # Refreshing biome's own version is what makes its config stale — the
+  # $schema pin and any option renamed since the template shipped. Its
+  # migrate command is the thing that knows what changed.
+  yarn biome migrate --write >/dev/null 2>&1 || true
+  # JSON.stringify writes two spaces; the repo may be formatted with tabs.
+  # Without this the very next lint run fails on a file this function wrote.
+  yarn biome check --write package.json >/dev/null 2>&1 || true
+  log "template-shipped ranges refreshed"
+}
+
+# Expo is the one place where the registry is not the authority. The SDK is
+# built against specific versions of react, react-native and every native
+# module, and `expo install` resolves against that table rather than latest.
+# Installing those with add_latest produces a tree the SDK rejects — usually
+# at runtime, on a device, long after the scaffold reported success.
+#
+# So: install through expo_install, then make Expo itself confirm the result.
+assert_expo_sdk_aligned() {
+  log "realigning SDK-managed packages"
+
+  # Clear whatever a previous run deferred, so a package held back by the age
+  # gate last week is reconsidered today rather than excluded forever.
+  node -e '
+    const fs = require("fs");
+    const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    const prev = p.orchestra?.ageGateDeferred || [];
+    if (!prev.length) process.exit(0);
+    const ex = p.expo?.install?.exclude || [];
+    if (p.expo?.install) p.expo.install.exclude = ex.filter((n) => !prev.includes(n));
+    delete p.orchestra.ageGateDeferred;
+    if (!Object.keys(p.orchestra).length) delete p.orchestra;
+    fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+  '
+
+  # --fix aborts the whole batch when one package cannot be installed, so a
+  # failure here is a starting point rather than a verdict.
+  yarn expo install --fix >/dev/null 2>&1 || warn "expo install --fix did not complete — resolving what is left"
+
+  local deferred=() attempt
+  for attempt in 1 2; do
+    local out lines=() line name installed expected settled
+    out="$(yarn expo install --check 2>&1 || true)"
+    # "  expo@57.0.14 - expected version: ~57.0.15"
+    while IFS= read -r line; do
+      [ -n "$line" ] && lines+=("$line")
+    done < <(printf '%s\n' "$out" | grep -E '^[[:space:]]+\S+@\S+ - expected version: ' || true)
+
+    [ ${#lines[@]} -gt 0 ] || { log "every SDK-managed package matches the installed Expo SDK"; return 0; }
+    [ "$attempt" = 1 ] || break
+
+    for line in "${lines[@]}"; do
+      name="$(printf '%s' "$line" | sed -E 's/^[[:space:]]+(.+)@[^@]+ - expected version: .*/\1/')"
+      installed="$(printf '%s' "$line" | sed -E 's/^[[:space:]]+.+@([^@]+) - expected version: .*/\1/')"
+      expected="$(printf '%s' "$line" | sed -E 's/.* - expected version: //')"
+      settled="$(settled_near "$name" "$expected" || true)"
+      [ -n "$settled" ] || die "$name must be $expected for this SDK and no such version exists"
+      if [ "$settled" = "$installed" ]; then
+        # The SDK wants a version published inside yarn's age gate. This is
+        # the newest one outside it, so it is already the right answer.
+        deferred+=("$name")
+        warn "deferred: ${name}@${installed} (SDK wants ${expected}, still inside the age gate)"
+      else
+        log "  $name $installed -> $settled (SDK wants $expected)"
+        yarn add "$name@$settled" >/dev/null 2>&1 || die "could not install $name@$settled"
+      fi
+    done
+  done
+
+  # Whatever is still off must be something we deliberately deferred, or the
+  # scaffold is wrong and has to say so.
+  local unresolved=0 line name
+  while IFS= read -r line; do
+    name="$(printf '%s' "$line" | sed -E 's/^[[:space:]]+(.+)@[^@]+ - expected version: .*/\1/')"
+    printf '%s\n' "${deferred[@]:-}" | grep -qx "$name" || { warn "off the SDK table: $line"; unresolved=1; }
+  done < <(yarn expo install --check 2>&1 | grep -E '^[[:space:]]+\S+@\S+ - expected version: ' || true)
+  [ "$unresolved" = 0 ] || die "packages remain off the installed Expo SDK"
+
+  # A deliberate, explained deviation has to be recorded where the tooling
+  # reads it, or `expo-doctor` fails on a brand-new project and the gate is
+  # broken before anyone has written a line of code. expo.install.exclude is
+  # the mechanism Expo provides for exactly this; orchestra.ageGateDeferred
+  # records which entries are ours, so the next run can clear them.
+  if [ ${#deferred[@]} -gt 0 ]; then
+    DEFERRED="${deferred[*]}" node -e '
+      const fs = require("fs");
+      const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+      const names = process.env.DEFERRED.split(/\s+/).filter(Boolean);
+      p.expo = p.expo || {};
+      p.expo.install = p.expo.install || {};
+      p.expo.install.exclude = [...new Set([...(p.expo.install.exclude || []), ...names])];
+      p.orchestra = { ...(p.orchestra || {}), ageGateDeferred: names };
+      fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+    '
+    warn "recorded in expo.install.exclude — re-run once these clear the age gate"
+  fi
+
+  # expo install rewrites package.json with its own formatting.
+  yarn biome check --write package.json >/dev/null 2>&1 || true
+  log "every SDK-managed package is on the newest version the SDK allows"
+}
+
+# A pinned action version ages exactly like a pinned package version, and
+# actions/checkout@v4 in a workflow generated today is a dependabot PR that
+# has already been written. Resolve the current major tag instead.
+# Falls back to the given value when the API is unreachable or rate-limited.
+latest_action_ref() { # owner/repo fallback
+  local repo="$1" fallback="$2" tag
+  tag="$(curl -fsSL --max-time 10 "https://api.github.com/repos/${repo}/releases/latest" 2>/dev/null \
+    | node -e '
+        let s = "";
+        process.stdin.on("data", (d) => (s += d)).on("end", () => {
+          try {
+            const t = JSON.parse(s).tag_name;
+            if (t) process.stdout.write(String(t).split(".")[0]);
+          } catch {
+        // Optional by design: the ref simply does not exist here.
+      }
+        });
+      ' 2>/dev/null)" || true
+  if [ -n "$tag" ]; then
+    printf '%s' "$tag"
+  else
+    warn "could not resolve the current ${repo} release — using ${fallback}"
+    printf '%s' "$fallback"
+  fi
+}
+
+# The first install of a freshly generated package.json is the one place the
+# age gate cannot be worked around by resolving versions ourselves — the
+# create tool already wrote the ranges, and one of them may name a version
+# published an hour ago. create-expo-app does this routinely: it writes
+# "expo": "~57.0.15" the day 57.0.15 ships, yarn quarantines it, and the
+# whole scaffold dies on its first install.
+#
+# Turning the gate off is not the fix. Step the quarantined ranges back to
+# the newest version that has settled, staying inside what the range meant.
+yarn_install() {
+  # Yarn turns on immutable installs by itself when CI is set, and an
+  # immutable install refuses to create a lockfile — "YN0028: The lockfile
+  # would have been created by this install, which is explicitly forbidden".
+  # That is the right default for a repo that has one and a guaranteed failure
+  # for a scaffold that is producing it for the first time. Scoped to this
+  # function, so the generated project still gets the strict behaviour.
+  export YARN_ENABLE_IMMUTABLE_INSTALLS=false
+
+  # Captured on the first attempt, not by running the install a second time.
+  # The old shape ran it twice — once for the person watching, once to grep —
+  # and the second run does not print what the first did: yarn had already
+  # resolved, so the quarantine notice was gone and every age-gate failure
+  # was reported as "not the age gate". CI found this on expo.
+  local out rc=0 specs=()
+  out="$(yarn install 2>&1)" || rc=$?
+  printf '%s\n' "$out"
+  # An if, not `[ ... ] && return`: under set -e a failing test as the final
+  # command of a && list exits the script, which would abort the scaffold at
+  # exactly the point this function exists to recover from.
+  if [ "$rc" -eq 0 ]; then return 0; fi
+  # YN0016: │ expo@npm:~57.0.15: All versions satisfying "~57.0.15" are quarantined
+  while IFS= read -r spec; do
+    [ -n "$spec" ] && specs+=("$spec")
+  # ANSI stripped first. Yarn colourises its output when GITHUB_ACTIONS is
+  # set — not when it is merely CI — so in Actions the package name arrives
+  # wrapped in escape codes and every pattern here missed it. That is why this
+  # branch reported "not the age gate" on the one stack that hits the age gate.
+  done < <(printf '%s\n' "$out" \
+    | sed $'s/\033\[[0-9;]*m//g' \
+    | grep -o '[^ │]*@npm:[^:]*: All versions satisfying' \
+    | sed 's/: All versions satisfying$//')
+
+  [ ${#specs[@]} -gt 0 ] || die "yarn install failed for a reason that is not the age gate — see the output above"
+
+  warn "the age gate quarantined ${#specs[@]} package(s) the template asked for"
+  local spec name range
+  for spec in "${specs[@]}"; do
+    name="${spec%@npm:*}"
+    range="${spec##*@npm:}"
+    local settled
+    settled="$(settled_near "$name" "$range")" || { warn "  no settled version for $name — leaving $range alone"; continue; }
+    node -e '
+      const fs = require("fs");
+      const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+      const [name, range, next] = process.argv.slice(1);
+      const prefix = (range.match(/^[\^~]/) || [""])[0];
+      for (const field of ["dependencies", "devDependencies"]) {
+        if (p[field] && p[field][name]) p[field][name] = prefix + next;
+      }
+      fs.writeFileSync("package.json", JSON.stringify(p, null, 2) + "\n");
+    ' "$name" "$range" "$settled"
+    log "  ${name} ${range} -> ${settled} (newest past the gate)"
+  done
+
+  yarn install || die "yarn install still fails after stepping back the quarantined packages"
+}
+
+# Newest settled version of a package that stays inside what a range meant:
+# the same major.minor for a tilde range, the same major otherwise. Falling
+# outside that is a different package as far as the scaffold is concerned.
+settled_near() { # pkg range
+  local pkg="$1" range="$2" gate
+  gate="$(yarn config get npmMinimalAgeGate 2>/dev/null || echo 1440)"
+  case "$gate" in ''|*[!0-9]*) gate=1440 ;; esac
+  GATE_MINUTES="$gate" RANGE="$range" node -e '
+    const name = process.argv[1];
+    const range = process.env.RANGE || "";
+    const cutoff = Date.now() - Number(process.env.GATE_MINUTES) * 60 * 1000;
+    const bare = range.replace(/^[\^~>=\s]*/, "");
+    const [major, minor] = bare.split(".");
+    const tilde = range.trim().startsWith("~");
+    const cmp = (a, b) => {
+      const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+      for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+      return 0;
+    };
+    fetch("https://registry.npmjs.org/" + name.replace("/", "%2f"))
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error("registry " + r.status))))
+      .then((doc) => {
+        const settled = Object.entries(doc.time || {})
+          .filter(([v]) => /^\d+\.\d+\.\d+$/.test(v))
+          .filter(([, t]) => Date.parse(t) < cutoff)
+          .map(([v]) => v)
+          .filter((v) => {
+            const [vMajor, vMinor] = v.split(".");
+            if (major && vMajor !== major) return false;
+            if (tilde && minor && vMinor !== minor) return false;
+            return true;
+          })
+          .sort(cmp);
+        if (!settled.length) process.exit(1);
+        process.stdout.write(settled[settled.length - 1]);
+      })
+      .catch(() => process.exit(1));
+  ' "$pkg"
+}
+
+# Gradle has no safe "@latest" — a dynamic version destroys build
+# reproducibility, which is why the version catalog pins explicitly. That is
+# an argument for writing the version down, not for writing it from memory:
+# resolve it from the repository here, then pin the result. Explicit and
+# current, rather than explicit and frozen at the time this script was typed.
+#
+# Usage: maven_latest <repo-base-url> <group> <artifact> <fallback>
+maven_latest() {
+  local repo="$1" group="$2" artifact="$3" fallback="$4" path v
+  path="$(printf '%s' "$group" | tr '.' '/')"
+  v="$(curl -fsSL --max-time 20 "${repo}/${path}/${artifact}/maven-metadata.xml" 2>/dev/null \
+    | grep -oE '<version>[^<]+</version>' \
+    | sed 's/<[^>]*>//g' \
+    | grep -viE 'alpha|beta|rc[0-9]|-rc|dev|eap|snapshot|-M[0-9]' \
+    | tail -1)" || true
+  if [ -n "$v" ]; then
+    printf '%s' "$v"
+  else
+    warn "could not resolve ${group}:${artifact} — using ${fallback}"
+    printf '%s' "$fallback"
+  fi
+}
+
+GOOGLE_MAVEN="https://dl.google.com/dl/android/maven2"
+MAVEN_CENTRAL="https://repo1.maven.org/maven2"
+
+# The gradle wrapper pins the build tool itself. Same rule as everything
+# else: read the current version, then write it down.
+gradle_latest() { # fallback
+  local fallback="$1" v
+  v="$(curl -fsSL --max-time 20 https://services.gradle.org/versions/current 2>/dev/null \
+    | node -e '
+        let s = "";
+        process.stdin.on("data", (d) => (s += d)).on("end", () => {
+          try {
+            const j = JSON.parse(s);
+            if (j.version && !j.nightly && !j.snapshot) process.stdout.write(j.version);
+          } catch {
+        // Optional by design: the ref simply does not exist here.
+      }
+        });
+      ' 2>/dev/null)" || true
+  if [ -n "$v" ]; then printf '%s' "$v"; else
+    warn "could not resolve the current gradle release — using ${fallback}"
+    printf '%s' "$fallback"
+  fi
+}
+
+# The gate that actually changes behaviour: branch coverage of the lines this
+# change touched. A global percentage reports the historical average and says
+# nothing about the code being written now.
+#
+# Written once at the repo root and shared by every app, like verify.sh.
+write_diff_coverage_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/diff-coverage.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/diff-coverage.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Branch coverage of the lines this change touched.
+ *
+ * A global coverage percentage reports a historical average. It cannot tell
+ * you whether the code in this pull request was tested, which is the only
+ * question a reviewer actually has.
+ *
+ * Usage: node scripts/diff-coverage.mjs [--app <dir>] [--base <ref>]
+ * Reads the threshold from .orchestra/config.yml (testing.coverage
+ * .diff_branch_threshold), falling back to 90.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const argv = process.argv.slice(2);
+const arg = (name, fallback) => {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? fallback : argv[i + 1];
+};
+
+const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const app = resolve(arg("app", process.cwd()));
+
+function threshold() {
+  const f = join(root, ".orchestra", "config.yml");
+  if (!existsSync(f)) return 90;
+  const m = readFileSync(f, "utf8").match(/^\s*diff_branch_threshold:\s*(\d+)/m);
+  return m ? Number(m[1]) : 90;
+}
+
+/** The first ref that resolves. A shallow CI clone may have none of them. */
+function baseRef() {
+  const explicit = arg("base", process.env.DIFF_COVERAGE_BASE);
+  const candidates = explicit ? [explicit] : ["origin/main", "origin/master", "main", "master"];
+  for (const ref of candidates) {
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { stdio: "pipe" });
+      return ref;
+    } catch {
+        // Optional by design: the ref simply does not exist here.
+      }
+  }
+  return null;
+}
+
+/** Added line numbers per file, from a zero-context diff. */
+function changedLines(base) {
+  const out = execFileSync(
+    "git",
+    ["diff", "--unified=0", "--no-color", `${base}...HEAD`, "--", relative(root, app) || "."],
+    { encoding: "utf8", cwd: root, maxBuffer: 64 * 1024 * 1024 }
+  );
+  const files = new Map();
+  let current = null;
+  for (const line of out.split("\n")) {
+    if (line.startsWith("+++ b/")) {
+      current = line.slice(6);
+      if (!files.has(current)) files.set(current, new Set());
+      continue;
+    }
+    if (!current || !line.startsWith("@@")) continue;
+    // @@ -12,0 +13,4 @@  → lines 13..16 are new
+    const m = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (!m) continue;
+    const start = Number(m[1]);
+    const count = m[2] === undefined ? 1 : Number(m[2]);
+    for (let i = 0; i < count; i++) files.get(current).add(start + i);
+  }
+  return files;
+}
+
+/** Only source files. A config or a test moving is not a coverage question. */
+const isSource = (p) =>
+  /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(p) &&
+  !/\.(test|spec)\./.test(p) &&
+  !/\.config\./.test(p) &&
+  !/\.d\.ts$/.test(p) &&
+  !/(^|\/)(node_modules|dist|build|coverage|\.next)\//.test(p);
+
+const base = baseRef();
+if (!base) {
+  console.log("  diff coverage: no base ref resolved — skipped");
+  process.exit(0);
+}
+
+const reportPath = join(app, "coverage", "coverage-final.json");
+if (!existsSync(reportPath)) {
+  console.error(`  diff coverage: no coverage report at ${reportPath} — run the coverage script first`);
+  process.exit(1);
+}
+const report = JSON.parse(readFileSync(reportPath, "utf8"));
+// Report keys are absolute; the diff is repo-relative.
+const byRelative = new Map(
+  Object.entries(report).map(([abs, data]) => [relative(root, abs), data])
+);
+
+const files = [...changedLines(base)].filter(([f]) => isSource(f));
+if (!files.length) {
+  console.log("  diff coverage: no source lines changed — nothing to gate");
+  process.exit(0);
+}
+
+let total = 0;
+let covered = 0;
+const misses = [];
+
+for (const [file, lines] of files) {
+  const data = byRelative.get(file);
+  if (!data) {
+    // Changed source the coverage run never loaded: nothing imported it, so
+    // nothing tested it. That is a miss, not an absence of data.
+    misses.push(`${file} — not present in the coverage report (no test imports it)`);
+    total += 1;
+    continue;
+  }
+  let fileTotal = 0;
+  let fileCovered = 0;
+
+  for (const [id, meta] of Object.entries(data.branchMap || {})) {
+    const counts = data.b?.[id] || [];
+    (meta.locations || []).forEach((loc, k) => {
+      const line = loc?.start?.line;
+      if (!line || !lines.has(line)) return;
+      fileTotal++;
+      if ((counts[k] || 0) > 0) fileCovered++;
+    });
+  }
+
+  // A changed line with no branch on it still has to have run at least once,
+  // otherwise a whole new untested function reads as 100%.
+  for (const [id, meta] of Object.entries(data.statementMap || {})) {
+    const line = meta?.start?.line;
+    if (!line || !lines.has(line)) continue;
+    fileTotal++;
+    if ((data.s?.[id] || 0) > 0) fileCovered++;
+  }
+
+  if (!fileTotal) continue;
+  total += fileTotal;
+  covered += fileCovered;
+  if (fileCovered < fileTotal) {
+    misses.push(`${file} — ${fileCovered}/${fileTotal} on changed lines`);
+  }
+}
+
+if (!total) {
+  console.log("  diff coverage: changed lines carry nothing executable — nothing to gate");
+  process.exit(0);
+}
+
+const pct = (covered / total) * 100;
+const min = threshold();
+console.log(`  diff coverage: ${pct.toFixed(1)}% of changed lines (${covered}/${total}), gate ${min}%  [base ${base}]`);
+for (const m of misses) console.log(`    - ${m}`);
+
+if (pct + 1e-9 < min) {
+  console.error(`  [x] changed lines are below the ${min}% gate`);
+  process.exit(1);
+}
+JS
+  chmod +x "$root/scripts/diff-coverage.mjs"
+  log "wrote scripts/diff-coverage.mjs"
+}
+
+# Coverage says a line ran. Mutation says the line was checked.
+#
+# Stryker rewrites the code one small change at a time — `>` becomes `>=`, a
+# return value is replaced — and runs the suite. A test suite that still
+# passes was executing that code without asserting anything about it.
+#
+# A full run takes hours, so the gate is scoped to the files a pull request
+# changed. The full run is a scheduled job.
+setup_mutation() {
+  # TypeScript 7 is the Go port, and it dropped the compiler JS API entirely:
+  # createProgram, readConfigFile and parseConfigFileTextToJson no longer
+  # exist. Stryker's sandbox preprocessor calls into that API before any of
+  # its own options are consulted, so it crashes on every run regardless of
+  # `checkers` or `tsconfigFile`. Installing it anyway would ship a package
+  # script that cannot work.
+  #
+  # This is a check on Stryker's dependency, not a permanent verdict. Drop it
+  # when Stryker supports the new compiler.
+  local ts_major
+  ts_major="$(node -e 'try{process.stdout.write(String(require("typescript").version).split(".")[0])}catch{process.stdout.write("0")}' 2>/dev/null || echo 0)"
+  if [ "${ts_major:-0}" -ge 7 ]; then
+    warn "mutation testing skipped: stryker needs the typescript compiler API,"
+    warn "which typescript ${ts_major} removed. Re-run setup_mutation once stryker"
+    warn "supports it — everything else it needs is already in place."
+    return 0
+  fi
+
+  local runner
+  if node -e 'const p=require("./package.json");const d={...p.dependencies,...p.devDependencies};process.exit(d.vitest?0:1)' 2>/dev/null; then
+    runner="vitest"
+  elif node -e 'const p=require("./package.json");const d={...p.dependencies,...p.devDependencies};process.exit(d.jest?0:1)' 2>/dev/null; then
+    runner="jest"
+  else
+    warn "no vitest or jest found — mutation testing not configured"
+    return 0
+  fi
+
+  add_latest --dev "@stryker-mutator/core" "@stryker-mutator/${runner}-runner" "@stryker-mutator/typescript-checker"
+
+  if [ ! -f stryker.config.json ]; then
+    RUNNER="$runner" node -e '
+      const fs = require("fs");
+      fs.writeFileSync("stryker.config.json", JSON.stringify({
+        $schema: "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+        testRunner: process.env.RUNNER,
+        checkers: ["typescript"],
+        tsconfigFile: "tsconfig.json",
+        // Only run the tests that actually cover each mutant.
+        coverageAnalysis: "perTest",
+        mutate: ["src/**/*.ts", "src/**/*.tsx", "!src/**/*.test.*", "!src/**/*.d.ts"],
+        // Caches results between runs so a scoped run stays fast.
+        incremental: true,
+        reporters: ["clear-text", "progress"],
+        // break is the failing gate; see testing.mutation.break_threshold in
+        // .orchestra/config.yml. scripts/mutation-diff.mjs passes the current
+        // value, so this is only the floor for a direct `yarn test:mutation`.
+        thresholds: { high: 85, low: 70, break: 70 },
+      }, null, 2) + "\n");
+    '
+  fi
+
+  write_mutation_diff_script
+  # The app is not always two levels down — a single-app repo has no apps/.
+  # Resolve the path rather than assuming the layout.
+  local root rel
+  root="$(git rev-parse --show-toplevel)"
+  rel="$(node -e 'const p=require("path");process.stdout.write(p.relative(process.cwd(), process.argv[1]))' "$root/scripts/mutation-diff.mjs")"
+  pkg_set scripts.test:mutation="stryker run" \
+          scripts.test:mutation:diff="node $rel"
+
+  # Stryker writes its incremental cache and reports here. Neither belongs in
+  # a commit — CI restores the cache from its own store.
+  if ! grep -q '^reports/' .gitignore 2>/dev/null; then
+    printf '\n# stryker\nreports/\n.stryker-tmp/\n' >> .gitignore
+  fi
+
+  log "mutation testing (${runner} runner), scoped to changed files"
+}
+
+# Companion to the above: works out what this change touched and hands only
+# those files to Stryker.
+write_mutation_diff_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/mutation-diff.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/mutation-diff.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Mutation testing over the files this change touched.
+ *
+ * A full Stryker run takes hours, which is why it belongs on a schedule. The
+ * per-pull-request gate mutates only what changed, which is where a missing
+ * assertion was just introduced anyway.
+ *
+ * Usage: node scripts/mutation-diff.mjs [--base <ref>]   (run from the app dir)
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+
+const argv = process.argv.slice(2);
+const arg = (name, fallback) => {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? fallback : argv[i + 1];
+};
+
+const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const app = resolve(process.cwd());
+
+function breakThreshold() {
+  const f = join(root, ".orchestra", "config.yml");
+  if (!existsSync(f)) return 70;
+  const m = readFileSync(f, "utf8").match(/^\s*break_threshold:\s*(\d+)/m);
+  return m ? Number(m[1]) : 70;
+}
+
+function baseRef() {
+  const explicit = arg("base", process.env.MUTATION_BASE);
+  const candidates = explicit ? [explicit] : ["origin/main", "origin/master", "main", "master"];
+  for (const ref of candidates) {
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { stdio: "pipe" });
+      return ref;
+    } catch {
+        // Optional by design: the ref simply does not exist here.
+      }
+  }
+  return null;
+}
+
+const base = baseRef();
+if (!base) {
+  console.log("  mutation: no base ref resolved — skipped");
+  process.exit(0);
+}
+
+const appPrefix = relative(root, app);
+const changed = execFileSync(
+  "git",
+  ["diff", "--name-only", "--diff-filter=ACMR", `${base}...HEAD`, "--", appPrefix || "."],
+  { encoding: "utf8", cwd: root }
+)
+  .split("\n")
+  .filter(Boolean)
+  // Repo-relative from git, app-relative for stryker.
+  .map((f) => (appPrefix ? relative(appPrefix, f) : f))
+  .filter(
+    (f) =>
+      /^src\/.*\.(ts|tsx)$/.test(f) &&
+      !/\.(test|spec)\./.test(f) &&
+      !/\.d\.ts$/.test(f)
+  );
+
+if (!changed.length) {
+  console.log("  mutation: no source files changed — nothing to mutate");
+  process.exit(0);
+}
+
+console.log(`  mutation: ${changed.length} changed file(s) [base ${base}]`);
+for (const f of changed) console.log(`    - ${f}`);
+
+// Stryker has no CLI flag for thresholds, and rewriting the committed
+// stryker.config.json at run time would leave a dirty tree. Generate a
+// throwaway config instead, so .orchestra/config.yml stays the one place the
+// break threshold is written down.
+const strykerConfig = existsSync(join(app, "stryker.config.json"))
+  ? JSON.parse(readFileSync(join(app, "stryker.config.json"), "utf8"))
+  : {};
+strykerConfig.thresholds = { ...(strykerConfig.thresholds || {}), break: breakThreshold() };
+const tmpDir = join(app, "reports");
+mkdirSync(tmpDir, { recursive: true });
+const tmpConfig = join(tmpDir, "stryker-diff.config.json");
+writeFileSync(tmpConfig, `${JSON.stringify(strykerConfig, null, 2)}\n`);
+
+const res = spawnSync(
+  "npx",
+  [
+    "stryker",
+    "run",
+    // The config file is a positional argument, not a flag.
+    relative(app, tmpConfig),
+    "--mutate",
+    changed.join(","),
+    "--incremental",
+    // A change that produces no mutants is not a failure.
+    "--allowEmpty",
+  ],
+  { stdio: "inherit", cwd: app }
+);
+process.exit(res.status ?? 1);
+JS
+  chmod +x "$root/scripts/mutation-diff.mjs"
+  log "wrote scripts/mutation-diff.mjs"
+}
+
+# Jest's equivalent of the vitest block above. Jest has no autoUpdate, so the
+# ratchet is a script that raises the committed threshold after a run that
+# beat it; jest's own coverageThreshold is what fails on a drop.
+# The folder the seam threshold points at, with the reason it exists written
+# where an agent will actually meet it — in the repo, not only in a skill.
+setup_integrations_dir() {
+  mkdir -p src/integrations
+  cat > src/integrations/README.md <<'MD'
+# integrations
+
+Anything that calls a third party's SDK or HTTP API lives here, one directory
+per provider. Nothing else imports that SDK.
+
+## Why
+
+**So the test suite has something to hold.** The rule in
+`.claude/rules/testing-standards.orchestra.md` is that a function calling into
+a third-party library has a test, and that a dependency bump which changes
+behaviour turns the suite red. Called inline across a dozen handlers there is
+no function to test, and the bump goes green.
+
+Coverage here is held at **100%** for that reason — these modules are small,
+so it is achievable, unlike a global 100%.
+
+**And so the policy is applied once.** Timeout, bounded retry, circuit
+breaker, error mapping, keeping the key out of the logs — see
+`.claude/skills/architecture/SKILL.md`. Spread across a dozen call sites you
+will miss one, and the one you miss is the one that hangs.
+
+## What this is not
+
+It is not an abstraction that makes the provider swappable. That is a guess
+about a migration that usually never happens, and it produces a
+lowest-common-denominator wrapper worse than the SDK. A wrapper here is thin,
+exposes what this app needs in this app's types, and is allowed to look
+obviously like the provider it wraps.
+
+## The threshold asks for exercise, not a test file
+
+An integration test that drives the wrapper through a faked HTTP boundary
+satisfies it. Do not add a unit test beside the wrapper to repeat what a route
+test already covers — see the same rule on not writing tests to move a number.
+MD
+  log "src/integrations/ — third-party wrappers, held at 100%"
+}
+
+setup_coverage_jest() {
+  # The reporters below write coverage/ into the app. create-next-app ignores
+  # it; create-hono and create-expo-app do not, so without this the first
+  # `git add -A` commits an HTML coverage report.
+  if ! grep -qE '^/?coverage' .gitignore 2>/dev/null; then
+    printf '\n# coverage output\ncoverage/\n' >> .gitignore
+  fi
+
+  pkg_set jest.coverageThreshold.global.lines=0 \
+          jest.coverageThreshold.global.functions=0 \
+          jest.coverageThreshold.global.branches=0 \
+          jest.coverageThreshold.global.statements=0
+  # json-summary feeds the ratchet, json feeds scripts/diff-coverage.mjs.
+  pkg_set 'jest.coverageReporters=["text","json","json-summary","lcov"]'
+  pkg_set 'jest.coveragePathIgnorePatterns=["/node_modules/","\\.d\\.ts$","/design/tokens\\.","\\.config\\.","/index\\.ts$"]'
+  # Every source file, not only the ones a test happened to load — same
+  # reason as the vitest branch. coveragePathIgnorePatterns above is where
+  # something that genuinely should not count goes.
+  pkg_set 'jest.collectCoverageFrom=["src/**/*.{ts,tsx}"]'
+
+  write_diff_coverage_script
+  write_coverage_ratchet_script
+
+  local root rel_ratchet rel_diff
+  root="$(git rev-parse --show-toplevel)"
+  rel_ratchet="$(node -e 'const p=require("path");process.stdout.write(p.relative(process.cwd(), process.argv[1]))' "$root/scripts/coverage-ratchet.mjs")"
+  rel_diff="$(node -e 'const p=require("path");process.stdout.write(p.relative(process.cwd(), process.argv[1]))' "$root/scripts/diff-coverage.mjs")"
+  # Same reason as the vitest branch: the ratchet rewrites package.json, and
+  # an unformatted package.json fails the next lint run.
+  # The seam sync runs first: jest fails outright when the glob matches
+  # nothing, so the key has to be right before jest starts, not after.
+  pkg_set scripts.test:coverage="node ${rel_ratchet} --sync-seams && jest --coverage --passWithNoTests && node ${rel_ratchet} && biome check --write package.json"
+  pkg_set scripts.test:coverage:diff="node ${rel_diff}"
+  log "coverage: ratchet + diff gate (jest)"
+}
+
+# Clamps the floor vitest's autoUpdate just wrote.
+#
+# autoUpdate records whatever the run achieved, which on a fresh scaffold is
+# 100% — the app is 71 lines and fully tested. That turns the ratchet into a
+# 100% line-coverage mandate on day one, stricter than the diff gate, decided
+# by nobody. The clamp holds the floor at testing.coverage.ratchet_ceiling.
+#
+# Only the global keys are touched, and the cap decides that by nesting depth
+# rather than by how the file happens to be formatted. It used to rely on a
+# seam glob sitting on one line so a line-anchored match could not reach it —
+# then a formatter broke the line apart and the seam gate was silently
+# rewritten from 100 to 90 on every web app.
+write_coverage_cap_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/coverage-cap.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/coverage-cap.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Hold the coverage ratchet below a ceiling.
+ *
+ * Vitest's thresholds.autoUpdate writes down whatever the run achieved. On a
+ * small, fully covered codebase that is 100, and the floor then demands every
+ * future line be covered — a target nobody set, and stricter than the diff
+ * gate that was chosen on purpose. Tests written to satisfy it are tests
+ * written to move a number, which .claude/rules/testing-standards.orchestra.md
+ * says to refuse rather than comply with.
+ *
+ * Run after `vitest run --coverage`, from the app directory.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+
+function ceiling() {
+  const f = join(root, ".orchestra", "config.yml");
+  if (!existsSync(f)) return 90;
+  const m = readFileSync(f, "utf8").match(/^\s*ratchet_ceiling:\s*(\d+(?:\.\d+)?)/m);
+  return m ? Number(m[1]) : 90;
+}
+
+const configPath = join(process.cwd(), "vitest.config.ts");
+if (!existsSync(configPath)) {
+  console.log("  coverage cap: no vitest.config.ts — skipped");
+  process.exit(0);
+}
+
+const cap = ceiling();
+const before = readFileSync(configPath, "utf8");
+
+/**
+ * Only the top-level ratchet, never a per-glob threshold.
+ *
+ * This used to rely on the seam globs being written on one line, so a
+ * line-anchored regex could not reach them. A formatter breaks that line
+ * across several, and then the seam gate the whole testing rule rests on was
+ * quietly rewritten from 100 to 90 — on every web app, invisibly.
+ *
+ * Depth is the thing that actually distinguishes them: the ratchet's keys are
+ * direct children of `thresholds`, a per-glob block is nested one deeper. So
+ * count braces instead of trusting how the file happens to be formatted.
+ */
+const capped = [];
+const lines = before.split("\n");
+let depth = -1; // -1 until `thresholds: {` is seen; 0 inside it
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  if (depth === -1) {
+    if (/\bthresholds\s*:\s*\{/.test(line)) depth = 0;
+    continue;
+  }
+
+  const match = /^(\s*)(lines|functions|branches|statements): (\d+(?:\.\d+)?),$/.exec(line);
+  if (match && depth === 0 && Number(match[3]) > cap) {
+    capped.push(`${match[2]} ${match[3]} -> ${cap}`);
+    lines[i] = `${match[1]}${match[2]}: ${cap},`;
+  }
+
+  const opens = (line.match(/\{/g) || []).length;
+  const closes = (line.match(/\}/g) || []).length;
+  depth += opens - closes;
+  if (depth < 0) break; // out of the thresholds block
+}
+const after = lines.join("\n");
+
+if (!capped.length) {
+  console.log(`  coverage cap: floor already at or below ${cap}`);
+  process.exit(0);
+}
+
+writeFileSync(configPath, after);
+console.log(`  coverage cap: ${capped.join(", ")}`);
+JS
+  chmod +x "$root/scripts/coverage-cap.mjs"
+  log "wrote scripts/coverage-cap.mjs"
+}
+
+# Raises the committed jest threshold to what the run actually achieved.
+# Never lowers it — that is the whole point.
+write_coverage_ratchet_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/coverage-ratchet.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/coverage-ratchet.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Coverage ratchet for jest. Vitest does this itself via
+ * thresholds.autoUpdate; jest does not.
+ *
+ * Two jobs, and the order matters:
+ *
+ *   --sync-seams   runs BEFORE jest. Adds the seam threshold when the first
+ *                  third-party wrapper appears under src/integrations/, and
+ *                  removes it when the last one goes. Jest fails the whole run
+ *                  with "Coverage data for <glob> was not found" when the glob
+ *                  matches nothing, so a fresh app cannot carry the key — and
+ *                  an app whose last wrapper was just deleted would be stuck
+ *                  failing if the key were only removed afterwards.
+ *
+ *   (no flag)      runs AFTER jest. Raises the committed global threshold to
+ *                  what the run achieved, and never lowers it. Jest's own
+ *                  check is what fails a drop; this only moves the floor up.
+ *
+ * The seam threshold asks that the wrapper be exercised, not that a test file
+ * sit beside it: an integration test driving it through a faked HTTP boundary
+ * satisfies it.
+ *
+ * Run from the app directory.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const syncSeamsOnly = process.argv.includes("--sync-seams");
+
+/**
+ * The highest floor this is allowed to record. Without it the ratchet writes
+ * down whatever a small, fully covered app achieved — 100 — and every line
+ * written afterwards has to be covered or the build fails. That is stricter
+ * than the diff gate, and it is a target nobody set.
+ */
+function ceiling() {
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    const f = join(root, ".orchestra", "config.yml");
+    if (!existsSync(f)) return 90;
+    const m = readFileSync(f, "utf8").match(/^\s*ratchet_ceiling:\s*(\d+(?:\.\d+)?)/m);
+    return m ? Number(m[1]) : 90;
+  } catch {
+    // Not a git checkout, or no config: the default is the documented one.
+    return 90;
+  }
+}
+const pkgPath = join(process.cwd(), "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+pkg.jest = pkg.jest || {};
+pkg.jest.coverageThreshold = pkg.jest.coverageThreshold || {};
+
+const notes = [];
+
+/** Seam key maintenance — see the header. */
+const SEAM_GLOB = "./src/integrations/**";
+const seamDir = join(process.cwd(), "src", "integrations");
+const hasSeams =
+  existsSync(seamDir) &&
+  readdirSync(seamDir, { recursive: true })
+    .map(String)
+    .some((f) => /\.(ts|tsx|js|jsx)$/.test(f) && !/\.(test|spec)\./.test(f));
+
+if (hasSeams && !pkg.jest.coverageThreshold[SEAM_GLOB]) {
+  pkg.jest.coverageThreshold[SEAM_GLOB] = {
+    lines: 100,
+    functions: 100,
+    branches: 100,
+    statements: 100,
+  };
+  notes.push(`seam threshold on ${SEAM_GLOB}`);
+} else if (!hasSeams && pkg.jest.coverageThreshold[SEAM_GLOB]) {
+  delete pkg.jest.coverageThreshold[SEAM_GLOB];
+  notes.push("seam threshold removed (no wrappers left)");
+}
+
+const save = () => {
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  console.log(`  coverage ratchet: ${notes.join(", ")}`);
+};
+
+if (syncSeamsOnly) {
+  if (notes.length) save();
+  process.exit(0);
+}
+
+const summaryPath = join(process.cwd(), "coverage", "coverage-summary.json");
+if (!existsSync(summaryPath)) {
+  if (notes.length) save();
+  else console.log("  coverage ratchet: no summary report — skipped");
+  process.exit(0);
+}
+
+const total = JSON.parse(readFileSync(summaryPath, "utf8")).total;
+if (!total) {
+  if (notes.length) save();
+  else console.log("  coverage ratchet: summary has no totals — skipped");
+  process.exit(0);
+}
+
+const cap = ceiling();
+const current = pkg.jest.coverageThreshold.global || {};
+for (const key of ["lines", "functions", "branches", "statements"]) {
+  // The seam globs are separate keys and are not capped — 100 there is the
+  // point, and those modules are small enough for it to mean something.
+  const achieved = Math.min(Math.floor(total[key]?.pct ?? 0), cap);
+  const committed = current[key] ?? 0;
+  if (achieved > committed) {
+    current[key] = achieved;
+    notes.push(`${key} ${committed} -> ${achieved}`);
+  }
+}
+
+if (!notes.length) {
+  console.log("  coverage ratchet: no improvement to record");
+  process.exit(0);
+}
+
+pkg.jest.coverageThreshold.global = current;
+save();
+JS
+  chmod +x "$root/scripts/coverage-ratchet.mjs"
+  log "wrote scripts/coverage-ratchet.mjs"
+}
+
+# End-to-end on a real simulator or emulator. This is the layer that is not
+# optional on mobile: jest-expo runs components in Node against mocked native
+# modules, so the entire JS suite can be green while the app does not launch.
+#
+# Maestro rather than Detox — YAML flows, no native build knowledge needed.
+# It is a CLI installed by its own installer, not an npm package, so this
+# writes the flows and the script and reports if the binary is absent.
+setup_maestro() {
+  mkdir -p .maestro
+
+  # Maestro addresses the installed app by its id, so a guess here produces a
+  # flow that runs against an app that is not on the device. Read it, and
+  # refuse to write flows if it is not set — `expo prebuild` would otherwise
+  # derive one from the machine's username, differently on every machine.
+  local app_id
+  app_id="$(node -e '
+    const fs = require("fs");
+    const f = ["app.json", "app.config.json"].find((x) => fs.existsSync(x));
+    const cfg = f ? JSON.parse(fs.readFileSync(f, "utf8")).expo || {} : {};
+    process.stdout.write(cfg.android?.package || cfg.ios?.bundleIdentifier || "");
+  ')"
+  [ -n "$app_id" ] || die "no android.package or ios.bundleIdentifier in app.json — maestro cannot address the app"
+
+  # The flow asserts a marker the app itself renders, rather than
+  # `assertVisible: id: ".*"`. The loose form matches any element in the
+  # foreground app's tree — including React Native's red "could not connect
+  # to development server" screen — so it cannot tell a mounted app from one
+  # that failed to load its bundle. app-root is rendered only by our own root
+  # view, so matching it proves the tree mounted.
+  #
+  # Verified on a simulator: react-native maps testID to the iOS
+  # accessibility identifier, which maestro matches as resource-id.
+  #
+  # Refuse rather than write the weaker assertion silently.
+  grep -q 'testID="app-root"' App.tsx 2>/dev/null \
+    || die "App.tsx has no testID=\"app-root\" — the launch flow could only assert that some element exists"
+
+  cat > .maestro/launch.yaml <<YAML
+# The single highest-value mobile check: the app starts, and it is the app in
+# front.
+#
+# Nothing in the JS suite can tell you this. jest-expo renders components in
+# Node against mocked native modules, so a missing native dependency, a bad
+# plugin or an SDK mismatch all pass every test and then fail here.
+#
+# app-root lives on the root view in App.tsx. Asserting anything looser —
+# "some element is visible" — also matches the red bundle-error screen, which
+# is exactly the failure this check exists to catch.
+appId: ${app_id}
+---
+- launchApp:
+    clearState: true
+- assertVisible:
+    id: "app-root"
+YAML
+
+  cat > .maestro/core-flow.yaml <<YAML
+# The one flow that proves the app does its job, end to end, on a device.
+#
+# Fill this in for this app — it is deliberately not generated, because a
+# flow that asserts nothing passes forever and teaches you to trust it.
+#
+# The shape that earns its keep:
+#   1. sign in
+#   2. perform the app's core action once
+#   3. assert the screen reflects it
+#   4. kill and relaunch, assert it is still there
+#
+# Step 4 is the point. It catches storage and migration bugs that no other
+# layer sees.
+appId: ${app_id}
+---
+- launchApp:
+    clearState: true
+# - tapOn: "Sign in"
+# - inputText: "..."
+# - tapOn: "..."
+# - assertVisible: "..."
+# - stopApp
+# - launchApp            # no clearState — the data must survive
+# - assertVisible: "..."
+YAML
+
+  pkg_set scripts.test:e2e="maestro test .maestro"
+
+  if command -v maestro >/dev/null 2>&1; then
+    log "maestro flows in .maestro/ (appId ${app_id})"
+  else
+    log "maestro flows in .maestro/ (appId ${app_id})"
+    warn "the maestro CLI is not installed — 'yarn test:e2e' needs it:"
+    warn "  curl -fsSL https://get.maestro.mobile.dev | bash"
+  fi
+}
+
+# Accessibility as an assertion, not a review note.
+#
+# Querying by role already fails a test when a control has no accessible
+# name. axe covers what a role query cannot see — contrast, duplicate
+# landmarks, orphaned labels, invalid ARIA — and it is mechanical, so a
+# machine should catch it on every run rather than a human at review time.
+#
+# axe-core directly rather than a wrapper: vitest-axe is 0.x and has not
+# published in over a year, and component tests already run in real Chromium,
+# which is the environment axe is built for. No adapter needed.
+setup_axe() {
+  add_latest --dev axe-core
+  mkdir -p src/test
+
+  cat > src/test/a11y.ts <<'TS'
+import axe, { type Result } from "axe-core";
+import { expect } from "vitest";
+
+/**
+ * Fails the test with a readable report if the given subtree has any
+ * accessibility violation.
+ *
+ * Raw axe output is a deep object nobody reads, so violations are flattened
+ * to one line each: the rule, the impact, and the element that broke it.
+ */
+export async function expectNoA11yViolations(
+  element: Element = document.body,
+): Promise<void> {
+  const results = await axe.run(element, {
+    rules: {
+      // Both need a whole document. A mounted component legitimately has
+      // neither, and failing on that trains people to ignore the report.
+      region: { enabled: false },
+      "page-has-heading-one": { enabled: false },
+    },
+  });
+
+  const lines = results.violations.flatMap((v: Result) =>
+    v.nodes.map(
+      (n) => `[${v.impact ?? "unknown"}] ${v.id}: ${v.help}\n    ${n.target.join(" ")}`,
+    ),
+  );
+
+  expect(lines, `accessibility violations:\n  ${lines.join("\n  ")}`).toEqual([]);
+}
+TS
+  log "axe helper at src/test/a11y.ts"
+}
+
+# The same check against the real, built page — where contrast, landmarks and
+# heading order actually exist. A component test cannot see any of those.
+setup_axe_e2e() {
+  # playwright-core explicitly: @axe-core/playwright peers on it, and the
+  # `playwright` package only pulls it in transitively — which leaves the peer
+  # genuinely unmet rather than merely noisy.
+  add_latest --dev @axe-core/playwright playwright-core
+  cat > e2e/a11y.spec.ts <<'SPEC'
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+/**
+ * Accessibility of the whole rendered page.
+ *
+ * Component tests check a mounted subtree. Only here do contrast against the
+ * real background, landmark structure and heading order exist at all — and
+ * those are the failures a screen reader user actually hits.
+ */
+test("the page has no accessibility violations", async ({ page }) => {
+  await page.goto("/");
+
+  const results = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+    .analyze();
+
+  const lines = results.violations.flatMap((v) =>
+    v.nodes.map((n) => `[${v.impact}] ${v.id}: ${v.help} — ${n.target.join(" ")}`),
+  );
+
+  expect(lines, `accessibility violations:\n  ${lines.join("\n  ")}`).toEqual([]);
+});
+SPEC
+  log "e2e/a11y.spec.ts (axe against the built page)"
+}
+
+# The rules, made executable.
+#
+# A rule nothing checks is prose an agent may or may not follow. These are
+# the ones from `.claude/rules/` that can be decided mechanically with high
+# precision — deliberately not the ones that cannot. A check that guesses
+# produces false positives, and a gate people learn to override is worse than
+# no gate.
+write_policy_check_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/policy-check.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/policy-check.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Mechanical enforcement of the rules in .claude/rules/.
+ *
+ * Only checks that can be decided with high precision live here. Authorization
+ * on a route and PII in a log line cannot be — they stay review items in the
+ * rules rather than becoming a check that cries wolf.
+ *
+ * Usage: node scripts/policy-check.mjs [--staged]
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+
+const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+const stagedOnly = process.argv.includes("--staged");
+
+const files = execFileSync(
+  "git",
+  stagedOnly
+    ? ["diff", "--cached", "--name-only", "--diff-filter=ACMR"]
+    : ["ls-files"],
+  { encoding: "utf8", cwd: root, maxBuffer: 64 * 1024 * 1024 },
+)
+  .split("\n")
+  .filter(Boolean)
+  .filter((f) => /\.(ts|tsx|js|jsx|mjs|kt|swift)$/.test(f))
+  .filter((f) => !/(^|\/)(node_modules|dist|build|coverage|\.next|android|ios)\//.test(f));
+
+const findings = [];
+const report = (file, line, rule, message) =>
+  findings.push({ file, line, rule, message });
+
+/**
+ * Whether React's compiler is enabled anywhere in this repo.
+ *
+ * Read, never assumed. React 19 memoizes automatically when it is on, and a
+ * check that demanded `memo` on top of that would be asking for noise — the
+ * same reason a library version is resolved rather than recalled.
+ */
+const reactCompilerOn = (() => {
+  const probes = ["app.json", "app.config.js", "next.config.js", "next.config.ts",
+                  "vite.config.ts", "babel.config.js", "package.json"];
+  for (const rel of probes) {
+    for (const dir of ["", "apps/web/", "apps/mobile/", "apps/api/"]) {
+      try {
+        const body = readFileSync(`${root}/${dir}${rel}`, "utf8");
+        if (/reactCompiler|react-compiler/.test(body)) return true;
+      } catch {
+        // Absent is the common case and says nothing — not every probe
+        // exists in every repo shape.
+      }
+    }
+  }
+  return false;
+})();
+
+/** Line number of an index into the source. */
+const lineAt = (src, index) => src.slice(0, index).split("\n").length;
+
+/**
+ * The same source with every comment, quoted string, regex literal and
+ * template-literal text blanked to spaces. Offsets and line numbers survive,
+ * so a finding still points at the right line.
+ *
+ * Without this the checks fire on their own subject matter. A test that
+ * guards the test-id rule is written by putting `getByTestId` inside a
+ * regex, and the rule then reports the guard as the violation it exists to
+ * prevent — which is how a gate teaches people to disable it.
+ *
+ * Interpolation holes stay as code: `${` is what the interpolated-sql check
+ * looks for, and the expression inside one can hold a real violation.
+ */
+function codeOnly(src) {
+  const out = src.split("");
+  const blank = (from, to) => {
+    for (let i = from; i < to && i < out.length; i++) if (out[i] !== "\n") out[i] = " ";
+  };
+  // What may precede a regex literal. After anything else a slash is division.
+  const regexMayFollow =
+    /[([{,;:=!&|?+\-*%~^<>]$|\b(return|typeof|case|in|of|new|delete|void|do|else|yield|await)$/;
+
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+
+    if (c === "/" && src[i + 1] === "/") {
+      let j = src.indexOf("\n", i);
+      if (j === -1) j = src.length;
+      blank(i, j);
+      i = j;
+      continue;
+    }
+
+    if (c === "/" && src[i + 1] === "*") {
+      let j = src.indexOf("*/", i + 2);
+      j = j === -1 ? src.length : j + 2;
+      blank(i, j);
+      i = j;
+      continue;
+    }
+
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      while (j < src.length) {
+        if (src[j] === "\\") { j += 2; continue; }
+        if (src[j] === c || src[j] === "\n") { j++; break; }
+        j++;
+      }
+      blank(i + 1, j - 1);
+      i = j;
+      continue;
+    }
+
+    if (c === "`") {
+      let j = i + 1;
+      let textStart = j;
+      while (j < src.length) {
+        if (src[j] === "\\") { j += 2; continue; }
+        if (src[j] === "$" && src[j + 1] === "{") {
+          blank(textStart, j);
+          let depth = 1;
+          j += 2;
+          while (j < src.length && depth > 0) {
+            if (src[j] === "{") depth++;
+            else if (src[j] === "}") depth--;
+            j++;
+          }
+          textStart = j;
+          continue;
+        }
+        if (src[j] === "`") break;
+        j++;
+      }
+      blank(textStart, j);
+      i = j + 1;
+      continue;
+    }
+
+    if (c === "/" && regexMayFollow.test(src.slice(0, i).replace(/\s+$/, ""))) {
+      let j = i + 1;
+      let inClass = false;
+      while (j < src.length) {
+        const d = src[j];
+        if (d === "\\") { j += 2; continue; }
+        if (d === "\n") break;
+        if (d === "[") inClass = true;
+        else if (d === "]") inClass = false;
+        else if (d === "/" && !inClass) { j++; break; }
+        j++;
+      }
+      blank(i + 1, j - 1);
+      i = j;
+      continue;
+    }
+
+    i++;
+  }
+  return out.join("");
+}
+
+for (const file of files) {
+  let src;
+  try {
+    src = readFileSync(`${root}/${file}`, "utf8");
+  } catch {
+    // Optional by design: a listed file may be gone or unreadable, and that
+    // is not this script's business to report.
+    continue;
+  }
+  const isTest = /\.(test|spec)\.|(^|\/)(__tests__|e2e)\//.test(file);
+  // Scoped to the kit, and to files that actually render. The same two
+  // patterns in a screen are a judgement call; in a component used inside a
+  // list they are a defect. See performance.orchestra.md.
+  const isKitComponent =
+    /(^|\/)src\/components\//.test(file) && /\.(tsx|jsx)$/.test(file) && !isTest;
+  const code = codeOnly(src);
+
+  // ── Comments ────────────────────────────────────────────────────────
+  // comments.orchestra.md. Both are read from the real source, because
+  // `code` has every comment blanked. One report per run of commented-out
+  // lines — a fifty-line dead block is one finding, not fifty.
+  //
+  // "Parses as a statement" is a handful of shapes, not a parser: a
+  // declaration, an import, a call or assignment ending in `;`, a control
+  // keyword opening a block, a bare closing brace. English does not end a
+  // line in `;` and does not open one with `const x =`, so the false
+  // positives are rare enough to leave the escape hatch out.
+  const commentedCode = [
+    /^(const|let|var|val)\s+[\w$]+\s*[=:]/,
+    /^import\s+(["'{*]|[\w$]+\s*(,|from\b))/,
+    /^export\s+(const|let|var|function|class|default|async|interface|type)\b/,
+    /^(if|for|while|switch)\s*\(.*\)\s*\{?\s*$/,
+    /^\}\s*(else\b.*|catch\b.*|finally\b.*)?\{?\s*$/,
+    /^(return|await|throw)\b.*;\s*$/,
+    /^[\w$.]+\s*(\(.*\)|=[^=].*);\s*$/,
+  ];
+  // Spelled with escapes so this file does not report itself: the check
+  // reads comments from the real source, and this is a comment.
+  const marker = "TO\u0044O|FIX\u004DE|HA\u0043K|X\u0058X";
+  const markerRe = new RegExp(`\\b(${marker})\\b(.*)$`);
+  const directive = new RegExp(`^(eslint|biome-ignore|prettier-ignore|@ts-|MARK:|noinspection|swiftlint|ktlint|${marker})`);
+  let inRun = false;
+  src.split("\n").forEach((line, i) => {
+    const m = line.match(/^\s*\/\/\s?(.*)$/);
+    const text = m ? m[1].trim() : "";
+    const dead =
+      !!m && !directive.test(text) && !/:\/\//.test(text) &&
+      commentedCode.some((re) => re.test(text));
+    if (dead && !inRun) {
+      report(file, i + 1, "commented-out-code",
+        "delete it — the history is in git, and a reader cannot tell a draft from a deletion");
+    }
+    inRun = dead;
+
+    // A to-do marker is a tech_debt task that skipped the tracker. It passes
+    // with the task beside it — `(#123)`, `(CU-86abc)` — or a link.
+    const todo = line.match(markerRe);
+    if (todo && !/^\s*\([^)]+\)|#\d+|:\/\//.test(todo[2])) {
+      report(file, i + 1, "todo-without-task",
+        "open the tech_debt task and put its id here, or do the work");
+    }
+  });
+
+  // ── Swallowed errors ────────────────────────────────────────────────
+  // observability.orchestra.md: every catch either handles the error
+  // meaningfully or reports it and rethrows. The one exception is a
+  // genuinely optional path, and it carries a comment saying why.
+  //
+  // Brace-matched rather than regex-matched. `catch {}` on one line has no
+  // newline to anchor a pattern on, so a regex demanding one either misses
+  // the plainest swallowed error there is, or runs on to the next closing
+  // brace and reports somebody else's code at the wrong line.
+  for (const m of code.matchAll(/\bcatch\s*(?:\([^)]*\))?\s*\{/g)) {
+    const open = m.index + m[0].length - 1;
+    let depth = 1;
+    let end = open + 1;
+    while (end < code.length && depth > 0) {
+      if (code[end] === "{") depth++;
+      else if (code[end] === "}") depth--;
+      end++;
+    }
+    const body = code.slice(open + 1, end - 1);
+    // The escape hatch is a comment saying why failure is acceptable, and
+    // comments are blanked in `code` — so read it from the real source.
+    if (/\/\/|\/\*/.test(src.slice(open + 1, end - 1))) continue;
+    // `exitCode` is here for the same reason `res.` is: in a CLI, a failure
+    // exit code is how the failure leaves the process. A catch that tells the
+    // user what happened and then exits non-zero has handled it.
+    const meaningful =
+      /\bthrow\b|\breject\b|captureException|Sentry|logger\.|report|res\.|exitCode|return\s+\S/.test(body);
+    const onlyLogs = /^\s*console\.\w+\([^)]*\);?\s*$/.test(body);
+    // In a test the failure is the subject: catching it and recording that
+    // it happened is handling it, and the assertion that follows is the report.
+    const handled = meaningful || (isTest && /\w\s*=[^=]/.test(body));
+    if (body.trim() === "" || onlyLogs || !handled) {
+      report(file, lineAt(code, m.index), "swallowed-error",
+        body.trim() === "" ? "empty catch block" : "catch neither handles nor reports");
+    }
+  }
+
+  // ── Test-id queries ─────────────────────────────────────────────────
+  // The suite should enforce accessibility, not route around it.
+  if (isTest) {
+    for (const m of code.matchAll(/\bgetByTestId|\bfindByTestId|\bqueryByTestId|onNodeWithTag/g)) {
+      report(file, lineAt(code, m.index), "query-by-testid",
+        "query by role or accessible name instead");
+    }
+  }
+
+  // ── A mocked database ───────────────────────────────────────────────
+  // testing-standards.orchestra.md: mock it and you test your own mock.
+  if (isTest) {
+    for (const m of code.matchAll(/(?:vi|jest)\.mock\(\s*["'`]([^"'`]+)["'`]/g)) {
+      if (/\b(db|database|prisma|drizzle|knex|pg|postgres|mongoose|sequelize|repository|repo)\b/i.test(m[1])) {
+        report(file, lineAt(code, m.index), "mocked-database",
+          `mocks ${m[1]} — use a real database in a container`);
+      }
+    }
+  }
+
+  // ── Interpolated SQL ────────────────────────────────────────────────
+  // security.orchestra.md: parameterised queries only.
+  for (const m of code.matchAll(/\.(query|execute|raw|unsafe)\s*\(\s*`[^`]*\$\{/g)) {
+    report(file, lineAt(code, m.index), "interpolated-sql",
+      "string-built SQL — use parameters");
+  }
+
+  // ── A round trip per iteration ──────────────────────────────────────
+  // performance.orchestra.md. The same defect whether the loop calls a
+  // database, an HTTP API or the filesystem; naming it N+1 is a database
+  // habit. Reads as ordinary code and costs a full round trip per row.
+  //
+  // `for await` is excluded — consuming an async iterable is the correct
+  // way to stream, not a mistake. Tests are excluded because a suite
+  // awaiting in sequence is usually setup, not a hot path.
+  if (!isTest) {
+    for (const m of code.matchAll(/\b(for|while)\s*(?:await\s*)?\(/g)) {
+      if (/for\s*await/.test(m[0])) continue;
+      // Past the header's own parentheses, then over the balanced body.
+      let i = m.index + m[0].length;
+      let depth = 1;
+      while (i < code.length && depth > 0) {
+        if (code[i] === "(") depth++;
+        else if (code[i] === ")") depth--;
+        i++;
+      }
+      const open = code.indexOf("{", i);
+      if (open === -1 || open > i + 40) continue;
+      depth = 1;
+      let end = open + 1;
+      while (end < code.length && depth > 0) {
+        if (code[end] === "{") depth++;
+        else if (code[end] === "}") depth--;
+        end++;
+      }
+      const body = code.slice(open + 1, end - 1);
+      if (!/\bawait\b/.test(body)) continue;
+      // Sequential is genuinely right sometimes — an ordered write, a rate
+      // limit, a cursor that depends on the previous page. A comment above
+      // the loop saying which clears it; comments are blanked in `code`, so
+      // it is read from the real source.
+      const before = src.slice(Math.max(0, m.index - 200), m.index);
+      if (/\/\/|\/\*/.test(before)) continue;
+      report(file, lineAt(code, m.index), "await-in-loop",
+        "a round trip per iteration — batch it, or say above the loop why sequential is required");
+    }
+  }
+
+  // ── An effect that starts a lifetime and never ends it ──────────────
+  // performance.orchestra.md: whoever starts a lifetime ends it, in the same
+  // place. A React effect is that place, and a listener, a timer or a
+  // subscription started inside one with no cleanup returned outlives the
+  // component — the one leak shape a script can see. Brace-matched like the
+  // catch check, for the same reason. A comment inside the effect saying
+  // why no cleanup is needed clears it; comments are blanked in `code`, so
+  // it is read from the real source.
+  if (/\.(tsx|jsx|ts|js)$/.test(file) && !isTest) {
+    for (const m of code.matchAll(/\buse(?:Layout)?Effect\s*\(\s*(?:async\s*)?(?:\([^)]*\)|[\w$]+)\s*=>\s*\{/g)) {
+      const open = m.index + m[0].length - 1;
+      let depth = 1;
+      let end = open + 1;
+      while (end < code.length && depth > 0) {
+        if (code[end] === "{") depth++;
+        else if (code[end] === "}") depth--;
+        end++;
+      }
+      const body = code.slice(open + 1, end - 1);
+      const starts =
+        /\b(?:addEventListener|setInterval|setTimeout|subscribe|addListener|on)\s*\(|\bnew\s+(?:WebSocket|EventSource|IntersectionObserver|ResizeObserver|MutationObserver)\b/.test(
+          body,
+        );
+      if (!starts) continue;
+      if (/^\s*return\b|[;{}]\s*return\b/m.test(body)) continue;
+      if (/\/\/|\/\*/.test(src.slice(open + 1, end - 1))) continue;
+      report(file, lineAt(code, m.index), "effect-without-cleanup",
+        "the effect starts a listener, timer or subscription and returns no cleanup — return the function that stops it, or say inside the effect why none is needed");
+    }
+  }
+
+  // ── An array index as a key ─────────────────────────────────────────
+  // performance.orchestra.md. A correctness bug before a performance one:
+  // reorder or delete and React reuses the wrong element with the wrong
+  // state. `key={item.id}` is the fix, never a counter.
+  for (const m of code.matchAll(/\bkey=\{\s*(i|idx|index)\s*\}/g)) {
+    report(file, lineAt(code, m.index), "array-index-key",
+      `key={${m[1]}} — key on the item's identity, not its position`);
+  }
+
+  // ── Kit components ──────────────────────────────────────────────────
+  // A component in src/components/ renders inside lists and under parents
+  // that re-render often, so these are decided once here rather than per
+  // phase. Scoped to the kit on purpose: the same two patterns in a screen
+  // are a judgement call, and a check that cries wolf gets switched off.
+  if (isKitComponent) {
+    for (const m of code.matchAll(/\bstyle=\{\{/g)) {
+      report(file, lineAt(code, m.index), "inline-style-object",
+        "new style object every render — StyleSheet.create, or memoize on the inputs");
+    }
+
+    // Only when the compiler is off. React 19's compiler memoizes for you,
+    // and asking for `memo` on top of it is asking for redundant noise —
+    // read from the project rather than assumed, the same as a version.
+    if (!reactCompilerOn) {
+      for (const m of code.matchAll(
+        /export\s+(?:default\s+)?(?:function\s+([A-Z]\w*)|const\s+([A-Z]\w*)\s*[:=])/g,
+      )) {
+        const name = m[1] || m[2];
+        const memoized = new RegExp(
+          `memo\\(\\s*(?:function\\s+)?${name}\\b|(?:const|let)\\s+${name}\\s*=\\s*(?:React\\.)?memo\\(`,
+        ).test(code);
+        // The escape hatch is a comment saying why, read from the real
+        // source because comments are blanked in `code`.
+        const explained = /\/\/|\/\*/.test(src.slice(Math.max(0, m.index - 200), m.index));
+        if (!memoized && !explained) {
+          report(file, lineAt(code, m.index), "unmemoized-kit-component",
+            `${name} is not memoized and the React compiler is off`);
+        }
+      }
+    }
+  }
+}
+
+if (!findings.length) {
+  console.log(`  policy: ${files.length} file(s) clean`);
+  process.exit(0);
+}
+
+const byRule = new Map();
+for (const f of findings) {
+  if (!byRule.has(f.rule)) byRule.set(f.rule, []);
+  byRule.get(f.rule).push(f);
+}
+
+console.error(`\n  [x] ${findings.length} policy violation(s)\n`);
+for (const [rule, items] of byRule) {
+  console.error(`  ${rule}`);
+  for (const i of items) console.error(`    ${i.file}:${i.line} — ${i.message}`);
+  console.error("");
+}
+console.error("  These are rules in .claude/rules/, not style preferences.");
+console.error("  Fix the code. Do not add an ignore.\n");
+process.exit(1);
+JS
+  chmod +x "$root/scripts/policy-check.mjs"
+  log "wrote scripts/policy-check.mjs"
+}
+
+# The component kit, and the line that decides where a component comes from.
+#
+# Two worked examples, because the rule is a boundary and one side of it
+# teaches nothing:
+#
+#   Button — a native <button>. The browser already supplies the role, the
+#            keyboard behaviour, the disabled semantics and form
+#            participation. A library here buys a dependency and nothing else.
+#
+#   Select — react-aria-components. There is no HTML element for a listbox
+#            that renders custom content, so a hand-rolled one has to
+#            re-implement roving tabindex, typeahead, dismissal, focus
+#            return and aria-activedescendant. axe runs as an assertion in
+#            this stack, so that work fails the gate repeatedly instead of
+#            once, at the library choice.
+setup_ui_primitives() {
+  # $1 = "client" on a framework with server components. Both files below
+  # carry an event handler or context, so on the Next App Router they are
+  # client components — without the directive the build fails rather than
+  # degrading, which at least fails loudly.
+  local client="${1:-}"
+  add_latest react-aria-components
+  mkdir -p src/components/Button src/components/Select
+
+  # --- Button: the native side of the line -----------------------------
+  cat > src/components/Button/Button.tsx <<'TSX'
+import type { ButtonHTMLAttributes, Ref } from "react";
+import type { Size } from "../../design";
+
+/**
+ * A button.
+ *
+ * Deliberately a native `<button>` with no library behind it. The element
+ * already carries the role, keyboard activation, `disabled` semantics and
+ * form submission — everything a primitive would re-supply.
+ */
+export type ButtonVariant = "primary" | "secondary";
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Union, not booleans — two intents cannot be requested at once. */
+  variant?: ButtonVariant;
+  size?: Size;
+  ref?: Ref<HTMLButtonElement>;
+}
+
+const VARIANT: Record<ButtonVariant, string> = {
+  primary: "bg-[var(--color-brand-900)] text-[var(--color-brand-50)]",
+  secondary: "border border-current bg-transparent text-[var(--on-surface)]",
+};
+
+const SIZE: Record<Size, string> = {
+  sm: "px-3 py-1 text-sm",
+  md: "px-4 py-2 text-base",
+  lg: "px-5 py-2.5 text-lg",
+};
+
+export function Button({
+  variant = "primary",
+  size = "md",
+  className = "",
+  type = "button",
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      // Not `type="submit"`. The HTML default submits the enclosing form,
+      // which is the wrong behaviour for every button that is not the
+      // submit button, and it is invisible until a form appears around one.
+      type={type}
+      className={[
+        "inline-flex items-center justify-center rounded-[var(--radius-control)] font-medium",
+        "transition-colors duration-[var(--duration-fast)]",
+        // Never `outline-none` without a replacement — the focus ring is
+        // the only thing a keyboard user has to locate themselves.
+        "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-brand-900)]",
+        "disabled:opacity-60",
+        VARIANT[variant],
+        SIZE[size],
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      {...props}
+    />
+  );
+}
+TSX
+
+  cat > src/components/Button/index.ts <<'TS'
+export { Button } from "./Button";
+export type { ButtonProps, ButtonVariant } from "./Button";
+TS
+
+  cat > src/components/Button/Button.fixture.tsx <<'TSX'
+import { Button } from "./Button";
+
+// react-cosmos fixture. The workbench catalogue, and the deterministic
+// render target a design comparison is taken against.
+export default {
+  primary: <Button>Save</Button>,
+  secondary: <Button variant="secondary">Cancel</Button>,
+  disabled: <Button disabled>Save</Button>,
+};
+TSX
+
+  cat > src/components/Button/Button.test.tsx <<'TSX'
+import { page, userEvent } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { describe, expect, test, vi } from "vitest";
+import { expectNoA11yViolations } from "../../test/a11y";
+import { Button } from "./Button";
+
+describe("Button", () => {
+  test("is reachable by its accessible name and fires on click", async () => {
+    const onClick = vi.fn();
+    await render(<Button onClick={onClick}>Save</Button>);
+
+    // By role, never by test id: a <div onClick> would fail this line,
+    // which is how the suite ends up enforcing accessibility rather than
+    // review noticing it.
+    await page.getByRole("button", { name: "Save" }).click();
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  test("activates from the keyboard", async () => {
+    const onClick = vi.fn();
+    await render(<Button onClick={onClick}>Save</Button>);
+
+    await userEvent.tab();
+    await userEvent.keyboard("{Enter}");
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  test("disabled means disabled, not merely dimmed", async () => {
+    const onClick = vi.fn();
+    await render(
+      <Button disabled onClick={onClick}>
+        Save
+      </Button>,
+    );
+
+    await expect
+      .element(page.getByRole("button", { name: "Save" }))
+      .toBeDisabled();
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  test("has no accessibility violations", async () => {
+    await render(<Button>Save</Button>);
+    await expectNoA11yViolations();
+  });
+});
+TSX
+
+  # --- Select: the side of the line that needs a primitive -------------
+  cat > src/components/Select/Select.tsx <<'TSX'
+import {
+  Select as AriaSelect,
+  Button,
+  Label,
+  ListBox,
+  ListBoxItem,
+  Popover,
+  SelectValue,
+} from "react-aria-components";
+// Not React's `Key` — React 19 widened it to include bigint and the
+// collection API did not, so importing from "react" fails to compile here.
+import type { Key } from "react-aria-components";
+
+/**
+ * A select.
+ *
+ * Built on react-aria-components rather than by hand. `<select>` cannot
+ * render custom option content, and the ARIA listbox pattern it would be
+ * replaced with is a long list of behaviours — roving focus, typeahead,
+ * Escape and outside-click dismissal, focus return to the trigger,
+ * `aria-activedescendant`, screen-reader announcement of the selection.
+ *
+ * The primitive supplies the behaviour and no styling; every class below is
+ * ours, referencing design tokens.
+ */
+export interface SelectOption {
+  id: Key;
+  label: string;
+}
+
+export interface SelectProps {
+  label: string;
+  options: readonly SelectOption[];
+  selectedKey?: Key | null;
+  defaultSelectedKey?: Key;
+  onSelectionChange?: (key: Key | null) => void;
+  placeholder?: string;
+  isDisabled?: boolean;
+}
+
+export function Select({ label, options, ...props }: SelectProps) {
+  return (
+    <AriaSelect className="flex flex-col gap-1" {...props}>
+      <Label className="text-sm font-medium">{label}</Label>
+      <Button
+        className={[
+          "flex items-center justify-between gap-2",
+          "rounded-[var(--radius-control)] border border-current px-3 py-2 text-left",
+          "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-brand-900)]",
+        ].join(" ")}
+      >
+        <SelectValue />
+        {/* Decorative, and an SVG rather than a text glyph on purpose: a
+            character here lands in the button's textContent, so every
+            assertion about the selected value would have to know about the
+            arrow. The accessible name still comes from the label. */}
+        <svg aria-hidden="true" focusable="false" width="10" height="6" viewBox="0 0 10 6">
+          <path d="M1 1l4 4 4-4" fill="none" stroke="currentColor" strokeWidth="1.5" />
+        </svg>
+      </Button>
+      <Popover className="min-w-[var(--trigger-width)] rounded-[var(--radius-control)] border border-current bg-[var(--surface)] text-[var(--on-surface)]">
+        <ListBox className="max-h-60 overflow-auto p-1 outline-none">
+          {options.map((option) => (
+            <ListBoxItem
+              key={String(option.id)}
+              id={option.id}
+              textValue={option.label}
+              className="cursor-default rounded-[var(--radius-control)] px-3 py-2 outline-none data-[focused]:bg-[var(--color-brand-900)] data-[focused]:text-[var(--color-brand-50)]"
+            >
+              {option.label}
+            </ListBoxItem>
+          ))}
+        </ListBox>
+      </Popover>
+    </AriaSelect>
+  );
+}
+TSX
+
+  cat > src/components/Select/index.ts <<'TS'
+export { Select } from "./Select";
+export type { SelectOption, SelectProps } from "./Select";
+TS
+
+  cat > src/components/Select/Select.fixture.tsx <<'TSX'
+import { Select } from "./Select";
+
+const OPTIONS = [
+  { id: "apple", label: "Apple" },
+  { id: "pear", label: "Pear" },
+  { id: "quince", label: "Quince" },
+];
+
+export default {
+  empty: <Select label="Fruit" options={OPTIONS} placeholder="Pick one" />,
+  selected: <Select label="Fruit" options={OPTIONS} defaultSelectedKey="pear" />,
+};
+TSX
+
+  cat > src/components/Select/Select.test.tsx <<'TSX'
+import { page, userEvent } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { describe, expect, test, vi } from "vitest";
+import { expectNoA11yViolations } from "../../test/a11y";
+import { Select } from "./Select";
+
+const OPTIONS = [
+  { id: "apple", label: "Apple" },
+  { id: "pear", label: "Pear" },
+  { id: "quince", label: "Quince" },
+];
+
+describe("Select", () => {
+  test("opens from the keyboard and exposes options by role", async () => {
+    await render(<Select label="Fruit" options={OPTIONS} />);
+
+    await userEvent.tab();
+    await userEvent.keyboard("{Enter}");
+
+    await expect.element(page.getByRole("listbox")).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("option", { name: "Pear" }))
+      .toBeInTheDocument();
+  });
+
+  test("selecting an option reports the key and updates the trigger", async () => {
+    const onSelectionChange = vi.fn();
+    await render(
+      <Select
+        label="Fruit"
+        options={OPTIONS}
+        onSelectionChange={onSelectionChange}
+      />,
+    );
+
+    await page.getByRole("button", { name: /fruit/i }).click();
+    await page.getByRole("option", { name: "Pear" }).click();
+
+    expect(onSelectionChange).toHaveBeenCalledWith("pear");
+    // vitest browser mode matches the element's FULL text, unlike jest-dom
+    // where a string is a substring match. That holds here only because the
+    // chevron is an SVG and contributes no text content.
+    await expect
+      .element(page.getByRole("button", { name: /fruit/i }))
+      .toHaveTextContent("Pear");
+  });
+
+  // The behaviour a hand-rolled listbox gets wrong, and the reason this
+  // component has a dependency behind it: dismissing has to put focus back
+  // where it came from, or a keyboard user is returned to the top of the
+  // document.
+  test("Escape closes the listbox and returns focus to the trigger", async () => {
+    await render(<Select label="Fruit" options={OPTIONS} />);
+    const trigger = page.getByRole("button", { name: /fruit/i });
+
+    await trigger.click();
+    await expect.element(page.getByRole("listbox")).toBeInTheDocument();
+
+    await userEvent.keyboard("{Escape}");
+
+    expect(page.getByRole("listbox").elements()).toHaveLength(0);
+    await expect.element(trigger).toHaveFocus();
+  });
+
+  test("has no accessibility violations, closed or open", async () => {
+    await render(<Select label="Fruit" options={OPTIONS} />);
+    await expectNoA11yViolations();
+
+    await page.getByRole("button", { name: /fruit/i }).click();
+    await expect.element(page.getByRole("listbox")).toBeInTheDocument();
+    await expectNoA11yViolations();
+  });
+});
+TSX
+
+  # Select only, and deliberately. Verified on a real Next build:
+  #
+  #   Select without the directive  -> build fails, "createContext is not a
+  #                                    function". The primitive uses hooks and
+  #                                    context, so it cannot be a Server
+  #                                    Component.
+  #   Button without the directive  -> builds. It is a native element with no
+  #                                    hooks, so it renders on the server and
+  #                                    ships no JavaScript. Marking it anyway
+  #                                    would push it into the client bundle to
+  #                                    buy nothing.
+  #
+  # A consumer passing onClick has to be a client component either way — that
+  # boundary is the caller's, not this file's.
+  if [ "$client" = "client" ]; then
+    printf '"use client";\n\n%s\n' "$(cat src/components/Select/Select.tsx)" \
+      > src/components/Select/Select.tsx
+    log "Select marked \"use client\" (Button stays a server component)"
+  fi
+
+  cat > src/components/README.md <<'MD'
+# Components
+
+Where a component comes from is decided by one question:
+
+> Does the browser already give me the role, the keyboard behaviour and the
+> focus management?
+
+**Yes — write it.** `button`, `input`, `select`, `textarea`, `a`, `table`,
+`details`, `dialog` with `showModal()`, the Popover API. No library. See
+`Button/`.
+
+**No — use the primitive.** Combobox, listbox with custom content, menu with
+typeahead, tabs, date picker, slider. These have no HTML element, so writing
+one means re-implementing the WAI-ARIA authoring practice for it. See
+`Select/`.
+
+`react-aria-components` ships behaviour and no styling. Every class in these
+files is ours and every colour is a token. Nothing here is a theme.
+
+A primitive is **not** an `src/integrations/` seam: it is not an SDK call or
+an HTTP API, so the third question in
+`.claude/skills/project-structure/SKILL.md` applies and it lives with the
+component that uses it. Its coverage comes from the interaction test above,
+which drives the real thing — a stronger check than a line-count gate.
+MD
+}
+
+# A bundle size budget, as a ratchet rather than a number somebody picked.
+#
+# Same shape as the coverage ratchet: the committed baseline is whatever the
+# build actually produced, and it may go down but never up. That removes the
+# argument about what the right number is, and still fails the day a stray
+# import pulls in a date library.
+setup_bundle_budget() {
+  local root rel
+  root="$(git rev-parse --show-toplevel)"
+  write_bundle_budget_script
+  rel="$(node -e 'const p=require("path");process.stdout.write(p.relative(process.cwd(), process.argv[1]))' "$root/scripts/bundle-budget.mjs")"
+  pkg_set scripts.build:budget="node ${rel}"
+  log "bundle budget (ratchet)"
+}
+
+write_bundle_budget_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/bundle-budget.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/bundle-budget.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Bundle size, ratcheted.
+ *
+ * Not a number somebody picked: the committed baseline is whatever the build
+ * actually produced. It may fall, and it may not rise. Nobody has to defend
+ * "why 180kB", and the day a stray import pulls in a date library the build
+ * still fails.
+ *
+ * Measured gzipped, because that is what a browser downloads. zlib is in the
+ * standard library — this needs no dependency.
+ *
+ * Run from the app directory, after the build.
+ */
+import { gzipSync } from "node:zlib";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const app = process.cwd();
+const OUT_DIRS = ["dist", "build", ".next/static", "out"];
+const outDir = OUT_DIRS.map((d) => join(app, d)).find((d) => existsSync(d));
+
+if (!outDir) {
+  console.log("  bundle budget: no build output found — run the build first");
+  process.exit(0);
+}
+
+/** Every javascript and css asset the browser would actually fetch. */
+function assets(dir) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...assets(full));
+    else if (/\.(js|mjs|css)$/.test(entry.name) && !/\.map$/.test(entry.name)) found.push(full);
+  }
+  return found;
+}
+
+const files = assets(outDir);
+if (!files.length) {
+  console.log("  bundle budget: build output has no js or css");
+  process.exit(0);
+}
+
+const total = files.reduce((sum, f) => sum + gzipSync(readFileSync(f)).length, 0);
+const kb = (n) => `${(n / 1024).toFixed(1)}kB`;
+
+const baselinePath = join(app, ".bundle-budget.json");
+const baseline = existsSync(baselinePath)
+  ? JSON.parse(readFileSync(baselinePath, "utf8"))
+  : null;
+
+// A few kB of noise between builds is normal — hashed filenames, a changed
+// build id. Failing on that would train people to re-record the baseline.
+const TOLERANCE = 1024 * 2;
+
+if (!baseline) {
+  writeFileSync(baselinePath, `${JSON.stringify({ gzipBytes: total }, null, 2)}\n`);
+  console.log(`  bundle budget: baseline recorded at ${kb(total)} gzipped (${files.length} files)`);
+  process.exit(0);
+}
+
+const before = baseline.gzipBytes;
+const delta = total - before;
+
+if (delta > TOLERANCE) {
+  console.error(
+    `\n  [x] bundle grew ${kb(delta)} — ${kb(before)} to ${kb(total)} gzipped\n\n` +
+      "  If the growth is deliberate, say so and re-record:\n" +
+      "    rm .bundle-budget.json && yarn build && yarn build:budget\n" +
+      "  If it is not, something was imported that should not have been.\n",
+  );
+  process.exit(1);
+}
+
+if (delta < 0) {
+  writeFileSync(baselinePath, `${JSON.stringify({ gzipBytes: total }, null, 2)}\n`);
+  console.log(`  bundle budget: ${kb(before)} -> ${kb(total)} gzipped, baseline lowered`);
+} else {
+  console.log(`  bundle budget: ${kb(total)} gzipped (baseline ${kb(before)})`);
+}
+JS
+  chmod +x "$root/scripts/bundle-budget.mjs"
+  log "wrote scripts/bundle-budget.mjs"
+}
+
+# The check that runs against the deployed thing, not against localhost.
+#
+# Railway's healthcheck already gates promotion on /ready. This is the layer
+# after it: a readiness probe can answer 200 while a route 500s, an asset
+# 404s, or a migration half-applied. It is also what decides whether the
+# release is rolled back.
+write_smoke_script() {
+  local root; root="$(git rev-parse --show-toplevel)"
+  [ -f "$root/scripts/smoke.mjs" ] && return 0
+  mkdir -p "$root/scripts"
+  cat > "$root/scripts/smoke.mjs" <<'JS'
+#!/usr/bin/env node
+/**
+ * Post-deploy smoke test against a real URL.
+ *
+ * Deliberately tiny and dependency-free: it runs on a runner right after a
+ * deploy, and anything it needs to install is another thing that can fail
+ * while production is already live.
+ *
+ * Usage: node scripts/smoke.mjs https://api.example.com
+ */
+const base = (process.argv[2] || process.env.DEPLOY_URL || "").replace(/\/$/, "");
+if (!base) {
+  console.error("  [x] no URL given — pass one or set DEPLOY_URL");
+  process.exit(1);
+}
+
+/**
+ * A deploy is not instant even after the healthcheck passes: DNS and the
+ * edge take a moment. Retry with a bounded backoff rather than failing on
+ * the first refused connection and rolling back a release that was fine.
+ */
+async function fetchWithRetry(url, { attempts = 6, waitMs = 5000 } = {}) {
+  let lastError;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      const res = await fetch(url, { redirect: "manual" });
+      // A 5xx during rollout is worth one more look; a 4xx is our own bug
+      // and retrying only delays the bad news.
+      if (res.status < 500 || i === attempts) return res;
+      lastError = new Error(`status ${res.status}`);
+    } catch (error) {
+      // Held, not swallowed: each attempt's error loses to the next one and
+      // the last is rethrown after the loop. A refused connection mid-rollout
+      // is the expected case this function exists to retry through.
+      lastError = error;
+    }
+    console.log(`    attempt ${i}/${attempts} not ready yet — waiting ${waitMs / 1000}s`);
+    await new Promise((r) => setTimeout(r, waitMs));
+  }
+  throw lastError;
+}
+
+const checks = [
+  {
+    name: "readiness reports every dependency reachable",
+    async run() {
+      const res = await fetchWithRetry(`${base}/ready`);
+      if (res.status !== 200) throw new Error(`/ready returned ${res.status}`);
+      const body = await res.json();
+      const failed = (body.checks ?? []).filter((c) => !c.ok);
+      if (failed.length) {
+        throw new Error(`dependencies down: ${failed.map((c) => c.name).join(", ")}`);
+      }
+    },
+  },
+  {
+    name: "liveness answers",
+    async run() {
+      const res = await fetchWithRetry(`${base}/health`);
+      if (res.status !== 200) throw new Error(`/health returned ${res.status}`);
+    },
+  },
+];
+
+// Add the flows this product exists for. A smoke suite that only proves the
+// process started is a smoke suite that has never caught anything.
+
+let failed = 0;
+for (const check of checks) {
+  try {
+    await check.run();
+    console.log(`  [+] ${check.name}`);
+  } catch (error) {
+    // Reported and counted, not swallowed: one failing check must not stop the
+    // rest from running, and a non-zero `failed` exits 1 below — which is what
+    // triggers the rollback.
+    failed++;
+    console.error(`  [x] ${check.name}\n      ${error.message}`);
+  }
+}
+
+if (failed) {
+  console.error(`\n  ${failed} smoke check(s) failed against ${base} — rolling back\n`);
+  process.exit(1);
+}
+console.log(`\n  smoke passed against ${base}\n`);
+JS
+  chmod +x "$root/scripts/smoke.mjs"
+  log "wrote scripts/smoke.mjs"
+}
+
+# The last thing a scaffold does: prove it produced clean work.
+#
+# Reports and fails. It deliberately does not fix anything — every
+# deterministic fix already happened during setup, and changing versions
+# *after* the verification gate ran would leave a repo whose gate passed
+# against different versions than the ones committed. A scaffold that quietly
+# adjusts itself at the end is one whose output nobody can reason about.
+#
+# When this fails, the fix belongs in the stack, not in the project.
+assert_scaffold_clean() {
+  local problems=0
+  local audit_checked=1
+
+  # ── Genuinely unmet peer dependencies ───────────────────────────────
+  # Yarn marks optional, unprovided peers with ✓ and real breakage with ✘.
+  # Only the second kind is a problem; treating the first as one would make
+  # this check noise, and noise gets disabled.
+  #
+  # And only the ones we can do something about. "workspace:. doesn't provide
+  # X" is ours — we forgot to install something. "@sentry/node doesn't provide
+  # X to @sentry/node-core" is a vendor's own manifest, unfixable from here,
+  # and failing a scaffold on it produces a gate nobody can satisfy, which is
+  # a gate that gets disabled.
+  local unmet ours theirs
+  unmet="$(yarn explain peer-requirements 2>/dev/null | grep '✘' || true)"
+  ours="$(printf '%s\n' "$unmet" | grep '@workspace:' || true)"
+  theirs="$(printf '%s\n' "$unmet" | grep '✘' | grep -v '@workspace:' || true)"
+
+  if [ -n "$ours" ]; then
+    warn "peer dependencies this app should provide and does not:"
+    printf '%s\n' "$ours" | sed 's/^/      /' >&2
+    problems=$((problems + 1))
+  fi
+  if [ -n "$theirs" ]; then
+    # Reported, never fatal: worth knowing which vendor ships a broken
+    # manifest, not worth blocking on something we cannot fix.
+    warn "unmet peers inside dependencies (vendor manifests, not ours):"
+    printf '%s\n' "$theirs" | sed 's/^/      /' >&2
+  fi
+
+  # ── Known vulnerabilities ───────────────────────────────────────────
+  # CI blocks a critical on every PR. Finding one only after the first push
+  # means the repo was born vulnerable and nobody said so.
+  #
+  # Run once and read the output, because a non-zero exit means two different
+  # things and only one of them is a vulnerability. When the registry does not
+  # answer, this used to print "a critical vulnerability is present in a
+  # freshly scaffolded app" and fail the scaffold — a claim nobody had
+  # observed, about a check that never ran. Saying unverified is the rule
+  # everywhere else here; it applies to bad news too.
+  local audit_out audit_rc=0
+  audit_out="$(yarn npm audit --severity critical 2>&1)" || audit_rc=$?
+
+  if [ "$audit_rc" -ne 0 ]; then
+    if printf '%s' "$audit_out" | grep -qiE 'RequestError|Timeout awaiting|ETIMEDOUT|ENOTFOUND|ECONNRESET|EAI_AGAIN|socket hang up'; then
+      # Not fatal. An unreachable registry is not a vulnerability, and CI runs
+      # the same audit on every pull request — this is the earlier of two
+      # chances, not the only one.
+      warn "could not check for advisories — the registry did not answer:"
+      printf '%s\n' "$audit_out" | head -3 | sed 's/^/      /' >&2
+      audit_checked=0
+    else
+      warn "a critical vulnerability is present in a freshly scaffolded app:"
+      printf '%s\n' "$audit_out" | head -20 | sed 's/^/      /' >&2
+      problems=$((problems + 1))
+    fi
+  fi
+
+  if [ "$problems" -gt 0 ]; then
+    warn ""
+    warn "This scaffold is not clean. Fix it in .orchestra/stacks/, not here —"
+    warn "otherwise the next project meets the same thing."
+    return 1
+  fi
+
+  if [ "$audit_checked" -eq 1 ]; then
+    log "scaffold is clean: peers satisfied, no critical advisories"
+  else
+    log "scaffold is clean: peers satisfied. advisories unchecked — see above"
+  fi
+}