@praxisflux/gates 0.5.0

package/lib/toolkit/diagrams.md

@@ -0,0 +1,57 @@
+# HTML/CSS diagram idioms
+
+Diagrams that are plain HTML + CSS (boxes, arrows, trees — often with an emoji as the icon)
+inherit the theme tokens, wrap responsively, and never hit SVG's text pitfalls. This is
+codebase-to-course's native diagram idiom, portable to any praxis surface. For hand-drawn
+SVG figures instead, see `svg-diagrams.md`.
+
+**Graceful degradation:** if this module isn't available, a numbered list of steps or an
+indented mono file listing does the job.
+
+## Flow of steps (boxes with arrow separators)
+
+```html
+<style>
+.flow{display:flex;align-items:stretch;gap:0;flex-wrap:wrap}
+.flow .step{flex:1;min-width:9em;background:var(--card);border:1px solid var(--line);
+  border-radius:12px;padding:.8em 1em;text-align:center}
+.flow .step b{display:block;margin-bottom:.25em}
+.flow .arrow{align-self:center;padding:0 .5em;color:var(--muted);font-size:1.4em}
+</style>
+
+<div class="flow">
+  <div class="step">📨 <b>Input</b><span class="muted">the click arrives</span></div>
+  <div class="arrow">→</div>
+  <div class="step">⚙️ <b>Process</b><span class="muted">the server decides</span></div>
+  <div class="arrow">→</div>
+  <div class="step">📬 <b>Output</b><span class="muted">the page updates</span></div>
+</div>
+```
+
+## Annotated file tree
+
+Use instead of paragraphs saying "this folder does X, that folder does Y":
+
+```html
+<style>
+.tree{font-family:var(--mono);background:var(--chip);border:1px solid var(--line);
+  border-radius:12px;padding:1em 1.2em;line-height:1.8;white-space:pre}
+.tree .why{font-family:var(--sans);color:var(--muted);font-style:italic}
+</style>
+
+<div class="tree">src/
+├─ api/        <span class="why">← every route the frontend can call</span>
+├─ models/     <span class="why">← what the data looks like</span>
+└─ jobs/       <span class="why">← work that runs on a schedule</span></div>
+```
+
+Rules: label every box/branch with WHY it matters, not just its name; keep a flow to 3–5
+steps (split longer chains — shared pedagogy: one idea per screen); emoji are icons, pick
+one each, don't decorate.
+
+## In codebase-to-course
+
+Courses get richer, *animated* versions from the prebuilt assets (flow animations, group-chat
+visualizations, interactive architecture diagrams) — author against the contracts in the
+skill's `interactive-elements.md`. These static idioms are the portable variants for decks
+and briefings.

package/lib/toolkit/pedagogy.md

@@ -0,0 +1,39 @@
+# Visual-teaching principles
+
+The shared pedagogy behind every praxis teaching surface — codebase-to-course's course screens,
+educate's deck slides, research's briefing pages. Written once here; each skill keeps only its
+medium-specific rules (and a one-line distillation as fallback) and points at this module.
+
+**Graceful degradation:** if this module isn't available, the one-liner to keep: *one idea per
+screen; show, don't tell; lead with the point; split, don't shrink.*
+
+## The principles
+
+1. **One idea per screen/slide.** Each unit of display teaches exactly one thing. If it feels
+   crammed, the fix is always MORE screens/slides, never smaller type or denser text. A
+   20-slide deck that's effortless beats a 6-slide deck you squint at.
+
+2. **Show, don't tell.** Eyes glaze over text blocks. Prefer a diagram, card row, flow, code
+   translation, or animation to a paragraph — if you're writing a fourth sentence, stop and
+   convert it into a visual. Aim closer to an infographic than a textbook.
+
+3. **Lead with the point.** State the claim/verdict/takeaway first, then justify it. A briefing
+   leads with the analysis's verdict; a deck leads with the lesson's claim; a course screen
+   leads with the concept, not the buildup. Don't make the reader reverse-engineer the answer.
+
+4. **Split, don't shrink.** Never reduce type, tighten spacing, or trim whitespace to make
+   content fit. Cut words, or add another screen/slide. Readability is the budget everything
+   else pays from.
+
+5. **Let visuals breathe.** A figure that matters gets the room it needs — its own slide, a
+   full-width screen block, generous whitespace around it. Alternate big visuals with narrow
+   text to create rhythm; don't wedge a diagram into a corner.
+
+## How each medium applies them
+
+- **Course screens** (codebase-to-course): every screen ≥50% visual, max 2–3 sentences per text
+  block, one "hero visual" per module — see the skill's `content-philosophy.md`.
+- **Deck slides** (educate): large type is non-negotiable; verify nothing clips at 16:9 — see
+  the deck template's header rules.
+- **Briefing pages** (research): verdict first, every figure traces to the analysis — see
+  `artifact-layer.md`.

package/lib/toolkit/quiz-patterns.md

@@ -0,0 +1,65 @@
+# Quiz patterns — test application, not memory
+
+A quiz exists to check whether the learner can *use* what they learned on a new problem, not
+whether they can regurgitate a definition. Originally codebase-to-course's quiz doctrine;
+the design rules are medium-independent.
+
+**Graceful degradation:** if this module isn't available, end the lesson/module with 2–3
+"what would you do?" questions in plain prose and discuss the answers.
+
+## The coverage rule (hard requirement)
+
+A question may only use terms, concepts, components, and scenarios the material has already
+introduced *before* the quiz. Applying knowledge to a brand-new situation is the whole point —
+but every term the question leans on must be 100% guaranteed already taught. A learner should
+never hit a quiz and think "we never talked about this." If a great question needs an
+unintroduced concept, teach it first or cut the question.
+
+## What to quiz (in order of value)
+
+1. **"What would you do?" scenarios** — a new situation, apply what you learned. The gold standard.
+2. **Debugging scenarios** — "X is broken; where would you look first?"
+3. **Architecture decisions** — "would you put this logic here or there — and why?"
+4. **Tracing exercises** — "when a user does X, what path does the data take?"
+
+**Never quiz:** definitions (that's what glossing is for), file-name recall, syntax details,
+or anything answerable by scrolling up and copying.
+
+## Tone
+
+Wrong answers get encouraging explanations that teach something new ("Not quite — here's
+why…"); right answers get brief reinforcement of the principle ("Exactly — this works
+because…"). Never punitive, never score-focused.
+
+## Portable snippet (decks, briefings — zero JS)
+
+`<details>`/`<summary>` gives tap-to-reveal answers with no script, keyboard-accessible,
+token-styled:
+
+```html
+<style>
+.quiz details{border:1px solid var(--line);border-radius:10px;margin:.4em 0;
+  background:var(--chip)}
+.quiz summary{cursor:pointer;padding:.55em .9em;font-weight:600}
+.quiz details p{margin:0;padding:.2em .9em .7em;color:var(--muted)}
+.quiz details.right summary{border-left:4px solid var(--accent2)}
+</style>
+
+<div class="quiz">
+  <p><b>You want to add a "save to favorites" feature. Where does the logic live?</b></p>
+  <details><summary>A. In the browser extension</summary>
+    <p>Not quite — the extension only displays data; it never owns it. Look one hop back.</p></details>
+  <details class="right"><summary>B. In the backend API</summary>
+    <p>Exactly — the API owns the data, so a new feature that stores state starts there.</p></details>
+</div>
+```
+
+Deck usage: one question per slide, reveal by tapping — a natural end-of-lesson slide before
+the takeaways.
+
+## In codebase-to-course
+
+Courses do NOT use this snippet — the prebuilt assets ship graded quiz engines
+(multiple-choice, drag-and-drop, spot-the-bug, scenario) with per-answer explanations; author
+against the contracts in the skill's `interactive-elements.md`. The coverage rule above
+applies everywhere.

package/lib/toolkit/svg-diagrams.md

@@ -0,0 +1,59 @@
+# Inline-SVG diagram rules
+
+Hand-drawn inline SVG is the praxis idiom for explanatory figures (educate decks draw
+diagrams this way; research briefings draw charts as inline SVG). SVG has sharp edges that
+HTML habits walk straight into — these are the hard-won rules, originally from educate's
+deck template.
+
+**Graceful degradation:** if this module isn't available, the two rules to keep: *no
+`<b>`/`<i>` inside SVG `<text>` (use `<tspan>`), and CSS `var(--…)` does not resolve in SVG
+presentation attributes — use literal values.*
+
+## The pitfalls (hard rules)
+
+1. **Never put `<b>` or `<i>` inside an SVG `<text>` element.** HTML formatting tags are
+   invisible-but-broken inside SVG — the text silently fails to render or renders unstyled.
+   Use `<tspan font-weight="700">` / `<tspan font-style="italic">` instead.
+
+2. **CSS `var(--token)` does NOT resolve in SVG presentation attributes** (`fill="var(--accent)"`
+   silently paints black). Use **literal color values** in SVG attributes — and since literals
+   can't follow the theme, pick colors that read on BOTH light and dark backgrounds, or give
+   the figure its own contrasting panel. (`var()` does work in a `style=""` attribute or CSS
+   rule targeting SVG elements — but only for properties CSS controls, and it's easy to get
+   this half-right; literals are the predictable path.)
+
+3. **Size for reflow:** `width:100%; height:auto` on the `<svg>` plus a `viewBox` — never fixed
+   pixel width/height attributes alone, or the figure won't scale with its container.
+
+4. **Accessibility:** `role="img"` and an `aria-label` describing what the diagram shows.
+
+5. **Give the figure room** (shared pedagogy — "let visuals breathe"): a diagram that carries
+   the point gets its own slide / a full-width block, filling most of the available width and
+   height. Don't wedge it beside a paragraph.
+
+## Skeleton — a boxes-and-arrows flow
+
+```html
+<svg viewBox="0 0 800 300" role="img" aria-label="input flows through process to output">
+  <rect x="40" y="110" width="200" height="80" rx="12" fill="#eef0ff" stroke="#4f46e5" stroke-width="2"/>
+  <text x="140" y="158" text-anchor="middle" font-size="26" fill="#1b2733" font-family="sans-serif">Input</text>
+  <line x1="240" y1="150" x2="320" y2="150" stroke="#5a6776" stroke-width="3" marker-end="url(#a)"/>
+  <rect x="320" y="110" width="200" height="80" rx="12" fill="#eefaf7" stroke="#0e9488" stroke-width="2"/>
+  <text x="420" y="158" text-anchor="middle" font-size="26" fill="#1b2733" font-family="sans-serif">Process</text>
+  <defs><marker id="a" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+    <path d="M0,0 L8,3 L0,6 Z" fill="#5a6776"/></marker></defs>
+</svg>
+```
+
+Notes: pastel fills + saturated strokes read on both themes; the `<marker>` def gives every
+arrow a clean head — define it once per SVG and reference with `marker-end="url(#a)"`; keep
+marker `id`s unique per page if a page holds several SVGs.
+
+## Who uses this
+
+- **educate decks** — the native idiom; the deck template's header carries the one-line
+  distillation and a sample diagram slide.
+- **research briefings** — charts are inline SVG; these rules apply on top of the `dataviz`
+  skill's chart guidance.
+- **codebase-to-course** — courses prefer the HTML/CSS + emoji diagram patterns in the skill's
+  `interactive-elements.md`; when a course page does hand-draw inline SVG, these rules apply.

package/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/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@praxisflux/gates",
+  "version": "0.5.0",
+  "description": "praxis gate checks as a zero-dependency CLI (spec-bridge, wiki-freshness, course) — status can't exceed proven artifacts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evanstern/praxis.git"
+  },
+  "type": "module",
+  "bin": {
+    "praxis-gates": "scripts/run-gates.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/run-gates.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// run-gates.mjs — the praxis CI consumption surface: run selected praxis gates against a
+// consumer repository. This is what action.yml (the composite GitHub Action) invokes; it also
+// runs by hand from any praxis checkout:
+//
+//   node scripts/run-gates.mjs --gates spec-bridge,wiki-freshness [--path <root>]
+//                              [--wiki-dir docs/wiki] [--course-dir docs/course]
+//
+// Gate names, options, and exit codes are praxis's versioned consumer contract
+// (docs/consuming-gates.md): exit 0 when every gate passes, 1 when any gate fails, 2 on a
+// usage error (unknown gate, missing --gates). Each failure line names its fix. This same
+// file ships as the @praxisflux/gates npm bin (scripts/build-npm.mjs carves the package).
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { runAsCli } from "../lib/cli.mjs";
+import { checkBridge } from "../spec-bridge/gates/bridge.mjs";
+import { validateFreshness } from "../grounding-wiki/gates/freshness.mjs";
+import { validateCourse } from "../codebase-to-course/gates/course.mjs";
+
+/** wiki-freshness resolves verified_against pins through git history, which a shallow CI
+ *  clone doesn't have — catch that up front with the exact fix instead of a wall of
+ *  unknown-pin failures. */
+function shallowCloneProblem(root) {
+  const r = spawnSync("git", ["rev-parse", "--is-shallow-repository"], { cwd: root, encoding: "utf8" });
+  if (r.status === 0 && r.stdout.trim() === "true")
+    return `${root} is a shallow clone — wiki-freshness needs full history to resolve verified_against pins; set "fetch-depth: 0" on actions/checkout`;
+  return null;
+}
+
+/** Each gate takes {root, wikiDir, courseDir} and returns {problems, warnings, ok} where
+ *  ok is the one-line success summary. */
+export const GATES = {
+  "spec-bridge": ({ root }) => {
+    const { links, problems, warnings } = checkBridge(root);
+    return { problems, warnings, ok: `spec-bridge ok: ${links.length} linked task(s), none exceed their artifacts` };
+  },
+  "wiki-freshness": ({ root, wikiDir }) => {
+    const shallow = shallowCloneProblem(root);
+    if (shallow) return { problems: [shallow], warnings: [], ok: "" };
+    const { fails, warns, checked } = validateFreshness(root, wikiDir);
+    return { problems: fails, warnings: warns, ok: `wiki-freshness ok: ${checked} note(s) fresh against their pinned sources` };
+  },
+  "course": ({ root, courseDir }) => {
+    const { fails, warns, modules } = validateCourse(join(root, courseDir));
+    return { problems: fails, warnings: warns, ok: `course ok: ${modules} module(s) pass the course gate` };
+  },
+};
+
+/** Run the named gates against opts.root. Returns [{gate, problems, warnings, ok}].
+ *  Throws on an unknown or empty gate list — a misspelled gate must fail the build loudly,
+ *  never skip silently. */
+export function runGates(names, opts) {
+  if (!names.length) throw new Error(`no gates requested — pass --gates with any of: ${Object.keys(GATES).join(", ")}`);
+  for (const n of names)
+    if (!GATES[n]) throw new Error(`unknown gate "${n}" — valid gates: ${Object.keys(GATES).join(", ")}`);
+  return names.map((gate) => ({ gate, ...GATES[gate](opts) }));
+}
+
+if (runAsCli(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const opt = (name, dflt) => {
+    const i = args.indexOf(`--${name}`);
+    return i !== -1 && args[i + 1] !== undefined ? args[i + 1] : dflt;
+  };
+  const opts = {
+    root: resolve(opt("path", ".")),
+    wikiDir: opt("wiki-dir", "docs/wiki"),
+    courseDir: opt("course-dir", "docs/course"),
+  };
+  const names = opt("gates", "").split(",").map((s) => s.trim()).filter(Boolean);
+
+  let results;
+  try {
+    results = runGates(names, opts);
+  } catch (e) {
+    console.error(`usage error: ${e.message}`);
+    process.exit(2);
+  }
+  let failed = 0;
+  for (const { gate, problems, warnings, ok } of results) {
+    for (const w of warnings) console.log(`[${gate}] warn: ${w}`);
+    if (problems.length) {
+      failed++;
+      console.log(`[${gate}] GATE FAILED (${problems.length} issue(s)):`);
+      for (const p of problems) console.log(`  - ${p}`);
+    } else {
+      console.log(`[${gate}] ${ok}`);
+    }
+  }
+  process.exit(failed ? 1 : 0);
+}

package/spec-bridge/gates/bridge.mjs

@@ -0,0 +1,130 @@
+// bridge.mjs — read-only logic of the spec-bridge: find Backlog tasks linked to Spec Kit spec
+// dirs and judge each task's kanban status against the state its spec artifacts prove.
+//
+// A task is "linked" by a marker line in its description: `Spec: <dir>` where <dir> is the spec
+// directory relative to the project root (the dir holding backlog/). The marker is planted and
+// maintained ONLY via the backlog CLI (link/sync skills); this module just reads the task files.
+//
+// Verdicts per linked task, comparing the task's frontmatter status to the derived status:
+//   exceeds — status claims more than the artifacts prove (e.g. Done over unchecked boxes).
+//             The Stop-hook gate blocks on these.
+//   lags    — artifacts are ahead of the status (honest but stale). Warn, never block.
+//   ok      — they agree.
+//   unknown — the task uses a status outside To Do / In Progress / Done (custom workflow);
+//             the bridge doesn't guess, so it neither blocks nor warns.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { deriveSpecState, STATUS } from "../lib/spec-derive.mjs";
+import { hasChild, findRootsDownwards } from "../lib/project-root.mjs";
+
+/**
+ * Per-project bridge config: `.spec-bridge.json` at the project root (beside backlog/).
+ * `{ "strictDone": true }` turns on analyze-gated Done (see lib/spec-derive.mjs). Missing or
+ * malformed config means checkbox-only mode — strictness is opt-in.
+ */
+export function loadBridgeConfig(root) {
+  try { return JSON.parse(readFileSync(join(root, ".spec-bridge.json"), "utf8")) ?? {}; }
+  catch { return {}; }
+}
+
+const MARKER = /^Spec:\s*(\S+?)\/?\s*$/m;
+const RANK = { "to do": 0, "in progress": 1, done: 2 };
+const DERIVED_RANK = { [STATUS.TODO]: 0, [STATUS.IN_PROGRESS]: 1, [STATUS.DONE_ELIGIBLE]: 2 };
+
+/**
+ * Parse one Backlog task file. Returns { id, status, specDir } for a linked task,
+ * null for anything else (no marker, unreadable, or not a task file).
+ */
+export function parseLinkedTask(raw) {
+  const text = String(raw ?? "");
+  const marker = text.match(MARKER);
+  if (!marker) return null;
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const field = (name) => fm[1].match(new RegExp(`^${name}:\\s*(.+?)\\s*$`, "m"))?.[1]?.replace(/^['"]|['"]$/g, "") ?? "";
+  const id = field("id");
+  const status = field("status");
+  if (!id) return null;
+  return { id, status, specDir: marker[1] };
+}
+
+/** Scan <root>/backlog/tasks/*.md for linked tasks. Unreadable files are skipped. */
+export function findLinkedTasks(root) {
+  const dir = join(root, "backlog", "tasks");
+  let entries = [];
+  try { entries = readdirSync(dir); } catch { return []; }
+  const linked = [];
+  for (const name of entries.filter((n) => n.endsWith(".md")).sort()) {
+    try {
+      const task = parseLinkedTask(readFileSync(join(dir, name), "utf8"));
+      if (task) linked.push({ ...task, file: join(dir, name) });
+    } catch { /* skip unreadable */ }
+  }
+  return linked;
+}
+
+/** Compare a task's Backlog status to its derived status: "exceeds" | "lags" | "ok" | "unknown". */
+export function verdict(taskStatus, derivedStatus) {
+  const t = RANK[String(taskStatus).toLowerCase()];
+  const d = DERIVED_RANK[derivedStatus];
+  if (t === undefined || d === undefined) return "unknown";
+  return t > d ? "exceeds" : t < d ? "lags" : "ok";
+}
+
+/** One human sentence on why a spec dir doesn't prove more than its derived status. */
+function shortfall(root, specDir, derived) {
+  const missing = ["spec.md", "plan.md"].filter((f) => !existsSync(join(root, specDir, f)));
+  const parts = missing.map((f) => `${f} missing`);
+  if (derived.tasksTotal === 0) parts.push("no tasks in tasks.md");
+  else if (derived.tasksDone < derived.tasksTotal)
+    parts.push(`${derived.tasksTotal - derived.tasksDone} of ${derived.tasksTotal} tasks unchecked (${derived.progressNote})`);
+  if (derived.analysis?.required) {
+    if (!derived.analysis.present)
+      parts.push("analysis.md missing (strict Done: save the /speckit.analyze report into the spec dir)");
+    else if (derived.analysis.criticals.length)
+      parts.push(`unresolved CRITICAL finding(s) in analysis.md: ${derived.analysis.criticals.join(" | ")}`);
+  }
+  return parts.join(", ") || "artifacts incomplete";
+}
+
+/**
+ * Judge every linked task under <root>. Returns:
+ *   links    — [{ id, status, specDir, derived, verdict }]
+ *   problems — blocking messages, one per "exceeds"
+ *   warnings — non-blocking messages, one per "lags"
+ */
+export function checkBridge(root) {
+  const links = [];
+  const problems = [];
+  const warnings = [];
+  const requireAnalysis = loadBridgeConfig(root).strictDone === true;
+  for (const task of findLinkedTasks(root)) {
+    const derived = deriveSpecState(join(root, task.specDir), { requireAnalysis });
+    const v = verdict(task.status, derived.status);
+    links.push({ ...task, derived, verdict: v });
+    if (v === "exceeds") {
+      problems.push(
+        `[spec-bridge] ${task.id} is "${task.status}" but ${task.specDir} only proves "${derived.status}": ` +
+        `${shortfall(root, task.specDir, derived)}. Finish the spec work or set the task back (backlog task edit ${task.id} -s "...").`
+      );
+    } else if (v === "lags") {
+      warnings.push(
+        `[spec-bridge] ${task.id} is "${task.status}" but ${task.specDir} already derives "${derived.status}" — run the spec-bridge sync skill to catch the board up.`
+      );
+    }
+  }
+  return { links, problems, warnings };
+}
+
+/**
+ * The Stop-hook gate, in gate-runner shape. Roots are directories holding a backlog/ dir;
+ * a root with no linked tasks yields no problems, so the gate is a natural no-op outside
+ * bridged projects. "exceeds" blocks; "lags" only warns.
+ */
+export const bridgeGate = {
+  name: "spec-bridge",
+  resolveRoots: (startDir) => findRootsDownwards(startDir, hasChild("backlog")),
+  check: (root) => checkBridge(root).problems,
+  warn: (root) => checkBridge(root).warnings,
+};

package/spec-bridge/gates/cli.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// cli.mjs — command-line entry to the spec-bridge gates (read-only; all Backlog writes go
+// through the backlog CLI in the skills). The skills call these instead of parsing markdown:
+//   node cli.mjs state <specDir>   derived state for one spec dir, as JSON
+//   node cli.mjs links <root>      every linked task under <root> with derived state + verdict, as JSON
+//   node cli.mjs check <root>      human report; exit 1 if any task's status exceeds its artifacts
+import { resolve } from "node:path";
+import { deriveSpecState } from "../lib/spec-derive.mjs";
+import { findRootUpwards, hasChild } from "../lib/project-root.mjs";
+import { checkBridge, loadBridgeConfig } from "./bridge.mjs";
+
+const [cmd, target] = process.argv.slice(2);
+if (!cmd || !target) {
+  console.error("usage: cli.mjs state <specDir> | links <root> | check <root>");
+  process.exit(2);
+}
+
+if (cmd === "state") {
+  // Honor the project's .spec-bridge.json (strictDone) — same config checkBridge uses.
+  const root = findRootUpwards(resolve(target), hasChild("backlog"));
+  const requireAnalysis = root ? loadBridgeConfig(root).strictDone === true : false;
+  console.log(JSON.stringify(deriveSpecState(target, { requireAnalysis }), null, 2));
+} else if (cmd === "links") {
+  console.log(JSON.stringify(checkBridge(target).links, null, 2));
+} else if (cmd === "check") {
+  const { links, problems, warnings } = checkBridge(target);
+  for (const w of warnings) console.log(`warn: ${w}`);
+  if (problems.length) {
+    console.log(`\nGATE FAILED (${problems.length} issue(s)):`);
+    for (const p of problems) console.log(`  - ${p}`);
+    process.exit(1);
+  }
+  console.log(`spec-bridge ok: ${links.length} linked task(s), none exceed their artifacts`);
+} else {
+  console.error(`unknown command: ${cmd}`);
+  process.exit(2);
+}

package/spec-bridge/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/spec-bridge/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/spec-bridge/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)}`);
+}