@skyf0xx/hedgehog 6.0.4 → 6.0.5

package/README.md

@@ -93,7 +93,7 @@ Every dependency is explicit, so Hedgehog knows which tasks can run in parallel.
 
 Agents fan out to give you great outcomes at **faster speeds**.
 
-## Your Code is a Graph
+## Live Dependency Awareness
 
 Hedgehog reaches for your editor's own Language Server Protocol integration to see what depends on what.
 
@@ -104,10 +104,9 @@ flowchart TD
     C --> D[Hedgehog]
 ```
 
-- **No index to go stale**: the language server's view of the code is always current
-- **No time spent hunting through the codebase for context**: find references and callers directly
-- **No more surprise breakage**: every task can check what depends on it before it edits
-- **Tests cover what changed**: verification that misses affected code gets caught
+- **Lower token cost**: a targeted symbol lookup replaces reading or grepping whole files for context
+- **Impact known before editing**: every task checks what depends on it before it changes anything
+- **Verification matches the real surface**: tests target what actually changed
 
 ## Deterministic Code Generation
 

package/README.zh-CN.md

@@ -93,7 +93,7 @@ npx @skyf0xx/hedgehog graph # 显示构建图
 
 多个 agent 并行展开工作，以**更快的速度**交付出色的结果。
 
-## 你的代码是一张图
+## 实时感知依赖关系
 
 Hedgehog 借助你编辑器自带的 Language Server Protocol 集成来查看代码间的依赖关系。
 
@@ -104,10 +104,9 @@ flowchart TD
     C --> D[Hedgehog]
 ```
 
-- **索引永不过期**：语言服务器看到的代码状态始终是最新的
-- **不必在代码库中翻找上下文**：直接查找引用和调用方
-- **不再意外改坏**：每个任务在动手前都能查一查有哪些代码依赖它
-- **测试覆盖改动**：遗漏受影响代码的验证会被发现
+- **更低的 token 成本**：精准的符号查找取代了为获取上下文而阅读或搜索整个文件
+- **改动前先知影响**：每个任务在动手前都能查清有哪些代码依赖它
+- **验证匹配真实改动范围**：测试针对实际发生变化的部分运行
 
 ## 确定性代码生成
 

package/bin/cli.mjs

@@ -53,6 +53,7 @@ import {
 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 { addDecision, listDecisions } from '../src/db/decision.mjs';
 import {
   shouldPromptForStar,
   recordStarAnswer,
@@ -397,19 +398,19 @@ function warnRebuildDrift({ drift }, corePath) {
   );
 }
 
-// Debt and friction notes are operator-recorded and have no committed
-// source, so a rebuild carries them across by task id. A note whose task
-// is no longer in the recompiled graph — its intent file was renamed,
-// deleted, or its layer sequence changed — has nowhere to re-attach.
-// Friction notes survive unattached (their task_id is nullable); debt
-// notes are lost, so both are printed with their text rather than
-// disappearing into a count.
+// Debt, decision, and friction notes are operator- or agent-recorded and
+// have no committed source, so a rebuild carries them across by task id.
+// A note whose task is no longer in the recompiled graph — its intent
+// file was renamed, deleted, or its layer sequence changed — has nowhere
+// to re-attach. Friction notes survive unattached (their task_id is
+// nullable); debt and decision notes are lost, so all three are printed
+// with their text rather than disappearing into a count.
 function warnOrphanedNotes({ orphanedNotes }) {
   if (!orphanedNotes || orphanedNotes.length === 0) return;
   console.log(
     `${yellow(bold('Notes without a task after rebuild.'))} ${orphanedNotes.length} note(s) referenced a\n` +
       'task the recompiled graph no longer holds. Friction notes were kept unattached;\n' +
-      'debt notes could not be, so they are reproduced here:\n',
+      'debt and decision notes could not be, so they are reproduced here:\n',
   );
   for (const note of orphanedNotes) {
     console.log(`  ${dim(note.kind)}  ${bold(note.taskId)}  ${note.note}`);
@@ -573,6 +574,9 @@ ${bold('Usage')}
   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 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
   npx @skyf0xx/hedgehog community star --answer <a>   record the star prompt's answer
   npx @skyf0xx/hedgehog --help
 
@@ -1155,9 +1159,13 @@ async function dbCommand(args) {
     await dbRebuildCommand();
     return;
   }
+  if (sub === 'migrate') {
+    await dbMigrateCommand();
+    return;
+  }
   if (sub !== 'init') {
     console.error(
-      `${red('Unknown db subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog db init\n   or: hedgehog db rebuild\n`,
+      `${red('Unknown db subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog db init\n   or: hedgehog db rebuild\n   or: hedgehog db migrate\n`,
     );
     process.exitCode = 1;
     return;
@@ -1179,6 +1187,44 @@ async function dbCommand(args) {
   }
 }
 
+// `hedgehog db migrate` — brings an existing build graph's schema up to
+// CURRENT_SCHEMA_VERSION on demand (see schema.mjs's runMigrations),
+// rather than only as a side effect of the next command that happens to
+// open the graph writably. Reports what moved, since an upgrade
+// shouldn't be a silent side effect the first time some other command
+// happens to trigger it.
+async function dbMigrateCommand() {
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const before = openDb({ readOnly: true });
+  const { user_version: fromVersion } = before.prepare('PRAGMA user_version').get();
+  before.close();
+
+  let toVersion;
+  try {
+    const db = openDb();
+    try {
+      ({ user_version: toVersion } = db.prepare('PRAGMA user_version').get());
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    console.error(`${red(err.message)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (fromVersion === toVersion) {
+    console.log(`${dim(`Build graph is already at the latest schema (v${toVersion}). Nothing to do.`)}\n`);
+    return;
+  }
+  console.log(`${green('Migrated')} build graph from schema v${fromVersion} to v${toVersion}.\n`);
+}
+
 // Resolves the project's core definition: an authored .hedgehog/core.yaml
 // takes precedence (spec: "Authored cores"); otherwise the core's
 // own core.yaml, which lands at repo root along with the rest of that
@@ -3095,6 +3141,77 @@ async function debtCommand(args) {
   process.exitCode = 1;
 }
 
+// `hedgehog decision add <task-id> "<note>"` / `hedgehog decision list
+// [<task-id>]` — declared decisions between tasks. A note recorded
+// against a task is rendered into the INHERITED DECISIONS section of the
+// packet of every task that depends on it (see src/db/decision.mjs and
+// src/db/next.mjs).
+async function decisionCommand(args) {
+  await ensureDb();
+
+  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') {
+    const taskId = args[1];
+    const note = args.slice(2).join(' ');
+    if (!taskId || !note) {
+      console.error(`${red('Usage:')} hedgehog decision add <task-id> "<note>"\n`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const db = openDb();
+    let entry;
+    try {
+      entry = 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`,
+      );
+      process.exitCode = 1;
+      return;
+    } finally {
+      db.close();
+    }
+
+    console.log(`  ${green('declared')}  #${entry.id} ${bold(entry.taskId)}`);
+    console.log(`  ${dim('reaches the packet of every task depending on it')}`);
+    return;
+  }
+
+  if (sub === 'list') {
+    const taskId = args[1];
+    const db = openDb();
+    let entries;
+    try {
+      entries = listDecisions(db, taskId);
+    } finally {
+      db.close();
+    }
+
+    if (entries.length === 0) {
+      console.log(`${dim('No decisions declared.')}\n`);
+      return;
+    }
+    for (const entry of entries) {
+      console.log(`#${entry.id}  ${dim(entry.loggedAt)}  ${bold(entry.taskId)}`);
+      console.log(`  ${entry.note}\n`);
+    }
+    return;
+  }
+
+  console.error(
+    `${red('Unknown decision subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog decision add <task-id> "<note>"\n   or: hedgehog decision list [<task-id>]\n`,
+  );
+  process.exitCode = 1;
+}
+
 // `hedgehog community star --answer starred|later|dismissed` — records
 // the star prompt's answer. No build graph or core needed: this is
 // project state about a question asked, not about the build.
@@ -3400,6 +3517,11 @@ async function main() {
     return;
   }
 
+  if (cmd === 'decision') {
+    await decisionCommand(args.slice(1));
+    return;
+  }
+
   if (cmd === 'community') {
     await communityCommand(args.slice(1));
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "6.0.4",
+  "version": "6.0.5",
   "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

@@ -14,9 +14,9 @@
 // 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.
-// The consequence is that debt does not survive `hedgehog db rebuild`
-// (which replays only `.hedgehog/intents/*.json`); by then the
-// inheriting task has usually already consumed 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).
 
 import { applySchema } from './schema.mjs';
 

package/src/db/decision.mjs

@@ -0,0 +1,64 @@
+// `hedgehog decision add` / `hedgehog decision list` — declared decisions
+// between tasks. See schema.mjs's `decisions` table and next.mjs's
+// INHERITED DECISIONS packet section.
+//
+// A layer that chose a pattern, a library, or a trade-off while building
+// has no way to tell the layer that inherits from it *why* — only debt.mjs
+// exists for that, and debt is specifically a known limitation, not a
+// decision that was made correctly and simply needs to be known. A
+// "we chose X because Y" comment in a source file is not a mechanism: the
+// inheriting task's packet is assembled from the graph, not from reading
+// its dependencies' comments, so the note never arrives. `decision add`
+// 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.
+
+import { applySchema } from './schema.mjs';
+
+const insertDecision = (db) =>
+  db.prepare(`
+    INSERT INTO decisions (task_id, note)
+    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 }) {
+  // 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
+  // table to insert into.
+  applySchema(db);
+
+  if (!taskId) throw new Error('decision requires a task id');
+  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);
+  return { id: Number(result.lastInsertRowid), taskId, note };
+}
+
+// Every decision row, oldest first, optionally narrowed to one task.
+export function listDecisions(db, taskId) {
+  const where = taskId ? 'WHERE task_id = ?' : '';
+  const params = taskId ? [taskId] : [];
+  try {
+    return db
+      .prepare(
+        `SELECT id, task_id AS taskId, note, logged_at AS loggedAt FROM decisions ${where} ORDER BY id ASC`,
+      )
+      .all(...params);
+  } catch {
+    // No `decisions` table yet (a build graph from before this table existed).
+    return [];
+  }
+}

package/src/db/init.mjs

@@ -24,12 +24,24 @@ export const dbAbsPath = (root = process.cwd()) => resolve(root, DB_PATH);
 // a call site that forgot them. journal_mode is skipped for read-only
 // handles — it requires write access and a readOnly connection has no
 // business changing the file's journal mode anyway.
+//
+// applySchema also runs here, not only from `dbInit`: a graph created by
+// an older CLI version is missing whatever tables/columns shipped since,
+// and every command besides `init`/`update` opens the graph straight
+// from here rather than going through dbInit first. Without this, those
+// commands only see the fix after someone thinks to rerun `init` on an
+// already-initialized project — which nothing prompts them to do — and
+// until then every query naming a newer column fails with "no such
+// column". Skipped for read-only handles for the same reason
+// journal_mode is: it requires write access, and a readOnly caller is
+// only ever reached after a writable open earlier in the same command.
 export function openDb({ readOnly = false } = {}) {
   const db = new DatabaseSync(dbAbsPath(), { readOnly });
   db.exec('PRAGMA foreign_keys = ON');
   db.exec('PRAGMA busy_timeout = 10000');
   if (!readOnly) db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA synchronous = NORMAL');
+  if (!readOnly) applySchema(db);
   return db;
 }
 

package/src/db/next.mjs

@@ -113,6 +113,24 @@ function loadInheritedDebt(db, taskId) {
   }
 }
 
+// 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.
+function loadInheritedDecisions(db, taskId) {
+  const upstream = loadUpstreamTaskIds(db, taskId);
+  if (upstream.length === 0) return [];
+  const placeholders = upstream.map(() => '?').join(',');
+  try {
+    return db
+      .prepare(
+        `SELECT task_id AS taskId, note FROM decisions WHERE task_id IN (${placeholders}) ORDER BY id ASC`,
+      )
+      .all(...upstream);
+  } catch {
+    return [];
+  }
+}
+
 function loadDirectDependents(db, taskId) {
   return db
     .prepare(
@@ -162,6 +180,7 @@ function assemblePacket(db, task) {
   const dependents = loadBlockedDownstream(db, task.id);
   const incompleteDeps = incompleteDependencies(db, task.id);
   const inheritedDebt = loadInheritedDebt(db, task.id);
+  const inheritedDecisions = loadInheritedDecisions(db, task.id);
 
   return {
     task,
@@ -170,6 +189,7 @@ function assemblePacket(db, task) {
     dependents,
     incompleteDeps,
     inheritedDebt,
+    inheritedDecisions,
   };
 }
 
@@ -344,8 +364,8 @@ const HONESTY = [
 ];
 
 // Renders a packet into the STATUS / INTENT / RELEVANT RULES /
-// INHERITED DEBT / WHY NOW / BLOCKED DOWNSTREAM / ALLOWED SCOPE /
-// PRE-READ / LAYER SHAPE / VERIFICATION / HONESTY format. The spec
+// INHERITED DEBT / INHERITED DECISIONS / WHY NOW / BLOCKED DOWNSTREAM /
+// ALLOWED SCOPE / PRE-READ / LAYER SHAPE / VERIFICATION / HONESTY 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
@@ -456,7 +476,15 @@ function firstArrivalLines(task, roots) {
 }
 
 export function formatPacket(packet, statusLine, coreId = null, exists = null) {
-  const { task, intent, requirements, dependents, incompleteDeps = [], inheritedDebt = [] } = packet;
+  const {
+    task,
+    intent,
+    requirements,
+    dependents,
+    incompleteDeps = [],
+    inheritedDebt = [],
+    inheritedDecisions = [],
+  } = packet;
   const scopeGlobs = JSON.parse(task.scope_globs);
   const firstArrival = firstArrivalPackages(task, exists);
 
@@ -494,6 +522,15 @@ export function formatPacket(packet, statusLine, coreId = null, exists = null) {
     }
   }
   lines.push('');
+  lines.push('INHERITED DECISIONS');
+  if (inheritedDecisions.length === 0) {
+    lines.push('  (none declared)');
+  } else {
+    for (const entry of inheritedDecisions) {
+      lines.push(`  * ${entry.taskId}  ${entry.note}`);
+    }
+  }
+  lines.push('');
   lines.push('WHY NOW');
   lines.push(`  ✓ Intent "${intent.id}" compiled into the graph`);
   // A once: true layer has no module — it compiled one task for the whole

package/src/db/rebuild.mjs

@@ -53,14 +53,15 @@ function intentExists(db, id) {
 //
 // Deleting `intents` cascades through requirements, tasks,
 // task_requirements, dependencies, artifacts and verifications — every
-// one of which this run re-derives. `debt` and `friction` are the
-// exception: they are operator-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.
+// 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.
 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();
   const friction = db.prepare('SELECT task_id, note, logged_at FROM friction').all();
 
   db.prepare('DELETE FROM intents').run();
@@ -69,14 +70,17 @@ function clearDerivedGraph(db) {
   // the single writer, so a note is not duplicated against its own copy.
   db.prepare('DELETE FROM friction').run();
 
-  return { debt, friction };
+  return { debt, decisions, friction };
 }
 
-function restoreNotes(db, { debt, friction }) {
+function restoreNotes(db, { debt, decisions, friction }) {
   const taskExists = db.prepare('SELECT 1 FROM tasks WHERE id = ?');
   const insertDebt = db.prepare(
     'INSERT INTO debt (task_id, note, logged_at) VALUES (?, ?, ?)',
   );
+  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 (?, ?, ?)',
   );
@@ -91,6 +95,14 @@ function restoreNotes(db, { debt, friction }) {
     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 });
+      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) {

package/src/db/schema.mjs

@@ -109,6 +109,21 @@ CREATE TABLE IF NOT EXISTS debt (
   logged_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
+-- Declared decision: a note one task leaves for the tasks that inherit
+-- from it, delivered the same way debt is (rendered into every dependent
+-- task's packet) but for a different purpose. Debt records what's still
+-- wrong with a task; a decision records why it was built the way it was
+-- — the pattern, library, or trade-off chosen. Without it, that
+-- reasoning lives only in the agent session that made the choice, and a
+-- dependent task built by a different, isolated session has no way to
+-- learn it beyond reading the diff and guessing.
+CREATE TABLE IF NOT EXISTS decisions (
+  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'))
+);
+
 CREATE TABLE IF NOT EXISTS friction (
   id        INTEGER PRIMARY KEY,
   task_id   TEXT REFERENCES tasks(id) ON DELETE SET NULL,
@@ -121,7 +136,25 @@ CREATE TABLE IF NOT EXISTS friction (
 // IF NOT EXISTS` above is a no-op against a DB created by an earlier
 // version, so a new column has to be ALTERed in explicitly or every
 // statement naming it fails on that DB. Each entry is `[name, ddl]`.
-const TASK_COLUMN_MIGRATIONS = [['claim_snapshot', 'claim_snapshot TEXT']];
+//
+// The lease columns (lease_owner, lease_expires_at, leased_at) and their
+// siblings (exclusive, verify_radius, blocked_reason) shipped together in
+// the same commit that introduced them to SCHEMA_SQL above, but were
+// never added here — so a graph created before that commit still lacks
+// them today, with every query naming lease_owner failing "no such
+// column" instead of self-healing the way claim_snapshot already does.
+const TASK_COLUMN_MIGRATIONS = [
+  ['exclusive', 'exclusive INTEGER NOT NULL DEFAULT 0'],
+  ['verify_radius', 'verify_radius TEXT'],
+  [
+    'blocked_reason',
+    "blocked_reason TEXT CHECK (blocked_reason IS NULL OR blocked_reason IN ('scope_violation','verification_failed','lease_expired'))",
+  ],
+  ['lease_owner', 'lease_owner TEXT'],
+  ['lease_expires_at', 'lease_expires_at TEXT'],
+  ['leased_at', 'leased_at TEXT'],
+  ['claim_snapshot', 'claim_snapshot TEXT'],
+];
 
 // Brings an already-created `tasks` table up to the current column set.
 // Idempotent and cheap (one PRAGMA), so callers that must not fail on a
@@ -136,9 +169,76 @@ export function ensureTaskColumns(db) {
   }
 }
 
-// Applies the schema to an already-open node:sqlite DatabaseSync instance.
-// Idempotent: safe to call against a DB that already has these tables.
+// Schema version this installed CLI knows about, tracked in the graph's
+// own `PRAGMA user_version` (an integer SQLite stores in the file header
+// — no table required, so it reads back even on a brand-new file).
+// Bumped by one for every entry added to MIGRATIONS below; never
+// 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;
+
+// Forward migrations, applied in order to bring a graph's user_version up
+// to CURRENT_SCHEMA_VERSION. Unlike the CREATE TABLE IF NOT EXISTS /
+// ensureTaskColumns pair above — which only ever reconciles present-day
+// shape against however old a graph is, and can't touch anything already
+// baked into an existing column (a CHECK constraint, a rename, a data
+// transform) — this is versioned, so a future change too structural for
+// a bare ADD COLUMN has somewhere to go, and upgrading is one fail-loud
+// step instead of every command's queries silently assuming a shape
+// that might not be there yet.
+const MIGRATIONS = [
+  {
+    version: 1,
+    // The lease/task columns TASK_COLUMN_MIGRATIONS covers already had to
+    // be idempotent against a fresh CREATE TABLE (which includes them
+    // from the start) — ensureTaskColumns' own presence check already
+    // does exactly what a migration step needs.
+    migrate: (db) => ensureTaskColumns(db),
+  },
+  {
+    version: 2,
+    migrate: (db) => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS decisions (
+          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'))
+        );
+      `);
+    },
+  },
+];
+
+// Brings a graph's `PRAGMA user_version` up to CURRENT_SCHEMA_VERSION,
+// running only the migrations it hasn't seen yet. A graph newer than
+// this installed CLI knows about (its user_version already ahead of
+// CURRENT_SCHEMA_VERSION — created by, or migrated with, a later
+// Hedgehog) fails loudly here with a plain-English fix, instead of every
+// later query failing confusingly on a column or table shape this code
+// has never heard of.
+export function runMigrations(db) {
+  const { user_version: current } = db.prepare('PRAGMA user_version').get();
+
+  if (current > CURRENT_SCHEMA_VERSION) {
+    throw new Error(
+      `This build graph was created by a newer version of Hedgehog (schema v${current}) than the one installed here (schema v${CURRENT_SCHEMA_VERSION}). Upgrade Hedgehog (\`npx @skyf0xx/hedgehog@latest update\`) before running commands against this graph.`,
+    );
+  }
+
+  for (const { version, migrate } of MIGRATIONS) {
+    if (version > current) {
+      migrate(db);
+      db.exec(`PRAGMA user_version = ${version}`);
+    }
+  }
+}
+
+// Applies the schema to an already-open node:sqlite DatabaseSync instance,
+// then brings it up to CURRENT_SCHEMA_VERSION. Idempotent: safe to call
+// against a DB that already has these tables and has already migrated.
 export function applySchema(db) {
   db.exec(SCHEMA_SQL);
-  ensureTaskColumns(db);
+  runMigrations(db);
 }

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

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

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

@@ -40,25 +40,16 @@ it.
 
 ## Writing the issue or PR
 
-Most of Hedgehog's inbound queue is read first by `inbound-triage`, an
-agent, before a human ever sees it — the same register `inbound-triage`
-uses when it comments back (see that skill's "Comment style" section).
-Write plainly for both readers at once:
+Use the `pr-writing` skill for style: brief, info-dense, Simplified
+Technical English, only verified claims. Most of Hedgehog's inbound queue
+is read first by `inbound-triage`, an agent, before a human ever sees it —
+the same register `inbound-triage` uses when it comments back (see that
+skill's "Comment style" section) — so write plainly for both readers at
+once.
 
-- Plain technical English, one claim per sentence, no hedging or
-  marketing language.
-- Lead with the concrete fact: "`hedgehog init` writes `.claude/agents/`
-  twice on Windows" beats "I noticed there might be an issue with how
-  the installer handles paths."
-- Fill every field the bug-report template asks for as its own labeled
-  fact (symptom, expected behavior, exact repro steps) rather than one
-  collapsed paragraph.
-- Cite `file:line` for anything about existing behavior — an
-  uncited claim is a hypothesis both readers have to re-derive.
-- One issue, one problem; one PR, one change.
-- Say what you verified, not what you assume: "Ran `node bin/cli.mjs
-  init` in a scratch dir, `.claude/skills/` is missing the new
-  directory" beats "this probably breaks the install."
+Fill every field the bug-report template asks for as its own labeled fact
+(symptom, expected behavior, exact repro steps) rather than one collapsed
+paragraph.
 
 ## Workflow
 
@@ -92,7 +83,8 @@ Write plainly for both readers at once:
    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.**
+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'
@@ -104,9 +96,10 @@ Write plainly for both readers at once:
    EOF
    )"
    ```
-   Describe the *why* in the PR body, not in the file being changed — same
-   rule `CONTRIBUTING.md` states for the content itself. 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. **Report the PR URL** `gh` returns and stop — don't merge, don't push
+   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
    further commits without being asked.

package/src/skills/pr-writing/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pr-writing
+description: Use whenever writing a PR title/description, a commit message body, a code review comment, or an issue — in Hedgehog's own repo or any consuming project. Triggers on "open a PR", "write the PR description", "comment on this PR", "file an issue". Covers writing style (terse, info-dense, Simplified Technical English) and the pre-open checklist (CI status, scope, verified claims only).
+---
+
+# PR Writing
+
+A PR description, commit message, or review comment is read by a human
+deciding whether to trust and merge the change. Write for that reader, not
+as a record of the work session.
+
+## Style rules
+
+- **Brief.** State the change and the reason. Skip the narrative of how you
+  got there.
+- **Info-dense, not verbose.** Every sentence carries a fact. Cut sentences
+  that restate the diff, the title, or each other.
+- **Don't write what's inferable.** A reviewer can read the diff — don't
+  describe what a line change does if the code already says so. State only
+  what the diff can't show: intent, a non-obvious constraint, a fact you
+  verified.
+- **Simplified Technical English.** One claim per sentence. Concrete
+  subjects, active voice, present tense for current behavior. No hedging
+  ("might", "could potentially", "it seems"), no filler ("simply",
+  "basically", "just"), no marketing language. Say "X fails when Y" — not
+  "there might be an issue where X could fail if Y happens."
+- **Write for a human, not an AI reviewer.** No emoji, no "Generated by",
+  no restating the obvious for machine parsing. Plain prose a teammate
+  would send in Slack.
+
+## Pre-open checklist
+
+- **CI must pass before you ask for review.** Run the project's checks
+  locally first — lint, tests, build. If a check is red after pushing, fix
+  it or say plainly in the PR why it's expected (a known, unrelated
+  flake), never leave it unexplained.
+- **One PR, one change.** A second unrelated fix noticed along the way is a
+  separate PR, not scope creep on this one.
+- **State only what you verified.** "Ran `X`, confirmed `Y`" — never "this
+  should work" or "this probably fixes it." An unverified claim in a test
+  plan is itself a defect; a reviewer trusts it and later finds it was
+  false.
+- **Cite `file:line` for claims about existing behavior.** An uncited claim
+  is a hypothesis the reviewer has to re-derive themselves.
+- **Reference the issue it closes**, if any (`Fixes #123`), instead of
+  restating the issue's content.
+
+## Shape
+
+- **Title**: `<type>(<scope>): <summary>`, imperative mood, under ~70
+  chars.
+- **Description**: 1-3 bullets — what changed, why. A test plan section
+  listing what you actually ran, not what should theoretically pass.
+- **Comments**: lead with the concrete finding, then (if needed) the fix
+  requested. No preamble.
+
+## When NOT to apply
+
+- Internal scratch notes, planning docs, or anything not read by another
+  person — write those however is fastest for you.
+- The user asks for a different register explicitly (e.g. a detailed
+  design-doc-style PR description for an architectural change that needs
+  the extra context).

package/src/templates/CLAUDE.md

@@ -104,8 +104,8 @@ 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/WHY NOW/BLOCKED
-   DOWNSTREAM/ALLOWED SCOPE/VERIFICATION packet) that the
+   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
@@ -141,6 +141,13 @@ 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