getadvantage 0.1.0 → 0.3.0

package/brief.mjs

@@ -1,634 +1,634 @@
-// Ship-Safe — PROJECT BRAIN (`ship-safe brief`).
-//
-// A portable, repo-resident, provider-agnostic project-context file that ANY
-// model / session / tool can read on start — so you can switch from Claude to
-// Qwen (or just session to session) WITHOUT re-explaining the project. Your
-// brain lives in the REPO, not your tool.
-//
-// `ship-safe brief` generates / updates a markdown file (default
-// PROJECT-BRIEF.md at the repo root; `--out <path>` to relocate) from the REAL
-// repo — everything below is GENERATED by reading the tree, never invented:
-//
-//   • What the app is   — name + description (package.json), detected
-//                          stack/framework/builder, what it does (best-effort
-//                          from README / package description).
-//   • Architecture map  — REUSES the overview scanners (scanApiSurface /
-//                          scanIntegrations / scanSchedules) so the brief and
-//                          the `check` maps never drift: API surface, the
-//                          integrations/agents + their env keys, the schedules.
-//   • How to work here  — CLAUDE.md (if present), package.json scripts
-//                          (dev/build/test), and the detected deploy method.
-//   • Current state     — git branch, last few commits, what's in flight
-//                          (uncommitted + unmerged-branch counts).
-//
-// MAINTENANCE: every generated brief carries a small staleness marker (the HEAD
-// sha + a timestamp) in BOTH the markdown frontmatter and a machine-readable
-// .ship-safe/brief.json. `ship-safe brief --check` (and the hook the main
-// `check` calls) WARNS — never blocks — if the brief is missing or the repo has
-// moved on since it was generated.
-//
-// Node built-ins only. ESM. Generating the brief WRITES two files (the brief +
-// the marker); `--check` reads only.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
-import { createHash } from "node:crypto";
-import path from "node:path";
-import { c, git, gitSafe, relPath } from "./util.mjs";
-import {
-  scanApiSurface,
-  apiRowTag,
-  scanIntegrations,
-  scanSchedules,
-  scheduleRowTag,
-} from "./overviews.mjs";
-
-const DEFAULT_OUT = "PROJECT-BRIEF.md";
-const MARKER_DIR = ".ship-safe";
-const MARKER_FILE = "brief.json";
-// A stable banner so a model/tool can recognise this file by its first lines.
-const BANNER = "<!-- ship-safe:project-brief -->";
-
-// ===========================================================================
-// repo-fact readers (best-effort; never throw on a missing/oddly-shaped file)
-// ===========================================================================
-
-function readJson(abs) {
-  try {
-    return JSON.parse(readFileSync(abs, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function readTextSafe(abs, max = 200_000) {
-  try {
-    const st = statSync(abs);
-    if (!st.isFile() || st.size > max) return "";
-    return readFileSync(abs, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-/** package.json → { name, version, description, scripts, deps, devDeps }. */
-function readPackage(cwd) {
-  const pkg = readJson(path.join(cwd, "package.json")) || {};
-  return {
-    name: typeof pkg.name === "string" ? pkg.name : "(unnamed)",
-    version: typeof pkg.version === "string" ? pkg.version : "",
-    description: typeof pkg.description === "string" ? pkg.description : "",
-    scripts: pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {},
-    deps: pkg.dependencies && typeof pkg.dependencies === "object" ? pkg.dependencies : {},
-    devDeps: pkg.devDependencies && typeof pkg.devDependencies === "object" ? pkg.devDependencies : {},
-  };
-}
-
-/**
- * Detect the stack/framework/builder from the dependency set + config files.
- * Returns an array of short human strings (e.g. "Next.js 16.2.0 (App Router)").
- * Generated from what's actually present — never assumed.
- */
-function detectStack(cwd, pkg) {
-  const all = { ...pkg.deps, ...pkg.devDeps };
-  const out = [];
-  const ver = (name) => (all[name] ? ` ${String(all[name]).replace(/^[\^~]/, "")}` : "");
-
-  // Framework / runtime.
-  if (all.next) {
-    const appRouter = existsSync(path.join(cwd, "app")) ? " (App Router)" : "";
-    out.push(`Next.js${ver("next")}${appRouter}`);
-  } else if (all["react-scripts"]) out.push("Create React App");
-  else if (all.vite) out.push(`Vite${ver("vite")}`);
-  else if (all.astro) out.push(`Astro${ver("astro")}`);
-  else if (all.remix || all["@remix-run/react"]) out.push("Remix");
-  else if (all.express) out.push(`Express${ver("express")}`);
-
-  if (all.react && !out.some((s) => s.startsWith("Next.js") || s.startsWith("Remix"))) {
-    out.push(`React${ver("react")}`);
-  } else if (all.react) {
-    out.push(`React${ver("react")}`);
-  }
-
-  // Language.
-  if (all.typescript || existsSync(path.join(cwd, "tsconfig.json"))) {
-    out.push(`TypeScript${ver("typescript")}`);
-  }
-
-  // Data layer (presence-driven, from this repo's real deps + the generic ones).
-  if (all["@neondatabase/serverless"]) out.push("Neon serverless Postgres (prod)");
-  if (all["@electric-sql/pglite"]) out.push("PGlite in-process Postgres (local fallback)");
-  if (all["@prisma/client"] || all.prisma) out.push("Prisma");
-  if (all["drizzle-orm"]) out.push("Drizzle ORM");
-
-  // Notable libs that shape how the app works.
-  if (all.stripe) out.push("Stripe (billing)");
-  if (all.jose) out.push("jose (JWT sessions)");
-  if (all.bcryptjs || all.bcrypt) out.push("bcrypt (password hashing)");
-  if (all["mcp-handler"] || all["@modelcontextprotocol/sdk"]) out.push("MCP server (mcp-handler)");
-
-  return out;
-}
-
-/** Detect the package manager from the lockfile present. */
-function detectPackageManager(cwd) {
-  if (existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync(path.join(cwd, "package-lock.json"))) return "npm";
-  if (existsSync(path.join(cwd, "bun.lockb"))) return "bun";
-  return "npm";
-}
-
-/**
- * Detect the deploy method. We DON'T invent — we report what's observable:
- *   • a co-located Ship-Safe deploy CLI (this repo) → the safe-deploy ritual
- *   • a .vercel link / vercel.json → Vercel
- *   • a Dockerfile / netlify.toml / .github workflows → note them
- */
-function detectDeploy(cwd) {
-  const notes = [];
-  if (existsSync(path.join(cwd, "cli", "ship-safe", "deploy.mjs"))) {
-    notes.push("Ship-Safe safe-deploy ritual (`ship-safe deploy`) — clean detached worktree + host-prefix confirm.");
-  }
-  if (existsSync(path.join(cwd, ".vercel")) || existsSync(path.join(cwd, "vercel.json"))) {
-    notes.push("Vercel (`vercel --prod` — CLI deploys the WORKING TREE, not a commit).");
-  }
-  if (existsSync(path.join(cwd, "netlify.toml"))) notes.push("Netlify (netlify.toml present).");
-  if (existsSync(path.join(cwd, "Dockerfile"))) notes.push("Docker (Dockerfile present).");
-  if (existsSync(path.join(cwd, ".github", "workflows"))) notes.push("GitHub Actions workflow(s) present (.github/workflows).");
-  if (notes.length === 0) notes.push("No deploy config detected (no .vercel / vercel.json / Dockerfile / CI workflow).");
-  return notes;
-}
-
-/**
- * Best-effort "what it does" sentence(s). Prefer the package description; fall
- * back to the first meaningful prose paragraph of the README (skipping the H1,
- * badges, and blank lines). Never invents — returns "" if nothing usable.
- */
-function whatItDoes(cwd, pkg) {
-  if (pkg.description) return pkg.description.trim();
-  // Try common README filenames.
-  for (const name of ["README.md", "Readme.md", "readme.md"]) {
-    const txt = readTextSafe(path.join(cwd, name));
-    if (!txt) continue;
-    const lines = txt.split("\n");
-    const para = [];
-    for (const raw of lines) {
-      const line = raw.trim();
-      if (!line) {
-        if (para.length) break; // end of the first prose paragraph
-        continue;
-      }
-      if (line.startsWith("#")) continue; // headings
-      if (/^!?\[[^\]]*\]\([^)]*\)$/.test(line)) continue; // a lone image/badge link
-      if (/^<!--/.test(line)) continue; // html comment
-      para.push(line);
-      if (para.join(" ").length > 320) break; // enough for a lede
-    }
-    if (para.length) {
-      // Strip markdown emphasis for a cleaner one-liner.
-      return para.join(" ").replace(/\*\*?/g, "").replace(/`/g, "").trim();
-    }
-  }
-  return "";
-}
-
-// ===========================================================================
-// git state
-// ===========================================================================
-
-function gitState(cwd) {
-  const branch = gitSafe(["rev-parse", "--abbrev-ref", "HEAD"], { cwd }) || "(unknown)";
-  const head = gitSafe(["rev-parse", "HEAD"], { cwd });
-  const commits = gitSafe(["log", "-5", "--format=%h %s"], { cwd })
-    .split("\n")
-    .filter(Boolean);
-  // Uncommitted = tracked changes + untracked, counted separately.
-  const porcelain = gitSafe(["status", "--porcelain"], { cwd })
-    .split("\n")
-    .filter((l) => l.length > 0);
-  let tracked = 0;
-  let untracked = 0;
-  for (const l of porcelain) {
-    if (l.startsWith("??")) untracked++;
-    else tracked++;
-  }
-  // Unmerged branches (not yet merged into the default branch).
-  const defaultBranch = gitSafe(["rev-parse", "--verify", "--quiet", "main"], { cwd })
-    ? "main"
-    : gitSafe(["rev-parse", "--verify", "--quiet", "master"], { cwd })
-      ? "master"
-      : null;
-  let unmerged = 0;
-  if (defaultBranch) {
-    unmerged = gitSafe(["branch", "--no-merged", defaultBranch], { cwd })
-      .split("\n")
-      .filter((l) => l.trim().length > 0).length;
-  }
-  return { branch, head, commits, tracked, untracked, unmerged, defaultBranch };
-}
-
-// ===========================================================================
-// markdown rendering
-// ===========================================================================
-
-function mdEscape(s) {
-  return String(s).replace(/\|/g, "\\|");
-}
-
-/** Build the full PROJECT-BRIEF.md text. */
-function renderBrief(cwd) {
-  const pkg = readPackage(cwd);
-  const stack = detectStack(cwd, pkg);
-  const pm = detectPackageManager(cwd);
-  const deploy = detectDeploy(cwd);
-  const does = whatItDoes(cwd, pkg);
-  const git = gitState(cwd);
-  const api = scanApiSurface(cwd);
-  const integ = scanIntegrations(cwd);
-  const sched = scanSchedules(cwd);
-  const now = new Date().toISOString();
-  const repoName = path.basename(cwd);
-
-  const claudePresent = existsSync(path.join(cwd, "CLAUDE.md"));
-  const handoffPresent = existsSync(path.join(cwd, "HANDOFF.md"));
-
-  const L = []; // lines
-
-  // ---- frontmatter (machine-readable staleness marker) --------------------
-  L.push("---");
-  L.push("ship_safe_brief: 1");
-  L.push(`generated_at: ${now}`);
-  L.push(`head_sha: ${git.head || "(none)"}`);
-  L.push(`branch: ${git.branch}`);
-  L.push("generator: ship-safe brief");
-  L.push("---");
-  L.push("");
-  L.push(BANNER);
-  L.push("");
-
-  // ---- "for the next agent/model" header ----------------------------------
-  L.push(`# Project Brain — ${pkg.name}`);
-  L.push("");
-  L.push("> **Read this first to get up to speed on this project.** This is a");
-  L.push("> portable, provider-agnostic brief generated from the repo itself by");
-  L.push("> `ship-safe brief`. It lets any model, session, or tool start cold");
-  L.push("> without re-explaining the project — your brain lives in the repo,");
-  L.push("> not in your tool. Everything here is generated from the real tree;");
-  L.push("> if it looks stale, run `ship-safe brief` to refresh it.");
-  L.push(">");
-  L.push("> This is the **COLD** layer — what the project *is* (slow-moving). For the");
-  L.push("> **HOT** layer — where work *left off right now* (what you were doing, the");
-  L.push("> next steps) — read `HANDOFF.md` if present, and run `ship-safe handoff` to");
-  L.push("> refresh both before you switch sessions or models.");
-  L.push("");
-
-  // ---- 1. What the app is --------------------------------------------------
-  L.push("## What this is");
-  L.push("");
-  if (does) {
-    L.push(does);
-    L.push("");
-  }
-  L.push(`- **Name:** ${pkg.name}${pkg.version ? ` (v${pkg.version})` : ""}`);
-  L.push(`- **Repo dir:** \`${repoName}\``);
-  if (stack.length) L.push(`- **Stack:** ${stack.join(" · ")}`);
-  L.push(`- **Package manager:** ${pm}`);
-  L.push("");
-
-  // ---- 2. Architecture map (REUSED scanners) ------------------------------
-  L.push("## Architecture map");
-  L.push("");
-  L.push("*Generated by the same scanners `ship-safe check` uses — so this map and");
-  L.push("the check verdicts never drift.*");
-  L.push("");
-
-  // API surface.
-  L.push("### API surface");
-  L.push("");
-  if (api.rows.length === 0) {
-    L.push("No `app/api/**/route` files found.");
-  } else {
-    L.push(
-      `${api.rows.length} route(s) · ${api.gatedCount} look gated (session or cron secret) · ` +
-        `${api.mutatingCount} mutate (write) · **${api.dangerous.length} mutate without any obvious gate**.`,
-    );
-    L.push("");
-    L.push("| Route | Methods | Posture |");
-    L.push("|---|---|---|");
-    const CAP = 80;
-    for (const r of api.rows.slice(0, CAP)) {
-      const methods = r.methods.length ? r.methods.join(", ") : "—";
-      L.push(`| \`${mdEscape(r.url)}\` | ${mdEscape(methods)} | ${mdEscape(apiRowTag(r))} |`);
-    }
-    if (api.rows.length > CAP) L.push(`| … | | …and ${api.rows.length - CAP} more route(s) |`);
-    if (api.dangerous.length > 0) {
-      L.push("");
-      L.push(
-        `> ⚠ ${api.dangerous.length} route(s) mutate but show no auth/session/cron-secret check — confirm each is meant to be public.`,
-      );
-    }
-  }
-  L.push("");
-
-  // Integrations / agents.
-  L.push("### Integrations & agents");
-  L.push("");
-  const labels = [...integ.integrations.keys()].sort();
-  if (labels.length === 0 && integ.clientSecretHits.length === 0) {
-    L.push("No external LLM / 3rd-party integrations detected in `app/`.");
-  } else {
-    L.push(`${labels.length} integration(s) detected${integ.mcpRouteFound ? " (incl. an MCP server at `/api/mcp`)" : ""}.`);
-    L.push("");
-    L.push("| Integration | Backing env key(s) | Files |");
-    L.push("|---|---|---|");
-    for (const label of labels) {
-      const e = integ.integrations.get(label);
-      const keys = [...e.keys];
-      const keyStr = keys.length ? keys.join(", ") : "_(no key — public endpoint)_";
-      L.push(`| ${mdEscape(label)} | ${mdEscape(keyStr)} | ${e.files.size} |`);
-    }
-    if (integ.clientSecretHits.length > 0) {
-      L.push("");
-      L.push(
-        `> ⚠ ${integ.clientSecretHits.length} secret env read(s) found in \`"use client"\` component(s) — those would ship in the browser bundle.`,
-      );
-    }
-  }
-  L.push("");
-
-  // Schedules / jobs.
-  L.push("### Schedules & jobs");
-  L.push("");
-  if (sched.rows.length === 0) {
-    L.push("No cron routes or `vercel.json` crons found.");
-  } else {
-    L.push(
-      `${sched.rows.length} job(s) · ${sched.cronCount} scheduled in \`vercel.json\` · ` +
-        `${sched.ungated.length} ungated · ${sched.orphanRoutes.length} cron route(s) not wired to a schedule.`,
-    );
-    L.push("");
-    L.push("| Job | Schedule | Gating |");
-    L.push("|---|---|---|");
-    for (const r of sched.rows) {
-      const s = r.schedule ? r.schedule : "not in vercel.json";
-      L.push(`| \`${mdEscape(r.url)}\` | ${mdEscape(s)} | ${mdEscape(scheduleRowTag(r))} |`);
-    }
-  }
-  L.push("");
-
-  // ---- 3. How to work here ------------------------------------------------
-  L.push("## How to work here");
-  L.push("");
-  // Scripts.
-  const scriptNames = Object.keys(pkg.scripts);
-  if (scriptNames.length) {
-    L.push("**Scripts** (from `package.json`):");
-    L.push("");
-    const order = ["dev", "build", "start", "test", "lint", "ship-safe"];
-    const seen = new Set();
-    const ordered = [
-      ...order.filter((s) => pkg.scripts[s]),
-      ...scriptNames.filter((s) => !order.includes(s)),
-    ];
-    for (const s of ordered) {
-      if (seen.has(s)) continue;
-      seen.add(s);
-      L.push(`- \`${pm} run ${s}\` — \`${mdEscape(pkg.scripts[s])}\``);
-    }
-    L.push("");
-  }
-  // Conventions doc.
-  if (claudePresent) {
-    L.push("**Conventions:** `CLAUDE.md` is present at the repo root — read it for the");
-    L.push("project's working rules, hard constraints, and architecture notes.");
-    L.push("");
-  }
-  if (handoffPresent) {
-    L.push("**Current status / in-flight work:** see `HANDOFF.md`.");
-    L.push("");
-  }
-  // Deploy method.
-  L.push("**Deploy:**");
-  L.push("");
-  for (const d of deploy) L.push(`- ${d}`);
-  L.push("");
-
-  // ---- 4. Current state ----------------------------------------------------
-  L.push("## Current state");
-  L.push("");
-  L.push(`- **Branch:** \`${git.branch}\`${git.head ? ` @ \`${git.head.slice(0, 10)}\`` : ""}`);
-  L.push(
-    `- **Working tree:** ${git.tracked} tracked change(s), ${git.untracked} untracked file(s)` +
-      `${git.tracked === 0 && git.untracked === 0 ? " — clean" : " — uncommitted work present"}`,
-  );
-  if (git.defaultBranch) {
-    L.push(`- **Branches not merged into \`${git.defaultBranch}\`:** ${git.unmerged}`);
-  }
-  if (git.commits.length) {
-    L.push("- **Last commits:**");
-    for (const ln of git.commits) L.push(`  - ${mdEscape(ln)}`);
-  }
-  L.push("");
-
-  // ---- footer -------------------------------------------------------------
-  L.push("---");
-  L.push("");
-  L.push(`_Generated by \`ship-safe brief\` at ${now} from \`${git.head ? git.head.slice(0, 10) : "(no HEAD)"}\`._`);
-  L.push("_Regenerate after meaningful changes: `ship-safe brief`. The brief is repo-resident on purpose — commit it so any model/session starts here._");
-  L.push("");
-
-  return { text: L.join("\n"), head: git.head, generatedAt: now, branch: git.branch };
-}
-
-// ===========================================================================
-// staleness marker (.ship-safe/brief.json) + detection
-// ===========================================================================
-
-function markerPath(cwd) {
-  return path.join(cwd, MARKER_DIR, MARKER_FILE);
-}
-
-/**
- * The brief's OWN artifacts — the files a `ship-safe brief` run writes. Staleness
- * must IGNORE changes to these (otherwise committing the freshly-generated brief
- * would immediately mark it stale, because committing it advances HEAD past the
- * sha the brief stamped). Paths are repo-relative, forward-slashed.
- */
-function briefArtifactPaths(cwd, out) {
-  return new Set([
-    relPath(path.resolve(cwd, out), cwd),
-    `${MARKER_DIR}/${MARKER_FILE}`,
-  ]);
-}
-
-/**
- * A content hash of the tracked CODE INPUTS the brief is derived from — i.e.
- * every tracked file EXCEPT the brief's own artifacts (PROJECT-BRIEF.md + the
- * .ship-safe/brief.json marker).
- *
- * We hash each tracked file's ACTUAL WORKING-TREE CONTENT (path + current bytes),
- * deliberately NOT its git blob object-id. The object-id would change the instant
- * a working-tree edit gets COMMITTED even though the bytes are identical — which
- * would make `generate brief → commit the brief → --check` report stale (the very
- * bug this guards against, since committing the brief advances HEAD/the index).
- * Content-hashing is commit-state-independent: the same bytes hash the same
- * whether they sit modified in the working tree or already committed. So:
- *   • generating + committing the brief (only the EXCLUDED artifacts change) keeps
- *     this hash constant → the brief never marks itself stale; while
- *   • any real change to a tracked code file (committed OR uncommitted) flips it.
- *
- * Deletions are folded in via the file list itself (a removed path drops out, so
- * the hash changes). Returns null if git isn't usable (callers fall back to the
- * HEAD-sha comparison).
- */
-function codeInputsHash(cwd, out) {
-  // -z → NUL-separated paths (robust to spaces / odd names, no quoting). This is
-  // the set of tracked files; their CONTENT is what we hash.
-  const listing = gitSafe(["ls-files", "-z"], { cwd });
-  if (!listing) return null;
-  const artifacts = briefArtifactPaths(cwd, out);
-  const h = createHash("sha256");
-
-  const files = listing.split("\0").filter(Boolean).sort();
-  for (const rel of files) {
-    if (artifacts.has(rel)) continue; // ignore the brief's own artifacts
-    const abs = path.resolve(cwd, rel);
-    let body = "";
-    let present = false;
-    try {
-      const st = statSync(abs);
-      if (st.isFile() && st.size <= 4_000_000) {
-        body = readFileSync(abs, "utf8");
-        present = true;
-      } else if (st.isFile()) {
-        // Oversized (e.g. a big asset): hash its size as a cheap proxy rather
-        // than reading megabytes — a content change still moves the size often
-        // enough, and we never want to OOM on a giant tracked binary.
-        body = `__oversize:${st.size}__`;
-        present = true;
-      }
-    } catch {
-      // Tracked but missing from the working tree (deleted/unstaged-delete) —
-      // fold the path in WITHOUT content so its removal still changes the hash.
-    }
-    h.update(rel + "\0" + (present ? "1" : "0") + "\0" + body + "\n");
-  }
-
-  return h.digest("hex");
-}
-
-function writeMarker(cwd, out, head, generatedAt, branch) {
-  const dir = path.join(cwd, MARKER_DIR);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const marker = {
-    schema: 2,
-    out: relPath(path.resolve(cwd, out), cwd),
-    head_sha: head || null,
-    // Content hash of the tracked code inputs EXCLUDING the brief's own
-    // artifacts — this is what staleness keys on, so committing the brief
-    // doesn't mark it stale. head_sha is kept for human display only.
-    code_hash: codeInputsHash(cwd, out),
-    branch: branch || null,
-    generated_at: generatedAt,
-  };
-  writeFileSync(markerPath(cwd), JSON.stringify(marker, null, 2) + "\n", "utf8");
-}
-
-function readMarker(cwd) {
-  return readJson(markerPath(cwd));
-}
-
-/**
- * Staleness verdict. Returns { status, reason } where status ∈
- *   "ok"      — brief present and matches the current HEAD
- *   "missing" — no brief file (or no marker) at all
- *   "stale"   — brief exists but the repo has moved on since it was generated
- * Pure read — never writes.
- */
-export function briefStaleness(cwd, out = DEFAULT_OUT) {
-  const briefAbs = path.resolve(cwd, out);
-  const marker = readMarker(cwd);
-
-  if (!existsSync(briefAbs)) {
-    return { status: "missing", reason: `No project brief at ${relPath(briefAbs, cwd)}.` };
-  }
-  if (!marker) {
-    return {
-      status: "stale",
-      reason: `Project brief exists but its ${MARKER_DIR}/${MARKER_FILE} marker is missing — can't confirm it's current.`,
-    };
-  }
-  const head = gitSafe(["rev-parse", "HEAD"], { cwd });
-
-  // Preferred signal: a content hash of the CODE INPUTS the brief is derived
-  // from, EXCLUDING the brief's own artifacts. This is stable across the
-  // generate→commit-the-brief step (which only touches those artifacts), so the
-  // brief never marks itself stale — but flips the moment real code changes.
-  if (marker.code_hash) {
-    const now = codeInputsHash(cwd, out);
-    if (now && now !== marker.code_hash) {
-      return {
-        status: "stale",
-        reason: `Tracked code changed since the brief was generated — regenerate to reflect it.`,
-      };
-    }
-    if (now) {
-      return { status: "ok", reason: `Project brief is current (code inputs unchanged${head ? `, HEAD ${head.slice(0, 10)}` : ""}).` };
-    }
-    // git unusable now — fall through to the HEAD comparison below.
-  }
-
-  // Fallback (old markers / no git ls-files): compare the raw HEAD sha.
-  if (head && marker.head_sha && head !== marker.head_sha) {
-    return {
-      status: "stale",
-      reason: `Repo HEAD moved to ${head.slice(0, 10)} since the brief was generated at ${String(marker.head_sha).slice(0, 10)}.`,
-    };
-  }
-  return { status: "ok", reason: `Project brief is current (HEAD ${head ? head.slice(0, 10) : "?"}).` };
-}
-
-// ===========================================================================
-// command entrypoints
-// ===========================================================================
-
-/**
- * `ship-safe brief` — generate / refresh the brief, or (`--check`) just report
- * staleness without writing.
- * @param {object} o
- * @param {string} o.cwd     repo root
- * @param {string} [o.out]   output path (default PROJECT-BRIEF.md)
- * @param {boolean} [o.check] check-only mode (no write)
- * @returns {number} exit code (0 always for generate; 0 even when stale in
- *                   --check mode — staleness WARNS, never blocks)
- */
-export function runBrief(o) {
-  const cwd = o.cwd;
-  const out = o.out || DEFAULT_OUT;
-
-  if (o.check) {
-    const s = briefStaleness(cwd, out);
-    if (s.status === "ok") {
-      console.log(`  ${c.green("✓")} ${c.bold("Project brief")} — ${s.reason}`);
-    } else {
-      console.log(
-        `  ${c.yellow("⚠")} ${c.bold("Project brief")} — ${s.reason}`,
-      );
-      console.log(`      ${c.gray("project brief is stale, run `ship-safe brief` to refresh.")}`);
-    }
-    return 0; // a warning, never a NO-GO
-  }
-
-  // Generate.
-  const { text, head, generatedAt, branch } = renderBrief(cwd);
-  const briefAbs = path.resolve(cwd, out);
-  writeFileSync(briefAbs, text, "utf8");
-  writeMarker(cwd, out, head, generatedAt, branch);
-
-  console.log(c.green(`✓ Project brief written → ${relPath(briefAbs, cwd)}`));
-  console.log(c.gray(`  Staleness marker → ${MARKER_DIR}/${MARKER_FILE} (HEAD ${head ? head.slice(0, 10) : "?"})`));
-  console.log(c.gray("  Commit it so any model/session/tool starts here — your brain lives in the repo, not your tool."));
-  return 0;
-}
-
-export { DEFAULT_OUT };
+// Ship-Safe — PROJECT BRAIN (`ship-safe brief`).
+//
+// A portable, repo-resident, provider-agnostic project-context file that ANY
+// model / session / tool can read on start — so you can switch from Claude to
+// Qwen (or just session to session) WITHOUT re-explaining the project. Your
+// brain lives in the REPO, not your tool.
+//
+// `ship-safe brief` generates / updates a markdown file (default
+// PROJECT-BRIEF.md at the repo root; `--out <path>` to relocate) from the REAL
+// repo — everything below is GENERATED by reading the tree, never invented:
+//
+//   • What the app is   — name + description (package.json), detected
+//                          stack/framework/builder, what it does (best-effort
+//                          from README / package description).
+//   • Architecture map  — REUSES the overview scanners (scanApiSurface /
+//                          scanIntegrations / scanSchedules) so the brief and
+//                          the `check` maps never drift: API surface, the
+//                          integrations/agents + their env keys, the schedules.
+//   • How to work here  — CLAUDE.md (if present), package.json scripts
+//                          (dev/build/test), and the detected deploy method.
+//   • Current state     — git branch, last few commits, what's in flight
+//                          (uncommitted + unmerged-branch counts).
+//
+// MAINTENANCE: every generated brief carries a small staleness marker (the HEAD
+// sha + a timestamp) in BOTH the markdown frontmatter and a machine-readable
+// .ship-safe/brief.json. `ship-safe brief --check` (and the hook the main
+// `check` calls) WARNS — never blocks — if the brief is missing or the repo has
+// moved on since it was generated.
+//
+// Node built-ins only. ESM. Generating the brief WRITES two files (the brief +
+// the marker); `--check` reads only.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { c, git, gitSafe, relPath } from "./util.mjs";
+import {
+  scanApiSurface,
+  apiRowTag,
+  scanIntegrations,
+  scanSchedules,
+  scheduleRowTag,
+} from "./overviews.mjs";
+
+const DEFAULT_OUT = "PROJECT-BRIEF.md";
+const MARKER_DIR = ".ship-safe";
+const MARKER_FILE = "brief.json";
+// A stable banner so a model/tool can recognise this file by its first lines.
+const BANNER = "<!-- ship-safe:project-brief -->";
+
+// ===========================================================================
+// repo-fact readers (best-effort; never throw on a missing/oddly-shaped file)
+// ===========================================================================
+
+function readJson(abs) {
+  try {
+    return JSON.parse(readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextSafe(abs, max = 200_000) {
+  try {
+    const st = statSync(abs);
+    if (!st.isFile() || st.size > max) return "";
+    return readFileSync(abs, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** package.json → { name, version, description, scripts, deps, devDeps }. */
+function readPackage(cwd) {
+  const pkg = readJson(path.join(cwd, "package.json")) || {};
+  return {
+    name: typeof pkg.name === "string" ? pkg.name : "(unnamed)",
+    version: typeof pkg.version === "string" ? pkg.version : "",
+    description: typeof pkg.description === "string" ? pkg.description : "",
+    scripts: pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {},
+    deps: pkg.dependencies && typeof pkg.dependencies === "object" ? pkg.dependencies : {},
+    devDeps: pkg.devDependencies && typeof pkg.devDependencies === "object" ? pkg.devDependencies : {},
+  };
+}
+
+/**
+ * Detect the stack/framework/builder from the dependency set + config files.
+ * Returns an array of short human strings (e.g. "Next.js 16.2.0 (App Router)").
+ * Generated from what's actually present — never assumed.
+ */
+function detectStack(cwd, pkg) {
+  const all = { ...pkg.deps, ...pkg.devDeps };
+  const out = [];
+  const ver = (name) => (all[name] ? ` ${String(all[name]).replace(/^[\^~]/, "")}` : "");
+
+  // Framework / runtime.
+  if (all.next) {
+    const appRouter = existsSync(path.join(cwd, "app")) ? " (App Router)" : "";
+    out.push(`Next.js${ver("next")}${appRouter}`);
+  } else if (all["react-scripts"]) out.push("Create React App");
+  else if (all.vite) out.push(`Vite${ver("vite")}`);
+  else if (all.astro) out.push(`Astro${ver("astro")}`);
+  else if (all.remix || all["@remix-run/react"]) out.push("Remix");
+  else if (all.express) out.push(`Express${ver("express")}`);
+
+  if (all.react && !out.some((s) => s.startsWith("Next.js") || s.startsWith("Remix"))) {
+    out.push(`React${ver("react")}`);
+  } else if (all.react) {
+    out.push(`React${ver("react")}`);
+  }
+
+  // Language.
+  if (all.typescript || existsSync(path.join(cwd, "tsconfig.json"))) {
+    out.push(`TypeScript${ver("typescript")}`);
+  }
+
+  // Data layer (presence-driven, from this repo's real deps + the generic ones).
+  if (all["@neondatabase/serverless"]) out.push("Neon serverless Postgres (prod)");
+  if (all["@electric-sql/pglite"]) out.push("PGlite in-process Postgres (local fallback)");
+  if (all["@prisma/client"] || all.prisma) out.push("Prisma");
+  if (all["drizzle-orm"]) out.push("Drizzle ORM");
+
+  // Notable libs that shape how the app works.
+  if (all.stripe) out.push("Stripe (billing)");
+  if (all.jose) out.push("jose (JWT sessions)");
+  if (all.bcryptjs || all.bcrypt) out.push("bcrypt (password hashing)");
+  if (all["mcp-handler"] || all["@modelcontextprotocol/sdk"]) out.push("MCP server (mcp-handler)");
+
+  return out;
+}
+
+/** Detect the package manager from the lockfile present. */
+function detectPackageManager(cwd) {
+  if (existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync(path.join(cwd, "package-lock.json"))) return "npm";
+  if (existsSync(path.join(cwd, "bun.lockb"))) return "bun";
+  return "npm";
+}
+
+/**
+ * Detect the deploy method. We DON'T invent — we report what's observable:
+ *   • a co-located Ship-Safe deploy CLI (this repo) → the safe-deploy ritual
+ *   • a .vercel link / vercel.json → Vercel
+ *   • a Dockerfile / netlify.toml / .github workflows → note them
+ */
+function detectDeploy(cwd) {
+  const notes = [];
+  if (existsSync(path.join(cwd, "cli", "ship-safe", "deploy.mjs"))) {
+    notes.push("Ship-Safe safe-deploy ritual (`ship-safe deploy`) — clean detached worktree + host-prefix confirm.");
+  }
+  if (existsSync(path.join(cwd, ".vercel")) || existsSync(path.join(cwd, "vercel.json"))) {
+    notes.push("Vercel (`vercel --prod` — CLI deploys the WORKING TREE, not a commit).");
+  }
+  if (existsSync(path.join(cwd, "netlify.toml"))) notes.push("Netlify (netlify.toml present).");
+  if (existsSync(path.join(cwd, "Dockerfile"))) notes.push("Docker (Dockerfile present).");
+  if (existsSync(path.join(cwd, ".github", "workflows"))) notes.push("GitHub Actions workflow(s) present (.github/workflows).");
+  if (notes.length === 0) notes.push("No deploy config detected (no .vercel / vercel.json / Dockerfile / CI workflow).");
+  return notes;
+}
+
+/**
+ * Best-effort "what it does" sentence(s). Prefer the package description; fall
+ * back to the first meaningful prose paragraph of the README (skipping the H1,
+ * badges, and blank lines). Never invents — returns "" if nothing usable.
+ */
+function whatItDoes(cwd, pkg) {
+  if (pkg.description) return pkg.description.trim();
+  // Try common README filenames.
+  for (const name of ["README.md", "Readme.md", "readme.md"]) {
+    const txt = readTextSafe(path.join(cwd, name));
+    if (!txt) continue;
+    const lines = txt.split("\n");
+    const para = [];
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (!line) {
+        if (para.length) break; // end of the first prose paragraph
+        continue;
+      }
+      if (line.startsWith("#")) continue; // headings
+      if (/^!?\[[^\]]*\]\([^)]*\)$/.test(line)) continue; // a lone image/badge link
+      if (/^<!--/.test(line)) continue; // html comment
+      para.push(line);
+      if (para.join(" ").length > 320) break; // enough for a lede
+    }
+    if (para.length) {
+      // Strip markdown emphasis for a cleaner one-liner.
+      return para.join(" ").replace(/\*\*?/g, "").replace(/`/g, "").trim();
+    }
+  }
+  return "";
+}
+
+// ===========================================================================
+// git state
+// ===========================================================================
+
+function gitState(cwd) {
+  const branch = gitSafe(["rev-parse", "--abbrev-ref", "HEAD"], { cwd }) || "(unknown)";
+  const head = gitSafe(["rev-parse", "HEAD"], { cwd });
+  const commits = gitSafe(["log", "-5", "--format=%h %s"], { cwd })
+    .split("\n")
+    .filter(Boolean);
+  // Uncommitted = tracked changes + untracked, counted separately.
+  const porcelain = gitSafe(["status", "--porcelain"], { cwd })
+    .split("\n")
+    .filter((l) => l.length > 0);
+  let tracked = 0;
+  let untracked = 0;
+  for (const l of porcelain) {
+    if (l.startsWith("??")) untracked++;
+    else tracked++;
+  }
+  // Unmerged branches (not yet merged into the default branch).
+  const defaultBranch = gitSafe(["rev-parse", "--verify", "--quiet", "main"], { cwd })
+    ? "main"
+    : gitSafe(["rev-parse", "--verify", "--quiet", "master"], { cwd })
+      ? "master"
+      : null;
+  let unmerged = 0;
+  if (defaultBranch) {
+    unmerged = gitSafe(["branch", "--no-merged", defaultBranch], { cwd })
+      .split("\n")
+      .filter((l) => l.trim().length > 0).length;
+  }
+  return { branch, head, commits, tracked, untracked, unmerged, defaultBranch };
+}
+
+// ===========================================================================
+// markdown rendering
+// ===========================================================================
+
+function mdEscape(s) {
+  return String(s).replace(/\|/g, "\\|");
+}
+
+/** Build the full PROJECT-BRIEF.md text. */
+function renderBrief(cwd) {
+  const pkg = readPackage(cwd);
+  const stack = detectStack(cwd, pkg);
+  const pm = detectPackageManager(cwd);
+  const deploy = detectDeploy(cwd);
+  const does = whatItDoes(cwd, pkg);
+  const git = gitState(cwd);
+  const api = scanApiSurface(cwd);
+  const integ = scanIntegrations(cwd);
+  const sched = scanSchedules(cwd);
+  const now = new Date().toISOString();
+  const repoName = path.basename(cwd);
+
+  const claudePresent = existsSync(path.join(cwd, "CLAUDE.md"));
+  const handoffPresent = existsSync(path.join(cwd, "HANDOFF.md"));
+
+  const L = []; // lines
+
+  // ---- frontmatter (machine-readable staleness marker) --------------------
+  L.push("---");
+  L.push("ship_safe_brief: 1");
+  L.push(`generated_at: ${now}`);
+  L.push(`head_sha: ${git.head || "(none)"}`);
+  L.push(`branch: ${git.branch}`);
+  L.push("generator: ship-safe brief");
+  L.push("---");
+  L.push("");
+  L.push(BANNER);
+  L.push("");
+
+  // ---- "for the next agent/model" header ----------------------------------
+  L.push(`# Project Brain — ${pkg.name}`);
+  L.push("");
+  L.push("> **Read this first to get up to speed on this project.** This is a");
+  L.push("> portable, provider-agnostic brief generated from the repo itself by");
+  L.push("> `ship-safe brief`. It lets any model, session, or tool start cold");
+  L.push("> without re-explaining the project — your brain lives in the repo,");
+  L.push("> not in your tool. Everything here is generated from the real tree;");
+  L.push("> if it looks stale, run `ship-safe brief` to refresh it.");
+  L.push(">");
+  L.push("> This is the **COLD** layer — what the project *is* (slow-moving). For the");
+  L.push("> **HOT** layer — where work *left off right now* (what you were doing, the");
+  L.push("> next steps) — read `HANDOFF.md` if present, and run `ship-safe handoff` to");
+  L.push("> refresh both before you switch sessions or models.");
+  L.push("");
+
+  // ---- 1. What the app is --------------------------------------------------
+  L.push("## What this is");
+  L.push("");
+  if (does) {
+    L.push(does);
+    L.push("");
+  }
+  L.push(`- **Name:** ${pkg.name}${pkg.version ? ` (v${pkg.version})` : ""}`);
+  L.push(`- **Repo dir:** \`${repoName}\``);
+  if (stack.length) L.push(`- **Stack:** ${stack.join(" · ")}`);
+  L.push(`- **Package manager:** ${pm}`);
+  L.push("");
+
+  // ---- 2. Architecture map (REUSED scanners) ------------------------------
+  L.push("## Architecture map");
+  L.push("");
+  L.push("*Generated by the same scanners `ship-safe check` uses — so this map and");
+  L.push("the check verdicts never drift.*");
+  L.push("");
+
+  // API surface.
+  L.push("### API surface");
+  L.push("");
+  if (api.rows.length === 0) {
+    L.push("No `app/api/**/route` files found.");
+  } else {
+    L.push(
+      `${api.rows.length} route(s) · ${api.gatedCount} look gated (session or cron secret) · ` +
+        `${api.mutatingCount} mutate (write) · **${api.dangerous.length} mutate without any obvious gate**.`,
+    );
+    L.push("");
+    L.push("| Route | Methods | Posture |");
+    L.push("|---|---|---|");
+    const CAP = 80;
+    for (const r of api.rows.slice(0, CAP)) {
+      const methods = r.methods.length ? r.methods.join(", ") : "—";
+      L.push(`| \`${mdEscape(r.url)}\` | ${mdEscape(methods)} | ${mdEscape(apiRowTag(r))} |`);
+    }
+    if (api.rows.length > CAP) L.push(`| … | | …and ${api.rows.length - CAP} more route(s) |`);
+    if (api.dangerous.length > 0) {
+      L.push("");
+      L.push(
+        `> ⚠ ${api.dangerous.length} route(s) mutate but show no auth/session/cron-secret check — confirm each is meant to be public.`,
+      );
+    }
+  }
+  L.push("");
+
+  // Integrations / agents.
+  L.push("### Integrations & agents");
+  L.push("");
+  const labels = [...integ.integrations.keys()].sort();
+  if (labels.length === 0 && integ.clientSecretHits.length === 0) {
+    L.push("No external LLM / 3rd-party integrations detected in `app/`.");
+  } else {
+    L.push(`${labels.length} integration(s) detected${integ.mcpRouteFound ? " (incl. an MCP server at `/api/mcp`)" : ""}.`);
+    L.push("");
+    L.push("| Integration | Backing env key(s) | Files |");
+    L.push("|---|---|---|");
+    for (const label of labels) {
+      const e = integ.integrations.get(label);
+      const keys = [...e.keys];
+      const keyStr = keys.length ? keys.join(", ") : "_(no key — public endpoint)_";
+      L.push(`| ${mdEscape(label)} | ${mdEscape(keyStr)} | ${e.files.size} |`);
+    }
+    if (integ.clientSecretHits.length > 0) {
+      L.push("");
+      L.push(
+        `> ⚠ ${integ.clientSecretHits.length} secret env read(s) found in \`"use client"\` component(s) — those would ship in the browser bundle.`,
+      );
+    }
+  }
+  L.push("");
+
+  // Schedules / jobs.
+  L.push("### Schedules & jobs");
+  L.push("");
+  if (sched.rows.length === 0) {
+    L.push("No cron routes or `vercel.json` crons found.");
+  } else {
+    L.push(
+      `${sched.rows.length} job(s) · ${sched.cronCount} scheduled in \`vercel.json\` · ` +
+        `${sched.ungated.length} ungated · ${sched.orphanRoutes.length} cron route(s) not wired to a schedule.`,
+    );
+    L.push("");
+    L.push("| Job | Schedule | Gating |");
+    L.push("|---|---|---|");
+    for (const r of sched.rows) {
+      const s = r.schedule ? r.schedule : "not in vercel.json";
+      L.push(`| \`${mdEscape(r.url)}\` | ${mdEscape(s)} | ${mdEscape(scheduleRowTag(r))} |`);
+    }
+  }
+  L.push("");
+
+  // ---- 3. How to work here ------------------------------------------------
+  L.push("## How to work here");
+  L.push("");
+  // Scripts.
+  const scriptNames = Object.keys(pkg.scripts);
+  if (scriptNames.length) {
+    L.push("**Scripts** (from `package.json`):");
+    L.push("");
+    const order = ["dev", "build", "start", "test", "lint", "ship-safe"];
+    const seen = new Set();
+    const ordered = [
+      ...order.filter((s) => pkg.scripts[s]),
+      ...scriptNames.filter((s) => !order.includes(s)),
+    ];
+    for (const s of ordered) {
+      if (seen.has(s)) continue;
+      seen.add(s);
+      L.push(`- \`${pm} run ${s}\` — \`${mdEscape(pkg.scripts[s])}\``);
+    }
+    L.push("");
+  }
+  // Conventions doc.
+  if (claudePresent) {
+    L.push("**Conventions:** `CLAUDE.md` is present at the repo root — read it for the");
+    L.push("project's working rules, hard constraints, and architecture notes.");
+    L.push("");
+  }
+  if (handoffPresent) {
+    L.push("**Current status / in-flight work:** see `HANDOFF.md`.");
+    L.push("");
+  }
+  // Deploy method.
+  L.push("**Deploy:**");
+  L.push("");
+  for (const d of deploy) L.push(`- ${d}`);
+  L.push("");
+
+  // ---- 4. Current state ----------------------------------------------------
+  L.push("## Current state");
+  L.push("");
+  L.push(`- **Branch:** \`${git.branch}\`${git.head ? ` @ \`${git.head.slice(0, 10)}\`` : ""}`);
+  L.push(
+    `- **Working tree:** ${git.tracked} tracked change(s), ${git.untracked} untracked file(s)` +
+      `${git.tracked === 0 && git.untracked === 0 ? " — clean" : " — uncommitted work present"}`,
+  );
+  if (git.defaultBranch) {
+    L.push(`- **Branches not merged into \`${git.defaultBranch}\`:** ${git.unmerged}`);
+  }
+  if (git.commits.length) {
+    L.push("- **Last commits:**");
+    for (const ln of git.commits) L.push(`  - ${mdEscape(ln)}`);
+  }
+  L.push("");
+
+  // ---- footer -------------------------------------------------------------
+  L.push("---");
+  L.push("");
+  L.push(`_Generated by \`ship-safe brief\` at ${now} from \`${git.head ? git.head.slice(0, 10) : "(no HEAD)"}\`._`);
+  L.push("_Regenerate after meaningful changes: `ship-safe brief`. The brief is repo-resident on purpose — commit it so any model/session starts here._");
+  L.push("");
+
+  return { text: L.join("\n"), head: git.head, generatedAt: now, branch: git.branch };
+}
+
+// ===========================================================================
+// staleness marker (.ship-safe/brief.json) + detection
+// ===========================================================================
+
+function markerPath(cwd) {
+  return path.join(cwd, MARKER_DIR, MARKER_FILE);
+}
+
+/**
+ * The brief's OWN artifacts — the files a `ship-safe brief` run writes. Staleness
+ * must IGNORE changes to these (otherwise committing the freshly-generated brief
+ * would immediately mark it stale, because committing it advances HEAD past the
+ * sha the brief stamped). Paths are repo-relative, forward-slashed.
+ */
+function briefArtifactPaths(cwd, out) {
+  return new Set([
+    relPath(path.resolve(cwd, out), cwd),
+    `${MARKER_DIR}/${MARKER_FILE}`,
+  ]);
+}
+
+/**
+ * A content hash of the tracked CODE INPUTS the brief is derived from — i.e.
+ * every tracked file EXCEPT the brief's own artifacts (PROJECT-BRIEF.md + the
+ * .ship-safe/brief.json marker).
+ *
+ * We hash each tracked file's ACTUAL WORKING-TREE CONTENT (path + current bytes),
+ * deliberately NOT its git blob object-id. The object-id would change the instant
+ * a working-tree edit gets COMMITTED even though the bytes are identical — which
+ * would make `generate brief → commit the brief → --check` report stale (the very
+ * bug this guards against, since committing the brief advances HEAD/the index).
+ * Content-hashing is commit-state-independent: the same bytes hash the same
+ * whether they sit modified in the working tree or already committed. So:
+ *   • generating + committing the brief (only the EXCLUDED artifacts change) keeps
+ *     this hash constant → the brief never marks itself stale; while
+ *   • any real change to a tracked code file (committed OR uncommitted) flips it.
+ *
+ * Deletions are folded in via the file list itself (a removed path drops out, so
+ * the hash changes). Returns null if git isn't usable (callers fall back to the
+ * HEAD-sha comparison).
+ */
+function codeInputsHash(cwd, out) {
+  // -z → NUL-separated paths (robust to spaces / odd names, no quoting). This is
+  // the set of tracked files; their CONTENT is what we hash.
+  const listing = gitSafe(["ls-files", "-z"], { cwd });
+  if (!listing) return null;
+  const artifacts = briefArtifactPaths(cwd, out);
+  const h = createHash("sha256");
+
+  const files = listing.split("\0").filter(Boolean).sort();
+  for (const rel of files) {
+    if (artifacts.has(rel)) continue; // ignore the brief's own artifacts
+    const abs = path.resolve(cwd, rel);
+    let body = "";
+    let present = false;
+    try {
+      const st = statSync(abs);
+      if (st.isFile() && st.size <= 4_000_000) {
+        body = readFileSync(abs, "utf8");
+        present = true;
+      } else if (st.isFile()) {
+        // Oversized (e.g. a big asset): hash its size as a cheap proxy rather
+        // than reading megabytes — a content change still moves the size often
+        // enough, and we never want to OOM on a giant tracked binary.
+        body = `__oversize:${st.size}__`;
+        present = true;
+      }
+    } catch {
+      // Tracked but missing from the working tree (deleted/unstaged-delete) —
+      // fold the path in WITHOUT content so its removal still changes the hash.
+    }
+    h.update(rel + "\0" + (present ? "1" : "0") + "\0" + body + "\n");
+  }
+
+  return h.digest("hex");
+}
+
+function writeMarker(cwd, out, head, generatedAt, branch) {
+  const dir = path.join(cwd, MARKER_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const marker = {
+    schema: 2,
+    out: relPath(path.resolve(cwd, out), cwd),
+    head_sha: head || null,
+    // Content hash of the tracked code inputs EXCLUDING the brief's own
+    // artifacts — this is what staleness keys on, so committing the brief
+    // doesn't mark it stale. head_sha is kept for human display only.
+    code_hash: codeInputsHash(cwd, out),
+    branch: branch || null,
+    generated_at: generatedAt,
+  };
+  writeFileSync(markerPath(cwd), JSON.stringify(marker, null, 2) + "\n", "utf8");
+}
+
+function readMarker(cwd) {
+  return readJson(markerPath(cwd));
+}
+
+/**
+ * Staleness verdict. Returns { status, reason } where status ∈
+ *   "ok"      — brief present and matches the current HEAD
+ *   "missing" — no brief file (or no marker) at all
+ *   "stale"   — brief exists but the repo has moved on since it was generated
+ * Pure read — never writes.
+ */
+export function briefStaleness(cwd, out = DEFAULT_OUT) {
+  const briefAbs = path.resolve(cwd, out);
+  const marker = readMarker(cwd);
+
+  if (!existsSync(briefAbs)) {
+    return { status: "missing", reason: `No project brief at ${relPath(briefAbs, cwd)}.` };
+  }
+  if (!marker) {
+    return {
+      status: "stale",
+      reason: `Project brief exists but its ${MARKER_DIR}/${MARKER_FILE} marker is missing — can't confirm it's current.`,
+    };
+  }
+  const head = gitSafe(["rev-parse", "HEAD"], { cwd });
+
+  // Preferred signal: a content hash of the CODE INPUTS the brief is derived
+  // from, EXCLUDING the brief's own artifacts. This is stable across the
+  // generate→commit-the-brief step (which only touches those artifacts), so the
+  // brief never marks itself stale — but flips the moment real code changes.
+  if (marker.code_hash) {
+    const now = codeInputsHash(cwd, out);
+    if (now && now !== marker.code_hash) {
+      return {
+        status: "stale",
+        reason: `Tracked code changed since the brief was generated — regenerate to reflect it.`,
+      };
+    }
+    if (now) {
+      return { status: "ok", reason: `Project brief is current (code inputs unchanged${head ? `, HEAD ${head.slice(0, 10)}` : ""}).` };
+    }
+    // git unusable now — fall through to the HEAD comparison below.
+  }
+
+  // Fallback (old markers / no git ls-files): compare the raw HEAD sha.
+  if (head && marker.head_sha && head !== marker.head_sha) {
+    return {
+      status: "stale",
+      reason: `Repo HEAD moved to ${head.slice(0, 10)} since the brief was generated at ${String(marker.head_sha).slice(0, 10)}.`,
+    };
+  }
+  return { status: "ok", reason: `Project brief is current (HEAD ${head ? head.slice(0, 10) : "?"}).` };
+}
+
+// ===========================================================================
+// command entrypoints
+// ===========================================================================
+
+/**
+ * `ship-safe brief` — generate / refresh the brief, or (`--check`) just report
+ * staleness without writing.
+ * @param {object} o
+ * @param {string} o.cwd     repo root
+ * @param {string} [o.out]   output path (default PROJECT-BRIEF.md)
+ * @param {boolean} [o.check] check-only mode (no write)
+ * @returns {number} exit code (0 always for generate; 0 even when stale in
+ *                   --check mode — staleness WARNS, never blocks)
+ */
+export function runBrief(o) {
+  const cwd = o.cwd;
+  const out = o.out || DEFAULT_OUT;
+
+  if (o.check) {
+    const s = briefStaleness(cwd, out);
+    if (s.status === "ok") {
+      console.log(`  ${c.green("✓")} ${c.bold("Project brief")} — ${s.reason}`);
+    } else {
+      console.log(
+        `  ${c.yellow("⚠")} ${c.bold("Project brief")} — ${s.reason}`,
+      );
+      console.log(`      ${c.gray("project brief is stale, run `ship-safe brief` to refresh.")}`);
+    }
+    return 0; // a warning, never a NO-GO
+  }
+
+  // Generate.
+  const { text, head, generatedAt, branch } = renderBrief(cwd);
+  const briefAbs = path.resolve(cwd, out);
+  writeFileSync(briefAbs, text, "utf8");
+  writeMarker(cwd, out, head, generatedAt, branch);
+
+  console.log(c.green(`✓ Project brief written → ${relPath(briefAbs, cwd)}`));
+  console.log(c.gray(`  Staleness marker → ${MARKER_DIR}/${MARKER_FILE} (HEAD ${head ? head.slice(0, 10) : "?"})`));
+  console.log(c.gray("  Commit it so any model/session/tool starts here — your brain lives in the repo, not your tool."));
+  return 0;
+}
+
+export { DEFAULT_OUT };