hedgehog-orchestrating

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: