tumwater 0.4.0 → 0.4.2

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

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

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

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

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

@@ -0,0 +1,159 @@
+/** The data half of the `<backlog-index>` block every role prompt carries: the 1-based line
+ * ranges each actionable entry occupies in its file (actionableEntryRanges/
+ * actionableEntryRangesFor) and the collapsed blocked-series rows
+ * (groupBlockedSeries/partsLabel) that back it. Extracted from backlog-structure.ts
+ * (organized 2026-10-25) so that module keeps only the backlog's structural-correctness checks
+ * (stranded plans, duplicate and readded headings, the new-plan-under-Done gate) and this one
+ * holds what the multiple index readers share — the role prompt's index block
+ * (backlog-index.ts), the eligibility and claims readers, the archive, write and release
+ * paths, and the status/tui surfaces all ask for the same section walk of the same file, so
+ * the stat-cached range walk (actionableEntryRangesFor) is the one shared helper. The walk
+ * and series grouping are pure markdown reading — no pi, no git. Rendering of the block
+ * lives in backlog-index.ts; this module holds only the data the surfaces share. */
+import path from "node:path";
+import { cachedTextByStat } from "../files/stat-cache.js";
+import { fenceTracker, headingTitle } from "./backlog-md.js";
+import { seriesPart } from "./backlog-parts.js";
+/** 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 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) 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-index.js

@@ -2,16 +2,18 @@
  * entry (PLANS.md ## Planned, BUGS.md ## Open, QUESTIONS.md ## Open) plus the newest closed
  * ones, each with the 1-based line range it occupies in its file — the bounded replacement for
  * the per-run `grep -n '^##'` heading map. The entry-range parsing (actionableEntryRanges) and
- * series collapsing (groupBlockedSeries, partsLabel) it builds on live in backlog-structure.ts
- * alongside the stranded-plan checks; this module holds only the block's rendering and its
- * per-file stat caches. Extracted from backlog-structure.ts (organized 2026-10-19) so that
- * module no longer carries a second responsibility. */
+ * series collapsing (groupBlockedSeries, partsLabel) it builds on live in
+ * backlog-index-data.ts; this module holds only the block's rendering and its per-file stat
+ * caches. Extracted from backlog-structure.ts (organized 2026-10-19, the data half split to
+ * backlog-index-data.ts 2026-10-25) so that module keeps only the backlog's structural
+ * checks. */
 import path from "node:path";
 import { cachedTextByStat } from "../files/stat-cache.js";
 import { FINISHED_ARCHIVES } from "./backlog-md.js";
 import { allLiveClaims } from "../runner/runner-state-load.js";
 import { collapseWhitespace, truncate } from "../text/text.js";
-import { actionableEntryRanges, groupBlockedSeries, partsLabel, stripEntryStamp, } from "./backlog-structure.js";
+import { actionableEntryRanges, groupBlockedSeries, partsLabel, } from "./backlog-index-data.js";
+import { stripEntryStamp } from "./backlog-structure.js";
 import { entryHoldAgainst, holdMark } from "./backlog-eligibility.js";
 import { plannedPartKeys } from "./backlog-parts.js";
 import { plannedPlanEntries } from "./backlog.js";