@palate/cli 0.0.0-stage → 0.0.1

package/src/guard.mjs

@@ -0,0 +1,377 @@
+// `palate guard`: the agent can't call UI work done until palate has looked at it.
+//
+// It runs when the agent stops (a Claude Code Stop hook: `palate guard --install` adds it), and asks four things
+// about the UI files changed in this session:
+//   1. Looked at: was every changed screen shot by palate after its last edit? (palate shoot / finish / section)
+//   2. Copy: does the changed copy pass palate copy (no hype, filler, placeholder text or unsourced proof)?
+//   3. Code tells: the changed lines against palate check's hard tells (placeholder content, purple gradients,
+//      gradient text). Softer ones (hard-coded colours, glass) are listed, never blocking.
+//   4. Gates: no route still failing the user's rules, the similarity gate, the quality gate or a match.
+// Anything open blocks the stop with one message the agent acts on. Three blocks per session at most, then it lets
+// the agent stop and says what is still open, so the agent tells the user instead of looping. A finding the agent
+// judges wrong is waived with a reason (`palate waive`), never hidden; waivers are listed in every report.
+// No browser, no network: it reads git, the files and .palate/, so a stop costs well under a second.
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { checkFindings } from "./check.mjs";
+import { extractCopy, isCopyFile, lintFiles, projectName } from "./copy.mjs";
+import { PALATE_HOME } from "./catalog/store.mjs";
+import { agentLabel, installedAgents } from "./guard-agents.mjs";
+
+export const MAX_ROUNDS = 3;
+export const MAX_WAIVERS = 12;
+const UI_FILE = /\.(tsx|jsx|vue|svelte|astro|html|css|scss|mdx)$/i;
+const NOT_UI = /(^|\/)(node_modules|\.next|dist|out|build|coverage|\.palate|\.git|\.claude|\.open-next|\.wrangler)\/|\.(test|spec|stories)\.[a-z]+$/i;
+// palate check ids that stop the guard; the rest are listed as worth a look.
+export const HARD_CHECKS = new Set(["placeholder", "purple-gradient", "gradient-text"]);
+const GENERIC_REASON = /^(n\/?a|ok|okay|fine|false positive|not (an )?issue|ignore|skip|wontfix|won't fix|intended|by design|as designed|test)\.?$/i;
+
+const git = (dir, args) => {
+  try {
+    return execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return null;
+  }
+};
+const readJson = (f, d) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return d;
+  }
+};
+const hashFile = (f) => {
+  try {
+    return crypto.createHash("sha1").update(fs.readFileSync(f)).digest("hex").slice(0, 12);
+  } catch {
+    return null;
+  }
+};
+const mtime = (f) => {
+  try {
+    return fs.statSync(f).mtimeMs;
+  } catch {
+    return 0;
+  }
+};
+
+// Files changed against HEAD plus new ones, relative to dir. Null when dir isn't in a git repo.
+export function changedFiles(dir) {
+  if (git(dir, ["rev-parse", "--is-inside-work-tree"])?.trim() !== "true") return null;
+  const tracked = git(dir, ["diff", "HEAD", "--name-only", "--relative"]) ?? git(dir, ["diff", "--name-only", "--relative"]) ?? "";
+  const untracked = git(dir, ["ls-files", "--others", "--exclude-standard"]) ?? "";
+  const all = new Set([...tracked.split("\n"), ...untracked.split("\n")].map((f) => f.trim().replace(/\\/g, "/")).filter(Boolean));
+  return [...all].filter((f) => fs.existsSync(path.join(dir, f)));
+}
+export const isUiFile = (f) => UI_FILE.test(f) && !NOT_UI.test(`/${f}`);
+// A .ts/.js/.json file under the app's source with three or more lines of prose (palate copy reads it as copy).
+export function isContentFile(dir, f) {
+  if (!/\.(ts|js|mjs|json)$/i.test(f) || NOT_UI.test(`/${f}`) || !isCopyFile(f) || /(^|\/)(scripts?|tests?|server|api|lib\/server)\//i.test(f)) return false;
+  try {
+    return extractCopy(fs.readFileSync(path.join(dir, f), "utf8"), f).length >= 3;
+  } catch {
+    return false;
+  }
+}
+
+// A screen's route from its file, when the framework says (Next app/pages, SvelteKit, Astro); else null.
+export function routeOf(file) {
+  const f = file.replace(/\\/g, "/");
+  let m = /(?:^|\/)app\/(.*?)\/?(?:page|layout)\.(?:tsx|jsx|mdx)$/.exec(f);
+  if (m) return "/" + m[1].split("/").filter((p) => p && !/^\(.*\)$/.test(p) && !p.startsWith("@")).join("/");
+  m = /(?:^|\/)pages\/(.*)\.(?:tsx|jsx|astro|mdx)$/.exec(f);
+  if (m && !/^_|\/_/.test(m[1]) && !m[1].startsWith("api/")) return "/" + m[1].replace(/(^|\/)index$/, "");
+  m = /(?:^|\/)routes\/(.*?)\/?\+page\.svelte$/.exec(f);
+  if (m) return "/" + m[1].split("/").filter((p) => p && !/^\(.*\)$/.test(p)).join("/");
+  if (/(^|\/)index\.html$/.test(f)) return "/";
+  return null;
+}
+
+// A file that isn’t a page itself (content.ts, a section component) belongs to the page in its folder, if there is one.
+export function routeNear(dir, f) {
+  const own = routeOf(f);
+  if (own) return own;
+  const folder = path.posix.dirname(f.replace(/\\/g, "/"));
+  for (const page of ["page.tsx", "page.jsx", "page.mdx", "+page.svelte"]) if (fs.existsSync(path.join(dir, folder, page))) return routeOf(path.posix.join(folder, page));
+  return null;
+}
+
+// When this session started: the transcript's first timestamp (Claude Code passes transcript_path), else its file time.
+export function sessionStart(input) {
+  const t = input?.transcript_path;
+  if (t) {
+    try {
+      const fd = fs.openSync(t, "r");
+      const buf = Buffer.alloc(16_384);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      fs.closeSync(fd);
+      const m = /"timestamp"\s*:\s*"([^"]+)"/.exec(buf.subarray(0, n).toString("utf8"));
+      if (m && !Number.isNaN(Date.parse(m[1]))) return Date.parse(m[1]);
+      const st = fs.statSync(t);
+      return st.birthtimeMs || st.ctimeMs;
+    } catch {}
+  }
+  // No transcript: every uncommitted UI change counts (a stop can't know which ones were this session's).
+  return null;
+}
+
+// The newest look palate took of this project's screens (shoot, finish, section and match renders).
+export function lastLook(dir) {
+  let newest = 0;
+  const walk = (d, depth) => {
+    let items;
+    try {
+      items = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const it of items) {
+      const p = path.join(d, it.name);
+      if (it.isDirectory()) {
+        if (depth < 4) walk(p, depth + 1);
+      } else if (/\.(png|jpe?g)$/i.test(it.name)) newest = Math.max(newest, mtime(p));
+    }
+  };
+  for (const sub of ["shots", "sections", "match", "gate", "states"]) walk(path.join(dir, ".palate", sub), 0);
+  return newest;
+}
+
+// ---------- waivers ----------
+const waiverFile = (dir) => path.join(dir, ".palate", "waivers.json");
+export const readWaivers = (dir) => readJson(waiverFile(dir), []).filter((w) => w && w.id && w.reason);
+
+// A waiver is a finding the agent or user judged wrong, with the reason a reviewer would accept. "unshot" (a screen
+// palate couldn't look at) holds only until that file changes again; the others hold until removed.
+export function addWaiver(dir, { id, file, reason, by = "agent" }) {
+  id = String(id ?? "").trim();
+  reason = String(reason ?? "").trim();
+  if (!/^[a-z][a-z0-9-]{2,40}$/.test(id)) return { ok: false, message: `Waive a finding by its id (copy-hype, placeholder, unshot …), not "${id}".` };
+  if (reason.length < 15 || GENERIC_REASON.test(reason)) return { ok: false, message: `A waiver needs a reason someone else would accept, in a sentence (why this finding is wrong here). "${reason}" isn't one.` };
+  const list = readWaivers(dir);
+  const rel = file ? String(file).replace(/\\/g, "/").replace(/^\.\//, "") : undefined;
+  if (rel && id !== "gate" && !fs.existsSync(path.join(dir, rel))) return { ok: false, message: `${rel} doesn't exist in ${dir}.` };
+  const same = (w) => w.id === id && (w.file ?? null) === (rel ?? null);
+  const rest = list.filter((w) => !same(w));
+  if (rest.length >= MAX_WAIVERS) return { ok: false, message: `This project already has ${MAX_WAIVERS} waivers. Fix some of those findings instead, or remove a waiver (palate waive --remove <id>).` };
+  const w = { id, ...(rel ? { file: rel } : {}), reason, by, at: new Date().toISOString(), ...(id === "unshot" && rel ? { hash: hashFile(path.join(dir, rel)) } : {}) };
+  fs.mkdirSync(path.join(dir, ".palate"), { recursive: true });
+  fs.writeFileSync(waiverFile(dir), JSON.stringify([...rest, w], null, 1));
+  recordWaiver(dir, w);
+  return { ok: true, message: `Waived ${id}${rel ? ` in ${rel}` : " everywhere in this project"}: ${reason}${id === "unshot" ? " (until that file changes again)" : ""}. Every guard report lists it.` };
+}
+export function removeWaiver(dir, id, file) {
+  const list = readWaivers(dir);
+  const keep = list.filter((w) => !(w.id === id && (!file || w.file === file)));
+  fs.mkdirSync(path.join(dir, ".palate"), { recursive: true });
+  fs.writeFileSync(waiverFile(dir), JSON.stringify(keep, null, 1));
+  return list.length - keep.length ? `Removed ${list.length - keep.length} waiver${list.length - keep.length > 1 ? "s" : ""} for ${id}.` : `No waiver for ${id}${file ? ` in ${file}` : ""}.`;
+}
+const waived = (waivers, dir, id, file) =>
+  waivers.find((w) => w.id === id && (!w.file || w.file === file) && (w.id !== "unshot" || !w.hash || w.hash === hashFile(path.join(dir, file))));
+
+// What the user keeps waiving across projects is taste: a copy tell waived with a reason in three or more
+// projects stops blocking for this user (it is still listed). The record stays on this machine.
+const WAIVER_LOG = () => path.join(PALATE_HOME, "history", "waivers.jsonl");
+function recordWaiver(dir, w) {
+  try {
+    fs.mkdirSync(path.dirname(WAIVER_LOG()), { recursive: true });
+    fs.appendFileSync(WAIVER_LOG(), JSON.stringify({ project: projectName(dir), id: w.id, reason: w.reason, by: w.by, at: w.at }) + "\n");
+  } catch {}
+}
+export function keptTells() {
+  const projects = new Map();
+  try {
+    for (const line of fs.readFileSync(WAIVER_LOG(), "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      const r = JSON.parse(line);
+      if (!r.id?.startsWith("copy-")) continue;
+      (projects.get(r.id) ?? projects.set(r.id, new Set()).get(r.id)).add(r.project);
+    }
+  } catch {}
+  return new Set([...projects].filter(([, p]) => p.size >= 3).map(([id]) => id));
+}
+
+// ---------- credits ----------
+// Every credits.json palate imagery wrote (public/ or static/, a few folders deep), its CC BY entries whose image the
+// source uses, and of those the ones whose author appears nowhere in the source.
+export function missingCredits(dir) {
+  const lists = [];
+  const walk = (d, depth) => {
+    let items;
+    try {
+      items = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const it of items) {
+      if (it.isDirectory() && depth < 4) walk(path.join(d, it.name), depth + 1);
+      else if (it.name === "credits.json") lists.push(readJson(path.join(d, it.name), []));
+    }
+  };
+  for (const pub of ["public", "static"]) walk(path.join(dir, pub), 0);
+  const owed = lists.flat().filter((e) => e && typeof e.file === "string" && (e.attribution || /^CC BY \d/.test(e.licence ?? "")) && e.artist);
+  if (!owed.length) return [];
+  const files = (git(dir, ["ls-files", "--cached", "--others", "--exclude-standard"]) ?? "").split("\n").filter((f) => f && /\.(tsx|jsx|vue|svelte|astro|html|mdx|ts|js|mjs|json|md)$/i.test(f) && !NOT_UI.test(`/${f}`) && !/credits\.json$/.test(f));
+  let source = "";
+  for (const f of files) {
+    try {
+      const st = fs.statSync(path.join(dir, f));
+      if (st.size < 400_000) source += "\n" + fs.readFileSync(path.join(dir, f), "utf8");
+    } catch {}
+  }
+  const fold = (s) => s.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase();
+  const all = fold(source);
+  return owed
+    .filter((e) => all.includes(fold(path.basename(e.file))) && !all.includes(fold(e.artist)))
+    .map((e) => ({ file: e.file, artist: e.artist, licence: e.licence, line: `${e.title}, ${e.artist}, ${e.licence}${e.changed ? `, ${e.changed}` : ""}` }));
+}
+
+// ---------- the guard ----------
+const stateFile = (dir) => path.join(dir, ".palate", "guard.json");
+
+// Inspect the project. Returns { open: [{ kind, id, text }], soft: [string], waived: [waiver], files, routes }.
+export function inspect(dir, { since = null } = {}) {
+  const changed = changedFiles(dir);
+  if (changed === null) return { skip: "not a git repository, so palate can't tell what changed" };
+  const copyFiles = changed.filter((f) => !since || mtime(path.join(dir, f)) > since);
+  // A content file (content.ts, strings.json) changes what a page shows: it counts as UI when it holds copy.
+  const ui = copyFiles.filter((f) => isUiFile(f) || isContentFile(dir, f));
+  if (!ui.length) return { skip: "no UI files changed in this session", files: [] };
+  const waivers = readWaivers(dir);
+  const used = new Set();
+  const open = [];
+  const soft = [];
+  const note = (w) => w && used.add(w);
+
+  // 1. Looked at after the last edit.
+  const look = lastLook(dir);
+  const unshot = ui.filter((f) => mtime(path.join(dir, f)) > look + 1500);
+  for (const f of unshot) {
+    const w = waived(waivers, dir, "unshot", f);
+    if (w) note(w);
+    else open.push({ kind: "unshot", id: "unshot", file: f, route: routeOf(f), text: f });
+  }
+
+  // 2. Copy.
+  const kept = keptTells();
+  const copy = lintFiles(dir, copyFiles);
+  for (const c of copy.findings) {
+    if (c.weight === "habit" && !c.over) continue;
+    const w = waived(waivers, dir, c.id, c.file);
+    if (w) { note(w); continue; }
+    const line = `${c.id} ${c.file}:${c.line} "${c.text.slice(0, 70)}"${c.match && c.match.length < c.text.length ? ` (${c.match})` : ""}`;
+    if (c.weight === "hint" || kept.has(c.id)) soft.push(`${line}${kept.has(c.id) ? " (you've kept this one in 3+ projects)" : ""}`);
+    else open.push({ kind: "copy", id: c.id, file: c.file, text: `${line}: ${c.fix}` });
+  }
+
+  // 3. Code tells on the changed lines.
+  const { findings, blockers } = checkFindings(dir, { only: ui.concat(copyFiles) });
+  for (const f of findings) {
+    if (f.id === "em-dash" || f.id === "emoji") { if (!waived(waivers, dir, f.id, f.file)) soft.push(`${f.id} ${f.file}: ${f.text.slice(0, 70)}`); continue; }
+    const w = waived(waivers, dir, f.id, f.file);
+    if (w) { note(w); continue; }
+    if (HARD_CHECKS.has(f.id)) open.push({ kind: "code", id: f.id, file: f.file, text: `${f.id} ${f.file}: ${f.text.slice(0, 70)}: ${f.fix}` });
+    else soft.push(`${f.id} ${f.file}: ${f.text.slice(0, 60)}`);
+  }
+
+  // 4. Credits: a CC BY photo the page uses must be credited on it (its author's name somewhere in the source).
+  for (const c of missingCredits(dir)) {
+    const w = waived(waivers, dir, "credit", c.file.replace(/^\//, ""));
+    if (w) note(w);
+    else open.push({ kind: "credit", id: "credit", text: `credit ${c.file} (${c.licence}, ${c.artist}): used on the page but its credit isn't. Show: "${c.line}"` });
+  }
+
+  // 5. Gates still failing (rules, similarity, quality, match).
+  for (const b of blockers) {
+    // A gate waiver names its route ("/", "/pricing"): the blocker text starts with it.
+    const w = waivers.find((x) => x.id === "gate" && x.file && (b.startsWith(`${x.file} `) || b.startsWith(`/${x.file.replace(/^\//, "")} `)));
+    if (w) note(w);
+    // A final verdict (its repair rounds are used up) is for the user to hear, not for the agent to loop on.
+    else if (/Tell the user exactly this/.test(b)) soft.push(`gate, final: ${b.replace(/ Tell the user exactly this.*$/, "")} (tell the user)`);
+    else open.push({ kind: "gate", id: "gate", text: b });
+  }
+  return { open, soft, waived: [...used], files: ui, routes: [...new Set(unshot.map((f) => routeNear(dir, f)).filter(Boolean))] };
+}
+
+// The message the agent reads when its stop is blocked: what is open and the one next step for each kind.
+export function blockMessage(r, round) {
+  const out = [`palate guard: not done yet (round ${round} of ${MAX_ROUNDS}). Fix these, then finish:`];
+  const unshot = r.open.filter((o) => o.kind === "unshot");
+  if (unshot.length) {
+    const routes = r.routes.length ? r.routes.join(", ") : "the routes these files render";
+    out.push("", `Not looked at since the last edit (${unshot.length} file${unshot.length > 1 ? "s" : ""}): ${unshot.slice(0, 6).map((o) => o.file).join(", ")}${unshot.length > 6 ? ` and ${unshot.length - 6} more` : ""}.`, `→ palate_shoot ${routes} (a small change: fold: true at 1440) or palate_finish on a new screen, and fix what it reports.`);
+  }
+  const copy = r.open.filter((o) => o.kind === "copy");
+  if (copy.length) out.push("", `Copy (${copy.length}):`, ...copy.slice(0, 8).map((o) => `- ${o.text}`), ...(copy.length > 8 ? [`- … ${copy.length - 8} more (palate copy lists them all)`] : []));
+  const code = r.open.filter((o) => o.kind === "code");
+  if (code.length) out.push("", `Code (${code.length}):`, ...code.slice(0, 6).map((o) => `- ${o.text}`));
+  const credit = r.open.filter((o) => o.kind === "credit");
+  if (credit.length) out.push("", "Credits owed (CC BY photos):", ...credit.map((o) => `- ${o.text}`), "→ Add them to the page's credits line (palate's creditsParagraph format is fine).");
+  const gate = r.open.filter((o) => o.kind === "gate");
+  if (gate.length) out.push("", "Gates still failing:", ...gate.map((o) => `- ${o.text}`), "→ Run the repair the gate wrote, then palate_gate on that route again for a new round (it rolls back a round that got worse). If a gate finding misreads the page (a measurement, not a judgement), palate_waive with id \"gate\", file = the route and the reason, and tell the user. Stopping again without either changes nothing.");
+  if (r.soft.length) out.push("", `Worth a look, not blocking (${r.soft.length}): ${r.soft.slice(0, 4).join("; ")}${r.soft.length > 4 ? " …" : ""}`);
+  if (r.waived.length) out.push("", `Waived: ${r.waived.map((w) => `${w.id}${w.file ? ` (${w.file})` : ""}: ${w.reason}`).join("; ")}`);
+  out.push("", "A finding that is wrong here: palate_waive with its id, the file and a reason the user would accept (an \"unshot\" waiver when no dev server can run). Don't ask the user; fix or waive, then stop again.");
+  return out.join("\n");
+}
+
+// The hook: decide for one stop. input is normalised by guard-agents.parseInput ({ session_id, transcript_path, cwd }).
+export function decide(input = {}, { dir: given } = {}) {
+  const dir = path.resolve(given ?? input.cwd ?? process.cwd());
+  const state = readJson(stateFile(dir), {});
+  const session = input.session_id ?? "local";
+  const fresh = state.session !== session;
+  const s = fresh ? { session, started: Date.now(), round: 0 } : state;
+  if (input.skip) return { decision: "allow", quiet: true, why: input.skip };
+  const since = sessionStart(input);
+  const r = inspect(dir, { since: since ? since - 2000 : null });
+  const key = (r.open ?? []).map((o) => `${o.id}:${o.file ?? ""}`).join("|");
+  const save = (extra) => {
+    try {
+      // The round count must survive, or a block could repeat forever: .palate is created (and git-ignored) if needed.
+      if (!fs.existsSync(path.join(dir, ".palate"))) {
+        fs.mkdirSync(path.join(dir, ".palate"), { recursive: true });
+        fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+      }
+      fs.writeFileSync(stateFile(dir), JSON.stringify({ ...s, ...extra, key, at: new Date().toISOString() }, null, 1));
+      fs.appendFileSync(path.join(dir, ".palate", "guard.jsonl"), JSON.stringify({ at: new Date().toISOString(), session, agent: input.agent ?? null, ...extra, open: (r.open ?? []).map((o) => o.id), waived: (r.waived ?? []).map((w) => w.id) }) + "\n");
+    } catch {}
+  };
+  if (r.skip) return { decision: "allow", quiet: true, why: r.skip };
+  if (!r.open.length) {
+    save({ round: 0, last: "pass" }); // later edits in the same session get their own rounds
+    return { decision: "allow", message: `palate guard: passed (${r.files.length} UI file${r.files.length === 1 ? "" : "s"} looked at${r.waived.length ? `, ${r.waived.length} waived` : ""}${r.soft.length ? `, ${r.soft.length} worth a look` : ""}).` };
+  }
+  // The same stop seen twice (two hook files for one agent, a re-sent payload): the same answer, no new round.
+  if (!fresh && state.last === "block" && state.key === key && Date.now() - Date.parse(state.at ?? 0) < 2000) return { decision: "block", reason: blockMessage(r, s.round), open: r.open, repeat: true };
+  if (s.round >= MAX_ROUNDS) {
+    save({ round: s.round, last: "gave-up" });
+    return { decision: "allow", message: `palate guard: ${MAX_ROUNDS} rounds used, letting the agent stop. Still open: ${r.open.slice(0, 5).map((o) => o.text.split(":")[0]).join("; ")}${r.open.length > 5 ? " …" : ""}.`, open: r.open };
+  }
+  const round = s.round + 1;
+  save({ round, last: "block" });
+  return { decision: "block", reason: blockMessage(r, round), open: r.open };
+}
+
+// ---------- install (every agent: guard-agents.mjs) ----------
+export { install, installedAgents, hookCommand } from "./guard-agents.mjs";
+export const installed = (dir) => installedAgents(dir)[0]?.file ?? null;
+
+// `palate guard` with no flags: the same inspection, printed for a person (no session limit, no rounds).
+export function report(dir) {
+  const r = inspect(dir);
+  const on = installedAgents(dir);
+  const head = on.length ? `palate guard is on for ${on.map((o) => agentLabel(o.agent)).join(", ")}.` : "palate guard is off here. palate guard --install turns it on for the agents this project uses.";
+  if (r.skip) return `${head}\nNothing to check: ${r.skip}.`;
+  if (!r.open.length) return `${head}\nPasses: ${r.files.length} changed UI file${r.files.length === 1 ? "" : "s"}, all looked at, copy and gates clean${r.waived.length ? `, ${r.waived.length} waived` : ""}.${r.soft.length ? `\nWorth a look: ${r.soft.join("; ")}` : ""}`;
+  return `${head}\n${blockMessage(r, 1).replace(/ \(round 1 of 3\)/, "")}`;
+}
+
+// The git pre-commit check (any agent, or a person): the report, and exit 1 while something is open.
+export function commitCheck(dir) {
+  const r = inspect(dir);
+  if (r.skip || !r.open.length) return { ok: true, text: r.skip ? "" : `palate guard: passed (${r.files.length} UI file${r.files.length === 1 ? "" : "s"}).` };
+  return { ok: false, text: `${blockMessage(r, 1).replace(/ \(round 1 of 3\)/, "").replace(/Don't ask the user; fix or waive, then stop again\./, "Fix or waive, then commit again (git commit --no-verify skips this once).")}` };
+}

package/src/kb.mjs

@@ -0,0 +1,91 @@
+// The knowledge base: Markdown entries with YAML frontmatter in /kb. Search returns short cards;
+// `show` returns full entries. Keyword and facet scoring, no embeddings, works offline.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import { KB_ROOT } from "./paths.mjs";
+
+const KB_DIR = process.env.PALATE_KB ?? KB_ROOT;
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = path.join(dir, e.name);
+    return e.isDirectory() ? walk(p) : e.name.endsWith(".md") ? [p] : [];
+  });
+}
+
+// Knowledge entries are the Markdown files with frontmatter. Source lists (kb/sources) and the shipped
+// index (kb/index) live in the same tree but aren't entries, so anything without frontmatter is skipped. Moves
+// (kb/moves) have their own loader and matcher in moves.mjs.
+export function loadKb() {
+  return walk(KB_DIR).flatMap((file) => {
+    if (/[\\/](sources|index|systems|moves)[\\/]/.test(path.relative(KB_DIR, file).replace(/^/, "/"))) return [];
+    const src = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+    const m = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!m) return [];
+    const meta = YAML.parse(m[1]);
+    return meta?.id ? [{ ...meta, body: m[2].trim(), file }] : [];
+  });
+}
+
+const words = (s) => (s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? [];
+const asText = (v) => (Array.isArray(v) ? v.join(" ") : typeof v === "string" ? v : "");
+
+export function search(query, { scope, limit = 6 } = {}) {
+  const q = new Set(words(query).filter((w) => w.length > 2 || /\d/.test(w)));
+  const entries = loadKb();
+  const scored = entries.map((e) => {
+    const fields = [
+      [asText(e.title), 4],
+      [asText(e.role), 4],
+      [asText(e.tags), 3],
+      [asText(e.answers), 2],
+      [asText(e.use_when), 2],
+      [asText(e.scope), 2],
+      [e.body.slice(0, 2000), 0.3],
+    ];
+    let score = 0;
+    for (const [text, weight] of fields) {
+      const ws = words(text);
+      for (const w of q) if (ws.includes(w)) score += weight;
+    }
+    if (scope && asText(e.scope).includes(scope)) score += 3;
+    if (e.kind === "universal") score += 0.5;
+    return { e, score };
+  });
+  return scored
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ e }) => e);
+}
+
+export function card(e) {
+  return [
+    `### ${e.id}: ${e.title}`,
+    `- kind: ${e.kind}${e.scope ? ` · scope: ${asText(e.scope)}` : ""}`,
+    e.answers ? `- answers: ${e.answers}` : undefined,
+    e.use_when ? `- use when: ${asText(e.use_when)}` : undefined,
+    e.avoid_when ? `- avoid when: ${asText(e.avoid_when)}` : undefined,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function show(ids) {
+  const entries = loadKb();
+  return ids.map((id) => {
+    const e = entries.find((x) => x.id === id);
+    if (!e) return `No entry "${id}". Run palate search to find ids.`;
+    const sources = e.seen_in ? `\n\nSeen in: ${asText(e.seen_in.map?.((s) => (typeof s === "string" ? s : s.source)) ?? e.seen_in)}` : "";
+    return `## ${e.id}: ${e.title}\n\n${e.body}${sources}`;
+  });
+}
+
+export function list() {
+  return loadKb()
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((e) => `${e.id.padEnd(34)} ${e.title}`);
+}