tumwater 0.2.0 → 0.3.0

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

@@ -1,4 +1,3 @@
-// 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";
@@ -8,7 +7,7 @@ import { NOTHING_TO_DO, REPLY_ENDINGS, SUMMARY_BLOCK } from "../verdict/reply-co
  * the cut-off and timeout bridges deliberately phrase their own finish instructions instead. */
 const CONTINUE_TASK_BRIDGE = `Continue the SAME task you were working on and finish it. If the work so far turns out to be
 unusable, redo it — but stay on this task rather than picking a new one.`;
-/** The follow-up prompt for resuming an interrupted tick. It is sent into the SAME pi session as
+/** The follow-up prompt for resuming an interrupted run. It is sent into the SAME pi session as
  * the interrupted run — which already carries the full original prompt, all rules, and the work
  * so far — so it only needs to bridge the gap. The bridge names the real cause: a run cut off at
  * the context ceiling needs to finish with the smallest change and read almost nothing more, not
@@ -63,11 +62,13 @@ ${contextBudgetRule(dialectFor(agent))}
 ${REPLY_ENDINGS}`;
 }
 /** The bridge for a `handoff` resume (plans/agent-backends.md "Sessions"): the newest session
- * in the worktree's session dir belongs to another agent, so this tick runs a FRESH session —
- * the full assembled tick prompt, plus the one fact a fresh session cannot know: an interrupted
+ * in the worktree's session dir belongs to another agent, so this run starts a FRESH session —
+ * the full assembled run 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", 
+ * so the bridge must send the new run to `git diff` before it starts its own work. A `salvaged`
+ * handoff's edits were restored from a patch of a run the harness lost track of
+ * (src/git/slot-salvage.ts) rather than kept in place. */
+export function buildHandoffPrompt(roleId, runPrompt, 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) {
@@ -80,12 +81,16 @@ discard them. This run starts on the model job the daily budget left you.`
 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
+            : cause === "salvaged"
+                ? `An earlier run of the "${roleId}" role was cut short before tumwater could save its work;
+its uncommitted edits were recovered and are in your worktree — review \`git status\` and
+\`git diff\` (new files show as untracked), then finish or discard them.`
+                : `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}`;
+    return `${runPrompt}\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 merged as "<role> tick N"
+/** The one-turn follow-up sent into a run's OWN session (--continue) when the run changed files
+ * but its reply carried no SUMMARY line — 73 of the first 670 commits merged as "<role> run 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. */
@@ -101,10 +106,10 @@ did not include the required closing block, so tumwater cannot describe the comm
 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 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. */
+/** The note injected into a role's next FRESH run prompt after its previous run(s) were cut
+ * off at the context ceiling without merging anything (the role gave up resuming — see
+ * run-apply.ts's CUT_OFF_RESUME_LIMIT — or a cut-off director prompt is re-running). The only
+ * cross-run 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 role ran out of context before merging anything. Pick a

package/dist/src/prompt/prompt.js

@@ -1,47 +1,53 @@
-// vocabulary: plain
 import path from "node:path";
 import { describeCheck } from "../build/build-check-report.js";
-import { DECOMPOSITION_GUIDANCE, NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE, PLAN_SIZING } from "../roles/role-guidance.js";
-import { CLAIMS_RULE, CLAIMS_RULE_COMPACT, REPLY_ENDINGS } from "../verdict/reply-contract.js";
+import { DECOMPOSITION_GUIDANCE, NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING } from "../roles/role-guidance.js";
+import { CLAIMS_RULE, REPLY_ENDINGS } from "../verdict/reply-contract.js";
 import { todayStamp } from "../budget/budget.js";
 import { daysBetween } from "../text/datetime.js";
 import { plural } from "../text/phrases.js";
 import { worktreePath } from "../paths.js";
 import { PI_DIALECT, dialectFor } from "./dialect.js";
-/** The context-budget rule every run carries. Under the old 87k window half of all ticks ended
+/** Prompt construction for the roles' pi runs (run and director). The reply contract those
+ * runs must follow — the TUMWATER_NOTHING_TO_DO sentinel, the TUMWATER_REFUSED line, the
+ * SUMMARY/WHY/RISK/VERIFIED block format, the three endings, and the claims rules — lives in
+ * reply-contract.ts; this module weaves it into each prompt. The follow-up prompts that pick a
+ * session back up — the resume bridge, the missing-summary recovery, and the fresh-run cut-off
+ * note — live in prompt-followup.ts. The merge gate's pi runs (conflict resolution, build fix,
+ * review) build their prompts in gate-prompts.ts; assembling a reply into the run's commit message
+ * lives in git/commit-message.ts.
+ *
+ * The prose is tuned for the team's models (2026-10-01): the primary GLM-5.3-Flash (an 18B-active
+ * MoE behind a ~1M window) and the budget fallback's local Qwen3.8-27B (~127k window). Both follow
+ * short grouped rules with concrete numbers and literal commands far better than long dense
+ * paragraphs, over-read when told merely to "work economically", make unchecked claims the reviewer
+ * then rejects (the primary's leading rejection cause), and need to be told how a reply must end
+ * — so the rules are grouped with one rule per bullet, budgets are numeric, role tasks are
+ * numbered steps, claims carry the check that proves them, the three possible endings are a
+ * mutually exclusive list, and that closing contract comes last, where a model attends to it most.
+ * The prompt is compact: its first request is re-sent on every turn, so the rules keep their
+ * directives without the reasons, the principles block keeps only its bullets, the brief file is
+ * read rather than inlined, and an assigned run goes without the material its assignment makes
+ * redundant. It was written for models with a window of at most 128k (2026-10-17) and became
+ * every model's prompt on 2026-10-18 to cut the tokens each turn re-sends; the longer full
+ * variant was deleted after a day of the team's runs on it (2026-10-19). The PRINCIPLES.md reader
+ * the principles block is fed from lives in principles.ts (readPrinciples, with its injection
+ * cap). */
+/** The context-budget rule every run carries. Under the old 87k window half of all runs ended
  * at the ceiling merging nothing (308 of 733 in the autonomous fortnight; 216 of 245 no-change
- * ticks in the first week of September), almost all of it whole-file reads: the model, told only
+ * runs in the first week of September), almost all of it whole-file reads: the model, told only
  * to "work economically", read the codebase file by file (277 whole-file reads against 6 ranged
  * ones in the bugfix/improve/clean logs). Every token read is prefill and dilutes the model's
  * attention, so the rule states the cost in numbers and the one habit that prevents it: check
- * size, then read in ranges. One rule per bullet (2026-10-01), so a small model can follow each
- * on its own. (Reasoning length is not addressed here: a "think briefly" bullet measured no drop in
- * the fallback model's thinking — the oMLX thinking-budget cap is the lever.) The bundled
- * context-budget extension
- * (src/pi-extension/context-budget.ts) complements this rule with the live fill level. Stated
- * once so the tick rules and prompt-followup.ts's resume bridge cannot drift. Must not contain
- * the phrase "ran out of context" — the loop tests use it to tell a fresh tick from a cut-off
- * resume. */
+ * size, then read in ranges. The range-read threshold is ~150 lines, what a 64k window's read cap
+ * holds (bounded-output.ts outputLimits), and the first bullet names the cost rather than the
+ * window's size, since every model gets it. One rule per bullet (2026-10-01), so a small model can
+ * follow each on its own. (Reasoning length is not addressed here: a "think briefly" bullet
+ * measured no drop in the fallback model's thinking — the oMLX thinking-budget cap is the lever.)
+ * The bundled context-budget extension (src/pi-extension/context-budget.ts) complements this rule
+ * with the live fill level. Stated once so the run rules and prompt-followup.ts's resume bridge
+ * cannot drift. Must not contain the phrase "ran out of context" — the loop tests use it to tell
+ * a fresh run from a cut-off resume. */
 export function contextBudgetRule(dialect = PI_DIALECT) {
-    return `- Your context window is finite: everything you read stays in it until the run ends, and a
-  run that fills the window lands nothing. A whole-file read of a 500-line module costs ~5k tokens.
-- Check size before reading (\`wc -l\`) and read files over ~300 lines in ranges: find the lines
-  with \`grep -n\`, then read them with ${dialect.readRange}.
-- Cap command output with \`head\`/\`tail\`. Never dump a file, a log, or a test run wholesale.
-- Do not re-read what you already saw — re-read only a region you edited.
-- Each turn re-sends everything read so far, so issue lookups that do not depend on each other
-  (a \`wc -l\` over several files, the ranges a \`grep -n\` found, a typecheck and a targeted
-  test) as separate tool calls in the same turn. Keep anything that depends on a prior result
-  sequential — do not batch an edit with the test that checks it.
-- ${dialect.oversizedOutput}`;
-}
-/** The pi-dialect reading-budget rule, byte-identical to the rule before the dialect split, for
- * the callers and tests that want the default text. */
-export const CONTEXT_BUDGET_RULE = contextBudgetRule(PI_DIALECT);
-/** contextBudgetRule for the compact prompt: the same habits, with the range-read threshold at
- * ~150 lines, which is what a 64k window's read cap holds (bounded-output.ts outputLimits). Its
- * first bullet names the cost rather than the window's size, since every model gets it. */
-export function compactContextBudgetRule(dialect = PI_DIALECT) {
     return `- Everything you read stays in your context until the run ends and is re-sent on every turn;
   a run that fills the window merges nothing. A whole read of a 500-line file costs ~5k tokens.
 - Check size first (\`wc -l\`) and read files over ~150 lines in ranges: find the lines with
@@ -52,7 +58,7 @@ export function compactContextBudgetRule(dialect = PI_DIALECT) {
   dependent steps sequential.
 - ${dialect.oversizedOutput}`;
 }
-/** The process-kill rule every run that may run commands carries, word for word: the tick and
+/** The process-kill rule every run that may run commands carries, word for word: the run and
  * director rules (full and compact, each adding its own reason), the conflict resolver, and the
  * reviewer. The team's runs and tumwater's own checks share one host, so a kill by pattern
  * reaches them all. On 2026-10-18 a feature run's `pkill -f "dist/test/test-runner.js"; pkill -f
@@ -62,7 +68,7 @@ export function compactContextBudgetRule(dialect = PI_DIALECT) {
 export const KILL_BY_PID_RULE = `Never kill processes by name or pattern (\`pkill\`, \`killall\`,
   \`pgrep … | xargs kill\`): stop only a process you started, by its PID (\`kill $!\` right after
   backgrounding it).`;
-/** The test-runner rule every run that may run tests carries: the tick and director rules, the
+/** The test-runner rule every run that may run tests carries: the run and director rules, the
  * conflict resolver, and the reviewer. Project-neutral on purpose — a team works on any codebase
  * (npm, cargo, pytest, a configured check.command), so the rule names no ecosystem's runner as THE
  * right one: it points at the declared check or the framework already in use, and its one example
@@ -78,14 +84,13 @@ export const TEST_RUNNER_RULE = `- Run tests only through the project's declared
   runner finds no tests at best, and can kill them mid-run, leaking processes and temp files.`;
 /** Render a dialect's `backendRules` as one bullet each, or nothing when the dialect has none
  * (pi and claude) — so a backend's extra shell/reasoning guidance rides the reading-budget
- * section right after the oversized-output rule and is present in both the full and compact
- * prompts. */
+ * section right after the oversized-output rule. */
 function backendRuleLines(rules) {
     if (!rules || rules.length === 0)
         return "";
     return "\n" + rules.map((rule) => `- ${rule}`).join("\n");
 }
-/** The date line every pi prompt carries — tick and director (via sharedPreamble) and the gate's
+/** The date line every pi prompt carries — run and director (via sharedPreamble) and the gate's
  * conflict and review runs — naming the local calendar day as YYYY-MM-DD. No prompt
  * used to say what day it is, so a run that had to write one (a BUGS.md heading's "(found by …
  * YYYY-MM-DD)", a Fixed or Refused date, NEEDS_REVIEW_NOTE's and NEEDS_REPLAN_NOTE's
@@ -98,7 +103,7 @@ function backendRuleLines(rules) {
 export function dateLine(today = todayStamp()) {
     return `Today's date is ${today} (local time).`;
 }
-/** The repo root as a loop's worktree reaches it (`../../..`, out of .tumwater/worktrees/<role>),
+/** The repo root as a role's worktree reaches it (`../../..`, out of .tumwater/worktrees/<role>),
  * derived from worktreePath so the prompt cannot drift from the layout: the hand-written "two
  * levels up (`../../node_modules`)" it replaced pointed at .tumwater/ itself, and on 2026-09-29
  * a bugfix run that followed it (`cd ../..`, git output empty there) fell back to the primary
@@ -111,118 +116,25 @@ export const DEFAULT_SCOPE = `- Do exactly ONE focused task, then stop. Small, c
 - Choose the task within your first ~15 tool calls, in a handful of turns. A task that would
   need more than roughly 60 tool calls, or most of the codebase in view, is too big for one
   run — take a smaller one.`;
-/** The rules every loop prompt carries — tick and director alike, so the two cannot drift.
+/** The rules every role prompt carries — run and director alike, so the two cannot drift.
  * `check` — the project's resolved check (plans/portability.md §6/7) — names the actual
  * verification command in the Leave-the-project-working rule instead of asserting npm, and
  * only an npm check keeps the node_modules borrowing sentence: false and actively misleading
  * in a repo with no node_modules anywhere (a Python, Rust, or Go repo, or one with no check
  * at all). Undefined keeps the generic wording, exactly as prompts read before a check could
- * be configured. `scope` is the Scope section's rules: DEFAULT_SCOPE unless the tick's role
- * states its own (Role.scope). A rule added here goes in compactRules too, and its directive in
- * test/compact-prompt.test.ts's DIRECTIVES list, which checks that both forms state it. */
-function commonRules(check, briefFile = "README.md", scope = DEFAULT_SCOPE, dialect = PI_DIALECT, compact) {
-    if (compact)
-        return compactRules(check, briefFile, scope, dialect, compact.assigned);
-    const verify = check
-        ? `verify with ${describeCheck(check)} (the project's declared check) — run it after your
+ * be configured. `scope` is the Scope section's rules: DEFAULT_SCOPE unless the run's role
+ * states its own (Role.scope). Orientation differs for an `assigned` run, which reads its entry
+ * first and the brief only when the entry needs it — reading the brief in full cost a median
+ * ~2.5k tokens of every run before its first edit (2026-10-17 audit). */
+function commonRules(check, briefFile = "README.md", scope = DEFAULT_SCOPE, dialect = PI_DIALECT, assigned = false, gateCommand) {
+    const verify = check && gateCommand
+        ? `verify with \`${gateCommand}\` (lint, compile and the tests your change affects) — run it
+  after your change and fix what you broke. Tumwater runs the full check (${describeCheck(check)})
+  itself; do not run it.`
+        : check
+            ? `verify with ${describeCheck(check)} (the project's declared check) — run it after your
   change and fix what you broke.`
-        : `if it has a build or test command, run it after your change and fix what you broke.`;
-    const modules = check?.kind === "npm"
-        ? `
-- Your worktree has no node_modules of its own; it borrows the install at the repo root
-  (\`${ROOT_FROM_WORKTREE}/node_modules\`). To inspect a dependency's types or source, read that
-  directory directly instead of widening the search outward.`
-        : "";
-    return `
-Rules for this run:
-
-Orientation — read this much before choosing your task, and no more:
-- First read the project brief (${briefFile}) in full, plus QUESTIONS.md when present.
-- PLANS.md and BUGS.md hold open work: the prompt's <backlog-index> block lists their actionable
-  entries (PLANS.md ## Planned, BUGS.md ## Open, QUESTIONS.md ## Open), each with its 1-based line
-  range, so read only the entries you need by those ranges. Finished entries live in
-  PLANS-DONE.md and BUGS-FIXED.md, newest first; the index lists the newest few with their
-  ranges. Those archive files only grow — never read them whole: search them with grep, or read
-  one entry by its range, and only when a specific finished entry matters to your task.
-- Your worktree starts clean at main, and tumwater checks main's build before code roles
-  start: do not run the build or test suite just to establish a baseline. Run it after your
-  change, or when the task itself needs its output (reproducing a failure, counting the suite).
-
-Scope:
-${scope}
-
-Reading budget:
-${contextBudgetRule(dialect)}${backendRuleLines(dialect.backendRules)}
-
-Where you work:
-- Stay inside your worktree: run commands from it — the directory you start in, where
-  \`git log\` and \`git show\` work just the same — or from a scratch directory under the system
-  temp.
-- Other agents run concurrently on this machine: put scratch files under \`$TMPDIR\` (made with
-  \`mktemp\`), never at a fixed \`/tmp\` path such as \`/tmp/check.log\`, so no other run overwrites
-  or reads yours.
-- Never cd to the repo root (\`${ROOT_FROM_WORKTREE}\`): it is the primary checkout, which tumwater
-  merges main into while you work, and when this project is tumwater itself its dist/ is the
-  code the running team executes — never build, test, or edit files in that checkout.${modules}
-- Never run an unbounded scan (\`find /\`, \`grep -r /\`, any recursive search rooted outside the
-  repo): it runs for tens of minutes with no output until tumwater kills your run as hung.
-- Never run a command that can wait forever — interactive programs (TUIs, REPLs, editors,
-  anything reading stdin), servers, or watch modes. To test such a program, background it with
-  a hard time limit (kill it after at most 30 minutes) and never give it a real TTY.
-- ${KILL_BY_PID_RULE} A pattern naming your check or test runner also matches other
-  agents' runs and tumwater's own checks on this machine, and kills them too.
-- Leave the project working: ${verify} One run answers every question about the check: write
-  its full output to a file in a scratch dir once (\`<check> > <scratch-dir>/check.log 2>&1\`),
-  then pipe that file through \`tail\` — only the failures matter. To see any other part of the
-  output, grep or read the same file; re-run the check only after an edit changes the tree.
-${TEST_RUNNER_RULE}
-
-Boundaries:
-- Never create, amend, or revert git commits, branches, or merges — tumwater handles all git
-  operations. Reading git history is fine.
-- Never touch the .tumwater directory or tumwater.json.
-- Never edit the brief block in ${briefFile} (between the tumwater:prompt markers).
-- PRINCIPLES.md holds this project's design principles; only the director and steward roles may
-  edit it. Treat it as read-only — to object to a principle, record the objection in PLANS.md.
-- docs/invariants.md states each subsystem's guarantees, pinned to the test that enforces them.
-  Read the matching section before you reconstruct what the code you are changing is supposed
-  to guarantee; when a merge adds or changes a guarantee, update the register in the same
-  commit.
-
-When to ask, when to refuse:
-- When a fork in the road is genuinely the user's call (product direction, an irreversible
-  choice, taste), do not guess: append a question to QUESTIONS.md under ## Open with context,
-  the options, and your own recommendation. Then continue with the parts that don't depend on
-  it, or end the run. Never block on an unanswered question; check QUESTIONS.md for answers at
-  the start of each run and act on one that unblocks your work. Do not re-ask an open question.
-- If partway in you conclude the task would harm the project — it violates PRINCIPLES.md, grows
-  complexity without justification, or keeps fighting back — refuse it. Revert nothing; append
-  this note directly under the entry's heading in PLANS.md (a planned feature) or BUGS.md:
-  **Refused <YYYY-MM-DD> by <role>: <one-line reason>**
-  That note is the only change a refusing run leaves.
-- When choosing work, skip entries carrying a Refused note — do not pick them and do not
-  re-refuse them. The objection stands until a human or the director edits the entry, so a
-  fully blocked backlog is a legitimate nothing-to-do state.
-
-${CLAIMS_RULE}
-
-How to end your reply — tumwater parses it, so the form matters:
-- Your last message is plain text: never a tool call, and never an announcement of what you would
-  do next ("Let me check…") — either make the call or finish. If a tool result only repeats what
-  you already have, do not call it again.
-${REPLY_ENDINGS}`;
-}
-/** commonRules for the compact prompt (CompactPrompt): every directive of the full rules, in
- * fewer words. Orientation differs for an assigned run, which reads its entry first and the
- * brief only when the entry needs it — reading the brief in full cost a median ~2.5k tokens of
- * every run before its first edit (2026-10-17 audit). Scope, Boundaries' first three bullets,
- * TEST_RUNNER_RULE and the reply contract are the full prompt's own text. Keep it in step with
- * commonRules: test/compact-prompt.test.ts checks every directive both must state. */
-function compactRules(check, briefFile, scope, dialect, assigned) {
-    const verify = check
-        ? `verify with ${describeCheck(check)} (the project's declared check) — run it after your
-  change and fix what you broke.`
-        : `if it has a build or test command, run it after your change and fix what you broke.`;
+            : `if it has a build or test command, run it after your change and fix what you broke.`;
     const modules = check?.kind === "npm"
         ? `
 - Your worktree has no node_modules; it borrows \`${ROOT_FROM_WORKTREE}/node_modules\`. Read a
@@ -233,14 +145,15 @@ function compactRules(check, briefFile, scope, dialect, assigned) {
 - Read your assigned entry (at the end of this prompt) by its line range first. It replaces your
   task's choosing steps, so this prompt carries no backlog index. Read the project brief
   (${briefFile}) or QUESTIONS.md only when the entry needs them.
-- PLANS.md and BUGS.md grow without bound — never read them wholesale. Read another entry only
-  by a range this prompt gives, or find it with \`grep -n\` first.`
+- Never read PLANS.md, BUGS.md or their archives (PLANS-DONE.md, BUGS-FIXED.md) whole. Read
+  another entry only by a range this prompt gives, or find it with \`grep -n\` first.`
         : `Orientation — read this much before choosing your task, and no more:
 - First read the project brief (${briefFile}) in full, plus QUESTIONS.md when present.
-- PLANS.md and BUGS.md grow without bound — never read them wholesale. The <backlog-index> block
-  gives each actionable entry and the newest closed ones with its 1-based line range: read only
-  the entries you need, by range. The steward role is the exception: it curates those files and
-  must see them whole.`;
+- PLANS.md and BUGS.md hold open work: the <backlog-index> block gives each actionable entry
+  with its 1-based line range, so read only the entries you need, by range. Finished entries live
+  in PLANS-DONE.md and BUGS-FIXED.md, newest first (the index lists the newest few). Never read
+  those archives whole: grep them, or read one entry by its range, only when a finished entry
+  matters to your task.`;
     return `
 Rules for this run:
 
@@ -252,7 +165,7 @@ Scope:
 ${scope}
 
 Reading budget:
-${compactContextBudgetRule(dialect)}${backendRuleLines(dialect.backendRules)}
+${contextBudgetRule(dialect)}${backendRuleLines(dialect.backendRules)}
 
 Where you work:
 - Run commands from your worktree (where you start; \`git log\` and \`git show\` work there) or a
@@ -266,7 +179,7 @@ Where you work:
   30 minutes) and never give it a real TTY.
 - ${KILL_BY_PID_RULE} A pattern also kills other agents' runs and checks.
 - Leave the project working: ${verify} Write the check's full output to a scratch file once
-  (\`<check> > <scratch-dir>/check.log 2>&1\`) and \`tail\` it; grep that file for anything else, and
+  (\`${gateCommand ? "<gate>" : "<check>"} > <scratch-dir>/check.log 2>&1\`) and \`tail\` it; grep that file for anything else, and
   re-run the check only after an edit changes the tree.
 ${TEST_RUNNER_RULE}
 
@@ -289,11 +202,13 @@ When to ask, when to refuse:
   justification, or keeps fighting back): refuse it. Revert nothing; append this note directly
   under the entry's heading in PLANS.md (a planned feature) or BUGS.md:
   **Refused <YYYY-MM-DD> by <role>: <one-line reason>**
-  That note is the only change a refusing run leaves.
+  The one-line reason must name what in this entry makes it harmful; another entry's hold, or
+  your own notes, is never a reason — skip that entry instead. That note is the only change a
+  refusing run leaves.
 - Skip entries carrying a Refused note: never pick or re-refuse them. A fully blocked backlog is
   a legitimate nothing-to-do state.
 
-${CLAIMS_RULE_COMPACT}
+${CLAIMS_RULE}
 
 How to end your reply — tumwater parses it, so the form matters:
 - Your last message is plain text: never a tool call, and never an announcement of what you would
@@ -301,21 +216,21 @@ How to end your reply — tumwater parses it, so the form matters:
   you already have, do not call it again.
 ${REPLY_ENDINGS}`;
 }
-/** The principles block's compact form: PRINCIPLES.md from its first list item on, dropping the
- * file's own introduction (which restates the block's heading). A file with no list item is
- * kept whole. */
+/** What the principles block carries of PRINCIPLES.md: the file from its first list item on,
+ * dropping its own introduction (which restates the block's heading). A file with no list item
+ * is kept whole. */
 export function principleBullets(principles) {
     const lines = principles.split("\n");
     const first = lines.findIndex((line) => /^[-*] /.test(line));
     return first <= 0 ? principles : lines.slice(first).join("\n");
 }
-/** The <principles> block injected into every tick and director prompt: the project's codified
- * taste, phrased positively so loops follow it rather than merely avoid violations. The file
- * itself is read by principles.ts's readPrinciples. */
+/** The <principles> block injected into every run and director prompt: the project's codified
+ * taste, phrased positively so roles follow it rather than merely avoid violations — its bullets
+ * only (principleBullets). The file itself is read by principles.ts's readPrinciples. */
 function principlesBlock(principles) {
-    return `Design principles this project holds — uphold them in everything you produce:\n<principles>\n${principles}\n</principles>`;
+    return `Design principles this project holds — uphold them in everything you produce:\n<principles>\n${principleBullets(principles)}\n</principles>`;
 }
-/** The <failure-digest> block injected into the telemetry role's prompt (plans/telemetry-role.md):
+/** The <failure-digest> block injected into the selfcheck role's prompt (plans/telemetry-role.md):
  * the harness renders the digest from its own event log at the project root and hands it over, so
  * the role spends no tool calls acquiring evidence and cannot read a stale or foreign log. */
 function digestBlock(digest) {
@@ -333,19 +248,29 @@ function savedClause(savedDay, today) {
         return "last saved today; ";
     return `last saved ${savedDay}, ${plural(age, "day")} ago; `;
 }
-/** The role's notebook as shown to it: its own earlier ticks' note, labeled as unverified.
+/** The role's notes as shown to it: its own earlier runs' note, labeled as unverified.
  * Rides only when there is a non-empty note; the standing instruction to write one is always
- * present (roleNotesInstruction), so a role's FIRST tick — with no note yet — still learns the
- * command exists and can seed the notebook. */
-function roleNotesBlock(notes, savedDay, today) {
+ * present (roleNotesInstruction), so a role's FIRST run — with no note yet — still learns the
+ * command exists and can seed the notes. */
+function roleNotesBlock(notes, hasBacklogIndex, savedDay, today) {
+    const liveSource = hasBacklogIndex
+        ? `the <backlog-index> block above is the live
+source of what is currently true of each entry and series, so check it (and the entry itself) before acting on a
+note's say-so.`
+        : `the backlog is the live
+source of what is currently true of each entry and series, so check the entry itself (and, when this run carries
+one, its line in the backlog) before acting on a note's say-so.`;
     return `Notes your role wrote in earlier runs (${savedClause(savedDay, today)}yours, unverified — check against the code before
-relying on them):\n<role-notes>\n${notes.trim()}\n</role-notes>`;
+relying on them). A claim they make about an entry's backlog state — refused, blocked, abandoned, needs-replan,
+done, behind another entry — is a snapshot of the past, not the present: ${liveSource}
+A note that tells you to skip or never re-author an entry is always overridden by the backlog.
+<role-notes>\n${notes.trim()}\n</role-notes>`;
 }
-/** The standing instruction that makes the notebook seedable: every role tick is told it may
- * write one, so the first tick (when no note exists yet) can create it. The note content block
+/** The standing instruction that makes the notes seedable: every role run is told it may
+ * write one, so the first run (when no note exists yet) can create it. The note content block
  * (roleNotesBlock) is what is omitted when there is nothing to show. Every backend speaks the
  * same shell command (plans/notes-command.md §3), and the director never reaches
- * buildTickPrompt, so it never carries one. */
+ * buildRunPrompt, so it never carries one. */
 export function roleNotesInstruction() {
     return `Before you end, if you learned something the next run of your role should know (where
 things live, what you ruled out and why, what you would look at next), save the full replacement
@@ -363,42 +288,43 @@ const OLDER_NAMES_MAP = "loop = role, tick = run, fleet = team, landing/landed =
 /** The sentence every assembled prompt carries once: the older names and where all of them are
  * listed. Interpolated into the shared preamble and the reviewer and resolver openers. */
 export const OLDER_NAMES_SENTENCE = `Older tumwater names still appear in code, git history and logs: ${OLDER_NAMES_MAP}; docs/glossary.md in tumwater's repository lists them all.`;
-/** Shared opening of every loop prompt: where the run happens, what day it is, and why the
- * project exists. Defined once so the tick and director prompts cannot drift — and so the one
- * sentence telling every role to date its records from dateLine, not from the repo, reaches
- * each of them without editing any role text. */
-function sharedPreamble(initialPrompt, today) {
-    const parts = [
+/** Shared opening of every role prompt: where the run happens and what day it is. The brief is
+ * not inlined: the rules send each run to the brief file, which holds the same text. Defined
+ * once so the run and director prompts cannot drift — and so the one sentence telling every
+ * role to date its records from dateLine, not from the repo, reaches each of them without
+ * editing any role text. */
+function sharedPreamble(today) {
+    return [
         `You work in a dedicated git worktree of this project; your changes will be committed and merged to main by tumwater after you finish.`,
         `${dateLine(today)} Stamp it on anything you record now — a new BUGS.md heading ends
-"(found by the <role> role YYYY-MM-DD)", a closing date reads "— fixed YYYY-MM-DD by the <role> role",
-a new PLANS.md heading reads "(planned YYYY-MM-DD by the <role> role …)", and a Refused or
+"(found by the <role> role YYYY-MM-DD)", a BUGS.md record closes with "— fixed YYYY-MM-DD by the <role> role",
+a finished plan's Done stamp reads "— done YYYY-MM-DD by the <role> role" appended after its
+"(planned YYYY-MM-DD by the <role> role …)" parenthetical, and a Refused or
 Needs-review note carries the date too — and count plan deadlines from it; never infer the date
 from the repo.`,
         OLDER_NAMES_SENTENCE,
     ];
-    if (initialPrompt) {
-        parts.push(`The project's brief — its reason to exist — is:\n<project-prompt>\n${initialPrompt}\n</project-prompt>`);
-    }
-    return parts;
 }
-/** The full prompt for one role run. */
-export function buildTickPrompt(input) {
-    const { role, initialPrompt, principles, digest, coverage, backlogStructure, backlogIndex, notes, notesSavedDay, extraInstructions, planTargetNote, flakyChecks, check, briefFile, today, userRequest, agent, compact } = input;
+/** The prompt for one role run. */
+export function buildRunPrompt(input) {
+    const { role, rejectedReview, principles, digest, coverage, filings, backlogStructure, backlogIndex, notes, notesSavedDay, notesBacklog, extraInstructions, planTargetNote, flakyChecks, check, gateCommand, briefFile, today, userRequest, agent, assigned } = input;
     const dialect = dialectFor(agent);
     const day = today ?? todayStamp();
     const parts = [
+        ...(rejectedReview ? [rejectedReview.trim()] : []),
         `You are the "${role.id}" role (${role.title}) on this project's tumwater team — tumwater runs a team of AI roles that develop the project.`,
-        ...sharedPreamble(initialPrompt, day),
+        ...sharedPreamble(day),
     ];
     if (principles)
-        parts.push(principlesBlock(compact ? principleBullets(principles) : principles));
+        parts.push(principlesBlock(principles));
     if (userRequest)
         parts.push(`An explicit request from the user, aimed at this role. Treat it as this run's steering;
 your role's rules and the merge gate still apply unchanged. If the request is out of this
 role's scope, say so in your reply instead of doing it anyway.\n<user-request>\n${userRequest.trim()}\n</user-request>`);
     if (coverage)
         parts.push(coverage);
+    if (filings)
+        parts.push(filings);
     if (digest)
         parts.push(digestBlock(digest));
     if (backlogStructure)
@@ -406,7 +332,9 @@ role's scope, say so in your reply instead of doing it anyway.\n<user-request>\n
     if (backlogIndex)
         parts.push(backlogIndex);
     if (notes && notes.trim() !== "")
-        parts.push(roleNotesBlock(notes, notesSavedDay, day));
+        parts.push(roleNotesBlock(notes, Boolean(backlogIndex), notesSavedDay, day));
+    if (notesBacklog)
+        parts.push(notesBacklog);
     parts.push(`Your task this run:\n${role.find.trim()}`);
     if (planTargetNote)
         parts.push(planTargetNote.trim());
@@ -415,39 +343,35 @@ role's scope, say so in your reply instead of doing it anyway.\n<user-request>\n
     if (extraInstructions)
         parts.push(`Additional standing instructions from the user:\n${extraInstructions.trim()}`);
     parts.push(roleNotesInstruction());
-    parts.push(commonRules(check, briefFile, role.scope, dialect, compact).trim());
+    parts.push(commonRules(check, briefFile, role.scope, dialect, assigned, gateCommand).trim());
     return parts.join("\n\n");
 }
-/** The prompt for a director tick, which routes a user request into the project. */
-export function buildDirectorPrompt(userPrompt, initialPrompt, principles, 
-/** The project's resolved check (plans/portability.md §6/7) — same threading as the tick
+/** The prompt for a director run, which routes a user request into the project. */
+export function buildDirectorPrompt(userPrompt, principles, 
+/** The project's resolved check (plans/portability.md §6/7) — same threading as the run
  * prompt, since commonRules is shared by both builders. */
 check, 
 /** The resolved brief file's name (plans/portability.md §7a/7) — same threading again. */
 briefFile, 
 /** Today's local date (see dateLine). Omitted: todayStamp() — tests pin it. */
 today, 
-/** Rendered actionable backlog index (see backlog-structure.ts); the tick prompt carries it
+/** Rendered actionable backlog index (see backlog-index.ts); the run prompt carries it
  * too, so the director can route against the same bounded view of the backlog. */
 backlogIndex, 
-/** The agent backend the director resolves to, selecting the prompt dialect (./dialect.ts).
+/** The backend the director resolves to, selecting the prompt dialect (./dialect.ts).
  * Omitted: pi's dialect. */
-agent, 
-/** The compact variant every run gets; a director run is never assigned an entry. Omitted:
- * the full prompt. */
-compact, 
+backend, 
 /** The director's `roles.director.instructions` override — its run prompt is otherwise the
  * user's request. Omitted: no `Additional standing instructions` block, exactly as today. */
 extraInstructions) {
-    const variant = compact ? { assigned: false } : undefined;
     const parts = [
         `You are the "director" role on this project's tumwater team — tumwater runs a team of AI roles that develop the project. The user steers
 the project by sending it requests; one has just arrived. Other specialist roles continuously
 implement planned features from PLANS.md and fix bugs from BUGS.md.`,
-        ...sharedPreamble(initialPrompt, today),
+        ...sharedPreamble(today),
     ];
     if (principles)
-        parts.push(principlesBlock(variant ? principleBullets(principles) : principles));
+        parts.push(principlesBlock(principles));
     if (backlogIndex)
         parts.push(backlogIndex);
     parts.push(`The user's request:\n<user-request>\n${userPrompt.trim()}\n</user-request>`);
@@ -455,7 +379,7 @@ implement planned features from PLANS.md and fix bugs from BUGS.md.`,
 work yourself:
 - A feature request or substantial change: write a concrete plan for it in PLANS.md (goal,
   approach, files touched, acceptance criteria) so the feature role implements it. Do not build
-  it now. ${PLAN_SIZING}
+  it now. ${PLAN_SIZING} ${PLAN_QUEUE_GUIDANCE}
 - A bug report: record it in BUGS.md (symptom, how to reproduce, suspected cause — investigate
   briefly to sharpen the report) so the bugfix role fixes it. Do not fix it now.
 - Guidance, a decision, or a constraint (e.g. "prefer X", "drop feature Y"): record it durably
@@ -494,7 +418,7 @@ work yourself:
     if (extraInstructions)
         parts.push(`Additional standing instructions from the user:\n${extraInstructions.trim()}`);
     // Before the shared rules, not after them: the closing reply contract stays the last thing
-    // in the prompt, where a model attends to it most (the tick prompt's invariant too).
+    // in the prompt, where a model attends to it most (the run prompt's invariant too).
     parts.push(`Note on one boundary in the rules below, director only: user-defined-role requests are
 executed by writing .tumwater-config-request.json in your worktree (shape and worked example
 above) — never by editing tumwater.json, which stays off-limits to you as to every role. Tumwater
@@ -502,6 +426,7 @@ validates the request and applies only its customRoles array; a request that als
 any other setting (timeouts, budgets, role enablement, review settings) has that key discarded
 with a warning, so such a request is guidance to record per the routing rules, not an edit you
 can make.`);
-    parts.push(commonRules(check, briefFile, undefined, dialectFor(agent), variant).trim());
+    // A director run is never assigned an entry.
+    parts.push(commonRules(check, briefFile, undefined, dialectFor(backend)).trim());
     return parts.join("\n\n");
 }