tumwater 0.4.0 → 0.4.2

package/dist/src/run/run-prompt.js

@@ -9,10 +9,10 @@ import { briefFile } from "../brief/brief.js";
 import { buildDirectorPrompt, buildRunPrompt } from "../prompt/prompt.js";
 import { readPrinciples } from "../prompt/principles.js";
 import { buildCutOffNote } from "../prompt/prompt-followup.js";
-import { buildAssignmentNote, buildConflictDiscardNote, buildHeldEntriesNote, buildMergedPrerequisitesNote, buildRejectedReviewNote, buildWaitingPartsNote } from "../prompt/gate-notes.js";
+import { buildAssignmentNote, buildConflictDiscardNote, buildHeldEntriesNote, buildMergedPrerequisitesNote, buildNoCheckNote, buildRejectedReviewNote, buildWaitingPartsNote } from "../prompt/gate-notes.js";
 import { eligibleEntries, mergedPrerequisiteRanges, waitingPartRanges } from "../backlog/backlog-eligibility.js";
 import { notesBacklogBlock } from "../prompt/notes-backlog.js";
-import { donePlans, openBugEntries, plannedPlanEntries } from "../backlog/backlog.js";
+import { donePlans, openBugEntries, plannedPlanEntries, declarationPlanEntry } from "../backlog/backlog.js";
 import { detectBuildCheck, gateCommandOf } from "../build/build-check-detect.js";
 import { flakeCounts, KNOWN_FLAKE_WINDOW_MS } from "../review/known-flakes.js";
 import { readEventsSince } from "../events/event-window.js";
@@ -83,199 +83,238 @@ function flakyChecksNote(root) {
         `names one of these, that bug is still firing. When \`## Open\` holds no entries, a check ` +
         `excused 2 or more times is a confirmed latent bug: take it as this run's latent-bug candidate.`);
 }
-/** Assemble the prompt a role's next run runs on — the whole "what should this run see"
- * concern, split out of runner.ts so the runner owns only lifecycle and the prompt owns only
- * content. Returns null when the role has nothing to run this run (a director with an empty
- * inbox); `userPrompt` carries the dequeued user request — the director's, or a per-role one
- * queued by `tumwater prompt --role <id>` — back so the runner can record it as pending and
- * re-queue it if the run leaves it unfulfilled; `userPromptFile` is the queue file it came
- * from, so that bookkeeping can clean the prompt's attachments by that file's stem. */
-export function assembleRunPrompt({ root, config, role, state, preview = false, backend }) {
-    // The brief's owning file (TUMWATER.md first, README.md as the compatibility path —
-    // plans/portability.md §7a/7), named in both prompt builders' rules instead of a hardcoded
-    // README.md. "README.md" is the fallback for a repo with no marked file yet — the team
-    // runs blind on prompts either way, so the name in the rules should still point somewhere.
-    const brief = briefFile(root) ?? "README.md";
-    // The project's design principles ride along in every prompt — run and director alike — so
-    // all roles share one standard of taste. Empty when the repo has no PRINCIPLES.md.
-    const principles = readPrinciples(root);
-    // The project's resolved check (plans/portability.md §6/7): the prompt names the actual
-    // verify command instead of asserting npm. Detection is a handful of stat calls — a
-    // per-run recompute keeps a config edit live on the next run.
-    const check = detectBuildCheck(root, config) ?? undefined;
-    // The bounded actionable index every run and director prompt carries, replacing the model's
-    // per-run `grep -n '^##'` map of the backlog files (BUGS.md 2026-10-06). One render serves
-    // both branches; the worktree starts at main at run start, so the ranges hold then.
-    const backlogIndex = renderBacklogIndexBlock(root);
-    // A change rejected in review is the only cross-run memory of what was built and why it
-    // failed — every run starts a fresh session, so the full reasons (with the reviewed head and
-    // timestamp) ride along on the next prompt until the role's next reviewed change replaces
-    // them. buildRunPrompt renders it at the very top, before the role charter, so the author
-    // cannot miss it (plans/reviewer-as-role.md part 4/4). A revision run carries the reasons in
-    // buildRevisionNote instead (the rejected diff is already in the worktree), so the note is
-    // suppressed here exactly as it was before this part.
-    const rejectedReview = (state.lastReview?.verdict === "reject" || state.lastReview?.verdict === "reverted") && !state.revision
-        ? buildRejectedReviewNote(state.lastReview, role)
-        : undefined;
-    let prompt;
+/** Build the director's prompt from its deferred request: the queue peek/dequeue, the
+ * empty-inbox null return, the not-before marker strip, and the buildDirectorPrompt call.
+ * Returns null when the director has nothing to run (an empty inbox). */
+function buildDirectorRunPrompt(root, config, preview, backend, brief, principles, check, backlogIndex) {
+    // A deferred director prompt's `tumwater:not-before` marker line is plumbing
+    // (src/inbox/prompt-not-before.ts),
+    // not content — stripped here exactly like the per-role path below, so the director's run
+    // prompt and the runner's re-queue both see the operator's text alone.
+    const entry = preview ? null : dequeuePromptEntry(root);
+    const dequeued = preview ? peekPrompt(root) : entry?.text ?? null;
+    if (!dequeued)
+        return null;
+    const userPrompt = stripNotBeforeMarker(dequeued);
+    const userPromptFile = entry?.file ?? null;
+    const prompt = buildDirectorPrompt(userPrompt, principles, check, brief, undefined, backlogIndex, backend ?? configForRole(config, DIRECTOR_ROLE).agent, config.roles[DIRECTOR_ROLE]?.instructions);
+    return { prompt, userPrompt, userPromptFile };
+}
+/** Build a non-director role's prompt from its queued request and state: the catalog/custom
+ * resolution and unknown-role throw, the role-prompt dequeue and marker strip, the
+ * observer evidence blocks, the notes and their backlog state, the plan target, and the
+ * flaky/no-check notes, feeding the single buildRunPrompt call. Never null — a role always
+ * has a prompt to run on. Each stage is read by one named helper below, so the body is the
+ * ordered calls and the single buildRunPrompt call. */
+function buildRoleRunPrompt(root, config, role, state, preview, backend, brief, principles, check, backlogIndex, rejectedReview) {
+    const { base, resolved } = resolveRoleForPrompt(config, role);
+    const { request, promptFile } = collectRoleRequest(root, role, preview);
+    const digest = collectSelfcheckDigest(root, base);
+    const coverage = collectQaCoverageBlock(root, base);
+    const ciParity = collectCiParityBlock(root, config, base);
+    const filings = collectFeedbackFilingsBlock(root, base);
+    const backlogStructure = collectBacklogStructureBlock(root, base);
+    const { notes, notesSavedDay, notesBacklog } = readPromptNotes(root, role);
+    const { planTargetNote, flakyChecks, noCheck } = collectRoleDirectives(root, config, base, check);
+    // A run holding a claim with no queued request is assigned its one entry (the assignment
+    // note below). Such a run reads that entry first, so the backlog index — what an unassigned
+    // run chooses its task from — stays out.
+    const assigned = state.claim !== undefined && request === null;
     let userPrompt = null;
     let userPromptFile = null;
-    if (role === DIRECTOR_ROLE) {
-        // A deferred director prompt's `tumwater:not-before` marker line is plumbing
-        // (src/inbox/prompt-not-before.ts),
-        // not content — stripped here exactly like the per-role path below, so the director's run
-        // prompt and the runner's re-queue both see the operator's text alone.
-        const entry = preview ? null : dequeuePromptEntry(root);
-        const dequeued = preview ? peekPrompt(root) : entry?.text ?? null;
-        if (!dequeued)
-            return null;
-        userPrompt = stripNotBeforeMarker(dequeued);
-        userPromptFile = entry?.file ?? null;
-        prompt = buildDirectorPrompt(userPrompt, principles, check, brief, undefined, backlogIndex, backend ?? configForRole(config, DIRECTOR_ROLE).agent, config.roles[DIRECTOR_ROLE]?.instructions);
+    const prompt = buildRunPrompt({
+        role: resolved,
+        principles,
+        digest,
+        coverage,
+        ciParity,
+        filings,
+        backlogStructure,
+        backlogIndex: assigned ? undefined : backlogIndex,
+        notes,
+        notesSavedDay,
+        notesBacklog,
+        planTargetNote,
+        flakyChecks,
+        noCheck,
+        extraInstructions: config.roles[base]?.instructions,
+        check,
+        gateCommand: gateCommandOf(config),
+        briefFile: brief,
+        agent: backend ?? configForRole(config, role).agent,
+        assigned,
+        rejectedReview,
+        // A per-role prompt queued by `tumwater prompt --role <id>` rides as an explicit user
+        // request block; its text is also the run's userPrompt,
+        // so the runner's pending-prompt machinery (re-queue on unfulfilled, clear on merge)
+        // treats it exactly like the director's dequeued request.
+        userRequest: request ?? undefined,
+    });
+    if (request) {
+        userPrompt = request;
+        userPromptFile = promptFile;
+    }
+    return { prompt, userPrompt, userPromptFile };
+}
+/** Resolve the run's role: the base role that keys the observer evidence, and the catalog or
+ * user-defined charter. Throws the shared unknown-role message when neither answers. */
+function resolveRoleForPrompt(config, role) {
+    // The role id keys its inbox and notes; every lookup ABOUT the role — catalog charter,
+    // instructions, the qa/selfcheck/clean blocks — resolves through the base role, so
+    // `feature-2` runs the feature charter and `roles.feature.instructions` while keeping its
+    // own queue and notes (plans/parallel-work-instances.md).
+    const base = baseRoleOf(role);
+    // Catalog first, then user-defined roles (plans/user-defined-loops.md): a custom's task
+    // is its entire find-something-to-do text and the title identifies it in the prompt.
+    const custom = config.customRoles.find((c) => c.name === role);
+    const resolved = roleById(role) ?? (custom ? customRole(custom.name, custom.task) : undefined);
+    if (!resolved) {
+        // The shared unknownRoleMessage (parseRoleFlag, the operator commands) names the valid
+        // ids; this defensive path — a runner asked to run a role no catalog entry or
+        // customRoles task can answer — says the same, so if it ever fires it reads as the
+        // harness bug it is instead of a bare dead end.
+        const validIds = [...allRoleIds(), ...config.customRoles.map((c) => c.name)];
+        throw new Error(unknownRoleMessage(role, validIds));
     }
-    else {
-        // The role id keys its inbox and notes; every lookup ABOUT the role — catalog charter,
-        // instructions, the qa/selfcheck/clean blocks — resolves through the base role, so
-        // `feature-2` runs the feature charter and `roles.feature.instructions` while keeping its
-        // own queue and notes (plans/parallel-work-instances.md).
-        const base = baseRoleOf(role);
-        // Catalog first, then user-defined roles (plans/user-defined-loops.md): a custom's task
-        // is its entire find-something-to-do text and the title identifies it in the prompt.
-        const custom = config.customRoles.find((c) => c.name === role);
-        const resolved = roleById(role) ?? (custom ? customRole(custom.name, custom.task) : undefined);
-        if (!resolved) {
-            // The shared unknownRoleMessage (parseRoleFlag, the operator commands) names the valid
-            // ids; this defensive path — a runner asked to run a role no catalog entry or
-            // customRoles task can answer — says the same, so if it ever fires it reads as the
-            // harness bug it is instead of a bare dead end.
-            const validIds = [...allRoleIds(), ...config.customRoles.map((c) => c.name)];
-            throw new Error(unknownRoleMessage(role, validIds));
+    return { base, resolved };
+}
+/** Dequeue (or, in preview, peek) the role's queued request and strip its not-before marker,
+ * returning the delivered text and the queue file it came from. */
+function collectRoleRequest(root, role, preview) {
+    // A queued per-role prompt is dequeued here, before the prompt is built, so its text rides
+    // in the run's prompt; PendingPrompt records it as pending and re-queues it on every
+    // unfulfilled outcome — including a merge-side `main_red` pin, which returns before any run.
+    // A deferred prompt's `tumwater:not-before` marker line is plumbing
+    // (src/inbox/prompt-not-before.ts), not
+    // content: it is stripped at delivery, so the role sees the operator's text alone and the
+    // runner's re-queue writes clean text.
+    const entry = preview ? null : dequeueRolePromptEntry(root, role);
+    const dequeued = preview ? peekRolePrompt(root, role) : entry?.text ?? null;
+    const request = dequeued === null ? null : stripNotBeforeMarker(dequeued);
+    return { request, promptFile: entry?.file ?? null };
+}
+/** The selfcheck and feedback observers' evidence is the harness's own event log, one level
+ * outside this worktree, so its evidence module renders it (selfcheckDigest) and the run
+ * injects it. */
+function collectSelfcheckDigest(root, base) {
+    return base === "selfcheck" || base === "feedback" ? selfcheckDigest(root) : undefined;
+}
+/** The `qa` observer's flow-coverage ledger: rerendered from disk each run, degrading to no
+ * block on a missing or unreadable ledger (plans/observer-roles.md 2/2). */
+function collectQaCoverageBlock(root, base) {
+    // The `qa` observer's flow rotation needs a memory of what it last exercised; every run
+    // is a fresh session, and a passing cheap check leaves nothing in the repo. The ledger is
+    // runtime state, and a missing or unreadable one degrades to no block.
+    let coverage;
+    if (base === "qa") {
+        try {
+            coverage = renderCoverageBlock(readQaCoverage(root));
         }
-        // A queued per-role prompt is dequeued here, before the prompt is built, so its text rides
-        // in the run's prompt; PendingPrompt records it as pending and re-queues it on every
-        // unfulfilled outcome — including a red-main gate block, which returns before any run.
-        // A deferred prompt's `tumwater:not-before` marker line is plumbing
-        // (src/inbox/prompt-not-before.ts), not
-        // content: it is stripped at delivery, so the role sees the operator's text alone and the
-        // runner's re-queue writes clean text.
-        const entry = preview ? null : dequeueRolePromptEntry(root, role);
-        const dequeued = preview ? peekRolePrompt(root, role) : entry?.text ?? null;
-        const request = dequeued === null ? null : stripNotBeforeMarker(dequeued);
-        // The selfcheck and feedback observers' evidence is the harness's own event log, one level
-        // outside this worktree, so its evidence module renders it (selfcheckDigest) and the run
-        // injects it.
-        const digest = base === "selfcheck" || base === "feedback" ? selfcheckDigest(root) : undefined;
-        // The `qa` observer's flow rotation needs a memory of what it last exercised; every run
-        // is a fresh session, and a passing cheap check leaves nothing in the repo. The ledger is
-        // runtime state, and a missing or unreadable one degrades to no block
-        // (plans/observer-roles.md 2/2).
-        let coverage;
-        if (base === "qa") {
-            try {
-                coverage = renderCoverageBlock(readQaCoverage(root));
-            }
-            catch {
-                coverage = undefined;
-            }
+        catch {
+            coverage = undefined;
         }
-        // The `ci` observer's parity block: what the last run covered (tip and lock hash) so a
-        // fresh session can decide nothing-to-do without re-running the whole suite (part 3/3).
-        // Runtime state, and a missing/unreadable record degrades to no block, exactly like qa's.
-        let ciParity;
-        if (base === "ci") {
-            try {
-                ciParity = parityBlockFor(root, config);
-            }
-            catch {
-                ciParity = undefined;
-            }
+    }
+    return coverage;
+}
+/** The `ci` observer's parity block: what the last run covered (tip and lock hash) so a
+ * fresh session can decide nothing-to-do without re-running the whole suite (part 3/3).
+ * Runtime state, and a missing/unreadable record degrades to no block, exactly like qa's. */
+function collectCiParityBlock(root, config, base) {
+    let ciParity;
+    if (base === "ci") {
+        try {
+            ciParity = parityBlockFor(root, config);
         }
-        // The `feedback` observer's per-install filing ledger: what this install already filed as
-        // GitHub issues on znation/tumwater, so the fresh session's charter dedupes against a
-        // "previously filed" block instead of the network alone. Runtime state, and a missing or
-        // unreadable ledger degrades to no block (plans/feedback-role.md 2/2).
-        // The render returns undefined for an empty ledger, so the prompt is unchanged in the common
-        // first-run case.
-        let filings;
-        if (base === "feedback") {
-            try {
-                filings = renderFilingsBlock(readFeedbackFilings(root));
-            }
-            catch {
-                filings = undefined;
-            }
+        catch {
+            ciParity = undefined;
         }
-        // The clean role's deterministic backlog repair: stranded plan headings in the primary
-        // checkout's PLANS.md (plans, part 3/4), rendered like the digest and coverage blocks.
-        // An unreadable or clean file gives no block, so the prompt is unchanged in the common case.
-        const backlogStructure = base === "clean" ? renderBacklogStructureBlock(root) : undefined;
-        // The role's notes (PLANS.md "Role notebook"): its own earlier runs' note. A missing,
-        // empty, or unreadable file yields undefined, so the block is omitted; the write
-        // instruction in buildRunPrompt is present either way. The director branch above never
-        // reads this path, so it carries no notes.
-        const notes = readRoleNote(root, role);
-        // The note file's mtime is when the notes were last saved (writes replace the file), so the
-        // run can weigh how stale they are.
-        const savedStat = notes === undefined ? null : statOrNull(roleNotesPath(root, role));
-        const notesSavedDay = savedStat ? dayKey(savedStat.mtimeMs) : undefined;
-        // The live state of each entry and series the notes name, so a stale note cannot keep a hold
-        // the backlog has lifted (notes-backlog.ts). The three readers are already stat-cached. A
-        // note naming nothing live yields undefined and no block — the common case, since most notes
-        // are about the code, not the backlog.
-        const notesBacklog = notes === undefined || notes.trim() === ""
-            ? undefined
-            : notesBacklogBlock(notes, {
-                planned: plannedPlanEntries(root),
-                openBugs: openBugEntries(root),
-                donePlanTitles: donePlans(root),
-            });
-        // The plan charter's stop threshold is derived from config (plans/parallel-work-
-        // instances.md "…keeping the plan role ahead", part 5c/7). The catalog text stays a
-        // config-free description of the rule; this note supplies the concrete eligible-plan count
-        // so the plan role stops only once every configured feature instance has a plan waiting.
-        const planTargetNote = base === "plan"
-            ? `This run's stop target: when PLANS.md \`## Planned\` already holds ` +
-                `${planBacklogTarget(config)} or more eligible plans, end with ${NOTHING_TO_DO}. ` +
-                `It holds ${eligibleEntries(root, "feature").length} now (tumwater's count of entries ` +
-                `feature could take, the same count that decides whether a plan run is deferred).`
-            : undefined;
-        const flakyChecks = base === "bugfix" ? flakyChecksNote(root) : undefined;
-        // A run holding a claim with no queued request is assigned its one entry (the assignment
-        // note below). Such a run reads that entry first, so the backlog index — what an unassigned
-        // run chooses its task from — stays out.
-        const assigned = state.claim !== undefined && request === null;
-        prompt = buildRunPrompt({
-            role: resolved,
-            principles,
-            digest,
-            coverage,
-            ciParity,
-            filings,
-            backlogStructure,
-            backlogIndex: assigned ? undefined : backlogIndex,
-            notes,
-            notesSavedDay,
-            notesBacklog,
-            planTargetNote,
-            flakyChecks,
-            extraInstructions: config.roles[base]?.instructions,
-            check,
-            gateCommand: gateCommandOf(config),
-            briefFile: brief,
-            agent: backend ?? configForRole(config, role).agent,
-            assigned,
-            rejectedReview,
-            // A per-role prompt queued by `tumwater prompt --role <id>` rides as an explicit user
-            // request block; its text is also the run's userPrompt,
-            // so the runner's pending-prompt machinery (re-queue on unfulfilled, clear on merge)
-            // treats it exactly like the director's dequeued request.
-            userRequest: request ?? undefined,
-        });
-        if (request) {
-            userPrompt = request;
-            userPromptFile = entry?.file ?? null;
+    }
+    return ciParity;
+}
+/** The `feedback` observer's per-install filing ledger: what this install already filed as
+ * GitHub issues on znation/tumwater, so the fresh session's charter dedupes against a
+ * "previously filed" block instead of the network alone. Runtime state, and a missing or
+ * unreadable ledger degrades to no block (plans/feedback-role.md 2/2). */
+function collectFeedbackFilingsBlock(root, base) {
+    // The render returns undefined for an empty ledger, so the prompt is unchanged in the common
+    // first-run case.
+    let filings;
+    if (base === "feedback") {
+        try {
+            filings = renderFilingsBlock(readFeedbackFilings(root));
+        }
+        catch {
+            filings = undefined;
         }
     }
+    return filings;
+}
+/** The clean role's deterministic backlog repair: stranded plan headings in the primary
+ * checkout's PLANS.md (plans, part 3/4), rendered like the digest and coverage blocks. */
+function collectBacklogStructureBlock(root, base) {
+    // An unreadable or clean file gives no block, so the prompt is unchanged in the common case.
+    return base === "clean" ? renderBacklogStructureBlock(root) : undefined;
+}
+/** Read the role's own notes plus their saved day and live backlog state (notes-backlog.ts),
+ * returning all three in one place. */
+function readPromptNotes(root, role) {
+    // The role's notes (PLANS.md "Role notebook"): its own earlier runs' note. A missing,
+    // empty, or unreadable file yields undefined, so the block is omitted; the write
+    // instruction in buildRunPrompt is present either way. The director branch above never
+    // reads this path, so it carries no notes.
+    const notes = readRoleNote(root, role);
+    // The note file's mtime is when the notes were last saved (writes replace the file), so the
+    // run can weigh how stale they are.
+    const savedStat = notes === undefined ? null : statOrNull(roleNotesPath(root, role));
+    const notesSavedDay = savedStat ? dayKey(savedStat.mtimeMs) : undefined;
+    // The live state of each entry and series the notes name, so a stale note cannot keep a hold
+    // the backlog has lifted (notes-backlog.ts). The three readers are already stat-cached. A
+    // note naming nothing live yields undefined and no block — the common case, since most notes
+    // are about the code, not the backlog.
+    const notesBacklog = notes === undefined || notes.trim() === ""
+        ? undefined
+        : notesBacklogBlock(notes, {
+            planned: plannedPlanEntries(root),
+            openBugs: openBugEntries(root),
+            donePlanTitles: donePlans(root),
+        });
+    return { notes, notesSavedDay, notesBacklog };
+}
+/** The directive notes a run may carry: the plan charter's stop target, the bugfix flake
+ * tally, and the plan/feature no-check note — each exactly as it stood inline. */
+function collectRoleDirectives(root, config, base, check) {
+    // The plan charter's stop threshold is derived from config (plans/parallel-work-
+    // instances.md "…keeping the plan role ahead", part 5c/7). The catalog text stays a
+    // config-free description of the rule; this note supplies the concrete eligible-plan count
+    // so the plan role stops only once every configured feature instance has a plan waiting.
+    const planTargetNote = base === "plan"
+        ? `This run's stop target: when PLANS.md \`## Planned\` already holds ` +
+            `${planBacklogTarget(config)} or more eligible plans, end with ${NOTHING_TO_DO}. ` +
+            `It holds ${eligibleEntries(root, "feature").length} now (tumwater's count of entries ` +
+            `feature could take, the same count that decides whether a plan run is deferred).`
+        : undefined;
+    const flakyChecks = base === "bugfix" ? flakyChecksNote(root) : undefined;
+    // The no-check note: when the project declares no deterministic check and the team is
+    // closing the gap itself, the plan note tells the plan role to write the declaration entry
+    // (no marker entry waits yet) and the feature note tells the feature role to implement the
+    // marker entry that does wait. Decided by CHECK_DECLARATION_MARKER (declarationPlanEntry)
+    // rather than prose, so a feature run never invents a declaration the plan role never wrote
+    // and a plan run cannot stack a second declaration on one already waiting. Any other role,
+    // or a declared check, gets neither note — byte-unchanged prompts.
+    const declaration = (base === "plan" || base === "feature") && check === undefined ? declarationPlanEntry(root) : undefined;
+    // Whole declaration drives the decision: `declarationPlanEntry` returns null (not
+    // undefined) when no marker entry waits, so a truthy test selects the feature note and a
+    // falsy one the plan note.
+    const noCheck = check === undefined && (base === "plan" || base === "feature")
+        ? (declaration
+            ? (base === "feature" ? buildNoCheckNote(base) : undefined)
+            : (base === "plan" ? buildNoCheckNote(base) : undefined))
+        : undefined;
+    return { planTargetNote, flakyChecks, noCheck };
+}
+/** Append the shared claim/held/discard/cut-off tail — identical for a director and a role —
+ * in its current order, and return the finished prompt. */
+function appendRunEpilogue(root, role, state, prompt, userPrompt, rejectedReview) {
     // A work instance holding a claim is told which entry is its one task (plans/parallel-work-
     // instances.md "Claims", part 4/7) — the harness picked it, so the charter's choosing step
     // is replaced. A run that dequeued a user request runs that request instead and keeps the
@@ -314,5 +353,50 @@ export function assembleRunPrompt({ root, config, role, state, preview = false,
     if ((state.cutOffStreak ?? 0) > 0) {
         prompt = appendPromptNote(prompt, buildCutOffNote(state.cutOffStreak ?? 0));
     }
-    return { prompt, userPrompt, userPromptFile };
+    return prompt;
+}
+/** Assemble the prompt a role's next run operates on — the whole "what should this run see"
+ * concern, split out of runner.ts so the runner owns only lifecycle and the prompt owns only
+ * content. Returns null when the role has nothing to run this run (a director with an empty
+ * inbox); `userPrompt` carries the dequeued user request — the director's, or a per-role one
+ * queued by `tumwater prompt --role <id>` — back so the runner can record it as pending and
+ * re-queue it if the run leaves it unfulfilled; `userPromptFile` is the queue file it came
+ * from, so that bookkeeping can clean the prompt's attachments by that file's stem. */
+export function assembleRunPrompt({ root, config, role, state, preview = false, backend }) {
+    // The brief's owning file (TUMWATER.md first, README.md as the compatibility path —
+    // plans/portability.md §7a/7), named in both prompt builders' rules instead of a hardcoded
+    // README.md. "README.md" is the fallback for a repo with no marked file yet — the team
+    // runs blind on prompts either way, so the name in the rules should still point somewhere.
+    const brief = briefFile(root) ?? "README.md";
+    // The project's design principles ride along in every prompt — run and director alike — so
+    // all roles share one standard of taste. Empty when the repo has no PRINCIPLES.md.
+    const principles = readPrinciples(root);
+    // The project's resolved check (plans/portability.md §6/7): the prompt names the actual
+    // verify command instead of asserting npm. Detection is a handful of stat calls — a
+    // per-run recompute keeps a config edit live on the next run.
+    const check = detectBuildCheck(root, config) ?? undefined;
+    // The bounded actionable index every run and director prompt carries, replacing the model's
+    // per-run `grep -n '^##'` map of the backlog files (BUGS.md 2026-10-06). One render serves
+    // both branches; the worktree starts at main at run start, so the ranges hold then.
+    const backlogIndex = renderBacklogIndexBlock(root);
+    // A change rejected in review is the only cross-run memory of what was built and why it
+    // failed — every run starts a fresh session, so the full reasons (with the reviewed head and
+    // timestamp) ride along on the next prompt until the role's next reviewed change replaces
+    // them. buildRunPrompt renders it at the very top, before the role charter, so the author
+    // cannot miss it (plans/reviewer-as-role.md part 4/4). A revision run carries the reasons in
+    // buildRevisionNote instead (the rejected diff is already in the worktree), so the note is
+    // suppressed here exactly as it was before this part.
+    const rejectedReview = (state.lastReview?.verdict === "reject" || state.lastReview?.verdict === "reverted") && !state.revision
+        ? buildRejectedReviewNote(state.lastReview, role)
+        : undefined;
+    const built = role === DIRECTOR_ROLE
+        ? buildDirectorRunPrompt(root, config, preview, backend, brief, principles, check, backlogIndex)
+        : buildRoleRunPrompt(root, config, role, state, preview, backend, brief, principles, check, backlogIndex, rejectedReview);
+    if (built === null)
+        return null;
+    return {
+        prompt: appendRunEpilogue(root, role, state, built.prompt, built.userPrompt, rejectedReview),
+        userPrompt: built.userPrompt,
+        userPromptFile: built.userPromptFile,
+    };
 }

package/dist/src/run/run-resume.js

@@ -29,12 +29,11 @@ export function planWithSalvagedWork(role, plan, restored, note) {
         restored,
     };
 }
-/** Decide how a run starts, consuming the resume flags as a side effect (the flag is
- * consumed here so a resume that fails falls back to a normal fresh run; another shutdown
- * mid-resume sets it again) and reclaiming the interrupted run's re-queued prompt. Returns
- * null — meaning the run is skipped — when the role has nothing to run (an empty director
- * inbox); a role runner's assembly never returns null. */
-export function planRunStart(opts) {
+/** Resolve how a run starts, consuming the resume flags as a side effect (a flag is consumed
+ * here so a resume that fails falls back to a normal fresh run; another shutdown mid-resume
+ * sets it again) and reclaiming the interrupted run's re-queued prompt. Owns every read and
+ * write of the resume flags, so a new cause or handoff rule is added here. */
+function resolveRunStartDecision(opts) {
     const s = opts.state;
     // The last merge's failure, read before the clear below: a merge that failed
     // non-terminally kept its pin (the merger's own vocabulary — review_error, merge_conflict,
@@ -88,12 +87,7 @@ export function planRunStart(opts) {
     // survive, but the next run is a FRESH session — the fallback seam may be a different backend,
     // and claude keeps no flags across `--resume` (plans/agent-backends.md §7, part 7a/7).
     const budgetCapped = pendingResumeCause === "budget-capped";
-    // An image-blind run with an image-capable peer tier ends `aborted` with this cause
-    // (plans/image-input.md part 4/5): the next run runs a FRESH session on the TARGET seam
-    // over the kept worktree — never `--continue` — because the old session carries pi's
-    // "image omitted" note and the target may be a different backend.
-    const imageReroute = pendingResumeCause === "image-reroute";
-    const handoff = (latest !== null && !resumable) || budgetCapped || imageReroute;
+    const handoff = (latest !== null && !resumable) || budgetCapped;
     s.resumePending = false;
     s.resumeCause = undefined;
     s.resumeMissing = undefined;
@@ -105,7 +99,7 @@ export function planRunStart(opts) {
     const resumeBlocked = s.phase === "review";
     // A budget-capped handback never resumes the session whose seam the cap moved off of, even
     // when its transcript is still resumable: it hands off instead.
-    const resuming = resumableSession && !resumeBlocked && !budgetCapped && !imageReroute;
+    const resuming = resumableSession && !resumeBlocked && !budgetCapped;
     const handingOff = handoff && !resumeBlocked;
     // Reclaim the prompt the interrupted run re-queued for its resume (src/inbox/pending-prompt.ts):
     // the resumed session still owns that request in its context, so this run's bookkeeping
@@ -122,39 +116,46 @@ export function planRunStart(opts) {
     const resumeCause = handingOff
         ? budgetCapped
             ? "budget-capped"
-            : imageReroute
-                ? "image-reroute"
-                : "handoff"
+            : "handoff"
         : pendingResumeCause ?? ((s.cutOffStreak ?? 0) > 0 ? "cut-off" : "restart");
+    return { priorMergeFailure, resuming, handoff: handingOff, resumeCause };
+}
+/** Build the run's prompt from the resolved decision: the resume bridge on a resume, the
+ * handoff bridge on a handoff, the assembled prompt otherwise. Returns null only when a
+ * handoff/fresh assemble yields nothing. The raw user prompt is read by the caller only when a
+ * prompt exists. */
+function buildRunStartPrompt(opts, d) {
+    const agent = opts.agent ?? "pi";
     let prompt;
-    if (resuming) {
-        prompt = buildResumePrompt(opts.role, resumeCause, agent);
+    if (d.resuming) {
+        prompt = buildResumePrompt(opts.role, d.resumeCause, agent);
     }
     else {
         const assembled = opts.runPrompt(agent);
-        // The image-reroute handoff note names the model the blind run was on and the image it
-        // read; those facts ride the one-shot marker, which is consumed here. A handoff's fresh
-        // session also needs the to-be-run model named for its own side of the note, but the
-        // bridge already carries the facts that matter.
-        const rerouteFacts = imageReroute && s.imageReroute
-            ? { from: s.imageReroute.from ?? "the prior model", path: s.imageReroute.path ?? "an image" }
-            : undefined;
-        if (imageReroute)
-            s.imageReroute = undefined;
         prompt =
             assembled === null
                 ? null
-                : handingOff
-                    ? buildHandoffPrompt(opts.role, assembled, resumeCause, rerouteFacts)
+                : d.handoff
+                    ? buildHandoffPrompt(opts.role, assembled, d.resumeCause)
                     : assembled;
     }
+    return prompt;
+}
+/** Decide how a run starts, consuming the resume flags as a side effect (a flag is consumed
+ * here so a resume that fails falls back to a normal fresh run; another shutdown mid-resume
+ * sets it again) and reclaiming the interrupted run's re-queued prompt. Returns null — meaning
+ * the run is skipped — when the role has nothing to run (an empty director inbox); a role
+ * runner's assembly never returns null. */
+export function planRunStart(opts) {
+    const d = resolveRunStartDecision(opts);
+    const prompt = buildRunStartPrompt(opts, d);
     if (prompt === null) {
         if (!opts.recoveryOnly)
             return null;
-        return { priorMergeFailure, resuming: false, handoff: false, resumeCause, prompt: null, userPrompt: null };
+        return { priorMergeFailure: d.priorMergeFailure, resuming: false, handoff: false, resumeCause: d.resumeCause, prompt: null, userPrompt: null };
     }
     // The raw user prompt a director run is executing (null for role runners), so an
     // unfulfilled outcome below can re-queue it. Captured before the field is cleared.
     const userPrompt = opts.pending.get();
-    return { priorMergeFailure, resuming, handoff: handingOff, resumeCause, prompt, userPrompt };
+    return { priorMergeFailure: d.priorMergeFailure, resuming: d.resuming, handoff: d.handoff, resumeCause: d.resumeCause, prompt, userPrompt };
 }