tumwater 0.2.0 → 0.3.0

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

@@ -1,12 +1,11 @@
-// vocabulary: plain
 /** The CLI layer of `tumwater prompt` — the steering-prompt command: submit a prompt to the
- * director (default) or one role's queue, `--list` what is queued with per-loop position
+ * director (default) or one role's queue, `--list` what is queued with per-role position
  * numbering, or `--cancel <n>` a queued prompt by position. Split out of
  * operator/operator-commands.ts because this command is not a team-control marker: its
  * sibling commands there ride the operator-intent marker protocol, while this command drives
- * the durable per-loop queues (src/inbox/inbox.ts) through the inbox-cancel, inbox-edit, and
+ * the durable per-role queues (src/inbox/inbox.ts) through the inbox-cancel, inbox-edit, and
  * operator-intent helpers, each with its own broken-config policy — so the command lives
- * beside the queue module it drives. The team-side half — the dequeue and requeue a loop
+ * beside the queue module it drives. The team-side half — the dequeue and requeue a role
  * performs — is inbox.ts and pending-prompt.ts. */
 import { fail, say, sayJson } from "../cli/cli-output.js";
 import path from "node:path";
@@ -15,8 +14,8 @@ import { cancelListedPrompt, cancelRolePrompt, resolveListedQueue, } from "./inb
 import { editListedPrompt, editQueuedFile, editRolePrompt, readQueuedPromptBody, } from "./inbox-edit.js";
 import { movePromptToTop } from "./inbox-top.js";
 import { editInEditor } from "../cli/cli-editor.js";
-import { listWideScope, queuedFileAtPosition, promptPreview, queuedListRows, renderQueuedList } from "./inbox.js";
-import { durationLabel } from "../cli/cli-args.js";
+import { listWideScope, queuedFileAtPosition, promptPreview, queuedListRows, queuedRowsMatching, renderQueuedList } from "./inbox.js";
+import { durationLabel, parseRoleListFlag } from "../cli/cli-args.js";
 import { knownRoleIds, knownRoleIdsCached, loadConfig } from "../config/config.js";
 import { errorMessage } from "../text/text.js";
 import { readPromptImageFiles } from "./inbox-attachments.js";
@@ -33,8 +32,8 @@ function failQueueMiss(listed, position) {
         if (listed.status === "ambiguous") {
             fail(`position ${position} is in more than one role's inbox (${listed.roles.join(", ")}) — name one with --role <id>`);
         }
-        // `queued` is the longest queue's length — the highest position any loop's numbering can
-        // reach — so a miss names it as the valid range when at least one loop holds a prompt.
+        // `queued` is the longest queue's length — the highest position any role's numbering can
+        // reach — so a miss names it as the valid range when at least one role holds a prompt.
         const range = listed.queued > 0 ? ` — valid: 1-${listed.queued}` : "";
         fail(`no prompt at position ${position} (longest inbox holds ${listed.queued})${range}`);
     }
@@ -46,15 +45,15 @@ function isQueueMiss(listed) {
     return listed.status === "ambiguous" || listed.status === "missing";
 }
 /** The shared tail of the list-wide cancel/edit branches: report an ambiguity (naming the
- * rival loops, with the `--role` escape hatch) or a miss (carrying the length of the longest
- * queue, the highest position numbering any loop can hold), else render the resolved outcome
+ * rival roles, with the `--role` escape hatch) or a miss (carrying the length of the longest
+ * queue, the highest position numbering any role can hold), else render the resolved outcome
  * through sayPromptOutcome. One helper so the
  * two verbs' handling of the miss shapes cannot drift. */
 function sayListedOutcome(listed, position) {
     const found = failQueueMiss(listed, position);
     sayPromptOutcome(position, found.role, found.outcome, true);
 }
-/** Run one loop-targeted queue verb (cancelRolePrompt/editRolePrompt) for a `--role`-scoped
+/** Run one role-targeted queue verb (cancelRolePrompt/editRolePrompt) for a `--role`-scoped
  * command: a thrown failure (a broken config, an unwritable queue) exits through fail with
  * its message, a success returns the verb's outcome for the caller to render. One helper so
  * the cancel and edit branches' broken-config policy cannot drift. */
@@ -70,7 +69,7 @@ function runRolePromptCommand(root, role, position, verb) {
  * cancel and edit modes (list-wide and `--role`-scoped each): a concurrent dequeue is a normal
  * race, not an error, so it is reported and exited clean; a resolved one previews the text it
  * removed (a cancel's `text`) or wrote (an edit's `newText`). When `labelRole` the line names
- * the loop — the no-`--role` command resolves across every loop, so its output must say where
+ * the role — the no-`--role` command resolves across every role, so its output must say where
  * the prompt went — while a `--role`-scoped command already names it in the user's own
  * command. One helper so the cancel and edit wordings cannot drift. */
 function sayPromptOutcome(position, role, outcome, labelRole) {
@@ -83,7 +82,7 @@ function sayPromptOutcome(position, role, outcome, labelRole) {
     say(labelRole ? `${outcome.status} (${role}): ${promptPreview(text)}` : `${outcome.status}: ${promptPreview(text)}`);
 }
 /** The gone-case tail shared by every resolved queue-verb reply: a concurrent dequeue is a
- * normal race, not an error, so report it and exit clean, naming the loop that took the
+ * normal race, not an error, so report it and exit clean, naming the role that took the
  * prompt. One helper so the cancel, edit and top verbs' gone wording cannot drift. */
 function sayPromptGone(position, role) {
     say(`prompt ${position} is no longer in the inbox — ${roleLabel(role)} already took it`);
@@ -91,7 +90,7 @@ function sayPromptGone(position, role) {
 /** The user-facing reply for one resolved top — the two branches of cmdPrompt's top mode
  * (list-wide and `--role`-scoped): a concurrent dequeue is a normal race, not an error, so it
  * is reported and exited clean; a resolved one previews the moved prompt. When `labelRole` the
- * line names the loop — the no-`--role` command resolves across every loop, so its output must
+ * line names the role — the no-`--role` command resolves across every role, so its output must
  * say where the prompt moved — while a `--role`-scoped command already names it in the user's
  * own command. The `sayPromptOutcome` contract, so the verbs cannot drift. */
 function sayTopOutcome(position, role, outcome, labelRole) {
@@ -115,53 +114,67 @@ function readPromptImages(paths) {
     }
 }
 /** `tumwater prompt [--role <id>] <text|list|cancel <n>|top <n>>`: submit a steering prompt to the
- * director (default) or one role's queue, list what is queued with per-loop position
- * numbering, cancel a queued prompt by position, or move one to the head of its
- * queue. The dispatcher in cli.ts gates on a ready
- * repo and delegates here; list output is grouped by loop — the director first (its queue is
+ * 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
+ * one to the head of its queue. The dispatcher in cli.ts gates on a ready repo and
+ * delegates here; list output is grouped by role — the director first (its queue is
  * the shared one every pre-1/2 prompt landed in), then each role with queued prompts — so a
  * per-role queue's position numbering stays unambiguous. */
 export async function cmdPrompt(root, args) {
     const parsed = parsePromptArgs(args);
-    if (parsed.role !== null)
+    // --list takes a comma list (parseRoleListFlag below); every other mode keeps one id.
+    if (parsed.role !== null && parsed.mode !== "list")
         parsed.role = canonicalRoleId(parsed.role);
-    // `--role <id>` scopes every mode to one loop's queue; the value is validated here, with
+    // `--role <id>` scopes every mode to one role's queue; the value is validated here, with
     // the same message every other --role consumer uses. The director is always valid: its
     // queue is the historical inbox (inbox.ts).
     //
     // Where the id set comes from differs by mode, following parseRoleScope's split: --list is
     // a read-only view, so a transiently broken tumwater.json must not take it down — it falls
     // back to the built-in catalog (knownRoleIdsCached), exactly like cmdLogs/cmdHistory's
-    // --role scope, at the cost of a broken config hiding a custom loop's queued section. The
+    // --role scope, at the cost of a broken config hiding a custom role's queued section. The
     // state-changing modes (enqueue, cancel) instead read through loadConfig and fail loudly
-    // when an id was given: before writing to a named loop's queue the operator is owed the
-    // config error, not a built-ins-only guess about whether the loop exists. With no --role,
+    // when an id was given: before writing to a named role's queue the operator is owed the
+    // config error, not a built-ins-only guess about whether the role exists. With no --role,
     // enqueue touches only the director queue (inbox.ts) and never reads the config — a broken
     // tumwater.json must not block steering the director — while cancel resolves its position
-    // across the per-loop sections --list prints, through the same cached, never-throwing id set
+    // across the per-role sections --list prints, through the same cached, never-throwing id set
     // --list uses, so it cancels exactly what the list showed even under a broken config.
     const validIds = parsed.mode === "list"
         ? knownRoleIdsCached(root)
         : parsed.role !== null
             ? knownRoleIds(loadConfig(root))
             : null;
-    if (validIds !== null && parsed.role !== null && !validIds.includes(parsed.role)) {
+    if (parsed.mode !== "list" && validIds !== null && parsed.role !== null && !validIds.includes(parsed.role)) {
         fail(unknownRoleMessage(parsed.role, validIds));
     }
     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-loop positions --cancel consumes can never disagree with 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.
-        const prompts = queuedListRows(root, role, validIds);
+        // `--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(role !== null ? `${roleLabel(role)}'s inbox is empty` : "every inbox is empty");
+            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()));
@@ -169,10 +182,10 @@ export async function cmdPrompt(root, args) {
     }
     if (parsed.mode === "cancel") {
         if (role === null) {
-            // No --role: the position addresses what --list shows — its per-loop sections, each
+            // 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 loop holding the position cancels there, several are ambiguous (the
-            // list itself shows two "N." lines), none is a miss. The output names the loop, since
+            // 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;
@@ -190,14 +203,14 @@ export async function cmdPrompt(root, args) {
         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
-        // tick-time discovery the submit gate prevents, so the refusal promise holds across every
+        // 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 loop that reroutes a blind read is told where the prompt will run. The
-        // target loop is resolved first (the same resolution the verb below makes) so the gate can
+        // 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 loop = role ?? failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
-            const guidance = imagePromptGuidance(root, loop);
+            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)
@@ -205,7 +218,7 @@ export async function cmdPrompt(root, args) {
         }
         const typed = parsed.text;
         if (typed === null) {
-            // Bare `--edit <n>`: open the prompt's body in the editor. The loop is resolved first
+            // 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;
@@ -213,18 +226,18 @@ export async function cmdPrompt(root, args) {
                 const resolved = resolveListedQueue(root, listWideScope(root), parsed.position);
                 target = failQueueMiss(resolved, parsed.position).role;
             }
-            const loop = target;
+            const targetRole = target;
             let name;
             let body;
             try {
-                name = path.basename(queuedFileAtPosition(root, loop, parsed.position));
-                body = readQueuedPromptBody(root, loop, name);
+                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, loop, { status: "gone" }, role === null);
+                sayPromptOutcome(parsed.position, targetRole, { status: "gone" }, role === null);
                 return;
             }
             const after = editInEditor(body, "prompt.md");
@@ -237,7 +250,7 @@ export async function cmdPrompt(root, args) {
                 return;
             }
             try {
-                sayPromptOutcome(parsed.position, loop, editQueuedFile(root, loop, name, after, images), role === null);
+                sayPromptOutcome(parsed.position, targetRole, editQueuedFile(root, targetRole, name, after, images), role === null);
             }
             catch (err) {
                 fail(errorMessage(err));
@@ -254,19 +267,19 @@ export async function cmdPrompt(root, args) {
     }
     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-loop sections and moves it in the resolved loop's queue;
+        // 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 loop is "already first".
+        // clean; position 1 of the resolved role is "already first".
         if (role === null) {
-            const loop = failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
+            const targetRole = failQueueMiss(resolveListedQueue(root, listWideScope(root), parsed.position), parsed.position).role;
             let outcome;
             try {
-                outcome = movePromptToTop(root, loop, parsed.position);
+                outcome = movePromptToTop(root, targetRole, parsed.position);
             }
             catch (err) {
                 return fail(errorMessage(err));
             }
-            sayTopOutcome(parsed.position, loop, outcome, true);
+            sayTopOutcome(parsed.position, targetRole, outcome, true);
             return;
         }
         const target = role ?? DIRECTOR_ROLE;
@@ -285,9 +298,9 @@ export async function cmdPrompt(root, args) {
     // 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 loop cannot read is refused here by
+    // 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 loop that reroutes a blind read is
+    // 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) {

package/dist/src/inbox/prompt-not-before.js

@@ -5,7 +5,7 @@
  * format migrates. Composed by notBeforeMarker, parsed by notBeforeMs — the two live together
  * so format and parser cannot drift. inbox.ts (the prompt-queue store) writes the marker into
  * enqueueRolePrompt's single atomic write and filters on deliverableNow; the display surfaces
- * (prompt-commands.ts, tick-prompt.ts) strip it with stripNotBeforeMarker. */
+ * (prompt-commands.ts, run-prompt.ts) strip it with stripNotBeforeMarker. */
 /** The marker line a deferred prompt's queue file starts with. */
 const NOT_BEFORE_PREFIX = "tumwater:not-before ";
 /** The marker line (plus the blank separator) that defers a queue file to `at` epoch ms.
@@ -17,7 +17,7 @@ export function notBeforeMarker(at) {
  * `YYYY-MM-DDTHH:MM:SS.sssZ`. Only a marker carrying the writer's full shape — the stamp line
  * plus the blank separator notBeforeMarker appends — counts as plumbing; anything else
  * after the prefix is the prompt's own content (e.g. a queued prompt that begins with a
- * marker-like line asking a loop to fix the marker itself, or a hand-edited file that lost
+ * marker-like line asking a role to fix the marker itself, or a hand-edited file that lost
  * the blank line), not a deferral. The stamp and separator are checked together so this
  * parser and stripNotBeforeMarker — which strips exactly this shape — can never disagree
  * about what is plumbing. */

package/dist/src/init/init-templates.js

@@ -1,9 +1,8 @@
-// vocabulary: plain
 /** The bundled project templates for `tumwater init --template`
  * (docs/feature-project-templates.md). Static string data, no file reads and no runtime
  * dependencies: a template is a brief preamble (the operator's own words stay appended after
  * it) plus a seeded PLANS.md backlog and a starter directory layout — never code scaffolds,
- * since the team's own first ticks write any code.
+ * since the team's own first runs write any code.
  * `blank` is the default and reproduces today's init output byte-identically. */
 import { typoSuffix } from "../text/suggest.js";
 const PYTHON_CLI_PREAMBLE = `This project is a Python command-line tool.

package/dist/src/init/init.js

@@ -1,13 +1,13 @@
-// vocabulary: plain
 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 { COMMIT_IDENT, GIT_MISSING_MESSAGE, git, gitTry } from "../git/git-run.js";
+import { GIT_MISSING_MESSAGE, commitAuthorArgs, committerIdentArgs, git, gitTry } from "../git/git-run.js";
 import { hasCommits, isGitRepo } from "../git/git.js";
-import { INITIAL_PROMPT_MAX_CHARS, PROMPT_END, PROMPT_START, briefFile, briefTemplate, readInitialPrompt, readmeTemplate, } from "../brief/brief.js";
-import { CONFIG_BASENAME, STATE_DIR, configPath } from "../paths.js";
+import { BRIEF_TEXT_MAX_CHARS, PROMPT_END, PROMPT_START, briefFile, briefTemplate, readBriefText, readmeTemplate, } from "../brief/brief.js";
+import { teamWorkspaceMessage } from "../gates/readiness.js";
+import { CONFIG_BASENAME, STATE_DIR, configPath, owningTeamRoot } from "../paths.js";
 import { projectName } from "../project-name.js";
 import { tooLongMessage } from "../text/text.js";
 import { PREFILL_REASON } from "../text/phrases.js";
@@ -58,7 +58,7 @@ function isScaffoldingPath(rel) {
 /** Whether `root` has a project of its own yet: not a git repo, a repo with no commits, or a
  * repo whose tracked and untracked-non-ignored files are all init's scaffolding. Drives the
  * bootstrap seed — a project created from nothing runs plan and feature before the maintenance
- * loops (plans/work-ratio.md, part 2/2). `withCommits` is whether `root` is a repo with at least
+ * roles (plans/work-ratio.md, part 2/2). `withCommits` is whether `root` is a repo with at least
  * one commit, which initProject has already established. One `ls-files -co` lists the tracked
  * files and the untracked non-ignored ones together (the exclude rules filter only the
  * untracked side). */
@@ -80,7 +80,7 @@ async function isFreshProject(root, withCommits) {
 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, initialPrompt, branch, opts = {}) {
+export async function initProject(root, briefText, branch, opts = {}) {
     const dryRun = opts.dryRun === true;
     // 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
@@ -92,24 +92,29 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     const tpl = template ?? getTemplate("blank");
     // 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 tick's prefill, so it obeys the same cap as a bare prompt — reject before any side
+    // every run's prefill, so it obeys the same cap as a bare prompt — reject before any side
     // effect so an overflowing preamble never lands in README.md.
     const combinedPrompt = tpl.briefPreamble
-        ? `${tpl.briefPreamble}\n\n${initialPrompt.trim()}`
-        : initialPrompt.trim();
-    if (combinedPrompt.length > INITIAL_PROMPT_MAX_CHARS) {
-        throw new Error(tooLongMessage(`the brief with the ${tpl.id} template's preamble`, combinedPrompt.length, INITIAL_PROMPT_MAX_CHARS, PREFILL_REASON));
+        ? `${tpl.briefPreamble}\n\n${briefText.trim()}`
+        : briefText.trim();
+    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));
     }
     if (!findOnPath("git"))
         throw new Error(GIT_MISSING_MESSAGE);
+    // 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 = initialPrompt.trim();
+    const prompt = briefText.trim();
     // 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
     // file is never rewritten, so a prompt given here must match it (refused below otherwise).
-    if (!prompt && combinedPrompt.trim() === "" && readInitialPrompt(root) === "") {
+    if (!prompt && combinedPrompt.trim() === "" && readBriefText(root) === "") {
         // A bare init with no prompt is only ever refused for one of two reasons, and they have
         // different fixes: no README (nothing to read — the message below is the whole story) or a
         // README that lacks the managed markers (bare init reads them — name the file and the
@@ -130,8 +135,8 @@ export async function initProject(root, initialPrompt, 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)`);
     }
-    // The loops read the project's reason to exist back out of the project brief on every
-    // tick (readInitialPrompt). A README.md without the managed section is the project's own
+    // 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
     // TUMWATER.md (plans/portability.md §7/7) — the same path `--adopt` asks for explicitly.
     // A brief that is already marked (in either file) wins over both: nothing brief-shaped is
@@ -140,18 +145,18 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     const readmeExists = fs.existsSync(path.join(root, "README.md"));
     const adopted = brief === null && (opts.adopt === true || readmeExists);
     // A TUMWATER.md without the markers is create-if-absent's blind spot: it would be left
-    // untouched and the prompt silently dropped — every loop would then run blind. Fail before
+    // untouched and the prompt silently dropped — every role would then run blind. Fail before
     // creating anything so the user fixes it and re-runs.
     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\``);
     }
     // 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 tick keeps running the old one. Refuse it and name the file
+    // silently dropped while every run keeps running the old one. Refuse it and name the file
     // that owns the brief — TUMWATER.md resolves ahead of README.md (plans/portability.md §7a/7),
     // so pointing at README.md would send the user to edit a file nobody reads. A re-run with the
     // same prompt, or a bare init, is the idempotent re-seed and passes.
-    if (prompt && brief !== null && combinedPrompt !== readInitialPrompt(root)) {
+    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;
@@ -207,7 +212,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     const write = (name, content) => claim(name, path.join(root, name), () => writeTextAtomic(path.join(root, name), content));
     // README.md is the brief only when none exists yet and there is no README to adopt (a fresh
     // repo): with TUMWATER.md owning the managed sections, a created README.md would carry a
-    // duplicate prompt + status block that readInitialPrompt never reaches and the readme role
+    // duplicate prompt + status block that readBriefText never reaches and the readme role
     // never maintains.
     const name = projectName(root);
     if (brief !== null)
@@ -220,7 +225,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
     else
         write("README.md", readmeTemplate(name, combinedPrompt));
     // A template with starter plans seeds the backlog with them, rendered as `### ` entries —
-    // the primary entry format every backlog reader parses — so the team's first ticks land on
+    // the primary entry format every backlog reader parses — so the team's first runs land on
     // real work. blank keeps the `_None yet._` placeholder byte-identical to today.
     const plansContent = tpl.starterPlans.length > 0
         ? PLANS_TEMPLATE.replace("_None yet._", tpl.starterPlans.map((p) => `### ${p}`).join("\n\n"))
@@ -246,8 +251,8 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         created.push(".gitignore");
     else if (fs.existsSync(path.join(root, ".gitignore")))
         leftAlone.push(".gitignore");
-    // The template's starter directories: empty ones only, before the first tick — the team's
-    // own ticks write any code. Existing directories are left alone, like existing files above.
+    // 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 }));
     }
@@ -265,7 +270,7 @@ export async function initProject(root, initialPrompt, branch, opts = {}) {
         if (staged === null) {
             // Non-zero exit = something is staged.
             const message = withCommits ? "tumwater: init files" : "tumwater: init";
-            await git(root, ...COMMIT_IDENT, "commit", "-m", message, "--", ...committable);
+            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "-m", message, "--", ...committable);
             committed = true;
         }
     }