tumwater 0.2.0 → 0.4.0

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,45 @@ 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, ciParity, 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 (ciParity)
+        parts.push(ciParity);
+    if (filings)
+        parts.push(filings);
     if (digest)
         parts.push(digestBlock(digest));
     if (backlogStructure)
@@ -406,7 +334,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 +345,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 +381,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 +420,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 +428,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");
 }

package/dist/src/redeploy/redeploy-policy.js

@@ -1,6 +1,7 @@
+import { HOUR_MS, DAY_MS } from "../text/datetime.js";
 /** Self-redeploy for a self-hosting team (see build/build-info.ts for why): when main's build
  * inputs have moved past the running build, verify that main is green, compile it into a staging
- * dir, drain the team (no new ticks; in-flight ones finish or are aborted resumably after
+ * dir, drain the team (no new runs; in-flight ones finish or are aborted resumably after
  * RESTART_DRAIN_MAX_MS), swap the compiled tree into dist/, and ask the supervisor
  * (src/process/supervisor.ts) to respawn the harness onto it by exiting RESTART_EXIT_CODE. Every
  * step is non-blocking from the orchestrator's poll: the green check and the compile run in the
@@ -24,38 +25,42 @@
  * BuildStatus.restartBlocked, which the dashboards and doctor render — because a stale build that
  * is about to be replaced and one that never will be look identical otherwise (BUGS.md
  * 2026-09-08). A green, compiled build can still be unable to START here — the environment, not
- * the code, fails `tumwater run`'s startup gate — so that gate is asked before the team is held
+ * the code, fails `tumwater start`'s startup gate — so that gate is asked before the team is held
  * and again right before the swap, and a failure refuses the restart with a `restart_refused`
  * event instead of trading a running team for a child that exits on its first line (BUGS.md
- * 2026-09-23). Every tick a restart interrupts resumes on the new build through the same resume
+ * 2026-09-23). Every run a restart interrupts resumes on the new build through the same resume
  * machinery a Ctrl+C uses, so a restart loses no work. */
-/** The exit code a supervised `tumwater run` child uses to say "rebuilt; respawn me" —
+/** The exit code a supervised `tumwater start` child uses to say "rebuilt; respawn me" —
  * EX_TEMPFAIL, distinct from success (0), fail() (1) and a forced Ctrl+C (130). */
 export const RESTART_EXIT_CODE = 75;
-/** The COLD-START drain window: how long a pending restart waits for in-flight ROLE ticks before
- * aborting them (they resume on the new build) when the orchestrator has too few completed-tick
+/** The COLD-START drain window: how long a pending restart waits for in-flight ROLE runs before
+ * aborting them (they resume on the new build) when the orchestrator has too few completed-run
  * samples to derive one. Measured across the whole unbroken hold, not per head — see
- * Redeployer.drainSince. Director ticks are exempt: an in-flight human prompt extends the hold
+ * Redeployer.drainSince. Director runs are exempt: an in-flight human prompt extends the hold
  * without any cap (see poll).
  *
- * The live window tracks the team's real tick duration: the orchestrator passes the p75 of recent
- * completed work-bearing role ticks (InFlightCounts.roleTickP75Ms) and poll uses it in place of
+ * The live window tracks the team's real run duration: the orchestrator passes the p75 of recent
+ * completed work-bearing role runs (InFlightCounts.roleRunP75Ms) and poll uses it in place of
  * this constant once it has enough samples (BUGS.md 2026-09-18). The hand-set 30 minutes had not
  * been re-derived since an earlier backend; measured p50 was 46 min and p75 82 min, so the drain
- * timed out on 60% of ticks — paying the full idle cost of waiting plus the interruption cost of
+ * timed out on 60% of runs — paying the full idle cost of waiting plus the interruption cost of
  * not waiting. */
 export const RESTART_DRAIN_MAX_MS = 30 * 60_000;
 /** How often a COMPLETED auto-restart may land — at most once per this window (BUGS.md
  * 2026-09-11): under sustained main churn every stale head would otherwise drive a full
  * hold+drain+swap episode back to back, halting the team for a drain over and over. Bounds
- * frequency across episodes; RESTART_DRAIN_MAX_MS bounds the drain within one. */
-export const RESTART_COOLDOWN_MS = 12 * 60 * 60_000;
+ * frequency across episodes; RESTART_DRAIN_MAX_MS bounds the drain within one. Cut from twelve
+ * hours to four on 2026-10-20: the last eight drains took a median of about 7 min (2 s to
+ * 26 min) and only one aborted runs, so the longer wait cost more than the drains it prevented. */
+export const RESTART_COOLDOWN_MS = 4 * HOUR_MS;
+/** The cooldown in whole hours — the one home of that ms→h division, for the warning text. */
+export const RESTART_COOLDOWN_HOURS = RESTART_COOLDOWN_MS / HOUR_MS;
 /** The cooldown's urgency carve-out (BUGS.md 2026-09-30): when the RUNNING build's own commit
- * carries a red baseline verdict, the deferral is cut to this window instead of the full 12 h —
- * a red running build is not churn but the exact predicament the self-redeploy exists to end,
- * and the rate limit protects against storms, not against a team knowingly executing code its
- * own tree fails. Still a real delay, so consecutive reds cannot storm: one episode per this
- * window at most, each swap giving the team a chance to merge on green. */
+ * carries a red baseline verdict, the deferral is cut to this window instead of the ordinary
+ * cooldown — a red running build is not churn but the exact predicament the self-redeploy exists
+ * to end, and the rate limit protects against storms, not against a team knowingly executing
+ * code its own tree fails. Still a real delay, so consecutive reds cannot storm: one episode
+ * per this window at most, each swap giving the team a chance to merge on green. */
 export const RESTART_URGENT_COOLDOWN_MS = 15 * 60_000;
 /** The urgent carve-out in whole minutes — the one home of that ms→min division, beside the
  * constant it derives from, so the three redeployer.ts warnings that restate the length in
@@ -66,6 +71,6 @@ export const RESTART_URGENT_COOLDOWN_MIN = RESTART_URGENT_COOLDOWN_MS / 60_000;
  * different commit, so the aggregate — hours pinned on a stale build while every rebuild dies —
  * raised no alarm anywhere the operator reads. One warning at this age, then at most one per
  * STALE_ESCALATE_EVERY_MS for as long as the episode lasts. */
-export const STALE_ESCALATE_AFTER_MS = 6 * 60 * 60_000;
+export const STALE_ESCALATE_AFTER_MS = 6 * HOUR_MS;
 /** The sustained-pin warning's repeat cadence: daily, not per poll and not per head. */
-export const STALE_ESCALATE_EVERY_MS = 24 * 60 * 60_000;
+export const STALE_ESCALATE_EVERY_MS = DAY_MS;