@skyf0xx/hedgehog 6.3.3 → 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';
@@ -58,7 +59,7 @@ import {
   formatMissingRequirements,
 } from '../src/db/requires.mjs';
 import { whyPath, formatWhy } from '../src/db/why.mjs';
-import { addFriction, listFriction } from '../src/db/friction.mjs';
+import { addFriction, listFriction, resolveFriction } from '../src/db/friction.mjs';
 import { addDebt, listDebt, resolveDebt } from '../src/db/debt.mjs';
 import { addDecision, listDecisions } from '../src/db/decision.mjs';
 import {
@@ -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
@@ -668,12 +771,15 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog graph --no-open           start (or reuse) the server; print the URL instead
   npx @skyf0xx/hedgehog why <path>                provenance chain for a file
   npx @skyf0xx/hedgehog friction add "<note>"     log a friction note [--task <task-id>]
-  npx @skyf0xx/hedgehog friction list             list logged friction, oldest first
+  npx @skyf0xx/hedgehog friction list [--all]     list open friction, oldest first (--all includes resolved)
+  npx @skyf0xx/hedgehog friction resolve <friction-id> --reason "<why>"   mark a friction note resolved
   npx @skyf0xx/hedgehog debt add <task-id> "<note>"   declare debt that lands in dependent tasks' packets
   npx @skyf0xx/hedgehog debt list [<task-id>] [--all]   list open debt, oldest first (--all includes resolved)
   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>]
@@ -3299,27 +3405,60 @@ async function frictionCommand(args) {
   }
 
   if (sub === 'list') {
+    const includeResolved = args.includes('--all') || args.includes('--resolved');
     const db = openDb();
     let entries;
     try {
-      entries = listFriction(db);
+      entries = listFriction(db, { includeResolved });
     } finally {
       db.close();
     }
 
     if (entries.length === 0) {
-      console.log(`${dim('No friction logged.')}\n`);
+      console.log(`${dim(includeResolved ? 'No friction logged.' : 'No open friction.')}\n`);
       return;
     }
     for (const entry of entries) {
       console.log(`#${entry.id}  ${dim(entry.loggedAt)}${entry.taskId ? `  ${bold(entry.taskId)}` : ''}`);
-      console.log(`  ${entry.note}\n`);
+      console.log(`  ${entry.note}`);
+      if (entry.resolvedAt) {
+        console.log(`  ${green('resolved')} ${dim(entry.resolvedAt)} — ${entry.resolvedReason}`);
+      }
+      console.log('');
     }
     return;
   }
 
+  if (sub === 'resolve') {
+    const frictionId = args[1];
+    const reasonIdx = args.indexOf('--reason');
+    const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : undefined;
+
+    if (!frictionId || frictionId.startsWith('--') || !reason) {
+      console.error(`${red('Usage:')} hedgehog friction resolve <friction-id> --reason "<why>"\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const db = openDb();
+    let result;
+    try {
+      result = await resolveFriction(db, { frictionId: Number(frictionId), reason });
+    } catch (err) {
+      console.error(`${red('Failed to resolve friction:')} ${err.message}\n`);
+      process.exitCode = 1;
+      return;
+    } finally {
+      db.close();
+    }
+
+    console.log(`  ${green('resolved')}  #${result.id}${result.taskId ? ` (${result.taskId})` : ''}`);
+    console.log(`  ${dim(result.note)}`);
+    return;
+  }
+
   console.error(
-    `${red('Unknown friction subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog friction add "<note>" [--task <task-id>]\n   or: hedgehog friction list\n`,
+    `${red('Unknown friction subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog friction add "<note>" [--task <task-id>]\n   or: hedgehog friction list [--all]\n   or: hedgehog friction resolve <friction-id> --reason "<why>"\n`,
   );
   process.exitCode = 1;
 }
@@ -4513,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.3",
+  "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/friction.mjs

@@ -33,8 +33,44 @@ export async function addFriction(db, { note, taskId }) {
 }
 
 // Returns every friction row, oldest first, for tweaker's review pass.
-export function listFriction(db) {
+// Resolved rows are excluded by default — same convention as
+// listDebt — and included when `includeResolved` is set (`--all`).
+export function listFriction(db, { includeResolved = false } = {}) {
+  const where = includeResolved ? '' : 'WHERE resolved_at IS NULL';
   return db
-    .prepare(`SELECT id, task_id AS taskId, note, logged_at AS loggedAt FROM friction ORDER BY id ASC`)
+    .prepare(
+      `SELECT id, task_id AS taskId, note, logged_at AS loggedAt,
+              resolved_at AS resolvedAt, resolved_reason AS resolvedReason
+       FROM friction ${where} ORDER BY id ASC`,
+    )
     .all();
 }
+
+// Resolves one friction row by id: marks it resolved in the DB and
+// appends the marker to the same committed log (FRICTION_LOG_PATH) the
+// original entry was written to — friction has no `.hedgehog/notes/`
+// record the way debt does, so this is the row's only committed source
+// and `db rebuild` leaves friction rows untouched (see rebuild.mjs).
+export async function resolveFriction(db, { frictionId, reason }) {
+  if (!frictionId) throw new Error('friction resolve requires a friction id');
+  if (!reason) throw new Error('friction resolve requires a --reason');
+
+  const row = db
+    .prepare('SELECT id, task_id AS taskId, note, resolved_at AS resolvedAt FROM friction WHERE id = ?')
+    .get(frictionId);
+  if (!row) throw new Error(`no such friction entry: #${frictionId}`);
+  if (row.resolvedAt) throw new Error(`friction #${frictionId} is already resolved`);
+
+  const resolvedAt = new Date().toISOString();
+  db.prepare('UPDATE friction SET resolved_at = ?, resolved_reason = ? WHERE id = ?').run(
+    resolvedAt,
+    reason,
+    frictionId,
+  );
+
+  await mkdir(FRICTION_DIR, { recursive: true });
+  const header = `## ${resolvedAt} resolved #${frictionId}${row.taskId ? ` ${row.taskId}` : ''}`;
+  await appendFile(FRICTION_LOG_PATH, `${header}\n\n${reason}\n\n`);
+
+  return { id: row.id, taskId: row.taskId, note: row.note, resolvedAt, resolvedReason: reason };
+}

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/satisfied.mjs

@@ -0,0 +1,116 @@
+// Possibly-satisfied detection: a `planned` task whose scope_globs are
+// already fully covered by git-tracked, committed files with nothing
+// pending inside that scope — the heuristic nudge toward `hedgehog
+// reconcile` for work that landed under a different task's or a
+// different intent's commit, so `db rebuild`'s exact-commit-subject
+// attribution (rebuild.mjs#markCompletedTasks) never had a subject to
+// credit it against and the task sits `planned` forever with no signal.
+//
+// This is evidence, not proof, exactly like reconcile.mjs's
+// gatherEvidence: a scope glob resolving to tracked, clean paths says
+// the files a task would have written already exist and nothing is
+// mid-edit there. It says nothing about whether the task's objective was
+// actually met by that content — a `planned` task can legitimately share
+// a glob with pre-existing, unrelated code that still needs real work.
+// False positives are expected and acceptable; this only flags "look at
+// this", it never completes anything itself.
+//
+// Uses the same git pathspec mechanism verify.mjs's own scope gate uses
+// (`:(glob)<glob>` handed to git literally, no in-process glob dialect of
+// its own to keep in sync with core.mjs's), rather than matchesGlob's
+// witness-path walk — a witness path proves non-containment against a
+// *set* of globs (core.mjs's own use, and coverage's), not "which real
+// files in this repo currently match one glob", which only git's own
+// pathspec matcher can answer without re-walking the whole tree.
+
+import { execFileSync } from 'node:child_process';
+import { isEngineStatePath } from './engineState.mjs';
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8' });
+}
+
+function pathspecsFor(scopeGlobs) {
+  return scopeGlobs.map((glob) => `:(glob)${glob}`);
+}
+
+// Tracked files under a task's scope, minus engine-state paths — the
+// same exclusion verify.mjs's gate applies, so a task whose scope happens
+// to reach into `.hedgehog/` never gets flagged on the build graph's own
+// bookkeeping.
+function trackedPathsInScope(scopeGlobs) {
+  let output;
+  try {
+    output = git(['ls-files', '--', ...pathspecsFor(scopeGlobs)]);
+  } catch {
+    return [];
+  }
+  return output
+    .split('\n')
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .filter((p) => !isEngineStatePath(p));
+}
+
+// Modified, staged, or untracked paths under a task's scope — anything
+// `git status --porcelain` reports there means the scope is still
+// mid-edit, the opposite of "already satisfied".
+function dirtyPathsInScope(scopeGlobs) {
+  let output;
+  try {
+    output = git(['status', '--porcelain', '--', ...pathspecsFor(scopeGlobs)]);
+  } catch {
+    return [];
+  }
+  return output
+    .split('\n')
+    .map((line) => line.slice(3).trim())
+    .filter(Boolean)
+    .filter((p) => !isEngineStatePath(p));
+}
+
+// Every `planned` task whose scope_globs resolve to at least one tracked
+// file and zero dirty ones — a task with an empty scope match (nothing in
+// the repo yet touches its globs at all) is not flagged, since that is
+// simply unstarted work, not possibly-satisfied work.
+//
+// Only `planned` is read, not `ready`: a `ready` task already cleared
+// every dependency and is next.mjs/claim.mjs's own queue to hand out —
+// flagging it here would tell an operator to reconcile work a claim is
+// about to pick up anyway. `building`/`verifying` are leased and mid-flight
+// by definition; `blocked` has its own NEEDS ATTENTION path; `complete` is
+// done. `planned` is the one status this signal exists for: work nothing
+// has looked at yet, sitting behind whatever unlocked it.
+const PLANNED_TASKS_SQL = `
+  SELECT id, layer, objective, scope_globs FROM tasks
+  WHERE status = 'planned'
+  ORDER BY priority, id;
+`;
+
+export function possiblySatisfiedTasks(db) {
+  const tasks = db.prepare(PLANNED_TASKS_SQL).all();
+  const flagged = [];
+  for (const task of tasks) {
+    const scopeGlobs = JSON.parse(task.scope_globs);
+    if (scopeGlobs.length === 0) continue;
+    const tracked = trackedPathsInScope(scopeGlobs);
+    if (tracked.length === 0) continue;
+    const dirty = dirtyPathsInScope(scopeGlobs);
+    if (dirty.length > 0) continue;
+    flagged.push({ id: task.id, layer: task.layer, objective: task.objective, paths: tracked });
+  }
+  return flagged;
+}
+
+export function formatPossiblySatisfied(flagged) {
+  const lines = [`POSSIBLY SATISFIED  ${flagged.length}`];
+  for (const { id, layer, paths } of flagged) {
+    lines.push(`  ${id}   ${layer}   ${paths.length} tracked path${paths.length === 1 ? '' : 's'} in scope, none pending`);
+  }
+  lines.push('');
+  lines.push(
+    '  Scope glob already covered by clean, tracked files — not proof the objective was met.' +
+      ' See: hedgehog reconcile',
+  );
+  return lines.join('\n');
+}

package/src/db/schema.mjs

@@ -127,10 +127,12 @@ CREATE TABLE IF NOT EXISTS decisions (
 );
 
 CREATE TABLE IF NOT EXISTS friction (
-  id        INTEGER PRIMARY KEY,
-  task_id   TEXT REFERENCES tasks(id) ON DELETE SET NULL,
-  note      TEXT NOT NULL,
-  logged_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id               INTEGER PRIMARY KEY,
+  task_id          TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  note             TEXT NOT NULL,
+  logged_at        TEXT NOT NULL DEFAULT (datetime('now')),
+  resolved_at      TEXT,
+  resolved_reason  TEXT
 );
 `;
 
@@ -178,7 +180,7 @@ export function ensureTaskColumns(db) {
 // hand-set past what MIGRATIONS actually covers, since runMigrations
 // trusts this number to mean "every migration through this version has
 // run."
-export const CURRENT_SCHEMA_VERSION = 3;
+export const CURRENT_SCHEMA_VERSION = 4;
 
 // Forward migrations, applied in order to bring a graph's user_version up
 // to CURRENT_SCHEMA_VERSION. Unlike the CREATE TABLE IF NOT EXISTS /
@@ -223,6 +225,18 @@ const MIGRATIONS = [
       }
     },
   },
+  {
+    version: 4,
+    // Same shape as version 3's debt columns, for friction — an existing
+    // graph's rows default to open the moment these columns exist.
+    migrate: (db) => {
+      const existing = new Set(db.prepare('PRAGMA table_info(friction)').all().map((row) => row.name));
+      if (!existing.has('resolved_at')) db.exec('ALTER TABLE friction ADD COLUMN resolved_at TEXT');
+      if (!existing.has('resolved_reason')) {
+        db.exec('ALTER TABLE friction ADD COLUMN resolved_reason TEXT');
+      }
+    },
+  },
 ];
 
 // Brings a graph's `PRAGMA user_version` up to CURRENT_SCHEMA_VERSION,

package/src/db/status.mjs

@@ -17,6 +17,7 @@ import { listFriction } from './friction.mjs';
 import { orphanedOverrides } from './overrides.mjs';
 import { RECONCILED_DIR, RECONCILED_NOTE_PREFIX } from './reconcile.mjs';
 import { formatMissingRequirements } from './requires.mjs';
+import { possiblySatisfiedTasks, formatPossiblySatisfied } from './satisfied.mjs';
 import { readyTasks, heldBackReason } from './ready.mjs';
 import { worktreeStatus } from './worktree.mjs';
 import { findClaimableTasks } from './claim.mjs';
@@ -219,6 +220,15 @@ function countFriction(db) {
 // in every count and list here. Reported unconditionally, not as a
 // warning: reconciling is a supported act, and the point is that the
 // distinction stays visible after the session that made it is gone.
+//
+// `possiblySatisfied` (satisfied.mjs) is a `planned` task whose scope
+// globs already resolve to tracked, clean files — a heuristic nudge, not
+// a completion: `db rebuild`'s attribution only credits a task whose own
+// commit_message appears as some commit's subject (rebuild.mjs), so work
+// that landed inside a commit made for a different task never has a
+// subject to match, and the task stays `planned` with no other signal
+// that its scope may already be covered. Read-only, like drift and
+// orphaned overrides — nothing here is ever auto-completed.
 // Synchronous, as it always was: `boundary.mjs#boundaryState` (a hot path
 // that only ever reads `graph.inFlight`) depends on that, and every other
 // section here is a plain SQL read with no I/O to await. The worktree
@@ -236,6 +246,7 @@ export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
   const debt = loadDebtByTask(db);
   const frictionCount = countFriction(db);
   const reconciled = loadReconciledTasks(db);
+  const possiblySatisfied = possiblySatisfiedTasks(db);
   const total = Object.values(counts).reduce((a, b) => a + b, 0);
   return {
     counts,
@@ -248,6 +259,7 @@ export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
     debt,
     frictionCount,
     reconciled,
+    possiblySatisfied,
     total,
   };
 }
@@ -262,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',
@@ -293,6 +311,7 @@ export function formatStatus({
   debt = [],
   frictionCount = 0,
   reconciled = [],
+  possiblySatisfied = [],
   worktrees = { active: [], orphaned: [] },
   total,
   missingRequirements,
@@ -381,6 +400,15 @@ export function formatStatus({
     lines.push(formatDrift(drift));
   }
 
+  // Below drift, same family of "condition of the graph as a whole" —
+  // and above orphaned overrides, since a possibly-satisfied task is work
+  // an operator can act on right now (`hedgehog reconcile`), where an
+  // orphaned override is only ever inert.
+  if (possiblySatisfied.length > 0) {
+    lines.push('');
+    lines.push(formatPossiblySatisfied(possiblySatisfied));
+  }
+
   // Below drift because it's the rarer of the two and never blocks the
   // build: an orphaned override is work the operator asked for that isn't
   // happening, not work the graph is getting wrong. `hedgehog override
@@ -448,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.3",
+  "version": "6.4.0",
   "description": "Hedgehog build discipline: ordered, tested, verified build steps.",
   "contextFileName": "GEMINI.md"
 }

package/src/registry/cores.json

@@ -47,7 +47,7 @@
     {
       "name": "adopted",
       "package": "@skyf0xx/hedgehog-core-adopted",
-      "version": "^1.1.0",
+      "version": ">=1.0.0 <2.0.0",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-adopted",
       "selects_when": "The description is about bringing Hedgehog's discipline to a codebase that already exists, rather than building something new — the repo already has real source files, or the user says so explicitly: \"adopt this repo\", \"add Hedgehog to my existing project\", \"I want scope/verify enforcement on my changes here\". Not chosen by matching a `when` paragraph the way a shipped core is: hedgehog-adopt reads the repo read-only, proposes a linear-chain .hedgehog/core.yaml whose verify commands are the repo's own, and writes only .hedgehog/ — never a workspace, never a stack migration. This is the core most often confused with authored: adopted brings discipline to an existing repo, while authored designs and scaffolds a workspace from scratch for something being built new — route here only when the work is landing on a codebase that already exists."

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}}