tumwater 0.1.2 → 0.2.0

package/dist/src/backlog/backlog.js

@@ -1,13 +1,13 @@
 import path from "node:path";
 import { cachedTextByStat } from "../files/stat-cache.js";
-import { entryDates, parseEntryDetails } from "./backlog-md.js";
+import { entryDates, finishedArchiveOf, lastDate, parseEntryDetails } from "./backlog-md.js";
 /** The stat-cached file readers of the project backlog data shown on both dashboards: planned
  * features (PLANS.md), open bugs (BUGS.md), and open questions (QUESTIONS.md). These are tracked
- * markdown that loops edit, so readers must never show a stale entry — but the dashboards poll
- * them every second while the files change only when a loop lands an edit. Each reader therefore
- * serves an unchanged file from a stat-keyed cache: one syscall per file per poll instead of
- * re-reading and re-parsing markdown that grows without bound over the project's lifetime
- * (PLANS/BUGS are append-only durable memory). Any write invalidates it via dev/ino/mtime/size
+ * markdown that loops edit, so readers must never show a stale entry — but the dashboards poll them
+ * every second while the files change only when a loop merges an edit. Each reader therefore serves
+ * an unchanged file from a stat-keyed cache: one syscall per file per poll instead of re-reading
+ * and re-parsing markdown that grows without bound over the project's lifetime (PLANS/BUGS are
+ * append-only durable memory). Any write invalidates it via dev/ino/mtime/size
  * (stat-cache.cachedByStat, same freshness check as files/tail.ts's incremental log readers). The
  * pure markdown parsing underneath lives in src/backlog/backlog-md.ts — this module owns only
  * reading and caching. Each dashboard formats this data for its own surface (the TUI's lines live
@@ -29,26 +29,113 @@ function sectionEntries(root, fileName, sectionTitle) {
 /** Stat-keyed cache of the completion-date reads, keyed by file + section + date regex (each
  * completion section's verbs differ) and bounded inside cachedTextByStat like sectionCache. */
 const dateCache = new Map();
-/** Completion dates of an entry section (PLANS.md `## Done`, BUGS.md `## Fixed`), stat-cached
- * like sectionEntries above. The usage report scans these sections on every /api/report fetch,
- * but the files change only when a loop lands an edit — serving an unchanged file from the
- * cache makes that cost one stat instead of a full read plus an O(size) markdown walk of
- * append-only documents that grow without bound. The date regex is part of the cache key
- * (each section's completion verbs differ); a missing or unreadable file yields []. */
+/** Completion dates of an entry section (PLANS.md `## Done`, BUGS.md `## Fixed`), stat-cached like
+ * sectionEntries above. The usage report scans these sections on every /api/report fetch, but the
+ * files change only when a loop merges an edit — serving an unchanged file from the cache makes
+ * that cost one stat instead of a full read plus an O(size) markdown walk of append-only documents
+ * that grow without bound. The date regex is part of the cache key (each section's completion verbs
+ * differ); a missing or unreadable file yields []. */
 export function sectionCompletionDates(root, fileName, sectionTitle, dateRe) {
     const file = path.join(root, fileName);
     return (cachedTextByStat(dateCache, `${file}\u0000${sectionTitle}\u0000${dateRe.source}\u0000${dateRe.flags}`, file, (md) => entryDates(md, sectionTitle, dateRe), (dates) => dates.slice()) ?? []);
 }
+/** Filing dates of an entry section (PLANS.md `## Planned` and `## Done`; BUGS.md `## Open`
+ * and `## Fixed`), stat-cached and detected exactly like sectionCompletionDates — the per-day
+ * filing twin of that completion read, but reading each entry's FIRST stamp date (entryDates'
+ * `first` mode) rather than the completion read's last-date: the filing date is the day the
+ * entry first opened, matching the canonical `filingDate` first-match that `plan|bug --list`
+ * and the doctor's unfixed-bug age use, so a later re-filing or a cross-reference
+ * ("found by … <early date>; found by … <later date>") cannot land the filing on the later day.
+ * Where the completion read keys its cache by the section
+ * date regex, this
+ * uses the module's fixed STAMP_DATE_RE, so the cache key carries a distinct `\u0000planned` marker
+ * instead (Plan adds and bug filings share the stamp verb set, so the section title alone cannot
+ * tell this read from a completion read of the same section). Every eligible heading carries its
+ * filing stamp in prose (`planned DATE`, `reported DATE`, `found by … DATE`), and the Usage view
+ * collects them per day so an operator can read net progress (opened vs done). A missing or
+ * unreadable file yields []. */
+export function sectionFilingDates(root, fileName, sectionTitle) {
+    const file = path.join(root, fileName);
+    return (cachedTextByStat(dateCache, `${file}\u0000${sectionTitle}\u0000planned`, file, (md) => entryDates(md, sectionTitle, STAMP_DATE_RE, true), (dates) => dates.slice()) ?? []);
+}
+/** The first `YYYY-MM-DD` after a `planned`/`reported`/`found by` stamp word in an entry heading:
+ * the filing date every eligible heading carries in prose (plans open with `(planned YYYY-MM-DD…)`,
+ * bugs with `(found by …)` or `(reported …)`), parsed so `plan|bug --list` shows how long an entry
+ * has waited, without opening the file. Read only the title — the whole heading, never the body,
+ * because the stamp is the entry's own and the body may name other dates.
+ * null when the heading carries no such clause. */
+const STAMP_DATE_RE = /(?:planned|reported|found by)\b[^)]*?\b(\d{4}-\d{2}-\d{2})/;
+export function filingDate(title) {
+    const m = STAMP_DATE_RE.exec(title);
+    return m ? m[1] : null;
+}
+/** The completion stamp of a `## Done` plan heading. */
+export const DONE_DATE_RE = /done (\d{4}-\d{2}-\d{2})/;
+// The completion verbs track the phrasing the harness's own loops actually write: the bugfix prompt
+// pins the date, not the verb, and the re-merge flow's own epitaph — "re-merged <date>" on an entry
+// whose first merge was rejected in review — is a completion the report must count (a rejected
+// merge is not a fix, the re-merge is). Body verbs without a date ("was fixed;") match nothing, and
+// a bare "merged <date>" stays out: headings mention sibling merges, and a sibling's date is not
+// this entry's. The completion stamp of a `## Fixed` bug heading. */
+export const FIXED_DATE_RE = /\b(?:re-landed|fixed|closed|resolved) (\d{4}-\d{2}-\d{2})/;
+/** The date a finished entry's heading records for `dateRe` (DONE_DATE_RE / FIXED_DATE_RE): its
+ * LAST match. Reads only the heading line, like filingDate; a date on a wrapped continuation
+ * line or in the body yields null. */
+export function completionDate(title, dateRe) {
+    return lastDate(title, dateRe);
+}
+/** Whole days between a filing stamp and `now`, floored at 0 so a future-dated entry reads as
+ * fresh (0d) rather than negative. Shared by the suffix and the `--list --json` `ageDays` field. */
+export function ageInDays(since, now = Date.now()) {
+    return Math.max(0, Math.floor((now - Date.parse(since)) / 86400000));
+}
+/** The ` · since YYYY-MM-DD (Nd)`/`(today)` tail a listing line gains for its entry's filing
+ * stamp — the one place the wording and the today/`Nd` choice live, so the plans/bugs list
+ * (entryAgeSuffix, stamp parsed by filingDate) and the questions list (questionAgeSuffix,
+ * parsed by questionFilingDate) cannot drift. `date` is the already-parsed stamp; the caller
+ * returns `""` for an undated heading. */
+export function ageSuffix(date, now = Date.now()) {
+    const n = ageInDays(date, now);
+    return ` · since ${date} (${n === 0 ? "today" : `${n}d`})`;
+}
+/** The ` · since YYYY-MM-DD (Nd)`/`(today)` tail an entry's listing line gains when its heading
+ * parses a filing stamp, else `""` — rendered through ageSuffix, the one place the age is
+ * worded (shared with the questions list's questionAgeSuffix). */
+export function entryAgeSuffix(title, now = Date.now()) {
+    const since = filingDate(title);
+    return since === null ? "" : ageSuffix(since, now);
+}
 /** Planned features: the `### ` headings under PLANS.md's `## Planned` section. Missing or
  * unreadable → []. */
 export function plannedPlans(root) {
     return sectionEntries(root, "PLANS.md", "Planned").map((e) => e.title);
 }
-/** Done plans: the `### ` headings under PLANS.md's `## Done` section. The bootstrap gate
- * (src/gates/bootstrap-gates.ts) counts these to decide when to latch bootstrap complete; the
- * stat-keyed cache means an unchanged PLANS.md costs one syscall per poll, not a re-read. */
+/** The finished entries of a live backlog file, newest first: its own finished section's
+ * (normally none — tumwater moves a finished entry to the archive as the change that finished it
+ * commits) followed by its archive file's (plans/backlog-archive.md). Both reads are stat-cached
+ * like every section read here. */
+function finishedEntries(root, file) {
+    const { section, archive } = finishedArchiveOf(file);
+    return [...sectionEntries(root, file, section), ...sectionEntries(root, archive, section)];
+}
+/** The files a live backlog file's finished entries sit in: the file itself, then its archive.
+ * The per-day date reads below are per file, so the report walks both. */
+export function finishedFiles(file) {
+    return [file, finishedArchiveOf(file).archive];
+}
+/** Done plans: the `### ` headings under `## Done` in PLANS.md and PLANS-DONE.md. The bootstrap
+ * gate (src/gates/bootstrap-gates.ts) counts these to decide when to latch bootstrap complete;
+ * the stat-keyed cache means unchanged files cost one syscall each per poll, not a re-read. */
 export function donePlans(root) {
-    return sectionEntries(root, "PLANS.md", "Done").map((e) => e.title);
+    return finishedEntries(root, "PLANS.md").map((e) => e.title);
+}
+/** Done plans as entries (title and body), newest first. */
+export function donePlanEntries(root) {
+    return finishedEntries(root, "PLANS.md");
+}
+/** Fixed bugs as entries (title and body), newest first. */
+export function fixedBugEntries(root) {
+    return finishedEntries(root, "BUGS.md");
 }
 /** Open bugs: the `### ` headings under BUGS.md's `## Open` section. Missing or unreadable →
  * []. */
@@ -74,6 +161,16 @@ export function openBugEntries(root) {
 export function openQuestionEntries(root) {
     return sectionEntries(root, "QUESTIONS.md", "Open");
 }
+/** Answered questions as full entries (title + body), in file order — oldest first, since
+ * tryAnswerQuestion appends. Missing or unreadable → []. */
+export function answeredQuestionEntries(root) {
+    return sectionEntries(root, "QUESTIONS.md", "Answered");
+}
+/** Whether an entry's heading or body contains `pattern`, ignoring case: the one matcher behind
+ * the finished-entry lists' `--grep`. */
+export function entryMatches(entry, pattern) {
+    return `${entry.title}\n${entry.body}`.toLowerCase().includes(pattern.toLowerCase());
+}
 /** The backlog as one machine-readable document: the three entry arrays the Markdown renderer
  * and the GUI's /api/backlog endpoint serve, so `tumwater backlog --json` prints the same data
  * every surface reads (status --json's "print the endpoint's payload" pattern). Each array keeps

package/dist/src/backlog/question-answer.js

@@ -0,0 +1,339 @@
+// vocabulary: plain
+/** The QUESTIONS.md reader/writer core — the shared home of the open-question outbox logic: listing
+ * the open questions in QUESTIONS.md and answering one, which moves its entry from `## Open` to
+ * `## Answered` with a dated operator answer. It does the markdown surgery — cut exactly one
+ * `### ` block (fence-aware, like every backlog reader in backlog-md.ts) and extend a missing
+ * `## Answered` section with the file's documented skeleton — so the loop→human→loop round trip
+ * never corrupts the file the loops read at their next tick. Pure: no subprocess and no CLI
+ * output helpers, so every surface can drive it without ending the process.
+ *
+ * Shared by every read/answer surface: the CLI's `tumwater questions` command body wraps it in
+ * src/cli/question-commands.ts (the say/fail/editor layer), while the TUI's answer box
+ * (src/ui/tui/tui-keys.ts) and the dashboard's POST route (src/gui/gui-endpoint-commands.ts)
+ * import the non-exiting answer core directly. It lives with the rest of the BUGS/PLANS/QUESTIONS
+ * markdown (src/backlog/), not under src/cli/, so the non-command surfaces never depend on the
+ * CLI command package for domain logic.
+ */
+import path from "node:path";
+import { fencedHeadingTitle, fenceTracker, nextSectionHeading } from "./backlog-md.js";
+import { answeredQuestionEntries, entryMatches, openQuestionEntries, ageInDays, ageSuffix } from "./backlog.js";
+import { normalizeEntryBody } from "./backlog-write.js";
+import { collapseWhitespace, trimLeadingBlankLines, trimTrailingBlankLines, truncate } from "../text/text.js";
+import { readTextOrNull, writeTextAtomic } from "../files/files.js";
+import { formatDate } from "../text/datetime.js";
+import { numberedList } from "../text/markdown.js";
+import { withStateLock } from "../concurrency/lock.js";
+import { primaryWorktreeLockPath } from "../paths.js";
+/** Cap on a question's one-line body preview, so one very long first line cannot dominate
+ * the `questions` list. */
+const BODY_PREVIEW_MAX = 100;
+/** The ` -- <ellipsized body>` suffix one prose list line carries for its question's first
+ * body line: the `prompt --list` numbered shape, so an operator can tell two open questions
+ * apart without opening the file. Truncated through text.ts's truncate — the one ellipsis
+ * rule — so the preview is never longer than BODY_PREVIEW_MAX and never splits a surrogate
+ * pair. Omitted for a heading-only entry. */
+function firstBodySuffix(body) {
+    const line = body
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l !== "");
+    if (line === undefined)
+        return "";
+    return ` — ${truncate(line, BODY_PREVIEW_MAX)}`;
+}
+/** The open question's filing stamp, `YYYY-MM-DD`, read from the heading's `(asked by <who>
+ * YYYY-MM-DD)` clause — the first `YYYY-MM-DD` after an `asked by` word in the title text — or
+ * null when the heading carries no such clause. Taken from the title text only, not the body:
+ * the stamp is the entry's own, and the body may name other dates. */
+export function questionFilingDate(title) {
+    const m = /(?:asked by)\b[^)]*?\b(\d{4}-\d{2}-\d{2})/.exec(title);
+    return m === null ? null : m[1];
+}
+/** The role id named in the heading's `(asked by <role> …)` clause — the first word after
+ * `asked by` — or null when the heading has no such clause. Taken from the title only, like
+ * questionFilingDate. */
+export function questionAsker(title) {
+    const m = /\(asked by ([A-Za-z0-9_-]+)/.exec(title);
+    return m === null ? null : m[1];
+}
+/** The ` · since <date> (…)` suffix naming how long an open question has waited for an answer,
+ * from its heading's stamp (see questionFilingDate), or "" when the heading is undated —
+ * rendered through backlog.ts's ageSuffix, the one place the wording lives (shared with the
+ * plans/bugs list's entryAgeSuffix), which floors at 0 through ageInDays so a future stamp
+ * reads `(today)`. */
+export function questionAgeSuffix(title, now = Date.now()) {
+    const date = questionFilingDate(title);
+    return date === null ? "" : ageSuffix(date, now);
+}
+/** `tumwater questions` with no arguments: the open questions numbered from 1 in file order,
+ * one line each (`prompt --list`'s shape), or one line when none are open. Reads through
+ * openQuestionEntries, so a missing or unreadable QUESTIONS.md degrades to "no open
+ * questions" like every backlog reader. */
+export function openQuestionList(root) {
+    const questions = openQuestionEntries(root);
+    if (questions.length === 0)
+        return "no open questions";
+    return numberedList(questions.map((q) => `${q.title}${questionAgeSuffix(q.title)}${firstBodySuffix(q.body)}`));
+}
+/** The Nth (1-based) open question in the shape of one `questionListPayload` entry, or null
+ * past the end: the reader behind `tumwater questions --show <n>`. */
+export function openQuestionAt(root, n) {
+    return questionListPayload(root).questions[n - 1] ?? null;
+}
+/** One question as `questions --show` prints it: the heading, a blank line, then the body
+ * (the heading alone when the body is empty). */
+export function renderShownQuestion(q) {
+    return q.body === "" ? q.title : `${q.title}\n\n${q.body}`;
+}
+/** The same list as data for `--json` (the backlog --json pattern: a JSON document in every
+ * exit-0 case, never prose): each entry's 1-based position (the number `answer` consumes),
+ * its verbatim heading text, and its full body. */
+export function questionListPayload(root) {
+    return {
+        questions: openQuestionEntries(root).map((q, i) => {
+            const sent = {
+                position: i + 1,
+                title: q.title,
+                body: q.body,
+            };
+            const since = questionFilingDate(q.title);
+            if (since !== null) {
+                sent.since = since;
+                sent.ageDays = ageInDays(since);
+            }
+            return sent;
+        }),
+    };
+}
+/** The date in an answer stamp paragraph (`**Answered <date> by …`). */
+const ANSWER_DATE_RE = /\*\*Answered (\d{4}-\d{2}-\d{2})\b/;
+/** The first answer stamp's date in an answered entry's body, or null when it has none. The
+ * stamp is a body paragraph, so this reads the body, not the heading. */
+function answerDate(body) {
+    const m = ANSWER_DATE_RE.exec(body);
+    return m === null ? null : m[1];
+}
+/** The first body line that starts with `**Answered `, markup stripped, whitespace collapsed
+ * and truncated; "" when no line matches. */
+function answerPreview(body) {
+    const line = body.split("\n").map((l) => l.trim()).find((l) => l.startsWith("**Answered "));
+    if (line === undefined)
+        return "";
+    return truncate(collapseWhitespace(line.replaceAll("**", "")), BODY_PREVIEW_MAX);
+}
+/** The newest `count` answered questions, newest first (the file appends, so it is reversed),
+ * each with its unfiltered newest-first position, and how many older matches were left out.
+ * A `pattern` keeps only the entries whose heading or body contains it (entryMatches). */
+function answeredQuestionsNewestFirst(root, count, pattern) {
+    const numbered = answeredQuestionEntries(root).reverse().map((e, i) => ({ ...e, position: i + 1 }));
+    const all = pattern === undefined ? numbered : numbered.filter((e) => entryMatches(e, pattern));
+    return { entries: all.slice(0, count), older: Math.max(0, all.length - count) };
+}
+/** `tumwater questions --answered`: lines numbered by `--show <n> --answered` position, newest
+ * first — a numbering separate from the `## Open` positions `questions answer <n>` takes. */
+export function answeredQuestionList(root, count, pattern) {
+    const { entries, older } = answeredQuestionsNewestFirst(root, count, pattern);
+    if (entries.length === 0)
+        return pattern === undefined ? "no answered questions" : `no answered questions match "${pattern}"`;
+    const lines = [
+        pattern === undefined
+            ? "answered questions in QUESTIONS.md, newest first:"
+            : `answered questions in QUESTIONS.md matching "${pattern}", newest first:`,
+    ];
+    for (const e of entries) {
+        const preview = answerPreview(e.body);
+        lines.push(`${e.position}. ${e.title}${preview === "" ? "" : ` — ${preview}`}`);
+    }
+    if (older > 0)
+        lines.push(`(${older} older; -n <count> shows more)`);
+    return lines.join("\n");
+}
+/** The Nth (1-based) newest answered question, or null past the end: the reader behind
+ * `tumwater questions --show <n> --answered`. */
+export function answeredQuestionAt(root, n) {
+    const e = answeredQuestionEntries(root).reverse()[n - 1];
+    return e === undefined ? null : { position: n, title: e.title, body: e.body, answeredOn: answerDate(e.body) };
+}
+/** How many answered questions QUESTIONS.md holds. */
+export function answeredQuestionCount(root) {
+    return answeredQuestionEntries(root).length;
+}
+/** The same list as data for `--json`. */
+export function answeredQuestionPayload(root, count, pattern) {
+    const { entries, older } = answeredQuestionsNewestFirst(root, count, pattern);
+    return {
+        questions: entries.map((e) => ({ position: e.position, title: e.title, body: e.body, answeredOn: answerDate(e.body) })),
+        older,
+    };
+}
+/** The dashboard's compact form of the `--answered` list: the same titles and truncated
+ * `**Answered …` lines, newest first, without bodies so each poll stays small. */
+export function answeredQuestionSummaries(root, count) {
+    return answeredQuestionsNewestFirst(root, count).entries.map((e) => ({ title: e.title, decision: answerPreview(e.body) }));
+}
+/** Locate QUESTIONS.md's `## Open` and `## Answered` section heading lines (fence-aware) and
+ * every open entry's block between them. Returns null when the file has no `## Open` section
+ * at all — then there is nothing to answer, whatever the position. */
+function scanQuestions(lines) {
+    const fenced = fenceTracker();
+    let openIdx = -1;
+    let answeredIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const title = fencedHeadingTitle(line, fenced, "## ");
+        if (title !== null) {
+            if (title === "Open" && openIdx === -1)
+                openIdx = i;
+            else if (title === "Answered" && answeredIdx === -1)
+                answeredIdx = i;
+        }
+    }
+    if (openIdx === -1)
+        return null;
+    // A fresh tracker for this walk: the first loop consumed every line and left the tracker in
+    // its end-of-file state, so reusing it here would quote all Open headings whenever a fence
+    // after the Open section runs unclosed to EOF — and `answer` would refuse a question the
+    // list just showed.
+    const fencedBlocks = fenceTracker();
+    // The section's end is the next `## ` heading of ANY title, fence-aware — the same boundary
+    // rule sectionLines applies, so the entries `--list` numbers (sectionEntries →
+    // parseEntryDetails) and the blocks `answer` moves can never disagree about where Open
+    // stops. Ending at the first `## Answered` instead would run the walk through any
+    // intermediate section and let one answer move another section's entries.
+    const openEnd = nextSectionHeading(lines, openIdx + 1, fencedBlocks);
+    const blocks = [];
+    // A fresh tracker for this walk too: the openEnd walk consumed the lines up to the section's
+    // end, so a fence in Open left unclosed at that boundary (an unclosed fence runs openEnd to
+    // EOF) would leave the shared tracker inside and quote every `### ` heading — answer would
+    // then see no blocks, or answer a later entry, on a file `--list` just numbered.
+    const fencedEntries = fenceTracker();
+    let current = null;
+    for (let i = openIdx + 1; i < openEnd; i++) {
+        const line = lines[i] ?? "";
+        const entryTitle = fencedHeadingTitle(line, fencedEntries, "### ");
+        if (entryTitle !== null) {
+            if (current !== null)
+                current.end = i;
+            current = { start: i, end: openEnd, title: entryTitle };
+            blocks.push(current);
+        }
+    }
+    return { openIdx, answeredIdx, openEnd, fenceOpen: fencedEntries.open(), blocks };
+}
+export const UNCLOSED_FENCE_MESSAGE = "QUESTIONS.md's ## Open section holds an unclosed code fence — every reader quotes the rest of the file as that entry's body, so answering would corrupt the file; close or remove the fence and re-run";
+/** The non-exiting answer core, for callers (the dashboard server) that must not end the process:
+ * runs the whole read-modify-write under the cross-process primary-worktree lock (paths.ts), shared
+ * with `tumwater bug`/`plan` and a merge's working-tree fast-forward, so an answer and a merged
+ * change to QUESTIONS.md cannot each overwrite the other's whole-file write. With `expectedTitle`,
+ * a block at position `n` titled otherwise is `moved` and nothing is written; the comparison runs
+ * inside the lock, after the scan. */
+export function tryAnswerQuestion(root, n, rawDecision, expectedTitle, keepLines = false) {
+    return withStateLock(primaryWorktreeLockPath(root), () => answerQuestionLocked(root, n, rawDecision, expectedTitle, keepLines));
+}
+/** `tumwater questions answer <n> <decision>`: move the Nth open question's full block —
+ * heading plus body, verbatim — from `## Open` to the end of `## Answered`, followed by a
+ * `**Answered <today> by the user:** <decision>` paragraph stamped with the local date — the
+ * positional decision is free-form operator prose, so it folds to one line (collapseWhitespace,
+ * the pause `--reason` precedent): verbatim multi-line text could carry a line that starts with
+ * `## ` or `### ` and grow a phantom section no reader wrote. The `--file` form (`keepLines`)
+ * keeps the lines, behind bodyStructureProblem — the guard `plan --file` uses — applied by its
+ * caller; a multi-line decision follows the stamp after a blank line. The Open section that is
+ * left empty regains its `_None yet._` placeholder; a file with no `## Answered` section gains
+ * one. Returns the outcome (see `AnswerOutcome`); on `answered` the title for the confirmation
+ * line, plus the collapsed decision that actually went into the file so callers report what was
+ * written rather than the caller's raw whitespace. */
+function answerQuestionLocked(root, n, rawDecision, expectedTitle, keepLines) {
+    const decision = keepLines ? normalizeEntryBody(rawDecision) : collapseWhitespace(rawDecision);
+    const file = path.join(root, "QUESTIONS.md");
+    const md = readTextOrNull(file);
+    const lines = md === null ? null : md.split("\n");
+    const scan = lines === null ? null : scanQuestions(lines);
+    const openCount = scan === null ? 0 : scan.blocks.length;
+    if (scan === null || n < 1 || n > scan.blocks.length) {
+        return { status: "missing", open: openCount };
+    }
+    const scanned = scan;
+    // A fence inside ## Open left unclosed runs to EOF (CommonMark), so the whole tail — the
+    // real ## Answered section included — reads as quoted body of the still-open entry. Acting
+    // on that degraded read moves Answered content inside the moved block's fence and grows a
+    // second ## Answered at the file's end, while the question still lists as open: refuse
+    // instead, and tell the operator the one local repair (close or remove the fence).
+    if (scanned.fenceOpen) {
+        return { status: "fenced" };
+    }
+    const block = scanned.blocks[n - 1];
+    if (expectedTitle !== undefined && block.title !== expectedTitle)
+        return { status: "moved", title: block.title };
+    const moved = lines.slice(block.start, block.end);
+    trimTrailingBlankLines(moved);
+    // Cut the block out of ## Open: everything before it, everything from its end on. When the
+    // section is left with no content at all, restore the `_None yet._` placeholder the skeleton
+    // carries, so an empty outbox still reads as an intentionally empty section.
+    // Emptiness is judged against the Open section only (openIdx+1 .. openEnd): with an
+    // intermediate section between Open and Answered, judging against answeredIdx would keep
+    // the placeholder from returning and, worse, the empty rebuild would drop that section.
+    const openContent = lines.slice(scanned.openIdx + 1, scanned.openEnd);
+    const remaining = openContent.filter((_, i) => i < block.start - scanned.openIdx - 1 || i >= block.end - scanned.openIdx - 1);
+    const openEmpty = remaining.every((l) => l.trim() === "");
+    const rebuilt = [];
+    if (openEmpty) {
+        rebuilt.push(...lines.slice(0, scanned.openIdx + 1), "", "_None yet._", 
+        // Resume at the section that followed Open (openEnd, not answeredIdx — an intermediate
+        // section between the two must survive) with the blank separator line the dropped Open
+        // content used to carry, so `_None yet._` never reads as a paragraph glued to a heading.
+        "", ...lines.slice(scanned.openEnd));
+    }
+    else {
+        rebuilt.push(...lines.slice(0, block.start), ...lines.slice(block.end));
+    }
+    // Append the block at the end of ## Answered: before the next `## ` heading when one
+    // follows, at the file's end otherwise — the section is last in the documented skeleton.
+    const stamp = `**Answered ${formatDate(new Date())} by the user:**`;
+    const stamped = decision.includes("\n") ? [stamp, "", ...decision.split("\n")] : [`${stamp} ${decision}`];
+    const answerLines = moved.concat("", ...stamped, "");
+    if (scanned.answeredIdx === -1) {
+        // No ## Answered section: grow the file's end with the skeleton section plus the block.
+        let out = rebuilt.join("\n");
+        if (out !== "" && !out.endsWith("\n"))
+            out += "\n";
+        out += `\n## Answered\n\n${answerLines.join("\n")}`;
+        writeTextAtomic(file, out);
+        return { status: "answered", title: block.title, decision };
+    }
+    const fenced2 = fenceTracker();
+    let answeredAt = -1;
+    const placeholderAt = [];
+    for (let i = 0; i < rebuilt.length; i++) {
+        const line = rebuilt[i] ?? "";
+        if (fenced2.inside(line))
+            continue;
+        if (answeredAt === -1) {
+            if (fencedHeadingTitle(line, fenced2, "## ") === "Answered")
+                answeredAt = i;
+        }
+        else if (fencedHeadingTitle(line, fenced2, "## ") !== null) {
+            break; // The Answered section's end: a placeholder beyond it is another section's.
+        }
+        else if (line.trim() === "_None yet._") {
+            placeholderAt.push(i);
+        }
+    }
+    // A section holding only its `_None yet._` skeleton placeholder must lose the placeholder when a
+    // real entry goes there: the placeholder means "no entries", so leaving it above the moved
+    // block makes ## Answered claim to be empty while holding an answered question. Fence-aware: a
+    // `_None yet._` line quoted inside a fenced block is quoted content, never the placeholder.
+    if (placeholderAt.length > 0) {
+        const dropped = new Set(placeholderAt);
+        const stripped = rebuilt.filter((_, i) => !dropped.has(i));
+        rebuilt.length = 0;
+        rebuilt.push(...stripped);
+    }
+    const insertAt = nextSectionHeading(rebuilt, answeredAt + 1, fenced2);
+    const head = rebuilt.slice(0, insertAt);
+    const tail = rebuilt.slice(insertAt);
+    trimTrailingBlankLines(head);
+    trimLeadingBlankLines(tail);
+    const result = head.concat("", answerLines, tail);
+    writeTextAtomic(file, result.join("\n"));
+    return { status: "answered", title: block.title, decision };
+}