tumwater 0.1.2 → 0.2.0

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

@@ -1,41 +1,42 @@
-/** The CLI layer of `tumwater bug` and `tumwater plan` — the operator-authored backlog
- * write half, mirroring the read half in backlog.ts: file a bug into BUGS.md's `## Open`
- * or a plan request into PLANS.md's `## Planned`, stamped the way loops write those
- * entries, and render the confirmation. Split out of cli.ts because the markdown surgery
- * it performs is more than a dispatch case: the entry must land after the section's last
- * entry and before the next `## ` heading, fenced-safe (a `## ` line quoted inside an
- * entry's code fence is body text, never a boundary — the same fenceTracker every backlog
- * reader consults), and a file tumwater init never seeded is created with init's template
- * rather than failing. The wake of the loop that should act stays in cli.ts beside the
- * other command bodies. */
+// vocabulary: plain
+/** The entry-writing half of `tumwater bug` and `tumwater plan` — the operator-authored backlog
+ * writes, mirroring the read half in backlog.ts: file a bug into BUGS.md's `## Open` or a plan
+ * request into PLANS.md's `## Planned`, stamped the way loops write those entries, and cancel,
+ * edit, release, or show an entry by position. The markdown surgery is more than a dispatch case:
+ * the entry must be placed after the section's last entry and before the next `## ` heading,
+ * fenced-safe (a `## ` line quoted inside an entry's code fence is body text, never a boundary —
+ * the same fenceTracker every backlog reader consults), and a file tumwater init never seeded is
+ * created with init's template rather than failing. Flag classification, preflights, and the
+ * printed confirmations live in backlog-cli.ts; the wake of the loop that should act stays in
+ * cli.ts beside the other command bodies. */
 import path from "node:path";
 import { fencedHeadingTitle, fenceTracker, headingMetadata, nextSectionHeading } from "./backlog-md.js";
 import { actionableEntryRanges, stripEntryStamp } from "./backlog-structure.js";
 import { readTextIfExists, writeTextAtomic } from "../files/files.js";
 import { formatDate } from "../text/datetime.js";
-import { fail, say, sayJson } from "../cli/cli-output.js";
-import { parsePositionFlag, rejectRepeatFlag } from "../cli/cli-args.js";
-import { promptFileValue, readPromptFileArg } from "../cli/cli-command-args.js";
-import { plannedPlanEntries, openBugEntries } from "./backlog.js";
-import { backlogHolds, holdMark } from "./backlog-eligibility.js";
-import { numberedList } from "../text/markdown.js";
+import { fail } from "../cli/cli-output.js";
+import { backlogHolds, withoutRefusalNotes, withoutWaitingNotes } from "./backlog-eligibility.js";
 import { collapseWhitespace, trimLeadingBlankLines, trimTrailingBlankLines } from "../text/text.js";
 import { BUGS_TEMPLATE, PLANS_TEMPLATE } from "../init/init.js";
-import { JSON_FLAG, rejectUnknownArgs } from "../cli/cli-flag-specs.js";
-import { requireReadyRepo } from "../cli/cli-repo-gate.js";
-import { submitRolePromptAndWake } from "../operator/operator-intent.js";
-import { promptLengthProblem } from "../inbox/inbox-submit.js";
 import { withStateLock } from "../concurrency/lock.js";
 import { primaryWorktreeLockPath } from "../paths.js";
 /** Today's stamp body every operator-filed entry carries, parenthesized by the caller that
  * builds the heading. Computed once per call (not module load) so a long-lived process
  * stamps with the date it filed on. */
-const operatorStamp = () => `reported by the operator ${formatDate(new Date())}`;
+const operatorStamp = () => `reported by the user ${formatDate(new Date())}`;
+/** The kind's open-section markdown file and its `## ` heading: bugs live in BUGS.md's `Open`
+ * section, plan requests in PLANS.md's `Planned`. Every position-based writer (cancel, edit,
+ * release, show) resolves the same pair. */
+function backlogTarget(kind) {
+    return kind === "bug"
+        ? { fileName: "BUGS.md", sectionTitle: "Open" }
+        : { fileName: "PLANS.md", sectionTitle: "Planned" };
+}
 /** The section-append entry point: run the whole read-modify-write under the cross-process
- * primary-worktree lock (paths.ts), which a landing's working-tree fast-forward (`ffMainTo`)
- * takes too, so a filed entry and a landed change to the same backlog file cannot each clobber
- * the other. The section is one read plus one atomic rename — short, never held across a build
- * check — and withStateLock creates the state dir the lock lives under on first use. */
+ * primary-worktree lock (paths.ts), which a merge's working-tree fast-forward (`ffMainTo`) takes
+ * too, so a filed entry and a merged change to the same backlog file cannot each clobber the other.
+ * The section is one read plus one atomic rename — short, never held across a build check — and
+ * withStateLock creates the state dir the lock lives under on first use. */
 function appendEntry(root, fileName, template, sectionTitle, heading, body) {
     withStateLock(primaryWorktreeLockPath(root), () => appendEntryLocked(root, fileName, template, sectionTitle, heading, body));
 }
@@ -102,7 +103,7 @@ function appendEntryLocked(root, fileName, template, sectionTitle, heading, body
 }
 /** The noun a cancel failure names the section by: the plan example's `no open bug at
  * position N`, and the parallel planned-feature wording for PLANS.md. */
-function sectionNoun(sectionTitle) {
+export function sectionNoun(sectionTitle) {
     if (sectionTitle === "Open")
         return "open bug";
     if (sectionTitle === "Planned")
@@ -116,7 +117,10 @@ function locateEntry(md, fileName, sectionTitle, n) {
     const entry = findEntry(md, sectionTitle, n);
     if (entry === undefined) {
         const count = actionableEntryRanges(md, sectionTitle).length;
-        fail(`no ${sectionNoun(sectionTitle)} at position ${n} (${count} in ${fileName})`);
+        // Name the valid range when the section is non-empty, so the operator sees the fix in the
+        // same line instead of deriving `1..N` from the count; an empty section needs no range.
+        const range = count > 0 ? ` — valid: 1-${count}` : "";
+        fail(`no ${sectionNoun(sectionTitle)} at position ${n} (${count} in ${fileName})${range}`);
     }
     return entry;
 }
@@ -136,7 +140,7 @@ function readEntryLines(root, fileName, sectionTitle, n) {
     return { file, lines: md.split("\n"), entry };
 }
 /** The section-remove entry point, the appendEntry analogue: the same cross-process lock, so a
- * cancel and a landing's working-tree fast-forward cannot each clobber the other's
+ * cancel and a merge's working-tree fast-forward cannot each clobber the other's
  * read-modify-write. */
 function removeEntry(root, fileName, sectionTitle, n) {
     return withStateLock(primaryWorktreeLockPath(root), () => removeEntryLocked(root, fileName, sectionTitle, n));
@@ -166,8 +170,7 @@ function spliceOutEntry(file, lines, entry) {
  * decided inside the lock. `expectedTitle` is the heading the caller saw (the status payload's
  * `plans`/`bugs` strings, the same `### ` text as ActionableEntryRange.title). */
 export function tryCancelEntry(root, kind, n, expectedTitle) {
-    const fileName = kind === "bug" ? "BUGS.md" : "PLANS.md";
-    const sectionTitle = kind === "bug" ? "Open" : "Planned";
+    const { fileName, sectionTitle } = backlogTarget(kind);
     return withStateLock(primaryWorktreeLockPath(root), () => {
         const file = path.join(root, fileName);
         const md = readTextIfExists(file) ?? "";
@@ -180,9 +183,9 @@ export function tryCancelEntry(root, kind, n, expectedTitle) {
         return { status: "cancelled", file: fileName, title: entry.title };
     });
 }
-/** The section-edit entry point, the appendEntry/removeEntry analogue: the same
- * cross-process lock, so an edit and a landing's working-tree fast-forward cannot each clobber
- * the other's read-modify-write. */
+/** The section-edit entry point, the appendEntry/removeEntry analogue: the same cross-process lock,
+ * so an edit and a merge's working-tree fast-forward cannot each clobber the other's
+ * read-modify-write. */
 function editEntry(root, fileName, sectionTitle, n, title, body) {
     return withStateLock(primaryWorktreeLockPath(root), () => editEntryLocked(root, fileName, sectionTitle, n, title, body));
 }
@@ -237,8 +240,7 @@ export function bodyStructureProblem(body) {
  * body's line structure kept (no whitespace fold). The caller validates (bodyStructureProblem,
  * non-empty title) first, since fail() exits the process. */
 export function tryEditEntry(root, kind, n, expectedTitle, rawTitle, rawBody) {
-    const fileName = kind === "bug" ? "BUGS.md" : "PLANS.md";
-    const sectionTitle = kind === "bug" ? "Open" : "Planned";
+    const { fileName, sectionTitle } = backlogTarget(kind);
     const title = stripEntryStamp(collapseWhitespace(rawTitle));
     const body = rawBody.replace(/\r\n?/g, "\n").trim();
     return withStateLock(primaryWorktreeLockPath(root), () => {
@@ -253,113 +255,6 @@ export function tryEditEntry(root, kind, n, expectedTitle, rawTitle, rawBody) {
         return { status: "edited", file: fileName, title };
     });
 }
-/** The title each file command derives from the CLI positionals, exported so the CLI case
- * can hand fileAndAnnounce the same derivation the write will carry: fileAndAnnounce
- * preflights the composed wake prompt (wakeText(title)) against the submission cap BEFORE
- * the write, and a titleOf that drifted from file()'s own derivation would preflight the
- * wrong text. bugTitleOf(positionals) is exactly fileBug's symptom when the CLI case passes
- * positionals.join(" ") as its raw text; planTitleOf(positionals) is exactly filePlan's
- * title when it passes positionals[0]. */
-export function bugTitleOf(positionals) {
-    return collapseWhitespace(positionals.join(" "));
-}
-export function planTitleOf(positionals) {
-    return collapseWhitespace(positionals[0] ?? "");
-}
-/** The one home of the prose-carrying file commands' flag classification (the `bug`/`plan`
- * file forms and their `--edit` forms): `--json` is the one boolean, refused on a repeat
- * (the "each flag at most once" rule every spec-parsed command and the questions parser
- * apply); when a position flag is supplied it is the one valued flag, likewise refused on a
- * repeat and parsed through the shared plain-decimal rule (parsePositionFlag); `--help`/`-h`
- * rides into the prose positionals rather than being skipped, because the dispatcher's help
- * interception stands down for text-carrying invocations (cli.ts) so a help token here is
- * always content; every other flag-shaped token is named by rejectUnknownArgs, and every
- * bare token is prose. Tokens keep their original order. */
-function scanProseFlags(args, command, positionFlag) {
-    let json = false;
-    let position = null;
-    const positionals = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i] ?? "";
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === positionFlag?.name) {
-            rejectRepeatFlag(position !== null, positionFlag.name);
-            position = parsePositionFlag(positionFlag.name, args[i + 1], positionFlag.example);
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h") {
-            positionals.push(arg);
-            continue;
-        }
-        if (arg.startsWith("-"))
-            rejectUnknownArgs(command, [arg], [JSON_FLAG]);
-        else
-            positionals.push(arg);
-    }
-    return { json, positionals, position };
-}
-/** The shared shell of the `bug` and `plan` CLI cases — the one home of the five-step
- * sequence both commands run in cli.ts: peel the free-form positionals (the questions
- * command's prose-token pattern), reject anything flag-shaped that is not `--json`, run the
- * ready-repo gate the other backlog commands run, write the entry via `file`, wake the
- * `role` loop that should act so it picks the entry up within one poll, then announce — the
- * wake always fires, its confirmation line rides the prose output only, in `--json` mode
- * stdout is the payload document alone (the prompt --json precedent) so a script can parse
- * it. The command name and usage string ride in for the reject/confirmation/empty-arg
- * wordings (fileBug/filePlan's empty-arg usage lines); `wakeText` builds the loop prompt
- * from the filed entry's title and `titleOf` derives that title from the positionals (the
- * exported bugTitleOf/planTitleOf, so the preflight and the write see one derivation).
- * The wake prompt rides into the target tick's prefill under the same submission cap every
- * prompt answers to, so fileAndAnnounce checks it (promptLengthProblem) BEFORE calling
- * `file` — otherwise an over-long operator text would write its entry and only then throw
- * inside submitRolePromptAndWake, half-applying the command with the backlog file already
- * grown. With `--file <path>` (`-` reads stdin) the entry comes from a markdown file instead
- * of positionals: `fileText` receives its text (splitEntryFile: first line the title, the rest
- * the body kept line for line), the same preflight runs on that title, and any positional
- * alongside --file is refused. */
-export async function fileAndAnnounce(root, args, command, file, role, wakeText, titleOf, fileText) {
-    const fileFlag = args.indexOf("--file");
-    if (fileFlag >= 0) {
-        const file = promptFileValue(args[fileFlag + 1]);
-        const rest = args.filter((_, i) => i !== fileFlag && i !== fileFlag + 1);
-        rejectRepeatFlag(rest.includes("--file"), "--file");
-        const { json, positionals } = scanProseFlags(rest, command);
-        const stray = positionals[0];
-        if (stray !== undefined)
-            fail(`unexpected argument ${JSON.stringify(stray)} — with --file the entry comes from the file`);
-        await requireReadyRepo(root);
-        const text = readPromptFileArg(file);
-        const wakeProblem = promptLengthProblem(wakeText(splitEntryFile(text).title), role);
-        if (wakeProblem)
-            fail(wakeProblem);
-        announceFiled(root, command, fileText(text), role, wakeText, json);
-        return;
-    }
-    // peelPositionals cannot serve this command: bug/plan's text is operator prose, and a
-    // standalone --help/-h token inside it ("the TUI mishandles --help output") is content —
-    // the dispatcher's help interception stands down for text-carrying invocations (cli.ts),
-    // so a help token that reaches here is always prose, and scanProseFlags keeps it in the
-    // positionals rather than flag-shaping it into rest for rejectUnknownArgs to refuse.
-    const { json, positionals } = scanProseFlags(args, command);
-    await requireReadyRepo(root);
-    const wakeProblem = promptLengthProblem(wakeText(titleOf(positionals)), role);
-    if (wakeProblem)
-        fail(wakeProblem);
-    announceFiled(root, command, file(positionals), role, wakeText, json);
-}
-/** The tail both fileAndAnnounce forms share: wake the `role` loop with the filed entry's
- * title, then print the confirmation (the wake line rides the prose output only). */
-function announceFiled(root, command, filed, role, wakeText, json) {
-    const wake = submitRolePromptAndWake(root, role, wakeText(filed.title));
-    sayFiled(command, filed, json);
-    if (!json)
-        say(wake);
-}
 /** Split a markdown entry file into its title and body: the title is the first non-blank line
  * (a leading `#`-marker stripped, folded through collapseWhitespace), the body every later
  * line kept as written with trailing whitespace stripped and edge blank lines dropped. */
@@ -379,6 +274,21 @@ export function normalizeEntryBody(body) {
     trimTrailingBlankLines(lines);
     return lines.join("\n");
 }
+/** Fail with the kind's empty-field usage line when the title/symptom is empty: the plan
+ * form names its missing field a "title", the bug form a "symptom". The single home of those
+ * two strings, shared by the inline, `--file`, and `--edit` forms so the CLI and dashboard
+ * can't drift. */
+function requireEntryTitle(kind, title, usage) {
+    if (title === "")
+        fail(kind === "plan" ? `plan needs a title: ${usage}` : `bug needs a symptom: ${usage}`);
+}
+/** Fail when a split `--file` body would grow a phantom section (bodyStructureProblem). verb is
+ * the CLI verb in the message: "filed" for `--file`, "written" for `--edit <n> --file`. */
+function requireBodyStructurallySound(body, verb) {
+    const problem = bodyStructureProblem(body);
+    if (problem)
+        fail(`the --file body cannot be ${verb}: ${problem}`);
+}
 /** File an already-validated title and body under PLANS.md's `## Planned` (plan) or BUGS.md's
  * `## Open` (bug). Shared by the `--file` forms and the dashboard file endpoint; the caller has
  * checked the title is non-empty and the body passes bodyStructureProblem. */
@@ -388,35 +298,32 @@ export function fileEntryWithBody(root, kind, title, body) {
         ? appendOperatorEntry(root, "PLANS.md", PLANS_TEMPLATE, "Planned", t, body)
         : appendOperatorEntry(root, "BUGS.md", BUGS_TEMPLATE, "Open", t, body);
 }
+/** The `--file` filing form shared by plan and bug: split the file's title and body, require a
+ * title and a structurally-sound body, and file under the kind's section (fileEntryWithBody).
+ * filePlanFromText and fileBugFromText are the public plan/bug twins routing through it. */
+function fileFromText(root, kind, text, usage) {
+    const { title, body } = splitEntryFile(text);
+    requireEntryTitle(kind, title, usage);
+    requireBodyStructurallySound(body, "filed");
+    return fileEntryWithBody(root, kind, title, body);
+}
 /** `tumwater plan --file`: file the markdown file's title and line-for-line body under
  * PLANS.md's `## Planned`. A body that would grow a phantom section writes nothing. */
 export function filePlanFromText(root, text, usage) {
-    const { title, body } = splitEntryFile(text);
-    if (title === "")
-        fail(`plan needs a title: ${usage}`);
-    const problem = bodyStructureProblem(body);
-    if (problem)
-        fail(`the --file body cannot be filed: ${problem}`);
-    return fileEntryWithBody(root, "plan", title, body);
+    return fileFromText(root, "plan", text, usage);
 }
 /** `tumwater bug --file`: the bug twin of filePlanFromText, under BUGS.md's `## Open`. */
 export function fileBugFromText(root, text, usage) {
-    const { title, body } = splitEntryFile(text);
-    if (title === "")
-        fail(`bug needs a symptom: ${usage}`);
-    const problem = bodyStructureProblem(body);
-    if (problem)
-        fail(`the --file body cannot be filed: ${problem}`);
-    return fileEntryWithBody(root, "bug", title, body);
+    return fileFromText(root, "bug", text, usage);
 }
 /** The loop prompt a filed bug wakes the `bugfix` loop with — one wording for the CLI's
  * `tumwater bug` and the dashboard's backlog-file endpoint. */
 export function bugWakeText(title) {
-    return `Operator filed a new bug with \`tumwater bug\`: "${title}" — it is under BUGS.md ## Open; fix it.`;
+    return `The user filed a new bug with \`tumwater bug\`: "${title}" — it is under BUGS.md ## Open; fix it.`;
 }
 /** The loop prompt a requested plan wakes the `feature` loop with, shared like bugWakeText. */
 export function planWakeText(title) {
-    return `Operator requested a plan with \`tumwater plan\`: "${title}" — it is under PLANS.md ## Planned; flesh out the plan stub.`;
+    return `The user requested a plan with \`tumwater plan\`: "${title}" — it is under PLANS.md ## Planned; flesh out the plan stub.`;
 }
 /** The loop each operator-filed kind wakes and the wording it wakes it with, keyed by the
  * kind the dashboard posts. */
@@ -434,26 +341,24 @@ function appendOperatorEntry(root, fileName, template, sectionTitle, title, body
     appendEntry(root, fileName, template, sectionTitle, `### ${title} (${stamp})`, body);
     return { file: fileName, title, stamp };
 }
-/** `tumwater bug "<symptom>"`: append one `### <symptom> (reported by the operator <date>)`
+/** `tumwater bug "<symptom>"`: append one `### <symptom> (reported by the user <date>)`
  * entry to BUGS.md's `## Open`. The symptom is operator prose, so it folds to one line
  * (collapseWhitespace, the questions answer precedent) — a multi-line raw text could carry
  * a `## `/`### ` line and grow a phantom section no reader wrote. An empty symptom fails
  * with the usage line and writes nothing. */
 export function fileBug(root, rawText, usage) {
     const symptom = collapseWhitespace(rawText);
-    if (symptom === "")
-        fail(`bug needs a symptom: ${usage}`);
+    requireEntryTitle("bug", symptom, usage);
     return appendOperatorEntry(root, "BUGS.md", BUGS_TEMPLATE, "Open", symptom, "");
 }
-/** `tumwater plan "<title>" [body...]`: append one `### <title> (reported by the operator
+/** `tumwater plan "<title>" [body...]`: append one `### <title> (reported by the user
  * <date>)` entry to PLANS.md's `## Planned`, with the optional body as the entry text. No
  * goal/approach/acceptance-criteria scaffolding is invented — the feature loop's
  * plan-refinement pass fleshes the stub out on pickup. An empty title fails with the usage
  * line and writes nothing. */
 export function filePlan(root, rawTitle, rawBody, usage) {
     const title = collapseWhitespace(rawTitle);
-    if (title === "")
-        fail(`plan needs a title: ${usage}`);
+    requireEntryTitle("plan", title, usage);
     return appendOperatorEntry(root, "PLANS.md", PLANS_TEMPLATE, "Planned", title, collapseWhitespace(rawBody));
 }
 /** `tumwater bug --cancel <n>`: remove the nth entry from BUGS.md's `## Open`, as
@@ -466,28 +371,29 @@ export function cancelBug(root, n) {
 export function cancelPlan(root, n) {
     return removeEntry(root, "PLANS.md", "Planned", n);
 }
+/** The `--edit <n> --file` form shared by plan and bug: split the file, strip a pasted-back
+ * heading's own stamp, and require a title and structurally-sound body before splicing into the
+ * kind's section (editEntry). editPlanFromText and editBugFromText are the public plan/bug twins
+ * routing through it, so the two cannot drift. */
+function editFromText(root, kind, n, text, usage) {
+    const { title: rawTitle, body } = splitEntryFile(text);
+    // A first line pasted back as the full heading carries the entry's stamp; the splice re-adds it.
+    const title = stripEntryStamp(rawTitle);
+    requireEntryTitle(kind, title, usage);
+    requireBodyStructurallySound(body, "written");
+    const target = backlogTarget(kind);
+    return editEntry(root, target.fileName, target.sectionTitle, n, title, body);
+}
 /** `tumwater plan --edit <n> --file`: rewrite the nth `## Planned` entry from a markdown file,
  * title and body kept line for line (splitEntryFile), position and original stamp kept. A body
  * that would grow a phantom section writes nothing. */
 export function editPlanFromText(root, n, text, usage) {
-    const { title, body } = splitEntryFile(text);
-    if (title === "")
-        fail(`plan needs a title: ${usage}`);
-    const problem = bodyStructureProblem(body);
-    if (problem)
-        fail(`the --file body cannot be written: ${problem}`);
-    return editEntry(root, "PLANS.md", "Planned", n, title, body);
+    return editFromText(root, "plan", n, text, usage);
 }
 /** `tumwater bug --edit <n> --file`: the bug twin of editPlanFromText over `## Open`. The body is
  * written as the file gives it, so a bug filed with `--file` can be revised with its body. */
 export function editBugFromText(root, n, text, usage) {
-    const { title, body } = splitEntryFile(text);
-    if (title === "")
-        fail(`bug needs a symptom: ${usage}`);
-    const problem = bodyStructureProblem(body);
-    if (problem)
-        fail(`the --file body cannot be written: ${problem}`);
-    return editEntry(root, "BUGS.md", "Open", n, title, body);
+    return editFromText(root, "bug", n, text, usage);
 }
 /** `tumwater bug --edit <n> "<symptom>"`: replace the nth BUGS.md `## Open` entry's heading
  * text with the new symptom, keeping its position and its original `(reported by …)` stamp.
@@ -496,8 +402,7 @@ export function editBugFromText(root, n, text, usage) {
  * body, so the rebuilt entry is its heading alone. */
 export function editBug(root, n, rawText, usage) {
     const symptom = collapseWhitespace(rawText);
-    if (symptom === "")
-        fail(`bug needs a symptom: ${usage}`);
+    requireEntryTitle("bug", symptom, usage);
     return editEntry(root, "BUGS.md", "Open", n, symptom, "");
 }
 /** `tumwater plan --edit <n> "<title>" [body...]`: replace the nth PLANS.md `## Planned`
@@ -506,148 +411,121 @@ export function editBug(root, n, rawText, usage) {
  * phantom section; an empty title fails with the usage line and writes nothing. */
 export function editPlan(root, n, rawTitle, rawBody, usage) {
     const title = collapseWhitespace(rawTitle);
-    if (title === "")
-        fail(`plan needs a title: ${usage}`);
+    requireEntryTitle("plan", title, usage);
     const body = collapseWhitespace(rawBody);
     return editEntry(root, "PLANS.md", "Planned", n, title, body);
 }
-/** The shared shell of the `bug --cancel` and `plan --cancel` CLI cases, mirroring
- * fileAndAnnounce's flag handling: `--cancel <n>` is the one valued flag, `--json` the one
- * boolean (at most once), `--help`/`-h` tolerated; any positional or other flag is refused
- * through rejectUnknownArgs. The position parses through the plain-decimal rule every position
- * flag shares (parsePositionFlag, cli-args.ts), not Number(). After requireReadyRepo it prints
- * `cancelled <command> in <file>: <title>` or the `--json` payload {file, title}. Unlike
- * fileAndAnnounce there is no wake: removing work must not wake a loop. */
-export async function cancelAndAnnounce(root, args, command, cancel) {
-    let position = null;
-    let json = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--cancel") {
-            rejectRepeatFlag(position !== null, "--cancel");
-            position = parsePositionFlag("--cancel", args[i + 1], "--cancel 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
-    // rejectUnknownArgs names both a stray positional and an unknown flag, with this command's
-    // (empty) valid-flag list — the vocabulary a cancel invocation accepts is exactly --cancel
-    // and --json, both consumed above.
-    rejectUnknownArgs(command, rest, []);
-    if (position === null)
-        fail(`--cancel needs a position (usage: tumwater ${command} --cancel <n>)`);
-    await requireReadyRepo(root);
-    const removed = cancel(position);
-    if (json)
-        sayJson({ file: removed.file, title: removed.title });
-    else
-        say(`cancelled ${command} in ${removed.file}: ${removed.title}`);
-}
-/** The shared shell of the `bug --list` and `plan --list` CLI cases — the read half of the
- * operator queue whose `--edit`/`--cancel` flags address entries by position. Reads the same
- * entries, in the same file order, that locateEntry numbers for `--edit`/`--cancel`, pairs
- * each with its eligibility hold (backlogHolds), and prints them numbered from 1, or the
- * command's `no …` line on an empty or missing file. Like `tumwater backlog` and `tumwater
- * questions` it is read-only: no requireReadyRepo gate and no wake. `--list` and `--json` are
- * the two booleans this shell consumes (repeats refused), `--help`/`-h` is tolerated, and any
- * positional or other flag is refused through rejectUnknownArgs. */
-export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
-    let json = false;
-    let list = false;
-    const rest = [];
-    for (const arg of args) {
-        if (arg === "--list") {
-            rejectRepeatFlag(list, "--list");
-            list = true;
-            continue;
-        }
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
-    // rejectUnknownArgs names a stray positional and an unknown flag with this command's (empty)
-    // valid-flag list: the vocabulary a list invocation accepts is exactly --list and --json,
-    // both consumed above.
-    rejectUnknownArgs(command, rest, []);
-    // BUGS.md's `## Open` is the one section whose noun is "bug"; every other caller is a plan.
-    const bugSection = sectionTitle === "Open";
-    const entries = bugSection ? openBugEntries(root) : plannedPlanEntries(root);
-    const holds = backlogHolds(root);
-    const entryHolds = bugSection ? holds.bugs : holds.plans;
-    if (json) {
-        sayJson({
-            entries: entries.map((entry, i) => ({
-                position: i + 1,
-                title: entry.title,
-                body: entry.body,
-                hold: entryHolds[i] ?? null,
-            })),
-        });
-        return;
-    }
-    const noun = sectionNoun(sectionTitle);
-    if (entries.length === 0) {
-        say(`no ${noun}s`);
-        return;
-    }
-    const numbered = entries.map((entry, i) => `${entry.title}${holdMark(entryHolds[i] ?? null)}`);
-    say(`${noun}s in ${fileName}:\n${numberedList(numbered)}`);
-}
-/** The shared shell of the `bug --edit` and `plan --edit` CLI cases, mirroring
- * fileAndAnnounce's prose classification and cancelAndAnnounce's flag handling: `--edit <n>` is
- * the one valued flag, `--json` the one boolean (at most once), `--help`/`-h` ride into the new
- * text, and any other flag-shaped token is refused through rejectUnknownArgs. Unlike cancel,
- * what remains after the flags is the new text the callback folds to one line (so a `## `/`### `
- * line quoted in it can never grow a phantom section). After requireReadyRepo it prints
- * `edited <command> in <file>: <title>` or the `--json` payload {file, title}. Unlike
- * fileAndAnnounce there is no wake: an edit adds no work for a loop to pick up. With
- * `--file <path>` (`-` reads stdin) the new entry comes from a markdown file instead of
- * positionals: `editText` receives its text, and any positional alongside --file is refused. */
-export async function editAndAnnounce(root, args, command, edit, editText) {
-    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);
-    if (path !== null)
-        rejectRepeatFlag(rest.includes("--file"), "--file");
-    const { json, positionals, position } = scanProseFlags(rest, command, {
-        name: "--edit",
-        example: "--edit 2",
+/** 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. False (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 = withoutWaitingNotes(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 withStateLock(primaryWorktreeLockPath(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 };
     });
-    if (path !== null) {
-        const stray = positionals[0];
-        if (stray !== undefined)
-            fail(`unexpected argument ${JSON.stringify(stray)} — with --file the entry comes from the file`);
+}
+/** Lift the Refused or Waiting for the next failure 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 withStateLock(primaryWorktreeLockPath(root), () => {
+        const { file, lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
+        if (!liftRefusal(lines, entry))
+            fail(`${kind} #${n} "${entry.title}" carries no Refused or Waiting for the next failure note`);
+        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 withStateLock(primaryWorktreeLockPath(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("");
     }
-    if (position === null)
-        fail(`--edit needs a position (usage: tumwater ${command} --edit <n>)`);
-    await requireReadyRepo(root);
-    const edited = path === null ? edit(position, positionals) : editText(position, readPromptFileArg(path));
-    if (json)
-        sayJson({ file: edited.file, title: edited.title });
-    else
-        say(`edited ${command} in ${edited.file}: ${edited.title}`);
-}
-/** One confirmation for both file commands, prose or `--json`: the JSON branch prints the
- * {file, title, stamp} payload as data, the prose branch one line naming the command, the
- * file, and the entry title. Private to this module — cli.ts reaches it through
- * fileAndAnnounce, the shared shell both file commands' CLI cases run through. */
-function sayFiled(command, filed, json) {
-    if (json)
-        sayJson({ file: filed.file, title: filed.title, stamp: filed.stamp });
-    else
-        say(`filed ${command} in ${filed.file}: ${filed.title}`);
+    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 withStateLock(primaryWorktreeLockPath(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 };
+    });
+}
+/** The nth entry as the markdown file `--edit <n> --file` reads back: the stamp-stripped title
+ * and the body with its indentation kept (read from the raw lines, not the trimmed
+ * BacklogEntry.body), plus the entry's eligibility hold. Read-only. */
+export function showEntry(root, kind, n) {
+    const { fileName, sectionTitle } = backlogTarget(kind);
+    const { lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
+    const meta = headingMetadata(lines, entry.start - 1);
+    const title = collapseWhitespace(stripEntryStamp(meta.text.replace(/^### /, "")));
+    const body = normalizeEntryBody(lines.slice(meta.next, entry.end).join("\n"));
+    const holds = backlogHolds(root);
+    const hold = (kind === "bug" ? holds.bugs : holds.plans)[n - 1] ?? null;
+    return { position: n, title, body, hold };
 }