plumbbob 0.10.3 → 0.11.0

package/dist/verbs/revert.js

@@ -23,6 +23,8 @@ import { findRepoRoot, resetHard, untrackedPaths } from "../lib/git.js";
 import { bumpStepStat, checkpointsPath, hasSession, resolveBuild, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
 import { isArtifactPath, matchesSeam } from "../lib/intent.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
+import { ending, notice, transition } from "../lib/notice.js";
+import { driverPointer } from "./handoff.js";
 /**
  * Rewind to a recorded checkpoint and return the build to the boundary.
  *
@@ -35,13 +37,13 @@ import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 export function revert(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);
     const to = parseTo(rest);
     if (to === 'invalid') {
-        process.stderr.write('plumbbob: revert --to needs a step number. Try: plumbbob revert --to 2.\n');
+        process.stderr.write(notice({ fact: 'revert --to needs a step number', remedy: 'plumbbob revert --to 2' }));
         return 1;
     }
     const checkpoints = readCheckpoints(root, slug);
@@ -52,13 +54,13 @@ export function revert(cwd, args) {
     else {
         const entry = checkpoints.steps.find((e) => e.n === to);
         if (entry === undefined) {
-            process.stderr.write(`plumbbob: no checkpoint recorded for step ${to}.\n`);
+            process.stderr.write(notice({ fact: `no checkpoint recorded for step ${to}` }));
             return 1;
         }
         sha = entry.sha;
     }
     if (sha === undefined) {
-        process.stderr.write('plumbbob: no baseline recorded in checkpoints — cannot revert.\n');
+        process.stderr.write(notice({ fact: 'no baseline recorded in checkpoints', detail: ['nothing to revert to'] }));
         return 1;
     }
     // Compute untracked-in-seam BEFORE the reset (reset --hard leaves untracked and
@@ -83,7 +85,16 @@ export function revert(cwd, args) {
     // revert keeps intent edits, so intent's checkboxes stay the truth to reflect.
     // Best-effort, like every build-log write.
     syncBuildLogState(root, slug, AT_BOUNDARY);
-    process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — back at the boundary. Park lines and intent edits were preserved.\n`);
+    // A step exit: nothing landed, so no Verdict rides above the pointer, and with
+    // the markers cleared it aims forward from the boundary.
+    process.stdout.write(ending({
+        lead: transition({
+            label: 'Reverted',
+            fact: `to ${sha.slice(0, 9)}`,
+            detail: ['park lines and intent edits preserved'],
+        }),
+        pointer: driverPointer(root, slug),
+    }));
     return 0;
 }
 /**

package/dist/verbs/spike.js

@@ -21,6 +21,8 @@ import { basename, dirname, join, relative } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
 import { buildFolder, clearSpike, hasSession, inSpike, listSpikeReports, markSpike, nextSpikeReportPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { readTemplate, stampTemplate } from "../lib/templates.js";
+import { advisory, blocks, ending, notice, transition } from "../lib/notice.js";
+import { driverPointer } from "./handoff.js";
 // Worktree/branch names when the caller lists none: a fork defaults to two arms.
 const DEFAULT_OPTIONS = ['a', 'b'];
 /**
@@ -37,7 +39,7 @@ const VERDICT_PLACEHOLDER = '*(viable | not viable | partial';
 export function spike(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: buildSlug, rest } = resolveBuild(root, args);
@@ -61,14 +63,21 @@ export function spike(cwd, args) {
 function spikeReport(root, buildSlug, positionals) {
     const slug = sanitize(positionals[0] ?? '');
     if (slug.length === 0) {
-        process.stderr.write('plumbbob: spike report needs a slug. Try: plumbbob spike report "auth-store".\n');
+        process.stderr.write(notice({ fact: 'spike report needs a slug', remedy: 'plumbbob spike report "auth-store"' }));
         return 1;
     }
     const inFlight = readInFlightStep(root, buildSlug);
     const via = inFlight !== null ? `step ${inFlight}` : '/plumbbob:spike';
     const path = scaffoldSpikeReport(root, buildSlug, slug, via);
-    process.stdout.write(`plumbbob: spike report scaffolded — ${relative(root, path)}. Fill Findings and the Verdict as you go; ` +
-        `a recorded Verdict is what closes a spike step.\n`);
+    process.stdout.write(ending({
+        lead: transition({
+            label: 'Spike report',
+            fact: 'scaffolded',
+            detail: [relative(root, path)],
+            remedy: 'record Findings and the Verdict there, which is what closes a spike step',
+        }),
+        pointer: driverPointer(root, buildSlug),
+    }));
     return 0;
 }
 /**
@@ -110,17 +119,20 @@ function readInFlightStep(root, buildSlug) {
  */
 function spikeStart(root, buildSlug, positionals) {
     if (inSpike(root, buildSlug)) {
-        process.stderr.write('plumbbob: already in a spike. Run `plumbbob spike done` to close it first.\n');
+        process.stderr.write(notice({ fact: 'already in a spike', remedy: 'plumbbob spike done to close it first' }));
         return 1;
     }
     if (existsSync(stepPath(root, buildSlug))) {
-        process.stderr.write('plumbbob: spike starts from a settled boundary, but a step is in flight. ' +
-            'A spike is a deliberate fork — checkpoint, abandon, or revert the current step first.\n');
+        process.stderr.write(notice({
+            fact: 'a step is in flight',
+            detail: ['a spike is a deliberate fork from a settled boundary'],
+            remedy: 'checkpoint, abandon, or revert the current step first',
+        }));
         return 1;
     }
     const slug = sanitize(positionals[0] ?? '');
     if (slug.length === 0) {
-        process.stderr.write('plumbbob: spike needs a slug. Try: plumbbob spike "auth-store" a b.\n');
+        process.stderr.write(notice({ fact: 'spike needs a slug', remedy: 'plumbbob spike "auth-store" a b' }));
         return 1;
     }
     const explicit = positionals.slice(1).map(sanitize).filter((o) => o.length > 0);
@@ -129,7 +141,11 @@ function spikeStart(root, buildSlug, positionals) {
     for (const opt of options) {
         const path = join(dirname(root), `${basename(root)}-spike-${slug}-${opt}`);
         if (existsSync(path)) {
-            process.stderr.write(`plumbbob: ${path} already exists — remove it or run \`plumbbob spike done\` first.\n`);
+            process.stderr.write(notice({
+                fact: 'the spike worktree path already exists',
+                detail: [path],
+                remedy: 'remove it, or run plumbbob spike done first',
+            }));
             return 1;
         }
         git(root, ['worktree', 'add', '-b', `spike/${slug}-${opt}`, path, 'HEAD']);
@@ -139,9 +155,25 @@ function spikeStart(root, buildSlug, positionals) {
     // Scaffold the report NOW, while the worktrees live: findings accrue during the
     // experiment, not from memory after the teardown. Provenance names the worktrees.
     const report = scaffoldSpikeReport(root, buildSlug, slug, `/plumbbob:spike — worktrees (${options.join(', ')})`);
-    process.stdout.write(`plumbbob: spiking — the main tree stays put. Experiment in the throwaway worktrees:\n${created
-        .map((p) => `  ${p}`)
-        .join('\n')}\nRecord findings and the Verdict in ${relative(root, report)} as you go, then run \`plumbbob spike done\`.\n`);
+    // The lead states the fact; the throwaway worktrees are a list, so they ride
+    // as a readout beneath it rather than crowding the line, and the report the
+    // spike scaffolded is a second landing under the same lead.
+    process.stdout.write(ending({
+        lead: blocks([
+            transition({
+                label: 'Spike',
+                fact: 'opened',
+                detail: ['the main tree stays put', `${created.length} throwaway worktree${created.length === 1 ? '' : 's'}`],
+            }) + created.map((path) => `  ${path}`).join('\n'),
+            transition({
+                label: 'Spike report',
+                fact: 'scaffolded',
+                detail: [relative(root, report)],
+                remedy: 'record findings and the Verdict there, then run plumbbob spike done',
+            }),
+        ]),
+        pointer: driverPointer(root, buildSlug),
+    }));
     return 0;
 }
 /**
@@ -152,7 +184,7 @@ function spikeStart(root, buildSlug, positionals) {
  */
 function spikeDone(root, buildSlug) {
     if (!inSpike(root, buildSlug)) {
-        process.stderr.write('plumbbob: no active spike to close.\n');
+        process.stderr.write(notice({ fact: 'no active spike to close' }));
         return 1;
     }
     // Check for an unrecorded verdict BEFORE teardown. The reports live in the
@@ -168,15 +200,22 @@ function spikeDone(root, buildSlug) {
     }
     clearSpike(root, buildSlug);
     // Guidance, not a gate: a missing verdict is a nudge, and the spike still
-    // closes. Name the reports so the human knows where to write it.
-    if (unfilled.length > 0) {
-        process.stderr.write(`plumbbob: heads-up — no verdict recorded in ${unfilled.join(', ')}. ` +
-            `The worktrees are gone; capture the call there before it fades.\n`);
-    }
-    const reports = listSpikeReports(root, buildSlug);
-    const where = reports.length > 0 ? `the spike report${reports.length === 1 ? '' : 's'} (${reports.join(', ')})` : 'intent.md';
-    process.stdout.write(`plumbbob: spike closed — worktrees and branches removed, back at the boundary. ` +
-        `Record the verdict (which option won, and why) in ${where} before you \`build\`.\n`);
+    // closes. It follows the line it qualifies, and names the reports so the
+    // human knows where to write the call. The pointer, read once the marker is
+    // cleared, aims back at the step the spike interrupted, or forward.
+    process.stdout.write(ending({
+        lead: transition({ label: 'Spike', fact: 'closed', detail: ['worktrees and branches removed'] }),
+        advisories: unfilled.length === 0
+            ? []
+            : [
+                advisory({
+                    fact: 'no verdict recorded',
+                    detail: unfilled,
+                    remedy: 'record which option won, and why, now the worktrees are gone',
+                }),
+            ],
+        pointer: driverPointer(root, buildSlug),
+    }));
     return 0;
 }
 /**

package/dist/verbs/start.js

@@ -10,6 +10,7 @@ import { readTemplate, stampTemplate } from "../lib/templates.js";
 import { findRepoRoot, hasCommit, headSha, isDirty, isIgnored } from "../lib/git.js";
 import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, setGrant, stampTick, } from "../lib/sidecar.js";
 import { settingsPath } from "../lib/settings.js";
+import { advisory, ending, notice, transition } from "../lib/notice.js";
 /**
  * Human-readable echo of the default check gate, stamped into the templates'
  * {{CHECK}} line.
@@ -37,36 +38,59 @@ export async function start(cwd, args) {
     const local = args.includes('--local');
     const title = (positionals[0] ?? '').trim();
     const slug = (flagValue(args, '--slug') ?? datedSlug(title)).trim();
+    // Every advisory the session accrues on its way open, collected rather than
+    // printed: they belong inside the one ending below, in the order found.
+    const advisories = [];
     if (title.length === 0) {
-        process.stderr.write('plumbbob: start needs a title. Try: plumbbob start "what you are building".\n');
+        process.stderr.write(notice({ fact: 'start needs a title', remedy: 'plumbbob start "what you are building"' }));
         return 1;
     }
     const root = findRepoRoot(cwd);
     if (root === null) {
-        process.stderr.write('plumbbob: not a git repository. PlumbBob records a baseline commit — run `git init` and make an initial commit first.\n');
+        process.stderr.write(notice({
+            fact: 'not a git repository',
+            detail: ['plumbbob records a baseline commit'],
+            remedy: 'git init, then make an initial commit',
+        }));
         return 1;
     }
     if (!hasCommit(root)) {
-        process.stderr.write('plumbbob: this repository has no commits yet. Make an initial commit so `start` can record a baseline.\n');
+        process.stderr.write(notice({
+            fact: 'this repository has no commits yet',
+            remedy: 'make an initial commit, so start can record a baseline',
+        }));
         return 1;
     }
     if (hasSession(root)) {
-        process.stderr.write('plumbbob: a session is already active here. Run `plumbbob finish` to close it before starting another.\n');
+        process.stderr.write(notice({ fact: 'a session is already active here', remedy: 'plumbbob finish to close it before starting another' }));
         return 1;
     }
     if (isDirty(root)) {
         if (!allowDirty) {
-            process.stderr.write('plumbbob: the working tree is dirty. Commit or stash first, or `plumbbob start --allow-dirty "<title>"` to record the current HEAD as the baseline.\n');
+            process.stderr.write(notice({
+                fact: 'the working tree is dirty',
+                remedy: 'commit or stash first, or plumbbob start --allow-dirty "<title>" to record HEAD as the baseline',
+            }));
             return 1;
         }
-        process.stderr.write('plumbbob: WARNING --allow-dirty: recording HEAD as baseline with a dirty tree. A later revert-to-baseline will DISCARD the uncommitted work.\n');
+        advisories.push(advisory({
+            fact: 'recording HEAD as the baseline with a dirty tree',
+            detail: ['--allow-dirty'],
+            remedy: 'a later revert to baseline will DISCARD the uncommitted work',
+        }));
     }
     if (!local && slug.length === 0) {
-        process.stderr.write(`plumbbob: could not derive a build slug from "${title}". Pass --slug <name>, or retitle with letters or digits.\n`);
+        process.stderr.write(notice({
+            fact: `could not derive a build slug from "${title}"`,
+            remedy: 'pass --slug <name>, or retitle with letters or digits',
+        }));
         return 1;
     }
     if (!local && listBuilds(root).includes(slug)) {
-        process.stderr.write(`plumbbob: a build named "${slug}" already exists in .plumbbob/builds/. Retitle, or pass --slug <name> to choose another.\n`);
+        process.stderr.write(notice({
+            fact: `a build named "${slug}" already exists in .plumbbob/builds/`,
+            remedy: 'retitle, or pass --slug <name> to choose another',
+        }));
         return 1;
     }
     const sha = headSha(root);
@@ -121,7 +145,6 @@ export async function start(cwd, args) {
     // grant's lifetime is one turn.
     setGrant(root, null);
     stampTick(root, local ? null : slug);
-    process.stdout.write(`plumbbob: started "${title}" — baseline ${sha.slice(0, 9)}. Frame and decide in ${intentLocation}; \`build\` a step once the decisions are made.\n`);
     // The tracked layout plants `builds/<slug>/` to ride the branch into the PR,
     // but a repo whose own `.gitignore` excludes `.plumbbob/` overrides that, and
     // an explicit `git add` of an ignored folder is a hard error. Detect it here,
@@ -132,9 +155,11 @@ export async function start(cwd, args) {
     // Guidance only, and the session is already open: a probe hiccup stays silent
     // rather than half-crashing a scaffolded session.
     if (!local && sidecarIsIgnored(root, slug)) {
-        process.stderr.write('plumbbob: heads-up — this repo gitignores .plumbbob/, so the tracked build folder cannot ride the branch.\n' +
-            '  Plan and finish commits will be record-only (empty commits; the plan and report ride the commit message).\n' +
-            '  To keep the record in-tree, unignore .plumbbob/builds/ (or the whole sidecar) before the first checkpoint.\n');
+        advisories.push(advisory({
+            fact: 'this repo gitignores .plumbbob/',
+            detail: ['the build folder cannot ride the branch', 'plan and finish commits will be record-only'],
+            remedy: 'unignore .plumbbob/builds/ before the first checkpoint to keep the record in the tree',
+        }));
     }
     // The plan-time gate probe: if checkride sees no code checks here, say so
     // NOW (while the human is still deciding) instead of at the first
@@ -143,10 +168,24 @@ export async function start(cwd, args) {
     // exit code, and a configured `check` or a probe hiccup stays silent.
     const gate = await detectGate(root);
     if (gate.configured === null && !gate.detected) {
-        process.stderr.write('plumbbob: heads-up — the check gate sees no code checks in this repo (checkride detected no tools).\n' +
-            '  Set one while you are still planning: add {"check": "npm test"} to .plumbbob/settings.json.\n' +
-            '  Checkpoints gate on it — with nothing to run, the gate refuses or greens vacuously.\n');
+        advisories.push(advisory({
+            fact: 'the check gate sees no code checks in this repo',
+            detail: ['checkride detected no tools', 'checkpoints gate on it and would green vacuously'],
+            remedy: 'add {"check": "npm test"} to .plumbbob/settings.json while you are still planning',
+        }));
     }
+    // No pointer: the plan skill owns the turn that follows, and there is no step
+    // yet to aim at, so the ending closes on the remedy line that says where to
+    // frame the build.
+    process.stdout.write(ending({
+        lead: transition({
+            label: 'Session',
+            fact: `started "${title}"`,
+            detail: [`baseline ${sha.slice(0, 9)}`],
+            remedy: `frame and decide in ${intentLocation}, then build a step`,
+        }),
+        advisories,
+    }));
     return 0;
 }
 /**
@@ -167,11 +206,11 @@ function datedSlug(title) {
     return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${base}`;
 }
 /**
- * Whether the tracked build folder is gitignored: the record-only heads-up's
+ * Whether the tracked build folder is gitignored: the record-only advisory's
  * predicate, probing exactly the path `checkpoint --plan` will try to stage.
  *
  * Best-effort: a probe that throws (a fatal `git check-ignore`) reads as
- * not-ignored so the heads-up stays silent rather than crashing a session that
+ * not-ignored so the advisory stays silent rather than crashing a session that
  * is already open.
  */
 function sidecarIsIgnored(root, slug) {

package/dist/verbs/use.js

@@ -11,6 +11,8 @@
 import { existsSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { activeBuild, hasSession, intentPath, listBuilds, setActiveBuild, stepPath } from "../lib/sidecar.js";
+import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { driverPointer } from "./handoff.js";
 /**
  * Switch the active-build cursor to the named build.
  *
@@ -20,35 +22,43 @@ import { activeBuild, hasSession, intentPath, listBuilds, setActiveBuild, stepPa
 export function use(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 builds = listBuilds(root);
     const target = args.find((a) => !a.startsWith('--'));
     if (target === undefined || target.length === 0) {
-        process.stderr.write(`plumbbob: use needs a build slug.${buildsHint(builds)}\n`);
+        process.stderr.write(notice({ fact: 'use needs a build slug', detail: builds, remedy: 'plumbbob use <slug>' }));
         return 1;
     }
     // Validate by the folder's intent.md, not the dir alone: an empty `builds/<slug>/`
     // is not a resumable build, and the flat `--local` layout has no builds/ at all.
     if (!existsSync(intentPath(root, target))) {
-        process.stderr.write(`plumbbob: no build named "${target}" in .plumbbob/builds/.${buildsHint(builds)}\n`);
+        process.stderr.write(notice({ fact: `no build named "${target}" in .plumbbob/builds/`, detail: builds }));
         return 1;
     }
     const leaving = activeBuild(root);
-    if (leaving !== null && leaving !== target && existsSync(stepPath(root, leaving))) {
-        process.stderr.write(`plumbbob: note — build "${leaving}" has a step in flight; its in-flight state is preserved ` +
-            `and resumes when you \`use ${leaving}\` again.\n`);
-    }
+    const left = leaving !== null && leaving !== target && existsSync(stepPath(root, leaving)) ? leaving : null;
     setActiveBuild(root, target);
-    const resuming = existsSync(stepPath(root, target)) ? ' (a step is in flight — `status` shows where)' : '';
-    process.stdout.write(`plumbbob: now on build "${target}"${resuming}. \`status\` to orient.\n`);
+    // The lead line, then the advisory it qualifies, then the pointer into the
+    // build just switched to: one fixed order for every ending, so the relay never
+    // has to guess which line leads.
+    process.stdout.write(ending({
+        lead: transition({
+            label: 'Active build',
+            fact: target,
+            detail: existsSync(stepPath(root, target)) ? ['a step is in flight'] : [],
+        }),
+        advisories: left === null
+            ? []
+            : [
+                advisory({
+                    fact: `build "${left}" has a step in flight`,
+                    detail: ['its in-flight state is preserved'],
+                    remedy: `plumbbob use ${left} to pick it back up`,
+                }),
+            ],
+        pointer: driverPointer(root, target),
+    }));
     return 0;
 }
-/**
- * A trailing " Builds: a, b." hint when any exist, so a bad or missing slug
- * points the user straight at the valid choices.
- */
-function buildsHint(builds) {
-    return builds.length > 0 ? ` Builds: ${builds.join(', ')}.` : '';
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Attention-first build process: 14 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",

package/skills/abandon/SKILL.md

@@ -10,7 +10,7 @@ allowed-tools: Bash(plumbbob status:*), Bash(plumbbob abandon:*)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."`
 
-This is a **driver skill**: a chat-side trigger for the mechanical `plumbbob abandon` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool**; its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+This is a **driver skill**: a chat-side trigger for the mechanical `plumbbob abandon` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool**; it shells the verb and relays its output verbatim, refusal included. A successful transition prints its whole ending, pointer and all, so one command is the whole turn. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
 
 Abandon is the third exit from an in-flight step. `/plumbbob:verify` lands the step and `/plumbbob:revert` destroys its work; abandon drops the attempt and keeps the working-tree diff exactly where it is. The step keeps its `[ ]` in the plan, re-buildable later, and the diff stays yours to keep, rework, or commit by hand.
 
@@ -18,3 +18,4 @@ Abandon is the third exit from an in-flight step. `/plumbbob:verify` lands the s
 
 1. Run `plumbbob abandon` via Bash. It clears the in-flight markers (`STEP`, `SEAM`, `TICK`, and the step's agent handoff ledger), appends an abandon line to the build log, and touches neither the working tree nor git.
 2. Report the verb's output verbatim: the step it dropped, or any refusal. A step exit crosses the same boundary as a checkpoint, so abandon honors the same approval latch; a "no human turn since this step began" refusal is the pause working, not an error. End the turn, and the human's next turn is what lets a re-fired abandon land.
+3. A successful abandon prints its own ending (the driver tier of the [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)): the lead line, a blank line, and the pointer, which aims at the step just dropped, since it kept its `[ ]` in the plan. Relay that block whole and run no second command. The latch refusal above is not a transition; it carries no pointer, so relay it and end the turn.

package/skills/build/SKILL.md

@@ -104,31 +104,110 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    build the step and reach the pause *in one turn*, so under plumbbob's turn hook the
    checkpoint at the end of that turn is **refused** ("no human turn since this step
    began"), and that refusal **is** the pause working as designed. Do exactly what the
-   pause asks: present the diff and the self-review, emit the closing block below, and
-   **end the turn**. The human's next message (their approval) is the human turn that
-   lets the checkpoint land: on that turn you run `plumbbob checkpoint <n>` (now allowed)
-   and **stop at the boundary**. Landing the checkpoint is its own deliberate beat (the
-   thing approval triggers), never a side effect of starting the next step, and
-   `/plumbbob:build` only ever starts the *next* step. **Never route around a refusal with a
-   raw `git commit`**; the work plane stays free, but the *record* is latched on purpose.
-
-   **End every default build turn with the standardized hand-off block.** Run `plumbbob
-   handoff` and present its output; it renders the same three-part shape (the state, the
-   choice, what's next) straight from the session: step N built, the looks-good /
-   needs-work choice, and the next undone step with its `- model:` recommendation. Show
-   your diff and self-review above it. The CLI owns the block so it can't drift from what
-   `/plumbbob:status` reports; you supply only the judgment above it. It already drops the model
-   clause when the next step has none, and says so when no planned step remains; you
-   don't reproduce the template by hand.
-
-   **Then hand off with the next model.** Once the checkpoint lands in the approval turn,
-   run `plumbbob handoff` again and relay its boundary block; with the step gone from
-   in-flight it renders "step N checkpointed" and points at the next undone step, carrying
-   that step's `- model:` recommendation (the plan's smallest-model-that-fits call) so the
-   human knows which `/model` to select before running `/plumbbob:build` again. It is what
-   carries the plan's suggestion across a fresh context window, which inherits the session
-   model, not the plan's. No `- model:` line means any model will do. Guidance, never a
-   gate.
+   pause asks: write the detail file, run `plumbbob handoff`, paste its block, and **end
+   the turn there**. The human's next
+   message (their approval) is the human turn that lets the checkpoint land: on that turn
+   you run `plumbbob checkpoint <n>` (now allowed) and **stop at the boundary**. Landing
+   the checkpoint is its own deliberate beat (the thing approval triggers), never a side
+   effect of starting the next step, and `/plumbbob:build` only ever starts the *next*
+   step. **Never route around a refusal with a raw `git commit`**; the work plane stays
+   free, but the *record* is latched on purpose.
+
+   **Render the pause: write the file, run handoff, paste.** A build pause is a decision
+   turn, and the
+   [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)
+   fixes it as one block. You author none of it in the chat. Your judgment goes into
+   `.plumbbob/detail.md`; `plumbbob handoff` renders the whole turn from that file and its
+   own measurements; you paste its output and write nothing before or after it. The rule is
+   positional on purpose: with the relay as the turn's whole text, no line is left for
+   "here is the pause", for reading the check verdict back in prose, or for a closing
+   courtesy. Each fact appears once, in its part.
+
+   *Write the detail file.* Before you call `plumbbob handoff`, overwrite
+   `.plumbbob/detail.md` for this step; never let a past step's detail linger. It is the
+   wire handoff parses, and it is the only path by which your judgment reaches the turn:
+
+   ```markdown
+   # Detail · Step <N> · <the step title>
+
+   ── recap · step <N> of <M> ──
+   done-when    met
+   decisions    honored: D1 (some-slug), D2 (another-slug)
+   constraints  all honored
+
+   ## Summary
+
+   <the outcome, not the activity: one sentence when one will do, a short
+   paragraph when the step needs explaining>
+
+   ## 1 <the first highlight: one sentence, one move>
+   <the full story: what moved, why, what was tried and dropped>
+
+   ## 2 ...
+
+   ## Recommendation
+
+   <The move.> <The reason, one or two sentences.>
+   ```
+
+   The three rows under the header rule are yours, and only those three; `check`, `seam`,
+   `diff`, and `spent` are measured by the CLI, and a row you wrote for them would be
+   overwritten. Keep the rows contiguous (the first blank line ends them). Each opens with a
+   verdict word from the closed set in the turn anatomy (`met`, `not met`, `drift`;
+   `honored`, `none exercised`, `bent`, `drift`; `all honored`, `bent`, `drift`); a cited
+   decision or constraint carries its slug (`C1 (no-new-deps)`, never a bare `C1`); a row
+   that cannot apply vanishes. A green row collapses to its word or its count and a red one
+   names the one offender in a short clause, which is what keeps the whole row inside the
+   fence's 80 columns (13 of label, 67 of value); two or more items break onto indented
+   continuation lines opening with `-`, and a red row's evidence onto an indented `→` line.
+
+   The `## Summary` lead and the `## <n>` section titles are the turn's opening block:
+   handoff prints the lead behind the `**Summary**:` label, appends the `(details: …)`
+   bracket, and renders the titles as the numbered highlights, so you type neither the path
+   nor the list. Five highlights at most, each one sentence and one move, plain English
+   first, a path in backticks only when the name itself is the news. The numbers are
+   handles: "expand 2" opens `## 2`, so every highlight has a section behind it with the
+   full story. A judgment or a flag (a stray the seam row will name, a decision you had to
+   bend, a doubt about the done-when) is one of those highlights, never a paragraph of its
+   own. The recommendation is the last section: the move you would take as its own
+   sentence, closed by a period, then the reason as a capitalized sentence or two. The lead
+   and the recommendation are flowing prose and handoff unwraps both to the renderer's
+   width, so never hard-wrap them; handoff also prepends the bold `**Recommendation**:`
+   label, which you never type. `checkpoint` folds this file into the commit body and then
+   truncates it, so the detail lands in the durable commit rather than piling up on disk.
+
+   *Paste the turn.* Run `plumbbob handoff` and paste its output whole, verbatim, at top
+   level, trailing blank line included, then end the turn. Never nest it inside a fence of
+   your own; it carries fences of its own and they cannot nest. It prints the Summary and
+   its highlights, the Readout fence (its measured `check`, `seam`, `diff`, and `spent`
+   rows folded with your three), a `diff` fence when the change is 20 lines or fewer, the
+   Verdict folded worst-of from the same rows, Next Up, Your Call, and your recommendation
+   last. The gate verdict's one home is that `check` row: no standalone verdict line
+   exists, and you never restate the verdict in prose. A narrowed run names the slots it
+   skipped there (`· without test`), and that named narrowing is the whole disclosure. The
+   notice checkride's Stop hook appends after your turn is not yours to relay or repeat;
+   the trailing blank line you kept is what lands it on its own line. Relayed CLI strings
+   keep their em-dashes; your own lines never use one, the write-versus-relay line of
+   [D78 (em-dash-ban)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d78).
+
+   *Then read the reply as an ask or a direction.* A message that **asks** ("expand 2",
+   "what does that mean?", "why did the seam row flag that?") is an expand: answer it from the detail file, from
+   `git diff`, or from `git show`, never from recall, then run `plumbbob handoff` again and
+   paste it. The step is still in flight, so it renders the same pause, and the Your Call
+   block stays the CLI's to render rather than yours to retype. A message that **directs**
+   is needs-work: take it as what to change, and nothing lands until the human says
+   `looks good`.
+
+   **Then hand off with the next model.** `plumbbob checkpoint` prints the whole boundary
+   ending itself: `**Checkpoint**: Step N complete (<sha>)`, the Verdict the step earned,
+   any advisory (a staged path outside the seam is the common one), and Next Up. Relay
+   that block whole, run no second command, and write nothing around it. It is the
+   orientation tier (no Your Call block, no recommendation), and it points at the next
+   undone step carrying that step's `- model:` recommendation (the plan's
+   smallest-model-that-fits call) so the human knows which `/model` to select before
+   running `/plumbbob:build` again. It is what carries the plan's suggestion across a fresh
+   context window, which inherits the session model, not the plan's. No `- model:` line
+   means any model will do. Guidance, never a gate.
 
 ## Running bound agents
 
@@ -181,10 +260,10 @@ and approves in the human's place**, and it **chains**:
   bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine`; an
   agent cannot advance the loop), a new decision is needed, no planned steps
   remain, or the top of a requested range is reached. **When `--auto` halts back to the
-  human, give the same hand-off the default pause does**; run `plumbbob handoff` and
-  relay its block: the step just completed, the next undone step, and that next step's
-  `- model:` recommendation if it has one, so a fresh context window knows which `/model`
-  to select.
+  human, end on the same turn the default pause does**: write the detail file, run
+  `plumbbob handoff`, and paste its block: the step just completed, the next undone step,
+  and that next step's `- model:` recommendation if it has one, so a fresh context window
+  knows which `/model` to select.
 
 `--auto` and a step range are the only paths that checkpoint without a human pause, and
 only because the human asked for it by name; a range re-imposes the pause at its top.
@@ -229,15 +308,17 @@ just the one more entry already in the halt list above.
   who verifies and (bar `--auto`) the human is still the clock. See **§ Running bound
   agents** for the mechanics.
 - **A refused checkpoint is the pause, not an error.** Under plumbbob's turn
-  hook a same-turn `checkpoint` is refused by design: present the diff and the closing
-  block, **end the turn**; the human's approval on their next turn is what lets you land
+  hook a same-turn `checkpoint` is refused by design: write the file, run `plumbbob
+  handoff`, paste its block, **end the turn there**; the human's approval on their next
+  turn is what lets you land
   it, and landing it is a deliberate beat, not a side effect of the next `/plumbbob:build`.
   Never route around it with a raw `git commit`. An explicit `/plumbbob:build --auto` or a typed
   step range in the human's own prompt are the only self-approvals; **never write `auto`
   into a settings file yourself to unlock a checkpoint. A grant you mint is no grant (the
   latch ignores it; [D67 (auto-not-a-grant)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d67)); ask the human to type
   `/plumbbob:build --auto` again instead.**
-- **Close with the next model.** When a step lands, run `plumbbob handoff` and relay its
-  block; it cites the completed step and the next undone step, and names that next step's
-  `- model:` recommendation if it has one, which is what a fresh context window needs to
-  pick the right `/model` before the next run. Guidance, never a gate.
+- **Close with the next model.** When a step lands, `plumbbob checkpoint` prints the whole
+  boundary ending; relay it with nothing written around it and no second command. It cites
+  the completed step and the next undone step, and names that next step's `- model:`
+  recommendation if it has one, which is what a fresh context window needs to pick the
+  right `/model` before the next run. Guidance, never a gate.