@praxisflux/gates 0.5.0

package/codebase-to-course/lib/toolkit/tooltip.md

@@ -0,0 +1,83 @@
+# Jargon glossary tooltip
+
+Gloss every technical term where it appears, so the reader never has to leave the page (or
+ask) to decode jargon. The definition rides a `data-tip` attribute; a popover shows it on
+hover (desktop) or tap (touch). This is the single most valuable accessibility feature for
+non-technical audiences — codebase-to-course's content rules call it "No Term Left Behind."
+
+**Graceful degradation:** if this module isn't available, gloss terms in parentheses on
+first use — `the manifest (the file that declares what the extension may do)` — and move on.
+
+## The contract
+
+Any element — HTML *or* SVG — may carry a `data-tip` attribute with a 1–2 sentence,
+everyday-language definition:
+
+```html
+<span data-tip="A service worker is a background script that runs independently of the
+page — a behind-the-scenes assistant that's on even when you're not looking.">service
+worker</span>
+```
+
+- Give the reader a **visible affordance** so glossed terms are discoverable: a dashed
+  underline, or a small `?` badge (educate's decks use the badge — see the deck template's
+  sample slide).
+- Keep definitions to 1–2 sentences, everyday language; a metaphor helps.
+- Gloss on **first use per screen/slide**, not every repetition.
+
+## The snippet
+
+Self-contained, and written against the **shared token names** (`--ink`, `--bg`) so it
+inherits the consuming plugin's palette in both light and dark themes (the bubble is
+inverted-contrast: dark-on-light pages get a dark bubble and vice versa). Popover text size
+follows `--tip-size` (default `1rem`) — decks set it larger. The popover is appended to
+`document.body` with `position: fixed`, so it is **never clipped** by an ancestor's
+`overflow: hidden`, and it hides when printing.
+
+Consumers embed the marked regions verbatim; `scripts/sync-shared.mjs` re-stamps them (drift
+fails the test suite). Hand-edit only here.
+
+```css
+/* praxis:tooltip-css:start */
+[data-tip]{cursor:help}
+.tip-pop{position:fixed;z-index:1000;max-width:min(420px,80vw);background:var(--ink);color:var(--bg);
+  font-size:var(--tip-size,1rem);line-height:1.4;padding:.65em .9em;border-radius:10px;
+  pointer-events:none;box-shadow:0 8px 24px rgba(0,0,0,.28);opacity:0;transform:translateY(4px);
+  transition:opacity .12s ease,transform .12s ease}
+.tip-pop.show{opacity:1;transform:translateY(0)}
+@media print{ .tip-pop{display:none} }
+/* praxis:tooltip-css:end */
+```
+
+```js
+// praxis:tooltip-js:start
+// One shared popover: follows the cursor on hover, toggles on click/tap (touch), clamps to
+// the viewport, and closes on tap-away. Works for HTML and SVG [data-tip] elements alike.
+(function(){
+  const pop=document.createElement('div'); pop.className='tip-pop'; document.body.appendChild(pop);
+  let shownFor=null;
+  const place=(x,y)=>{ const pad=14, r=pop.getBoundingClientRect();
+    let px=x+pad, py=y+pad;
+    if(px+r.width>innerWidth-8) px=Math.max(8,x-r.width-pad);
+    if(py+r.height>innerHeight-8) py=Math.max(8,y-r.height-pad);
+    pop.style.left=px+'px'; pop.style.top=py+'px'; };
+  const show=(t,x,y)=>{ pop.textContent=t.getAttribute('data-tip'); pop.classList.add('show'); shownFor=t; place(x,y); };
+  const hide=()=>{ pop.classList.remove('show'); shownFor=null; };
+  document.addEventListener('mouseover',e=>{ const t=e.target.closest&&e.target.closest('[data-tip]'); if(t) show(t,e.clientX,e.clientY); });
+  document.addEventListener('mousemove',e=>{ if(shownFor) place(e.clientX,e.clientY); });
+  document.addEventListener('mouseout',e=>{ const t=e.target.closest&&e.target.closest('[data-tip]'); if(t && !t.contains(e.relatedTarget)) hide(); });
+  document.addEventListener('click',e=>{ const t=e.target.closest&&e.target.closest('[data-tip]');
+    if(t){ e.stopPropagation(); (shownFor===t)?hide():show(t,e.clientX,e.clientY); } else hide(); });
+})();
+// praxis:tooltip-js:end
+```
+
+## Where each plugin gets it
+
+- **educate decks** — the deck template carries the stamped regions; nothing to author.
+- **research briefings** — copy both regions into the page (alongside the base.html blocks).
+- **codebase-to-course pages** — courses do NOT use this snippet: the prebuilt assets
+  (`references/styles.css` + `references/main.js`, copied verbatim into every course) ship
+  the same pattern as a course-native engine with the `.term` + `data-definition` contract
+  and a dashed-underline affordance. Author course HTML against that contract and never
+  inline tooltip CSS/JS there (see the skill's `interactive-elements.md`).

package/codebase-to-course/skills/codebase-to-course/references/validate.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/* codebase-to-course chrome v2 — inline translation engine (comments-on-top)
+ *
+ * validate.mjs — translation-block validator.
+ * Copy this file verbatim into the course output directory; build.sh runs it
+ * before assembling index.html. It is self-contained (Node stdlib only).
+ *
+ * Two contracts are enforced on every .translation-block:
+ *
+ *  1. PAIRING — exactly one .tl note per .code-line. The inline engine pairs
+ *     them positionally, so one missing note silently misaligns every note
+ *     after it. A count mismatch is always an authoring bug.
+ *
+ *  2. BALANCE — the block's code, read as text (tags stripped, HTML entities
+ *     decoded, string literals and comments removed), must have balanced
+ *     ()/[]/{} brackets. A code excerpt that stops mid-structure reads as
+ *     broken to anyone who knows code. Trim excerpts from WITHIN instead:
+ *     replace the skipped middle with a `// …` comment code-line (with its
+ *     own paired .tl note) and keep every closing bracket.
+ *
+ * Usage:
+ *   node validate.mjs modules/*.html          check; exit 1 on violations
+ *   node validate.mjs --fix modules/*.html    also auto-close fixable blocks
+ *
+ * --fix handles the mechanical half only: when a block's sole problem is
+ * unclosed brackets, it appends an elision comment code-line plus a closer
+ * code-line (and two paired .tl notes) so pairing and balance both hold.
+ * Stray closers, mismatched pairs, and unterminated strings still need a
+ * human/author pass — the excerpt itself is cut wrong.
+ *
+ * Opt-out: <div class="translation-block" data-validate="off"> skips a block.
+ * Reserve it for deliberately fragmentary pseudo-code.
+ */
+import { readFileSync, writeFileSync, existsSync, realpathSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The chrome generation this validator ships with. Bump ONLY when the
+ *  rendering contract changes (what authored markup means on screen), and
+ *  bump the stamp in every chrome file together — see docs/skill-patterns.md
+ *  "Versioned course chrome". v1 is the retired side-by-side renderer, which
+ *  predates stamping (no header = v1). */
+export const CHROME_VERSION = 2;
+
+const OPEN = { "(": ")", "[": "]", "{": "}" };
+const CLOSE = { ")": "(", "]": "[", "}": "{" };
+
+/* ── HTML micro-parsing (no dependencies) ─────────────────────── */
+
+function hasClassToken(attrs, token) {
+  const m = /class\s*=\s*"([^"]*)"/.exec(attrs) || /class\s*=\s*'([^']*)'/.exec(attrs);
+  return !!m && m[1].split(/\s+/).includes(token);
+}
+
+function stripTags(html) {
+  return html.replace(/<[^>]*>/g, "");
+}
+
+function decodeEntities(s) {
+  return s
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(+n))
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&");
+}
+
+function lineOf(html, index) {
+  let n = 1;
+  for (let i = 0; i < index; i++) if (html[i] === "\n") n++;
+  return n;
+}
+
+/** All elements of `tagName` whose class list contains `classToken`,
+ *  with nesting of the same tag handled. Returns
+ *  { start, end, innerStart, innerEnd, inner } (end = after the close tag). */
+function findElements(html, tagName, classToken) {
+  const out = [];
+  const re = /<(\/?)([a-zA-Z][\w-]*)([^>]*)>/g;
+  let m, open = null, depth = 0;
+  while ((m = re.exec(html))) {
+    const [, slash, name, attrs] = m;
+    if (name.toLowerCase() !== tagName) continue;
+    const selfClosing = /\/\s*$/.test(attrs);
+    if (!slash) {
+      if (open === null) {
+        if (hasClassToken(attrs, classToken)) {
+          if (selfClosing) out.push({ start: m.index, end: re.lastIndex, innerStart: re.lastIndex, innerEnd: re.lastIndex, inner: "" });
+          else { open = { start: m.index, innerStart: re.lastIndex }; depth = 1; }
+        }
+      } else if (!selfClosing) depth++;
+    } else if (open !== null && --depth === 0) {
+      out.push({ start: open.start, end: re.lastIndex, innerStart: open.innerStart, innerEnd: m.index, inner: html.slice(open.innerStart, m.index) });
+      open = null;
+    }
+  }
+  return out;
+}
+
+/** Open tags (any element) whose class list contains `classToken` — exact
+ *  token match, so `tl` does not match `tl-inline`. */
+function openTagsWithClass(html, classToken) {
+  const out = [];
+  const re = /<([a-zA-Z][\w-]*)([^>]*)>/g;
+  let m;
+  while ((m = re.exec(html))) if (hasClassToken(m[2], classToken)) out.push({ start: m.index, end: re.lastIndex });
+  return out;
+}
+
+/** Each .translation-block open tag, its attrs, and its chunk extent (to the
+ *  next block or end of input — blocks never nest, and the tracked classes
+ *  only occur inside blocks, so chunk counting is exact). */
+function findBlocks(html) {
+  const opens = [];
+  const re = /<div([^>]*)>/g;
+  let m;
+  while ((m = re.exec(html))) if (hasClassToken(m[1], "translation-block")) opens.push({ start: m.index, attrs: m[1] });
+  return opens.map((o, i) => ({ ...o, end: i + 1 < opens.length ? opens[i + 1].start : html.length, n: i + 1 }));
+}
+
+/* ── bracket balance over code text ───────────────────────────── */
+
+/** Scan decoded code text with a small language-agnostic lexer: skips
+ *  '…'/"…" strings (single-line), `…` template literals (multi-line),
+ *  //-line, ⧸*…*⧸-block, and whitespace-then-# line comments, then tracks
+ *  bracket depth. Returns { errs, unclosed, fixable }. */
+export function scanBalance(text) {
+  const errs = [];
+  const stack = [];
+  let line = 1, state = "code", hard = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i], next = text[i + 1];
+    if (c === "\n") {
+      line++;
+      // sq/dq strings and line comments end at the newline (a string left
+      // open by a bad cut must not swallow the rest of the block)
+      if (state === "sq" || state === "dq" || state === "line") state = "code";
+      continue;
+    }
+    switch (state) {
+      case "sq": if (c === "\\") i++; else if (c === "'") state = "code"; break;
+      case "dq": if (c === "\\") i++; else if (c === '"') state = "code"; break;
+      case "bt": if (c === "\\") i++; else if (c === "`") state = "code"; break;
+      case "block": if (c === "*" && next === "/") { i++; state = "code"; } break;
+      case "line": break;
+      default:
+        if (c === "'") state = "sq";
+        else if (c === '"') state = "dq";
+        else if (c === "`") state = "bt";
+        else if (c === "/" && next === "/") { state = "line"; i++; }
+        else if (c === "/" && next === "*") { state = "block"; i++; }
+        // `#` comments only when followed by whitespace or `!` (shebang) —
+        // keeps CSS hex colors, #include, #region reading as code
+        else if (c === "#" && (next === undefined || next === " " || next === "\t" || next === "!")) state = "line";
+        else if (OPEN[c]) stack.push({ ch: c, line });
+        else if (CLOSE[c]) {
+          const top = stack.pop();
+          if (!top) { errs.push(`stray '${c}' on code line ${line} — nothing is open for it to close`); hard = true; }
+          else if (OPEN[top.ch] !== c) { errs.push(`'${top.ch}' opened on code line ${top.line} is closed by '${c}' on line ${line}`); hard = true; }
+        }
+    }
+  }
+  if (state === "bt") { errs.push("unterminated template literal — the excerpt ends mid-string"); hard = true; }
+  for (const o of stack) errs.push(`'${o.ch}' opened on code line ${o.line} is never closed`);
+  return { errs, unclosed: stack.map((o) => o.ch), fixable: !hard && stack.length > 0 };
+}
+
+/* ── the check ────────────────────────────────────────────────── */
+
+/** Validate every translation block in an HTML string (a module file or a
+ *  built index.html). Returns { fails, blocks, details }; `fails` is
+ *  human-readable, `details` feeds --fix. */
+export function checkTranslationBlocks(html, source = "html") {
+  const fails = [];
+  const details = [];
+  const blocks = findBlocks(html);
+  for (const b of blocks) {
+    const id = `${source}: translation block ${b.n} (line ${lineOf(html, b.start)})`;
+    if (/data-validate\s*=\s*["']off["']/.test(b.attrs)) { details.push({ ...b, skipped: true }); continue; }
+    const chunk = html.slice(b.start, b.end);
+    const codeEls = findElements(chunk, "span", "code-line");
+    const tls = openTagsWithClass(chunk, "tl");
+    if (!codeEls.length) fails.push(`${id}: no .code-line spans found`);
+    if (codeEls.length !== tls.length)
+      fails.push(`${id}: ${codeEls.length} .code-line vs ${tls.length} .tl — the inline engine pairs positionally, so every note after the first gap sits on the wrong code line. Author exactly one .tl per .code-line, in order.`);
+    const codeText = codeEls.map((e) => decodeEntities(stripTags(e.inner))).join("\n");
+    const bal = scanBalance(codeText);
+    for (const e of bal.errs) fails.push(`${id}: ${e}`);
+    details.push({ ...b, codeEls, tls, bal });
+  }
+  return { fails, blocks: blocks.length, details };
+}
+
+/* ── --fix: mechanical auto-close ─────────────────────────────── */
+
+const ELIDE_NOTE_1 = "The middle of this code is trimmed for the lesson — the shape above is what matters.";
+const ELIDE_NOTE_2 = "…and everything that was opened gets closed.";
+
+/** Auto-close every fixable block in an HTML string. Returns
+ *  { html, fixed, unfixable } — `unfixable` lists block numbers whose
+ *  problems need an author (stray/mismatched closers, unterminated strings,
+ *  pairing gaps in the middle of the block). */
+export function fixTranslationBlocks(html, source = "html") {
+  const { details } = checkTranslationBlocks(html, source);
+  let fixed = 0;
+  const unfixable = [];
+  // last-to-first so earlier offsets stay valid across insertions
+  for (const b of [...details].reverse()) {
+    if (b.skipped || !b.bal || !b.bal.errs.length) continue;
+    if (!b.bal.fixable) { unfixable.push(b.n); continue; }
+    const chunk = html.slice(b.start, b.end);
+    const lastCode = b.codeEls[b.codeEls.length - 1];
+    const linesDiv = findElements(chunk, "div", "translation-lines")[0];
+    if (!lastCode || !linesDiv) { unfixable.push(b.n); continue; }
+    const closers = b.bal.unclosed.slice().reverse().map((ch) => OPEN[ch]).join("");
+    const codeIns =
+      `\n<span class="code-line"><span class="code-comment">// … rest of this excerpt elided …</span></span>` +
+      `\n<span class="code-line">${closers}</span>`;
+    const noteIns =
+      `  <p class="tl">${ELIDE_NOTE_1}</p>\n` +
+      `      <p class="tl">${ELIDE_NOTE_2}</p>\n    `;
+    const edits = [
+      { at: b.start + linesDiv.innerEnd, text: noteIns },
+      { at: b.start + lastCode.end, text: codeIns },
+    ].sort((a, z) => z.at - a.at);
+    for (const e of edits) html = html.slice(0, e.at) + e.text + html.slice(e.at);
+    fixed++;
+  }
+  return { html, fixed, unfixable };
+}
+
+/* ── chrome version consistency ───────────────────────────────── */
+
+const STAMP = /chrome v(\d+)/;
+
+/** Check that a course dir's vendored chrome matches this validator's
+ *  generation. Unstamped chrome is v1 (pre-inline side-by-side) — the drift
+ *  the stamp exists to catch; mixed stamps mean a partial upgrade. */
+export function checkChrome(courseDir) {
+  const fails = [];
+  for (const f of ["styles.css", "main.js"]) {
+    const p = join(courseDir, f);
+    if (!existsSync(p)) { fails.push(`${f}: missing from ${courseDir}`); continue; }
+    const m = STAMP.exec(readFileSync(p, "utf8").slice(0, 600));
+    if (!m) fails.push(`${f} has no chrome version stamp — that's v1, the retired side-by-side renderer. Upgrade: copy the plugin references/ files over this course dir and rebuild (gotchas.md "Stale Chrome").`);
+    else if (+m[1] !== CHROME_VERSION) fails.push(`${f} is chrome v${m[1]} but this validator is v${CHROME_VERSION} — mixed chrome. Re-copy ALL reference files together, then rebuild.`);
+  }
+  return fails;
+}
+
+/* ── CLI ──────────────────────────────────────────────────────── */
+
+function main() {
+  const args = process.argv.slice(2);
+  const fix = args.includes("--fix");
+  const files = [];
+  let chromeDir = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--fix") continue;
+    else if (args[i] === "--chrome-dir") chromeDir = args[++i];
+    else files.push(args[i]);
+  }
+  if (!files.length && !chromeDir) {
+    console.error("usage: node validate.mjs [--fix] [--chrome-dir <course-dir>] <module.html>...");
+    process.exit(2);
+  }
+  let allFails = chromeDir ? checkChrome(chromeDir) : [];
+  for (const file of files) {
+    let html = readFileSync(file, "utf8");
+    if (fix) {
+      const r = fixTranslationBlocks(html, file);
+      if (r.fixed) {
+        writeFileSync(file, r.html);
+        html = r.html;
+        console.log(`fixed: ${file} — auto-closed ${r.fixed} block(s)`);
+      }
+      for (const n of r.unfixable)
+        console.log(`unfixable: ${file} block ${n} — needs an author pass (see failures below)`);
+    }
+    allFails = allFails.concat(checkTranslationBlocks(html, file).fails);
+  }
+  if (allFails.length) {
+    console.log(`\nTRANSLATION-BLOCK VALIDATION FAILED (${allFails.length} issue(s)):`);
+    for (const f of allFails) console.log(`  - ${f}`);
+    console.log(
+      "\nhint: trim excerpts from WITHIN — replace a skipped middle with a `// …` comment" +
+      "\ncode-line (plus its paired .tl note) and keep every closing bracket. `--fix`" +
+      '\nappends the closers mechanically; data-validate="off" on a block opts it out.'
+    );
+    process.exit(1);
+  }
+  console.log(`OK: translation blocks valid across ${files.length} file(s).`);
+}
+
+// Realpath both sides: import.meta.url is symlink-resolved but argv[1] is as typed, so a
+// naive comparison through a symlinked path silently skips main() — never validating.
+if (process.argv[1] && existsSync(process.argv[1]) &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(resolve(process.argv[1]))) main();

package/grounding-wiki/gates/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// cli.mjs — command-line entry to the grounding-wiki gates.
+//   node cli.mjs freshness <repo-root> [corpus-dir]     (corpus-dir defaults to docs/wiki)
+import { validateFreshness } from "./freshness.mjs";
+
+function report({ fails = [], warns = [], checked = 0 }, okMsg) {
+  for (const w of warns) console.log(`warn: ${w}`);
+  if (fails.length) {
+    console.log(`\nGATE FAILED (${fails.length} issue(s)):`);
+    for (const f of fails) console.log(`  - ${f}`);
+    process.exit(1);
+  }
+  console.log(okMsg.replace("%n", String(checked)));
+  process.exit(0);
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === "freshness") {
+  const [root, corpusDir] = rest;
+  if (!root) { console.error("usage: cli.mjs freshness <repo-root> [corpus-dir]"); process.exit(2); }
+  const r = validateFreshness(root, corpusDir || "docs/wiki");
+  report(r, "OK: %n note(s) fresh against their pinned sources.");
+} else {
+  console.error("usage: cli.mjs freshness <repo-root> [corpus-dir]");
+  process.exit(2);
+}

package/grounding-wiki/gates/freshness.mjs

@@ -0,0 +1,92 @@
+// freshness.mjs — read-only staleness check for a code-grounded corpus (docs/corpus-spec.md).
+//
+// A note is STALE when any path in its `sources:` frontmatter changed after its
+// `verified_against:` pin. Verified with git plumbing against the repo the corpus lives in.
+// Never writes to disk (gates/ contract).
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, isAbsolute, basename } from "node:path";
+import { execFileSync } from "node:child_process";
+import { parseFrontmatter, stripCode, extractWikilinks } from "../lib/markdown.mjs";
+
+function git(repoRoot, args) {
+  return execFileSync("git", args, { cwd: repoRoot, encoding: "utf8" }).trim();
+}
+
+/**
+ * Parse a `sources:` block list from raw frontmatter text. lib/markdown.mjs handles only
+ * inline `[a, b]` arrays; corpus notes use YAML block lists for readability.
+ */
+export function parseSourcesBlock(text) {
+  const m = /^---\s*\n([\s\S]*?)\n---/.exec((text || "").replace(/^/, "").replace(/^\s+/, ""));
+  if (!m) return [];
+  const out = [];
+  let inBlock = false;
+  for (const line of m[1].split("\n")) {
+    if (/^sources:\s*$/.test(line)) { inBlock = true; continue; }
+    if (!inBlock) continue;
+    const item = /^\s+-\s+(.+)$/.exec(line);
+    if (item) { out.push(item[1].trim()); continue; }
+    if (!/^\s/.test(line)) inBlock = false;
+  }
+  return out;
+}
+
+/**
+ * Check every note in a corpus for staleness against the repo's git history.
+ * corpusDir is relative to repoRoot unless absolute. Returns { fails, warns, checked };
+ * fails non-empty ⇒ the corpus is stale (or malformed) and the gate should block.
+ */
+export function validateFreshness(repoRoot, corpusDir = "docs/wiki") {
+  const fails = [];
+  const warns = [];
+  const dir = isAbsolute(corpusDir) ? corpusDir : join(repoRoot, corpusDir);
+
+  if (!existsSync(join(dir, "INDEX.md"))) {
+    return { fails: [`not a corpus: ${join(dir, "INDEX.md")} missing`], warns, checked: 0 };
+  }
+
+  const files = readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "INDEX.md").sort();
+  const names = new Set(files.map((f) => basename(f, ".md")));
+  let checked = 0;
+
+  for (const file of files) {
+    const rel = `${corpusDir}/${file}`;
+    const text = readFileSync(join(dir, file), "utf8");
+    const fm = parseFrontmatter(text);
+    checked++;
+
+    if (!fm) { fails.push(`${rel}: no frontmatter — not a corpus note`); continue; }
+
+    const pin = fm.verified_against;
+    if (!pin) { fails.push(`${rel}: no verified_against pin`); continue; }
+    try {
+      git(repoRoot, ["cat-file", "-e", `${pin}^{commit}`]);
+    } catch {
+      fails.push(`${rel}: pin ${pin} is not a known commit`);
+      continue;
+    }
+
+    const sources = parseSourcesBlock(text);
+    if (sources.length === 0) {
+      warns.push(`${rel}: no sources listed — staleness is unverifiable`);
+    } else {
+      let changed = "";
+      try {
+        changed = git(repoRoot, ["log", "--oneline", `${pin}..HEAD`, "--", ...sources]);
+      } catch (e) {
+        fails.push(`${rel}: git log failed for its sources (${String(e).split("\n")[0]})`);
+        continue;
+      }
+      if (changed) {
+        const lines = changed.split("\n");
+        fails.push(`${rel}: STALE — sources changed since ${pin.slice(0, 12)} (${lines.length} commit(s), e.g. ${lines[0]})`);
+      }
+    }
+
+    for (const link of extractWikilinks(stripCode(text))) {
+      if (!names.has(link)) warns.push(`${rel}: [[${link}]] does not resolve to a sibling note`);
+    }
+  }
+
+  return { fails, warns, checked };
+}

package/grounding-wiki/lib/README.md

@@ -0,0 +1,8 @@
+# lib — the shared Node chassis
+
+Zero-dependency Node modules shared by every plugin, **vendored into each plugin at build time**
+(a shipped `.plugin` is self-contained; `${CLAUDE_PLUGIN_ROOT}/lib/…` resolves at runtime).
+
+Planned modules (**TASK-1.2**): `project-root` · `gate-runner` (Stop-hook harness) · `markdown`
+· `selfcontained` (HTML verifier) · `lifecycle` (status-cannot-exceed-proven-artifacts) ·
+`installer` · `dates` · `template`.

package/grounding-wiki/lib/cli.mjs

@@ -0,0 +1,23 @@
+// cli.mjs — the run-as-CLI guard for dual-use modules (importable library + executable
+// script).
+//
+// The naive `import.meta.url === `file://${process.argv[1]}`` comparison breaks through
+// symlinks: Node resolves import.meta.url to the module's physical path, while argv[1] stays
+// as typed, so a script invoked via a symlinked checkout (~/projects -> Claude/Code) compares
+// unequal and silently runs none of its CLI body — for a gate runner that means exit 0 having
+// checked nothing, the exact silent skip the gates doctrine forbids. Realpath both sides so
+// the comparison is invocation-path-independent.
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** True when the module at `moduleUrl` (pass import.meta.url) is the script Node was asked
+ *  to run, regardless of symlinks on either side. False when imported as a module, or when
+ *  there is no entry script (`node -e`, REPL) or argv[1] is a runner's virtual entry. */
+export function runAsCli(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}

package/grounding-wiki/lib/dates.mjs

@@ -0,0 +1,11 @@
+// dates.mjs — ISO date helpers shared across the suite.
+
+/** Today's date (or `date`'s) as an ISO `YYYY-MM-DD` string. */
+export function today(date = new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+
+/** Rewrite an `updated:` frontmatter line to today's date. No-op if none present. */
+export function bumpUpdated(text, date = new Date()) {
+  return (text || "").replace(/^(updated:\s*).*$/m, `$1${today(date)}`);
+}

package/grounding-wiki/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);
+  }
+}