@skyf0xx/hedgehog 2.0.13 → 3.0.0

package/src/db/next.mjs

@@ -0,0 +1,179 @@
+// `hedgehog next` — readiness query + task-packet assembly for one task.
+// See hedgehog-persistent-build-graph.md, the readiness `SELECT` under
+// "Schema", and "The task packet" / the `hedgehog next` output example.
+//
+// Readiness: a task with no dependency whose status isn't `complete`,
+// lowest `priority` then `id`. Pickable status is `planned` OR `ready` —
+// `plan.mjs` inserts new tasks as `planned`, but `verify.mjs`'s
+// unlockReadyDependents sets a dependent's status to `ready` directly
+// once its dependencies complete (see verify.mjs), without ever passing
+// back through `planned`. A task already marked `ready` still has to
+// satisfy the same no-incomplete-dependency condition here — the OR
+// widens which statuses are eligible, it doesn't relax the dependency
+// check itself. Once found, the packet is assembled by querying tasks
+// joined through intents/requirements/task_requirements — never
+// hand-written, never the whole plan.
+
+const READY_TASK_SQL = `
+  SELECT t.* FROM tasks t
+  WHERE t.status IN ('planned', 'ready')
+    AND NOT EXISTS (
+      SELECT 1 FROM dependencies d
+      JOIN tasks dep ON dep.id = d.depends_on_task_id
+      WHERE d.task_id = t.id AND dep.status <> 'complete'
+    )
+  ORDER BY t.priority, t.id
+  LIMIT 1;
+`;
+
+function findReadyTask(db) {
+  return db.prepare(READY_TASK_SQL).get();
+}
+
+function loadIntent(db, intentId) {
+  return db.prepare('SELECT * FROM intents WHERE id = ?').get(intentId);
+}
+
+function loadTaskRequirements(db, taskId) {
+  return db
+    .prepare(
+      `
+      SELECT r.* FROM requirements r
+      JOIN task_requirements tr ON tr.requirement_id = r.id
+      WHERE tr.task_id = ?
+    `,
+    )
+    .all(taskId);
+}
+
+function loadDirectDependents(db, taskId) {
+  return db
+    .prepare(
+      `
+      SELECT t.* FROM tasks t
+      JOIN dependencies d ON d.task_id = t.id
+      WHERE d.depends_on_task_id = ?
+      ORDER BY t.priority, t.id
+    `,
+    )
+    .all(taskId);
+}
+
+// The full transitive closure of tasks blocked on `taskId`, not just its
+// direct dependents (spec example: BLOCKED DOWNSTREAM lists the ready
+// task's entire remaining chain — contract, repository, service, screen —
+// not only the one task directly depending on it). Walked breadth-first,
+// de-duplicated, in dependency order.
+function loadBlockedDownstream(db, taskId) {
+  const seen = new Set([taskId]);
+  const result = [];
+  let frontier = [taskId];
+  while (frontier.length > 0) {
+    const next = [];
+    for (const id of frontier) {
+      for (const dep of loadDirectDependents(db, id)) {
+        if (seen.has(dep.id)) continue;
+        seen.add(dep.id);
+        result.push(dep);
+        next.push(dep.id);
+      }
+    }
+    frontier = next;
+  }
+  return result;
+}
+
+// Assembles the packet for `task` (already known ready) by querying its
+// intent, requirements, and blocked downstream chain. Returns null fields
+// never — every field here is NOT NULL on tasks, or defaults to an empty
+// list.
+function assemblePacket(db, task) {
+  const intent = loadIntent(db, task.intent_id);
+  const requirements = loadTaskRequirements(db, task.id);
+  const dependents = loadBlockedDownstream(db, task.id);
+
+  return {
+    task,
+    intent,
+    requirements,
+    dependents,
+  };
+}
+
+// Returns the assembled packet for the one ready task (spec: readiness
+// SELECT), or null if no task is ready.
+export function nextTask(db) {
+  const task = findReadyTask(db);
+  if (!task) return null;
+  return assemblePacket(db, task);
+}
+
+// Tasks stalled awaiting a re-verify: `failed` (verification returned
+// nonzero) or `implemented` (scope violation refused to run it). Neither
+// is pickable by the readiness query, so when `nextTask` returns null the
+// caller uses this to tell "the build is finished" apart from "the build
+// is stuck on a task that needs fixing" — otherwise a failed task makes
+// a blocked graph look complete.
+export function stalledTasks(db) {
+  return db
+    .prepare(
+      `
+      SELECT t.* FROM tasks t
+      WHERE t.status IN ('failed', 'implemented')
+      ORDER BY t.priority, t.id
+    `,
+    )
+    .all();
+}
+
+// Renders a packet into the STATUS / INTENT / RELEVANT RULES / WHY NOW /
+// BLOCKED DOWNSTREAM / ALLOWED SCOPE / VERIFICATION format. The spec
+// splits this across two examples — the `hedgehog next` display and "The
+// task packet" (which carries the intent and its rules) — but an agent
+// receives one thing, so the packet is one thing: everything the worker
+// needs to build the task without reading the plan.
+export function formatNext(packet) {
+  const { task, intent, requirements, dependents } = packet;
+  const scopeGlobs = JSON.parse(task.scope_globs);
+
+  const lines = [];
+  lines.push(`TASK  ${task.id}`);
+  lines.push(task.objective);
+  lines.push('');
+  lines.push('STATUS   READY');
+  lines.push('');
+  lines.push('INTENT');
+  lines.push(`  ${intent.goal}`);
+  lines.push(`  ${intent.outcome}`);
+  lines.push('');
+  lines.push('RELEVANT RULES');
+  if (requirements.length === 0) {
+    lines.push('  (none recorded)');
+  } else {
+    for (const req of requirements) {
+      lines.push(`  - ${req.statement}`);
+    }
+  }
+  lines.push('');
+  lines.push('WHY NOW');
+  lines.push(`  ✓ Intent "${intent.id}" compiled into the graph`);
+  lines.push(`  ✓ Domain module "${task.module}" resolved`);
+  lines.push('  ✓ No incomplete dependencies');
+  lines.push('');
+  lines.push('BLOCKED DOWNSTREAM');
+  if (dependents.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const dep of dependents) {
+      lines.push(`  ✗ ${dep.id}   ${dep.layer}`);
+    }
+  }
+  lines.push('');
+  lines.push('ALLOWED SCOPE');
+  for (const glob of scopeGlobs) lines.push(`  ${glob}`);
+  lines.push('');
+  lines.push('VERIFICATION');
+  lines.push(`  ${task.verify_command}`);
+
+  return lines.join('\n');
+}

package/src/db/plan.mjs

@@ -0,0 +1,222 @@
+// `hedgehog plan` — compiles pending intents against the project's core
+// definition into `tasks` + `dependencies` rows. See
+// hedgehog-persistent-build-graph.md, "The build graph" and "Task
+// lifecycle", plus the readiness SELECT under "Schema".
+//
+// full-stack-app: one task per layer per intent (an intent is a domain
+// module — see the core definition's `{module}` placeholder). landing-page:
+// one task per phase, no module axis. Both are the same operation — walk
+// a core definition's layer chain once per intent — because a linear
+// chain is the degenerate case of the layer graph (spec: MVP scope
+// item 5).
+
+function fillModule(template, module) {
+  return template.replaceAll('{module}', module);
+}
+
+// Deterministic, human-legible task id: <INTENT>-<LAYER>, upper-cased.
+// Stable across repeated `hedgehog plan` runs on the same intent/layer.
+function taskId(intentId, layerId) {
+  return `${intentId}-${layerId}`.toUpperCase();
+}
+
+// Compiles one intent's tasks + intra-intent dependencies (mirroring the
+// core definition's layer order) without touching the database.
+function compileIntentTasks(intent, core) {
+  const module = intent.id;
+  const tasks = core.layers.map((layer) => ({
+    id: taskId(intent.id, layer.id),
+    intent_id: intent.id,
+    module,
+    layer: layer.id,
+    objective: `${layer.id} for ${module}`,
+    scope_globs: JSON.stringify(layer.scope.map((g) => fillModule(g, module))),
+    verify_command: fillModule(layer.verify, module),
+    commit_message: fillModule(layer.commit, module),
+    priority: intent.priority,
+  }));
+
+  const dependencies = [];
+  for (const layer of core.layers) {
+    if (!layer.depends_on) continue;
+    dependencies.push({
+      task_id: taskId(intent.id, layer.id),
+      depends_on_task_id: taskId(intent.id, layer.depends_on),
+    });
+  }
+
+  return { tasks, dependencies };
+}
+
+// Reads pending intents (status 'proposed' or 'planned' — not yet
+// compiled into tasks) in dependency order: an intent is compiled only
+// after every intent it depends_on. Intents with no ordering constraint
+// between them compile in `priority, id` order.
+function orderIntents(intents, intentDependencies) {
+  const byId = new Map(intents.map((i) => [i.id, i]));
+  const dependsOn = new Map(intents.map((i) => [i.id, []]));
+  for (const { intent_id, depends_on_intent_id } of intentDependencies) {
+    if (!dependsOn.has(intent_id)) continue;
+    if (!byId.has(depends_on_intent_id)) continue;
+    dependsOn.get(intent_id).push(depends_on_intent_id);
+  }
+
+  const ordered = [];
+  const visited = new Set();
+  const visiting = new Set();
+
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) {
+      throw new Error(`intent_dependencies cycle detected at "${id}"`);
+    }
+    visiting.add(id);
+    for (const depId of dependsOn.get(id) ?? []) visit(depId);
+    visiting.delete(id);
+    visited.add(id);
+    ordered.push(byId.get(id));
+  }
+
+  const remaining = [...intents].sort(
+    (a, b) => a.priority - b.priority || a.id.localeCompare(b.id),
+  );
+  for (const intent of remaining) visit(intent.id);
+
+  return ordered;
+}
+
+const PENDING_INTENT_STATUSES = ['proposed', 'planned'];
+
+function loadPendingIntents(db) {
+  const placeholders = PENDING_INTENT_STATUSES.map(() => '?').join(',');
+  return db
+    .prepare(`SELECT * FROM intents WHERE status IN (${placeholders})`)
+    .all(...PENDING_INTENT_STATUSES);
+}
+
+function loadIntentDependencies(db) {
+  return db.prepare('SELECT * FROM intent_dependencies').all();
+}
+
+function loadIntentRequirements(db, intentId) {
+  return db
+    .prepare('SELECT id FROM requirements WHERE intent_id = ? ORDER BY id')
+    .all(intentId);
+}
+
+function taskExists(db, taskId) {
+  return db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(taskId) !== undefined;
+}
+
+const insertTask = (db) =>
+  db.prepare(`
+    INSERT INTO tasks
+      (id, intent_id, module, layer, objective, scope_globs, verify_command,
+       commit_message, priority, status)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'planned')
+  `);
+
+const insertDependency = (db) =>
+  db.prepare(`
+    INSERT OR IGNORE INTO dependencies (task_id, depends_on_task_id)
+    VALUES (?, ?)
+  `);
+
+const insertTaskRequirement = (db) =>
+  db.prepare(`
+    INSERT OR IGNORE INTO task_requirements (task_id, requirement_id)
+    VALUES (?, ?)
+  `);
+
+// Compiles every pending intent against `core` and writes tasks +
+// dependencies to `db`. Idempotent per intent: an intent whose tasks
+// already exist (by id) is skipped entirely, so re-running `hedgehog
+// plan` after adding a new intent doesn't touch already-compiled ones.
+//
+// Cross-intent ordering: for each `intent_dependencies` edge (A depends
+// on B), A's first task in layer order gets an extra `dependencies` row
+// on B's last task in layer order — so A's chain cannot start until B's
+// chain is entirely `complete`.
+//
+// Requirement linkage: every task an intent compiles to is linked to all
+// of that intent's requirements via `task_requirements`. The compiler has
+// no basis for splitting requirements across layers — a rule like
+// "invitations expire after 7 days" constrains the schema, the service,
+// and the screen alike — so each layer carries the whole set and the task
+// packet shows the agent every rule its intent is bound by. Without this
+// the traceability chain (spec: "Traceability") has no middle link:
+// `hedgehog why` could reach the intent but never name the requirement a
+// file satisfies.
+export function planTasks(db, core) {
+  const intents = loadPendingIntents(db);
+  const intentDependencies = loadIntentDependencies(db);
+  const ordered = orderIntents(intents, intentDependencies);
+
+  const dependsOnByIntent = new Map();
+  for (const { intent_id, depends_on_intent_id } of intentDependencies) {
+    if (!dependsOnByIntent.has(intent_id)) dependsOnByIntent.set(intent_id, []);
+    dependsOnByIntent.get(intent_id).push(depends_on_intent_id);
+  }
+
+  const firstLayerId = core.layers[0].id;
+  const lastLayerId = core.layers[core.layers.length - 1].id;
+
+  const runInsert = insertTask(db);
+  const runInsertDep = insertDependency(db);
+  const runInsertTaskReq = insertTaskRequirement(db);
+
+  const compiledIntentIds = [];
+  const skippedIntentIds = [];
+
+  db.exec('BEGIN');
+  try {
+    for (const intent of ordered) {
+      const firstTaskId = taskId(intent.id, firstLayerId);
+      if (taskExists(db, firstTaskId)) {
+        skippedIntentIds.push(intent.id);
+        continue;
+      }
+
+      const { tasks, dependencies } = compileIntentTasks(intent, core);
+      const requirementIds = loadIntentRequirements(db, intent.id).map((r) => r.id);
+      for (const t of tasks) {
+        runInsert.run(
+          t.id,
+          t.intent_id,
+          t.module,
+          t.layer,
+          t.objective,
+          t.scope_globs,
+          t.verify_command,
+          t.commit_message,
+          t.priority,
+        );
+        for (const requirementId of requirementIds) {
+          runInsertTaskReq.run(t.id, requirementId);
+        }
+      }
+      for (const d of dependencies) {
+        runInsertDep.run(d.task_id, d.depends_on_task_id);
+      }
+
+      // Cross-intent edge: this intent's first task can't be ready until
+      // every intent it depends_on has its last task complete.
+      for (const depIntentId of dependsOnByIntent.get(intent.id) ?? []) {
+        const depLastTaskId = taskId(depIntentId, lastLayerId);
+        runInsertDep.run(firstTaskId, depLastTaskId);
+      }
+
+      // An intent whose tasks now exist is no longer `proposed` — it's
+      // been compiled into the graph and is being built.
+      db.prepare("UPDATE intents SET status = 'active' WHERE id = ?").run(intent.id);
+
+      compiledIntentIds.push(intent.id);
+    }
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+
+  return { compiled: compiledIntentIds, skipped: skippedIntentIds };
+}

package/src/db/schema.mjs

@@ -0,0 +1,95 @@
+// The Hedgehog build graph schema — see hedgehog-persistent-build-graph.md,
+// "SQLite as build state" → Schema, for the source of truth these table
+// definitions mirror verbatim.
+
+export const SCHEMA_SQL = `
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS intents (
+  id          TEXT PRIMARY KEY,
+  goal        TEXT NOT NULL,
+  outcome     TEXT NOT NULL,
+  priority    INTEGER NOT NULL DEFAULT 100,
+  status      TEXT NOT NULL DEFAULT 'proposed'
+              CHECK (status IN ('proposed','planned','active','complete')),
+  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS requirements (
+  id          TEXT PRIMARY KEY,
+  intent_id   TEXT NOT NULL REFERENCES intents(id) ON DELETE CASCADE,
+  kind        TEXT NOT NULL CHECK (kind IN ('rule','constraint','acceptance')),
+  statement   TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS intent_dependencies (
+  intent_id            TEXT NOT NULL REFERENCES intents(id) ON DELETE CASCADE,
+  depends_on_intent_id TEXT NOT NULL REFERENCES intents(id) ON DELETE CASCADE,
+  PRIMARY KEY (intent_id, depends_on_intent_id),
+  CHECK (intent_id <> depends_on_intent_id)
+);
+
+CREATE TABLE IF NOT EXISTS tasks (
+  id             TEXT PRIMARY KEY,
+  intent_id      TEXT NOT NULL REFERENCES intents(id) ON DELETE CASCADE,
+  module         TEXT NOT NULL,
+  layer          TEXT NOT NULL,
+  objective      TEXT NOT NULL,
+  scope_globs    TEXT NOT NULL,
+  verify_command TEXT NOT NULL,
+  commit_message TEXT NOT NULL,
+  priority       INTEGER NOT NULL DEFAULT 100,
+  -- Every value here is one the engine actually writes. A CHECK listing
+  -- states nothing can produce documents a lifecycle that doesn't exist
+  -- and invites writing one the engine can't handle.
+  status         TEXT NOT NULL DEFAULT 'proposed'
+                 CHECK (status IN ('proposed','planned','ready',
+                                   'implemented','verified',
+                                   'complete','failed')),
+  created_at     TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS task_requirements (
+  task_id        TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  requirement_id TEXT NOT NULL REFERENCES requirements(id) ON DELETE CASCADE,
+  PRIMARY KEY (task_id, requirement_id)
+);
+
+CREATE TABLE IF NOT EXISTS dependencies (
+  task_id            TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  depends_on_task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  PRIMARY KEY (task_id, depends_on_task_id),
+  CHECK (task_id <> depends_on_task_id)
+);
+
+CREATE TABLE IF NOT EXISTS artifacts (
+  id        INTEGER PRIMARY KEY,
+  task_id   TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  path      TEXT NOT NULL,
+  kind      TEXT NOT NULL CHECK (kind IN ('created','modified')),
+  commit_sha TEXT
+);
+
+CREATE TABLE IF NOT EXISTS verifications (
+  id         INTEGER PRIMARY KEY,
+  task_id    TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  command    TEXT NOT NULL,
+  exit_code  INTEGER,
+  output     TEXT,
+  status     TEXT NOT NULL CHECK (status IN ('passed','failed')),
+  ran_at     TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+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'))
+);
+`;
+
+// Applies the schema to an already-open node:sqlite DatabaseSync instance.
+// Idempotent: safe to call against a DB that already has these tables.
+export function applySchema(db) {
+  db.exec(SCHEMA_SQL);
+}

package/src/db/status.mjs

@@ -0,0 +1,113 @@
+// `hedgehog status` — graph overview: task counts by status, and the
+// current ready list. See hedgehog-persistent-build-graph.md, "Task
+// lifecycle" for the status set and "The CLI is the only writer" for the
+// `hedgehog status` line.
+//
+// The ready list reuses next.mjs's readiness query rather than
+// reimplementing it: a task is pickable by `hedgehog next` when its
+// status is `planned` or `ready` (plan.mjs inserts `planned`;
+// verify.mjs's unlockReadyDependents sets `ready` directly) and it has
+// no dependency whose status isn't `complete`. `hedgehog status` lists
+// every task meeting that condition, not just the one `hedgehog next`
+// would pick.
+
+// The task lifecycle in order, matching the tasks CHECK constraint in
+// schema.mjs exactly — every status the engine can write, and no others.
+const TASK_STATUSES = [
+  'proposed',
+  'planned',
+  'ready',
+  'implemented',
+  'verified',
+  'complete',
+  'failed',
+];
+
+const READY_TASKS_SQL = `
+  SELECT t.* FROM tasks t
+  WHERE t.status IN ('planned', 'ready')
+    AND NOT EXISTS (
+      SELECT 1 FROM dependencies d
+      JOIN tasks dep ON dep.id = d.depends_on_task_id
+      WHERE d.task_id = t.id AND dep.status <> 'complete'
+    )
+  ORDER BY t.priority, t.id;
+`;
+
+function countTasksByStatus(db) {
+  const rows = db
+    .prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status')
+    .all();
+  const counts = Object.fromEntries(TASK_STATUSES.map((s) => [s, 0]));
+  for (const row of rows) counts[row.status] = row.n;
+  return counts;
+}
+
+function loadReadyTasks(db) {
+  return db.prepare(READY_TASKS_SQL).all();
+}
+
+// Tasks that need a human/agent decision before the graph can move again:
+// `failed` (verification ran and returned nonzero) and `implemented` (a
+// scope violation refused to run verification). Neither is pickable by
+// `hedgehog next`, so without listing them here a build whose only
+// remaining work is a failed task looks identical to a finished one —
+// "READY (none)" with no indication anything is wrong. Listing them is
+// what makes the fix-and-re-verify path in hedgehog-loop's Loop step 4
+// discoverable from a fresh context.
+const ATTENTION_TASKS_SQL = `
+  SELECT t.* FROM tasks t
+  WHERE t.status IN ('failed', 'implemented')
+  ORDER BY t.priority, t.id;
+`;
+
+function loadAttentionTasks(db) {
+  return db.prepare(ATTENTION_TASKS_SQL).all();
+}
+
+// Returns { counts, ready, attention, total } — counts keyed by every
+// status in the tasks CHECK constraint (present even at zero), ready the
+// full list of currently-pickable tasks, attention the stalled tasks
+// needing a re-verify, total the sum across all statuses.
+export function graphStatus(db) {
+  const counts = countTasksByStatus(db);
+  const ready = loadReadyTasks(db);
+  const attention = loadAttentionTasks(db);
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+  return { counts, ready, attention, total };
+}
+
+// Renders a graphStatus() result into a plain-text overview: counts by
+// status (only non-zero ones, in lifecycle order), then the ready list.
+export function formatStatus({ counts, ready, attention, total }) {
+  const lines = [];
+  lines.push(`TASKS  ${total}`);
+  lines.push('');
+  for (const status of TASK_STATUSES) {
+    if (counts[status] === 0) continue;
+    lines.push(`  ${status.padEnd(12)} ${counts[status]}`);
+  }
+  lines.push('');
+  lines.push('READY');
+  if (ready.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const task of ready) {
+      lines.push(`  ${task.id}   ${task.layer}   ${task.objective}`);
+    }
+  }
+
+  if (attention && attention.length > 0) {
+    lines.push('');
+    lines.push('NEEDS ATTENTION');
+    for (const task of attention) {
+      const reason =
+        task.status === 'failed' ? 'verification failed' : 'scope violation';
+      lines.push(`  ${task.id}   ${task.layer}   ${reason}`);
+    }
+    lines.push('');
+    lines.push('  Fix the work, then re-run: hedgehog verify <task-id>');
+  }
+
+  return lines.join('\n');
+}