tumwater 0.4.0 → 0.4.2

package/dist/src/inbox/prompt-commands.js

@@ -18,6 +18,7 @@ import { listWideScope, queuedFileAtPosition, promptPreview, queuedListRows, que
 import { durationLabel, parseRoleListFlag } from "../cli/cli-args.js";
 import { knownRoleIds, knownRoleIdsCached, loadConfig } from "../config/config.js";
 import { errorMessage } from "../text/text.js";
+import { plural } from "../text/phrases.js";
 import { readPromptImageFiles } from "./inbox-attachments.js";
 import { DIRECTOR_ROLE, unknownRoleMessage } from "../roles/roles.js";
 import { submitRolePromptAndWake } from "../operator/operator-intent.js";
@@ -39,6 +40,12 @@ function failQueueMiss(listed, position) {
     }
     return listed;
 }
+/** Resolve a list-wide position to the single role holding it, failing on ambiguity or miss.
+ * The no-`--role` resolution the cancel/edit/top branches each make, shared so the three
+ * verbs cannot drift from one another or from sayListedOutcome's wordings. */
+function resolveListedRole(root, position) {
+    return failQueueMiss(resolveListedQueue(root, listWideScope(root), position), position).role;
+}
 /** Whether a list-wide outcome is one of the two miss shapes — the guard that narrows the
  * miss fields (`roles`, `queued`) without a cast. */
 function isQueueMiss(listed) {
@@ -113,6 +120,188 @@ function readPromptImages(paths) {
         return fail(errorMessage(err));
     }
 }
+/** `--list` mode — the inspection verb: filter the list-wide rows by `--role a,b` and `--grep`,
+ * then print the prose list, the `--json` document, or one of the empty/no-match lines. One
+ * helper so `--list`'s rules are found by name. */
+function runPromptList(root, args, json, grep, validIds) {
+    // One payload, two shapes: the prose render and the --json output both come from the
+    // same array, so the per-role positions --cancel consumes can never disagree with the
+    // data a script reads. Full text, verbatim: this is the inspection command that tells
+    // you what a queued prompt actually says before you cancel it.
+    // `--role a,b` filters the list-wide rows, so section order and each section's own
+    // numbering stay what `--cancel <n> --role <id>` takes.
+    const listRoles = parseRoleListFlag(args, validIds);
+    const allRows = queuedListRows(root, null, validIds);
+    const scoped = listRoles === null ? allRows : allRows.filter((row) => listRoles.includes(row.role));
+    const prompts = queuedRowsMatching(scoped, grep ?? null);
+    if (json) {
+        // An empty queue still prints the document, the history --json empty-rows precedent.
+        sayJson({ prompts });
+        return;
+    }
+    if (prompts.length === 0 && scoped.length > 0) {
+        say(`no queued prompt matches "${grep}"`);
+        return;
+    }
+    if (prompts.length === 0) {
+        say(listRoles === null
+            ? "every inbox is empty"
+            : listRoles.length === 1
+                ? `${roleLabel(listRoles[0])}'s inbox is empty`
+                : `every listed inbox is empty (${listRoles.join(", ")})`);
+        return;
+    }
+    say(renderQueuedList(prompts, Date.now()));
+}
+/** `--cancel <n>` mode — remove a queued prompt by position, list-wide or `--role`-scoped. One
+ * helper so `--cancel`'s rules are found by name. */
+function runPromptCancel(root, position, role) {
+    if (role === null) {
+        // No --role: the position addresses what --list shows — its per-role sections, each
+        // numbered from 1 (the director first, then the roles in catalog order). Resolve across
+        // that scope: one role holding the position cancels there, several are ambiguous (the
+        // list itself shows two "N." lines), none is a miss. The output names the role, since
+        // the caller scoped nothing.
+        sayListedOutcome(cancelListedPrompt(root, listWideScope(root), position), position);
+        return;
+    }
+    const target = role ?? DIRECTOR_ROLE;
+    sayPromptOutcome(position, target, runRolePromptCommand(root, target, position, cancelRolePrompt), false);
+}
+/** Run the CLI's image-input gate for one `prompt` surface. Shared by the submit and
+ * --edit forms so the refusal promise holds across every CLI attach surface: an image no
+ * configured model can read is refused (fail) before a byte is written, and a role that
+ * reroutes a blind read is told (say) where the prompt will run. */
+function runPromptImageGate(root, target) {
+    const guidance = imagePromptGuidance(root, target);
+    if (guidance.refusal)
+        fail(guidance.refusal);
+    if (guidance.notice)
+        say(guidance.notice);
+}
+/** `--edit <n>` mode — replace a queued prompt's body by position: the attachment gate, then
+ * the editor for a bare position or the typed/`--file` text, list-wide or `--role`-scoped. One
+ * helper so `--edit`'s rules are found by name. */
+function runPromptEdit(root, position, text, attachPaths, role) {
+    // The same broken-config policy and list-wide resolution as cancel, one verb over: the
+    // file's new content rides the same queue file (position, enqueue stamp, and a pending
+    // --at deferral untouched), and a concurrent dequeue reports gone and exits clean. An
+    // `--attach` list is read through the same helper the enqueue form uses and appended to
+    // the prompt's images in place.
+    const images = attachPaths.length > 0 ? readPromptImages(attachPaths) : undefined;
+    // Image-input gate, `--edit`'s twin of the submit branch below (plans/image-input.md
+    // "Attachments", part 5/5): editing an attachment into a queued prompt is the same
+    // run-time discovery the submit gate prevents, so the refusal promise holds across every
+    // CLI attach surface — an image no configured model can read is refused before a byte is
+    // written, and a role that reroutes a blind read is told where the prompt will run. The
+    // target role is resolved first (the same resolution the verb below makes) so the gate can
+    // name it.
+    if (images !== undefined && images.length > 0) {
+        const targetRole = role ?? resolveListedRole(root, position);
+        runPromptImageGate(root, targetRole);
+    }
+    const typed = text;
+    if (typed === null) {
+        // Bare `--edit <n>`: open the prompt's body in the editor. The role is resolved first
+        // and the write goes by file name, so a dequeue while the editor is open reports gone
+        // instead of editing the neighbour that shifted into the position.
+        const targetRole = role ?? resolveListedRole(root, position);
+        let name;
+        let body;
+        try {
+            name = path.basename(queuedFileAtPosition(root, targetRole, position));
+            body = readQueuedPromptBody(root, targetRole, name);
+        }
+        catch (err) {
+            return fail(errorMessage(err));
+        }
+        if (body === null) {
+            sayPromptOutcome(position, targetRole, { status: "gone" }, role === null);
+            return;
+        }
+        const after = editInEditor(body, "prompt.md");
+        // An emptied buffer is an abort, not a blank prompt: the queue would otherwise hold a
+        // prompt with no text, which the enqueue forms refuse.
+        if (after.trim() === "" && body.trim() !== "")
+            fail("the edited prompt is empty; nothing changed (use --cancel <n> to drop it)");
+        if (after.trim() === body.trim() && images === undefined) {
+            say(`prompt ${position} unchanged`);
+            return;
+        }
+        try {
+            sayPromptOutcome(position, targetRole, editQueuedFile(root, targetRole, name, after, images), role === null);
+        }
+        catch (err) {
+            fail(errorMessage(err));
+        }
+        return;
+    }
+    if (role === null) {
+        sayListedOutcome(editListedPrompt(root, listWideScope(root), position, typed, images), position);
+        return;
+    }
+    const target = role ?? DIRECTOR_ROLE;
+    sayPromptOutcome(position, target, runRolePromptCommand(root, target, position, (r, role, position) => editRolePrompt(r, role, position, typed, images)), false);
+}
+/** `--top <n>` mode — move a queued prompt to the head of its queue by position, list-wide or
+ * `--role`-scoped. One helper so `--top`'s rules are found by name. */
+function runPromptTop(root, position, role) {
+    // The same list-wide resolution the cancel branch uses, one verb on: no --role resolves the
+    // position across `--list`'s per-role sections and moves it in the resolved role's queue;
+    // with --role it is the role-scoped call. A concurrent dequeue reports gone and exits
+    // clean; position 1 of the resolved role is "already first".
+    if (role === null) {
+        const targetRole = resolveListedRole(root, position);
+        let outcome;
+        try {
+            outcome = movePromptToTop(root, targetRole, position);
+        }
+        catch (err) {
+            return fail(errorMessage(err));
+        }
+        sayTopOutcome(position, targetRole, outcome, true);
+        return;
+    }
+    const target = role ?? DIRECTOR_ROLE;
+    let outcome;
+    try {
+        outcome = movePromptToTop(root, target, position);
+    }
+    catch (err) {
+        return fail(errorMessage(err));
+    }
+    sayTopOutcome(position, target, outcome, false);
+}
+/** The default (enqueue) mode — the steering-prompt submit form: the `--at` due time, the
+ * `--attach` read and image-input gate, then submitRolePromptAndWake and the confirmation.
+ * One helper so the submit form's rules are found by name. */
+function runPromptSubmit(root, text, atDelayMs, attachPaths, role) {
+    const target = role ?? DIRECTOR_ROLE;
+    // `--at <duration>` is a delay, not an epoch: the marker's not-before time is now + the
+    // parsed duration, computed at submit so the deferral starts when the operator queued it.
+    const dueMs = atDelayMs !== null ? Date.now() + atDelayMs : undefined;
+    // `--attach <path>`: read and validate through the shared helper (a bad path fails by name
+    // before anything is queued). An attachment the target role cannot read is refused here by
+    // name — the same gate submitRolePrompt enforces, surfaced early so the CLI exits non-zero
+    // with the fix before anything is written or queued; a role that reroutes a blind read is
+    // not refused, but the operator is told where the prompt will actually run.
+    const images = attachPaths.length > 0 ? readPromptImages(attachPaths) : undefined;
+    if (images && images.length > 0) {
+        runPromptImageGate(root, target);
+    }
+    const wake = submitRolePromptAndWake(root, target, text, images, dueMs);
+    const attached = images !== undefined ? ` with ${plural(images.length, "image")}` : "";
+    const owner = target === DIRECTOR_ROLE ? "the director's" : `${roleLabel(target)}'s`;
+    if (atDelayMs !== null) {
+        // A deferred prompt's confirmation names the delivery delay, in the same duration
+        // vocabulary --at parsed (durationLabel), so the user can re-type it.
+        say(`added to ${owner} inbox — delivers in ${durationLabel(atDelayMs)}${attached}`);
+    }
+    else {
+        say(`added to ${owner} inbox${attached}`);
+    }
+    say(wake);
+}
 /** `tumwater prompt [--role <id>] <text|list|cancel <n>|top <n>>`: submit a steering prompt to the
  * director (default) or one role's queue (`--list` takes `--role <id>[,<id>...]`), list what
  * is queued with per-role position numbering, cancel a queued prompt by position, or move
@@ -150,176 +339,20 @@ export async function cmdPrompt(root, args) {
     }
     const role = parsed.role;
     if (parsed.mode === "list") {
-        // One payload, two shapes: the prose render and the --json output both come from the
-        // same array, so the per-role positions --cancel consumes can never disagree with the
-        // data a script reads. Full text, verbatim: this is the inspection command that tells
-        // you what a queued prompt actually says before you cancel it.
-        // `--role a,b` filters the list-wide rows, so section order and each section's own
-        // numbering stay what `--cancel <n> --role <id>` takes.
-        const listRoles = parseRoleListFlag(args, validIds);
-        const allRows = queuedListRows(root, null, validIds);
-        const scoped = listRoles === null ? allRows : allRows.filter((row) => listRoles.includes(row.role));
-        const prompts = queuedRowsMatching(scoped, parsed.grep ?? null);
-        if (parsed.json) {
-            // An empty queue still prints the document, the history --json empty-rows precedent.
-            sayJson({ prompts });
-            return;
-        }
-        if (prompts.length === 0 && scoped.length > 0) {
-            say(`no queued prompt matches "${parsed.grep}"`);
-            return;
-        }
-        if (prompts.length === 0) {
-            say(listRoles === null
-                ? "every inbox is empty"
-                : listRoles.length === 1
-                    ? `${roleLabel(listRoles[0])}'s inbox is empty`
-                    : `every listed inbox is empty (${listRoles.join(", ")})`);
-            return;
-        }
-        say(renderQueuedList(prompts, Date.now()));
+        runPromptList(root, args, parsed.json, parsed.grep, validIds);
         return;
     }
     if (parsed.mode === "cancel") {
-        if (role === null) {
-            // No --role: the position addresses what --list shows — its per-role sections, each
-            // numbered from 1 (the director first, then the roles in catalog order). Resolve across
-            // that scope: one role holding the position cancels there, several are ambiguous (the
-            // list itself shows two "N." lines), none is a miss. The output names the role, since
-            // the caller scoped nothing.
-            sayListedOutcome(cancelListedPrompt(root, listWideScope(root), parsed.position), parsed.position);
-            return;
-        }
-        const target = role ?? DIRECTOR_ROLE;
-        sayPromptOutcome(parsed.position, target, runRolePromptCommand(root, target, parsed.position, cancelRolePrompt), false);
+        runPromptCancel(root, parsed.position, role);
         return;
     }
     if (parsed.mode === "edit") {
-        // The same broken-config policy and list-wide resolution as cancel, one verb over: the
-        // file's new content rides the same queue file (position, enqueue stamp, and a pending
-        // --at deferral untouched), and a concurrent dequeue reports gone and exits clean. An
-        // `--attach` list is read through the same helper the enqueue form uses and appended to
-        // the prompt's images in place.
-        const images = parsed.attachPaths.length > 0 ? readPromptImages(parsed.attachPaths) : undefined;
-        // Image-input gate, `--edit`'s twin of the submit branch below (plans/image-input.md
-        // "Attachments", part 5/5): editing an attachment into a queued prompt is the same
-        // run-time discovery the submit gate prevents, so the refusal promise holds across every
-        // CLI attach surface — an image no configured model can read is refused before a byte is
-        // written, and a role that reroutes a blind read is told where the prompt will run. The
-        // target role is resolved first (the same resolution the verb below makes) so the gate can
-        // name it.
-        if (images !== undefined && images.length > 0) {
-            const targetRole = role ?? failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
-            const guidance = imagePromptGuidance(root, targetRole);
-            if (guidance.refusal)
-                return fail(guidance.refusal);
-            if (guidance.notice)
-                say(guidance.notice);
-        }
-        const typed = parsed.text;
-        if (typed === null) {
-            // Bare `--edit <n>`: open the prompt's body in the editor. The role is resolved first
-            // and the write goes by file name, so a dequeue while the editor is open reports gone
-            // instead of editing the neighbour that shifted into the position.
-            let target = role;
-            if (target === null) {
-                const resolved = resolveListedQueue(root, listWideScope(root), parsed.position);
-                target = failQueueMiss(resolved, parsed.position).role;
-            }
-            const targetRole = target;
-            let name;
-            let body;
-            try {
-                name = path.basename(queuedFileAtPosition(root, targetRole, parsed.position));
-                body = readQueuedPromptBody(root, targetRole, name);
-            }
-            catch (err) {
-                return fail(errorMessage(err));
-            }
-            if (body === null) {
-                sayPromptOutcome(parsed.position, targetRole, { status: "gone" }, role === null);
-                return;
-            }
-            const after = editInEditor(body, "prompt.md");
-            // An emptied buffer is an abort, not a blank prompt: the queue would otherwise hold a
-            // prompt with no text, which the enqueue forms refuse.
-            if (after.trim() === "" && body.trim() !== "")
-                fail("the edited prompt is empty; nothing changed (use --cancel <n> to drop it)");
-            if (after.trim() === body.trim() && images === undefined) {
-                say(`prompt ${parsed.position} unchanged`);
-                return;
-            }
-            try {
-                sayPromptOutcome(parsed.position, targetRole, editQueuedFile(root, targetRole, name, after, images), role === null);
-            }
-            catch (err) {
-                fail(errorMessage(err));
-            }
-            return;
-        }
-        if (role === null) {
-            sayListedOutcome(editListedPrompt(root, listWideScope(root), parsed.position, typed, images), parsed.position);
-            return;
-        }
-        const target = role ?? DIRECTOR_ROLE;
-        sayPromptOutcome(parsed.position, target, runRolePromptCommand(root, target, parsed.position, (r, role, position) => editRolePrompt(r, role, position, typed, images)), false);
+        runPromptEdit(root, parsed.position, parsed.text, parsed.attachPaths, role);
         return;
     }
     if (parsed.mode === "top") {
-        // The same list-wide resolution the cancel branch uses, one verb on: no --role resolves the
-        // position across `--list`'s per-role sections and moves it in the resolved role's queue;
-        // with --role it is the role-scoped call. A concurrent dequeue reports gone and exits
-        // clean; position 1 of the resolved role is "already first".
-        if (role === null) {
-            const targetRole = failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
-            let outcome;
-            try {
-                outcome = movePromptToTop(root, targetRole, parsed.position);
-            }
-            catch (err) {
-                return fail(errorMessage(err));
-            }
-            sayTopOutcome(parsed.position, targetRole, outcome, true);
-            return;
-        }
-        const target = role ?? DIRECTOR_ROLE;
-        let outcome;
-        try {
-            outcome = movePromptToTop(root, target, parsed.position);
-        }
-        catch (err) {
-            return fail(errorMessage(err));
-        }
-        sayTopOutcome(parsed.position, target, outcome, false);
+        runPromptTop(root, parsed.position, role);
         return;
     }
-    const target = role ?? DIRECTOR_ROLE;
-    // `--at <duration>` is a delay, not an epoch: the marker's not-before time is now + the
-    // parsed duration, computed at submit so the deferral starts when the operator queued it.
-    const dueMs = parsed.atDelayMs !== null ? Date.now() + parsed.atDelayMs : undefined;
-    // `--attach <path>`: read and validate through the shared helper (a bad path fails by name
-    // before anything is queued). An attachment the target role cannot read is refused here by
-    // name — the same gate submitRolePrompt enforces, surfaced early so the CLI exits non-zero
-    // with the fix before anything is written or queued; a role that reroutes a blind read is
-    // not refused, but the operator is told where the prompt will actually run.
-    const images = parsed.attachPaths.length > 0 ? readPromptImages(parsed.attachPaths) : undefined;
-    if (images && images.length > 0) {
-        const guidance = imagePromptGuidance(root, target);
-        if (guidance.refusal)
-            return fail(guidance.refusal);
-        if (guidance.notice)
-            say(guidance.notice);
-    }
-    const wake = submitRolePromptAndWake(root, target, parsed.text, images, dueMs);
-    const attached = images !== undefined ? ` with ${images.length} image(s)` : "";
-    const owner = target === DIRECTOR_ROLE ? "the director's" : `${roleLabel(target)}'s`;
-    if (parsed.atDelayMs !== null) {
-        // A deferred prompt's confirmation names the delivery delay, in the same duration
-        // vocabulary --at parsed (durationLabel), so the user can re-type it.
-        say(`added to ${owner} inbox — delivers in ${durationLabel(parsed.atDelayMs)}${attached}`);
-    }
-    else {
-        say(`added to ${owner} inbox${attached}`);
-    }
-    say(wake);
+    runPromptSubmit(root, parsed.text, parsed.atDelayMs, parsed.attachPaths, role);
 }

package/dist/src/init/init.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { saveConfig } from "../config/config.js";
 import { seedConfig } from "../config/config-example.js";
-import { findOnPath, writeTextAtomic } from "../files/files.js";
+import { ensureDir, findOnPath, writeTextAtomic } from "../files/files.js";
 import { GIT_MISSING_MESSAGE, commitAuthorArgs, committerIdentArgs, git, gitTry } from "../git/git-run.js";
 import { hasCommits, isGitRepo } from "../git/git.js";
 import { BRIEF_TEXT_MAX_CHARS, PROMPT_END, PROMPT_START, briefFile, briefTemplate, readBriefText, readmeTemplate, } from "../brief/brief.js";
@@ -71,25 +71,21 @@ async function isFreshProject(root, withCommits) {
         .filter((line) => line !== "");
     return listed.every(isScaffoldingPath);
 }
-/** Initialize a repo for tumwater: README (with prompt + status) when no project brief exists
- * yet, PLANS, BUGS, QUESTIONS, PRINCIPLES, tumwater.json, .gitignore — then commit whatever was
- * created. When the cwd is not a git repository yet, one is seeded first (`git init -b main`),
- * matching the README's "seeds a git repo" promise for brand-new projects. An existing repo
- * whose README.md carries no tumwater markers (or any repo without a brief, with `adopt`) is
- * adopted instead: the brief goes in TUMWATER.md and README.md is never touched. `--branch` seeds a
-new repository only and is refused on an existing one, where its value would otherwise be silently
-ignored. `dryRun` runs
- * the same validation and computes the same lists, but writes, inits and commits nothing. */
-export async function initProject(root, briefText, branch, opts = {}) {
-    const dryRun = opts.dryRun === true;
+/** The single job this helper owns: resolve the template up front, refusing an unknown id and
+ * defaulting to the blank template (INV-Q1: before any side effect). */
+function resolveInitTemplate(id) {
     // Resolve the template before any side effect: an unknown id (possible for direct callers of
     // initProject — the CLI parser already validated its own path) is refused up front, and the
     // template shapes everything below.
-    const template = opts.template ? getTemplate(opts.template) : null;
-    if (opts.template && !template) {
-        throw new Error(unknownTemplateError(opts.template));
+    const template = id ? getTemplate(id) : null;
+    if (id && !template) {
+        throw new Error(unknownTemplateError(id));
     }
-    const tpl = template ?? getTemplate("blank");
+    return template ?? getTemplate("blank");
+}
+/** The single job this helper owns: join the template's preamble with the operator's words and
+ * enforce the brief cap (INV-Q1: before any side effect). */
+function combineInitBrief(tpl, briefText) {
     // The brief records the template's preamble ahead of the operator's words, so their words
     // remain the tail ("latest instruction wins" reads naturally). The combined text rides into
     // every run's prefill, so it obeys the same cap as a bare prompt — reject before any side
@@ -100,16 +96,26 @@ export async function initProject(root, briefText, branch, opts = {}) {
     if (combinedPrompt.length > BRIEF_TEXT_MAX_CHARS) {
         throw new Error(tooLongMessage(`the brief with the ${tpl.id} template's preamble`, combinedPrompt.length, BRIEF_TEXT_MAX_CHARS, PREFILL_REASON));
     }
+    return combinedPrompt;
+}
+/** The single job this helper owns: refuse when `git` is missing from PATH (INV-Q1: before any
+ * side effect). */
+function requireGitOnPath() {
     if (!findOnPath("git"))
         throw new Error(GIT_MISSING_MESSAGE);
+}
+/** The single job this helper owns: refuse when `root` sits inside a team workspace (INV-Q1:
+ * before any side effect). */
+function refuseTeamWorkspace(root) {
     // A team workspace is not a project: seeding it would commit tumwater.json and a phantom
     // .tumwater on the role's branch. Refused before any side effect, dry run included.
     const owner = owningTeamRoot(root);
     if (owner !== undefined)
         throw new Error(teamWorkspaceMessage(owner));
-    // Validate everything that is pure validation before any side effect, so a bad prompt or
-    // README never leaves a half-seeded repo behind.
-    const prompt = briefText.trim();
+}
+/** The single job this helper owns: refuse a bare init that has no prompt to read anywhere
+ * (INV-Q1: before any side effect). */
+function refuseMissingBrief(root, prompt, combinedPrompt) {
     // A project brief that already carries the prompt makes it optional: a fresh clone of an
     // initialized project, or a checkout that lost its now-untracked tumwater.json
     // (plans/portability.md §4a/7), re-seeds with a bare `tumwater init` — the existing brief
@@ -125,6 +131,10 @@ export async function initProject(root, briefText, branch, opts = {}) {
             : "";
         throw new Error(`a brief is required: tumwater init <prompt | --file prompt.md>${readmeHint}`);
     }
+}
+/** The single job this helper owns: answer whether `root` is already a git repo, refusing
+ * `--branch` on one (INV-Q1: before any side effect). */
+async function resolveInitWasRepo(root, branch) {
     // `--branch` seeds a NEW repository only: an existing repo's checked-out branch is the
     // team's business (`tumwater start --branch` or baseBranch chooses it at runtime), so a
     // --branch given here would otherwise be silently ignored — the exact failure mode
@@ -135,6 +145,12 @@ export async function initProject(root, briefText, branch, opts = {}) {
     if (branch !== undefined && wasRepo) {
         throw new Error(`--branch only seeds a new repository: this directory is already a git repository and init leaves its checked-out branch alone — drop --branch, or point the team at a branch with \`tumwater start --branch ${branch}\` (or baseBranch in tumwater.json)`);
     }
+    return wasRepo;
+}
+/** The single job this helper owns: decide adoption — whether the brief goes to TUMWATER.md and
+ * README.md is left untouched — refusing an unmarked TUMWATER.md (INV-Q1: before any side
+ * effect). */
+function resolveInitAdoption(root, opts) {
     // The roles read the project's reason to exist back out of the project brief on every
     // run (readBriefText). A README.md without the managed section is the project's own
     // documentation, so it is never rewritten: the repo is adopted instead, with the brief in
@@ -150,6 +166,11 @@ export async function initProject(root, briefText, branch, opts = {}) {
     if (adopted && fs.existsSync(path.join(root, "TUMWATER.md"))) {
         throw new Error(`TUMWATER.md already exists without a brief between the tumwater:prompt markers, so your prompt would be lost — add it to TUMWATER.md between ${PROMPT_START} and ${PROMPT_END} (or delete TUMWATER.md so init creates one), then re-run \`tumwater init\``);
     }
+    return { brief, readmeExists, adopted };
+}
+/** The single job this helper owns: refuse a changed prompt when a brief already owns the
+ * managed sections (INV-Q1: before any side effect). */
+function refuseChangedBrief(root, brief, prompt, combinedPrompt) {
     // The same loss one step later: a brief that already owns the managed sections is never
     // rewritten (init only creates what is absent), so a DIFFERENT prompt given here would be
     // silently dropped while every run keeps running the old one. Refuse it and name the file
@@ -159,8 +180,13 @@ export async function initProject(root, briefText, branch, opts = {}) {
     if (prompt && brief !== null && combinedPrompt !== readBriefText(root)) {
         throw new Error(`${brief} already carries a different brief between the tumwater:prompt markers, and init never rewrites an existing project brief, so your prompt would be lost — to change the prompt, edit it in ${brief} between ${PROMPT_START} and ${PROMPT_END}; to re-seed with the current one, re-run a bare \`tumwater init\``);
     }
-    let repoInitialized = false;
-    let createdBranch;
+}
+/** The single job this helper owns: resolve and validate the new-repo branch, last, only when a
+ * repo will be seeded (INV-Q1: before any side effect). */
+async function resolveInitPreferredBranch(root, branch, wasRepo) {
+    // Last, resolve the new-repo branch — only when a repo will be seeded — and validate it with
+    // git's own rule before any side effect, dry run included.
+    let preferredBranch;
     if (!wasRepo) {
         // Branch precedence: the caller's explicit --branch, else git's own init.defaultBranch
         // preference, else main. `git init -b` does not consult init.defaultBranch, so the
@@ -179,10 +205,49 @@ export async function initProject(root, briefText, branch, opts = {}) {
                 : `git config init.defaultBranch ${JSON.stringify(preferred)}`;
             throw new Error(`${namedBy} is not a valid git branch name — pick a name like main, trunk, or release/2.0 (git's rules: no spaces, colons, or ~^?*[ characters; no leading/trailing slash or double slash; not a dotted or .lock-suffixed component)`);
         }
+        preferredBranch = preferred;
+    }
+    return preferredBranch;
+}
+/** Validate an init request and resolve everything it needs, in the existing order, with no
+ * write, no `git init`, no `created`/`leftAlone` allocation and no commit — every refusal
+ * an over-long brief, `--branch` on an existing repo, an invalid branch name or a team
+ * workspace (INV-Q1) throws here, ahead of any side effect, dry run included. The new-repo
+ * branch is validated last (only when a repo will be seeded) so the invalid-branch refusal
+ * still precedes any write. The body composes the named validation jobs in their invocation
+ * order (the template resolve, the brief cap, the git check, the team-workspace refusal, the
+ * missing-brief refusal, the `--branch`-on-an-existing-repo refusal, the adoption resolve,
+ * the changed-brief refusal and the preferred-branch resolve), so each job is found by name;
+ * every refusal still throws before any side effect (INV-Q1). Returns the resolved plan for
+ * `seedProject` to act on. */
+async function resolveInitPlan(root, briefText, branch, opts) {
+    const dryRun = opts.dryRun === true;
+    const tpl = resolveInitTemplate(opts.template);
+    const combinedPrompt = combineInitBrief(tpl, briefText);
+    requireGitOnPath();
+    refuseTeamWorkspace(root);
+    const prompt = briefText.trim();
+    refuseMissingBrief(root, prompt, combinedPrompt);
+    const wasRepo = await resolveInitWasRepo(root, branch);
+    const { brief, readmeExists, adopted } = resolveInitAdoption(root, opts);
+    refuseChangedBrief(root, brief, prompt, combinedPrompt);
+    const preferredBranch = await resolveInitPreferredBranch(root, branch, wasRepo);
+    return { dryRun, tpl, combinedPrompt, brief, readmeExists, adopted, wasRepo, preferredBranch };
+}
+/** Seed `root` from a resolved `InitPlan`: git init (a new repo only), every absent project
+ * file and starter directory, the config, and the commit. Holds the `created`/`leftAlone`
+ * bookkeeping locally; performs no validation and never refuses. Returns everything the
+ * composed `InitResult` needs except `adopted`, `dryRun` and `template`, which `initProject`
+ * reads off `plan`. */
+async function seedProject(root, plan) {
+    const { dryRun, tpl, combinedPrompt, brief, readmeExists, adopted, wasRepo, preferredBranch } = plan;
+    let repoInitialized = false;
+    let createdBranch;
+    if (!wasRepo) {
         if (!dryRun)
-            await git(root, "init", "-b", preferred);
+            await git(root, "init", "-b", preferredBranch);
         repoInitialized = true;
-        createdBranch = preferred;
+        createdBranch = preferredBranch;
     }
     // Decided before any project file is written (init only seeds bootstrap on a fresh project).
     // A repo the `git init` above just created (or a dry run would) has no commits, and init
@@ -254,7 +319,7 @@ export async function initProject(root, briefText, branch, opts = {}) {
     // The template's starter directories: empty ones only, before the first run — the team's
     // own runs write any code. Existing directories are left alone, like existing files above.
     for (const dir of tpl.starterDirs) {
-        claim(dir, path.join(root, dir), () => fs.mkdirSync(path.join(root, dir), { recursive: true }));
+        claim(dir, path.join(root, dir), () => ensureDir(path.join(root, dir)));
     }
     // The config stays out of the commit pathspec: `git add -- tumwater.json` fails on a path
     // the just-written .gitignore ignores (plans/portability.md §4a/7). It still heads the
@@ -274,5 +339,19 @@ export async function initProject(root, briefText, branch, opts = {}) {
             committed = true;
         }
     }
-    return { created, leftAlone, committed, repoInitialized, branch: createdBranch, adopted, dryRun, template: tpl.id, bootstrap };
+    return { created, leftAlone, committed, repoInitialized, branch: createdBranch, bootstrap };
+}
+/** Initialize a repo for tumwater: README (with prompt + status) when no project brief exists
+ * yet, PLANS, BUGS, QUESTIONS, PRINCIPLES, tumwater.json, .gitignore — then commit whatever was
+ * created. When the cwd is not a git repository yet, one is seeded first (`git init -b main`),
+ * matching the README's "seeds a git repo" promise for brand-new projects. An existing repo
+ * whose README.md carries no tumwater markers (or any repo without a brief, with `adopt`) is
+ * adopted instead: the brief goes in TUMWATER.md and README.md is never touched. `--branch` seeds a
+new repository only and is refused on an existing one, where its value would otherwise be silently
+ignored. `dryRun` runs
+ * the same validation and computes the same lists, but writes, inits and commits nothing. */
+export async function initProject(root, briefText, branch, opts = {}) {
+    const plan = await resolveInitPlan(root, briefText, branch, opts);
+    const seeded = await seedProject(root, plan);
+    return { ...seeded, adopted: plan.adopted, dryRun: plan.dryRun, template: plan.tpl.id };
 }

package/dist/src/merge/merge-core.js

@@ -225,7 +225,7 @@ export const RETRIABLE_MERGE_RESULTS = new Set([
  * conflict (mergeApprovedChange), so both send the change back for revision the same way. A
  * rejection with no `revisionRound` is a fresh change's first round (1). The director never
  * revises. */
-async function recordRejectedChange(root, role, state, rejectedHead, revisionRound, priorCounts) {
+export async function recordRejectedChange(root, role, state, rejectedHead, revisionRound, priorCounts) {
     if (role === DIRECTOR_ROLE)
         return;
     const nextRound = (revisionRound ?? 0) + 1;

package/dist/src/merge/merge-drain.js

@@ -7,7 +7,7 @@ import { errorMessage } from "../text/text.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { saveRunnerState } from "../runner/runner-state.js";
 import { addPostReview } from "../review/post-merge-review.js";
-import { drainPostReviews } from "./merge-post-review.js";
+import { drainPostReviews } from "./merge-post-review-drain.js";
 import { subscribeEvents } from "../events/events.js";
 import { treeDiffFiles } from "../git/git-diff.js";
 import { isExemptDiff } from "../review/exemptions.js";

package/dist/src/merge/merge-git.js

@@ -9,6 +9,7 @@ import { CONFIG_BASENAME, configPath } from "../paths.js";
 import { withPrimaryWorktreeLockAsync } from "../concurrency/lock.js";
 import { TUMWATER_SOURCE, warnEventBestEffort } from "../events/events.js";
 import { errorFirstLine, errorMessage, joinWithMore } from "../text/text.js";
+import { topAndHidden } from "../collections.js";
 /** Git plumbing for the merge flow: rebasing a worktree branch onto main, inspecting and
  * finishing a conflicted rebase, and fast-forwarding main — the mechanics, with no merge policy
  * of their own. Merge policy (lock → rebase → verify → ff, conflict resolution, batch ff)
@@ -56,10 +57,8 @@ export async function mainCommitsTouching(wt, since, mainBranch, files) {
         const [sha = "", subject = "", ...rest] = record.split("\x1f");
         return { sha, subject, body: capIntentBody(rest.join("\x1f").trim()) };
     });
-    return {
-        commits: parsed.slice(0, MAX_INTENT_COMMITS),
-        omitted: Math.max(0, parsed.length - MAX_INTENT_COMMITS),
-    };
+    const { visible: commits, hidden: omitted } = topAndHidden(parsed, MAX_INTENT_COMMITS);
+    return { commits, omitted };
 }
 /** Attempt to rebase the worktree branch onto main and classify the outcome WITHOUT
  * cleaning up: "rebased" (including already up to date), "conflict" (the rebase stopped on
@@ -191,7 +190,8 @@ export function conflictedFileHunks(wt, files) {
         }
         const text = readTextOrNull(full) ?? "";
         const all = text.includes("\0") ? [] : conflictHunkRanges(text);
-        return { path: f, hunks: all.slice(0, MAX_LISTED_HUNKS), more: Math.max(0, all.length - MAX_LISTED_HUNKS) };
+        const { visible: hunks, hidden: more } = topAndHidden(all, MAX_LISTED_HUNKS);
+        return { path: f, hunks, more };
     });
 }
 /** The reason naming every changed file that still carries a conflict marker, or undefined when