@skyf0xx/hedgehog 6.2.17 → 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,
@@ -86,6 +86,7 @@ import {
   onHedgehogBranch,
   writeAbandonedFile,
   applyAbandonment,
+  loadAbandoned,
   ABANDONED_DIR,
 } from '../src/db/worktree.mjs';
 import { loadOverrides, addOverride, orphanedOverrides, OVERRIDES_DIR } from '../src/db/overrides.mjs';
@@ -662,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
@@ -1557,11 +1559,21 @@ async function planCommand(args = []) {
   // by the same rule that got it a worktree in the first place. Without
   // this guard, that recursive call would try to create a second,
   // colliding worktree for itself instead of just compiling normally.
+  // A committed `.hedgehog/abandoned/<id>.json` record outlives the
+  // `intent_dependencies` reset that comes with it (issue #431) — see
+  // worktree.mjs#eligibleIntents for why the abandonment record, not the
+  // (re-clearable) dependency table, has to be the thing checked there.
+  // Loaded unconditionally (not just under the onHedgehogBranch guard
+  // below) because it also feeds excludeIntentIds just below: an abandoned
+  // intent must never fall through to a plain trunk compile just because
+  // eligibleIntents excluded it from the worktree path.
+  const abandonedIntentIds = new Set((await loadAbandoned()).keys());
+
   let eligible = [];
   if (!onHedgehogBranch()) {
     const eligibilityDb = openDb({ readOnly: true });
     try {
-      eligible = eligibleIntents(eligibilityDb);
+      eligible = eligibleIntents(eligibilityDb, abandonedIntentIds);
     } finally {
       eligibilityDb.close();
     }
@@ -1572,8 +1584,12 @@ async function planCommand(args = []) {
   // it a worktree this run (hasWorktree true already, or the commit check
   // below defers it) — an eligible intent must never fall through to
   // compiling on trunk, or it would sit there just like any pre-feature
-  // intent and this feature would have done nothing for it.
-  const excludeIntentIds = new Set(eligible.map((i) => i.id));
+  // intent and this feature would have done nothing for it. Abandoned
+  // intents are unioned in for the same reason (issue #431): excluded from
+  // `eligible` itself now, they'd otherwise read as "not eligible, so
+  // compile normally" and get recompiled straight onto trunk instead of
+  // being left alone — the abandonment record makes that impossible.
+  const excludeIntentIds = new Set([...eligible.map((i) => i.id), ...abandonedIntentIds]);
 
   const worktreesCreated = [];
   for (const intent of eligible) {
@@ -2240,7 +2256,8 @@ async function verifyCommand(args) {
       process.exitCode = 1;
       return;
     }
-    result = verifyTask(db, taskId, owner);
+    const overrides = await loadOverrides();
+    result = verifyTask(db, taskId, owner, overrides);
   } catch (err) {
     console.error(`${red('Verify failed:')} ${err.message}\n`);
     process.exitCode = 1;
@@ -3332,7 +3349,7 @@ async function overrideCommand(args) {
     console.log(`  ${green('added')}  ${OVERRIDES_DIR}/${record.task.toLowerCase()}.json`);
     for (const glob of record.scope_add) console.log(`    + ${glob}`);
     console.log(
-      `  ${dim(`run \`hedgehog plan --recompile\` to widen ${record.task} now, if it's already compiled`)}\n`,
+      `  ${dim(`\`hedgehog verify\` picks this up immediately; run \`hedgehog plan --recompile\` to also widen ${record.task}'s stored scope_globs (task listing, drift detection) now, if it's already compiled`)}\n`,
     );
     return;
   }
@@ -3828,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.2.17",
+  "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/claim.mjs

@@ -8,6 +8,14 @@
 // — by setting status and the three lease columns in the same UPDATE:
 // a task entering `building` gets an owner, and a task leaving it (to
 // ready, planned, blocked) has all three cleared.
+//
+// Both `findClaimableTasks` (the fan-out's candidate set) and `claimTask`
+// (a targeted, named claim) additionally treat a dependency as satisfied
+// when it is complete anywhere reachable from a local git ref, not only
+// in this worktree's own DB — see crossBranch.mjs. This is a read-only
+// widening of "is this dependency done", never a write across worktrees:
+// no DB row in this file ever crosses from one worktree's
+// `.hedgehog/hedgehog.db` to another's (worktree.mjs's file header).
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, readlinkSync, lstatSync } from 'node:fs';
@@ -17,6 +25,7 @@ import { inTransaction } from './init.mjs';
 import { conflicts } from './conflict.mjs';
 import { incompleteDependencies } from './next.mjs';
 import { ensureTaskColumns } from './schema.mjs';
+import { buildCrossBranchIndex, commitMessageExistsAnywhere } from './crossBranch.mjs';
 
 // ── Claim-time working-tree snapshot ──────────────────────────────────
 //
@@ -154,10 +163,94 @@ const CLAIMABLE_TASKS_SQL = `
   ORDER BY t.priority, t.exclusive DESC, t.id
 `;
 
+// The same shape as CLAIMABLE_TASKS_SQL's own NOT EXISTS clause, but
+// naming which dependency is unsatisfied *in this DB* rather than merely
+// excluding the candidate — this is the raw material
+// findUnsatisfiedDependencies (below) needs to then ask crossBranch.mjs
+// whether that specific dependency is satisfied elsewhere instead.
+const UNSATISFIED_DEPENDENCIES_SQL = `
+  SELECT d.task_id AS taskId, dep.id AS dependsOnId, dep.commit_message AS commitMessage
+  FROM dependencies d
+  JOIN tasks dep ON dep.id = d.depends_on_task_id
+  WHERE dep.status <> 'complete'
+`;
+
+// Candidate tasks CLAIMABLE_TASKS_SQL's own NOT EXISTS would exclude
+// (status planned/ready, unleased, but blocked on a dependency this DB
+// still shows incomplete) that become claimable once that dependency's
+// commit is credited from ANY local branch's history — see crossBranch.mjs
+// for why this is exactly `git log --all` widened from the current
+// branch's own `git log`, and for the documented ambiguous-commit-message
+// gap this can't resolve.
+//
+// This is a live, read-only re-derivation: nothing here writes
+// `tasks.status` in the current worktree's DB (that would be exactly the
+// "no DB row crosses worktrees" invariant this feature deliberately does
+// not touch — see worktree.mjs's file header). A future claim/verify pass
+// in this same worktree still needs its own copy of that fact; this only
+// answers "is it claimable right now".
+//
+// `index` is always caller-supplied (buildCrossBranchIndex shells out to
+// `git log`, and this file's own `inTransaction` contract — see
+// claimTasks/claimTask below — forbids running a subprocess while a sqlite
+// transaction is open; findClaimableTasks builds the index before ever
+// entering one).
+function crossBranchClaimableCandidates(db, index) {
+  const candidates = db
+    .prepare(
+      `SELECT t.* FROM tasks t
+       WHERE t.status IN ('planned', 'ready')
+         AND t.lease_owner IS NULL
+         AND EXISTS (
+           SELECT 1 FROM dependencies d
+           JOIN tasks dep ON dep.id = d.depends_on_task_id
+           WHERE d.task_id = t.id AND dep.status <> 'complete'
+         )
+       ORDER BY t.priority, t.exclusive DESC, t.id`,
+    )
+    .all();
+  if (candidates.length === 0) return [];
+
+  const unsatisfied = db.prepare(UNSATISFIED_DEPENDENCIES_SQL).all();
+  const unsatisfiedByTask = new Map();
+  for (const row of unsatisfied) {
+    if (!unsatisfiedByTask.has(row.taskId)) unsatisfiedByTask.set(row.taskId, []);
+    unsatisfiedByTask.get(row.taskId).push(row);
+  }
+
+  return candidates.filter((candidate) =>
+    unsatisfiedByTask
+      .get(candidate.id)
+      .every((dep) => commitMessageExistsAnywhere({ commit_message: dep.commitMessage }, index)),
+  );
+}
+
 // Exported for ready.mjs, which walks the identical candidate set to
 // simulate this same fan-out without claiming anything.
-export function findClaimableTasks(db) {
-  return db.prepare(CLAIMABLE_TASKS_SQL).all();
+//
+// Merges CLAIMABLE_TASKS_SQL's own current-DB-only candidates with the
+// cross-branch set above, then re-sorts to the same `priority, exclusive
+// DESC, id` order the fan-out and every caller depend on — the two source
+// queries are individually ordered but interleaving them requires a single
+// re-sort over the union.
+//
+// `index` is optional: a caller outside any sqlite transaction (ready.mjs,
+// status.mjs) can omit it and this builds one itself. A caller that runs
+// inside `inTransaction` (claimTasks/claimTask, below) MUST build the
+// index first and pass it in — building it here would shell out to `git
+// log` with a `BEGIN IMMEDIATE` already open, which this codebase
+// forbids (see init.mjs#inTransaction's own contract, restated in
+// claimTasks's comment).
+export function findClaimableTasks(db, index = buildCrossBranchIndex(db)) {
+  const local = db.prepare(CLAIMABLE_TASKS_SQL).all();
+  const crossBranch = crossBranchClaimableCandidates(db, index);
+  if (crossBranch.length === 0) return local;
+
+  return [...local, ...crossBranch].sort((a, b) => {
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    if (a.exclusive !== b.exclusive) return b.exclusive - a.exclusive;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
 }
 
 // Tasks another call already holds a lease on — the conflict check's other
@@ -266,6 +359,11 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
   // Taking it a moment early can only miss a path dirtied in between,
   // which leaves that path attributed — the strict direction.
   const claimSnapshot = snapshotWorkingTree();
+  // Same rule, same reason, for the cross-branch index: buildCrossBranchIndex
+  // shells out to `git log --all` (twice — see crossBranch.mjs), so it is
+  // built here, before BEGIN, and threaded into findClaimableTasks rather
+  // than left to build itself once inside the transaction below.
+  const crossBranchIndex = buildCrossBranchIndex(db);
 
   return inTransaction(db, () => {
     const justReaped = reapExpiredLeases(db);
@@ -275,7 +373,7 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
       return { claimed: [], blocked };
     }
 
-    const candidates = findClaimableTasks(db);
+    const candidates = findClaimableTasks(db, crossBranchIndex);
     const inFlight = findInFlightTasks(db);
     const runClaim = claimOne(db);
     const claimed = [];
@@ -317,8 +415,13 @@ export function claimTasks(db, { owner, count = 1, leaseMinutes = 45 }) {
 export function claimTask(db, taskId, { owner, leaseMinutes = 45 }) {
   ensureTaskColumns(db);
   // Same rule as claimTasks: read before BEGIN, no subprocess inside a
-  // transaction.
+  // transaction. buildCrossBranchIndex shells out to `git log --all`, so
+  // it is built here unconditionally (cheap relative to a `git` process
+  // spawn either way) rather than only on the branch that turns out to
+  // need it, which would otherwise tempt building it lazily from inside
+  // the transaction below.
   const claimSnapshot = snapshotWorkingTree();
+  const crossBranchIndex = buildCrossBranchIndex(db);
 
   return inTransaction(db, () => {
     reapExpiredLeases(db);
@@ -330,7 +433,15 @@ export function claimTask(db, taskId, { owner, leaseMinutes = 45 }) {
       return { claimed: false, reason: 'not_claimable', task };
     }
 
-    const incomplete = incompleteDependencies(db, taskId);
+    // Same cross-branch widening findClaimableTasks's fan-out applies: a
+    // dependency this DB still shows incomplete may already be complete on
+    // trunk or a sibling worktree's branch. Checked here too so a targeted
+    // `hedgehog claim <task-id>` doesn't refuse a task the fan-out would
+    // have happily claimed.
+    const stillIncomplete = incompleteDependencies(db, taskId);
+    const incomplete = stillIncomplete.filter(
+      (dep) => !commitMessageExistsAnywhere(dep, crossBranchIndex),
+    );
     if (incomplete.length > 0) {
       return { claimed: false, reason: 'incomplete_dependencies', task, incomplete };
     }

package/src/db/crossBranch.mjs

@@ -0,0 +1,186 @@
+// Cross-branch commit-history visibility for `hedgehog ready`/`claim`/
+// `status`/`reconcile`, run live inside a `git worktree` checkout — where
+// `hedgehog db rebuild` (rebuild.mjs#loadCommitSubjects) intentionally
+// only ever reads the CURRENT branch's own `git log`.
+//
+// The gap this closes: each worktree carries its own `.hedgehog/hedgehog.db`
+// (worktree.mjs's file header), and no DB row is ever copied between them
+// or from a worktree to trunk — that invariant is the reason the build
+// graph is a pure function of committed files plus git history in the
+// first place. But "current git history" was, until now, silently read as
+// "the current branch's history" everywhere a live command checked whether
+// a dependency was done: claim.mjs's CLAIMABLE_TASKS_SQL joins only the
+// current DB's own `tasks.status`, and reconcile.mjs's `commitsSince`
+// ranges over `HEAD` alone. A task completed and committed on trunk (or on
+// a sibling worktree's branch) is therefore invisible to a different
+// worktree's own DB even though the *commit* — the actual source of truth
+// — is sitting right there in the same repository's object store, reachable
+// from a local ref this checkout can already see.
+//
+// This module answers the same question rebuild.mjs#loadCommitSubjects
+// answers for the current branch (did a commit with this exact subject
+// ever happen), widened to `git log --all` — every local branch's
+// reachable history, which covers trunk and every open worktree's branch,
+// since a worktree's branch is still a local ref of the same checkout.
+// `--all` is exactly the right and only widening: it costs nothing beyond
+// one extra `git log` flag, needs no new git remotes or fetches, and a
+// project that has never used worktrees has exactly one branch with any
+// commits — `git log --all` degenerates to `git log` for it, so this
+// function is a strict no-op there (acceptance criterion: zero behavior
+// change for a project that never opened a worktree).
+//
+// ── the ambiguous-commit-message case: a documented, deliberate gap ────
+//
+// rebuild.mjs#markCompletedTasks resolves a commit_message shared by more
+// than one task (the linear-chain core case — authored/adopted, no
+// `{module}` axis) via an ordering+consumption fixpoint walk over
+// `dependencies` rows, mutating `tasks.status` directly as it goes. That
+// walk is inseparable from the DB write path it drives (UPDATE statements
+// interleaved with the fixpoint, `reconciledTaskIds` seeded in up front,
+// re-open-on-failed-claim at the end) and rebuild.mjs is explicitly out of
+// scope for this change — re-deriving its `positionOf`/`available`/
+// `ranAfterPrerequisites` machinery here as a read-only, no-mutation
+// sibling would either (a) silently drift from the real algorithm the
+// first time either copy changes, which is exactly the "three divergent
+// implementations" this file exists to avoid, or (b) require touching
+// rebuild.mjs to extract a shared core, which the task constraints forbid.
+//
+// So: a task whose `commit_message` is NOT unique across the whole graph
+// (the ambiguous / linear-chain case) is left OUT of `subjectsAllBranches`
+// entirely by this module — see `buildCrossBranchIndex`'s filtering below.
+// Every caller (claim.mjs, ready.mjs indirectly, status.mjs, reconcile.mjs)
+// then treats "not present in the index" as "can't determine — leave
+// blocked", the safe direction: a cross-worktree dependency this module
+// can't resolve stays exactly as blocked as it already was, never
+// incorrectly unblocked. The module-axis case — the overwhelmingly common
+// one, since it's what `full-stack-app`/`pwa-app`/`landing-page` compile —
+// has a `commit_message` unique to each task by construction (the layer's
+// `commit` template interpolates `{module}`) and is fully solved.
+import { execSync } from 'node:child_process';
+
+// Memoized per `git log --all` call: a Map from commit subject to the
+// number of times it occurs, newest-history-order irrelevant here (unlike
+// rebuild.mjs's positional Map, this module never needs to order two
+// candidate commits against each other, since it only ever answers for the
+// unambiguous case where any one occurrence is as good as any other).
+// Re-running `git log --all` per call rather than caching across calls:
+// every entry point here (claim, ready, status, reconcile) is invoked at
+// most once per CLI process, so there is no repeated-call cost to amortize
+// within a run, and caching across separate `hedgehog` invocations would
+// risk serving a stale answer to a long-lived process (the graph server)
+// after a sibling worktree commits.
+function subjectCountsFrom(gitArgs) {
+  let output;
+  try {
+    output = execSync(`git log ${gitArgs} --topo-order --format=%H%x00%s`, { encoding: 'utf8' });
+  } catch {
+    // No commits reachable from the requested ref set yet (a brand-new
+    // repo, or — for the current-branch-only call — a worktree whose
+    // branch predates its very first commit). Every subject is absent,
+    // which is the correct, honest answer.
+    return new Map();
+  }
+  const counts = new Map();
+  for (const line of output.split('\n')) {
+    if (!line) continue;
+    const [, subject] = line.split('\0');
+    if (subject === undefined) continue;
+    counts.set(subject, (counts.get(subject) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function loadAllBranchesSubjectCounts() {
+  return subjectCountsFrom('--all');
+}
+
+// The current branch's own subject counts — i.e. exactly what
+// rebuild.mjs#loadCommitSubjects would see (membership only; this module
+// never needs commit position, only "did this subject occur here at
+// all"). Used by buildCrossBranchIndex below to detect the one case
+// cross-branch crediting must refuse: a task reopened via the Correction
+// Protocol (claim.mjs#reopenTask) after an EARLIER commit with the same
+// subject already landed on this very branch. That earlier commit is
+// exactly as visible via `--all` as any genuine cross-branch completion —
+// nothing about the subject string distinguishes "this is a fresh
+// completion on another branch" from "this is the stale completion this
+// branch itself already reset". A task whose current DB status is not
+// `complete` but whose commit_message already appears on THIS branch is
+// therefore excluded from resolvableMessages entirely: crediting it would
+// resurrect a completion this worktree's own history has already
+// superseded, which is worse than the safe "leave it blocked, the
+// dependency isn't obviously satisfied" default this whole module commits
+// to elsewhere.
+function loadCurrentBranchSubjectCounts() {
+  return subjectCountsFrom('');
+}
+
+// Builds the set of commit_messages this module can safely credit as
+// "happened somewhere in this repository's visible history" — i.e. every
+// subject that occurs in `git log --all` AND belongs, in `db`, to exactly
+// one task. A subject occurring for two distinct reasons (two different
+// tasks in this graph legitimately share a commit_message — the ambiguous
+// linear-chain case) is deliberately excluded even though it does appear
+// in history, per the module-header comment above: this function cannot
+// tell which of the sharing tasks a given commit actually credits, and
+// guessing is worse than leaving both blocked.
+//
+// `db` is read only for `tasks.commit_message` grouping — never written.
+export function buildCrossBranchIndex(db) {
+  const tasks = db.prepare('SELECT id, commit_message, status FROM tasks').all();
+  const messageCounts = new Map();
+  const statusByMessage = new Map();
+  for (const task of tasks) {
+    messageCounts.set(task.commit_message, (messageCounts.get(task.commit_message) ?? 0) + 1);
+    statusByMessage.set(task.commit_message, task.status);
+  }
+
+  const subjectCounts = loadAllBranchesSubjectCounts();
+  const currentBranchCounts = loadCurrentBranchSubjectCounts();
+  const resolvableMessages = new Set();
+  for (const [message, taskCount] of messageCounts) {
+    if (taskCount !== 1) continue; // ambiguous in THIS graph — see header comment
+    const total = subjectCounts.get(message) ?? 0;
+    if (total === 0) continue; // not seen on any branch
+    const onThisBranch = currentBranchCounts.get(message) ?? 0;
+    // Reopen guard (see loadCurrentBranchSubjectCounts): if every
+    // occurrence of this subject anywhere (`total`) is already accounted
+    // for on THIS branch (`onThisBranch >= total`) and the task is still
+    // not `complete` here, there is no occurrence anywhere else to credit
+    // — the one this branch already has is exactly the completion a
+    // Correction Protocol reopen (claim.mjs#reopenTask) superseded, and
+    // `--all` has nothing further to offer. Strictly fewer occurrences on
+    // this branch than `total` means at least one occurrence exists on
+    // SOME other branch this worktree cannot otherwise see, which is
+    // exactly the genuine cross-branch completion this module exists to
+    // surface — trusted even when this branch also independently carries
+    // its own earlier, now-superseded copy of the same subject.
+    if (onThisBranch >= total && statusByMessage.get(message) !== 'complete') {
+      continue;
+    }
+    resolvableMessages.add(message);
+  }
+
+  return { resolvableMessages };
+}
+
+// Returns true if `task` (a `tasks` row carrying `commit_message`, and
+// unique in `db` for that message) can be credited complete from
+// cross-branch history, per the index built above. Callers pass the same
+// `index` across many tasks in one call rather than rebuilding it per
+// task — one `git log --all` per CLI invocation, mirroring
+// rebuild.mjs#loadCommitSubjects's own one-call-per-run shape.
+export function commitMessageExistsAnywhere(task, index) {
+  return index.resolvableMessages.has(task.commit_message);
+}
+
+// Convenience for a caller that only has a raw commit_message string (no
+// task row) — reconcile.mjs's evidence path doesn't need the
+// per-task-uniqueness guard, since it isn't resolving a *dependency*'s
+// status, only widening the commit window it reads from. Kept separate
+// from commitMessageExistsAnywhere (which is intentionally conservative
+// about ambiguity) so this narrower use doesn't inherit a guard it has no
+// use for.
+export function anyCommitAnywhereWithSubject(subject) {
+  return (loadAllBranchesSubjectCounts().get(subject) ?? 0) > 0;
+}

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;
 }
 
@@ -311,7 +328,7 @@ function loadCommitSubjects() {
 // and applying either check there would cascade that gap through the
 // whole chain and reset already-built modules that have no ambiguity to
 // resolve in the first place.
-function markCompletedTasks(db, commitSubjects) {
+function markCompletedTasks(db, commitSubjects, reconciledTaskIds = new Set()) {
   const tasks = db.prepare('SELECT id, module, commit_message FROM tasks').all();
   const prerequisites = new Map(tasks.map((t) => [t.id, []]));
   for (const d of db.prepare('SELECT task_id, depends_on_task_id FROM dependencies').all()) {
@@ -329,7 +346,16 @@ function markCompletedTasks(db, commitSubjects) {
   // resolved separately below, since "the" matching commit for its
   // subject isn't decided until a claim succeeds.
   const positionOf = new Map();
-  const complete = new Set();
+  // Seeded with every reconciled task up front, before the ambiguous-task
+  // fixpoint walk below ever runs: a reconciled task was closed precisely
+  // because it has no commit of its own to match in commitSubjects (a
+  // hand-written commit predating the reconciliation, or none at all), so
+  // without this seed it can never enter `complete` from inside this
+  // function — leaving every task that depends on it, directly or
+  // transitively, stuck `planned` forever, since replayReconciliations
+  // (the only other path that would mark it complete) runs after this
+  // function returns.
+  const complete = new Set(reconciledTaskIds);
   const ambiguousTasks = [];
   for (const task of tasks) {
     if (task.module === CORE_MODULE || isAmbiguous(task)) {
@@ -552,7 +578,18 @@ export async function rebuildDb(
   planTasks(db, core, overrides, { excludeIntentIds: openWorktreeIntentIds });
 
   const commitSubjects = loadCommitSubjects();
-  const tasksMarkedComplete = markCompletedTasks(db, commitSubjects);
+  // Reconciled task ids are seeded into markCompletedTasks's own `complete`
+  // set before its ambiguous-task fixpoint walk runs, not after: a
+  // reconciled task's whole reason for being in .hedgehog/reconciled/ is
+  // that it has no commit of its own in commitSubjects to match, so
+  // without this it can never satisfy `every prerequisite is complete` for
+  // whatever depends on it — see markCompletedTasks's own comment on
+  // `reconciledTaskIds` for the full mechanics. replayReconciliations
+  // (below) still runs afterward to write the provenance note and cover
+  // any reconciled task markCompletedTasks doesn't touch (module = CORE_MODULE
+  // edge cases aside, every reconciled id ends up here either way).
+  const reconciledTaskIds = new Set(reconciliations.keys());
+  const tasksMarkedComplete = markCompletedTasks(db, commitSubjects, reconciledTaskIds);
 
   const tasksReconciled = replayReconciliations(db, reconciliations);
   const orphanedReconciled = orphanedReconciliations(db, reconciliations);

package/src/db/reconcile.mjs

@@ -15,6 +15,16 @@
 // — which every loop skill forbids, because the graph is derived and
 // gitignored and the patch dies at the next rebuild.
 //
+// `commitsSince`'s scan window is `git log --all`, not just the current
+// branch's `HEAD` — a hand-written commit that satisfies an open task's
+// scope can just as well sit on trunk or a sibling worktree's branch as on
+// this checkout's own branch, and `gatherEvidence` has to be able to
+// propose reconciling that task from whichever worktree happens to run
+// `hedgehog reconcile`, not only from the one that made the commit. See
+// `commitsSince` below for why the *start* of that window
+// (`newestGraphCommit`) stays scoped to the current branch's own history
+// rather than widening the same way.
+//
 // Four properties, each load-bearing:
 //
 //   - **It proposes; it never asserts.** `gatherEvidence` reports which
@@ -179,6 +189,19 @@ export function orphanedReconciliations(db, reconciliations) {
 // Returns null when no commit matches any task's message (nothing has
 // been verified yet) — the caller then reads the whole history, which is
 // the honest window for a project whose loop has not closed a task.
+//
+// Scoped to the current branch's own `git log` (not `--all`), deliberately
+// unlike `commitsSince` below: this names the boundary of THIS worktree's
+// own graph-written history — the newest commit that credits some task as
+// far as this checkout's own branch has progressed — and that is a fact
+// about this branch specifically, not about the repository as a whole. A
+// sibling branch can be ahead or behind this one in ways that have nothing
+// to do with where this worktree's own evidence window should start; using
+// `--all` here would let a commit on an unrelated, unmerged branch move
+// this worktree's own "since" boundary out from under it. Only the
+// forward-scanning window (commitsSince) needs the wider net, to catch a
+// hand-written commit that landed elsewhere; the floor it scans from stays
+// anchored to what this branch itself has already credited.
 function newestGraphCommit(db) {
   const messages = new Set(
     db.prepare('SELECT commit_message FROM tasks').all().map((r) => r.commit_message),
@@ -196,13 +219,30 @@ function newestGraphCommit(db) {
 
 // Every commit after `sinceSha` (exclusive), newest first, with the paths
 // it touched. `sinceSha` null means the whole history.
+//
+// The window's floor (`sinceSha`, from `newestGraphCommit` above) is
+// deliberately still scoped to whatever the caller resolved it against —
+// it names a specific commit, and `<sha>..` is unambiguous regardless of
+// which branch's `git log` produced that sha. It is only the window's
+// *ceiling* that widens here: `--all` in place of the bare `HEAD` ref,
+// so the scan reaches every commit on every local branch newer than
+// `sinceSha`, not only the ones that happen to be reachable from this
+// worktree's own checked-out branch. A hand-written commit sitting on
+// trunk while this runs inside an intent's own worktree (or vice versa)
+// is exactly the case `--all` exists to reach — without it, `hedgehog
+// reconcile` run from worktree B can never see a commit that only landed
+// on worktree A's branch or on trunk, which is the same blind spot
+// `commitMessageExistsAnywhere` (crossBranch.mjs) exists to close for
+// `claim`/`ready`/`status`. A project that has never opened a worktree has
+// exactly one branch with any commits, so `--all` and `HEAD` name the
+// same set there and this is a no-op for it.
 function commitsSince(sinceSha) {
-  const range = sinceSha ? [`${sinceSha}..HEAD`] : ['HEAD'];
+  const range = sinceSha ? [`${sinceSha}..`, '--all'] : ['--all'];
   let output;
   try {
     output = git(['log', '--topo-order', '--name-only', '--format=%x01%H%x00%s', ...range]);
   } catch {
-    // An empty repository has no HEAD to log.
+    // An empty repository has no ref to log at all.
     return [];
   }
 

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/db/status.mjs

@@ -19,6 +19,7 @@ import { RECONCILED_DIR, RECONCILED_NOTE_PREFIX } from './reconcile.mjs';
 import { formatMissingRequirements } from './requires.mjs';
 import { readyTasks, heldBackReason } from './ready.mjs';
 import { worktreeStatus } from './worktree.mjs';
+import { findClaimableTasks } from './claim.mjs';
 
 // The task lifecycle in order, matching the tasks CHECK constraint in
 // schema.mjs exactly — every status the engine can write, and no others.
@@ -35,17 +36,16 @@ const TASK_STATUSES = [
 // `exclusive DESC` matches claim.mjs's CLAIMABLE_TASKS_SQL and next.mjs's
 // READY_TASK_SQL, so this list is in the order those two would actually
 // take the work — see claim.mjs for why exclusive sorts first.
-const READY_TASKS_SQL = `
-  SELECT t.* FROM tasks t
-  WHERE t.status IN ('planned', 'ready')
-    AND t.lease_owner IS NULL
-    AND NOT EXISTS (
-      SELECT 1 FROM dependencies d
-      JOIN tasks dep ON dep.id = d.depends_on_task_id
-      WHERE d.task_id = t.id AND dep.status <> 'complete'
-    )
-  ORDER BY t.priority, t.exclusive DESC, t.id;
-`;
+//
+// Reuses claim.mjs#findClaimableTasks rather than a duplicate SQL string —
+// this used to run its own local-DB-only query, which meant `hedgehog
+// status` and `hedgehog claim` could disagree about which tasks are ready
+// the moment a dependency's completing commit exists only cross-branch
+// (crossBranch.mjs): a task the fan-out would happily claim would still
+// show as blocked here. findClaimableTasks already returns exactly the
+// same candidate set `hedgehog claim`'s fan-out and `hedgehog ready` use,
+// merged and re-sorted, so this file no longer needs its own copy of the
+// query.
 
 const IN_FLIGHT_TASKS_SQL = `
   SELECT t.* FROM tasks t
@@ -88,7 +88,7 @@ function countTasksByStatus(db) {
 }
 
 function loadReadyTasks(db) {
-  return db.prepare(READY_TASKS_SQL).all();
+  return findClaimableTasks(db);
 }
 
 // Tasks that need a human/agent decision before the graph can move again

package/src/db/verify.mjs

@@ -62,7 +62,7 @@ import { withCommitLock, LOCK_PATH } from './commitLock.mjs';
 import { reapExpiredLeases, pathFingerprint } from './claim.mjs';
 import { ensureTaskColumns } from './schema.mjs';
 import { FRICTION_DIR } from './friction.mjs';
-import { OVERRIDES_DIR } from './overrides.mjs';
+import { OVERRIDES_DIR, composeScope } from './overrides.mjs';
 import { RECONCILED_DIR } from './reconcile.mjs';
 import { INTENTS_DIR } from './intent.mjs';
 import { COMMUNITY_PATH } from './community.mjs';
@@ -463,10 +463,23 @@ function claimForVerify(db, taskId, owner) {
 // `completedIntent` is the intent row (id/goal/outcome) when this task
 // was the last one of its intent, else null — the CLI prints it back as
 // an INTENT CHECK.
-export function verifyTask(db, taskId, owner) {
+//
+// `overrides` (a Map from loadOverrides(), same shape recompileTasks and
+// detectDrift already take from their own callers) composes live into
+// this task's scope for both gates below, rather than trusting
+// task.scope_globs alone — that DB column is only ever widened by a
+// `hedgehog plan --recompile` the caller may not have run yet, so an
+// override written after claim but before recompile would otherwise
+// flag its own newly-allowed paths as scope violations. verifyTask
+// itself stays synchronous (loadOverrides is async, reading a
+// directory); the CLI already awaits loadOverrides() for
+// planRecompileCommand, so it does the same here and passes the
+// resulting Map in — defaulting to an empty Map keeps every other/test
+// caller's behavior unchanged.
+export function verifyTask(db, taskId, owner, overrides = new Map()) {
   const task = claimForVerify(db, taskId, owner);
 
-  const scopeGlobs = JSON.parse(task.scope_globs);
+  const scopeGlobs = JSON.parse(composeScope({ scope_globs: task.scope_globs }, taskId, overrides).scope_globs);
   // Gate 1 runs inside the commit lock: the diff has to see a working
   // tree no other task's commit is landing into mid-read, and the
   // neighbor-scope split has to be computed against a snapshot, not a

package/src/db/worktree.mjs

@@ -11,6 +11,17 @@
 // re-derives trunk's graph from what merged. No DB row ever crosses from
 // one worktree's `.hedgehog/hedgehog.db` to another's, or to trunk's.
 //
+// That invariant is about DB rows, not about what a live command may read
+// from git itself: `hedgehog ready`/`claim`/`status` (claim.mjs) and
+// `hedgehog reconcile` (reconcile.mjs) additionally check whether a
+// dependency's commit exists anywhere reachable from a local ref
+// (crossBranch.mjs's `git log --all`), not only on this worktree's own
+// checked-out branch — so a task completed and committed on trunk or on a
+// sibling worktree's branch is reflected as complete here without any DB
+// row ever having moved. The two facts are independent: this widens what
+// a query is willing to read from git history, never what a write copies
+// between databases.
+//
 // Trigger: task ids are `<intent>-<layer>` (plan.mjs's taskId), so the
 // intent is the natural partition — every task at a layer belongs to
 // exactly one intent, and a layer-boundary trigger would instead fan the
@@ -113,7 +124,21 @@ export function onHedgehogBranch({ repoRoot = process.cwd() } = {}) {
 // `--depends-on` on `hedgehog intent add` never trips this path, full
 // stop. Ordered by priority, id so a repeat `hedgehog plan` run always
 // considers the same intents in the same order.
-export function eligibleIntents(db) {
+//
+// `abandonedIntentIds` excludes an intent with a committed
+// `.hedgehog/abandoned/<id>.json` record (issue #431): applyAbandonment
+// resets an abandoned intent to `status = 'planned'` by design —
+// abandonment is a separate committed fact, not a status value — but that
+// reset also clears its `intent_dependencies` rows (clearIntentDependencies
+// in this file), and a later `hedgehog intent add` re-declaring the same
+// `--depends-on` (or a rebuild replaying intent files back onto trunk)
+// repopulates that table. Once the now-again-declared dependency
+// completes, this function's own readiness rule alone would read the
+// abandoned intent as eligible again and hand it a fresh worktree — the
+// committed abandonment record is the one place that fact survives, so
+// checking it here is what stops the recompile-and-offer cycle from
+// repeating on every subsequent `hedgehog plan`.
+export function eligibleIntents(db, abandonedIntentIds = new Set()) {
   const intents = db
     .prepare(
       `SELECT * FROM intents WHERE status IN ('proposed','planned') AND id <> '_core'
@@ -131,6 +156,7 @@ export function eligibleIntents(db) {
   );
 
   return intents.filter((intent) => {
+    if (abandonedIntentIds.has(intent.id)) return false;
     const deps = dependsOnByIntent.get(intent.id);
     if (!deps || deps.length === 0) return false;
     return deps.every((depId) => statusById.get(depId) === 'complete');

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

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

package/src/skills/code-comment-discipline/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: code-comment-discipline
+description: Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.
+---
+
+# Code Comment Discipline
+
+Well-named identifiers and clear structure explain what code does. A
+comment earns its place only when it explains something the code cannot:
+a hidden constraint, a non-obvious invariant, a workaround for a specific
+external bug, or behavior that would surprise a reader.
+
+## Default: no comment
+
+Most lines, functions, and blocks need zero comments. Before writing one,
+check whether the same clarity is reachable by renaming a variable or
+function instead — prefer that over a comment every time.
+
+## When a comment is allowed
+
+Only for the non-obvious:
+
+- A constraint imposed from outside the code (an API's undocumented
+  limit, a browser quirk, a platform requirement) that isn't visible at
+  the call site.
+- An invariant the code relies on that isn't implied by types or names
+  (e.g. "callers must hold the lock before this runs").
+- A deliberate workaround for a specific bug in a dependency, with enough
+  detail to know when it's safe to remove.
+- Behavior that looks like a mistake but is intentional.
+
+## What a comment must never say
+
+- What the code does — that's the identifier's job, not the comment's.
+- Why *this* task needed the change, who asked for it, or which ticket,
+  issue, or conversation prompted it.
+- History: "used to be X," "changed from Y," "removed Z," "previously,"
+  "now we," or any other before/after narration. A comment states the
+  current state and its non-obvious reason only, never how it got there.
+- A restatement of the function/variable name in prose ("increments the
+  counter" above `counter++`).
+
+## Applying to existing comments
+
+When editing a file that already has comments violating these rules,
+remove or rewrite them as part of the same change rather than leaving
+them in place — don't let a nearby edit normalize the pattern.