@praxisflux/gates 0.5.0

package/spec-bridge/lib/gate-runner.mjs

@@ -0,0 +1,69 @@
+// gate-runner.mjs — the shared Stop-hook harness.
+//
+// Each plugin ships a Stop hook whose command is a one-line Node entry that calls runStopHook
+// with that plugin's gates. When several plugins are installed, each fires its own hook — so
+// "run every applicable gate" happens naturally across plugins; within one plugin the runner
+// runs that plugin's gates additively over every root they resolve.
+//
+// A gate is: { name, resolveRoots(startDir) -> string[], check(root) -> string[] (problems),
+//             warn?(root) -> string[] (non-blocking notices) }.
+// A gate that resolves no roots is a no-op (this isn't its kind of project). `check` problems
+// block the stop (exit 2); optional `warn` notices are surfaced on stderr but never block (exit 0)
+// — for freshness reminders and the like that shouldn't refuse to let the model finish.
+//
+// Contract (Claude Code Stop hook): stdin is JSON with { stop_hook_active, cwd, … };
+// exit 0 = allow the model to stop; exit 2 = block, and stderr becomes the message it sees.
+
+/** Read all of stdin as a string (empty string on a TTY, so it's safe to run by hand). */
+export function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve("");
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+  });
+}
+
+/**
+ * Pure core: given the parsed hook input and the gates, return { block, message }.
+ * Separated from process I/O so it is unit-testable.
+ */
+export function evaluate(input, gates, { cwd = process.cwd() } = {}) {
+  if (input && input.stop_hook_active === true) return { block: false, message: "", warnings: "" };
+  const start = process.env.CLAUDE_PROJECT_DIR || (input && input.cwd) || cwd;
+  const problems = [];
+  const warnings = [];
+  for (const gate of gates) {
+    let roots = [];
+    try { roots = gate.resolveRoots(start) || []; } catch { roots = []; }
+    for (const root of roots) {
+      try { problems.push(...(gate.check(root) || [])); } catch (e) {
+        problems.push(`[${gate.name || "gate"}] crashed on ${root}: ${e.message}`);
+      }
+      if (typeof gate.warn === "function") {
+        try { warnings.push(...(gate.warn(root) || [])); } catch { /* warnings are best-effort */ }
+      }
+    }
+  }
+  return { block: problems.length > 0, message: problems.join("\n"), warnings: warnings.join("\n") };
+}
+
+/**
+ * Full harness: read stdin, evaluate the gates, exit 0 (allow) or 2 (block, message on stderr).
+ * Blocking problems win; otherwise any non-blocking warnings are written to stderr and we still
+ * allow the stop (exit 0).
+ */
+export async function runStopHook({ gates, exit = process.exit } = {}) {
+  const raw = await readStdin();
+  let input = {};
+  try { input = JSON.parse(raw || "{}"); } catch { input = {}; }
+  const { block, message, warnings } = evaluate(input, gates);
+  if (block) {
+    process.stderr.write([message, warnings].filter(Boolean).join("\n") + "\n");
+    exit(2);
+  } else {
+    if (warnings) process.stderr.write(warnings + "\n");
+    exit(0);
+  }
+}

package/spec-bridge/lib/handoff.mjs

@@ -0,0 +1,75 @@
+// handoff.mjs — the shared inter-plugin handoff TRANSPORT (envelope + lifecycle, not semantics).
+//
+// One plugin hands work to another through files, but those messages are transient plumbing —
+// they must NOT clutter git. So payloads live in a gitignored `.handoff/` at the project root;
+// the durable EVIDENCE that a handoff happened is the consumer's job to record in its own tracked
+// state (e.g. progress.json). The chassis moves opaque payloads and never touches a plugin's ledger.
+//
+// The payload SCHEMA is per plugin pair (educate→build sends a SPEC; build→educate returns
+// findings). This module only knows the envelope: id, kind (request|response), from, to, ref.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { ensureGitignore } from "./installer.mjs";
+import { parseFrontmatter } from "./markdown.mjs";
+
+export const HANDOFF_DIR = ".handoff";
+
+export function handoffDir(root) { return join(root, HANDOFF_DIR); }
+
+/** Ensure `.handoff/` exists and is gitignored (so it never shows in `git status`). */
+export function ensureHandoffDir(root) {
+  const dir = handoffDir(root);
+  mkdirSync(dir, { recursive: true });
+  ensureGitignore(root, HANDOFF_DIR + "/");
+  return dir;
+}
+
+/**
+ * Write a handoff. Envelope fields are frontmatter; `body` is the opaque, plugin-defined payload.
+ *   kind: "request" (e.g. a SPEC) | "response" (e.g. findings)
+ *   ref:  correlation id tying a response back to its request
+ * Returns the file path.
+ */
+export function writeHandoff(root, { id, kind, from, to, ref = "", title = "", body = "" }) {
+  if (!id || !kind || !from || !to) throw new Error("handoff requires id, kind, from, to");
+  const dir = ensureHandoffDir(root);
+  const fm = [`id: ${id}`, `kind: ${kind}`, `from: ${from}`, `to: ${to}`, `ref: ${ref}`, `title: ${title}`].join("\n");
+  const path = join(dir, `${id}.md`);
+  writeFileSync(path, `---\n${fm}\n---\n${body}\n`);
+  return path;
+}
+
+/** Read a handoff → { envelope, body, path } or null if absent. */
+export function readHandoff(root, id) {
+  const path = join(handoffDir(root), `${id}.md`);
+  if (!existsSync(path)) return null;
+  const text = readFileSync(path, "utf8");
+  const envelope = parseFrontmatter(text) || {};
+  const body = text.replace(/^---[\s\S]*?\n---\s*\n?/, "");
+  return { envelope, body, path };
+}
+
+/** List pending (unconsumed) handoffs, optionally filtered by envelope fields, e.g. {to, kind, ref}. */
+export function listHandoffs(root, filter = {}) {
+  const dir = handoffDir(root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => readHandoff(root, f.replace(/\.md$/, "")))
+    .filter((h) => h && Object.entries(filter).every(([k, v]) => h.envelope[k] === v));
+}
+
+/**
+ * Consume a handoff: move it into `.handoff/consumed/` so it stops appearing as pending. The
+ * durable record ("this handoff happened, here's what it changed") is the CONSUMER's job to write
+ * into its own tracked state — the chassis never edits a plugin's ledger. Returns false if absent.
+ */
+export function markConsumed(root, id) {
+  const src = join(handoffDir(root), `${id}.md`);
+  if (!existsSync(src)) return false;
+  const cdir = join(handoffDir(root), "consumed");
+  mkdirSync(cdir, { recursive: true });
+  renameSync(src, join(cdir, `${id}.md`));
+  return true;
+}

package/spec-bridge/lib/html/base.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>praxis — self-contained page base</title>
+<!--
+  base.html — the SHARED, self-contained, theme-aware foundation for every praxis HTML artifact
+  (educate decks AND research briefings). Copy the token block, reset, theme-toggle, and table
+  component from here; never load anything external (the Artifact CSP blocks remote hosts —
+  inline all CSS/JS, embed images as data: URIs). Validate the result with lib/selfcontained.mjs.
+
+  Theme contract: style with the tokens below. Light is the default; dark is provided both by
+  @media (prefers-color-scheme: dark) AND by :root[data-theme="dark"], and an explicit
+  :root[data-theme="light"] block lets the on-page toggle override the OS in either direction.
+-->
+<style>
+  /* The canonical token schema. Hand-edit ONLY here (between the praxis:tokens markers);
+     consumers (educate's deck template) carry a stamped copy — scripts/sync-shared.mjs. */
+  /* praxis:tokens:start */
+  /* ---- design tokens (light) ---- */
+  :root{
+    --bg:#f4f6f9; --card:#ffffff; --ink:#1b2733; --muted:#5a6776;
+    --accent:#4f46e5; --accent2:#0e9488; --warn:#b4530a;
+    --line:#dde3ea; --chip:#f3f5f8;
+    --callout-bg:#f5f5ff; --warn-bg:#fff6ee; --ok-bg:#eefaf7;
+    --sans:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+    --mono:"SF Mono",ui-monospace,"JetBrains Mono",Menlo,Consolas,monospace;
+  }
+  /* ---- dark tokens: follow the OS by default ... ---- */
+  @media (prefers-color-scheme: dark){
+    :root{
+      --bg:#0e141b; --card:#161d26; --ink:#e7ecf2; --muted:#9aa7b5;
+      --accent:#8b83ff; --accent2:#3ac9b8; --warn:#e8903f;
+      --line:#28323e; --chip:#1d2630;
+      --callout-bg:#1b1d38; --warn-bg:#33220f; --ok-bg:#0f2a27;
+    }
+  }
+  /* ... and the on-page toggle wins in either direction. */
+  :root[data-theme="dark"]{
+    --bg:#0e141b; --card:#161d26; --ink:#e7ecf2; --muted:#9aa7b5;
+    --accent:#8b83ff; --accent2:#3ac9b8; --warn:#e8903f;
+    --line:#28323e; --chip:#1d2630;
+    --callout-bg:#1b1d38; --warn-bg:#33220f; --ok-bg:#0f2a27;
+  }
+  :root[data-theme="light"]{
+    --bg:#f4f6f9; --card:#ffffff; --ink:#1b2733; --muted:#5a6776;
+    --accent:#4f46e5; --accent2:#0e9488; --warn:#b4530a;
+    --line:#dde3ea; --chip:#f3f5f8;
+    --callout-bg:#f5f5ff; --warn-bg:#fff6ee; --ok-bg:#eefaf7;
+  }
+  /* praxis:tokens:end */
+
+  /* ---- reset + base ---- */
+  *{box-sizing:border-box}
+  html,body{margin:0}
+  body{background:var(--bg);color:var(--ink);font-family:var(--sans);line-height:1.55;
+    -webkit-text-size-adjust:100%;padding:0}
+  .wrap{max-width:900px;margin:0 auto;padding:40px 24px 80px}
+  h1{font-size:2rem;line-height:1.15;letter-spacing:-.02em;margin:0 0 .4em}
+  h2{font-size:1.4rem;margin:1.8em 0 .5em;letter-spacing:-.01em}
+  p,li{font-size:1.05rem;color:var(--ink)}
+  .muted{color:var(--muted)}
+  a{color:var(--accent)}
+  code,.mono{font-family:var(--mono);background:var(--chip);border:1px solid var(--line);
+    border-radius:6px;padding:1px 6px;font-size:.9em}
+  .callout{border-left:4px solid var(--accent);background:var(--callout-bg);
+    border-radius:0 10px 10px 0;padding:14px 18px;margin:16px 0}
+  .callout.warn{border-left-color:var(--warn);background:var(--warn-bg)}
+  .callout.ok{border-left-color:var(--accent2);background:var(--ok-bg)}
+
+  /* ---- auditable data table (numbers must trace) ---- */
+  table.data{border-collapse:collapse;width:100%;margin:16px 0;font-size:.98rem}
+  table.data caption{text-align:left;color:var(--muted);font-size:.9rem;margin-bottom:6px}
+  table.data th,table.data td{border:1px solid var(--line);padding:8px 12px;text-align:left}
+  table.data thead th{background:var(--chip);font-weight:700}
+  table.data td.num{text-align:right;font-variant-numeric:tabular-nums;font-family:var(--mono)}
+  .table-scroll{overflow-x:auto}
+
+  /* ---- theme toggle ---- */
+  .theme-toggle{position:fixed;top:14px;right:14px;z-index:50;font:inherit;font-size:.9rem;
+    color:var(--ink);background:var(--card);border:1px solid var(--line);border-radius:8px;
+    padding:6px 12px;cursor:pointer}
+  .theme-toggle:hover{background:var(--chip)}
+  @media print{ .theme-toggle{display:none} body{background:#fff} }
+</style>
+</head>
+<body>
+<button class="theme-toggle" id="themeToggle" aria-label="Toggle light/dark theme">◐ theme</button>
+<div class="wrap">
+  <h1>Self-contained page base</h1>
+  <p class="muted">The shared foundation for praxis artifacts — theme-aware, offline, CSP-safe.
+    Replace this content; keep the tokens, reset, toggle, and table.</p>
+
+  <div class="callout">Lead with the point. A briefing leads with the analysis's verdict; a deck
+    leads with the lesson's claim.</div>
+
+  <h2>Auditable figures</h2>
+  <p>Every number an artifact shows should trace to its source. Include a table so a reader can check.</p>
+  <div class="table-scroll">
+    <table class="data">
+      <caption>Example — figures trace to the grounding/analysis</caption>
+      <thead><tr><th>Option</th><th class="num">Cost</th><th>Note</th></tr></thead>
+      <tbody>
+        <tr><td>A</td><td class="num">1,200</td><td>baseline</td></tr>
+        <tr><td>B</td><td class="num">1,850</td><td>faster, pricier</td></tr>
+      </tbody>
+    </table>
+  </div>
+</div>
+<script>
+  // The shared theme-cycle core. Hand-edit ONLY here (between the praxis:theme markers);
+  // consumers carry a stamped copy — scripts/sync-shared.mjs.
+  // praxis:theme:start
+  // Cycles auto -> light -> dark, stamping data-theme on <html> so the CSS token overrides win
+  // over the OS preference. No storage, no external calls. State rides on the button
+  // (dataset.mode) so any page can bind its own button.
+  function praxisCycleTheme(btn){
+    const order=["auto","light","dark"], label={auto:"◐ auto",light:"☀ light",dark:"☾ dark"};
+    const next=order[(order.indexOf(btn.dataset.mode||"auto")+1)%order.length];
+    if(next==="auto") document.documentElement.removeAttribute("data-theme");
+    else document.documentElement.setAttribute("data-theme",next);
+    btn.dataset.mode=next; btn.textContent=label[next]; return next;
+  }
+  // praxis:theme:end
+  document.getElementById('themeToggle').addEventListener('click',(e)=>praxisCycleTheme(e.currentTarget));
+</script>
+</body>
+</html>

package/spec-bridge/lib/installer.mjs

@@ -0,0 +1,52 @@
+// installer.mjs — the shared "plant a project" helpers used by each plugin's start skill.
+//
+// A plugin has no always-on context slot, so it installs a project CLAUDE.md + scaffolding.
+// These helpers make that dotfile-safe, idempotent, and honest (verify on disk, never clobber
+// what the user has grown). Zero-dependency.
+
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Recursively copy `src` → `dest`. Uses node:fs cp, which copies dotfiles (e.g. `.template/`)
+ * — the copy helpers that silently drop `.`-prefixed names are exactly what this avoids.
+ * `overwrite:false` leaves an existing dest untouched.
+ */
+export function copyDir(src, dest, { overwrite = true } = {}) {
+  cpSync(src, dest, { recursive: true, force: overwrite, errorOnExist: false });
+}
+
+/** Copy a single file, creating parent dirs. Returns false if it existed and overwrite is off. */
+export function copyFile(src, dest, { overwrite = true } = {}) {
+  if (!overwrite && existsSync(dest)) return false;
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest, { force: true });
+  return true;
+}
+
+/**
+ * Ensure `.gitignore` in `root` contains `entry` (e.g. `.handoff/`), creating the file if
+ * absent and preserving existing lines. Idempotent — returns true only if it added the line.
+ */
+export function ensureGitignore(root, entry) {
+  const p = join(root, ".gitignore");
+  const want = entry.trim();
+  const existing = existsSync(p) ? readFileSync(p, "utf8") : "";
+  if (existing.split("\n").some((l) => l.trim() === want)) return false;
+  const prefix = existing === "" ? "" : existing.replace(/\n*$/, "\n");
+  writeFileSync(p, prefix + want + "\n");
+  return true;
+}
+
+/** Which of `relPaths` (relative to `root`) are missing on disk. Empty = all present. */
+export function verifyPresent(root, relPaths) {
+  return relPaths.filter((r) => !existsSync(join(root, r)));
+}
+
+/**
+ * Decide install mode from the project root: `fresh` if none of the `markers` exist yet,
+ * else `update`. Lets a start skill branch between a clean install and an idempotent migrate.
+ */
+export function installMode(root, markers) {
+  return markers.some((m) => existsSync(join(root, m))) ? "update" : "fresh";
+}

package/spec-bridge/lib/lifecycle.mjs

@@ -0,0 +1,67 @@
+// lifecycle.mjs — the "a status cannot exceed the artifacts that prove it" engine.
+//
+// Generalized from educate's progress.mjs. A plugin declares an ordered set of states, a map
+// of artifact keys → filenames, and which artifacts each state requires. The engine derives
+// the artifact map from disk and flags any item whose declared status outranks its evidence.
+//
+// Vocabulary stays per-plugin (educate: scaffolded…done; research: branch→analyzed→rendered);
+// only the mechanism is shared.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Derive { key: bool } for each artifact by checking its filename on disk in `dir`. */
+export function computeArtifacts(dir, artifactFiles) {
+  const out = {};
+  for (const [key, file] of Object.entries(artifactFiles)) out[key] = existsSync(join(dir, file));
+  return out;
+}
+
+/**
+ * Build a lifecycle checker.
+ *   states:    ordered array of status names (index = rank)
+ *   artifacts: { key: filename }
+ *   requires:  { state: [artifactKey, …] } — artifacts that must exist on disk once an item
+ *              is at or beyond that state.
+ */
+export function createLifecycle({ states, artifacts, requires = {} }) {
+  const rank = new Map(states.map((s, i) => [s, i]));
+
+  /**
+   * Problems (strings) for an item at `status` living in `dir`. Empty array = consistent.
+   * `extraRequires` lets a caller add dynamically-required artifacts (e.g. a delegated build
+   * adds handoff artifacts) keyed the same way as `requires`.
+   */
+  const check = (dir, status, extraRequires = {}) => {
+    const problems = [];
+    const statusRank = rank.get(status);
+    if (statusRank === undefined) {
+      problems.push(`unknown status ${JSON.stringify(status)} (expected one of ${states.join(", ")})`);
+      return problems;
+    }
+    const present = computeArtifacts(dir, artifacts);
+    const merged = { ...requires };
+    for (const [state, keys] of Object.entries(extraRequires)) {
+      merged[state] = [...(merged[state] || []), ...keys];
+    }
+    // Collapse all in-force requirements to the earliest state demanding each artifact key,
+    // so a key required by several states is reported at most once.
+    const requiredBy = new Map(); // key -> state name (lowest rank in force)
+    for (const [state, keys] of Object.entries(merged)) {
+      const r = rank.get(state);
+      if (r === undefined || r > statusRank) continue; // requirement not yet in force
+      for (const key of keys) {
+        const prev = requiredBy.get(key);
+        if (prev === undefined || r < rank.get(prev)) requiredBy.set(key, state);
+      }
+    }
+    for (const [key, state] of requiredBy) {
+      if (!present[key]) {
+        problems.push(`status=${status} implies '${state}' but required artifact '${key}' (${artifacts[key] || key}) is missing on disk`);
+      }
+    }
+    return problems;
+  };
+
+  return { states, artifacts, rank, compute: (dir) => computeArtifacts(dir, artifacts), check };
+}

package/spec-bridge/lib/markdown.mjs

@@ -0,0 +1,81 @@
+// markdown.mjs — the small slice of Markdown/YAML/wikilink parsing the gates need.
+//
+// Ported from the research gates' Python (verify_branch/verify_analysis). Deliberately
+// minimal: inline `key: value` and inline `[key]` arrays in frontmatter, code-span
+// stripping, and Obsidian `[[wikilink]]` extraction. Zero-dependency.
+
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`]*`/g;
+const LINK_RE = /\[\[([^\]]+)\]\]/g;
+
+const unquote = (s) => s.replace(/^["']|["']$/g, "");
+
+/** Remove fenced and inline code so links inside code spans are ignored. */
+export function stripCode(text) {
+  return (text || "").replace(FENCE_RE, "").replace(INLINE_CODE_RE, "");
+}
+
+/**
+ * Parse a leading `---` YAML frontmatter block into a flat object, or null if the
+ * file has no block (i.e. it is not a vault note). Values that look like `[a, b]`
+ * become arrays; everything else is an unquoted string. `type` is lowercased.
+ */
+export function parseFrontmatter(text) {
+  if (!text) return null;
+  const t = text.replace(/^/, "").replace(/^\s+/, "");
+  if (!t.startsWith("---")) return null;
+  const m = /^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/.exec(t);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const kv = /^([A-Za-z0-9_]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const key = kv[1].toLowerCase();
+    const val = kv[2].trim();
+    if (val.startsWith("[") && val.endsWith("]")) {
+      fm[key] = val.slice(1, -1).split(",").map((s) => unquote(s.trim())).filter(Boolean);
+    } else {
+      fm[key] = unquote(val);
+    }
+  }
+  if (typeof fm.type === "string") fm.type = fm.type.toLowerCase();
+  return fm;
+}
+
+/** Reduce a raw wikilink body to its target note name (drop `|alias`, `#head`, `^block`). */
+export function linkTarget(raw) {
+  return raw.split("|")[0].split("#")[0].split("^")[0].trim();
+}
+
+/** Every wikilink target in `text`, ignoring links inside code spans. */
+export function extractWikilinks(text) {
+  const stripped = stripCode(text);
+  const out = [];
+  let m;
+  LINK_RE.lastIndex = 0;
+  while ((m = LINK_RE.exec(stripped)) !== null) out.push(linkTarget(m[1]));
+  return out;
+}
+
+/** The set of names a note answers to: its filename stem, title, and aliases (lowercased). */
+export function namesFor(basenameNoExt, fm) {
+  const names = new Set([basenameNoExt.toLowerCase()]);
+  if (fm) {
+    if (fm.title) names.add(String(fm.title).toLowerCase());
+    for (const a of fm.aliases || []) names.add(String(a).toLowerCase());
+  }
+  return names;
+}
+
+/**
+ * Partition wikilink targets into those that resolve against `knownNames` (a Set of
+ * lowercased names) and those that do not (cross-branch or broken).
+ */
+export function resolveLinks(targets, knownNames) {
+  const resolved = [], unresolved = [];
+  for (const t of targets) {
+    if (!t) continue;
+    (knownNames.has(t.toLowerCase()) ? resolved : unresolved).push(t);
+  }
+  return { resolved, unresolved };
+}

package/spec-bridge/lib/project-root.mjs

@@ -0,0 +1,52 @@
+// project-root.mjs — locate a project root by walking the filesystem.
+//
+// Two shapes, because the suite has two placement models:
+//   - educate lives in a favored home folder, marked by a child (e.g. `topics/`). Walk UP.
+//   - research is drop-anywhere; a tree may contain several vaults. Find roots DOWN.
+//
+// Zero-dependency. Marker functions decide what "a root" means for each plugin.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve, dirname, parse } from "node:path";
+
+/** A marker function: presence of a child file/dir named `name`. */
+export function hasChild(name) {
+  return (dir) => existsSync(join(dir, name));
+}
+
+/**
+ * Walk up from `startDir` until `markerFn(dir)` is truthy. Returns the matching
+ * directory (absolute) or null if the filesystem root is reached without a match.
+ */
+export function findRootUpwards(startDir, markerFn) {
+  let dir = resolve(startDir);
+  const { root: fsRoot } = parse(dir);
+  for (;;) {
+    if (markerFn(dir)) return dir;
+    if (dir === fsRoot) return null;
+    dir = dirname(dir);
+  }
+}
+
+const defaultSkip = (name) => name.startsWith(".") || name === "node_modules";
+
+/**
+ * Find every directory at or under `startDir` for which `markerFn` is truthy.
+ * Does not descend into a matched root (a vault owns its subtree) or into skipped
+ * dirs (hidden / node_modules by default). Bounded by `maxDepth`.
+ */
+export function findRootsDownwards(startDir, markerFn, { skip = defaultSkip, maxDepth = 8 } = {}) {
+  const roots = [];
+  const walk = (dir, depth) => {
+    if (markerFn(dir)) { roots.push(dir); return; } // matched → don't descend
+    if (depth >= maxDepth) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory() || skip(e.name)) continue;
+      walk(join(dir, e.name), depth + 1);
+    }
+  };
+  walk(resolve(startDir), 0);
+  return roots;
+}

package/spec-bridge/lib/selfcontained.mjs

@@ -0,0 +1,37 @@
+// selfcontained.mjs — verify a rendered HTML page is self-contained and CSP-safe.
+//
+// Ported from research's verify_artifact.py. The Artifact host enforces a strict CSP that
+// blocks every external host, so a page that loads a remote script/font/style/image silently
+// breaks. Both educate's deck.html and research's *-briefing.html are checked with this.
+//
+// Returns { ok, fails: string[], warns: string[] } — no process exit here; callers decide.
+
+const EXT = "https?://";
+const CHECKS = [
+  [new RegExp(`<script[^>]+\\bsrc\\s*=\\s*['"]?${EXT}`, "i"), "external <script src>"],
+  [new RegExp(`<link[^>]+\\bhref\\s*=\\s*['"]?${EXT}`, "i"), "external <link href> (stylesheet/font)"],
+  [new RegExp(`<(?:img|source|image)[^>]+\\bsrc\\s*=\\s*['"]?${EXT}`, "i"), "external image src"],
+  [new RegExp(`<[^>]+\\bsrcset\\s*=\\s*['"][^'"]*${EXT}`, "i"), "external srcset"],
+  [new RegExp(`url\\(\\s*['"]?${EXT}`, "i"), "external CSS url()"],
+  [new RegExp(`@import\\s+(?:url\\()?\\s*['"]?${EXT}`, "i"), "external @import"],
+  [new RegExp(`\\bfetch\\s*\\(\\s*['"]${EXT}`, "i"), "runtime fetch() to external host"],
+  [new RegExp(`\\.open\\s*\\(\\s*['"][A-Z]+['"]\\s*,\\s*['"]${EXT}`, "i"), "XHR to external host"],
+];
+
+/** Check an HTML string. `substantialBytes` is the size above which a data table is expected. */
+export function checkHtml(html, { substantialBytes = 6000 } = {}) {
+  const fails = [], warns = [];
+  if (!/<title>\s*\S/i.test(html)) fails.push("no <title> — the artifact needs a name");
+  for (const [rx, label] of CHECKS) {
+    if (rx.test(html)) {
+      fails.push(`loads a resource from an external host: ${label} — the Artifact CSP blocks this; inline it or embed as a data: URI`);
+    }
+  }
+  if (!/prefers-color-scheme/i.test(html)) {
+    warns.push("no @media (prefers-color-scheme) — page may not adapt to dark/light themes");
+  }
+  if (html.length > substantialBytes && !/<table/i.test(html)) {
+    warns.push("no <table> found — consider a data table so the figures are auditable");
+  }
+  return { ok: fails.length === 0, fails, warns };
+}