@praxisflux/gates 0.5.0

package/grounding-wiki/lib/toolkit/README.md

@@ -0,0 +1,45 @@
+# lib/toolkit — shared educational content modules
+
+Reusable teaching and visual tools shared across the praxis plugins. Where the rest of `lib/`
+is shared *plumbing* (code the gates and scripts import), `toolkit/` is shared *content*:
+authoring guidance and copy-paste CSS/JS snippets a skill reads while producing a deck, course,
+or briefing. The full convention lives in
+[`docs/skill-patterns.md`](../../docs/skill-patterns.md) ("Shared content modules — the toolkit").
+
+The convention in brief:
+
+- **Vendored, not linked.** `scripts/build.mjs` copies `lib/` wholesale into every packaged
+  plugin, so each installed plugin carries its own copy — no runtime cross-plugin dependency.
+- **Referenced as `${CLAUDE_PLUGIN_ROOT}/lib/toolkit/<module>.md`** from skill prose and
+  templates. Gate code doesn't import from toolkit/ (it's content, not plumbing).
+- **Optional, always.** A skill that uses a module must state a one-line inline fallback and
+  still function when the module is absent (graceful degradation).
+- **Styled by the shared token schema.** Snippets use the shared CSS custom-property *names*
+  (see `lib/html/base.html`) so they inherit whichever palette the consuming plugin defines.
+
+## Modules
+
+| Module | What it provides | Status |
+|---|---|---|
+| `tooltip.md` | Jargon-glossary hover/tap tooltip (overflow-safe, mouse + touch; stamped into consumers by `scripts/sync-shared.mjs`) | shipped |
+| `pedagogy.md` | Visual-teaching principles: one idea per screen, show don't tell, lead with the point, split don't shrink, let visuals breathe | shipped |
+| `svg-diagrams.md` | Inline-SVG authoring rules and pitfalls (`<tspan>` not `<b>`, no `var()` in SVG attrs, both-theme colors) | shipped |
+| `code-translation.md` | Code ↔ plain-English translation (rules + zero-JS comments-on-top panel) | shipped |
+| `quiz-patterns.md` | Quiz design (coverage rule, application-not-memory) + zero-JS reveal quiz | shipped |
+| `diagrams.md` | HTML/CSS flow + annotated file-tree diagram idioms | shipped |
+
+## Plugin-owned versioned chrome (indexed here, lives with its owner)
+
+Some shared visual machinery is too heavy and too domain-specific to vendor into every plugin,
+but still needs one canonical, versioned home. Those modules stay in their owning plugin and are
+*indexed* here so "where does shared visual machinery live" has a single answer:
+
+| Chrome | Canonical source | Version | Convention |
+|---|---|---|---|
+| Course chrome (`styles.css`, `main.js`, `_footer.html`, `build.sh`, `validate.mjs`) | `codebase-to-course/skills/codebase-to-course/references/` | `chrome v2 — inline translation engine (comments-on-top)` | `docs/skill-patterns.md` "Versioned course chrome" |
+
+The rules that keep it from fossilizing: rendering files open with the version stamp (no stamp
+= v1, the retired side-by-side renderer); `validate.mjs` carries `CHROME_VERSION`, and both
+`build.sh` and the course gate fail unstamped or version-mixed copies; `build.sh` refreshes the
+chrome from the canonical source whenever `CLAUDE_PLUGIN_ROOT`/`C2C_REFERENCES` resolves.
+Vendored course copies are build artifacts, never templates.

package/grounding-wiki/lib/toolkit/code-translation.md

@@ -0,0 +1,50 @@
+# Code ↔ plain-English translation
+
+The single most valuable tool for teaching code to non-technical readers: never show code
+without a plain-English translation of what each line does, and never write a paragraph
+*about* code when you can annotate the code itself. Originally codebase-to-course's pattern.
+
+**Graceful degradation:** if this module isn't available, follow the code with a short
+"in plain English:" list — one bullet per line that matters.
+
+## The rules (medium-independent)
+
+- **Use real code, verbatim.** Never modify, simplify, or trim snippets — the reader should
+  be able to open the file and see exactly what they learned from. *Choose* naturally short,
+  punchy snippets (5–10 lines) instead of butchering long ones.
+- **No horizontal scrollbars, ever.** `white-space: pre-wrap; word-break: break-word` — this
+  is teaching material, not an IDE; readability beats preserved indentation.
+- **One note per line that matters,** in everyday language, positioned so the pairing is
+  unmistakable. Skip noise lines (braces, imports) rather than annotating them emptily.
+- A metaphor inside a note is welcome; jargon inside a note defeats the point (gloss it —
+  see `tooltip.md`).
+
+## Portable snippet (decks, briefings — zero JS)
+
+Comments-on-top: each plain-English note is a styled line directly ABOVE the code it
+explains, inside one token-styled panel. Inherits the consumer's palette.
+
+```html
+<style>
+.translate{background:var(--ink);color:var(--bg);border-radius:12px;padding:1em 1.2em;
+  font-family:var(--mono);font-size:.9em;line-height:1.6;
+  white-space:pre-wrap;word-break:break-word}
+.translate .note{display:block;color:var(--accent2);font-family:var(--sans);
+  font-style:italic;filter:brightness(1.25)}
+</style>
+
+<pre class="translate"><span class="note">// Ask the server for this user's saved items…</span>
+const res = await fetch(`/api/favorites/${userId}`);
+<span class="note">// …and unpack the JSON body once it arrives.</span>
+const favorites = await res.json();</pre>
+```
+
+Deck usage: give the translation its own slide (shared pedagogy — one idea per slide); the
+deck's 30px body type means 4–8 code lines fill a slide comfortably.
+
+## In codebase-to-course
+
+Courses do NOT use this snippet — the prebuilt assets ship a far richer engine (side-by-side
+panels rebuilt as comments-on-top at render time, syntax highlighting, per-block "hide notes"
+toggle). Author against the `.translation-block` contract in the skill's
+`interactive-elements.md`; this module is the portable variant for every other surface.

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