tumwater 0.4.0 → 0.4.2

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

@@ -23,7 +23,7 @@ export function finishedArchiveOf(file) {
 }
 /** The repo-root backlog markdown files shared by every layer that knows them by name: the
  * tracked files roles edit and readers parse by `## ` section — read by backlog-structure.ts's
- * structural checks, merge/backlog-conflicts.ts's mechanical insert-conflict resolver, and
+ * structural checks, merge/merge-backlog-conflicts.ts's mechanical insert-conflict resolver, and
  * doctor-backlog-plans.ts's duplicate-heading check. One definition, so the three cannot disagree
  * about which files count. The archive files count too: merges insert at their top, and their
  * `## ` heading is as load-bearing as the live files'. */
@@ -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,13 +1,12 @@
 /** 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 path from "node:path";
-import { backlogTarget, findEntry, readEntryLines } from "./backlog-write.js";
-import { withoutHeldForOperatorNotes, withoutRefusalNotes, withoutWaitingNotes } from "./backlog-eligibility.js";
-import { readTextIfExists, writeTextAtomic } from "../files/files.js";
+import { backlogTarget, findEntry, locateDashboardEntry, readEntryLines } from "./backlog-write.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";
 import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
@@ -16,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";
@@ -48,13 +39,10 @@ function liftRefusal(lines, entry) {
 export function tryReleaseEntry(root, kind, n, expectedTitle) {
     const { fileName, sectionTitle } = backlogTarget(kind);
     return withPrimaryWorktreeLock(root, () => {
-        const file = path.join(root, fileName);
-        const md = readTextIfExists(file) ?? "";
-        const entry = findEntry(md, sectionTitle, n);
-        if (entry === undefined)
-            return { status: "gone" };
-        if (entry.title !== expectedTitle)
-            return { status: "moved", title: entry.title };
+        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
+        if (located.status !== "ok")
+            return located;
+        const { file, md, entry } = located;
         const lines = md.split("\n");
         const lifted = liftRefusal(lines, entry);
         if (lifted === null)
@@ -63,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
@@ -74,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 };
     });
@@ -117,13 +105,10 @@ function spliceEntryToTop(lines, sectionTitle, entry) {
 export function tryMoveEntryToTop(root, kind, n, expectedTitle) {
     const { fileName, sectionTitle } = backlogTarget(kind);
     return withPrimaryWorktreeLock(root, () => {
-        const file = path.join(root, fileName);
-        const md = readTextIfExists(file) ?? "";
-        const entry = findEntry(md, sectionTitle, n);
-        if (entry === undefined)
-            return { status: "gone" };
-        if (entry.title !== expectedTitle)
-            return { status: "moved", title: entry.title };
+        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
+        if (located.status !== "ok")
+            return located;
+        const { file, md, entry } = located;
         if (n === 1)
             return { status: "already_first", title: entry.title };
         const lines = md.split("\n");

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

@@ -1,5 +1,5 @@
 import { entryMatches } from "./backlog.js";
-import { groupBlockedSeries, partsLabel } from "./backlog-structure.js";
+import { groupBlockedSeries, partsLabel } from "./backlog-index-data.js";
 import { holdMark, inProgressMark } from "./backlog-eligibility.js";
 /** One `## ` section: its entries verbatim, or the single `_(none)_` placeholder line. When
  * `holds` is given, entry `i`'s hold mark rides on its `### ` heading. */

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";
@@ -6,7 +7,6 @@ import { BACKLOG_FILES, FINISHED_ARCHIVES, fenceTracker, headingMetadata, parseE
 import { changeBaseRev, fileContentAt } from "../git/git.js";
 import { plural } from "../text/phrases.js";
 import { collapseWhitespace, truncate } from "../text/text.js";
-import { seriesPart } from "./backlog-parts.js";
 /** The archive files of PLANS.md and BUGS.md (FINISHED_ARCHIVES). */
 const PLANS_ARCHIVE = FINISHED_ARCHIVES[0].archive;
 const BUGS_ARCHIVE = FINISHED_ARCHIVES[1].archive;
@@ -252,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);
@@ -356,146 +368,3 @@ the readers that scan one section, so no role sees them as backlog work:
 ${listed}
 </backlog-structure>`;
 }
-/** The entries under one `## <sectionTitle>` section with their 1-based line ranges, in file
- * order: the fence-aware walk sectionLines and parseEntryDetails share, carrying the line
- * numbers neither returns. An entry starts at a `### ` line and ends at the line before the
- * next `### ` or `## ` line (or EOF) — the same boundary parseEntryDetails closes bodies on —
- * so a role reading lines `start`..`end` sees exactly the entry's heading and body. A `## ` or
- * `### ` line inside a fenced code block is body content, never a boundary, through
- * backlog-md.ts's shared fenceTracker. */
-export function actionableEntryRanges(md, sectionTitle) {
-    const lines = md.split("\n");
-    const fenced = fenceTracker();
-    const entries = [];
-    let inSection = false;
-    let open = null;
-    // `end` is the 1-based number of the entry's last body line, i.e. the 0-based index of the
-    // next heading; at EOF it is the line count (the last 1-based line number).
-    const close = (end) => {
-        if (open !== null)
-            entries.push({ title: open.title, start: open.start, end });
-        open = null;
-    };
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? "";
-        if (fenced.inside(line))
-            continue;
-        if (line.startsWith("## ")) {
-            close(i);
-            inSection = headingTitle(line, "## ") === sectionTitle;
-        }
-        else if (inSection && line.startsWith("### ")) {
-            close(i);
-            open = { title: headingTitle(line, "### "), start: i + 1 };
-        }
-    }
-    // A document ending in a newline splits to a trailing "" element; the last real line is one
-    // less, so an entry running to EOF ends there instead of at the phantom line.
-    close(md.endsWith("\n") ? lines.length - 1 : lines.length);
-    return entries;
-}
-/** Per-file cache of a section's actionable ranges (actionableEntryRangesFor). */
-const actionableRangesCache = new Map();
-/** `actionableEntryRanges` for one backlog file, stat-cached per (file path, section title):
- * the per-poll and per-run readers (eligibility's eligibleEntries, claims' listedKeys) ask for
- * the same section of the same file every couple of seconds, and BUGS.md's closed history —
- * which the whole-file walk reads — grows without bound, so an unchanged file costs one stat
- * instead of a full read, split, and section walk. Keyed by file path so distinct roots never
- * collide, bounded inside cachedTextByStat. A missing or unreadable file reads as no ranges. The
- * result is copied out, so each caller owns its data. */
-export function actionableEntryRangesFor(root, file, sectionTitle) {
-    const full = path.join(root, file);
-    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
- * claim names it. Returns the row's series part when it collapses, else null. */
-function collapsibleSeriesPart(row) {
-    if (row.claimer !== undefined)
-        return null;
-    if (typeof row.hold !== "object" || row.hold === null)
-        return null;
-    return seriesPart(row.title);
-}
-/** The collapsed part list for a series' blocked parts: each part as `i/n`, with a run of
- * consecutive numeric parts (same total, adjacent values) joined into one en-dash range
- * (`2/5–5/5`) and each lettered part (`2a`) listed singly. */
-export function partsLabel(rows) {
-    const refs = rows.map((r) => seriesPart(r.title));
-    const pieces = [];
-    let start = null;
-    let prev = null;
-    const numeric = (p) => /^\d+$/.test(p);
-    const flush = () => {
-        if (start === null || prev === null)
-            return;
-        pieces.push(start.part === prev.part
-            ? `${start.part}/${start.of}`
-            : `${start.part}/${start.of}–${prev.part}/${prev.of}`);
-        start = null;
-        prev = null;
-    };
-    for (const ref of refs) {
-        if (prev !== null &&
-            numeric(ref.part) &&
-            numeric(prev.part) &&
-            Number(ref.part) === Number(prev.part) + 1 &&
-            ref.of === prev.of) {
-            prev = ref;
-            continue;
-        }
-        flush();
-        start = ref;
-        prev = ref;
-    }
-    flush();
-    return pieces.join(", ");
-}
-/** Renders `rows` to index lines, collapsing a multi-part series' blocked parts to one line per
- * series (this plan, "Compact backlog index, part 1/1"): a long series' chain of held parts would
- * otherwise fill every role prompt with lines no role can act on. An entry collapses when it is a
- * series part held only by an unmerged prerequisite and no live claim names it; a series with two
- * 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
- * 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,
- * hold and claimer: each series with two or more collapsible blocked parts becomes one `series`
- * group at its first part's place; every other row stays a `row` group in order. */
-export function groupBlockedSeries(rows) {
-    // Group the collapsible rows by series, keyed on the lowercased series name.
-    const bySeries = new Map();
-    for (const row of rows) {
-        const part = collapsibleSeriesPart(row);
-        if (part === null)
-            continue;
-        const key = part.series.toLowerCase();
-        const list = bySeries.get(key) ?? [];
-        list.push(row);
-        bySeries.set(key, list);
-    }
-    // Only a series with two or more blocked parts collapses; a lone blocked part keeps its
-    // exact `requires` line.
-    const collapse = new Set();
-    for (const [key, list] of bySeries)
-        if (list.length >= 2)
-            collapse.add(key);
-    const groups = [];
-    const skipped = new Set();
-    for (const row of rows) {
-        if (skipped.has(row))
-            continue;
-        const part = collapsibleSeriesPart(row);
-        if (part !== null && collapse.has(part.series.toLowerCase())) {
-            const group = bySeries.get(part.series.toLowerCase());
-            groups.push({ kind: "series", series: part.series, rows: group });
-            for (const g of group)
-                skipped.add(g);
-            continue;
-        }
-        groups.push({ kind: "row", row });
-    }
-    return groups;
-}

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

@@ -11,7 +11,8 @@
  * cli.ts beside the other command bodies. */
 import path from "node:path";
 import { fencedHeadingTitle, fenceTracker, headingMetadata, nextSectionHeading } from "./backlog-md.js";
-import { actionableEntryRanges, stripEntryStamp } from "./backlog-structure.js";
+import { actionableEntryRanges } from "./backlog-index-data.js";
+import { stripEntryStamp } from "./backlog-structure.js";
 import { readTextIfExists, writeTextAtomic } from "../files/files.js";
 import { formatDate } from "../text/datetime.js";
 import { fail } from "../cli/cli-output.js";
@@ -138,6 +139,24 @@ export function readEntryLines(root, fileName, sectionTitle, n) {
     const entry = locateEntry(md, fileName, sectionTitle, n);
     return { file, lines: md.split("\n"), entry };
 }
+/** The title-checked entry lookup the four non-exiting dashboard writers share
+ * (tryCancelEntry, tryEditEntry here; tryReleaseEntry, tryMoveEntryToTop in backlog-release.ts):
+ * resolve `<fileName>`, read it — an absent file is an empty section, never a seed — locate the
+ * `n`th actionable entry, and compare its heading to `expectedTitle`. Returns `gone` when there
+ * is no entry at the position and `moved` when a different heading sits there, so the caller can
+ * refuse as data without writing; on success returns the `ok` file path, raw markdown and entry
+ * for the caller to splice and write its own outcome. A pure lookup, decided inside the caller's
+ * lock. */
+export function locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle) {
+    const file = path.join(root, fileName);
+    const md = readTextIfExists(file) ?? "";
+    const entry = findEntry(md, sectionTitle, n);
+    if (entry === undefined)
+        return { status: "gone" };
+    if (entry.title !== expectedTitle)
+        return { status: "moved", title: entry.title };
+    return { status: "ok", file, md, entry };
+}
 /** The section-remove entry point, the appendEntry analogue: the same cross-process lock, so a
  * cancel and a merge's working-tree fast-forward cannot each clobber the other's
  * read-modify-write. */
@@ -145,7 +164,7 @@ function removeEntry(root, fileName, sectionTitle, n) {
     return withPrimaryWorktreeLock(root, () => removeEntryLocked(root, fileName, sectionTitle, n));
 }
 /** Remove the `n`th entry (1-based, as `tumwater backlog` lists it) from `<root>/<fileName>`'s
- * `## <sectionTitle>` section. The ranges come from actionableEntryRanges (backlog-structure.ts),
+ * `## <sectionTitle>` section. The ranges come from actionableEntryRanges (backlog-index-data.ts),
  * whose walk is fence-aware, so a `## `/`### ` line quoted inside an entry's code fence is body
  * text: slicing the range removes the heading and its body whole without mistaking a quoted line
  * for the boundary. An out-of-range position (an empty section, or one holding only the
@@ -171,13 +190,10 @@ function spliceOutEntry(file, lines, entry) {
 export function tryCancelEntry(root, kind, n, expectedTitle) {
     const { fileName, sectionTitle } = backlogTarget(kind);
     return withPrimaryWorktreeLock(root, () => {
-        const file = path.join(root, fileName);
-        const md = readTextIfExists(file) ?? "";
-        const entry = findEntry(md, sectionTitle, n);
-        if (entry === undefined)
-            return { status: "gone" };
-        if (entry.title !== expectedTitle)
-            return { status: "moved", title: entry.title };
+        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
+        if (located.status !== "ok")
+            return located;
+        const { file, md, entry } = located;
         spliceOutEntry(file, md.split("\n"), entry);
         return { status: "cancelled", file: fileName, title: entry.title };
     });
@@ -191,7 +207,7 @@ function editEntry(root, fileName, sectionTitle, n, title, body) {
 /** Replace the `n`th entry (1-based, as `tumwater backlog` lists it) of `<root>/<fileName>`'s
  * `## <sectionTitle>` section with `### <title><stamp>` plus `body`, in place: the entry keeps
  * its position and its original trailing stamp parenthetical. The ranges come from
- * actionableEntryRanges (backlog-structure.ts), whose fence-aware walk means a `## `/`### `
+ * actionableEntryRanges (backlog-index-data.ts), whose fence-aware walk means a `## `/`### `
  * line quoted inside an entry's code fence is body text, so the spliced range covers exactly
  * the heading and body without mistaking a quoted line for the boundary. The stamp is the
  * trailing suffix of the JOINED heading metadata (headingMetadata folds a wrapped heading onto
@@ -249,13 +265,10 @@ export function tryEditEntry(root, kind, n, expectedTitle, rawTitle, rawBody) {
     const title = stripEntryStamp(collapseWhitespace(rawTitle));
     const body = rawBody.replace(/\r\n?/g, "\n").trim();
     return withPrimaryWorktreeLock(root, () => {
-        const file = path.join(root, fileName);
-        const md = readTextIfExists(file) ?? "";
-        const entry = findEntry(md, sectionTitle, n);
-        if (entry === undefined)
-            return { status: "gone" };
-        if (entry.title !== expectedTitle)
-            return { status: "moved", title: entry.title };
+        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
+        if (located.status !== "ok")
+            return located;
+        const { file, md, entry } = located;
         const wrote = spliceInEditedEntry(file, md.split("\n"), entry, title, body);
         return { status: wrote ? "edited" : "unchanged", file: fileName, title };
     });
@@ -348,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,7 @@
 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
  * markdown that roles edit, so readers must never show a stale entry — but the dashboards poll them
@@ -78,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})/;
@@ -168,6 +170,14 @@ export function openQuestions(root) {
 export function plannedPlanEntries(root) {
     return sectionEntries(root, "PLANS.md", "Planned");
 }
+/** The PLANS.md `## Planned` entry that declares this project's deterministic check — the one
+ * whose body carries CHECK_DECLARATION_MARKER (the plan role writes it under the no-check note's
+ * direction, src/prompt/gate-notes.ts buildNoCheckNote; the feature role reads it as its task).
+ * Null when no planned entry declares one, so a declaration already waiting is never
+ * double-planned and a feature run implements only a declaration the plan role actually wrote. */
+export function declarationPlanEntry(root) {
+    return plannedPlanEntries(root).find((e) => e.body.includes(CHECK_DECLARATION_MARKER)) ?? null;
+}
 /** Open bugs as full entries (title + body), in file order. Missing or unreadable → []. */
 export function openBugEntries(root) {
     return sectionEntries(root, "BUGS.md", "Open");