tumwater 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the tumwater authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# tumwater
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+tumwater is an opinionated autonomous development harness built on
+[pi](https://github.com/badlogic/pi-mono). You write a short project brief, and a fleet of
+role-driven loops (feature, bugfix, planning, tests, cleanup, docs, and more) builds the project
+one small, reviewed commit at a time. It came from wanting to write only the brief and let a team
+of always-on specialists do the rest: each loop owns one concern, lands one change per tick,
+sleeps when it has nothing to do, and wakes when main moves. All project state lives in the
+local git repo, and no remote is ever touched.
+
+![The tumwater web dashboard running tumwater's own fleet: a sidebar with the project, its fleet status, the Fleet, History, Usage, Failures, and Settings views, today's spend against the cap, and the pause control; an alert that the running build is behind main; the director prompt box; today's progress (loops in flight, commits landed, ticks, open backlog); and the loops grouped by what they are doing, each with its status, current work or last result, spend, and controls](docs/gui.png)
+
+## Status
+
+<!-- tumwater:status:start -->
+**v0.1**: working harness. All 13 roles and the director are enabled by default.
+
+Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
+[QUESTIONS.md](QUESTIONS.md) (open questions).
+<!-- tumwater:status:end -->
+
+## Usage
+
+```bash
+npm install -g tumwater     # or run any command with npx tumwater
+                            # from a checkout: npm install && npm run build && npm link
+cd your-project             # a new or existing directory
+tumwater init "Build a tiny markdown-to-html converter CLI in Python."
+                            # add --template <id> to seed from a bundled starting point
+                            # (blank, python-cli, node-cli, static-site); --list-templates
+                            # prints the catalog
+                            # add --file <path> to read the brief from a file
+                            # add --adopt to adopt an existing repo as-is
+tumwater run                # start the loops (Ctrl+C to stop)
+```
+
+Then, from another terminal:
+
+| To | Run |
+| --- | --- |
+| Watch the fleet | `tumwater tui`, or `tumwater gui` for the browser dashboard at http://127.0.0.1:7180 |
+| Watch per-tick history | `tumwater history [--role <id>] [-n N] [--since <duration>] [--grep <text>]`, or `tumwater history --json` for the rows as JSON; `tumwater tick <role> <n>` for one tick's full event trail (a summary header — when it ran, how long, result, usage — followed by the tick's events, oldest first; `--json` prints the payload as JSON, `null` when the log holds no such tick) |
+| Check state | `tumwater status`, `tumwater logs -f`, `tumwater logs --since <duration>`, `tumwater logs --grep <text>`, `tumwater logs --json` (the event feed as NDJSON, for scripts), `tumwater logs --role <id>`, `tumwater backlog` (planned features, open bugs, open questions as Markdown), `tumwater backlog --json` (the backlog as JSON, for scripts), `tumwater role <id>` (one loop's standing prompt — find text, `instructions` override, resolved model and interval, enabled/paused state — plus its next tick's assembled prompt, which shows the oldest queued prompt without consuming it (one is dequeued per tick; `--json` for scripts)) |
+| See a loop's pending change | `tumwater diff --role <id>` — that loop's branch's unlanded commits (with the patch) and its worktree's uncommitted edits (staged and unstaged); without `--role`, one line per loop holding pending work; `--json` prints the payload as data |
+| Steer the project | `tumwater prompt "prefer no third-party deps"` queues a request for the director; add `--role <id>` to aim it at one loop's next tick, `tumwater prompt --list` shows the queued prompts numbered and grouped by loop, with how long each has waited (`--json` for scripts), and `tumwater prompt --cancel <n>` removes the Nth entry as `--list` shows them (add `--role <id>` when several loops share that number) |
+| Answer open questions | `tumwater questions` lists QUESTIONS.md's open questions numbered (as the loops wrote them); `tumwater questions answer <n> "decision text"` moves the Nth entry to ## Answered with your dated answer (loops read the file back on their next tick); `--json` prints the list as data |
+| Control the loops | `tumwater pause [--for <duration>]` / `resume [--role <id>]` (fleet or one loop; `--for 2h` auto-resumes, capped at 90d; add `--reason <text>` on a fleet pause to state why — it shows on `status`, the TUI, and the dashboard), `tumwater wake` (skip backoff), `tumwater abort --role <id>`, `tumwater stop` (drain and exit, like Ctrl+C) |
+| Audit | `tumwater doctor` (pre-flight; `--json` prints the report as JSON, for scripts), `tumwater report` (usage and cost; totals include landing runs — reviewer + conflict resolution), `tumwater report --since <duration>` (totals over a trailing window, capped at 7d), `tumwater report --json` (the `--days`/`--since`/`--failures` reports as JSON, for scripts), `tumwater report --failures` (the failure digest: per-role outcomes, each role's time and spend by outcome, and the top five loss causes ranked by agent-hours, with a marker naming how many were cut) |
+
+`tumwater help` lists every command and flag; `tumwater help <command>` shows one command's usage. `gui --all-interfaces` exposes the dashboard, and
+with it the director prompt, to your whole network, so pair it with `--token <secret>`.
+
+Settings live in `tumwater.json`: enabled roles, model, intervals, the daily spend cap
+(`maxDailyCostUsd`, with optional per-role caps `maxDailyCostUsdPerRole` — a loop over its own
+cap starts no new ticks until the next local day or a live edit), a nightly `quietHours` window
+(e.g. `"23:00-07:00"` local time) during
+which role loops start no new ticks (the director is exempt), user-defined `customLoops`, and an
+optional `notify` shell command run when the fleet needs a human (a budget pause, a budget warning
+at 80% of the cap while the gate is still open, an error-streak
+breaker trip, a failed landing, a blocked restart — the command gets `TUMWATER_EVENT_TYPE`,
+`TUMWATER_EVENT_LOOP`, and `TUMWATER_EVENT_MESSAGE` in its environment).
+Edits apply live while the fleet runs.
+From the terminal, `tumwater config` prints the effective config as JSON, `tumwater config get
+<key>` reads one resolved value, and `tumwater config set <key> <value>` writes one top-level
+key.
+
+**Backends:** any OpenAI-compatible model pi can reach works; set `provider` and `model` in
+`tumwater.json`. See [docs/backends.md](docs/backends.md) for requirements and a worked setup.
+
+For how the loops, review gate, scheduling, and self-redeploy work, see
+[docs/how-it-works.md](docs/how-it-works.md). For a measured comparison of tumwater's own
+code against human-written open source, see [docs/code-metrics.md](docs/code-metrics.md).
+
+## Appendix: initial prompt
+
+The brief this repository was started from, kept for history. The harness still reads it from
+between the markers below on every tick.
+
+<!-- tumwater:prompt:start -->
+Idea: agentic harness
+
+Opinionated. Built on pi. Lots of autonomous loops. You only write the markdown/initial prompt.
+It builds the project with immense effort. First puts the initial prompt and project status into
+README.md. Background loops are observable by gui/tui/log. GUI/TUI also gives user a main prompt.
+Loop sleeps a while when the prompt results in no further changes. Starts again after a while to
+see if the answer has changed due to the new state of the world. Each run attempts to find
+something to do, do one thing, commit, merge to main. The find-something-to-do part is role
+specific. Each loop has a role:
+
+- Make the code more organized
+- Increase unit test code coverage
+- Make the code cleaner
+- Make the code less repetitive
+- Implement a planned feature (tracked in PLANS.md)
+- Fix a bug (tracked in BUGS.md in repo)
+- Plan a feature (write markdown plan, add to PLANS.md)
+- Keep the README up to date
+- Make an improvement to the code
+
+Assumptions: run within a git repo dir. Each loop uses a persistent git workspace and branch.
+Each loop keeps itself synced up with git main. Don't involve git remotes at all; do everything
+locally and keep all project state within the git repo.
+<!-- tumwater:prompt:end -->

package/dist/build-info.json

@@ -0,0 +1,5 @@
+{
+  "sha": "4c69994273d9f4d707b0c5a6e7d00f50a3b265e6",
+  "builtAt": 1791110618512,
+  "root": "/home/runner/work/tumwater/tumwater"
+}

package/dist/src/backlog-structure.js

@@ -0,0 +1,166 @@
+import path from "node:path";
+import { readTextOrNull } from "./files.js";
+import { headingMetadata, sectionBodyLines, fenceAwareHeadingLines } from "./backlog.js";
+import { gitTry } from "./git.js";
+import { collapseWhitespace } from "./text.js";
+/** A heading's parenthetical dates: `(planned YYYY-MM-DD` opens a plan entry; `done
+ * YYYY-MM-DD` records its completion. Matched against the JOINED heading metadata
+ * (headingMetadata), never the bare first line — many headings wrap their dates onto a
+ * second line (`(planned 2026-09-02, done` / `2026-09-03)`). */
+const PLANNED_DATE = /\(planned \d{4}-\d{2}-\d{2}/;
+const DONE_DATE = /\bdone \d{4}-\d{2}-\d{2}/;
+/** The `### ` headings of `md`'s PLANS.md that sit under the wrong section, in file order:
+ * (a) entries under `## Done` whose heading carries a `(planned YYYY-MM-DD…)` parenthetical
+ * but no `done YYYY-MM-DD` — written as plans, never stamped done, and invisible to every
+ * Planned reader (`plannedPlanEntries` reads only `## Planned`); and (b) entries under
+ * `## Planned` whose heading already carries `done YYYY-MM-DD` — finished and never moved,
+ * so the feature loop may implement them again. Fence-aware through backlog.ts's shared
+ * machinery: a `### `/`## ` line inside a fenced code block is quoted content, not structure,
+ * and heading dates are matched against the same joined metadata entryDates matches against.
+ * BUGS.md and QUESTIONS.md are deliberately out of scope — their Fixed-section headings do
+ * not all carry a date suffix, so the same rule would misfire there. */
+export function strandedPlanEntries(md) {
+    const stranded = [];
+    // Each `## ` section is walked through backlog.ts's sectionLines — the single home of
+    // "where a section starts and ends", shared with entryDates' readers — so this scanner and
+    // the entry readers can never disagree about the boundary. Walking the section titles in
+    // file order (each occurrence once) keeps the output in document order, the same order the
+    // whole-document walk it replaced produced. Inside a section, the fence filter matches
+    // entryDates': a fenced `### ` line is quoted content, never an entry.
+    for (const section of sectionTitles(md)) {
+        if (section !== "Planned" && section !== "Done")
+            continue;
+        // Inside a section, the fence filter matches entryDates': a fenced `### ` line is quoted
+        // content, never an entry — the shared sectionBodyLines walk (backlog.ts).
+        const lines = sectionBodyLines(md, section);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            if (!line.startsWith("### "))
+                continue;
+            const { text } = headingMetadata(lines, i);
+            if (section === "Done" ? PLANNED_DATE.test(text) && !DONE_DATE.test(text) : DONE_DATE.test(text))
+                stranded.push({ title: line.slice(4).trim(), section });
+        }
+    }
+    return stranded;
+}
+/** A `### ` heading's comparison key: the heading text before its first ` (`, whitespace-
+ * normalized (text.ts's collapseWhitespace — the one home for this, shared with
+ * normalizeFixedHeading's BUGS.md counterpart below), so an entry that moved between
+ * sections with its dates intact keys equal on both sides of a diff. */
+function planHeadingKey(title) {
+    const cut = title.indexOf(" (");
+    return collapseWhitespace(cut === -1 ? title : title.slice(0, cut));
+}
+/** The comparison keys of every `### ` heading in `md`, in ANY `## ` section, fence-aware
+ * (backlog.ts's shared tracker). The base-side set for the new-plan-under-Done rule: an entry
+ * whose key the base already carried is a move between sections, never a stranding. */
+function planHeadingKeys(md) {
+    const keys = new Set();
+    for (const line of fenceAwareHeadingLines(md, "### ")) {
+        keys.add(planHeadingKey(line.slice(4).trim()));
+    }
+    return keys;
+}
+/** The backlog files every structural check covers — the tracked markdown loops edit and
+ * readers parse by `## ` section. */
+const BACKLOG_FILES = ["PLANS.md", "BUGS.md", "QUESTIONS.md"];
+/** The `## ` section titles of `md`, in file order, fence-aware (backlog.ts's shared tracker:
+ * a `## Done` quoted inside a fenced code block is body text, not structure). */
+function sectionTitles(md) {
+    return fenceAwareHeadingLines(md, "## ").map((line) => line.slice(3).trim());
+}
+/** How many times each `## ` title appears in `md` — the tally `duplicateHeadings` reports
+ * repeats from and `backlogStructureReason` compares head against base for both backlog
+ * files, so the three sites count sections through one helper and cannot drift apart. */
+function sectionTitleCounts(md) {
+    const counts = new Map();
+    for (const title of sectionTitles(md))
+        counts.set(title, (counts.get(title) ?? 0) + 1);
+    return counts;
+}
+/** The `## ` titles of `md` that appear more than once, in first-appearance order — the
+ * duplicate-heading signal `checkBacklogHeadings` reports for main and
+ * `backlogStructureReason` checks on a tree being landed. */
+export function duplicateHeadings(md) {
+    return [...sectionTitleCounts(md)].filter(([, n]) => n > 1).map(([title]) => title);
+}
+/** The first structural fault a diff landing on `mainBranch` leaves in a backlog file, or
+ * undefined when none: for each touched backlog file it compares the `## ` heading set of the
+ * tree being landed (`wt`) against the diff's merge-base — the same base falseFixReason
+ * measures against, so a stacked batch is judged change by change — and rejects when
+ * (a) the head carries MORE of a title than the base carried (a duplicate `## Done` added, or
+ * a second one where the base had none), or (b) a title present on the base is gone from the
+ * head (a whole section dropped). The rule is deliberately about heading sets, not section
+ * names: a project whose BUGS.md adds `## Verified` (this repo's does) or a fresh repo seeded
+ * from src/init.ts's templates passes unchanged. A base that already carries a duplicate never
+ * blocks unrelated edits — rule (a) fires only when the head's count EXCEEDS the base's, so a
+ * change that removes a duplicate always passes. For PLANS.md there is a third rule
+ * (part 4/4): a head that ADDS a `### ` entry directly under `## Done` whose joined heading
+ * metadata carries `(planned YYYY-MM-DD` but no `done YYYY-MM-DD`, and whose key the base's
+ * PLANS.md never carried in ANY section, is a plan filed into the wrong section — rejected with
+ * a reason naming the entry and the one-line fix. Judged against the merge-base (the same base
+ * the heading rules use), so a Planned → Done move of an entry the base already had passes, a
+ * stacked batch is measured change by change, and a pre-existing stranded entry (whose key the
+ * base has) never blocks unrelated landings — the clean loop's repair (part 3/4) owns those.
+ * Detection is deterministic markdown reading —
+ * no pi — so both the review gate (exempt and code diffs alike) and the in-lock landing
+ * re-check can afford it on every landing (plans: "Backlog structure check", part 2/4). */
+export async function backlogStructureReason(wt, mainBranch, files) {
+    const touched = files.filter((f) => BACKLOG_FILES.includes(f));
+    if (touched.length === 0)
+        return undefined;
+    const baseRev = (await gitTry(wt, "merge-base", "HEAD", mainBranch)) ?? mainBranch;
+    for (const file of touched) {
+        // A deleted file reads as empty: every heading the base had is gone — rule (b).
+        const head = readTextOrNull(path.join(wt, file)) ?? "";
+        const base = (await gitTry(wt, "show", `${baseRev}:${file}`)) ?? "";
+        const headCounts = sectionTitleCounts(head);
+        const baseCounts = sectionTitleCounts(base);
+        for (const [title, count] of headCounts)
+            if (count > 1 && count > (baseCounts.get(title) ?? 0))
+                return (`${file} adds another "## ${title}" heading — readers take the first section of a ` +
+                    `name, so anything under the duplicate is invisible; keep one "## ${title}" per file`);
+        for (const title of baseCounts.keys())
+            if (!headCounts.has(title))
+                return (`${file} drops the "## ${title}" section the base had — entries filed under it would ` +
+                    `be invisible to every section reader; restore "## ${title}"`);
+        // Part 4/4's rule, PLANS.md only (see this function's doc comment): a NEW plan filed
+        // directly under ## Done with no done date. strandedPlanEntries already does the
+        // fence-aware, joined-metadata reading the first two conditions need; the base's key set
+        // supplies the third.
+        if (file === "PLANS.md") {
+            const baseKeys = planHeadingKeys(base);
+            const newcomer = strandedPlanEntries(head).find((e) => e.section === "Done" && !baseKeys.has(planHeadingKey(e.title)));
+            if (newcomer)
+                return (`PLANS.md files "${newcomer.title}" directly under "## Done" with no done date — a plan ` +
+                    `written into the done section is invisible to every Planned reader; file it under ` +
+                    `"## Planned" instead`);
+        }
+    }
+    return undefined;
+}
+/** The clean loop's `<backlog-structure>` prompt block for the primary checkout at `root`
+ * (the same root the telemetry digest and qa coverage blocks read): a rendered block listing
+ * each stranded heading with its current section, or undefined when PLANS.md is missing,
+ * unreadable, or clean — an unreadable or clean file gives no block, so the prompt is
+ * unchanged in the common case. */
+export function renderBacklogStructureBlock(root) {
+    // readTextOrNull never throws — an unreadable file arrives as null, its own contract.
+    const md = readTextOrNull(path.join(root, "PLANS.md"));
+    if (md === null)
+        return undefined;
+    const stranded = strandedPlanEntries(md);
+    if (stranded.length === 0)
+        return undefined;
+    const listed = stranded
+        .map((e) => `- (now under ## ${e.section}) ${e.title}`)
+        .join("\n");
+    // The task wording lives in the clean role's find text (src/role-catalog.ts); the block only
+    // carries the evidence, like the digest and coverage blocks do.
+    return `Plan headings filed under the wrong section of PLANS.md — invisible to the readers
+that scan one section, so no loop sees them as backlog work:
+<backlog-structure>
+${listed}
+</backlog-structure>`;
+}

package/dist/src/backlog.js

@@ -0,0 +1,285 @@
+import path from "node:path";
+import { readTextOrNull } from "./files.js";
+import { cachedByStat } from "./stat-cache.js";
+/** A per-line CommonMark fenced-code state machine, shared by every line-level parser of
+ * backlog markdown. `inside(line)` feeds one line and returns whether it is fence syntax or
+ * fenced content — never markdown structure: a fence opens at a ```` ``` ````/`~~~` line (an
+ * info string is allowed, except that a backtick fence's info string may not contain a
+ * backtick — such a line is paragraph text that opens nothing), closes only at a bare fence
+ * line of the same character at least as long, and an unclosed fence runs to EOF. Every reader
+ * that classifies backlog lines as markdown structure (section boundaries, entry headings,
+ * bullets) must consult this, so two readers can never disagree about what is body content.
+ * `open()` reports whether the tracker is inside a fence where the walk stopped — true when a
+ * fence ran unclosed to the walk's end, so a caller that walked a bounded region can tell its
+ * read is fence-degraded (the region's tail quoted real structure). */
+export function fenceTracker() {
+    // The open fence's marker (null = none): only a matching bare fence line closes it.
+    let fence = null;
+    return {
+        open() {
+            return fence !== null;
+        },
+        inside(line) {
+            const fenceLine = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+            if (fenceLine) {
+                const marker = fenceLine[1] ?? ""; // The group always participates; "" keeps types honest.
+                if (fence === null) {
+                    // CommonMark: an info string for a backtick fence cannot contain a backtick, so a
+                    // line like ````md / ## Done / ````` quoted in prose is paragraph text, not a fence
+                    // opener — taken as one, no later bare fence line can close it and the fence runs to
+                    // EOF, swallowing the rest of the document as fenced content.
+                    const info = line.replace(/^ {0,3}/, "").slice(marker.length);
+                    if (marker.charAt(0) === "`" && info.includes("`"))
+                        return false;
+                    fence = { char: marker.charAt(0), length: marker.length };
+                }
+                else if (marker.charAt(0) === fence.char && marker.length >= fence.length && line.trim() === marker)
+                    fence = null;
+                return true; // The fence line itself is fence syntax, never structure.
+            }
+            return fence !== null;
+        },
+    };
+}
+/** The body lines of the `## <sectionTitle>` section of a markdown document: everything
+ * between that heading line and the next `## ` line (or EOF), neither boundary included. A
+ * `## ` line inside a fenced code block (entries quote markdown templates and shell traces) is
+ * body content, never a boundary. The single home of "where a section starts and ends" — every
+ * reader of a `## ` section (backlog entry parsing here, the usage report's Done/Fixed date
+ * scan in src/report-data.ts, and backlog-structure.ts's strandedPlanEntries) walks its
+ * section through this, so independent readers can never disagree about the boundary. */
+export function sectionLines(md, sectionTitle) {
+    const lines = [];
+    let inSection = false;
+    const fenced = fenceTracker();
+    for (const line of md.split("\n")) {
+        const inFence = fenced.inside(line);
+        if (!inFence && line.startsWith("## ")) {
+            inSection = line.slice(3).trim() === sectionTitle;
+            continue;
+        }
+        if (inSection)
+            lines.push(line);
+    }
+    return lines;
+}
+/** The body lines of one `## <sectionTitle>` section with fenced content stripped: the
+ * sectionLines walk, then a fresh fenceTracker's filter — the shape every reader that
+ * classifies a section's lines as markdown structure (entry headings, bullets, dates) walks.
+ * Exactly two call sites today: entryDates (below) and backlog-structure.ts's
+ * strandedPlanEntries. The fresh tracker is in sync with the document here: sectionLines
+ * only recognizes a `## ` boundary outside a fence, so the section's heading line is
+ * non-fenced and the fence state at the section's first line is closed — a tracker started
+ * there sees exactly what a document-wide tracker sees inside the section. Readers that
+ * must KEEP fenced lines as body content (parseEntryDetails) do not use this. */
+export function sectionBodyLines(md, sectionTitle) {
+    const fenced = fenceTracker();
+    return sectionLines(md, sectionTitle).filter((line) => !fenced.inside(line));
+}
+/** The heading lines of `md` starting with `prefix` (a `"## "` section heading or a `"### "`
+ * entry heading), in file order, fence-aware (fenceTracker): a heading line quoted inside a
+ * fenced code block is body text, never structure. The single home of the whole-document
+ * prefix-heading walk — backlog-structure.ts's sectionTitles ("## ") and planHeadingKeys
+ * ("### ") each carried their own tracker before, so their fence handling could drift from
+ * sectionLines'. Callers slice and trim the prefix themselves. (sectionLines does not use
+ * this: its walk must track which section it is inside, not just collect headings; readers
+ * inside one section go through sectionLines/sectionBodyLines instead.) */
+export function fenceAwareHeadingLines(md, prefix) {
+    const fenced = fenceTracker();
+    const lines = [];
+    for (const line of md.split("\n")) {
+        if (fenced.inside(line))
+            continue;
+        if (line.startsWith(prefix))
+            lines.push(line);
+    }
+    return lines;
+}
+/** The entries inside one `## <sectionTitle>` section of a markdown document, each with its
+ * full body: stops at the next `## ` line (so Done/Fixed entries never leak in), skips
+ * non-heading placeholders like `_None yet._` and any prose before the first heading, keeps
+ * interior blank lines within a body while trimming leading/trailing ones, and ends an open
+ * entry's body at EOF as well as at the next heading. */
+export function parseEntryDetails(md, sectionTitle) {
+    const entries = [];
+    let title = null; // The open entry's heading (null = no entry open yet).
+    let bodyLines = [];
+    const close = () => {
+        if (title !== null)
+            entries.push({ title, body: bodyLines.join("\n").trim() });
+        title = null;
+        bodyLines = []; // Prose before the first heading never becomes a body.
+    };
+    // A `### ` line inside a fenced code block is quoted content, never an entry boundary: an
+    // entry quoting a markdown template keeps its whole body instead of splitting into a phantom
+    // entry at the quoted heading.
+    const fenced = fenceTracker();
+    for (const line of sectionLines(md, sectionTitle)) {
+        if (fenced.inside(line))
+            bodyLines.push(line);
+        else if (line.startsWith("### ")) {
+            close();
+            title = line.slice(4).trim();
+        }
+        else {
+            bodyLines.push(line);
+        }
+    }
+    close(); // An entry at the end of file ends with EOF, not a heading.
+    return entries;
+}
+/** The completion dates ("YYYY-MM-DD") of the entries inside one `## <sectionTitle>` section.
+ * An entry starts at a `### ` heading or `- ` bullet line and ends at the next such line; only
+ * its METADATA is matched for dates — never its body, so a body's "**Done 2026-…**" recap line
+ * (or a prose cross-reference like "(done 2026-…)") cannot double-count. Fenced lines are
+ * body content, never entry starts — an entry quoting a markdown template with a
+ * `### … (fixed DATE)` heading inside must not count as a completion of its own. Metadata is
+ * headingMetadata's join (below). Entries without a parseable date are skipped.
+ *
+ * A `- ` line needs more than a date to be an entry: the sections also hold body bullets (an
+ * entry's repro steps, a plan's task breakdown), and a body bullet that merely mentions a
+ * completion — "- same shape as the sibling bug (fixed 2026-09-24)" — is not one. The epitaph
+ * shape separates them: an epitaph always closes its line with a parenthetical that records
+ * both the completion date and the landing commit ("(planned …, done …; commit abc1234)"),
+ * so a bullet counts only when its trailing `(…)` group carries the date AND a `commit`
+ * reference; a heading entry keeps the plain metadata match (headings are the primary entry
+ * format and always close their metadata parenthetical by convention). */
+export function entryDates(md, sectionTitle, dateRe) {
+    const dates = [];
+    const lines = sectionBodyLines(md, sectionTitle);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (!line.startsWith("### ") && !line.startsWith("- "))
+            continue;
+        const meta = headingMetadata(lines, i);
+        let date = null;
+        if (line.startsWith("- ")) {
+            // Epitaph guard (see the doc comment): the date must live in the line's trailing
+            // parenthetical beside a commit reference, or the bullet is body text, not an entry.
+            // Within the parenthetical the completion is the LAST dated verb, matching the heading
+            // branch: a decomposition cross-reference ("decomposed from the sibling bug fixed
+            // <date>, fixed <date>") precedes the entry's own completion record.
+            const tail = trailingParenthetical(line);
+            if (/\bcommits?\b/.test(tail))
+                date = lastDate(tail, dateRe);
+        }
+        else {
+            date = lastDate(meta.text, dateRe);
+        }
+        if (date)
+            dates.push(date);
+        i = meta.next - 1; // The loop's ++ resumes at the first line not consumed as metadata.
+    }
+    return dates;
+}
+/** A `### `/`- ` entry start's METADATA, joined for matching: the start line plus, for `### `
+ * headings only, continuation lines up to and including the first line ending in `)` (capped
+ * at 3 lines) — wrapped headings carry their date on the second line, while `- ` epitaphs are
+ * single-line by construction, so a bullet's own line is its whole metadata (a following prose
+ * paragraph is body, never matched). Joining with a space keeps "done\n2026-…" matchable.
+ * Returns the joined text and the index of the first line NOT consumed as metadata, so a
+ * walker can resume its scan there. Extracted from entryDates (its only original caller) so
+ * the stranded-plan detector (src/backlog-structure.ts) matches dates against exactly the
+ * same joined text instead of growing a second, drifting copy of the join rule. */
+export function headingMetadata(lines, start) {
+    const line = lines[start] ?? "";
+    const meta = [line];
+    let closed = line.endsWith(")");
+    let j = start + 1;
+    // Continuation is a heading-only concern (wrapped headings); bullets are single-line.
+    while (line.startsWith("### ") && meta.length < 3 && j < lines.length && !closed) {
+        const next = lines[j] ?? "";
+        if (next.startsWith("### ") || next.startsWith("- "))
+            break; // The entry ends at the next start.
+        meta.push(next);
+        j++;
+        closed = next.endsWith(")");
+    }
+    return { text: meta.join(" "), next: j };
+}
+/** A `- ` line's trailing parenthetical's inner text, nesting-aware: a backward scan from the
+ * line's closing ")" to its matching "(" returns the group's FULL inner text, so an epitaph
+ * that quotes a parenthetical of its own — "(planned …, done …; commit abc1234 (re-landed
+ * after review fix))" — still yields its date-bearing text. The previous flat `\([^()]*\)$`
+ * match saw only the innermost group ("" when the line ended in two closes) and silently
+ * dropped the epitaph's date from the day report (BUGS.md 2026-09-29). Unbalanced text (no
+ * matching open paren) yields "" — the guard then treats the bullet as body text, as before. */
+function trailingParenthetical(line) {
+    if (!line.endsWith(")"))
+        return "";
+    let depth = 0;
+    for (let i = line.length - 1; i >= 0; i--) {
+        const ch = line[i];
+        if (ch === ")")
+            depth++;
+        else if (ch === "(" && --depth === 0)
+            return line.slice(i + 1, -1);
+    }
+    return "";
+}
+/** A text's LAST `<dateRe>` capture — the completion rule both branches of entryDates share:
+ * an entry's completion is its LAST dated verb, not the first, because found-by,
+ * decomposition, and sibling mentions ("decomposed from the X bug fixed <date>") all precede
+ * the completion record, so first-match let a sibling's date steal the entry's count onto the
+ * wrong day (BUGS.md 2026-09-29). dateRe is cloned with the g flag so matchAll sees every
+ * date; a text with no date yields null. */
+function lastDate(text, dateRe) {
+    const global = new RegExp(dateRe.source, dateRe.flags.includes("g") ? dateRe.flags : `${dateRe.flags}g`);
+    const all = [...text.matchAll(global)];
+    return all[all.length - 1]?.[1] ?? null;
+}
+/** Parsed sections keyed by file + section title (a future reader of a second section from the
+ * same file must not collide with the first). Bounded inside cachedByStat: many short-lived
+ * roots in tests would otherwise accumulate. Stores the richer {title, body} shape — one parse
+ * per file change subsumes both the titles-only and the full-entry reads. */
+const sectionCache = new Map();
+/** The entries under `<root>/<fileName>`'s `## <sectionTitle>`: fresh when the file's identity
+ * or mtime/size changed since the last read, cached otherwise (see module docs). A missing or
+ * unreadable file yields [] — a render path must never throw on backlog state. */
+function sectionEntries(root, fileName, sectionTitle) {
+    const file = path.join(root, fileName);
+    return (cachedByStat(sectionCache, `${file}\u0000${sectionTitle}`, file, () => {
+        const md = readTextOrNull(file); // Missing or unreadable — no data.
+        return md === null ? null : parseEntryDetails(md, sectionTitle);
+    }, (entries) => entries.map((e) => ({ ...e }))) ?? []);
+}
+/** 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);
+}
+/** Open bugs: the `### ` headings under BUGS.md's `## Open` section. Missing or unreadable → []. */
+export function openBugs(root) {
+    return sectionEntries(root, "BUGS.md", "Open").map((e) => e.title);
+}
+/** Open questions: the `### ` headings under QUESTIONS.md's `## Open` section — loops post
+ * them when a decision is genuinely the user's (see plans/questions-outbox.md). Missing or
+ * unreadable → []. */
+export function openQuestions(root) {
+    return sectionEntries(root, "QUESTIONS.md", "Open").map((e) => e.title);
+}
+/** Planned features as full entries (title + body), in file order — the TUI's project-status
+ * browse and the GUI's /api/backlog endpoint read these. Missing or unreadable → []. */
+export function plannedPlanEntries(root) {
+    return sectionEntries(root, "PLANS.md", "Planned");
+}
+/** Open bugs as full entries (title + body), in file order. Missing or unreadable → []. */
+export function openBugEntries(root) {
+    return sectionEntries(root, "BUGS.md", "Open");
+}
+/** Open questions as full entries (title + body), in file order. Missing or unreadable → []. */
+export function openQuestionEntries(root) {
+    return sectionEntries(root, "QUESTIONS.md", "Open");
+}
+/** 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
+ * file order and {title, body} verbatim, and a missing or unreadable file degrades to [] like the
+ * individual readers — a bare directory yields the all-empty object, never an error. */
+export function backlogPayload(root) {
+    return {
+        plans: plannedPlanEntries(root),
+        bugs: openBugEntries(root),
+        questions: openQuestionEntries(root),
+    };
+}