tumwater 0.4.0 → 0.4.2

package/dist/src/doctor/doctor-backlog-bugs.js

@@ -1,20 +1,18 @@
-import { andMore, readBacklogChecked, FIX_CLAIMS_CHECKED, FIX_CLAIM_HEADING_MAX, REFUSAL_NOTE_MAX, STALE_QUESTION_DAYS, STALE_BUG_DAYS, STALE_WAIT_DAYS } from "./doctor-backlog.js";
+import { andMore, quoteHeading, readBacklogChecked, FIX_CLAIMS_CHECKED, REFUSAL_NOTE_MAX, STALE_QUESTION_DAYS, STALE_BUG_DAYS } from "./doctor-backlog.js";
 import { truncate } from "../text/text.js";
+import { plural, agree } from "../text/phrases.js";
 import { ageInDays, filingDate, fixedBugEntries, openBugEntries, openQuestionEntries, plannedPlanEntries } from "../backlog/backlog.js";
-import { stripEntryStamp } from "../backlog/backlog-structure.js";
 import { questionFilingDate } from "../backlog/question-answer.js";
-import { refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
+import { needsReviewNote, refusalNote } from "../backlog/backlog-eligibility.js";
 import { plannedPartKeys, plansWaitingOn, prerequisitesMerged } from "../backlog/backlog-parts.js";
 import { lastDate } from "../backlog/backlog-md.js";
 import { formatTimestamp } from "../text/datetime.js";
 import { stringList } from "../files/json-object.js";
-import { byDaysThenIndex } from "../collections.js";
 import { readEventsSince } from "../events/event-window.js";
 import { okOutcome, warnOutcome } from "./outcome.js";
 /** The doctor's open-bug and question checks, split out of doctor-backlog.ts: questions that
  * have waited too long for an answer (checkStaleQuestions), bugs left unfixed (checkStaleBugs),
- * bugs held for their next failure (checkWaitingBugs, with its quotedTestName / waitingNoteDate /
- * failureMentions helpers), fixed records whose quoted test regressed (checkRegressedFixes), and
+ * fixed records whose quoted test regressed (checkRegressedFixes), and
  * entries parked by a Refused note (checkRefusedEntries). They import the shared helpers
  * (readBacklogChecked, andMore) from doctor-backlog.ts, plus the age/trim bounds, and
  * all warn instead of failing: a stale or
@@ -44,21 +42,22 @@ export function checkStaleQuestions(root) {
     const [first, ...rest] = stale;
     if (!first)
         return okOutcome("no open question has waited more than 7 days for an answer");
-    const more = andMore(rest, (q) => `"${truncate(q.title, FIX_CLAIM_HEADING_MAX)}"`);
-    return warnOutcome(`QUESTIONS.md question "${truncate(first.title, FIX_CLAIM_HEADING_MAX)}" has waited ${first.days} d for an answer${more} — ` +
+    const more = andMore(rest, (q) => quoteHeading(q.title));
+    return warnOutcome(`QUESTIONS.md question ${quoteHeading(first.title)} has waited ${first.days} d for an answer${more} — ` +
         `a question that waits too long for a human answer is worth your attention`);
 }
-/** Stale bugs — unrefused open BUGS.md bugs whose `(found by … YYYY-MM-DD)` or `(reported …)`
- * stamp is at least 3 days old. The bugfix role fixes a bug within hours, so one that sits means
- * no role is fixing it. Positions are the 1-based `bug --list` numbers; a refused bug is skipped
- * (checkRefusedEntries names it), a waiting bug is skipped (checkWaitingBugs names it) and so is
- * an undated heading. A warn, never a fail. */
+/** Stale bugs — unrefused, unheld open BUGS.md bugs whose `(found by … YYYY-MM-DD)` or
+ * `(reported …)` stamp is at least 3 days old. The bugfix role fixes a bug within hours, so one
+ * that sits means no role is fixing it. Positions are the 1-based `bug --list` numbers; a refused
+ * bug is skipped (checkRefusedEntries names it), a bug parked by a Needs-review note is skipped
+ * (the note names what would make it fail, so it is not unfixed), and so is an undated heading.
+ * A warn, never a fail. */
 export function checkStaleBugs(root) {
     const doc = readBacklogChecked(root, "BUGS.md");
     if (typeof doc !== "string")
         return doc;
     const stale = openBugEntries(root).flatMap((entry, index) => {
-        if (refusalNote(entry.body) !== null || waitingNote(entry.body) !== null)
+        if (refusalNote(entry.body) !== null || needsReviewNote(entry.body) !== null)
             return [];
         const stamp = filingDate(entry.title);
         if (stamp === null)
@@ -69,8 +68,8 @@ export function checkStaleBugs(root) {
     const [first, ...rest] = stale;
     if (!first)
         return okOutcome("no open bug has waited more than 3 days for a fix");
-    const more = andMore(rest, (b) => `#${b.position} "${truncate(b.title, FIX_CLAIM_HEADING_MAX)}"`);
-    return warnOutcome(`BUGS.md bug #${first.position} "${truncate(first.title, FIX_CLAIM_HEADING_MAX)}" has waited ${first.days} d for a fix${more} — ` +
+    const more = andMore(rest, (b) => `#${b.position} ${quoteHeading(b.title)}`);
+    return warnOutcome(`BUGS.md bug #${first.position} ${quoteHeading(first.title)} has waited ${first.days} d for a fix${more} — ` +
         `no role is fixing it: check that the bugfix role is enabled and not failing, or retract it with \`tumwater bug --cancel ${first.position}\``);
 }
 /** The first span between straight double quotes in a bug heading that is at least 12
@@ -85,10 +84,6 @@ export function quotedTestName(title) {
 function dayAfterMs(date) {
     return new Date(Number(date.slice(0, 4)), Number(date.slice(5, 7)) - 1, Number(date.slice(8, 10)) + 1).getTime();
 }
-/** The first `YYYY-MM-DD` in a Waiting for the next failure note's text, or null. */
-export function waitingNoteDate(note) {
-    return /\d{4}-\d{2}-\d{2}/.exec(note)?.[0] ?? null;
-}
 /** True when `text` is a check-failure report that names `name` as a test that failed — the
  * doctors' recurrence/regression evidence. The recurrence scans must not count any line that
  * merely *contains* the quoted test name as the flake's return, or a warning that only quotes
@@ -127,8 +122,8 @@ export function failureMentions(events, name, sinceMs) {
 }
 /** The newest failure report at or after `since` naming `name` — `failureMentions`'s last
  * mention — or undefined when none. The single home of the "did this flake come back after
- * its boundary?" step, shared by the waiting-bug recurrence scan (checkWaitingBugs) and the
- * regressed-fix match (matchedRegressedFixes), so both keep the same last-mention rule. */
+ * its boundary?" step, shared by the regressed-fix match (matchedRegressedFixes), so both
+ * keep the same last-mention rule. */
 function lastFailureMention(events, name, sinceMs) {
     const mentions = failureMentions(events, name, sinceMs);
     return mentions[mentions.length - 1];
@@ -136,104 +131,11 @@ function lastFailureMention(events, name, sinceMs) {
 /** The read-events window (ms) that reaches the oldest of `sinces` — `Date.now()` minus the
  * oldest timestamp, floored at 0 — so a recurrence check reads events past every candidate's
  * `since`. The single home of the "oldest of a set of since-times" step, shared by
- * checkWaitingBugs and checkRegressedFixes, so those sites cannot drift on the clamp or the
+ * checkRegressedFixes, so those sites cannot drift on the clamp or the
  * time base. */
 function sinceWindowMs(sinces) {
     return Math.max(0, Date.now() - Math.min(...sinces));
 }
-/** Open BUGS.md bugs held by a **Waiting for the next failure …** note, in file order: the
- * doctor's `checkWaitingBugs` selection and anchor, factored out so the always-on stale-wait
- * feed (staleWaitingBugRows) reads the same held set and cannot drift from the doctor's rule.
- * A bug that is also Refused is left to checkRefusedEntries. `since` is the day-after the
- * note's date — the recurrence scan's boundary; `date` the note's own `YYYY-MM-DD` or null. */
-function heldWaitingBugs(root) {
-    return openBugEntries(root).flatMap((entry, index) => {
-        const note = waitingNote(entry.body);
-        if (note === null || refusalNote(entry.body) !== null)
-            return [];
-        const name = quotedTestName(entry.title);
-        const date = waitingNoteDate(note);
-        const since = name !== null && date !== null ? dayAfterMs(date) : null;
-        return [{ index, position: index + 1, title: entry.title, note, name, since, date }];
-    });
-}
-/** Waiting bugs — open BUGS.md bugs held by a **Waiting for the next failure …** note, which
- * parks a bug until it fails again. Positions are the 1-based `bug --list` numbers; a bug that
- * is also Refused is left to checkRefusedEntries. Ok when the hold is undisturbed — doctor
- * then only names the bugs and how to release one — and a warn when a held bug's quoted test
- * has failed in a gate or merge check since the day after its note (the note carries only a
- * date, so a same-day failure cannot be told from the one it was written about). A warn is
- * never a fail, and doctor writes nothing to BUGS.md. */
-export function checkWaitingBugs(root) {
-    const doc = readBacklogChecked(root, "BUGS.md");
-    if (typeof doc !== "string")
-        return doc;
-    const held = heldWaitingBugs(root);
-    const [first, ...rest] = held;
-    if (!first)
-        return okOutcome("no open bug is waiting for its next failure");
-    const sinces = held.flatMap((b) => (b.since !== null && !Number.isNaN(b.since) ? [b.since] : []));
-    if (sinces.length > 0) {
-        const { events } = readEventsSince(root, sinceWindowMs(sinces));
-        const recurred = held.flatMap((b) => {
-            if (b.name === null || b.since === null)
-                return [];
-            const newest = lastFailureMention(events, b.name, b.since);
-            return newest ? [{ ...b, newest }] : [];
-        });
-        const [again, ...others] = recurred;
-        if (again) {
-            const more = andMore(others, (b) => `#${b.position} "${truncate(b.title, FIX_CLAIM_HEADING_MAX)}"`);
-            return warnOutcome(`BUGS.md bug #${again.position} "${truncate(again.title, FIX_CLAIM_HEADING_MAX)}" failed again since its Waiting for the next failure note ` +
-                `(${formatTimestamp(again.newest.ts)}: ${truncate(again.newest.text, REFUSAL_NOTE_MAX)})${more} — ` +
-                `record the occurrence under the entry and release it with \`tumwater bug --release ${again.position}\``);
-        }
-    }
-    /* A Waiting hold has no expiry of its own, so a bug whose flake never comes back parks
-     * indefinitely; a hold that has outlived STALE_WAIT_DAYS without a recurrence is escalated
-     * from the ok below to a warn so the operator is nudged to release or re-hold it. */
-    const lapsed = held.flatMap((b) => {
-        /* An undated note (no YYYY-MM-DD in its text) has no hold-start marker, and checkStaleBugs
-         * skips any bug carrying a waiting note, so without a fallback it would park indefinitely
-         * too; the filing stamp anchors it — the hold cannot be younger than the bug it dates from. */
-        const anchor = b.date ?? filingDate(b.title);
-        if (anchor === null)
-            return [];
-        const days = ageInDays(anchor);
-        return days >= STALE_WAIT_DAYS ? [{ ...b, days }] : [];
-    });
-    const [firstLapsed, ...restLapsed] = lapsed;
-    if (firstLapsed) {
-        const more = andMore(restLapsed, (b) => `#${b.position} "${truncate(b.title, FIX_CLAIM_HEADING_MAX)}"`);
-        return warnOutcome(`BUGS.md bug #${firstLapsed.position} "${truncate(firstLapsed.title, FIX_CLAIM_HEADING_MAX)}" has waited ${firstLapsed.days} d for its next failure without one ` +
-            `— its flake likely never comes back, so it parks indefinitely; release it with \`tumwater bug --release ${firstLapsed.position}\`${more}`);
-    }
-    const more = andMore(rest, (b) => `#${b.position} "${truncate(b.title, FIX_CLAIM_HEADING_MAX)}"`);
-    return okOutcome(`BUGS.md bug #${first.position} "${truncate(first.title, FIX_CLAIM_HEADING_MAX)}" is held until it fails again ` +
-        `(${truncate(first.note, REFUSAL_NOTE_MAX)})${more} — selfcheck lifts the note when it records a new occurrence; ` +
-        `release it now with \`tumwater bug --release ${first.position}\``);
-}
-/** The always-on rows behind the dashboard/TUI/`tumwater status` waiting-bug alert: open BUGS.md
- * bugs held by a **Waiting for the next failure …** note whose anchor (the note's `YYYY-MM-DD`,
- * else the heading's filing stamp) is at least STALE_WAIT_DAYS old. Shares the doctor's
- * STALE_WAIT_DAYS threshold and the heldWaitingBugs selection/anchor, so the alert and the
- * doctor's `waiting bugs` row cannot drift on the rule; an undated note-and-heading is skipped.
- * The returned objects carry the 0-based index (drawer address `bugs:<index>`), the 1-based
- * position (`bug --release <position>`), the stamp-stripped title, and the whole-day age.
- * Returned most-days-waited-first, ties in file order, like staleOpenBugs. This deliberately
- * omits `checkWaitingBugs`'s recurrence scan, because that scan reads events back to the oldest
- * hold and is too costly on the status poll path; the doctor still reports a recurrence first. */
-export function staleWaitingBugRows(root, now = Date.now()) {
-    return heldWaitingBugs(root)
-        .flatMap((b) => {
-        const anchor = b.date ?? filingDate(b.title);
-        if (anchor === null)
-            return [];
-        const days = ageInDays(anchor, now);
-        return days >= STALE_WAIT_DAYS ? [{ index: b.index, position: b.position, title: stripEntryStamp(b.title), days }] : [];
-    })
-        .sort(byDaysThenIndex);
-}
 /** The regression candidates for the `regressed fixes` feed: a newest-FIX_CLAIMS_CHECKED BUGS.md
  * Fixed record whose heading quotes a test name and carries a `YYYY-MM-DD` date, unless an Open
  * bug already quotes the same test (which means the regression is filed). Shared by the doctor's
@@ -268,8 +170,8 @@ export function regressedFixesPhrase(regressed) {
     const [first, ...rest] = regressed;
     if (!first)
         return null;
-    const more = andMore(rest, (c) => `"${truncate(c.title, FIX_CLAIM_HEADING_MAX)}"`);
-    return `BUGS.md Fixed record "${truncate(first.title, FIX_CLAIM_HEADING_MAX)}" quotes a test that failed again after its ${first.date} fix ` +
+    const more = andMore(rest, (c) => quoteHeading(c.title));
+    return `BUGS.md Fixed record ${quoteHeading(first.title)} quotes a test that failed again after its ${first.date} fix ` +
         `(${formatTimestamp(first.newest.ts)}: ${truncate(first.newest.text, REFUSAL_NOTE_MAX)})${more} — ` +
         "file it as a new bug with `tumwater bug`, quoting the test name and citing the Fixed record";
 }
@@ -314,14 +216,14 @@ export function checkRefusedEntries(root) {
     const [first, ...rest] = held;
     if (!first)
         return okOutcome("no planned plan or open bug is held by a Refused note");
-    const more = andMore(rest, (e) => `${e.file} ${e.command} #${e.position} "${truncate(e.title, FIX_CLAIM_HEADING_MAX)}"` +
+    const more = andMore(rest, (e) => `${e.file} ${e.command} #${e.position} ${quoteHeading(e.title)}` +
         (e.mergeDone.length > 0 ? " [prerequisites no longer planned]" : "") +
-        (e.waiting > 0 ? ` [${e.waiting} part(s) wait on it]` : ""));
+        (e.waiting > 0 ? ` [${plural(e.waiting, "part waits on it", "parts wait on it")}]` : ""));
     const stale = first.mergeDone.length > 0
-        ? `; its prerequisite(s) ${first.mergeDone.map((r) => `${r.series} ${r.part}/${r.of}`).join(", ")} are no longer planned, so the refusal may be stale`
+        ? `; its ${agree(first.mergeDone.length, "prerequisite", "prerequisites")} ${first.mergeDone.map((r) => `${r.series} ${r.part}/${r.of}`).join(", ")} ${agree(first.mergeDone.length, "is", "are")} no longer planned, so the refusal may be stale`
         : "";
     const waiting = first.waiting > 0
-        ? `; ${first.waiting} planned part(s) wait on it, directly or through an earlier part`
+        ? `; ${plural(first.waiting, "planned part waits on it", "planned parts wait on it")}, directly or through an earlier part`
         : "";
     return warnOutcome(`${first.file} ${first.command} #${first.position} "${first.title}" is held by a Refused note ` +
         `(${truncate(first.note, REFUSAL_NOTE_MAX)})${stale}${waiting}${more} — no role takes a refused entry until it is edited: ` +

package/dist/src/doctor/doctor-backlog-plans.js

@@ -1,4 +1,4 @@
-import { andMore, readDoc, readBacklogChecked, FIX_CLAIMS_CHECKED, FIX_CLAIM_HEADING_MAX, REFUSAL_NOTE_MAX } from "./doctor-backlog.js";
+import { andMore, quoteHeading, readDoc, readBacklogChecked, FIX_CLAIMS_CHECKED, REFUSAL_NOTE_MAX } from "./doctor-backlog.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { VALIDATION_GAP_TAGS } from "../roles/role-guidance.js";
 import path from "node:path";
@@ -9,9 +9,8 @@ import { planDependencyProblems } from "../backlog/backlog-parts.js";
 import { BACKLOG_FILES, FINISHED_ARCHIVES, validationGapTag } from "../backlog/backlog-md.js";
 import { statOrNull } from "../files/files.js";
 import { duplicateHeadings, strandedPlanEntriesFor } from "../backlog/backlog-structure.js";
-import { liveFinishedHistory } from "../backlog/backlog-archive.js";
+import { liveFinishedHistory, liveFinishedRowList } from "../backlog/backlog-archive.js";
 import { fixSymbols, missingSymbolNames, cachedSourceHaystack, unbackedSymbols } from "../verdict/fix-claim.js";
-import { plural } from "../text/phrases.js";
 import { okOutcome, warnOutcome } from "./outcome.js";
 /** The doctor's PLANS.md-structure and fix-claim checks, split out of doctor-backlog.ts: the
  * checks that re-verify BUGS.md's newest Fixed records against the tree (checkFixClaims,
@@ -45,7 +44,7 @@ export function checkFixClaims(root) {
     const { heading, missing } = first;
     const names = missingSymbolNames(missing);
     // Every other suspect is still named, shortened: a doctor check is one line.
-    const more = andMore(rest, (p) => `"${truncate(p.heading, FIX_CLAIM_HEADING_MAX)}"`, "record(s)");
+    const more = andMore(rest, (p) => quoteHeading(p.heading), "record(s)");
     return warnOutcome(`BUGS.md records "${heading}" as Fixed, but none of the symbols its Fix paragraph names ` +
         `exist on this tree: ${names}${more} — land the fix or keep the bug Open / refresh a stale record`);
 }
@@ -148,14 +147,14 @@ export function checkValidationGaps(root) {
     if (!first) {
         if (unpinned.length > 0) {
             const up = unpinned[0];
-            const more = andMore(unpinned.slice(1), (s) => `"${truncate(s.title, FIX_CLAIM_HEADING_MAX)}"`, "record(s)");
+            const more = andMore(unpinned.slice(1), (s) => quoteHeading(s.title), "record(s)");
             return warnOutcome(`BUGS.md record "${up.title}" is an \`unclear-invariant\` fix but names no ` +
                 `docs/invariants.md section — record the reconstructed guarantee there (a "Pinned by" line) in the ` +
                 `same commit so the next bug in that area does not reconstruct it again${more}`);
         }
         return okOutcome(`newest ${validationGapRecords(root).length} Fixed record(s) carry a known Validation gap tag`);
     }
-    const more = andMore(rest, (s) => `"${truncate(s.title, FIX_CLAIM_HEADING_MAX)}"`, "record(s)");
+    const more = andMore(rest, (s) => quoteHeading(s.title), "record(s)");
     const what = first.kind === "missing"
         ? `BUGS.md record "${first.title}" has no **Validation gap:** line`
         : `BUGS.md record "${first.title}" names unrecognized Validation gap tag "${first.tag}"`;
@@ -183,7 +182,7 @@ export function checkStrandedPlans(root) {
     const [first, ...rest] = stranded;
     if (!first)
         return okOutcome(clean);
-    const more = andMore(rest, (e) => `"${truncate(e.title, FIX_CLAIM_HEADING_MAX)}"`);
+    const more = andMore(rest, (e) => quoteHeading(e.title));
     const file = first.file ?? "PLANS.md";
     return warnOutcome(`${file} has a plan stranded under ## ${first.section}: "${first.title}"${more} — ` +
         `move it under ## ${first.section === "Done" ? "Planned" : "Done"}${file === "PLANS.md" ? "" : " in PLANS.md"} ` +
@@ -199,8 +198,7 @@ export function checkLiveFinished(root) {
     const live = liveFinishedHistory(root);
     if (live.length === 0)
         return okOutcome("PLANS.md and BUGS.md hold no finished entries — they are archived");
-    const parts = live.map((l) => `${l.file} ## ${l.section} holds ${plural(l.entries, "finished entry", "finished entries")} (${Math.round(l.bytes / 1024)} KB)`);
-    return warnOutcome(`${parts.join("; ")} — every run that reads the file pays for them; ` +
+    return warnOutcome(`${liveFinishedRowList(live)} — every run that reads the file pays for them; ` +
         "`tumwater archive` moves them to the archive files and commits them (a starting team does too)");
 }
 /** The always-on `backlog-headings` alert polls this on every observer surface and every
@@ -245,8 +243,8 @@ function scanBacklogHeadings(root) {
  * always-on alert so the poll path never re-reads an unchanged backlog or archive file. */
 const backlogHeadingFileCache = new Map();
 /** The duplicated `## ` headings already on main, exported so the always-on `backlog-headings`
- * team alert (src/ui/team-alerts.ts) renders the same set the doctor's `backlog headings` row
- * warns about. */
+ * team alert (src/ui/team-alert-backlog.ts) renders the same set the doctor's `backlog
+ * headings` row warns about. */
 export function duplicatedBacklogHeadings(root) {
     return scanBacklogHeadings(root).duplicates;
 }
@@ -258,9 +256,10 @@ export function duplicatedBacklogHeadings(root) {
  * stat-keyed cache entry can serve it. */
 const liveFinishedCache = new Map();
 /** The finished-history rows already on main, exported so the always-on `backlog-archive` team
- * alert (src/ui/team-alerts.ts) renders the same set the doctor's `backlog archive` row warns
- * about — stat-gated so a steady-state poll pays four stats, not a full re-parse. The cache key
- * is the stat identity (`dev:ino:mtimeMs:size`, `absent` when the stat is null) of every
+ * alert (src/ui/team-alert-backlog.ts) renders the same set the doctor's `backlog archive`
+ * row warns about — stat-gated so a steady-state poll pays four stats, not a full re-parse.
+ * The cache key is the stat identity (`dev:ino:mtimeMs:size`, `absent` when the stat is
+ * null) of every
  * FINISHED_ARCHIVES live file and archive under `root`, so any write that changes finished
  * history or the archive refreshes the rows on the next call without a process restart. Returns
  * a copy on a hit; on a miss it recomputes via liveFinishedHistory, and returns `[]` (uncached)
@@ -310,24 +309,24 @@ export function checkBacklogHeadings(root) {
         `later entries are invisible; keep one heading per name (the gate blocks only a merge ` +
         `that adds another copy — remove the duplicate in a deliberate edit)`);
 }
-/** Stalled entries — plans or bugs held by a **Needs review …** or **Needs replan …** note,
+/** Stalled entries — plans or bugs held by a **Needs review …** note,
  * parked until the plan role splits or replans them, plus the held-for-operator entries
  * parked until the operator releases them. No role takes a held entry (the claim gate refuses
  * one) and nothing clears the note on its own, so the state is visible only as the
- * `[needs review]`/`[needs replan]` marks in the backlog listings; this names them so an
+ * `[needs review]` marks in the backlog listings; this names them so an
  * operator gets a single-line health signal from `tumwater doctor`. Reads the tree at `root`
  * — the primary checkout IS main's tree — like checkRefusedEntries, which is also where
  * refusal notes (a different hold) are surfaced. entryHold (src/backlog/backlog-eligibility.ts)
  * already classifies the notes, so this check adds no parsing: only the entries whose hold is
- * exactly needs-review, needs-replan, or held-for-operator are collected, from both PLANS.md
+ * exactly needs-review or held-for-operator are collected, from both PLANS.md
  * and BUGS.md. A warn, never a fail — the checkRefusedEntries precedent: a parked entry is
- * operator signal, not a broken environment; the plan role resolves the first two itself, and
+ * operator signal, not a broken environment; the plan role resolves the first itself, and
  * a held-for-operator entry is the operator's to release (`tumwater plan|bug --release`). */
 export function checkStalledEntries(root) {
     const planned = plannedPlanEntries(root);
     const collect = (entry, file) => {
         const hold = entryHold(entry, planned);
-        return hold === "needs-review" || hold === "needs-replan" || hold === "held-for-operator" // vocabulary-ok: the held-for-operator hold's key
+        return hold === "needs-review" || hold === "held-for-operator" // vocabulary-ok: the held-for-operator hold's key
             ? { file, entry }
             : null;
     };
@@ -337,16 +336,16 @@ export function checkStalledEntries(root) {
     ].filter((x) => x !== null);
     const [first, ...rest] = stalled;
     if (!first)
-        return okOutcome("no planned plan or open bug is held by a Needs-review, Needs-replan, or held-for-operator note"); // vocabulary-ok: names the held-for-operator hold
-    const more = andMore(rest, (s) => `"${truncate(s.entry.title, FIX_CLAIM_HEADING_MAX)}"`);
+        return okOutcome("no planned plan or open bug is held by a Needs-review or held-for-operator note"); // vocabulary-ok: names the held-for-operator hold
+    const more = andMore(rest, (s) => quoteHeading(s.entry.title));
     const kind = entryKindLabel(first.file); // "Bug" | "Plan"
     const head = `${first.file === "bugs" ? "BUGS.md" : "PLANS.md"} ${kind.toLowerCase()}`;
     const hold = entryHold(first.entry, planned);
-    const note = (first.entry.body.split(/\n/).find((line) => line.trimStart().startsWith("**Needs review ") || line.trimStart().startsWith("**Needs replan ")) ?? "").replace(/^\s*\*\*/, "").replace("**", "");
+    const note = (first.entry.body.split(/\n/).find((line) => line.trimStart().startsWith("**Needs review ")) ?? "").replace(/^\s*\*\*/, "").replace("**", "");
     if (hold === "held-for-operator") { // vocabulary-ok: the held-for-operator hold's key
-        return warnOutcome(`${head} "${truncate(first.entry.title, FIX_CLAIM_HEADING_MAX)}" is held for the operator ${heldCount(first.entry.body)} times${more} — release it with tumwater ${kind.toLowerCase()} --release`); // vocabulary-ok: a held-for-operator entry is the operator's to release
+        return warnOutcome(`${head} ${quoteHeading(first.entry.title)} is held for the operator ${heldCount(first.entry.body)} times${more} — release it with tumwater ${kind.toLowerCase()} --release`); // vocabulary-ok: a held-for-operator entry is the operator's to release
     }
-    return warnOutcome(`${head} "${truncate(first.entry.title, FIX_CLAIM_HEADING_MAX)}" is held by a ${hold === "needs-review" ? "Needs review" : "Needs replan"} note ` +
+    return warnOutcome(`${head} ${quoteHeading(first.entry.title)} is held by a Needs review note ` +
         `(${truncate(note, REFUSAL_NOTE_MAX)})${more} — the plan role resolves it by splitting or replanning`);
 }
 /** Plan dependencies — mistakes in the planned plans' `requires … landed` clauses that the claim
@@ -361,7 +360,7 @@ export function planDependencyProblem(root) {
     const [firstDangling, ...restDangling] = dangling;
     const [firstUnparsed, ...restUnparsed] = unparsed;
     const [firstMisworded, ...restMisworded] = misworded;
-    const quote = (t) => `"${truncate(t, FIX_CLAIM_HEADING_MAX)}"`;
+    const quote = quoteHeading;
     const others = (parts) => parts.some(([n]) => n > 0) ? ` (also ${parts.map(([n, noun]) => `${n} ${noun}`).join(", ")})` : "";
     const danglingMsg = (d) => `PLANS.md plan ${quote(d.title)} requires ${d.ref}, which no PLANS.md heading carries — the hold is void, ` +
         "so the plan is claimable now; fix the series name or part number";

package/dist/src/doctor/doctor-backlog.js

@@ -37,9 +37,9 @@ import { okOutcome, warnOutcome } from "./outcome.js";
  * and pre-convention Fixed entries predate the validation-gap line — so a whole-section scan
  * would warn forever on records nobody should rewrite. */
 export const FIX_CLAIMS_CHECKED = 10;
-/** A second or later suspect record's heading is trimmed to this many characters in the warn —
- * the first is named in full, the rest only enough to find them in BUGS.md. */
-export const FIX_CLAIM_HEADING_MAX = 60;
+/** A cited record's heading is trimmed to this many characters in a doctor warn — enough to
+ * find it back in its file; quoteHeading applies it to every citation. */
+const FIX_CLAIM_HEADING_MAX = 60;
 /** A refused entry's note is trimmed to this many characters in the refusals warn. */
 export const REFUSAL_NOTE_MAX = 120;
 /** The whole days an open question may wait before the stale-questions check warns about it:
@@ -50,13 +50,6 @@ export const STALE_QUESTION_DAYS = 7;
  * opinionated default with no knob, like STALE_QUESTION_DAYS. Three days is long enough that a
  * bug filed late one evening and fixed the next day never warns. */
 export const STALE_BUG_DAYS = 3;
-/** The whole days a bug may stay held by a Waiting for the next failure note before the
- * waiting-bugs check warns that its flake has not come back. A note parks a bug until it fails
- * again, but the failure may never come, so a hold has to lapse or the entry parks indefinitely;
- * one week without a recurrence is long enough that a recurring flake would almost surely have
- * shown up, and short enough that a bug which never returns stops squatting in the backlog as
- * an ok. An opinionated default with no knob, like STALE_BUG_DAYS. */
-export const STALE_WAIT_DAYS = 7;
 /** The `(and N more …)` suffix three one-line doctor details append after naming their first
  * suspect (fix claims, stranded plans, duplicated headings): the rest stay visible but
  * shortened, since a doctor check renders one line. `render` makes each extra item's short
@@ -69,6 +62,12 @@ export function andMore(rest, render, noun = "") {
         ? ` (and ${rest.length} more${noun ? ` ${noun}` : ""}: ${rest.map(render).join(", ")})`
         : "";
 }
+/** Quote a heading/summary in a doctor sentence, truncated to FIX_CLAIM_HEADING_MAX so a check
+ * stays one line: `"…"`. The doctor's citations all quote-then-truncate the same way; this is
+ * the one home for that shape. */
+export function quoteHeading(title) {
+    return `"${truncate(title, FIX_CLAIM_HEADING_MAX)}"`;
+}
 /** Read one backlog file for a check, or the failure message explaining why it could not be
  * read (text.ts's errorMessage). Callers shape the failure themselves — a returned warn for a
  * single-file check, an "(unreadable)" list entry for the multi-file heading sweep. */
@@ -94,7 +93,7 @@ export function readDocChecked(p, file, missingDetail) {
 }
 /** The standard single-file check's read prologue for a backlog document at `root`: the
  * readDocChecked call every per-file doctor check (checkFixClaims, checkValidationGaps,
- * checkStrandedPlans, checkStaleQuestions, and the stale/waiting bug checks) repeats, with the
+ * checkStrandedPlans, checkStaleQuestions, and the stale bug checks) repeats, with the
  * `no <file> — nothing to verify` missing-detail derived from the file name so the file triple
  * (path, display name, message) and the message template cannot drift across the seven call
  * sites. Returns the document, or the outcome the caller should return as-is. */
@@ -105,11 +104,9 @@ export function readBacklogChecked(root, file) {
  * warns: 6 hours, fixed. A verify plus a merge completes in minutes (plans/merge-queue.md), so a
  * full six-hour silence while the team is healthy — not on a hold, which doctor already reports
  * separately — is never a merely busy pipeline: it reads as a drain that has stalled. The one
- * opinionated default, like STALE_QUESTION_DAYS, so no knob. The always-on `stale-merges` team
- * alert (src/ui/status-payload.ts staleMerges) reuses this same window through
- * staleQueuedMergeRows, so the doctor's row and the alert cannot drift on the threshold (the
+ * opinionated default, like STALE_QUESTION_DAYS, so no knob (the dead-alert feed is gone; the
  * STALE_PROMPT_MS/STALE_BUG_DAYS precedent). */
-export const MERGE_QUEUE_STALE_MS = 6 * HOUR_MS;
+const MERGE_QUEUE_STALE_MS = 6 * HOUR_MS;
 /** The window of the merge-wait phrase on the stale merge-queue row. */
 const MERGE_WAIT_WINDOW_MS = DAY_MS;
 /** Stale queued merges — a change that has sat in the durable merge queue too long without starting
@@ -141,19 +138,18 @@ export function checkStaleQueuedMerges(root, now) {
     const [first, ...rest] = stale;
     if (!first)
         return withWait(okOutcome(`no merge-queue entry has waited more than ${humanSeconds(MERGE_QUEUE_STALE_MS / 1000)} to start`));
-    const more = andMore(rest, (e) => `${e.role} — "${truncate(e.summary, FIX_CLAIM_HEADING_MAX)}"`);
-    return withWait(warnOutcome(`merge-queue entry of ${roleLabel(first.role)} — "${truncate(first.summary, FIX_CLAIM_HEADING_MAX)}" — has waited ` +
+    const more = andMore(rest, (e) => `${e.role} — ${quoteHeading(e.summary)}`);
+    return withWait(warnOutcome(`merge-queue entry of ${roleLabel(first.role)} — ${quoteHeading(first.summary)} — has waited ` +
         `${first.age} to start${more}; a queued change the pipeline neither approves nor flags reads as healthy, so the merge queue has stopped moving`));
 }
-/** The one traversal shared by the doctor's `stale merge-queue entries` row
- * (checkStaleQueuedMerges) and the always-on `stale-merges` team alert
- * (src/ui/status-payload.ts staleMerges): every queued merge whose role is not in the in-flight
+/** The one traversal for the doctor's `stale merge-queue entries` row
+ * (checkStaleQueuedMerges): every queued merge whose role is not in the in-flight
  * marker and whose wait strictly exceeds MERGE_QUEUE_STALE_MS (6 h), in queue-file order (oldest
  * first). The in-flight set comes from readMergeMarker via mergeChanges (an absent or
  * never-throwing unreadable marker contributes the empty set) — a slow review is not a stalled
- * drain. Each row carries { role, summary, waitedMs }; the doctor's row adds its age phrase and
- * the alert names the wait, so the rule and its threshold live in one place and cannot drift. */
-export function staleQueuedMergeRows(root, now) {
+ * drain. Each row carries { role, summary, waitedMs }, which the row renders with its age
+ * phrase, so the rule and its threshold live in one place and cannot drift. */
+function staleQueuedMergeRows(root, now) {
     const marker = readMergeMarker(root);
     const inFlight = new Set(marker ? mergeChanges(marker).map((c) => c.role) : []);
     return queuedMerges(root)
@@ -161,9 +157,8 @@ export function staleQueuedMergeRows(root, now) {
         .map((e) => ({ role: e.role, summary: e.summary, waitedMs: now - e.enqueuedAt }));
 }
 /** The merge-queue files `readMergeQueue` skips — torn, foreign, or vanished mid-listing — as
- * checkout-relative paths. One traversal shared by the doctor's `checkMergeQueueFiles` row and
- * the always-on `skipped-merges` team alert (src/ui/status-payload.ts skippedMergeFiles), so
- * the two surfaces select the same files and name the same paths and cannot drift. */
+ * checkout-relative paths. The one traversal behind the doctor's `checkMergeQueueFiles` row, so
+ * the row names the same paths the reader actually skips and cannot drift. */
 export function skippedMergeQueueFiles(root) {
     return unreadableMergeQueueFiles(root).map((f) => path.relative(root, f));
 }
@@ -197,9 +192,8 @@ export const POST_REVIEW_AT_RISK_FAILURES = POST_REVIEW_FAILURE_LIMIT - 1;
  * is not waiting on a verdict and must not read as one failed run from being dropped.
  * A review that has already landed its fix (`fixed` set) is left out too — it is a settled
  * record naming both shas, not a verdict-less entry the next run could drop.
- * One traversal shared by the doctor's `post-merge reviews` row (checkPostReviews) and the
- * always-on `post-merge-risk` team alert (src/ui/status-payload.ts postReviewRiskAlert), so the
- * two surfaces select the same entries and cannot drift. Reads .tumwater/state/post-review.json
+ * One traversal used by the doctor's `post-merge reviews` row (checkPostReviews), so the row's
+ * selection lives in one place. Reads .tumwater/state/post-review.json
  * through readPostReviews, which degrades a missing or torn file to the well-formed subset or
  * `[]` and never throws. */
 export function atRiskPostReviews(root) {
@@ -209,22 +203,22 @@ export function atRiskPostReviews(root) {
 }
 /** The doctor's one sentence naming the post-merge reviews one failed run from being dropped
  * (the checkStaleQueuedMerges phrase precedent): the first in full — role, short commit, summary
- * and the failures count — the rest folded through andMore, and the one sentence every surface
- * shows, so the doctor row and the alert cannot drift on the wording. null for an empty list. */
+ * and the failures count — the rest folded through andMore, the one sentence the row shows, so
+ * the wording lives in one place. null for an empty list. */
 export function atRiskPostReviewsPhrase(rows) {
     const [first, ...rest] = rows;
     if (!first)
         return null;
     const more = andMore(rest, (r) => `${roleLabel(r.role)} ${shortSha(r.commit)}`);
-    return `the post-merge review of ${roleLabel(first.role)} ${shortSha(first.commit)} — "${truncate(first.summary, FIX_CLAIM_HEADING_MAX)}" — has ended without a verdict ${first.failures} times${more}; ` +
+    return `the post-merge review of ${roleLabel(first.role)} ${shortSha(first.commit)} — ${quoteHeading(first.summary)} — has ended without a verdict ${first.failures} times${more}; ` +
         `one more failed run drops it and the commit stays on main unreviewed — fix the reviewer backend or accept the commit unreviewed deliberately`;
 }
 /** A post-merge review one failed run from being dropped (src/review/post-merge-review.ts, the
  * drain drops an entry at POST_REVIEW_FAILURE_LIMIT failed runs) — the last moment an operator
  * can fix the reviewer backend or deliberately accept the commit unreviewed before the drain
  * drops it from the queue and it stays on main unreviewed. Reads .tumwater/state/post-review.json
- * through the shared atRiskPostReviews traversal the always-on post-merge-risk team alert
- * (src/ui/status-payload.ts postReviewRiskAlert) uses, so the two surfaces cannot drift. A warn,
+ * through the shared atRiskPostReviews traversal, so the selection and wording live in one
+ * place. A warn,
  * never a fail — the checkStaleQueuedMerges precedent: a failing reviewer is operator signal,
  * not a broken environment; readPostReviews never throws (a missing or torn file degrades to the
  * well-formed subset or `[]`), so the check needs no read-error arm. */
@@ -236,16 +230,14 @@ export function checkPostReviews(root) {
 /** How long a queued prompt may wait for its role to dequeue it before the stale-prompt check
  * warns: a day, fixed. An opinionated default with no knob, like MERGE_QUEUE_STALE_MS: a day is
  * long enough that a healthy role's next run would have dequeued the prompt, and short enough
- * that a paused or disabled role's stranded prompt shows up. The always-on stale-prompt team
- * alert (src/ui/status-payload.ts stalePrompts) reuses this same threshold, so it cannot drift
- * from the doctor's check — the STALE_BUG_DAYS precedent. */
-export const STALE_PROMPT_MS = DAY_MS;
+ * that a paused or disabled role's stranded prompt shows up. The stale-prompt check reads this
+ * same threshold, so it cannot drift — the STALE_BUG_DAYS precedent. */
+const STALE_PROMPT_MS = DAY_MS;
 /** The queued inbox prompts the doctor's stale-prompt rule calls stale — deliverable now (a
  * `--at` prompt still counting down is never stale) and queued more than STALE_PROMPT_MS,
  * oldest-first, `queuedAtMs` narrowed to a number. One traversal shared by the doctor's
- * `checkStalePrompts` check and the always-on `stalePrompts` team alert (src/ui/status-payload.ts),
- * so the two surfaces read the same rule at the same threshold and cannot drift. */
-export function staleQueuedPromptRows(root, now) {
+ * `checkStalePrompts` check, so the rule lives in one place at one threshold. */
+function staleQueuedPromptRows(root, now) {
     return queuedListRows(root, null, listWideScope(root))
         .filter((p) => p.queuedAtMs !== null && deliverableAt(p.notBeforeMs, now) && now - p.queuedAtMs > STALE_PROMPT_MS)
         .sort((a, b) => a.queuedAtMs - b.queuedAtMs)
@@ -258,7 +250,7 @@ export function staleQueuedPromptRows(root, now) {
  * views (`tumwater prompt --list`, the dashboard Inbox tab, the TUI Inbox pane) show its age —
  * and only when the operator looks. This names the oldest due-but-undelivered prompt, its role,
  * and the deliver-or-drop commands. Reads the queue through the shared `staleQueuedPromptRows`
- * traversal the always-on stale-prompts alert uses (no new reader in src/inbox/), keeping only
+ * traversal (no new reader in src/inbox/), keeping only
  * rows that are deliverable now — a `--at 7d` prompt still counting down is never stale — and
  * stamped more than STALE_PROMPT_MS ago. A warn, never a fail — the checkStaleQueuedMerges
  * precedent: a stranded prompt is operator signal, not a broken environment. */

package/dist/src/doctor/doctor-check-names.js

@@ -12,6 +12,7 @@ export const DOCTOR_CHECK_NAMES = [
     "init",
     "config key names",
     "brief",
+    "principles",
     "bootstrap",
     "pause",
     "quiet hours",
@@ -28,7 +29,6 @@ export const DOCTOR_CHECK_NAMES = [
     "over-cap model",
     "fallback chain",
     "models for each tier",
-    "image input",
     "claude auth",
     "claude api key",
     "claude version",
@@ -59,6 +59,7 @@ export const DOCTOR_CHECK_NAMES = [
     "check",
     "ci parity",
     "qa coverage",
+    "role notes",
     "root install",
     "flaky checks",
     "post-merge churn",
@@ -72,11 +73,12 @@ export const DOCTOR_CHECK_NAMES = [
     "plan dependencies",
     "stale questions",
     "stale bugs",
-    "waiting bugs",
     "regressed fixes",
     "stale merge-queue entries",
     "merge-queue files",
     "post-merge reviews",
+    "main diff rules",
+    "dropped post-merge reviews",
     "stale prompts",
     "uncommitted backlog",
     "update",