tumwater 0.2.0 → 0.3.0

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

@@ -1,3 +1,4 @@
+import { daysBetween } from "../text/datetime.js";
 /** The pure markdown layer of the backlog parsers: fence-aware reading of PLANS.md / BUGS.md /
  * 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
@@ -21,9 +22,9 @@ 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
+ * tracked files roles edit and readers parse by `## ` section — read by backlog-structure.ts's
  * structural checks, merge/backlog-conflicts.ts's mechanical insert-conflict resolver, and
- * doctor-backlog.ts's duplicate-heading check. One definition, so the three cannot disagree
+ * doctor-backlog-plans.ts's duplicate-heading check. One definition, so the three cannot disagree
  * about which files count. The archive files count too: merges insert at their top, and their
  * `## ` heading is as load-bearing as the live files'. */
 export const BACKLOG_FILES = new Set([
@@ -133,8 +134,9 @@ export function nextSectionHeading(lines, from, fenced) {
 /** The body lines of one `## <sectionTitle>` section with fenced content stripped: the
  * sectionLines walk, then a fresh fenceTracker's filter — the shape every reader that
  * classifies a section's lines as markdown structure (entry headings, bullets, dates) walks.
- * Exactly two call sites today: entryDates (below) and backlog-structure.ts's
- * strandedPlanEntries. The fresh tracker is in sync with the document here: sectionLines
+ * Exactly three call sites today: entryDates (below), backlog-structure.ts's
+ * strandedPlanEntries, and stage-backlog-checks.ts's placeholderSections. The fresh
+ * tracker is in sync with the document here: sectionLines
  * only recognizes a `## ` boundary outside a fence, so the section's heading line is
  * non-fenced and the fence state at the section's first line is closed — a tracker started
  * there sees exactly what a document-wide tracker sees inside the section. Readers that
@@ -271,6 +273,51 @@ export function entryDates(md, sectionTitle, dateRe, first = false) {
     }
     return dates;
 }
+/** The filing-to-done span of each finished entry inside one `## <sectionTitle>` section,
+ * paired with the day it completed on: `{ done, lagDays }` for every entry `entryDates` counts
+ * (`### ` headings and `- ` epitaphs whose trailing parenthetical carries a commit
+ * reference), an entry's `done` date being its LAST `dateRe` match and `filed` its FIRST
+ * `filingRe` match — the same completion/filing rules `entryDates`/`sectionFilingDates`
+ * apply (a `- ` epitaph reads both from its trailing parenthetical, exactly as entryDates
+ * does), so the report's lag read cannot disagree with the completion and filing reads about
+ * which date belongs to the entry. `filingRe` is a parameter so the backlog module's
+ * STAMP_DATE_RE keeps its one home; `dateRe` is cloned with the g flag (like lastDate) so
+ * matchAll sees every date. An entry with no filing stamp, or a filing later than its
+ * completion, contributes nothing. The span is whole calendar days via `daysBetween`. */
+export function entryLags(md, sectionTitle, dateRe, filingRe) {
+    const lags = [];
+    const lines = sectionBodyLines(md, sectionTitle);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (!line.startsWith("### ") && !line.startsWith("- "))
+            continue;
+        const meta = headingMetadata(lines, i);
+        let done = null;
+        let filed = null;
+        if (line.startsWith("- ")) {
+            // Same epitaph guard as entryDates: the completion must live in the trailing
+            // parenthetical beside a commit reference, and the filing read follows the same
+            // rule — sectionFilingDates matches the first stamp inside that same parenthetical
+            // for a `- ` bullet, so a description-date mention before it must not pair.
+            const tail = trailingParenthetical(line);
+            if (/\bcommits?\b/.test(tail)) {
+                done = lastDate(tail, dateRe);
+                filed = firstDate(tail, filingRe);
+            }
+        }
+        else {
+            done = lastDate(meta.text, dateRe);
+            filed = firstDate(meta.text, filingRe);
+        }
+        if (done !== null && filed !== null) {
+            const lagDays = daysBetween(filed, done);
+            if (lagDays >= 0)
+                lags.push({ done, lagDays });
+        }
+        i = meta.next - 1; // The loop's ++ resumes at the first line not consumed as metadata.
+    }
+    return lags;
+}
 /** A `### `/`- ` entry start's METADATA, joined for matching: the start line plus, for `### `
  * headings only, continuation lines up to and including the first line ending in `)` (capped
  * at 3 lines) — wrapped headings carry their date on the second line, while `- ` epitaphs are
@@ -310,7 +357,7 @@ 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 (falling back to
+ * backlog-parts.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(")"))
@@ -361,7 +408,8 @@ export function lastDate(text, dateRe) {
  * (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. */
+ * `first`, so the walker stays single-homed like lastDate's completion rule (entryLags reads
+ * it directly for an entry's filing stamp). */
 function firstDate(text, dateRe) {
     const global = new RegExp(dateRe.source, dateRe.flags.includes("g") ? dateRe.flags : `${dateRe.flags}g`);
     const match = global.exec(text);

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

@@ -0,0 +1,254 @@
+/** Backlog series parts: the `Series, part i/n` identity of a plan heading and the dependency
+ * graph the `requires parts … landed` clauses form among the planned entries. Pure over heading
+ * text and entry lists; the hold rules built on them live in backlog-eligibility.ts. */
+import { collapseWhitespace } from "../text/text.js";
+import { openParenthetical, trailingParenthetical } from "./backlog-md.js";
+import { stripEntryStamp } from "./backlog-structure.js";
+/** 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, "");
+    if (text === "")
+        return [];
+    const m = /^(?:([\s\S]+?)\s+)?([0-9]+[a-z]?)\/(\d+)(?:\s*[–-]\s*(\d+)\/(\d+))?$/i.exec(text);
+    if (m === null)
+        return [];
+    const series = (m[1]?.trim() ?? "") || ownSeries;
+    if (series === null || series === "")
+        return [];
+    const of = Number(m[3]);
+    const start = m[2].toLowerCase();
+    if (!Number.isInteger(of) || of < 1)
+        return [];
+    if (m[4] === undefined)
+        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]);
+    if (!Number.isInteger(from) || !Number.isInteger(to) || to < from)
+        return [];
+    const parts = [];
+    for (let p = from; p <= to; p++)
+        parts.push({ series, part: String(p), of });
+    return parts;
+}
+/** The stable identity of an entry heading: its `(planned …)`/`(done …)` stamp suffix
+ * removed through the shared stripEntryStamp, whitespace collapsed, lowercased. Adding a
+ * done stamp or a Refused note therefore leaves the key unchanged. */
+export function entryKey(title) {
+    return collapseWhitespace(stripEntryStamp(title)).toLowerCase();
+}
+/** An entry's own series and part from its heading, or null when the heading is not a
+ * `<Series>, part i/n: …` title. The series is the text before `, part i/n:`. */
+export function seriesPart(title) {
+    const m = /^(.+?),\s*part\s+([0-9]+[a-z]?)\/(\d+)\s*:/i.exec(stripEntryStamp(title));
+    if (m === null)
+        return null;
+    const series = m[1].trim();
+    if (series === "")
+        return null;
+    return { series, part: m[2].toLowerCase(), of: Number(m[3]) };
+}
+/** The one identity a PartRef matches by: lowercased series, verbatim part token. */
+export function partKey(series, part) {
+    return `${series.toLowerCase()}\u0000${part}`;
+}
+/** 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).
+ * Series compare case-insensitively and part tokens verbatim, exactly as entryHoldAgainst
+ * matches them. */
+export function plannedPartKeys(planned) {
+    const keys = new Set();
+    for (const p of planned) {
+        const part = seriesPart(p.title);
+        if (part !== null)
+            keys.add(partKey(part.series, part.part));
+    }
+    return keys;
+}
+/** The planned parts a cancel released: the 1-based positions and stamp-free titles of the entries
+ * in `planned` (read after the cancel) whose requiredParts name the cancelled title's part, by
+ * partKey. Only direct dependents count — a part further down the chain is still held by its own
+ * prerequisite. [] when the title has no series part, or when another planned entry still carries
+ * the same part key, because the dependents are then still held. */
+export function plansReleasedBy(planned, cancelledTitle) {
+    const own = seriesPart(cancelledTitle);
+    if (own === null)
+        return [];
+    const key = partKey(own.series, own.part);
+    if (plannedPartKeys(planned).has(key))
+        return [];
+    const released = [];
+    planned.forEach((entry, i) => {
+        if (requiredParts(entry.title).some((ref) => partKey(ref.series, ref.part) === key)) {
+            released.push({ position: i + 1, title: stripEntryStamp(entry.title) });
+        }
+    });
+    return released;
+}
+/** The note a plan cancel adds for plansReleasedBy's result: "" for none, else the positions and
+ * titles of the parts that no longer wait, and the command that cancels one. */
+export function releasedPartsNote(parts) {
+    if (parts.length === 0)
+        return "";
+    const tail = " — cancel what cannot stand alone with `tumwater plan --cancel <n>`";
+    const titles = parts.map((p) => p.title).join("; ");
+    if (parts.length === 1)
+        return `plan #${parts[0].position} required it and no longer waits on it: ${titles}${tail}`;
+    return `plans ${parts.map((p) => `#${p.position}`).join(", ")} required it and no longer wait on them: ${titles}${tail}`;
+}
+/** 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 clause = requiresClause(title);
+    if (clause === null)
+        return [];
+    const ownSeries = seriesPart(title)?.series ?? null;
+    const refs = [];
+    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;
+}

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

@@ -0,0 +1,117 @@
+/** The hold-lifting and reordering writes of `tumwater bug|plan --release <n>` and `--top <n>`:
+ * lift an entry's Refused, Waiting-for-the-next-failure, or held-for-operator note, or move
+ * it to the head of its open
+ * section. Each comes as an exiting writer (the CLI) and a non-exiting `try…` core that refuses as
+ * data (the TUI and dashboard); entry lookup and the section's file target are
+ * backlog-write.ts's. */
+import path from "node:path";
+import { backlogTarget, findEntry, readEntryLines } from "./backlog-write.js";
+import { withoutHeldForOperatorNotes, withoutRefusalNotes, withoutWaitingNotes } from "./backlog-eligibility.js";
+import { readTextIfExists, writeTextAtomic } from "../files/files.js";
+import { fail } from "../cli/cli-output.js";
+import { trimTrailingBlankLines } from "../text/text.js";
+import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
+/** Drop the Refused note from `entry`'s slice of `lines`, in place; an entry with none loses its
+ * Waiting-for-the-next-failure note instead, and one with neither loses its held-for-operator
+ * Needs-review/Needs-replan note (the `(held N)` count at/above threshold, plus its
+ * **Previously held N** line). False (and `lines` untouched) when the entry carries none of the
+ * three, shared by releaseEntry and tryReleaseEntry so they cannot drift. */
+function liftRefusal(lines, entry) {
+    const slice = lines.slice(entry.start - 1, entry.end);
+    let kept = withoutRefusalNotes(slice);
+    if (kept.length === slice.length)
+        kept = withoutWaitingNotes(slice);
+    if (kept.length === slice.length)
+        kept = withoutHeldForOperatorNotes(slice);
+    if (kept.length === slice.length)
+        return false;
+    lines.splice(entry.start - 1, slice.length, ...kept);
+    return true;
+}
+/** The non-exiting release the dashboard calls: releaseEntry's splice with tryCancelEntry's
+ * title check, all decided inside the lock. */
+export function tryReleaseEntry(root, kind, n, expectedTitle) {
+    const { fileName, sectionTitle } = backlogTarget(kind);
+    return withPrimaryWorktreeLock(root, () => {
+        const file = path.join(root, fileName);
+        const md = readTextIfExists(file) ?? "";
+        const entry = findEntry(md, sectionTitle, n);
+        if (entry === undefined)
+            return { status: "gone" };
+        if (entry.title !== expectedTitle)
+            return { status: "moved", title: entry.title };
+        const lines = md.split("\n");
+        if (!liftRefusal(lines, entry))
+            return { status: "not_refused", title: entry.title };
+        writeTextAtomic(file, lines.join("\n"));
+        return { status: "released", file: fileName, title: entry.title };
+    });
+}
+/** Lift the Refused, Waiting for the next failure, or held-for-operator note from the
+ * `n`th entry (1-based, as `--list` numbers them) of the kind's open section and write the
+ * file, under the same lock the cancel and edit writers hold.
+ * An out-of-range position fails with locateEntry's wording; an entry with neither note
+ * fails too, writing nothing. */
+export function releaseEntry(root, kind, n) {
+    const { fileName, sectionTitle } = backlogTarget(kind);
+    return withPrimaryWorktreeLock(root, () => {
+        const { file, lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
+        if (!liftRefusal(lines, entry))
+            fail(`${kind} #${n} "${entry.title}" carries no Refused, Waiting for the next failure, or held-for-operator note`); // vocabulary-ok: the held-for-operator note's release wording
+        writeTextAtomic(file, lines.join("\n"));
+        return { file: fileName, title: entry.title };
+    });
+}
+/** Move the `n`th entry (1-based, as `--list` numbers them) of the kind's open section to the
+ * head of that section and write the file, under the same lock as the other writers. Position
+ * 1 fails ("is already first") and an out-of-range one fails with locateEntry's wording, both
+ * writing nothing. The entry's lines move byte for byte; only the blank lines around the cut
+ * and the splice are normalized, and an entry that was the file's last content leaves the file
+ * ending as it did before the move (a trailing newline iff it had one). */
+export function moveEntryToTop(root, kind, n) {
+    const { fileName, sectionTitle } = backlogTarget(kind);
+    return withPrimaryWorktreeLock(root, () => {
+        const { file, lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
+        if (n === 1)
+            fail(`${kind} #1 "${entry.title}" is already first`);
+        spliceEntryToTop(lines, sectionTitle, entry);
+        writeTextAtomic(file, lines.join("\n"));
+        return { file: fileName, title: entry.title };
+    });
+}
+/** Cut `entry` out of `lines` and put it at the head of the section, in place; shared by
+ * moveEntryToTop and tryMoveEntryToTop so their bytes cannot drift. */
+function spliceEntryToTop(lines, sectionTitle, entry) {
+    const first = findEntry(lines.join("\n"), sectionTitle, 1);
+    const endsWithNewline = lines[lines.length - 1] === "";
+    const atEof = lines.slice(entry.end).every((l) => l.trim() === "");
+    const cut = lines.slice(entry.start - 1, entry.end);
+    trimTrailingBlankLines(cut);
+    lines.splice(entry.start - 1, entry.end - entry.start + 1);
+    if (atEof) {
+        trimTrailingBlankLines(lines);
+        if (endsWithNewline)
+            lines.push("");
+    }
+    lines.splice(first.start - 1, 0, ...cut, "");
+}
+/** The non-exiting reorder the dashboard calls: moveEntryToTop's splice with tryReleaseEntry's
+ * title check, all decided inside the lock. */
+export function tryMoveEntryToTop(root, kind, n, expectedTitle) {
+    const { fileName, sectionTitle } = backlogTarget(kind);
+    return withPrimaryWorktreeLock(root, () => {
+        const file = path.join(root, fileName);
+        const md = readTextIfExists(file) ?? "";
+        const entry = findEntry(md, sectionTitle, n);
+        if (entry === undefined)
+            return { status: "gone" };
+        if (entry.title !== expectedTitle)
+            return { status: "moved", title: entry.title };
+        if (n === 1)
+            return { status: "already_first", title: entry.title };
+        const lines = md.split("\n");
+        spliceEntryToTop(lines, sectionTitle, entry);
+        writeTextAtomic(file, lines.join("\n"));
+        return { status: "moved_to_top", file: fileName, title: entry.title };
+    });
+}

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

@@ -1,3 +1,4 @@
+import { entryMatches } from "./backlog.js";
 import { groupBlockedSeries, partsLabel } from "./backlog-structure.js";
 import { holdMark, inProgressMark } from "./backlog-eligibility.js";
 /** One `## ` section: its entries verbatim, or the single `_(none)_` placeholder line. When
@@ -77,3 +78,29 @@ export function readyBacklog(view) {
             : {}),
     };
 }
+/** The view with only the entries whose heading or body contains `pattern` (case-insensitively) —
+ * the active-entry twin of the finished-entry `--grep`, through the same one matcher
+ * (entryMatches, backlog.ts) the finished-entry lists use: keep plan `i`, bug `i` and question
+ * `i` only when entryMatches(entry, pattern), and filter `holds.plans`/`holds.bugs` and
+ * `inProgress.plans`/`inProgress.bugs` by the same kept indexes so the parallel arrays stay
+ * aligned (the `pick` shape readyBacklog reuses). Questions carry no holds and filter by
+ * entryMatches alone. A view without `holds`/`inProgress` only filters the entry arrays. */
+export function grepBacklog(view, pattern) {
+    const keep = (xs) => Array.from({ length: xs.length }, (_, i) => i).filter((i) => entryMatches(xs[i], pattern));
+    const plan = keep(view.plans);
+    const bug = keep(view.bugs);
+    const question = keep(view.questions);
+    const pick = (xs, idx) => idx.map((i) => xs?.[i]);
+    return {
+        ...view,
+        plans: pick(view.plans, plan),
+        bugs: pick(view.bugs, bug),
+        questions: pick(view.questions, question),
+        ...(view.holds
+            ? { holds: { plans: pick(view.holds.plans, plan), bugs: pick(view.holds.bugs, bug) } }
+            : {}),
+        ...(view.inProgress
+            ? { inProgress: { plans: pick(view.inProgress.plans, plan), bugs: pick(view.inProgress.bugs, bug) } }
+            : {}),
+    };
+}