plumbbob 0.9.2 → 0.9.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "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

@@ -26,31 +26,260 @@ import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 import { agent } from "./verbs/agent.js";
 import { turn } from "./verbs/turn.js";
-/** One help-table row per verb, in the order the table prints. */
+/** Shared across every verb that resolves through the active-build cursor. */
+const BUILD_FLAG = {
+    name: '--build',
+    value: '<slug>',
+    gloss: 'target a specific build instead of the active cursor',
+};
+/**
+ * The full CLI spec, in the order the help table prints.
+ *
+ * One table drives three things: the top-level verb table, per-verb `--help`,
+ * and the unknown-flag refusal in `run`. Keeping it as data rather than inline
+ * writes is the deliberate exception to the write-at-the-call-site convention —
+ * a synopsis has to be readable by the validator, not just printable.
+ */
 const VERBS = [
-    { name: 'start', summary: 'scaffold .plumbbob/; open the session; record the baseline commit' },
-    { name: 'status', summary: 'print the orientation dashboard, or NO ACTIVE SESSION' },
-    { name: 'build', summary: 'build [<n>]: write the seam from step n, or the next undone step (in-flight, not a lock)' },
-    { name: 'handoff', summary: 'print the standardized build hand-off block (pause or post-checkpoint); read-only' },
-    { name: 'check', summary: 'run the heavy check and report; no state change (--bail --only a,b … narrow the checkride gate)' },
-    { name: 'checkpoint', summary: 'checkpoint [<n>]: gate on green, commit/record SHA, mark step done (executor-agnostic)' },
-    { name: 'revert', summary: 'revert [--to n]: git reset --hard to a checkpoint SHA' },
-    { name: 'park', summary: 'park "<text>": append a raw line to the park list' },
-    { name: 'spike', summary: 'spike "<slug>" | spike report "<slug>" | spike done: worktree experiment + report' },
-    { name: 'use', summary: 'use <slug>: re-point the active-build cursor and resume that build' },
-    { name: 'finish', summary: 'close-out: report + final commit (no gate), clear the control state, close the session' },
-    { name: 'init', summary: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob); --uninstall to undo' },
-    { name: 'doctor', summary: 'diagnose the plugin link + detect a legacy flat sidecar; doctor --migrate moves it into builds/ (staged, not committed)' },
-    { name: 'agent', summary: 'agent list | run <name> [--step N] [--mode before|build|after]: list or spawn a user-authored agent' },
-    { name: 'turn', summary: 'turn: UserPromptSubmit hook machinery — tick the turn ledger from stdin (not a user verb)' },
+    {
+        name: 'start',
+        description: 'scaffold .plumbbob/; open the session; record the baseline commit',
+        synopsis: ['start "<title>" [--slug <name>] [--local] [--allow-dirty]'],
+        args: [{ name: '<title>', gloss: 'what you are building (quoted)' }],
+        flags: [
+            { name: '--slug', value: '<name>', gloss: 'use this slug verbatim instead of the derived YYYY-MM-DD-<title-slug>' },
+            { name: '--local', gloss: 'opt into the old fully-untracked flat layout' },
+            { name: '--allow-dirty', gloss: 'record the current HEAD as baseline despite a dirty tree' },
+        ],
+        notes: 'Refuses (exit 1) on an empty title, a slug collision, a non-git directory, a repo with no commits, an already-active session, or a dirty tree.',
+    },
+    {
+        name: 'status',
+        description: 'print the orientation dashboard, or NO ACTIVE SESSION',
+        synopsis: ['status [--build <slug>]'],
+        flags: [BUILD_FLAG],
+        notes: 'Read-only; always exits 0. With no cursor it lists the available builds.',
+    },
+    {
+        name: 'build',
+        description: 'write the seam from step n, or the next undone step (in-flight, not a lock)',
+        synopsis: ['build [<n>] [--build <slug>]'],
+        args: [{ name: '<n>', gloss: 'step to build (default: the next undone step)' }],
+        flags: [BUILD_FLAG],
+        notes: 'Refuses (exit 1) with no session, a non-numeric or < 1 step, or a seam it cannot parse.',
+    },
+    {
+        name: 'handoff',
+        description: 'print the standardized build hand-off block (pause or post-checkpoint); read-only',
+        synopsis: ['handoff [<n>] [--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.',
+    },
+    {
+        name: 'check',
+        description: 'run the heavy check and report; no state change',
+        synopsis: ['check [--bail] [--changed] [--all] [--only a,b] [--skip a,b] [--include a,b]'],
+        flags: [
+            { name: '--bail', gloss: 'stop at the first red slot' },
+            { name: '--changed', gloss: 'limit the run to changed files' },
+            { name: '--all', gloss: 'run every slot' },
+            { name: '--only', value: '<a,b>', gloss: 'run only these slots' },
+            { name: '--skip', value: '<a,b>', gloss: 'run every slot except these' },
+            { name: '--include', value: '<a,b>', gloss: 'add these slots to the run' },
+        ],
+        notes: 'Exits 0 green, 1 red, 2 when the gate itself broke. The flags narrow a checkride run and are warned-and-ignored on the `check` settings-override path.',
+    },
+    {
+        name: 'checkpoint',
+        description: 'gate on green, commit/record SHA, mark step done (executor-agnostic)',
+        synopsis: ['checkpoint [<n>] [-m <msg>] [--body]', 'checkpoint --plan [--body]'],
+        args: [{ name: '<n>', gloss: 'step to checkpoint (else the in-flight STEP, else the first undone step)' }],
+        flags: [
+            { name: '--plan', gloss: "commit only the build's artifact folder as chore(<scope>): plan" },
+            { name: '-m', value: '<msg>', gloss: 'override the CLI-owned Conventional subject' },
+            { name: '--body', gloss: 'read the commit body from stdin (heredoc)' },
+        ],
+        notes: 'Refuses (exit 1) with no session, no resolvable step, or a red check.',
+    },
+    {
+        name: 'revert',
+        description: 'git reset --hard to a checkpoint SHA',
+        synopsis: ['revert [--to <n>] [--build <slug>]'],
+        flags: [
+            { name: '--to', value: '<n>', gloss: "revert to step n's checkpoint (default: the last, else the baseline)" },
+            BUILD_FLAG,
+        ],
+        notes: 'Refuses (exit 1) with no session, an invalid --to, or a step with no recorded checkpoint.',
+    },
+    {
+        name: 'park',
+        description: 'append a raw line to the park list',
+        synopsis: ['park "<text>"'],
+        args: [{ name: '<text>', gloss: 'the note to park (free text; quote it)' }],
+        tolerateUnknownFlags: true,
+        notes: 'Refuses (exit 1) with no session, empty text, or no `## Park list` section.',
+    },
+    {
+        name: 'spike',
+        description: 'worktree experiment + report for a genuine fork',
+        synopsis: ['spike "<slug>" [opt…] [--build <slug>]', 'spike report "<slug>"', 'spike done'],
+        args: [
+            { name: '<slug>', gloss: 'name of the experiment' },
+            { name: '[opt…]', gloss: 'the options to fork (default: a and b)' },
+        ],
+        flags: [BUILD_FLAG],
+        notes: 'Refuses (exit 1) with no session, a step already in flight, an empty slug, or a worktree path that already exists.',
+    },
+    {
+        name: 'use',
+        description: 're-point the active-build cursor and resume that build',
+        synopsis: ['use <slug>'],
+        args: [{ name: '<slug>', gloss: 'the build folder under .plumbbob/builds/ to resume' }],
+        notes: 'Refuses (exit 1) with an empty slug or a slug with no build folder; warns (but allows) leaving a step in flight.',
+    },
+    {
+        name: 'finish',
+        description: 'close-out: report + final commit (no gate), clear the control state, close the session',
+        synopsis: ['finish [--body] [--build <slug>]'],
+        flags: [{ name: '--body', gloss: 'read the commit body from stdin (heredoc)' }, BUILD_FLAG],
+        notes: 'Refuses (exit 1) only with no session. There is no refuse-without-report gate.',
+    },
+    {
+        name: 'init',
+        description: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob)',
+        synopsis: ['init [--uninstall] [--force]'],
+        flags: [
+            { name: '--uninstall', gloss: 'drop the link' },
+            { name: '--force', gloss: 'override the marketplace double-install guard' },
+        ],
+        notes: 'Idempotent and global-only; it never writes settings.json. Restart Claude Code (or /reload-plugins) to activate.',
+    },
+    {
+        name: 'doctor',
+        description: 'diagnose the plugin link + check gate; detect a legacy flat sidecar',
+        synopsis: ['doctor [--migrate]'],
+        flags: [{ name: '--migrate', gloss: 'move a legacy flat sidecar into builds/ (staged, not committed)' }],
+        notes: 'Exits 0 when everything passes, 1 when a check fails or an un-migrated legacy sidecar is present.',
+    },
+    {
+        name: 'agent',
+        description: 'list or spawn a user-authored agent',
+        synopsis: [
+            'agent list',
+            'agent run <name> [--step N] [--mode before|build|after] [--agent <path>] [--build <slug>]',
+            'agent run --mode before|build|after [--step N]',
+        ],
+        args: [
+            { name: 'list', gloss: 'print every resolvable agent — name, origin tier, slots, description' },
+            { name: 'run', gloss: 'spawn an agent through the doorway; no code path advances the loop' },
+        ],
+        flags: [
+            { name: '--step', value: '<n>', gloss: 'pick the step (else the in-flight STEP)' },
+            { name: '--mode', value: '<slot>', gloss: 'the slot to run in: before, build, or after' },
+            { name: '--agent', value: '<path>', gloss: 'point at an explicit agent directory (top of the ladder)' },
+            BUILD_FLAG,
+        ],
+        notes: 'Exits 0 on a clean run, 1 on a failed one. See docs/agents.md for the author contract.',
+    },
+    {
+        name: 'turn',
+        description: 'UserPromptSubmit hook machinery — tick the turn ledger from stdin (not a user verb)',
+        synopsis: ['turn'],
+        tolerateUnknownFlags: true,
+        notes: 'Reads the hook payload from stdin and always exits 0 — a broken hook must never wedge a prompt.',
+    },
 ];
 /**
  * Render the verb table for `plumbbob help`.
  */
 export function formatHelp() {
     const width = Math.max(...VERBS.map((v) => v.name.length));
-    const rows = VERBS.map((v) => `  ${v.name.padEnd(width)}  ${v.summary}`);
-    return ['plumbbob — attention-first build process', '', 'Usage: plumbbob <verb> [args]', '', 'Verbs:', ...rows, ''].join('\n');
+    const rows = VERBS.map((v) => `  ${v.name.padEnd(width)}  ${v.description}`);
+    return [
+        'plumbbob — attention-first build process',
+        '',
+        'Usage: plumbbob <verb> [args]',
+        '',
+        'Verbs:',
+        ...rows,
+        '',
+        "Run 'plumbbob <verb> --help' for a verb's arguments and flags.",
+        '',
+    ].join('\n');
+}
+/**
+ * Render the synopsis, argument, and flag block for `plumbbob <verb> --help`,
+ * or null when the name is not a verb.
+ *
+ * Arguments and flags share one aligned column so the reader scans a single
+ * list; a flag that takes a value prints as `--only <a,b>` so the spelling in
+ * the help is the spelling you type.
+ */
+export function formatVerbHelp(name) {
+    const spec = verbSpec(name);
+    if (spec === null)
+        return null;
+    const entries = [
+        ...(spec.args ?? []).map((a) => ({ label: a.name, gloss: a.gloss })),
+        ...(spec.flags ?? []).map((f) => ({
+            label: f.value === undefined ? f.name : `${f.name} ${f.value}`,
+            gloss: f.gloss,
+        })),
+    ];
+    const width = Math.max(0, ...entries.map((e) => e.label.length));
+    const rows = entries.map((e) => `  ${e.label.padEnd(width)}  ${e.gloss}`);
+    return [
+        ...spec.synopsis.map((s) => `plumbbob ${s}`),
+        '',
+        spec.description,
+        ...(rows.length > 0 ? ['', ...rows] : []),
+        ...(spec.notes === undefined ? [] : ['', spec.notes]),
+        '',
+        `See: docs/cli-reference.md#${spec.name}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Look up a verb's spec by name, or null when the name is not a verb.
+ */
+export function verbSpec(name) {
+    return VERBS.find((v) => v.name === name) ?? null;
+}
+/**
+ * Every verb name, in table order — the contract tests iterate this.
+ */
+export function verbNames() {
+    return VERBS.map((v) => v.name);
+}
+/**
+ * Walk a verb's argv against its spec: did it ask for help, and what did it
+ * spell wrong?
+ *
+ * Value-consuming flags swallow their next token, so a value that happens to
+ * look like a flag (`checkpoint -m "--help"`) is read as the value it is. Bare
+ * `--help`/`-h` are recognized for every verb without being declared.
+ */
+function scanFlags(spec, args) {
+    const known = new Map((spec.flags ?? []).map((f) => [f.name, f]));
+    const unknown = [];
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const flag = known.get(arg);
+        if (flag !== undefined) {
+            if (flag.value !== undefined)
+                i++;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+        }
+        else if (arg.startsWith('-') && arg.length > 1) {
+            unknown.push(arg);
+        }
+    }
+    return { help, unknown };
 }
 /**
  * The package version, or 'unknown'.
@@ -116,21 +345,49 @@ async function dispatch(verb, cwd, rest) {
 /**
  * The CLI entrypoint minus the exit: parse argv, dispatch, return the exit code.
  *
- * `help` and `version` short-circuit before dispatch; any thrown error becomes
- * a one-line stderr report and exit 1, so the bin entry only ever exits with
- * the code returned here.
+ * `help` and `version` short-circuit before dispatch, as do per-verb `--help`
+ * and the unknown-flag refusal. Screening flags *here* rather than in each verb
+ * is what makes it safe by construction: a mutating verb can no longer be
+ * reached by an argv it does not understand, which is how `checkpoint --help`
+ * used to commit a real checkpoint. Any thrown error becomes a one-line stderr
+ * report and exit 1, so the bin entry only ever exits with the code returned
+ * here.
  */
 export async function run(argv) {
     const verb = argv[0] ?? 'help';
     const rest = argv.slice(1);
     if (verb === 'help' || verb === '--help' || verb === '-h') {
-        process.stdout.write(`${formatHelp()}\n`);
+        // `plumbbob help <verb>` is the same page as `plumbbob <verb> --help` —
+        // both spellings get typed, so both work.
+        const topic = rest.find((a) => !a.startsWith('-'));
+        if (topic === undefined) {
+            process.stdout.write(`${formatHelp()}\n`);
+            return 0;
+        }
+        const help = formatVerbHelp(topic);
+        if (help === null) {
+            process.stderr.write(`plumbbob: unknown verb '${topic}'. Run 'plumbbob help' for the verb table.\n`);
+            return 1;
+        }
+        process.stdout.write(`${help}\n`);
         return 0;
     }
     if (verb === 'version' || verb === '--version' || verb === '-v') {
         process.stdout.write(`plumbbob ${readVersion()}\n`);
         return 0;
     }
+    const spec = verbSpec(verb);
+    if (spec !== null) {
+        const { help, unknown } = scanFlags(spec, rest);
+        if (help) {
+            process.stdout.write(`${formatVerbHelp(verb)}\n`);
+            return 0;
+        }
+        if (unknown.length > 0 && spec.tolerateUnknownFlags !== true) {
+            process.stderr.write(`plumbbob: ${verb}: unknown flag '${unknown[0]}'. Run 'plumbbob ${verb} --help' for the flags.\n`);
+            return 1;
+        }
+    }
     try {
         return await dispatch(verb, process.cwd(), rest);
     }

package/dist/verbs/agent.js

@@ -215,8 +215,9 @@ function degrade(ambient, hard, soft) {
  * agent name and the value flags.
  *
  * A value flag missing its value, or `--step` given a non-number, is a loud
- * error (returned as a string) rather than a silent default. Unknown `--flags`
- * are ignored — the point is the named agent.
+ * error (returned as a string) rather than a silent default. An undeclared
+ * `--flag` never arrives here — `run` screens argv against the verb spec in
+ * cli-core.ts and refuses before dispatch.
  */
 function parseRunArgs(args) {
     const positionals = [];

package/dist/verbs/check.js

@@ -32,8 +32,12 @@ export async function check(cwd, args = []) {
 /**
  * Map argv onto checkride's flags: bare booleans plus comma-separated slot lists.
  *
- * Unknown args are ignored rather than refused — running the gate is the point,
- * not flag hygiene.
+ * Only the declared flags are read here; an undeclared one never reaches this
+ * function, because `run` screens argv against the verb spec in cli-core.ts and
+ * refuses before dispatch. This used to tolerate unknown args on the grounds
+ * that running the gate mattered more than flag hygiene — but the same tolerance
+ * on the mutating verbs let `checkpoint --help` commit, so the screen is now
+ * central and uniform.
  */
 function parseFlags(args) {
     return {

package/package.json

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