@skyf0xx/hedgehog 3.1.0 → 4.0.3

package/README.md

@@ -28,7 +28,7 @@ Hedgehog combines:
 
 Software that stays structured as it grows.
 
-![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/handoff.jpg)
+![Just describe what you want](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/handoff.png)
 
 ## The Hedgehog Loop
 
@@ -60,6 +60,14 @@ npx @skyf0xx/hedgehog graph # show graph
 
 ![The Hedgehog build graph](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/graph.png)
 
+## Parallel by Default
+
+Every dependency is explicit, so Hedgehog knows which tasks can run in parallel.
+
+![Comparison](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/comparison.png)
+
+Agents fan out to give you great outcomes at **faster speeds**.
+
 ## What Hedgehog builds
 
 ### Full-stack applications
@@ -109,7 +117,9 @@ then generates that workspace and builds it one verified layer at a time.
 The enforcement remains the same: ordered steps,
 scoped file access and a verification command per layer.
 
-![Why Hedgehog works: a different way to build with AI, comparing traditional AI workflow to Hedgehog](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.png)
+## Why Hedgehog Works
+
+![Why Hedgehog works](https://raw.githubusercontent.com/skyf0xx/hedgehog/master/docs/images/why.png)
 
 ## Install
 

package/bin/cli.mjs

@@ -14,24 +14,32 @@
 
 import { cp, mkdir, access, readdir, stat, rm, readFile, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { DatabaseSync } from 'node:sqlite';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
-import { dbInit, DB_PATH } from '../src/db/init.mjs';
+import { dbInit, DB_PATH, openDb } from '../src/db/init.mjs';
 import { loadCore } from '../src/db/core.mjs';
 import { planTasks } from '../src/db/plan.mjs';
-import { addIntent } from '../src/db/intent.mjs';
+import { addIntent, INTENTS_DIR } from '../src/db/intent.mjs';
 import { nextTask, formatNext, stalledTasks } from '../src/db/next.mjs';
 import { verifyTask } from '../src/db/verify.mjs';
+import { claimTasks, releaseTask, renewLease } from '../src/db/claim.mjs';
+import { readyTasks, formatReady } from '../src/db/ready.mjs';
 import { graphStatus, formatStatus } from '../src/db/status.mjs';
 import { whyPath, formatWhy } from '../src/db/why.mjs';
 import { addFriction, listFriction } from '../src/db/friction.mjs';
+import { rebuildDb } from '../src/db/rebuild.mjs';
 import { HOSTS, HOST_FLAGS, DEFAULT_HOST, availableHosts } from '../src/hosts/index.mjs';
 import { recordHosts, installedHosts } from '../src/hosts/installed.mjs';
 
 const AUTHORED_CORE_PATH = '.hedgehog/core.yaml';
 
+const BLOCKED_REASON_LABELS = {
+  verification_failed: 'verification failed',
+  scope_violation: 'scope violation',
+  lease_expired: 'lease expired',
+};
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 const DEST_ROOT = process.cwd();
@@ -179,6 +187,42 @@ const exists = (p) =>
     () => false,
   );
 
+// Runs once at the top of every command that needs the build graph. A
+// fresh clone has no `.hedgehog/hedgehog.db` (it's a derived artifact,
+// not committed) but does have `.hedgehog/intents/*.json` — the committed
+// source of truth — so this reconstructs the DB automatically instead of
+// making every such command fail with "no build graph" on a repo that
+// only just lost the file it never should have needed committed. If
+// there's nothing to rebuild from either (a genuinely fresh project, no
+// intents yet), this no-ops and leaves the DB missing — the caller's own
+// existing "No build graph found" guard still fires for that case.
+async function ensureDb() {
+  if (await exists(DB_PATH)) return;
+
+  let intentFiles = [];
+  try {
+    intentFiles = (await readdir(INTENTS_DIR)).filter((name) => name.endsWith('.json'));
+  } catch {
+    // .hedgehog/intents/ doesn't exist yet — nothing to rebuild from.
+  }
+  if (intentFiles.length === 0) return;
+
+  const corePath = await resolveCorePath();
+  if (!corePath) return;
+
+  await dbInit(DB_PATH);
+  const db = openDb();
+  let result;
+  try {
+    result = await rebuildDb(db, { corePath });
+  } finally {
+    db.close();
+  }
+  console.log(
+    `${dim('DB missing — rebuilt from')} ${bold(INTENTS_DIR)}${dim(':')} ${dim(`${result.intentsReplayed} intent(s) replayed, ${result.tasksMarkedComplete} task(s) marked complete`)}\n`,
+  );
+}
+
 // Writes one planned file to disk — a straight copy, or for a `merge`
 // entry, the shell template with {{CORE_SECTION}} replaced by the
 // chosen core's include.
@@ -260,13 +304,19 @@ ${bold('Usage')}
   npx @skyf0xx/hedgehog init --force              overwrite existing files
   npx @skyf0xx/hedgehog update                    refresh the installed agents + skills
   npx @skyf0xx/hedgehog db init                   create .hedgehog/hedgehog.db if absent
+  npx @skyf0xx/hedgehog db rebuild                re-derive the build graph from committed intents + git history
   npx @skyf0xx/hedgehog plan                      compile pending intents into tasks + dependencies,
                                                    then open the build graph if anything compiled
   npx @skyf0xx/hedgehog intent add [flags]        add an intent (rules/requirements/dependencies)
   npx @skyf0xx/hedgehog intent add --file <path>  add an intent from a JSON file
   npx @skyf0xx/hedgehog next                      print the task packet for one ready task
-  npx @skyf0xx/hedgehog verify <task-id>          run scope + verify checks, commit on pass
-  npx @skyf0xx/hedgehog status                    graph overview: counts by status, ready list
+  npx @skyf0xx/hedgehog claim --owner <owner> [--count <n>]   atomically claim up to n ready tasks
+  npx @skyf0xx/hedgehog release <task-id> --owner <owner>   hand a claimed task back to ready
+  npx @skyf0xx/hedgehog renew <task-id> --owner <owner> [--minutes <n>]   extend a held lease
+  npx @skyf0xx/hedgehog verify <task-id> --owner <owner>   run scope + verify checks, commit on pass
+  npx @skyf0xx/hedgehog status                    graph overview: counts by status, ready list, in flight
+  npx @skyf0xx/hedgehog ready                     preview which ready tasks are claimable now vs held back
+  npx @skyf0xx/hedgehog quiesce                   report whether anything is still in flight
   npx @skyf0xx/hedgehog graph                     start (or reuse) the live graph server and open it
   npx @skyf0xx/hedgehog graph --no-open           start (or reuse) the server; print the URL instead
   npx @skyf0xx/hedgehog why <path>                provenance chain for a file
@@ -460,10 +510,40 @@ async function update({ hosts }) {
   );
 }
 
+async function dbRebuildCommand() {
+  const corePath = await resolveCorePath();
+  if (!corePath) {
+    console.error(
+      `${red('No core definition found.')} Expected ${bold(AUTHORED_CORE_PATH)} or a root ${bold('core.yaml')} (from \`hedgehog init\`).\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  await dbInit(DB_PATH);
+  const db = openDb();
+  let result;
+  try {
+    result = await rebuildDb(db, { corePath });
+  } finally {
+    db.close();
+  }
+
+  console.log(
+    `${green('rebuilt')}  ${dim(`${result.intentsReplayed} intent(s) replayed, ${result.tasksMarkedComplete} task(s) marked complete`)}\n`,
+  );
+}
+
 async function dbCommand(args) {
   const sub = args[0];
+  if (sub === 'rebuild') {
+    await dbRebuildCommand();
+    return;
+  }
   if (sub !== 'init') {
-    console.error(`${red('Unknown db subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog db init\n`);
+    console.error(
+      `${red('Unknown db subcommand:')} ${sub ?? '(none)'}\n\nUsage: hedgehog db init\n   or: hedgehog db rebuild\n`,
+    );
     process.exitCode = 1;
     return;
   }
@@ -491,6 +571,8 @@ async function resolveCorePath() {
 }
 
 async function planCommand() {
+  await ensureDb();
+
   const corePath = await resolveCorePath();
   if (!corePath) {
     console.error(
@@ -507,10 +589,9 @@ async function planCommand() {
   }
 
   const core = await loadCore(corePath);
-  const db = new DatabaseSync(DB_PATH);
+  const db = openDb();
   let result;
   try {
-    db.exec('PRAGMA foreign_keys = ON;');
     result = planTasks(db, core);
   } finally {
     db.close();
@@ -600,6 +681,8 @@ async function parseIntentArgs(args) {
 }
 
 async function intentCommand(args) {
+  await ensureDb();
+
   const sub = args[0];
   if (sub !== 'add') {
     console.error(
@@ -624,11 +707,10 @@ async function intentCommand(args) {
     return;
   }
 
-  const db = new DatabaseSync(DB_PATH);
+  const db = openDb();
   let intent;
   try {
-    db.exec('PRAGMA foreign_keys = ON;');
-    intent = addIntent(db, record);
+    intent = await addIntent(db, record);
   } catch (err) {
     console.error(`${red('Failed to add intent:')} ${err.message}\n`);
     process.exitCode = 1;
@@ -642,17 +724,18 @@ async function intentCommand(args) {
 }
 
 async function nextCommand() {
+  await ensureDb();
+
   if (!(await exists(DB_PATH))) {
     console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
     process.exitCode = 1;
     return;
   }
 
-  const db = new DatabaseSync(DB_PATH);
+  const db = openDb();
   let packet;
   let stalled = [];
   try {
-    db.exec('PRAGMA foreign_keys = ON;');
     packet = nextTask(db);
     if (!packet) stalled = stalledTasks(db);
   } finally {
@@ -666,8 +749,7 @@ async function nextCommand() {
     if (stalled.length > 0) {
       console.error(`${red(bold('No ready task, but the graph is blocked.'))}\n`);
       for (const task of stalled) {
-        const reason =
-          task.status === 'failed' ? 'verification failed' : 'scope violation';
+        const reason = BLOCKED_REASON_LABELS[task.blocked_reason] ?? task.blocked_reason;
         console.error(`  ${red('✗')} ${bold(task.id)}   ${task.layer}   ${dim(reason)}`);
       }
       console.error(
@@ -684,9 +766,13 @@ async function nextCommand() {
 }
 
 async function verifyCommand(args) {
+  await ensureDb();
+
   const taskId = args[0];
-  if (!taskId) {
-    console.error(`${red('Usage:')} hedgehog verify <task-id>\n`);
+  const ownerIdx = args.indexOf('--owner');
+  const owner = ownerIdx !== -1 ? args[ownerIdx + 1] : undefined;
+  if (!taskId || !owner) {
+    console.error(`${red('Usage:')} hedgehog verify <task-id> --owner <owner>\n`);
     process.exitCode = 1;
     return;
   }
@@ -697,11 +783,10 @@ async function verifyCommand(args) {
     return;
   }
 
-  const db = new DatabaseSync(DB_PATH);
+  const db = openDb();
   let result;
   try {
-    db.exec('PRAGMA foreign_keys = ON;');
-    result = verifyTask(db, taskId);
+    result = verifyTask(db, taskId, owner);
   } catch (err) {
     console.error(`${red('Verify failed:')} ${err.message}\n`);
     process.exitCode = 1;
@@ -711,7 +796,7 @@ async function verifyCommand(args) {
   }
 
   if (result.outcome === 'scope_violation') {
-    console.error(`${red(bold('Scope violation.'))} Task ${bold(taskId)} stays ${bold('implemented')}.\n`);
+    console.error(`${red(bold('Scope violation.'))} Task ${bold(taskId)} is now ${bold('blocked')}.\n`);
     console.error('Touched paths outside allowed scope:');
     for (const path of result.offending) console.error(`  ${red('✗')} ${path}`);
     console.error();
@@ -720,7 +805,7 @@ async function verifyCommand(args) {
   }
 
   if (result.outcome === 'failed') {
-    console.error(`${red(bold('Verification failed.'))} Task ${bold(taskId)} is now ${bold('failed')} (exit ${result.exitCode}).\n`);
+    console.error(`${red(bold('Verification failed.'))} Task ${bold(taskId)} is now ${bold('blocked')} (exit ${result.exitCode}).\n`);
     if (result.output) console.error(result.output);
     process.exitCode = 1;
     return;
@@ -738,17 +823,142 @@ async function verifyCommand(args) {
   }
 }
 
+// `hedgehog claim --owner <owner> [--count <n>]` — atomically claims up to
+// `count` mutually non-conflicting ready tasks (claimTasks's fan-out, item
+// 13) and prints each one's packet-level summary, plus which owner now
+// holds them.
+async function claimCommand(args) {
+  await ensureDb();
+
+  const ownerIdx = args.indexOf('--owner');
+  const owner = ownerIdx !== -1 ? args[ownerIdx + 1] : undefined;
+  const countIdx = args.indexOf('--count');
+  const count = countIdx !== -1 ? Number(args[countIdx + 1]) : 1;
+  if (!owner) {
+    console.error(`${red('Usage:')} hedgehog claim --owner <owner> [--count <n>]\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = openDb();
+  let claimed;
+  try {
+    claimed = claimTasks(db, { owner, count });
+  } finally {
+    db.close();
+  }
+
+  if (claimed.length === 0) {
+    console.log(`${dim('No claimable task.')} Nothing is ready with no lease held.\n`);
+    return;
+  }
+
+  if (claimed.length > 1) {
+    console.log(`${green(bold('Claimed.'))} ${claimed.length} task(s) to ${bold(owner)}.`);
+  } else {
+    console.log(`${green(bold('Claimed.'))} Task ${bold(claimed[0].id)} leased to ${bold(owner)}.`);
+  }
+  for (const task of claimed) {
+    if (claimed.length > 1) console.log(`  ${bold(task.id)}`);
+    console.log(`  ${dim('expires')}  ${task.lease_expires_at}`);
+  }
+}
+
+// `hedgehog release <task-id> --owner <owner>` — hands a claimed task
+// back to `ready` without marking it blocked, for an agent stopping
+// cleanly before finishing.
+async function releaseCommand(args) {
+  await ensureDb();
+
+  const taskId = args[0];
+  const ownerIdx = args.indexOf('--owner');
+  const owner = ownerIdx !== -1 ? args[ownerIdx + 1] : undefined;
+  if (!taskId || !owner) {
+    console.error(`${red('Usage:')} hedgehog release <task-id> --owner <owner>\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = openDb();
+  let result;
+  try {
+    result = releaseTask(db, taskId, owner);
+  } finally {
+    db.close();
+  }
+
+  if (!result.released) {
+    console.error(`${red('Not released.')} Task ${bold(taskId)} is not leased to ${bold(owner)} as ${bold('building')}.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`${green(bold('Released.'))} Task ${bold(taskId)} is now ${bold('ready')}.`);
+}
+
+// `hedgehog renew <task-id> --owner <owner> [--minutes <n>]` — extends a
+// held lease, for an agent still working past the original lease window.
+async function renewCommand(args) {
+  await ensureDb();
+
+  const taskId = args[0];
+  const ownerIdx = args.indexOf('--owner');
+  const owner = ownerIdx !== -1 ? args[ownerIdx + 1] : undefined;
+  const minutesIdx = args.indexOf('--minutes');
+  const minutes = minutesIdx !== -1 ? Number(args[minutesIdx + 1]) : 45;
+  if (!taskId || !owner) {
+    console.error(`${red('Usage:')} hedgehog renew <task-id> --owner <owner> [--minutes <n>]\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = openDb();
+  let result;
+  try {
+    result = renewLease(db, taskId, owner, minutes);
+  } finally {
+    db.close();
+  }
+
+  if (!result.renewed) {
+    console.error(`${red('Not renewed.')} Task ${bold(taskId)} is not leased to ${bold(owner)}.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`${green(bold('Renewed.'))} Task ${bold(taskId)}'s lease extended by ${minutes} minute(s).`);
+}
+
 async function statusCommand() {
+  await ensureDb();
+
   if (!(await exists(DB_PATH))) {
     console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
     process.exitCode = 1;
     return;
   }
 
-  const db = new DatabaseSync(DB_PATH);
+  const db = openDb();
   let result;
   try {
-    db.exec('PRAGMA foreign_keys = ON;');
     result = graphStatus(db);
   } finally {
     db.close();
@@ -757,6 +967,63 @@ async function statusCommand() {
   console.log(formatStatus(result));
 }
 
+// `hedgehog ready` — read-only preview of what a `hedgehog claim` call
+// would claim right now, and why anything ready is held back. Claims
+// nothing.
+async function readyCommand() {
+  await ensureDb();
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = openDb();
+  let result;
+  try {
+    result = readyTasks(db);
+  } finally {
+    db.close();
+  }
+
+  console.log(formatReady(result));
+}
+
+// `hedgehog quiesce` — reports whether anything is still in flight
+// (`building` or `verifying`), for a caller that has stopped dispatching
+// and wants to know it's safe to treat the graph as settled. Claims and
+// changes nothing; exits non-zero when the graph isn't quiesced yet so a
+// caller can poll it in a loop or script.
+async function quiesceCommand() {
+  await ensureDb();
+
+  if (!(await exists(DB_PATH))) {
+    console.error(`${red('No build graph found.')} Run ${bold('hedgehog db init')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const db = openDb();
+  let inFlight;
+  try {
+    ({ inFlight } = graphStatus(db));
+  } finally {
+    db.close();
+  }
+
+  if (inFlight.length === 0) {
+    console.log(`${green(bold('Quiesced.'))} Nothing in flight.`);
+    return;
+  }
+
+  console.error(`${yellow(bold('Not quiesced.'))} ${inFlight.length} task(s) still in flight:\n`);
+  for (const task of inFlight) {
+    console.error(`  ${task.id}   ${task.status}    owner: ${task.lease_owner}`);
+  }
+  process.exitCode = 1;
+}
+
 const GRAPH_PIDFILE_PATH = '.hedgehog/graph-server.json';
 const GRAPH_SERVER_MODULE = join(PKG_ROOT, 'src/db/graph-server.mjs');
 const GRAPH_TEMPLATE_PATH = join(PKG_ROOT, 'src/templates/graph.html');
@@ -885,6 +1152,8 @@ async function graphCommand(args) {
 }
 
 async function whyCommand(args) {
+  await ensureDb();
+
   const path = args[0];
   if (!path) {
     console.error(`${red('Usage:')} hedgehog why <path>\n`);
@@ -898,10 +1167,9 @@ async function whyCommand(args) {
     return;
   }
 
-  const db = new DatabaseSync(DB_PATH);
+  const db = openDb();
   let chain;
   try {
-    db.exec('PRAGMA foreign_keys = ON;');
     chain = whyPath(db, path);
   } finally {
     db.close();
@@ -911,6 +1179,8 @@ async function whyCommand(args) {
 }
 
 async function frictionCommand(args) {
+  await ensureDb();
+
   const sub = args[0];
 
   if (!(await exists(DB_PATH))) {
@@ -941,11 +1211,10 @@ async function frictionCommand(args) {
       return;
     }
 
-    const db = new DatabaseSync(DB_PATH);
+    const db = openDb();
     let entry;
     try {
-      db.exec('PRAGMA foreign_keys = ON;');
-      entry = addFriction(db, { note, taskId });
+      entry = await addFriction(db, { note, taskId });
     } catch (err) {
       console.error(`${red('Failed to log friction:')} ${err.message}\n`);
       process.exitCode = 1;
@@ -959,10 +1228,9 @@ async function frictionCommand(args) {
   }
 
   if (sub === 'list') {
-    const db = new DatabaseSync(DB_PATH);
+    const db = openDb();
     let entries;
     try {
-      db.exec('PRAGMA foreign_keys = ON;');
       entries = listFriction(db);
     } finally {
       db.close();
@@ -1073,11 +1341,36 @@ async function main() {
     return;
   }
 
+  if (cmd === 'claim') {
+    await claimCommand(args.slice(1));
+    return;
+  }
+
+  if (cmd === 'release') {
+    await releaseCommand(args.slice(1));
+    return;
+  }
+
+  if (cmd === 'renew') {
+    await renewCommand(args.slice(1));
+    return;
+  }
+
   if (cmd === 'status') {
     await statusCommand();
     return;
   }
 
+  if (cmd === 'ready') {
+    await readyCommand();
+    return;
+  }
+
+  if (cmd === 'quiesce') {
+    await quiesceCommand();
+    return;
+  }
+
   if (cmd === 'graph') {
     await graphCommand(args.slice(1));
     return;

package/package.json

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

package/src/agents/backend-eng.md

@@ -11,9 +11,9 @@ You are the backend-eng role in the Hedgehog discipline, building Phase A
 `apps/worker`) one domain module at a time. The stack and the layer
 sequence within a module are fixed (`hedgehog-loop`, compiled into
 `src/golden-cores/full-stack-app/core.yaml`) — not yours to reorder or
-reshape. You're invoked with a `hedgehog next` task packet, not a step
-name — build exactly what its ALLOWED SCOPE names, one layer at a time,
-gated by `hedgehog verify` before the next starts.
+reshape. You're invoked with a claimed task packet, not a step name —
+build exactly what its ALLOWED SCOPE names, one layer at a time, gated by
+`hedgehog verify` before the next starts.
 
 ## Stack (locked)
 
@@ -62,7 +62,7 @@ needed.
 
 ## Workflow
 
-1. Read the `hedgehog next` task packet: its ALLOWED SCOPE is what to
+1. Read the claimed task packet: its ALLOWED SCOPE is what to
    build, not a step name you infer independently. Its WHY NOW section
    already confirms the module is in scope and every dependency is
    `complete` — no need to re-derive that by hand. Cross-module FK
@@ -86,6 +86,10 @@ needed.
 
 ## Constraints
 
+- Default to no comments. Add one only when the WHY is non-obvious — a
+  hidden constraint, a workaround for a specific bug, an invariant the
+  code alone can't convey. Never comment WHAT the code does; a
+  well-named schema field, function, or variable already says that.
 - Never self-certify a task as done or run `git commit` for its changes —
   see Workflow step 3.
 - Never import another module's repository, service, or schema directly
@@ -108,3 +112,17 @@ needed.
 - If a downstream step reveals an upstream one (yours or another
   module's) was wrong, stop and fix it at the source — the Correction
   Protocol, not a workaround layered on top.
+- You may be one of several agents building concurrently, each holding a
+  lease on its own task and scoped to its own ALLOWED SCOPE — a file
+  outside your scope changing while you work is another agent's task, not
+  a stray edit to fix. Never edit, revert, or "clean up" a file outside
+  your own scope, and never run a repo-wide command (a formatter over the
+  whole repo, a codemod, `nx migrate`, `nx format:write` with no path
+  filter) — it doesn't respect scope boundaries and will collide with
+  another agent's in-flight files.
+- If verification fails for a reason plainly not yours — a neighboring
+  in-flight task's file shows up as a conflict, or a shared/global check
+  fails for reasons outside this task's scope — report it rather than
+  fixing it. That's a scheduler or core-design bug, and diagnosing it
+  belongs to the orchestrating session's Correction Protocol, not to this
+  step reaching outside its task to patch things over.