tumwater 0.4.2 → 0.4.4

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

@@ -3,8 +3,8 @@ import { daysBetween } from "../text/datetime.js";
  * QUESTIONS.md text, with no filesystem access — every function here takes the markdown text as
  * an argument. Split from src/backlog/backlog.ts, which keeps the stat-cached file readers
  * (sectionEntries, the root-based plannedPlans/openBugs/openQuestions family, and the
- * Done/Fixed date scan): consumers who only parse markdown (question-answer.ts's QUESTIONS.md
- * walks, backlog-write.ts's section appends, backlog-structure.ts's stranding checks)
+ * Done/Fixed date scan): consumers who only parse markdown (backlog-question-answer.ts's
+ * QUESTIONS.md walks, backlog-write.ts's section appends, backlog-structure.ts's stranding checks)
  * import from here without reaching the file/cache layer, and a caller who parses a string never
  * pays for a stat. Both layers share one fenceTracker state machine, so independent readers can
  * never disagree about what is body content. */
@@ -87,7 +87,7 @@ export function headingTitle(line, prefix) {
  * code block. The single home of the fence-aware heading guard (`!fenced.inside(line) &&
  * line.startsWith(prefix)` plus headingTitle) that every line-level reader of the backlog
  * docs repeats: sectionLines' section boundaries and parseEntryDetails' entry boundaries here,
- * and question-answer.ts's walks of QUESTIONS.md (the Open/Answered scan, the `### ` block
+ * and backlog-question-answer.ts's walks of QUESTIONS.md (the Open/Answered scan, the `### ` block
  * split, and the Answered section's start); that file's two pure next-`## ` boundary walks
  * go through nextSectionHeading below instead. Readers that walk
  * whole documents collecting heading lines go through fenceAwareHeadingLines instead; callers
@@ -120,7 +120,7 @@ export function sectionLines(md, sectionTitle) {
 /** The index of the next `## ` section heading at or after `from`, fence-aware through the
  * caller's `fenced` tracker — or `lines.length` when none follows. The section-end boundary
  * rule as an index, for readers that must cut or splice at the boundary rather than collect
- * its content (question-answer.ts cuts the Open section at its end and inserts a moved
+ * its content (backlog-question-answer.ts cuts the Open section at its end and inserts a moved
  * block before Answered's next `## `; backlog-write.ts cuts the section a filed entry is
  * appended to). Shares fencedHeadingTitle's guard with sectionLines, so
  * a boundary found here is the same boundary sectionLines would stop at. */
@@ -418,7 +418,7 @@ export function lastDate(text, dateRe) {
  * about when an entry opened. dateRe is cloned with the g flag so matchAll sees every date; a
  * 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;
+ * (backlog-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) {

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

@@ -16,25 +16,37 @@ function parseRef(chunk, fallbackSeries) {
     const m = /^(?:([\s\S]+?)\s+)?([0-9]+[a-z]?)\/(\d+)(?:\s*[–-]\s*(\d+)\/(\d+))?$/i.exec(text);
     if (m === null)
         return { refs: [], named: null };
-    let named = (m[1]?.trim() ?? "").replace(/\s+parts?$/i, "");
-    const series = named || fallbackSeries;
-    if (series === null || series === "")
-        return { refs: [], named: named || null };
+    const { named, series } = resolveRefSeries(m[1], fallbackSeries);
     const of = Number(m[3]);
-    const start = m[2].toLowerCase();
-    if (!Number.isInteger(of) || of < 1)
-        return { refs: [], named: named || null };
-    if (m[4] === undefined)
-        return { refs: [{ series, part: start, of }], named: named || null };
+    if (series === null || !Number.isInteger(of) || of < 1)
+        return { refs: [], named };
+    return { refs: refsFromMatch(series, of, m[2], m[4] ?? null), named };
+}
+/** Whichever series a ref chunk resolves to: a captured name with any trailing `parts`/`part`
+ * keyword dropped, or — for a bare `parts a/n` — the clause's last-named series (null when it
+ * named none, so a bare ref there resolves to nothing). */
+function resolveRefSeries(matchName, fallbackSeries) {
+    const named = (matchName?.trim() ?? "").replace(/\s+parts?$/i, "");
+    if (named !== "")
+        return { named, series: named };
+    return { named: null, series: fallbackSeries === "" ? null : fallbackSeries };
+}
+/** Build the resolved refs for a chunk whose regex matched: the one part, or an inclusive
+ * numeric range. The part token arrives verbatim (so `2a` survives); a range is numeric on
+ * both ends (the lettered parts never range) and expands to that many single refs. */
+function refsFromMatch(series, of, startText, toText) {
+    const start = startText.toLowerCase();
+    if (toText === null)
+        return [{ series, part: start, of }];
     // A range is numeric on both ends (the lettered parts never range); expand it inclusively.
     const from = Number(start);
-    const to = Number(m[4]);
+    const to = Number(toText);
     if (!Number.isInteger(from) || !Number.isInteger(to) || to < from)
-        return { refs: [], named: named || null };
+        return [];
     const parts = [];
     for (let p = from; p <= to; p++)
         parts.push({ series, part: String(p), of });
-    return { refs: parts, named: named || null };
+    return parts;
 }
 /** The stable identity of an entry heading: its `(planned …)`/`(done …)` stamp suffix
  * removed through the shared stripEntryStamp, whitespace collapsed, lowercased. Adding a
@@ -181,12 +193,45 @@ const MISWORDED_DEPENDENCY_RE = /\b(?:blocked by|blocked on|after|follows|depend
  * Refused and needs-review entries count like the rest, since their clauses still decide when
  * they unblock. */
 export function planDependencyProblems(planned, doneTitles) {
+    const known = dependencyKnownParts(planned, doneTitles);
+    const { nodes, dangling, unparsed, misworded } = dependencyEntryScan(planned, known);
+    return { cycle: firstDependencyCycle(nodes), dangling, unparsed, misworded };
+}
+/** The part keys that count as known for dangling checks: every still-planned entry's part plus
+ * every done title's part — a dangling ref is one no planned or done heading carries. */
+function dependencyKnownParts(planned, doneTitles) {
     const known = plannedPartKeys(planned);
     for (const t of doneTitles) {
         const part = seriesPart(t);
         if (part !== null)
             known.add(partKey(part.series, part.part));
     }
+    return known;
+}
+/** The misworded refs a still-planned `Series, part i/n:` entry contributes: the series-parts its
+ * trailing-or-open parenthetical names through a dependency verb with no requires clause holding
+ * them, each `title`+`ref` deduped against the refs already collected across the whole planned
+ * list (a duplicate title contributes one ref, not one per occurrence). */
+function miswordedDependencyRefs(entry, own, refs, plannedKeys, misworded) {
+    let meta = trailingParenthetical(entry.title);
+    if (meta === "")
+        meta = openParenthetical(entry.title);
+    const held = new Set(refs.map((ref) => partKey(ref.series, ref.part)));
+    for (const m of meta.matchAll(MISWORDED_DEPENDENCY_RE)) {
+        for (const ref of parseRef(m[1], own.series).refs) {
+            const key = partKey(ref.series, ref.part);
+            if (!plannedKeys.has(key) || held.has(key))
+                continue;
+            const name = `${ref.series} ${ref.part}/${ref.of}`;
+            if (!misworded.some((w) => w.title === entry.title && w.ref === name))
+                misworded.push({ title: entry.title, ref: name });
+        }
+    }
+}
+/** The one-pass scan over the planned entries: a clause that parses to no refs pushes its title to
+ * `unparsed`, a ref `known` does not carry lands in `dangling`, and each entry with a series part
+ * contributes its misworded refs and a graph node whose deps are its required parts' keys. */
+function dependencyEntryScan(planned, known) {
     const dangling = [];
     const unparsed = [];
     const misworded = [];
@@ -203,25 +248,18 @@ export function planDependencyProblems(planned, doneTitles) {
         const own = seriesPart(entry.title);
         if (own === null)
             continue;
-        let meta = trailingParenthetical(entry.title);
-        if (meta === "")
-            meta = openParenthetical(entry.title);
-        const held = new Set(refs.map((ref) => partKey(ref.series, ref.part)));
-        for (const m of meta.matchAll(MISWORDED_DEPENDENCY_RE)) {
-            for (const ref of parseRef(m[1], own.series).refs) {
-                const key = partKey(ref.series, ref.part);
-                if (!plannedKeys.has(key) || held.has(key))
-                    continue;
-                const name = `${ref.series} ${ref.part}/${ref.of}`;
-                if (!misworded.some((w) => w.title === entry.title && w.ref === name))
-                    misworded.push({ title: entry.title, ref: name });
-            }
-        }
+        miswordedDependencyRefs(entry, own, refs, plannedKeys, misworded);
         nodes.set(partKey(own.series, own.part), {
             name: `${own.series} ${own.part}/${own.of}`,
             deps: refs.map((ref) => partKey(ref.series, ref.part)),
         });
     }
+    return { nodes, dangling, unparsed, misworded };
+}
+/** The first dependency cycle the depth-first walk finds, as `Series i/n` names in walk order with
+ * the first name repeated last (a self-reference is a one-hop cycle), or null when the graph is
+ * acyclic. The `open`/`done` state map and the walk order decide which cycle reports first. */
+function firstDependencyCycle(nodes) {
     const state = new Map();
     const stack = [];
     const visit = (key) => {
@@ -252,7 +290,7 @@ export function planDependencyProblems(planned, doneTitles) {
         if (cycle !== null)
             break;
     }
-    return { cycle, dangling, unparsed, misworded };
+    return cycle;
 }
 /** The prerequisite refs of `title`'s `requires … landed` clause when none of them is still in
  * `plannedParts` (built by plannedPartKeys), else []. A heading with no parseable clause is never

package/dist/src/backlog/{question-answer.js → backlog-question-answer.js}

@@ -7,7 +7,7 @@
  * output helpers, so every surface can drive it without ending the process.
  *
  * Shared by every read/answer surface: the CLI's `tumwater questions` command body wraps it in
- * src/cli/question-commands.ts (the say/fail/editor layer), while the TUI's answer box
+ * src/cli/cli-question-commands.ts (the say/fail/editor layer), while the TUI's answer box
  * (src/ui/tui/tui-keys.ts) and the dashboard's POST route (src/gui/gui-endpoint-commands.ts)
  * import the non-exiting answer core directly. It lives with the rest of the BUGS/PLANS/QUESTIONS
  * markdown (src/backlog/), not under src/cli/, so the non-command surfaces never depend on the

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

@@ -1,35 +1,35 @@
 /** The hold-lifting and reordering writes of `tumwater bug|plan --release <n>` and `--top <n>`:
- * lift an entry's Refused or held-for-operator note, or move
+ * lift an entry's Refused or Needs-review 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 } from "./backlog-eligibility.js";
+import { withoutNeedsReviewNotes, 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";
-/** The prose naming the note `lifted` kind a release removed, shared by the CLI, TUI and the
- * exit-announcers so their released lines cannot drift. */
+/** The prose naming the note kind a release removed — plural, since a release lifts every line
+ * of the chosen kind — shared by the CLI, TUI and the exit-announcers so their released lines
+ * cannot drift. */
 export function liftedNotePhrase(lifted) {
     return lifted === "refused"
-        ? "the Refused note"
-        : "the held-for-operator note"; // vocabulary-ok: the held-for-operator note's release wording
+        ? "the Refused notes"
+        : "the Needs review notes";
 }
 /** Drop the Refused note from `entry`'s slice of `lines`, in place, and return its kind; an
- * 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
+ * entry with none loses its Needs-review note. Null (and `lines` untouched) when the entry
  * 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 = withoutHeldForOperatorNotes(slice);
+        kept = withoutNeedsReviewNotes(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
+        return "needs-review";
     }
     lines.splice(entry.start - 1, slice.length, ...kept);
     return "refused";
@@ -51,7 +51,7 @@ export function tryReleaseEntry(root, kind, n, expectedTitle) {
         return { status: "released", file: fileName, title: entry.title, lifted };
     });
 }
-/** Lift the Refused or held-for-operator note from the
+/** Lift the Refused or Needs-review 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
@@ -62,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 or held-for-operator note`); // vocabulary-ok: the held-for-operator note's release wording
+            fail(`${kind} #${n} "${entry.title}" carries no Refused or Needs review note`);
         writeTextAtomic(file, lines.join("\n"));
         return { file: fileName, title: entry.title, lifted };
     });

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

@@ -215,6 +215,113 @@ export function doubleBlockFixedEntries(md) {
     }
     return found;
 }
+/** The duplicate-heading rule (a): the first `## ` title `head` carries more of than `base` did,
+ * or undefined when none. A base that already carries a duplicate never blocks unrelated edits —
+ * this fires only when the head's count EXCEEDS the base's, so a change that removes a duplicate
+ * always passes. */
+function duplicateSectionReason(file, headCounts, baseCounts) {
+    for (const [title, count] of headCounts)
+        if (count > 1 && count > (baseCounts.get(title) ?? 0))
+            return (`${file} adds another "## ${title}" heading — readers take the first section of a ` +
+                `name, so anything under the duplicate is invisible; keep one "## ${title}" per file`);
+    return undefined;
+}
+/** The dropped-known-section rule (b): the first `## ` title the base carried but `head` dropped,
+ * restricted to this file's KNOWN_SECTIONS, or undefined when none. A `## ` title that is not one
+ * of this file's known sections is not load-bearing: ADDING one is a legitimate project extension
+ * (this repo grew `## Verified`, a doc-only stack can grow `## Notes`), so a new one passes — but
+ * DROPPING one is the repair for a misplaced heading, so this rule guards only known sections and
+ * leaves an unknown one free to be demoted to `### ` under a known section (BUGS.md 2026-10-23). */
+function droppedSectionReason(file, headCounts, baseCounts) {
+    // A `## ` title that is not one of this file's known sections (KNOWN_SECTIONS) is not
+    // load-bearing: ADDING one is a legitimate project extension (this repo grew `## Verified`,
+    // a doc-only stack can grow `## Notes`), so a new one passes — but DROPPING one is the repair
+    // for a misplaced heading, so rule (b) guards only known sections and leaves an unknown one
+    // free to be demoted to `### ` under a known section (BUGS.md 2026-10-23).
+    const known = KNOWN_SECTIONS[file] ?? [];
+    for (const title of baseCounts.keys())
+        if (!headCounts.has(title) && known.includes(title))
+            return (`${file} drops the "## ${title}" section the base had — entries filed under it would ` +
+                `be invisible to every section reader; restore "## ${title}"`);
+    return undefined;
+}
+/** The re-added-archive-heading rule: for PLANS.md's and BUGS.md's archives only, rejects a head
+ * that adds a copy of a `### ` heading the base archive already carries (readdedHeadings) —
+ * finished history pasted back, never a new finished entry — or undefined for every other file.
+ * An archive only grows by new headings: a copy of one the base archive already carries is
+ * finished history pasted back (readdedHeadings), never a new finished entry.
+ */
+function readdedHeadingReason(file, base, head) {
+    if (file === PLANS_ARCHIVE || file === BUGS_ARCHIVE) {
+        const readded = readdedHeadings(base, head);
+        if (readded.length > 0)
+            return (`${file} adds ${plural(readded.length, '"### " heading', '"### " headings')} it already carries ` +
+                `(first: "${truncate(readded[0], 160)}") — the archive holds each finished entry once, so the ` +
+                `copies duplicate its history; remove them, and edit an archived entry in place instead`);
+    }
+    return undefined;
+}
+/** The misplaced-plan rule (part 4/4), for PLANS.md and its archive only, else undefined: rejects
+ * a head that ADDS a `### ` entry directly under `## Done` whose joined heading metadata carries
+ * `(planned YYYY-MM-DD` but no `done YYYY-MM-DD`, and whose key the base's PLANS.md and archive
+ * never carried in ANY section — a plan filed into the wrong section. strandedPlanEntries already
+ * does the fence-aware, joined-metadata reading the first two conditions need; the base's key set
+ * — over both files, since tumwater moves a finished plan from one to the other
+ * (plans/backlog-archive.md) — supplies the third. Judged against the merge-base (the same base
+ * the heading rules use), so a Planned → Done move of an entry the base already had passes and a
+ * pre-existing stranded entry (whose key the base has) never blocks unrelated merges. */
+async function misplacedPlanReason(file, wt, baseRev, base, head) {
+    // Part 4/4's rule, PLANS.md and its archive (see this function's doc comment): a NEW plan
+    // filed directly under ## Done with no done date. strandedPlanEntries already does the
+    // fence-aware, joined-metadata reading the first two conditions need; the base's key set —
+    // over both files, since tumwater moves a finished plan from one to the other
+    // (plans/backlog-archive.md) — supplies the third.
+    if (file === "PLANS.md" || file === PLANS_ARCHIVE) {
+        const baseKeys = new Set([
+            ...planHeadingKeys(file === "PLANS.md" ? base : await fileContentAt(wt, baseRev, "PLANS.md")),
+            ...planHeadingKeys(file === PLANS_ARCHIVE ? base : await fileContentAt(wt, baseRev, PLANS_ARCHIVE)),
+        ]);
+        const newcomer = strandedPlanEntries(head).find((e) => e.section === "Done" && !baseKeys.has(planHeadingKey(e.title)));
+        if (newcomer)
+            // The fault and its fix differ by file: in PLANS.md a NEW plan (the base never carried
+            // it in any section) was pasted under ## Done unfinished and belongs under ## Planned;
+            // in the archive the same heading is a finished plan the commit-time sweep already moved
+            // here, whose only fault is a missing `done YYYY-MM-DD` token — telling its author to
+            // "file it under ## Planned" is the opposite of the fix and wastes a revision.
+            return file === PLANS_ARCHIVE
+                ? `${file} files "${newcomer.title}" directly under "## Done" with no done date — the ` +
+                    `entry is finished and archived, so the only fix is to add \`done YYYY-MM-DD\` to its ` +
+                    `"### " heading; do not move it back under "## Planned"`
+                : `${file} files "${newcomer.title}" directly under "## Done" with no done date — a plan ` +
+                    `written into the done section is invisible to every Planned reader; file it under ` +
+                    `"## Planned" instead`;
+    }
+    return undefined;
+}
+/** The hidden-fixed-record rule, for BUGS.md and its archive only, else undefined: rejects a head
+ * whose multi-block `## Fixed` entries (doubleBlockFixedEntries) the base did not carry — a new
+ * headingless record merged into a neighbor's body — or undefined when none. A new headingless
+ * record cannot hide in a Fixed entry's body: reject a head whose multi-block entries the base did
+ * not carry (an existing one never blocks unrelated edits, matching the heading-set rules above).
+ * The Fix paragraph is the guard's unit, so a merged second block would otherwise sit inside the
+ * neighbor it was symbol-checked against. BUGS-FIXED.md holds the same entries once archived.
+ */
+function hiddenFixedRecordReason(file, base, head) {
+    // A new headingless record cannot hide in a Fixed entry's body: reject a head whose
+    // multi-block entries the base did not carry (an existing one never blocks unrelated
+    // edits, matching the heading-set rules above). The Fix paragraph is the guard's unit, so
+    // a merged second block would otherwise sit inside the neighbor it was symbol-checked
+    // against. BUGS-FIXED.md holds the same entries once archived.
+    if (file === "BUGS.md" || file === BUGS_ARCHIVE) {
+        const baseTitles = new Set(doubleBlockFixedEntries(base));
+        const newcomer = doubleBlockFixedEntries(head).find((title) => !baseTitles.has(title));
+        if (newcomer)
+            return (`${file}'s Fixed entry "${newcomer}" holds more than one **Symptom:**/**Fix:** block — ` +
+                `a record with no "### " heading has merged into it, so the hidden record is invisible ` +
+                `to every section reader; give it its own "### " heading`);
+    }
+    return undefined;
+}
 /** The first structural fault a diff merging into `mainBranch` leaves in a backlog file, or
  * undefined when none: for each touched backlog file it compares the `## ` heading set of the tree
  * being merged (`wt`) against the diff's merge-base — the same base falseFixReason measures
@@ -268,67 +375,13 @@ export async function backlogStructureReason(wt, mainBranch, files) {
         const base = await fileContentAt(wt, baseRev, file);
         const headCounts = sectionTitleCounts(head);
         const baseCounts = sectionTitleCounts(base);
-        for (const [title, count] of headCounts)
-            if (count > 1 && count > (baseCounts.get(title) ?? 0))
-                return (`${file} adds another "## ${title}" heading — readers take the first section of a ` +
-                    `name, so anything under the duplicate is invisible; keep one "## ${title}" per file`);
-        // A `## ` title that is not one of this file's known sections (KNOWN_SECTIONS) is not
-        // load-bearing: ADDING one is a legitimate project extension (this repo grew `## Verified`,
-        // a doc-only stack can grow `## Notes`), so a new one passes — but DROPPING one is the repair
-        // for a misplaced heading, so rule (b) guards only known sections and leaves an unknown one
-        // free to be demoted to `### ` under a known section (BUGS.md 2026-10-23).
-        const known = KNOWN_SECTIONS[file] ?? [];
-        for (const title of baseCounts.keys())
-            if (!headCounts.has(title) && known.includes(title))
-                return (`${file} drops the "## ${title}" section the base had — entries filed under it would ` +
-                    `be invisible to every section reader; restore "## ${title}"`);
-        // An archive only grows by new headings: a copy of one the base archive already carries is
-        // finished history pasted back (readdedHeadings), never a new finished entry.
-        if (file === PLANS_ARCHIVE || file === BUGS_ARCHIVE) {
-            const readded = readdedHeadings(base, head);
-            if (readded.length > 0)
-                return (`${file} adds ${plural(readded.length, '"### " heading', '"### " headings')} it already carries ` +
-                    `(first: "${truncate(readded[0], 160)}") — the archive holds each finished entry once, so the ` +
-                    `copies duplicate its history; remove them, and edit an archived entry in place instead`);
-        }
-        // Part 4/4's rule, PLANS.md and its archive (see this function's doc comment): a NEW plan
-        // filed directly under ## Done with no done date. strandedPlanEntries already does the
-        // fence-aware, joined-metadata reading the first two conditions need; the base's key set —
-        // over both files, since tumwater moves a finished plan from one to the other
-        // (plans/backlog-archive.md) — supplies the third.
-        if (file === "PLANS.md" || file === PLANS_ARCHIVE) {
-            const baseKeys = new Set([
-                ...planHeadingKeys(file === "PLANS.md" ? base : await fileContentAt(wt, baseRev, "PLANS.md")),
-                ...planHeadingKeys(file === PLANS_ARCHIVE ? base : await fileContentAt(wt, baseRev, PLANS_ARCHIVE)),
-            ]);
-            const newcomer = strandedPlanEntries(head).find((e) => e.section === "Done" && !baseKeys.has(planHeadingKey(e.title)));
-            if (newcomer)
-                // The fault and its fix differ by file: in PLANS.md a NEW plan (the base never carried
-                // it in any section) was pasted under ## Done unfinished and belongs under ## Planned;
-                // in the archive the same heading is a finished plan the commit-time sweep already moved
-                // here, whose only fault is a missing `done YYYY-MM-DD` token — telling its author to
-                // "file it under ## Planned" is the opposite of the fix and wastes a revision.
-                return file === PLANS_ARCHIVE
-                    ? `${file} files "${newcomer.title}" directly under "## Done" with no done date — the ` +
-                        `entry is finished and archived, so the only fix is to add \`done YYYY-MM-DD\` to its ` +
-                        `"### " heading; do not move it back under "## Planned"`
-                    : `${file} files "${newcomer.title}" directly under "## Done" with no done date — a plan ` +
-                        `written into the done section is invisible to every Planned reader; file it under ` +
-                        `"## Planned" instead`;
-        }
-        // A new headingless record cannot hide in a Fixed entry's body: reject a head whose
-        // multi-block entries the base did not carry (an existing one never blocks unrelated
-        // edits, matching the heading-set rules above). The Fix paragraph is the guard's unit, so
-        // a merged second block would otherwise sit inside the neighbor it was symbol-checked
-        // against. BUGS-FIXED.md holds the same entries once archived.
-        if (file === "BUGS.md" || file === BUGS_ARCHIVE) {
-            const baseTitles = new Set(doubleBlockFixedEntries(base));
-            const newcomer = doubleBlockFixedEntries(head).find((title) => !baseTitles.has(title));
-            if (newcomer)
-                return (`${file}'s Fixed entry "${newcomer}" holds more than one **Symptom:**/**Fix:** block — ` +
-                    `a record with no "### " heading has merged into it, so the hidden record is invisible ` +
-                    `to every section reader; give it its own "### " heading`);
-        }
+        const reason = duplicateSectionReason(file, headCounts, baseCounts) ??
+            droppedSectionReason(file, headCounts, baseCounts) ??
+            readdedHeadingReason(file, base, head) ??
+            (await misplacedPlanReason(file, wt, baseRev, base, head)) ??
+            hiddenFixedRecordReason(file, base, head);
+        if (reason !== undefined)
+            return reason;
     }
     return undefined;
 }

package/dist/src/backlog/backlog.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { cachedTextByStat } from "../files/stat-cache.js";
+import { DAY_MS } from "../text/datetime.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
@@ -81,7 +82,7 @@ export function sectionCompletionLags(root, fileName, sectionTitle, dateRe) {
  * because the stamp is the entry's own and the body may name other dates.
  * 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. */
+ * questionFilingDate (backlog-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) {
     return firstDate(title, STAMP_DATE_RE);
@@ -104,7 +105,7 @@ export function completionDate(title, dateRe) {
 /** Whole days between a filing stamp and `now`, floored at 0 so a future-dated entry reads as
  * fresh (0d) rather than negative. Shared by the suffix and the `--list --json` `ageDays` field. */
 export function ageInDays(since, now = Date.now()) {
-    return Math.max(0, Math.floor((now - Date.parse(since)) / 86400000));
+    return Math.max(0, Math.floor((now - Date.parse(since)) / DAY_MS));
 }
 /** The ` · since YYYY-MM-DD (Nd)`/`(today)` tail a listing line gains for its entry's filing
  * stamp — the one place the wording and the today/`Nd` choice live, so the plans/bugs list