@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

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

@@ -0,0 +1,928 @@
+/**
+ * TDD spec for `scripts/backlog/prompt.ts` (tasks 4.2/4.3).
+ *
+ * Runner: `node --import tsx --test scripts/backlog/prompt.test.ts`
+ *
+ * Covers design.md's "Executor prompt contract": `assembleExecutorPrompt`'s six ordered blocks
+ * (task text, the working directory block, precomputed hook outputs, injected skill paths, the
+ * delegation contract verbatim, the operating envelope) plus retry inclusion (the prior `Blocked`
+ * comment and reviewer
+ * findings); `matchSkillPaths` against a small inline triggers index; `computeHookOutputs`'s
+ * runner invocation shapes (reset-then-drive, synthetic-stdin-shaped calls); and
+ * `extractDelegationContract`'s verbatim extraction of `catalyst-delegation`'s section 3 block.
+ */
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import {
+  assembleExecutorPrompt,
+  buildFrontierAddendum,
+  buildFrontierPrompt,
+  buildHookPromptText,
+  buildParentCloseAttemptPrompt,
+  computeHookOutputs,
+  extractDelegationContract,
+  isParentCloseAttempt,
+  matchSkillPaths,
+  parseAcceptanceCriteria,
+  parseDefinitionOfDone,
+  parseLastComment,
+  renderRetryBlock,
+  type HookRunners,
+} from './prompt.js';
+import { LANE, TASK_STATUS, TIER, type Board, type Task } from './types.js';
+
+const baseTask = (overrides: Partial<Task> = {}): Task => ({
+  id: 'T-42',
+  status: TASK_STATUS.QUEUED,
+  tier: 'minor',
+  lane: LANE.LOCAL,
+  path: 'direct',
+  bc: 'o-auth',
+  filesToTouch: ['backend/src/@app/o-auth/session.service.ts'],
+  testCommand: 'pnpm --filter aurora-back test',
+  acceptanceCriteria: [],
+  definitionOfDone: [],
+  dependsOn: [],
+  attempts: 0,
+  priority: 1,
+  createdAt: 0,
+  updatedAt: 0,
+  ...overrides,
+});
+
+// ── buildHookPromptText ────────────────────────────────────────────────────────
+
+describe('buildHookPromptText', () => {
+  it('combines the bc and the declared files into one string', () => {
+    const text = buildHookPromptText(baseTask(), ['backend/src/@app/o-auth/session.service.ts']);
+    assert.equal(text, 'o-auth backend/src/@app/o-auth/session.service.ts');
+  });
+
+  // M9: the id used to lead this string, which made the hook match its own task prefix and inject a
+  // WHOLE task block — the same task text block 1 of the envelope already carries verbatim. The
+  // local worker read its task twice, in two formats, one of them describing an interactive Task
+  // Gate it has no business walking.
+  it('omits the task id, so the hook task block never fires inside the executor prompt', () => {
+    assert.ok(!buildHookPromptText(baseTask(), ['a.ts']).includes('T-42'));
+  });
+
+  it('drops a missing bc without leaving a stray space', () => {
+    const text = buildHookPromptText(baseTask({ bc: undefined }), ['a.ts']);
+    assert.equal(text, 'a.ts');
+  });
+
+  it('comes back empty when the task declares neither a bc nor a file', () => {
+    assert.equal(buildHookPromptText(baseTask({ bc: undefined }), []), '');
+  });
+});
+
+// ── computeHookOutputs ─────────────────────────────────────────────────────────
+
+describe('computeHookOutputs', () => {
+  it('resets the injector cache before driving either hook', () => {
+    const calls: string[] = [];
+    const runners: HookRunners = {
+      resetInjectorCache: () => calls.push('reset'),
+      runInjectPromptContext: (prompt) => {
+        calls.push(`prompt:${prompt}`);
+        return '';
+      },
+      runBusinessRulesInjector: (filePath) => {
+        calls.push(`br:${filePath}`);
+        return '';
+      },
+    };
+
+    computeHookOutputs(runners, baseTask(), ['a.ts', 'b.ts']);
+
+    assert.equal(calls[0], 'reset');
+  });
+
+  it('drives runInjectPromptContext once with the task-derived prompt text', () => {
+    const promptsSeen: string[] = [];
+    const runners: HookRunners = {
+      resetInjectorCache: () => {},
+      runInjectPromptContext: (prompt) => {
+        promptsSeen.push(prompt);
+        return '';
+      },
+      runBusinessRulesInjector: () => '',
+    };
+
+    computeHookOutputs(runners, baseTask(), ['a.ts']);
+
+    assert.deepEqual(promptsSeen, [buildHookPromptText(baseTask(), ['a.ts'])]);
+  });
+
+  it('drives runBusinessRulesInjector once per declared file, in order', () => {
+    const filesSeen: string[] = [];
+    const runners: HookRunners = {
+      resetInjectorCache: () => {},
+      runInjectPromptContext: () => '',
+      runBusinessRulesInjector: (filePath) => {
+        filesSeen.push(filePath);
+        return '';
+      },
+    };
+
+    computeHookOutputs(runners, baseTask(), ['a.ts', 'b.ts', 'c.ts']);
+
+    assert.deepEqual(filesSeen, ['a.ts', 'b.ts', 'c.ts']);
+  });
+
+  it('maps blank hook output to a null promptContext and drops blank per-file results', () => {
+    const runners: HookRunners = {
+      resetInjectorCache: () => {},
+      runInjectPromptContext: () => '   ',
+      runBusinessRulesInjector: () => '',
+    };
+
+    const result = computeHookOutputs(runners, baseTask(), ['a.ts']);
+
+    assert.equal(result.promptContext, null);
+    assert.deepEqual(result.fileRules, []);
+  });
+
+  it('carries non-blank hook output through verbatim', () => {
+    const runners: HookRunners = {
+      resetInjectorCache: () => {},
+      runInjectPromptContext: () => '# Skills relevantes\n- foo',
+      runBusinessRulesInjector: (filePath) => (filePath === 'a.ts' ? 'BR-OAUTH-001 — ...' : ''),
+    };
+
+    const result = computeHookOutputs(runners, baseTask(), ['a.ts', 'b.ts']);
+
+    assert.equal(result.promptContext, '# Skills relevantes\n- foo');
+    assert.deepEqual(result.fileRules, [{ filePath: 'a.ts', context: 'BR-OAUTH-001 — ...' }]);
+  });
+});
+
+// ── matchSkillPaths ────────────────────────────────────────────────────────────
+
+describe('matchSkillPaths', () => {
+  const triggersIndex = {
+    skills: [
+      {
+        name: 'catalyst-langs',
+        path: '.claude/skills/catalyst-langs/SKILL.md',
+        triggers: ['i18n', 'idiomas', 'CommonLang'],
+      },
+      {
+        name: 'business-rules-guard',
+        path: '.claude/skills/business-rules-guard/SKILL.md',
+        triggers: ['cliter/business-rules', 'derogar'],
+      },
+    ],
+  };
+
+  it('matches a skill whose trigger appears in a declared file path', () => {
+    const matched = matchSkillPaths(['cliter/business-rules/o-auth.md'], triggersIndex);
+    assert.deepEqual(matched, ['.claude/skills/business-rules-guard/SKILL.md']);
+  });
+
+  it('returns no matches when no trigger appears in any declared file', () => {
+    const matched = matchSkillPaths(['backend/src/@app/o-auth/session.service.ts'], triggersIndex);
+    assert.deepEqual(matched, []);
+  });
+
+  it('is case-insensitive and deduplicates a skill matched by more than one file', () => {
+    const matched = matchSkillPaths(
+      [
+        'frontend/src/@aurora/modules/I18N/foo.ts',
+        'frontend/src/environments/environment.type.ts (i18n)',
+      ],
+      triggersIndex,
+    );
+    assert.deepEqual(matched, ['.claude/skills/catalyst-langs/SKILL.md']);
+  });
+
+  it('returns matches sorted alphabetically by path', () => {
+    const matched = matchSkillPaths(['cliter/business-rules/x.md (i18n)'], triggersIndex);
+    assert.deepEqual(matched, [
+      '.claude/skills/business-rules-guard/SKILL.md',
+      '.claude/skills/catalyst-langs/SKILL.md',
+    ]);
+  });
+});
+
+// ── extractDelegationContract ──────────────────────────────────────────────────
+
+describe('extractDelegationContract', () => {
+  const skillMd = [
+    '## 2. Pre-flight before every Agent call',
+    '',
+    'Some unrelated section.',
+    '',
+    '## 3. Injectable contract blocks (copy verbatim into the prompt)',
+    '',
+    '```',
+    '## Skills to load before work',
+    'Read these files BEFORE starting the task:',
+    '- <repo-relative path to SKILL.md>',
+    '```',
+    '',
+    '## 4. Reading the returned fields',
+    '',
+    'Some other unrelated section.',
+  ].join('\n');
+
+  it('extracts exactly the fenced block under section 3', () => {
+    const contract = extractDelegationContract(skillMd);
+    assert.equal(
+      contract,
+      [
+        '## Skills to load before work',
+        'Read these files BEFORE starting the task:',
+        '- <repo-relative path to SKILL.md>',
+      ].join('\n'),
+    );
+  });
+
+  it('throws a descriptive error when section 3 is missing', () => {
+    assert.throws(() => extractDelegationContract('no section here'), /section 3/i);
+  });
+});
+
+// ── envelope extraction from `backlog task view --plain` text ─────────────────
+
+describe('parseAcceptanceCriteria / parseDefinitionOfDone', () => {
+  // Verbatim `backlog task view T-2 --plain` output (captured 2026-09-06), the real shape these
+  // parsers must handle — checklist items numbered `#N`, a dashed underline under each heading,
+  // and a blank line ending each section.
+  const realTaskView = [
+    'Task T-2 - Scratch inspection task',
+    '==================================================',
+    '',
+    'Status: ○ To Do',
+    'Priority: Medium',
+    'Type: task',
+    'Ordinal: 1000',
+    'Created: 2026-09-06 14:14 (UTC)',
+    'Labels: tier:minor, lane:local, path:direct, bc:scratch',
+    '',
+    'Description:',
+    '--------------------------------------------------',
+    'Test command: pnpm --filter backend test -- session.spec.ts',
+    '',
+    'Acceptance Criteria:',
+    '--------------------------------------------------',
+    '- [ ] #1 First AC',
+    '- [ ] #2 Second AC',
+    '',
+    'Definition of Done:',
+    '--------------------------------------------------',
+    '- [ ] #1 Scoped tests pass with the command declared in the task',
+    '- [ ] #2 Prettier and barrels lint pass on the diff',
+    '',
+  ].join('\n');
+
+  it('parses acceptance criteria stripped of their "- [ ] #N " prefix', () => {
+    assert.deepEqual(parseAcceptanceCriteria(realTaskView), ['First AC', 'Second AC']);
+  });
+
+  it('parses Definition of Done items the same way', () => {
+    assert.deepEqual(parseDefinitionOfDone(realTaskView), [
+      'Scoped tests pass with the command declared in the task',
+      'Prettier and barrels lint pass on the diff',
+    ]);
+  });
+
+  it('returns an empty array when a section heading is absent', () => {
+    assert.deepEqual(parseAcceptanceCriteria('Task T-1\n\nNo sections here.\n'), []);
+  });
+});
+
+describe('parseLastComment', () => {
+  // Verbatim `backlog task view --plain` shape for the Comments section (captured 2026-09-06):
+  // heading, dashed underline, then `#N - <timestamp> (UTC)` followed by the comment body.
+  const withComments = [
+    'Comments:',
+    '--------------------------------------------------',
+    '#1 - 2026-09-06 14:10 (UTC)',
+    'First attempt failed on a flaky test.',
+    '',
+    '#2 - 2026-09-06 14:17 (UTC)',
+    'Push failed: no disk space. Please retry.',
+    '',
+  ].join('\n');
+
+  it('returns the most recent comment body', () => {
+    assert.equal(parseLastComment(withComments), 'Push failed: no disk space. Please retry.');
+  });
+
+  it('returns null when there is no Comments section', () => {
+    assert.equal(parseLastComment('Task T-1\n\nNo comments here.\n'), null);
+  });
+
+  it('keeps a multi-paragraph comment whole, stopping only at the next comment heading', () => {
+    const multiline = [
+      'Comments:',
+      '--------------------------------------------------',
+      '#1 - 2026-09-06 14:10 (UTC)',
+      'Old comment.',
+      '',
+      '#2 - 2026-09-06 14:17 (UTC)',
+      'El scope check falló:',
+      '',
+      '- backend/src/x.ts no estaba declarado',
+      '- frontend/src/y.ts tampoco',
+      '',
+      'Declara ambos en "Files to touch" antes de reencolar.',
+      '',
+    ].join('\n');
+    assert.equal(
+      parseLastComment(multiline),
+      [
+        'El scope check falló:',
+        '',
+        '- backend/src/x.ts no estaba declarado',
+        '- frontend/src/y.ts tampoco',
+        '',
+        'Declara ambos en "Files to touch" antes de reencolar.',
+      ].join('\n'),
+    );
+  });
+
+  it('stops at the next --plain section heading when Comments is not the last block', () => {
+    const withTrailingSection = [
+      'Comments:',
+      '--------------------------------------------------',
+      '#1 - 2026-09-06 14:10 (UTC)',
+      'Cuerpo del comentario.',
+      '',
+      'Implementation Notes:',
+      '--------------------------------------------------',
+      'No forma parte del comentario.',
+      '',
+    ].join('\n');
+    assert.equal(parseLastComment(withTrailingSection), 'Cuerpo del comentario.');
+  });
+
+  it('stops a multi-paragraph comment at the NEXT comment heading, never swallowing it', () => {
+    const multiline = [
+      'Comments:',
+      '--------------------------------------------------',
+      '#1 - 2026-09-06 14:10 (UTC)',
+      'Primer párrafo.',
+      '',
+      'Segundo párrafo.',
+      '',
+      '#2 - 2026-09-06 14:17 (UTC)',
+      'El último.',
+      '',
+    ].join('\n');
+    assert.equal(parseLastComment(multiline), 'El último.');
+  });
+});
+
+// ── assembleExecutorPrompt ──────────────────────────────────────────────────────
+
+describe('assembleExecutorPrompt', () => {
+  const baseInput = {
+    task: 'Task T-42: fix session expiry redirect\nFile: /main/checkout/.backlog/tasks/t-42 - fix.md',
+    slotPath: '/main/checkout/.claude/worktrees/dispatch-a',
+    mainCheckoutPath: '/main/checkout',
+    hookOutputs: {
+      promptContext: '# Skills relevantes\n- foo',
+      fileRules: [{ filePath: 'a.ts', context: 'BR-1 — ...' }],
+    },
+    skillPaths: ['.claude/skills/catalyst-langs/SKILL.md'],
+    contract: 'CONTRACT VERBATIM TEXT',
+    envelope: {
+      allowedFiles: ['a.ts'],
+      forbiddenPaths: ['o-auth/', 'iam/'],
+      testCommand: 'pnpm --filter backend test -- a.spec.ts',
+      taskId: 'T-42',
+      editCommand: 'npx --loglevel=error tsx /repo/scripts/backlog/worker-edit.ts T-42',
+      acceptanceCriteria: [
+        { index: 1, text: 'Expired-token requests redirect to /login' },
+        { index: 2, text: 'The redirect preserves the original path' },
+      ],
+      dod: ['Scoped tests pass'],
+    },
+  };
+
+  // Measured defect (T-5, 2026-09-07): the executor's FIRST `Edit` targeted the MAIN checkout's
+  // copy of the file, not its slot's — it had inferred the repository root from the `File:` line of
+  // the task block, which names the board file in the main checkout. `Edit(./**)` denied it (the cwd
+  // is the slot), so the attempt spent turns on a denial for a path nothing had told it about:
+  // nothing in the envelope named its working directory at all.
+  describe('the working-directory block', () => {
+    it('names the slot as the working directory, before anything else the prompt says', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+
+      const slotIdx = prompt.indexOf(baseInput.slotPath);
+      assert.ok(slotIdx >= 0, 'the slot path is nowhere in the prompt');
+      assert.ok(
+        slotIdx < prompt.indexOf(baseInput.hookOutputs.promptContext),
+        'it must come before the hook block',
+      );
+      assert.match(prompt, /every path in this task is relative to it/i);
+    });
+
+    it('forbids the main checkout by name, and says the board path in the task lives there', () => {
+      // Whitespace-collapsed: the block is hard-wrapped prose, and a line break must not decide
+      // whether this assertion holds.
+      const prompt = assembleExecutorPrompt(baseInput).replace(/\s+/g, ' ');
+
+      assert.ok(prompt.includes(baseInput.mainCheckoutPath));
+      assert.match(prompt, /never read, edit or run anything there/i);
+      assert.match(prompt, /do not treat its directory as your repository root/i);
+    });
+  });
+
+  it('renders the six blocks in order: task, working directory, hook outputs, skill paths, contract, envelope', () => {
+    const prompt = assembleExecutorPrompt(baseInput);
+
+    const taskIdx = prompt.indexOf(baseInput.task);
+    const hookIdx = prompt.indexOf(baseInput.hookOutputs.promptContext);
+    const fileRuleIdx = prompt.indexOf('BR-1 — ...');
+    const skillIdx = prompt.indexOf(baseInput.skillPaths[0]);
+    const contractIdx = prompt.indexOf(baseInput.contract);
+    const envelopeIdx = prompt.indexOf(baseInput.envelope.testCommand);
+
+    assert.ok(taskIdx >= 0, 'task text missing');
+    assert.ok(hookIdx > taskIdx, 'hook output block out of order');
+    assert.ok(fileRuleIdx > taskIdx, 'per-file BR block out of order');
+    assert.ok(skillIdx > hookIdx && skillIdx > fileRuleIdx, 'skill paths block out of order');
+    assert.ok(contractIdx > skillIdx, 'contract block out of order');
+    assert.ok(envelopeIdx > contractIdx, 'envelope block out of order');
+  });
+
+  it('includes every envelope field', () => {
+    const prompt = assembleExecutorPrompt(baseInput);
+    assert.ok(prompt.includes('o-auth/'));
+    assert.ok(prompt.includes('iam/'));
+    assert.ok(prompt.includes('Expired-token requests redirect to /login'));
+    assert.ok(prompt.includes('Scoped tests pass'));
+  });
+
+  // J3: nothing in the prompt ever told the worker to tick anything, yet the pre-PR gate FAILS the
+  // attempt on any unchecked criterion. The whole lane was one instruction short of ever passing.
+  describe('the acceptance-criteria ticking instructions (J3)', () => {
+    it('renders each criterion with the #N index --check-ac actually takes', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.ok(prompt.includes('#1 Expired-token requests redirect to /login'));
+      assert.ok(prompt.includes('#2 The redirect preserves the original path'));
+    });
+
+    // K1: the raw `backlog task edit` is not granted any more — a prefix rule could not narrow the
+    // flags that followed it. The prompt must print the wrapper the launch actually granted, or the
+    // worker spends its turns on a command it is denied.
+    it('gives the exact wrapper command, scoped to the task id', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.ok(prompt.includes(`${baseInput.envelope.editCommand} --check-ac <N>`));
+      assert.ok(
+        !prompt.includes('backlog task edit T-42'),
+        'the ungranted raw CLI write must not be advertised',
+      );
+    });
+
+    // L6: the read is the same wrapper (`--view`). The separate `Bash(backlog task view <id>:*)`
+    // grant is gone, so a prompt still advertising the raw read sends the worker into a denial.
+    it('tells the worker to read its own task through the wrapper --view', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.ok(prompt.includes(`${baseInput.envelope.editCommand} --view`));
+      assert.ok(
+        !prompt.includes('backlog task view T-42'),
+        'the ungranted raw CLI read must not be advertised',
+      );
+    });
+
+    it('names the evidence flags, so a tick is never a bare claim', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.ok(prompt.includes('--append-notes'));
+    });
+
+    it('says the close BLOCKS the attempt when a criterion is left unchecked', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.match(prompt, /unchecked/i);
+      assert.match(prompt, /block/i);
+    });
+
+    // K1: "anything else is denied" was false — the granted prefix ended at the first flag, so a
+    // trailing `--status` was permitted. The wrapper is what refuses it, and the prompt says so
+    // rather than repeating a guarantee the permission layer never gave.
+    it('names the wrapper as the barrier instead of claiming everything else is denied', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.match(prompt, /worker-edit\.ts/);
+      assert.ok(!/anything else is denied/i.test(prompt));
+    });
+
+    it('forbids the flags that would let the worker re-status itself or rewrite its criteria', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      for (const flag of ['--status', '--ac', '--title']) {
+        assert.ok(prompt.includes(flag), `the envelope must name ${flag} as forbidden`);
+      }
+    });
+  });
+
+  it('omits the retry section when no retry is given', () => {
+    const prompt = assembleExecutorPrompt(baseInput);
+    assert.ok(!/Retry/i.test(prompt));
+  });
+
+  it('includes the prior Blocked comment and reviewer findings on a retry, after the envelope', () => {
+    const prompt = assembleExecutorPrompt({
+      ...baseInput,
+      retry: {
+        blockedComment: 'Push failed: no disk space',
+        reviewerFindings: 'Missing null check on line 42',
+      },
+    });
+
+    const envelopeIdx = prompt.indexOf(baseInput.envelope.testCommand);
+    const blockedIdx = prompt.indexOf('Push failed: no disk space');
+    const findingsIdx = prompt.indexOf('Missing null check on line 42');
+
+    assert.ok(blockedIdx > envelopeIdx, 'retry block out of order');
+    assert.ok(findingsIdx > blockedIdx);
+  });
+
+  it('renders "(none)" placeholders when hook outputs and skill paths are both empty', () => {
+    const prompt = assembleExecutorPrompt({
+      ...baseInput,
+      hookOutputs: { promptContext: null, fileRules: [] },
+      skillPaths: [],
+    });
+    assert.ok(prompt.includes('(none)'));
+  });
+
+  // T-3: measured — a worker piped the declared test command through `grep`/`tail` to trim
+  // ts-jest noise and was DENIED: `Bash(<test command>:*)` grants only the declared command, and
+  // Claude Code evaluates each segment of a compound line separately, so the piped segments carry
+  // no permission of their own. Filtering the output bought nothing anyway — the close runs the
+  // SAME bare command again afterwards. Nothing in the envelope said any of this.
+  describe('the bare-test-command instruction (T-3)', () => {
+    it('tells the worker to run the declared test command with no pipes, &&, redirections or cd', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      assert.match(prompt, /EXACTLY as written/);
+      assert.match(prompt, /no pipes, no `&&`, no redirections, no `cd`/);
+    });
+
+    it('places the instruction next to the scoped test command it governs', () => {
+      const prompt = assembleExecutorPrompt(baseInput);
+      const testCommandIdx = prompt.indexOf(baseInput.envelope.testCommand);
+      const instructionIdx = prompt.indexOf('EXACTLY as written');
+      assert.ok(
+        testCommandIdx >= 0 && instructionIdx > testCommandIdx,
+        'instruction must follow the test command',
+      );
+    });
+  });
+});
+
+// ── G16: the frontier lane's retry needs the prior failure too ────────────────
+
+describe('buildFrontierPrompt', () => {
+  it('is the bare deterministic entry on the first attempt', () => {
+    assert.equal(buildFrontierPrompt('T-12'), 'trabajemos T-12');
+  });
+
+  it('appends the prior Blocked comment and reviewer findings on a retry', () => {
+    const prompt = buildFrontierPrompt('T-12', {
+      blockedComment: 'scope-check-failed: tocó packages/cli/',
+      reviewerFindings: 'VERDICT: fail — el test no falla si rompes la lógica',
+    });
+
+    assert.ok(prompt.startsWith('trabajemos T-12'));
+    assert.ok(prompt.includes('scope-check-failed: tocó packages/cli/'));
+    assert.ok(prompt.includes('el test no falla si rompes la lógica'));
+  });
+
+  it('reuses the same retry block the local lane renders, not a second copy of it', () => {
+    const retry = { blockedComment: 'motivo previo' };
+    assert.ok(buildFrontierPrompt('T-12', retry).includes(renderRetryBlock(retry)));
+  });
+});
+
+// ── T-8, last point: the parent's one automated close attempt ────────────────
+//
+// A Complex parent's own work is the decomposition plus, once every subtask has merged into
+// `task/<parentId>`, a FINAL close — see `parent.ts`'s rules 4/5 for the "exactly once" derivation
+// that gets it dispatched. `isParentCloseAttempt` re-derives, at LAUNCH time, whether THIS dispatch
+// is that close attempt (rather than threading a flag through from the maintenance pass that
+// enqueued it): the condition is cheap, pure, and idempotent to recompute, and re-deriving it here
+// means a RETRY of the same close attempt (the human release flow, section 10 of the skill) is
+// recognised exactly the same way as the first dispatch, with no separate "why was this launched"
+// state to keep in sync.
+
+const board = (tasks: Task[]): Board => ({
+  tasksById: Object.fromEntries(tasks.map((task) => [task.id, task])),
+});
+
+describe('isParentCloseAttempt', () => {
+  it('is true for a Complex parent whose children are all Done', () => {
+    const parent = baseTask({ id: 'T-10', tier: TIER.COMPLEX });
+    const child = baseTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE });
+    assert.equal(isParentCloseAttempt(parent, board([parent, child])), true);
+  });
+
+  it('is false while any child is still short of Done', () => {
+    const parent = baseTask({ id: 'T-10', tier: TIER.COMPLEX });
+    const done = baseTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE });
+    const inProgress = baseTask({
+      id: 'T-12',
+      parentId: 'T-10',
+      status: TASK_STATUS.IN_PROGRESS,
+    });
+    assert.equal(isParentCloseAttempt(parent, board([parent, done, inProgress])), false);
+  });
+
+  it('is false for a task with no children — it is not a parent at all', () => {
+    const task = baseTask({ id: 'T-10', tier: TIER.COMPLEX });
+    assert.equal(isParentCloseAttempt(task, board([task])), false);
+  });
+
+  it('is false for a non-Complex parent, even with every child Done', () => {
+    const parent = baseTask({ id: 'T-10', tier: TIER.MEDIUM });
+    const child = baseTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE });
+    assert.equal(isParentCloseAttempt(parent, board([parent, child])), false);
+  });
+
+  it('is false for a parent carrying no tier at all (an untriaged board entry)', () => {
+    const parent = baseTask({ id: 'T-10', tier: undefined });
+    const child = baseTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE });
+    assert.equal(isParentCloseAttempt(parent, board([parent, child])), false);
+  });
+
+  // Defect 11 (2026-09-08): for a three-level tree, a child that is ITSELF a parent can be
+  // EFFECTIVELY done (parent.ts's effectiveStatus, recomputed fresh from ITS OWN children) one
+  // maintenance pass before its own literal board status is written back — parentIds sorts
+  // lexicographically, so a great-parent like 'T-10' is recomputed before a middle parent like
+  // 'T-10.1'. The default (no override) still reads the literal field, for a caller with nothing
+  // better; a caller that CAN answer "effectively done" must be able to override it.
+  it("defaults to a child's literal status, but a caller can override it with an effective check", () => {
+    const parent = baseTask({ id: 'T-10', tier: TIER.COMPLEX });
+    // A middle parent whose own children are all Done and whose own PR merged is EFFECTIVELY Done,
+    // even though its literal board status still reads In Progress this same pass.
+    const middle = baseTask({
+      id: 'T-10.1',
+      parentId: 'T-10',
+      tier: TIER.COMPLEX,
+      status: TASK_STATUS.IN_PROGRESS,
+    });
+    const boardState = board([parent, middle]);
+
+    assert.equal(
+      isParentCloseAttempt(parent, boardState),
+      false,
+      'the default literal check must not fabricate a Done it cannot see on the board',
+    );
+    assert.equal(
+      isParentCloseAttempt(parent, boardState, (child) => child.id === 'T-10.1'),
+      true,
+      'an injected effective-status check must decide instead of the literal field',
+    );
+  });
+});
+
+describe('buildParentCloseAttemptPrompt', () => {
+  it('is deterministic — the SAME fixed brief regardless of the task id', () => {
+    const promptA = buildParentCloseAttemptPrompt('T-10');
+    const promptB = buildParentCloseAttemptPrompt('T-99').replaceAll('T-99', 'T-10');
+    assert.equal(promptA, promptB);
+  });
+
+  it('opens with the deterministic entry the harness Task Gate recognises', () => {
+    assert.ok(buildParentCloseAttemptPrompt('T-10').startsWith('trabajemos T-10'));
+  });
+
+  it('states plainly this is NOT the task-derived brief — the description below is not the job', () => {
+    const prompt = buildParentCloseAttemptPrompt('T-10');
+    assert.match(prompt, /brief fijo/i);
+    assert.match(prompt, /no.*(implementación nueva|new implementation)/i);
+  });
+
+  it('names the accumulated diff on the parent branch as what gets reviewed', () => {
+    assert.match(buildParentCloseAttemptPrompt('T-10'), /task\/T-10/);
+  });
+
+  it('instructs ticking tasks.md with evidence, never writing new implementation', () => {
+    const prompt = buildParentCloseAttemptPrompt('T-10');
+    assert.match(prompt, /tasks\.md/);
+    assert.match(prompt, /evidencia|evidence/i);
+  });
+
+  it('routes any confirmed finding to needs-guidance instead of a self-fix (no new implementation allowed)', () => {
+    const prompt = buildParentCloseAttemptPrompt('T-10');
+    assert.match(prompt, /needs-guidance/);
+  });
+
+  it('appends the retry block on a retry, exactly like the standard frontier prompt', () => {
+    const retry = { blockedComment: 'scope-check-failed: tocó packages/cli/' };
+    const prompt = buildParentCloseAttemptPrompt('T-10', retry);
+    assert.ok(prompt.includes(renderRetryBlock(retry)));
+  });
+
+  it('has no retry block on a first attempt', () => {
+    assert.ok(!buildParentCloseAttemptPrompt('T-10').includes('Retry — this attempt continues'));
+  });
+});
+
+// ── buildFrontierAddendum (L1) ────────────────────────────────────────────────
+//
+// The frontier worker used to be launched with NO system-prompt file at all: it read `CLAUDE.md`
+// through the harness, which says nothing about the dispatcher's wrapper — so it reached for
+// `backlog task edit`, was denied, and left every acceptance criterion unticked. The close's AC gate
+// then failed the attempt, every time, for a command nobody had told it about.
+
+describe('buildFrontierAddendum', () => {
+  const template = [
+    '# Dispatched worker',
+    '',
+    'The dispatcher already set {{TASK_ID}} to `In Progress`; never write the task status.',
+    '',
+    'Tick with `{{WORKER_EDIT_COMMAND}} --check-ac <N>`, read with `{{WORKER_EDIT_COMMAND}} --view`.',
+    '',
+    'You work in {{SLOT_PATH}}; {{MAIN_CHECKOUT_PATH}} is not yours.',
+  ].join('\n');
+
+  const rendered = (): string =>
+    buildFrontierAddendum({
+      template,
+      taskId: 'T-42',
+      mainCheckoutPath: '/Users/carlos/repo',
+      slotPath: '/Users/carlos/repo/.claude/worktrees/dispatch-b',
+    });
+
+  it('renders the wrapper command bound to this attempt task id', () => {
+    assert.ok(
+      rendered().includes('/Users/carlos/repo/scripts/backlog/worker-edit.ts T-42 --check-ac <N>'),
+    );
+  });
+
+  it('substitutes every placeholder — a leftover would reach the worker as literal text', () => {
+    assert.ok(!/\{\{[A-Z_]+\}\}/.test(rendered()));
+  });
+
+  it('names the task id wherever the template asked for it', () => {
+    assert.match(rendered(), /T-42 to `In Progress`/);
+  });
+
+  // Same measured defect as the local envelope's working-directory block: the worker had no way to
+  // know which of the two checkouts it was in, and inferred the wrong one from the task text.
+  it('renders the slot it works in and the main checkout it must not touch', () => {
+    assert.ok(rendered().includes('/Users/carlos/repo/.claude/worktrees/dispatch-b'));
+    assert.ok(rendered().includes('/Users/carlos/repo is not yours'));
+  });
+
+  // The whole point of the addendum: the worker must never touch its own status, and the wrapper
+  // refuses `--status` anyway. Advertising it would spend turns on a denial.
+  it('never mentions --status', () => {
+    assert.ok(!rendered().includes('--status'));
+  });
+
+  it('refuses a template with an unknown placeholder rather than shipping it verbatim', () => {
+    assert.throws(
+      () =>
+        buildFrontierAddendum({
+          template: 'see {{BRANCH_NAME}}',
+          taskId: 'T-42',
+          mainCheckoutPath: '/repo',
+          slotPath: '/repo/.claude/worktrees/dispatch-b',
+        }),
+      /BRANCH_NAME/,
+    );
+  });
+});
+
+// The REAL template, not a synthetic one: the builder can only refuse placeholders it does not
+// know, so everything else about the shipped file — that it renders with no leftover `{{...}}`, and
+// that it never advertises a flag the wrapper refuses — is only pinned here.
+describe('the shipped frontier addendum template', () => {
+  const rendered = buildFrontierAddendum({
+    template: fs.readFileSync(
+      path.join(
+        import.meta.dirname,
+        '..',
+        '..',
+        '.claude',
+        'skills',
+        'catalyst-backlog',
+        'frontier-worker-addendum.md',
+      ),
+      'utf8',
+    ),
+    taskId: 'T-7',
+    mainCheckoutPath: '/main/checkout',
+    slotPath: '/main/checkout/.claude/worktrees/dispatch-b',
+  });
+
+  it('renders with no placeholder left behind', () => {
+    assert.ok(!/\{\{/.test(rendered), 'a leftover placeholder reaches the worker as literal text');
+  });
+
+  it('carries the wrapper command bound to this task, and its four flags', () => {
+    for (const flag of ['--check-ac', '--append-notes', '--plan', '--view']) {
+      assert.ok(
+        rendered.includes(`/main/checkout/scripts/backlog/worker-edit.ts T-7 ${flag}`),
+        `missing ${flag}`,
+      );
+    }
+  });
+
+  // The addendum exists to stop the worker touching its own status. Naming the flag — even to refuse
+  // it — puts the string in front of a model that is looking for a way to close its task.
+  // `--title`/`--desc` are deliberately EXCLUDED from this list: `--subtask` legitimately accepts
+  // them (see the next `it`), so they are no longer a flag the wrapper refuses outright — only a
+  // flag it refuses when it rewrites the worker's OWN task, which the addendum's `--subtask`
+  // example never does (its `-p`/target is the new subtask, not T-7 itself).
+  it('never names a flag the wrapper refuses', () => {
+    for (const refused of ['--status', '--acceptance-criteria', '--dod']) {
+      assert.ok(!rendered.includes(refused), `the addendum must not advertise ${refused}`);
+    }
+  });
+
+  // `--subtask` is the headless split's only board write (`catalyst-backlog/SKILL.md` §6): the
+  // addendum must both name it and forbid the one thing that would smuggle a real board mutation
+  // past guard 1 — passing `--parent` instead of relying on the wrapper's own binding.
+  it('documents --subtask and forbids --parent', () => {
+    assert.ok(
+      rendered.includes(`/main/checkout/scripts/backlog/worker-edit.ts T-7 --subtask`),
+      'missing --subtask example',
+    );
+    assert.match(rendered, /Never pass `--parent`/);
+  });
+
+  it('says the dispatcher owns the status and that a human gate ends the run', () => {
+    assert.match(rendered, /Never write the task status/);
+    assert.match(rendered, /status: needs-guidance/);
+  });
+
+  it('names the slot as the working directory and forbids the main checkout', () => {
+    // Whitespace-collapsed for the same reason as the local envelope's block: hard-wrapped prose.
+    const flat = rendered.replace(/\s+/g, ' ');
+    assert.ok(flat.includes('/main/checkout/.claude/worktrees/dispatch-b'));
+    assert.match(flat, /never read, edit or run anything there/i);
+    assert.match(flat, /do not treat its directory as your repository root/i);
+  });
+
+  // T-3: same measured defect as the local envelope (see prompt.test.ts's "bare-test-command"
+  // block above) — a frontier orchestrator has no envelope block naming its test command at all,
+  // so the instruction has to live in the addendum's static prose instead.
+  it('tells the worker to run its test command with no pipes, &&, redirections or cd', () => {
+    assert.match(rendered, /EXACTLY as written/);
+    assert.match(rendered, /no pipes, no `&&`, no redirections, no `cd`/);
+  });
+
+  // T-3: measured — the frontier worker read the skills describing `path:sdd` and then
+  // implemented directly, skipping the SDD flow entirely: no `openspec/changes/<name>` was ever
+  // created. `CLAUDE.md`'s Medium-tier rule ("RECOMMEND SDD and let the user choose") does not
+  // resolve headless — there is no user to ask — so the addendum has to say the label decides.
+  it('says the path: label is binding and names both branches', () => {
+    const flat = rendered.replace(/\s+/g, ' ');
+    assert.match(flat, /`path:`.*binding/i);
+    assert.match(flat, /path:sdd.*opsx:propose.*opsx:apply/i);
+    assert.match(flat, /path:direct.*direct path/i);
+    assert.match(flat, /needs-guidance/);
+  });
+
+  // T-3: the same run edited `backend/src/@app/iam/**` (a security surface) with no
+  // `/security-review` pass — the root `CLAUDE.md`'s security gate has no person to trigger it
+  // headless either.
+  it('requires a /security-review pass before finishing when the diff touches the security surface', () => {
+    assert.match(rendered, /\/security-review/);
+    assert.match(rendered, /o-auth\//);
+    assert.match(rendered, /iam\//);
+  });
+
+  // T-6: measured four `--subtask` invocations out of five DENIED by the Bash permission matcher
+  // for `--desc $'…\n…'` — `$'` reads to it as a `$` expansion, not a quoted literal. The addendum
+  // may still WARN about that quoting in prose (hence no blanket "no $'" assertion) — what it must
+  // never do again is MODEL it as the copy-paste example.
+  it("never models --desc \$'…' as the copy-paste example, and points to --desc-file instead", () => {
+    assert.ok(
+      !rendered.includes("--desc $'"),
+      'the addendum must not demonstrate the ANSI-C quoting that gets denied',
+    );
+    assert.match(rendered, /--desc-file/);
+  });
+
+  // T-6: the split subtasks of a Complex task's SDD design phase implement an EXISTING OpenSpec
+  // change — a subtask labelled path:sdd must run /opsx:apply on it, never re-propose it.
+  it('says path:sdd on an existing OpenSpec change means /opsx:apply, never a second /opsx:propose', () => {
+    const flat = rendered.replace(/\s+/g, ' ');
+    assert.match(flat, /openspec\/changes\/<name>/);
+    assert.match(flat, /opsx:apply <name>/);
+    assert.match(flat, /never a second `?\/opsx:propose/i);
+  });
+
+  // T-25: `CLAUDE.md`'s generated Backlog block orders EVERY reader to reach the board through the
+  // Backlog.md MCP server — `backlog://workflow/overview`, `backlog.get_backlog_instructions()` —
+  // and the frontier worker reads `CLAUDE.md` (no `--bare` on this lane). Since T-24 it launches
+  // with `--strict-mcp-config`, so neither handler exists in its session: the block sends it after
+  // a tool that cannot answer, and the cost is turns burnt on it, or a `needs-guidance` that is
+  // none. The local lane cancels the block in its own system prompt ("no MCP server loads for
+  // you"); this addendum is the only place the frontier lane can. The generated block itself stays
+  // untouched — it is true for the interactive sessions that DO load the server.
+  it('cancels the CLAUDE.md Backlog MCP block, naming both handlers it must not attempt', () => {
+    const flat = rendered.replace(/\s+/g, ' ');
+    assert.match(flat, /--strict-mcp-config/);
+    assert.match(flat, /backlog:\/\/workflow\/overview/);
+    assert.match(flat, /backlog\.get_backlog_instructions\(\)/);
+    assert.match(flat, /does not apply to you/i);
+  });
+});