tumwater 0.2.0 → 0.4.0

package/dist/src/prompt/notes-backlog.js

@@ -0,0 +1,184 @@
+/** The live backlog state a role's notes are checked against, so a note cannot keep a belief the
+ * backlog has lifted. Role notes are free text carried into every later run and rewritten from
+ * the previous note; when a note states something about the backlog (an entry is refused, a
+ * series is dead, a part is done) nothing used to check that claim again — on 2026-10-21 a plan
+ * run wrote "Codex 2b/9 carry Refused — never re-add or re-author them; the Codex theme is dead",
+ * then both Refused notes became Needs-replan notes the plan role exists to act on, but its own
+ * notes kept telling it to skip them and the series stalled. This module renders, from the notes
+ * and the live backlog, a short block saying what is currently true of each entry and series the
+ * notes name, so the live state wins without anyone editing a notes file.
+ *
+ * Naming is a pure function of the notes text, case-insensitive on word boundaries:
+ *  - a series among the planned entries is named by its full name, or by its first word when no
+ *    other live series shares that first word;
+ *  - a line holding a series token and a `i/n` part ref of that series names that part;
+ *  - a line holding a series token and no part ref names the series;
+ *  - a line holding, in order, the first six words of a planned entry's or Open bug's title
+ *    names that entry.
+ * Each named planned part carries its eligibility hold (entryHoldAgainst); a part in
+ * PLANS-DONE.md reads `done`, a part found nowhere reads `not in the backlog`. Each named series
+ * gets one summary line of its planned-part state. The block is at most 12 lines and returns
+ * undefined when the notes name nothing live. */
+import { entryHoldAgainst, entryKindLabel } from "../backlog/backlog-eligibility.js";
+import { entryKey, partKey, plannedPartKeys, seriesPart } from "../backlog/backlog-parts.js";
+import { collapseWhitespace, escapeRegExp } from "../text/text.js";
+const MAX_BLOCK_LINES = 12;
+const HEADER = "What the backlog says now about entries your notes name (PLANS.md and BUGS.md as of this run; where your notes disagree, this is current):";
+/** Build the per-series state maps from the planned entries and done titles. Holds are judged
+ * against all planned parts (cross-series prerequisites count too), exactly as entryHoldAgainst
+ * does, so a part that waits on another series reads `waits on …`. */
+function seriesInfos(planned, doneTitles) {
+    const allParts = plannedPartKeys(planned);
+    const map = new Map();
+    for (const entry of planned) {
+        const part = seriesPart(entry.title);
+        if (part === null)
+            continue;
+        const key = partKey(part.series, part.part);
+        let info = map.get(part.series.toLowerCase());
+        if (info === undefined) {
+            info = { name: part.series, of: part.of, plannedCount: 0, replan: 0, review: 0, waiting: 0, refused: 0, holds: new Map(), done: new Set() };
+            map.set(part.series.toLowerCase(), info);
+        }
+        info.plannedCount++;
+        const hold = entryHoldAgainst(entry, allParts);
+        info.holds.set(key, hold);
+        if (hold === "needs-replan")
+            info.replan++;
+        else if (hold === "needs-review" || hold === "held-for-operator")
+            info.review++; // vocabulary-ok: the held-for-operator hold is an operator decision
+        else if (hold === "refused")
+            info.refused++;
+        else if (typeof hold === "object" && hold !== null)
+            info.waiting++;
+    }
+    for (const title of doneTitles) {
+        const part = seriesPart(title);
+        if (part === null)
+            continue;
+        const info = map.get(part.series.toLowerCase());
+        if (info !== undefined)
+            info.done.add(partKey(part.series, part.part));
+    }
+    return map;
+}
+/** The first word of a series name, lowercased. */
+function firstWord(name) {
+    return name.toLowerCase().split(/\s+/)[0];
+}
+/** Whether `lowerLine` contains `token` on word boundaries (both already lowercased). */
+function lineHas(lowerLine, token) {
+    const quoted = escapeRegExp(token);
+    return new RegExp(`\\b${quoted}\\b`).test(lowerLine);
+}
+/** The `i/n` part refs in a line, numerators lowercased. */
+function partRefsInLine(line) {
+    const out = [];
+    const re = /\b([0-9]+[a-z]?)\/([0-9]+)\b/g;
+    for (let m = re.exec(line); m !== null; m = re.exec(line)) {
+        out.push({ part: m[1].toLowerCase(), of: Number(m[2]) });
+    }
+    return out;
+}
+/** The first six words of an entry title, entryKey-normalized (stamp stripped, whitespace
+ * collapsed, lowercased). */
+function firstSixWords(normalizedKey) {
+    return normalizedKey.split(/\s+/).slice(0, 6).join(" ");
+}
+/** The wording of one named item's state: an eligibility hold, `done`, or `not in the backlog`.
+ * `file` is which backlog the entry lives in, so a held-for-operator entry names the operator's
+ * matching release command (`tumwater plan --release` for a plan, `tumwater bug --release` for a
+ * bug) — the same Plan/Bug derivation the operator-held alert uses. */
+function holdWording(state, file = "plans") {
+    if (state === "done")
+        return "done";
+    if (state === "not-in-backlog")
+        return "not in the backlog";
+    if (state === null)
+        return "eligible";
+    if (state === "refused")
+        return "refused (only the operator clears it)"; // vocabulary-ok: the plan-mandated refused hold wording refers to the tumwater operator
+    if (state === "needs-review")
+        return "needs review";
+    if (state === "needs-replan")
+        return "needs replan (the plan role rewrites it)";
+    if (state === "held-for-operator")
+        return `held for the operator (tumwater ${entryKindLabel(file).toLowerCase()} --release)`; // vocabulary-ok: names the operator-held wording and the operator's release command
+    if (state === "waiting-for-failure")
+        return "waiting for the next failure";
+    return `waits on ${state.blockedBy.join(", ")}`;
+}
+/** The one summary line of a named series' planned-part state. */
+function seriesSummary(info) {
+    const counts = [];
+    if (info.replan > 0)
+        counts.push(`${info.replan} ${info.replan === 1 ? "needs a replan" : "need a replan"}`);
+    if (info.review > 0)
+        counts.push(`${info.review} ${info.review === 1 ? "needs review" : "need review"}`);
+    if (info.waiting > 0)
+        counts.push(`${info.waiting} ${info.waiting === 1 ? "waits" : "wait"} on an earlier part`);
+    counts.push(info.refused === 0 ? "none refused" : `${info.refused} refused`);
+    return `${info.plannedCount} ${info.plannedCount === 1 ? "part" : "parts"} planned: ${counts.join(", ")}`;
+}
+/** The live backlog block for the notes, or undefined when they name nothing live. */
+export function notesBacklogBlock(notes, backlog) {
+    const { planned, openBugs, donePlanTitles } = backlog;
+    const series = seriesInfos(planned, donePlanTitles);
+    const allParts = plannedPartKeys(planned);
+    const firstWordCounts = new Map();
+    for (const info of series.values()) {
+        const w = firstWord(info.name);
+        firstWordCounts.set(w, (firstWordCounts.get(w) ?? 0) + 1);
+    }
+    const allEntries = [...planned, ...openBugs];
+    const namedSeries = new Set();
+    const namedParts = new Map();
+    const namedEntries = new Map();
+    for (const rawLine of notes.split("\n")) {
+        const line = collapseWhitespace(rawLine).toLowerCase();
+        if (line === "")
+            continue;
+        for (const [sLower, info] of series) {
+            const hasFull = lineHas(line, info.name.toLowerCase());
+            const fw = firstWord(info.name);
+            const hasFirst = firstWordCounts.get(fw) === 1 && lineHas(line, fw);
+            if (!hasFull && !hasFirst)
+                continue;
+            const refs = partRefsInLine(line).filter((r) => r.of === info.of);
+            if (refs.length === 0) {
+                namedSeries.add(sLower);
+            }
+            else {
+                for (const r of refs) {
+                    const key = partKey(info.name, r.part);
+                    const state = info.holds.has(key) ? info.holds.get(key) : info.done.has(key) ? "done" : "not-in-backlog";
+                    namedParts.set(`${sLower}\u0000${r.part}\u0000${r.of}`, { seriesLower: sLower, part: r.part, of: r.of, state });
+                }
+            }
+        }
+        for (const [i, entry] of allEntries.entries()) {
+            const phrase = firstSixWords(entryKey(entry.title));
+            if (phrase !== "" && line.includes(phrase)) {
+                namedEntries.set(entryKey(entry.title), { title: entry.title, file: i < planned.length ? "plans" : "bugs", state: entryHoldAgainst(entry, allParts) });
+            }
+        }
+    }
+    const lines = [];
+    for (const sLower of namedSeries) {
+        const info = series.get(sLower);
+        if (info !== undefined)
+            lines.push(`- ${info.name} — ${seriesSummary(info)}`);
+    }
+    for (const p of namedParts.values()) {
+        const info = series.get(p.seriesLower);
+        if (info === undefined)
+            continue;
+        lines.push(`- ${info.name}, part ${p.part}/${p.of} — ${holdWording(p.state, "plans")}`);
+    }
+    for (const entry of namedEntries.values())
+        lines.push(`- ${entry.title} — ${holdWording(entry.state, entry.file)}`);
+    if (lines.length === 0)
+        return undefined;
+    const shown = lines.slice(0, MAX_BLOCK_LINES - 1);
+    return [HEADER, ...shown].join("\n");
+}

package/dist/src/prompt/principles.js

@@ -1,9 +1,8 @@
-// vocabulary: plain
 import path from "node:path";
 import { readTextOrNull } from "../files/files.js";
 import { truncateWithNote } from "../text/text.js";
 /** Cap on the PRINCIPLES.md text injected into every prompt, so a runaway file cannot blow up
- * each tick's prefill. */
+ * each run's prefill. */
 export const PRINCIPLES_MAX_CHARS = 4000;
 /** The project's design principles (PRINCIPLES.md), capped for injection into prompts. Empty
  * string when the file is missing or unreadable — prompt building must never throw on it.

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