@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/monorepo/scripts/backlog/maintenance.ts

@@ -3,10 +3,12 @@
  * before any task is selected for dispatch.
  *
  * Implements `specs/backlog-task-dispatcher/spec.md` — "Maintenance pass precedes task selection"
- * (dead-lock sweep, orphan-slot release, merged-PR-to-Done, recompute every parent, commit pending
- * `.backlog/**` changes) and "Manual cancellation kills the worker after saving work";
- * `specs/backlog-task-lifecycle/spec.md` — "Derived parent state" (reused verbatim from
- * `parent.ts`, never re-derived here).
+ * (dead-lock sweep, orphan-slot release, merged-PR-to-Done, recompute every parent, refresh the
+ * graph-holder task, commit pending `.backlog/**` changes) and "Manual cancellation kills the
+ * worker after saving work"; `specs/backlog-task-lifecycle/spec.md` — "Derived parent state"
+ * (reused verbatim from `parent.ts`, never re-derived here); `specs/backlog-dependency-graph/spec.md`
+ * — "Graph-holder task mirrors the view" (the write half; `graph.ts` owns the render/decide logic
+ * this step only calls).
  *
  * `runMaintenance(ctx)` is a single synchronous function; every side effect (reading/writing
  * `slots.json`, reading/removing lock files, PID liveness, the clock, `gh`, `backlog task edit`,
@@ -33,17 +35,34 @@
  * automated close attempt gets enqueued (`parent.ts`'s rules 4/5) — the write this step already
  * makes moves the parent straight to `Queued`, and the pass's own selection phase (later in this
  * SAME `runOnce`) may dispatch it before the next pass ever runs;
+ * (5b) refresh the graph-holder task (`backlog-dependency-graph` capability) — re-renders the
+ * dependency view over the board AS STEP 5 LEFT IT and replaces the holder's description only when
+ * the text differs, so the refresh rides in the SAME board commit (step 6) as whatever change
+ * caused it. Skipped when `boardComplete` is false (same reason as step 5: a view derived from part
+ * of the board would show a waiting task as ready) or when zero tasks carry `board:graph` (reported
+ * on `MaintenanceResult`, nothing written). When MORE than one task carries the label, each one
+ * that does not already show it gets an ambiguity notice instead of the view (also reported on
+ * `MaintenanceResult`) — one holder's write failing never costs the other its notice. A throw from
+ * reading or writing a description is caught and recorded on `MaintenanceResult` — this step can
+ * never fail the pass it rides along in;
  * (6) commit any pending `.backlog/**` changes with a Conventional Commit message and `--no-verify`
  * (design.md decision (l) — Backlog.md's own `auto_commit` stays `false`). `--no-verify` for the
  * same reason every other dispatcher-authored commit carries it: the hooks a commit would run are
  * files in a working tree a dispatched worker may have just written, and running them here would
  * execute that code as the dispatcher.
  */
+import {
+  buildExecutionRecordBlock,
+  hasExecutionRecordBlock,
+  sanitizeCommentBody,
+} from './close.js';
+import { decideGraphWrite } from './graph.js';
 import { taskBaseBranch } from './guards.js';
 import { deriveParentStatus, effectiveStatus, type ParentDerivationNode } from './parent.js';
 import { isLockAlive, releaseSlotEntries } from './slots.js';
 import {
   TASK_STATUS,
+  type Board,
   type DispatchLock,
   type SlotInfo,
   type SlotRegistry,
@@ -100,6 +119,23 @@ export interface MaintenanceFs {
   hasCloseAttemptBeenEnqueued(taskId: string): boolean;
   /** Marks it. See `hasCloseAttemptBeenEnqueued`'s own JSDoc. */
   markCloseAttemptEnqueued(taskId: string): void;
+  /**
+   * The classified terminal outcome of one attempt's `stream.jsonl` (`render.ts`'s
+   * `classifyStreamOutcome`) — T-68's ONE structurally-detectable environment failure (a budget
+   * cutoff, `STREAM_OUTCOME.BUDGET`, feeds the «Registro de ejecución» block's "Fallos de entorno").
+   * `null` when the attempt directory or its stream file does not exist — never thrown, since a
+   * missing attempt is a legitimate "no data" answer for the close-record composer, not a fault.
+   */
+  attemptStreamOutcome(taskId: string, attempt: number): string | null;
+  /**
+   * One attempt's `review.md` verdict (`reviewer.ts`'s `parseReviewerVerdict`, reused rather than
+   * reimplemented) — feeds the «Registro de ejecución» block's "Rondas de corrección"/"revisor"
+   * (T-68 fix 2: a retry count alone cannot tell a correction round from a quota-cutoff retry, and
+   * the lane label cannot tell "the reviewer ran and passed" from "this lane has no reviewer at
+   * all"). `null` when the attempt has no `review.md` — never thrown: only the local lane's close
+   * ever writes one, so `null` is the ordinary answer for every frontier-lane attempt.
+   */
+  attemptReviewVerdict(taskId: string, attempt: number): string | null;
 }
 
 export interface MaintenanceGh {
@@ -144,10 +180,31 @@ export interface MaintenanceGh {
    * leaving a stale `Done` to be re-checked on the NEXT pass rather than reverting on a question
    * `gh` could not actually answer.
    *
-   * OPTIONAL for the same reason `prState` is: an unwired caller must default to `unknown` (never
-   * to a guessed `merged`/`not-merged`) — see step 3b's own use of it.
+   * REQUIRED, unlike `prState` — T-20 point 4 (2026-09-11): this answer also gates two pushers
+   * (the recovery retry and the dead-worker rescue) that must never land a commit on an
+   * already-merged branch. A caller free to omit the collaborator entirely made "cannot confirm"
+   * indistinguishable from "confirmed not merged" at those two sites — a missing CAPABILITY
+   * silently switching a safety gate off, not a legitimate `unknown` answer. Making it required
+   * moves that failure to the type checker: a `MaintenanceGh` built with no `mergedState` no longer
+   * compiles, so there is no runtime branch left to fail open. A collaborator that genuinely cannot
+   * answer (the `gh` outage this whole tri-state exists for) still returns `PR_MERGE_STATE.UNKNOWN`
+   * itself — that is the legitimate use of the third state, not an excuse to omit the function.
+   */
+  mergedState(branch: string): PrMergeState;
+  /**
+   * The branch's PR number, or `null` when `gh` reports no PR at all (or is unavailable/
+   * unauthenticated — the same fail-closed reading `prState`/`isPrMerged` give). T-68's «Registro de
+   * ejecución» block reads this for a task with `attempts === 0` (never dispatched — a supervisada
+   * session closed by step 3/`recomputeParent`, whose Worktree Gate forces it onto the same
+   * `task/T-nn` branch): with no attempt directory to point `Fuente` at, the merged PR is the only
+   * trace left.
+   *
+   * OPTIONAL, same as `prState` — until `dispatch.ts`'s real `gh` collaborator wires it, an unwired
+   * caller here reads exactly like a failed read (see the call site's own handling): the PR is
+   * confirmed to exist (both call sites only ever reach this with a CONFIRMED merged PR), only its
+   * number could not be obtained.
    */
-  mergedState?(branch: string): PrMergeState;
+  prNumber?(branch: string): number | null;
 }
 
 /**
@@ -189,6 +246,35 @@ export interface MaintenanceBacklog {
   setStatus(taskId: string, status: TaskStatus, comment?: string): void;
   /** Records a comment WITHOUT moving the task — for news a person needs but that decides nothing. */
   comment(taskId: string, comment: string): void;
+  /**
+   * Appends to the task's notes (`backlog task edit --append-notes`) — the one field the `Queued`
+   * scope freeze (`catalyst-backlog/SKILL.md` §11) leaves open on a `Queued`/`In Progress`/`Done`
+   * task. T-68's only writer: the «Registro de ejecución» block (§12), appended once at the `Done`
+   * transition step 3 makes.
+   */
+  appendNotes(taskId: string, notes: string): void;
+  /**
+   * The task's current notes text, or `null` when it could not be read. T-68's ONLY reader: §12.3's
+   * idempotence check, which only needs to know whether `close.ts`'s `EXECUTION_RECORD_HEADING`
+   * occurs anywhere in it — the full `backlog task view --plain` output is fine to pass through
+   * as-is. `null` reads as "not yet written": a pass that cannot confirm the block is already there
+   * appends it rather than silently skipping, so the heading itself stays the durable guard, never
+   * this read.
+   */
+  readNotes(taskId: string): string | null;
+  /**
+   * Replaces a task's description outright (`backlog task edit --desc`) — the graph-holder
+   * refresh's (step 5b) only writer. `graph.ts`'s `pnpm backlog:graph --write` uses the same
+   * `decideGraphWrite` decision this step calls, so both paths write through one function.
+   */
+  setDescription(taskId: string, description: string): void;
+  /**
+   * The task's current description text (`task-view.ts`'s `parseDescription`, over a fresh
+   * `backlog task view --plain`) — step 5b's reader, called for the single holder task it found, or
+   * once per holder when more than one carries the label (never for zero holders, which need no
+   * comparison at all). `null` when it could not be read.
+   */
+  readDescription(taskId: string): string | null;
 }
 
 export interface SaveWipResult {
@@ -198,7 +284,12 @@ export interface SaveWipResult {
 export interface MaintenanceGit {
   /** `git status --porcelain -- .backlog` in the main checkout, collapsed to a boolean. */
   hasPendingBacklogChanges(): boolean;
-  /** `git add .backlog && git commit -m <message>` in the main checkout. */
+  /**
+   * `git add` of only the `.backlog` paths that belong to Backlog.md's own managed schema
+   * (tasks/milestones/archive/completed/config.yml, or an ID-prefixed `docs/` entry), then `git
+   * commit` — a dirty path outside that schema is excluded and logged (T-78), never silently
+   * swallowed nor blindly included alongside the board's own output.
+   */
   commitBacklogChanges(message: string): void;
   /** WIP-commits and pushes the worker's current changes on `branch` (manual-cancellation save). */
   saveWipAndPush(branch: string): SaveWipResult;
@@ -375,6 +466,26 @@ export interface MaintenanceResult {
    * `isBranchConfirmedMerged`'s own JSDoc for why `unknown` never lands a task here.
    */
   pushRefusedMergedBranches: string[];
+  /**
+   * The graph-holder task (step 5b) this pass WROTE a fresh dependency view to, or `null` when
+   * nothing needed writing: no holder on the board, the rendered view already matched the holder's
+   * description, the board read was incomplete, more than one task carries the label (see
+   * `graphHolderAmbiguous`), or the step itself threw (see `graphHolderRefreshError` to tell that
+   * last case apart from the rest).
+   */
+  graphHolderRefreshed: string | null;
+  /**
+   * Step 5b: ids of every task carrying `board:graph` when more than one did. Each one that does
+   * not already show the ambiguity notice gets it written — see `graph.ts`'s
+   * `ambiguousHolderNotice` — so this is populated even though `graphHolderRefreshed` stays `null`.
+   */
+  graphHolderAmbiguous: string[];
+  /**
+   * Set when step 5b's read or write collaborator threw. The pass still closes merged tasks,
+   * recomputes parents, commits pending board changes and selects a task regardless — a
+   * dependency-view refresh is never allowed to block the pass it rides along in.
+   */
+  graphHolderRefreshError: string | null;
   /**
    * The registry AFTER every release this pass performed. The caller must use THIS for slot
    * acquisition: reading `slots.json` again before maintenance ran (or using the snapshot it was
@@ -442,20 +553,38 @@ export interface RecomputeParentInput {
    * SAME `false` (see `MaintenanceGh.mergedState`'s own JSDoc for the identical trap step 3b was
    * built to avoid), and when every child is Done, THIS parent's own merge state is the one thing
    * standing between `Done` and a derived `In Progress`/`Queued` that differs from the board and
-   * therefore gets WRITTEN. `mergedState` is optional for the same reason it is everywhere else in
-   * this module: an unwired caller must default to `unknown`, never to a guessed answer.
+   * therefore gets WRITTEN. `mergedState` is REQUIRED on `MaintenanceGh` (T-20 point 4): a caller
+   * with no way to answer it no longer type-checks, so the only `unknown` this function can ever
+   * see is a WIRED collaborator's honest answer to a real `gh` outage, never an omitted function.
+   */
+  /** `prNumber` (optional, like on `MaintenanceGh` itself) is T-68's addition — see `backlog`'s own JSDoc just below for why. */
+  gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState' | 'prNumber'>;
+  /**
+   * `setStatus` moves the parent; `appendNotes`/`readNotes` are T-68's addition — a parent that
+   * reaches `Done` THROUGH this derivation (every child Done, own PR merged) carries the «Registro
+   * de ejecución» block exactly like a leaf task does (§12: "every task"), and this is the only
+   * place that transition is written, so it is the only place that can write it. `comment` is what
+   * a FAILED write falls back to (`writeExecutionRecordOnce` never blocks the transition) — the
+   * same port every other Blocked cause already posts through.
    */
-  gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState'>;
-  /** Only `setStatus` is used: a derivation either moves the parent or does nothing at all. */
-  backlog: Pick<MaintenanceBacklog, 'setStatus'>;
+  backlog: Pick<MaintenanceBacklog, 'setStatus' | 'appendNotes' | 'readNotes' | 'comment'>;
   /**
    * The durable "has rule 4 already fired for this parent, ever" signal (T-8 defect 3) — see
-   * `MaintenanceFs.hasCloseAttemptBeenEnqueued`'s own JSDoc. Required, not optional: unlike
-   * `prState`/`branchExists`/`mergedState` elsewhere in this module, there is no safe "unwired"
-   * default here — defaulting to `false` would silently resurrect the bug this signal exists to
-   * close (every caller re-deriving `Queued` forever for a parent that already ran once).
+   * `MaintenanceFs.hasCloseAttemptBeenEnqueued`'s own JSDoc. Required for the same reason
+   * `mergedState` now is: there is no safe "unwired" default here — defaulting to `false` would
+   * silently resurrect the bug this signal exists to close (every caller re-deriving `Queued`
+   * forever for a parent that already ran once).
+   *
+   * `attemptStreamOutcome`/`attemptReviewVerdict` are T-68 fix 3's addition, read only when this
+   * derivation is about to write `Done` — see `backlog`'s own JSDoc just above.
    */
-  fs: Pick<MaintenanceFs, 'hasCloseAttemptBeenEnqueued' | 'markCloseAttemptEnqueued'>;
+  fs: Pick<
+    MaintenanceFs,
+    | 'hasCloseAttemptBeenEnqueued'
+    | 'markCloseAttemptEnqueued'
+    | 'attemptStreamOutcome'
+    | 'attemptReviewVerdict'
+  >;
 }
 
 /**
@@ -491,7 +620,7 @@ export function recomputeParent(input: RecomputeParentInput): RecomputedParent |
     children.length > 0 && children.every((child) => effectiveStatus(child) === TASK_STATUS.DONE);
   let ownPrMerged = node.ownPrMerged ?? false;
   if (allChildrenDone) {
-    const mergeState = input.gh.mergedState?.(branchFor(input.parentId)) ?? PR_MERGE_STATE.UNKNOWN;
+    const mergeState = input.gh.mergedState(branchFor(input.parentId));
     if (mergeState === PR_MERGE_STATE.UNKNOWN) {
       return null; // gh outage: cannot tell "merged" from "not yet" — say nothing this pass.
     }
@@ -523,6 +652,17 @@ export function recomputeParent(input: RecomputeParentInput): RecomputedParent |
     return null;
   }
 
+  // T-68: a parent that reaches `Done` through THIS derivation gets the same «Registro de
+  // ejecución» block a leaf task gets from step 3 — before the transition, same as there. Also same
+  // as there: a failed write never blocks it (`writeExecutionRecordOnce`'s own JSDoc) — a parent
+  // withheld from `Done` here would re-derive the SAME "all children Done, PR merged" state every
+  // later pass with no way to fix it (this function's own no-op-on-no-change guard just above means
+  // a genuine retry never even reaches this line again), so the write is best-effort and the
+  // transition proceeds regardless.
+  if (newStatus === TASK_STATUS.DONE) {
+    writeExecutionRecordOnce(input, parentTask);
+  }
+
   input.backlog.setStatus(input.parentId, newStatus);
   return { id: input.parentId, from: parentTask.status, to: newStatus };
 }
@@ -554,10 +694,13 @@ function deadWorkerComment(lock: DispatchLock, workSaved: boolean): string {
  * purpose for a maybe; the worst case of pushing under genuine uncertainty is a few commits that
  * land on an already-merged branch and go unused (recoverable — they still exist, on the remote),
  * while the worst case of refusing is the ONLY copy of the work never reaching the remote at all.
- * Only a CONFIRMED `merged` answer blocks the push.
+ * Only a CONFIRMED `merged` answer blocks the push. `mergedState` is REQUIRED on `MaintenanceGh`
+ * (T-20 point 4, 2026-09-11): a caller with no way to answer this question no longer type-checks,
+ * so the only `unknown` this function can ever see is a WIRED collaborator's honest answer to a
+ * real outage — never an omitted function silently read as "not merged".
  */
 function isBranchConfirmedMerged(gh: Pick<MaintenanceGh, 'mergedState'>, branch: string): boolean {
-  return (gh.mergedState?.(branch) ?? PR_MERGE_STATE.UNKNOWN) === PR_MERGE_STATE.MERGED;
+  return gh.mergedState(branch) === PR_MERGE_STATE.MERGED;
 }
 
 /**
@@ -723,6 +866,99 @@ export function buildBoardCommitMessage(transitions: readonly string[]): string
   ].join('\n');
 }
 
+/** The narrow slice `writeExecutionRecordOnce` needs — satisfied by a full `MaintenanceContext`, and by `RecomputeParentInput`'s own narrowed `backlog`/`fs`/`gh` once widened below. */
+interface ExecutionRecordDeps {
+  backlog: Pick<MaintenanceBacklog, 'appendNotes' | 'readNotes' | 'comment'>;
+  fs: Pick<MaintenanceFs, 'attemptStreamOutcome' | 'attemptReviewVerdict'>;
+  gh: Pick<MaintenanceGh, 'prNumber'>;
+}
+
+/**
+ * The `Blocked`-comment-style message a person reads on the task when the record itself could not
+ * be written — the ONE signal a failed write leaves on the board. Names the skill's
+ * own manual template (§12) so the person filling it in by hand does not have to go hunting for it.
+ */
+const executionRecordWriteFailureComment = (message: string): string =>
+  `No se pudo escribir el «Registro de ejecución» al pasar a Done: ${message}. Añádelo a mano con ` +
+  'la plantilla de la sección 12 de .claude/skills/catalyst-backlog/SKILL.md.';
+
+/**
+ * Writes the «Registro de ejecución» block (`close.ts`'s `buildExecutionRecordBlock`) once, BEFORE
+ * the caller's `setStatus(..., DONE, ...)` — so a SUCCESSFUL write lands on the board before the
+ * transition does. But this function NEVER throws, and a failed write never blocks the transition.
+ * Skipping the transition to retry later is a silent, permanent stall: `appendNotes` already retries
+ * through `withBoardWriteRetry` (6 tries, backoff), so a throw here is not transient, and a task kept
+ * out of `Done` keeps its attempt directory (the orphan sweep ignores it) and never reaches
+ * `cleanupBranchOnDone`. A confirmed merge is never held hostage to bookkeeping.
+ *
+ * On failure: logs, then posts EXACTLY ONE board comment through the same `comment`
+ * port every other Blocked cause already uses — sanitized through `close.ts`'s
+ * `sanitizeCommentBody` so a long error cannot blow the comment up — naming the gap and pointing at
+ * the skill's own manual template. If `comment` ITSELF throws, that is caught and logged too: this
+ * function's whole contract is "never throw", not "never fail".
+ *
+ * Reads the task's current notes first (§12.3's sentinel, enforced here via
+ * `hasExecutionRecordBlock` over `task-view.ts`'s `notesRegion`-scoped text) so a task an earlier
+ * pass already recorded — or this same task, were this ever called twice — is left untouched:
+ * idempotence lives in the heading itself, not in a second, parallel marker file. A task the write
+ * failed for is never revisited either, but for a DIFFERENT reason: it already left `In Progress`
+ * in the SAME pass (the caller proceeds to `setStatus` regardless), so step 3's own `status ===
+ * IN_PROGRESS` guard is what keeps the next pass from trying again — not anything in here.
+ */
+function writeExecutionRecordOnce(deps: ExecutionRecordDeps, task: Task): void {
+  try {
+    if (hasExecutionRecordBlock(deps.backlog.readNotes(task.id))) {
+      return;
+    }
+    const attemptOutcomes: Array<string | null> = [];
+    const reviewVerdicts: Array<string | null> = [];
+    for (let attempt = 1; attempt <= task.attempts; attempt += 1) {
+      attemptOutcomes.push(deps.fs.attemptStreamOutcome(task.id, attempt));
+      reviewVerdicts.push(deps.fs.attemptReviewVerdict(task.id, attempt));
+    }
+    const sourcePath =
+      task.attempts > 0 ? `.backlog/.dispatch/${task.id}/intento-${task.attempts}` : null;
+    // Only asked when `attempts === 0` (never dispatched — a supervisada task closed by the SAME
+    // merged-PR path a headless one is) — an ordinary dispatched close has no use for it, so this
+    // skips the extra `gh` round-trip entirely for the common case. Both real call sites (step 3,
+    // `recomputeParent`) only ever reach this with a CONFIRMED merged PR, so a non-number answer
+    // here means "exists, but its number could not be read" — `'read-failed'`, never `null`
+    // (`close.ts`'s own `sourceLine` reads that as `desconocido`, not `sin evidencia`).
+    let prNumber: number | 'read-failed' | undefined;
+    if (task.attempts === 0) {
+      const prNumberResult = deps.gh.prNumber?.(branchFor(task.id)) ?? null;
+      prNumber = typeof prNumberResult === 'number' ? prNumberResult : 'read-failed';
+    }
+    deps.backlog.appendNotes(
+      task.id,
+      buildExecutionRecordBlock({
+        lane: task.lane,
+        attempts: task.attempts,
+        attemptOutcomes,
+        reviewVerdicts,
+        sourcePath,
+        prNumber,
+      }),
+    );
+  } catch (error) {
+    console.error(
+      `maintenance.ts: could not write the «Registro de ejecución» block for ${task.id}; the transition proceeds anyway, and a board comment records the gap:`,
+      error,
+    );
+    try {
+      deps.backlog.comment(
+        task.id,
+        sanitizeCommentBody(executionRecordWriteFailureComment(String(error))),
+      );
+    } catch (commentError) {
+      console.error(
+        `maintenance.ts: could not even POST the «Registro de ejecución» failure comment for ${task.id}:`,
+        commentError,
+      );
+    }
+  }
+}
+
 /**
  * Runs the maintenance pass. Pure orchestration over injected collaborators — every mutation
  * (removing a lock, releasing a slot, editing a task's status, committing the board) goes through
@@ -781,7 +1017,7 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
   // already asked it for the SAME branch this same pass.
   const prMergedCache = new Map<string, boolean>();
   const mergeStateCache = new Map<string, PrMergeState>();
-  const gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState'> = {
+  const gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState' | 'prNumber'> = {
     isPrMerged: (branch) => {
       const cached = prMergedCache.get(branch);
       if (cached !== undefined) {
@@ -796,10 +1032,14 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
       if (cached !== undefined) {
         return cached;
       }
-      const state = ctx.gh.mergedState?.(branch) ?? PR_MERGE_STATE.UNKNOWN;
+      const state = ctx.gh.mergedState(branch);
       mergeStateCache.set(branch, state);
       return state;
     },
+    // Uncached, unlike the two above: `writeExecutionRecordOnce` is the ONLY caller, at most once
+    // per parent per pass (a supervisada parent, `attempts === 0`), so memoizing it would add a map
+    // this pass almost never fills.
+    prNumber: (branch) => ctx.gh.prNumber?.(branch) ?? null,
   };
 
   const tasksById: Record<string, Task> = Object.fromEntries(
@@ -952,15 +1192,22 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
       continue;
     }
     if (task.status === TASK_STATUS.IN_PROGRESS && gh.isPrMerged(branchFor(task.id))) {
+      // T-68: the record is written BEFORE the transition, so a successful block is on the board
+      // before `Done` is — but the write NEVER blocks the transition itself (see
+      // `writeExecutionRecordOnce`'s own JSDoc): a merged PR is a confirmed fact, and a task
+      // withheld here would leave `In Progress` forever, invisible to the orphan sweep and to
+      // `cleanupBranchOnDone` below. A failed write instead leaves ONE board comment and the pass
+      // proceeds exactly as it would on a clean write.
+      writeExecutionRecordOnce(ctx, task);
       ctx.backlog.setStatus(task.id, TASK_STATUS.DONE, 'PR mergeado: tarea completada.');
       movedToDone.push(task.id);
       transitions.push(`${task.id} -> ${TASK_STATUS.DONE}`);
       tasksById[task.id] = { ...task, status: TASK_STATUS.DONE };
       // T-8 point 5 — never reached on the Blocked path. Defect 7: only push it when the remote
       // half is CONFIRMED gone, not merely attempted. `taskBaseBranch` is the subtask's OWN base —
-      // its parent's DECLARED branch when it named one, `task/<parentId>` otherwise, never `main` —
-      // the same naming `close.ts`'s PR diff already uses (T-15).
-      const baseRef = `origin/${taskBaseBranch(task, tasksById)}`;
+      // `task/<parentId>`, never `main` — the same naming `close.ts`'s PR diff already uses (T-14,
+      // T-52).
+      const baseRef = `origin/${taskBaseBranch(task)}`;
       const outcome = cleanupBranchOnDone(task.id, ctx.git, baseRef);
       if (outcome === BRANCH_CLEANUP_OUTCOME.CLEANED) {
         cleanedUpBranches.push(task.id);
@@ -999,7 +1246,7 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
     if (!(ctx.git.branchExists?.(branch) ?? false)) {
       continue; // no branch, no PR: legitimately done by hand (or `branchExists` is not wired yet).
     }
-    const mergeState = ctx.gh.mergedState?.(branch) ?? PR_MERGE_STATE.UNKNOWN;
+    const mergeState = ctx.gh.mergedState(branch);
     if (mergeState === PR_MERGE_STATE.UNKNOWN) {
       // `gh` could not actually answer (outage, missing binary, expired token) — the worst case of
       // skipping here is a stale `Done` re-checked on the NEXT pass, never a revert this pass cannot
@@ -1044,6 +1291,15 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
       if (task.status !== TASK_STATUS.IN_PROGRESS || aliveLocksByTaskId.has(task.id)) {
         continue;
       }
+      // A parent's status is DERIVED from its children (parent.ts), never written by hand, so it
+      // can never be an orphan by this step's own definition — it will never carry a lock, a slot
+      // or an attempt directory of its own. Without this guard, a Complex parent sitting `In
+      // Progress` with a Done/To Do child mix (correct per parent.ts) gets blocked here on every
+      // pass once its `updated_date` goes stale, since nothing about it ever refreshes that field.
+      const hasChildren = Object.values(tasksById).some((candidate) => candidate.parentId === task.id);
+      if (hasChildren) {
+        continue;
+      }
       if (revertedThisPass.has(task.id)) {
         // T-8 defect 2: measured failure scenario — a person pushes `task/T-20`, opens a PR, and
         // marks the task `Done` by hand at 09:00. A pass runs at 14:00. Step 3b reverts it to
@@ -1132,9 +1388,8 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
         // T-8 point 5 applies here too: a parent that reaches Done because every child did, and
         // its own PR merged, gets the same branch cleanup a leaf task gets from step 3. Defect 7:
         // same "confirmed gone" condition as the leaf path above. The base is THIS parent's own
-        // `parentId` (its grandparent's DECLARED branch, `task/<grandparentId>`, or `main`) — a
-        // parent can itself be a subtask.
-        const baseRef = `origin/${taskBaseBranch(tasksById[parentId], tasksById)}`;
+        // `parentId` (`task/<grandparentId>`, or `main`) — a parent can itself be a subtask.
+        const baseRef = `origin/${taskBaseBranch(tasksById[parentId])}`;
         const outcome = cleanupBranchOnDone(parentId, ctx.git, baseRef);
         if (outcome === BRANCH_CLEANUP_OUTCOME.CLEANED) {
           cleanedUpBranches.push(parentId);
@@ -1146,6 +1401,46 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
     }
   }
 
+  // ── Step 5b: refresh the graph-holder task ──
+  // Placed AFTER step 5 (parent recompute) and BEFORE step 6 (board commit): rendering over
+  // `tasksById` as step 5 left it means a parent that just became Done stops being an open
+  // dependency in the SAME pass that closed it, and writing before the commit means the refresh
+  // rides in the SAME `chore(backlog): sync board state` commit as whatever change caused it.
+  let graphHolderRefreshed: string | null = null;
+  let graphHolderAmbiguous: string[] = [];
+  let graphHolderRefreshError: string | null = null;
+  try {
+    const board: Board = { tasksById, complete: ctx.boardComplete };
+    const decision = decideGraphWrite(board, (id) => ctx.backlog.readDescription(id) ?? '');
+    if (decision.kind === 'write') {
+      ctx.backlog.setDescription(decision.id, decision.description);
+      graphHolderRefreshed = decision.id;
+    } else if (decision.kind === 'ambiguous') {
+      graphHolderAmbiguous = decision.ids;
+      // Each holder's write is independent: one throwing must not cost the other its notice, and
+      // must not fail the whole step (`graphHolderRefreshError` stays reserved for a failure that
+      // aborts step 5b entirely, not a single holder's write).
+      for (const holderWrite of decision.writes) {
+        try {
+          ctx.backlog.setDescription(holderWrite.id, holderWrite.description);
+        } catch (error) {
+          console.error(
+            `maintenance.ts: could not write the ambiguity notice to ${holderWrite.id}; continuing the pass:`,
+            error,
+          );
+        }
+      }
+      console.warn(
+        `maintenance.ts: more than one board:graph holder (${decision.ids.join(', ')}); the dependency view was not refreshed.`,
+      );
+    }
+    // 'no-holder', 'unchanged' and 'incomplete' all mean nothing to write — the board that did
+    // not change (design.md decision 5's own framing) costs nothing: no edit, no commit.
+  } catch (error) {
+    graphHolderRefreshError = error instanceof Error ? error.message : String(error);
+    console.error('maintenance.ts: the graph-holder refresh failed; continuing the pass:', error);
+  }
+
   // ── Step 6: commit pending .backlog/** changes ──
   let committedBoard = false;
   if (ctx.git.hasPendingBacklogChanges()) {
@@ -1180,6 +1475,9 @@ export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
     revertedHandwrittenDone,
     orphanInProgressBlocked,
     pushRefusedMergedBranches,
+    graphHolderRefreshed,
+    graphHolderAmbiguous,
+    graphHolderRefreshError,
     slots: finalRegistry,
   };
 }

package/dist/templates/monorepo/scripts/backlog/render.test.ts

@@ -21,7 +21,15 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import { describe, it } from 'node:test';
-import { classifyStreamOutcome, extractResultText, planKindForOutcome, renderEvent, renderStream, STREAM_OUTCOME } from './render.js';
+import {
+  classifyStreamOutcome,
+  createLiveRenderer,
+  extractResultText,
+  planKindForOutcome,
+  renderEvent,
+  renderStream,
+  STREAM_OUTCOME,
+} from './render.js';
 
 const FIXTURE_PATH = path.join(import.meta.dirname, '__fixtures__', 'stream-success.jsonl');
 
@@ -172,6 +180,66 @@ describe('renderStream', () => {
   });
 });
 
+// ── createLiveRenderer: the incremental renderer `watch.ts` feeds one line at a time ──
+//
+// T-30: `pnpm backlog:watch <id>` must show new lines AS the worker produces them, tailing
+// `stream.jsonl` instead of waiting for `run.log` (written once, at the very end, by
+// `sink.finish()`). `createLiveRenderer` is the piece that makes that cost O(1) per line: it
+// keeps `t0` in closure state and renders one event at a time, rather than `renderStream`'s
+// batch replay — a per-line write must never re-render the whole session collected so far.
+
+describe('createLiveRenderer', () => {
+  it('renders the SAME lines as a batch renderStream, fed one at a time', () => {
+    const lines = readFixtureLines();
+    const renderer = createLiveRenderer();
+    const fed = lines.map((line) => renderer.feed(line)).filter((line): line is string => line !== null);
+    assert.deepEqual(fed, renderStream(lines));
+  });
+
+  it('derives t0 from the first line carrying a parseable timestamp, like renderStream', () => {
+    const renderer = createLiveRenderer();
+    // No timestamp at all: silent event, t0 still unset.
+    assert.equal(renderer.feed(JSON.stringify({ type: 'system', subtype: 'init' })), null);
+    const first = renderer.feed(
+      JSON.stringify({
+        type: 'assistant',
+        timestamp: '2026-09-04T20:08:41.000Z',
+        message: { content: [{ type: 'tool_use', name: 'Read', input: {} }] },
+      }),
+    );
+    assert.match(first as string, /^\+0s/);
+    const second = renderer.feed(
+      JSON.stringify({
+        type: 'assistant',
+        timestamp: '2026-09-04T20:08:53.000Z', // 12s after the first event, which set t0
+        message: { content: [{ type: 'tool_use', name: 'Read', input: {} }] },
+      }),
+    );
+    assert.match(second as string, /^\+12s/);
+  });
+
+  it('returns null for a line that fails to parse as JSON, without throwing', () => {
+    const renderer = createLiveRenderer();
+    assert.doesNotThrow(() => {
+      assert.equal(renderer.feed('not json at all'), null);
+    });
+  });
+
+  it('keeps rendering later valid lines after an unparseable one', () => {
+    const renderer = createLiveRenderer();
+    renderer.feed('not json at all');
+    const line = renderer.feed(
+      JSON.stringify({
+        type: 'assistant',
+        timestamp: '2026-09-04T20:08:41.000Z',
+        message: { content: [{ type: 'text', text: 'still works' }] },
+      }),
+    );
+    assert.ok(line);
+    assert.match(line as string, /still works/);
+  });
+});
+
 // ── classifyStreamOutcome: a failure that is not one of the three named shapes ─────
 
 describe('classifyStreamOutcome — unrecognized terminal failures', () => {
@@ -181,8 +249,11 @@ describe('classifyStreamOutcome — unrecognized terminal failures', () => {
     assert.equal(classifyStreamOutcome(resultLine({ subtype: 'error_max_turns', is_error: true })), 'error_max_turns');
   });
 
-  it('treats is_error:true as a failure even when the subtype says success', () => {
-    assert.equal(classifyStreamOutcome(resultLine({ subtype: 'success', is_error: true })), 'success');
+  it('treats is_error:true as a failure even when the subtype says success, and never names the cause "success"', () => {
+    assert.equal(
+      classifyStreamOutcome(resultLine({ subtype: 'success', is_error: true })),
+      STREAM_OUTCOME.UNNAMED_FAILURE,
+    );
   });
 
   it('still recognizes the budget stop by its own name', () => {