@skyf0xx/hedgehog 6.3.4 → 6.4.0

package/bin/cli.mjs

@@ -14,6 +14,7 @@
 //   npx @skyf0xx/hedgehog --help
 
 import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile, mkdtemp } from 'node:fs/promises';
+import { Buffer } from 'node:buffer';
 import { constants, existsSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -104,7 +105,7 @@ import { NOOP_DIR } from '../src/db/noop.mjs';
 import { runFastpath, loadFastpaths, orphanedFastpathTasks, FASTPATH_DIR } from '../src/db/fastpath.mjs';
 import { HOSTS, HOST_FLAGS, DEFAULT_HOST, availableHosts } from '../src/hosts/index.mjs';
 import { recordHosts, installedHosts } from '../src/hosts/installed.mjs';
-import { wrapSection } from '../src/hosts/claude-md-merge.mjs';
+import { wrapSection, stripPhaseBlocks } from '../src/hosts/claude-md-merge.mjs';
 import {
   recordVersion,
   checkForUpdate,
@@ -372,6 +373,11 @@ function corePayload(core, h, { hostOnly = false } = {}) {
 // re-vendor, per each shelf's ATTRIBUTION.md) — none of those belong in
 // an update, so a core's `workspace` and `vendor_skills` are left alone
 // here while its agents and skills are refreshed.
+// The bootstrap file is excluded here on purpose: `hedgehog shed` (and
+// writePlannedFile's own self-heal) is the only thing allowed to remove
+// content from it, and an update pass that also touched it would race
+// that removal against whatever bootstrap-only content a fresh shell
+// still carries.
 function updatePlan(host = DEFAULT_HOST, core = null) {
   const h = HOSTS[host];
   return [
@@ -478,6 +484,98 @@ function warnOrphanedNotes({ orphanedNotes }) {
   console.log('');
 }
 
+const PHASE_NAME = 'bootstrap-only';
+
+// Engine-generic conditions for "this project's build graph is past
+// bootstrap" — never core-specific facts like nx.json or
+// astro.config.mjs, which the engine has no business knowing about. Both
+// must hold: a build graph exists, and at least one task has been
+// compiled into it. The bootstrap file's own {{PROJECT_SUMMARY}}
+// placeholder is the third condition (see shedCommand and
+// writePlannedFile's self-heal) but is checked per-file, since a
+// multi-host project can have several bootstrap files to test.
+async function graphPastBootstrap() {
+  if (!(await exists(DB_PATH))) return false;
+  const db = openDb();
+  try {
+    return db.prepare('SELECT 1 FROM tasks LIMIT 1').get() !== undefined;
+  } finally {
+    db.close();
+  }
+}
+
+async function canShed(bootstrapContent) {
+  if (!(await graphPastBootstrap())) return false;
+  return !bootstrapContent.includes('{{PROJECT_SUMMARY}}');
+}
+
+// `hedgehog shed` — strips bootstrap-only content from every host
+// bootstrap file actually on disk, once the project has provably moved
+// past bootstrap. Guard conditions are engine-generic only (see
+// graphPastBootstrap/canShed above); this command names which one failed
+// rather than a single generic refusal, in the style of `hedgehog
+// boundary`.
+async function shedCommand() {
+  if (!(await exists(DB_PATH))) {
+    console.error(
+      `${red('No build graph found.')} ${bold(dbAbsPath())} does not exist — run ${bold('hedgehog init')} or ${bold('hedgehog db init')} first.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!(await graphPastBootstrap())) {
+    console.error(
+      `${red('No task has been compiled into the build graph yet.')} Run ${bold('hedgehog plan')} first.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const hosts = await installedHosts(DEST_ROOT);
+  const bootstrapFiles = [
+    ...new Set(hosts.map((name) => HOSTS[name].bootstrapFile).filter(Boolean)),
+  ];
+
+  const present = [];
+  for (const rel of bootstrapFiles) {
+    const abs = join(DEST_ROOT, rel);
+    if (await exists(abs)) present.push({ rel, abs });
+  }
+  if (present.length === 0) {
+    console.error(`${red('No bootstrap file found.')} Expected one of: ${bootstrapFiles.join(', ')}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const unfilled = [];
+  for (const { rel, abs } of present) {
+    const content = await readFile(abs, 'utf8');
+    if (content.includes('{{PROJECT_SUMMARY}}')) unfilled.push(rel);
+  }
+  if (unfilled.length > 0) {
+    console.error(
+      `${red('{{PROJECT_SUMMARY}} is still unfilled in:')} ${unfilled.join(', ')} — nothing has been built yet.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let anyStripped = false;
+  for (const { rel, abs } of present) {
+    const before = await readFile(abs, 'utf8');
+    const after = stripPhaseBlocks(before, PHASE_NAME);
+    if (after === before) continue;
+    anyStripped = true;
+    await writeFile(abs, after);
+    const beforeBytes = Buffer.byteLength(before, 'utf8').toLocaleString('en-US');
+    const afterBytes = Buffer.byteLength(after, 'utf8').toLocaleString('en-US');
+    console.log(`${rel}  ${beforeBytes} → ${afterBytes} B`);
+  }
+  if (!anyStripped) {
+    console.log('nothing to shed');
+  }
+}
+
 // Writes one planned file to disk — a straight copy, or for a `merge`
 // entry, the shell template with {{CORE_SECTION}} replaced by the
 // chosen core's include.
@@ -528,7 +626,12 @@ async function writePlannedFile(f) {
       out = out.replaceAll('{{CORE_SECTION}}', wrapSection(section));
     }
     const dispatch = await readFile(join(PKG_ROOT, f.merge.dispatch), 'utf8');
-    await writeFile(f.dest, out.replaceAll('{{HOST_DISPATCH}}', dispatch.trimEnd()));
+    out = out.replaceAll('{{HOST_DISPATCH}}', dispatch.trimEnd());
+    // Self-heal: a project past bootstrap that re-runs `init --force`
+    // must not silently regain bootstrap-only content just because this
+    // write started from the pristine shell again.
+    if (await canShed(out)) out = stripPhaseBlocks(out, PHASE_NAME);
+    await writeFile(f.dest, out);
     return;
   }
   // Rendered from the payload rather than copied from it — the routing
@@ -675,6 +778,8 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog debt resolve <debt-id> --reason "<why>"   mark a debt note resolved
   npx @skyf0xx/hedgehog decision add <task-id> "<note>"   declare a decision that lands in dependent tasks' packets
   npx @skyf0xx/hedgehog decision list [<task-id>]     list declared decisions, oldest first
+  npx @skyf0xx/hedgehog shed                      strip bootstrap-only content from the installed
+                                                   bootstrap file(s), once the project is past bootstrap
   npx @skyf0xx/hedgehog db migrate                bring the graph's schema up to the latest version
   npx @skyf0xx/hedgehog community star --answer <a>   record the star prompt's answer
   npx @skyf0xx/hedgehog community showcase --repo <url> [--description <text>]
@@ -4547,6 +4652,11 @@ async function main() {
     return;
   }
 
+  if (cmd === 'shed') {
+    await shedCommand();
+    return;
+  }
+
   console.error(`${red('Unknown command:')} ${cmd}\n`);
   await help();
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "6.3.4",
+  "version": "6.4.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/agents/bootstrap.md

@@ -61,9 +61,11 @@ workspace is scaffolded (see `planner.md`'s Workflow step 7 and step 9).
 This compiles those intents into tasks so the core's loop skill has
 something to pick up from `hedgehog next`. Then run `hedgehog graph` to
 start (or reuse) the live graph server and open it, so the build graph is
-on screen before the first build step starts. Then state plainly that
-Bootstrap is closed and name the loop skill that owns everything from
-here. Don't hand off to another instance of yourself.
+on screen before the first build step starts. Run `hedgehog shed` to
+strip bootstrap-only content from the bootstrap file now that it no
+longer applies. Then state plainly that Bootstrap is closed and name the
+loop skill that owns everything from here. Don't hand off to another
+instance of yourself.
 
 
 ## Constraints

package/src/db/ready.mjs

@@ -7,6 +7,7 @@
 
 import { findClaimableTasks, findInFlightTasks } from './claim.mjs';
 import { conflicts, verifyRadius } from './conflict.mjs';
+import { ORCHESTRATING_FOOTER } from './status.mjs';
 
 // Walks the same candidates claimTasks would, in the same priority/id
 // order, greedily sorting each into CLAIMABLE (doesn't conflict with
@@ -92,5 +93,8 @@ export function formatReady({ claimable, heldBack }) {
     }
   }
 
+  lines.push('');
+  lines.push(ORCHESTRATING_FOOTER);
+
   return lines.join('\n');
 }

package/src/db/status.mjs

@@ -274,6 +274,12 @@ export async function graphWorktreeStatus(db, opts) {
   return worktreeStatus(db, opts);
 }
 
+// Printed at the bottom of both `hedgehog status` and `hedgehog ready` —
+// the two commands every session provably runs — since no static check
+// can verify an orchestrating session actually reads the skill this
+// names.
+export const ORCHESTRATING_FOOTER = 'See the hedgehog-orchestrating skill for the claim → dispatch → verify cycle.';
+
 const BLOCKED_REASON_LABELS = {
   verification_failed: 'verification failed',
   scope_violation: 'scope violation',
@@ -470,5 +476,8 @@ export function formatStatus({
     lines.push('  See: hedgehog reconcile list');
   }
 
+  lines.push('');
+  lines.push(ORCHESTRATING_FOOTER);
+
   return lines.join('\n');
 }

package/src/hosts/claude/DISPATCH.md

@@ -6,14 +6,5 @@ context with its own tool grant. The skills in `.claude/skills/` are
 available the same way; invoke one by name rather than reimplementing what
 it describes.
 
-Claude Code reads that registration once, at session start — an agent or
-skill file written mid-session (by `hedgehog init` or `hedgehog update`
-just now) is not yet dispatchable by name in this session. If a name-based
-dispatch reports it as not found, read the file directly from
-`.claude/agents/` or `.claude/skills/` and follow it inline instead of
-retrying the dispatch; it becomes dispatchable by name after a session
-restart or a fresh context.
-
-Clear context with `/clear` at the unit boundaries described above —
-`hedgehog boundary` tells you whether you're at one (exit 0), and
-`hedgehog boundary --handoff` is what the next session starts from.
+Clear context with `/clear` at the unit boundaries the
+`hedgehog-orchestrating` skill states.

package/src/hosts/claude-md-merge.mjs

@@ -64,6 +64,74 @@ export function appendCoreSection(existingContent, section) {
   return `${existingContent.trimEnd()}\n\n${block}\n`;
 }
 
+// One phase name only, `bootstrap-only` — there is exactly one
+// transition in a project's life (still bootstrapping vs. not), so a
+// predicate grammar for a one-bit state would be a maintenance burden
+// with no second case to justify it.
+const PHASE_MARKER_START = (phase) => `<!-- hedgehog:${phase} start -->`;
+const PHASE_MARKER_END = (phase) => `<!-- hedgehog:${phase} end -->`;
+
+// Removes every `<!-- hedgehog:<phase> start -->...end -->` block from
+// `content`, along with the blank lines immediately surrounding each
+// removed block, so stripping never leaves a double blank line behind.
+// Byte-for-byte identity when no markers are present is the contract
+// every core package not yet using markers relies on.
+//
+// A block is self-contained by convention (no section outside it may
+// reference into it), so removal never leaves a dangling reference for
+// this function to worry about — that's enforced by review of what gets
+// marked, not by this code.
+export function stripPhaseBlocks(content, phase) {
+  const start = PHASE_MARKER_START(phase);
+  const end = PHASE_MARKER_END(phase);
+  const startCount = countOccurrences(content, start);
+  const endCount = countOccurrences(content, end);
+  if (startCount === 0 && endCount === 0) return content;
+  if (startCount !== endCount) {
+    throw new Error(
+      `stripPhaseBlocks: ${startCount} "${start}" marker(s) but ${endCount} "${end}" marker(s) — unterminated or orphaned`,
+    );
+  }
+
+  // Flat, non-nesting blocks only: a start found before the matching end
+  // of the previous block indicates nesting, which this vocabulary
+  // deliberately does not support.
+  const blockRe = new RegExp(`${escapeRe(start)}[\\s\\S]*?${escapeRe(end)}`, 'g');
+  // Not a valid marker (the phase name can't contain whitespace), and not
+  // realistic page content either, so it can't collide with anything
+  // already in `content` — used as a removal placeholder instead of a
+  // control character, which linting disallows anywhere a regex pattern
+  // could embed it.
+  const PLACEHOLDER = '⁣hedgehog-stripped-block⁣';
+  let matchCount = 0;
+  let stripped = content.replace(blockRe, () => {
+    matchCount++;
+    return PLACEHOLDER;
+  });
+  if (matchCount !== startCount) {
+    throw new Error(
+      `stripPhaseBlocks: found ${startCount} "${start}" marker(s) but only ${matchCount} well-formed block(s) — check for nesting or an orphaned marker`,
+    );
+  }
+
+  // Each removed block leaves a placeholder; collapse it and the blank
+  // lines around it so no double blank line remains.
+  const placeholderRe = new RegExp(`[ \\t]*\\n?[ \\t]*${escapeRe(PLACEHOLDER.trim())}[ \\t]*\\n?[ \\t]*\\n?`, 'g');
+  stripped = stripped.replace(placeholderRe, '\n');
+  stripped = stripped.replace(/\n{3,}/g, '\n\n');
+  return stripped;
+}
+
+function countOccurrences(haystack, needle) {
+  let count = 0;
+  let i = 0;
+  while ((i = haystack.indexOf(needle, i)) !== -1) {
+    count++;
+    i += needle.length;
+  }
+  return count;
+}
+
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

package/src/hosts/cursor/DISPATCH.md

@@ -16,6 +16,5 @@ gates the commit either way.
 The skills in `.cursor/skills/` are procedures to follow — read the one
 whose situation applies rather than improvising the steps.
 
-Clear the conversation at the unit boundaries described above —
-`hedgehog boundary` tells you whether you're at one (exit 0), and
-`hedgehog boundary --handoff` is what the next session starts from.
+Clear the conversation at the unit boundaries the `hedgehog-orchestrating`
+skill states.

package/src/hosts/gemini/DISPATCH.md

@@ -22,8 +22,7 @@ commit lands.
 The skills in `.gemini/skills/` are procedures to follow — read the one
 whose situation applies rather than improvising the steps.
 
-Clear the conversation at the unit boundaries described above —
-`hedgehog boundary` tells you whether you're at one (exit 0), and
-`hedgehog boundary --handoff` is what the next session starts from.
+Clear the conversation at the unit boundaries the `hedgehog-orchestrating`
+skill states.
 
 @./AGENTS.md

package/src/hosts/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hedgehog",
-  "version": "6.3.4",
+  "version": "6.4.0",
   "description": "Hedgehog build discipline: ordered, tested, verified build steps.",
   "contextFileName": "GEMINI.md"
 }

package/src/skills/hedgehog-orchestrating/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: hedgehog-orchestrating
+description: Use at the start of any session on a project with a build graph (`.hedgehog/hedgehog.db`), and again at every claim/dispatch/verify cycle within it. Owns consuming the build graph — claiming task packets, delegating each to the layer's agent, running `hedgehog verify` to gate the commit, recording debt and decisions, the intent check at an intent's last layer, and when to clear context. Not for a build agent handed an already-claimed packet — that agent never claims, dispatches, or verifies; this skill is the orchestrating session's own.
+---
+
+# Orchestrating the build
+
+`.hedgehog/hedgehog.db` is the source of truth for what's next — never
+re-derive build state from prose. To work from it:
+
+1. Run `hedgehog claim --count N --owner <owner>`. It's atomic and
+   lease-based, and returns up to N tasks (each with its own full
+   STATUS/INTENT/RELEVANT RULES/INHERITED DEBT/INHERITED DECISIONS/WHY
+   NOW/BLOCKED DOWNSTREAM/ALLOWED SCOPE/VERIFICATION packet) that the
+   scheduler has already verified are safe to run together right now —
+   scope and verify-radius disjoint. `--count` is a maximum, not a
+   promise: a call may return fewer than N, or zero. `hedgehog ready` is
+   a read-only preview of the claimable/held-back split (and why a task
+   is held back — conflict with another claimable task, or exclusivity)
+   before you claim.
+2. Delegate each claimed packet to this core's loop skill (named in the
+   project's core section), one dispatch per packet, running concurrently.
+3. As each agent reports its packet done, run `hedgehog verify
+   <task-id> --owner <owner>` **serially** — one at a time, even though
+   the building happened concurrently, because verify writes git commits
+   and those must land one at a time. It checks the touched files
+   against the packet's ALLOWED SCOPE, runs the verification command,
+   and on a pass writes the commit and unlocks whatever the task was
+   blocking. An agent reporting success never moves the task — only a
+   passing `hedgehog verify` exit code does.
+
+`hedgehog claim` hands out only tasks safe to run together. Never run
+two tasks it didn't hand you together.
+
+The packet's **INTENT** block names the goal and outcome of the *whole*
+intent, not just this layer. A layer's own verify command runs the tests
+that layer wrote, so it measures internal consistency and never coverage
+of what was asked — a layer that builds half the intent and tests that
+half exhaustively is green. Build the layer's share of the goal, and say
+so when the packet doesn't account for something the goal asks for.
+When `hedgehog verify` closes the **last** layer of an intent it prints
+that goal and outcome back as an **INTENT CHECK**: read the built work
+against it there, because nothing else in the build does.
+
+A layer that discovers a limitation the next layer has to compensate for
+records it with `hedgehog debt add <task-id> "<note>"` — it lands in the
+**INHERITED DEBT** section of every packet that depends on that task. A
+comment in a source file is not a mechanism; nothing reads it.
+
+A layer that makes a choice a dependent layer needs to know about — a
+pattern, a library, a trade-off, anything the next task should follow
+rather than reinvent or contradict — records it with `hedgehog decision
+add <task-id> "<note>"`, landing in the **INHERITED DECISIONS** section
+the same way. Debt is what's still wrong with a task; a decision is why
+it was built the way it was.
+
+`planner` owns writing intents (`hedgehog intent add`) at planning
+intake; `hedgehog plan` compiles them into the task graph the loop
+consumes. Nothing checks a box — there is no checklist, only queryable
+state.
+
+**When the build is done:** once `hedgehog status` shows every task
+`complete` and `hedgehog boundary` exits 0 (see **Managing context**
+below — it checks nothing-in-flight, a clean tree, and a closed intent
+together), the build session is complete. The permanent record is the
+committed intents (`.hedgehog/intents/*.json`), the friction log
+(`.hedgehog/friction/*.md`), the core definition (root `core.yaml` for a
+shipped core, `.hedgehog/core.yaml` for an authored one), and the git
+commit history itself — not the database. `.hedgehog/hedgehog.db` is
+gitignored: a derived index, rebuildable at any time via `hedgehog db
+rebuild`, which replays those committed sources against git history.
+That rebuild also runs automatically on a fresh clone when the DB is
+missing but `.hedgehog/intents/` exists. That's what makes every later
+session cheap.
+
+A completed build is **extendable, not sealed**. Offer the user a
+fresh-context handoff, and name both ways forward:
+
+- **Adjustments to what's built** → the `tweaker` agent, from a *new*
+  chat window, not a subagent call inside this one — this session's
+  context has been building the whole project and is exactly what
+  "clearing context now costs nothing" (below) means to discard. Tell
+  the user plainly: close this chat window and open a new one, then
+  paste this to start it:
+
+  > The build for {{PROJECT_NAME}} is complete. Use the tweaker agent:
+  > first review the friction log and ask me for feedback on the build,
+  > then take my tweak requests one at a time.
+
+  In the new window, `tweaker` starts clean, once reviews the friction
+  log (`hedgehog friction list`) for possible discipline-improvement
+  issues and separately asks the user directly for feedback on the
+  build, filing each real pattern or piece of feedback as its own GitHub
+  issue against the Hedgehog repo itself, never this project's repo
+  (friction as `bug`/`help wanted`, feedback as `suggestion`, each only
+  after showing the exact content and getting explicit approval), then
+  takes any tweak requests one at a time.
+- **New scope** — a new module or feature, anything beyond adjusting what
+  exists → on a core with a module axis, the `planner` agent, which runs
+  `hedgehog-planning-intake`'s **Re-entry pass**. It reads the existing
+  planning archive as context and elicits only what's new, then adds
+  intents and runs `hedgehog plan`. This is append-only: `plan` skips
+  intents already compiled, so every `complete` task keeps its status and
+  its commits, and `hedgehog claim` resumes at the first tasks of the new
+  work. Planning is not re-run from scratch, and the workspace is not
+  re-scaffolded. (This core's own section states where new scope goes if
+  this core has no module axis to add an intent to.)
+
+If a request turns out to be structural rather than either of those —
+something already built is wrong at its source — that's the Correction
+Protocol's post-build entry, in this core's own loop skill.
+
+## Managing context
+
+Hedgehog is designed so the conversation is disposable. Keep the working
+context small:
+
+- **Clear context at natural boundaries** — a module's Phase A, a
+  landing page section, whatever this core's own unit boundary is — once
+  that unit is done and committed. Ask `hedgehog boundary` rather than
+  judging it: it exits 0 only when all three of nothing-in-flight, a
+  clean working tree, and a last closed task that completed its intent
+  hold, and names which one failed otherwise. Clear the conversation and
+  start fresh, then run `hedgehog status`/`hedgehog claim` and continue.
+  Nothing is lost, because the build graph, commits, and code hold all
+  the state. Prefer this over letting one session accumulate the entire
+  project.
+- **`hedgehog quiesce` and `hedgehog boundary` answer different
+  questions.** `quiesce` reports whether anything is still in flight —
+  necessary before clearing (clearing while a lease is outstanding
+  orphans that lease until it expires), but not sufficient: a graph can
+  be perfectly settled halfway through an intent, with a dirty working
+  tree. `boundary` is the whole question — is this a moment to throw the
+  conversation away — and it includes the `quiesce` check as its first
+  condition. Use `quiesce` when you're waiting for dispatched work to
+  land (the Correction Protocol), `boundary` when you're deciding whether
+  to clear.
+- **A cleared or new session recovers by running `hedgehog status` and
+  reading the commit log**, never by needing the prior conversation.
+  `hedgehog boundary --handoff` prints that recovery block directly —
+  where the build is, what's next and why, what's in flight, what's
+  blocked — derived from the graph, so no session hands a summary to the
+  next one.
+- **Delegate heavy work to agents.** Scaffolding and every build step
+  run in their own isolated context, so work doesn't pile up in the
+  main thread. Planning intake's BMAD Phase 0 is the exception — the
+  project's own instructions file states it — and stays in that session
+  through Confirm & Lock; the mining, `bootstrap`, and per-module steps
+  after it delegate as usual.
+- **Don't paste large context back in.** If you find yourself
+  re-explaining the architecture, stop — it's fixed and stated in the
+  project's core section, not something to reconstruct. If you need a
+  project specific, read it from the code. That's the self-documenting
+  design working as intended.

package/src/templates/CLAUDE.md

@@ -1,3 +1,4 @@
+<!-- hedgehog:bootstrap-only start -->
 <!--
   Hedgehog project CLAUDE.md template.
 
@@ -11,6 +12,7 @@
 
   Delete this comment block after the placeholders are filled in.
 -->
+<!-- hedgehog:bootstrap-only end -->
 
 # {{PROJECT_NAME}}
 
@@ -24,6 +26,7 @@ This project is built with **Hedgehog**: a one-step-at-a-time build
 discipline. The rules below aren't project preferences — they're how the
 build stays mechanically correct. Follow them exactly.
 
+<!-- hedgehog:bootstrap-only start -->
 ## First message in a fresh install
 
 If `{{PROJECT_SUMMARY}}` above is still an unfilled placeholder, this is a
@@ -51,6 +54,7 @@ read the file and carry on.
 Don't re-explain the discipline or summarize this file; the greeting is
 one line, not a tour. Skip this entirely once the placeholder is filled
 in — every later session starts with `hedgehog status`, not a greeting.
+<!-- hedgehog:bootstrap-only end -->
 
 ## How to work here
 
@@ -74,8 +78,8 @@ whole plan in context — the plan lives in the structure:
 
 Because state lives in those places and not in the conversation, a fresh
 context loses nothing: the architecture is known a priori, and the
-project's specifics are re-read on demand. Use that (see **Managing
-context** below).
+project's specifics are re-read on demand. The `hedgehog-orchestrating`
+skill (see **Running the build** below) is what uses that.
 
 **Use only the skills and agents this repo provides**, including its
 vendored BMAD shelf — never a general-purpose build-tool skill pack
@@ -97,154 +101,12 @@ taking the faster path.
 
 {{CORE_SECTION}}
 
-## Consuming the graph
-
-`.hedgehog/hedgehog.db` is the source of truth for what's next — never
-re-derive build state from prose. To work from it:
-
-1. Run `hedgehog claim --count N --owner <owner>`. It's atomic and
-   lease-based, and returns up to N tasks (each with its own full
-   STATUS/INTENT/RELEVANT RULES/INHERITED DEBT/INHERITED DECISIONS/WHY
-   NOW/BLOCKED DOWNSTREAM/ALLOWED SCOPE/VERIFICATION packet) that the
-   scheduler has already verified are safe to run together right now —
-   scope and verify-radius disjoint. `--count` is a maximum, not a
-   promise: a call may return fewer than N, or zero. `hedgehog ready` is
-   a read-only preview of the claimable/held-back split (and why a task
-   is held back — conflict with another claimable task, or exclusivity)
-   before you claim.
-2. Delegate each claimed packet to this core's loop skill (named in the
-   section above), one dispatch per packet, running concurrently.
-3. As each agent reports its packet done, run `hedgehog verify
-   <task-id> --owner <owner>` **serially** — one at a time, even though
-   the building happened concurrently, because verify writes git commits
-   and those must land one at a time. It checks the touched files
-   against the packet's ALLOWED SCOPE, runs the verification command,
-   and on a pass writes the commit and unlocks whatever the task was
-   blocking. An agent reporting success never moves the task — only a
-   passing `hedgehog verify` exit code does.
-
-`hedgehog claim` hands out only tasks safe to run together. Never run
-two tasks it didn't hand you together.
-
-The packet's **INTENT** block names the goal and outcome of the *whole*
-intent, not just this layer. A layer's own verify command runs the tests
-that layer wrote, so it measures internal consistency and never coverage
-of what was asked — a layer that builds half the intent and tests that
-half exhaustively is green. Build the layer's share of the goal, and say
-so when the packet doesn't account for something the goal asks for.
-When `hedgehog verify` closes the **last** layer of an intent it prints
-that goal and outcome back as an **INTENT CHECK**: read the built work
-against it there, because nothing else in the build does.
-
-A layer that discovers a limitation the next layer has to compensate for
-records it with `hedgehog debt add <task-id> "<note>"` — it lands in the
-**INHERITED DEBT** section of every packet that depends on that task. A
-comment in a source file is not a mechanism; nothing reads it.
-
-A layer that makes a choice a dependent layer needs to know about — a
-pattern, a library, a trade-off, anything the next task should follow
-rather than reinvent or contradict — records it with `hedgehog decision
-add <task-id> "<note>"`, landing in the **INHERITED DECISIONS** section
-the same way. Debt is what's still wrong with a task; a decision is why
-it was built the way it was.
-
-`planner` owns writing intents (`hedgehog intent add`) at planning
-intake; `hedgehog plan` compiles them into the task graph the loop
-consumes. Nothing checks a box — there is no checklist, only queryable
-state.
-
-**When the build is done:** once `hedgehog status` shows every task
-`complete` and `hedgehog boundary` exits 0 (see **Managing context**
-below — it checks nothing-in-flight, a clean tree, and a closed intent
-together), the build session is complete. The permanent record is the committed
-intents (`.hedgehog/intents/*.json`), the friction log
-(`.hedgehog/friction/*.md`), the core definition (root `core.yaml` for a
-shipped core, `.hedgehog/core.yaml` for an authored one), and the git
-commit history itself — not the database. `.hedgehog/hedgehog.db` is gitignored: a
-derived index, rebuildable at any time via `hedgehog db rebuild`, which
-replays those committed sources against git history. That rebuild also
-runs automatically on a fresh clone when the DB is missing but
-`.hedgehog/intents/` exists. That's what makes every later session
-cheap.
-
-A completed build is **extendable, not sealed**. Offer the user a
-fresh-context handoff, and name both ways forward:
-
-- **Adjustments to what's built** → the `tweaker` agent, from a *new*
-  chat window, not a subagent call inside this one — this session's
-  context has been building the whole project and is exactly what
-  "clearing context now costs nothing" (above) means to discard. Tell
-  the user plainly: close this chat window and open a new one, then
-  paste this to start it:
-
-  > The build for {{PROJECT_NAME}} is complete. Use the tweaker agent:
-  > first review the friction log and ask me for feedback on the build,
-  > then take my tweak requests one at a time.
-
-  In the new window, `tweaker` starts clean, once reviews the friction
-  log (`hedgehog friction list`) for possible discipline-improvement
-  issues and separately asks the user directly for feedback on the
-  build, filing each real pattern or piece of feedback as its own GitHub
-  issue against the Hedgehog repo itself, never this project's repo
-  (friction as `bug`/`help wanted`, feedback as `suggestion`, each only
-  after showing the exact content and getting explicit approval), then
-  takes any tweak requests one at a time.
-- **New scope** — a new module or feature, anything beyond adjusting what
-  exists → on a core with a module axis, the `planner` agent, which runs
-  `hedgehog-planning-intake`'s **Re-entry pass**. It reads the existing
-  planning archive as context and elicits only what's new, then adds
-  intents and runs `hedgehog plan`. This is append-only: `plan` skips
-  intents already compiled, so every `complete` task keeps its status and
-  its commits, and `hedgehog claim` resumes at the first tasks of the new
-  work. Planning is not re-run from scratch, and the workspace is not
-  re-scaffolded. (This core's own section above states where new scope
-  goes if this core has no module axis to add an intent to.)
-
-If a request turns out to be structural rather than either of those —
-something already built is wrong at its source — that's the Correction
-Protocol's post-build entry, in this core's own loop skill.
-
-## Managing context
-
-Hedgehog is designed so the conversation is disposable. Keep the working
-context small:
-
-- **Clear context at natural boundaries** — a module's Phase A, a
-  landing page section, whatever this core's own unit boundary is — once
-  that unit is done and committed. Ask `hedgehog boundary` rather than
-  judging it: it exits 0 only when all three of nothing-in-flight, a
-  clean working tree, and a last closed task that completed its intent
-  hold, and names which one failed otherwise. Clear the conversation and
-  start fresh, then run `hedgehog status`/`hedgehog claim` and continue.
-  Nothing is lost, because the build graph, commits, and code hold all
-  the state. Prefer this over letting one session accumulate the entire
-  project.
-- **`hedgehog quiesce` and `hedgehog boundary` answer different
-  questions.** `quiesce` reports whether anything is still in flight —
-  necessary before clearing (clearing while a lease is outstanding
-  orphans that lease until it expires), but not sufficient: a graph can
-  be perfectly settled halfway through an intent, with a dirty working
-  tree. `boundary` is the whole question — is this a moment to throw the
-  conversation away — and it includes the `quiesce` check as its first
-  condition. Use `quiesce` when you're waiting for dispatched work to
-  land (the Correction Protocol), `boundary` when you're deciding whether
-  to clear.
-- **A cleared or new session recovers by running `hedgehog status` and
-  reading the commit log**, never by needing the prior conversation.
-  `hedgehog boundary --handoff` prints that recovery block directly —
-  where the build is, what's next and why, what's in flight, what's
-  blocked — derived from the graph, so no session hands a summary to the
-  next one.
-- **Delegate heavy work to agents.** Scaffolding and every build step
-  run in their own isolated context, so work doesn't pile up in the
-  main thread. Planning intake's BMAD Phase 0 is the exception — see
-  **First message in a fresh install** above — and stays here through
-  Confirm & Lock; the mining, `bootstrap`, and per-module steps after it
-  delegate as usual.
-- **Don't paste large context back in.** If you find yourself
-  re-explaining the architecture, stop — it's fixed and stated in this
-  file's core section, not something to reconstruct. If you need a
-  project specific, read it from the code. That's the self-documenting
-  design working as intended.
+## Running the build
+
+The build graph is the source of truth for what's next — never re-derive
+build state from prose. The `hedgehog-orchestrating` skill owns the claim →
+dispatch → verify cycle, the intent check, debt and decision recording, the
+context boundaries to clear at, and the post-build handoff. Read it at the
+start of every session and follow it.
 
 {{HOST_DISPATCH}}