tumwater 0.1.2 → 0.2.0

package/dist/src/baseline/main-baseline.js

@@ -1,5 +1,6 @@
+// vocabulary: plain
 import { runBuildCheck, } from "../build/build-check.js";
-import { SLEEP_SPAN_TOLERANCE_MS, owesCleanRetry } from "../build/build-check-events.js";
+import { SLEEP_SPAN_TOLERANCE_MS, runWithCleanRetry } from "../build/build-check-events.js";
 import { sampleSleepClock } from "../build/host-sleep.js";
 import { CHECK_TIER, withCheckPermit } from "../concurrency/check-permit.js";
 import { detectBuildCheck } from "../build/build-check-detect.js";
@@ -10,11 +11,12 @@ import { isExemptDiff } from "../review/exemptions.js";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { isJsonObject } from "../files/json-object.js";
 import { baselineVerdictsPath } from "../paths.js";
-/** Fleet-shared verdict cache, keyed by main SHA. In-memory only: after a restart the cache is cold
+import { memoSetLru } from "../collections.js";
+/** Team-shared verdict cache, keyed by main SHA. In-memory only: after a restart the cache is cold
  * and one re-check per red SHA happens — cheap and deterministic, mirroring the budget gate's
  * stateless resume. Entries come from two sources: checkMainBaseline's own runs, and
  * noteGreenBaseline seeding a green verdict for a SHA that just became main
- * (src/landing/landing-merge.ts: either its in-lock post-rebase re-check passed on exactly that
+ * (src/merge/merge-to-main.ts: either its in-lock post-rebase re-check passed on exactly that
  * tree, or the rebase was a no-op so the review gate's pre-check had already run green on it).
  * A third kind of entry is an inherited green (MainBaseline.inheritedFrom), which no check
  * observed. It is carried over across doc-only differences (inheritedGreen, noteInheritedGreen)
@@ -26,7 +28,7 @@ import { baselineVerdictsPath } from "../paths.js";
  * tree: the same SHA can fail in one worktree and pass in another when the failure is really
  * about the environment the check ran in (a worktree with no install, a half-written
  * node_modules). On 2026-09-08 exactly that happened — a role worktree's environmental red
- * became the fleet-wide verdict that blocked the harness's own restart (BUGS.md) — so a caller
+ * became the team-wide verdict that blocked the harness's own restart (BUGS.md) — so a caller
  * whose false block is expensive may re-verify a red in its own worktree (`reverifyRed`), and a
  * green from that run promotes the SHA for everyone. Since 2026-09-18 that re-verification is
  * not opt-in only: a red carries the worktrees that observed it (`redFrom`) and is re-run by the
@@ -34,29 +36,24 @@ import { baselineVerdictsPath } from "../paths.js";
  * role until main moves — see shouldRerunRed. */
 const baselineCache = new Map();
 /** Safety cap so the per-process verdict cache can never grow unbounded: it is keyed by every
- * merged code SHA and a red entry carries the failed run's output tail, so a fleet running for
- * weeks would accumulate one entry per landing forever. Evicting the oldest entry (Map's
- * insertion order) costs at most one redundant suite run if that SHA is consulted again: a
- * green for a SHA that becomes main is re-seeded by the next landing (or its own
- * checkMainBaseline run), and a red is provisional by shouldRerunRed anyway. In-place updates
- * never grow the map and are never evicted. */
+ * merged code SHA and a red entry carries the failed run's output tail, so a team running for
+ * weeks would accumulate one entry per merge forever. Evicting the oldest entry (Map's insertion
+ * order) costs at most one redundant suite run if that SHA is consulted again: a green for a SHA
+ * that becomes main is re-seeded by the next merge (or its own checkMainBaseline run), and a red
+ * is provisional by shouldRerunRed anyway. In-place updates never grow the map and are never
+ * evicted. */
 const BASELINE_CACHE_MAX = 256;
 /** Insert or update `sha`'s verdict, evicting the oldest entry when a NEW SHA would exceed the
  * cap. Both write sites route through here so the cap cannot be bypassed, and so does the
  * mirror on disk (saveGreens). */
 function rememberBaseline(sha, baseline) {
-    if (!baselineCache.has(sha) && baselineCache.size >= BASELINE_CACHE_MAX) {
-        const oldest = baselineCache.keys().next().value;
-        if (oldest !== undefined)
-            baselineCache.delete(oldest);
-    }
-    baselineCache.set(sha, baseline);
+    memoSetLru(baselineCache, sha, baseline, BASELINE_CACHE_MAX);
     saveGreens();
 }
 /** The file the cache's greens are mirrored to (persistBaselineVerdicts), or undefined while no
- * fleet process has asked for it: the CLI and the tests keep the cache in memory only. */
+ * team process has asked for it: the CLI and the tests keep the cache in memory only. */
 let greensFile;
-/** Mirror the green verdicts to disk, so the fleet's next generation starts with them. A restart
+/** Mirror the green verdicts to disk, so the team's next generation starts with them. A restart
  * used to empty the cache, and the first tick after every restart re-ran the suite on a main the
  * previous generation had already verified (41 of 319 baseline runs over 2026-10-02..12 started
  * within 10 minutes of an orchestrator start). Only greens are kept: a green is a fact about an
@@ -76,7 +73,7 @@ function saveGreens() {
     }
 }
 /** Load the green verdicts a previous generation saved under `root` and keep mirroring them
- * there (saveGreens). Called once at fleet startup (cli/cli-run.ts). An entry the cache already
+ * there (saveGreens). Called once at team startup (cli/cli-run.ts). An entry the cache already
  * holds is left as it is, and a malformed file or entry reads as no data. */
 export function persistBaselineVerdicts(root) {
     const file = baselineVerdictsPath(root);
@@ -100,14 +97,14 @@ export function persistBaselineVerdicts(root) {
 const baselineInFlight = new Map();
 /** Should a cached RED be re-run here instead of trusted? A red says as much about the
  * environment the check ran in as about the tree — a worktree mid-install, or a machine under
- * the load the fleet deliberately creates starving a timing-sensitive test (BUGS.md's
- * load-sensitive tests entry). The role loops consult this fleet-shared cache and, before
+ * the load the team deliberately creates starving a timing-sensitive test (BUGS.md's
+ * load-sensitive tests entry). The role loops consult this team-shared cache and, before
  * 2026-09-18, trusted a red forever: one environmental red blocked every code role until main
  * moved, and main could not move, because blocking the code roles is exactly what stops it —
  * a deadlock broken only by restarting the orchestrator, since the cache is per-process.
  *
  * So a red is provisional until two DIFFERENT worktrees have seen it. The second observer pays
- * one extra suite run and a green from it promotes the SHA fleet-wide; a second red makes the
+ * one extra suite run and a green from it promotes the SHA team-wide; a second red makes the
  * verdict authoritative for everyone. The cost is bounded at ONE confirmation run per SHA, not
  * one per role. `reverifyRed` still forces a run unconditionally for the redeploy gate, whose
  * false block is expensive enough to always pay for its own opinion. */
@@ -119,32 +116,32 @@ function shouldRerunRed(cached, wt, reverifyRed) {
     const seen = cached.redFrom ?? [];
     return seen.length < 2 && !seen.includes(wt);
 }
-/** Record a green baseline verdict for `sha` WITHOUT running anything. The callers are the landing
- * path (src/landing/landing-merge.ts's verifyLanding) and the stack lander
- * (src/landing/landing-stack.ts' landStack) — both call it only after their fast-forward
- * SUCCEEDED, with the exact SHA that just became main: verifyLanding with the POST-rebase head
- * in two cases — its own in-lock re-check just ran this project's declared check green on that
- * tree, or the rebase was a no-op so the review gate's pre-check (which runs outside the merge
- * lock) had already run green on exactly this tree — and landStack with the stacked tip when a
- * scope-`batch` check ran green on exactly it (a skipped check seeds nothing, and neither does
- * a merge_blocked stack or a doc-only re-stack that landed without a check of its own). Seeding
- * here means that once the merge lands — main now points at this very SHA — the next fresh
+/** Record a green baseline verdict for `sha` WITHOUT running anything. The callers are the merge
+ * path (src/merge/merge-to-main.ts's verifyMerge) and the stack lander
+ * (src/merge/merge-stack.ts' mergeStack) — both call it only after their fast-forward SUCCEEDED,
+ * with the exact SHA that just became main: verifyMerge with the POST-rebase head in two cases —
+ * its own in-lock re-check just ran this project's declared check green on that tree, or the
+ * rebase was a no-op so the review gate's pre-check (which runs outside the merge lock) had
+ * already run green on exactly this tree — and mergeStack with the stacked tip when a
+ * scope-`batch` check ran green on exactly it (a skipped check seeds nothing, and neither does a
+ * merge_blocked stack or a doc-only re-stack that merged without a check of its own). Seeding
+ * here means that once the merge completes — main now points at this very SHA — the next fresh
  * tick's checkMainBaseline is a cache hit instead of re-running the full suite on an
  * already-verified tree: for tumwater itself that saves one redundant `npm test` (~1 min) per
  * merged code tick, plus every other role waking on "main moved" stalling behind that in-flight
  * run. Never seed a pre-rebase head: whenever main moved under the review, that SHA never
  * becomes main and the entry would silently miss (BUGS.md 2026-09-08). Safe because git trees
  * are immutable — a SHA's content cannot change under a cached verdict, the same staleness
- * semantics checkMainBaseline already has for its own entries. Only a directly observed pass
- * may seed this; skips and failures leave the baseline unknown (the caller decides). */
+ * semantics checkMainBaseline already has for its own entries. Only a directly observed pass may
+ * seed this; skips and failures leave the baseline unknown (the caller decides). */
 export function noteGreenBaseline(sha) {
     rememberBaseline(sha, { status: "green", sha });
 }
 /** Record an INHERITED green for `sha` (MainBaseline.inheritedFrom): a tree no check ran on, whose
  * only difference from the green-verified `from` is in review-exempt paths. The caller is
- * landing-merge.ts's verifyLanding, after it skipped the in-lock check because main moved
+ * merge-to-main.ts's verifyMerge, after it skipped the in-lock check because main moved
  * under the gate-verified head only by doc commits. It seeds the head about to become main, as
- * verifyLanding's own noteGreenBaseline calls do. If the fast-forward then fails, the entry is
+ * verifyMerge's own noteGreenBaseline calls do. If the fast-forward then fails, the entry is
  * still true of that tree and simply never consulted. It never displaces an observed verdict: a
  * check that actually ran on this tree knows more than the carry-over. */
 export function noteInheritedGreen(sha, from) {
@@ -153,22 +150,21 @@ export function noteInheritedGreen(sha, from) {
         return;
     rememberBaseline(sha, { status: "green", sha, inheritedFrom: from });
 }
-/** How far down main's first-parent history inheritedGreen looks for a verdict to carry over.
- * main gains about two dozen commits an hour under a full fleet, and the walk stops at the
- * first cached verdict anyway (every code landing seeds one), so this bound only caps the
- * rev-list on a cold cache. */
+/** How far down main's first-parent history inheritedGreen looks for a verdict to carry over. main
+ * gains about two dozen commits an hour under a full team, and the walk stops at the first cached
+ * verdict anyway (every code merge seeds one), so this bound only caps the rev-list on a cold
+ * cache. */
 const INHERIT_WALK_MAX = 64;
-/** A green for `sha` carried over from its nearest verdict-bearing first-parent ancestor, or
- * null when there is none to carry. The nearest ancestor with a cached verdict must be GREEN, and
- * the tree diff from it to `sha` must touch only `exemptPaths` (config.review.exemptPaths, the
- * same patterns that let a doc-only change land with no build check at all). Under that policy
- * a doc commit cannot change the suite's verdict, so re-running the suite on every doc-only
- * move of main buys nothing. Before this, 82% of the baseline runs (260 of 319 over
- * 2026-10-02..12) ran on a main whose tip was doc commits on top of a code landing that had
- * already seeded green. The nearest RED stops the walk: a doc commit after a red may be the
- * fix, so it is re-checked, never inherited past. An uncached ancestor is walked through, since
- * the single diff from the green covers it. Never throws: any git failure means no inheritance,
- * and the caller runs the suite as before. */
+/** A green for `sha` carried over from its nearest verdict-bearing first-parent ancestor, or null
+ * when there is none to carry. The nearest ancestor with a cached verdict must be GREEN, and the
+ * tree diff from it to `sha` must touch only `exemptPaths` (config.review.exemptPaths, the same
+ * patterns that let a doc-only change merge with no build check at all). Under that policy a doc
+ * commit cannot change the suite's verdict, so re-running the suite on every doc-only move of main
+ * buys nothing. Before this, 82% of the baseline runs (260 of 319 over 2026-10-02..12) ran on a
+ * main whose tip was doc commits on top of a code merge that had already seeded green. The nearest
+ * RED stops the walk: a doc commit after a red may be the fix, so it is re-checked, never inherited
+ * past. An uncached ancestor is walked through, since the single diff from the green covers it.
+ * Never throws: any git failure means no inheritance, and the caller runs the suite as before. */
 async function inheritedGreen(wt, sha, exemptPaths) {
     const ancestors = gitLines(await gitTry(wt, "rev-list", "--first-parent", `--max-count=${INHERIT_WALK_MAX}`, `${sha}^`));
     for (const ancestor of ancestors) {
@@ -191,14 +187,13 @@ function exemptPathsOf(config) {
     const patterns = config.review?.exemptPaths;
     return Array.isArray(patterns) ? patterns.filter((p) => typeof p === "string" && p !== "") : [];
 }
-/** The cached verdict for `sha` WITHOUT running anything — "green", "red", or undefined when
- * this process holds none. The redeployer's urgency carve-out consults it first (BUGS.md
- * 2026-09-30): a verdict already in hand answers the RUNNING build's redness for free — the
- * warm path, a red observed here while that SHA was still main's tip. Undefined — a cold
- * cache, e.g. a fresh orchestrator that inherited a stale build — sends the caller to run the
- * check itself (redeploy.ts's witness worktree at the build SHA), which lands in this same
- * cache and answers every later consult. Read-only: deciding a SHA's verdict is
- * checkMainBaseline's alone. */
+/** The cached verdict for `sha` WITHOUT running anything — "green", "red", or undefined when this
+ * process holds none. The redeployer's urgency carve-out consults it first (BUGS.md 2026-09-30): a
+ * verdict already in hand answers the RUNNING build's redness for free — the warm path, a red
+ * observed here while that SHA was still main's tip. Undefined — a cold cache, e.g. a fresh
+ * orchestrator that inherited a stale build — sends the caller to run the check itself
+ * (redeploy.ts's witness worktree at the build SHA), which is recorded in this same cache and
+ * answers every later consult. Read-only: deciding a SHA's verdict is checkMainBaseline's alone. */
 export function cachedBaselineVerdict(sha) {
     return baselineCache.get(sha)?.status;
 }
@@ -219,8 +214,8 @@ onRun,
 /** Ignore a cached RED verdict and run the suite here instead (a cached green still short-
  * circuits — see baselineCache). For the caller whose false block is expensive enough to pay
  * one extra run: the redeploy gate, where trusting another worktree's environmental red
- * strands the whole fleet on a stale build until main moves. A green from the re-run promotes
- * the SHA fleet-wide, which unblocks the role loops too. */
+ * strands the whole team on a stale build until main moves. A green from the re-run promotes
+ * the SHA team-wide, which unblocks the role loops too. */
 reverifyRed = false, 
 /** Ignore the cache entirely and run the suite here, even over a GREEN verdict. For the one
  * caller that cannot trust a green (BUGS.md 2026-10-06: the review gate re-attributing a
@@ -273,19 +268,11 @@ observedOnly = false) {
             // withCheckPermit): this runs the suite directly, so it must count against the cap too.
             // Only the one run per key holds a permit; deduped waiters above await `pending` holding
             // none.
-            const { outcome, durationMs } = await withCheckPermit(config, CHECK_TIER.other, async () => {
-                const startedAt = Date.now();
-                const first = await runBuildCheck(wt, check, undefined, undefined, sampleSleep);
-                if (!owesCleanRetry(first))
-                    return { outcome: first, durationMs: Date.now() - startedAt };
-                // Weather (a late deadline, a foreign kill, a host sleep) made no verdict about the tree:
-                // the first attempt is priced as its own run, and the retry's outcome stands — the same
-                // rule runScopedBuildCheck applies at every other scope.
-                onRun?.({ outcome: first, durationMs: Date.now() - startedAt });
-                const retryStart = Date.now();
-                const retry = await runBuildCheck(wt, check, undefined, undefined, sampleSleep);
-                return { outcome: retry, durationMs: Date.now() - retryStart };
-            });
+            const { outcome, durationMs } = await withCheckPermit(config, CHECK_TIER.other, () => runWithCleanRetry(() => runBuildCheck(wt, check, undefined, undefined, sampleSleep), 
+            // Weather (a late deadline, a foreign kill, a host sleep) made no verdict about the
+            // tree: the first attempt is priced as its own run, and the retry's outcome stands —
+            // the same rule runScopedBuildCheck applies at every other scope.
+            (first, dur) => onRun?.({ outcome: first, durationMs: dur })));
             onRun?.({ outcome, durationMs });
             if (outcome.status === "skipped") {
                 // Environmental (timeout/no-npm), after the clean retry above for weather shapes:
@@ -295,7 +282,7 @@ observedOnly = false) {
             if (outcome.status === "failed" && (outcome.run?.sleptMs ?? 0) > SLEEP_SPAN_TOLERANCE_MS) {
                 // A failure the host slept through made no verdict about the tree either (BUGS.md
                 // 2026-09-30): the sleep expired a test's own wall-clock wait at the wake and the suite
-                // exited 1 inside the deadline. Caching it red would make sleep weather the fleet's
+                // exited 1 inside the deadline. Caching it red would make sleep weather the team's
                 // authoritative red main, so nothing is cached — the next consult re-runs, and a clean
                 // verdict then settles the SHA exactly as before.
                 return { baseline: null, run: outcome.run, unverified: true };
@@ -311,9 +298,9 @@ observedOnly = false) {
                     outputTail: outcome.outputTail,
                     redFrom: priorRedFrom.includes(wt) ? priorRedFrom : [...priorRedFrom, wt],
                 };
-            // A green always lands (promoting a provisional red); a red never overwrites an observed
-            // green — a concurrent run may have promoted this SHA while this one was still going. An
-            // inherited green is no observation, so this run's verdict replaces it either way.
+            // A green is always recorded (promoting a provisional red); a red never overwrites an
+            // observed green — a concurrent run may have promoted this SHA while this one was still
+            // going. An inherited green is no observation, so this run's verdict replaces it either way.
             const current = baselineCache.get(sha);
             if (current?.status !== "green" || current.inheritedFrom !== undefined)
                 rememberBaseline(sha, baseline);
@@ -329,19 +316,19 @@ observedOnly = false) {
             baselineInFlight.delete(key);
     }
 }
-/** Is main green at the mirror worktree's HEAD? The landing path seeds a green verdict for
- * every merged code SHA (noteGreenBaseline — its in-lock post-rebase re-check, or the gate's
- * pre-check when the rebase was a no-op), so the common case is a cache hit. A head that only
- * added doc commits on top of such a SHA inherits its green (checkMainBaseline's
- * inheritedGreen). The redeployer's cooldown pre-warm asks this for every new head, and those doc
- * heads were most of the harness's baseline runs (247 of 319 over 2026-10-02..12). Otherwise the
- * project's declared check runs once in the mirror. No declared check or an
- * environmental skip reads as green — the gates' warn-and-proceed policy.
+/** Is main green at the mirror worktree's HEAD? The merge path seeds a green verdict for every
+ * merged code SHA (noteGreenBaseline — its in-lock post-rebase re-check, or the gate's pre-check
+ * when the rebase was a no-op), so the common case is a cache hit. A head that only added doc
+ * commits on top of such a SHA inherits its green (checkMainBaseline's inheritedGreen). The
+ * redeployer's cooldown pre-warm asks this for every new head, and those doc heads were most of the
+ * harness's baseline runs (247 of 319 over 2026-10-02..12). Otherwise the project's declared check
+ * runs once in the mirror. No declared check or an environmental skip reads as green — the gates'
+ * warn-and-proceed policy.
  *
  * A cached RED, though, is re-verified here (checkMainBaseline's `reverifyRed`) instead of
  * being taken as given. A red verdict can belong to the worktree that produced it rather than
  * to the tree, and the redeploy gate that asks this is the one place where believing a wrong
- * red is expensive: it strands the whole fleet on a stale build with no retry until main
+ * red is expensive: it strands the whole team on a stale build with no retry until main
  * moves. One extra suite run per red head buys that, and a green from it promotes the SHA for
  * every other gate too. */
 export async function mainIsGreen(mirrorWt, 
@@ -349,7 +336,7 @@ export async function mainIsGreen(mirrorWt,
  * §6/7), so a configured command makes the green check run on a non-npm repo too; its
  * maxConcurrentChecks sizes the check permit this run takes. */
 config, 
-/** Hook for the build_check event — this run is a minute of the fleet's time and belongs in
+/** Hook for the build_check event — this run is a minute of the team's time and belongs in
  * the feed like the role loops' own baseline checks. */
 onRun) {
     const check = await checkMainBaseline(mirrorWt, config, onRun, true);

package/dist/src/baseline/main-red.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import { baselineBlocked } from "../roles/roles.js";
 import { isCustomRole, liveConfig } from "../config/config.js";
 import { BUILD_CHECK_TIMEOUT_MS } from "../build/build-check-detect.js";
@@ -5,7 +6,7 @@ import { failureHeadline } from "../build/build-check-report.js";
 import { baselineCheckEventLogger, buildCheckSkipWarning, sleptPhrase } from "../build/build-check-events.js";
 import { checkMainBaseline } from "./main-baseline.js";
 import { buildMainRedNote } from "../prompt/gate-prompts.js";
-import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { mainRedPhrase } from "../text/phrases.js";
 import { branchHead } from "../git/git.js";
@@ -18,14 +19,15 @@ import { ensureDetachedWorktree } from "../git/worktree.js";
  * and "Tests red on main" entries), so while a SHA is known red the blocked roles skip authoring
  * instead of burning runs that are guaranteed to fail. Split out of loop.ts — which keeps the
  * tick lifecycle around it — because this is a self-contained policy with its own per-process
- * state (one harness-level warning per newly-discovered red SHA) and its own event contract; what
- * it borrows from the loop is identity and the role's worktree, and it consumes
+ * state (one harness-level `main_red_hold` event per newly-discovered red SHA) and its own
+ * event contract; what it borrows from the loop is identity and the role's worktree, and it
+ * consumes
  * build/build-check.ts's checkMainBaseline machinery (detection + execution + per-SHA cache),
  * which stays unaware of ticks. */
-/** The last main SHA for which this process logged a red-main warning (the baseline check):
- * one harness-level warning per newly-discovered red SHA, not one per blocked role's tick —
- * module-level so every runner in the fleet shares it. A restart re-logs once: the cache is
- * cold then too, and an operator restarting into a still-red main should see why nothing lands. */
+/** The last main SHA for which this process logged a red-main hold event (the baseline check): one
+ * harness-level warning per newly-discovered red SHA, not one per blocked role's tick —
+ * module-level so every runner in the team shares it. A restart re-logs once: the cache is cold
+ * then too, and an operator restarting into a still-red main should see why nothing merges. */
 let lastMainRedSha = null;
 /** The red-main message's shared spine — the SHA, script, and failure headline a red baseline
  * carries, phrased once so the once-per-SHA warning and the main_red outcome cannot drift apart
@@ -34,26 +36,32 @@ function redMainMessage(red, action) {
     const firstLine = failureHeadline(red.outputTail);
     return `${mainRedPhrase(red.sha)} (${red.script}${firstLine ? `: ${firstLine}` : ""}) — ${action}`;
 }
-/** Log the fleet-wide red-main warning for `red`'s SHA at most once per process. Module-level
- * (with lastMainRedSha) so the gate and the bugfix handoff share one guard: whichever observes
- * the red first logs it, the other stays silent. */
+/** Log the team-wide `main_red_hold` event (the notify hook pages it) for `red`'s SHA at
+ * most once per process. Module-level (with lastMainRedSha) so the gate and the bugfix
+ * handoff share one guard: whichever observes the red first logs it, the other stays silent. */
 function warnMainRedOnce(root, red) {
     if (lastMainRedSha === red.sha)
         return;
     lastMainRedSha = red.sha;
-    warnEventBestEffort(root, "harness", redMainMessage(red, "code merges blocked until main is green"));
+    logEventBestEffort(root, {
+        source: TUMWATER_SOURCE,
+        type: "main_red_hold",
+        sha: red.sha,
+        script: red.script,
+        message: redMainMessage(red, "code merges blocked until main is green"),
+    });
 }
 /** checkMainBaseline's per-run hook: log the one run per SHA (cache misses only) under the role
  * that paid for it, with its duration — the gate's build_check sibling, so both halves of the
- * fleet's deterministic verification are priced in the feed. The one logger for every baseline
+ * team's deterministic verification are priced in the feed. The one logger for every baseline
  * check this module runs — the bugfix handoff, the authoring gate, and mainTipVerdict's tip
- * check (which review.ts's gate and landing-check-failures.ts's attributeRedCheck reach
+ * check (which review.ts's gate and merge-check-failures.ts's attributeRedCheck reach
  * through it) — so the event's shape cannot drift between them. */
 function baselineCheckLogger(root, role) {
     return baselineCheckEventLogger(role, (event) => logEventBestEffort(root, event));
 }
 /** Red-main handoff for the `bugfix` healer: mainRedGate exempts
- * bugfix so the only role that can unblock the fleet may author, but its prompt then starts from
+ * bugfix so the only role that can unblock the team may author, but its prompt then starts from
  * BUGS.md and knows nothing about the red suite. This runs the same per-SHA baseline check
  * (cache and provisional-red re-verification reused unchanged, so it costs at most the one run
  * the gate would have paid for) and, when main is red, returns the note that points the healer
@@ -68,7 +76,7 @@ export async function bugfixMainRedNote(root, role, wt) {
     if (red?.status !== "red")
         return undefined;
     warnMainRedOnce(root, red);
-    return buildMainRedNote(red.sha, red.script, failureHeadline(red.outputTail));
+    return buildMainRedNote(red.sha, red.script, failureHeadline(red.outputTail), red.outputTail);
 }
 /** Gate one fresh tick on main's baseline. Returns null when authoring may proceed — role not
  * blocked, no declared check, green, or an environmental skip (warned under the role and
@@ -104,7 +112,7 @@ sampleSleep) {
         return {
             result: "main_red",
             summary: "code merges blocked until main is green",
-            // The cause rides the outcome so the tick's `tick_end` carries it
+            // The cause rides the outcome so the tick's `run_end` carries it
             // (tick-finalize.ts folds it into state.lastError before logging): the digest itemizes
             // the outcome that blocks every merge, instead of leaving it a bare count behind a
             // once-per-SHA warning (BUGS.md 2026-09-28).
@@ -113,25 +121,25 @@ sampleSleep) {
     }
     return null;
 }
-/** Serializes mainTipVerdict's use of its one worktree: the landing pipeline's vets run their
+/** Serializes mainTipVerdict's use of its one worktree: the merge pipeline's verifies run their
  * gates concurrently, and a second gate re-pointing the checkout at a newer main while the first's
- * check ran in it would measure a tree that is neither. Each link is bounded — a few git
- * commands plus at most one check run, which runBuildCheck kills at its timeout — and takes no
- * other lock, so a waiter waits at most for the gates queued ahead of it. */
+ * check ran in it would measure a tree that is neither. Each link is bounded — a few git commands
+ * plus at most one check run, which runBuildCheck kills at its timeout — and takes no other lock,
+ * so a waiter waits at most for the gates queued ahead of it. */
 let gateMainQueue = Promise.resolve();
 /** Main's baseline verdict at its current tip, for attributing a gate check that failed twice
  * (src/review/review.ts): gateMainWorktreePath is re-pointed at `mainBranch`'s tip and asked
- * through checkMainBaseline — the same per-SHA, fleet-wide cache mainRedGate reads, which every
- * landing seeds green for the SHA it moved main to, so the common case is a cache hit. A miss
- * (or a provisional red from another worktree, or a green that was only inherited across doc
- * commits) runs the declared check once here, bounded by its timeout. A red is warned fleet-wide once per SHA, exactly as mainRedGate warns it. Never
- * throws: an unreadable main, a checkout that fails, no declared check on main, or a skipped
- * run all read as `unavailable`.
+ * through checkMainBaseline — the same per-SHA, team-wide cache mainRedGate reads, which every
+ * merge seeds green for the SHA it moved main to, so the common case is a cache hit. A miss (or a
+ * provisional red from another worktree, or a green that was only inherited across doc commits)
+ * runs the declared check once here, bounded by its timeout. A red is warned team-wide once per
+ * SHA, exactly as mainRedGate warns it. Never throws: an unreadable main, a checkout that fails, no
+ * declared check on main, or a skipped run all read as `unavailable`.
  *
- * `forceFresh` bypasses that per-SHA cache and runs main's declared check now, even over a
- * cached green (checkMainBaseline's forceFresh): the review gate needs it to re-attribute a
- * repeated gate failure on a clock- or load-sensitive test whose cached green has gone stale
- * (BUGS.md 2026-10-06). The landing pipeline's attribution reads the cached verdict instead. */
+ * `forceFresh` bypasses that per-SHA cache and runs main's declared check now, even over a cached
+ * green (checkMainBaseline's forceFresh): the review gate needs it to re-attribute a repeated gate
+ * failure on a clock- or load-sensitive test whose cached green has gone stale (BUGS.md
+ * 2026-10-06). The merge pipeline's attribution reads the cached verdict instead. */
 export function mainTipVerdict(root, role, mainBranch, config, forceFresh = false) {
     const run = gateMainQueue.then(() => verdictAtMainTip(root, role, mainBranch, config, forceFresh));
     gateMainQueue = run.catch(() => undefined);

package/dist/src/brief/brief-edit.js

@@ -0,0 +1,43 @@
+// vocabulary: plain
+import fs from "node:fs";
+import path from "node:path";
+import { INITIAL_PROMPT_MAX_CHARS, PROMPT_END, PROMPT_START, briefPath, replaceInitialPrompt } from "./brief.js";
+import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
+import { withStateLock } from "../concurrency/lock.js";
+import { writeTextAtomic } from "../files/files.js";
+import { stampedSubject } from "../git/commit-message.js";
+import { primaryWorktreeLockPath } from "../paths.js";
+import { PREFILL_REASON } from "../text/phrases.js";
+import { tooLongMessage } from "../text/text.js";
+const NO_BRIEF = "no project brief with a prompt block found — run `tumwater init` first";
+/** Replace the initial prompt with `text` under the checks init applies (non-empty, at most
+ * INITIAL_PROMPT_MAX_CHARS, no prompt marker), write it under the primary-worktree lock, and
+ * commit that one file on main. The one writer behind `tumwater brief --file` and the
+ * dashboard's Settings card, so the two cannot drift. */
+export async function editInitialPrompt(root, text) {
+    const prompt = text.trim();
+    if (prompt === "")
+        return { ok: false, error: "the new brief is empty" };
+    if (prompt.length > INITIAL_PROMPT_MAX_CHARS)
+        return { ok: false, error: tooLongMessage("the new brief", prompt.length, INITIAL_PROMPT_MAX_CHARS, PREFILL_REASON) };
+    if (prompt.includes(PROMPT_START) || prompt.includes(PROMPT_END))
+        return { ok: false, error: "the new brief contains a tumwater:prompt marker, which would break the block for every reader" };
+    const file = briefPath(root);
+    if (file === null)
+        return { ok: false, error: NO_BRIEF };
+    const name = path.basename(file);
+    const changed = withStateLock(primaryWorktreeLockPath(root), () => {
+        const current = fs.readFileSync(file, "utf8");
+        const next = replaceInitialPrompt(current, prompt);
+        if (next === null)
+            return `${name} no longer carries a prompt block`;
+        if (next === current)
+            return false;
+        writeTextAtomic(file, next);
+        return true;
+    });
+    if (typeof changed === "string")
+        return { ok: false, error: changed };
+    const committed = changed && (await commitOperatorBacklogEdit(root, name, stampedSubject("operator", "Edit brief"))); // vocabulary-ok: commit prefix stays
+    return { ok: true, file: name, changed, committed };
+}

package/dist/src/{brief.js → brief/brief.js}

@@ -1,7 +1,8 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
-import { briefCandidates } from "./paths.js";
-import { errorMessage, truncateWithNote } from "./text/text.js";
+import { briefCandidates } from "../paths.js";
+import { errorMessage, truncateWithNote } from "../text/text.js";
 /** The managed sections of the project brief (TUMWATER.md, with README.md as the
  * compatibility path — plans/portability.md §7a/7): marker constants, the templates a fresh
  * repo gets, and reading the project's initial prompt back out. */
@@ -9,7 +10,7 @@ export const PROMPT_START = "<!-- tumwater:prompt:start -->";
 export const PROMPT_END = "<!-- tumwater:prompt:end -->";
 /** Cap on the initial prompt (see readInitialPrompt). The prompt is the project's reason to
  * exist and rides into EVERY tick and director prompt, so unbounded text would be a standing
- * per-tick prefill cost — the same budget customLoops.task and roles.<id>.instructions are
+ * per-tick prefill cost — the same budget customRoles.task and roles.<id>.instructions are
  * held to. `tumwater init` rejects an over-long prompt before it is committed (init.ts); this
  * constant is the shared bound so the read path and the init check cannot drift. */
 export const INITIAL_PROMPT_MAX_CHARS = 4096;
@@ -18,6 +19,11 @@ export const INITIAL_PROMPT_MAX_CHARS = 4096;
 // prompt markers above stay exported because init.ts names them in its error message.
 export const STATUS_START = "<!-- tumwater:status:start -->";
 export const STATUS_END = "<!-- tumwater:status:end -->";
+/** The placeholder every fresh template seeds between the status markers. A brief still
+ * carrying exactly this body (or an empty one) is "description incomplete"; once the readme
+ * role replaces it with a real status the tight-loop rule turns itself off. Hoisted so the
+ * template and briefStatusIncomplete cannot drift on the wording. */
+export const EMPTY_STATUS = "_No status yet. The readme role keeps this section up to date._";
 /** The two managed sections a fresh brief carries — the initial prompt in its prompt
  * markers, an empty status in its status markers — under the given H1. Both homes render
  * the identical body (README.md for a fresh repo, TUMWATER.md for an adopted one), so the
@@ -26,7 +32,7 @@ export const STATUS_END = "<!-- tumwater:status:end -->";
 function managedSections(heading, initialPrompt) {
     return `# ${heading}
 
-## Initial prompt
+## Brief
 
 ${PROMPT_START}
 ${initialPrompt.trim()}
@@ -35,7 +41,7 @@ ${PROMPT_END}
 ## Status
 
 ${STATUS_START}
-_No status yet. The readme loop keeps this section up to date._
+${EMPTY_STATUS}
 ${STATUS_END}
 `;
 }
@@ -67,7 +73,7 @@ function ownsBrief(text) {
  * A candidate that exists but cannot be read (README.md created as a directory, a
  * permission-lost file) is an operator-visible break, not a silent skip: the brief is
  * every loop's reason to exist, read each tick, so falling through to the next candidate
- * could run the fleet on the wrong brief and throwing raw would crash every tick with an
+ * could run the team on the wrong brief and throwing raw would crash every tick with an
  * errno that names neither the file nor the fix — the message below names both. */
 function firstBriefText(root, accepts) {
     for (const candidate of briefCandidates(root)) {
@@ -78,7 +84,7 @@ function firstBriefText(root, accepts) {
             text = fs.readFileSync(candidate, "utf8");
         }
         catch (err) {
-            throw new Error(`cannot read the project brief ${JSON.stringify(path.basename(candidate))}: ${errorMessage(err)} — every loop reads this file's prompt each tick, so make it a readable file carrying the ${PROMPT_START}/${PROMPT_END} markers (or move it aside)`);
+            throw new Error(`cannot read the project brief ${JSON.stringify(path.basename(candidate))}: ${errorMessage(err)} — every role reads this file's brief on each run, so make it a readable file carrying the ${PROMPT_START}/${PROMPT_END} markers (or move it aside)`);
         }
         if (accepts(text))
             return { file: path.basename(candidate), text };
@@ -92,6 +98,25 @@ function firstBriefText(root, accepts) {
 export function briefFile(root) {
     return readBrief(root)?.file ?? null;
 }
+/** False when there is no resolved brief, or the resolved brief carries no well-formed
+ * STATUS_START/STATUS_END pair (a malformed brief is doctor's warning, not a tight loop);
+ * otherwise true when the status body between the markers is empty or still the EMPTY_STATUS
+ * placeholder. The one machine-detectable "description not yet complete" signal: the initial
+ * prompt half of the description is always present (init rejects an empty one). One small
+ * single-file read, like readInitialPrompt. */
+export function briefStatusIncomplete(root) {
+    const found = firstBriefText(root, ownsBrief);
+    if (!found)
+        return false;
+    const bodyStart = found.text.indexOf(STATUS_START);
+    if (bodyStart < 0)
+        return false;
+    const bodyEnd = found.text.indexOf(STATUS_END, bodyStart + STATUS_START.length);
+    if (bodyEnd < 0)
+        return false;
+    const body = found.text.slice(bodyStart + STATUS_START.length, bodyEnd).trim();
+    return body === "" || body === EMPTY_STATUS;
+}
 /** The project's initial prompt, extracted from the resolved brief file's managed section —
  * TUMWATER.md when it exists with markers, else README.md (plans/portability.md §7a/7). The
  * closing marker is searched for only AFTER the opening one: an end marker mentioned in prose
@@ -101,19 +126,45 @@ export function briefFile(root) {
 export function readInitialPrompt(root) {
     return readBrief(root)?.prompt ?? "";
 }
-function extractPrompt(text) {
+/** The full path of the file that owns the prompt block (the same candidate readBrief
+ * resolves), or null when none does — so a writer edits the file every reader reads. */
+export function briefPath(root) {
+    const found = firstBriefText(root, ownsBrief);
+    return found ? path.join(root, found.file) : null;
+}
+/** `text` with the prompt block's content replaced by `prompt` (trimmed), every byte outside
+ * the two markers kept; null when the text has no well-formed block. Finds the block by
+ * extractPrompt's rule (first start marker, then the first end marker after it). */
+export function replaceInitialPrompt(text, prompt) {
+    const start = text.indexOf(PROMPT_START);
+    if (start < 0)
+        return null;
+    const bodyStart = start + PROMPT_START.length;
+    const end = text.indexOf(PROMPT_END, bodyStart);
+    if (end < 0)
+        return null;
+    return `${text.slice(0, bodyStart)}\n${prompt.trim()}\n${text.slice(end)}`;
+}
+/** The trimmed, untruncated text between the first start marker and the first end marker after
+ * it; null when `text` has no well-formed block. */
+export function promptBlockOf(text) {
     const start = text.indexOf(PROMPT_START);
     if (start < 0)
         return null;
     const end = text.indexOf(PROMPT_END, start + PROMPT_START.length);
     if (end < 0)
         return null;
-    const prompt = text.slice(start + PROMPT_START.length, end).trim();
+    return text.slice(start + PROMPT_START.length, end).trim();
+}
+function extractPrompt(text) {
+    const prompt = promptBlockOf(text);
+    if (prompt === null)
+        return null;
     // A hand-edited brief can carry an over-long prompt past init's length check. Truncate it
     // for every tick instead of injecting the whole thing (the same defensive cap readPrinciples
     // applies, through text.ts's truncateWithNote), with a visible note so the loss is not
     // silent. init rejects the normal path before it is committed, so this is the backstop.
-    return truncateWithNote(prompt, INITIAL_PROMPT_MAX_CHARS, "initial prompt");
+    return truncateWithNote(prompt, INITIAL_PROMPT_MAX_CHARS, "brief");
 }
 /** The resolved brief as one value: the owning file's basename (briefFile) and its extracted
  * initial prompt (readInitialPrompt) from a SINGLE firstBriefText scan. Tick prompt assembly
@@ -125,3 +176,8 @@ export function readBrief(root) {
     const found = firstBriefText(root, ownsBrief);
     return found ? { file: found.file, prompt: extractPrompt(found.text) ?? "" } : null;
 }
+/** The brief's plain-text form: its file name, then the initial prompt — what `tumwater brief`
+ * prints and the TUI's Brief tab shows, so the two cannot drift. */
+export function renderBrief(brief) {
+    return `${brief.file}\n${brief.prompt}`;
+}