tumwater 0.0.0-stage → 0.1.1

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,144 @@
-# 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)
+
+## Install
+
+Requires Node 20.3 or later on macOS or Linux.
+
+```bash
+npm install -g tumwater
+```
+
+Or run any command without installing: `npx tumwater`. To run from a checkout of this repo
+instead: `npm install && npm run build && npm link`.
+
+## Status
+
+<!-- tumwater:status:start -->
+**v0.1.1**: working harness. The director and 14 of the 15 roles are enabled by default; `telemetry`,
+which files harness bugs from tumwater's own event log, is opt-in (`roles.telemetry.enabled`).
+
+Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
+[QUESTIONS.md](QUESTIONS.md) (open questions).
+<!-- tumwater:status:end -->
+
+## Usage
+
+```bash
+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
+                            # a fresh/empty project is seeded with
+                            # "bootstrap": {"untilPlansDone": 5}, holding the maintenance
+                            # loops until 5 plans are done; remove "bootstrap" from
+                            # tumwater.json to end that early
+tumwater run                # start the loops (Ctrl+C to stop)
+tumwater run --gui          # ... and serve the browser dashboard at http://127.0.0.1:7180 from the same process
+tumwater run --for 2h       # run for a bounded window (capped at 90d), then drain and exit like Ctrl+C would
+```
+
+Then, from another terminal:
+
+| To | Run |
+| --- | --- |
+| Watch the fleet | `tumwater tui`, or the browser dashboard at http://127.0.0.1:7180 — `tumwater gui` on its own, or `tumwater run --gui` to boot the fleet and the dashboard together |
+| 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; `--last` shows the newest completed tick's trail instead of numbering one; `--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, its notebook — 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, `--file <path>` (`-` for stdin) to read the text from a file, or `--at <duration>` to defer it until the duration passes (45s, 90m, 1h30m, 1d; capped at 90d), `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, and `tumwater prompt --edit <n> "new text"` rewrites the Nth entry in place, keeping its position and wait time (both take `--role <id>` when several loops share that number), and `--attach <path>` (repeatable, up to 4 images — png, jpg, jpeg, gif, webp, bmp, each at most 5 MiB) attaches an image the receiving loop reads at its next tick; `tumwater bug "<symptom>"` files a bug into BUGS.md's Open section and wakes the bugfix loop, `tumwater plan "<title>" [body...]` files a plan request into PLANS.md's Planned section and wakes the feature loop — both stamped as operator-reported (the other half of `tumwater backlog`) |
+| 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; `wake --in 45m` schedules the wake for 45 minutes from now — the marker is written immediately but consumed no earlier than the deadline, like `pause --for`'s auto-resume), `tumwater reclaim [--dry-run]` (drop gitignored build outputs from every harness worktree; `--dry-run` lists the candidates and cleans nothing), `tumwater retire --role <id>` (remove a disabled loop's worktree, branch, and per-role state — use after setting `enabled: false` for that role; `--force` overrides the safety rails), `tumwater abort --role <id>`, `tumwater stop` (drain and exit, like Ctrl+C), `tumwater reset-counters [--role <id>]` (zero the per-loop counters the dashboards show, starting a fresh observation window — scheduling is untouched) |
+| Audit | `tumwater doctor` (pre-flight; `--json` prints the report as JSON, for scripts), `tumwater report` (usage and cost, with landed commits by role and the work/maintenance split; 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 (either one selector or a map of tiers
+`small`/`default`/`strong` — omitted tiers inherit `default`; per-tier `fallback` overrides may name a
+model or `"pause"`, and a role's `model` may name a tier; see [plans/model-tiers.md](plans/model-tiers.md)),
+intervals, per-role `instances` (`feature` and `bugfix` may each run 1–8 parallel runners, every one
+with its own branch and state; default 1), 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
+`maintenancePerWorkLanding` ratio (default 2; a rolling 24 h allowance of that many
+code-maintenance landings per feature/bugfix/director landing, plus a floor of 12 — when the
+window reaches it the scheduler holds the enabled maintenance loops until it rolls under, and a
+fresh `tumwater wake <role>` or a queued prompt for one admits a single tick anyway), a nightly `quietHours` window
+(e.g. `"23:00-07:00"` local time) during
+which role loops start no new ticks (the director is exempt), with optional per-role windows
+`quietHoursPerRole` — a loop inside its own window starts no new ticks, whether or not the
+fleet-wide window covers now — a `diskHoldGB` free-space floor (default 10; when the volume
+holding the worktrees drops below it, no new work starts until free space recovers 5 GB above it;
+0 disables), a `diskReclaimGB` pressure-reclaim threshold (default 40; below it idle worktrees
+drop their gitignored build outputs before the hold engages; 0 disables), and a
+`worktreeIdleReclaimHours` window (default 24; an hourly pass drops a worktree's gitignored build
+outputs once it has sat unused that long, whatever the free space; 0 disables), a
+`worktreeSlots` count of pooled checkouts shared by role ticks and landing vets (default
+`maxConcurrent` + 1; the director's worktree sits outside the pool) — 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; dotted keys (`maxDailyCostUsdPerRole.feature 1.5`, `roles.qa.model x`) merge one entry
+into the existing map or role entry, while bare keys replace the whole value.
+
+**Backends:** any OpenAI-compatible model pi can reach works; set `model` in `tumwater.json` to
+one `provider/id[:thinking]` selector (plus `fallback` to a free selector), or a map of tiers
+`small`/`default`/`strong`. A role whose primary keeps failing with provider-class errors
+(three consecutive 429s or backend failures) runs its next ticks on its tier's resolved
+`fallback` pair and probes the primary once the 5-minute cooldown elapses, returning to it
+when a probe answers; `tumwater status`, the TUI, the dashboard, and `tumwater role <id>` name
+the off-model episode. 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": "dd415e942c5569f2a1c468345a9277febbdaaed0",
+  "builtAt": 1791538389108,
+  "root": "/home/runner/work/tumwater/tumwater"
+}

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

@@ -0,0 +1,141 @@
+/** Backlog eligibility: which PLANS.md / BUGS.md entries a work loop may take now (plans,
+ * parallel-work-instances, part 2/7). An entry is held when its body carries a **Refused …**,
+ * **Needs review …** or **Needs replan …** note, or when its heading's trailing parenthetical
+ * names a prerequisite (`requires parts 1/5–3/5 landed`) that is itself still listed under
+ * `## Planned`. The parsers are pure over markdown text; `eligibleEntries` is the stat-backed
+ * reader for a caller that wants the list. The backlog index marks every held entry so a loop
+ * skips it without re-deriving the rule. */
+import path from "node:path";
+import { readTextOrNull } from "../files/files.js";
+import { collapseWhitespace } from "../text/text.js";
+import { NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX } from "../roles/role-guidance.js";
+import { baseRoleOf } from "../roles/loop-ids.js";
+import { trailingParenthetical } from "./backlog-md.js";
+import { actionableEntryRanges, stripEntryStamp } from "./backlog-structure.js";
+import { openBugEntries, plannedPlanEntries } from "./backlog.js";
+/** The `**Refused …` note prefix a refusing tick writes. Every hold note — this one and the
+ * imported Needs-review and Needs-replan prefixes — is matched as a line prefix (hasNoteLine)
+ * so a mention in prose never holds an entry. */
+const REFUSED_PREFIX = "**Refused ";
+/** True when `body` carries a line (ignoring leading indentation) that begins with `prefix`.
+ * The one home of the hold-note rule: a note holds its entry only when written as its own
+ * line, never when its prefix is quoted inside prose. */
+function hasNoteLine(body, prefix) {
+    return body.split("\n").some((line) => line.trimStart().startsWith(prefix));
+}
+/** One prerequisite ref, resolved against the entry's own series when it names none. */
+function parseRef(chunk, ownSeries) {
+    const text = chunk.trim().replace(/^parts?\s+/i, "");
+    if (text === "")
+        return [];
+    const m = /^(?:([\s\S]+?)\s+)?([0-9]+[a-z]?)\/(\d+)(?:\s*[–-]\s*(\d+)\/(\d+))?$/i.exec(text);
+    if (m === null)
+        return [];
+    const series = (m[1]?.trim() ?? "") || ownSeries;
+    if (series === null || series === "")
+        return [];
+    const of = Number(m[3]);
+    const start = m[2].toLowerCase();
+    if (!Number.isInteger(of) || of < 1)
+        return [];
+    if (m[4] === undefined)
+        return [{ series, part: start, of }];
+    // A range is numeric on both ends (the lettered parts never range); expand it inclusively.
+    const from = Number(start);
+    const to = Number(m[4]);
+    if (!Number.isInteger(from) || !Number.isInteger(to) || to < from)
+        return [];
+    const parts = [];
+    for (let p = from; p <= to; p++)
+        parts.push({ series, part: String(p), of });
+    return parts;
+}
+/** The stable identity of an entry heading: its `(planned …)`/`(done …)` stamp suffix
+ * removed through the shared stripEntryStamp, whitespace collapsed, lowercased. Adding a
+ * done stamp or a Refused note therefore leaves the key unchanged. */
+export function entryKey(title) {
+    return collapseWhitespace(stripEntryStamp(title)).toLowerCase();
+}
+/** An entry's own series and part from its heading, or null when the heading is not a
+ * `<Series>, part i/n: …` title. The series is the text before `, part i/n:`. */
+export function seriesPart(title) {
+    const m = /^(.+?),\s*part\s+([0-9]+[a-z]?)\/(\d+)\s*:/i.exec(stripEntryStamp(title));
+    if (m === null)
+        return null;
+    const series = m[1].trim();
+    if (series === "")
+        return null;
+    return { series, part: m[2].toLowerCase(), of: Number(m[3]) };
+}
+/** The prerequisite parts a plan heading's trailing parenthetical names through the clause
+ * `requires <ref>((, | and )<ref>)* landed`, with each range (e.g. `parts 1/5–3/5`) expanded.
+ * Returns [] when the heading has no such clause or the clause does not parse — an agent judges
+ * an unparseable clause, exactly as it does today. Only the heading is read, never the body. */
+export function requiredParts(title) {
+    const meta = trailingParenthetical(title);
+    if (meta === "")
+        return [];
+    const m = /requires\s+(.+?)\s+landed\b/i.exec(meta);
+    if (m === null)
+        return [];
+    const ownSeries = seriesPart(title)?.series ?? null;
+    const refs = [];
+    for (const chunk of m[1].split(/\s*,\s*|\s+and\s+/i))
+        refs.push(...parseRef(chunk, ownSeries));
+    return refs;
+}
+/** Why `entry` is held against the still-`planned` entries, or null when it may be taken: a
+ * `**Refused …` line (refused), a Needs-review line (needs-review), a Needs-replan line
+ * (needs-replan — the plan loop owns it), or a prerequisite `(series, part)` still among
+ * `planned` ({ blockedBy }). Series compare case-insensitively; part tokens compare verbatim.
+ * Bodies mentioning "requires" are never consulted — only the heading's trailing
+ * parenthetical. */
+export function entryHold(entry, planned) {
+    if (hasNoteLine(entry.body, REFUSED_PREFIX))
+        return "refused";
+    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX))
+        return "needs-review";
+    if (hasNoteLine(entry.body, NEEDS_REPLAN_PREFIX))
+        return "needs-replan";
+    const refs = requiredParts(entry.title);
+    if (refs.length === 0)
+        return null;
+    const parts = planned
+        .map((p) => seriesPart(p.title))
+        .filter((p) => p !== null);
+    const blocked = refs.filter((ref) => parts.some((p) => p.series.toLowerCase() === ref.series.toLowerCase() && p.part === ref.part));
+    return blocked.length === 0
+        ? null
+        : { blockedBy: blocked.map((ref) => `${ref.series} ${ref.part}/${ref.of}`) };
+}
+/** The entries a `role` loop may take now, in file order: PLANS.md's `## Planned` entries for
+ * feature, BUGS.md's `## Open` entries for bugfix, minus every entry entryHold holds, each with
+ * its stamp-free key, verbatim title and 1-based line range. Reads the primary checkout through
+ * the same stat-cached readers the index uses; a missing or unreadable file yields []. */
+export function eligibleEntries(root, role) {
+    // An instance id (`bugfix-2`) resolves through its base role, exactly as claims.ts's
+    // roleSection does, so a claim's line range is read from the right file.
+    const bugfix = baseRoleOf(role) === "bugfix";
+    const file = bugfix ? "BUGS.md" : "PLANS.md";
+    const section = bugfix ? "Open" : "Planned";
+    const md = readTextOrNull(path.join(root, file));
+    if (md === null)
+        return [];
+    const entries = bugfix ? openBugEntries(root) : plannedPlanEntries(root);
+    const ranges = actionableEntryRanges(md, section);
+    const planned = plannedPlanEntries(root);
+    const out = [];
+    for (let i = 0; i < entries.length && i < ranges.length; i++) {
+        const entry = entries[i];
+        if (entryHold(entry, planned) !== null)
+            continue;
+        const range = ranges[i];
+        out.push({
+            key: entryKey(entry.title),
+            title: entry.title,
+            start: range.start,
+            end: range.end,
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,270 @@
+/** The pure markdown layer of the backlog parsers: fence-aware reading of PLANS.md / BUGS.md /
+ * QUESTIONS.md text, with no filesystem access — every function here takes the markdown text as
+ * an argument. Split from src/backlog/backlog.ts, which keeps the stat-cached file readers
+ * (sectionEntries, the root-based plannedPlans/openBugs/openQuestions family, and the
+ * Done/Fixed date scan): consumers who only parse markdown (question-commands.ts's QUESTIONS.md
+ * walks, backlog-write.ts's section appends, backlog-structure.ts's stranding checks)
+ * import from here without reaching the file/cache layer, and a caller who parses a string never
+ * pays for a stat. Both layers share one fenceTracker state machine, so independent readers can
+ * never disagree about what is body content. */
+/** The repo-root backlog markdown files shared by every layer that knows them by name: the
+ * tracked files loops edit and readers parse by `## ` section — read by backlog-structure.ts's
+ * structural checks, landing/backlog-conflicts.ts's mechanical insert-conflict resolver, and
+ * doctor-backlog.ts's duplicate-heading check. One definition, so the three cannot disagree
+ * about which files count. */
+export const BACKLOG_FILES = new Set(["PLANS.md", "BUGS.md", "QUESTIONS.md"]);
+/** 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 trimmed title of `line` when it is a markdown heading line at `prefix` level and not
+ * quoted content — null otherwise, including when fenceTracker reports the line inside a fenced
+ * code block. The single home of the fence-aware heading guard (`!fenced.inside(line) &&
+ * line.startsWith(prefix)` plus the slice/trim) that every line-level reader of the backlog
+ * docs repeats: sectionLines' section boundaries and parseEntryDetails' entry boundaries here,
+ * and question-commands.ts's walks of QUESTIONS.md (the Open/Answered scan, the `### ` block
+ * split, and the Answered section's start); that file's two pure next-`## ` boundary walks
+ * go through nextSectionHeading below instead. Readers that walk
+ * whole documents collecting heading lines go through fenceAwareHeadingLines instead; callers
+ * that only need "is this a heading" pass a tracker and compare the title or test for null. */
+export function fencedHeadingTitle(line, fenced, prefix) {
+    return !fenced.inside(line) && line.startsWith(prefix) ? line.slice(prefix.length).trim() : 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/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")) {
+        if (fencedHeadingTitle(line, fenced, "## ") !== null) {
+            inSection = line.slice(3).trim() === sectionTitle;
+            continue;
+        }
+        if (inSection)
+            lines.push(line);
+    }
+    return lines;
+}
+/** The index of the next `## ` section heading at or after `from`, fence-aware through the
+ * caller's `fenced` tracker — or `lines.length` when none follows. The section-end boundary
+ * rule as an index, for readers that must cut or splice at the boundary rather than collect
+ * its content (question-commands.ts cuts the Open section at its end and inserts a moved
+ * block before Answered's next `## `; backlog-write.ts cuts the section a filed entry is
+ * appended to). Shares fencedHeadingTitle's guard with sectionLines, so
+ * a boundary found here is the same boundary sectionLines would stop at. */
+export function nextSectionHeading(lines, from, fenced) {
+    for (let i = from; i < lines.length; i++) {
+        if (fencedHeadingTitle(lines[i] ?? "", fenced, "## ") !== null)
+            return i;
+    }
+    return lines.length;
+}
+/** 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 (fencedHeadingTitle(line, fenced, "### ") !== null) {
+            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/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 or `### ` heading's trailing parenthetical's inner text, nesting-aware: a
+ * backward scan from the text'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. The one home for this rule: entryDates reads it for `- ` epitaphs and
+ * backlog-eligibility.ts's requiredParts for a heading's prerequisite clause. */
+export 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;
+}

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

@@ -0,0 +1,37 @@
+/** The terminal's view of the project backlog — the same three open sections the GUI's
+ * /api/backlog endpoint and the TUI's project-status browse show, rendered as Markdown for
+ * `tumwater backlog`. The renderer consumes the payload backlogPayload collects — the three
+ * backlog.ts entry readers with their cache behavior, placeholder skipping, and Done/Fixed
+ * exclusion the dashboards rely on — so the terminal view cannot drift from the dashboard
+ * view (one parser, two surfaces) and the CLI's --json/human branches share one collection
+ * (sayJsonOrRender's thunk) instead of each reading the entry files afresh. Entries render
+ * verbatim — heading text with its `(planned …)`/`(reported …)` suffix, body lines
+ * indented two spaces under it — because these are markdown the loops
+ * wrote, including their Goal/Approach/Acceptance-criteria structure; reflowing them here
+ * would make this command a worse reader of its own backlog than the files it summarizes. An
+ * empty section renders a single `_(none)_` line rather than disappearing, so an all-clear
+ * backlog reads as three explicit empties, not a suspiciously short document. */
+/** One `## ` section: its entries verbatim, or the single `_(none)_` placeholder line. */
+function renderSection(title, entries) {
+    const lines = [`## ${title}`, ""];
+    if (entries.length === 0) {
+        lines.push("_(none)_", "");
+        return lines;
+    }
+    for (const entry of entries) {
+        lines.push(`### ${entry.title}`, "");
+        // The body is already trimmed by parseEntryDetails; only the indent is added here.
+        for (const line of entry.body.split("\n"))
+            lines.push(line === "" ? "" : `  ${line}`);
+        lines.push("");
+    }
+    return lines;
+}
+/** Render the backlog payload (planned plans, open bugs, open questions) as Markdown. */
+export function renderBacklogMarkdown(payload) {
+    const lines = ["# tumwater backlog", ""];
+    lines.push(...renderSection("Planned features", payload.plans));
+    lines.push(...renderSection("Open bugs", payload.bugs));
+    lines.push(...renderSection("Open questions", payload.questions));
+    return lines.join("\n").trimEnd();
+}