plumbbob 0.10.3 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/dist/cli-core.js

@@ -79,11 +79,15 @@ const VERBS = [
     },
     {
         name: 'handoff',
-        description: 'print the standardized build hand-off block (pause or post-checkpoint); read-only',
-        synopsis: ['handoff [<n>] [--build <slug>]'],
+        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver); read-only',
+        synopsis: ['handoff [<n>] [--plan] [--driver] [--build <slug>]'],
         args: [{ name: '<n>', gloss: 'step to report on (default: the in-flight step, else the last checkpointed one)' }],
-        flags: [BUILD_FLAG],
-        notes: 'Read-only; refuses (exit 1) only with no session.',
+        flags: [
+            { name: '--plan', gloss: 'render the plan-pause card instead of a step tier' },
+            { name: '--driver', gloss: "render a driver turn's pointer back at the open step" },
+            BUILD_FLAG,
+        ],
+        notes: 'Read-only; refuses (exit 1) with no session, or with --plan and --driver together.',
     },
     {
         name: 'check',

package/dist/lib/agents.js

@@ -267,7 +267,7 @@ export function resolveAgent(root, name, opts = {}) {
     }
     return {
         ok: false,
-        error: `no agent named "${name}" — looked in ${projectAgentsDir(root)} and ${personalAgentsDir(home)}.`,
+        error: `no agent named "${name}", looked in ${projectAgentsDir(root)} and ${personalAgentsDir(home)}`,
     };
 }
 /**
@@ -610,7 +610,7 @@ function parseChildEnvelope(stdout) {
         raw = JSON.parse(stdout);
     }
     catch {
-        return { ok: false, error: 'the agent wrote non-JSON to stdout — the envelope must be a single JSON object.' };
+        return { ok: false, error: 'the agent wrote non-JSON to stdout, so the envelope is not a single JSON object' };
     }
     return parseEnvelope(raw);
 }

package/dist/lib/git.js

@@ -76,19 +76,74 @@ export function isDirty(root) {
  * commits are surfaced, never blocked). `--first-parent` keeps the count on
  * the branch's own line: merging upstream reads as the one merge commit, not
  * the dozens it carried; those didn't land "outside the ledger" in any sense
- * the receipt should nag about. Best-effort and never throws: 0 when the range
- * is empty, `sha` is unknown to the repo, or HEAD is unborn: the count is
- * informational (the human commits freely), never a gate.
+ * the receipt should nag about. `excluding` is a commit-message pattern whose
+ * matches are left out of the count, which is how a caller drops plumbbob's own
+ * commits from a tally of what landed around them.
+ *
+ * Best-effort and never throws: 0 when the range is empty, `sha` is unknown to
+ * the repo, or HEAD is unborn: the count is informational (the human commits
+ * freely), never a gate.
  */
-export function commitsSince(root, sha) {
+export function commitsSince(root, sha, excluding) {
     try {
-        const n = Number.parseInt(runGit(root, ['rev-list', '--count', '--first-parent', `${sha}..HEAD`]), 10);
+        const skip = excluding === undefined ? [] : ['--grep', excluding, '--invert-grep'];
+        const n = Number.parseInt(runGit(root, ['rev-list', '--count', '--first-parent', ...skip, `${sha}..HEAD`]), 10);
         return Number.isFinite(n) && n > 0 ? n : 0;
     }
     catch {
         return 0;
     }
 }
+/**
+ * The working tree's changes against the index, one entry per file, as
+ * `git diff --numstat` reports them; a binary file counts 0/0.
+ *
+ * This feeds the recap's `diff` and `seam` rows at the pause: information,
+ * never a gate, so it is best-effort and never throws ([] on any failure).
+ */
+export function diffNumstat(root) {
+    let out;
+    try {
+        out = runGit(root, ['diff', '--numstat']);
+    }
+    catch {
+        return [];
+    }
+    if (out.length === 0) {
+        return [];
+    }
+    return out.split('\n').map((line) => {
+        const [added, removed, ...path] = line.split('\t');
+        return { added: toCount(added), removed: toCount(removed), path: path.join('\t') };
+    });
+}
+/**
+ * A numstat count field as a number: `-` (a binary file) and anything else
+ * unparseable read as 0.
+ */
+function toCount(field) {
+    const n = Number.parseInt(field ?? '', 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/**
+ * The raw `git diff` patch for `paths` (working tree against the index), or ''
+ * when nothing differs or git refuses.
+ *
+ * Only the pause's inline-diff fence reads this, and only after the numstat
+ * count came in at 20 changed lines or fewer, so the patch is always small.
+ * Best-effort like diffNumstat: information, never a gate.
+ */
+export function diffPatch(root, paths) {
+    if (paths.length === 0) {
+        return '';
+    }
+    try {
+        return runGit(root, ['diff', '--', ...paths]);
+    }
+    catch {
+        return '';
+    }
+}
 // --- mutation helpers (build-loop: done checkpoints, revert resets). Additive
 // only: stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
 /**

package/dist/lib/notice.js

@@ -0,0 +1,140 @@
+// The one renderer for every line plumbbob says out loud and a skill relays,
+// and the assembly that stacks those lines into an ending. It has three heads,
+// and the ending picks which: a transition's lead line goes to stdout wearing a
+// bold label, like every other part of the ending
+// (`**Checkpoint**: Step 15 complete (2d917cde7)`); an advisory riding that
+// ending goes to stdout too, as a bare sentence, since a block with one speaker
+// needs no one named; and a refusal goes to stderr keeping the `plumbbob:`
+// prefix, which earns its colon where checkride's output and git's share one
+// result. Under every head the shape is the same: the fact as one clause, the
+// detail a trailing parenthetical that degrades by count instead of running off
+// the edge, and an optional indented arrow line carrying what to do next. One
+// shape, so moving it is one edit rather than a sweep. The pointer at the next
+// step is not a line's job: `handoff` renders one, and the verb prints it as
+// the ending's last part. Pure string assembly, no fs, no gate.
+/** The column budget a notice line aims to fit, matching the readout fence. */
+const WIDTH = 80;
+/** The fewest detail items a degraded parenthetical still names, so the count has a universe to size. */
+const FLOOR = 2;
+/**
+ * Render one prefixed notice, newline included.
+ *
+ * The refusal head, and the head for a warning that joins no ending (an
+ * ambient agent that could not resolve, say):
+ *
+ * ```text
+ * plumbbob: no build named "auth" in .plumbbob/builds/ (rate-limit, logging)
+ *   → plumbbob use <slug>
+ * ```
+ */
+export function notice(n) {
+    return line(`${n.prefix ?? 'plumbbob'}: ${trimFact(n.fact)}${n.advisory === true ? ' ⚠' : ''}`, n);
+}
+/**
+ * Render one transition, newline included.
+ *
+ * The lead line of an ending, wearing a bold label so it reads as a part of the
+ * ending rather than as a second grammar beside it:
+ *
+ * ```text
+ * **Checkpoint**: Step 15 complete (2d917cde7)
+ * **Parked**: should /password-reset get the same throttle? (tangent)
+ * ```
+ *
+ * A transition never warns: an advisory qualifies the line and prints beneath
+ * it, on the same stream, as its own part of the ending.
+ */
+export function transition(t) {
+    return line(`**${t.label}**: ${trimFact(t.fact)}`, t);
+}
+/**
+ * Render one advisory of an ending, newline included.
+ *
+ * No prefix and no label: it rides stdout inside a block that has one speaker
+ * already, so it reads as the sentence it is, the warning glyph trailing the
+ * fact and the remedy on the line beneath.
+ *
+ * ```text
+ * Staged paths reach outside Step 16's seam ⚠ (test/integration/spike.test.ts)
+ *   → the checkpoint captures them, so revise the plan with /plumbbob:step
+ * ```
+ */
+export function advisory(a) {
+    return line(`${capitalize(trimFact(a.fact))} ⚠`, a);
+}
+/**
+ * Assemble a transition's whole ending: the labeled lead line, the Verdict
+ * where one was measured, the advisories, and the pointer.
+ *
+ * The order is the type's field order, so a verb composes parts and never a
+ * sequence. A part with nothing in it vanishes rather than leaving a gap.
+ */
+export function ending(e) {
+    return blocks([e.lead, e.verdict ?? null, ...(e.advisories ?? []), e.pointer ?? null]);
+}
+/**
+ * Stack a turn's parts: one blank line between each, one beneath the last.
+ *
+ * The trailing blank is the ending's own: the block is the turn's last text,
+ * and one flush against what follows cannot read as an ending. Empty parts drop
+ * out, so a caller can pass a part it may not have.
+ */
+export function blocks(parts) {
+    const kept = parts.filter((p) => p !== null && p.trim().length > 0);
+    return `${kept.map((p) => p.replace(/\n+$/, '')).join('\n\n')}\n\n`;
+}
+/**
+ * The head, its trailing parenthetical, and the remedy line beneath, assembled.
+ *
+ * The one place the parts meet, so a prefixed line and a labeled one can never
+ * drift in anything but their heads.
+ */
+function line(head, n) {
+    const detail = fit(head, (n.detail ?? []).map((d) => d.trim()).filter((d) => d.length > 0));
+    const text = detail.length === 0 ? head : `${head} (${detail.join(', ')})`;
+    return n.remedy === undefined ? `${text}\n` : `${text}\n  → ${n.remedy}\n`;
+}
+/**
+ * The fact as a bare clause: whitespace trimmed and one terminal period
+ * dropped.
+ *
+ * The formatter owns the line's punctuation, so a message composed elsewhere
+ * (a parse error, a park line a human wrote) still reads as one clause with a
+ * parenthetical after it rather than `… . (detail)`.
+ */
+function trimFact(fact) {
+    const text = fact.trim();
+    return text.endsWith('.') && !text.endsWith('..') ? text.slice(0, -1) : text;
+}
+/**
+ * The detail items that fit the width budget, with the overrun collapsed to a
+ * count.
+ *
+ * Two items or fewer are the fact's own qualifiers rather than a list, so they
+ * always render whole even when the line runs long: a notice wraps where a
+ * fence row cannot. A real list drops from the tail until the line fits,
+ * naming at least `FLOOR` of them, because a count with nothing beside it
+ * sizes a universe the reader cannot see.
+ */
+function fit(head, items) {
+    if (items.length <= FLOOR)
+        return items;
+    for (let keep = items.length; keep > FLOOR; keep -= 1) {
+        const shown = keep === items.length ? items : [...items.slice(0, keep), others(items.length - keep)];
+        if (columns(head) + columns(` (${shown.join(', ')})`) <= WIDTH)
+            return shown;
+    }
+    return [...items.slice(0, FLOOR), others(items.length - FLOOR)];
+}
+/** A fact's first letter raised, so an unprefixed advisory opens as a sentence. */
+function capitalize(fact) {
+    return fact.length === 0 ? fact : `${fact[0]?.toUpperCase()}${fact.slice(1)}`;
+}
+/** The collapsed tail naming how many items the line left out. */
+function others(count) {
+    return `and ${count} other${count === 1 ? '' : 's'}`;
+}
+/** A string's printed width, counted in code points so the glyphs measure as one column each. */
+function columns(text) {
+    return [...text].length;
+}