@skyf0xx/hedgehog 6.1.6 → 6.1.7

package/bin/cli.mjs

@@ -3293,7 +3293,7 @@ async function debtCommand(args) {
     const db = openDb();
     let entry;
     try {
-      entry = addDebt(db, { taskId, note });
+      entry = await addDebt(db, { taskId, note });
     } catch (err) {
       console.error(
         `${red('Failed to declare debt:')} ${err.message}\n\nRun ${bold('hedgehog status')} to see valid task ids.\n`,
@@ -3364,7 +3364,7 @@ async function decisionCommand(args) {
     const db = openDb();
     let entry;
     try {
-      entry = addDecision(db, { taskId, note });
+      entry = await addDecision(db, { taskId, note });
     } catch (err) {
       console.error(
         `${red('Failed to declare decision:')} ${err.message}\n\nRun ${bold('hedgehog status')} to see valid task ids.\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "6.1.6",
+  "version": "6.1.7",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/agents/bootstrap.md

@@ -16,7 +16,10 @@ read it.
 
 You touch no build content on any core. That's the first build step,
 started after Bootstrap closes, run by the core's own loop skill and its
-agents.
+agents. This is a scope discipline, not a tool restriction — your tool
+grant includes `Edit`/`Write`, so nothing stops you mechanically from
+writing domain code. Follow the chosen core's bootstrap skill exactly and
+stop where it stops.
 
 ## Finding your step
 

package/src/db/debt.mjs

@@ -10,30 +10,37 @@
 // arrives. `debt add` records the note against the declaring task, and
 // next.mjs renders it into the packet of every task that depends on it.
 //
-// Unlike friction.mjs, nothing is written to a committed markdown log.
-// Debt is in-build traffic between two tasks, and a file under
-// `.hedgehog/` written mid-task sits outside every task's scope globs —
-// it would trip verify's scope gate on the very task that declared it.
-// Debt has no committed source `hedgehog db rebuild` could replay it
-// from, so rebuild.mjs carries it across a rebuild by task id instead
-// (a note whose task no longer exists there is reported, not dropped).
+// A note recorded here has a committed source behind it —
+// `.hedgehog/notes/<task-id>.json` (notes.mjs) — the same way
+// `.hedgehog/reconciled/*.json` backs a reconciliation. Debt is in-build
+// traffic between two tasks, and a file under `.hedgehog/` written
+// mid-task sits outside every task's scope globs — it would trip verify's
+// scope gate on the very task that declared it — so `hedgehog debt add`
+// writes it directly rather than through the declaring task's own commit.
+// `hedgehog db rebuild` replays it from there (rebuild.mjs), the same way
+// it replays overrides and reconciliations.
 
 import { applySchema } from './schema.mjs';
+import { appendNote } from './notes.mjs';
 
 const insertDebt = (db) =>
   db.prepare(`
-    INSERT INTO debt (task_id, note)
-    VALUES (?, ?)
+    INSERT INTO debt (task_id, note, logged_at)
+    VALUES (?, ?, ?)
   `);
 
 function taskExists(db, taskId) {
   return db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(taskId) !== undefined;
 }
 
-// Writes one debt row against `taskId`. The task must exist — debt
-// addressed to nobody reaches nobody, and the schema's foreign key would
-// reject it anyway, less legibly.
-export function addDebt(db, { taskId, note }) {
+// Writes one debt row against `taskId`, and its committed record. The
+// task must exist — debt addressed to nobody reaches nobody, and the
+// schema's foreign key would reject it anyway, less legibly.
+//
+// Committed file before DB row, deliberately — reconcile.mjs's same
+// ordering, for the same reason: if the write fails, nothing has been
+// recorded on a fact that would not survive the next rebuild.
+export async function addDebt(db, { taskId, note }, notesDir = undefined) {
   // Idempotent, and the migration path for a build graph created before
   // the `debt` table existed: dbInit only applies the schema to a DB it
   // just created, so an in-flight project's DB would otherwise have no
@@ -44,7 +51,10 @@ export function addDebt(db, { taskId, note }) {
   if (!note) throw new Error('debt requires a note');
   if (!taskExists(db, taskId)) throw new Error(`no such task: ${taskId}`);
 
-  const result = insertDebt(db).run(taskId, note);
+  const loggedAt = new Date().toISOString();
+  await appendNote(taskId, { kind: 'debt', note, loggedAt }, notesDir);
+
+  const result = insertDebt(db).run(taskId, note, loggedAt);
   return { id: Number(result.lastInsertRowid), taskId, note };
 }
 

package/src/db/decision.mjs

@@ -12,27 +12,33 @@
 // records the note against the declaring task, and next.mjs renders it
 // into the packet of every task that depends on it.
 //
-// Same as debt: nothing is written to a committed markdown log, so a
-// decision has no source `hedgehog db rebuild` could replay it from —
-// rebuild.mjs carries debt, decisions, and friction across a rebuild by
-// task id instead, for exactly this reason.
+// Same as debt: a note recorded here has a committed source behind it —
+// `.hedgehog/notes/<task-id>.json` (notes.mjs), the same way
+// `.hedgehog/reconciled/*.json` backs a reconciliation. `hedgehog db
+// rebuild` replays it from there, alongside overrides and
+// reconciliations.
 
 import { applySchema } from './schema.mjs';
+import { appendNote } from './notes.mjs';
 
 const insertDecision = (db) =>
   db.prepare(`
-    INSERT INTO decisions (task_id, note)
-    VALUES (?, ?)
+    INSERT INTO decisions (task_id, note, logged_at)
+    VALUES (?, ?, ?)
   `);
 
 function taskExists(db, taskId) {
   return db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(taskId) !== undefined;
 }
 
-// Writes one decision row against `taskId`. The task must exist — a
-// decision addressed to nobody reaches nobody, and the schema's foreign
-// key would reject it anyway, less legibly.
-export function addDecision(db, { taskId, note }) {
+// Writes one decision row against `taskId`, and its committed record. The
+// task must exist — a decision addressed to nobody reaches nobody, and
+// the schema's foreign key would reject it anyway, less legibly.
+//
+// Committed file before DB row, deliberately — reconcile.mjs's same
+// ordering, for the same reason: if the write fails, nothing has been
+// recorded on a fact that would not survive the next rebuild.
+export async function addDecision(db, { taskId, note }, notesDir = undefined) {
   // Idempotent, and the migration path for a build graph created before
   // the `decisions` table existed: dbInit only applies the schema to a DB
   // it just created, so an in-flight project's DB would otherwise have no
@@ -43,7 +49,10 @@ export function addDecision(db, { taskId, note }) {
   if (!note) throw new Error('decision requires a note');
   if (!taskExists(db, taskId)) throw new Error(`no such task: ${taskId}`);
 
-  const result = insertDecision(db).run(taskId, note);
+  const loggedAt = new Date().toISOString();
+  await appendNote(taskId, { kind: 'decision', note, loggedAt }, notesDir);
+
+  const result = insertDecision(db).run(taskId, note, loggedAt);
   return { id: Number(result.lastInsertRowid), taskId, note };
 }
 

package/src/db/notes.mjs

@@ -0,0 +1,121 @@
+// `.hedgehog/notes/<task-id>.json` — the committed record behind `debt`
+// and `decisions` rows.
+//
+// Both tables are operator- or agent-recorded notes with no committed
+// source, in the same position `.hedgehog/reconciled/*.json` was in
+// before reconcile.mjs existed: the only place they live is the DB, and
+// `hedgehog db rebuild` clears and re-derives the DB from committed files
+// on every run (rebuild.mjs#clearDerivedGraph). Before this file existed,
+// rebuild carried debt/decisions across by reading them out of the *same*
+// DB it was about to wipe — which only works because today there is
+// always exactly one DB. A worktree gets its own DB with no memory of
+// what a sibling worktree's DB held, so a note logged there and merged
+// back has nothing for a post-merge rebuild to carry across, and is
+// silently dropped. This file gives both tables the committed source
+// `friction` already has (`.hedgehog/friction/log.md`) and `reconciled`
+// records have (`.hedgehog/reconciled/*.json`), so a rebuild anywhere —
+// worktree or trunk — replays the same notes from the same files.
+//
+// One file per task, holding every debt and decision note logged against
+// it — unlike a reconciliation, which is one-shot per task, `debt add`
+// and `decision add` are routinely called more than once against the same
+// task, so the file is a list, not a single record, and a write appends
+// rather than refusing to overwrite.
+
+import { readdir, readFile, mkdir, writeFile, rename, rm } from 'node:fs/promises';
+
+export const NOTES_DIR = '.hedgehog/notes';
+
+function notesFilePath(taskId, notesDir = NOTES_DIR) {
+  return `${notesDir}/${taskId.toLowerCase()}.json`;
+}
+
+function validateNotesFile(record, path) {
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+    throw new Error(`${path}: notes file must be a JSON object`);
+  }
+  const { task, notes } = record;
+  if (!task || typeof task !== 'string') {
+    throw new Error(`${path}: notes file requires a "task" id (string)`);
+  }
+  if (!Array.isArray(notes)) {
+    throw new Error(`${path}: notes file requires a "notes" array`);
+  }
+  for (const entry of notes) {
+    if (entry === null || typeof entry !== 'object') {
+      throw new Error(`${path}: notes file "${task}" has a non-object entry in notes`);
+    }
+    if (entry.kind !== 'debt' && entry.kind !== 'decision') {
+      throw new Error(
+        `${path}: notes file "${task}" has an entry with kind "${entry.kind}" — expected "debt" or "decision"`,
+      );
+    }
+    if (!entry.note || typeof entry.note !== 'string') {
+      throw new Error(`${path}: notes file "${task}" has an entry with no "note" (string)`);
+    }
+    if (!entry.logged_at || typeof entry.logged_at !== 'string') {
+      throw new Error(`${path}: notes file "${task}" has an entry with no "logged_at" timestamp`);
+    }
+  }
+  return { task: task.toUpperCase(), notes };
+}
+
+// Every notes file in `notesDir`, validated, as a Map from task id to its
+// full { debt: [], decisions: [] } note list — the shape rebuild.mjs
+// replays directly. Absent directory reads as "no notes recorded", the
+// same way overrides.mjs#loadOverrides treats a missing directory.
+export async function loadNotes(notesDir = NOTES_DIR) {
+  let entries;
+  try {
+    entries = await readdir(notesDir);
+  } catch {
+    return new Map();
+  }
+
+  const byTask = new Map();
+  for (const name of entries.filter((n) => n.endsWith('.json')).sort()) {
+    const path = `${notesDir}/${name}`;
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile(path, 'utf8'));
+    } catch (err) {
+      throw new Error(`could not read notes file ${path}: ${err.message}`);
+    }
+    const { task, notes } = validateNotesFile(parsed, path);
+    byTask.set(task, notes);
+  }
+  return byTask;
+}
+
+// Appends one note to `taskId`'s file, creating it if this is the task's
+// first. Read-modify-write via temp file + rename, so a crash mid-write
+// never leaves a half-written file for loadNotes to trip on —
+// reconcile.mjs#writeReconciledFile's pattern, applied to a file that
+// grows instead of one written once.
+export async function appendNote(taskId, { kind, note, loggedAt }, notesDir = NOTES_DIR) {
+  const path = notesFilePath(taskId, notesDir);
+
+  let existing = [];
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    existing = validateNotesFile(parsed, path).notes;
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') throw err;
+  }
+
+  const record = {
+    task: taskId.toUpperCase(),
+    notes: [...existing, { kind, note, logged_at: loggedAt }],
+  };
+
+  await mkdir(notesDir, { recursive: true });
+  const tempPath = `${path}.tmp-${process.pid}`;
+  try {
+    await writeFile(tempPath, `${JSON.stringify(record, null, 2)}\n`);
+    await rename(tempPath, path);
+  } catch (err) {
+    await rm(tempPath, { force: true }).catch(() => {});
+    throw err;
+  }
+  return record;
+}

package/src/db/rebuild.mjs

@@ -30,8 +30,8 @@ import {
   orphanedReconciliations,
   reconciledNote,
   RECONCILED_DIR,
-  RECONCILED_NOTE_PREFIX,
 } from './reconcile.mjs';
+import { loadNotes, NOTES_DIR } from './notes.mjs';
 
 // Alphabetical by filename, purely to make the *tie-break* deterministic
 // across machines and runs. It is NOT the replay order — see
@@ -61,38 +61,32 @@ function intentExists(db, id) {
 // back, producing a graph no set of committed intents describes.
 //
 // Deleting `intents` cascades through requirements, tasks,
-// task_requirements, dependencies, artifacts and verifications — every
-// one of which this run re-derives. `debt`, `decisions`, and `friction`
-// are the exception: they are operator- or agent-recorded notes with no
-// committed source, so they are carried across by task id (deterministic,
-// so a note re-attaches to the same task the replay recompiles). A note
-// whose task no longer exists in the new graph has nowhere to live and is
-// reported rather than silently dropped.
+// task_requirements, dependencies, artifacts, verifications, `debt` and
+// `decisions` (all `ON DELETE CASCADE` from `tasks`) — every one of which
+// this run re-derives. `debt` and `decisions` are then replayed from
+// `.hedgehog/notes/*.json` (replayNotes, below) rather than carried
+// across from the DB's own prior rows — a worktree's own DB never held a
+// sibling worktree's notes, so carrying across only the current DB's rows
+// would silently drop everything logged elsewhere. `friction` keeps its
+// own committed source (`.hedgehog/friction/log.md`, friction.mjs) and is
+// left untouched here — its `task_id` is `ON DELETE SET NULL`, not
+// CASCADE, so its rows outlive this delete unattached rather than being
+// cleared.
 //
-// One class of decision row is excluded from that carry-across: the
-// provenance note a reconciliation writes (reconcile.mjs). That one DOES
-// have a committed source — `.hedgehog/reconciled/*.json` — and
-// replayReconciliations below re-writes it from that file. Carrying it
-// across as well would give a reconciled task two identical notes after
-// the first rebuild, and one more on every rebuild after that.
+// One class of decision row needs no replay from notes.mjs: the
+// provenance note a reconciliation writes (reconcile.mjs). That one has a
+// different committed source — `.hedgehog/reconciled/*.json` — and
+// replayReconciliations below re-writes it from that file instead.
 function clearDerivedGraph(db) {
-  const debt = db.prepare('SELECT task_id, note, logged_at FROM debt').all();
-  const decisions = db
-    .prepare('SELECT task_id, note, logged_at FROM decisions')
-    .all()
-    .filter((row) => !row.note.startsWith(RECONCILED_NOTE_PREFIX));
-  const friction = db.prepare('SELECT task_id, note, logged_at FROM friction').all();
-
   db.prepare('DELETE FROM intents').run();
-  // `friction.task_id` is ON DELETE SET NULL rather than CASCADE, so its
-  // rows outlive the delete above. Clear them too and let restoreNotes be
-  // the single writer, so a note is not duplicated against its own copy.
-  db.prepare('DELETE FROM friction').run();
-
-  return { debt, decisions, friction };
 }
 
-function restoreNotes(db, { debt, decisions, friction }) {
+// Replays `.hedgehog/notes/*.json` (notes.mjs) — the committed record
+// behind every `debt add` / `decision add` call — the same way
+// replayReconciliations below replays `.hedgehog/reconciled/*.json`. A
+// note whose task no longer exists in the new graph has nowhere to live
+// and is reported rather than silently dropped.
+function replayNotes(db, notesByTask) {
   const taskExists = db.prepare('SELECT 1 FROM tasks WHERE id = ?');
   const insertDebt = db.prepare(
     'INSERT INTO debt (task_id, note, logged_at) VALUES (?, ?, ?)',
@@ -100,38 +94,23 @@ function restoreNotes(db, { debt, decisions, friction }) {
   const insertDecision = db.prepare(
     'INSERT INTO decisions (task_id, note, logged_at) VALUES (?, ?, ?)',
   );
-  const insertFriction = db.prepare(
-    'INSERT INTO friction (task_id, note, logged_at) VALUES (?, ?, ?)',
-  );
 
   const orphaned = [];
-
-  for (const row of debt) {
-    if (taskExists.get(row.task_id) === undefined) {
-      orphaned.push({ kind: 'debt', taskId: row.task_id, note: row.note });
-      continue;
-    }
-    insertDebt.run(row.task_id, row.note, row.logged_at);
-  }
-
-  for (const row of decisions) {
-    if (taskExists.get(row.task_id) === undefined) {
-      orphaned.push({ kind: 'decision', taskId: row.task_id, note: row.note });
+  for (const [taskId, notes] of notesByTask) {
+    if (taskExists.get(taskId) === undefined) {
+      for (const entry of notes) {
+        orphaned.push({ kind: entry.kind, taskId, note: entry.note });
+      }
       continue;
     }
-    insertDecision.run(row.task_id, row.note, row.logged_at);
-  }
-
-  for (const row of friction) {
-    // friction.task_id is nullable — an unattached note always survives.
-    if (row.task_id !== null && taskExists.get(row.task_id) === undefined) {
-      insertFriction.run(null, row.note, row.logged_at);
-      orphaned.push({ kind: 'friction', taskId: row.task_id, note: row.note });
-      continue;
+    for (const entry of notes) {
+      if (entry.kind === 'debt') {
+        insertDebt.run(taskId, entry.note, entry.logged_at);
+      } else {
+        insertDecision.run(taskId, entry.note, entry.logged_at);
+      }
     }
-    insertFriction.run(row.task_id, row.note, row.logged_at);
   }
-
   return orphaned;
 }
 
@@ -392,17 +371,19 @@ export async function rebuildDb(
     intentsDir = INTENTS_DIR,
     overridesDir = OVERRIDES_DIR,
     reconciledDir = RECONCILED_DIR,
+    notesDir = NOTES_DIR,
   } = {},
 ) {
   applySchema(db);
 
-  const notes = clearDerivedGraph(db);
+  clearDerivedGraph(db);
 
   const intentsReplayed = await replayIntents(db, intentsDir);
 
   const core = await loadCore(corePath);
   const overrides = await loadOverrides(overridesDir);
   const reconciliations = await loadReconciliations(reconciledDir);
+  const notesByTask = await loadNotes(notesDir);
 
   planTasks(db, core, overrides);
 
@@ -412,7 +393,7 @@ export async function rebuildDb(
   const tasksReconciled = replayReconciliations(db, reconciliations);
   const orphanedReconciled = orphanedReconciliations(db, reconciliations);
 
-  const orphanedNotes = restoreNotes(db, notes);
+  const orphanedNotes = replayNotes(db, notesByTask);
 
   const drift = detectDrift(db, core, { overrides });
 

package/src/db/verify.mjs

@@ -66,18 +66,19 @@ import { OVERRIDES_DIR } from './overrides.mjs';
 import { RECONCILED_DIR } from './reconcile.mjs';
 import { INTENTS_DIR } from './intent.mjs';
 import { COMMUNITY_PATH } from './community.mjs';
+import { NOTES_DIR } from './notes.mjs';
 
 // Build-graph state directories: written by their own command
 // (`friction add`, `override add`, `intent add`/`db rebuild`, `reconcile
-// confirm`), committed by that command's own next step, never by a
-// layer's verify_command. A
+// confirm`, `debt add`/`decision add`), committed by that command's own
+// next step, never by a layer's verify_command. A
 // layer's own work never lands here, so a path under one of these is
 // never this task's doing regardless of when it changed relative to
 // claim time — unlike attributedToTask's fingerprint check, which only
 // excludes a path unchanged since claim and so still attributes a
 // friction note logged mid-layer (exactly what the loop skill instructs)
 // to whichever task happened to be building when it was logged.
-const BUILD_GRAPH_STATE_DIRS = [FRICTION_DIR, OVERRIDES_DIR, INTENTS_DIR, RECONCILED_DIR];
+const BUILD_GRAPH_STATE_DIRS = [FRICTION_DIR, OVERRIDES_DIR, INTENTS_DIR, RECONCILED_DIR, NOTES_DIR];
 
 function isBuildGraphStatePath(path) {
   return BUILD_GRAPH_STATE_DIRS.some((dir) => path === dir || path.startsWith(`${dir}/`));

package/src/hosts/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hedgehog",
-  "version": "6.1.6",
+  "version": "6.1.7",
   "description": "Hedgehog build discipline: ordered, tested, verified build steps.",
   "contextFileName": "GEMINI.md"
 }

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

@@ -76,29 +76,22 @@ paragraph.
    land correctly, and that the specific thing you changed shows up as
    expected (a new skill directory copied over, a new host's files in the
    right place, a new blueprint reachable from `hedgehog-core-design`).
-5. **Commit with Conventional Commits.** If the change is already one
-   logical unit, commit it directly (`feat(hosts): add windsurf support`,
-   `fix(tweaker): ...`, `docs(roadmap): ...`) — Hedgehog's commit format,
-   same as the one `hedgehog-loop` uses for a project build. If the working
-   tree has accumulated several unrelated changes that need splitting into
-   atomic commits, use the `conventional-commits` skill rather than
-   hand-rolling the split.
+5. **Commit with Conventional Commits**, in the format the
+   `conventional-commits` skill states. If the change is already one
+   logical unit, commit it directly. If the working tree has accumulated
+   several unrelated changes that need splitting into atomic commits, use
+   the `conventional-commits` skill rather than hand-rolling the split.
 6. **Push and open the PR**, following `pr-writing`'s checklist and shape
    (CI passing, one change, only verified claims):
    ```bash
    git push -u origin <branch-name>
-   gh pr create --repo skyf0xx/hedgehog --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF'
-   ## Summary
-   <1-3 bullets: what changed and why>
-
-   ## Test plan
-   - [ ] Ran `node bin/cli.mjs init` in a scratch dir and confirmed the change lands correctly
-   EOF
-   )"
+   gh pr create --repo skyf0xx/hedgehog --title "<type>(<scope>): <summary>" --body "..."
    ```
-   If the PR closes or addresses a `ROADMAP.md` item or a filed issue,
-   reference it (`Addresses the "<item name>" item in ROADMAP.md`, or
-   `Fixes #<n>`).
+   The body follows `pr-writing`'s shape (a short Summary, a Test plan
+   listing what was actually run — for this repo, `node bin/cli.mjs init`
+   in a scratch dir, confirming the change lands correctly). If the PR
+   closes or addresses a `ROADMAP.md` item or a filed issue, reference it
+   (`Addresses the "<item name>" item in ROADMAP.md`, or `Fixes #<n>`).
 7. **Check CI** with `gh pr checks <number> --repo skyf0xx/hedgehog` after
    opening. Fix a red check before asking for review.
 8. **Report the PR URL** `gh` returns and stop — don't merge, don't push