@skyf0xx/hedgehog 4.0.15 → 4.1.0

package/bin/cli.mjs

@@ -933,10 +933,10 @@ async function nextCommand() {
 
   const db = openDb();
   let packet;
-  let stalled = [];
+  let stalled;
   try {
     packet = nextTask(db);
-    if (!packet) stalled = stalledTasks(db);
+    stalled = stalledTasks(db);
   } finally {
     db.close();
   }
@@ -947,10 +947,7 @@ async function nextCommand() {
     // a failed verification.
     if (stalled.length > 0) {
       console.error(`${red(bold('No ready task, but the graph is blocked.'))}\n`);
-      for (const task of stalled) {
-        const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
-        console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
-      }
+      printStalledTasks(stalled);
       // `verify` refuses anything that isn't `building` and leased to
       // the caller, so a blocked task has to go back through the queue
       // — retry, claim, then verify — rather than straight to verify.
@@ -964,9 +961,28 @@ async function nextCommand() {
     return;
   }
 
+  // A blocked task elsewhere in the graph doesn't stop this ready task
+  // from being handed out — leases are scoped to disjoint work, so an
+  // unrelated block is no reason to halt everything else. But it's easy
+  // to miss otherwise: the queue keeps producing ready tasks right up
+  // until it doesn't, and a block can sit unnoticed the whole time. This
+  // warns without withholding the packet.
+  if (stalled.length > 0) {
+    console.error(`${yellow(bold(`${stalled.length} task(s) blocked elsewhere in the graph:`))}`);
+    printStalledTasks(stalled);
+    console.error('');
+  }
+
   console.log(formatNext(packet));
 }
 
+function printStalledTasks(stalled) {
+  for (const task of stalled) {
+    const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
+    console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
+  }
+}
+
 // Mirrors, read-only, the condition verifyTask's own Phase 0
 // (claimForVerify) enforces: after expired leases are reaped, the task
 // must be `building` and leased to `owner`. The expiry predicate is
@@ -1185,13 +1201,30 @@ async function claimCommand(args) {
   }
 
   const db = openDb();
-  let claimed;
+  let claimed, blocked;
   try {
-    claimed = claimTasks(db, { owner, count });
+    ({ claimed, blocked } = claimTasks(db, { owner, count }));
   } finally {
     db.close();
   }
 
+  // Stop-the-line: claimTasks refuses the whole batch, in any module,
+  // while any task anywhere is blocked — see its own comment in
+  // claim.mjs. A targeted `hedgehog claim <task-id>` is unaffected, which
+  // is how the blocked task itself gets reclaimed after `hedgehog retry`.
+  if (blocked.length > 0) {
+    console.error(`${red(bold('Claim refused.'))} ${blocked.length} task(s) blocked:\n`);
+    for (const task of blocked) {
+      const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
+      console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
+    }
+    console.error(
+      `\nFix the work, then ${bold('hedgehog retry <task-id>')} before claiming more.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   if (claimed.length === 0) {
     console.log(`${dim('No claimable task.')} Nothing is ready with no lease held.\n`);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "4.0.15",
+  "version": "4.1.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {
@@ -44,4 +44,4 @@
     "hedgehog"
   ],
   "license": "MIT"
-}
+}

package/src/db/claim.mjs

@@ -180,16 +180,25 @@ function loadTask(db, taskId) {
 // concurrent `claim` call in the interim would otherwise reach `verify`
 // with a technically-expired lease that still matches status/lease_owner
 // and sail through unreaped.
+//
+// Returns the ids it just flipped, as a Set — claimTasks's stop-the-line
+// check uses this to tell a block this very call produced from one that
+// was already sitting there, so a dead agent's lease lapsing doesn't
+// itself become the reason every other module's fan-out refuses.
 export function reapExpiredLeases(db) {
-  db.prepare(
-    `
+  const rows = db
+    .prepare(
+      `
     UPDATE tasks
     SET status = 'blocked', blocked_reason = 'lease_expired',
         lease_owner = NULL, lease_expires_at = NULL, leased_at = NULL,
         claim_snapshot = NULL
     WHERE status IN ('building', 'verifying') AND lease_expires_at < datetime('now')
+    RETURNING id
   `,
-  ).run();
+    )
+    .all();
+  return new Set(rows.map((r) => r.id));
 }
 
 // The atomic claim primitive: the WHERE clause re-checks status and
@@ -204,8 +213,38 @@ const claimOne = (db) =>
     RETURNING id
   `);
 
-// Claims up to `count` ready tasks for `owner`. `count` is a maximum, not
-// a promise — returns however many were actually claimed, possibly zero.
+// Every `blocked` task in the graph, regardless of module or reason —
+// the fan-out claim's stop-the-line check. Ordered the same as the
+// NEEDS ATTENTION list in status.mjs, so the two never disagree about
+// which tasks are outstanding.
+function findBlockedTasks(db) {
+  return db.prepare(`SELECT * FROM tasks WHERE status = 'blocked' ORDER BY priority, id`).all();
+}
+
+// Claims up to `count` ready tasks for `owner`, returning
+// `{ claimed, blocked }`. `count` is a maximum, not a promise — `claimed`
+// may hold fewer tasks than `count`, or none. `blocked` is non-empty only
+// on the stop-the-line refusal below, in which case `claimed` is always
+// empty.
+//
+// Stop-the-line: if any task anywhere in the graph was already `blocked`
+// before this call, the fan-out refuses to claim anything at all, in any
+// module — a blocked task needs a human/agent decision (retry after a
+// fix, or leave it), and handing out fresh work around it makes that easy
+// to ignore indefinitely. Deliberately stricter than dependency-based
+// blocking: an unrelated module isn't literally stuck on the blocked
+// task, but the fan-out stops anyway until it's retried. A targeted
+// `hedgehog claim <task-id>` (claimTask, below) is exempt — that's how
+// the blocked task itself gets reclaimed after `hedgehog retry`.
+//
+// "Already blocked" excludes a lease this same call's reapExpiredLeases
+// just flipped: a dead agent's lease can lapse on an unrelated module,
+// and the first `claim` call after that lapse is whichever one happens to
+// discover it. That call still claims normally; the reaped task still
+// lands in `blocked`/`lease_expired` and still needs `hedgehog retry`
+// before it's claimable — only this one call's refusal is skipped. Every
+// `claim` call after it sees the same task still blocked and stops as
+// usual.
 //
 // Fan-out keeps the batch mutually non-conflicting, and non-conflicting
 // with every task already in flight, per conflict.mjs's
@@ -229,7 +268,12 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
   const claimSnapshot = snapshotWorkingTree();
 
   return inTransaction(db, () => {
-    reapExpiredLeases(db);
+    const justReaped = reapExpiredLeases(db);
+
+    const blocked = findBlockedTasks(db).filter((task) => !justReaped.has(task.id));
+    if (blocked.length > 0) {
+      return { claimed: [], blocked };
+    }
 
     const candidates = findClaimableTasks(db);
     const inFlight = findInFlightTasks(db);
@@ -245,7 +289,7 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
       claimed.push(loadTask(db, candidate.id));
     }
 
-    return claimed;
+    return { claimed, blocked: [] };
   });
 }
 

package/src/db/ready.mjs

@@ -46,8 +46,10 @@ export function readyTasks(db) {
 // Renders one HELD BACK reason. `exclusive` splits on which side of the
 // pair is exclusive: the candidate itself (runs alone, full stop) vs. the
 // already-CLAIMABLE task it lost the slot to (named, so the reason points
-// at what's actually occupying the batch).
-function formatReason(candidate, conflict) {
+// at what's actually occupying the batch). Exported for status.mjs, which
+// annotates the same held-back tasks inline in its own READY section
+// rather than duplicating this formatting.
+export function heldBackReason(candidate, conflict) {
   const { with: other, kind } = conflict;
 
   if (kind === 'exclusive') {
@@ -86,7 +88,7 @@ export function formatReady({ claimable, heldBack }) {
     lines.push('');
     lines.push('HELD BACK');
     for (const { task, conflict } of heldBack) {
-      lines.push(`  ${task.id.padEnd(20)}${task.layer.padEnd(13)}${formatReason(task, conflict)}`);
+      lines.push(`  ${task.id.padEnd(20)}${task.layer.padEnd(13)}${heldBackReason(task, conflict)}`);
     }
   }
 

package/src/db/status.mjs

@@ -13,6 +13,7 @@
 
 import { detectDrift, formatDrift } from './drift.mjs';
 import { formatMissingRequirements } from './requires.mjs';
+import { readyTasks, heldBackReason } from './ready.mjs';
 
 // The task lifecycle in order, matching the tasks CHECK constraint in
 // schema.mjs exactly — every status the engine can write, and no others.
@@ -81,11 +82,16 @@ function loadAttentionTasks(db) {
   return db.prepare(ATTENTION_TASKS_SQL).all();
 }
 
-// Returns { counts, ready, inFlight, attention, drift, total } — counts
-// keyed by every status in the tasks CHECK constraint (present even at
-// zero), ready the full list of currently-pickable tasks, inFlight the
-// tasks currently leased (building or verifying), attention the stalled
-// tasks needing a fix, total the sum across all statuses.
+// Returns { counts, ready, heldBack, inFlight, attention, drift, total } —
+// counts keyed by every status in the tasks CHECK constraint (present even
+// at zero), ready the full list of currently-pickable tasks, heldBack the
+// subset of those that `hedgehog claim` would skip over right now because
+// they conflict with in-flight work or another ready task ahead of them
+// (ready.mjs's own simulation, reused rather than reimplemented — without
+// this a task can sit in READY indefinitely with no visible reason, the
+// same invisible-stall shape blocked tasks had before `attention` existed),
+// inFlight the tasks currently leased (building or verifying), attention
+// the stalled tasks needing a fix, total the sum across all statuses.
 //
 // `core` is optional and, when given, adds `drift`: the tasks whose
 // layer-derived fields no longer match core.yaml (drift.mjs). It's a
@@ -100,11 +106,12 @@ function loadAttentionTasks(db) {
 export function graphStatus(db, { core = null, overrides = new Map() } = {}) {
   const counts = countTasksByStatus(db);
   const ready = loadReadyTasks(db);
+  const { heldBack } = readyTasks(db);
   const inFlight = loadInFlightTasks(db);
   const attention = loadAttentionTasks(db);
   const drift = core ? detectDrift(db, core, { overrides }) : [];
   const total = Object.values(counts).reduce((a, b) => a + b, 0);
-  return { counts, ready, inFlight, attention, drift, total };
+  return { counts, ready, heldBack, inFlight, attention, drift, total };
 }
 
 const BLOCKED_REASON_LABELS = {
@@ -127,6 +134,7 @@ const BLOCKED_REASON_LABELS = {
 export function formatStatus({
   counts,
   ready,
+  heldBack = [],
   inFlight,
   attention,
   drift,
@@ -146,12 +154,18 @@ export function formatStatus({
     lines.push(...missingLines);
     lines.push('');
   }
+  // Each ready task is annotated inline with why `hedgehog claim` would
+  // skip it right now, rather than listed flatly — a task can otherwise
+  // sit in READY indefinitely with no visible reason (see graphStatus).
+  const heldBackById = new Map(heldBack.map(({ task, conflict }) => [task.id, conflict]));
   lines.push('READY');
   if (ready.length === 0) {
     lines.push('  (none)');
   } else {
     for (const task of ready) {
-      lines.push(`  ${task.id}   ${task.layer}   ${task.objective}`);
+      const conflict = heldBackById.get(task.id);
+      const note = conflict ? `   (held back — ${heldBackReason(task, conflict)})` : '';
+      lines.push(`  ${task.id}   ${task.layer}   ${task.objective}${note}`);
     }
   }
 

package/src/skills/hedgehog-authored-loop/SKILL.md

@@ -117,14 +117,21 @@ runtime detail.
    moves to `blocked` with a `blocked_reason` of `scope_violation` or
    `verification_failed`, and nothing downstream unlocks. Fix the work,
    then run `hedgehog retry <task-id>` to return the task to `planned`,
-   claim it again, and verify again — `hedgehog verify` only accepts a
-   task you currently hold in `building`, so a blocked task has to go
-   back through `retry` and `claim` first. Don't hand-commit around it.
-
-   A `blocked` task is not pickable by `hedgehog claim`, so `hedgehog
-   status` lists it under NEEDS ATTENTION with the task id to retry.
-   If `hedgehog claim` returns nothing and the graph isn't actually done,
-   fix that task — don't treat it as "nothing left to do."
+   claim it again (by task id — see below), and verify again —
+   `hedgehog verify` only accepts a task you currently hold in
+   `building`, so a blocked task has to go back through `retry` and
+   `claim` first. Don't hand-commit around it.
+
+   A `blocked` task anywhere in the graph — in this layer or any other —
+   makes `hedgehog claim --count N` refuse to hand out anything at all,
+   with a non-zero exit naming the blocked task(s). `hedgehog status`
+   lists them too, under NEEDS ATTENTION. Fix and `retry` the named
+   task(s) before claiming more. A **targeted** `hedgehog claim <task-id>
+   --owner <owner>` is exempt — that's how the just-retried task gets
+   reclaimed in the step above. A lease the same `claim` call reaps for
+   having just expired is exempt too: that call still claims whatever
+   else is ready, and the reaped task lands in NEEDS ATTENTION for the
+   next `claim` call to stop on.
 5. **Repeat** — `hedgehog claim --count N --owner <owner>` again for the
    next batch.
 

package/src/skills/hedgehog-landing-loop/SKILL.md

@@ -187,10 +187,19 @@ paragraph algorithm, and their self-tests.
    check, the task moves to `blocked` with a `blocked_reason` of
    `scope_violation` or `verification_failed`, and nothing downstream
    unlocks. Fix the work, then run `hedgehog retry <task-id>` to return
-   the task to `planned`, claim it again, and verify again — `hedgehog
-   verify` only accepts a task you currently hold in `building`, so a
-   blocked task has to go back through `retry` and `claim` first. Don't
-   hand-commit around it.
+   the task to `planned`, claim it again by task id, and verify again —
+   `hedgehog verify` only accepts a task you currently hold in
+   `building`, so a blocked task has to go back through `retry` and
+   `claim` first. Don't hand-commit around it.
+
+   A `blocked` task anywhere in the graph makes `hedgehog claim --count
+   <n>` refuse to hand out anything at all, with a non-zero exit naming
+   the blocked task(s). Fix and `retry` it before claiming more. A
+   **targeted** `hedgehog claim <task-id> --owner <owner>` is exempt —
+   that's how the just-retried task gets reclaimed above. A lease the
+   same `claim` call reaps for having just expired is exempt too: that
+   call still claims whatever else is ready, and the reaped task lands in
+   NEEDS ATTENTION for the next `claim` call to stop on.
 5. **Repeat** — `hedgehog claim --owner <owner> --count <n>` again for
    the following layer.
 

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

@@ -169,14 +169,21 @@ writes `docs/design/<module>.md`, not its own compiled layer — the
    `blocked` with a `blocked_reason` of `scope_violation` or
    `verification_failed`, and nothing downstream unlocks. Fix the work,
    then run `hedgehog retry <task-id>` to return the task to `planned`,
-   claim it again, and verify again — `hedgehog verify` only accepts a
-   task you currently hold in `building`, so a blocked task has to go
-   back through `retry` and `claim` first. Don't hand-commit around it.
-
-   A `blocked` task is not pickable by `hedgehog claim`, so `hedgehog
-   status` lists it under NEEDS ATTENTION with the task id to retry.
-   If `hedgehog claim` returns nothing and the graph isn't actually done,
-   fix that task — don't treat it as "nothing left to do."
+   claim it again (by task id — see below), and verify again —
+   `hedgehog verify` only accepts a task you currently hold in
+   `building`, so a blocked task has to go back through `retry` and
+   `claim` first. Don't hand-commit around it.
+
+   A `blocked` task anywhere in the graph — in this module or any other —
+   makes `hedgehog claim --count N` refuse to hand out anything at all,
+   with a non-zero exit naming the blocked task(s). `hedgehog status`
+   lists them too, under NEEDS ATTENTION. Fix and `retry` the named
+   task(s) before claiming more. A **targeted** `hedgehog claim <task-id>
+   --owner <owner>` is exempt — that's how the just-retried task gets
+   reclaimed in the step above. A lease the same `claim` call reaps for
+   having just expired is exempt too: that call still claims whatever
+   else is ready, and the reaped task lands in NEEDS ATTENTION for the
+   next `claim` call to stop on.
 5. **Repeat** — `hedgehog claim --count N --owner <owner>` again for the
    next batch.