tumwater 0.1.0 → 0.1.1

package/README.md

@@ -10,10 +10,22 @@ 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**: working harness. All 13 roles and the director are enabled by default.
+**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).
@@ -22,8 +34,6 @@ Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 ## 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
@@ -31,30 +41,54 @@ tumwater init "Build a tiny markdown-to-html converter CLI in Python."
                             # 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 `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)) |
+| 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, `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) |
+| 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), `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) |
+| 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, intervals, the daily spend cap
+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 nightly `quietHours` window
+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), user-defined `customLoops`, and an
+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`,
@@ -62,10 +96,17 @@ breaker trip, a failed landing, a blocked restart — the command gets `TUMWATER
 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.
+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

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "4c69994273d9f4d707b0c5a6e7d00f50a3b265e6",
-  "builtAt": 1791110618512,
+  "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.js → backlog/backlog-md.js}

@@ -1,6 +1,18 @@
-import path from "node:path";
-import { readTextOrNull } from "./files.js";
-import { cachedByStat } from "./stat-cache.js";
+/** 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
@@ -41,20 +53,32 @@ export function fenceTracker() {
         },
     };
 }
+/** 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-data.ts, and backlog-structure.ts's strandedPlanEntries) walks its
+ * 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")) {
-        const inFence = fenced.inside(line);
-        if (!inFence && line.startsWith("## ")) {
+        if (fencedHeadingTitle(line, fenced, "## ") !== null) {
             inSection = line.slice(3).trim() === sectionTitle;
             continue;
         }
@@ -63,6 +87,20 @@ export function sectionLines(md, sectionTitle) {
     }
     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.
@@ -117,7 +155,7 @@ export function parseEntryDetails(md, sectionTitle) {
     for (const line of sectionLines(md, sectionTitle)) {
         if (fenced.inside(line))
             bodyLines.push(line);
-        else if (line.startsWith("### ")) {
+        else if (fencedHeadingTitle(line, fenced, "### ") !== null) {
             close();
             title = line.slice(4).trim();
         }
@@ -179,7 +217,7 @@ export function entryDates(md, sectionTitle, dateRe) {
  * 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
+ * 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] ?? "";
@@ -197,14 +235,16 @@ export function headingMetadata(lines, start) {
     }
     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) {
+/** 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;
@@ -228,58 +268,3 @@ function lastDate(text, dateRe) {
     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),
-    };
-}

package/dist/src/{ui/backlog-report.js → backlog/backlog-render.js}

@@ -4,8 +4,9 @@
  * 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
+ * (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