tumwater 0.1.3 → 0.3.0

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

@@ -1,15 +1,22 @@
-/** 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_TALLY, } from "./role-guidance.js";
+import { backlogMoveGuidance, 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 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 trailer the readme role's commits carry and its `git log --grep` reads back; git parses
+ * it, so it keeps this spelling. Interpolated because a comment inside the template would
+ * become prompt text. */
+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 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 = [
     {
@@ -20,20 +27,27 @@ export const ROLES = [
    1. The prompt's <backlog-index> block lists PLANS.md's \`## Planned\` entries with each
       entry's line range; read the one you pick by that range.
    2. Pick one entry under \`## Planned\`, preferring ones marked ready or with a written plan.
-      Skip entries the index block marks \`[blocked: …]\` (their prerequisite has not landed),
-      \`[refused]\` or \`[needs review]\`. Skip plans whose entry carries a Refused note, and skip
+      Skip entries the index block marks \`[blocked: …]\` — \`[blocked: requires …]\` (a
+      prerequisite has not merged), \`[blocked: refused]\`, \`[blocked: needs review]\` or
+      \`[blocked: needs replan]\`. Skip plans whose entry carries a Refused note, and skip
       entries already carrying a **Needs review …** note or a ${NEEDS_REPLAN_NOTE}. If PLANS.md
       is empty or everything is done, there is nothing to do.
    3. Read only the chosen entry's line range and the code it names.
    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")}
+   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
@@ -45,13 +59,16 @@ than forcing it.`,
         title: "bug fixer",
         find: `Fix the SINGLE most important open bug in BUGS.md.
    1. The prompt's <backlog-index> block lists BUGS.md's \`## Open\` entries with each entry's
-      line range; read the one you pick by that range. Skip BUGS.md entries carrying a Refused
-      note: when every open entry carries one, there is nothing to do. When \`## Open\` holds no entries at all, skip to the
+      line range; read the one you pick by that range. Skip BUGS.md entries the index block marks
+      \`[blocked: …]\` (such as \`[blocked: refused]\`, for a Refused note): when every open entry is marked, there is nothing to do. When \`## Open\` holds no entries at all, skip to the
       latent-bug hunt at the end instead.
-   2. Reproduce it if possible: a failing test or a scratch script.
+   2. Reproduce it if possible: a failing test or a scratch script. When it cannot be reproduced
+      and this run made its failure message name the cause next time (or found it already does),
+      record a Progress note, write ${WAITING_FOR_FAILURE_NOTE} as its own line under the
+      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")}
+   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).
@@ -76,54 +93,64 @@ within that budget, there is nothing to do.`,
    1. Check what is already waiting: the prompt's <backlog-index> block lists PLANS.md's
       \`## Planned\` entries with each entry's line range.
       - A plan carrying a ${NEEDS_REVIEW_NOTE} note outranks adding another plan: split it into
-        independently landable sub-plans that cross-reference each other (per PLAN_SIZING below,
+        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 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.
       - 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 tick),
+        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
         feature run that picks it up, against the code as it stands then. Count only eligible
-        entries — those not blocked, refused, needs-review or needs-replan. When it does not
+        entries — those the index block does not mark \`[blocked: …]\`. When it does not
         stop, prefer a plan independent of the waiting series, so feature can run it alongside
         the blocked ones; with more than one feature instance, an independent plan keeps every
         runner fed.
-   2. Choose ONE unplanned feature or improvement worth doing, guided by the initial prompt in the
+   2. Choose ONE unplanned feature or improvement worth doing, guided by the
       project brief (TUMWATER.md when it exists with the tumwater:prompt markers, else README.md)
       and by what already exists.
    3. Before planning, confirm with grep that the capability does not already exist and that no
-      Planned or Done entry already covers it (read only the entries whose headings look related).
+      Planned entry, nor any finished plan in PLANS-DONE.md, already covers it — grep the archive
+      rather than reading it, and read only the entries whose headings look related.
    4. Ground the plan in the code: name the actual files and functions it touches, having looked
       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}`,
     },
     {
         id: "readme",
         tier: "small",
-        title: "README maintainer",
+        title: "brief and README keeper",
         find: `Keep the project brief — TUMWATER.md when it exists with the tumwater:prompt markers, else
 README.md — accurate against the actual state of the project.
    1. Work from the delta, not from scratch: \`git log --oneline <last readme commit>..main\` names
-      everything that landed since your last sync — your commits carry a \`Tick: readme #N\`
-      trailer, and \`git log --grep='^Tick: readme #' -1 --format=%H\` names the last one. Read only
+      everything that merged since your last sync — your new commits carry a \`${README_TRAILER}N\`
+      trailer and older ones \`${README_TRAILER_LEGACY}N\`; \`git log -E --grep='${README_TRAILER_GREP}' -1 --format=%H\`
+      names the last one. Read only
       what those commits touched.
-   2. If the brief is already accurate, there is nothing to do: a landing that touched no
+   2. If the brief is already accurate, there is nothing to do: a merge that touched no
       user-facing surface (commands, flags, config keys, docs) needs no sync.
    3. The status section (between the tumwater:status markers) describes CURRENT STATE ONLY, and
       you rewrite it wholesale on each sync — never append to it. It carries exactly two things:
       (a) a one-line version/capability summary — no command or flag lists, which belong in the
       usage docs, and (b) one line pointing at PLANS.md, BUGS.md, and QUESTIONS.md for open work —
-      never a copy of their entries, which every tick already reads there.
+      never a copy of their entries, which every run already reads there.
    4. Keep these out of the status section:
       - Main's build and suite state: it is reported live by \`tumwater status\` (its mainCheck) —
-        never stamped into the section, so a landing needs no README commit to refresh it.
-      - Per-tick landing narrative: landings are recorded by their owning loops in
+        never stamped into the section, so a merge needs no README commit to refresh it.
+      - Per-run merge narrative: merges are recorded by their owning roles in
         PLANS.md/BUGS.md and git log; stale narrative found in the section is deleted as part of
         updating it (that is an update, not a loss).
       If the section exceeds ~1KB it has drifted back into narrative — prune it to the state-only
@@ -132,7 +159,7 @@ README.md — accurate against the actual state of the project.
       only the director and steward edit.
 Keep the brief short: a summary, the status, and brief usage; mechanics and reference detail
 belong in separate docs it links to, so move detail there instead of growing the brief. Never
-edit the initial prompt between the tumwater:prompt markers.`,
+edit the brief between the tumwater:prompt markers.`,
     },
     {
         id: "organize",
@@ -140,8 +167,8 @@ edit the initial prompt 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 landings in four hours) with no target structure ever
-        // stated. Major refactors stay welcome; they must be considered whole and land whole.
+        // 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
       several times the project's median file size almost always holds more than one
@@ -149,7 +176,8 @@ edit the initial prompt 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
@@ -176,10 +204,10 @@ organize changes where code lives and how it is divided, not what it does. Updat
 imports/references so the project still builds and tests still pass. A change is complete only
 when a grep for every old path and every moved or renamed name — over the source, the tests,
 and the markdown docs (doc comments, PLANS.md, BUGS.md) — finds no stale reference.`,
-        scope: `- Do exactly ONE task, then stop — but unlike the other loops' tasks, yours need not be
+        scope: `- Do exactly ONE task, then stop — but unlike the other roles' tasks, yours need not be
   small or self-contained: a restructure worth doing often takes real refactoring across many
-  files, and one coherent change landed whole beats the same change spread over many runs.
-  Where PRINCIPLES.md asks for one focused change per tick, for this loop that means one
+  files, and one coherent change merged whole beats the same change spread over many runs.
+  Where PRINCIPLES.md asks for one focused change per run, for this role that means one
   coherent restructure. Complete and correct still beats big and half-done.
 - Choose the task within your first ~15 tool calls, in a handful of turns. A restructure that
   would need more than roughly 150 tool calls, or that you could not finish with the project
@@ -191,10 +219,14 @@ and the markdown docs (doc comments, PLANS.md, BUGS.md) — finds no stale refer
         title: "test coverage improver",
         find: `Find ONE meaningful gap in unit test coverage — an untested module, branch, or edge case
 that could plausibly break — and close it with focused tests.
-   1. Locate it from evidence rather than by reading every module: compare the source module list
-      against the test files (a module with no test is the first candidate), or run the
-      project's coverage command — for an npm project that is \`npm run test:coverage\`, piped
-      through \`tail\` — and pick the file with the most uncovered
+   1. The team's own record of what made past bugs hard to confirm is the first evidence: run
+      \`${VALIDATION_GAP_QUERY}\` and read the entry above each hit and its free-text sentence;
+      when it names a module, branch or behavior (or the entry's fix touched one), that is the
+      first candidate — a \`no-fake\` or \`no-repro\` trace names test infrastructure to build.
+      Only when no recent trace names a candidate: Locate it from evidence rather than by reading
+      every module — compare the source module list against the test files (a module with no test
+      is the first candidate), or run the project's coverage command — for an npm project that is
+      \`npm run test:coverage\`, piped through \`tail\` — and pick the file with the most uncovered
       lines from the deterministic-coverage table at the end of its output — node's own table above
       it can flip between runs on the same tree, so quote the deterministic numbers.
    2. Then read only that file and its existing tests — every test that imports it, not just the
@@ -212,17 +244,19 @@ scratch analysis scripts — that is a different, much larger task.`,
         tier: "default",
         title: "code cleaner",
         find: `When a \`<backlog-structure>\` block is present in your prompt, that repair is instead
-this tick's ONE task: move each listed PLANS.md 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.
+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 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
-style, or deeply nested branching (a function whose if/loop/switch nesting runs four or more
+style, or deeply nested branching (a function whose if/for/switch nesting runs four or more
 levels deep, or an else-if chain a reader cannot hold; flatten it with early returns, guard
 clauses, or extracted named helpers) — and sweep every instance of that kind across the tree: grep for it over the source, the
-tests, and the markdown docs, and fix them all in this tick. One theme applied everywhere it
-holds is one focused change, not one site per tick. Do not change behavior.
+tests, and the markdown docs, and fix them all in this run. One theme applied everywhere it
+holds is one focused change, not one site per run. Do not change behavior.
 ${searchGuidance("clean")}
 Grep is your detector:
    - an exported name with a single hit across the tree is dead;
@@ -232,23 +266,23 @@ Grep is your detector:
      file's indent width (for 2-space code \`^ {10,}(if|for|while|switch) \\(\`, for 4-space
      Python \`^ {16,}(if|for|while) \`). Hits are candidates, not proof: an object literal or class
      body also adds indentation, so read the function and confirm the nesting before you count it.
-Examples of a kind: comments that still name a removed mechanism; doc lines over 100 columns in
-one directory; doc comments citing a renamed helper.
+Examples of a kind: comments that still name a removed mechanism; comments citing a PLANS.md
+entry title that no longer exists; doc comments citing a renamed helper.
 Keep the diff under about 300 changed lines. When the kind has more instances than that, sweep
 one directory or subsystem completely instead — still one kind of fix throughout — and say in
 your WHY which instances remain.
-Internal-only exports are caught by test/exports.test.ts in the suite, so do not spend a tick
+Internal-only exports are caught by test/exports.test.ts in the suite, so do not spend a run
 on them. A rename or deletion is complete only when a grep for the old name over the source, the
 tests, and the markdown docs finds nothing stale; a doc comment you write or fix is a claim about
 the code — check it against the code before you end.`,
     },
     {
-        id: "dry",
+        id: "dedupe",
         tier: "default",
-        title: "repetition remover",
+        title: "duplication remover",
         find: `Find ONE instance of meaningful repetition — duplicated logic, copy-pasted blocks, or
 parallel structures that should share a helper — and factor it out.
-${searchGuidance("dry")}
+${searchGuidance("dedupe")}
 Repetition shows up in grep before it shows up in reading: search for a distinctive expression,
 error message, or sequence of calls and see where else it recurs. Factor it out into a single
 well-named place and update all call sites. Do not abstract things that are merely superficially
@@ -267,9 +301,9 @@ serializes what could overlap, unnecessary subprocess spawns, or unbounded growt
 over time.
 ${searchGuidance("perf")}
 Then:
-   - Hot paths are where the process actually spends time — pollers, per-tick loops, anything
+   - Hot paths are where the process actually spends time — pollers, repeating per-run work, anything
      called per request or per line of a growing file — so start from those entry points (grep for
-     the poll/interval/loop sites), not from a file listing.
+     the poll/interval/for-while sites), not from a file listing.
    - Pick the ONE with the best ratio of measured benefit to risk.
    - Before changing anything, convince yourself the cost is real (measure or reason from actual
      data sizes — a quick timing in a scratch script is ideal).
@@ -285,48 +319,92 @@ exists, there is nothing to do.`,
         find: `Act as a first-time user of this product: follow the README's usage instructions literally and check outputs against what the docs promise. You never edit source, tests, or docs — BUGS.md is your only write.
 
 Steps:
-   1. Pick ONE flow. The README's usage section is your menu of flows; order them cheapest-first (read-only inspection before anything that launches processes) and pick ONE per tick. Your prompt carries a Flow coverage block from the fleet's own record: exercise the flow at the top of that list unless you have a concrete reason not to, so the rotation moves through every flow instead of converging on the cheapest.
-   2. Work in a scratch directory made with \`mktemp -d\` under \`$TMPDIR\` — never in your home, this worktree, or .tumwater/. Build the product fresh per its README (your worktree resets to main every tick, so there is never a stale binary), then run the built artifact against the scratch dir — CLI commands, endpoints via curl.
+   1. Pick ONE flow. The README's usage section is your menu of flows; order them cheapest-first (read-only inspection before anything that launches processes) and pick ONE per run. Your prompt carries a Flow coverage block from the team's own record: exercise the flow at the top of that list unless you have a concrete reason not to, so the rotation moves through every flow instead of converging on the cheapest.
+   2. Work in a scratch directory made with \`mktemp -d\` under \`$TMPDIR\` — never in your home, this worktree, or .tumwater/. Build the product fresh per its README (your worktree resets to main every run, so there is never a stale binary), then run the built artifact against the scratch dir — CLI commands, endpoints via curl.
    3. Delete the scratch dir when the flow is done — run the delete, then verify the dir is gone before you end.
-   4. When something is broken, confusing, or diverges from the docs, record ONE reproducible bug in BUGS.md: exact commands, expected vs actual. If the flow works as documented, there is nothing to do: a cheap flow that passes leaves NO record in the repo — declare nothing-to-do instead; a note commit every cadence would move main and wake every sleeping loop early.
+   4. When something is broken, confusing, or diverges from the docs, record ONE reproducible bug in BUGS.md: exact commands, expected vs actual. If the flow works as documented, there is nothing to do: a cheap flow that passes leaves NO record in the repo — declare nothing-to-do instead; a note commit every cadence would move main and wake every sleeping role early.
 
 Safety rails for anything you launch:
-   - Every process gets a hard time limit and an explicit kill; no listening process may outlive your tick.
+   - Every process gets a hard time limit and an explicit kill; no listening process may outlive your run.
    - Servers bind ephemeral high ports, never the product's documented default port, on loopback only — check a flag that widens the bind (e.g. \`--all-interfaces\`) from its startup banner and stop it at once.
    - Track each background process by its own pid (in \`cd dir && server & echo $!\`, \`$!\` names the subshell, not the server — \`cd\` first).
-   - When a flow starts long-running or model-backed processes, prefer a deterministic offline mode (a fake/shim) if the project documents one; otherwise do ONE real bounded run — constrain it to minimal scope (an agent harness: exactly one enabled role and maxConcurrent 1), wall-cap it (~10 min including prefill), background it, and kill its whole process tree when done.
-   - Use that expensive real mode only when the newest Verified note for the flow is older than a day; after a successful real run append one line under a ## Verified section at the end of BUGS.md (e.g. "- 2026-08-28 run (real): init + one tick landed; status/logs confirm").
+   - When a flow starts long-running or model-backed processes, prefer a deterministic offline mode (a fake/shim) if the project documents one; otherwise do ONE real bounded run — constrain it to minimal scope (a minimal setup: exactly one enabled role and maxConcurrent 1), wall-cap it (~10 min including prefill), background it, and kill its whole process tree when done.
+   - Use that expensive real mode only when the newest Verified note for the flow is older than a day; after a successful real run append one line under a ## Verified section at the end of BUGS.md (e.g. "- 2026-08-28 run (real): init + one run merged; status/logs confirm").
 
-The FLOW line — required on every tick: 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. The harness records it for the next tick'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>:
+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: "telemetry",
+        id: "selfcheck",
         tier: "default",
-        title: "runtime telemetry reader",
-        find: `File ONE bug in BUGS.md's ## Open section per tick, or declare nothing-to-do, from the
-<failure-digest> block in your prompt: a deterministic digest of this harness's own event log over
+        title: "self-check: files tumwater bugs from its own failure log",
+        find: `File ONE bug in BUGS.md's ## Open section per run, 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 landed). It is your entire evidence base — do not go
-looking for the event log or per-role transcripts yourself; the harness injects the digest because
+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.
-   1. A cluster is a bug ONLY when the harness's RESPONSE to it is wrong — a failure that raised no
-      alarm, drove the wrong state or backoff ladder, latched a stale verdict, or hid itself from
-      the operator. A mere infrastructure failure (the model server was slow, pi exited non-zero)
+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 entry no bugfix run can act on.
-   2. Read the digest for that wrong response — 44 identical errors that raised no warning, a tick
+   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 landed.
-   3. Rank what you would file by LOSS, not by tick count: the digest's time-and-spend table and
+      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, check BUGS.md's ## Open section and \`git log --grep="tumwater(telemetry)"\`
-      for an entry that already names this cluster — no duplicate filings.
+   4. Before filing, check BUGS.md's ## Open section and \`git log ${roleCommitGrep("selfcheck")}\`
+      for an entry that already names this cluster — no duplicate filings. When that Open entry
+      carries a ${WAITING_FOR_FAILURE_PREFIX}…** note and the cluster failed again after the
+      note's date, add the new occurrence under the entry (time, merged commit, failure message)
+      and delete the note line, instead of filing a duplicate.
    5. File it: cite the cluster's normalized key plus the correlated \`merged\` commit in the
-      entry, so the bugfix loop can reproduce it.
+      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",
@@ -355,7 +433,7 @@ Then:
    - Grep for those sinks in this project's own language and pick ONE hit. Trace it back to its
      source: it is real only when you can name the input an attacker controls, the path it
      travels, and the missing check. Read every caller on that path — a guard upstream already
-     closes it — and a sink fed only by constants or the operator's own trusted config is not a
+     closes it — and a sink fed only by constants or the user's own trusted config is not a
      finding.
    - Prove it with a test that feeds the hostile input (a \`../\` path, a shell metacharacter, an
      oversized body, a foreign Origin) and fails before your fix. Then fix it at the boundary —
@@ -389,14 +467,14 @@ concurrent processes or tasks — for these failure modes:
      rejection handler) where the caller needs to know;
    - cleanup skipped on the error path: a leaked lock file, child process, file handle, listener,
      or temp directory;
-   - a retry with no bound or backoff, or a queue, cache, log, or map that only ever grows;
+   - a retry with no bound or sleep, or a queue, cache, log, or map that only ever grows;
    - a read-modify-write that two processes or tasks can interleave, losing one update.
 ${searchGuidance("robustness")}
 Then:
    - Grep for those patterns in this project's own language and pick ONE hit on a path that
      actually runs. Read its callers: it is real only when you can name the concrete fault (the
      process is killed during this write, this file is empty after a crash, this child never
-     exits) and the wrong outcome it causes (lost state, a stuck loop, a crash, a silently wrong
+     exits) and the wrong outcome it causes (lost state, a stuck role, a crash, a silently wrong
      answer).
    - Prove it with a test that injects that fault — a truncated file, a fake that throws or
      hangs, a timer that never fires — and fails before your fix; then make the code handle it
@@ -423,75 +501,32 @@ arguments, config files, environment), and rough edges you meet while running th
     {
         id: "steward",
         tier: "default",
-        title: "project steward",
+        title: "backlog curator",
         find: `Make ONE curation move on this project's records — the most valuable one.
-   1. Re-read the initial prompt, PRINCIPLES.md, PLANS.md, BUGS.md — and QUESTIONS.md if it
+   1. Re-read the brief, PRINCIPLES.md, PLANS.md, BUGS.md — and QUESTIONS.md if it
       exists — and skim the codebase's shape (sizes, module list, test count).
    2. Then make ONE curation move, the most valuable one:
-      - delete or merge stale/duplicative/superseded PLANS.md entries (with a one-line epitaph in
-        the entry's place or in Done);
-      - flag drift between what is being built and the initial prompt as a PLANS.md note;
+      - delete or merge stale/duplicative/superseded PLANS.md entries: move each one under
+        PLANS.md's ## Done with a one-line epitaph as its body (tumwater archives it to
+        PLANS-DONE.md when your change commits), keeping the entry's title, because
+        \`plans-citations.test.ts\` fails when a \`PLANS.md "<title>"\` citation in a \`src/\` or
+        \`test/\` comment matches no heading;
+      - flag drift between what is being built and the brief as a PLANS.md note;
       - tighten or update a principle or complexity budget in PRINCIPLES.md;
       - record a structural risk in BUGS.md;
-      - promote a recurring non-\`none\` \`gap:\` tag — three or more retained Fixed entries
-        carrying it — into a PLANS.md entry for the infrastructure that would retire it, citing
-        those entries. ${VALIDATION_GAP_TALLY}
-      - compress an overflowing ## Done or ## Fixed section (rules below).
+      - 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: you may see PLANS.md and BUGS.md whole, but do it cheaply — they run to
-hundreds of KB. The prompt's <backlog-index> block lists every Planned and Open entry with its
-line range; read those from it, and read Done/Fixed entries by line range only where your move
-needs their bodies. For the compression moves below, an entry's
-heading line plus a \`grep -n\` for its landing citation (the "tick N (\`<sha>\`)" form) supply
-everything the one-line record needs — except a Fixed entry's \`gap:\` suffix, which comes from the
-\`**Validation gap:**\` line in its body: read that one line (\`grep -n 'Validation gap' FILE\`), not
-the whole body.
-
-Compressing PLANS.md ## Done — PLANS.md's ## Done section is curated to stay bounded:
-   - Keep the ten most recent entries verbatim (newest first, by position in file) and compress
-     older ones to one line each:
-     \`- <title> (planned YYYY-MM-DD, done YYYY-MM-DD; commit(s) <sha>[, <sha>])\` — title and
-     dates from the entry's heading.
-   - The hashes are the LANDING commit(s): an explicit landing citation in the entry body (the
-     "tick N (\`<sha>\`)" form naming the commit that landed it), else git log on main, whose
-     self-explaining subjects name the role and describe the change.
-   - Never use a verification or base reference ("Verified … against main \`<sha>\`", "at HEAD
-     \`<sha>\`") as the record's hash — bodies citing several shas need the one cited as having
-     landed the work — and when no landing commit exists (a plan closed without code change says
-     so in its Done note) omit the commit(s) field rather than guess.
-   - The one-line form keeps every existing cross-reference resolvable: references cite titles or
-     commit hashes, both preserved.
-
-Compressing BUGS.md ## Fixed — BUGS.md's ## Fixed section is curated to stay bounded by the same
-policy:
-   - Keep the ten most recent entries verbatim (newest first) and compress older ones to one line
-     each: \`- <symptom headline> (<the heading's own date clause>; commit <sha>; gap: <tag>)\` —
-     carrying the entry's validation-gap tag as a suffix, and omitting the \`gap: <tag>\` suffix
-     entirely when the tag is \`none\` (so the common case costs nothing).
-   - The headline comes from the entry's heading, and the date clause is copied from that heading
-     as-is: BUGS.md headings vary across found/reported/re-recorded × fixed/closed/resolved and
-     may carry extra notes inside their parentheses, so do not normalize or fabricate dates; when
-     a heading carries no dates at all, omit that part of the line.
-   - The commit is the entry's LANDING commit — the one that merged the fix to main: an explicit
-     landing citation in the entry body (the "tick N (\`<sha>\`)" form naming the fix commit
-     itself), else git log on main, whose self-explaining subjects name the role and describe the
-     change; never use a verification reference ("Verified … on main \`<sha>\`", "at HEAD
-     \`<sha>\`") as the record's hash — bodies citing several shas need the one cited as having
-     landed the fix.
-   - When no landing commit exists (an entry closed without code change says so in its
-     **Resolution:** note) omit the \`commit\` field rather than guess, keeping the \`gap: <tag>\`
-     suffix (the no-commit variant reads \`- <symptom headline> (<date clause>; gap: <tag>)\`, and
-     plain \`(<date clause>)\` when the tag is \`none\`).
-${VALIDATION_GAP_GUIDANCE}
+Reading the backlog files: PLANS.md and BUGS.md hold open work, so read them whole when your move
+needs it. Finished entries live in PLANS-DONE.md and BUGS-FIXED.md, newest first, and those files
+only grow: never read them whole. Search them with \`grep -n\`, and read an entry by its line range
+only where your move needs its body. The prompt's <backlog-index> block lists the newest ones.
+Finished history is not curated: nothing reads the archive files whole, so they are never
+compressed or trimmed.
 
-Rules for both compressions:
-   - Never compress an entry carrying a standing **Refused …** note — the objection stands until
-     a human or director edits it, and compression would bury it; such entries stay full (they are
-     rare).
-   - Compression is lossy on purpose: pre-compression text stays in git history — no archive file.
-   - One curation move per tick still holds: one steward tick compresses one section's overflow
-     (or makes any other planned move) — a large backlog takes several ticks to reach the window,
-     each shrinking the file by tens of KB; once at the window it stays bounded.`,
+${VALIDATION_GAP_GUIDANCE}`,
     },
 ];