@praxisflux/gates 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Stern
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# Consuming praxis gates from another repo
+
+praxis's gates — "status can't exceed proven artifacts" — are enforceable in repos that don't
+carry praxis itself. There are two enforcement points, deliberately split the same way praxis
+splits them for its own development:
+
+- **Locally / interactively**: the installed plugins' Stop hooks run the gates as you work.
+  These float with plugin updates and are advisory.
+- **In CI**: the composite GitHub Action runs the same gates at a **pinned release**. CI is
+  authoritative. Pin drift between local and CI is fine by design.
+
+## The action
+
+```yaml
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0        # wiki-freshness resolves pins through git history
+      - uses: evanstern/praxis@v0.5.0
+        with:
+          gates: spec-bridge, wiki-freshness
+```
+
+The action runs the gates via `npx @praxisflux/gates@<version>` — the npm package carved from
+the same tree, pinned in lockstep with the tag you chose, and guaranteed live before the tag
+exists (release order: npm publish, then tag). No install step, no dependencies (the gates
+are zero-dependency Node, and every runner ships node + npm). Upgrade by bumping the tag;
+Dependabot's `github-actions` ecosystem automates that.
+
+### Inputs
+
+| input        | default       | meaning |
+|--------------|---------------|---------|
+| `gates`      | *(required)*  | Comma-separated: `spec-bridge`, `wiki-freshness`, `course`. An unknown name fails the build — gates never skip silently. |
+| `path`       | `.`           | Repository root to check, relative to the workspace. |
+| `wiki-dir`   | `docs/wiki`   | Grounded-corpus directory for `wiki-freshness`. |
+| `course-dir` | `docs/course` | Built course directory for the `course` gate. |
+
+### The gates
+
+- **`spec-bridge`** — every Backlog task linked to a Spec Kit spec dir carries a status its
+  spec artifacts prove (needs a `backlog/` dir; passes trivially with zero linked tasks).
+- **`wiki-freshness`** — every `docs/wiki` note is fresh against its `verified_against` pin
+  (needs full git history: `fetch-depth: 0`; a shallow clone fails with exactly that fix).
+- **`course`** — a built codebase-to-course course passes its output gate (self-contained,
+  quizzes/translations per module, current chrome stamp).
+
+## The npm package
+
+The same surface ships on npm as **`@praxisflux/gates`** (published with provenance by the
+release pipeline, version lockstep with the marketplace release), so non-GitHub CI and
+one-off local runs need no praxis checkout:
+
+```sh
+npx @praxisflux/gates --gates spec-bridge,wiki-freshness --path /path/to/repo
+```
+
+The package's bin (`praxis-gates`) is `scripts/run-gates.mjs` itself, carved out by
+`scripts/build-npm.mjs` with the chassis and gate modules alongside — same flags, same exit
+codes, same failure lines.
+
+## The contract
+
+Gate names, inputs, and exit codes (0 all pass · 1 any gate failed · 2 usage error) are
+praxis's versioned consumer interface, released and semver-bumped like everything else
+(`docs/releasing.md`); each failure line names its fix. You can also invoke the runner
+directly from any praxis checkout:
+
+```sh
+node scripts/run-gates.mjs --gates spec-bridge,wiki-freshness --path /path/to/repo
+```

package/codebase-to-course/gates/cli.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// cli.mjs — command-line entry to the codebase-to-course gates.
+//   node cli.mjs course <course-dir>
+import { validateCourse } from "./course.mjs";
+
+const [cmd, courseDir] = process.argv.slice(2);
+if (cmd !== "course" || !courseDir) {
+  console.error("usage: cli.mjs course <course-dir>");
+  process.exit(2);
+}
+
+const r = validateCourse(courseDir);
+for (const w of r.warns) console.log(`warn: ${w}`);
+if (r.fails.length) {
+  console.log(`\nGATE FAILED (${r.fails.length} issue(s)):`);
+  for (const f of r.fails) console.log(`  - ${f}`);
+  process.exit(1);
+}
+console.log(`OK: course gate passed — ${r.modules} module(s), self-contained, all mandatory elements present.`);
+process.exit(0);

package/codebase-to-course/gates/course.mjs

@@ -0,0 +1,58 @@
+// course.mjs — read-only output gate for a built codebase-to-course course (SKILL.md Phase 4).
+//
+// Checks the assembled index.html: it exists, is self-contained (lib/selfcontained.mjs;
+// Google Fonts is the ONE allowed external host), nav dots match module count, every module
+// carries >=1 quiz and >=1 code translation block, the course as a whole has >=1 group
+// chat and >=1 flow animation, every translation block honors the pairing + bracket-balance
+// contracts, and the vendored chrome carries the current version stamp.
+// Never writes to disk (gates/ contract).
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { checkHtml } from "../lib/selfcontained.mjs";
+import { checkTranslationBlocks, checkChrome } from "../skills/codebase-to-course/references/validate.mjs";
+
+const GOOGLE_FONTS = /https?:\/\/(?:fonts\.googleapis\.com|fonts\.gstatic\.com)[^'")\s>]*/gi;
+// Any of these container classes counts as a quiz (multiple-choice, drag-and-drop,
+// spot-the-bug, scenario — per SKILL.md "any quiz type counts").
+const QUIZ_CLASSES = ["quiz-container", "dnd-container", "bug-challenge", "scenario-block"];
+
+const count = (html, marker) => html.split(marker).length - 1;
+const hasAny = (html, classes) => classes.some((c) => html.includes(`class="${c}`));
+
+/** Gate a built course directory. Returns { ok, fails, warns, modules }. */
+export function validateCourse(courseDir) {
+  const fails = [], warns = [];
+  const indexPath = join(courseDir, "index.html");
+  if (!existsSync(indexPath)) {
+    return { ok: false, fails: [`no index.html in ${courseDir} — run build.sh to assemble the course`], warns, modules: 0 };
+  }
+  const html = readFileSync(indexPath, "utf8");
+
+  // Self-contained, with Google Fonts masked out first — it is the one allowed external.
+  const sc = checkHtml(html.replaceAll(GOOGLE_FONTS, "allowed-google-fonts"));
+  fails.push(...sc.fails); // sc.warns are artifact-page guidance (data table etc.) — not course concerns
+
+  const moduleChunks = html.split(/<section[^>]+class="module[\s"]/).slice(1);
+  const modules = moduleChunks.length;
+  const dots = count(html, 'class="nav-dot"');
+  if (modules === 0) fails.push('no <section class="module"> found — the course has no modules');
+  if (dots !== modules) fails.push(`nav dots (${dots}) != modules (${modules}) — fix NAV_DOTS in _base.html and rebuild`);
+
+  moduleChunks.forEach((chunk, i) => {
+    if (!hasAny(chunk, QUIZ_CLASSES)) fails.push(`module ${i + 1} has no quiz (need one of: ${QUIZ_CLASSES.join(", ")})`);
+    if (!chunk.includes('class="translation-block')) fails.push(`module ${i + 1} has no code translation block (.translation-block)`);
+  });
+
+  if (!html.includes('class="chat-window')) fails.push("course has no group chat animation (.chat-window) — at least one is mandatory");
+  if (!html.includes('class="flow-animation')) fails.push("course has no flow animation (.flow-animation) — at least one is mandatory");
+
+  // Translation-block contracts (same checks build.sh runs pre-assembly via the
+  // course's copied validate.mjs): 1:1 .tl/.code-line pairing + bracket balance.
+  fails.push(...checkTranslationBlocks(html, "index.html").fails);
+
+  // Vendored chrome must match the plugin's generation — unstamped (v1) or
+  // mixed-version chrome is the fossilization this gate exists to catch.
+  fails.push(...checkChrome(courseDir));
+
+  return { ok: fails.length === 0, fails, warns, modules };
+}

package/codebase-to-course/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/codebase-to-course/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/codebase-to-course/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/codebase-to-course/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/codebase-to-course/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/codebase-to-course/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/codebase-to-course/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/codebase-to-course/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 };
+}