tumwater 0.1.2 → 0.2.0

package/dist/src/prompt/gate-prompts.js

@@ -1,13 +1,14 @@
+// vocabulary: plain
 import { shortSha } from "../text/format.js";
-import { TEST_RUNNER_RULE, dateLine } from "./prompt.js";
+import { KILL_BY_PID_RULE, OLDER_NAMES_SENTENCE, TEST_RUNNER_RULE, dateLine } from "./prompt.js";
 import { NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE } from "../roles/role-guidance.js";
 import { describeCheck } from "../build/build-check-report.js";
 import { formatTimestamp } from "../text/datetime.js";
 import { numberedList } from "../text/markdown.js";
 import { SUMMARY_BLOCK, VERDICT_ENDING, NOTHING_TO_DO } from "../verdict/reply-contract.js";
-/** Prompts for the landing gate's pi runs — the runs the merge/review pipeline starts, not the
+/** Prompts for the merge gate's pi runs — the runs the merge/review pipeline starts, not the
  * role loops' authoring ticks (those live in prompt.ts): conflict resolution after a rebase
- * (landing-merge.ts), the adversarial pre-merge review (review.ts), and the notes that carry the
+ * (merge-to-main.ts), the adversarial pre-merge review (review.ts), and the notes that carry the
  * gate's verdicts back to the loop that authored the change (loop-tick.ts, tick-prompt.ts,
  * main-red.ts). The machine-detectable half of the gate's reply contract — verdict constants
  * and detection for parsing a reviewer's VERDICT line — lives in reply-contract.ts. */
@@ -37,38 +38,67 @@ function conflictIntentBlocks(intent) {
         lines.push(`(${intent.mainOmitted} more not shown)`);
     return lines.join("\n");
 }
+/** One conflicted file's bullet: its path, then its conflict hunks' line ranges when known
+ * (merge-git.ts's conflictedFileHunks). A plain path, or a file with no hunks found, is the bare
+ * bullet. */
+function conflictedFileLine(file) {
+    if (typeof file === "string")
+        return `- ${file}`;
+    if (file.hunks.length === 0)
+        return `- ${file.path}`;
+    const ranges = file.hunks.map((h) => `${h.start}-${h.end}`).join(", ");
+    const more = file.more > 0 ? `, and ${file.more} more` : "";
+    return `- ${file.path} (conflict hunks at lines ${ranges}${more})`;
+}
+/** True when any conflicted file carries hunk ranges, so the prompt can point at them. */
+function listsHunks(files) {
+    return files.some((f) => typeof f !== "string" && f.hunks.length > 0);
+}
 /** The prompt for resolving merge conflicts left in a loop's worktree. `check` — the project's
  * resolved check, as the tick prompt threads it — is named so the resolver knows which command
  * the harness will run (told only to keep the tests passing, the 2026-10-04 resolver guessed
  * `npx vitest run` in a node:test repo, BUGS.md 2026-10-05), and the rules tell it not to run
- * that check itself: landing-merge.ts's verifyLanding runs it on the resolved tree before
- * anything lands, and the resolver runs inside the merge slot, so its own copy of the run held
- * every queued landing. On 2026-10-12 the resolvers' own suite runs were 86% of their wall time
+ * that check itself: merge-to-main.ts's verifyMerge runs it on the resolved tree before
+ * anything merges, and the resolver runs inside the merge slot, so its own copy of the run held
+ * every queued merge. On 2026-10-12 the resolvers' own suite runs were 86% of their wall time
  * (951 of 1,104 s over seven runs; one spent 6 min re-testing a tree identical to main).
  * Undefined keeps the generic sentence and adds no such rule: with no declared check the
  * harness verifies nothing. `intent` — this branch's own
  * commit message and the main commits that touched the conflicted files since the merge-base —
  * shows the resolver what both sides meant instead of only the markers; omitted, the prompt is
- * unchanged. `today` pins the date line (prompt.ts's dateLine) for tests; omitted, it is the
- * local day. */
+ * unchanged. A file given with its conflict hunks' line ranges (conflictedFileHunks) is listed
+ * with them, and the rules then send the resolver to those ranges: told only to grep the
+ * markers, the 2026-10-17..19 resolvers still opened the conflicted PLANS.md at line 1, one
+ * tool-output-capped read after another, while every queued merge waited. A plain path lists
+ * the file alone. `today` pins the date line (prompt.ts's dateLine) for tests; omitted, it is
+ * the local day. */
 export function buildConflictPrompt(roleId, files, check, intent, today) {
     const noCheckRunRule = check
         ? `
-- Do not run ${describeCheck(check)} (the project's declared check) or the full test suite: the
-  harness runs that check on the resolved tree before it lands, and every queued landing waits
+- Do not run ${describeCheck(check)} (the project's declared check) or the full test suite:
+  tumwater runs that check on the resolved tree before it merges, and every queued merge waits
   on this run. If you combined code from both sides, a compile or the one or two test files
   that cover it is enough.`
         : "";
     const intentBlocks = intent ? conflictIntentBlocks(intent) : "";
     const removalCitation = intent ? ` (see "What main changed in these files" above)` : "";
-    return `You are the "${roleId}" loop of tumwater, an autonomous development harness. A rebase of
+    const readRule = listsHunks(files)
+        ? `- Read only the conflicted files and what they directly reference, not the codebase at large.
+  Read each conflict hunk listed above as its line range plus about five lines of context on
+  each side; never read a conflicted file from the top, where one read of a long-lined file
+  fills the tool-output limit. Editing a hunk shifts the line numbers below it, so resolve the
+  last hunk first, or re-run \`grep -n '<<<<<<<' FILE\`, which also finds hunks past the listed
+  ones.`
+        : `- Read only the conflicted files and what they directly reference (\`grep -n '<<<<<<<' FILE\`
+  finds each marker; read around it in ranges) — not the codebase at large.`;
+    return `You are the "${roleId}" role on this project's tumwater team — tumwater runs a team of AI roles that develop the project. ${OLDER_NAMES_SENTENCE} A rebase of
 your work branch onto main stopped on conflicts; the conflict markers are sitting in the
 worktree now. Resolve them.
 
 ${dateLine(today)}
 
 Conflicted files:
-${files.map((f) => `- ${f}`).join("\n")}
+${files.map(conflictedFileLine).join("\n")}
 ${intentBlocks ? intentBlocks + "\n" : ""}
 Resolve every conflict marker (<<<<<<<, =======, >>>>>>>) by combining the intent of BOTH sides:
 "ours" is this branch's change, "theirs" is the latest main. Do not simply pick one side unless
@@ -76,20 +106,20 @@ the two changes are genuinely alternatives. Keep the project building and its te
 
 Rules for this run:
 - Edit files only. Never run any git command that changes state (no add, commit, merge, rebase,
-  reset, checkout) — the harness concludes the rebase for you. Reading git state is fine.
-- Read only the conflicted files and what they directly reference (\`grep -n '<<<<<<<' FILE\`
-  finds each marker; read around it in ranges) — not the codebase at large.
+  reset, checkout) — tumwater concludes the rebase for you. Reading git state is fine.
+${readRule}
 - When main has deliberately removed or replaced what the branch edits (a revert, a rewrite of
   the same code), the branch's edit is dropped: resolve toward main's version — the branch's
   change is re-derived on top of current main by its author if it still matters. Never merge
   the branch's version back in over main's deliberate removal${removalCitation}.
 - Never touch the .tumwater directory or tumwater.json.
 ${TEST_RUNNER_RULE}${noCheckRunRule}
+- ${KILL_BY_PID_RULE}
 - When a conflicted file is a markdown backlog file (PLANS.md, BUGS.md, QUESTIONS.md), its
   \`## \` section headings are structure, not text: the result keeps exactly one of each
   \`## \` heading, and every \`### \` entry sits under the section its own side put it in —
   a newly planned feature stays under \`## Planned\` even when the other side moved entries
-  around it.
+  around it. \`grep -n '^## ' FILE\` lists those headings with their line numbers.
 - When every marker is resolved and the project is consistent, just stop.`;
 }
 /** The prompt for the adversarial pre-merge review gate: a fresh-session pi run that sees only the
@@ -99,29 +129,29 @@ ${TEST_RUNNER_RULE}${noCheckRunRule}
  * green on this exact tree (e.g. "`npm run test` passed"), so the reviewer spends its run on what a
  * green suite cannot show instead of re-running it. The no-re-run instruction is its own line in
  * the rules list, not a clause in the context paragraph: stated there, reviewers read past it and
- * re-ran the suite in scratch copies under /tmp while holding the landing slot (BUGS.md
+ * re-ran the suite in scratch copies under /tmp while holding the merge slot (BUGS.md
  * 2026-09-23). It appears only when a verified result exists: after a timed-out, killed, or skipped
  * pre-check no green run stands behind the tree, and a reviewer running the suite itself is doing
  * its job. `baseRev` is the frozen revision the diff is measured against (changeBaseRev's
  * merge-base, resolved when the gate builds the diff): the prompt names it and tells the reviewer
- * to compare against it, never `main`, because other loops land on main while the review runs
+ * to compare against it, never `main`, because other loops merge to main while the review runs
  * (BUGS.md 2026-10-06). Omitted, the prompt keeps the generic "ahead of main" wording. `today` pins
  * the date line (prompt.ts's dateLine) for tests; omitted, it is the local day. The text must
  * contain the literal "VERDICT:" exactly twice — the two advertised forms — because a prompt
- * test derives the accepted forms from it. `priorReview` is present only when this landing is a
+ * test derives the accepted forms from it. `priorReview` is present only when this merge is a
  * revision of a previously rejected change (plans/revise-rejected.md part 2/2): it names the round
  * and shows the prior objections plus the interdiff so the re-review checks each one first.
  * Omitted, the prompt is unchanged from a fresh change's. */
 export function buildReviewPrompt(diff, summary, commitBody, principles, highFriction, verifiedByHarness, baseRev, today, priorReview) {
     const parts = [
-        `You are an adversarial code reviewer for tumwater, an autonomous development harness. A
-loop's change is about to be merged to main; you decide whether it may land. You have no context
+        `You are an adversarial code reviewer for tumwater, which runs a team of AI roles on this project. ${OLDER_NAMES_SENTENCE} A
+role's change is about to be merged to main; you decide whether it may merge. You have no context
 from the authoring run — judge only what is in front of you, and assume nothing until you have
 checked it.`,
         dateLine(today),
     ];
     if (highFriction)
-        parts.push(`This change was flagged HIGH-FRICTION by the harness: its authoring run burned far more
+        parts.push(`This change was flagged HIGH-FRICTION by tumwater: its authoring run burned far more
 assistant turns or wall-clock time than this project's thresholds. Difficulty is a signal that
 the work may not fit the system — apply extra scrutiny to whether the change should exist at all,
 not just whether it is correct.`);
@@ -135,24 +165,27 @@ not just whether it is correct.`);
 of the prior review's numbered objections FIRST — an unresolved one is a rejection on its own —
 then review the whole diff as usual. List only the still-unresolved objections as your numbered
 reasons; state that a prior objection is resolved in prose, never as a numbered reason, so the
-recorded rejection is not read as the resolution itself. The prior objections were:\n${list}\nThe interdiff
+recorded rejection is not read as the resolution itself. When a numbered reason restates one of
+the prior objections, start it with the tag (prior N) where N is that objection's number in the
+prior list, and leave a newly raised objection untagged — the tag is how tumwater tells a repeat
+from a new finding. The prior objections were:\n${list}\nThe interdiff
 between the rejected version and this revision (what the revision changed, main's own movement
 excluded):\n<interdiff>\n${priorReview.interdiff}\n</interdiff>`);
     }
     if (verifiedByHarness)
-        parts.push(`The harness already ran the project's own check on this exact tree and it passed:
+        parts.push(`Tumwater already ran the project's own check on this exact tree and it passed:
 ${verifiedByHarness}. Spend your run on what a green check cannot show: wrong behavior the tests
 never exercise, claims the diff does not back, work left half-done.`);
     if (principles) {
         parts.push(`Design principles this project holds — your review standard; a violation of one is a finding:\n<principles>\n${principles}\n</principles>`);
     }
-    // The base the diff is measured from, named in the prompt: main moves while a landing is vetted,
+    // The base the diff is measured from, named in the prompt: main moves while a merge is approved,
     // and a reviewer that double-checks scope with `git diff main` reads a newer merge, reversed, as
     // part of the change (BUGS.md 2026-10-06). Sentence only when a base is given; the callers that
     // omit it (unit tests of the prompt's other clauses) keep the generic wording.
     const diffBase = baseRev ? `measured against ${shortSha(baseRev)}` : "everything the branch is ahead of main";
     const baseClause = baseRev
-        ? ` It is measured against ${shortSha(baseRev)}; other loops land on main while you review, so compare against ${shortSha(baseRev)}, never against \`main\`, and treat the provided diff as authoritative for which files this change touches.`
+        ? ` It is measured against ${shortSha(baseRev)}; other roles merge on main while you review, so compare against ${shortSha(baseRev)}, never against \`main\`, and treat the provided diff as authoritative for which files this change touches.`
         : "";
     const truncationBase = baseRev ? shortSha(baseRev) : "main";
     parts.push(`The full diff this merge will land (${diffBase}):\n<diff>\n${diff}\n</diff>`);
@@ -160,7 +193,7 @@ never exercise, claims the diff does not back, work left half-done.`);
     // something, but a copy made to run the suite is the re-run this line forbids.
     const noRerunRule = verifiedByHarness
         ? `
-- Do not re-run the check named above or the project's full test suite: the harness's green run
+- Do not re-run the check named above or the project's full test suite: tumwater's green run
   is the verified result. Copying the tree elsewhere to run it — rsync or cp into a temp
   directory, reinstalling dependencies there (for an npm project, \`npm ci\`; otherwise its
   equivalent) — counts as re-running it. Running one
@@ -186,7 +219,7 @@ Check, in this order:
 1. Does the diff do exactly what the summary and WHY claim — no more, no less? An unclaimed
    change is a finding.
 2. Are the VERIFIED claims consistent with the diff (commands, files, observations)? A claim you
-   can disprove is a rejection. Suite counts are the harness's own attestation — they appear in
+   can disprove is a rejection. Suite counts are tumwater's own attestation — they appear in
    the passed-check line above when the check ran green — so a count missing from VERIFIED is
    not a finding, and neither is an author-stated count that differs from it: judge whether the
    tests exist and exercise the change (check 3), not the author's arithmetic.
@@ -208,6 +241,7 @@ Rules for this run:
   verdict below. Reading files and git history is fine; a scratch copy under the system temp
   directory is fine when you need to run something.${noRerunRule}
 ${TEST_RUNNER_RULE}
+- ${KILL_BY_PID_RULE}
 - Weigh the change against its stated purpose; do not approve work you did not actually check.
 - End your reply with exactly one line in this form:
   ${VERDICT_ENDING.replace(/\n/g, "\n  ")}`);
@@ -226,7 +260,7 @@ export function buildReviewResumePrompt(baseRev, patchId) {
 
 You are resuming an adversarial review of a tumwater change: the previous attempt hit its time budget while still making progress, and this run continues that same reviewer session. Everything you already read — the diff and the files you checked — is in your context; do not re-read it.
 
-The change is unchanged since that attempt (patch-id ${patchId}) and is still measured against ${shortSha(baseRev)}. Other loops land on main while you review, so compare against ${shortSha(baseRev)}, never against \`main\`.
+The change is unchanged since that attempt (patch-id ${patchId}) and is still measured against ${shortSha(baseRev)}. Other roles merge on main while you review, so compare against ${shortSha(baseRev)}, never against \`main\`.
 
 Finish the checks you had not completed, then end your reply with exactly one line in this form:
   ${VERDICT_ENDING.replace(/\n/g, "\n  ")}`;
@@ -239,7 +273,7 @@ Finish the checks you had not completed, then end your reply with exactly one li
  * too yields nothing (BUGS.md 2026-09-29). It shares the review prompt's closing rule
  * (reply-contract.ts's VERDICT_ENDING), so the accepted forms cannot drift between the prompts. */
 export function buildVerdictRequestPrompt() {
-    return `Your review reply above did not include the verdict line the harness parses, so
+    return `Your review reply above did not include the verdict line tumwater parses, so
 your judgment was lost. Reply now with ONLY the closing block — no tool calls, no other text:
 one line in this form:
   ${VERDICT_ENDING}`;
@@ -249,7 +283,7 @@ one line in this form:
  * asks it to finish the review from what it already read. The reviewer's only output channel
  * is the verdict, so the closing rule names both accepted forms like the review prompt does. */
 export function buildNoRerunPrompt(rerun) {
-    return `You started a tool call the harness's pre-check already covered, so it must not run:
+    return `You started a tool call tumwater's pre-check already covered, so it must not run:
   ${rerun}
 The full check passed at this exact tree before your review began. Do not re-run it — not in
 this worktree, not in a scratch copy. Finish the review now from what you have already read:
@@ -257,20 +291,23 @@ reply with ONLY the closing block — no tool calls, no other text — one line
   ${VERDICT_ENDING}`;
 }
 /** The one-turn follow-up sent into a tick's OWN session (--continue) when the harness's
- * pre-queue self-check found deterministic faults the landing gate would reject. The session
- * still holds everything the run did, so the author fixes the faults before the change commits
- * and queues — the gate keeps its final say, and the fix costs one bounded turn instead of a
- * rejection cycle. A finding the author believes is wrong is answered in RISK rather than
- * forced away; the reply re-states the closing block because the harness re-derives the commit
- * message from it. Carries the tick prompt's no-git rule (the harness commits). */
+ * pre-queue self-check found problems likely to get the change rejected. Only some findings are
+ * the merge gate's own deterministic checks; the rest (path drift, plan dependencies) are
+ * heuristics, so the prompt never claims the gate rejects every one — claiming it did made an
+ * author sweep a rename through the backlog's history (2026-10-18). The session still holds
+ * everything the run did, so the author fixes the faults before the change commits and queues —
+ * the gate keeps its final say, and the fix costs one bounded turn instead of a rejection cycle.
+ * A finding the author believes is wrong is answered in RISK rather than forced away; the reply
+ * re-states the closing block because the harness re-derives the commit message from it.
+ * Carries the tick prompt's no-git rule (the harness commits). */
 export function buildStageFixPrompt(findings) {
-    return `Your change is about to commit, but the harness's pre-queue self-check found faults the
-landing gate rejects deterministically:
+    return `Your change is about to commit, but tumwater's pre-queue self-check found problems the
+merge gate or its review is likely to reject:
 ${numberedList(findings)}
 Fix each one in the worktree now with the smallest edit that resolves it, and keep everything else
 as it is. When a finding is wrong, say why in your RISK line instead of forcing a change that
 does not help. Do not run any git command that changes state (no add, commit, reset, checkout) —
-the harness commits for you.
+tumwater commits for you.
 When done, reply with ONLY the closing block again — no tool calls, no other text, one line each:
 ${SUMMARY_BLOCK}`;
 }
@@ -295,15 +332,15 @@ export function buildRejectedReviewNote(review, role) {
     // notebook instead: it records the abandoned purpose and any instances that remain
     // unhandled, then takes a different theme on the next tick. Re-authoring the same purpose
     // from the same objections is what restarted the round and produced the long rejection
-    // runs this note exists to end. The markdown-only replan note lands review-exempt, but a
-    // landed change clears the standing rejection (clearSupersededRejection, tick-apply.ts), so
-    // the instruction does not re-inject once the note has landed.
+    // runs this note exists to end. The markdown-only replan note merges review-exempt, but a
+    // merged change clears the standing rejection (clearSupersededRejection, tick-apply.ts), so
+    // the instruction does not re-inject once the note has merged.
     let finality = "";
     if (review.exhausted) {
         finality =
             role === "feature"
-                ? ` This was the change's final revision round — the rejected diff and ref are gone. If it implemented a PLANS.md entry, do not re-author it: append ${NEEDS_REPLAN_NOTE} under that entry's heading, with the numbered objections above quoted beneath it, and land that markdown-only change and nothing else so the plan loop can rewrite the plan. Otherwise, redo the change against current main.`
-                : " This was the change's final revision round — the rejected diff and ref are gone, so do not re-author it. Record the abandoned purpose and any instances of it that remain unhandled in your notebook, then take a different theme on this tick: re-deriving the same purpose from the same objections is what produced the long rejection runs this note exists to end.";
+                ? ` This was the change's final revision round — the same objection survived two revisions (or the chain hit its cap), so the rejected diff and ref are gone. If it implemented a PLANS.md entry, do not re-author it: append ${NEEDS_REPLAN_NOTE} under that entry's heading, with the numbered objections above quoted beneath it, and merge that markdown-only change and nothing else so the plan role can rewrite the plan. Otherwise, redo the change against current main.`
+                : " This was the change's final revision round — the same objection survived two revisions (or the chain hit its cap), so the rejected diff and ref are gone. Do not re-author it. Record the abandoned purpose and any instances of it that remain unhandled in your notes, then take a different theme on this run: re-deriving the same purpose from the same objections is what produced the long rejection runs this note exists to end.";
     }
     return `Your previous change was rejected in review${context}:\n${list}\nAddress the objections or take a different approach.${finality}`;
 }
@@ -311,12 +348,13 @@ export function buildRejectedReviewNote(review, role) {
  * current main as uncommitted edits (plans/revise-rejected.md, loop/revision.ts's
  * applyRevision): this tick's one task is to revise the change already in the worktree, not
  * author a new one. The prior objections are numbered so the author can work through them; a
- * revision round past the first also reaches here. A pure function so its shape is pinned in
- * tests. */
-export function buildRevisionNote(review, round, limit) {
+ * revision round past the first also reaches here. The chain keeps revising while each round
+ * fixes the prior objection; it ends only on a repeated objection or the backstop (BUGS.md
+ * 2026-10-14). A pure function so its shape is pinned in tests. */
+export function buildRevisionNote(review, round) {
     const list = numberedList(review.reasons, NO_REASONS);
     return `Your previously rejected change is already in the worktree as uncommitted edits — this
-is revision ${round} of ${limit}. This tick's ONE task is to revise it; do not author anything else.
+is revision ${round}. This run's ONE task is to revise it; do not author anything else.
 The review objections were:\n${list}
 Fix each numbered objection with the smallest edit that resolves it, and keep everything else as it
 is. When an objection is about a build-check failure in a test the change does not touch that you
@@ -324,22 +362,27 @@ cannot reproduce, say so in RISK and keep the change as it is. Rewrite the closi
 describes the WHOLE change as it now stands:
 ${SUMMARY_BLOCK}
 When an objection shows the change should not exist (its premise is disproven, it duplicates main,
-or it has no reachable benefit), end your reply with the line ${NOTHING_TO_DO} instead, and the
-harness drops the change.`;
+or it has no reachable benefit), end your reply with the line ${NOTHING_TO_DO} instead, and
+tumwater drops the change.`;
 }
 /** The note appended to a work instance's tick prompt when it holds a claim (plans/parallel-
  * work-instances.md "Claims", part 4/7): the harness has already picked its entry, so the
  * charter's choosing step is replaced. A pure function so its shape is pinned in tests; the
  * range is optional because a claim whose entry was already released still gets the note. */
-export function buildAssignmentNote(claim, range) {
+export function buildAssignmentNote(claim, range, missingPaths = []) {
     const where = range ? ` (${claim.file} lines ${range.start}-${range.end})` : ` (${claim.file})`;
     const intro = claim.source === "staged"
         ? `Your change moved ONE backlog entry, so it is now your task, replacing your charter's "pick one" step:`
-        : `The harness has assigned you ONE backlog entry, replacing your charter's "pick one" step:`;
+        : `Tumwater has assigned you ONE backlog entry, replacing your charter's "pick one" step:`;
+    const shown = missingPaths.slice(0, 10).map((p) => `\`${p}\``).join(", ");
+    const rest = missingPaths.length - 10;
+    const missingLine = missingPaths.length === 0
+        ? ""
+        : `\nThe entry names paths that do not exist in your checkout: ${shown}${rest > 0 ? `, and ${rest} more` : ""}. Each was renamed or removed after the entry was written (find its successor with \`git log --follow --name-status -- <path>\` or by grepping for the symbols the entry names), or is a file the entry asks you to create.`;
     return `<assigned-entry>
 ${intro}
 "${claim.title}"${where}.
-Implement or fix only that entry. If it is too large for one run, append ${NEEDS_REVIEW_NOTE} under its heading and end your reply with that note alone. If it should not be done, append a Refused note under its heading with your objection and change nothing else. Do not edit any other backlog entry.
+Implement or fix only that entry. If it is too large for one run, append ${NEEDS_REVIEW_NOTE} under its heading and end your reply with that note alone. If it should not be done, append a Refused note under its heading with your objection and change nothing else. Do not edit any other backlog entry.${missingLine}
 </assigned-entry>`;
 }
 /** The note appended to an unassigned work instance's prompt when siblings hold backlog entries
@@ -352,38 +395,74 @@ Sibling instances hold these backlog entries; do not pick, edit, or implement th
 ${titles.map((t) => `- "${t}"`).join("\n")}
 </held-entries>`;
 }
+/** The capped series-part range list shared by the merged-prerequisites and waiting-parts
+ * notes: at most five `- "title"` lines, each naming the entry's heading line range, then one
+ * `- …and N more` line for the rest, so the two notes list a part's neighbors identically. A
+ * pure function so its shape is pinned in tests (test/gate-prompts.test.ts). */
+/** The longest title a compact prompt quotes in an entry list: a PLANS.md heading's tail names
+ * the plan's dates and every file it touches, which its range already leads to. */
+const COMPACT_TITLE_CHARS = 100;
+function entryRangeLines(entries, compact = false) {
+    // Cut by code point, so an astral character is never split in half.
+    const title = (t) => {
+        const cps = Array.from(t);
+        return compact && cps.length > COMPACT_TITLE_CHARS ? `${cps.slice(0, COMPACT_TITLE_CHARS).join("").trimEnd()}…` : t;
+    };
+    const lines = entries.slice(0, 5).map((e) => `- "${title(e.title)}" (${e.file ?? "PLANS.md"} lines ${e.start}-${e.end})`);
+    if (entries.length > 5)
+        lines.push(`- …and ${entries.length - 5} more`);
+    return lines;
+}
+/** The note appended to a series part's assignment when parts it requires already merged: each
+ * one's Done heading, file (PLANS-DONE.md once archived) and line range, so the implementer reads
+ * exactly what that part changed instead of searching a history that runs to thousands of lines.
+ * Lists at most five, then a count of the rest. A pure function so its shape is pinned in tests. */
+export function buildMergedPrerequisitesNote(entries, 
+/** The compact prompt every run gets: each title cut to COMPACT_TITLE_CHARS. */
+compact = false) {
+    const lines = entryRangeLines(entries, compact);
+    return `<merged-prerequisites>
+Your assigned entry builds on parts that are already merged. Each one's Done entry records what it actually changed; read one by its range when your entry depends on its details, rather than searching the backlog files:
+${lines.join("\n")}
+</merged-prerequisites>`;
+}
 /** The note injected into a role's prompt after leftover recovery discarded its pinned change
  * at MERGE_CONFLICT_LIMIT (src/loop/leftover.ts): at the cap recovery ordinarily hands the
  * change back to its author with markers instead, so a discard means that lineage already used
- * its hand-back. The landing failures were harness-level, so without the note the author would
+ * its hand-back. The merge failures were harness-level, so without the note the author would
  * never learn its work is gone — or that redoing it from memory of the old diff would conflict
  * again. A pure function so its shape is pinned in tests. */
 export function buildConflictDiscardNote(summary, attempts) {
-    return (`Your previous change ("${summary}") was discarded without landing: it conflicted with main ` +
+    return (`Your previous change ("${summary}") was discarded without merging: it conflicted with main ` +
         `${attempts} times and conflict resolution could not reconcile it. Main has moved on since you ` +
         `wrote it. If the change is still needed, redo it against current main, starting from main's ` +
         `current version of the files it touched rather than your earlier diff.`);
 }
 /** The note appended to a role's tick prompt when a change was handed back to it with the
- * conflict markers left in place (PLANS.md "Robust conflict landing, part 2/2"): the landing
+ * conflict markers left in place (PLANS.md "Robust conflict landing, part 2/2"): the merge
  * resolver could not settle it, so the author — who knows what the change was for — resolves it
- * over current main. `reason` says whether it was an approved change whose landing kept
+ * over current main. `reason` says whether it was an approved change whose merge kept
  * conflicting or a rejected change whose revision re-apply conflicted. The note names the
  * conflicted files and shows the same "What main changed in these files" intent block part 1/2
- * gives the resolver, so the author sees what main did without re-deriving it. A pure function
- * so its shape is pinned in tests. */
+ * gives the resolver, so the author sees what main did without re-deriving it. Files given with
+ * their hunk ranges are listed the way the resolver prompt lists them, with a line pointing the
+ * author at those ranges: a hand-back can leave markers in a 1.9 MB PLANS-DONE.md. A pure
+ * function so its shape is pinned in tests. */
 export function buildConflictHandbackNote(reason, conflicted, intent) {
-    const why = reason === "landing"
-        ? "Your previously approved change could not be landed: conflict resolution could not reconcile it with main"
+    const why = reason === "merge"
+        ? "Your previously approved change could not be merged: conflict resolution could not reconcile it with main"
         : "Your rejected change was being revised, but its diff no longer applies cleanly to main";
-    const files = conflicted.length > 0 ? conflicted.map((f) => `- ${f}`).join("\n") : "- (none recorded)";
+    const files = conflicted.length > 0 ? conflicted.map(conflictedFileLine).join("\n") : "- (none recorded)";
+    const readHint = listsHunks(conflicted)
+        ? "\nRead each listed hunk's line range plus a few lines of context, not a conflicted file from the top."
+        : "";
     return `<conflict-handback>
 ${why}. Main moved under it, and the change is now in your worktree as uncommitted edits with the
 conflict markers left in place.
 Resolve every marker (<<<<<<<, =======, >>>>>>>) by combining the intent of BOTH sides, keeping
 main's deliberate removals, then re-run the project's declared check.
 Conflicted files:
-${files}
+${files}${readHint}
 
 ${conflictIntentBlocks(intent)}
 </conflict-handback>`;
@@ -396,14 +475,38 @@ ${conflictIntentBlocks(intent)}
  * the suite red, so authoring anything else first is waste. A pure function so its shape is
  * pinned in tests; script/headline are optional because a red carries a failing script, but the
  * note must still read sensibly if it is ever absent. */
-export function buildMainRedNote(sha, script, headline) {
+export function buildMainRedNote(sha, script, headline, tail) {
     const what = script
         ? `${script}${headline ? `: ${headline}` : ""}`
         : (headline ?? "the project's declared check");
+    // A red baseline already carries the check's bounded clipped tail (clipBuildTail, ≤12 lines:
+    // the failing test's name, the error-message line, then the stack). Hoist it into the note so
+    // the healer starts from the actual assertion and stack instead of the one-line headline —
+    // often just the test name — and must burn its run reproducing the failure first. The tail is
+    // fenced and labeled, and never touches the directive lines above, so the failure's own text
+    // cannot read as instructions to the role. An absent, empty, or all-blank tail renders today's
+    // exact note. */
+    const output = (tail ?? []).map((l) => l.trim()).filter((l) => l !== "");
+    const tailBlock = output.length > 0
+        ? `\nFailing check output (${output.length} lines):\n\`\`\`\n${output.join("\n")}\n\`\`\`\n`
+        : "";
     return `<main-red>
 main's own suite is red at ${shortSha(sha)} (${what}). Every code-producing role is skipping authoring and no change merges until main is green.
-This tick your job is to make main green: reproduce that failure, fix it (add a regression test where one is feasible), and land the fix.
+This run your job is to make main green: reproduce that failure, fix it (add a regression test where one is feasible), and merge the fix.
 The review gate's deterministic pre-check runs main + your change, so a change that leaves the suite red is rejected — do not author anything else first.
 If the failure is environmental — flaky, load-sensitive, or a broken local toolchain — say so plainly in your reply rather than editing unrelated code.
-</main-red>`;
+${tailBlock}</main-red>`;
+}
+/** The note appended to an assigned series part's prompt naming the later planned parts that
+ * wait on it, so the implementer sees where its part ends and leaves their share alone. At most
+ * five are listed, then a literal `- …and N more` line (the `moreSuffix` phrase renders inline,
+ * not as a list line). A pure function so its shape is pinned in tests. */
+export function buildWaitingPartsNote(entries, 
+/** The compact prompt every run gets: each title cut to COMPACT_TITLE_CHARS. */
+compact = false) {
+    const shown = entryRangeLines(entries, compact);
+    return `<waiting-parts>
+Later parts of your series wait for yours to land, and each one plans its own share of the work: do none of it here, and keep in place the names and files they say your part leaves behind. Read one by its range when you need to know what it expects:
+${shown.join("\n")}
+</waiting-parts>`;
 }

package/dist/src/prompt/principles.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import path from "node:path";
 import { readTextOrNull } from "../files/files.js";
 import { truncateWithNote } from "../text/text.js";

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

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import { contextBudgetRule } from "./prompt.js";
 import { dialectFor } from "./dialect.js";
 import { NOTHING_TO_DO, REPLY_ENDINGS, SUMMARY_BLOCK } from "../verdict/reply-contract.js";
@@ -16,39 +17,39 @@ unusable, redo it — but stay on this task rather than picking a new one.`;
  * model re-read the whole tree and repeated identical reads of one file nine times. */
 export function buildResumePrompt(roleId, cause = "restart", agent) {
     const opening = cause === "cut-off"
-        ? `Your previous run as the "${roleId}" loop ran out of context before it could finish, so the
-harness compacted the session and is continuing it now. Your worktree is exactly as you left it;
+        ? `Your previous run as the "${roleId}" role ran out of context before it could finish, so
+tumwater compacted the session and is continuing it now. Your worktree is exactly as you left it;
 what you did so far is summarized above. Do NOT re-read the codebase: trust the summary and
 re-check only what you must, in ranges — at most ~10 tool calls of re-reading, and never the same
 file twice. Finish the SAME task with the smallest change that completes it. If it cannot be
 finished within a fraction of the window, scope it down to what is already complete and coherent,
 leave the project working, and stop.`
         : cause === "hung-tool"
-            ? `The harness killed your previous run as the "${roleId}" loop because it made no progress long enough to trip its hang watchdog — almost always one tool call that hung (a command waiting on input, or a scan far wider than intended). That tool call is dead: do not re-run it unchanged. Your worktree is exactly as you left it, and this session carries everything you did so far — verify the effect of anything the killed call was supposed to produce before relying on it, and bound any long-running command (a time limit, a scoped path).
+            ? `Tumwater killed your previous run as the "${roleId}" role because it made no progress long enough to trip its hang watchdog — almost always one tool call that hung (a command waiting on input, or a scan far wider than intended). That tool call is dead: do not re-run it unchanged. Your worktree is exactly as you left it, and this session carries everything you did so far — verify the effect of anything the killed call was supposed to produce before relying on it, and bound any long-running command (a time limit, a scoped path).
 
 ${CONTINUE_TASK_BRIDGE}`
             : cause === "timeout"
-                ? `Your previous run as the "${roleId}" loop reached the harness's tick time limit while
-it was still making progress — a slow run, not a failed one — so the harness preserved your
+                ? `Your previous run as the "${roleId}" role reached tumwater's run time limit while
+it was still making progress — a slow run, not a failed one — so tumwater preserved your
 worktree and this session and is continuing them now. Finish the SAME task, but budget against
 that same limit: make the smallest change that completes the task coherently, verify it, and
 stop. Do not restart broad exploration the first run already finished; trust the work so far
 and build on it.`
                 : cause === "budget-resumed"
-                    ? `The fleet's daily budget has reopened, and your previous run as the "${roleId}" loop
-started on the fallback model — the harness has moved this session back to the primary model and
+                    ? `The team's daily budget has reopened, and your previous run as the "${roleId}" role
+started on the fallback model — tumwater has moved this session back to the primary model and
 is continuing it now. Your worktree is exactly as you left it, and this session carries everything
 you did so far.
 
 ${CONTINUE_TASK_BRIDGE}`
                     : cause === "rate-limit"
                         ? `The claude.ai subscription usage window rejected your previous run as the "${roleId}"
-loop before it could finish, so the harness held every subscription claude seam until the window
+role before it could finish, so tumwater held every subscription claude model job until the window
 reset. Your worktree is exactly as you left it, and this session carries everything you did so
-far. The window has since reset, and the harness is continuing this session now.
+far. The window has since reset, and tumwater is continuing this session now.
 
 ${CONTINUE_TASK_BRIDGE}`
-                        : `The harness was restarted while you (the "${roleId}" loop) were mid-run. Your worktree
+                        : `Tumwater was restarted while you (the "${roleId}" role) were mid-run. Your worktree
 is exactly as you left it, and this session carries everything you did so far. A tool call that
 was executing when the restart hit may not have finished — verify its effect before relying on it.
 
@@ -57,7 +58,7 @@ ${CONTINUE_TASK_BRIDGE}`;
 still apply, in particular:
 - Do exactly ONE focused task, then stop.
 ${contextBudgetRule(dialectFor(agent))}
-- Never create, amend, or revert git commits — the harness handles all git operations.
+- Never create, amend, or revert git commits — tumwater handles all git operations.
 - Your last message is plain text — never a tool call or an announcement of a next step.
 ${REPLY_ENDINGS}`;
 }
@@ -66,33 +67,47 @@ ${REPLY_ENDINGS}`;
  * the full assembled tick prompt, plus the one fact a fresh session cannot know: an interrupted
  * run's uncommitted edits are sitting in the worktree. The worktree is NOT reset for a handoff,
  * so the bridge must send the new run to `git diff` before it starts its own work. */
-export function buildHandoffPrompt(roleId, tickPrompt, cause = "handoff") {
+export function buildHandoffPrompt(roleId, tickPrompt, cause = "handoff", 
+/** Named facts an image-reroute handoff note needs that the cause alone cannot carry: the
+ * model the blind run was on and the image file it read. */
+imageReroute) {
     const note = cause === "budget-capped"
-        ? `An earlier API-billed claude run of the "${roleId}" loop hit its per-run budget cap before it
+        ? `An earlier API-billed claude run of the "${roleId}" role hit its per-run budget cap before it
 could finish; its uncommitted edits are in your worktree — review \`git diff\`, then finish or
-discard them. This run starts on the seam the daily budget left you.`
-        : `An earlier run of the "${roleId}" loop on another model was interrupted; its
+discard them. This run starts on the model job the daily budget left you.`
+        : cause === "image-reroute"
+            ? `An earlier run of the "${roleId}" role on ${imageReroute?.from ?? "another model"} stopped
+when it read ${imageReroute?.path ?? "an image"}, because that model cannot read images; its
+uncommitted edits are in your worktree — review \`git diff\`, then finish or discard them. This
+run is on a model that CAN read images, so read the image again.`
+            : `An earlier run of the "${roleId}" role on another model was interrupted; its
 uncommitted edits are in your worktree — review \`git diff\`, then finish or discard them.`;
     return `${tickPrompt}\n\n${note}`;
 }
 /** The one-turn follow-up sent into a tick's OWN session (--continue) when the run changed files
- * but its reply carried no SUMMARY line — 73 of the first 670 commits landed as "<role> tick N"
+ * but its reply carried no SUMMARY line — 73 of the first 670 commits merged as "<role> tick N"
  * because of that, most of them the largest diffs in the repo. The session still holds everything
  * the run did, so one short reply recovers the subject and body the commit deserves; the caller
  * bounds the run tightly and falls back to a diff-derived subject if this too yields nothing. */
-export function buildSummaryRequestPrompt() {
+export function buildSummaryRequestPrompt(overLength) {
+    if (overLength !== undefined) {
+        return `Your final reply's SUMMARY line is ${overLength} characters; the commit subject holds at most 72,
+so tumwater would cut it mid-word. Reply now with ONLY the closing block, with the SUMMARY
+restated in at most 72 characters — no tool calls, no other text, one line each:
+${SUMMARY_BLOCK}`;
+    }
     return `Your run changed files in the worktree, but your final reply
-did not include the required closing block, so the harness cannot describe the commit it is about
+did not include the required closing block, so tumwater cannot describe the commit it is about
 to make. Reply now with ONLY that block — no tool calls, no other text, one line each:
 ${SUMMARY_BLOCK}`;
 }
 /** The note injected into a role's next FRESH tick prompt after its previous run(s) were cut
- * off at the context ceiling without landing anything (the loop gave up resuming — see
+ * off at the context ceiling without merging anything (the loop gave up resuming — see
  * tick-apply.ts's CUT_OFF_RESUME_LIMIT — or a cut-off director prompt is re-running). The only
  * cross-tick memory that the last attempt was too big for the window. */
 export function buildCutOffNote(streak) {
     const runs = streak === 1 ? "run" : `${streak} runs`;
-    return `Your previous ${runs} as this loop ran out of context before landing anything. Pick a
+    return `Your previous ${runs} as this role ran out of context before merging anything. Pick a
 smaller, more targeted task this time and budget your reading: grep first, read in ranges, cap
 command output. If the smallest useful task still needs most of the codebase in view, reply
 ${NOTHING_TO_DO} instead of starting it.`;