tumwater 0.2.0 → 0.4.0

package/dist/src/review/secret-leaks.js

@@ -1,7 +1,7 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
-import { readTextOrNull } from "../files/files.js";
+import { errCode } from "../errno.js";
+import { isJsonObject } from "../files/json-object.js";
 import { readJsonFile } from "../files/json-files.js";
 import { changeBaseRev, fileContentAt } from "../git/git.js";
 import { piModelsPath } from "../pi/pi-models.js";
@@ -32,9 +32,6 @@ export function secretEnvValues(env) {
     }
     return out;
 }
-function isRecord(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
 /** The credentials pi stores: literal `apiKey`s and header values in `models.json`, and the
  * `key`/`access`/`refresh` fields (plus secret-named `env` values) of the sibling `auth.json`.
  * `$NAME` interpolations (secretEnvValues covers those) and `!command` values are skipped. A
@@ -48,12 +45,12 @@ export function piCredentialValues(modelsPath = piModelsPath()) {
             out.push({ name, value });
     };
     const models = readJsonFile(modelsPath);
-    if (models && isRecord(models.providers)) {
+    if (models && isJsonObject(models.providers)) {
         for (const [p, cfg] of Object.entries(models.providers)) {
-            if (!isRecord(cfg))
+            if (!isJsonObject(cfg))
                 continue;
             add(`models.json ${p}.apiKey`, cfg.apiKey);
-            if (isRecord(cfg.headers)) {
+            if (isJsonObject(cfg.headers)) {
                 for (const [h, v] of Object.entries(cfg.headers))
                     add(`models.json ${p}.headers.${h}`, v);
             }
@@ -62,11 +59,11 @@ export function piCredentialValues(modelsPath = piModelsPath()) {
     const auth = readJsonFile(path.join(path.dirname(modelsPath), "auth.json"));
     if (auth) {
         for (const [p, cred] of Object.entries(auth)) {
-            if (!isRecord(cred))
+            if (!isJsonObject(cred))
                 continue;
             for (const f of ["key", "access", "refresh"])
                 add(`auth.json ${p}.${f}`, cred[f]);
-            if (isRecord(cred.env)) {
+            if (isJsonObject(cred.env)) {
                 for (const [n, v] of Object.entries(cred.env)) {
                     if (SECRET_NAME.test(n))
                         add(`auth.json ${p}.env.${n}`, v);
@@ -85,12 +82,21 @@ export function knownSecrets(env = process.env, modelsPath = piModelsPath()) {
     ];
     return all.filter((s, i) => all.findIndex((o) => o.value === s.value) === i);
 }
+/** Whether `err` says the path holds no file (deleted, or a parent replaced). */
+function noFile(err) {
+    const code = errCode(err);
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** The finding for a changed file the gate could not read. */
+function unreadable(file, err) {
+    return `\`${file}\` could not be read to check for leaked secrets (${errCode(err) ?? "error"})`;
+}
 /** The deterministic gate/stage finding for a change that writes the value of a secret
  * environment variable or stored pi credential into a file (a Node diagnostic report dumps
  * the whole environment). A value already present in the file at the merge-base is not this
  * change's leak. The reason
- * names files and variables, never the value. undefined when nothing leaked; never throws on
- * an unreadable file. */
+ * names files and variables, never the value. undefined when nothing leaked. A changed file
+ * that exists but cannot be read counts as a finding; a deleted file does not. */
 export async function secretLeakReason(wt, mainBranch, files, secrets = knownSecrets()) {
     if (secrets.length === 0)
         return undefined;
@@ -100,16 +106,30 @@ export async function secretLeakReason(wt, mainBranch, files, secrets = knownSec
         const full = path.join(wt, file);
         let stat;
         try {
-            stat = fs.statSync(full);
+            // lstat, not stat: a symlink in the change set is not followed. The gate scans the
+            // content each change writes, and a change that adds a symlink writes no content — its
+            // target (which lstat's isFile() leaves unreadable, unlike stat's, which follows it out
+            // of the worktree) is not what the change put there. Following it would read an
+            // arbitrary host path a malicious repo can point a link at, and would flag that outside
+            // file's contents as this change's leak.
+            stat = fs.lstatSync(full);
         }
-        catch {
+        catch (err) {
+            if (!noFile(err))
+                leaks.push(unreadable(file, err));
             continue;
         }
         if (!stat.isFile() || stat.size > MAX_SCAN_BYTES)
             continue;
-        const head = readTextOrNull(full);
-        if (head === null)
+        let head;
+        try {
+            head = fs.readFileSync(full, "utf8");
+        }
+        catch (err) {
+            if (!noFile(err))
+                leaks.push(unreadable(file, err));
             continue;
+        }
         const hits = secrets.filter((s) => head.includes(s.value));
         if (hits.length === 0)
             continue;

package/dist/src/review/suite-rerun.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Detecting a reviewer run that re-ran the full suite on a tree the gate's pre-check already
  * verified — pure string logic over the bash command lines a pi run started, no subprocess or
  * file I/O. The review prompt tells such a reviewer not to (src/prompt/gate-prompts.ts), but on

package/dist/src/roles/legacy-role-migration.js

@@ -1,23 +1,56 @@
 import fs from "node:fs";
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { deleteRefIfAt, refSha } from "../git/git.js";
 import { gitTry, runGit } from "../git/git-run.js";
 import { branchName, mergeRefName, rejectedRefName, reviewSessionDir, roleInboxDir, roleNotesPath, sessionDir, statePath } from "../paths.js";
 import { errorMessage } from "../text/text.js";
 import { LEGACY_ROLE_IDS } from "./legacy-role-ids.js";
+/** Rewrite a JSON state file's `role` field to the id its file name now names; a non-JSON file
+ * (or one without a `role` field) is left untouched. `role` is the one field that must match
+ * the file name — saveRunnerState writes `statePath(root, state.role)` — so a file moved by
+ * migration must not keep its old id inside or it would be saved back to the retired file. */
+function rewriteStateRole(file, role) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        const rec = parsed;
+        if (rec.role === role)
+            return;
+        rec.role = role;
+        // writeJsonAtomic, not a plain writeFileSync like every other production state writer
+        // (INV-AF4): the rewritten file is a role's runner state, and a tmp+rename keeps a crash
+        // mid-write (or a concurrent reader) from ever seeing a torn file. A migration that dies
+        // before the rename leaves the target at its pre-rewrite bytes — retried next startup —
+        // never a truncated state file the runner would read as no state.
+        writeJsonAtomic(file, rec);
+    }
+    catch {
+        /* not a JSON state file — leave it alone */
+    }
+}
 /** Move each retired role id's branch, refs and files to the new id (plans/terminology.md "Role
- * names"). Returns one line per artifact moved or skipped. Nothing that exists under the new id
- * is overwritten, each artifact fails alone, and pi and native logs stay put as history. */
+ * names"). Returns one line per artifact, sorted into moved, kept (both
+ * ids exist) and failed. State files are the one exception to "kept": when both id-named copies
+ * exist and the old-id copy carries the newer end-of-run stamp (`lastRunEndedAt`, or the
+ * pre-rename `lastTickEndedAt` a frozen copy carries), that copy is folded over the stale
+ * new-name one under the new name (the earlier migration renamed only the file list, not the
+ * `role` field inside, so the runner kept writing the old-id name and the two copies drifted —
+ * BUGS.md 2026-10-23); otherwise both are left in place. Nothing other than a state file that
+ * exists under the new id is overwritten, each artifact fails alone, and pi and native logs stay
+ * put as history. */
 export async function migrateLegacyRoleIds(root, legacy = LEGACY_ROLE_IDS) {
-    const notes = [];
+    const notes = { moved: [], kept: [], failed: [] };
     for (const [oldId, newId] of Object.entries(legacy)) {
         const attempt = async (what, move) => {
             try {
                 const note = await move();
-                if (note !== null)
-                    notes.push(note);
+                if (note === null)
+                    return;
+                (note.startsWith("kept ") ? notes.kept : notes.moved).push(note);
             }
             catch (err) {
-                notes.push(`could not move ${what}: ${errorMessage(err)}`);
+                notes.failed.push(`could not move ${what}: ${errorMessage(err)}`);
             }
         };
         await attempt("branch", async () => {
@@ -45,7 +78,47 @@ export async function migrateLegacyRoleIds(root, legacy = LEGACY_ROLE_IDS) {
                 return `moved ${from} to ${to}`;
             });
         }
-        for (const pathFor of [statePath, roleNotesPath, roleInboxDir, sessionDir, reviewSessionDir]) {
+        // State files get a one-time heal, not "kept": when both id-named copies exist (a state
+        // object the earlier migration renamed without rewriting `role`, so the runner kept saving
+        // under the old-id name and the two files drifted), fold them into one — when the old-id copy
+        // is the newer one, keep it under the new name and drop the stale new-name copy. A live copy
+        // carries `lastRunEndedAt`; a frozen copy (never saved since the earlier rename) carries only
+        // the pre-rename `lastTickEndedAt`, so the stamp reads either. When either copy is not a state
+        // object (unreadable/torn, or a non-object), their stamps tie, or the new-name copy is the
+        // newer one, keep both untouched, so the heal never fabricates or destroys a file it does not
+        // understand.
+        await attempt(`state ${statePath(root, oldId)}`, async () => {
+            const from = statePath(root, oldId);
+            const to = statePath(root, newId);
+            if (!fs.existsSync(from))
+                return null;
+            if (!fs.existsSync(to)) {
+                fs.renameSync(from, to);
+                rewriteStateRole(to, newId);
+                return `moved ${from} to ${to}`;
+            }
+            const stamp = (p) => {
+                const j = readJsonFile(p);
+                if (typeof j?.lastRunEndedAt === "number")
+                    return j.lastRunEndedAt;
+                return typeof j?.lastTickEndedAt === "number" ? j.lastTickEndedAt : -2; // retired-name-ok: legacy state field the frozen copy carries
+            };
+            const oldStamp = stamp(from);
+            const newStamp = stamp(to);
+            if (oldStamp < 0 || newStamp < 0 || oldStamp === newStamp)
+                return `kept ${from} and ${to}: both exist`;
+            if (oldStamp < newStamp)
+                return `kept ${from} and ${to}: both exist`;
+            // The old-id file holds the newer state (the live runner kept saving under the old name
+            // after the earlier migration). Fold it into the new-name path atomically: renameSync
+            // replaces the destination and removes the source in one step, so a crash between the two
+            // cannot leave the new-name file torn over the still-present old copy (which would read as
+            // -2 next time and wedge the heal in "kept").
+            fs.renameSync(from, to);
+            rewriteStateRole(to, newId);
+            return `healed ${from} and ${to}: kept ${from}, newer`;
+        });
+        for (const pathFor of [roleNotesPath, roleInboxDir, sessionDir, reviewSessionDir]) {
             const from = pathFor(root, oldId);
             const to = pathFor(root, newId);
             await attempt(from, async () => {

package/dist/src/roles/role-catalog.js

@@ -1,11 +1,10 @@
-// vocabulary: plain
-/** The role catalog: one built-in loop's identity and its role-specific "find something to do"
+/** The role catalog: one built-in role's identity and its role-specific "find something to do"
  * instruction text. Split out of roles.ts (2026-10-01, organize) so the catalog's embedded
  * prompt prose lives apart from the derived registries and classification helpers, which stayed
  * in roles.ts. Pure catalog data — the shared instruction fragments role prompts embed live in
  * role-guidance.ts (import-only downward, so prompt assembly depends on both without a cycle).
  * roles.ts re-exports ROLES and Role, so every existing importer keeps its import path. */
-import { backlogMoveGuidance, DECOMPOSITION_GUIDANCE, NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE, PLAN_SIZING, searchGuidance, VALIDATION_GAP_GUIDANCE, VALIDATION_GAP_QUERY, VALIDATION_GAP_TALLY, WAITING_FOR_FAILURE_NOTE, WAITING_FOR_FAILURE_PREFIX, } from "./role-guidance.js";
+import { backlogMoveGuidance, CONVERGENCE_HOLD_MARKER, DECOMPOSITION_GUIDANCE, HELD_TAG_PREFIX, NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING, PRIOR_HELD_PREFIX, searchGuidance, VALIDATION_GAP_GUIDANCE, VALIDATION_GAP_QUERY, VALIDATION_GAP_TALLY, WAITING_FOR_FAILURE_NOTE, WAITING_FOR_FAILURE_PREFIX, } from "./role-guidance.js";
 import { roleCommitGrep } from "./legacy-role-ids.js";
 import { NOTHING_TO_DO } from "../verdict/reply-contract.js";
 /** The trailer the readme role's commits carry and its `git log --grep` reads back; git parses
@@ -14,10 +13,10 @@ import { NOTHING_TO_DO } from "../verdict/reply-contract.js";
 const README_TRAILER = "Run: readme #";
 const README_TRAILER_GREP = "^(Run|Tick): readme #"; // vocabulary-ok: legacy name read from old refs or commits
 const README_TRAILER_LEGACY = "Tick: readme #"; // vocabulary-ok: legacy name read from old refs or commits
-/** The opinionated role catalog. Every loop runs one role; a role's `find` text is
- * the role-specific "find something to do" half of the tick prompt.
+/** The opinionated role catalog. Every role has one job; a role's `find` text is
+ * the role-specific "find something to do" half of the run prompt.
  *
- * Order matters: it is the scheduling priority when loops are otherwise tied
+ * Order matters: it is the scheduling priority when roles are otherwise tied
  * (e.g. the startup burst), so shipping work (feature, bugfix) outranks hygiene. */
 export const ROLES = [
     {
@@ -37,12 +36,18 @@ export const ROLES = [
    4. A plan too large to finish in this run is not split by you: append the note
       ${NEEDS_REVIEW_NOTE}
       under its heading, skip it, and implement the next available plan that fits. You may mark
-      several oversized entries while scanning, but land exactly one plan.
+      several oversized entries while scanning, but land exactly one plan. The held tag you write
+      — \`${HELD_TAG_PREFIX}<N>)\` on a Needs-review note, \`${HELD_TAG_PREFIX}<H>)\` on a
+      Needs-replan note — is ONE past the count already on the entry: read your own or an earlier
+      mark's \`${HELD_TAG_PREFIX}N)\` tag, else the \`${PRIOR_HELD_PREFIX}<N>**\` line a lift left
+      behind, else start at 1 — never reset it while the same plan ping-pongs, so three holds
+      without a merge reach \`${HELD_TAG_PREFIX}3)\`. A plan that merged and left \`## Planned\`
+      carries no marker — the convergence backstop starts fresh there.
    5. Implement it completely: code, tests, and any docs. The reviewer checks your diff against
       the entry's files-touched list and acceptance criteria, so land everything the entry
       promises, or update the entry to say what changed and why. When a plan's anchors no longer
       match the code, correct the entry in the same change instead of refusing.
-   6. Mark the plan done in PLANS.md — ${backlogMoveGuidance("PLANS.md", "## Planned", "## Done", "PLANS-DONE.md")}
+   6. Mark the plan done in PLANS.md — ${backlogMoveGuidance("PLANS.md", "## Planned", "## Done", "PLANS-DONE.md", "done")}
    7. Verify last, after the PLANS.md edit, so one run of the project's check covers everything
       you changed (see "Leave the project working" below).
 A plan that resists implementation is a finding: refuse it with the objection recorded rather
@@ -63,7 +68,7 @@ than forcing it.`,
       heading, and end the run. Do not keep investigating without new evidence.
    3. Fix it, and add a regression test that fails without the fix — run that test to watch it
       fail before the fix and pass after.
-   4. Mark it fixed in BUGS.md — ${backlogMoveGuidance("BUGS.md", "## Open", "## Fixed", "BUGS-FIXED.md")}
+   4. Mark it fixed in BUGS.md — ${backlogMoveGuidance("BUGS.md", "## Open", "## Fixed", "BUGS-FIXED.md", "fixed")}
    5. In the moved entry, write the required validation-gap trace line (format below).
    6. Verify last, after the BUGS.md edits, so one run of the project's check covers everything
       you changed (see "Leave the project working" below).
@@ -90,11 +95,30 @@ within that budget, there is nothing to do.`,
       - A plan carrying a ${NEEDS_REVIEW_NOTE} note outranks adding another plan: split it into
         independently mergeable sub-plans that cross-reference each other (per PLAN_SIZING below,
         each with its own acceptance criteria), then remove the note. That split is this run's task.
+      - A BUGS.md \`## Open\` entry carrying a ${NEEDS_REVIEW_NOTE} or ${NEEDS_REPLAN_NOTE} note
+        (the feature or bugfix role parked it as too large for one run) also outranks adding another
+        plan: resolve it in the same run by splitting it into independently fixable sub-bugs (each
+        its own BUGS.md heading) then removing the note, or by lifting the note when the work does
+        not decompose, since no
+        other role takes a held bug. That split is this run's task.
+      - A plan held by the automatic convergence hold (${CONVERGENCE_HOLD_MARKER}) also outranks
+        adding another plan: the text after the dash is the reviewer's surviving objections, so read
+        the quoted objections and the code they name and rewrite the plan so an implementation
+        following it would answer each — correcting the approach or the anchors, tightening the
+        acceptance criteria, or splitting it per PLAN_SIZING — then remove the note.
       - A plan carrying a ${NEEDS_REPLAN_NOTE} note also outranks adding another plan: read the
         quoted objections and the code they name, then rewrite the plan so an implementation
         following it would answer them — correcting the approach or the anchors, tightening the
         acceptance criteria, splitting it per PLAN_SIZING, or refusing it with the objection
         recorded when it should not be done — and remove both the note and the quoted objections.
+      - When you lift a Needs-review or Needs-replan note (a split or a rewrite) and the change
+        has NOT merged, keep the held count instead of letting it reset: remove any existing
+        \`**Previously held N**\` line on the surviving parent and every child part the split
+        produces, then write \`${PRIOR_HELD_PREFIX}<N>**\` at the lifted note's count on the
+        parent and copy it to each child, so exactly one marker survives and heldCount reads the
+        lifted count everywhere — a merged parent (one whose plan left \`## Planned\`) leaves no
+        marker, and a note with no \`(held N)\` tag (the automatic convergence hold) is lifted
+        without writing a \`**Previously held 0**\` marker.
       - Otherwise, when PLANS.md \`## Planned\` already holds one more eligible plan than there
         are feature instances (one waiting per instance, plus one for the next planner run),
         end with ${NOTHING_TO_DO} — feature has work, and a waiting plan is refined by the
@@ -113,6 +137,7 @@ within that budget, there is nothing to do.`,
       at them in ranges.
    5. Write it as a short markdown section under \`## Planned\` in PLANS.md: goal, approach, files
       touched, acceptance criteria.
+${PLAN_QUEUE_GUIDANCE}
 ${PLAN_SIZING}
 ${DECOMPOSITION_GUIDANCE}`,
     },
@@ -154,7 +179,7 @@ edit the brief between the tumwater:prompt markers.`,
         title: "code organizer",
         // Written against the 2026-10-05/06 churn: with minor fixes exhausted and the shared
         // small-and-self-contained scope rule in force, organize reorganized the whole tree one
-        // directory per tick (45 of 86 merges in four hours) with no target structure ever
+        // directory per run (45 of 86 merges in four hours) with no target structure ever
         // stated. Major refactors stay welcome; they must be considered whole and merge whole.
         find: `Find ONE way the code could be better organized, and restructure it.
    1. First rank the production source files (not the tests) by \`wc -l\`. A production module
@@ -163,7 +188,8 @@ edit the brief between the tumwater:prompt markers.`,
       file of similar size: a test file's shape follows the module it covers. An outlier that is
       mostly one large function or closure cannot be split in one run: do not start the split,
       write it as a plan in PLANS.md under ## Planned that states the target structure (which
-      state and handlers move into which module). Then look for other minor improvements to
+      state and handlers move into which module).
+${PLAN_QUEUE_GUIDANCE} Then look for other minor improvements to
       the existing structure: a module in the wrong directory, a missing separation between
       layers, or inconsistent file naming.
    2. When the minor improvements are exhausted, a major refactor — new directories, a
@@ -233,7 +259,8 @@ scratch analysis scripts — that is a different, much larger task.`,
 this run's ONE task: move each listed entry to the section its heading's dates say it belongs in
 (cut and paste, under the existing \`## \` heading — never add, remove, or rename a \`## \`
 heading), leave its text verbatim, and change nothing else. An entry listed under PLANS-DONE.md's
-\`## Done\` with no done date goes back under PLANS.md's \`## Planned\`.
+\`## Done\` with no done date is already finished and archived there: keep it in place and only add the
+missing \`done YYYY-MM-DD\` to its \`### \` heading — never move it back under PLANS.md's \`## Planned\`.
 
 Otherwise, pick ONE kind of uncleanliness — dead code, misleading names, commented-out blocks,
 overly clever constructs, missing or wrong doc comments on public surfaces, inconsistent
@@ -319,6 +346,52 @@ Safety rails for anything you launch:
 The FLOW line — required on every run: your final reply carries one result-carrying line — \`FLOW: <name> — <passed|bug>\` — naming the flow you exercised and whether it passed or filed a bug (spell the name as the coverage block does, e.g. \`FLOW: run (real) — passed\`), placed just before your ending (the nothing-to-do line, or the SUMMARY block when you filed a bug). The verdict is required: a bare \`FLOW: <name>\` with no \`passed|bug\` suffix is not a result and is not recorded, so the rotation never advances. tumwater records it for the next run's coverage block. A passing flow's reply ends with two lines in this form, with the name of the flow you actually exercised in place of <name>:
    FLOW: <name> — passed
    ${NOTHING_TO_DO}`,
+    },
+    {
+        id: "ci",
+        tier: "default",
+        title: "CI parity runner",
+        find: `Run the CI workflow's own jobs against main's tip and repair what fails. You close the gap
+between what GitHub CI runs and what the team's own merge gate skips: the workflow's test job runs
+the project's whole test suite and e2e suite, while the merge gate runs only the affected tests —
+so only you run the whole thing where it counts, before a user, a release tag, or a post-merge
+reviewer finds what a green gate missed.
+
+Steps:
+   1. Read .github/workflows/ci.yml fresh each run and execute its jobs' own run: steps verbatim
+      against main's tip in this worktree, in order — for an npm project like this repo, that is
+      \`npm ci\`, then \`npm test\`, then \`npm run test:e2e\`; when the tip is a push-to-main tip,
+      also \`npm pack\` (the workflow's package job). The actions/checkout, setup-node and git
+      identity are this worktree's own. Reading the workflow means a step added to it is picked
+      up without a code change.
+   2. A failing step is the work: reproduce it, fix the source/tests/docs it names, re-run that
+      step until green, and commit the fix as the run's one change. A step that fails once and
+      passes on the re-run is a flake — file ONE BUGS.md entry naming the test and the flake and
+      change nothing else.
+   3. Whatever a failing step's own cause you cannot fix is filed in BUGS.md with the failing
+      output quoted.
+
+Boundaries:
+   - You never edit .github/workflows/* (you read them) and never weaken a test to make a step
+     pass.
+   - Your product is a verdict and a fix: when everything is green, declare nothing-to-do (here
+     \`no_change\` means "checked, green") rather than inventing busywork.
+
+The parity block and the CI line — both required on every run: your prompt carries a CI parity
+block from this team's own record naming the main tip and lock hash the last run covered. When it
+says \`current\` (main unmoved since the last green run covered exactly this tip with exactly this
+lock), declare nothing-to-do in ONE model run without running the suite — that is the cheap no-op
+the block exists for. When it is stale (main moved, the lock changed, or the last run failed), run
+the full workflow as the steps above say. Your final reply then carries one result-carrying line —
+\`CI: <sha> — <passed|failed>\` — naming the main tip you covered and whether it passed or failed,
+placed just before your ending (the nothing-to-do line, or the SUMMARY block when you committed a
+fix). The verdict is required and the sha must be a hex id: a bare \`CI: <sha>\` is not a result and
+is not recorded, so the parity block cannot advance on a truncated reply (the same rule as qa's
+FLOW line). tumwater records it for the next run's parity block. A passing run's reply ends with two
+lines in this form:
+   CI: <sha> — passed
+   ${NOTHING_TO_DO}
+`,
     },
     {
         id: "selfcheck",
@@ -330,6 +403,9 @@ the last day (per-role outcome counts, each role's time and spend by outcome, no
 warning clusters, review rejections, and what merged). It is your entire evidence base — do not go
 looking for the event log or per-role transcripts yourself; tumwater injects the digest because
 the live log lives outside your worktree.
+The digest ends with a ## Fast merge guardrails section when the post-merge machinery is failing
+quietly (main red over 30 minutes, quarantine aged or oversized). Each line there is tumwater's
+own response failing, so it is fileable as it stands under rule 1.
    1. A cluster is a bug ONLY when tumwater's RESPONSE to it is wrong — a failure that raised no
       alarm, drove the wrong state or sleep ladder, latched a stale verdict, or hid itself from
       the user. A mere infrastructure failure (the model server was slow, pi exited non-zero)
@@ -349,6 +425,44 @@ the live log lives outside your worktree.
       entry, so the bugfix role can reproduce it.
 BUGS.md is your only write; never edit source, tests, or docs. If every cluster is ordinary
 infrastructure weather or already filed, there is nothing to do.`,
+    },
+    {
+        id: "feedback",
+        tier: "default",
+        title: "feedback: files tumwater bugs upstream on GitHub",
+        find: `File ONE bug per run as a GitHub issue on github.com/znation/tumwater, or declare
+nothing-to-do, from the <failure-digest> block in your prompt: a deterministic digest of this
+project's own event log over the last day (per-role outcome counts, each role's time and spend by
+outcome, normalized error and warning clusters, review rejections, and what merged). It is your
+entire evidence base — do not go looking for the event log or per-role transcripts yourself; tumwater
+injects the digest because the live log lives outside your worktree.
+The digest ends with a ## Fast merge guardrails section when the post-merge machinery is failing
+quietly (main red over 30 minutes, quarantine aged or oversized). Each line there is tumwater's
+own response failing, so it is fileable as it stands under rule 1.
+   1. A cluster is a bug ONLY when tumwater's RESPONSE to it is wrong — a failure that raised no
+      alarm, drove the wrong state or sleep ladder, latched a stale verdict, or hid itself from
+      the user. A mere infrastructure failure (the model server was slow, pi exited non-zero)
+      is weather, not a bug: filing it produces an issue no maintainer can act on.
+   2. Read the digest for that wrong response — 44 identical errors that raised no warning, a run
+      that failed in 200 ms then climbed the idle ladder, a cluster that begins on the date a
+      specific commit merged.
+   3. Rank what you would file by LOSS, not by run count: the digest's time-and-spend table and
+      top loss causes price each cause in agent-hours and dollars, and a cluster that burned hours
+      outranks one that burned seconds — cite its cost when it is the reason you file.
+   4. Before filing, dedupe: check the "Previously filed from this install" block in your prompt
+      and run \`gh issue list --repo znation/tumwater --search <cluster terms>\` — never file a
+      duplicate. When the same cluster is already filed, there is nothing to do.
+   5. File it with \`gh issue create --repo znation/tumwater --title … --body …\` from the shell
+      and verify the issue URL in the command's output before you report it. The body cites the
+      cluster's normalized key, its count and roles, the correlated \`merged\` commit, and the
+      output of \`tumwater version\`; redact absolute paths and secrets — file only what the digest
+      itself already shows.
+You never edit files in this repo — \`gh\` is your only write. End every run with the
+${NOTHING_TO_DO} sentinel; when you filed, one \`FILED: #<n> — <title>\` line rides just above it
+(named as qa's FLOW line is). A run that cannot file because \`gh\` is missing, unauthenticated,
+or failed ends WITHOUT the sentinel, naming the failure in your final prose so tumwater's
+finished-without-changes warning surfaces it. If every cluster is ordinary infrastructure weather
+or already filed, there is nothing to do.`,
     },
     {
         id: "security",
@@ -461,6 +575,7 @@ arguments, config files, environment), and rough edges you meet while running th
       - promote a recurring non-\`none\` \`gap:\` tag — three or more Fixed entries carrying it —
         into a PLANS.md entry for the infrastructure that would retire it, citing those entries.
         ${VALIDATION_GAP_TALLY}
+        ${PLAN_QUEUE_GUIDANCE}
 You edit only markdown — never source.
 
 Reading the backlog files: PLANS.md and BUGS.md hold open work, so read them whole when your move

package/dist/src/roles/role-guidance.js

@@ -1,11 +1,10 @@
-// vocabulary: plain
 /** Shared instruction fragments role prompts and prompt assembly embed verbatim. Pure
  * data: this module imports only the dependency-free legacy-role-ids, so prompt assembly
  * can depend on it without a cycle.
  * Split from roles.ts, whose catalog (now role-catalog.ts) find texts embed these fragments
  * while prompt.ts embeds them too — the wording is one concern, the catalog another. */
 import { roleCommitGrep } from "./legacy-role-ids.js";
-/** Shared guidance for any loop about to record a plan or bug: split independent parts
+/** Shared guidance for any role about to record a plan or bug: split independent parts
  * into their own entries. Defined once so the director and role prompts cannot drift.
  * Lives here (not in prompt.ts) because two role `find` texts embed it — keeping this
  * module import-free, with the dependency running one way: prompt assembly → roles,
@@ -14,8 +13,8 @@ export const DECOMPOSITION_GUIDANCE = `Before recording a plan or bug, check whe
 into independent subparts (separate features, or separate bugs). If it does, record each part as
 its own PLANS.md/BUGS.md entry that cross-references its siblings, so roles can pick them up
 independently; if the parts are not truly independent, keep a single entry.`;
-/** Shared instruction for closing a backlog entry (the feature loop moving a plan to Done,
- * the bugfix loop moving a bug to Fixed). Written against the observed failure (PLANS.md
+/** Shared instruction for closing a backlog entry (the feature role moving a plan to Done,
+ * the bugfix role moving a bug to Fixed). Written against the observed failure (PLANS.md
  * 2026-09-30, part 1/3): "move it to a Done section" reads as "create a section", and five
  * commits left PLANS.md with two `## Done` headings — so the wording names the file's EXISTING
  * resolved heading, forbids touching `## ` structure, and gives the verifiable invariant
@@ -23,11 +22,16 @@ independently; if the parts are not truly independent, keep a single entry.`;
  * numbered step of their task. The pasted entry does not stay there: tumwater moves it to the top
  * of `archive` when the change commits (plans/backlog-archive.md), which the last line says so no
  * run opens the archive to do it by hand. Takes the file, section and archive names so the feature
- * and bugfix texts cannot drift apart; lives here with the other shared fragments. */
-export function backlogMoveGuidance(file, openSection, resolvedSection, archive) {
+ * and bugfix texts cannot drift apart; lives here with the other shared fragments. Also takes
+ * the closing token ("done" for a finished plan, "fixed" for a BUGS.md record) chosen by the
+ * caller, so the verb and the heading-key rule are named instead of left for the role to guess. */
+export function backlogMoveGuidance(file, openSection, resolvedSection, archive, token) {
     return `move the entry, step by step:
       a. cut the entry out of \`${openSection}\`;
-      b. add the closing date to its \`### \` heading;
+      b. add the closing stamp to its \`### \` heading, at the end — \`— ${token} YYYY-MM-DD by the <role> role\`
+         (a finished plan appends it after its existing \`(planned …)\` parenthetical; the heading
+         text before its first \` (\` must not change, or the gate reads it as a brand-new entry
+         under \`${resolvedSection}\` rather than a move);
       c. paste it as the first entry under the file's existing \`${resolvedSection}\` heading;
       d. if it was the last entry under \`${openSection}\`, leave a \`_None yet._\` placeholder
          there.
@@ -39,7 +43,7 @@ export function backlogMoveGuidance(file, openSection, resolvedSection, archive)
  * a comment inside the template would become prompt text. */
 const REQUIRES_PART_FORM = "requires part N/M landed"; // vocabulary-ok: requiredParts parses this heading syntax
 /** Shared sizing rule for anyone writing a plan (the plan role and the director): the feature
- * loop is one mid-sized local model working alone in one run, and the review gate rejects a
+ * role is one mid-sized local model working alone in one run, and the review gate rejects a
  * change that lands less than its entry promises — so a plan must fit that run. Oversized plans
  * were the pattern behind "half-done against its own plan" rejections. The last sentence is the
  * self-hosting build lag (BUGS.md 2026-09-23): plan 4b bundled "the merge preserves the live
@@ -58,6 +62,17 @@ ranges, because line anchors go stale with every merge. When tumwater is buildin
 every commit merges under the build that predates it, so a
 change to how merges behave and any step that depends on it are separate sub-plans, the second
 merge only once the first is the running build.`;
+/** Shared guidance for anyone writing a plan (the plan role, the organize role, and the
+ * director): a new plan joins the BACK of the `## Planned` queue, never the top. Part of the
+ * define-once pattern of DECOMPOSITION_GUIDANCE/PLAN_SIZING — file order under `## Planned` IS
+ * the work queue: claim assignment takes the first free entry in file order (`assignNext`,
+ * src/scheduling/claims.ts), so an entry set at the top jumps ahead of work already waiting.
+ * Lives here because three role `find` texts and the director's routing bullet embed it. */
+export const PLAN_QUEUE_GUIDANCE = `A new plan joins the queue at the BACK: append the entry at the
+END of \`## Planned\`, after every existing entry, never at the top. File order under
+\`## Planned\` is the work queue — claim assignment takes the first free entry in that order
+(\`assignNext\`, src/scheduling/claims.ts) — so an entry inserted at the top jumps ahead of work
+already waiting.`;
 /** The closed vocabulary for the validation-gap trace (plans/repair-traces.md): what made a bug
  * hard to *confirm*, which is the only evidence of where this project's test infrastructure is
  * weakest. Closed on purpose so the traces aggregate, and `none` is a written value rather than an
@@ -109,36 +124,66 @@ export const VALIDATION_GAP_QUERY = `grep -snE '\\*\\*Validation gap:\\*\\* (${V
  * parsing the date or the wording out of the full template — the same split as
  * NEEDS_REPLAN_PREFIX. */
 export const NEEDS_REVIEW_PREFIX = `**Needs review `;
-/** The markdown note the feature loop appends to a plan it cannot finish in one run, so the plan
- * loop can split it. Mirrors the **Refused …** note convention: a note the next fresh tick reads,
+/** The tag text before the held count, shared by the note templates and the parser
+ * (backlog-eligibility's heldCount) so the two cannot drift: the live count on a Needs-review
+ * or Needs-replan note is written inline as `(held N)`, with `N` one past the surviving prior
+ * count (the feature role appends it, the plan role's split carries it via PRIOR_HELD_NOTE). */
+export const HELD_TAG_PREFIX = `(held `;
+/** The markdown note the feature role appends to a plan it cannot finish in one run, so the plan
+ * role can split it. Mirrors the **Refused …** note convention: a note the next fresh run reads,
  * with no code parsing it. Defined once so the feature and plan texts and the director's routing
- * clause cannot drift. */
-export const NEEDS_REVIEW_NOTE = `${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature: too large for one run**`;
+ * clause cannot drift. The trailing `(held <N>)` tag (HELD_TAG_PREFIX) is the live held count,
+ * written as one past the count surviving on the entry; it sits inside the line, so
+ * NEEDS_REVIEW_PREFIX still recognizes the note. */
+export const NEEDS_REVIEW_NOTE = `${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature: too large for one run ${HELD_TAG_PREFIX}<N>)**`;
+/** The literal reason the automatic convergence hold writes into a held plan's note
+ * (holdEntryAfterExhaustion, src/runner/revision.ts, builds the note as
+ * `**Needs review … by <role>: could not converge — <surviving objections>**`, INV-BH4).
+ * Exported so the writer and the reader share one literal: it sits between holdEntryAfterExhaustion
+ * (which writes the note) and the plan role's charter (role-catalog.ts `find`) which reads it, so
+ * reason to recognize the automatic hold as distinct from the feature role's too-large
+ * ${NEEDS_REVIEW_NOTE} note and the ${NEEDS_REPLAN_PREFIX} note — both carry no
+ * `could not converge` text, so the charter routes each hold to its own action without matching
+ * on a second literal. Add no second spelling of this text. */
+export const CONVERGENCE_HOLD_MARKER = "could not converge";
+/** The marker a lifted hold leaves behind, so a split or rewrite carries the count instead of
+ * letting it reset: `**Previously held N**` on the note's line. The live count is `(held N)` on
+ * the note; the surviving marker after a lift is `**Previously held N**` — heldCount reads the
+ * first as the priority, then the second. */
+export const PRIOR_HELD_PREFIX = `**Previously held `;
+/** The literal marker a lift leaves on a split or rewrite so the held count survives instead of
+ * resetting: a `**Previously held <N>**` line at the same count the lifted note carried (the
+ * <N> here is the value the note's `(held N)` tag held). heldCount reads this as the fallback
+ * when no live note is present, so the count round-trips a split. */
+export const PRIOR_HELD_NOTE = `${PRIOR_HELD_PREFIX}<N>**`;
 /** The literal prefix every Needs-replan note starts with. Exported so a reader that only has to
  * recognize one (the backlog index's ` [blocked: needs replan]` mark) can match on it instead of
  * parsing the date or the round count out of the full template. */
 export const NEEDS_REPLAN_PREFIX = `**Needs replan `;
-/** The markdown note the feature loop appends under a plan whose change was rejected after its
- * final revision round, carrying the reviewer's objections back to the strong-tier plan loop
+/** The markdown note the feature role appends under a plan whose change was rejected after its
+ * final revision round, carrying the reviewer's objections back to the strong-tier plan role
  * instead of letting feature re-author the same plan. Same convention as NEEDS_REVIEW_NOTE: a
- * note a later fresh tick reads, with no code parsing it. */
-export const NEEDS_REPLAN_NOTE = `${NEEDS_REPLAN_PREFIX}<YYYY-MM-DD> by feature: rejected after <N> review rounds**`;
+ * note a later fresh run reads, with no code parsing it. The trailing `(held <H>)` tag
+ * (HELD_TAG_PREFIX) is the live held count, one past the count surviving on the entry; the
+ * placeholder is `<H>` (for held) so it reads apart from the `<N>` review-round count earlier
+ * in the same line. It sits inside the line, so NEEDS_REPLAN_PREFIX still recognizes the note. */
+export const NEEDS_REPLAN_NOTE = `${NEEDS_REPLAN_PREFIX}<YYYY-MM-DD> by feature: rejected after <N> review rounds ${HELD_TAG_PREFIX}<H>)**`;
 /** The literal prefix every Waiting-for-the-next-failure note starts with. Exported so a reader
  * that only has to recognize one (the backlog index's ` [blocked: waiting for the next failure]`
  * mark) can match on it instead of parsing the date or the wording out of the full template. */
 export const WAITING_FOR_FAILURE_PREFIX = `**Waiting for the next failure `;
-/** The markdown note the bugfix loop writes under an open bug it cannot reproduce once it has made
+/** The markdown note the bugfix role writes under an open bug it cannot reproduce once it has made
  * the failure explain itself, so bugfix stops spending runs without new evidence. Same convention
- * as NEEDS_REPLAN_NOTE: a note a later fresh tick reads. It lifts when whoever records the next
+ * as NEEDS_REPLAN_NOTE: a note a later fresh run reads. It lifts when whoever records the next
  * occurrence deletes the line, or by `tumwater bug --release <n>`. */
 export const WAITING_FOR_FAILURE_NOTE = `${WAITING_FOR_FAILURE_PREFIX}<YYYY-MM-DD> by bugfix: <what the next failure's message will show>**`;
 /** How a role with no backlog (organize, clean, dedupe, perf, security, robustness, improve) finds
  * its one task, as numbered steps. Written against the observed failure: with nothing to point
  * at, a local model reads the codebase file by file — thirty whole-file reads, ~300 KB of tool
- * output — and then either fills its window or declares nothing-to-do (improve: 41 of 44 ticks in
+ * output — and then either fills its window or declares nothing-to-do (improve: 41 of 44 runs in
  * the first week of September landed nothing). Cheap signals shortlist candidates; a decision
  * deadline ends the search; the harness's own commit subjects (`tumwater(<role>): …`) are the
- * only cross-tick memory of what the role did lately, so the text names them. Takes the role id
+ * only cross-run memory of what the role did lately, so the text names them. Takes the role id
  * so the git command is literal, not a placeholder the model has to fill in. */
 export function searchGuidance(roleId) {
     return `How to search — do not read the codebase file by file: a whole-tree survey costs most of