@skyf0xx/hedgehog 4.3.1 → 4.3.4

package/bin/cli.mjs

@@ -13,13 +13,13 @@
 //   npx @skyf0xx/hedgehog --help
 
 import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile } from 'node:fs/promises';
-import { constants } from 'node:fs';
+import { constants, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { dbInit, DB_PATH, dbAbsPath, openDb } from '../src/db/init.mjs';
-import { loadCore, lintCore } from '../src/db/core.mjs';
-import { planTasks } from '../src/db/plan.mjs';
+import { loadCore, lintCore, isModuleAxis } from '../src/db/core.mjs';
+import { planTasks, CORE_INTENT_ID } from '../src/db/plan.mjs';
 import { addIntent, INTENTS_DIR } from '../src/db/intent.mjs';
 import {
   nextTask,
@@ -281,6 +281,26 @@ function warnRebuildDrift({ drift }, corePath) {
   );
 }
 
+// Debt and friction notes are operator-recorded and have no committed
+// source, so a rebuild carries them across by task id. A note whose task
+// is no longer in the recompiled graph — its intent file was renamed,
+// deleted, or its layer sequence changed — has nowhere to re-attach.
+// Friction notes survive unattached (their task_id is nullable); debt
+// notes are lost, so both are printed with their text rather than
+// disappearing into a count.
+function warnOrphanedNotes({ orphanedNotes }) {
+  if (!orphanedNotes || orphanedNotes.length === 0) return;
+  console.log(
+    `${yellow(bold('Notes without a task after rebuild.'))} ${orphanedNotes.length} note(s) referenced a\n` +
+      'task the recompiled graph no longer holds. Friction notes were kept unattached;\n' +
+      'debt notes could not be, so they are reproduced here:\n',
+  );
+  for (const note of orphanedNotes) {
+    console.log(`  ${dim(note.kind)}  ${bold(note.taskId)}  ${note.note}`);
+  }
+  console.log('');
+}
+
 // 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,16 +548,33 @@ async function init({ force, core, explicitCore, host = DEFAULT_HOST, hostOnly =
     );
     console.log(dim('     instead of polling tightly or narrating the wait.'));
     console.log(`  2. ${bold('git add -A && git commit -m "chore: install Hedgehog"')}`);
-    console.log(`  3. Open ${HOSTS[host].label} and describe what you want to build.`);
+    console.log(
+      `  3. Start a ${bold('new')} ${HOSTS[host].label} session 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 ${HOSTS[host].label} and describe what you want to build.`);
+    console.log(
+      `  2. Start a ${bold('new')} ${HOSTS[host].label} session and describe what you want to build.`,
+    );
   }
   console.log(
     dim(
       `     The ${bold('planner')} agent runs planning intake, then hands off to bootstrap.`,
     ),
   );
+  // A host enumerates its agents once, at session start. This install just
+  // wrote them mid-session, so in THIS session they are not dispatchable —
+  // and the failure is worse than a plain error: names like `planner` and
+  // `reviewer` often resolve to the user's own unrelated global agents,
+  // silently running a different discipline instead of erroring.
+  console.log(
+    dim(
+      `     A new session matters: ${HOSTS[host].label} lists its agents at startup, so the\n` +
+        '     ones just installed are not dispatchable in the session that ran this.\n' +
+        '     If a handoff must happen here anyway, read the agent file and follow it\n' +
+        '     inline rather than dispatching to a name that may resolve elsewhere.',
+    ),
+  );
   console.log();
   if (explicitCore) {
     console.log(dim(`Core: ${bold(core)}.`));
@@ -636,6 +673,7 @@ async function dbRebuildCommand() {
   console.log(
     `${green('rebuilt')}  ${dim(`${result.intentsReplayed} intent(s) replayed, ${result.tasksMarkedComplete} task(s) marked complete`)}\n`,
   );
+  warnOrphanedNotes(result);
   warnRebuildDrift(result, corePath);
 }
 
@@ -667,6 +705,13 @@ async function dbCommand(args) {
 // along with the rest of src/golden-cores/<core>). Neither exists yet on
 // a deferred install (plain `init`, no explicit core flag) until
 // `bootstrap` runs — this returns null until then.
+// Synchronous on purpose: formatPacket renders in one pass and takes this
+// as a predicate, so the FIRST ARRIVAL check cannot be an await. Paths are
+// repo-relative, the same way scope globs are.
+function packetExists(path) {
+  return existsSync(join(DEST_ROOT, path));
+}
+
 async function resolveCorePath() {
   if (await exists(join(DEST_ROOT, AUTHORED_CORE_PATH))) {
     return join(DEST_ROOT, AUTHORED_CORE_PATH);
@@ -821,6 +866,7 @@ async function planCommand(args = []) {
   const driftDb = openDb({ readOnly: true });
   let drifted;
   try {
+    warnSingularModuleIdsAtPlan(core, driftDb);
     drifted = detectDrift(driftDb, core, { overrides });
   } finally {
     driftDb.close();
@@ -957,6 +1003,114 @@ async function intentCommand(args) {
 
   console.log(`  ${green('added')}  ${intent.id}`);
   console.log(`  ${dim(`${intent.requirements.length} requirement(s), ${intent.depends_on.length} dependency(ies)`)}`);
+  await warnSingularModuleId(intent);
+}
+
+// On a module-axis core the intent id becomes {module} in every layer's
+// scope glob and verify command, and the generators the packet points at
+// take the module name plural. A singular id compiles a whole graph
+// scoped to a directory the generator will never write, and nothing
+// downstream catches it: plan compiles it, claim hands out a packet whose
+// own scaffold command contradicts its ALLOWED SCOPE.
+//
+// A warning rather than a refusal: plenty of real modules are singular
+// (`billing`, `search`), so the convention cannot be enforced without
+// rejecting correct ids. Raised here because this is the last moment the
+// fix is one file rename — three layers later it is a Correction Protocol
+// case across every compiled task.
+//
+// The convention is a heuristic, not a checkable property of the graph:
+// `tasks` and `task` are both structurally valid, and nothing downstream
+// knows which one the generator wants. So this only ever reports.
+function looksSingular(id) {
+  return !/(s|ae|ia|people|children)$/i.test(id);
+}
+
+// `intent add` is one route to the compiler among several — `--file`, a
+// hand-written intents/*.json, and `db rebuild` all reach it without
+// passing through here — so `plan` re-raises the same check where every
+// route converges. See planCommand.
+async function warnSingularModuleId(intent) {
+  const corePath = await resolveCorePath();
+  if (!corePath) return;
+
+  let core;
+  try {
+    core = await loadCore(corePath);
+  } catch {
+    // A core that will not load is `plan`'s error to report, not this
+    // advisory's.
+    return;
+  }
+  if (!isModuleAxis(core)) return;
+  if (!looksSingular(intent.id)) return;
+
+  console.log(
+    `\n${yellow(bold('Module id looks singular.'))} On this core the intent id is ${bold('{module}')} in\n` +
+      `every layer's scope, and the generators take it plural — so ${bold(intent.id)} compiles\n` +
+      `scope for ${bold(`${intent.id}/`)} while the scaffold command writes ${bold(`${intent.id}s/`)}.\n` +
+      `If ${bold(`${intent.id}s`)} is the name you meant, fix it now, before ${bold('hedgehog plan')}:\n` +
+      `  ${dim(`git mv ${INTENTS_DIR}/${intent.id}.json ${INTENTS_DIR}/${intent.id}s.json`)}\n` +
+      `  ${dim(`# edit "id" and every ${intent.id.toUpperCase()}-* requirement id, then:`)}\n` +
+      `  ${dim('hedgehog db rebuild')}\n`,
+  );
+}
+
+// The same advisory at `plan`, where `--file`, a hand-written intent
+// file, and `db rebuild` all converge — none of them passes through
+// `intent add`, so on those routes this is the first and last cheap
+// warning before a whole graph is compiled against the id. It reports
+// while every one of an intent's tasks is still unstarted; once work has
+// landed the fix is a Correction Protocol case rather than a rename, and
+// repeating the `git mv` advice would point at the wrong recovery.
+//
+// One block for however many ids trip it, rather than repeating the
+// per-intent explanation: the reasoning is identical every time, and
+// stacking it once per intent buries the list of names under it. The
+// recovery is still per-id, so those lines are listed one per name.
+function warnSingularModuleIdsAtPlan(core, db) {
+  if (!isModuleAxis(core)) return;
+
+  // Every intent whose tasks have all yet to start, not just the ones
+  // this run compiled. `db rebuild` replays the committed intent files
+  // *and* compiles their tasks, so a `plan` after it compiles nothing —
+  // and that is precisely the route where nothing else has ever looked at
+  // the id. The cheap-fix window is "no work has landed yet", which
+  // outlasts any single `plan` invocation.
+  const singular = db
+    .prepare(
+      `SELECT i.id FROM intents i
+        WHERE i.id <> ?
+          AND NOT EXISTS (
+            SELECT 1 FROM tasks t
+             WHERE t.intent_id = i.id
+               AND t.status NOT IN ('proposed','planned','ready')
+          )
+        ORDER BY i.id`,
+    )
+    .all(CORE_INTENT_ID)
+    .map((row) => row.id)
+    .filter(looksSingular);
+  if (singular.length === 0) return;
+
+  const many = singular.length > 1;
+  console.log(
+    `${yellow(bold(many ? `${singular.length} module ids look singular.` : 'Module id looks singular.'))} ` +
+      `On this core an intent id is ${bold('{module}')} in\n` +
+      `every layer's scope, and the generators take it plural — so ${many ? 'each of these compiles' : 'this compiles'}\n` +
+      `scope for a directory the scaffold command will never write:\n` +
+      singular.map((id) => `  ${bold(id)} ${dim(`— scope ${id}/, scaffold writes ${id}s/`)}`).join('\n') +
+      `\n\nThis is a naming convention, not a rule — ${bold('billing')} and ${bold('search')} are ` +
+      `legitimately\nsingular. If the plural is what you meant, it is still cheap to fix:\n` +
+      singular
+        .map(
+          (id) =>
+            `  ${dim(`git mv ${INTENTS_DIR}/${id}.json ${INTENTS_DIR}/${id}s.json`)}\n` +
+            `  ${dim(`# edit "id" and every ${id.toUpperCase()}-* requirement id`)}`,
+        )
+        .join('\n') +
+      `\n  ${dim('hedgehog db rebuild')}\n`,
+  );
 }
 
 async function nextCommand() {
@@ -1010,7 +1164,7 @@ async function nextCommand() {
     console.error('');
   }
 
-  console.log(formatNext(packet, await resolveCoreId()));
+  console.log(formatNext(packet, await resolveCoreId(), packetExists));
 }
 
 function printStalledTasks(stalled) {
@@ -1237,7 +1391,7 @@ async function printPackets(tasks) {
       const packet = taskPacket(db, task.id);
       if (!packet) continue;
       console.log();
-      console.log(formatPacket(packet, taskStatusLine(packet.task), coreId));
+      console.log(formatPacket(packet, taskStatusLine(packet.task), coreId, packetExists));
     }
   } finally {
     db.close();
@@ -1467,7 +1621,9 @@ async function showCommand(args) {
     return;
   }
 
-  console.log(formatPacket(packet, taskStatusLine(packet.task), await resolveCoreId()));
+  console.log(
+    formatPacket(packet, taskStatusLine(packet.task), await resolveCoreId(), packetExists),
+  );
 }
 
 // `hedgehog release <task-id> --owner <owner>` — hands a claimed task

package/package.json

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

package/src/agents/planner.md

@@ -50,6 +50,28 @@ follows delegates normally. Re-entry stays a subagent dispatch: its
 questions are short, scoped, and answer-shaped, not a facilitated
 session.
 
+A hard rule stated in this file or `hedgehog-planning-intake` (this one
+included) is not one option to weigh against a user's earlier
+instruction — it's a constraint to work within. If a user instruction
+genuinely conflicts with one (e.g. "don't ask clarifying questions"
+against Phase 0's live elicitation requirement), say plainly that the
+two conflict and ask the user how to proceed. Never resolve the conflict
+by defaulting to a recommendation that bypasses the rule, and never
+present bypassing it as an equally-weighted option alongside following
+it — that smuggles the bypass in as the path of least resistance instead
+of surfacing the actual conflict.
+
+"Don't ask clarifying questions" is the common case, and on full-stack-app
+or an authored core it has a defined destination once the user has chosen
+it: **compressed intake** (`hedgehog-planning-intake`'s Phase 0). Surface
+the conflict first, exactly as above — compressed intake is what the
+user's answer can select, never what you recommend to avoid the
+conversation. Say what it costs when you name it: one batched round of
+questions instead of the shelf, a thinner archive, and an architecture
+(on an authored core) designed from a brief rather than elicited drivers.
+Landing-page has no such destination — see that skill for why — so there
+the conflict is surfaced and resolved with the user, not routed.
+
 ## Phase 0 — which core applies
 
 Before invoking any planning-intake skill, on a first run only (Workflow
@@ -189,6 +211,11 @@ anything here a background job, or is it all instant reads and writes?",
 default an add-on on or off without either a concrete trigger in the PRD
 or a direct answer.
 
+This gate holds identically on compressed intake — it is the reason that
+mode has a batched round of questions at all. Whatever the brief doesn't
+concretely trigger goes into that round; nothing here is inferred from
+silence because the user asked not to be asked.
+
 Write the decision to `.hedgehog/addons.yaml`, one entry per add-on with
 its on/off state and the one-line reason it landed there:
 
@@ -219,7 +246,9 @@ accounts get added where there were none).
 - Decide which core applies before running any planning-intake skill —
   Phase 0 above.
 - **full-stack-app**: owns `.hedgehog/BMAD/` (archival, written once,
-  never edited after) and `.hedgehog/addons.yaml` as artifacts; the
+  never edited after — including its `00-manifest.md`, which records
+  which intake mode produced it) and `.hedgehog/addons.yaml` as
+  artifacts; the
   intent records Phase 1 writes via `hedgehog intent add` live in the
   build graph, not a file this agent owns.
 - **landing-page**: owns `.hedgehog/BMAD/` and
@@ -277,11 +306,14 @@ accounts get added where there were none).
    that turns out to be wrong is a Correction Protocol case, not a quiet
    rewrite here.
 5. **Run planning intake**, in the shape this path calls for:
-   - **First run, full-stack-app**: run the vendored BMAD shelf, then
-     mine `04-prd.md` only into intent records per the PRD→graph-row
-     table (spec: "Mapping BMAD output to intents") and the Add-ons
-     decision (see above) — asking the user directly only for whatever
-     the PRD leaves unresolved.
+   - **First run, full-stack-app**: run the vendored BMAD shelf — or, if
+     the user has explicitly chosen it after the conflict was surfaced,
+     compressed intake's batched round — then mine `04-prd.md` only into
+     intent records per the PRD→graph-row table (spec: "Mapping BMAD
+     output to intents") and the Add-ons decision (see above) — asking
+     the user directly only for whatever the PRD leaves unresolved. The
+     mining step is the same either way; only how the archive was
+     produced differs.
    - **First run, landing-page**: run the same vendored BMAD shelf in
      full, then mine `.hedgehog/BMAD/` into a draft subject statement
      (subject, audience, single page job) — asking the user directly only

package/src/agents/ux-planner.md

@@ -35,15 +35,26 @@ material `planner` files per module at planning intake, for you to act on here.
 If it's thin, or a specific detail you need (information architecture, a
 named flow, visual identity) isn't in it, read the full source directly:
 `.hedgehog/BMAD/05-ux-spec/DESIGN.md` and `EXPERIENCE.md`, the un-mined
-UX spec `planner`'s notes were drawn from. Read the notes file if present,
-then say so plainly and ask for anything further
-before producing the rationale: "Phase A is closed for `<module>` — this
-is the UX planning step before the screen gets built. [If notes exist:
-"I've got what was noted at planning intake for this module — here's a quick
-recap: (one-line summary)."] If you have a mockup, screenshot, an export
-from a tool like Google Stitch or Figma, or an existing screen you want
-this to resemble, hand it over now; otherwise I'll propose the layout
-from the contract, hook, and any notes on file." Treat whatever's
+UX spec `planner`'s notes were drawn from. Read whichever of the two the
+archive holds — a project planned through compressed intake
+(`hedgehog-planning-intake`'s Phase 0) has `EXPERIENCE.md` only, and one
+whose brief stated no flows may have neither. **An absent file is your
+cue to ask, not to invent.** Visual identity is the first thing a
+compressed brief omits, so where the archive is silent, say so and
+propose from the contract and hook rather than inferring a direction the
+user never gave — that inference is the improvisation this step exists to
+replace.
+
+Read the notes file if present, then say so plainly and ask for anything
+further before producing the rationale: "Phase A is closed for
+`<module>` — this is the UX planning step before the screen gets built.
+[If notes exist: "I've got what was noted at planning intake for this
+module — here's a quick recap: (one-line summary)."] [If the archive
+holds no UX spec: "This project was planned through compressed intake, so
+there's no visual direction on file."] If you have a mockup, screenshot,
+an export from a tool like Google Stitch or Figma, or an existing screen
+you want this to resemble, hand it over now; otherwise I'll propose the
+layout from the contract, hook, and any notes on file." Treat whatever's
 supplied or on file the same way — a source of screen inventory and
 hierarchy, not something to transcribe pixel-for-pixel. No visual tool or
 prior note is required; the rationale stands on its own when nothing is
@@ -70,7 +81,10 @@ mockup, not a design system, not code:
    was (a screenshot, a Stitch/Figma export, a named reference app,
    planning-intake notes from `docs/design/<module>-notes.md`, or the
    raw UX spec at `.hedgehog/BMAD/05-ux-spec/`) and what was drawn from
-   it versus decided independently.
+   it versus decided independently. Where there was none — a compressed
+   archive with no UX spec and nothing supplied — say that plainly here,
+   so `front-end-eng` and `reviewer` read the rationale as reasoned from
+   the contract and hook rather than from a direction on file.
 
 Keep it short — a few bullets per screen, not a document. This is a
 rationale `front-end-eng` reads once before starting, and `reviewer` can
@@ -110,9 +124,11 @@ conclusion.
 1. Confirm the module's hook step is committed (`feat(<module>): hooks`)
    — if not, stop, this is being asked for too early.
 2. Check for `docs/design/<module>-notes.md` and read it if present. If
-   it's thin or missing a detail you need, read
-   `.hedgehog/BMAD/05-ux-spec/DESIGN.md` and `EXPERIENCE.md` directly for
-   the full material it was drawn from.
+   it's thin or missing a detail you need, read whichever of
+   `.hedgehog/BMAD/05-ux-spec/DESIGN.md` and `EXPERIENCE.md` the archive
+   holds, for the full material it was drawn from. Where neither the
+   notes nor the spec covers what you need, that gap goes into step 3's
+   ask — it is not something to fill in yourself.
 3. Announce the Phase B transition and ask for visual input, per "When
    you run," above.
 4. Read the contract (`packages/contracts`) for the module: what

package/src/db/core.mjs

@@ -480,6 +480,14 @@ function tokenInsideGlob(token, glob) {
   return false;
 }
 
+// True when the core compiles one task per domain module rather than one
+// per layer — i.e. some layer's scope varies by {module}. The single
+// owner of that question: validateCore, lintCore, and `intent add`'s
+// plural-id check all read it from here.
+export function isModuleAxis(core) {
+  return core.layers.some((layer) => layer.scope.join('').includes('{module}'));
+}
+
 // Enforces the interview's rule (spec: "Authored cores") — a layer without
 // scope or without a verify command is rejected. Applied uniformly to
 // shipped and authored cores alike; the loader has no shipped-core-only
@@ -600,10 +608,7 @@ export function validateCore(core) {
   // is nothing for a {module} in its scope to isolate — and requiring one
   // would reject exactly the cross-cutting layers `once` exists to
   // express.
-  const isModuleAxis = core.layers.some((layer) =>
-    layer.scope.join('').includes('{module}'),
-  );
-  if (isModuleAxis) {
+  if (isModuleAxis(core)) {
     for (const layer of core.layers) {
       if (layer.exclusive || layer.once) continue;
       if (!layer.scope.join('').includes('{module}')) {
@@ -662,10 +667,7 @@ export function validateCore(core) {
 // hedgehog-core-design carries the question as an authoring rule too.
 export function lintCore(core) {
   const warnings = [];
-  const isModuleAxis = core.layers.some((layer) =>
-    layer.scope.join('').includes('{module}'),
-  );
-  if (isModuleAxis) {
+  if (isModuleAxis(core)) {
     for (const layer of core.layers) {
       if (layer.exclusive || layer.once) continue;
       if (!layer.scope.join('').includes('{module}')) continue; // validateCore already rejects this

package/src/db/next.mjs

@@ -360,9 +360,74 @@ const HONESTY = [
 // HONESTY is last deliberately: it's the one section that qualifies the
 // gate above it, so it reads as the answer to "and what if I can't clear
 // VERIFICATION honestly" rather than as preamble.
-export function formatPacket(packet, statusLine, coreId = null) {
+// The package root a scope glob lives inside: the literal path above the
+// glob's first wildcard, truncated at `src/` when one appears — a package
+// root is where `package.json` sits, which is always above the `src/` a
+// module directory hangs off.
+//
+// `{module}` is substituted first rather than treated as a wildcard,
+// because on this core it is a real directory name in the compiled task
+// and the package root can sit *below* it: `packages/contracts/src/tasks/**`
+// has its root two segments up, while `libs/tasks/repository/**` has its
+// root at the full literal path. Only `*` genuinely ends the literal part.
+export function scopePackageRoot(glob, module) {
+  const segments = glob.replace('{module}', module).split('/');
+  const wildcard = segments.findIndex((s) => s.includes('*'));
+  const literal = wildcard === -1 ? segments.slice(0, -1) : segments.slice(0, wildcard);
+  const src = literal.indexOf('src');
+  const root = src === -1 ? literal : literal.slice(0, src);
+  // A package root is at least `<area>/<name>`; anything shallower is the
+  // repo itself, which is never a first arrival.
+  return root.length >= 2 ? root.join('/') : null;
+}
+
+// A task is the first arrival in its package when the package the scope
+// points into has no package.json on disk yet: the generator that
+// scaffolds this layer will create the package shell (package.json,
+// tsconfig*.json, vitest.config.mts, src/index.ts) alongside the module's
+// own files, and every one of those lands outside a {module}-bearing
+// glob. Detected here rather than left to be discovered from a failed
+// verify, which is where the override stops being available and the
+// recovery becomes a five-command round trip.
+//
+// `exists` is injected so this module keeps no filesystem dependency of
+// its own; the CLI passes a real one and the packet degrades to no
+// section when a caller supplies none.
+export function firstArrivalPackages(task, exists) {
+  if (!exists) return [];
+  const roots = new Set();
+  for (const glob of JSON.parse(task.scope_globs)) {
+    const root = scopePackageRoot(glob, task.module);
+    if (root && !exists(`${root}/package.json`)) roots.add(root);
+  }
+  return [...roots].sort();
+}
+
+function firstArrivalLines(task, roots) {
+  const scopes = roots.flatMap((root) => [`${root}/*`, `${root}/src/*`]);
+  return [
+    'FIRST ARRIVAL',
+    `  ${roots.join(', ')} ${roots.length > 1 ? 'do' : 'does'} not exist yet, so this task's`,
+    "  generator also creates the package shell (package.json, tsconfig*.json,",
+    '  vitest.config.mts, src/index.ts) plus any package-wide source it writes',
+    '  at the src/ root. All of that lands OUTSIDE the scope above. Widen this',
+    '  one task before building it, or verify will reject those paths and',
+    '  block the task:',
+    '',
+    `  hedgehog override add ${task.id} \\`,
+    ...scopes.map((s) => `    --scope '${s}' \\`),
+    `    --reason 'first module through ${task.layer} also creates the package shell'`,
+    '',
+    '  src/* is non-recursive on purpose: it covers src/index.ts and any',
+    "  shared util beside it without re-granting the module directory the",
+    '  scope above already covers.',
+  ];
+}
+
+export function formatPacket(packet, statusLine, coreId = null, exists = null) {
   const { task, intent, requirements, dependents, incompleteDeps = [], inheritedDebt = [] } = packet;
   const scopeGlobs = JSON.parse(task.scope_globs);
+  const firstArrival = firstArrivalPackages(task, exists);
 
   const lines = [];
   lines.push(`TASK  ${task.id}`);
@@ -428,6 +493,10 @@ export function formatPacket(packet, statusLine, coreId = null) {
   lines.push('ALLOWED SCOPE');
   for (const glob of scopeGlobs) lines.push(`  ${glob}`);
   lines.push('');
+  if (firstArrival.length > 0) {
+    lines.push(...firstArrivalLines(task, firstArrival));
+    lines.push('');
+  }
   const shapeLines = layerShapeLines(task, coreId);
   if (shapeLines) {
     lines.push(...shapeLines);
@@ -443,6 +512,6 @@ export function formatPacket(packet, statusLine, coreId = null) {
 
 // `hedgehog next`'s rendering: its task always came out of the readiness
 // SELECT, so STATUS is READY by construction.
-export function formatNext(packet, coreId = null) {
-  return formatPacket(packet, 'READY', coreId);
+export function formatNext(packet, coreId = null, exists = null) {
+  return formatPacket(packet, 'READY', coreId, exists);
 }

package/src/db/rebuild.mjs

@@ -43,6 +43,67 @@ function intentExists(db, id) {
   return db.prepare('SELECT 1 FROM intents WHERE id = ?').get(id) !== undefined;
 }
 
+// A rebuild's result is a pure function of the committed sources
+// (`.hedgehog/intents/`, core.yaml, overrides, git history), so the
+// derived graph is cleared before replay rather than replayed on top of
+// whatever the DB already held. Without this, an intent file that was
+// renamed or deleted leaves its tasks behind: the scheduler then sees a
+// ghost task whose scope overlaps the real one and holds the real one
+// back, producing a graph no set of committed intents describes.
+//
+// Deleting `intents` cascades through requirements, tasks,
+// task_requirements, dependencies, artifacts and verifications — every
+// one of which this run re-derives. `debt` and `friction` are the
+// exception: they are operator-recorded notes with no committed source,
+// so they are carried across by task id (deterministic, so a note
+// re-attaches to the same task the replay recompiles). A note whose task
+// no longer exists in the new graph has nowhere to live and is reported
+// rather than silently dropped.
+function clearDerivedGraph(db) {
+  const debt = db.prepare('SELECT task_id, note, logged_at FROM debt').all();
+  const friction = db.prepare('SELECT task_id, note, logged_at FROM friction').all();
+
+  db.prepare('DELETE FROM intents').run();
+  // `friction.task_id` is ON DELETE SET NULL rather than CASCADE, so its
+  // rows outlive the delete above. Clear them too and let restoreNotes be
+  // the single writer, so a note is not duplicated against its own copy.
+  db.prepare('DELETE FROM friction').run();
+
+  return { debt, friction };
+}
+
+function restoreNotes(db, { debt, friction }) {
+  const taskExists = db.prepare('SELECT 1 FROM tasks WHERE id = ?');
+  const insertDebt = db.prepare(
+    'INSERT INTO debt (task_id, note, logged_at) VALUES (?, ?, ?)',
+  );
+  const insertFriction = db.prepare(
+    'INSERT INTO friction (task_id, note, logged_at) VALUES (?, ?, ?)',
+  );
+
+  const orphaned = [];
+
+  for (const row of debt) {
+    if (taskExists.get(row.task_id) === undefined) {
+      orphaned.push({ kind: 'debt', taskId: row.task_id, note: row.note });
+      continue;
+    }
+    insertDebt.run(row.task_id, row.note, row.logged_at);
+  }
+
+  for (const row of friction) {
+    // friction.task_id is nullable — an unattached note always survives.
+    if (row.task_id !== null && taskExists.get(row.task_id) === undefined) {
+      insertFriction.run(null, row.note, row.logged_at);
+      orphaned.push({ kind: 'friction', taskId: row.task_id, note: row.note });
+      continue;
+    }
+    insertFriction.run(row.task_id, row.note, row.logged_at);
+  }
+
+  return orphaned;
+}
+
 // Topological sort over `depends_on`, tie-broken by the file order above
 // so two runs over the same directory always replay identically.
 //
@@ -71,9 +132,9 @@ function orderIntentsForReplay(records, isSatisfied) {
 
     const entry = byId.get(id);
     if (!entry) {
-      // Not a file in this directory. Fine if the DB already has it
-      // (rebuild tolerates an already-populated DB); otherwise the edge
-      // points at nothing and would fail the FOREIGN KEY.
+      // Not a file in this directory, and the derived graph was cleared
+      // before replay, so the edge points at nothing and would fail the
+      // FOREIGN KEY.
       if (isSatisfied(id)) return;
       throw new Error(
         `intent "${requiredBy}" depends_on "${id}", which has no intent file in ` +
@@ -98,12 +159,6 @@ function orderIntentsForReplay(records, isSatisfied) {
 // Reads every intent file, normalizes it, orders the set by depends_on,
 // and inserts the rows. Read-only with respect to the files themselves.
 //
-// The insert is unconditional (an intent id is never re-added through
-// `intent add` in normal use), so rebuild — the one caller that must also
-// tolerate an already-populated DB, per "re-derive from source-of-truth
-// after suspected corruption" — skips any intent whose id is already
-// present rather than letting the UNIQUE constraint fail the whole run.
-//
 // Ordering is resolved for the whole set BEFORE any row is written, so a
 // cycle or a dangling depends_on fails the run without having half-built
 // the graph.
@@ -232,10 +287,9 @@ function markCompletedTasks(db, commitSubjects) {
   const setComplete = db.prepare("UPDATE tasks SET status = 'complete' WHERE id = ?");
   for (const id of complete) setComplete.run(id);
 
-  // Rebuild also runs against an already-populated DB ("after suspected
-  // corruption"), where a once-task may be sitting at `complete` from
-  // before a re-entry pass added work under it. Reconcile it back rather
-  // than leaving the stale status untouched.
+  // A once-task can be marked complete by the loop above and then fail
+  // one of the extra conditions on a later pass of the fixpoint walk.
+  // Reconcile it back rather than leaving the stale status untouched.
   const reopen = db.prepare(
     "UPDATE tasks SET status = 'planned' WHERE id = ? AND status = 'complete'",
   );
@@ -268,6 +322,8 @@ export async function rebuildDb(
 ) {
   applySchema(db);
 
+  const notes = clearDerivedGraph(db);
+
   const intentsReplayed = await replayIntents(db, intentsDir);
 
   const core = await loadCore(corePath);
@@ -277,7 +333,9 @@ export async function rebuildDb(
   const commitSubjects = loadCommitSubjects();
   const tasksMarkedComplete = markCompletedTasks(db, commitSubjects);
 
+  const orphanedNotes = restoreNotes(db, notes);
+
   const drift = detectDrift(db, core, { overrides });
 
-  return { intentsReplayed, tasksMarkedComplete, drift };
+  return { intentsReplayed, tasksMarkedComplete, orphanedNotes, drift };
 }