@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -0,0 +1,800 @@
+/**
+ * TDD spec for `scripts/backlog/graph.ts`.
+ *
+ * Runner: `node --import tsx --test scripts/backlog/graph.test.ts`
+ *
+ * Covers `specs/backlog-dependency-graph/spec.md` — "Flat-list view of open-task dependencies",
+ * "Graph-holder task mirrors the view" — over literal `Board` fixtures, per design.md decision 1
+ * (flat list, Kahn order, numeric id tie-break) and decision 7 (test strategy).
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  ambiguousHolderNotice,
+  decideGraphWrite,
+  GRAPH_CLI_EXIT,
+  GRAPH_HOLDER_HEADER,
+  listGraphHolderIds,
+  renderDependencyGraph,
+  renderHolderDescription,
+  runGraphCli,
+  type GraphCliEffects,
+} from './graph.js';
+import { GRAPH_HOLDER_LABEL, TASK_STATUS, type Board, type Task } from './types.js';
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+
+const makeTask = (overrides: Partial<Task> & { id: string }): Task => ({
+  status: TASK_STATUS.TO_DO,
+  filesToTouch: [],
+  testCommand: null,
+  acceptanceCriteria: [],
+  definitionOfDone: [],
+  dependsOn: [],
+  attempts: 0,
+  priority: 0,
+  createdAt: 0,
+  updatedAt: 0,
+  ...overrides,
+});
+
+const boardOf = (...tasks: Task[]): Board => ({
+  tasksById: Object.fromEntries(tasks.map((task) => [task.id, task])),
+});
+
+describe('renderDependencyGraph — ready tasks', () => {
+  it('lists a task with no declared dependency as ready', () => {
+    const board = boardOf(makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO }));
+    const text = renderDependencyGraph(board);
+    assert.match(text, /LISTAS — sin dependencias abiertas/);
+    assert.match(text, /T-1 \[To Do\]/);
+    assert.doesNotMatch(text, /EN ESPERA/);
+  });
+
+  it('lists a task whose only dependency is Done as ready, not waiting', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO, dependsOn: ['T-2'] }),
+      makeTask({ id: 'T-2', status: TASK_STATUS.DONE }),
+    );
+    const text = renderDependencyGraph(board);
+    assert.match(text, /LISTAS — sin dependencias abiertas/);
+    assert.match(text, /T-1 \[To Do\]/);
+    assert.doesNotMatch(text, /EN ESPERA/);
+    // A Done dependency is not a reason to wait, and it is not listed at all — it is Done, not open.
+    assert.doesNotMatch(text, /T-2/);
+  });
+});
+
+describe('renderDependencyGraph — waiting tasks', () => {
+  it('names every open dependency a waiting task declares', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-3', status: TASK_STATUS.TO_DO, dependsOn: ['T-1', 'T-2'] }),
+      makeTask({ id: 'T-1', status: TASK_STATUS.IN_PROGRESS }),
+      makeTask({ id: 'T-2', status: TASK_STATUS.TO_DO }),
+    );
+    const text = renderDependencyGraph(board);
+    assert.match(text, /EN ESPERA/);
+    const waitingLine = text.split('\n').find((line) => line.includes('T-3'));
+    assert.ok(waitingLine, 'expected a line naming T-3');
+    assert.match(waitingLine!, /espera a: T-1, T-2/);
+  });
+
+  it('lists a task with two waiting parents exactly once', () => {
+    // T-2 and T-3 both wait on T-1; T-4 waits on both T-2 and T-3.
+    const board = boardOf(
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-2', status: TASK_STATUS.TO_DO, dependsOn: ['T-1'] }),
+      makeTask({ id: 'T-3', status: TASK_STATUS.TO_DO, dependsOn: ['T-1'] }),
+      makeTask({ id: 'T-4', status: TASK_STATUS.TO_DO, dependsOn: ['T-2', 'T-3'] }),
+    );
+    const text = renderDependencyGraph(board);
+    for (const id of ['T-1', 'T-2', 'T-3', 'T-4']) {
+      const occurrences = text.split('\n').filter((line) => line.trim().startsWith(id)).length;
+      assert.equal(occurrences, 1, `${id} must appear exactly once`);
+    }
+  });
+
+  it('orders a waiting task after every open dependency it names, in the waiting section', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-2', status: TASK_STATUS.TO_DO, dependsOn: ['T-1'] }),
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO, dependsOn: ['T-0'] }),
+      makeTask({ id: 'T-0', status: TASK_STATUS.TO_DO }),
+    );
+    const text = renderDependencyGraph(board);
+    const lines = text.split('\n');
+    const indexOfT1 = lines.findIndex((line) => line.includes('T-1'));
+    const indexOfT2 = lines.findIndex((line) => line.includes('T-2'));
+    assert.ok(indexOfT1 >= 0 && indexOfT2 >= 0);
+    assert.ok(indexOfT1 < indexOfT2, 'T-1 must be listed before T-2, which waits on it');
+  });
+
+  it('marks a dependency id the board cannot resolve as unknown', () => {
+    const board = boardOf(makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO, dependsOn: ['T-999'] }));
+    const text = renderDependencyGraph(board);
+    assert.match(text, /EN ESPERA/);
+    const line = text.split('\n').find((entry) => entry.includes('T-1'));
+    assert.match(line!, /T-999 \(desconocida\)/);
+  });
+
+  it('lists a dependency cycle last, in id order, still naming what each member waits for', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-5', status: TASK_STATUS.TO_DO, dependsOn: ['T-6'] }),
+      makeTask({ id: 'T-6', status: TASK_STATUS.TO_DO, dependsOn: ['T-5'] }),
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO, dependsOn: ['T-2'] }),
+      makeTask({ id: 'T-2', status: TASK_STATUS.TO_DO }),
+    );
+    const text = renderDependencyGraph(board);
+    const lines = text
+      .split('\n')
+      .filter((line) => /^\s+T-\d/.test(line))
+      .map((line) => line.trim());
+    // T-1 (acyclic, orderable) must precede both cycle members T-5/T-6.
+    const idxT1 = lines.findIndex((line) => line.startsWith('T-1 '));
+    const idxT5 = lines.findIndex((line) => line.startsWith('T-5 '));
+    const idxT6 = lines.findIndex((line) => line.startsWith('T-6 '));
+    assert.ok(idxT1 < idxT5 && idxT1 < idxT6, 'acyclic tasks must precede cycle members');
+    assert.ok(idxT5 < idxT6, 'cycle members are ordered by id');
+    assert.match(lines[idxT5], /espera a: T-6/);
+    assert.match(lines[idxT6], /espera a: T-5/);
+  });
+});
+
+describe('renderDependencyGraph — graph-holder exclusion', () => {
+  it('never lists the task carrying the board:graph label', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-2', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+    );
+    const text = renderDependencyGraph(board);
+    assert.doesNotMatch(text, /T-2/);
+  });
+});
+
+describe('renderDependencyGraph — a parent waits for its own open subtasks', () => {
+  it('lists a parent with two open subtasks as waiting, naming both', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.TO_DO, parentId: 'T-10' }),
+      makeTask({ id: 'T-10.2', status: TASK_STATUS.TO_DO, parentId: 'T-10' }),
+    );
+    const text = renderDependencyGraph(board);
+    assert.match(text, /EN ESPERA/);
+    const parentLine = text.split('\n').find((line) => line.trim().startsWith('T-10 ['));
+    assert.ok(parentLine, 'expected a waiting line for the parent');
+    assert.match(parentLine!, /espera a: T-10\.1, T-10\.2/);
+  });
+
+  it('does not count a Done subtask as a reason to wait', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.DONE, parentId: 'T-10' }),
+      makeTask({ id: 'T-10.2', status: TASK_STATUS.TO_DO, parentId: 'T-10' }),
+    );
+    const text = renderDependencyGraph(board);
+    const parentLine = text.split('\n').find((line) => line.trim().startsWith('T-10 ['));
+    assert.ok(parentLine, 'expected a waiting line for the parent');
+    assert.match(parentLine!, /espera a: T-10\.2/);
+    assert.doesNotMatch(parentLine!, /T-10\.1/);
+  });
+
+  it('lists a parent as ready once every subtask is Done', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.DONE, parentId: 'T-10' }),
+    );
+    const text = renderDependencyGraph(board);
+    assert.match(text, /LISTAS — sin dependencias abiertas/);
+    assert.match(text, /T-10 \[To Do\]/);
+    assert.doesNotMatch(text, /EN ESPERA/);
+  });
+
+  it('merges an open subtask (derived) with a declared dependency (explicit), in numeric order', () => {
+    const board = boardOf(
+      // T-10 declares ONLY T-2 as a dependency; T-10.1 becomes a reason to wait purely from being
+      // its open SUBTASK, with no dependsOn entry naming it at all.
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO, dependsOn: ['T-2'] }),
+      makeTask({ id: 'T-2', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.TO_DO, parentId: 'T-10' }),
+    );
+    const text = renderDependencyGraph(board);
+    const parentLine = text.split('\n').find((line) => line.trim().startsWith('T-10 ['));
+    assert.ok(parentLine, 'expected a waiting line for the parent');
+    assert.match(parentLine!, /espera a: T-2, T-10\.1$/);
+  });
+
+  it('does not repeat an id declared as BOTH a dependency and derived from being an open subtask', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO, dependsOn: ['T-10.1'] }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.TO_DO, parentId: 'T-10' }),
+    );
+    const text = renderDependencyGraph(board);
+    const parentLine = text.split('\n').find((line) => line.trim().startsWith('T-10 ['));
+    assert.ok(parentLine, 'expected a waiting line for the parent');
+    assert.equal((parentLine!.match(/T-10\.1/g) ?? []).length, 1, 'T-10.1 must appear exactly once');
+  });
+
+  it('does not make the subtask wait for its own parent', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.TO_DO, parentId: 'T-10' }),
+    );
+    const text = renderDependencyGraph(board);
+    const subtaskLine = text.split('\n').find((line) => line.trim().startsWith('T-10.1 ['));
+    assert.ok(subtaskLine, 'expected a line for the subtask');
+    assert.match(subtaskLine!, /^\s*T-10\.1 \[To Do\]$/, 'the subtask itself must render as READY, not waiting on its parent');
+  });
+
+  it('orders the parent after its open subtask in the waiting section', () => {
+    // The subtask itself waits on an unrelated task, so BOTH the subtask and the parent land in the
+    // waiting section, and the parent must still print after the subtask it depends on.
+    const board = boardOf(
+      makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.TO_DO, parentId: 'T-10', dependsOn: ['T-1'] }),
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO }),
+    );
+    const text = renderDependencyGraph(board);
+    const lines = text.split('\n');
+    const idxSubtask = lines.findIndex((line) => line.trim().startsWith('T-10.1 ['));
+    const idxParent = lines.findIndex((line) => line.trim().startsWith('T-10 ['));
+    assert.ok(idxSubtask >= 0 && idxParent >= 0);
+    assert.ok(idxSubtask < idxParent, 'the subtask must be listed before the parent waiting on it');
+  });
+
+  // Through `renderDependencyGraph`, not a local re-implementation of the comparator: `T-10.2` vs
+  // `T-10.10` and `T-9` vs `T-11` sort OPPOSITELY under plain string comparison versus Intl numeric
+  // collation ('T-10.10' < 'T-10.2' and 'T-11' < 'T-9' lexicographically; the reverse numerically) —
+  // exactly the case `compareTaskId`'s `{ numeric: true }` exists for.
+  it('orders a dotted subtask id numerically, not lexicographically, in BOTH the ready section and an espera a: list', () => {
+    const numericOrder = ['T-9', 'T-10.1', 'T-10.2', 'T-10.10', 'T-11'];
+    // Inserted scrambled — neither numeric nor lexicographic order — so nothing here rides on
+    // insertion order the way the earlier (tautological) version of this test did.
+    const board = boardOf(
+      makeTask({ id: 'T-11', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-9', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.10', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO, dependsOn: [...numericOrder] }),
+      makeTask({ id: 'T-10.2', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-10.1', status: TASK_STATUS.TO_DO }),
+    );
+
+    const text = renderDependencyGraph(board);
+    const lines = text.split('\n');
+
+    const readyStart = lines.indexOf('LISTAS — sin dependencias abiertas') + 1;
+    assert.deepEqual(
+      lines.slice(readyStart, readyStart + numericOrder.length),
+      numericOrder.map((id) => `  ${id} [To Do]`),
+      'the ready section must list every id in NUMERIC order',
+    );
+
+    const waitingLine = lines.find((line) => line.trim().startsWith('T-1 ['));
+    assert.ok(waitingLine, 'expected a waiting line for T-1, which depends on all five');
+    assert.match(waitingLine!, new RegExp(`espera a: ${numericOrder.join(', ')}$`));
+  });
+});
+
+describe('renderDependencyGraph — determinism', () => {
+  it('renders identical text, in numeric id order, regardless of insertion order', () => {
+    // T-9/T-106 and T-3/T-20 sort ONE WAY numerically and the OPPOSITE way lexicographically
+    // ('T-106' < 'T-9', but 'T-20' < 'T-3'). A board rebuilt in the SAME insertion order would pass
+    // even with the numeric tie-break deleted,
+    // since a plain object preserves insertion order regardless of how the ids compare.
+    const ready1 = makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO });
+    const ready9 = makeTask({ id: 'T-9', status: TASK_STATUS.TO_DO });
+    const ready106 = makeTask({ id: 'T-106', status: TASK_STATUS.TO_DO });
+    const waiting20 = makeTask({ id: 'T-20', status: TASK_STATUS.TO_DO, dependsOn: ['T-1'] });
+    const waiting3 = makeTask({ id: 'T-3', status: TASK_STATUS.TO_DO, dependsOn: ['T-1'] });
+
+    const boardInsertionOrderA = boardOf(ready106, ready9, ready1, waiting20, waiting3);
+    const boardInsertionOrderB = boardOf(waiting3, waiting20, ready1, ready9, ready106);
+
+    const textA = renderDependencyGraph(boardInsertionOrderA);
+    const textB = renderDependencyGraph(boardInsertionOrderB);
+    assert.equal(textA, textB, 'insertion order must not change the rendered text');
+
+    // Ready section: numeric order is T-1, T-9, T-106 — lexicographic order would put T-106 before T-9.
+    assert.ok(
+      textA.indexOf('T-1 [') < textA.indexOf('T-9 [') && textA.indexOf('T-9 [') < textA.indexOf('T-106 ['),
+      'the ready section must list T-1, T-9, T-106 in NUMERIC order',
+    );
+    // Waiting section: both wait only on T-1, so the tie is broken by id — numeric order is T-3
+    // before T-20, the opposite of lexicographic order.
+    assert.ok(
+      textA.indexOf('T-3 [') < textA.indexOf('T-20 ['),
+      'the waiting section must list T-3 before T-20 (numeric tie-break), not T-20 before T-3',
+    );
+  });
+});
+
+// ── listGraphHolderIds ───────────────────────────────────────────────────────
+
+describe('listGraphHolderIds', () => {
+  it('returns an empty list when no task carries the label', () => {
+    const board = boardOf(makeTask({ id: 'T-1' }));
+    assert.deepEqual(listGraphHolderIds(board), []);
+  });
+
+  it('returns every id carrying the label, sorted numerically', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-20', isGraphHolder: true }),
+      makeTask({ id: 'T-3', isGraphHolder: true }),
+    );
+    assert.deepEqual(listGraphHolderIds(board), ['T-3', 'T-20']);
+  });
+});
+
+// ── GRAPH_HOLDER_HEADER / renderHolderDescription ────────────────────────────
+
+describe('GRAPH_HOLDER_HEADER', () => {
+  it('states that only declared links are shown', () => {
+    assert.match(GRAPH_HOLDER_HEADER, /declarad/i);
+  });
+
+  it('states that the view does not authorize queueing', () => {
+    assert.match(GRAPH_HOLDER_HEADER, /no autoriza a encolar/i);
+  });
+
+  it('states the text is generated and must not be edited by hand', () => {
+    assert.match(GRAPH_HOLDER_HEADER, /generad/i);
+    assert.match(GRAPH_HOLDER_HEADER, /no.*edit/i);
+  });
+
+  // The spec scenario "The header states the limit of the view" requires the description to START
+  // with the declared-links limitation — a reader (human or AI) must hit that caveat before
+  // anything else, never after scrolling past a generated/do-not-edit notice first.
+  it('opens with the declared-links statement, and closes with the generated notice', () => {
+    const paragraphs = GRAPH_HOLDER_HEADER.split('\n\n');
+    assert.match(paragraphs[0], /declarad/i, 'the first paragraph must state the declared-links limit');
+    assert.match(
+      paragraphs[paragraphs.length - 1],
+      /generad/i,
+      'the last paragraph must be the generated/do-not-edit notice',
+    );
+  });
+});
+
+describe('renderHolderDescription', () => {
+  it('opens with the header, followed by the rendered flat list', () => {
+    const board = boardOf(makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO }));
+    const description = renderHolderDescription(board);
+    assert.ok(description.startsWith(GRAPH_HOLDER_HEADER));
+    assert.match(description, /T-1 \[To Do\]/);
+  });
+});
+
+// ── decideGraphWrite ─────────────────────────────────────────────────────────
+
+describe('decideGraphWrite', () => {
+  it('reports no-holder and never calls the description reader when no task carries the label', () => {
+    const board = boardOf(makeTask({ id: 'T-1' }));
+    const decision = decideGraphWrite(board, () => {
+      throw new Error('must not be called with zero holders');
+    });
+    assert.deepEqual(decision, { kind: 'no-holder' });
+  });
+
+  it('reports ambiguous, naming every id, and a write for EACH holder that does not already show the notice', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-2', isGraphHolder: true }),
+      makeTask({ id: 'T-1', isGraphHolder: true }),
+    );
+    const decision = decideGraphWrite(board, () => 'stale text, not the notice');
+    assert.equal(decision.kind, 'ambiguous');
+    if (decision.kind === 'ambiguous') {
+      assert.deepEqual(decision.ids, ['T-1', 'T-2']);
+      assert.deepEqual(
+        decision.writes.map((write) => write.id).sort(),
+        ['T-1', 'T-2'],
+        'both holders need the notice written',
+      );
+      for (const write of decision.writes) {
+        assert.match(write.description, /T-1/);
+        assert.match(write.description, /T-2/);
+        assert.doesNotMatch(write.description, /`/, 'no backticks — the board popup lifts inline code out of the sentence');
+      }
+    }
+  });
+
+  it('does not rewrite a holder that already shows the ambiguity notice', () => {
+    const board = boardOf(
+      makeTask({ id: 'T-2', isGraphHolder: true }),
+      makeTask({ id: 'T-1', isGraphHolder: true }),
+    );
+    const notice = ambiguousHolderNotice(['T-1', 'T-2']);
+    const decision = decideGraphWrite(board, (id) => (id === 'T-1' ? notice : 'stale text'));
+    assert.equal(decision.kind, 'ambiguous');
+    if (decision.kind === 'ambiguous') {
+      assert.deepEqual(decision.writes.map((write) => write.id), ['T-2']);
+    }
+  });
+
+  it('reports unchanged when the rendered description already matches the current one', () => {
+    const board = boardOf(makeTask({ id: 'T-9', isGraphHolder: true, status: TASK_STATUS.TO_DO }));
+    const current = renderHolderDescription(board);
+    const decision = decideGraphWrite(board, () => current);
+    assert.deepEqual(decision, { kind: 'unchanged', id: 'T-9' });
+  });
+
+  it('reports write with the new description when it differs from the current one', () => {
+    const board = boardOf(makeTask({ id: 'T-9', isGraphHolder: true, status: TASK_STATUS.TO_DO }));
+    const decision = decideGraphWrite(board, () => 'stale text');
+    assert.equal(decision.kind, 'write');
+    if (decision.kind === 'write') {
+      assert.equal(decision.id, 'T-9');
+      assert.equal(decision.description, renderHolderDescription(board));
+    }
+  });
+
+  it('reports incomplete and never calls the description reader when the board read was partial', () => {
+    const board: Board = {
+      tasksById: { 'T-9': makeTask({ id: 'T-9', isGraphHolder: true }) },
+      complete: false,
+    };
+    const decision = decideGraphWrite(board, () => {
+      throw new Error('must not be called over an incomplete board');
+    });
+    assert.deepEqual(decision, { kind: 'incomplete' });
+  });
+});
+
+// ── runGraphCli ──────────────────────────────────────────────────────────────
+//
+// The CLI wiring `main()` binds to the real world: `decideGraphWrite` itself is well covered, but
+// nothing proved that the argv gate or the effect dispatch actually APPLIES its verdict. Every
+// collaborator is injected — board load, description read/write, stdout/stderr — so a broken
+// `--write` gate or a dropped `write` case fails here without a real board or a real `backlog` CLI.
+
+describe('runGraphCli', () => {
+  const holderTask = (): Task => makeTask({ id: 'T-112', status: TASK_STATUS.TO_DO, isGraphHolder: true });
+  const openTask = (): Task => makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO });
+
+  const collectingEffects = (
+    overrides: Partial<GraphCliEffects> = {},
+  ): GraphCliEffects & {
+    printed: string[];
+    errors: string[];
+    writeCalls: Array<{ id: string; description: string }>;
+    /** `print`/`reportError` in call order — the two sinks alone cannot tell which came first. */
+    outputOrder: Array<'print' | 'reportError'>;
+  } => {
+    const printed: string[] = [];
+    const errors: string[] = [];
+    const writeCalls: Array<{ id: string; description: string }> = [];
+    const outputOrder: Array<'print' | 'reportError'> = [];
+    return {
+      loadBoard: () => boardOf(),
+      readDescription: () => '',
+      writeDescription: (id, description) => {
+        writeCalls.push({ id, description });
+      },
+      print: (line) => {
+        outputOrder.push('print');
+        printed.push(line);
+      },
+      reportError: (line) => {
+        outputOrder.push('reportError');
+        errors.push(line);
+      },
+      printed,
+      errors,
+      writeCalls,
+      outputOrder,
+      ...overrides,
+    };
+  };
+
+  it('without --write: prints the view and never calls the writer, even when the holder description differs', () => {
+    const board = boardOf(holderTask(), openTask());
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => 'stale text, deliberately different from the rendered one',
+    });
+
+    const exitCode = runGraphCli([], effects);
+
+    assert.equal(effects.writeCalls.length, 0);
+    assert.equal(effects.printed.length, 1);
+    assert.match(effects.printed[0], /T-1 \[To Do\]/);
+    assert.deepEqual(effects.errors, []);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+  });
+
+  it('with --write and a write decision: calls the writer exactly once with the holder id and the rendered description', () => {
+    const board = boardOf(holderTask(), openTask());
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => 'stale text',
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.equal(effects.writeCalls.length, 1);
+    assert.deepEqual(effects.writeCalls[0], {
+      id: 'T-112',
+      description: renderHolderDescription(board),
+    });
+    assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+  });
+
+  it('with --write and unchanged: prints, never calls the writer', () => {
+    const board = boardOf(holderTask(), openTask());
+    const current = renderHolderDescription(board);
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => current,
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.equal(effects.writeCalls.length, 0);
+    assert.equal(effects.printed.length, 2, 'the view, then the outcome line');
+    assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+  });
+
+  it('with --write and no holder: prints, never calls the writer, and reports no error', () => {
+    const board = boardOf(openTask());
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => {
+        throw new Error('must not be called with zero holders');
+      },
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.equal(effects.writeCalls.length, 0);
+    assert.equal(effects.printed.length, 2, 'the view, then the outcome line');
+    assert.deepEqual(effects.errors, []);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+  });
+
+  it('with --write and two or more holders: writes the ambiguity notice to each, reports the ids on stderr, and fails', () => {
+    const board = boardOf(
+      holderTask(),
+      makeTask({ id: 'T-113', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+      openTask(),
+    );
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => 'stale text, not the notice',
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.deepEqual(
+      effects.writeCalls.map((call) => call.id).sort(),
+      ['T-112', 'T-113'],
+      'both holders receive the ambiguity notice',
+    );
+    for (const call of effects.writeCalls) {
+      assert.match(call.description, /T-112/);
+      assert.match(call.description, /T-113/);
+    }
+    assert.equal(effects.errors.length, 1);
+    assert.match(effects.errors[0], /T-112/);
+    assert.match(effects.errors[0], /T-113/);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+
+  it('with --write and two or more holders, one already showing the notice: writes only the other', () => {
+    const board = boardOf(
+      holderTask(),
+      makeTask({ id: 'T-113', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+      openTask(),
+    );
+    const notice = ambiguousHolderNotice(['T-112', 'T-113']);
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: (id) => (id === 'T-112' ? notice : 'stale text'),
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.deepEqual(effects.writeCalls.map((call) => call.id), ['T-113']);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+
+  it('with --write and two or more holders: a throw writing one notice does not prevent the other', () => {
+    const board = boardOf(
+      holderTask(),
+      makeTask({ id: 'T-113', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+      openTask(),
+    );
+    const succeededWrites: Array<{ id: string; description: string }> = [];
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => 'stale text',
+      writeDescription: (id, description) => {
+        if (id === 'T-112') {
+          throw new Error('simulated failure writing T-112');
+        }
+        succeededWrites.push({ id, description });
+      },
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.deepEqual(succeededWrites.map((call) => call.id), ['T-113']);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+
+  it('with --write and an incomplete board read: never calls the writer, warns BEFORE the view, still prints, and fails', () => {
+    const board: Board = { tasksById: { 'T-112': holderTask() }, complete: false };
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => {
+        throw new Error('must not be called over an incomplete board');
+      },
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.equal(effects.writeCalls.length, 0);
+    assert.equal(effects.errors.length, 1);
+    assert.match(effects.errors[0], /parcial/i);
+    assert.equal(effects.printed.length, 1, 'the view is still printed over an incomplete board');
+    assert.deepEqual(effects.outputOrder, ['reportError', 'print'], 'the warning must precede the view');
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+
+  // Without --write the incomplete-board caveat must still surface — an AI consumer that never
+  // passes --write must not read "LISTAS" as trustworthy over a partial board either.
+  it('without --write and an incomplete board read: warns BEFORE the view, still prints, and fails, never touching readDescription', () => {
+    const board: Board = { tasksById: { 'T-1': openTask() }, complete: false };
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => {
+        throw new Error('must not be called at all without --write');
+      },
+    });
+
+    const exitCode = runGraphCli([], effects);
+
+    assert.equal(effects.errors.length, 1);
+    assert.match(effects.errors[0], /parcial/i);
+    assert.equal(effects.printed.length, 1);
+    assert.deepEqual(effects.outputOrder, ['reportError', 'print'], 'the warning must precede the view');
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+
+  it('prints the placeholder line for an empty open board', () => {
+    const effects = collectingEffects({ loadBoard: () => boardOf() });
+
+    const exitCode = runGraphCli([], effects);
+
+    assert.deepEqual(effects.printed, ['(sin tareas abiertas)']);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+  });
+
+  // A scripted caller cannot tell "refreshed" from "refused" if a mistyped flag is
+  // silently ignored — `--wirte`/`-w`/`--write=true` must all be refused, writing nothing.
+  describe('argv gate', () => {
+    for (const badArg of ['--wirte', '-w', '--write=true']) {
+      it(`refuses the unrecognized argument "${badArg}", writing nothing`, () => {
+        const board = boardOf(holderTask(), openTask());
+        const effects = collectingEffects({
+          loadBoard: () => board,
+          readDescription: () => {
+            throw new Error('must not be called when the argv gate refuses the run');
+          },
+        });
+
+        const exitCode = runGraphCli([badArg], effects);
+
+        assert.equal(effects.writeCalls.length, 0);
+        assert.equal(effects.errors.length, 1);
+        assert.match(effects.errors[0], new RegExp(badArg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+        assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+      });
+    }
+
+    // pnpm passes a literal `--` through in some versions (`pnpm backlog:graph -- --write`) — it
+    // is pnpm's own separator, not an argument this command declares, so it must be a no-op rather
+    // than an unrecognized argument.
+    it('treats a bare "--" as no argument at all, not as unrecognized', () => {
+      const effects = collectingEffects({ loadBoard: () => boardOf(openTask()) });
+
+      const exitCode = runGraphCli(['--'], effects);
+
+      assert.deepEqual(effects.errors, []);
+      assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+    });
+
+    it('still recognizes --write behind a leading "--" separator', () => {
+      const board = boardOf(holderTask(), openTask());
+      const effects = collectingEffects({ loadBoard: () => board, readDescription: () => 'stale text' });
+
+      const exitCode = runGraphCli(['--', '--write'], effects);
+
+      assert.equal(effects.writeCalls.length, 1);
+      assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+    });
+  });
+
+  // `readDescription` throws on a failed underlying read instead of being swallowed
+  // into `''` — the CLI must report that as a failed run, not silently write nothing and exit 0.
+  it('with --write and a readDescription that throws: reports it and fails, never calls the writer', () => {
+    const board = boardOf(holderTask(), openTask());
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => {
+        throw new Error('simulated backlog task view failure');
+      },
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.equal(effects.writeCalls.length, 0);
+    assert.equal(effects.errors.length, 1);
+    assert.match(effects.errors[0], /simulated backlog task view failure/);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+
+  // `write`/`unchanged`/`no-holder` each report one Spanish stdout line, AFTER the view, so a
+  // scripted caller reading stdout (not just the exit code) can tell them apart.
+  describe('--write reports what it did, after the view', () => {
+    it('write: prints "holder <id> refrescado" after the view', () => {
+      const board = boardOf(holderTask(), openTask());
+      const effects = collectingEffects({ loadBoard: () => board, readDescription: () => 'stale text' });
+
+      const exitCode = runGraphCli(['--write'], effects);
+
+      assert.equal(effects.printed.length, 2);
+      assert.match(effects.printed[0], /T-1 \[To Do\]/);
+      assert.equal(effects.printed[1], 'backlog:graph: holder T-112 refrescado.');
+      assert.deepEqual(effects.outputOrder, ['print', 'print']);
+      assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+    });
+
+    it('unchanged: prints "holder <id> ya está al día" after the view', () => {
+      const board = boardOf(holderTask(), openTask());
+      const current = renderHolderDescription(board);
+      const effects = collectingEffects({ loadBoard: () => board, readDescription: () => current });
+
+      const exitCode = runGraphCli(['--write'], effects);
+
+      assert.equal(effects.printed.length, 2);
+      assert.equal(effects.printed[1], 'backlog:graph: holder T-112 ya está al día.');
+      assert.deepEqual(effects.outputOrder, ['print', 'print']);
+      assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+    });
+
+    it('no-holder: prints "ninguna tarea lleva board:graph" after the view', () => {
+      const board = boardOf(openTask());
+      const effects = collectingEffects({ loadBoard: () => board });
+
+      const exitCode = runGraphCli(['--write'], effects);
+
+      assert.equal(effects.printed.length, 2);
+      assert.match(effects.printed[1], /backlog:graph: ninguna tarea lleva board:graph/);
+      assert.deepEqual(effects.outputOrder, ['print', 'print']);
+      assert.equal(exitCode, GRAPH_CLI_EXIT.OK);
+    });
+
+    it('without --write: prints only the view, no outcome line', () => {
+      const board = boardOf(holderTask(), openTask());
+      const effects = collectingEffects({ loadBoard: () => board });
+
+      runGraphCli([], effects);
+
+      assert.equal(effects.printed.length, 1);
+    });
+  });
+
+  it('with --write and a writeDescription that throws: reports it and fails', () => {
+    const board = boardOf(holderTask(), openTask());
+    const effects = collectingEffects({
+      loadBoard: () => board,
+      readDescription: () => 'stale text',
+      writeDescription: () => {
+        throw new Error('simulated backlog task edit failure');
+      },
+    });
+
+    const exitCode = runGraphCli(['--write'], effects);
+
+    assert.equal(effects.errors.length, 1);
+    assert.match(effects.errors[0], /simulated backlog task edit failure/);
+    assert.equal(exitCode, GRAPH_CLI_EXIT.FAILURE);
+  });
+});