tumwater 0.1.2 → 0.2.0

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

@@ -1,16 +1,23 @@
+// vocabulary: plain
 /** Backlog eligibility: which PLANS.md / BUGS.md entries a work loop may take now (plans,
  * parallel-work-instances, part 2/7). An entry is held when its body carries a **Refused …**,
- * **Needs review …** or **Needs replan …** note, or when its heading's trailing parenthetical
- * names a prerequisite (`requires parts 1/5–3/5 landed`) that is itself still listed under
- * `## Planned`. The parsers are pure over markdown text; `eligibleEntries` is the stat-backed
- * reader for a caller that wants the list. The backlog index marks every held entry so a loop
+ * **Needs review …**, **Needs replan …** or **Waiting for the next failure …** 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
+ * markdown text; `eligibleEntries` is the stat-backed reader for a caller that wants the list.
+ * The backlog index marks every held entry so a loop
  * skips it without re-deriving the rule. */
+import path from "node:path";
+import { statOrNull } from "../files/files.js";
+import { allLiveClaims } from "../loop/loop-state.js";
 import { collapseWhitespace } from "../text/text.js";
-import { NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX } from "../roles/role-guidance.js";
+import { NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX, WAITING_FOR_FAILURE_PREFIX } from "../roles/role-guidance.js";
 import { baseRoleOf } from "../roles/loop-ids.js";
-import { trailingParenthetical } from "./backlog-md.js";
+import { roleLabel } from "../roles/role-labels.js";
+import { openParenthetical, trailingParenthetical } from "./backlog-md.js";
 import { actionableEntryRangesFor, stripEntryStamp } from "./backlog-structure.js";
-import { openBugEntries, plannedPlanEntries } from "./backlog.js";
+import { finishedFiles, openBugEntries, plannedPlanEntries } from "./backlog.js";
 /** The `**Refused …` note prefix a refusing tick writes. Every hold note — this one and the
  * imported Needs-review and Needs-replan prefixes — is matched as a line prefix (hasNoteLine)
  * so a mention in prose never holds an entry. */
@@ -21,6 +28,47 @@ const REFUSED_PREFIX = "**Refused ";
 function hasNoteLine(body, prefix) {
     return body.split("\n").some((line) => line.trimStart().startsWith(prefix));
 }
+/** The text of `body`'s note for `prefix`: the first line (ignoring leading indentation) that
+ * begins with it, trimmed, with the leading `**` and the first closing `**` removed. Null when
+ * no line matches — the same line-prefix rule entryHold uses. */
+function noteText(body, prefix) {
+    const line = body.split("\n").map((l) => l.trim()).find((l) => l.startsWith(prefix));
+    return line === undefined ? null : line.replace(/^\*\*/, "").replace("**", "");
+}
+/** The text of `body`'s Refused note, or null when it has none (entryHold's "refused" hold). */
+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);
+}
+/** `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,
+ * so releasing leaves one blank line where the note was. Every other line is kept. */
+function withoutNoteLines(lines, prefix) {
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trimStart().startsWith(prefix)) {
+            out.push(line);
+            continue;
+        }
+        if ((lines[i - 1] ?? "x").trim() === "" && (lines[i + 1] ?? "x").trim() === "")
+            i++;
+    }
+    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. */
+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);
+}
 /** One prerequisite ref, resolved against the entry's own series when it names none. */
 function parseRef(chunk, ownSeries) {
     const text = chunk.trim().replace(/^parts?\s+/i, "");
@@ -69,6 +117,53 @@ export function seriesPart(title) {
 function partKey(series, part) {
     return `${series.toLowerCase()}\u0000${part}`;
 }
+/** The Done entries of the parts `title` requires, in the order its requires clause names them:
+ * for each requiredParts ref, the first `## Done` entry whose seriesPart has the same partKey,
+ * searching PLANS.md's live section and then PLANS-DONE.md (plans/backlog-archive.md), each
+ * carrying the file it was found in. Done is newest-first, so the first match is the most recent
+ * merge. A ref with no Done match (still planned, or renamed) adds nothing, so a title with no
+ * requires clause, or missing files, gives []. Lets the assignment prompt point at the exact
+ * range to read instead of leaving the implementer to search a history that runs to thousands of
+ * lines. */
+export function mergedPrerequisiteRanges(root, title) {
+    const refs = requiredParts(title);
+    if (refs.length === 0)
+        return [];
+    const done = finishedFiles("PLANS.md").flatMap((file) => actionableEntryRangesFor(root, file, "Done").map((e) => ({ ...e, file })));
+    const out = [];
+    for (const ref of refs) {
+        const want = partKey(ref.series, ref.part);
+        const hit = done.find((e) => {
+            const part = seriesPart(e.title);
+            return part !== null && partKey(part.series, part.part) === want;
+        });
+        if (hit !== undefined) {
+            out.push({ key: entryKey(hit.title), title: hit.title, start: hit.start, end: hit.end, file: hit.file });
+        }
+    }
+    return out;
+}
+/** The still-planned parts that wait on the planned entry titled `title`, with their line ranges,
+ * in file order: plansWaitingOn's indexes (transitive, so a part waiting through a chain is
+ * listed) paired by index with the Planned ranges, as eligibleEntries pairs them. [] when no
+ * planned entry has that title, the entry has no series part, or PLANS.md is missing. Lets the
+ * assignment prompt name the work a series part must leave to the parts after it. */
+export function waitingPartRanges(root, title) {
+    const planned = plannedPlanEntries(root);
+    const ranges = actionableEntryRangesFor(root, "PLANS.md", "Planned");
+    const want = entryKey(title);
+    const index = planned.findIndex((e) => entryKey(e.title) === want);
+    if (index < 0 || seriesPart(planned[index].title) === null)
+        return [];
+    const out = [];
+    for (const i of plansWaitingOn(planned, index)) {
+        const range = ranges[i];
+        if (range === undefined)
+            continue;
+        out.push({ key: entryKey(planned[i].title), title: planned[i].title, start: range.start, end: range.end });
+    }
+    return out;
+}
 /** The prerequisite-set identities of the still-planned entries — seriesPart(title) of each,
  * keyed by partKey — built once for a batch and reused across every entry judged against it, so
  * judging n entries is n seriesPart parses rather than n² (entryHold rebuilt the set per entry).
@@ -83,29 +178,167 @@ export function plannedPartKeys(planned) {
     }
     return keys;
 }
-/** The prerequisite parts a plan heading's trailing parenthetical names through the clause
+/** The doctor's count of a refusal's stranded dependents: the ascending indexes into `planned` of
+ * the entries that require `planned[index]`'s own part, directly or through a chain of parts.
+ * Matching is by partKey, as entryHoldAgainst matches. [] when that entry has no series part. A
+ * dependency cycle ends the walk, and `index` itself is never listed. */
+export function plansWaitingOn(planned, index) {
+    const root = planned[index];
+    const own = root === undefined ? null : seriesPart(root.title);
+    if (own === null)
+        return [];
+    const dependents = new Map();
+    planned.forEach((entry, i) => {
+        if (seriesPart(entry.title) === null)
+            return;
+        for (const ref of requiredParts(entry.title)) {
+            const key = partKey(ref.series, ref.part);
+            dependents.set(key, [...(dependents.get(key) ?? []), i]);
+        }
+    });
+    const seen = new Set([index]);
+    const queue = [partKey(own.series, own.part)];
+    for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
+        for (const i of dependents.get(key) ?? []) {
+            if (seen.has(i))
+                continue;
+            seen.add(i);
+            const part = seriesPart(planned[i].title);
+            queue.push(partKey(part.series, part.part));
+        }
+    }
+    seen.delete(index);
+    return [...seen].sort((a, b) => a - b);
+}
+/** The prerequisite parts a plan heading's trailing parenthetical (or, when the heading wraps
+ * and the parenthetical stays open past the line, its open parenthetical) names through the clause
  * `requires <ref>((, | and )<ref>)* landed`, with each range (e.g. `parts 1/5–3/5`) expanded.
  * Returns [] when the heading has no such clause or the clause does not parse — an agent judges
  * an unparseable clause, exactly as it does today. Only the heading is read, never the body. */
 export function requiredParts(title) {
-    const meta = trailingParenthetical(title);
-    if (meta === "")
-        return [];
-    const m = /requires\s+(.+?)\s+landed\b/i.exec(meta);
-    if (m === null)
+    const clause = requiresClause(title);
+    if (clause === null)
         return [];
     const ownSeries = seriesPart(title)?.series ?? null;
     const refs = [];
-    for (const chunk of m[1].split(/\s*,\s*|\s+and\s+/i))
+    for (const chunk of clause.split(/\s*,\s*|\s+and\s+/i))
         refs.push(...parseRef(chunk, ownSeries));
     return refs;
 }
+/** The ref text a heading's `requires <refs> landed` clause captures — read from the trailing
+ * parenthetical, or the open one of a wrapped heading — or null when the heading has no such
+ * clause. requiredParts parses it; planDependencyProblems uses it to spot a clause that parses to
+ * nothing. */
+function requiresClause(title) {
+    let meta = trailingParenthetical(title);
+    if (meta === "")
+        meta = openParenthetical(title);
+    if (meta === "")
+        return null;
+    const m = /requires\s+(.+?)\s+landed\b/i.exec(meta); // vocabulary-ok: parses the requires … landed heading syntax
+    return m === null ? null : m[1];
+}
+/** A dependency verb followed by a series part ref in a heading's parenthetical — the wording the
+ * claim allocator ignores (BUGS.md 2026-10-14: a part headed "blocked by part 1/2 above" was handed
+ * out six times while part 1/2 was in flight). planDependencyProblems reports each such ref. */
+const MISWORDED_DEPENDENCY_RE = /\b(?:blocked by|blocked on|after|follows|depends on|waits on|waits for|once)\s+(?:the\s+)?(parts?\s+[0-9]+[a-z]?\/[0-9]+)/gi;
+/** The mistakes in the planned entries' `requires … landed` clauses that the claim allocator
+ * cannot see: `dangling` — a ref naming a part no planned or done heading carries (its hold is
+ * void), `unparsed` — titles whose clause yields no refs, and `cycle` — the first dependency cycle
+ * among planned `Series, part i/n:` entries as `Series i/n` names in walk order, first name
+ * repeated last (a self-reference is a one-hop cycle), or null — and `misworded`: a series part
+ * whose heading parenthetical names a still-planned part through a dependency verb ("blocked by
+ * part 1/2") with no requires clause holding that part, so the allocator hands it out now.
+ * Refused and needs-review entries count like the rest, since their clauses still decide when
+ * they unblock. */
+export function planDependencyProblems(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));
+    }
+    const dangling = [];
+    const unparsed = [];
+    const misworded = [];
+    const plannedKeys = plannedPartKeys(planned);
+    const nodes = new Map();
+    for (const entry of planned) {
+        const refs = requiredParts(entry.title);
+        if (refs.length === 0 && requiresClause(entry.title) !== null)
+            unparsed.push(entry.title);
+        for (const ref of refs) {
+            if (!known.has(partKey(ref.series, ref.part)))
+                dangling.push({ title: entry.title, ref: `${ref.series} ${ref.part}/${ref.of}` });
+        }
+        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)) {
+                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 });
+            }
+        }
+        nodes.set(partKey(own.series, own.part), {
+            name: `${own.series} ${own.part}/${own.of}`,
+            deps: refs.map((ref) => partKey(ref.series, ref.part)),
+        });
+    }
+    const state = new Map();
+    const stack = [];
+    const visit = (key) => {
+        state.set(key, "open");
+        stack.push(key);
+        for (const dep of nodes.get(key).deps) {
+            if (!nodes.has(dep))
+                continue;
+            const seen = state.get(dep);
+            if (seen === "open") {
+                return [...stack.slice(stack.indexOf(dep)), dep].map((k) => nodes.get(k).name);
+            }
+            if (seen === undefined) {
+                const found = visit(dep);
+                if (found !== null)
+                    return found;
+            }
+        }
+        stack.pop();
+        state.set(key, "done");
+        return null;
+    };
+    let cycle = null;
+    for (const key of nodes.keys()) {
+        if (state.has(key))
+            continue;
+        cycle = visit(key);
+        if (cycle !== null)
+            break;
+    }
+    return { cycle, dangling, unparsed, misworded };
+}
+/** 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
+ * reported, so only a refusal whose named prerequisites have all left `## Planned` reads as
+ * possibly stale. */
+export function prerequisitesMerged(title, plannedParts) {
+    const refs = requiredParts(title);
+    return refs.some((ref) => plannedParts.has(partKey(ref.series, ref.part))) ? [] : refs;
+}
 /** 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 loop owns it), 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
- * parenthetical. */
+ * Bodies mentioning "requires" are never consulted — only the heading's trailing or
+ * still-open parenthetical. */
 export function entryHold(entry, planned) {
     return entryHoldAgainst(entry, plannedPartKeys(planned));
 }
@@ -119,6 +352,8 @@ export function entryHoldAgainst(entry, plannedParts) {
         return "needs-review";
     if (hasNoteLine(entry.body, NEEDS_REPLAN_PREFIX))
         return "needs-replan";
+    if (hasNoteLine(entry.body, WAITING_FOR_FAILURE_PREFIX))
+        return "waiting-for-failure";
     const refs = requiredParts(entry.title);
     if (refs.length === 0)
         return null;
@@ -135,34 +370,110 @@ export function holdMark(hold) {
     if (hold === null)
         return "";
     if (hold === "refused")
-        return " [refused]";
+        return " [blocked: refused]";
     if (hold === "needs-review")
-        return " [needs review]";
+        return " [blocked: needs review]";
     if (hold === "needs-replan")
-        return " [needs replan]";
+        return " [blocked: needs replan]";
+    if (hold === "waiting-for-failure")
+        return " [blocked: waiting for the next failure]";
     return ` [blocked: requires ${hold.blockedBy.join(", ")}]`;
 }
-/** Why each entry the operator's `tumwater backlog` surfaces list is held, as two arrays
- * parallel to backlogPayload's `plans` and `bugs`: the same entryHold decision the prompt's
- * backlog index carries, so a hold is observable rather than inferred. The planned entries
- * are read once and reused as the prerequisite set. Questions carry no holds. */
-export function backlogHolds(root) {
-    const planned = plannedPlanEntries(root);
+/** `/api/status` polls the holds on the 1-second dashboard poll and the TUI recomputes them each
+ * frame while PLANS.md/BUGS.md change only when a loop merges an edit. The file reads beneath are
+ * already stat-cached (plannedPlanEntries/openBugEntries), but the per-entry eligibility walk
+ * (entryHoldAgainst's body scan + heading clause) is pure CPU re-derived on every call, growing
+ * with the append-only backlog. Cache the derived holds keyed on both files' stat identities — the
+ * same dev/ino/mtimeMs/size freshness check stat-cache.ts applies — so an unchanged backlog costs
+ * two stat syscalls per poll instead of the walk. Bounded (like sectionCache) so many short-lived
+ * roots in tests cannot grow it unbounded. */
+const HOLDS_CACHE_MAX = 64;
+const holdsCache = new Map();
+function holdsStatKey(root) {
+    const statId = (file) => {
+        const st = statOrNull(file);
+        return st === null ? "-" : `${st.dev}:${st.ino}:${st.mtimeMs}:${st.size}`;
+    };
+    return `${statId(path.join(root, "PLANS.md"))}\u0000${statId(path.join(root, "BUGS.md"))}`;
+}
+const cloneHold = (hold) => hold !== null && typeof hold === "object" ? { blockedBy: [...hold.blockedBy] } : hold;
+/** A copy of the holds so each caller owns its data, matching stat-cache's contract (mutating
+ * one result must not poison later polls). */
+function cloneHolds(holds) {
+    return { plans: holds.plans.map(cloneHold), bugs: holds.bugs.map(cloneHold) };
+}
+/** The two reader calls computeBacklogHolds derives from, grouped in one object — the one
+ * deliberate mock seam in this module. Both readers are themselves stat-cached, so a repeat
+ * poll's only cost is this per-entry walk; exposing them on an object lets a test count whether
+ * a poll re-runs the walk at all, which is the holds cache's observable win (a hit serves the
+ * cached derives without calling these). */
+export const holdsBacklogReaders = {
+    plannedPlanEntries,
+    openBugEntries,
+};
+/** The uncached derivation, shared by backlogHolds' miss path. */
+function computeBacklogHolds(root) {
+    const planned = holdsBacklogReaders.plannedPlanEntries(root);
     const parts = plannedPartKeys(planned);
     return {
         plans: planned.map((entry) => entryHoldAgainst(entry, parts)),
-        bugs: openBugEntries(root).map((entry) => entryHoldAgainst(entry, parts)),
+        bugs: holdsBacklogReaders.openBugEntries(root).map((entry) => entryHoldAgainst(entry, parts)),
     };
 }
-/** The eligibility mark (holdMark) for each planned plan and open bug, two arrays parallel
- * to the entries the observer surfaces list (backlogPayload's `plans`/`bugs`, the TUI's list
- * and entry modes): backlogHolds' verdicts projected through holdMark, so a surface derives
- * its marks from the one hold decision rather than re-walking the entries. holdMark renders
- * an eligible entry as the empty string, so a client can append the mark without a separate
- * eligibility check. Questions carry no holds. */
+export function backlogHolds(root) {
+    const key = holdsStatKey(root);
+    const hit = holdsCache.get(key);
+    if (hit !== undefined)
+        return cloneHolds(hit);
+    const value = computeBacklogHolds(root);
+    if (holdsCache.size >= HOLDS_CACHE_MAX)
+        holdsCache.clear();
+    holdsCache.set(key, value);
+    return cloneHolds(value);
+}
+/** The mark for each planned plan and open bug, two arrays parallel to the entries the
+ * observer surfaces list (backlogPayload's `plans`/`bugs`, the TUI's list and entry modes):
+ * the eligibility hold (holdMark) then the working-on-it mark (inProgressMark), the order
+ * `tumwater backlog` prints. A surface derives its marks from the one hold decision and the
+ * one claim lookup rather than re-walking the entries. An eligible entry nobody is working on
+ * renders as the empty string, so a client can append the mark without a separate check.
+ * Questions carry no holds. backlogHolds alone still drives the allocator. */
 export function backlogMarks(root) {
     const holds = backlogHolds(root);
-    return { plans: holds.plans.map(holdMark), bugs: holds.bugs.map(holdMark) };
+    const working = backlogInProgress(root);
+    const mark = (hold, runner) => holdMark(hold) + inProgressMark(runner ?? null);
+    return {
+        plans: holds.plans.map((h, i) => mark(h, working.plans[i])),
+        bugs: holds.bugs.map((h, i) => mark(h, working.bugs[i])),
+    };
+}
+/** The verbatim titles of the planned plans, then the open bugs, whose hold is `"refused"`, in
+ * file order: the entries that wait on an operator decision (the `refused` team alert's
+ * input). Pairs backlogHolds' arrays with the entries the same readers return, like
+ * backlogInProgress. A missing file yields `[]`. */
+export function refusedEntryTitles(root) {
+    const holds = backlogHolds(root);
+    const titlesOf = (entries, held) => entries.filter((_, i) => held[i] === "refused").map((e) => e.title);
+    return [
+        ...titlesOf(plannedPlanEntries(root), holds.plans),
+        ...titlesOf(openBugEntries(root), holds.bugs),
+    ];
+}
+/** The runner id holding a live claim on each planned plan and open bug, two arrays parallel
+ * to backlogHolds' (same readers, same order); `null` when no role is working on the entry.
+ * Keyed by entryKey alone, exactly as the backlog index's claim lookup is. */
+export function backlogInProgress(root) {
+    const claims = allLiveClaims(root);
+    const runnerOf = (entry) => claims.get(entryKey(entry.title)) ?? null;
+    return {
+        plans: plannedPlanEntries(root).map(runnerOf),
+        bugs: openBugEntries(root).map(runnerOf),
+    };
+}
+/** The heading mark for an entry a role is working on: empty when nobody is, else
+ * ` [working on it: feature #2]` (the runner id through roleLabel). */
+export function inProgressMark(runner) {
+    return runner === null ? "" : ` [working on it: ${roleLabel(runner)}]`;
 }
 /** The entries a `role` loop 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
@@ -178,11 +489,24 @@ export function eligibleEntries(root, role) {
     const ranges = actionableEntryRangesFor(root, file, section);
     const planned = plannedPlanEntries(root);
     const parts = plannedPartKeys(planned);
+    // The cross-role in-flight hold (BUGS.md 2026-10-09): an entry another role's base has
+    // claimed is not eligible here. Same-base claims are excluded from the hold — the scheduling
+    // pass's claim groups and tick-stage's staged claims already hold those — so the queried
+    // role's own claim (and a sibling instance's) stays eligible and its release rules are
+    // unchanged; only a plan another base currently owns is taken off this base's hands.
+    const ownBase = baseRoleOf(role);
+    const claimedElsewhere = new Set();
+    for (const [key, claimer] of allLiveClaims(root)) {
+        if (baseRoleOf(claimer) !== ownBase)
+            claimedElsewhere.add(key);
+    }
     const out = [];
     for (let i = 0; i < entries.length && i < ranges.length; i++) {
         const entry = entries[i];
         if (entryHoldAgainst(entry, parts) !== null)
             continue;
+        if (claimedElsewhere.has(entryKey(entry.title)))
+            continue;
         const range = ranges[i];
         out.push({
             key: entryKey(entry.title),

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

@@ -2,17 +2,36 @@
  * 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-commands.ts's QUESTIONS.md
+ * 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)
  * 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. */
+/** Where each live backlog file's finished entries go (plans/backlog-archive.md): PLANS.md's
+ * `## Done` empties into PLANS-DONE.md and BUGS.md's `## Fixed` into BUGS-FIXED.md, each under
+ * the same `## ` heading, newest first, so one section parser reads both files. The live file
+ * keeps the heading, empty: roles paste a finished entry there, and tumwater moves it into the
+ * archive (src/backlog/backlog-archive.ts). */
+export const FINISHED_ARCHIVES = [
+    { file: "PLANS.md", section: "Done", archive: "PLANS-DONE.md" },
+    { file: "BUGS.md", section: "Fixed", archive: "BUGS-FIXED.md" },
+];
+/** The archive row for a live backlog file. */
+export function finishedArchiveOf(file) {
+    return file === "PLANS.md" ? FINISHED_ARCHIVES[0] : FINISHED_ARCHIVES[1];
+}
 /** The repo-root backlog markdown files shared by every layer that knows them by name: the
  * tracked files loops edit and readers parse by `## ` section — read by backlog-structure.ts's
- * structural checks, landing/backlog-conflicts.ts's mechanical insert-conflict resolver, and
+ * structural checks, merge/backlog-conflicts.ts's mechanical insert-conflict resolver, and
  * doctor-backlog.ts's duplicate-heading check. One definition, so the three cannot disagree
- * about which files count. */
-export const BACKLOG_FILES = new Set(["PLANS.md", "BUGS.md", "QUESTIONS.md"]);
+ * 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'. */
+export const BACKLOG_FILES = new Set([
+    "PLANS.md",
+    "BUGS.md",
+    "QUESTIONS.md",
+    ...FINISHED_ARCHIVES.map((a) => a.archive),
+]);
 /** A per-line CommonMark fenced-code state machine, shared by every line-level parser of
  * backlog markdown. `inside(line)` feeds one line and returns whether it is fence syntax or
  * fenced content — never markdown structure: a fence opens at a ```` ``` ````/`~~~` line (an
@@ -67,7 +86,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-commands.ts's walks of QUESTIONS.md (the Open/Answered scan, the `### ` block
+ * and 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
@@ -100,7 +119,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-commands.ts cuts the Open section at its end and inserts a moved
+ * its content (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. */
@@ -148,6 +167,29 @@ export function fenceAwareHeadingLines(md, prefix) {
  * non-heading placeholders like `_None yet._` and any prose before the first heading, keeps
  * interior blank lines within a body while trimming leading/trailing ones, and ends an open
  * entry's body at EOF as well as at the next heading. */
+/** The `Validation gap` tag of one already-parsed entry body — the first line outside a fence
+ * matching `` **Validation gap:** <tag> `` (an optional `- ` bullet before the marker is
+ * allowed), the tag lowercased, or `null` when no such line exists. Fence-aware because a
+ * `## Fixed` body may quote the bug template (the case BUGS.md's "a fix narrative can land on
+ * main without its fix" entry records): a quoted `**Validation gap:**` line inside a fenced
+ * block is an example, not this entry's own trace, and must not count. The consumer that owns
+ * the closed tag vocabulary (the bugfix role guidance's VALIDATION_GAP_TAGS) validates the
+ * returned tag; this reader only records that a trace line exists and what it named. Walked
+ * line by line through the module's fenceTracker so this reader can never disagree with
+ * sectionLines/parseEntryDetails about what is fenced content. Returns the FIRST such line:
+ * a body with two validation-gap lines records the first (the tally counts an entry once). */
+export function validationGapTag(body) {
+    const fenced = fenceTracker();
+    const re = /^\s*(?:[-*]\s+)?\*\*Validation gap:\*\*\s*([A-Za-z][A-Za-z-]*)/;
+    for (const line of body.split("\n")) {
+        if (fenced.inside(line))
+            continue;
+        const m = re.exec(line);
+        if (m)
+            return m[1].toLowerCase();
+    }
+    return null;
+}
 export function parseEntryDetails(md, sectionTitle) {
     const entries = [];
     let title = null; // The open entry's heading (null = no entry open yet).
@@ -189,14 +231,20 @@ export function parseEntryDetails(md, sectionTitle) {
  *
  * A `- ` line needs more than a date to be an entry: the sections also hold body bullets (an
  * entry's repro steps, a plan's task breakdown), and a body bullet that merely mentions a
- * completion — "- same shape as the sibling bug (fixed 2026-09-24)" — is not one. The epitaph
- * shape separates them: an epitaph always closes its line with a parenthetical that records
- * both the completion date and the landing commit ("(planned …, done …; commit abc1234)"),
- * so a bullet counts only when its trailing `(…)` group carries the date AND a `commit`
- * reference; a heading entry keeps the plain metadata match (headings are the primary entry
- * format and always close their metadata parenthetical by convention). */
-export function entryDates(md, sectionTitle, dateRe) {
+ * completion — "- same shape as the sibling bug (fixed 2026-09-24)" — is not one. The epitaph shape
+ * separates them: an epitaph always closes its line with a parenthetical that records both the
+ * completion date and the merge commit ("(planned …, done …; commit abc1234)"), so a bullet counts
+ * only when its trailing `(…)` group carries the date AND a `commit` reference; a heading entry
+ * keeps the plain metadata match (headings are the primary entry format and always close their
+ * metadata parenthetical by convention).
+ *
+ * The LAST dated match is the completion rule when `first` is false (the default): found-by,
+ * decomposition, and sibling mentions precede the completion record, so a sibling's date must
+ * not steal the count. `first` selects the FIRST dated match instead — the filing rule the
+ * filing read uses, matching the canonical `filingDate` (via firstDate). */
+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] ?? "";
@@ -212,10 +260,10 @@ export function entryDates(md, sectionTitle, dateRe) {
             // <date>, fixed <date>") precedes the entry's own completion record.
             const tail = trailingParenthetical(line);
             if (/\bcommits?\b/.test(tail))
-                date = lastDate(tail, dateRe);
+                date = pick(tail, dateRe);
         }
         else {
-            date = lastDate(meta.text, dateRe);
+            date = pick(meta.text, dateRe);
         }
         if (date)
             dates.push(date);
@@ -262,7 +310,8 @@ export function headingMetadata(lines, start) {
  * and silently dropped the epitaph's date from the day report (BUGS.md 2026-09-29). Unbalanced
  * text (no matching open paren) yields "" — the guard then treats the bullet as body text, as
  * before. The one home for this rule: entryDates reads it for `- ` epitaphs and
- * backlog-eligibility.ts's requiredParts for a heading's prerequisite clause. */
+ * backlog-eligibility.ts's requiredParts for a heading's prerequisite clause (falling back to
+ * openParenthetical when the heading's parenthetical wraps past the line). */
 export function trailingParenthetical(line) {
     if (!line.endsWith(")"))
         return "";
@@ -276,14 +325,45 @@ export function trailingParenthetical(line) {
     }
     return "";
 }
+/** The text after the outermost "(" still open at the end of `line`, or "" when every group
+ * closes: a wrapped `### ` heading's stamp parenthetical continues on the following lines, so
+ * the heading line has no closing ")". A ")" at depth 0 is ignored. */
+export function openParenthetical(line) {
+    let depth = 0;
+    let open = -1;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "(") {
+            if (depth++ === 0)
+                open = i;
+        }
+        else if (ch === ")" && depth > 0)
+            depth--;
+    }
+    return depth > 0 ? line.slice(open + 1) : "";
+}
 /** A text's LAST `<dateRe>` capture — the completion rule both branches of entryDates share:
  * an entry's completion is its LAST dated verb, not the first, because found-by,
  * decomposition, and sibling mentions ("decomposed from the X bug fixed <date>") all precede
  * the completion record, so first-match let a sibling's date steal the entry's count onto the
- * wrong day (BUGS.md 2026-09-29). dateRe is cloned with the g flag so matchAll sees every
+ * wrong day (BUGS.md 2026-09-29). Also read by completionDate (backlog.ts) for the finished-entry
+ * listings. dateRe is cloned with the g flag so matchAll sees every
  * date; a text with no date yields null. */
-function lastDate(text, dateRe) {
+export function lastDate(text, dateRe) {
     const global = new RegExp(dateRe.source, dateRe.flags.includes("g") ? dateRe.flags : `${dateRe.flags}g`);
     const all = [...text.matchAll(global)];
     return all[all.length - 1]?.[1] ?? null;
 }
+/** A text's FIRST `<dateRe>` capture — the filing rule, the mirror of lastDate: an entry's
+ * filing month is its FIRST stamp verb, because a later re-filing or a cross-reference
+ * ("found by bugfix <date>; found by doctor <date>") records a later date that must not move
+ * 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. */
+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;
+}