tumwater 0.4.2 → 0.4.3

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

@@ -238,8 +238,35 @@ export async function topAndAnnounce(root, args, command, top) {
  * $VISUAL/$EDITOR and the saved buffer goes through `editText`. A saved buffer, positional or
  * `--file` text that rebuilds the entry byte-for-byte writes and commits nothing (`unchanged
  * <command> <n>: <title>`), and an out-of-range position fails
- * before the editor launches. */
+ * before the editor launches. The flag vocabulary, editor round-trip, unchanged report and
+ * commit-plus-hold announcement each live in their own named helper below. */
 export async function editAndAnnounce(root, args, command, edit, editText) {
+    const { path, json, positionals, position } = parseEditArgs(args, command);
+    await requireReadyRepo(root);
+    let text = null;
+    if (path === null && positionals.length === 0) {
+        const opened = openEditInEditor(root, command, position);
+        if (!opened.changed) {
+            sayUnchangedEdit(command, position, json, opened.file, opened.title);
+            return;
+        }
+        text = opened.text;
+    }
+    else if (path !== null)
+        text = readPromptFileArg(path);
+    const edited = text === null ? edit(position, positionals) : editText(position, text);
+    if (edited.unchanged) {
+        sayUnchangedEdit(command, position, json, edited.file, edited.title);
+        return;
+    }
+    await announceEdited(root, command, position, json, edited);
+}
+/** The flag vocabulary of the `--edit` shell: `--file <path>` is extracted and the repeat
+ * of the flag refused; the remaining tokens go through scanProseFlags (the `--json` boolean
+ * at most once, an `--edit <n>` position required here through scanProseFlags' one valued
+ * flag), and a stray positional alongside `--file` is refused. `fail` returns never, so on
+ * return `position` is a `number`. */
+function parseEditArgs(args, command) {
     const fileFlag = args.indexOf("--file");
     const path = fileFlag >= 0 ? promptFileValue(args[fileFlag + 1]) : null;
     const rest = path === null ? args : args.filter((_, i) => i !== fileFlag && i !== fileFlag + 1);
@@ -253,32 +280,36 @@ export async function editAndAnnounce(root, args, command, edit, editText) {
         rejectStrayWithFile(positionals[0]);
     if (position === null)
         fail(`--edit needs a position (usage: tumwater ${command} --edit <n>)`);
-    await requireReadyRepo(root);
-    const sayUnchanged = (file, title) => {
-        if (json)
-            sayJson({ file, title, changed: false });
-        else
-            say(`unchanged ${command} ${position}: ${title}`);
-    };
-    let text = null;
-    if (path === null && positionals.length === 0) {
-        const shown = showEntry(root, command, position);
-        const before = renderShownEntry(shown);
-        const after = editInEditor(before, `${command}-${position}.md`);
-        if (after.trim() === before.trim()) {
-            const file = command === "bug" ? "BUGS.md" : "PLANS.md";
-            sayUnchanged(file, shown.title);
-            return;
-        }
-        text = after;
-    }
-    else if (path !== null)
-        text = readPromptFileArg(path);
-    const edited = text === null ? edit(position, positionals) : editText(position, text);
-    if (edited.unchanged) {
-        sayUnchanged(edited.file, edited.title);
-        return;
+    return { path, json, positionals, position };
+}
+/** The no-op wording when an edit changes nothing: a `--json` `{ file, title, changed: false }`
+ * payload, else a single `unchanged <command> <n>: <title>` line. */
+function sayUnchangedEdit(command, position, json, file, title) {
+    if (json)
+        sayJson({ file, title, changed: false });
+    else
+        say(`unchanged ${command} ${position}: ${title}`);
+}
+/** The editor round-trip taken when the `--edit` shell has neither `--file` nor positionals:
+ * the entry rendered as `--show` prints it (showEntry/renderShownEntry) opens in
+ * $VISUAL/$EDITOR, and a saved buffer that trims to the same text reports `{ changed: false }`
+ * with the backing file's name and the shown title; otherwise the saved text is returned as
+ * `{ changed: true, text }`. */
+function openEditInEditor(root, command, position) {
+    const shown = showEntry(root, command, position);
+    const before = renderShownEntry(shown);
+    const after = editInEditor(before, `${command}-${position}.md`);
+    if (after.trim() === before.trim()) {
+        return { changed: false, file: command === "bug" ? "BUGS.md" : "PLANS.md", title: shown.title };
     }
+    return { changed: true, text: after };
+}
+/** The commit-and-announce tail of the `--edit` shell: the changed entry is committed through
+ * commitOperatorBacklogEdit with the `Edit <command>: <title>` subject (warned on an
+ * uncommitted worktree), the still-held role from the one before `position` is picked for the
+ * hold report, and the `--json` payload (with `hold` when held) or the prose `edited …` line
+ * plus stillHeldNote is printed. */
+async function announceEdited(root, command, position, json, edited) {
     warnIfUncommitted(await commitOperatorBacklogEdit(root, edited.file, stampedSubject("operator", `Edit ${command}: ${edited.title}`)), edited.file); // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
     const holds = backlogHolds(root);
     const hold = (command === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;

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

@@ -10,53 +10,21 @@
 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_REVIEW_PREFIX, PRIOR_HELD_PREFIX } from "../roles/role-guidance.js";
+import { firstTrimmedLineStartingWith } from "../text/text.js";
+import { NEEDS_REVIEW_PREFIX } from "../roles/role-guidance.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { roleLabel } from "../roles/role-labels.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 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 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);
-        if (!note)
-            continue;
-        const tag = tagRe.exec(line);
-        if (tag !== null)
-            return Number(tag[1]);
-        if (line.includes(HELD_TAG_PREFIX))
-            return 0;
-    }
-    return 0;
-}
-/** 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);
-    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 prefix — is matched as a line prefix (hasNoteLine)
  * so a mention in prose never holds an entry. */
 const REFUSED_PREFIX = "**Refused ";
+/** The legacy marker the old increment rule left beside a Needs-review note's prior held count
+ * (`**Previously held N−1**` beside the live `(held N)`), dropped by withoutNeedsReviewNotes so
+ * a release leaves no orphan. No writer emits it anymore; only survives on live notes. */
+const PRIOR_HELD_PREFIX = "**Previously held ";
 /** True when `body` carries a line (ignoring leading indentation) that begins with `prefix`.
  * The one home of the hold-note rule: a note holds its entry only when written as its own
  * line, never when its prefix is quoted inside prose. */
@@ -80,6 +48,25 @@ export function refusalNote(body) {
 export function needsReviewNote(body) {
     return noteText(body, NEEDS_REVIEW_PREFIX);
 }
+/** True when `entry` is parked with the plan role — its Needs-review note is the feature
+ * role's too-large note, the automatic convergence hold, or a final-round rejection, all of
+ * which the plan role clears by splitting or replanning (role-catalog.ts `plan` find). False
+ * for the bugfix role's wait-for-the-next-failure note ("by bugfix: …"), which parks the
+ * entry for selfcheck to lift when the cluster fails again (selfcheck step 4) and which no
+ * role can act on until then. entryHold returns "needs-review" for every such note (all of
+ * them park the entry), so the stalled-with-the-plan-role surfaces — the stalled-entries team
+ * alert (team-alert-backlog.ts) and the doctor's `stalled entries` row
+ * (checkStalledEntries) — classify by this agreed subset, keeping the bugfix parks out of the
+ * plan-role blame. Reads the note's text after the NEEDS_REVIEW_PREFIX once, so the alert and
+ * the doctor row cannot disagree on which notes the plan role clears; the eligibility mark
+ * (holdMark) continues to hold every needs-review note, a by-bugfix park included. */
+export function isPlanStalled(entry) {
+    const note = needsReviewNote(entry.body);
+    if (note === null)
+        return false;
+    // A "by bugfix:" note is a wait for evidence that selfcheck clears, not plan-role work.
+    return !note.includes("by bugfix");
+}
 /** `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. */
@@ -101,33 +88,25 @@ function withoutNoteLines(lines, prefix) {
 export function withoutRefusalNotes(lines) {
     return withoutNoteLines(lines, REFUSED_PREFIX);
 }
-/** `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
- * threshold, so release still cannot lift a live first/second Needs-review hold. Consecutive
- * dropped lines are collapsed to one blank line, the same rule withoutNoteLines applies to a
- * single dropped note. */
-export function withoutHeldForOperatorNotes(lines) {
-    const drop = new Set();
-    const priorHeld = new Set();
-    lines.forEach((raw, i) => {
-        const c = lineHeldCount(raw);
-        if (c !== undefined && c >= OPERATOR_HOLD_THRESHOLD) {
-            priorHeld.add(c - 1);
-            drop.add(i);
-        }
-    });
-    if (priorHeld.size === 0)
+/** `lines` without its Needs-review note lines and the legacy `**Previously held N**`
+ * markers the old increment rule left beside them, the release's lift when the entry has no
+ * Refused note: a `--release` that finds no Refused note drops every Needs-review note line so
+ * the entry becomes eligible, and takes each `**Previously held N**` marker in the slice with
+ * it, so the lift leaves no orphan whether or not the note still carries a `(held N)` tag.
+ * Nothing changes when the slice carries no Needs-review note, so a marker that sits on an
+ * eligible entry stays put. Every other line, Refused notes included, is kept, so the
+ * Needs-review lift never lifts a refusal. */
+export function withoutNeedsReviewNotes(lines) {
+    // A lift only happens when the slice carries a Needs-review note; without one, the slice
+    // (and any legacy prior-held marker on it) is left byte for byte.
+    if (!lines.some((raw) => raw.trimStart().startsWith(NEEDS_REVIEW_PREFIX)))
         return lines;
+    const drop = new Set();
     lines.forEach((raw, i) => {
-        if (drop.has(i))
-            return;
         const trimmed = raw.trimStart();
-        if (!trimmed.startsWith(PRIOR_HELD_PREFIX))
-            return;
-        const count = /\d+/.exec(trimmed.slice(PRIOR_HELD_PREFIX.length));
-        if (count !== null && priorHeld.has(Number(count[0])))
+        // Every Needs-review note goes, and so does each `**Previously held N**` marker the old
+        // increment rule wrote with it.
+        if (trimmed.startsWith(NEEDS_REVIEW_PREFIX) || trimmed.startsWith(PRIOR_HELD_PREFIX))
             drop.add(i);
     });
     const out = [];
@@ -140,7 +119,7 @@ export function withoutHeldForOperatorNotes(lines) {
         while (j < lines.length && drop.has(j))
             j++;
         // A dropped run between two blank lines drops the blank after it too, so the lift leaves
-        // one blank line where the note was (the same rule withoutNoteLines applies to one).
+        // one blank line where the note was (the same rule withoutNoteLines applies to one note).
         if (j < lines.length && (lines[i - 1] ?? "x").trim() === "" && (lines[j] ?? "x").trim() === "")
             j++;
         i = j - 1;
@@ -209,13 +188,10 @@ 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)) {
-        // A note whose held count reached OPERATOR_HOLD_THRESHOLD stops out of the role loop:
-        // 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
-            : "needs-review";
-    }
+    // A Needs-review note — the feature role's too-large note or the convergence hold's — parks the
+    // entry for the plan role to split or replan, at any count: nothing escalates to the operator.
+    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX))
+        return "needs-review";
     const refs = requiredParts(entry.title);
     if (refs.length === 0)
         return null;
@@ -235,8 +211,6 @@ export function holdMark(hold) {
         return " [blocked: refused]";
     if (hold === "needs-review")
         return " [blocked: needs review]";
-    if (hold === "held-for-operator")
-        return " [blocked: held for operator]"; // vocabulary-ok: this hold names the operator-held wording for the operator decision
     return ` [blocked: requires ${hold.blockedBy.join(", ")}]`;
 }
 /** The line `plan|bug --release` and `--top` print when the entry they touched is still held:
@@ -315,42 +289,22 @@ export function backlogMarks(root) {
         bugs: holds.bugs.map((h, i) => mark(h, working.bugs[i])),
     };
 }
-/** A planned plan or open bug whose hold is `"held-for-operator"`, in file order: the
- * entries parked until the operator lifts them with `tumwater plan --release` or `tumwater
- * bug --release` (the `operator-held` team alert's input), each carrying the backlog file
- * and its 0-based position so a surface opening the row can land on it, the same RefusedEntry
- * shape refusedEntries returns. The convergence hold writes only on plans, but a role's own
- * too-large note can sit on a bug and reach this threshold, so a bug can be held this way too.
- * A missing file yields `[]`. */
-export function operatorHeldEntries(root) {
-    const holds = backlogHolds(root);
-    const out = [];
-    const entriesOf = (entries, held, file) => {
-        entries.forEach((e, i) => {
-            if (held[i] === "held-for-operator")
-                out.push({ file, index: i, title: e.title }); // vocabulary-ok: the held-for-operator hold's key
-        });
-    };
-    entriesOf(plannedPlanEntries(root), holds.plans, "plans");
-    entriesOf(openBugEntries(root), holds.bugs, "bugs");
-    return out;
-}
 /** The display noun for a backlog-file discriminator — the `"plans" | "bugs"` `file` on
  * RefusedEntry and StalledEntry (and the same discriminator the prompt's named-hold wording
  * and the doctor's Stalled row take): BUGS.md is a "Bug" and PLANS.md a "Plan", and the
  * lowercase form is the `Refused plan|bug:` label and the `tumwater plan|bug --release`
- * command noun the operator-held alert body interpolates. */
+ * command noun. */
 export function entryKindLabel(file) {
     return file === "bugs" ? "Bug" : "Plan";
 }
-/** 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
+/** The planned plans and open bugs parked with the plan role — whose Needs-review hold the plan
+ * role clears by splitting or replanning (the feature role's too-large note, the convergence hold,
+ * a final-round rejection), in file order: 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 `refusedEntries` uses, so the alert and the doctor's
+ * `stalled entries` row classify through the same `entryHold` + `isPlanStalled` and cannot
+ * disagree on which holds are role-resolvable. The bugfix role's wait-for-the-next-failure
+ * parks ("by bugfix:") are excluded: selfcheck lifts them, not the plan role. A missing
  * file yields `[]`. */
 export function stalledEntries(root) {
     const holds = backlogHolds(root);
@@ -358,7 +312,9 @@ export function stalledEntries(root) {
     const entriesOf = (entries, held, file) => {
         entries.forEach((e, i) => {
             const hold = held[i];
-            if (hold === "needs-review")
+            // Only holds the plan role can clear surface as stalled: the bugfix role's
+            // wait-for-the-next-failure parks stay out of the plan-role blame.
+            if (hold === "needs-review" && isPlanStalled(e))
                 out.push({ file, index: i, title: e.title, hold });
         });
     };

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

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

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

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

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

@@ -1,35 +1,35 @@
 /** The hold-lifting and reordering writes of `tumwater bug|plan --release <n>` and `--top <n>`:
- * lift an entry's Refused or held-for-operator note, or move
+ * lift an entry's Refused or Needs-review note, or move
  * it to the head of its open
  * section. Each comes as an exiting writer (the CLI) and a non-exiting `try…` core that refuses as
  * data (the TUI and dashboard); entry lookup and the section's file target are
  * backlog-write.ts's. */
 import { backlogTarget, findEntry, locateDashboardEntry, readEntryLines } from "./backlog-write.js";
-import { withoutHeldForOperatorNotes, withoutRefusalNotes } from "./backlog-eligibility.js";
+import { withoutNeedsReviewNotes, withoutRefusalNotes } from "./backlog-eligibility.js";
 import { writeTextAtomic } from "../files/files.js";
 import { fail } from "../cli/cli-output.js";
 import { trimTrailingBlankLines } from "../text/text.js";
 import { withPrimaryWorktreeLock } from "../concurrency/lock.js";
-/** The prose naming the note `lifted` kind a release removed, shared by the CLI, TUI and the
- * exit-announcers so their released lines cannot drift. */
+/** The prose naming the note kind a release removed — plural, since a release lifts every line
+ * of the chosen kind — shared by the CLI, TUI and the exit-announcers so their released lines
+ * cannot drift. */
 export function liftedNotePhrase(lifted) {
     return lifted === "refused"
-        ? "the Refused note"
-        : "the held-for-operator note"; // vocabulary-ok: the held-for-operator note's release wording
+        ? "the Refused notes"
+        : "the Needs review notes";
 }
 /** Drop the Refused note from `entry`'s slice of `lines`, in place, and return its kind; an
- * entry with none loses its held-for-operator Needs-review note (the `(held N)` count at/above
- * threshold, plus its **Previously held N** line). Null (and `lines` untouched) when the entry
+ * entry with none loses its Needs-review note. Null (and `lines` untouched) when the entry
  * carries neither, shared by releaseEntry and tryReleaseEntry so they cannot drift. */
 function liftRefusal(lines, entry) {
     const slice = lines.slice(entry.start - 1, entry.end);
     let kept = withoutRefusalNotes(slice);
     if (kept.length === slice.length) {
-        kept = withoutHeldForOperatorNotes(slice);
+        kept = withoutNeedsReviewNotes(slice);
         if (kept.length === slice.length)
             return null;
         lines.splice(entry.start - 1, slice.length, ...kept);
-        return "held-for-operator"; // vocabulary-ok: the held-for-operator note's release wording
+        return "needs-review";
     }
     lines.splice(entry.start - 1, slice.length, ...kept);
     return "refused";
@@ -51,7 +51,7 @@ export function tryReleaseEntry(root, kind, n, expectedTitle) {
         return { status: "released", file: fileName, title: entry.title, lifted };
     });
 }
-/** Lift the Refused or held-for-operator note from the
+/** Lift the Refused or Needs-review note from the
  * `n`th entry (1-based, as `--list` numbers them) of the kind's open section and write the
  * file, under the same lock the cancel and edit writers hold, returning which hold it lifted.
  * An out-of-range position fails with locateEntry's wording; an entry with neither note
@@ -62,7 +62,7 @@ export function releaseEntry(root, kind, n) {
         const { file, lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
         const lifted = liftRefusal(lines, entry);
         if (lifted === null)
-            fail(`${kind} #${n} "${entry.title}" carries no Refused or held-for-operator note`); // vocabulary-ok: the held-for-operator note's release wording
+            fail(`${kind} #${n} "${entry.title}" carries no Refused or Needs review note`);
         writeTextAtomic(file, lines.join("\n"));
         return { file: fileName, title: entry.title, lifted };
     });