@skyf0xx/hedgehog 6.0.4 → 6.1.0

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,
@@ -280,19 +281,6 @@ function corePayload(core, h, { hostOnly = false } = {}) {
     // than generating it live. A core that scaffolds nothing (its
     // workspace is designed during planning) declares no `workspace`.
     ...(manifest.workspace ? [{ type: 'dir', root, from: manifest.workspace, to: '.' }] : []),
-    // A second CLAUDE.md section for cores whose path fills
-    // {{CORE_SECTION}} after install rather than at it — adoption reads
-    // it from the project instead of the package it ships in.
-    ...(manifest.template_adopted
-      ? [
-          {
-            type: 'file',
-            root,
-            from: manifest.template_adopted,
-            to: `.hedgehog/${manifest.template_adopted}`,
-          },
-        ]
-      : []),
   ];
 }
 
@@ -397,19 +385,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}`);
@@ -525,7 +513,7 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --pwa-app            scaffold the pwa-app core now
   npx @skyf0xx/hedgehog init --landing-page       scaffold the landing-page core now
   npx @skyf0xx/hedgehog cores list                every core this release can install
-  npx @skyf0xx/hedgehog core record-adopted       land the authored core's agents/skills and record
+  npx @skyf0xx/hedgehog core record-adopted       land the adopted core's agents/skills and record
                                                    this project as adopted (hedgehog-adopt calls this
                                                    after writing .hedgehog/core.yaml; not for other cores)
   npx @skyf0xx/hedgehog init --cursor             install for Cursor (default: Claude Code)
@@ -573,6 +561,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
 
@@ -1042,10 +1033,10 @@ async function resolveInstalledCore() {
 }
 
 // `hedgehog core record-adopted` — the record path for `hedgehog-adopt`
-// (shipped in @skyf0xx/hedgehog-core-authored), which brings the
+// (shipped in @skyf0xx/hedgehog-core-adopted), which brings the
 // discipline to an existing repo by writing `.hedgehog/core.yaml` and
 // `.hedgehog/adoption.md` directly. That path has no `init` step and so
-// never fetches the `authored` package or calls `recordCore` — a no-flag
+// never fetches the `adopted` package or calls `recordCore` — a no-flag
 // `init` (what the offer skill actually runs before adoption) installs
 // only the shared engine payload, never a core's own agents/skills, and
 // `bootstrap` (the only other place a core package gets fetched) is
@@ -1057,24 +1048,27 @@ async function resolveInstalledCore() {
 // `core.yaml` (the shipped-core workspace marker) and finds nothing for
 // an adopted repo's `.hedgehog/core.yaml`, so it would read as "no core
 // yet" and update would silently rewrite `.claude/agents`/`.claude/skills`
-// down to just the shared payload, deleting the authored package's files
+// down to just the shared payload, deleting the adopted package's files
 // with nothing put back.
 //
-// This command is both fixes at once: it fetches the `authored` package
+// This command is both fixes at once: it fetches the `adopted` package
 // and lands its agents/skills for every host this project already has
-// installed (never its workspace, template, or vendor_skills — adoption
-// already wrote its own CLAUDE.md section and root workspace is the one
-// thing adoption must never touch), then records the core with
-// `adopted: true` so `update` refreshes it correctly from here on.
-// Idempotent and safe to re-run — e.g. from a later `hedgehog-adopt` pass
-// adding new change-work — since it always overwrites from the current
-// package rather than merging.
+// installed (never its workspace or vendor_skills — root workspace is
+// the one thing adoption must never touch), plus a local copy of its
+// `CLAUDE.core.md` at `.hedgehog/CLAUDE.core.md` — `hedgehog-adopt`'s own
+// Confirm & Lock step reads that file from there to merge into root
+// `CLAUDE.md`, since a no-flag `init` never ran the normal
+// `{{CORE_SECTION}}` merge this project's core would otherwise get — then
+// records the core the same as any other, naming `adopted`, so `update`
+// refreshes it correctly from here on. Idempotent and safe to re-run —
+// e.g. from a later `hedgehog-adopt` pass adding new change-work — since
+// it always overwrites from the current package rather than merging.
 async function recordAdoptedCommand() {
   const entry = await resolveCore(ADOPTED_CORE_NAME);
   if (!entry) {
     console.error(
-      `${red('authored core not in this release.')} This Hedgehog release's registry has no\n` +
-        `entry named "authored" — nothing to install. Update Hedgehog and retry.\n`,
+      `${red('adopted core not in this release.')} This Hedgehog release's registry has no\n` +
+        `entry named "adopted" — nothing to install. Update Hedgehog and retry.\n`,
     );
     process.exitCode = 1;
     return;
@@ -1102,7 +1096,19 @@ async function recordAdoptedCommand() {
     }
   }
 
-  await recordCore(DEST_ROOT, { name: core.manifest.name, version: core.version, adopted: true });
+  const templateFile = (
+    await plannedFiles({
+      type: 'file',
+      root: core.root,
+      from: core.manifest.template,
+      to: '.hedgehog/CLAUDE.core.md',
+    })
+  )[0];
+  await writePlannedFile(templateFile);
+  written++;
+  console.log(`  ${green('install')}  ${relative(DEST_ROOT, templateFile.dest)}`);
+
+  await recordCore(DEST_ROOT, { name: core.manifest.name, version: core.version });
 
   console.log(
     `\n${green(bold('Adopted core recorded.'))} ${dim(
@@ -1155,9 +1161,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 +1189,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 +3143,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 +3519,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.1.0",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo, for Claude Code, Cursor, or Gemini CLI.",
   "type": "module",
   "repository": {

package/src/agents/planner.md

@@ -31,7 +31,8 @@ You run on two paths, and Workflow step 2 decides which:
   scope into additional intents without re-running the BMAD shelf.
   Landing-page has no module axis, so this path doesn't apply to it — see
   the landing-page constraint below for where its new scope actually
-  goes.
+  goes. New change-work on an **adopted** core is a separate case again —
+  see "An existing repo, ongoing adoption" below.
 
 Either path is entered when the user says "plan", "scope", "break down",
 asks for something that's new scope rather than a tweak (routed here by
@@ -200,14 +201,14 @@ none of them is a description matching a `when` paragraph:
   repo", "add Hedgehog to my existing project", "I want scope/verify
   enforcement on my changes here"). This is a distinct question from
   everything above: it's not about which core fits new work, because no
-  new workspace gets built at all. Route straight to `hedgehog-adopt` —
-  bootstrap and every other Phase 0 outcome are skipped entirely, since
-  there is no workspace to scaffold and no shipped stack to adopt toward.
-  `hedgehog-adopt` runs its own read-only intake and writes its own
-  `.hedgehog/core.yaml`; don't run `hedgehog-planning-intake`'s BMAD shelf
-  first — the drivers that skill elicits (persistence, stack, deployment
-  target) are already settled facts of the existing repo, not open
-  decisions.
+  new workspace gets built at all. This project gets the **adopted
+  core**. Route straight to `hedgehog-adopt` — bootstrap and every other
+  Phase 0 outcome are skipped entirely, since there is no workspace to
+  scaffold and no shipped stack to adopt toward. `hedgehog-adopt` runs
+  its own read-only intake and writes its own `.hedgehog/core.yaml`;
+  don't run `hedgehog-planning-intake`'s BMAD shelf first — the drivers
+  that skill elicits (persistence, stack, deployment target) are already
+  settled facts of the existing repo, not open decisions.
 
 State the decision plainly before Phase 1 begins, with the one-line
 reason it landed there — this is cheap to correct now and expensive once
@@ -375,7 +376,7 @@ as full-stack-app's Auth/Queue/Mobile trio.
   the build graph.
 - **landing-page**: owns `.hedgehog/BMAD/` and
   `.hedgehog/chain/00-brief.md` as artifacts.
-- **brownfield adoption**: owns nothing here — `hedgehog-adopt` owns
+- **adopted**: owns nothing here — `hedgehog-adopt` owns
   `.hedgehog/core.yaml` and `.hedgehog/adoption.md`, the same way an
   authored core's design is `hedgehog-core-design`'s.
 

package/src/agents/reviewer.md

@@ -30,7 +30,8 @@ Everything the commit gate already enforces — the layer's own `verify`
 command, and whatever typecheck/lint/test it runs — is out of scope;
 don't re-report a green gate. Read the core's own design first: its loop
 skill for a shipped core, `.hedgehog/core.yaml` and
-`.hedgehog/core-design.md` for an authored one. That is where the layer
+`.hedgehog/core-design.md` for an authored one, `.hedgehog/core.yaml` and
+`.hedgehog/adoption.md` for an adopted one. That is where the layer
 boundaries, the interface between them, and this core's own conventions
 are stated. Your checklist is derived from it, not from a stack you
 recognize.
@@ -96,7 +97,7 @@ Check what the gate structurally cannot:
 - Don't nitpick style. Focus on structural correctness relative to the
   stack and build order the core's own design fixed — its loop and
   bootstrap skills on a shipped core, `.hedgehog/core-design.md` on an
-  authored one.
+  authored one, `.hedgehog/adoption.md` on an adopted one.
 - 3 real findings beats 20 suggestions. This review sits at a phase or
   layer boundary, not mid-Loop — don't slow the Loop down for anything
   that isn't load-bearing for the work that comes next.

package/src/agents/tweaker.md

@@ -1,6 +1,6 @@
 ---
 name: tweaker
-description: Use once a core's build is complete (every task in the build graph `complete`) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction and asks the user directly for feedback, filing each as its own GitHub issue (friction as `bug`/`help wanted`, user feedback as `suggestion`), gated by explicit user approval at every step, then makes a single one-time, no-pressure mention that Hedgehog itself takes contributions via `ROADMAP.md`. Shared by every core with a Stop Condition — not an adopted repo (`hedgehog-adopt`), which has none; there, new change-work goes straight through `hedgehog-adopt` and `hedgehog-authored-loop` instead.
+description: Use once a core's build is complete (every task in the build graph `complete`) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction and asks the user directly for feedback, filing each as its own GitHub issue (friction as `bug`/`help wanted`, user feedback as `suggestion`), gated by explicit user approval at every step, then makes a single one-time, no-pressure mention that Hedgehog itself takes contributions via `ROADMAP.md`. Shared by every core with a Stop Condition — not the `adopted` core, which has none; there, new change-work goes straight through `hedgehog-adopt` and `hedgehog-authored-loop` instead.
 model: sonnet
 color: green
 tools: Read, Glob, Grep, Edit, Write, Bash
@@ -15,7 +15,7 @@ conversation. You start from a cleared context on purpose. Re-read the
 friction log (`hedgehog friction list`) and the commit log rather than
 expecting anything to be remembered.
 
-**Not for an adopted repo (`.hedgehog/core.yaml` written by
+**Not for the `adopted` core (`.hedgehog/core.yaml` written by
 `hedgehog-adopt`).** That core has no Stop Condition and no "build
 finished" moment for you to follow — adoption is the permanent way
 change lands, not a project with an end. A request there is just the
@@ -44,8 +44,8 @@ straight to job 1.
 
 None of its own — you work inside whichever core's stack is already
 installed (a shipped core's, or the stack an authored core's
-`.hedgehog/core-design.md` names — an adopted repo never reaches you, per
-the note above), editing the same files the core's own build agents
+`.hedgehog/core-design.md` names — the `adopted` core never reaches you,
+per the note above), editing the same files the core's own build agents
 would. `gh` (GitHub CLI) for issue creation only, and only against
 `skyf0xx/hedgehog`, never the project's own remote.
 

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/claude-md-merge.mjs

@@ -13,7 +13,7 @@
 // instead of substituting into one.
 //
 // Referenced by name (not substance) from hedgehog-adopt's own SKILL.md
-// in the @skyf0xx/hedgehog-core-authored package — that skill invokes
+// in the @skyf0xx/hedgehog-core-adopted package — that skill invokes
 // `appendCoreSection` the same way it already invokes `loadCore` from
 // src/db/core.mjs, via `node -e "import('<path-to-hedgehog-install>/
 // src/hosts/claude-md-merge.mjs')..."`.

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

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

package/src/registry/cores.json

@@ -39,10 +39,18 @@
     {
       "name": "authored",
       "package": "@skyf0xx/hedgehog-core-authored",
-      "version": "^1.0.2",
+      "version": "^1.1.0",
       "language": "typescript",
       "repository": "https://github.com/skyf0xx/hedgehog-core-authored",
-      "selects_when": "Neither shipped core fits, but the description names a real artifact a Builder step would produce — just not in either shipped core's shape. This core is designed by the planner rather than chosen from a fixed set: hedgehog-planning-intake's Phase 0 elicits the drivers first, then hedgehog-core-design names the system shape, picks the stack, derives the layers, and writes .hedgehog/core.yaml. It carries the same enforcement as a shipped core — ordered layers, scoped file access, verification before completion — but the sequence is designed for this project rather than battle-tested across many."
+      "selects_when": "Neither shipped core fits, but the description names a real artifact a Builder step would produce — just not in either shipped core's shape. This core is designed by the planner rather than chosen from a fixed set: hedgehog-planning-intake's Phase 0 elicits the drivers first, then hedgehog-core-design names the system shape, picks the stack, derives the layers, and writes .hedgehog/core.yaml. It carries the same enforcement as a shipped core — ordered layers, scoped file access, verification before completion — but the sequence is designed for this project rather than battle-tested across many. This is the core most often confused with adopted: authored designs a workspace from scratch for a project being built new, while adopted brings Hedgehog's discipline to a repo that already exists — route here only when there is no existing codebase this work is being added to."
+    },
+    {
+      "name": "adopted",
+      "package": "@skyf0xx/hedgehog-core-adopted",
+      "version": "^1.0.0",
+      "language": "typescript",
+      "repository": "https://github.com/skyf0xx/hedgehog-core-adopted",
+      "selects_when": "The description is about bringing Hedgehog's discipline to a codebase that already exists, rather than building something new — the repo already has real source files, or the user says so explicitly: \"adopt this repo\", \"add Hedgehog to my existing project\", \"I want scope/verify enforcement on my changes here\". Not chosen by matching a `when` paragraph the way a shipped core is: hedgehog-adopt reads the repo read-only, proposes a linear-chain .hedgehog/core.yaml whose verify commands are the repo's own, and writes only .hedgehog/ — never a workspace, never a stack migration. This is the core most often confused with authored: adopted brings discipline to an existing repo, while authored designs and scaffolds a workspace from scratch for something being built new — route here only when the work is landing on a codebase that already exists."
     }
   ]
 }

package/src/registry/installed.mjs

@@ -7,21 +7,19 @@
 // the core — `installedCore` returns null until then, and `update` limits
 // itself to the shared payload.
 //
-// `authored` has a second entry point with no `init` step at all:
-// `hedgehog-adopt` brings the discipline to a repo that already exists by
-// writing `.hedgehog/core.yaml` itself, directly, and never calls
-// `recordCore` (see that skill, shipped in
-// @skyf0xx/hedgehog-core-authored — adoption has no npm package of its
-// own to fetch, just a core.yaml and adoption.md derived from the
-// existing repo). `hedgehog core record-adopted` (bin/cli.mjs) is the
-// record path for that case instead: it lands the authored package's
-// agents/skills — otherwise never installed, since adoption's `init` runs
-// with no `--core` flag and `bootstrap` is skipped entirely for adoption
-// — and calls `recordCore` with `adopted: true`. That flag is the one
-// thing distinguishing an adopted record from a normal one: `update`'s
-// resolveInstalledCore refreshes an adopted project's payload the same as
-// any other (same package, same agents/skills, kept current) but must
-// never treat `record.name` changing upstream, or the record going
+// `adopted` has no `init` step at all: `hedgehog-adopt` (shipped in
+// @skyf0xx/hedgehog-core-adopted) brings the discipline to a repo that
+// already exists by writing `.hedgehog/core.yaml` itself, directly, and
+// never calls `recordCore`. `hedgehog core record-adopted` (bin/cli.mjs)
+// is the record path for that case instead: it fetches the `adopted`
+// package and lands its agents/skills — otherwise never installed, since
+// adoption's `init` runs with no `--core` flag and `bootstrap` is skipped
+// entirely for adoption — and calls `recordCore` the same as any other
+// core, naming `adopted`. That name is the one thing distinguishing an
+// adopted record from a normal one: `update`'s resolveInstalledCore
+// refreshes an adopted project's payload the same as any other (same
+// package, same agents/skills, kept current) but must never treat
+// `record.name === 'adopted'` changing upstream, or the record going
 // missing, as license to fetch and install a *different* core the way it
 // would for a project that chose one at `init` — adoption's core is a
 // fixed fact of the repo (its `.hedgehog/core.yaml`), not a choice
@@ -30,38 +28,34 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
-export const ADOPTED_CORE_NAME = 'authored';
+export const ADOPTED_CORE_NAME = 'adopted';
 
 const CORE_PATH = '.hedgehog/core.json';
 
 /**
  * Record the core a project installed and the exact version resolved for
  * it. Written after the core's files land, so the record describes what
- * is on disk. `adopted: true` marks a record written by `hedgehog core
- * record-adopted` rather than by `init` — see the module comment above.
+ * is on disk.
  */
-export async function recordCore(root, { name, version, adopted = false }) {
+export async function recordCore(root, { name, version }) {
   const path = join(root, CORE_PATH);
   await mkdir(dirname(path), { recursive: true });
   await writeFile(
     path,
-    `${JSON.stringify(
-      { core: name, version, installedAt: new Date().toISOString(), ...(adopted ? { adopted: true } : {}) },
-      null,
-      2,
-    )}\n`,
+    `${JSON.stringify({ core: name, version, installedAt: new Date().toISOString() }, null, 2)}\n`,
   );
 }
 
 /**
- * The core `update` should refresh — `{ name, version, adopted }` — or
- * null when this project has no core installed yet. `adopted` is always a
- * boolean, `false` for every record `init` writes.
+ * The core `update` should refresh — `{ name, version }` — or null when
+ * this project has no core installed yet. `name === 'adopted'` marks a
+ * record written by `hedgehog core record-adopted` rather than by `init`
+ * — see the module comment above.
  */
 export async function installedCore(root) {
   try {
-    const { core, version, adopted } = JSON.parse(await readFile(join(root, CORE_PATH), 'utf8'));
-    return core ? { name: core, version, adopted: adopted === true } : null;
+    const { core, version } = JSON.parse(await readFile(join(root, CORE_PATH), 'utf8'));
+    return core ? { name: core, version } : null;
   } catch {
     return null;
   }

package/src/registry/manifest.mjs

@@ -11,7 +11,6 @@
 //   engine: "^<major>.<minor>.<patch>" which CLI versions can install it
 //   workspace: workspace/              omitted by a core that scaffolds nothing
 //   template: CLAUDE.core.md           fills the CLAUDE.md shell's core section
-//   template_adopted: <path>           optional second section, for adoption
 //   agents: [<name>, ...]              agents/<name>.md in the package
 //   skills: [<name>, ...]              skills/<name>/ in the package
 //   vendor_skills: [<name>, ...]       vendor-skills/<name>/ in the package

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