@skyf0xx/hedgehog 2.0.13 → 3.0.0

package/README.md

@@ -21,7 +21,7 @@ The codebase carries the context, not the model.
 Hedgehog combines:
 
 - **BMAD for planning** — turn an idea into a clear brief, requirements, and architecture
-- **An opinionated stack** — remove unnecessary technical decisions
+- **An opinionated stack** — remove unnecessary technical decisions, and settle the necessary ones once
 - **TDD and progressive layering** — build one tested layer at a time
 - **Mechanical enforcement** — use tooling and phase gates instead of trusting the AI to follow instructions
 - **Small context loops** — keep every change focused, verifiable, and easy to review
@@ -86,6 +86,12 @@ Sequence
 Artifact
 ```
 
+### Anything else
+
+A CLI, a library, a data pipeline, a compiler, etc. a project fitting neither
+shape gets its own build order, designed from your planning documents at
+intake rather than chosen from a menu.
+
 ![Why Hedgehog works: a different way to build with AI, comparing traditional AI workflow to Hedgehog](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.png)
 
 ## Install
@@ -109,7 +115,7 @@ npx @skyf0xx/hedgehog update
 ```
 
 This refreshes `.claude/agents/` and `.claude/skills/` only. It never
-touches `CLAUDE.md`, `TODO.md`, the core workspace, or
+touches `CLAUDE.md`, the build graph, the core workspace, or
 `skills/BMAD`, since those carry project-specific or write-once content.
 
 ## Why Hedgehog
@@ -121,7 +127,7 @@ Hedgehog improves the **system AI builds inside**.
 | | Raw AI | BMAD | Hedgehog |
 | --- | --- | --- | --- |
 | **Planning** | Conversation | Multi-agent workflow | BMAD |
-| **Architecture** | AI decides | Documented | Opinionated and enforced |
+| **Architecture** | AI decides, drifts | Documented | Decided once, then enforced |
 | **Build order** | Improvised | Guided by docs | Mechanically enforced |
 | **Context** | Held in the prompt | Large planning documents | Encoded in the codebase |
 | **Verification** | Optional | Process-dependent | Tests and phase gates |

package/bin/cli.mjs

@@ -11,8 +11,20 @@
 
 import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
+import { dbInit, DB_PATH } from '../src/db/init.mjs';
+import { loadCore } from '../src/db/core.mjs';
+import { planTasks } from '../src/db/plan.mjs';
+import { addIntent } from '../src/db/intent.mjs';
+import { nextTask, formatNext, stalledTasks } from '../src/db/next.mjs';
+import { verifyTask } from '../src/db/verify.mjs';
+import { graphStatus, formatStatus } from '../src/db/status.mjs';
+import { whyPath, formatWhy } from '../src/db/why.mjs';
+import { addFriction, listFriction } from '../src/db/friction.mjs';
+
+const AUTHORED_CORE_PATH = '.hedgehog/core.yaml';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
@@ -79,12 +91,6 @@ function plan(core) {
       include: `src/templates/CLAUDE.core.${core}.md`,
       to: 'CLAUDE.md',
     },
-    {
-      type: 'merge',
-      shell: 'src/templates/TODO.md',
-      include: `src/templates/TODO.core.${core}.md`,
-      to: 'TODO.md',
-    },
     // The pre-built, pre-verified workspace for the chosen core —
     // everything a fresh project of that shape needs at repo root
     // (lands the root package.json too, so there's no separate
@@ -98,11 +104,11 @@ function plan(core) {
 // project-specific or write-once content: `update` re-copies exactly
 // this, always overwriting, since a consuming project's own
 // .claude/agents and .claude/skills are supposed to match upstream
-// verbatim. CLAUDE.md/TODO.md carry project-filled content, the core
-// workspace is verified once by its bootstrap-core skill, and
-// skills/BMAD and skills/GSAP are re-vendored only deliberately (a
-// manual re-vendor, per each shelf's ATTRIBUTION.md) — none of those
-// belong in an update.
+// verbatim. CLAUDE.md carries project-filled content, the build graph
+// and core workspace are verified once by their own init/bootstrap-core
+// steps, and skills/BMAD and skills/GSAP are re-vendored only
+// deliberately (a manual re-vendor, per each shelf's ATTRIBUTION.md) —
+// none of those belong in an update.
 const UPDATE_PLAN = [
   { type: 'dir', from: 'src/agents', to: '.claude/agents' },
   { type: 'dir', from: 'src/skills', to: '.claude/skills' },
@@ -157,9 +163,9 @@ async function help() {
   console.log(`
 ${bold('Hedgehog installer')}
 
-Copies the Hedgehog agents and skills into ${bold('.claude/')} and drops the
-CLAUDE.md / TODO.md templates into the repo root, so the discipline is
-committed alongside your code.
+Copies the Hedgehog agents and skills into ${bold('.claude/')}, drops the
+CLAUDE.md template and an empty build graph (${bold('.hedgehog/hedgehog.db')})
+into the repo root, so the discipline is committed alongside your code.
 
 ${bold('Usage')}
   npx @skyf0xx/hedgehog init                      scaffold, ${DEFAULT_CORE} core (default)
@@ -167,6 +173,16 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --landing-page       scaffold the landing-page core instead
   npx @skyf0xx/hedgehog init --force              overwrite existing files
   npx @skyf0xx/hedgehog update                    refresh .claude/agents + .claude/skills
+  npx @skyf0xx/hedgehog db init                   create .hedgehog/hedgehog.db if absent
+  npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies
+  npx @skyf0xx/hedgehog intent add [flags]        add an intent (rules/requirements/dependencies)
+  npx @skyf0xx/hedgehog intent add --file <path>  add an intent from a JSON file
+  npx @skyf0xx/hedgehog next                      print the task packet for one ready task
+  npx @skyf0xx/hedgehog verify <task-id>          run scope + verify checks, commit on pass
+  npx @skyf0xx/hedgehog status                    graph overview: counts by status, ready list
+  npx @skyf0xx/hedgehog why <path>                provenance chain for a file
+  npx @skyf0xx/hedgehog friction add "<note>"     log a friction note [--task <task-id>]
+  npx @skyf0xx/hedgehog friction list             list logged friction, oldest first
   npx @skyf0xx/hedgehog --help
 
 Available cores: ${cores.join(', ')}
@@ -178,9 +194,9 @@ off to bootstrap.
 ${bold('update')} re-copies only .claude/agents and .claude/skills from the
 installed Hedgehog version, so an already-bootstrapped project can pick up
 agent/skill changes from a newer release. It always overwrites those two
-directories and never touches CLAUDE.md, TODO.md, the core workspace, or
-skills/BMAD and skills/GSAP — those are project-specific or updated
-deliberately, not by this command.
+directories and never touches CLAUDE.md, the build graph, the core
+workspace, or skills/BMAD and skills/GSAP — those are project-specific or
+updated deliberately, not by this command.
 `);
 }
 
@@ -234,6 +250,10 @@ async function init({ force, core }) {
     }
   }
 
+  const { created: dbCreated, path: dbPath } = await dbInit(DB_PATH);
+  console.log(`  ${dbCreated ? green('create') : dim('exists')}  ${dbPath}`);
+  if (dbCreated) written++;
+
   console.log(
     `\n${green(bold('Hedgehog installed.'))} ${dim(
       `${written} created${overwritten ? `, ${overwritten} overwritten` : ''}`,
@@ -287,13 +307,397 @@ async function update() {
   console.log(`  2. ${bold('git add -A && git commit -m "chore: update hedgehog"')}\n`);
   console.log(
     dim(
-      'CLAUDE.md, TODO.md, the core workspace, and skills/BMAD and\n' +
-        'skills/GSAP are untouched — those carry project-specific or\n' +
+      'CLAUDE.md, the build graph, the core workspace, and skills/BMAD\n' +
+        'and skills/GSAP are untouched — those carry project-specific or\n' +
         'write-once content.',
     ),
   );
 }
 
+async function dbCommand(args) {
+  const sub = args[0];
+  if (sub !== 'init') {
+    console.error(`${red('Unknown db subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog db init\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const { created, path } = await dbInit(DB_PATH);
+  console.log(
+    created
+      ? `  ${green('create')}  ${path}`
+      : `  ${dim('exists')}  ${path} ${dim('(no-op)')}`,
+  );
+}
+
+// Resolves the project's core definition: an authored .hedgehog/core.yaml
+// takes precedence (spec: "Authored cores"); otherwise the shipped Golden
+// Core landed at repo root by `init` (its core.yaml copies there along
+// with the rest of src/golden-cores/<core>).
+async function resolveCorePath() {
+  if (await exists(join(DEST_ROOT, AUTHORED_CORE_PATH))) {
+    return join(DEST_ROOT, AUTHORED_CORE_PATH);
+  }
+  const rootCore = join(DEST_ROOT, 'core.yaml');
+  if (await exists(rootCore)) return rootCore;
+  return null;
+}
+
+async function planCommand() {
+  const corePath = await resolveCorePath();
+  if (!corePath) {
+    console.error(
+      `${red('No core definition found.')} Expected ${bold(AUTHORED_CORE_PATH)} or a root ${bold('core.yaml')} (from \`hedgehog init\`).\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const core = await loadCore(corePath);
+  const db = new DatabaseSync(DB_PATH);
+  let result;
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    result = planTasks(db, core);
+  } finally {
+    db.close();
+  }
+
+  for (const id of result.compiled) console.log(`  ${green('compiled')}  ${id}`);
+  for (const id of result.skipped) console.log(`  ${dim('skipped')}  ${id} ${dim('(already compiled)')}`);
+  console.log(
+    `\n${green(bold('Plan complete.'))} ${dim(`${result.compiled.length} intent(s) compiled, ${result.skipped.length} skipped`)}\n`,
+  );
+}
+
+// Parses `hedgehog intent add` args into the same record shape
+// src/db/intent.mjs#normalizeIntent expects. Two sources: `--file <path>`
+// (a JSON file matching the intent record shape verbatim), or flags —
+// `--id`, `--goal`, `--outcome`, `--priority`, repeatable `--rule`
+// / `--constraint` / `--acceptance` / `--depends-on`. Mixing the two
+// is rejected: one intent, one unambiguous source.
+async function parseIntentArgs(args) {
+  const fileIdx = args.indexOf('--file');
+  const hasFlags = args.some((a) => a.startsWith('--') && a !== '--file');
+
+  if (fileIdx !== -1) {
+    if (hasFlags) {
+      throw new Error('--file cannot be combined with other intent flags');
+    }
+    const filePath = args[fileIdx + 1];
+    if (!filePath) throw new Error('--file requires a path');
+    const text = await readFile(resolve(DEST_ROOT, filePath), 'utf8');
+    return JSON.parse(text);
+  }
+
+  const record = { rules: [], constraints: [], acceptance: [], depends_on: [] };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    const value = args[i + 1];
+    switch (flag) {
+      case '--id':
+        record.id = value;
+        i++;
+        break;
+      case '--goal':
+        record.goal = value;
+        i++;
+        break;
+      case '--outcome':
+        record.outcome = value;
+        i++;
+        break;
+      case '--priority':
+        record.priority = Number(value);
+        i++;
+        break;
+      case '--rule':
+        record.rules.push(value);
+        i++;
+        break;
+      case '--constraint':
+        record.constraints.push(value);
+        i++;
+        break;
+      case '--acceptance':
+        record.acceptance.push(value);
+        i++;
+        break;
+      case '--depends-on':
+        record.depends_on.push(value);
+        i++;
+        break;
+      default:
+        throw new Error(`Unknown intent flag: ${flag}`);
+    }
+  }
+  return record;
+}
+
+async function intentCommand(args) {
+  const sub = args[0];
+  if (sub !== 'add') {
+    console.error(
+      `${red('Unknown intent subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog intent add --id <id> --goal <goal> --outcome <outcome> [--rule <r>]... [--depends-on <id>]...\n   or: hedgehog intent add --file <path.json>\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let record;
+  try {
+    record = await parseIntentArgs(args.slice(1));
+  } catch (err) {
+    console.error(`${red('Invalid arguments:')} ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = new DatabaseSync(DB_PATH);
+  let intent;
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    intent = addIntent(db, record);
+  } catch (err) {
+    console.error(`${red('Failed to add intent:')} ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  } finally {
+    db.close();
+  }
+
+  console.log(`  ${green('added')}  ${intent.id}`);
+  console.log(`  ${dim(`${intent.requirements.length} requirement(s), ${intent.depends_on.length} dependency(ies)`)}`);
+}
+
+async function nextCommand() {
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = new DatabaseSync(DB_PATH);
+  let packet;
+  let stalled = [];
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    packet = nextTask(db);
+    if (!packet) stalled = stalledTasks(db);
+  } finally {
+    db.close();
+  }
+
+  if (!packet) {
+    // A stalled task is not pickable, so without naming it here "no ready
+    // task" reads identically whether the build is finished or wedged on
+    // 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 =
+          task.status === 'failed' ? 'verification failed' : 'scope violation';
+        console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
+      }
+      console.error(
+        `\nFix the work, then re-run ${bold('hedgehog verify <task-id>')}.\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`${dim('No ready task.')} Nothing is planned with all dependencies complete.\n`);
+    return;
+  }
+
+  console.log(formatNext(packet));
+}
+
+async function verifyCommand(args) {
+  const taskId = args[0];
+  if (!taskId) {
+    console.error(`${red('Usage:')} hedgehog verify <task-id>\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = new DatabaseSync(DB_PATH);
+  let result;
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    result = verifyTask(db, taskId);
+  } catch (err) {
+    console.error(`${red('Verify failed:')} ${err.message}\n`);
+    process.exitCode = 1;
+    return;
+  } finally {
+    db.close();
+  }
+
+  if (result.outcome === 'scope_violation') {
+    console.error(`${red(bold('Scope violation.'))} Task ${bold(taskId)} stays ${bold('implemented')}.\n`);
+    console.error('Touched paths outside allowed scope:');
+    for (const path of result.offending) console.error(`  ${red('✗')} ${path}`);
+    console.error();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.outcome === 'failed') {
+    console.error(`${red(bold('Verification failed.'))} Task ${bold(taskId)} is now ${bold('failed')} (exit ${result.exitCode}).\n`);
+    if (result.output) console.error(result.output);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`${green(bold('Verified.'))} Task ${bold(taskId)} is now ${bold('complete')}.`);
+  if (result.commitSha) console.log(`  ${dim('commit')}  ${result.commitSha}`);
+  if (result.unlocked.length === 0) {
+    console.log(`  ${dim('no dependents unlocked')}`);
+  } else {
+    for (const id of result.unlocked) console.log(`  ${green('ready')}  ${id}`);
+  }
+  if (result.intentComplete) {
+    console.log(`  ${green('intent complete')}  ${dim('every task for this intent is done')}`);
+  }
+}
+
+async function statusCommand() {
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = new DatabaseSync(DB_PATH);
+  let result;
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    result = graphStatus(db);
+  } finally {
+    db.close();
+  }
+
+  console.log(formatStatus(result));
+}
+
+async function whyCommand(args) {
+  const path = args[0];
+  if (!path) {
+    console.error(`${red('Usage:')} hedgehog why <path>\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = new DatabaseSync(DB_PATH);
+  let chain;
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    chain = whyPath(db, path);
+  } finally {
+    db.close();
+  }
+
+  console.log(formatWhy(path, chain));
+}
+
+async function frictionCommand(args) {
+  const sub = args[0];
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (sub === 'add') {
+    // Split `--task <id>` out of the note words by index, not by value —
+    // filtering on the *value* dropped the flag but kept its argument in
+    // the note (and would mangle a note that legitimately contains the
+    // word "--task").
+    const rest = args.slice(1);
+    const taskIdx = rest.indexOf('--task');
+    const taskId = taskIdx !== -1 ? rest[taskIdx + 1] : undefined;
+    if (taskIdx !== -1 && !taskId) {
+      console.error(`${red('--task requires a task id')}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    const note = rest
+      .filter((_, i) => taskIdx === -1 || (i !== taskIdx && i !== taskIdx + 1))
+      .join(' ');
+    if (!note) {
+      console.error(`${red('Usage:')} hedgehog friction add "<note>" [--task <task-id>]\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const db = new DatabaseSync(DB_PATH);
+    let entry;
+    try {
+      db.exec('PRAGMA foreign_keys = ON;');
+      entry = addFriction(db, { note, taskId });
+    } catch (err) {
+      console.error(`${red('Failed to log friction:')} ${err.message}\n`);
+      process.exitCode = 1;
+      return;
+    } finally {
+      db.close();
+    }
+
+    console.log(`  ${green('logged')}  #${entry.id}${entry.taskId ? ` (${entry.taskId})` : ''}`);
+    return;
+  }
+
+  if (sub === 'list') {
+    const db = new DatabaseSync(DB_PATH);
+    let entries;
+    try {
+      db.exec('PRAGMA foreign_keys = ON;');
+      entries = listFriction(db);
+    } finally {
+      db.close();
+    }
+
+    if (entries.length === 0) {
+      console.log(`${dim('No friction logged.')}\n`);
+      return;
+    }
+    for (const entry of entries) {
+      console.log(`#${entry.id}  ${dim(entry.loggedAt)}${entry.taskId ? `  ${bold(entry.taskId)}` : ''}`);
+      console.log(`  ${entry.note}\n`);
+    }
+    return;
+  }
+
+  console.error(
+    `${red('Unknown friction subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog friction add "<note>" [--task <task-id>]\n   or: hedgehog friction list\n`,
+  );
+  process.exitCode = 1;
+}
+
 async function main() {
   const args = process.argv.slice(2);
   if (args.includes('--help') || args.includes('-h') || args.length === 0) {
@@ -324,6 +728,46 @@ async function main() {
     return;
   }
 
+  if (cmd === 'db') {
+    await dbCommand(args.slice(1));
+    return;
+  }
+
+  if (cmd === 'plan') {
+    await planCommand();
+    return;
+  }
+
+  if (cmd === 'intent') {
+    await intentCommand(args.slice(1));
+    return;
+  }
+
+  if (cmd === 'next') {
+    await nextCommand();
+    return;
+  }
+
+  if (cmd === 'verify') {
+    await verifyCommand(args.slice(1));
+    return;
+  }
+
+  if (cmd === 'status') {
+    await statusCommand();
+    return;
+  }
+
+  if (cmd === 'why') {
+    await whyCommand(args.slice(1));
+    return;
+  }
+
+  if (cmd === 'friction') {
+    await frictionCommand(args.slice(1));
+    return;
+  }
+
   console.error(`${red('Unknown command:')} ${cmd}\n`);
   await help();
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "2.0.13",
+  "version": "3.0.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -19,6 +19,7 @@
   "files": [
     "bin",
     "src/agents",
+    "src/db",
     "src/skills",
     "src/templates",
     "src/golden-cores",
@@ -26,7 +27,7 @@
     "skills/GSAP"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.5.0"
   },
   "keywords": [
     "claude",