tumwater 0.4.1 → 0.4.2

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

@@ -1,6 +1,6 @@
 /** Backlog eligibility: which PLANS.md / BUGS.md entries a work role may take now (plans,
- * parallel-work-instances, part 2/7). An entry is held when its body carries a **Refused …**,
- * **Needs review …**, **Needs replan …** or **Waiting for the next failure …** note, or when
+ * parallel-work-instances, part 2/7). An entry is held when its body carries a **Refused …**
+ * or **Needs review …** note, or when
  * its heading's trailing parenthetical
  * (or a parenthetical left open by a wrapped heading) names a prerequisite (`requires parts
  * 1/5–3/5 landed`) that is itself still listed under `## Planned`. The parsers are pure over
@@ -11,24 +11,26 @@ import path from "node:path";
 import { statOrNull } from "../files/files.js";
 import { allLiveClaims } from "../runner/runner-state-load.js";
 import { escapeRegExp, firstTrimmedLineStartingWith } from "../text/text.js";
-import { HELD_TAG_PREFIX, NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX, PRIOR_HELD_PREFIX, WAITING_FOR_FAILURE_PREFIX } from "../roles/role-guidance.js";
+import { HELD_TAG_PREFIX, NEEDS_REVIEW_PREFIX, PRIOR_HELD_PREFIX } from "../roles/role-guidance.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { actionableEntryRangesFor } from "./backlog-index-data.js";
 import { entryKey, partKey, plannedPartKeys, plansWaitingOn, requiredParts, seriesPart } from "./backlog-parts.js";
 import { finishedFiles, openBugEntries, plannedPlanEntries } from "./backlog.js";
-/** The number of holds an entry's count must reach before a Needs-review/Needs-replan note
+/** The number of holds an entry's count must reach before a Needs-review note
  * becomes a `held-for-operator` hold (the operator's decision, surfaced by parts 2/3 and 3/3). */
 export const OPERATOR_HOLD_THRESHOLD = 3;
-/** The held count a body records: the integer in the first Needs-review or Needs-replan note
- * line's `(held N)` tag, else the integer in a `**Previously held N**` line, else 0. A present
- * but non-numeric `(held …)` tag is 0 (and stops the scan), so a malformed tag never throws.
- * Pure over the body text — the data-layer read half of the convergence backstop. */
+/** The held count a body records: the integer in the first Needs-review note
+ * line's `(held N)` tag, else 0. A present but non-numeric `(held …)` tag is 0 (and stops the
+ * scan), so a malformed tag never throws. Pure over the body text — the data-layer read half of
+ * the convergence backstop. No writer emits a `(held N)` tag anymore and the `**Previously held
+ * N**` markers left on disk are never read, so a freshly written flat note always reads 0 and a
+ * new hold never escalates to the operator's desk. */
 export function heldCount(body) {
     const tagRe = new RegExp(`${escapeRegExp(HELD_TAG_PREFIX)}(\\d+)\\)`);
     for (const raw of body.split("\n")) {
         const line = raw.trimStart();
-        const note = line.startsWith(NEEDS_REVIEW_PREFIX) || line.startsWith(NEEDS_REPLAN_PREFIX);
+        const note = line.startsWith(NEEDS_REVIEW_PREFIX);
         if (!note)
             continue;
         const tag = tagRe.exec(line);
@@ -37,29 +39,22 @@ export function heldCount(body) {
         if (line.includes(HELD_TAG_PREFIX))
             return 0;
     }
-    for (const raw of body.split("\n")) {
-        const line = raw.trimStart();
-        if (!line.startsWith(PRIOR_HELD_PREFIX))
-            continue;
-        const count = /\d+/.exec(line.slice(PRIOR_HELD_PREFIX.length));
-        return count === null ? 0 : Number(count[0]);
-    }
     return 0;
 }
-/** The `(held N)` count on a single Needs-review or Needs-replan note line, or undefined when the
+/** The `(held N)` count on a single Needs-review note line, or undefined when the
  * line is not such a note or carries no numeric tag. The per-line form of heldCount, so a writer
  * that drops notes (withoutHeldForOperatorNotes) can gate on the same threshold without scanning
  * the whole body. */
 function lineHeldCount(line) {
     const trimmed = line.trimStart();
-    const isNote = trimmed.startsWith(NEEDS_REVIEW_PREFIX) || trimmed.startsWith(NEEDS_REPLAN_PREFIX);
+    const isNote = trimmed.startsWith(NEEDS_REVIEW_PREFIX);
     if (!isNote)
         return undefined;
     const tag = new RegExp(`${escapeRegExp(HELD_TAG_PREFIX)}(\\d+)\\)`).exec(trimmed);
     return tag === null ? undefined : Number(tag[1]);
 }
 /** The `**Refused …` note prefix a refusing run writes. Every hold note — this one and the
- * imported Needs-review and Needs-replan prefixes — is matched as a line prefix (hasNoteLine)
+ * imported Needs-review prefix — is matched as a line prefix (hasNoteLine)
  * so a mention in prose never holds an entry. */
 const REFUSED_PREFIX = "**Refused ";
 /** True when `body` carries a line (ignoring leading indentation) that begins with `prefix`.
@@ -79,9 +74,11 @@ function noteText(body, prefix) {
 export function refusalNote(body) {
     return noteText(body, REFUSED_PREFIX);
 }
-/** The text of `body`'s Waiting-for-the-next-failure note, or null when it has none. */
-export function waitingNote(body) {
-    return noteText(body, WAITING_FOR_FAILURE_PREFIX);
+/** The text of `body`'s Needs-review note, or null when it has none (entryHold's
+ * "needs-review" hold). A needs-review note parks the entry (an unreproducible bug, a plan
+ * judged too large, a rejected plan), so the stale-bug checks skip it like a refused one. */
+export function needsReviewNote(body) {
+    return noteText(body, NEEDS_REVIEW_PREFIX);
 }
 /** `lines` without any line starting with `prefix` (the same line-prefix rule hasNoteLine
  * applies). When a dropped note sat between two blank lines, the blank line after it goes too,
@@ -99,17 +96,12 @@ function withoutNoteLines(lines, prefix) {
     }
     return out;
 }
-/** `lines` without any Refused note line. Every other line, Needs-review, needs-replan and
- * waiting notes included, is kept, so refusal lifting never lifts another hold. */
+/** `lines` without any Refused note line. Every other line, Needs-review notes included, is
+ * kept, so refusal lifting never lifts another hold. */
 export function withoutRefusalNotes(lines) {
     return withoutNoteLines(lines, REFUSED_PREFIX);
 }
-/** `lines` without any Waiting-for-the-next-failure note line, collapsing blank lines as
- * withoutRefusalNotes does. */
-export function withoutWaitingNotes(lines) {
-    return withoutNoteLines(lines, WAITING_FOR_FAILURE_PREFIX);
-}
-/** `lines` with every Needs-review/Needs-replan note whose `(held N)` count reached
+/** `lines` with every Needs-review note whose `(held N)` count reached
  * OPERATOR_HOLD_THRESHOLD removed, together with its `**Previously held N−1**` line (the prior
  * count the increment rule recorded beside the live `(held N)`), so a `--release` lift leaves
  * neither behind and the entry becomes eligible. Drops nothing when no note is at or past the
@@ -203,9 +195,9 @@ export function waitingPartRanges(root, title) {
     return out;
 }
 /** Why `entry` is held against the still-`planned` entries, or null when it may be taken: a
- * `**Refused …` line (refused), a Needs-review line (needs-review), a Needs-replan line
- * (needs-replan — the plan role owns it), or a prerequisite `(series, part)` still among
- * `planned` ({ blockedBy }). Series compare case-insensitively; part tokens compare verbatim.
+ * `**Refused …` line (refused), a Needs-review line (needs-review), or a prerequisite
+ * `(series, part)` still among `planned` ({ blockedBy }). Series compare case-insensitively;
+ * part tokens compare verbatim.
  * Bodies mentioning "requires" are never consulted — only the heading's trailing or
  * still-open parenthetical. */
 export function entryHold(entry, planned) {
@@ -217,17 +209,13 @@ export function entryHold(entry, planned) {
 export function entryHoldAgainst(entry, plannedParts) {
     if (hasNoteLine(entry.body, REFUSED_PREFIX))
         return "refused";
-    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX) || hasNoteLine(entry.body, NEEDS_REPLAN_PREFIX)) {
+    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX)) {
         // A note whose held count reached OPERATOR_HOLD_THRESHOLD stops out of the role loop:
-        // neither the plan role (planBacklogFull tests only these two) nor this role takes it.
+        // neither the plan role (planBacklogFull) nor this role takes it.
         return heldCount(entry.body) >= OPERATOR_HOLD_THRESHOLD
             ? "held-for-operator" // vocabulary-ok: the operator-held string names the operator hold decision
-            : hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX)
-                ? "needs-review"
-                : "needs-replan";
+            : "needs-review";
     }
-    if (hasNoteLine(entry.body, WAITING_FOR_FAILURE_PREFIX))
-        return "waiting-for-failure";
     const refs = requiredParts(entry.title);
     if (refs.length === 0)
         return null;
@@ -247,12 +235,8 @@ export function holdMark(hold) {
         return " [blocked: refused]";
     if (hold === "needs-review")
         return " [blocked: needs review]";
-    if (hold === "needs-replan")
-        return " [blocked: needs replan]";
     if (hold === "held-for-operator")
         return " [blocked: held for operator]"; // vocabulary-ok: this hold names the operator-held wording for the operator decision
-    if (hold === "waiting-for-failure")
-        return " [blocked: waiting for the next failure]";
     return ` [blocked: requires ${hold.blockedBy.join(", ")}]`;
 }
 /** The line `plan|bug --release` and `--top` print when the entry they touched is still held:
@@ -359,13 +343,13 @@ export function operatorHeldEntries(root) {
 export function entryKindLabel(file) {
     return file === "bugs" ? "Bug" : "Plan";
 }
-/** The planned plans and open bugs whose hold is exactly `"needs-review"` or
- * `"needs-replan"`, in file order: the entries parked by a Needs-review/Needs-replan note
- * until the plan role splits or replans them (the `stalled-entries` team alert's input), each
- * carrying its backlog file, 0-based index and the hold. Same `backlogHolds(root)` + the
- * planned/`openBugEntries` readers `operatorHeldEntries` uses, so the alert and the doctor's
- * `stalled entries` row classify through the same `entryHold` and cannot disagree on which
- * holds are role-resolvable. A held-for-operator entry (a note at the held threshold) is
+/** The planned plans and open bugs whose hold is exactly `"needs-review"`, in file order: the
+ * entries parked by a Needs-review note until the plan role splits or replans them (the
+ * `stalled-entries` team alert's input), each carrying its backlog file, 0-based index and the
+ * hold. Same `backlogHolds(root)` + the planned/`openBugEntries` readers `operatorHeldEntries`
+ * uses, so the alert and the doctor's `stalled entries` row classify through the same
+ * `entryHold` and cannot disagree on which holds are role-resolvable. A held-for-operator
+ * entry (a note at the held threshold) is
  * excluded — it feeds `operatorHeldEntries` and the `operator-held` alert instead. A missing
  * file yields `[]`. */
 export function stalledEntries(root) {
@@ -374,7 +358,7 @@ export function stalledEntries(root) {
     const entriesOf = (entries, held, file) => {
         entries.forEach((e, i) => {
             const hold = held[i];
-            if (hold === "needs-review" || hold === "needs-replan")
+            if (hold === "needs-review")
                 out.push({ file, index: i, title: e.title, hold });
         });
     };
@@ -426,17 +410,25 @@ export function cancelledClaimNote(runner) {
         ? ""
         : `${roleLabel(runner)} is still working on it — its run goes on; \`tumwater abort --role ${runner}\` stops it`;
 }
+/** The backlog file and section a claim-taking role's entries live under: BUGS.md's `## Open`
+ * for bugfix, PLANS.md's `## Planned` for every other base. An instance id resolves through its
+ * base role. The one home of the role → (file, section) mapping, so eligibility (eligibleEntries
+ * below) and claim staging (scheduling/claims.ts) read a claim's line range from the right file
+ * and cannot drift on which section a role owns. */
+export function roleSection(role) {
+    return baseRoleOf(role) === "bugfix"
+        ? { file: "BUGS.md", section: "Open" }
+        : { file: "PLANS.md", section: "Planned" };
+}
 /** The entries `role` may take now, in file order: PLANS.md's `## Planned` entries for
  * feature, BUGS.md's `## Open` entries for bugfix, minus every entry entryHold holds, each with
  * its stamp-free key, verbatim title and 1-based line range. Reads the primary checkout through
  * the same stat-cached readers the index uses; a missing or unreadable file yields []. */
 export function eligibleEntries(root, role) {
-    // An instance id (`bugfix-2`) resolves through its base role, exactly as claims.ts's
-    // roleSection does, so a claim's line range is read from the right file.
-    const bugfix = baseRoleOf(role) === "bugfix";
-    const file = bugfix ? "BUGS.md" : "PLANS.md";
-    const section = bugfix ? "Open" : "Planned";
-    const entries = bugfix ? openBugEntries(root) : plannedPlanEntries(root);
+    // An instance id (`bugfix-2`) resolves through its base role, as roleSection does, so a
+    // claim's line range and the entry list are read from the right file.
+    const { file, section } = roleSection(role);
+    const entries = section === "Open" ? openBugEntries(root) : plannedPlanEntries(root);
     const ranges = actionableEntryRangesFor(root, file, section);
     const planned = plannedPlanEntries(root);
     const parts = plannedPartKeys(planned);

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

@@ -0,0 +1,133 @@
+/** File brand-new BUGS.md `## Open` entries (operator bug reports, quarantined flaky tests) on
+ * the base branch as one `tumwater(operator):` commit, under the merge lock and the
+ * primary-worktree lock. Split out of backlog-archive.ts, whose name and doc cover archiving
+ * finished entries to the archive files, not appending new open entries. */
+import fs from "node:fs";
+import path from "node:path";
+import { withLock, withPrimaryWorktreeLockAsync } from "../concurrency/lock.js";
+import { readTextIfExists, writeTextAtomic } from "../files/files.js";
+import { commitAuthorArgs, committerIdentArgs, git, gitTry } from "../git/git-run.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { mergeLockDir } from "../paths.js";
+import { plural } from "../text/phrases.js";
+import { collapseWhitespace, errorFirstLine } from "../text/text.js";
+import { formatDate } from "../text/datetime.js";
+import { parseEntryDetails } from "./backlog-md.js";
+import { appendBugEntryLocked } from "./backlog-write.js";
+import { primaryOffBaseBranchReason } from "./backlog-archive.js";
+/** The start of a quarantine entry's title for `test`, up to the date. appendBugEntryLocked
+ * collapses whitespace in the title, so the test part is collapsed the same way; collapsing the
+ * whole prefix would trim its trailing space. */
+function quarantineTitlePrefix(test) {
+    return collapseWhitespace(`\`${test}\` failed, then passed on the same tree`) + " (quarantined by tumwater ";
+}
+/** Output fenced into a bug body: a fence of its own length cannot be closed by the quoted text. */
+function fencedTail(tail) {
+    return ["~~~~", ...tail.replaceAll("~~~~", "~~~").split("\n").slice(-30), "~~~~"].join("\n");
+}
+/** File one BUGS.md `## Open` entry per given entry and commit BUGS.md on the base branch as one
+ * `tumwater(operator):` commit (the subject built from the number of entries actually appended is
+ * stamped under the operator role), under the merge lock and the primary-worktree lock exactly as
+ * archiveFinishedOnMain does. Skipped,
+ * writing nothing, when the primary checkout is off the base branch, BUGS.md has uncommitted
+ * changes, or BUGS.md exists but cannot be read; a failed append or commit restores BUGS.md.
+ * Every entry is appended verbatim as its own `## Open` heading — unless its `ifOpen` dedupe
+ * matches an existing heading, which is reused instead — and the returned headings are the
+ * entry headings in input order. */
+export async function fileBugsOnMain(root, entries, subject, opts = {}) {
+    return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
+        const offBase = await primaryOffBaseBranchReason(root);
+        if (offBase !== null)
+            return { status: "skipped", reason: offBase };
+        const status = await gitTry(root, "status", "--porcelain", "--", "BUGS.md");
+        if (status === null)
+            return { status: "skipped", reason: "could not read git status" };
+        if (status.trim() !== "" && !status.startsWith("??")) {
+            return { status: "skipped", reason: "BUGS.md has uncommitted changes" };
+        }
+        const file = path.join(root, "BUGS.md");
+        let before;
+        try {
+            before = readTextIfExists(file);
+        }
+        catch (err) {
+            return { status: "skipped", reason: `BUGS.md could not be read: ${errorFirstLine(err)}` };
+        }
+        const open = before === null ? [] : parseEntryDetails(before, "Open").map((e) => e.title);
+        const headings = [];
+        let appended = 0;
+        const restoreBugs = async () => {
+            await gitTry(root, "reset", "-q", "--", "BUGS.md");
+            if (before === null)
+                fs.rmSync(file, { force: true });
+            else
+                writeTextAtomic(file, before);
+        };
+        try {
+            for (const entry of entries) {
+                if (entry.ifOpen !== undefined) {
+                    const existing = entry.ifOpen(open);
+                    if (existing !== undefined) {
+                        headings.push(existing);
+                        continue;
+                    }
+                }
+                headings.push(appendBugEntryLocked(root, entry.title, entry.body));
+                appended++;
+            }
+        }
+        catch (err) {
+            await restoreBugs();
+            return { status: "skipped", reason: `a BUGS.md entry could not be written: ${errorFirstLine(err)}` };
+        }
+        if (appended === 0)
+            return { status: "filed", headings };
+        const commitSubject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
+        subject(appended));
+        try {
+            await git(root, "add", "--", "BUGS.md");
+            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", commitSubject, "--", "BUGS.md");
+        }
+        catch (err) {
+            await restoreBugs();
+            return { status: "skipped", reason: `the commit failed: ${errorFirstLine(err)}` };
+        }
+        return { status: "filed", headings };
+    }), opts.lockTimeoutMs);
+}
+/** File one BUGS.md `## Open` entry per newly quarantined test and commit BUGS.md on the base
+ * branch as one `tumwater(operator):` commit, delegating the locked write/commit to
+ * fileBugsOnMain and preserving the existing subject. A test whose quarantine entry is already
+ * under `## Open` (a filing whose markQuarantineFiled failed after the commit) gets that heading
+ * back and is not filed again — the dedupe runs inside fileBugsOnMain under the merge lock (via
+ * each entry's `ifOpen`), so concurrent quarantine filings cannot both append a duplicate, and
+ * the real skip on a dirty or off-base BUGS.md is enforced under the same lock. */
+export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
+    const date = formatDate(new Date());
+    const toFile = [];
+    for (const { test, tail } of tests) {
+        const prefix = quarantineTitlePrefix(test);
+        const body = [
+            `The check failed on this test and then passed on a re-run of the same tree, so tumwater quarantined it: it counts as a known failure until this entry leaves \`## Open\`. Find why it is unstable and fix it.`,
+            ...(tail ? ["", fencedTail(tail)] : []),
+        ].join("\n");
+        toFile.push({
+            title: `${prefix}${date})`,
+            body,
+            // Dedupe under the lock, against the headings fileBugsOnMain reads: the reused heading
+            // (not a duplicate) is returned in headings and zipped back to this test below.
+            ifOpen: (open) => open.find((t) => t.startsWith(prefix)),
+        });
+    }
+    const outcome = await fileBugsOnMain(root, toFile, 
+    // Size the subject by what was actually appended: tests whose `## Open` entry was already
+    // present are reused, not filed, so a mixed batch keeps the original "File N …" wording
+    // with N the count of new entries only.
+    (appended) => `File ${plural(appended, "quarantined flaky test", "quarantined flaky tests")} in BUGS.md`, opts);
+    if (outcome.status === "skipped")
+        return { status: "skipped", reason: outcome.reason };
+    // fileBugsOnMain's headings align with `tests` in order (reused headings or appended titles).
+    const bugs = new Map();
+    outcome.headings.forEach((heading, i) => bugs.set(tests[i].test, heading));
+    return { status: "filed", bugs };
+}

package/dist/src/backlog/backlog-index-data.js

@@ -66,7 +66,7 @@ export function actionableEntryRangesFor(root, file, sectionTitle) {
     return (cachedTextByStat(actionableRangesCache, `${full}\u0000${sectionTitle}`, full, (md) => actionableEntryRanges(md, sectionTitle), (ranges) => ranges.slice()) ?? []);
 }
 /** True when `row` is a candidate for series-collapsing: it is a series part held only by an
- * unmerged prerequisite (`{ blockedBy }`, not a Refused/needs-review/needs-replan note) and no live
+ * unmerged prerequisite (`{ blockedBy }`, not a Refused/needs-review note) and no live
  * claim names it. Returns the row's series part when it collapses, else null. */
 function collapsibleSeriesPart(row) {
     if (row.claimer !== undefined)
@@ -116,7 +116,7 @@ export function partsLabel(rows) {
  * or more such parts renders as one line at the position of its first collapsed part, spanning from
  * that part's start to the last's end, with the part list (`2/4–4/4`) and a `[blocked: each waits
  * on an earlier part]` mark. A series with a single blocked part, an eligible part, a note-held
- * (Refused/needs-review/needs-replan) part and a claimed part keep their ordinary lines, so the
+ * (Refused/needs-review) part and a claimed part keep their ordinary lines, so the
  * eligibility rules the feature role's charter teaches are unchanged; the collapsed mark keeps the
  * `[blocked: …]` prefix it already skips. */
 /** The grouping half of backlog-index's collapseBlockedSeries, on any rows carrying a title,

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

@@ -134,7 +134,7 @@ export function nextSectionHeading(lines, from, fenced) {
 /** The body lines of one `## <sectionTitle>` section with fenced content stripped: the
  * sectionLines walk, then a fresh fenceTracker's filter — the shape every reader that
  * classifies a section's lines as markdown structure (entry headings, bullets, dates) walks.
- * Exactly three call sites today: entryDates (below), backlog-structure.ts's
+ * Exactly four call sites today: entryDates and entryLags (both below), backlog-structure.ts's
  * strandedPlanEntries, and stage-backlog-checks.ts's placeholderSections. The fresh
  * tracker is in sync with the document here: sectionLines
  * only recognizes a `## ` boundary outside a fence, so the section's heading line is
@@ -248,30 +248,44 @@ export function entryDates(md, sectionTitle, dateRe, first = false) {
     const dates = [];
     const pick = first ? firstDate : lastDate;
     const lines = sectionBodyLines(md, sectionTitle);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? "";
-        if (!line.startsWith("### ") && !line.startsWith("- "))
-            continue;
-        const meta = headingMetadata(lines, i);
+    eachEntryStart(lines, ({ isBullet, meta, tail }) => {
         let date = null;
-        if (line.startsWith("- ")) {
+        if (isBullet) {
             // Epitaph guard (see the doc comment): the date must live in the line's trailing
             // parenthetical beside a commit reference, or the bullet is body text, not an entry.
             // Within the parenthetical the completion is the LAST dated verb, matching the heading
             // branch: a decomposition cross-reference ("decomposed from the sibling bug fixed
             // <date>, fixed <date>") precedes the entry's own completion record.
-            const tail = trailingParenthetical(line);
-            if (/\bcommits?\b/.test(tail))
-                date = pick(tail, dateRe);
+            const bulletTail = tail ?? "";
+            if (/\bcommits?\b/.test(bulletTail))
+                date = pick(bulletTail, dateRe);
         }
         else {
             date = pick(meta.text, dateRe);
         }
         if (date)
             dates.push(date);
+    });
+    return dates;
+}
+/** One walk over the entry starts inside a `## ` section's body lines, visiting each `### `
+ * heading or `- ` bullet line in order. An entry start is a line that begins `### ` or `- `
+ * (any other line is body content, skipped); `meta` is headingMetadata's join of the entry's
+ * metadata, `tail` is a bullet's trailing `(…)` parenthetical (null for a heading), and
+ * `isBullet` tells which shape it is. Advances past each entry's metadata by
+ * headingMetadata.next, so a later entry cannot scan the earlier one's continuation as body.
+ * Shared by entryDates and entryLags, whose date readings branch on the same `### `/`- `
+ * shape, so the two walks stay in lockstep. */
+function eachEntryStart(lines, visit) {
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (!line.startsWith("### ") && !line.startsWith("- "))
+            continue;
+        const meta = headingMetadata(lines, i);
+        const isBullet = line.startsWith("- ");
+        visit({ isBullet, meta, tail: isBullet ? trailingParenthetical(line) : null });
         i = meta.next - 1; // The loop's ++ resumes at the first line not consumed as metadata.
     }
-    return dates;
 }
 /** The filing-to-done span of each finished entry inside one `## <sectionTitle>` section,
  * paired with the day it completed on: `{ done, lagDays }` for every entry `entryDates` counts
@@ -287,22 +301,18 @@ export function entryDates(md, sectionTitle, dateRe, first = false) {
 export function entryLags(md, sectionTitle, dateRe, filingRe) {
     const lags = [];
     const lines = sectionBodyLines(md, sectionTitle);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? "";
-        if (!line.startsWith("### ") && !line.startsWith("- "))
-            continue;
-        const meta = headingMetadata(lines, i);
+    eachEntryStart(lines, ({ isBullet, meta, tail }) => {
         let done = null;
         let filed = null;
-        if (line.startsWith("- ")) {
+        if (isBullet) {
             // Same epitaph guard as entryDates: the completion must live in the trailing
             // parenthetical beside a commit reference, and the filing read follows the same
             // rule — sectionFilingDates matches the first stamp inside that same parenthetical
             // for a `- ` bullet, so a description-date mention before it must not pair.
-            const tail = trailingParenthetical(line);
-            if (/\bcommits?\b/.test(tail)) {
-                done = lastDate(tail, dateRe);
-                filed = firstDate(tail, filingRe);
+            const bulletTail = tail ?? "";
+            if (/\bcommits?\b/.test(bulletTail)) {
+                done = lastDate(bulletTail, dateRe);
+                filed = firstDate(bulletTail, filingRe);
             }
         }
         else {
@@ -314,8 +324,7 @@ export function entryLags(md, sectionTitle, dateRe, filingRe) {
             if (lagDays >= 0)
                 lags.push({ done, lagDays });
         }
-        i = meta.next - 1; // The loop's ++ resumes at the first line not consumed as metadata.
-    }
+    });
     return lags;
 }
 /** A `### `/`- ` entry start's METADATA, joined for matching: the start line plus, for `### `
@@ -407,10 +416,12 @@ export function lastDate(text, dateRe) {
  * the filing onto a later day. This is the same first-match the canonical `filingDate`
  * (backlog.ts) applies to a heading line, so the filing read and `plan|bug --list`'s age agree
  * about when an entry opened. dateRe is cloned with the g flag so matchAll sees every date; a
- * text with no date yields null. Module-local: entryDates (its only caller) selects it with
- * `first`, so the walker stays single-homed like lastDate's completion rule (entryLags reads
- * it directly for an entry's filing stamp). */
-function firstDate(text, dateRe) {
+ * text with no date yields null. Exported so the heading stamp parsers that apply the same
+ * filing rule to a single title line — `filingDate` (backlog.ts) and `questionFilingDate`
+ * (question-answer.ts) — share the one first-match mechanism instead of re-stating it;
+ * entryDates selects it with `first`, so the walker stays single-homed like lastDate's
+ * completion rule. */
+export function firstDate(text, dateRe) {
     const global = new RegExp(dateRe.source, dateRe.flags.includes("g") ? dateRe.flags : `${dateRe.flags}g`);
     const match = global.exec(text);
     return match?.[1] ?? null;

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

@@ -1,11 +1,11 @@
 /** The hold-lifting and reordering writes of `tumwater bug|plan --release <n>` and `--top <n>`:
- * lift an entry's Refused, Waiting-for-the-next-failure, or held-for-operator note, or move
+ * lift an entry's Refused or held-for-operator note, or move
  * it to the head of its open
  * section. Each comes as an exiting writer (the CLI) and a non-exiting `try…` core that refuses as
  * data (the TUI and dashboard); entry lookup and the section's file target are
  * backlog-write.ts's. */
 import { backlogTarget, findEntry, locateDashboardEntry, readEntryLines } from "./backlog-write.js";
-import { withoutHeldForOperatorNotes, withoutRefusalNotes, withoutWaitingNotes } from "./backlog-eligibility.js";
+import { withoutHeldForOperatorNotes, withoutRefusalNotes } from "./backlog-eligibility.js";
 import { writeTextAtomic } from "../files/files.js";
 import { fail } from "../cli/cli-output.js";
 import { trimTrailingBlankLines } from "../text/text.js";
@@ -15,29 +15,21 @@ import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
 export function liftedNotePhrase(lifted) {
     return lifted === "refused"
         ? "the Refused note"
-        : lifted === "waiting-for-failure"
-            ? "the Waiting-for-the-next-failure note"
-            : "the held-for-operator note"; // vocabulary-ok: the held-for-operator note's release wording
+        : "the held-for-operator note"; // vocabulary-ok: the held-for-operator note's release wording
 }
 /** Drop the Refused note from `entry`'s slice of `lines`, in place, and return its kind; an
- * entry with none loses its Waiting-for-the-next-failure note instead, and one with neither
- * loses its held-for-operator Needs-review/Needs-replan note (the `(held N)` count at/above
+ * entry with none loses its held-for-operator Needs-review note (the `(held N)` count at/above
  * threshold, plus its **Previously held N** line). Null (and `lines` untouched) when the entry
- * carries none of the three, shared by releaseEntry and tryReleaseEntry so they cannot drift. */
+ * carries neither, shared by releaseEntry and tryReleaseEntry so they cannot drift. */
 function liftRefusal(lines, entry) {
     const slice = lines.slice(entry.start - 1, entry.end);
     let kept = withoutRefusalNotes(slice);
     if (kept.length === slice.length) {
-        kept = withoutWaitingNotes(slice);
-        if (kept.length === slice.length) {
-            kept = withoutHeldForOperatorNotes(slice);
-            if (kept.length === slice.length)
-                return null;
-            lines.splice(entry.start - 1, slice.length, ...kept);
-            return "held-for-operator"; // vocabulary-ok: the held-for-operator note's release wording
-        }
+        kept = withoutHeldForOperatorNotes(slice);
+        if (kept.length === slice.length)
+            return null;
         lines.splice(entry.start - 1, slice.length, ...kept);
-        return "waiting-for-failure";
+        return "held-for-operator"; // vocabulary-ok: the held-for-operator note's release wording
     }
     lines.splice(entry.start - 1, slice.length, ...kept);
     return "refused";
@@ -59,7 +51,7 @@ export function tryReleaseEntry(root, kind, n, expectedTitle) {
         return { status: "released", file: fileName, title: entry.title, lifted };
     });
 }
-/** Lift the Refused, Waiting for the next failure, or held-for-operator note from the
+/** Lift the Refused or held-for-operator note from the
  * `n`th entry (1-based, as `--list` numbers them) of the kind's open section and write the
  * file, under the same lock the cancel and edit writers hold, returning which hold it lifted.
  * An out-of-range position fails with locateEntry's wording; an entry with neither note
@@ -70,7 +62,7 @@ export function releaseEntry(root, kind, n) {
         const { file, lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
         const lifted = liftRefusal(lines, entry);
         if (lifted === null)
-            fail(`${kind} #${n} "${entry.title}" carries no Refused, Waiting for the next failure, or held-for-operator note`); // vocabulary-ok: the held-for-operator note's release wording
+            fail(`${kind} #${n} "${entry.title}" carries no Refused or held-for-operator note`); // vocabulary-ok: the held-for-operator note's release wording
         writeTextAtomic(file, lines.join("\n"));
         return { file: fileName, title: entry.title, lifted };
     });

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

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { increment } from "../collections.js";
 import { readTextOrNull } from "../files/files.js";
@@ -251,7 +252,19 @@ export async function backlogStructureReason(wt, mainBranch, files) {
     const baseRev = await changeBaseRev(wt, mainBranch);
     for (const file of touched) {
         // A deleted file reads as empty: every heading the base had is gone — rule (b).
-        const head = readTextOrNull(path.join(wt, file)) ?? "";
+        const full = path.join(wt, file);
+        // A symlink is never followed out of the worktree (it holds no heading of its own — the
+        // same lstat policy the backlog-conflict resolver and the false-fix guard pin, INV-G3), so
+        // it too reads as empty rather than bringing an arbitrary host file's headings into this
+        // gate's verdict.
+        let head = "";
+        try {
+            if (fs.lstatSync(full).isFile())
+                head = readTextOrNull(full) ?? "";
+        }
+        catch {
+            head = "";
+        }
         const base = await fileContentAt(wt, baseRev, file);
         const headCounts = sectionTitleCounts(head);
         const baseCounts = sectionTitleCounts(base);

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

@@ -361,7 +361,7 @@ function appendOperatorEntry(root, fileName, template, sectionTitle, title, body
 }
 /** Append one tumwater-filed bug under BUGS.md's `## Open` with the heading as given (no operator
  * stamp), for a caller that already holds the primary-worktree lock and commits the file itself
- * (backlog-archive.ts's quarantine filing). Returns the heading line's title. */
+ * (backlog-file-bugs.ts's quarantine filing). Returns the heading line's title. */
 export function appendBugEntryLocked(root, title, body) {
     const t = collapseWhitespace(title);
     requireBodyStructurallySound(body, "filed");

package/dist/src/backlog/backlog.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { cachedTextByStat } from "../files/stat-cache.js";
-import { entryDates, entryLags, finishedArchiveOf, lastDate, parseEntryDetails } from "./backlog-md.js";
+import { entryDates, entryLags, finishedArchiveOf, firstDate, lastDate, parseEntryDetails } from "./backlog-md.js";
 import { CHECK_DECLARATION_MARKER } from "../roles/role-guidance.js";
 /** The stat-cached file readers of the project backlog data shown on both dashboards: planned
  * features (PLANS.md), open bugs (BUGS.md), and open questions (QUESTIONS.md). These are tracked
@@ -79,11 +79,12 @@ export function sectionCompletionLags(root, fileName, sectionTitle, dateRe) {
  * bugs with `(found by …)` or `(reported …)`), parsed so `plan|bug --list` shows how long an entry
  * has waited, without opening the file. Read only the title — the whole heading, never the body,
  * because the stamp is the entry's own and the body may name other dates.
- * null when the heading carries no such clause. */
+ * null when the heading carries no such clause. Routed through backlog-md.ts's firstDate -
+ * the one first-match mechanism - with this module's own stamp regex.
+ * questionFilingDate (question-answer.ts) is the same recipe for the `asked by` verb. */
 const STAMP_DATE_RE = /(?:planned|reported|found by)\b[^)]*?\b(\d{4}-\d{2}-\d{2})/;
 export function filingDate(title) {
-    const m = STAMP_DATE_RE.exec(title);
-    return m ? m[1] : null;
+    return firstDate(title, STAMP_DATE_RE);
 }
 /** The completion stamp of a `## Done` plan heading. */
 export const DONE_DATE_RE = /done (\d{4}-\d{2}-\d{2})/;