@skyf0xx/hedgehog 4.0.14 → 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.14",
+  "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-core-design/SKILL.md

@@ -358,6 +358,61 @@ expressible: it requires a commit before the verify that gates the
 commit. Choose a model that applies directly rather than designing a
 layer around it.
 
+## Step 4d — make the product's own surface reachable
+
+Skip this only if nothing the project publishes is reached through an
+**arbitrator**: an ingress, a router, a gateway, a reverse proxy, a
+process supervisor — anything that decides which backend answers a
+request, and that no layer publishing a surface owns. For every core
+with one, add a `once: true` **reachability layer** at the tail,
+`depends_on` the last per-module layer, whose `verify` makes a real
+request to each intent's primary surface and asserts something specific
+about the answer.
+
+Every other check in this skill judges one layer against its own claim.
+This one exists because the defect it catches belongs to no layer. On a
+module axis each layer's `scope` is a disjoint per-module subtree, so an
+API layer choosing a route and a web layer choosing a screen path make
+independent choices that only ever meet in the arbitrator's config —
+owned by a third layer that knows neither. Each layer is individually
+correct, each verify passes in isolation, and the request 404s. That is
+a whole-graph property, and only a task that runs after the whole graph
+can hold it.
+
+What the layer asserts is the intent's `outcome` read back from outside:
+the route answers, with a status and a body that could not come from the
+wrong backend. Assert something the *other* side of the arbitrator
+cannot produce — a JSON shape, a header, a field the API returns and the
+web app does not. A bare 200 is satisfied by the fall-through app's own
+200, which is the exact confusion this layer exists to detect.
+
+The tail position is doing real work here, and the same three properties
+that make `once: true` right for a composition seam (Step 4) make it
+right here:
+
+- **One task, after everything.** `depends_on` the last per-module layer
+  makes it wait on *every* module's copy, so it runs once, with the
+  whole product standing up.
+- **Re-entrant by construction.** When `planner`'s Re-entry pass adds a
+  module to a finished build, that module's task becomes a prerequisite
+  of this already-complete layer, so `hedgehog plan` reopens it — a new
+  module's surface gets checked for reachability without anyone
+  remembering to ask.
+- **It closes the graph's own claim.** Without it, "every task complete"
+  is a statement about tasks. With it, the last task completing means
+  the product answers.
+
+Two failure modes to design out. The layer must carry no `{module}`
+anywhere — `validateCore` rejects a `once` layer that does — so it
+enumerates the surfaces it checks in one command rather than
+substituting a module in. And it needs the arbitrator's routing to
+already be applied, which makes it strictly later than the deploy layer,
+never merged into it: a deploy layer verifies its own manifests landed,
+which is what six green deploy layers over a 404 already looked like.
+
+Record in `core-design.md` which layer is the reachability gate and what
+each surface it checks is asserting.
+
 ## Step 5 — write `.hedgehog/core.yaml`
 
 The loader parses `id` plus a `layers` list of flat maps. Every layer
@@ -487,6 +542,16 @@ if missed:
   deployment/app` read the same thing regardless of which module's task
   is running, so six modules' deploy tasks assert the identical claim six
   times rather than each module's own deployment.
+- **A reachability layer's `verify` asserts the product answers, not
+  that a layer deployed.** The tail `once: true` layer Step 4d calls for
+  is the one place a `verify` command is about the whole build rather
+  than its own scope, so the usual scope/filter cross-checks above have
+  nothing to say about it. Its command makes a real request through the
+  arbitrator to each intent's primary surface and asserts a response
+  only the intended backend could produce. Its `scope` is whatever
+  fixture or script the check itself lives in — a layer that writes
+  nothing still needs a scope glob it may write, since `hedgehog verify`
+  rejects writes outside it.
 - **Declare the binaries `verify` needs, in `requires`.** Optional, an
   inline list alongside `scope`/`verify`/`commit`
   (`requires: ["terraform", "kubectl"]`), and only for tools that come
@@ -549,6 +614,9 @@ to change only until the file lands. Hard stop.
   (intents × layers tasks, or one task per layer).
 - For any layer that deploys or publishes: where the push happens
   relative to that layer's commit (Step 4c) — or that no layer deploys.
+- Which layer is the reachability gate and what each surface it checks
+  asserts (Step 4d) — or that nothing published is reached through an
+  arbitrator.
 - That this is an authored core: the sequence was designed for this
   project, not battle-tested across many, and it carries the same
   enforcement as a Golden Core but a weaker guarantee.

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.