@skyf0xx/hedgehog 6.3.0 → 6.3.1

package/bin/cli.mjs

@@ -59,7 +59,7 @@ import {
 } from '../src/db/requires.mjs';
 import { whyPath, formatWhy } from '../src/db/why.mjs';
 import { addFriction, listFriction } from '../src/db/friction.mjs';
-import { addDebt, listDebt } from '../src/db/debt.mjs';
+import { addDebt, listDebt, resolveDebt } from '../src/db/debt.mjs';
 import { addDecision, listDecisions } from '../src/db/decision.mjs';
 import {
   shouldPromptForStar,
@@ -663,7 +663,8 @@ ${bold('Usage')}
   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 debt add <task-id> "<note>"   declare debt that lands in dependent tasks' packets
-  npx @skyf0xx/hedgehog debt list [<task-id>]     list declared debt, oldest first
+  npx @skyf0xx/hedgehog debt list [<task-id>] [--all]   list open debt, oldest first (--all includes resolved)
+  npx @skyf0xx/hedgehog debt resolve <debt-id> --reason "<why>"   mark a debt note resolved
   npx @skyf0xx/hedgehog decision add <task-id> "<note>"   declare a decision that lands in dependent tasks' packets
   npx @skyf0xx/hedgehog decision list [<task-id>]     list declared decisions, oldest first
   npx @skyf0xx/hedgehog db migrate                bring the graph's schema up to the latest version
@@ -3844,28 +3845,61 @@ async function debtCommand(args) {
   }
 
   if (sub === 'list') {
-    const taskId = args[1];
+    const includeResolved = args.includes('--all') || args.includes('--resolved');
+    const taskId = args.slice(1).find((a) => !a.startsWith('--'));
     const db = openDb();
     let entries;
     try {
-      entries = listDebt(db, taskId);
+      entries = listDebt(db, taskId, { includeResolved });
     } finally {
       db.close();
     }
 
     if (entries.length === 0) {
-      console.log(`${dim('No debt declared.')}\n`);
+      console.log(`${dim(includeResolved ? 'No debt declared.' : 'No open debt.')}\n`);
       return;
     }
     for (const entry of entries) {
       console.log(`#${entry.id}  ${dim(entry.loggedAt)}  ${bold(entry.taskId)}`);
-      console.log(`  ${entry.note}\n`);
+      console.log(`  ${entry.note}`);
+      if (entry.resolvedAt) {
+        console.log(`  ${green('resolved')} ${dim(entry.resolvedAt)} — ${entry.resolvedReason}`);
+      }
+      console.log('');
+    }
+    return;
+  }
+
+  if (sub === 'resolve') {
+    const debtId = args[1];
+    const reasonIdx = args.indexOf('--reason');
+    const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : undefined;
+
+    if (!debtId || debtId.startsWith('--') || !reason) {
+      console.error(`${red('Usage:')} hedgehog debt resolve <debt-id> --reason "<why>"\n`);
+      process.exitCode = 1;
+      return;
     }
+
+    const db = openDb();
+    let result;
+    try {
+      result = await resolveDebt(db, { debtId: Number(debtId), reason });
+    } catch (err) {
+      console.error(`${red('Failed to resolve debt:')} ${err.message}\n`);
+      process.exitCode = 1;
+      return;
+    } finally {
+      db.close();
+    }
+
+    console.log(`  ${green('resolved')}  #${result.id} ${bold(result.taskId)}`);
+    console.log(`  ${dim(result.note)}`);
     return;
   }
 
   console.error(
-    `${red('Unknown debt subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog debt add <task-id> "<note>"\n   or: hedgehog debt list [<task-id>]\n`,
+    `${red('Unknown debt subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog debt add <task-id> "<note>"\n   or: hedgehog debt list [<task-id>] [--all]\n   or: hedgehog debt resolve <debt-id> --reason "<why>"\n`,
   );
   process.exitCode = 1;
 }

package/package.json

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

package/src/db/debt.mjs

@@ -58,14 +58,25 @@ export async function addDebt(db, { taskId, note }, notesDir = undefined) {
   return { id: Number(result.lastInsertRowid), taskId, note };
 }
 
-// Every debt row, oldest first, optionally narrowed to one task.
-export function listDebt(db, taskId) {
-  const where = taskId ? 'WHERE task_id = ?' : '';
-  const params = taskId ? [taskId] : [];
+// Every debt row, oldest first, optionally narrowed to one task. Resolved
+// rows are excluded by default — `debt list` is meant to answer "what's
+// still open", the same way `reconcile list` never re-surfaces a task once
+// it has closed — and included when `includeResolved` is set (`--all`).
+export function listDebt(db, taskId, { includeResolved = false } = {}) {
+  const conditions = [];
+  const params = [];
+  if (taskId) {
+    conditions.push('task_id = ?');
+    params.push(taskId);
+  }
+  if (!includeResolved) conditions.push('resolved_at IS NULL');
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
   try {
     return db
       .prepare(
-        `SELECT id, task_id AS taskId, note, logged_at AS loggedAt FROM debt ${where} ORDER BY id ASC`,
+        `SELECT id, task_id AS taskId, note, logged_at AS loggedAt,
+                resolved_at AS resolvedAt, resolved_reason AS resolvedReason
+         FROM debt ${where} ORDER BY id ASC`,
       )
       .all(...params);
   } catch {
@@ -73,3 +84,54 @@ export function listDebt(db, taskId) {
     return [];
   }
 }
+
+// Count of open (unresolved) debt across the whole graph — the one-line
+// figure `hedgehog next`/`hedgehog claim` surface so debt doesn't
+// accumulate silently with nothing prompting a look at it.
+export function openDebtCount(db) {
+  try {
+    const row = db.prepare('SELECT COUNT(*) AS n FROM debt WHERE resolved_at IS NULL').get();
+    return row.n;
+  } catch {
+    return 0;
+  }
+}
+
+// Resolves one debt row by id: marks it resolved in the DB and writes the
+// committed record behind it — same ordering as addDebt (file before row)
+// and the same reason: if the write fails, nothing has been resolved on a
+// fact that would not survive the next rebuild.
+//
+// The committed note is keyed by the debt row's own (task_id, note,
+// logged_at) rather than its DB `id`, because that id is a fresh
+// autoincrement every time rebuild.mjs#replayNotes re-inserts debt rows —
+// it is not stable across a rebuild, so a resolution referencing it would
+// point at nothing once replayed. The triple already committed for the
+// debt note itself is the one part of its identity that *is* stable.
+export async function resolveDebt(db, { debtId, reason }, notesDir = undefined) {
+  applySchema(db);
+
+  if (!debtId) throw new Error('debt resolve requires a debt id');
+  if (!reason) throw new Error('debt resolve requires a --reason');
+
+  const row = db
+    .prepare('SELECT id, task_id AS taskId, note, logged_at AS loggedAt, resolved_at AS resolvedAt FROM debt WHERE id = ?')
+    .get(debtId);
+  if (!row) throw new Error(`no such debt: #${debtId}`);
+  if (row.resolvedAt) throw new Error(`debt #${debtId} is already resolved`);
+
+  const resolvedAt = new Date().toISOString();
+  await appendNote(
+    row.taskId,
+    { kind: 'debt-resolve', resolves: row.loggedAt, reason, loggedAt: resolvedAt },
+    notesDir,
+  );
+
+  db.prepare('UPDATE debt SET resolved_at = ?, resolved_reason = ? WHERE id = ?').run(
+    resolvedAt,
+    reason,
+    debtId,
+  );
+
+  return { id: row.id, taskId: row.taskId, note: row.note, resolvedAt, resolvedReason: reason };
+}

package/src/db/next.mjs

@@ -105,7 +105,9 @@ function loadInheritedDebt(db, taskId) {
   try {
     return db
       .prepare(
-        `SELECT task_id AS taskId, note FROM debt WHERE task_id IN (${placeholders}) ORDER BY id ASC`,
+        `SELECT task_id AS taskId, note FROM debt
+         WHERE task_id IN (${placeholders}) AND resolved_at IS NULL
+         ORDER BY id ASC`,
       )
       .all(...upstream);
   } catch {
@@ -113,6 +115,20 @@ function loadInheritedDebt(db, taskId) {
   }
 }
 
+// Total open (unresolved) debt across the whole graph — not just this
+// task's ancestors — so a packet can say plainly that debt exists even
+// where none of it happens to be inherited here. Tolerates a `debt` table
+// or `resolved_at` column that doesn't exist yet, the same way
+// loadInheritedDebt does.
+function loadOpenDebtCount(db) {
+  try {
+    const row = db.prepare('SELECT COUNT(*) AS n FROM debt WHERE resolved_at IS NULL').get();
+    return row.n;
+  } catch {
+    return 0;
+  }
+}
+
 // Decisions declared by anything this task inherits from (see
 // decision.mjs) — same upstream walk as loadInheritedDebt, same tolerance
 // for a `decisions` table that doesn't exist yet on an older graph.
@@ -181,6 +197,7 @@ function assemblePacket(db, task) {
   const incompleteDeps = incompleteDependencies(db, task.id);
   const inheritedDebt = loadInheritedDebt(db, task.id);
   const inheritedDecisions = loadInheritedDecisions(db, task.id);
+  const openDebtCount = loadOpenDebtCount(db);
 
   return {
     task,
@@ -190,6 +207,7 @@ function assemblePacket(db, task) {
     incompleteDeps,
     inheritedDebt,
     inheritedDecisions,
+    openDebtCount,
   };
 }
 
@@ -484,6 +502,7 @@ export function formatPacket(packet, statusLine, coreId = null, exists = null) {
     incompleteDeps = [],
     inheritedDebt = [],
     inheritedDecisions = [],
+    openDebtCount = 0,
   } = packet;
   const scopeGlobs = JSON.parse(task.scope_globs);
   const firstArrival = firstArrivalPackages(task, exists);
@@ -521,6 +540,11 @@ export function formatPacket(packet, statusLine, coreId = null, exists = null) {
       lines.push(`  ! ${entry.taskId}  ${entry.note}`);
     }
   }
+  if (openDebtCount > 0) {
+    lines.push(
+      `  ${openDebtCount} open debt note(s) across the whole graph — \`hedgehog debt list --all\` to see them all`,
+    );
+  }
   lines.push('');
   lines.push('INHERITED DECISIONS');
   if (inheritedDecisions.length === 0) {

package/src/db/notes.mjs

@@ -45,12 +45,21 @@ function validateNotesFile(record, path) {
     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') {
+    if (entry.kind !== 'debt' && entry.kind !== 'decision' && entry.kind !== 'debt-resolve') {
       throw new Error(
-        `${path}: notes file "${task}" has an entry with kind "${entry.kind}" — expected "debt" or "decision"`,
+        `${path}: notes file "${task}" has an entry with kind "${entry.kind}" — expected "debt", "decision", or "debt-resolve"`,
       );
     }
-    if (!entry.note || typeof entry.note !== 'string') {
+    if (entry.kind === 'debt-resolve') {
+      if (!entry.resolves || typeof entry.resolves !== 'string') {
+        throw new Error(
+          `${path}: notes file "${task}" has a "debt-resolve" entry with no "resolves" (the logged_at of the debt note it closes)`,
+        );
+      }
+      if (!entry.reason || typeof entry.reason !== 'string') {
+        throw new Error(`${path}: notes file "${task}" has a "debt-resolve" entry with no "reason"`);
+      }
+    } else 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') {
@@ -92,7 +101,7 @@ export async function loadNotes(notesDir = NOTES_DIR) {
 // 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) {
+export async function appendNote(taskId, { kind, note, loggedAt, resolves, reason }, notesDir = NOTES_DIR) {
   const path = notesFilePath(taskId, notesDir);
 
   let existing = [];
@@ -103,9 +112,17 @@ export async function appendNote(taskId, { kind, note, loggedAt }, notesDir = NO
     if (!err || err.code !== 'ENOENT') throw err;
   }
 
+  // `debt-resolve` entries carry `resolves`/`reason` instead of `note` —
+  // omit `note` entirely rather than writing it as undefined/null, so a
+  // resolve entry's shape matches what validateNotesFile expects back.
+  const entry =
+    kind === 'debt-resolve'
+      ? { kind, resolves, reason, logged_at: loggedAt }
+      : { kind, note, logged_at: loggedAt };
+
   const record = {
     task: taskId.toUpperCase(),
-    notes: [...existing, { kind, note, logged_at: loggedAt }],
+    notes: [...existing, entry],
   };
 
   await mkdir(notesDir, { recursive: true });

package/src/db/rebuild.mjs

@@ -110,23 +110,40 @@ function replayNotes(db, notesByTask) {
   const insertDecision = db.prepare(
     'INSERT INTO decisions (task_id, note, logged_at) VALUES (?, ?, ?)',
   );
+  const resolveDebtRow = db.prepare(
+    'UPDATE debt SET resolved_at = ?, resolved_reason = ? WHERE task_id = ? AND logged_at = ? AND resolved_at IS NULL',
+  );
 
   const orphaned = [];
+  // Two passes: every `debt`/`decision` entry inserted first, then every
+  // `debt-resolve` entry applied — a resolve entry can appear anywhere
+  // after its debt entry in the same file, but the row it references must
+  // already exist for the UPDATE to find it.
   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 });
+        if (entry.kind !== 'debt-resolve') orphaned.push({ kind: entry.kind, taskId, note: entry.note });
       }
       continue;
     }
     for (const entry of notes) {
       if (entry.kind === 'debt') {
         insertDebt.run(taskId, entry.note, entry.logged_at);
-      } else {
+      } else if (entry.kind === 'decision') {
         insertDecision.run(taskId, entry.note, entry.logged_at);
       }
     }
   }
+  for (const [taskId, notes] of notesByTask) {
+    if (taskExists.get(taskId) === undefined) continue;
+    for (const entry of notes) {
+      if (entry.kind !== 'debt-resolve') continue;
+      const result = resolveDebtRow.run(entry.logged_at, entry.reason, taskId, entry.resolves);
+      if (result.changes === 0) {
+        orphaned.push({ kind: entry.kind, taskId, note: `resolve for ${entry.resolves}` });
+      }
+    }
+  }
   return orphaned;
 }
 

package/src/db/schema.mjs

@@ -103,10 +103,12 @@ CREATE TABLE IF NOT EXISTS verifications (
 -- every task that (transitively) depends on task_id, so the limitation
 -- travels down the chain the same way the dependency does.
 CREATE TABLE IF NOT EXISTS debt (
-  id        INTEGER PRIMARY KEY,
-  task_id   TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
-  note      TEXT NOT NULL,
-  logged_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id               INTEGER PRIMARY KEY,
+  task_id          TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  note             TEXT NOT NULL,
+  logged_at        TEXT NOT NULL DEFAULT (datetime('now')),
+  resolved_at      TEXT,
+  resolved_reason  TEXT
 );
 
 -- Declared decision: a note one task leaves for the tasks that inherit
@@ -176,7 +178,7 @@ export function ensureTaskColumns(db) {
 // hand-set past what MIGRATIONS actually covers, since runMigrations
 // trusts this number to mean "every migration through this version has
 // run."
-export const CURRENT_SCHEMA_VERSION = 2;
+export const CURRENT_SCHEMA_VERSION = 3;
 
 // Forward migrations, applied in order to bring a graph's user_version up
 // to CURRENT_SCHEMA_VERSION. Unlike the CREATE TABLE IF NOT EXISTS /
@@ -209,6 +211,18 @@ const MIGRATIONS = [
       `);
     },
   },
+  {
+    version: 3,
+    // A `debt` row with no `resolved_at` reads back as unresolved, so an
+    // existing graph's rows default to open the moment this column exists.
+    migrate: (db) => {
+      const existing = new Set(db.prepare('PRAGMA table_info(debt)').all().map((row) => row.name));
+      if (!existing.has('resolved_at')) db.exec('ALTER TABLE debt ADD COLUMN resolved_at TEXT');
+      if (!existing.has('resolved_reason')) {
+        db.exec('ALTER TABLE debt ADD COLUMN resolved_reason TEXT');
+      }
+    },
+  },
 ];
 
 // Brings a graph's `PRAGMA user_version` up to CURRENT_SCHEMA_VERSION,

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

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