@skyf0xx/hedgehog 3.0.5 → 3.0.7

package/README.md

@@ -88,7 +88,7 @@ Artifact
 
 ### Anything else
 
-A CLI, a library, a browser extension, a data pipeline, etc. fitting neither shape gets its own build order, designed at intake rather than chosen from a menu.
+A CLI, a library, a browser extension, a data pipeline, etc. fitting neither shape gets its own build order, designed at intake rather than chosen from a menu — starting from a [battle-tested blueprint](src/skills/hedgehog-core-design/blueprints) for the system's shape where one exists.
 
 Run `init` with no core flag: planning intake names the system shape, picks
 the stack, derives the layers, and locks them to `.hedgehog/core.yaml`,
@@ -101,7 +101,7 @@ scoped file access and a verification command per layer.
 
 ## Install
 
-From an empty project folder, ask Claude to run:
+From an empty project folder, run:
 
 ``` bash
 # Full-stack app
@@ -114,7 +114,29 @@ npx @skyf0xx/hedgehog init --landing-page
 npx @skyf0xx/hedgehog init
 ```
 
-Then open Claude Code and describe what you want to build.
+Then open your coding agent and describe what you want to build.
+
+### Coding agents
+
+Hedgehog installs for **Claude Code** by default. Add a host flag to
+install for another one, or several at once:
+
+``` bash
+npx @skyf0xx/hedgehog init --cursor              # Cursor
+npx @skyf0xx/hedgehog init --gemini              # Gemini CLI
+npx @skyf0xx/hedgehog init --host=claude,cursor  # both
+npx @skyf0xx/hedgehog init --all-hosts           # every supported agent
+```
+
+Each one gets the discipline in its own native shape — agents and skills
+in the directory it reads, and the instructions file it loads at session
+start (`CLAUDE.md`, `HEDGEHOG.md`, or `GEMINI.md`).
+
+Every install also writes **`AGENTS.md`** at the repo root: an index of
+every agent and skill, when each applies, and the build loop. Coding
+agents that read `AGENTS.md` — Codex, Copilot CLI, OpenCode, and others —
+work from that index, following the same ordered steps and the same
+`hedgehog verify` gate.
 
 Plain `init` (no core flag) installs the agents, skills, and build graph
 that every core shares. Planning intake designs an opinionated build
@@ -128,9 +150,11 @@ To update:
 npx @skyf0xx/hedgehog update
 ```
 
-This refreshes `.claude/agents/` and `.claude/skills/` only. It never
-touches `CLAUDE.md`, the build graph, the core workspace, or
-`skills/BMAD`, since those carry project-specific or write-once content.
+This refreshes the installed agents and skills — for every coding agent
+the project was set up for — along with the `AGENTS.md` index derived
+from them. It never touches the instructions file, the build graph, the
+core workspace, or `skills/BMAD`, since those carry project-specific or
+write-once content.
 
 To see the build graph:
 
@@ -139,16 +163,7 @@ npx @skyf0xx/hedgehog graph
 ```
 
 Starts a small local server and opens a live, read-only diagram of every
-task and its dependencies — one node per task, coloured by lifecycle
-status, laid out top-to-bottom by dependency order. Click a task to see
-its objective, verify command, and commit message; click empty canvas to
-close it. The page polls for changes, so it keeps updating on its own as
-`hedgehog verify` moves tasks through their lifecycle — no re-running the
-command or reloading the page. Running `graph` again while a server is
-already up reuses it instead of starting a second one. Pass `--no-open`
-to start (or reuse) the server and print its URL instead of launching a
-browser. `hedgehog plan` opens the same live view automatically whenever
-it compiles new tasks.
+task, status and its dependencies.
 
 ## Why Hedgehog
 

package/bin/cli.mjs

@@ -6,8 +6,10 @@
 //   npx @skyf0xx/hedgehog init                        install; planner picks the core at intake
 //   npx @skyf0xx/hedgehog init --ts-full-stack-app     scaffold the full-stack-app core now
 //   npx @skyf0xx/hedgehog init --landing-page          scaffold the landing-page core now
+//   npx @skyf0xx/hedgehog init --cursor                install for Cursor (default: Claude Code)
+//   npx @skyf0xx/hedgehog init --all-hosts             install for every supported coding agent
 //   npx @skyf0xx/hedgehog init --force                 overwrite files that already exist
-//   npx @skyf0xx/hedgehog update                       refresh .claude/agents + .claude/skills
+//   npx @skyf0xx/hedgehog update                       refresh the installed agents + skills
 //   npx @skyf0xx/hedgehog --help
 
 import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile } from 'node:fs/promises';
@@ -25,6 +27,8 @@ import { verifyTask } from '../src/db/verify.mjs';
 import { graphStatus, formatStatus } from '../src/db/status.mjs';
 import { whyPath, formatWhy } from '../src/db/why.mjs';
 import { addFriction, listFriction } from '../src/db/friction.mjs';
+import { HOSTS, HOST_FLAGS, DEFAULT_HOST, availableHosts } from '../src/hosts/index.mjs';
+import { recordHosts, installedHosts } from '../src/hosts/installed.mjs';
 
 const AUTHORED_CORE_PATH = '.hedgehog/core.yaml';
 
@@ -84,26 +88,49 @@ async function availableCores() {
 // core `planner` picks — the first time either way. An explicit flag
 // (`--ts-full-stack-app`, `--landing-page`) is a confirmed choice, so it
 // scaffolds that workspace immediately, at install time.
-function plan(core) {
-  const base = [
-    { type: 'dir', from: 'src/agents', to: '.claude/agents' },
-    { type: 'dir', from: 'src/skills', to: '.claude/skills' },
-    // The vendored BMAD-METHOD planning shelf that hedgehog-planning-intake
-    // runs — referenced by repo-root-relative path (skills/BMAD/...), so it
-    // lands there rather than under .claude/.
-    { type: 'dir', from: 'skills/BMAD', to: 'skills/BMAD' },
-    // The vendored GSAP animation skill shelf that front-end-eng loads for
-    // motion work — same repo-root-relative referencing as skills/BMAD.
-    { type: 'dir', from: 'skills/GSAP', to: 'skills/GSAP' },
+// `hostOnly` plans just the parts that differ per host — used when a
+// second host is added to a project whose shared payload (the vendored
+// shelves, the core workspace) is already on disk.
+function plan(core, host = DEFAULT_HOST, { hostOnly = false } = {}) {
+  const h = HOSTS[host];
+  const perHost = [
+    { type: 'dir', from: 'src/agents', to: h.agentsDir, emit: h.emitAgent },
+    { type: 'dir', from: 'src/skills', to: h.skillsDir },
+    // Whatever else this host needs to find the payload — its own rules
+    // file, extension manifest, or routing doc. Empty for a host that
+    // auto-loads its bootstrap file and registers agents from disk.
+    ...(h.extraEntries ?? []),
   ];
 
+  // Host-independent: one copy per project however many hosts read it.
+  const shared = hostOnly
+    ? []
+    : [
+        // The vendored BMAD-METHOD planning shelf that
+        // hedgehog-planning-intake runs — referenced by repo-root-relative
+        // path (skills/BMAD/...), so it lands there rather than under a
+        // host's own directory.
+        { type: 'dir', from: 'skills/BMAD', to: 'skills/BMAD' },
+        // The vendored GSAP animation skill shelf that front-end-eng loads
+        // for motion work — same repo-root-relative referencing.
+        { type: 'dir', from: 'skills/GSAP', to: 'skills/GSAP' },
+      ];
+
+  const base = [...perHost, ...shared];
+
   if (core === null) {
     return [
       ...base,
       // The shell with its {{CORE_SECTION}} placeholder left unfilled —
       // whichever bootstrap-core skill runs first fills it in for the
-      // core planner actually picked.
-      { type: 'file', from: 'src/templates/CLAUDE.md', to: 'CLAUDE.md' },
+      // core planner actually picked. {{HOST_DISPATCH}} is filled now:
+      // which host this is doesn't depend on the core.
+      {
+        type: 'merge',
+        shell: 'src/templates/CLAUDE.md',
+        dispatch: `src/hosts/${host}/DISPATCH.md`,
+        to: h.bootstrapFile,
+      },
     ];
   }
 
@@ -113,30 +140,37 @@ function plan(core) {
       type: 'merge',
       shell: 'src/templates/CLAUDE.md',
       include: `src/templates/CLAUDE.core.${core}.md`,
-      to: 'CLAUDE.md',
+      dispatch: `src/hosts/${host}/DISPATCH.md`,
+      to: h.bootstrapFile,
     },
     // The pre-built, pre-verified workspace for the chosen core —
     // everything a fresh project of that shape needs at repo root
     // (lands the root package.json too, so there's no separate
     // placeholder for it). The relevant bootstrap-core skill verifies
     // this on first run rather than generating it live.
-    { type: 'dir', from: `src/golden-cores/${core}`, to: '.' },
+    ...(hostOnly ? [] : [{ type: 'dir', from: `src/golden-cores/${core}`, to: '.' }]),
   ];
 }
 
 // The subset of plan() that's the discipline's payload rather than
 // project-specific or write-once content: `update` re-copies exactly
-// this, always overwriting, since a consuming project's own
-// .claude/agents and .claude/skills are supposed to match upstream
-// verbatim. CLAUDE.md carries project-filled content, the build graph
-// and core workspace are verified once by their own init/bootstrap-core
-// steps, and skills/BMAD and skills/GSAP are re-vendored only
-// deliberately (a manual re-vendor, per each shelf's ATTRIBUTION.md) —
-// none of those belong in an update.
-const UPDATE_PLAN = [
-  { type: 'dir', from: 'src/agents', to: '.claude/agents' },
-  { type: 'dir', from: 'src/skills', to: '.claude/skills' },
-];
+// this, always overwriting, since a consuming project's installed agents
+// and skills are supposed to match upstream verbatim. The bootstrap file
+// carries project-filled content, the build graph and core workspace are
+// verified once by their own init/bootstrap-core steps, and skills/BMAD
+// and skills/GSAP are re-vendored only deliberately (a manual re-vendor,
+// per each shelf's ATTRIBUTION.md) — none of those belong in an update.
+function updatePlan(host = DEFAULT_HOST) {
+  const h = HOSTS[host];
+  return [
+    { type: 'dir', from: 'src/agents', to: h.agentsDir, emit: h.emitAgent },
+    { type: 'dir', from: 'src/skills', to: h.skillsDir },
+    // Derived from the agents and skills above — an agent added, renamed,
+    // or redescribed upstream has to be reflected in the index that
+    // points at it, so it is regenerated alongside them.
+    ...(h.extraEntries ?? []).filter((e) => e.type === 'generated'),
+  ];
+}
 
 const exists = (p) =>
   access(p, constants.F_OK).then(
@@ -150,9 +184,29 @@ const exists = (p) =>
 async function writePlannedFile(f) {
   await mkdir(dirname(f.dest), { recursive: true });
   if (f.merge) {
-    const shell = await readFile(join(PKG_ROOT, f.merge.shell), 'utf8');
-    const section = await readFile(join(PKG_ROOT, f.merge.include), 'utf8');
-    await writeFile(f.dest, shell.replaceAll('{{CORE_SECTION}}', section.trimEnd()));
+    let out = await readFile(join(PKG_ROOT, f.merge.shell), 'utf8');
+    // A deferred install has no core yet, so {{CORE_SECTION}} stays put
+    // for whichever bootstrap-core skill runs first to fill in. The host
+    // is always known at install time, so {{HOST_DISPATCH}} never is.
+    if (f.merge.include) {
+      const section = await readFile(join(PKG_ROOT, f.merge.include), 'utf8');
+      out = out.replaceAll('{{CORE_SECTION}}', section.trimEnd());
+    }
+    const dispatch = await readFile(join(PKG_ROOT, f.merge.dispatch), 'utf8');
+    await writeFile(f.dest, out.replaceAll('{{HOST_DISPATCH}}', dispatch.trimEnd()));
+    return;
+  }
+  // Rendered from the payload rather than copied from it — the routing
+  // doc's tables are built from the agents' and skills' own frontmatter.
+  if (f.generate) {
+    await writeFile(f.dest, await f.generate({ pkgRoot: PKG_ROOT, projectRoot: DEST_ROOT }));
+    return;
+  }
+  // A host whose format differs from the canonical one rewrites the file
+  // on the way in. Hosts that read the canonical format have no emitter,
+  // so their payload is copied verbatim.
+  if (f.emit) {
+    await writeFile(f.dest, f.emit(await readFile(f.src, 'utf8'), { src: f.src }));
     return;
   }
   await cp(f.src, f.dest);
@@ -163,9 +217,12 @@ async function plannedFiles(entry) {
   if (entry.type === 'merge') {
     return [{ dest: join(DEST_ROOT, entry.to), merge: entry }];
   }
+  if (entry.type === 'generated') {
+    return [{ dest: join(DEST_ROOT, entry.to), generate: entry.generate }];
+  }
   const src = join(PKG_ROOT, entry.from);
   if (entry.type === 'file') {
-    return [{ src, dest: join(DEST_ROOT, entry.to) }];
+    return [{ src, dest: join(DEST_ROOT, entry.to), emit: entry.emit }];
   }
   const out = [];
   async function walk(rel) {
@@ -175,7 +232,7 @@ async function plannedFiles(entry) {
       for (const name of await readdir(abs)) await walk(join(rel, name));
     } else {
       const renamed = DOTFILE_RENAMES[rel] ?? rel;
-      out.push({ src: abs, dest: join(DEST_ROOT, entry.to, renamed) });
+      out.push({ src: abs, dest: join(DEST_ROOT, entry.to, renamed), emit: entry.emit });
     }
   }
   await walk('.');
@@ -187,16 +244,20 @@ async function help() {
   console.log(`
 ${bold('Hedgehog installer')}
 
-Copies the Hedgehog agents and skills into ${bold('.claude/')}, drops the
-CLAUDE.md template and an empty build graph (${bold('.hedgehog/hedgehog.db')})
-into the repo root, so the discipline is committed alongside your code.
+Copies the Hedgehog agents and skills into your coding agent's own
+directory, drops that agent's instructions file, an AGENTS.md index, and an
+empty build graph (${bold('.hedgehog/hedgehog.db')}) into the repo root, so
+the discipline is committed alongside your code.
 
 ${bold('Usage')}
   npx @skyf0xx/hedgehog init                      install; planner picks the core at intake
   npx @skyf0xx/hedgehog init --ts-full-stack-app  scaffold the full-stack-app core now
   npx @skyf0xx/hedgehog init --landing-page       scaffold the landing-page core now
+  npx @skyf0xx/hedgehog init --cursor             install for Cursor (default: Claude Code)
+  npx @skyf0xx/hedgehog init --host=claude,gemini install for several coding agents at once
+  npx @skyf0xx/hedgehog init --all-hosts          install for every supported coding agent
   npx @skyf0xx/hedgehog init --force              overwrite existing files
-  npx @skyf0xx/hedgehog update                    refresh .claude/agents + .claude/skills
+  npx @skyf0xx/hedgehog update                    refresh the installed agents + skills
   npx @skyf0xx/hedgehog db init                   create .hedgehog/hedgehog.db if absent
   npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies,
                                                    then open the build graph if anything compiled
@@ -213,10 +274,11 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog --help
 
 Available cores: ${cores.join(', ')}
+Available hosts: ${availableHosts().join(', ')} (default: ${DEFAULT_HOST})
 
-After it runs, commit the payload, open Claude Code, and describe what
-you want to build — the planner agent runs planning intake, then hands
-off to bootstrap.
+After it runs, commit the payload, open your coding agent, and describe
+what you want to build — the planner agent runs planning intake, then
+hands off to bootstrap.
 
 Building something else (a CLI, library, browser extension, data
 pipeline, desktop app, etc.)? Run plain 'init' with no core flag rather
@@ -226,16 +288,17 @@ shares. The planner agent designs a core at planning intake
 (hedgehog-core-design) and bootstrap generates that workspace once it's
 confirmed. Describe the actual project and let Phase 0 route it.
 
-${bold('update')} re-copies only .claude/agents and .claude/skills from the
-installed Hedgehog version, so an already-bootstrapped project can pick up
-agent/skill changes from a newer release. It always overwrites those two
-directories and never touches CLAUDE.md, the build graph, the core
-workspace, or skills/BMAD and skills/GSAP — those are project-specific or
-updated deliberately, not by this command.
+${bold('update')} re-copies the agents and skills (and the AGENTS.md index
+derived from them) from the installed Hedgehog version, so an
+already-bootstrapped project can pick up changes from a newer release. It
+refreshes every host the project was installed for, always overwriting
+those directories. The instructions file, the build graph, the core
+workspace, and skills/BMAD and skills/GSAP stay as they are — those are
+project-specific or updated deliberately, not by this command.
 `);
 }
 
-async function init({ force, core, explicitCore }) {
+async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly = false }) {
   if (explicitCore) {
     const cores = await availableCores();
     if (!cores.includes(core)) {
@@ -251,13 +314,18 @@ async function init({ force, core, explicitCore }) {
   // before touching anything. A deferred install (no explicit core) plans
   // against `null` — the shared agents/skills/build-graph payload only.
   const groups = [];
-  for (const entry of plan(explicitCore ? core : null)) {
+  for (const entry of plan(explicitCore ? core : null, host, { hostOnly })) {
     const files = await plannedFiles(entry);
     groups.push({ entry, files });
   }
 
+  // A generated file is derived from the payload rather than authored in
+  // the project, so rewriting it loses nothing and never counts as a
+  // conflict — that's what lets a second host be added to a project the
+  // first one already set up.
   const conflicts = [];
-  for (const { files } of groups) {
+  for (const { entry, files } of groups) {
+    if (entry.type === 'generated') continue;
     for (const f of files) {
       if (await exists(f.dest)) conflicts.push(f.dest);
     }
@@ -275,6 +343,10 @@ async function init({ force, core, explicitCore }) {
     return;
   }
 
+  // Recorded before anything is written: the routing doc is generated
+  // from this list, so it has to already name the host being installed.
+  await recordHosts(DEST_ROOT, [host]);
+
   let written = 0;
   let overwritten = 0;
   for (const { files } of groups) {
@@ -301,10 +373,10 @@ async function init({ force, core, explicitCore }) {
   if (explicitCore) {
     console.log(`  1. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
     console.log(`  2. ${bold('pnpm install')}`);
-    console.log(`  3. Open Claude Code and describe what you want to build.`);
+    console.log(`  3. Open ${HOSTS[host].label} and describe what you want to build.`);
   } else {
     console.log(`  1. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
-    console.log(`  2. Open Claude Code and describe what you want to build.`);
+    console.log(`  2. Open ${HOSTS[host].label} and describe what you want to build.`);
   }
   console.log(
     dim(
@@ -333,36 +405,55 @@ async function init({ force, core, explicitCore }) {
   }
 }
 
-async function update() {
-  // Full replace, not a merge: clear each destination dir first so a
-  // rename or removal upstream (e.g. an agent renamed between releases)
-  // doesn't leave a stale file sitting alongside the new one.
-  for (const entry of UPDATE_PLAN) {
-    await rm(join(DEST_ROOT, entry.to), { recursive: true, force: true });
-  }
+async function update({ hosts }) {
+  const targets = hosts?.length ? hosts : await installedHosts(DEST_ROOT);
 
   let written = 0;
-  for (const entry of UPDATE_PLAN) {
-    const files = await plannedFiles(entry);
-    for (const f of files) {
-      await mkdir(dirname(f.dest), { recursive: true });
-      await cp(f.src, f.dest);
-      written++;
-      console.log(`  ${green('update')}  ${relative(DEST_ROOT, f.dest)}`);
+  for (const host of targets) {
+    const entries = updatePlan(host);
+
+    // Full replace, not a merge: clear each payload directory first so a
+    // rename or removal upstream (e.g. an agent renamed between releases)
+    // doesn't leave a stale file sitting alongside the new one. Generated
+    // files are single files rewritten in place, so they're left alone.
+    for (const entry of entries) {
+      if (entry.type === 'dir') {
+        await rm(join(DEST_ROOT, entry.to), { recursive: true, force: true });
+      }
+    }
+
+    for (const entry of entries) {
+      for (const f of await plannedFiles(entry)) {
+        await writePlannedFile(f);
+        written++;
+        console.log(`  ${green('update')}  ${relative(DEST_ROOT, f.dest)}`);
+      }
     }
   }
 
+  const label = targets.map((h) => HOSTS[h].label).join(', ');
   console.log(
-    `\n${green(bold('Hedgehog agents/skills updated.'))} ${dim(`${written} files written`)}\n`,
+    `\n${green(bold('Hedgehog agents/skills updated.'))} ${dim(
+      `${written} files written for ${label}`,
+    )}\n`,
   );
   console.log('Next steps:');
-  console.log(`  1. ${bold('git diff .claude/')} to review what changed`);
+  const reviewDirs = [
+    ...new Set(
+      targets.map((h) => {
+        const d = dirname(HOSTS[h].agentsDir);
+        return d === '.' ? HOSTS[h].agentsDir : `${d}/`;
+      }),
+    ),
+  ];
+  console.log(`  1. ${bold(`git diff ${reviewDirs.join(' ')}`)} to review what changed`);
   console.log(`  2. ${bold('git add -A && git commit -m "chore: update hedgehog"')}\n`);
+  const bootstraps = [...new Set(targets.map((h) => HOSTS[h].bootstrapFile))].join(', ');
   console.log(
     dim(
-      'CLAUDE.md, the build graph, the core workspace, and skills/BMAD\n' +
-        'and skills/GSAP are untouched — those carry project-specific or\n' +
-        'write-once content.',
+      `${bootstraps}, the build graph, the core workspace, and\n` +
+        'skills/BMAD and skills/GSAP are untouched — those carry\n' +
+        'project-specific or write-once content.',
     ),
   );
 }
@@ -912,13 +1003,46 @@ async function main() {
   }
   const core = coreFlag ? CORE_FLAGS[coreFlag] : DEFAULT_CORE;
 
+  // Which coding agent this repo is being set up for. `--host=<name>` and
+  // the per-host shorthand flags are equivalent; absent either, the
+  // default host applies.
+  const allHosts = args.includes('--all-hosts');
+  const hostFlags = args.filter((a) => a in HOST_FLAGS).map((a) => HOST_FLAGS[a]);
+  const hostEq = args
+    .filter((a) => a.startsWith('--host='))
+    .flatMap((a) => a.slice('--host='.length).split(','))
+    .map((h) => h.trim())
+    .filter(Boolean);
+  const named = [...new Set([...hostFlags, ...hostEq])];
+  const unknown = named.filter((h) => !(h in HOSTS));
+  if (unknown.length) {
+    console.error(
+      `${red('Unknown host:')} ${unknown.join(', ')}\n\n` +
+        `Available hosts: ${availableHosts().join(', ')}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const hosts = allHosts ? availableHosts() : named;
+
   if (cmd === 'init') {
-    await init({ force, core, explicitCore: Boolean(coreFlag) });
+    // The shared payload — vendored shelves, core workspace — lands with
+    // the first host; the rest add only what differs per host.
+    const targets = hosts.length ? hosts : [DEFAULT_HOST];
+    for (const [i, host] of targets.entries()) {
+      await init({
+        force,
+        core,
+        explicitCore: Boolean(coreFlag),
+        host,
+        hostOnly: i > 0,
+      });
+    }
     return;
   }
 
   if (cmd === 'update') {
-    await update();
+    await update({ hosts });
     return;
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "3.0.5",
-  "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
+  "version": "3.0.7",
+  "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
     "bin",
     "src/agents",
     "src/db",
+    "src/hosts",
     "src/skills",
     "src/templates",
     "src/golden-cores",
@@ -32,6 +33,9 @@
   "keywords": [
     "claude",
     "claude-code",
+    "cursor",
+    "gemini-cli",
+    "agents-md",
     "agents",
     "skills",
     "scaffold",

package/src/db/graph.mjs

@@ -18,6 +18,16 @@ const ALL_DEPENDENCIES_SQL = `
   SELECT task_id, depends_on_task_id FROM dependencies;
 `;
 
+// One query for every task's requirement links, not one query per task —
+// this runs on every poll (see graph-server.mjs), so an N+1 here would
+// mean N+1 queries every 2 seconds rather than once.
+const ALL_TASK_REQUIREMENTS_SQL = `
+  SELECT tr.task_id, r.kind, r.statement
+  FROM task_requirements tr
+  JOIN requirements r ON r.id = tr.requirement_id
+  ORDER BY tr.task_id, r.id;
+`;
+
 function loadAllTasks(db) {
   return db.prepare(ALL_TASKS_SQL).all();
 }
@@ -26,13 +36,32 @@ function loadAllDependencies(db) {
   return db.prepare(ALL_DEPENDENCIES_SQL).all();
 }
 
+function loadAllTaskRequirements(db) {
+  return db.prepare(ALL_TASK_REQUIREMENTS_SQL).all();
+}
+
+// Groups the flat requirement rows by task_id, same rule/constraint/
+// acceptance mix hedgehog next's RELEVANT RULES section shows — a task
+// is bound by all three kinds equally, so the graph's detail panel
+// doesn't split them out either.
+function groupRequirementsByTask(rows) {
+  const byTask = new Map();
+  for (const row of rows) {
+    if (!byTask.has(row.task_id)) byTask.set(row.task_id, []);
+    byTask.get(row.task_id).push({ kind: row.kind, statement: row.statement });
+  }
+  return byTask;
+}
+
 // Shapes the full build graph into { nodes, edges } for the viewer.
 // Each node carries exactly the fields the viewer displays on click
-// (objective, verify_command, commit_message) plus the fields that drive
-// layout and status colour — nothing the viewer doesn't render.
+// (objective, verify_command, commit_message, requirements) plus the
+// fields that drive layout and status colour — nothing the viewer
+// doesn't render.
 export function buildGraph(db) {
   const tasks = loadAllTasks(db);
   const dependencies = loadAllDependencies(db);
+  const requirementsByTask = groupRequirementsByTask(loadAllTaskRequirements(db));
 
   const nodes = tasks.map((t) => ({
     id: t.id,
@@ -43,6 +72,7 @@ export function buildGraph(db) {
     verifyCommand: t.verify_command,
     commitMessage: t.commit_message,
     intentGoal: t.intent_goal,
+    requirements: requirementsByTask.get(t.id) ?? [],
   }));
 
   // Edge direction follows the dependency, not the SQL column order: