tumwater 0.3.0 → 0.4.0

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

@@ -1,23 +1,24 @@
-import { andMore, readDoc, readDocChecked, FIX_CLAIMS_CHECKED, FIX_CLAIM_HEADING_MAX, REFUSAL_NOTE_MAX } from "./doctor-backlog.js";
+import { andMore, readDoc, readBacklogChecked, FIX_CLAIMS_CHECKED, FIX_CLAIM_HEADING_MAX, REFUSAL_NOTE_MAX } from "./doctor-backlog.js";
+import { cachedByStat } from "../files/stat-cache.js";
 import { VALIDATION_GAP_TAGS } from "../roles/role-guidance.js";
-import fs from "node:fs";
 import path from "node:path";
 import { truncate } from "../text/text.js";
-import { donePlans, plannedPlanEntries } from "../backlog/backlog.js";
-import { entryHold, heldCount } from "../backlog/backlog-eligibility.js";
+import { donePlans, fixedBugEntries, openBugEntries, plannedPlanEntries } from "../backlog/backlog.js";
+import { entryHold, entryKindLabel, heldCount } from "../backlog/backlog-eligibility.js";
 import { planDependencyProblems } from "../backlog/backlog-parts.js";
-import { BACKLOG_FILES, validationGapTag } from "../backlog/backlog-md.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 { fixSymbols, fixedEntriesAt, missingSymbolNames, sourceHaystack, unbackedSymbols } from "../verdict/fix-claim.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,
  * checkValidationGaps) and the PLANS.md / backlog-file integrity checks that read sections and
  * clauses rather than a single document's entries (checkStrandedPlans, checkLiveFinished,
- * checkBacklogHeadings, checkStalledPlans, checkPlanDependencies). They import the shared helpers
- * (readDoc and its checked wrapper readDocChecked, andMore) from doctor-backlog.ts and the
+ * checkBacklogHeadings, checkStalledEntries, checkPlanDependencies). They import the shared helpers
+ * (readDoc and its checked wrapper readBacklogChecked, andMore) from doctor-backlog.ts and the
  * heading-trim bounds,
  * and all of them warn instead of failing: damaged documentation is operator signal, not a
  * broken environment. doctor.ts composes them beside the open-item and queue checks; the shared
@@ -33,28 +34,13 @@ import { okOutcome, warnOutcome } from "./outcome.js";
  * legitimate. A warn, never a fail (the checkFallbackModel precedent): a suspicious record is
  * operator signal, not a broken environment. */
 export function checkFixClaims(root) {
-    const doc = readDocChecked(path.join(root, "BUGS.md"), "BUGS.md", "no BUGS.md — nothing to verify");
+    const doc = readBacklogChecked(root, "BUGS.md");
     if (typeof doc !== "string")
         return doc;
-    // One parse feeds every record's title and body: bugEntryBody re-parsed the whole document
-    // per heading, and BUGS.md grows without bound, so the newest-10 scan paid 1 + 10 full-document
-    // walks where one suffices.
-    const records = fixedEntriesAt(root, doc).slice(0, FIX_CLAIMS_CHECKED);
-    // The haystack walks src/, test/ and scripts/: build it only once a record names something.
-    let haystack;
-    const phantoms = [];
-    for (const { title: heading, body } of records) {
-        const symbols = fixSymbols(body);
-        if (symbols.length === 0)
-            continue;
-        haystack ??= sourceHaystack(root);
-        const missing = unbackedSymbols(root, symbols, haystack);
-        if (missing.length === symbols.length)
-            phantoms.push({ heading, missing });
-    }
-    const [first, ...rest] = phantoms;
+    const problems = fixClaimProblems(root);
+    const [first, ...rest] = problems;
     if (!first)
-        return okOutcome(`newest ${records.length} Fixed record(s) name code that exists on this tree`);
+        return okOutcome(`newest ${fixClaimRecords(root).length} Fixed record(s) name code that exists on this tree`);
     // falseFixReason's message shape: the heading, then up to 3 missing names.
     const { heading, missing } = first;
     const names = missingSymbolNames(missing);
@@ -63,6 +49,76 @@ export function checkFixClaims(root) {
     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`);
 }
+/** The fix-claim rows shared by the doctor's check and the always-on alert: each newest Fixed
+ * record classified through fixSymbols and unbackedSymbols — the gate's own parsing and
+ * existence rules — against ONE cachedSourceHaystack built for the whole scan, keeping a record
+ * only when EVERY symbol its Fix paragraph names is absent, and skipping a record that names no
+ * symbols (pure-documentation fixes are legitimate). */
+function classifyFixClaims(records, root) {
+    const problems = [];
+    let haystack;
+    for (const { title, body } of records) {
+        const symbols = fixSymbols(body);
+        if (symbols.length === 0)
+            continue;
+        haystack ??= cachedSourceHaystack(root);
+        const missing = unbackedSymbols(root, symbols, haystack);
+        if (missing.length === symbols.length)
+            problems.push({ heading: title, missing });
+    }
+    return problems;
+}
+/** The ONE shared fix-claim scan: the newest Fixed records (bounded to FIX_CLAIMS_CHECKED so
+ * pre-convention history never warns forever) as fixedBugEntries reads them — the stat-cached
+ * section reader BUGS.md + BUGS-FIXED.md, bodies kept whole — classified through
+ * classifyFixClaims. Reading through this same reader (and not a one-off fixedEntriesAt walk) is
+ * what keeps the alert and the doctor on the identical problem set; there is only one scan. */
+function fixClaimRecords(root) {
+    return fixedBugEntries(root).slice(0, FIX_CLAIMS_CHECKED);
+}
+/** The problems the ONE shared fix-claim scan found among the newest Fixed records at `root`
+ * (empty when BUGS.md is unreadable or every newest Fixed record names at least one live
+ * symbol). Feeds the always-on amber alert through the stat-cached fixedBugEntries reader and
+ * cachedSourceHaystack, so it stays in step with the doctor and adds no re-read to the 1 Hz TUI
+ * and status-poll path. */
+export function fixClaimProblems(root) {
+    return classifyFixClaims(fixClaimRecords(root), root);
+}
+/** The validation-gap rows shared by the doctor's check and the always-on alert: each newest
+ * Fixed record classified against the closed `**Validation gap:**` vocabulary through
+ * validationGapTag, which is fence-aware — suspects (missing/unrecognized) first, then
+ * `unpinned`, so the first row is the one the doctor's message names and the alert's reason
+ * picks. */
+function classifyValidationGaps(records) {
+    const suspects = [];
+    const unpinned = [];
+    for (const { title, body } of records) {
+        const tag = validationGapTag(body);
+        if (tag === null)
+            suspects.push({ title, kind: "missing" });
+        else if (!VALIDATION_GAP_TAGS.includes(tag))
+            suspects.push({ title, kind: "unrecognized", tag });
+        else if (tag === "unclear-invariant" && !body.toLowerCase().includes("docs/invariants.md"))
+            unpinned.push({ title, kind: "unpinned" });
+    }
+    return [...suspects, ...unpinned];
+}
+/** The ONE scan the doctor's `validation gaps` check and the always-on alert both hand their
+ * rows from: the newest Fixed records (bounded to FIX_CLAIMS_CHECKED so pre-convention history
+ * never warns forever) as fixedBugEntries reads them — the stat-cached section reader BUGS.md +
+ * BUGS-FIXED.md, bodies kept whole — classified through classifyValidationGaps. Reading both
+ * through this same reader (and not the doctor's one-off fixedEntriesAt/fixedSection walk) is
+ * what keeps the alert and the doctor on the identical problem set; there is only one scan. */
+function validationGapRecords(root) {
+    return fixedBugEntries(root).slice(0, FIX_CLAIMS_CHECKED);
+}
+/** The problems the ONE shared validation-gap scan found among the newest Fixed records at `root`
+ * (empty when BUGS.md/BUGS-FIXED.md are unreadable or every newest Fixed record carries a known
+ * tag/trace). Feeds the always-on amber alert through the stat-cached fixedBugEntries reader, so
+ * it stays in step with the doctor and adds no re-read to the 1 Hz TUI and status-poll path. */
+export function validationGapProblems(root) {
+    return classifyValidationGaps(validationGapRecords(root));
+}
 /** The fixed-record validation-gap twin of checkFixClaims, standing in for plans/repair-traces.md's
  * invariant 2 ("the vocabulary is closed and lives in one place"): the bugfix guidance tells every
  * run to write exactly one `**Validation gap:**` line with a known tag, and `none` rather than no
@@ -78,21 +134,16 @@ export function checkFixClaims(root) {
  * may spuriously warn). A warn, never a fail, like its sibling: a suspect record is
  * operator signal, not a broken environment. */
 export function checkValidationGaps(root) {
-    const doc = readDocChecked(path.join(root, "BUGS.md"), "BUGS.md", "no BUGS.md — nothing to verify");
+    // The doctor's check reads BUGS.md itself so it can return its no-file outcome (a missing
+    // BUGS.md — nothing to verify); the classification then runs on the SAME fixedBugEntries
+    // reader the always-on alert feeds from, so the two cannot drift on the problem set. There
+    // is only one scan (validationGapRecords).
+    const doc = readBacklogChecked(root, "BUGS.md");
     if (typeof doc !== "string")
         return doc;
-    const records = fixedEntriesAt(root, doc).slice(0, FIX_CLAIMS_CHECKED);
-    const suspects = [];
-    const unpinned = [];
-    for (const { title, body } of records) {
-        const tag = validationGapTag(body);
-        if (tag === null)
-            suspects.push({ title, problem: "missing" });
-        else if (!VALIDATION_GAP_TAGS.includes(tag))
-            suspects.push({ title, problem: "unrecognized", tag });
-        else if (tag === "unclear-invariant" && !body.toLowerCase().includes("docs/invariants.md"))
-            unpinned.push({ title });
-    }
+    const problems = classifyValidationGaps(validationGapRecords(root));
+    const suspects = problems.filter((p) => p.kind !== "unpinned");
+    const unpinned = problems.filter((p) => p.kind === "unpinned");
     const [first, ...rest] = suspects;
     if (!first) {
         if (unpinned.length > 0) {
@@ -102,10 +153,10 @@ export function checkValidationGaps(root) {
                 `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 ${records.length} Fixed record(s) carry a known Validation gap tag`);
+        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 what = first.problem === "missing"
+    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}"`;
     const valid = VALIDATION_GAP_TAGS.join(", ");
@@ -120,7 +171,7 @@ export function checkValidationGaps(root) {
  * the primary checkout IS main's tree — like checkFixClaims. A warn, never a fail: a misplaced
  * heading is operator signal, not a broken environment. */
 export function checkStrandedPlans(root) {
-    const doc = readDocChecked(path.join(root, "PLANS.md"), "PLANS.md", "no PLANS.md — nothing to verify");
+    const doc = readBacklogChecked(root, "PLANS.md");
     if (typeof doc !== "string")
         return doc;
     // PLANS-DONE.md too: finished plans are archived there (plans/backlog-archive.md), and a plan
@@ -152,6 +203,94 @@ export function checkLiveFinished(root) {
     return warnOutcome(`${parts.join("; ")} — 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
+ * observer tick, so the per-file read must be stat-cached: a steady-state poll pays one stat
+ * per file, not a full re-read of every BACKLOG_FILES member — the archives grow without bound
+ * (PLANS-DONE.md and BUGS-FIXED.md run to MBs), and an uncached read on every poll would copy
+ * them wholesale each time, unlike the stat-cached section readers the rest of the poll path
+ * uses. cachedByStat serves an unchanged file from cache (dev/ino/mtime/size) and re-reads on
+ * a change, so this shares the poll path's freshness contract. The one loop over BACKLOG_FILES
+ * that feeds both checkBacklogHeadings and the always-on `backlog-headings` team alert: absent
+ * files (an early repo) contribute nothing, an existing file that cannot be read adds
+ * `${file} (unreadable)` to `rows` (its duplicate headings, if any, are invisible to every
+ * reader), and each duplicate `## ` title joins both `duplicates` and, as
+ * `${file} "## ${title}"`, `rows` — which therefore keeps BACKLOG_FILES order, the order the
+ * doctor's `backlog headings` row lists its messages in. Two public functions share this so
+ * they cannot drift on the file set, the unreadable clause, or the headings. */
+function scanBacklogHeadings(root) {
+    const duplicates = [];
+    const rows = [];
+    for (const file of BACKLOG_FILES) {
+        const p = path.join(root, file);
+        const scan = cachedByStat(backlogHeadingFileCache, p, p, () => {
+            const read = readDoc(p);
+            if ("error" in read)
+                return { status: "unreadable", headings: [] };
+            return { status: "ok", headings: duplicateHeadings(read.doc) };
+        }, (v) => ({ status: v.status, headings: [...v.headings] }));
+        if (scan === null)
+            continue; // Absent file (early repo): contributes nothing.
+        if (scan.status === "unreadable") {
+            rows.push(`${file} (unreadable)`);
+            continue;
+        }
+        for (const heading of scan.headings) {
+            duplicates.push({ file, heading });
+            rows.push(`${file} "## ${heading}"`);
+        }
+    }
+    return { duplicates, rows };
+}
+/** The module-level stat cache backing scanBacklogHeadings, shared by the doctor row and the
+ * 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. */
+export function duplicatedBacklogHeadings(root) {
+    return scanBacklogHeadings(root).duplicates;
+}
+/** The module-level stat cache backing liveFinishedEntriesFor, keyed by root, so a steady-state
+ * status poll pays four stat calls (two live files, two archives) instead of re-parsing the
+ * live files and the unbounded archives (PLANS-DONE.md runs to MBs) on every poll. Keyed by a
+ * combined stat signature rather than the shared cachedByStat because each row spans FOUR files
+ * (a live file, its finished entries, and the archive it empties into), so no single-file
+ * 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
+ * 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)
+ * when that throws, so an unreadable file stays checkLiveFinished's loud signal and never
+ * breaks a status poll. checkLiveFinished keeps calling liveFinishedHistory directly and is
+ * unchanged. */
+export function liveFinishedEntriesFor(root) {
+    const key = FINISHED_ARCHIVES
+        .flatMap((spec) => [path.join(root, spec.file), path.join(root, spec.archive)])
+        .map((p) => {
+        const st = statOrNull(p);
+        return st ? `${st.dev}:${st.ino}:${st.mtimeMs}:${st.size}` : "absent";
+    })
+        .join("|");
+    const cached = liveFinishedCache.get(root);
+    if (cached?.key === key)
+        return cached.rows.map((r) => ({ ...r }));
+    let rows;
+    try {
+        rows = liveFinishedHistory(root);
+    }
+    catch {
+        liveFinishedCache.delete(root); // Never serve a stale read for an unreadable tree.
+        return []; // Unreadable — checkLiveFinished's signal; a status poll must not throw.
+    }
+    if (liveFinishedCache.size >= 64)
+        liveFinishedCache.clear(); // Safety cap, like backlogHeadingFileCache.
+    liveFinishedCache.set(root, { key, rows });
+    return rows.map((r) => ({ ...r }));
+}
 /** Duplicated `## ` headings already on main (the duplicate-heading half of the backlog-structure
  * check, src/backlog/backlog-structure.ts): a `## Done` a past merge or conflict resolution added
  * twice leaves every later entry after the first section invisible to the section readers, and
@@ -162,63 +301,59 @@ export function checkLiveFinished(root) {
  * that leaves an existing duplicate alone passes and the duplicate itself needs a deliberate
  * removal edit. */
 export function checkBacklogHeadings(root) {
-    const duplicates = [];
-    for (const file of BACKLOG_FILES) {
-        const p = path.join(root, file);
-        if (!fs.existsSync(p))
-            continue; // Absent file (early repo): contributes nothing.
-        const read = readDoc(p);
-        if ("error" in read) {
-            duplicates.push(`${file} (unreadable)`);
-            continue;
-        }
-        const { doc } = read;
-        for (const title of duplicateHeadings(doc))
-            duplicates.push(`${file} "## ${title}"`);
-    }
-    if (duplicates.length === 0)
+    const { rows } = scanBacklogHeadings(root);
+    if (rows.length === 0)
         return okOutcome("no duplicated ## section headings in the backlog files");
-    const [first, ...rest] = duplicates;
+    const [first, ...rest] = rows;
     const more = andMore(rest, (d) => d);
     return warnOutcome(`${first}${more} appears more than once — readers take the first section of a name, so ` +
         `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 plans — planned plans held by a **Needs review …** or **Needs replan …** note,
- * parked until the plan role splits or replans 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
+/** Stalled entries — plans or bugs held by a **Needs review …** or **Needs replan …** 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
  * 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 planned entries whose
- * hold is exactly needs-review, needs-replan, or held-for-operator are collected. A warn, never
- * a fail — the checkRefusedEntries precedent: a parked plan is operator signal, not a broken
- * environment; the plan role resolves the first two itself, and a held-for-operator plan is
- * the operator's to release (`tumwater plan --release`). */
-export function checkStalledPlans(root) {
+ * 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
+ * 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
+ * a held-for-operator entry is the operator's to release (`tumwater plan|bug --release`). */
+export function checkStalledEntries(root) {
     const planned = plannedPlanEntries(root);
-    const stalled = planned.filter((entry) => {
+    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 === "needs-replan" || hold === "held-for-operator" // vocabulary-ok: the held-for-operator hold's key
+            ? { file, entry }
+            : null;
+    };
+    const stalled = [
+        ...planned.map((e) => collect(e, "plans")),
+        ...openBugEntries(root).map((e) => collect(e, "bugs")),
+    ].filter((x) => x !== null);
     const [first, ...rest] = stalled;
     if (!first)
-        return okOutcome("no planned plan 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, (e) => `"${truncate(e.title, FIX_CLAIM_HEADING_MAX)}"`);
-    const hold = entryHold(first, planned);
-    const note = (first.body.split(/\n/).find((line) => line.trimStart().startsWith("**Needs review ") || line.trimStart().startsWith("**Needs replan ")) ?? "").replace(/^\s*\*\*/, "").replace("**", "");
+        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)}"`);
+    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("**", "");
     if (hold === "held-for-operator") { // vocabulary-ok: the held-for-operator hold's key
-        return warnOutcome(`PLANS.md plan "${truncate(first.title, FIX_CLAIM_HEADING_MAX)}" is held for the operator ${heldCount(first.body)} times${more} — release it with tumwater plan --release`); // vocabulary-ok: a held-for-operator plan is the operator's to release
+        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(`PLANS.md plan "${truncate(first.title, FIX_CLAIM_HEADING_MAX)}" is held by a ${hold === "needs-review" ? "Needs review" : "Needs replan"} note ` +
+    return warnOutcome(`${head} "${truncate(first.entry.title, FIX_CLAIM_HEADING_MAX)}" is held by a ${hold === "needs-review" ? "Needs review" : "Needs replan"} 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
  * allocator (entryHoldAgainst) cannot see: a ref naming no heading (the hold is void, so the
  * dependent is claimable now), a clause that parses to no refs (it holds nothing), and a
  * dependency cycle (every part on it stays blocked forever). Reads the tree at `root` through
- * planDependencyProblems. A warn, never a fail, like checkStalledPlans: the plan role writes the
+ * planDependencyProblems. A warn, never a fail, like checkStalledEntries: the plan role writes the
  * clauses by hand and fixes them itself. The most serious kind is named — cycle, then dangling,
  * then unparsed — with a count of the other kinds. */
 export function planDependencyProblem(root) {

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

@@ -2,6 +2,8 @@ import { roleLabel } from "../roles/role-labels.js";
 import fs from "node:fs";
 import path from "node:path";
 import { errorMessage, truncate } from "../text/text.js";
+import { shortSha } from "../text/format.js";
+import { readPostReviews, POST_REVIEW_FAILURE_LIMIT } from "../review/post-merge-review.js";
 import { humanSeconds, secondsSince, HOUR_MS, DAY_MS } from "../text/datetime.js";
 import { eventsSince } from "../events/event-window.js";
 import { finiteNumber } from "../files/json-object.js";
@@ -13,12 +15,15 @@ import { listWideScope, queuedListRows } from "../inbox/inbox.js";
 import { deliverableAt } from "../inbox/prompt-not-before.js";
 import { currentBranch, targetBranch } from "../git/git.js";
 import { gitTry } from "../git/git-run.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { briefFile } from "../brief/brief.js";
 import { BACKLOG_FILES } from "../backlog/backlog-md.js";
 import { okOutcome, warnOutcome } from "./outcome.js";
 /** The doctor's backlog modules' shared scaffolding and the check groups that do not read a
- * single backlog document: the merge-queue and queued-prompt checks (checkStaleQueuedMerges,
- * checkMergeQueueFiles, checkStalePrompts and the mergeWaitPhrase helper) and the uncommitted-
+ * single backlog document: the merge-queue, post-merge-review and queued-prompt checks
+ * (checkStaleQueuedMerges, checkMergeQueueFiles, checkPostReviews, checkStalePrompts and the
+ * mergeWaitPhrase helper) and the uncommitted-
  * edits-in-the-primary-checkout check. This module also hosts the helpers and constants the
  * per-document checks import — readDoc and its checked wrapper readDocChecked, andMore, and the
  * age/heading-trim bounds — so the per-document reads cannot drift. The per-document
@@ -75,9 +80,10 @@ export function readDoc(p) {
         return { error: errorMessage(err) };
     }
 }
-/** The single-file check's read prologue, shared by checkFixClaims and checkStrandedPlans:
- * an absent file is that check's own "nothing to verify" ok outcome, an unreadable one a warn
- * naming the file. Returns the document, or the outcome the caller should return as-is. */
+/** The single-file check's read prologue: an absent file is that check's own "nothing to
+ * verify" ok outcome, an unreadable one a warn naming the file. Returns the document, or the
+ * outcome the caller should return as-is. The per-file doctor checks go through readBacklogChecked.
+ * */
 export function readDocChecked(p, file, missingDetail) {
     if (!fs.existsSync(p))
         return okOutcome(missingDetail);
@@ -86,6 +92,15 @@ export function readDocChecked(p, file, missingDetail) {
         return warnOutcome(`cannot read ${file} — ${read.error}`);
     return read.doc;
 }
+/** 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
+ * `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. */
+export function readBacklogChecked(root, file) {
+    return readDocChecked(path.join(root, file), file, `no ${file} — nothing to verify`);
+}
 /** How long a queued merge may wait without its change starting before the stale-queued-merge check
  * 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
@@ -109,7 +124,7 @@ const MERGE_WAIT_WINDOW_MS = DAY_MS;
  * holding a change being verified or merged right now — a slow review is not a stalled drain, and
  * an absent or never-throwing unreadable marker contributes the empty set. Reads the tree at `root`
  * with the already-exported readers, changing nothing in src/merge/. A warn, never a fail — the
- * checkStaleQuestions/checkStalledPlans precedent: a queued wait is legitimate while the team is
+ * checkStaleQuestions/checkStalledEntries precedent: a queued wait is legitimate while the team is
  * genuinely held, and those holds already warn separately. */
 export function checkStaleQueuedMerges(root, now) {
     const withWait = (out) => {
@@ -169,6 +184,55 @@ export function checkMergeQueueFiles(root) {
     return warnOutcome(`the merge queue holds ${plural(files.length, "file")} the reader skips — ${first}${more}; ` +
         `a torn or foreign file is never cleared, so nothing ages it or surfaces its merge — remove it (a crashed enqueue's merge ref still recovers on the next run)`);
 }
+/** The failures count at which a post-merge review is one failed run from being dropped: one
+ * below POST_REVIEW_FAILURE_LIMIT, so the drain's drop limit and this at-risk bar cannot drift
+ * (the STALE_BUG_DAYS precedent). A review at this bar has as many unreviewed failures as the
+ * drain allows before it drops the commit from the queue forever. */
+export const POST_REVIEW_AT_RISK_FAILURES = POST_REVIEW_FAILURE_LIMIT - 1;
+/** The post-merge reviews one failed run from being dropped, in file (FIFO) order: every entry
+ * whose `failures` is at least POST_REVIEW_AT_RISK_FAILURES, each with `commit`, `role`,
+ * `summary` and `failures` carried out (a missing failures reads as 0, so it is never at risk).
+ * A review that has already been rejected is left out: the drain settles a rejection as
+ * `{ ...entry, rejected }` (it preserves `failures`) and never re-runs it, so a rejected commit
+ * 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
+ * through readPostReviews, which degrades a missing or torn file to the well-formed subset or
+ * `[]` and never throws. */
+export function atRiskPostReviews(root) {
+    return readPostReviews(root)
+        .filter((e) => e.rejected === undefined && e.fixed === undefined && (e.failures ?? 0) >= POST_REVIEW_AT_RISK_FAILURES)
+        .map((e) => ({ commit: e.commit, role: e.role, summary: e.summary, failures: e.failures ?? 0 }));
+}
+/** 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. */
+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}; ` +
+        `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,
+ * 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. */
+export function checkPostReviews(root) {
+    const rows = atRiskPostReviews(root);
+    const phrase = atRiskPostReviewsPhrase(rows);
+    return phrase === null ? okOutcome("no post-merge review is one failed run from being dropped") : warnOutcome(phrase);
+}
 /** 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
@@ -223,6 +287,35 @@ export function mergeWaitPhrase(events) {
     const longest = Math.max(...waits);
     return `merges in the last 24h waited ${shortSpanPhrase(median)} median, ${shortSpanPhrase(longest)} longest (${plural(waits.length, "merge")})`;
 }
+/** Discover the tracked backlog/brief files with uncommitted edits in the primary checkout (the
+ * shared discovery behind checkUncommittedBacklog and commitUncommittedBacklog). A primary off
+ * the base branch is skipped by its callers: the ref-push merge arm leaves its working tree
+ * alone. Untracked files are not edits of a tracked file and are ignored. */
+export async function dirtyBacklogFiles(root, config) {
+    const primary = await currentBranch(root);
+    const base = targetBranch(config?.baseBranch, primary);
+    // A primary off the base branch is skipped by every caller before it reads `watched`/`dirty`, so
+    // the brief is not touched here either: an unreadable brief must not turn that skip into a throw
+    // (the ref-push merge arm leaves an off-base working tree alone).
+    if (primary === null || primary !== base)
+        return { base, primary, watched: [], dirty: [] };
+    let brief = null;
+    try {
+        brief = briefFile(root);
+    }
+    catch {
+        // An unreadable brief is a doctor finding of its own; it must not abort the uncommitted-backlog
+        // check or `--commit-backlog`, so the tracked backlog set is watched without it.
+    }
+    const watched = [...new Set([...BACKLOG_FILES, ...(brief ? [brief] : [])])];
+    const out = await gitTry(root, "status", "--porcelain", "--", ...watched);
+    if (out === null)
+        return { base, primary, watched, dirty: null };
+    const dirtySet = new Set(out.split("\n")
+        .filter((line) => line.length > 3 && !line.startsWith("??"))
+        .map((line) => line.slice(3)));
+    return { base, primary, watched, dirty: watched.filter((f) => dirtySet.has(f)) };
+}
 /** Names the backlog files (and the brief file) with uncommitted edits in the primary checkout. An
  * operator write is meant to be committed on the base branch by commitOperatorBacklogEdit; when
  * that commit does not happen the edit is invisible to every role worktree (they branch from main)
@@ -230,26 +323,66 @@ export function mergeWaitPhrase(events) {
  * the base branch is skipped: the ref-push merge arm leaves its working tree alone. Untracked files
  * are not edits of a tracked file and are ignored. */
 export async function checkUncommittedBacklog(root, config) {
-    const primary = await currentBranch(root);
-    const base = targetBranch(config?.baseBranch, primary);
+    const { base, primary, watched, dirty } = await dirtyBacklogFiles(root, config);
     if (primary === null || primary !== base) {
         return okOutcome(`your checkout is not on ${base}; backlog writes from you are not committed from it`);
     }
-    const brief = briefFile(root);
-    const files = [...new Set([...BACKLOG_FILES, ...(brief ? [brief] : [])])];
-    const out = await gitTry(root, "status", "--porcelain", "--", ...files);
-    if (out === null)
+    if (dirty === null)
         return okOutcome("could not read git status; skipped");
-    const dirty = new Set(out.split("\n")
-        .filter((line) => line.length > 3 && !line.startsWith("??"))
-        .map((line) => line.slice(3)));
-    const named = files.filter((f) => dirty.has(f));
-    if (named.length === 0) {
-        const list = files.slice(0, -1).join(", ");
-        return okOutcome(`${list} and ${files[files.length - 1]} are committed`);
+    if (dirty.length === 0) {
+        const list = watched.slice(0, -1).join(", ");
+        return okOutcome(`${list} and ${watched[watched.length - 1]} are committed`);
     }
-    const list = named.join(", ");
-    return warnOutcome(`${list} ${named.length > 1 ? "have" : "has"} uncommitted changes in your checkout — ` +
+    const list = dirty.join(", ");
+    return warnOutcome(`${list} ${dirty.length > 1 ? "have" : "has"} uncommitted changes in your checkout — ` +
         `roles branch from main and do not see them, and a merge that touches one cannot fast-forward the checkout ` +
-        `(merge_blocked); review them with \`git diff -- ${list}\` and commit them on ${base}`);
+        `(merge_blocked); review them with \`git diff -- ${list}\` and commit them on ${base} ` +
+        `(or run \`tumwater doctor --commit-backlog\`, or the Health card's Commit backlog, or the TUI Health tab's Ctrl+A)`);
+}
+/** Commit every dirty tracked backlog or brief file in the primary checkout on the base branch,
+ * through the same commitOperatorBacklogEdit core every operator backlog write uses, running
+ * under the primary-worktree lock it takes. The dirtyBacklogFiles discovery and branch precedence
+ * are checkUncommittedBacklog's own, so a `tumwater doctor --commit-backlog` unblocks exactly the
+ * merges the `uncommitted backlog` row warns would be blocked. When the primary is off the base
+ * branch or the status cannot be read it commits nothing and reports a skip sentence; a file whose
+ * commit fails stays dirty and lands in `failed` while the other listed files are still attempted.
+ * Never throws. */
+export async function commitUncommittedBacklog(root, config) {
+    const d = await dirtyBacklogFiles(root, config);
+    if (d.primary === null || d.primary !== d.base)
+        return { base: d.base, committed: [], failed: [], skipped: `your checkout is not on ${d.base}; nothing committed` };
+    if (d.dirty === null)
+        return { base: d.base, committed: [], failed: [], skipped: "could not read git status; nothing committed" };
+    const committed = [];
+    const failed = [];
+    for (const name of d.dirty) {
+        const ok = await commitOperatorBacklogEdit(root, name, stampedSubject("operator", `Commit uncommitted ${name}`)); // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
+        (ok ? committed : failed).push(name);
+    }
+    return { base: d.base, committed, failed, skipped: null };
+}
+/** The committed/failed/skip wording the CLI, the dashboard handler and the TUI flash all share
+ * for a BacklogCommitReport, so the three surfaces cannot drift: one `committed <file> on
+ * <base>` line per committed file, one `could not commit <file> — commit it by hand` line per
+ * failed file, then the skipped sentence when set. `[]` when the report committed nothing,
+ * failed nothing, and carried no skip sentence. `tumwater doctor --commit-backlog` (src/cli.ts),
+ * the dashboard Health card's Commit backlog (handleCommitBacklog) and the TUI Health tab's
+ * Ctrl+A all render from this one source. */
+export function backlogCommitLines(report) {
+    const lines = [
+        ...report.committed.map((file) => `committed ${file} on ${report.base}`),
+        ...report.failed.map((file) => `could not commit ${file} — commit it by hand`),
+    ];
+    if (report.skipped !== null)
+        lines.push(report.skipped);
+    return lines;
+}
+/** The single-line message a surface flashes or answers for a BacklogCommitReport: the shared
+ * backlogCommitLines joined with "; ", or the nothing-to-commit sentence when the report
+ * committed nothing, failed nothing and carried no skip sentence. Lives here beside
+ * backlogCommitLines so the dashboard Health card's Commit backlog handler and the TUI Health
+ * tab's Ctrl+A flash cannot drift from each other. */
+export function backlogCommitMessage(report) {
+    const lines = backlogCommitLines(report);
+    return lines.length ? lines.join("; ") : "nothing to commit — every watched backlog or brief file is committed";
 }