@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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

@@ -0,0 +1,622 @@
+/**
+ * prompt.ts — assembles the local-lane executor's user prompt: the six ordered blocks from
+ * design.md's "Executor prompt contract" (task text, the working directory block, precomputed
+ * hook outputs, injected skill paths, the delegation contract verbatim, the operating envelope —
+ * with the prior `Blocked` comment and reviewer findings appended on a retry), plus the pieces that
+ * feed them
+ * (`computeHookOutputs`, `matchSkillPaths`, `extractDelegationContract`).
+ *
+ * Implements `specs/headless-harness-execution/spec.md` — "Executor startup contract". Every
+ * function here is pure or takes its side effects injected (`HookRunners`), matching the rest of
+ * `scripts/backlog/`'s design (see launch.ts, close.ts): `dispatch.ts` wires the real hook
+ * subprocesses and calls these functions from its `buildPrompt` callback for `lane:local` tasks
+ * only — a `lane:frontier` task keeps the minimal "trabajemos <id>" entry prompt (spec:
+ * "Headless orchestrator entry"), which this module has no part in.
+ */
+import {
+  ACCEPTANCE_CRITERIA_HEADING,
+  DEFINITION_OF_DONE_HEADING,
+  parseChecklistItems,
+} from './task-view.js';
+import { TASK_STATUS, TIER, type Board, type Task } from './types.js';
+import { workerEditCommand } from './worker-edit.js';
+
+// ── Hook precompute (Phase 1 spike 1.3's confirmed approach) ──────────────────
+
+export interface HookOutputs {
+  /** `inject-prompt-context.ts`'s combined stdout for the task's derived prompt text, or `null`
+   * when the hook emitted nothing (no matching BR/HR/skill). */
+  promptContext: string | null;
+  /** One entry per declared file whose `business-rules-injector.ts` output was non-blank. */
+  fileRules: Array<{ filePath: string; context: string }>;
+}
+
+/**
+ * The two hook scripts driven here take side effects only through this interface — real
+ * subprocess spawning (`tsx .claude/hooks/inject-prompt-context.ts` etc. with synthetic stdin, per
+ * Phase 1 spike 1.3) is `dispatch.ts`'s job, so this module unit-tests without a real filesystem
+ * or child process. `cwd` is intentionally NOT a parameter here: each runner already knows which
+ * directory to run the hook against (the dispatcher binds it when it builds the real runners for
+ * a specific dispatched attempt), matching this module's `(runners, task, declaredFiles)` shape.
+ */
+export interface HookRunners {
+  /** Deletes `.claude/.cache/br-injected.json` — Phase 1 spike 1.3's finding: without this, a
+   * rule injected for a previous task on this slot silently fails to surface again. */
+  resetInjectorCache: () => void;
+  /** Drives `inject-prompt-context.ts` with synthetic stdin `{ prompt, cwd }`; returns its raw
+   * stdout (may be empty). */
+  runInjectPromptContext: (prompt: string) => string;
+  /** Drives `business-rules-injector.ts` with the PreToolUse envelope
+   * `{ tool_name: 'Edit', tool_input: { file_path }, cwd }` for one declared file; returns the
+   * parsed `additionalContext` string (may be empty). */
+  runBusinessRulesInjector: (filePath: string) => string;
+}
+
+/**
+ * The representative "prompt" text fed to `inject-prompt-context.ts` for a dispatched task: its
+ * bounded context and the files it declares. That is the whole signal the hook needs — it resolves
+ * the BR, HR and skill blocks by BC and by file path, which is the only reason this text exists.
+ *
+ * The `title` the `Task` shape carries is deliberately left OUT. It is prose written for a human
+ * reader, it matches no rule catalog and no skill trigger by design, and adding it would only feed
+ * the matcher words that resolve nothing. Block 1 of the executor envelope already gives the worker
+ * the whole task view, title included, in the format the close reads back.
+ *
+ * The task ID is deliberately NOT in it. It used to lead the string, and the hook matched its own
+ * `task_prefix` against it and injected a whole task block — the same task text the executor
+ * prompt's block 1 already carries verbatim, in the format the close reads. The worker got its task
+ * twice, and the second copy came with the interactive Task Gate framing it has no business walking.
+ * The frontier lane still gets that block, and should: there the hook runs against the REAL prompt
+ * (`trabajemos <id>`), which is the case the block was built for.
+ *
+ * Exported so `computeHookOutputs`'s expected input is independently testable.
+ */
+export function buildHookPromptText(task: Task, declaredFiles: readonly string[]): string {
+  return [task.bc ?? '', ...declaredFiles].filter((part) => part.length > 0).join(' ');
+}
+
+/**
+ * Computes the executor prompt's block 2: resets the injector cache FIRST (so a rule injected for
+ * a previous attempt on this slot cannot suppress itself for this one), then drives
+ * `inject-prompt-context.ts` once against the task's derived prompt text and
+ * `business-rules-injector.ts` once per declared file, dropping blank results.
+ */
+export function computeHookOutputs(
+  runners: HookRunners,
+  task: Task,
+  declaredFiles: readonly string[],
+): HookOutputs {
+  runners.resetInjectorCache();
+
+  const rawPromptContext = runners.runInjectPromptContext(buildHookPromptText(task, declaredFiles));
+  const promptContext = rawPromptContext.trim().length > 0 ? rawPromptContext : null;
+
+  const fileRules = declaredFiles
+    .map((filePath) => ({ filePath, context: runners.runBusinessRulesInjector(filePath) }))
+    .filter((entry) => entry.context.trim().length > 0);
+
+  return { promptContext, fileRules };
+}
+
+// ── Skill path matching (block 3) ──────────────────────────────────────────────
+
+export interface SkillTriggerLike {
+  name: string;
+  path: string;
+  triggers: string[];
+}
+
+export interface SkillTriggerIndexLike {
+  skills: SkillTriggerLike[];
+}
+
+/**
+ * Matches `.claude/skills-triggers-index.json` entries against the task's declared files, the
+ * same substring-of-a-trigger predicate `inject-prompt-context.ts` uses against prompt text (see
+ * its `matchedKeywords`) — here the "text" being scanned is the declared file paths themselves,
+ * since a dispatched task has no free-text prompt of its own. Case-insensitive; returns each
+ * matched skill's path at most once, sorted for a deterministic prompt.
+ */
+export function matchSkillPaths(
+  declaredFiles: readonly string[],
+  triggersIndex: SkillTriggerIndexLike,
+): string[] {
+  const haystack = declaredFiles.join(' ').toLowerCase();
+  const matched = new Set<string>();
+  for (const skill of triggersIndex.skills) {
+    const hit = skill.triggers.some((trigger) => haystack.includes(trigger.toLowerCase()));
+    if (hit) {
+      matched.add(skill.path);
+    }
+  }
+  return [...matched].sort();
+}
+
+// ── Delegation contract extraction (block 4) ───────────────────────────────────
+
+const CONTRACT_SECTION_HEADING = /^## 3\. Injectable contract blocks.*$/m;
+
+/**
+ * Extracts the fenced code block under `catalyst-delegation/SKILL.md`'s
+ * "## 3. Injectable contract blocks (copy verbatim into the prompt)" heading — the two mandatory
+ * blocks (`skill_resolution`/`status` reporting fields, plus the escalation protocol) every
+ * code-touching delegation must carry, per that skill's own contract. Reads the heading and fence
+ * mechanically so the executor prompt can never drift from the maintained source of truth in the
+ * skill file.
+ */
+export function extractDelegationContract(skillMdText: string): string {
+  const headingMatch = CONTRACT_SECTION_HEADING.exec(skillMdText);
+  if (!headingMatch) {
+    throw new Error(
+      'extractDelegationContract: section 3 ("Injectable contract blocks") heading not found',
+    );
+  }
+  const afterHeading = skillMdText.slice(headingMatch.index + headingMatch[0].length);
+  const fenceMatch = /```[^\n]*\n([\s\S]*?)```/.exec(afterHeading);
+  if (!fenceMatch) {
+    throw new Error('extractDelegationContract: no fenced code block found under section 3');
+  }
+  return fenceMatch[1].replace(/\n$/, '');
+}
+
+// ── Envelope extraction from `backlog task view --plain` text ─────────────────
+//
+// `Task` (types.ts) has no structured `acceptanceCriteria`/`dod` fields — both only exist today as
+// `backlog task create --ac/--dod` checklist items. The `--plain` checklist format itself is owned
+// by `task-view.ts` (one parser for one format, `parseTestCommand` included); the two readers below
+// just drop the checked state, which an executor prompt has no use for.
+
+/** Extracts `--ac`-created acceptance criteria from `backlog task view --plain` output. */
+export function parseAcceptanceCriteria(taskText: string): string[] {
+  return parseChecklistItems(taskText, ACCEPTANCE_CRITERIA_HEADING).map((item) => item.text);
+}
+
+/**
+ * The same criteria WITH their `#N`, for the operating envelope. The reviewer only needs the texts
+ * (it judges, it does not tick); the executor needs the index, because that is the argument
+ * `backlog task edit --check-ac` takes.
+ */
+export function parseIndexedAcceptanceCriteria(
+  taskText: string,
+): { index: number; text: string }[] {
+  return parseChecklistItems(taskText, ACCEPTANCE_CRITERIA_HEADING).map((item) => ({
+    index: item.index,
+    text: item.text,
+  }));
+}
+
+/** Extracts `--dod`-created Definition of Done items from `backlog task view --plain` output. */
+export function parseDefinitionOfDone(taskText: string): string[] {
+  return parseChecklistItems(taskText, DEFINITION_OF_DONE_HEADING).map((item) => item.text);
+}
+
+const COMMENTS_HEADING = /^Comments:\s*\n-+\s*\n/m;
+const COMMENT_ENTRY_HEADING = /^#\d+ - .+\(UTC\)$/m;
+/** Any other `--plain` section heading (`Implementation Notes:` + its dashed underline). */
+const NEXT_SECTION_HEADING = /\n[A-Z][^\n:]*:\n-{5,}\n/;
+
+/**
+ * Extracts the most recent comment's body from `backlog task view --plain` output's "Comments:"
+ * section — the retry path's source for "the prior `Blocked` comment" (design.md's Executor
+ * prompt contract, block 5). `null` when the task has no comments yet.
+ */
+export function parseLastComment(taskText: string): string | null {
+  const headingMatch = COMMENTS_HEADING.exec(taskText);
+  if (!headingMatch) {
+    return null;
+  }
+  const section = taskText.slice(headingMatch.index + headingMatch[0].length);
+  const entryStarts = [...section.matchAll(new RegExp(COMMENT_ENTRY_HEADING, 'gm'))].map(
+    (m) => m.index,
+  );
+  if (entryStarts.length === 0) {
+    return null;
+  }
+  const lastStart = entryStarts[entryStarts.length - 1]!;
+  // The body runs to the NEXT comment heading, not to the first blank line: a `Blocked` comment is
+  // routinely several paragraphs (cause, then a bulleted list, then what to do), and cutting at the
+  // blank line handed the retry prompt only its first sentence.
+  const afterHeading = section.slice(lastStart).replace(/^#\d+ - .+\(UTC\)\n/, '');
+  const nextSection = NEXT_SECTION_HEADING.exec(afterHeading);
+  const body = (nextSection ? afterHeading.slice(0, nextSection.index) : afterHeading).trim();
+  return body.length > 0 ? body : null;
+}
+
+// ── Operating envelope and retry (block 5) ─────────────────────────────────────
+
+export interface OperatingEnvelope {
+  allowedFiles: readonly string[];
+  forbiddenPaths: readonly string[];
+  testCommand: string;
+  /** The worker's own task id: the `backlog` grant, and every command below, are scoped to it. */
+  taskId: string;
+  /**
+   * The one board-write command the launch granted (`worker-edit.ts`'s `workerEditCommand`),
+   * already bound to this task id. Passed in rather than composed here so the string the prompt
+   * prints and the string the permission rule was built from are the same one — a drift between
+   * them is a command the worker is told to run and then denied.
+   */
+  editCommand: string;
+  /**
+   * Rendered WITH the `#N` the CLI prints, because that number is the argument `--check-ac` takes.
+   * Texts alone left the worker to guess an index, and a wrong guess ticks someone else's criterion.
+   */
+  acceptanceCriteria: readonly { index: number; text: string }[];
+  dod: readonly string[];
+}
+
+/** Present only on a retry: the prior `Blocked` comment and the close's reviewer findings, so the
+ * worker does not repeat the same mistake in fresh context (design.md decision (k)). */
+export interface RetryContext {
+  blockedComment: string;
+  reviewerFindings?: string;
+}
+
+export interface AssembleExecutorPromptInput {
+  /** Block 1 — `backlog task view <id> --plain`'s output, verbatim. */
+  task: string;
+  /** The worktree slot this attempt runs in — the worker's cwd, and the root every path resolves against. */
+  slotPath: string;
+  /** The dispatcher's own checkout: the tree the worker must never read, edit or run anything in. */
+  mainCheckoutPath: string;
+  /** Block 2. */
+  hookOutputs: HookOutputs;
+  /** Block 3 — exact `SKILL.md` paths matched by `matchSkillPaths`. */
+  skillPaths: readonly string[];
+  /** Block 4 — `extractDelegationContract`'s output, verbatim. */
+  contract: string;
+  /** Block 5. */
+  envelope: OperatingEnvelope;
+  /** Appended to block 5 on a retry only. */
+  retry?: RetryContext;
+}
+
+/**
+ * Which of the two checkouts the worker is in, named rather than left to inference.
+ *
+ * Measured defect (T-5, 2026-09-07): the executor's FIRST `Edit` targeted the MAIN checkout's copy
+ * of the file it had to change, not its slot's. It had read the repository root off the `File:` line
+ * of the task block — which names the board file, and the board lives in the main checkout — and
+ * nothing in the prompt said otherwise. `Edit(./**)` denied it (the cwd is the slot), so the attempt
+ * spent turns being refused a path it was never told about; a `python3 -c` in the same run, granted
+ * by a click-approval the lane did not intend to load, DID write there.
+ *
+ * A permission rule is the barrier; this is the instruction that stops the worker walking into it.
+ */
+function renderWorkingDirectoryBlock(slotPath: string, mainCheckoutPath: string): string {
+  return [
+    '## Working directory',
+    '',
+    `Your working directory is \`${slotPath}\` — every path in this task is relative to it.`,
+    `The main checkout \`${mainCheckoutPath}\` is NOT yours: never read, edit or run anything there.`,
+    'The board file path shown in the task block lives in the main checkout; do not treat its',
+    'directory as your repository root.',
+  ].join('\n');
+}
+
+function renderHookOutputsBlock(hookOutputs: HookOutputs): string {
+  const lines: string[] = ['## Precomputed hook context'];
+  lines.push('', '### Prompt-relevant business rules, harness rules, and skills');
+  lines.push(hookOutputs.promptContext ?? '(none)');
+  lines.push('', '### Business rules governing declared files');
+  if (hookOutputs.fileRules.length === 0) {
+    lines.push('(none)');
+  } else {
+    for (const rule of hookOutputs.fileRules) {
+      lines.push(`- ${rule.filePath}:`, rule.context);
+    }
+  }
+  return lines.join('\n');
+}
+
+function renderSkillPathsBlock(skillPaths: readonly string[]): string {
+  const lines: string[] = ['## Skills to load before work'];
+  if (skillPaths.length === 0) {
+    lines.push('(none)');
+  } else {
+    for (const path of skillPaths) {
+      lines.push(`- ${path}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * How to tick a criterion, and why it is not optional. Nothing in the prompt used to say ANY of
+ * this, while the close's pre-PR gate fails the attempt on the first unchecked criterion — so the
+ * lane was one instruction short of a run that could ever pass.
+ *
+ * The command is the dispatcher's `worker-edit.ts` wrapper, not the `backlog` CLI: a permission
+ * rule matches a PREFIX, so `Bash(backlog task edit <id> --notes:*)` still admitted a trailing
+ * `--status Done`. The wrapper validates the whole argv, which is why it — and not the flag order —
+ * is what a refusal comes from.
+ */
+function renderTickingInstructions(envelope: OperatingEnvelope): string[] {
+  return [
+    '### Ticking your acceptance criteria (REQUIRED before you finish)',
+    '',
+    `- Tick each criterion as you produce the evidence for it: \`${envelope.editCommand} --check-ac <N>\`,`,
+    '  with the `#N` shown above.',
+    `- Record the evidence with \`${envelope.editCommand} --append-notes "<what proves it>"\` (or`,
+    '  `--notes` to replace them wholesale). A tick with no evidence behind it is a claim, not a result.',
+    `- Read your own task back with \`${envelope.editCommand} --view\`. That is the only read you are`,
+    '  granted: the `backlog` CLI itself is not.',
+    '- That wrapper is your ONLY channel to the board, and it reads the whole command line: only',
+    '  `--check-ac`, `--notes`, `--append-notes` and `--plan`, each at most once. Anything else — `-s`,',
+    '  `--status`, `--ac`, `--acceptance-criteria`, `--title`, `--desc`, a repeated flag, a second task',
+    '  id — exits 2 without writing, wherever in the command line it appears.',
+    '- Your own status and your own criteria are not yours to change: the close re-reads both and fails',
+    '  the attempt if either moved.',
+    '- Leaving any criterion unchecked BLOCKS the attempt at the close, however good the code is.',
+  ];
+}
+
+function renderEnvelopeBlock(envelope: OperatingEnvelope, retry: RetryContext | undefined): string {
+  const lines: string[] = [
+    '## Operating envelope',
+    '',
+    '### Allowed files',
+    ...(envelope.allowedFiles.length > 0
+      ? envelope.allowedFiles.map((file) => `- ${file}`)
+      : ['(none declared)']),
+    '',
+    '### Forbidden paths',
+    ...(envelope.forbiddenPaths.length > 0
+      ? envelope.forbiddenPaths.map((forbiddenPath) => `- ${forbiddenPath}`)
+      : ['(none)']),
+    '',
+    '### Scoped test command',
+    envelope.testCommand,
+    '',
+    // T-3: measured — a worker piped this command through `grep`/`tail` to trim ts-jest noise and
+    // was DENIED. `Bash(<test command>:*)` grants only the declared command; Claude Code evaluates
+    // each segment of a compound line separately, so the piped/appended segments carry no
+    // permission of their own — and filtering the output buys nothing anyway, because the close
+    // runs this SAME bare command again afterwards.
+    'Run the declared test command EXACTLY as written — no pipes, no `&&`, no redirections, no `cd`.',
+    'Claude Code evaluates each segment of a compound line separately and the extra segments have no',
+    'permission; the close runs the same command afterwards, so filtering its output buys nothing.',
+    '',
+    '### Acceptance criteria',
+    ...envelope.acceptanceCriteria.map((ac) => `- #${ac.index} ${ac.text}`),
+    '',
+    ...renderTickingInstructions(envelope),
+    '',
+    '### Definition of Done',
+    ...envelope.dod.map((item) => `- ${item}`),
+  ];
+
+  if (retry) {
+    lines.push('', renderRetryBlock(retry));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * The prior attempt's `Blocked` comment and reviewer findings, as a prompt block. Exported because
+ * BOTH lanes need it: the local lane appends it to the assembled envelope, and the frontier lane —
+ * whose prompt is just `trabajemos <id>` — appends it to that. Without it a frontier retry started
+ * in fresh context with no idea why the previous attempt was blocked, and reliably repeated it.
+ */
+export function renderRetryBlock(retry: RetryContext): string {
+  const lines = [
+    '## Retry — this attempt continues a prior failed one',
+    '',
+    '### Prior Blocked comment',
+    retry.blockedComment,
+  ];
+  if (retry.reviewerFindings) {
+    lines.push('', '### Reviewer findings', retry.reviewerFindings);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The frontier lane's whole user prompt: the same deterministic `trabajemos <id>` entry an
+ * interactive session uses (spec: "Headless orchestrator entry"), plus the retry block when this is
+ * not the first attempt. The orchestrator reads the task itself through the harness, so it needs no
+ * envelope — but nothing in the board tells it that a PREVIOUS attempt failed or why, and a retry
+ * that starts in fresh context without that reliably reproduces the failure it is retrying.
+ */
+export function buildFrontierPrompt(taskId: string, retry?: RetryContext): string {
+  const entry = `trabajemos ${taskId}`;
+  return retry ? [entry, '', '---', '', renderRetryBlock(retry)].join('\n') : entry;
+}
+
+// ── T-8, last point: the parent's one automated close attempt ─────────────────
+//
+// `parent.ts`'s `deriveParentStatus` (rules 4/5) enqueues a Complex parent for exactly ONE close
+// attempt once every child reads `Done` — see that module's doc comment for the "exactly once"
+// mechanism. What runs once it is dispatched still needs deciding: the parent's own DESCRIPTION is
+// whatever brief it was created with (the decomposition — "split this into subtasks"), not a close
+// brief, and a frontier orchestrator that read `trabajemos <id>` the normal way would try to
+// re-plan or re-implement work its subtasks already finished. So this dispatch gets a DIFFERENT,
+// FIXED prompt instead of the task-derived `buildFrontierPrompt` above — the human decision this
+// implements (2026-09-08, "Option B") names it explicitly: "un brief fijo: ejecutar las puertas
+// 8.x del change sobre el diff acumulado de la rama del padre, marcar tasks.md con evidencia, sin
+// implementación nueva".
+
+/**
+ * Whether dispatching `task` right now IS a Complex parent's automated close attempt: it has at
+ * least one child on the board, its own tier is `complex`, and every child is EFFECTIVELY `Done`.
+ *
+ * Recomputed at LAUNCH time from the board rather than carried as a flag from the maintenance pass
+ * that enqueued it (`parent.ts`'s rule 4): the condition is pure, cheap, and — critically —
+ * idempotent to ask again. A RETRY of a close attempt that failed a gate (the `Blocked` release
+ * flow, `catalyst-backlog/SKILL.md` section 10, re-queues the SAME task) reaches this exact same
+ * `true`, with no separate "why was this dispatched" marker to keep in sync with the board.
+ *
+ * `isChildDone` decides "effectively" (defect 11, 2026-09-08): a child that is ITSELF a parent has
+ * its own literal board `.status` kept correct by `maintenance.ts`'s `recomputeParent` — but for a
+ * three-level tree, a single maintenance pass can enqueue a great-parent (via `parent.ts`'s
+ * `effectiveStatus`, which recomputes a parent-shaped child's status FRESH rather than trusting its
+ * literal field) in the SAME pass a middle parent's own `Done` write has not landed yet
+ * (`parentIds` sorts lexicographically, so `'T-10'` is recomputed before `'T-10.1'`). Reading the
+ * literal status alone — this function's ORIGINAL behavior — answered `false` in that window, and a
+ * dispatch that should have received the close-attempt brief got the ordinary decomposition one
+ * instead. The default below preserves that literal check for a caller with nothing better (every
+ * existing test, and every LEAF child, where literal and effective always agree); a caller that CAN
+ * answer "effectively done" — `dispatch.ts` wires `parent.ts`'s `effectiveStatus` over
+ * `maintenance.ts`'s `toDerivationNode`, the SAME derivation `recomputeParent` itself uses — must
+ * pass it explicitly. This is the "two answers to one question" shape T-4.1 measured for a task's
+ * base branch (`guards.ts`'s `resolveTaskBase`, now the ONE place that question is answered):
+ * collapsed here the same way, by making the caller with the fuller answer supply it instead of a
+ * second, independent computation drifting out of sync with the first.
+ */
+export function isParentCloseAttempt(
+  task: Task,
+  board: Board,
+  isChildDone: (child: Task) => boolean = (child) => child.status === TASK_STATUS.DONE,
+): boolean {
+  if (task.tier !== TIER.COMPLEX) {
+    return false;
+  }
+  const children = Object.values(board.tasksById).filter(
+    (candidate) => candidate.parentId === task.id,
+  );
+  if (children.length === 0) {
+    return false;
+  }
+  return children.every(isChildDone);
+}
+
+/**
+ * The parent close attempt's FIXED brief — deliberately NOT derived from `taskId`'s own
+ * description (contrast `buildFrontierPrompt`, which hands the orchestrator the task verbatim).
+ * Opens with the same `trabajemos <id>` entry the harness's Task Gate recognises (root `CLAUDE.md`'s
+ * zeroth gate: "the prompt matches the backlog prefix and the task exists"), then immediately
+ * overrides what that would normally mean, because the task's own description is the ORIGINAL
+ * decomposition brief and reading it as "what to build" here would re-open work its subtasks
+ * already closed.
+ *
+ * The brief instructs, in order: locate the OpenSpec change this task's `References:`/description
+ * names; run that change's verification-gate tasks (SPEC CONFORMITY, `/security-review` if the
+ * surface applies, and the FINAL verification — `judgment-day` for a Complex change) over the
+ * diff `task/<taskId>` now holds (every subtask merged into it, so it is the WHOLE accumulated
+ * change) using the frontier lane's own read-only `git diff`/`git log` grants — never `git push`,
+ * `git commit`, or an Edit outside `openspec/changes/<name>/tasks.md` and the board; tick that
+ * `tasks.md` with the evidence the gate produced; and write NO new implementation, ever — a
+ * confirmed finding is reported via `status: needs-guidance`, never fixed here, because a "quick
+ * fix" IS new implementation and this brief forbids it outright. `needs-guidance` is what turns a
+ * finding into a `Blocked` a person can act on: the close reads the worker's own report text as the
+ * `Blocked` comment (`entry.ts`'s `needsGuidanceQuestion(extractResultText(...))`, already wired —
+ * T-8 point 7 needed no new code, only this prompt telling the orchestrator to use it), so the
+ * verdict IS the actionable comment, not a summary of one.
+ *
+ * On a clean run the close-attempt's own acceptance criteria get ticked and the attempt finishes
+ * normally, which the ALREADY-WIRED close then reads as success: `close.ts`'s `resolveBaseBranch`
+ * delegates to `guards.ts`'s `taskBaseBranch`, which answers `main` for any task with no
+ * `parentId` — the top-level parent itself — so the PR this close opens is `task/<taskId>` ->
+ * `main` with no special-casing needed here (T-8 point 5).
+ */
+export function buildParentCloseAttemptPrompt(taskId: string, retry?: RetryContext): string {
+  const branch = `task/${taskId}`;
+  const brief = [
+    `trabajemos ${taskId}`,
+    '',
+    '---',
+    '',
+    '## Intento de cierre del padre — brief fijo (no derivado de la descripción de la tarea)',
+    '',
+    `Todos los hijos de ${taskId} están \`Done\`. Su rama \`${branch}\` acumula ahora el diff`,
+    'completo del change: cada subtarea ha fusionado su propio PR contra ella. La descripción de',
+    `${taskId} que verás más abajo es el brief ORIGINAL de descomposición — no es tu trabajo de`,
+    'hoy. Tu única tarea es CERRAR el padre. No planifiques, no repartas trabajo nuevo, no',
+    'implementes nada: solo verificación y evidencia.',
+    '',
+    '1. Localiza el change de OpenSpec de esta tarea (`References:` o la descripción nombran',
+    '   `openspec/changes/<name>` — comprueba también `openspec/changes/archive/` si ya se',
+    '   archivó parcialmente).',
+    '2. Con los comandos `git` de solo lectura que tu lane concede (`git diff`, `git log`,',
+    `   \`git show\`), inspecciona el diff ACUMULADO de \`${branch}\` frente a \`origin/main\`.`,
+    '3. Ejecuta las puertas de verificación de `tasks.md` — SPEC CONFORMITY, `/security-review`',
+    '   si el diff toca la superficie de seguridad, y la verificación FINAL (`judgment-day` para',
+    '   un change Complex) — sobre ese diff acumulado, no sobre un archivo aislado.',
+    '4. Marca en `tasks.md` cada puerta con su evidencia (fichero:línea, el test que la cubre).',
+    '   Checked boxes sin evidencia no cuentan — igual que en `/opsx:apply`.',
+    '',
+    '**No hay implementación nueva, bajo ninguna circunstancia.** Si `judgment-day` o cualquier',
+    'otra puerta encuentra un hallazgo confirmado, no lo arregles — arreglarlo ES implementación',
+    'nueva, y este brief la prohíbe. Termina el informe con `status: needs-guidance` y el veredicto',
+    'completo como pregunta: el cierre lee ese texto tal cual como comentario de `Blocked`, así que',
+    'debe bastarle a una persona para actuar sin tener que investigar por su cuenta.',
+    '',
+    'Si todas las puertas pasan limpias: marca las acceptance criteria propias de esta tarea con',
+    'su evidencia (el wrapper de `worker-edit.ts` de siempre) y termina normalmente. El cierre',
+    `abre entonces el PR \`${branch}\` -> \`main\` — no lo abras tú, ni hagas \`git push\`.`,
+  ].join('\n');
+  return retry ? [brief, '', '---', '', renderRetryBlock(retry)].join('\n') : brief;
+}
+
+// ── The frontier lane's system-prompt addendum ────────────────────────────────
+
+export interface BuildFrontierAddendumInput {
+  /** `.claude/skills/catalyst-backlog/frontier-worker-addendum.md`, verbatim. */
+  template: string;
+  taskId: string;
+  /** Where the granted wrapper lives — the MAIN checkout's copy, never the slot's. */
+  mainCheckoutPath: string;
+  /** The worktree slot this attempt runs in: the worker's cwd, and the only tree it may change. */
+  slotPath: string;
+}
+
+/** The only placeholders the template may use; anything else is a typo the worker would read raw. */
+const FRONTIER_ADDENDUM_PLACEHOLDER = /\{\{([A-Z_]+)\}\}/g;
+
+/**
+ * Renders the frontier worker's system-prompt addendum: the short list of facts a DISPATCHED run
+ * adds to what `CLAUDE.md` already says, with the per-launch parts (the task id and the wrapper
+ * command bound to it) filled in.
+ *
+ * It exists because the frontier lane was launched with no system-prompt file at all. `CLAUDE.md`
+ * describes an interactive session — it knows nothing about `worker-edit.ts` — so the worker reached
+ * for `backlog task edit`, was denied, and finished with every acceptance criterion unticked; the
+ * close's AC gate then failed the attempt for a command nobody had told it about.
+ *
+ * The static file is the TEMPLATE (a skill file people can read and edit); the dynamic halves are
+ * rendered here, per attempt, and written into the attempt directory. Pure — the caller reads the
+ * template and writes the result.
+ */
+export function buildFrontierAddendum(input: BuildFrontierAddendumInput): string {
+  const values: Record<string, string> = {
+    TASK_ID: input.taskId,
+    WORKER_EDIT_COMMAND: workerEditCommand(input.mainCheckoutPath, input.taskId),
+    SLOT_PATH: input.slotPath,
+    MAIN_CHECKOUT_PATH: input.mainCheckoutPath,
+  };
+  return input.template.replace(FRONTIER_ADDENDUM_PLACEHOLDER, (_match, name: string) => {
+    const value = values[name];
+    if (value === undefined) {
+      // Left in place it would reach the worker as literal `{{...}}` text — a system prompt that
+      // reads as a broken template is a system prompt nobody follows.
+      throw new Error(
+        `buildFrontierAddendum: unknown placeholder {{${name}}} in the addendum template`,
+      );
+    }
+    return value;
+  });
+}
+
+/**
+ * Assembles the executor's user prompt from the six blocks design.md's "Executor prompt
+ * contract" mandates, IN ORDER: task text, precomputed hook outputs, injected skill paths, the
+ * delegation contract verbatim, and the operating envelope (with a retry's prior `Blocked`
+ * comment and reviewer findings appended to that last block). Pure — every input is already
+ * resolved by the caller (`dispatch.ts`'s `buildPrompt` callback for `lane:local` tasks).
+ *
+ * The working directory is named immediately AFTER the task, because that is where the wrong answer
+ * came from: the task text carries the board file's path in the main checkout, and a worker that
+ * reads it as its repository root edits the wrong tree (see `renderWorkingDirectoryBlock`).
+ */
+export function assembleExecutorPrompt(input: AssembleExecutorPromptInput): string {
+  const blocks = [
+    ['## Task', input.task].join('\n'),
+    renderWorkingDirectoryBlock(input.slotPath, input.mainCheckoutPath),
+    renderHookOutputsBlock(input.hookOutputs),
+    renderSkillPathsBlock(input.skillPaths),
+    ['## Delegation contract (verbatim)', input.contract].join('\n'),
+    renderEnvelopeBlock(input.envelope, input.retry),
+  ];
+  return blocks.join('\n\n---\n\n');
+}