@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/monorepo/scripts/backlog/README.md

@@ -0,0 +1,689 @@
+# `backlog` dispatcher
+
+The reconciler that turns a `Queued` Backlog.md task into a running headless worker and, on
+completion, into a merge-ready PR. Three triggers fire it — a `onStatusChange` callback, a
+`launchd` timer, and a `gh` poll for merged PRs inside the maintenance pass — and every trigger
+runs the exact same idempotent pass: sweep dead locks and orphan slots, close out merged PRs,
+recompute every parent's derived status, pick the next `Queued` task by priority then age, run it
+through twelve guards, verify the local model is loaded when the task needs it, acquire a worktree
+slot, launch the right lane (`local`, a curated LM Studio executor, or `frontier`, a headless
+Claude Code orchestrator), and close — board integrity, a mechanical scope check, format → barrels
+→ the task's declared test, the reviewer on the local lane, the AC/DoD gate on both, then a PR — or,
+on any failure, save the work before ever releasing the slot. `openspec/changes/add-backlog-task-dispatch/design.md`
+(and the archived changes under `openspec/changes/archive/`) hold the rationale and decision log;
+this file documents how the pieces fit together operationally, as they stand today.
+
+## Module table
+
+| Module | Responsibility |
+| --- | --- |
+| `entry.ts` | Orchestration root: resolves the MAIN checkout every other entry point reads and writes board state in (`resolveContext`/`resolveMainCheckout` — `BACKLOG_CWD` first, `git rev-parse --git-common-dir` otherwise, so a trigger fired from a worktree still lands on the main checkout), serializes concurrent invocations with a single-flight file lock, applies the anti-loop guard to a status-change trigger, selects the next `Queued` task, and wires maintenance → selection → guards → model readiness → slot acquisition → launch → close into one pass (`runOnce`). Releases the single-flight lock mid-pass — see "Process model" |
+| `maintenance.ts` | Runs first every pass and returns the post-sweep slot registry, in order: retries a pending push (refusing once the branch's PR reads `merged`); sweeps locks with a dead PID or an expired heartbeat, saving work before releasing; releases slots with no live process; attempts the «Registro de ejecución» block THEN, regardless of whether that write succeeded, moves a task with a merged PR to `Done` (see "The «Registro de ejecución» block" below — a write that fails posts ONE board comment instead and never blocks the transition) and deletes its `task/<id>` branch once confirmed free of unmerged commits and confirmed gone on the remote; reverts a hand-written `Done` back to `In Progress` when GitHub does not report the PR merged; blocks an orphan `In Progress` task past `lanes.json`'s `orphanInProgressThresholdHours` (`0` disables this step); kills a manually-cancelled task's worker after saving its work; recomputes every parent's derived state — attempting the SAME block, the SAME way, for a parent this derivation itself moves to `Done` (deleting its branch the same way a leaf task's is); refreshes the graph-holder task (see "The dependency view" below) with the current dependency view when it changed; commits any pending `.backlog/**` change |
+| `guards.ts` | `evaluateGuards(task, board, slots, limits, permissions, remoteBranches)` — the twelve dispatch guards over the selected task, in fixed order (see "The guard chain"). Also owns `resolveTestCommand` (the one allowlist for a declared `Test command:`, shared with `launch.ts` and `close.ts`), `grantCovers`/`denyWouldRevoke`/`findPermissionConflict` (the permission-rule comparison guard 1b and `launch.ts` both read), and `taskBaseBranch`/`resolveTaskBase` — the ONE place a task's base branch is named (`task/<parentId>`, or `main`), consulted by `slots.ts`'s branch resolution and by `close.ts`'s PR-base resolution |
+| `graph.ts` | The pure logic behind the dependency view (see "The dependency view" below): `renderDependencyGraph`/`renderHolderDescription` over a `Board`, `decideGraphWrite` (what, if anything, a refresh should write), and `runGraphCli` (the whole `backlog:graph` behaviour — argv gate, the incomplete-board warning, the effect dispatch, the exit code) over injected effects. Never imports `dispatch.ts` |
+| `graph-cli.ts` | The `backlog:graph` executable entry point: binds `graph.ts`'s `runGraphCli` to the real board (`dispatch.ts`'s `loadAllTasks`) and the real `backlog` CLI (`dispatch.ts`'s `realBacklog`), and resolves the MAIN checkout through `entry.ts`'s `resolveContext`, fed `dispatch.ts`'s `realGitCommonDir` |
+| `slots.ts` | Acquires and releases one of the three reusable worktrees, provisions one on demand (`git worktree add --detach origin/main` → `scripts/worktree-link.sh` → `pnpm install`), and — after `prepareSlot` resets the slot onto the task's branch — installs (never builds) `packages/cli`'s own dependencies, tracked by its own `cliLockfileHash` field. Owns the dispatch-lock lifecycle (PID + heartbeat), branch resolution (reuse the existing branch on retry; otherwise `resolveTaskBase` names the base and `resolveBranch` throws if that base is missing from the remote), `slotPathForTask`, the one release procedure (`releaseSlotAndDetach`), the manual rescue behind `--release-slot` (`releaseHeldSlotEntries`), and `updateSlots` — the one mutation primitive every `slots.json` write goes through |
+| `launch.ts` | Per-lane launch preparation: lane/model resolution from the task's labels, the exact `claude` argv per lane (the lane settings' `permissions.allow`/`deny` become `--allowedTools`/`--disallowedTools`, merged with the `worker-edit.ts` wrapper rule and the task's own validated test-command rule), settings-source loading and the allow→deny subtraction (`composeGrantedAllow`), `assertLaneGrantsFileAccess` (a lane must grant at least one read rule and one write rule), `dispatchLimitsFrom` (the `maxParallel`/`attempts` caps), `sanitizeInheritedEnv` (drops every inherited `ANTHROPIC_*`/`CLAUDE_CODE_*` key and every other credential-shaped one), the line-streamed `spawnWorker`, `killProcessTree`, and the LM Studio readiness check before a local-lane launch |
+| `close.ts` | The dispatch close: `checkBoardIntegrity`, `checkScope`, `planMechanicalChecks` (Prettier `--write` then `--check` per workspace → barrels lint → the task's declared test, all scoped to the attempt's own changed files), the CLI scaffold mirror regeneration, `evaluateAcceptanceGate`, `open-pr`, and the failure-path save — see "The close". Also owns `buildExecutionRecordBlock`/`hasExecutionRecordBlock`, the PURE composer and idempotence sentinel `maintenance.ts`'s `Done` transition calls — see "The «Registro de ejecución» block" |
+| `parent.ts` | `deriveParentStatus(children, ownPrMerged, tier?, closeAttempted?)` — the parent-state precedence rule (see "Load-bearing invariants"), applied recursively through `effectiveStatus`. Parent state is written ONLY by `maintenance.ts`'s `recomputeParent` |
+| `render.ts` | Maps one `stream-json` event to a human-readable log line (`renderEvent`) and replays a whole recorded session (`renderStream`); shared by the close's `run.log` writer and `watch.ts` |
+| `watch.ts` | `pnpm backlog:watch <id>` tails that attempt's rendered `run.log` live; with no id, lists busy slots from `slots.json`. Stops once the task's lock file disappears (the close removes it as its last step). Read-only — never writes board state, a lock, or a slot |
+| `notify.ts` | Fires a macOS notification (`osascript`) on `Blocked` and on PR-opened; a no-op on any non-`darwin` platform |
+| `attempt.ts` | The per-attempt record under `.backlog/.dispatch/<TASK_ID>/intento-<N>/`: `countAttempts`, `createAttemptDir` (opened before the worker starts, so `backlog:watch` can tail it live), and `createAttemptSink` (appends `stream.jsonl` line by line, renders `run.log` once on `finish`, and refreshes the lock heartbeat every 30 s until `stopHeartbeat`) |
+| `reviewer.ts` | The local lane's close reviewer: an isolated, read-only `claude` argv (`--setting-sources user --strict-mcp-config --disable-slash-commands`, no write tool, deliberately not `--bare`), the dual-verdict prompt (defects, per-criterion conformity, and "would this test fail if its logic broke?") with the diff fenced as untrusted data, and the `REVIEW COMPLETE` + `VERDICT: pass|fail` parse. Fails closed — no verdict blocks the task |
+| `task-view.ts` | The single parser for the `backlog` CLI's plain output: `parseBoardTaskIds`, the `Task` shape (`tier`/`lane`/`path` resolved against real label values), the `Files to touch:`/`Test command:` conventions, the acceptance/DoD texts snapshotted at launch, and the AC/DoD checklists with their checked state |
+| `worker-edit.ts` | The ONLY board channel a dispatched worker is granted, read included — see "`worker-edit.ts`: the worker's only board channel" |
+| `dispatch.ts` | The executable entry point every trigger invokes: wires the real collaborators (`fs`, `git`/`gh`/`backlog` shell-outs, a real `claude` spawn) and calls `entry.ts`'s `runOnce`. Owns the `--release-slot` rescue flag |
+
+`types.ts` holds the shared shapes (task labels, `slots.json`, `locks/<TASK_ID>.json`) every other
+module imports from. `prompt.ts` assembles the local-lane executor's five-block user prompt and, with
+`buildFrontierAddendum`, renders the frontier lane's per-attempt system-prompt addendum from
+`.claude/skills/catalyst-backlog/frontier-worker-addendum.md`.
+
+## Load-bearing invariants
+
+- Parent state is never written by hand: `maintenance.ts`'s `recomputeParent` is the only writer.
+- The per-task lock's heartbeat covers the close too, not just the worker's run — it stops only
+  once the slot has been released or held, so a close whose own steps outlast the 10-minute TTL is
+  never mistaken for a dead worker.
+- `guards.ts`'s `resolveTaskBase` is the ONE place a task's base branch is named; `slots.ts`'s branch
+  resolution and `close.ts`'s PR-base resolution both consult it rather than compute their own answer.
+- A task's branch closes itself only when it is named `task/T-nn` — the merge sweep deduces the
+  branch from the task id and asks `gh` whether that branch's PR merged.
+- A subtask's base is always `task/<parentId>` — a pure deduction from the parent's id, never a
+  value a task declares.
+- Every `slots.json` write goes through `slots.ts`'s `updateSlots`, which takes an exclusive lock,
+  RE-READS the file, and applies the caller's transform to what it finds there.
+- A slot never keeps a task branch checked out after release: every release path runs
+  `git checkout --detach` first, because git refuses to check the same branch out in two worktrees.
+- Work is branched and diffed against `origin/…`, never a local ref — a reusable slot's local `main`
+  is whatever its last fetch left behind.
+- `worker-edit.ts` is the ONLY board channel a dispatched worker is granted, reading included.
+- The declared `Test command:`, `Files to touch:`, the title and the AC/DoD texts are snapshotted at
+  launch; the close judges the attempt against that snapshot, never a re-read of the board.
+- The twelve guards run in a fixed order and the first one that fires wins — no later guard is
+  evaluated once an earlier one has decided the outcome.
+- `--permission-mode dontAsk` denies any Edit/Write on a path carrying a `.claude` segment,
+  regardless of what any allow rule says, on either lane — no lane-settings change can undo this.
+- The click-approval overlay (`.claude/settings.local.json`, a person's own ad-hoc approvals) is
+  never a loaded settings source for a dispatched worker, on either lane.
+- A dispatched worker's `Bash` grant is not the only thing that lets a command run: Claude Code
+  itself auto-approves a `Bash` command it can statically read as read-only (a bare `ls`, `grep`,
+  `find` without `-exec`/`-delete`, …), whatever the allow list says — a compound line is not.
+- Every headless worker runs with `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`, forced by `launch.ts`
+  over any lane `env`, on both lanes — a `-p` session kills a backgrounded Bash call the moment it
+  ends its own turn, and kills a backgrounded Agent's longer work too, after at most one extra
+  relay turn.
+
+## On-disk data layout
+
+The board (`.backlog/tasks/`, `.backlog/config.yml`) lives ONLY in the main checkout, never in a
+slot; every dispatcher process, and every `backlog` CLI call it makes, is pointed there with
+`BACKLOG_CWD=<main checkout>`. Both lane settings deny `Edit`/`Write` on `.backlog/**`, and the
+close's scope check reports a change there as a violation on both lanes, so a slot's own `.backlog/`
+copy is never the board of record. `.backlog/config.yml` sets `check_active_branches: false`
+(three worktrees independently writing the same task files would be a merge-conflict generator) and
+`auto_commit: false` — Backlog.md's own auto-commit message fails this repo's commitlint, so
+`maintenance.ts`'s `commitBacklogChanges` commits any pending `.backlog/**` change itself, with a
+Conventional Commit message, `--no-verify`, and a trailing `-- .backlog` pathspec so an unrelated
+staged file never rides along.
+
+Everything the dispatcher writes at RUNTIME lives under `.backlog/.dispatch/`, which is gitignored
+(unlike `.backlog/` itself):
+
+```
+.backlog/.dispatch/
+  <TASK_ID>.log                 # nohup redirect of every reconciler run this task's status
+                                 # transitions started — APPENDED to
+  launchd.log                   # the launchd launcher's own output
+  reconciler.log                # nohup redirect of the detached reconciler
+  slots.json                    # [{ name, path, lane, taskId|null, pid|null, lockfileHash, heldForRecovery? }]
+  slots.lock                    # exclusive lock guarding every slots.json write
+  locks/<TASK_ID>.json           # { taskId, slot, pid, workerPid, startedAt, heartbeatAt, lane, attempt, branch }
+  <TASK_ID>/intento-<N>/
+    stream.jsonl                 # raw stream-json, appended line by line while the worker runs
+    run.log                      # human-rendered, written ONCE when the worker exits
+    test.log                     # transcript of the close's mechanical checks
+    review.md                    # the close reviewer's findings (local lane); read back on a retry
+```
+
+There is no `meta.json` file: the per-attempt record is `stream.jsonl` + `run.log` + `test.log` +
+`review.md` only.
+
+A lock is dead when `process.kill(pid, 0)` throws, or when `heartbeatAt` is older than the TTL
+(10 minutes) even with a live PID. `attempt.ts` refreshes `heartbeatAt` on a 30 s timer, deliberately
+not from the stream events, so a worker merely thinking or waiting on a long test run is never
+swept. The reviewer subprocess is separately bounded by `lanes.json`'s `reviewerTimeoutMinutes`.
+
+**External call timeout (T-97).** That 30 s timer only runs BETWEEN synchronous subprocess calls —
+it cannot fire while `dispatch.ts` is blocked inside a single `execFileSync` (`git`, `gh`, `backlog`,
+`node`, `osascript`, `npx tsx`), because that blocks the whole event loop the timer needs. Before this
+task none of `dispatch.ts`'s ~20 `execFileSync` calls carried a `timeout`, so a single hung one — a
+stalled `ssh` inside `git ls-remote`, measured 2026-09-15: 2h23m holding `dispatch.lock` — starved the
+heartbeat until the maintenance sweep declared a live pass dead. Every such call now carries a
+`timeout`, well under the 10-minute lock TTL above, so a hang fails like any other failure of that
+call (never a new destructive path) instead of blocking forever:
+
+- `EXTERNAL_CALL_TIMEOUT_MS` (`dispatch.ts`, 60 s) bounds every `git`/`gh`/`backlog`/`osascript`/
+  `npx tsx` call — metadata reads and writes that normally finish in well under a second.
+- `MECHANICAL_CHECK_TIMEOUT_MS` (`dispatch.ts`, private, 8 minutes) bounds only the close's own
+  mechanical checks (prettier, the barrels lint, the task's declared Test command) — these
+  legitimately run for minutes, so they get a longer leash than the metadata calls above, but one
+  that still fails before the 10-minute lock TTL rather than exhausting it.
+- `RealGitDeps.timeoutMs` and `makeGhRunner(timeoutMs)` are the injection seams that let a test bind
+  a short bound instead of the production default — see `dispatch.test.ts`'s "a hanging git/gh call
+  is bounded" suites.
+
+`packages/cli`'s dependency install (`provisionSlot`/`provisionCliDependencies`, `stdio: 'inherit'`)
+is deliberately NOT bounded by either constant: it runs before any per-task lock exists, under the
+single-flight lock instead, which is PID-liveness-based rather than TTL-based — a slow (not hung)
+install there does not starve a heartbeat that has not started yet, and a real install can legitimately
+outrun even `MECHANICAL_CHECK_TIMEOUT_MS` on a cold cache.
+
+The lock carries TWO pids: `pid` is the RECONCILER (the liveness probe), `workerPid` is the spawned
+`claude` process (what a cancellation kills, as a whole process group). `slots.json` is the
+allocation mutex (which of the three worktrees — `dispatch-a`, `dispatch-b`, `dispatch-c` — is
+occupied, by which task, for which lane); `locks/<TASK_ID>.json` is the liveness detail for whoever
+holds it. A slot flagged `heldForRecovery` is neither free nor reassignable — it holds the only
+copy of work that never reached the remote.
+
+`packages/cli`'s dependency install (never its build) runs in the same pass, on its own tracked
+field (`cliLockfileHash`) — `packages/cli` is not a pnpm workspace member, so the root `pnpm
+install` never reaches it; the step is skipped in a repo with no `packages/cli` of its own. The same
+pass also removes `packages/cli/dist` (gitignored) so a worker never inherits a previous occupant's
+build output — building it is the worker's own job (`pnpm cli:build`).
+
+## Process model
+
+One reconciler process handles at most one dispatch, but it does NOT hold the single-flight lock for
+the worker's lifetime:
+
+1. Acquire the single-flight lock (`.backlog/.dispatch/dispatch.lock`, PID-based) and run the whole
+   maintenance → selection → guards → readiness → slot-acquisition sequence under it.
+2. Once the slot is taken, the per-task lock is written and the task is `In Progress`, **release the
+   single-flight lock** — it only serializes selection, never a worker's whole run.
+3. Spawn the worker asynchronously, in its own process group, with a sanitized environment (every
+   `ANTHROPIC_*`/`CLAUDE_CODE_*` key and every other credential-shaped one dropped before the lane's
+   own `env` is layered on). Its pid is written as `workerPid` the moment it exists; its stdout
+   streams into `stream.jsonl`; a 30 s timer refreshes `heartbeatAt`.
+4. When the worker exits, render `run.log` and run the close. The heartbeat keeps beating through it,
+   stopping only once the slot has been released or held — true only because every close step's own
+   subprocess calls are bounded well under the lock TTL (see "External call timeout (T-97)" above);
+   an unbounded call inside a close step would block the 30 s timer for as long as it hung.
+
+Before step 4 runs anything, the pass RE-READS its own per-task lock: a lock that is gone, or that
+names another pid, means another pass's maintenance sweep already declared this worker dead, saved
+its work and released the slot — this pass skips the close entirely rather than open a PR off a
+branch someone else now owns.
+
+Both triggers detach the reconciler with `nohup` and return at once, which is why holding the
+single-flight lock across a worker's whole run would be wrong: it would make the frontier cap of 2
+unreachable and stall every later pass.
+
+**Cancellation is explicit, never inferred from "not `In Progress`".** A cancellation is a task moved
+by hand to `Blocked`/`To Do`, or a task missing from a board read that completed in FULL — never
+merely a task the sweep does not currently see as `In Progress`. On a cancellation the worker's whole
+process group is killed AFTER its work is saved, never before.
+
+Everything from taking the slot to the worker exiting runs inside one try/catch: any failure — a
+failing install, a vanished ref, a dying hook — returns the slot to the pool, removes the lock, and
+moves the task to `Blocked` with the error, rather than leaving it stuck `In Progress`.
+
+A close that drains re-acquires the single-flight lock and runs ONE more pass for the next `Queued`
+task; two passes per invocation is the cap.
+
+## The guard chain (`guards.ts`)
+
+`evaluateGuards` runs twelve checks in this fixed order over the selected `Queued` task. The first
+one that returns a result wins:
+
+| # | Check | Fires on | Result |
+| --- | --- | --- | --- |
+| 0 | Supervised mode | the task carries `mode:supervised` | block |
+| 1 | Triage complete | missing `tier`/`lane`/`path`/`mode`; `tier:medium` on `lane:local`; `lane:local` with no `Files to touch:`; no declared `Test command:`, or one the allowlist refuses | block |
+| 1c | Declared slot-executed path | a `Files to touch:` entry reaches `SLOT_EXECUTED_PATHS`/`SLOT_EXECUTED_BASENAMES`, as a file or a containing directory | block |
+| 1d | Declared `.claude` path | a `Files to touch:` entry carries a `.claude` path component at any depth | block |
+| 1e | Declared supervised-only path | a `Files to touch:` entry reaches a path on `SUPERVISED_ONLY_PATHS` | block |
+| 1b | Permission composition | a settings rule this worker's sources load is broader than what the launch would grant, or scopes a file tool the lane does not cover | block |
+| 2 | Complex on local | `tier:complex` with `lane:local` | block |
+| 3 | Dependencies | an unresolved dependency id | block; an unfinished-but-resolvable one | wait |
+| 4 | Security path on local | `lane:local` declares a file under a security-surface pattern | block |
+| 4b | Parent branch on remote | a subtask whose `task/<parentId>` is missing from `origin` | block |
+| 5 | Attempts exhausted | `task.attempts >= lanes.json`'s `attempts` cap | block |
+| 6 | Free slot | the lane is at `maxParallel` capacity | wait (`no-free-slot`); this task's own slot is held for push recovery | wait (`push-pending`) |
+
+Falling through all twelve means the task is clear to launch. A `block` moves the task to `Blocked`
+with a Spanish comment naming the cause; a `wait` leaves it `Queued` for the next pass. Guard 0 runs
+before every other guard, including guard 1's triage check: a `mode:supervised` task has exactly one
+true verdict, so it blocks as supervised even when it also lacks a `Test command:` (guard 1), declares
+a hard-list or supervised-only path (guards 1c/1e), or has an unfinished dependency (guard 3) —
+without guard 0 at the head, a person would fix one of those first, re-queue, and only then learn the
+task was never dispatchable to begin with. Its `Blocked` comment names the exact edit: remove
+`mode:supervised` and add `mode:headless` in the SAME `backlog task edit` (`--remove-label
+mode:supervised --add-label mode:headless` — `--add-label` alone APPENDS, it does not replace, which
+would leave both `mode:` labels on the task), then re-queue.
+
+The security-surface patterns (guard 4, and re-checked at close against the real diff) are:
+`o-auth/`, `iam/`, `.guard.ts`, `@auth`, `sops`, `.env` — matched as a case-insensitive substring of
+each declared path.
+
+## The dependency view (`graph.ts`, `graph-cli.ts`)
+
+`renderDependencyGraph` is the one pure function that decides what the board's open-task dependency
+view says: a flat list — a tree would repeat a task with two parents, since dependencies form a
+DAG — in two sections, `LISTAS — sin dependencias abiertas` (no recorded open wait) and `EN ESPERA`
+(waits for at least one, each line naming every one it waits for, in topological order). It derives
+from what the board RECORDS and nothing else, over the four open statuses (`To Do`, `Queued`,
+`In Progress`, `Blocked`): each task's declared `dependencies`, AND the parent/subtask link — a
+parent waits for every one of its OPEN subtasks exactly like an open dependency, merged with any it
+declares, deduplicated; a subtask never waits for its own parent this way; a `Done` dependency or
+`Done` subtask is never a reason to wait. It guesses no link from what files two tasks happen to
+touch. `renderHolderDescription` prepends the fixed header stating the view's own limit — recorded
+links only, order rather than authorization — and `decideGraphWrite` turns a rendered view into one
+of `no-holder` / `ambiguous` / `incomplete` / `unchanged` / `write`, without performing any I/O
+itself, so both writers below share the exact same decision.
+
+**Two callers, one function — different resolution each.** `pnpm backlog:graph` (`graph-cli.ts`'s
+entry point, which binds `graph.ts`'s pure `runGraphCli` to the real world) prints the current view
+and edits nothing; `pnpm backlog:graph --write` also calls `decideGraphWrite` and applies a `write`
+decision immediately. It resolves the board through the MAIN checkout with `entry.ts`'s
+`resolveContext` — the same resolver every dispatcher entry point uses — so running it from a
+worktree operates the main checkout's board and not the worktree's own copy, which would be a blind
+reconciler. `maintenance.ts`'s step 5b (see its own module-table row and doc comment) calls
+`decideGraphWrite` directly, as part of every reconciler pass, between recomputing parent state and
+the board commit, so a refresh it triggers rides in the same `chore(backlog): sync board state`
+commit as whatever change caused it — it needs no resolution of its own, since it reuses the
+`MaintenanceBacklog.setDescription`/`readDescription` collaborators `dispatch.ts` wired for it, both
+already bound to the resolved main checkout.
+
+**The command reports failure, never silently.** `runGraphCli` returns a non-zero exit code — and
+`graph-cli.ts` sets `process.exitCode` from it — on an unrecognized argument (refused before
+anything runs, nothing written), a board read the loader reported partial, more than one
+`board:graph` holder, or a failed underlying read/write; `0` covers every "printed / refreshed /
+nothing to do" outcome and nothing else. A partial board read is reported on stderr BEFORE the view
+itself, with or without `--write`: a task waiting on one that could not be read would otherwise
+render under "LISTAS" with no caveat in sight.
+
+**The graph-holder task.** Found by the label `board:graph`, never by a task id — this tooling ships
+to every scaffolded application, whose boards number their tasks differently. Zero holders is a
+valid state (the feature is off); two or more is an ambiguity, reported by the caller
+(`console.error` on the CLI, `MaintenanceResult`'s `graphHolderAmbiguous`) — the VIEW is written to
+none of them, but each holder that does not already show it gets a plain-text notice instead, naming
+every id and saying to keep the label on only one, under the same write-on-difference rule as the
+view itself. The CLI still exits non-zero over an ambiguous board (the refresh it was asked for did
+not happen), and removing the label from all but one brings the view back on the next refresh. The
+holder's description is GENERATED — nobody edits it by hand, and it is never queued, worked or
+closed; `catalyst-backlog/SKILL.md` §13 has it labelled `mode:supervised`, so a `Queued` holder is
+refused by guard 0 first — guard evaluation is first-wins (see "The guard chain"), so guard 1's
+separate "no `Test command:`" reason never even runs against it.
+
+**The refresh REPLACES THE WHOLE DESCRIPTION, without reading it first.** Whichever text a holder's
+`--desc` carries today — the view, the ambiguity notice, or whatever a person wrote by hand — the
+next refresh overwrites all of it outright (`backlog task edit --desc`), on both the CLI and
+maintenance step 5b. This is accepted behaviour, not a defect: `board:graph` is a declaration that
+this task's description is machine-owned from now on, so it must never be put on a task whose
+description is worth keeping — see "Accepted risks" below.
+
+## Lane profiles (`lanes.json`)
+
+`scripts/backlog/lanes.json` holds what Claude Code itself cannot express (slot pool, per-lane caps,
+the direct/sdd model split, the LM Studio health-check URL, the reviewer's model and timeout);
+everything Claude Code DOES understand — `model`, `env`, `permissions` — lives in a standard settings
+file per lane, which `launch.ts` reads and translates into the launch (`model` → `--model`,
+`permissions.allow`/`deny` → `--allowedTools`/`--disallowedTools`, `env` → the spawn environment).
+These files are read directly, never passed with `--settings`.
+
+| | `local` | `frontier` |
+| --- | --- | --- |
+| Settings file | `scripts/backlog/lanes/local.settings.json` | `scripts/backlog/lanes/frontier.settings.json` |
+| Model | fixed in the settings file's own `env` (an LM Studio model id) | resolved from the task's `path:` label — `direct` → Sonnet, `sdd` → Opus |
+| `maxParallel` | 1 | 2 |
+| `maxTurns` | 40 | 120 |
+| `timeoutMinutes` | 60 | 90 |
+| `--bare` | yes | no |
+| `--setting-sources` | `user` | `user,project` |
+| Reviewer | `sonnet`, 15 min timeout | none — the AC/DoD gate is the only check |
+
+`attempts` (global, both lanes: 3) and `orphanInProgressThresholdHours` (24) are the other two
+top-level `lanes.json` fields. Both `orphanInProgressThresholdHours` and `lanes.local.reviewerTimeoutMinutes`
+are MANDATORY: `lanes.json` is their only source of truth, and `loadLaneConfig` has no code-level
+fallback for either — an omitted key is a load-time error, not a silent default. `harnessReviewer`
+(top-level, optional) is the human-review mark's `gh` reviewer handle, unset by default since `gh`
+refuses to assign the PR's own author as reviewer.
+`lanes.frontier.maxBudgetUsd` is optional too: set a number on an API-key login for a hard dollar
+stop, omit it on a subscription login where the estimate is not billed.
+
+Both settings files' `env` also carries `DATABASE_MIGRATE_ON_BOOT: "false"`: a slot's backend boot
+(a task's own `test:e2e` `Test command:`) would otherwise apply an unreviewed branch's pending
+migrations straight to the shared dev database, so applying migrations stays a human step on either
+lane.
+
+**`--bare` does not stop settings loading.** Both lanes name a `--setting-sources` value and load it
+for real — the local lane's `user` file, the frontier lane's `user,project` (bringing the project's
+hooks and `.mcp.json`-independent tool set). Whatever loads still brings its own
+`permissions.allow`, and `--allowedTools` ADDS to that rather than replacing it, so the launch also
+computes a deny list: every allow rule the loaded sources contribute that the lane's own list does
+not grant is emitted as a `deny`. A loaded rule already covered by a granted one is skipped
+(`grantCovers`); a loaded rule BROADER than a granted one has no safe answer and blocks the task at
+guard 1b instead of being silently denied or silently kept.
+
+**A read-only `Bash` command needs no allow rule at all** — Claude Code auto-approves a command it
+can statically read as read-only, on both lanes, independent of any settings source. The frontier
+lane's project-hook source additionally vets a wider read-only table
+(`.claude/hooks/auto-allow-readonly-bash.ts`) for the same purpose.
+
+**The task's own `Test command:` is granted per launch, never by a standing rule** — `launch.ts`
+turns the snapshotted line into one `Bash(<command>:*)` rule on both lanes. **Every board write goes
+through exactly one rule, on both lanes:**
+`Bash(npx --loglevel=error tsx <main checkout>/scripts/backlog/worker-edit.ts T-nn:*)` — the grant
+names the MAIN CHECKOUT's copy of the script, never the slot's.
+
+### As shipped: `local.settings.json`
+
+```
+allow: Read, Grep, Glob, Edit(./**), Write(./**), Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git rev-parse:*), Bash(git symbolic-ref:*), Bash(pnpm --filter * exec prettier --check), Bash(pnpm --filter * exec prettier --check *)
+
+deny: Bash(git push:*), Bash(git push*), Bash(git add:*), Bash(git add*), Bash(git commit:*), Bash(git commit*), Bash(git restore:*), Bash(git restore*), Bash(git branch:*), Bash(git branch*), Bash(git clean:*), Bash(git clean*), Bash(gh:*), Bash(gh *), WebFetch, WebSearch, Edit(.backlog/**), Write(.backlog/**), Edit(.husky/**), Write(.husky/**), Edit(.claude/**), Write(.claude/**), Edit(scripts/**), Write(scripts/**), Edit(package.json), Write(package.json), Edit(pnpm-lock.yaml), Write(pnpm-lock.yaml), Edit(node_modules/**), Write(node_modules/**), Edit(.git/**), Write(.git/**)
+```
+
+Plus, per launch: the `worker-edit.ts` wrapper rule and the task's own `Test command:` rule. The
+local lane carries no standing `pnpm` test/build rule of its own — the task's own grant is its only
+one.
+
+### As shipped: `frontier.settings.json`
+
+```
+allow: Read, Grep, Glob, Edit(./**), Write(./**), Agent, Skill, TodoWrite, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git rev-parse:*), Bash(git symbolic-ref:*), Bash(openspec:*), Bash(catalyst:*), Bash(pnpm cli:build:*), Bash(node packages/cli/bin/run.js:*), Bash(pnpm --filter * test), Bash(pnpm --filter * test *), Bash(pnpm --filter * exec prettier --check), Bash(pnpm --filter * exec prettier --check *), Bash(pnpm --filter * exec tsc --noEmit), Bash(pnpm --filter * exec tsc --noEmit *), Bash(pnpm --filter * db:generate), Bash(pnpm --filter * db:generate *), Bash(pnpm db:generate), Bash(pnpm db:generate *), Bash(pnpm --filter * db:check), Bash(pnpm --filter * db:check *), Bash(pnpm db:check), Bash(pnpm db:check *), Bash(pnpm --filter * db:query), Bash(pnpm --filter * db:query *), Bash(pnpm db:query), Bash(pnpm db:query *)
+
+deny: Bash(git push:*), Bash(git push*), Bash(git add:*), Bash(git add*), Bash(git commit:*), Bash(git commit*), Bash(git restore:*), Bash(git restore*), Bash(git branch:*), Bash(git branch*), Bash(git clean:*), Bash(git clean*), Bash(find:*), Bash(find *), Bash(fd:*), Bash(fd *), Bash(gh:*), Bash(gh *), Bash(backlog task edit:*), Bash(backlog task edit *), mcp__backlog__task_edit, mcp__backlog__task_create, mcp__backlog__task_complete, mcp__backlog__task_archive, WebFetch, WebSearch, mcp__claude_ai_Asana__*, mcp__claude_ai_Atlassian__*, mcp__claude_ai_Box__*, mcp__claude_ai_Canva__*, mcp__claude_ai_Figma__*, mcp__claude_ai_Gmail__*, mcp__claude_ai_HubSpot__*, mcp__claude_ai_Intercom__*, mcp__claude_ai_Linear__*, mcp__claude_ai_Notion__*, mcp__claude_ai_monday_com__*, Edit(.backlog/**), Write(.backlog/**), Edit(.husky/**), Write(.husky/**), Edit(.claude/settings.json), Write(.claude/settings.json), Edit(.claude/hooks/**), Write(.claude/hooks/**), Edit(.claude/scripts/**), Write(.claude/scripts/**), Edit(.claude/settings.local.json), Write(.claude/settings.local.json), Edit(CLAUDE.md), Write(CLAUDE.md), Edit(**/CLAUDE.md), Write(**/CLAUDE.md), Edit(Claude.md), Write(Claude.md), Edit(**/Claude.md), Write(**/Claude.md), Edit(claude.md), Write(claude.md), Edit(**/claude.md), Write(**/claude.md), Edit(package.json), Write(package.json), Edit(pnpm-lock.yaml), Write(pnpm-lock.yaml), Edit(node_modules/**), Write(node_modules/**), Edit(.git/**), Write(.git/**)
+```
+
+Plus, per launch: the same `worker-edit.ts` wrapper rule and the task's own `Test command:` rule.
+`--strict-mcp-config` also runs on this lane, so no MCP server tool loads at all — the
+`mcp__*` deny rules above are defence in depth, not the active barrier.
+
+The `.claude/**` allowances this file's `allow` list carries (`.claude/hooks/**`,
+`.claude/scripts/**`, both settings files, `CLAUDE.md` in every casing) never actually take effect:
+`--permission-mode dontAsk` denies any Edit/Write on a `.claude`-segment path outright, on either
+lane, whatever a rule grants. They exist only so a reviewer of this file sees the intent stated,
+not silently relied on.
+
+`db:generate`/`db:check`/`db:query` are all OFFLINE — they diff a workspace's `*.schema.ts` files
+against its last `snapshot.json`; none of them ever reaches a real database (`catalyst-schema-migrations`).
+
+## Task description conventions
+
+**`Test command:`** — mandatory on both lanes, validated by `guards.ts`'s `resolveTestCommand` and
+spawned directly, never through a shell:
+
+```
+pnpm [--filter <pkg> | --dir <relative-path>] [run] <test | cli:test | test:*> [args…]
+```
+
+`pnpm` is the only allowed binary; the script itself must match `test`, `cli:test` or
+`test:<word>`; a `--filter` value must be a plain package name (never another flag); `--dir` is the
+alternative selector for `packages/cli` (not a workspace member), and its value must be a relative
+path with no `..` segment; the line may carry no shell metacharacter (`; & | \` $() <> {} \`).
+
+**`Files to touch:`** — mandatory on `lane:local` (guard 1 blocks its absence), optional on
+`lane:frontier`. Entries are repo-relative paths read three ways: an exact file; a directory
+(trailing `/`), covering everything under it; and a declared source file's sibling `.spec.ts`/
+`.test.ts`, covered without being named. It is the allowlist the close's local-lane scope check runs
+the real diff against, and the list guard 4 (security paths) inspects before a task is ever
+dispatched to `lane:local`.
+
+**A subtask's base branch is always `task/<parentId>`** — a pure deduction from the parent's id,
+never something a parent declares. The parent's `task/<parentId>` branch must exist on the remote
+before the subtask is queued (guard 4b blocks it otherwise, naming the branch it tried and any
+remote candidate that mentions the parent's id).
+
+## Forbidden paths, split by mechanism
+
+The close's scope check (`checkScope`) and the pre-launch guards read lists split by whether
+something EXECUTES or READS the path inside the slot, during the attempt or the close — a separate,
+harness-level mechanism handles `.claude/` paths on its own.
+
+**Contents are read from the constant, not copied here** (design.md decision 4d of
+`add-backlog-dependency-graph-and-execution-mode`) — a copy would go stale the next time a list
+changes, and it is exactly the reader deciding what to declare in `Files to touch:` that a stale
+copy would mislead:
+
+| List | Kind | Contents | Effect |
+| --- | --- | --- | --- |
+| `SLOT_EXECUTED_PATHS` | hard | see `guards.ts` — the harness's own settings and local overlay, its hook and script directories, the version-control hooks the close's own commit runs, the package manifest/lockfile/dependency tree, the board directory, and the two script directories the close spawns from inside the slot | refused on both lanes, declared or not; guard 1c blocks a DECLARATION (file or containing directory) before a slot is taken |
+| `SLOT_EXECUTED_BASENAMES` | hard, by basename (any depth, case-insensitive) | see `guards.ts` — the one instruction file every later reader treats as law | same as above |
+| `CLAUDE_DIR_SEGMENTS` | hard, harness-level | see `guards.ts` — any path with a `.claude` path component | guard 1d blocks the declaration; `--permission-mode dontAsk` denies the write outright regardless — there is no real diff for `checkScope` to ever check this against |
+| `HUMAN_REVIEW_PATHS` | soft | see `guards.ts` — the generator package alone | admitted; the close marks the PR `harness-review` (plus the configured reviewer) instead of failing. On `lane:local` the path must still be DECLARED in `Files to touch:` to pass. On `lane:frontier` it need not be declared |
+| `SUPERVISED_ONLY_PATHS` | hard, by POLICY | see `guards.ts` — the framework packages both applications compile against, and the dispatcher's own sources | refused on both lanes, declared or not; guard 1e blocks a DECLARATION before a slot is taken. Refused for a cause no other list shares: nothing in the slot executes these files and the harness does not deny the write — the DECISION is architectural. A framework change reaches every consumer at once and no test inside the changed package shows it; a dispatcher change alters the machinery every LATER task is judged by and ships to every scaffolded application, where no solution task has any business touching it. By the time such a change is a marked pull request its shape is settled, so the soft list is the wrong instrument. Measured on T-94 (2026-09-16): a framework change was written, the consumer could not compile it, and a whole frontier slot ended in `needs-guidance`. That work goes in an interactive session |
+| `LOCAL_FORBIDDEN_PATHS` | hard, local-lane only | see `guards.ts` — `SLOT_EXECUTED_PATHS` plus the local lane's own extras | refused only on the local lane's close-time scope check |
+| mirror output | hard | see `MIRROR_OUTPUT_PREFIXES` in `close.ts` — the dispatcher-owned regeneration output | refused on both lanes regardless of the split; checked FIRST, before either list |
+
+**The frontier lane does not require a soft-list path to be declared** — its `checkScope` branch
+never consults `declaredFiles`, so an undeclared soft-list edit is admitted the same as a declared
+one, and the `harness-review` mark is the mitigation this relies on.
+
+**Soft does not mean inert.** A soft-list file can be executed inside the slot during the close (the
+task's own `Test command:` may run the generator package's own test suite), and a soft-list edit
+survives a failed attempt — the failure path pushes the whole slot tree to `task/<id>`, and the
+retry's `checkout -B` restores it.
+
+A pull request marked for human review carries the section on the body (unfailable, part of
+`gh pr create`), the `harness-review` label, and the configured reviewer handle — the last two are
+separate best-effort `gh pr edit` calls that never fail the close. A FAILED close opens no pull
+request at all, so on that path the `Blocked` comment names the soft-list files and any refused path
+the attempt left behind instead.
+
+## The close: what actually gates a PR
+
+`close.ts`'s `planClose` runs these steps in order, on the success path:
+
+1. **`board-check`** (`checkBoardIntegrity`) — the task must still read `In Progress`, with its
+   title, acceptance criteria, DoD texts, `Files to touch:` and `Test command:` unchanged from the
+   snapshot taken at launch. Everything after this trusts the board.
+2. **`scope-check`** — the mirror-output prefix first (refused regardless of the two lists below),
+   then the hard list (`SLOT_EXECUTED_PATHS`/`SLOT_EXECUTED_BASENAMES`, plus `LOCAL_FORBIDDEN_PATHS`
+   on the local lane and the security paths there too), then the soft list — admitted and recorded as
+   `humanReviewFiles`, never a violation — over the attempt's real changed files
+   (`git diff --name-only -z` ∪ `git status --porcelain -z --untracked-files=all`).
+3. **`format-lint-test`** — Prettier `--write` then `--check` per workspace that ships it, barrels
+   lint, then the task's own declared `Test command:`, all scoped to the attempt's changed files.
+4. **`mirror-regen`** — runs `node scripts/packager/publish.mjs`, but only when the attempt touched a
+   root the packager reads (read from the slot's own drift-check workflow `paths:` filter). AFTER the
+   triad (so it copies formatted sources) and AFTER the scope check (so the mirror stays forbidden TO
+   THE WORKER). A repo with no drift-check workflow skips this step entirely.
+5. **`reviewer`** — local lane only. Isolated read-only `claude`, dual verdict, fails closed.
+6. **`ac-check`** (`evaluateAcceptanceGate`) — every acceptance criterion must be checked; every
+   OTHER Definition-of-Done item not owned by a prior step (the four project defaults are ticked by
+   the step that proves them: the triad ticks "scoped tests pass" and "Prettier and barrels lint
+   pass", this step ticks "every AC is checked", `open-pr` ticks "PR opened").
+7. **`open-pr`** — asks `gh pr view <branch>` first and reuses an `OPEN` PR on that branch (a retry);
+   otherwise creates one. Applies the human-review mark when step 2 recorded soft-list files.
+8. **`release-slot`**, **`recompute-parent`**, **`drain`** (may re-arm one more pass).
+
+**On any failure**, the plan diverts to `save-work` (commit + push the whole slot tree to
+`task/<id>`, `--no-verify`) and then `block` (or `block-keep-slot` when the push itself failed). A
+slot whose push failed is flagged `heldForRecovery`: no acquisition picks it, and the maintenance
+pass retries the push for up to 3 attempts before stopping and asking a person to run
+`pnpm backlog:dispatch -- --release-slot <name>`. The `Blocked` comment names the cause, any
+soft-list files the attempt touched, and any refused path it left behind.
+
+The attempt cap is `lanes.json`'s `attempts` (3); a task `Blocked` on its last attempt has no
+automatic path back and needs a human decision.
+
+### The «Registro de ejecución» block (T-68)
+
+`close.ts`'s `planClose`/`executeClose` never set `Done` — `maintenance.ts` is the ONLY module that
+does, and it does it from TWO places: step 3 (a leaf task, merged PR -> `Done`) and `recomputeParent`
+(a parent whose children are all `Done` and whose own PR merged — §12 says "every task", a parent
+included, and `recomputeParent` is what the close's own `recompute-parent` step calls too, so a
+subtask's close reaches this same path). Both write the block through the SAME
+`writeExecutionRecordOnce` helper, and both write it BEFORE the `setStatus(..., DONE, ...)` call that
+follows it — a successful block is on the board before the transition is — but **the write can never
+block the transition**. `writeExecutionRecordOnce` never throws: a failure
+(`readNotes`/`attemptStreamOutcome`/`attemptReviewVerdict`/`appendNotes` all reach the `backlog` CLI
+or the filesystem, and `appendNotes` already retries through `withBoardWriteRetry` — 6 tries with
+backoff — before it can throw here at all) is logged, and then reported with EXACTLY ONE board
+comment through the same `comment` port every other cause already uses, naming the gap and pointing
+at the skill's own manual template (§12) — sanitized through `sanitizeCommentBody` so a long error
+cannot blow the comment up. If `comment` itself throws, that is caught and logged too. Either way the
+caller proceeds to `setStatus(..., DONE, ...)` and everything after it (branch cleanup included)
+exactly as it would on a clean write.
+
+Skipping the transition to retry on a later pass is not an option: a task withheld from `Done`
+keeps its attempt directory (so the orphan sweep ignores it), never reaches `cleanupBranchOnDone`,
+and no later pass revisits it — a silent, permanent stall. A confirmed merge is never held hostage to
+bookkeeping: the block is best-effort, the transition is not.
+
+The eight fields (`.claude/skills/catalyst-backlog/SKILL.md` §12 has the full contract) are composed
+by `close.ts`'s `buildExecutionRecordBlock` — a PURE function `close.test.ts` asserts directly, given
+the raw facts `maintenance.ts` gathers: the task's own `attempts` count, each attempt's classified
+stream outcome (`render.ts`'s `classifyStreamOutcome`, read back from `stream.jsonl` via
+`MaintenanceFs.attemptStreamOutcome`), each attempt's `review.md` verdict (`reviewer.ts`'s
+`parseReviewerVerdict`, read back via `MaintenanceFs.attemptReviewVerdict` — reused, never
+reimplemented), and the task's current notes, scoped to the notes SECTION alone
+(`task-view.ts`'s `notesRegion`, via `MaintenanceBacklog.readNotes`) — a description, an AC or a
+comment can legitimately contain text that reads like the heading, and only the notes section is
+this task's own write surface. The `## Registro de ejecución` heading, matched as a WHOLE LINE inside
+that scoped text (`close.ts`'s `hasExecutionRecordBlock`), is the §12.3 sentinel that stops a second
+pass from duplicating the block, rather than a separate marker file.
+
+Three fields lean on that data rather than a guess:
+
+- **"Resultado del intento 1"** carries the FIRST attempt's own cause when the stream classifier
+  found one (`Blocked (needs-guidance)`, `Blocked (budget)`, …), falling back to the template's
+  cause-free `reintento` when only the retry COUNT is known (a later, close-level failure — a scope
+  violation, a failed mechanical check — never touches the stream).
+- **"Rondas de corrección"** / its **"revisor"** come from MEASURED `review.md` verdicts ONLY —
+  never from the retry count (a quota cutoff or a crash retries with no review at all: that is not a
+  correction round) and never from the lane label (the frontier lane's close never runs a reviewer
+  the dispatcher can see, so a lane-based guess would fabricate a `code-review` that never happened).
+  The round count is how many attempts' `review.md` verdict reads FAIL; `revisor: code-review` once
+  at least one `review.md` exists at all; **both halves read `desconocido`** when no attempt has one
+  — the ordinary case for every frontier-lane task, whose own worker runs whatever gates it runs,
+  invisible to the dispatcher.
+- **"Fallos de entorno"** can positively detect only a budget cutoff (`STREAM_OUTCOME.BUDGET`) and
+  reads `desconocido` otherwise — an LM Studio or network failure is real but untraceable after the
+  fact, since `entry.ts`'s `onLocalModelMissing` writes only a `Blocked` COMMENT, routinely
+  overwritten by the next transition, never a file under `.backlog/.dispatch/`.
+
+"Intervenciones humanas" is deliberately its OWN count (`attempts - 1`, never shared with "Rondas de
+corrección"): every retry passes through a human-released `Blocked` (§10), which is measured and
+certain, independent of whether that retry's attempt ever produced a `review.md`. "Tiempo de ciclo" is
+`desconocido` unconditionally — no status-transition timestamp survives anywhere today (§12.2 rule 4).
+
+**`attempts === 0` means the dispatcher never launched this task at all.** The root `CLAUDE.md`'s
+Worktree Gate forces EVERY task onto a `task/T-nn` branch, a supervisada (interactive) session
+included, so step 3/`recomputeParent` close such a task the moment its `task/T-nn` PR merges — the
+exact same path a headless task takes. That absence of any attempt IS a measurement, so the block
+records `Modo: supervisada — desconocido` (the motivo of an interactive session is recorded nowhere
+the dispatcher can read), `Intervenciones humanas: desconocido — tipo: desconocido` (the dispatcher
+has no visibility into a supervisada session's own human steps — a measured `ninguna` would be a
+number nobody actually counted), and `Fuente` points at the merged PR instead of an attempt
+directory that never existed: `PR #<n>` when `MaintenanceGh.prNumber` reads its number, `desconocido`
+when the PR is confirmed to exist (both real call sites only ever reach this with a CONFIRMED merged
+PR) but its number could not be read, `sin evidencia` only for the pure composer's own generic
+"neither an attempt nor a PR" case. If a person already appended their own block to a supervisada
+task's notes by hand, the §12.3 sentinel applies exactly as it does to any other task: the reconciler
+never touches it.
+
+### Releasing a `Blocked` task
+
+1. Read the comment — it always carries the cause and the open question.
+2. Answer it (a comment, or an edit to the task body/AC while the task sits `Blocked` — the one
+   state where the description is still open).
+3. Move it: to `Queued` to retry on the SAME `task/T-nn` branch, with the prior comment and any
+   reviewer findings carried into the retry's prompt; or to `To Do` for a human to work in session.
+
+Starting over instead of retrying means deleting the remote `task/T-nn` branch first, or the next
+dispatch reuses it.
+
+## `worker-edit.ts`: the worker's only board channel
+
+A permission rule matches a PREFIX and cannot narrow what follows it, so any per-flag `Bash(backlog
+task edit T-nn --notes:*)`-style grant also admits `--notes x --status Done` on the same command
+line. `worker-edit.ts` closes that gap by reading the WHOLE argv itself: exactly the dispatched task
+id (from `BACKLOG_TASK_ID` in the worker's env, never from the command line), then one or more of
+`--check-ac`, `--notes`, `--append-notes`, `--plan` — each at most once, each with a value that is
+not itself a flag — or `--view` alone (forwarding to `backlog task view <id> --plain`). Anything else
+exits `2` and writes nothing. Its second mode, `--subtask` (mutually exclusive with the above), is
+the headless way a Complex task's SDD design phase creates the subtasks a split produces — see
+`.claude/skills/catalyst-backlog/SKILL.md` §6 for its validation rules. The wrapper is granted by
+naming the MAIN CHECKOUT's copy of the script, never the slot's, so the barrier itself is never
+inside the tree under test.
+
+## Trigger wiring
+
+`.backlog/config.yml`'s `onStatusChange`:
+
+```yaml
+onStatusChange: 'mkdir -p .backlog/.dispatch; nohup npx --loglevel=error tsx scripts/backlog/dispatch.ts >> ".backlog/.dispatch/$TASK_ID.log" 2>&1 < /dev/null &'
+```
+
+Backlog.md runs this callback synchronously and holds the task lock until it returns, so the
+`nohup ... &` detachment is required — without it, moving a task to `Queued` would freeze whoever
+moved it for the whole dispatched run. `onStatusChange` never fires on task creation or on a merge;
+the `launchd` timer and the maintenance pass's `gh` poll cover both gaps. Every trigger runs through
+the identical idempotent pass, so a missed or duplicated event self-heals on the next one.
+
+**Anti-loop:** every `backlog task edit` the reconciler runs against itself carries
+`BACKLOG_DISPATCH_ACTIVE='1'` in its env; `entry.ts`'s `main()` checks this BEFORE resolving
+`BACKLOG_CWD` or running any maintenance, and exits 0 with one log line rather than starting a nested
+pass. A callback with no sentinel (a human moving a task) is unaffected.
+
+## Installing the `launchd` recovery timer
+
+1. Copy `scripts/backlog/dev.aurora.backlog-dispatch.plist` to
+   `~/Library/LaunchAgents/dev.aurora.backlog-dispatch.plist`, replacing the three absolute paths
+   inside it (your `which npx`, your main checkout as `WorkingDirectory`, and
+   `<main checkout>/.backlog/.dispatch/launchd.log` for both `StandardOutPath`/`StandardErrorPath`).
+   The command itself detaches the reconciler into `reconciler.log` and exits — launchd tracks the
+   pid of what it starts, and the reconciler lives as long as its worker, so running it directly
+   would silence the timer for the whole length of every dispatch.
+2. The one manual prerequisite: `gh auth login` on the machine that runs the dispatcher — its own
+   `gh` calls run with `GITHUB_TOKEN`/`GH_TOKEN` stripped, so the keyring login is the only
+   credential they get.
+3. Load: `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.aurora.backlog-dispatch.plist`.
+   Remove: `launchctl bootout gui/$(id -u)/dev.aurora.backlog-dispatch`, then delete the plist.
+
+Validate any edit with `plutil -lint dev.aurora.backlog-dispatch.plist` first.
+
+## Operator commands
+
+| Script | Command | Use |
+| --- | --- | --- |
+| `backlog:dispatch` | `tsx scripts/backlog/dispatch.ts` | Run one reconciler pass manually |
+| `backlog:dispatch -- --release-slot <name> [--force]` | same script, one flag | Detach a slot, drop its lock and clear a push-recovery hold. Takes the single-flight lock and refuses (exit 2) a running pass, or a slot with a live worker unless `--force` |
+| `backlog:watch` | `tsx scripts/backlog/watch.ts` | Tail a running attempt's log, or list busy slots |
+| `backlog:graph` | `tsx scripts/backlog/graph-cli.ts` | Print the current dependency view (see "The dependency view" above). No board write. Exits non-zero on an unrecognized argument or a partial board read |
+| `backlog:graph --write` | same script, one flag | Also refresh the graph-holder task immediately, instead of waiting for the next maintenance pass. Exits non-zero instead of writing on an unrecognized argument, a partial board read, more than one holder, or a failed read/write |
+| `test:backlog` | `node --import tsx --test "scripts/backlog/**/*.test.ts"` | Run every dispatcher unit/contract test |
+
+```bash
+pnpm backlog:watch T-12   # tails the human-rendered run.log of T-12's current attempt
+pnpm backlog:watch         # no id: lists busy slots (name, lane, taskId, pid) from slots.json
+```
+
+Reading a finished attempt directly: `run.log` (the whole rendered session), `test.log` (the
+mechanical checks' transcript), `review.md` (the local-lane reviewer's findings, read back by a
+retry's prompt).
+
+## Known gotchas
+
+- **A board read that half-failed is not an empty board.** `loadBoard` returns
+  `{ tasks, complete }`; with `complete: false` the sweep skips absence-based cancellation (an
+  explicit `Blocked`/`To Do` still cancels) and skips parent derivation entirely.
+- **A slot is the only place a close may touch** — `slotPathForTask` returning `null` fails the
+  step; it never falls back to the main checkout.
+- **`--max-budget-usd` stops at turn boundaries**, comparing an unbilled estimate on a subscription
+  login; `maxTurns`/`timeoutMinutes` are the guards that always apply.
+- **`Write(<glob>)` path-scoped permission rules are unverified** (`Edit(<glob>)` is confirmed to
+  scope correctly); the close's scope check is the barrier that does not depend on it.
+- **`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` is undocumented** — absent from the public env-vars
+  reference — so its behaviour is measured, not guaranteed: Bash's `run_in_background` and a
+  backgrounded Agent both run synchronously under it (measured 2026-09-15, Claude Code 2.1.272). If
+  a future Claude Code version changes this, a worker's `task_started` system event would carry
+  `is_backgrounded: true` again, or a `task_updated` event's `patch.status` would read `"killed"`
+  right after a Bash/Agent call — either is the signal to re-measure.
+- **With background tasks disabled, every Bash call runs synchronously**, bounded by
+  `BASH_DEFAULT_TIMEOUT_MS` (2 minutes when the call passes no `timeout`) and
+  `BASH_MAX_TIMEOUT_MS` (a 10-minute ceiling).
+
+## Accepted risks
+
+Measured, weighed, and deliberately left as is — not oversights, and not to be re-proposed without
+new evidence.
+
+- The declared `Test command:` names a repo script; the allowlist constrains the line's shape, not
+  what the script does. Accepted because the script lives in the repo and reaches the slot only
+  through a reviewed PR. (T-36)
+- The attempt directory doubles as the "was dispatched" signal for the orphan sweep, so a parent
+  enqueued and immediately guard-blocked becomes invisible to that sweep. (T-20 §1)
+- `sanitizeCommentBody` replaces `---` with `___` in PR bodies, a restriction inherited from
+  `backlog task edit --comment`. (T-20 §2)
+- `isParentCloseAttempt` keeps a default `isChildDone` that no production caller uses. (T-20 §3)
+- Guard 1c checks the shared hard list only; the three local-lane path extras are enforced at the
+  close, not in the queue. (T-35)
+- A worker that reports `needs-guidance` with no `questions:` block is closed as a block, not as a
+  completion: the close obeys the reported status, not the text. One occurrence in 39 dispatches;
+  it costs one attempt. (T-54 attempt 2)
+- A Complex parent whose children merged to `main` through their own PRs still gets its one
+  automated close attempt on its own stale branch. The frontier worker refuses it (measured on T-4:
+  102 s, $1.36, no PR opened). An automatic rule cannot tell that branch from one with real work
+  without a destructive false-Done path, so the parent is closed by hand after deleting its branch.
+- A Complex parent that declares a supervised-only path, or carries `mode:supervised`, loses its one
+  automated close attempt: it is enqueued, the marker is written, and guard 0 or 1e blocks it,
+  although the close brief writes no implementation. Accepted as policy: a person closes a harness
+  or supervised parent in a session; from `Blocked` a manual re-queue still runs the close brief.
+  The alternative, exempting the close attempt from the declared-path and mode guards, waits for
+  evidence that the manual path is tedious. (T-113)
+- `graph-cli.ts`'s `main()` — the binding of `runGraphCli` to the real board and CLI — has no test
+  of its own; everything it decides lives in `runGraphCli`, which is covered branch by branch. (T-113)
+- A task whose `Status:` line cannot be parsed reads as `Unknown`, which is not an open status, so
+  the dependency view omits it without marking the board read as partial; a task that waits for it
+  still names it. No such task has been seen on a board. (T-113)
+- The holder refresh REPLACES THE WHOLE DESCRIPTION of whatever task carries `board:graph`, without
+  reading it first: a real task labelled by mistake loses its description — `Test command:` and
+  `Files to touch:` included — the pass commits the loss, and a `Queued`/`In Progress` task then
+  fails its close's board-integrity check. Accepted: the label is the declaration, and the text is
+  recoverable from git history; writing only over an empty or generated description was considered
+  and not taken. (T-113)