plumbbob 0.10.3 → 0.11.0

package/dist/verbs/agent.js

@@ -20,6 +20,9 @@ import { SLOTS, composeStepContext, formatAgentList, isSlot, listAgents, parseSl
 import { appendToSection } from "../lib/buildlog.js";
 import { resolveBoolean, resolveNumber, resolveRecord } from "../lib/settings.js";
 import { appendHandoff, buildFolder, buildLogPath, hasSession, intentPath, resolveBuild, stepPath } from "../lib/sidecar.js";
+import { notice } from "../lib/notice.js";
+/** The remedy on an ambient binding's advisory: a binding is configuration the loop must survive without. */
+const SKIPPING = 'skipping this binding, since the loop works without it';
 /**
  * Dispatch `plumbbob agent list|run`, refusing an unknown subcommand with a hint.
  */
@@ -30,7 +33,9 @@ export async function agent(cwd, args = []) {
     if (sub === 'run')
         return run(cwd, rest);
     const known = 'Available subcommands: list, run.';
-    const message = sub === undefined ? `plumbbob agent <subcommand>. ${known}` : `plumbbob: unknown 'agent' subcommand '${sub}'. ${known}`;
+    const message = sub === undefined
+        ? `plumbbob agent <subcommand>. ${known}`
+        : notice({ fact: `unknown 'agent' subcommand '${sub}'`, remedy: 'plumbbob agent list, or plumbbob agent run' }).trimEnd();
     process.stderr.write(`${message}\n`);
     return 1;
 }
@@ -40,7 +45,7 @@ export async function agent(cwd, args = []) {
 function list(cwd, _args) {
     const root = findRepoRoot(cwd);
     if (root === null) {
-        process.stderr.write('plumbbob: not inside a git repository.\n');
+        process.stderr.write(notice({ fact: 'not inside a git repository' }));
         return 1;
     }
     process.stdout.write(`${formatAgentList(listAgents(root))}\n`);
@@ -58,7 +63,7 @@ function list(cwd, _args) {
 async function run(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
-        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        process.stderr.write(notice({ fact: 'no active session', remedy: 'plumbbob start "<title>"' }));
         return 1;
     }
     const { build: slug, rest } = resolveBuild(root, args);
@@ -69,13 +74,17 @@ async function run(cwd, args) {
     }
     const step = parsed.step ?? readStep(root, slug);
     if (step === null) {
-        process.stderr.write('plumbbob: no step to run against — pass --step N, or `plumbbob build N` first.\n');
+        process.stderr.write(notice({ fact: 'no step to run against', remedy: 'pass --step N, or plumbbob build N first' }));
         return 1;
     }
     // A `--agent <path>` flag still needs a name; it labels an explicit run (the
     // handoff ledger and the human summary key on the name), it does not name one.
     if (parsed.name === undefined && parsed.flagPath !== undefined) {
-        process.stderr.write('plumbbob: --agent needs an agent name too, for the run label. Try: plumbbob agent run reviewer --agent ./path --step 3.\n');
+        process.stderr.write(notice({
+            fact: '--agent needs an agent name too',
+            detail: ['the name is the run label'],
+            remedy: 'plumbbob agent run reviewer --agent ./path --step 3',
+        }));
         return 1;
     }
     // An explicit name outranks every binding: run exactly it, fail loud on a
@@ -103,12 +112,13 @@ async function run(cwd, args) {
 async function runOne(root, slug, step, spec) {
     const resolution = resolveAgent(root, spec.name, spec.flagPath !== undefined ? { flagPath: spec.flagPath } : {});
     if (!resolution.ok) {
-        return degrade(spec.ambient, `plumbbob: ${resolution.error}`, `plumbbob: bound agent "${spec.name}" did not resolve — ${resolution.error} Skipping — D54 (bindings-degrade-soft): the loop works without it.`);
+        return degrade(spec.ambient, notice({ fact: resolution.error }).trimEnd(), notice({ fact: resolution.error, advisory: true, remedy: SKIPPING }).trimEnd());
     }
     const { manifest, dir } = resolution.agent;
     const resolved = resolveMode(spec.mode, manifest);
     if (!resolved.ok) {
-        return degrade(spec.ambient, resolved.error, `plumbbob: bound agent "${spec.name}" — ${resolved.error.replace(/^plumbbob:\s*/, '')} Skipping — D54 (bindings-degrade-soft).`);
+        const parts = { fact: resolved.fact, detail: resolved.detail };
+        return degrade(spec.ambient, notice(resolved.remedy === undefined ? parts : { ...parts, remedy: resolved.remedy }).trimEnd(), notice({ ...parts, advisory: true, remedy: SKIPPING }).trimEnd());
     }
     const mode = resolved.mode;
     let intent;
@@ -116,7 +126,7 @@ async function runOne(root, slug, step, spec) {
         intent = readFileSync(intentPath(root, slug), 'utf8');
     }
     catch {
-        process.stderr.write('plumbbob: no intent.md for the active build — cannot compose the agent input.\n');
+        process.stderr.write(notice({ fact: 'no intent.md for the active build', detail: ['cannot compose the agent input'] }));
         return 1;
     }
     const composed = composeStepContext({
@@ -168,11 +178,14 @@ async function runOne(root, slug, step, spec) {
  */
 async function runBound(root, slug, step, modeFlag) {
     if (modeFlag === undefined) {
-        process.stderr.write('plumbbob: agent run needs an agent name, or --mode <slot> to run the step\'s bound agents.\n');
+        process.stderr.write(notice({
+            fact: 'agent run needs an agent name',
+            remedy: "name one, or pass --mode <slot> to run the step's bound agents",
+        }));
         return 1;
     }
     if (!isSlot(modeFlag)) {
-        process.stderr.write(`plumbbob: unknown --mode '${modeFlag}' — slots are ${SLOTS.join(', ')}.\n`);
+        process.stderr.write(notice({ fact: `unknown --mode '${modeFlag}'`, detail: [...SLOTS] }));
         return 1;
     }
     const harness = readHarnessFile(join(buildFolder(root, slug), 'harness.json'));
@@ -188,7 +201,7 @@ async function runBound(root, slug, step, modeFlag) {
         slot: modeFlag,
     });
     if (names.length === 0) {
-        process.stderr.write(`plumbbob: no agents bound to the '${modeFlag}' slot for step ${step} — nothing to run.\n`);
+        process.stderr.write(notice({ fact: `no agents bound to the '${modeFlag}' slot for step ${step}`, detail: ['nothing to run'] }));
         return 0;
     }
     let worst = 0;
@@ -229,20 +242,20 @@ function parseRunArgs(args) {
         if (arg === '--step') {
             const value = args[++i];
             if (value === undefined || !/^\d+$/.test(value) || Number(value) < 1) {
-                return 'plumbbob: --step needs a positive step number.';
+                return notice({ fact: '--step needs a positive step number' }).trimEnd();
             }
             step = Number(value);
         }
         else if (arg === '--mode') {
             const value = args[++i];
             if (value === undefined)
-                return `plumbbob: --mode needs a slot (${SLOTS.join(', ')}).`;
+                return notice({ fact: '--mode needs a slot', detail: [...SLOTS] }).trimEnd();
             mode = value;
         }
         else if (arg === '--agent') {
             const value = args[++i];
             if (value === undefined)
-                return 'plumbbob: --agent needs a path to an agent directory.';
+                return notice({ fact: '--agent needs a path to an agent directory' }).trimEnd();
             flagPath = value;
         }
         else if (!arg.startsWith('--')) {
@@ -262,12 +275,14 @@ function parseRunArgs(args) {
  */
 function resolveMode(flag, manifest) {
     if (flag !== undefined) {
-        if (!isSlot(flag))
-            return { ok: false, error: `plumbbob: unknown --mode '${flag}' — slots are ${SLOTS.join(', ')}.` };
+        if (!isSlot(flag)) {
+            return { ok: false, fact: `unknown --mode '${flag}'`, detail: [...SLOTS] };
+        }
         if (!manifest.slots.includes(flag)) {
             return {
                 ok: false,
-                error: `plumbbob: agent "${manifest.name}" does not declare the '${flag}' slot (it declares ${manifest.slots.join(', ')}).`,
+                fact: `agent "${manifest.name}" does not declare the '${flag}' slot`,
+                detail: [`it declares ${manifest.slots.join(', ')}`],
             };
         }
         return { ok: true, mode: flag };
@@ -276,7 +291,9 @@ function resolveMode(flag, manifest) {
         return { ok: true, mode: manifest.slots[0] };
     return {
         ok: false,
-        error: `plumbbob: agent "${manifest.name}" declares multiple slots (${manifest.slots.join(', ')}) — pass --mode <slot>.`,
+        fact: `agent "${manifest.name}" declares multiple slots`,
+        detail: manifest.slots,
+        remedy: 'pass --mode <slot>',
     };
 }
 /**
@@ -307,15 +324,18 @@ function report(root, slug, name, mode, step, result) {
 function failureLine(name, result) {
     switch (result.reason) {
         case 'exit':
-            return `plumbbob: agent "${name}" exited ${result.code} — failed run, stopping. No side effects applied.`;
+            return notice({
+                fact: `agent "${name}" exited ${result.code}`,
+                detail: ['a failed run, stopping', 'no side effects applied'],
+            }).trimEnd();
         case 'contract':
-            return `plumbbob: agent "${name}" is out of contract — ${result.error}`;
+            return notice({ fact: `agent "${name}" is out of contract`, detail: [result.error] }).trimEnd();
         case 'timeout':
-            return `plumbbob: agent "${name}" timed out after ${result.seconds}s — killed.`;
+            return notice({ fact: `agent "${name}" timed out after ${result.seconds}s`, detail: ['killed'] }).trimEnd();
         case 'interrupted':
-            return `plumbbob: interrupted — killed agent "${name}".`;
+            return notice({ fact: `agent "${name}" killed`, detail: ['interrupted'] }).trimEnd();
         case 'spawn':
-            return `plumbbob: could not spawn agent "${name}" — ${result.error}`;
+            return notice({ fact: `could not spawn agent "${name}"`, detail: [result.error] }).trimEnd();
     }
 }
 /**
@@ -334,17 +354,20 @@ function applyParked(root, slug, parked) {
         content = readFileSync(path, 'utf8');
     }
     catch {
-        process.stderr.write(`plumbbob: no build-log.md — could not park ${parked.length} line(s) the agent returned.\n`);
+        process.stderr.write(notice({
+            fact: 'no build-log.md',
+            detail: [`could not park ${parked.length} line${parked.length === 1 ? '' : 's'} the agent returned`],
+        }));
         return;
     }
     for (const line of parked) {
         const updated = appendToSection(content, 'Park list', `- [ ] ${line}`);
         if (updated === null) {
-            process.stderr.write(`plumbbob: no "## Park list" in build-log.md — could not park: ${line}\n`);
+            process.stderr.write(notice({ fact: 'no "## Park list" in build-log.md', detail: [`could not park ${line}`] }));
             return;
         }
         content = updated;
-        process.stderr.write(`plumbbob: parked — ${line}\n`);
+        process.stderr.write(notice({ prefix: 'parked', fact: line }));
     }
     writeFileSync(path, content);
 }
@@ -356,15 +379,24 @@ function applyParked(root, slug, parked) {
  * the same status for the calling skill; this stderr copy is the terminal read.
  */
 function humanSummary(name, mode, envelope) {
-    const head = `plumbbob: agent "${name}" (${mode}) — ${envelope.status}: ${envelope.summary}\n`;
-    const notes = envelope.notes.length > 0 ? `  notes: ${envelope.notes}\n` : '';
+    const detail = [`${mode} slot`, envelope.summary];
+    if (envelope.notes.length > 0)
+        detail.push(envelope.notes);
     if (envelope.status === 'blocked') {
-        return `${head}  blocked — the agent couldn't finish; unblock and re-run.\n${notes}`;
+        return notice({
+            fact: `agent "${name}" reports blocked`,
+            detail,
+            remedy: "the agent couldn't finish, so unblock it and re-run",
+        });
     }
     if (envelope.status === 'drift') {
-        return `${head}  drift — the plan no longer matches reality; /plumbbob:refine before continuing.\n${notes}`;
+        return notice({
+            fact: `agent "${name}" reports drift`,
+            detail,
+            remedy: 'the plan no longer matches reality, so /plumbbob:refine before continuing',
+        });
     }
-    return head;
+    return notice({ fact: `agent "${name}" reports ${envelope.status}`, detail });
 }
 /**
  * The in-flight step for this build (the STEP marker `build` wrote), or null.

package/dist/verbs/build.js

@@ -10,6 +10,7 @@ import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTic
 import { parseStepSeam } from "../lib/intent.js";
 import { parseSteps } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
+import { notice } from "../lib/notice.js";
 /**
  * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
@@ -21,7 +22,7 @@ import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
-        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        process.stderr.write(notice({ fact: 'no active session', remedy: 'plumbbob start "<title>"' }));
         return 1;
     }
     const { build: slug, rest } = resolveBuild(root, args);
@@ -30,13 +31,17 @@ export function build(cwd, args) {
     // through the range, then pause), not a CLI capability: the CLI records one
     // in-flight step at a time. Name it rather than bounce off the generic usage.
     if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
-        process.stderr.write(`plumbbob: build takes one step number; \`${raw}\` step ranges are a \`/plumbbob:build\` feature (auto-approve through the range, then pause). Try \`plumbbob build ${raw.split('-')[0]}\`.\n`);
+        process.stderr.write(notice({
+            fact: 'build takes one step number',
+            detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through it and then pauses`],
+            remedy: `plumbbob build ${raw.split('-')[0]}`,
+        }));
         return 1;
     }
     // An explicit arg that isn't a positive integer is a usage error: caught before
     // reading intent.md so the message doesn't depend on the plan being present.
     if (raw !== undefined && (!/^\d+$/.test(raw) || Number(raw) < 1)) {
-        process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n');
+        process.stderr.write(notice({ fact: 'build needs a step number', remedy: 'plumbbob build 2' }));
         return 1;
     }
     const intent = readFileSync(intentPath(root, slug), 'utf8');
@@ -49,7 +54,11 @@ export function build(cwd, args) {
     if (raw === undefined) {
         const nextUndone = steps.find((s) => !s.done);
         if (nextUndone === undefined) {
-            process.stderr.write('plumbbob: no undone step to build — every planned step is checkpointed. `/plumbbob:step` to add an increment, or `/plumbbob:finish`.\n');
+            process.stderr.write(notice({
+                fact: 'no undone step to build',
+                detail: ['every planned step is checkpointed'],
+                remedy: '/plumbbob:step to add an increment, or /plumbbob:finish',
+            }));
             return 1;
         }
         step = nextUndone.n;
@@ -59,7 +68,7 @@ export function build(cwd, args) {
     }
     const parsed = parseStepSeam(intent, step);
     if (!parsed.ok) {
-        process.stderr.write(`plumbbob: ${parsed.error} Fix the step's seam in intent.md, then \`build ${step}\` again.\n`);
+        process.stderr.write(notice({ fact: parsed.error, remedy: `fix the step's seam in intent.md, then \`build ${step}\` again` }));
         return 1;
     }
     writeFileSync(seamPath(root, slug), `${parsed.seam.join('\n')}\n`);
@@ -81,10 +90,17 @@ export function build(cwd, args) {
     // deliberate `build 22` and a confused one look different on the page.
     const skipped = raw === undefined ? 0 : steps.filter((s) => !s.done && s.n < step).length;
     const picked = raw === undefined
-        ? ' (next undone)'
+        ? ['next undone']
         : skipped > 0
-            ? ` (explicitly requested; skips ${skipped} undone step${skipped === 1 ? '' : 's'})`
-            : '';
-    process.stdout.write(`plumbbob: building step ${step}${picked}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
+            ? ['explicitly requested', `skips ${skipped} undone step${skipped === 1 ? '' : 's'}`]
+            : [];
+    // Two lines, one colon each, then the seam as a plain readout beneath the
+    // notice that frames it: the paths are a list, and a list is not a one-liner.
+    process.stdout.write(notice({ fact: `building step ${step}`, detail: picked }) +
+        notice({
+            fact: 'the seam is orientation, not a lock',
+            detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],
+        }) +
+        `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }

package/dist/verbs/check.js

@@ -67,10 +67,15 @@ function slotList(args, flag) {
     return names.length > 0 ? { [flag.slice(2)]: names } : {};
 }
 /**
- * The one-line human verdict for a check exit code.
+ * The one-line human verdict for a check exit code, printed on its own line.
  *
- * A broken gate (exit 2) reports distinctly from red: a misconfigured harness
- * must never read as broken code, though both block a checkpoint.
+ * This is `plumbbob check`'s own console verdict, for whoever ran it. In the
+ * turn anatomy the gate verdict's home is the recap's check row, which
+ * `plumbbob handoff` re-emits from its own read of `.check/summary.json`
+ * (docs/presentation.md); nothing relays these strings any more, but they stay
+ * word-for-word stable because humans grep scrollback for them. A broken gate
+ * (exit 2) reports distinctly from red: a misconfigured harness must never
+ * read as broken code, though both block a checkpoint.
  */
 function verdictLine(code) {
     if (code === 0)

package/dist/verbs/checkpoint.js

@@ -11,7 +11,7 @@
 // DESIGN boundary.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearTick, detailPath, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
@@ -20,6 +20,8 @@ import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
+import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { boundaryEnding } from "./handoff.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
  *
@@ -29,7 +31,7 @@ import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 export async function checkpoint(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
-        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        process.stderr.write(notice({ fact: 'no active session', remedy: 'plumbbob start "<title>"' }));
         return 1;
     }
     // Before either staging path: `-A` below, and the plan commit's folder-scoped
@@ -41,7 +43,7 @@ export async function checkpoint(cwd, args) {
     }
     const step = resolveStep(root, args);
     if (step === null) {
-        process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
+        process.stderr.write(notice({ fact: 'no step to checkpoint', remedy: 'pass a step number, or plan a step in intent.md first' }));
         return 1;
     }
     // Checked before the latch and the check gate: a socket stdin can never
@@ -70,22 +72,32 @@ export async function checkpoint(cwd, args) {
             bumpStepStat(root, undefined, step, 'redChecks');
         }
         process.stderr.write(gate === 2
-            ? 'plumbbob: the check gate itself broke — checkpoint refuses until the harness is fixed.\n'
-            : 'plumbbob: check failed (red) — checkpoint refuses on red. Fix it and re-run.\n');
+            ? notice({
+                fact: 'checkpoint refused',
+                detail: ['the check gate itself broke'],
+                remedy: 'fix the harness, then run it again',
+            })
+            : notice({ fact: 'checkpoint refused', detail: ['the check is red'], remedy: 'fix it, then run it again' }));
         return 1;
     }
     let sha;
+    // The drift advisory is read off the index (staged, before the commit clears
+    // it) but printed inside the ending below, where the fixed order puts it: the
+    // fact, the Verdict it earned a rung on, then what qualifies it.
+    let drift = '';
     if (isDirty(root)) {
         stageAll(root);
-        warnScopeDrift(root, step);
-        const body = withMarker(`plumbbob step ${step}`, bodyResult.body ?? fallbackBody(root, step));
+        drift = scopeDriftNotice(root, step);
+        const lead = bodyResult.body ?? fallbackBody(root, step);
+        const body = withMarker(`plumbbob step ${step}`, foldDetail(lead, readDetail(root)));
         sha = commit(root, messageArg(args) ?? subjectForStep(root, step), body);
+        clearDetail(root); // the detail is folded into the commit now; clear it so no stale detail rides into the next step.
     }
     else {
         sha = headSha(root);
     }
     appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
-    flipIntent(root, step);
+    const flipNotice = flipIntent(root, step);
     stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
     logCheckpoint(root, step, sha);
     // The step landed: the build-log's ☐/☑ mirror flips and its Current-step line
@@ -97,7 +109,17 @@ export async function checkpoint(cwd, args) {
     rmSync(stepPath(root), { force: true });
     clearHandoff(root); // the agent-run handoff ledger is step-scoped; clear it with the markers.
     clearTick(root); // the step's entry stamp is spent; the next `build <n>` re-stamps.
-    process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
+    // The whole ending, one block: the lead line, the Verdict folded over what
+    // just landed, the advisories this checkpoint alone can state, and the
+    // pointer. Read after the flip and the ledger append, so the fold and the
+    // pointer both see the boundary the human is standing at.
+    const landed = boundaryEnding(root, activeBuild(root), step);
+    process.stdout.write(ending({
+        lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: [sha.slice(0, 9)] }),
+        verdict: landed.verdict,
+        advisories: [drift, flipNotice],
+        pointer: landed.pointer,
+    }));
     return 0;
 }
 /**
@@ -137,9 +159,21 @@ function checkpointPlan(root, args) {
     // Landing the plan consumes `start`'s entry stamp: a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
     clearTick(root);
-    process.stdout.write(staged
-        ? `plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`
-        : `plumbbob: plan committed (record-only — sidecar is gitignored; the plan rides the commit message, the files stay untracked) — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
+    // No Verdict: the plan commit measures nothing. The pointer aims at the step
+    // the build starts on, which is what `handoff` renders from a null step.
+    process.stdout.write(ending({
+        lead: transition({ label: 'Plan', fact: 'committed', detail: [sha.slice(0, 9)] }),
+        advisories: staged
+            ? []
+            : [
+                advisory({
+                    fact: 'the plan rides the commit message',
+                    detail: ['record-only', '.plumbbob/ is gitignored, so the files stay untracked'],
+                    remedy: 'unignore .plumbbob/builds/ to keep the record in the tree',
+                }),
+            ],
+        pointer: boundaryEnding(root, activeBuild(root), null).pointer,
+    }));
     return 0;
 }
 /**
@@ -176,23 +210,28 @@ function resolveStep(root, args) {
     }
 }
 /**
- * Warn (never refuse) when the staged tree reaches beyond the step's seam.
+ * The advisory (never a refusal) for a staged tree that reaches beyond the
+ * step's seam, or '' when it held.
  *
- * Guidance, not a gate: the checkpoint captures the drift and says so. The seam
+ * Guidance, not a gate: the checkpoint captures the drift and says so, and the
+ * bumped stat puts a `staged outside the seam` rung under the Verdict. The seam
  * (the step's edit grant: exact paths or `dir/` prefixes) comes from the
  * in-flight SEAM file when a build is live, else the step's declared seam in
  * intent.md. Plumbbob's own artifact plane is whitelisted inside `scopeDrift`,
  * so the `[x]` flip and build-log line this very checkpoint stages never read
  * as drift. No seam means no warning.
  */
-function warnScopeDrift(root, step) {
+function scopeDriftNotice(root, step) {
     const seam = seamTokens(root, step);
     const outside = scopeDrift(stagedPaths(root), seam);
-    if (outside.length > 0) {
-        bumpStepStat(root, undefined, step, 'driftWarnings'); // accrues into the build-log's stats receipt
-        process.stderr.write(`plumbbob: heads-up — staged paths outside step ${step}'s seam: ${outside.join(', ')}. ` +
-            `The checkpoint captures them; if that's real scope drift, the plan may need a \`/plumbbob:step\` revision.\n`);
-    }
+    if (outside.length === 0)
+        return '';
+    bumpStepStat(root, undefined, step, 'driftWarnings'); // accrues into the build-log's stats receipt, and into the Verdict's third rung
+    return advisory({
+        fact: `staged paths reach outside Step ${step}'s seam`,
+        detail: outside,
+        remedy: 'the checkpoint captures them, so revise the plan with /plumbbob:step if that is real scope drift',
+    });
 }
 /**
  * The seam tokens governing the in-flight step.
@@ -222,15 +261,20 @@ function seamTokens(root, step) {
  *
  * Best-effort bookkeeping (the checkpoint SHA is the source of truth) but the
  * dashboard reads intent.md, so a swallowed failure here would make orientation
- * lie; the catch warns and asks for a hand flip instead.
+ * lie; the catch returns the advisory asking for a hand flip, which the caller
+ * folds into the ending. Returns '' on the happy path.
  */
 function flipIntent(root, step) {
     try {
         writeFileSync(intentPath(root), markStepDone(readFileSync(intentPath(root), 'utf8'), step));
+        return '';
     }
     catch {
-        process.stderr.write(`plumbbob: heads-up — could not flip step ${step} to [x] in intent.md; ` +
-            `the checkpoint is recorded, but the dashboard will still show step ${step} as next. Flip it by hand.\n`);
+        return advisory({
+            fact: `could not flip Step ${step} to [x] in intent.md`,
+            detail: ['the checkpoint is recorded', `the dashboard still shows Step ${step} as next`],
+            remedy: 'flip the checkbox by hand',
+        });
     }
 }
 /**
@@ -359,6 +403,35 @@ function fallbackBody(root, step) {
     }
     return parts.length > 0 ? parts.join('\n\n') : undefined;
 }
+/**
+ * The in-flight step's detail from `.plumbbob/detail.md`, or null when the file
+ * is absent or empty.
+ *
+ * The model overwrites it before every pause; checkpoint reads it once here for
+ * the fold, and the caller clears it afterward. A missing or blank file folds
+ * nothing.
+ */
+function readDetail(root) {
+    try {
+        const raw = readFileSync(detailPath(root), 'utf8').trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fold the detail beneath the lead prose for the commit body.
+ *
+ * The lead (an explicit `--body`, else the deterministic fallback) leads and the
+ * detail file's content follows, joined by a blank line so git keeps them as
+ * separate paragraphs. Either part may be absent; an all-empty fold returns
+ * undefined so `withMarker` leaves just the marker line.
+ */
+function foldDetail(lead, detail) {
+    const parts = [lead, detail].filter((part) => part !== undefined && part !== null && part.length > 0);
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
 /**
  * The step's done-when line from intent.md, or null when absent or unreadable.
  */

package/dist/verbs/finish.js

@@ -7,7 +7,9 @@
 // offers the artifact, it does not wall the door. The git footprint stays
 // additive: one forward commit under the Conventional `chore(<scope>): finish`
 // subject, with the `plumbbob finish` identifier riding a marker line at the head
-// of the body so `git log --grep plumbbob` still finds it.
+// of the body so `git log --grep plumbbob` still finds it. The turn's forward
+// pointer is printed here rather than by `handoff`, the one ending handoff
+// cannot render: finish has just cleared the session it would read from.
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
@@ -15,6 +17,11 @@ import { readCommitBody } from "../lib/commitbody.js";
 import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, refreshExcludes, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 import { parseBuildScope } from "../lib/intent.js";
+import { advisory, ending, notice, transition } from "../lib/notice.js";
+// The pointer finish leaves the turn on. Every other one is `handoff`'s, but a
+// finished session has no state left to render from, and past a closed build
+// the only move is framing the next goal.
+const NEXT_UP = '**Next Up**: Nothing planned - /plumbbob:plan';
 /**
  * Close out the active build: report tail, final commit, control-state cleanup.
  *
@@ -26,7 +33,7 @@ import { parseBuildScope } from "../lib/intent.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
-        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        process.stderr.write(notice({ fact: 'no active session', remedy: 'plumbbob start "<title>"' }));
         return 1;
     }
     // Checked before any of finish's writes: appendCheckpointShas/appendStats
@@ -39,14 +46,11 @@ export function finish(cwd, args = []) {
         return 1;
     }
     const { build: slug } = resolveBuild(root, args);
-    if (existsSync(reportPath(root, slug))) {
+    const reported = existsSync(reportPath(root, slug));
+    if (reported) {
         appendCheckpointShas(root, slug);
         appendStats(root, slug);
     }
-    else {
-        process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
-            '(/plumbbob:finish normally writes the report first). No gate — D9 (finish-no-gate).\n');
-    }
     // The final commit: stage the report just written plus the build folder's tail
     // (a step's commit sweeps its own bookkeeping along with the work, so the last
     // step's `checkpoints` line lands one commit late and finish absorbs it) and
@@ -74,9 +78,29 @@ export function finish(cwd, args = []) {
     clearTick(root, slug);
     setGrant(root, null);
     rmSync(join(sidecarDir(root), 'STATE'), { force: true });
+    // The whole ending in the fixed order: the lead line, the advisory that
+    // qualifies it (finishing without a report is guidance, never a gate; the
+    // session is already closed by the time it prints), and the pointer, which is
+    // the turn's last text. finish renders that pointer itself: it just cleared
+    // the session `handoff` would read one from.
     const where = slug === null ? '.plumbbob/' : `.plumbbob/builds/${slug}/`;
-    process.stdout.write(`plumbbob: finished — ${sha.slice(0, 9)}. ${where} rides your branch into the PR. ` +
-        'Run `/plumbbob:plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
+    process.stdout.write(ending({
+        lead: transition({
+            label: 'Session',
+            fact: 'finished',
+            detail: [sha.slice(0, 9), `${where} rides your branch into the PR`],
+        }),
+        advisories: reported
+            ? []
+            : [
+                advisory({
+                    fact: 'no report.md found',
+                    detail: ['finished without one', 'no gate here by design'],
+                    remedy: '/plumbbob:finish normally writes the report first',
+                }),
+            ],
+        pointer: NEXT_UP,
+    }));
     return 0;
 }
 /**