plumbbob 0.9.5 → 0.10.0

package/dist/lib/latch.js

@@ -1,25 +1,25 @@
-// The approval latch — the ledger-plane predicate `checkpoint` evaluates before
+// The approval latch: the ledger-plane predicate `checkpoint` evaluates before
 // its check gate (the latch is cheap, so it runs first; the heavy gate already
-// ran in the verify tick). The work plane stays guidance — no edit is ever
-// blocked — but the commit tick is latched: a step may not land unless a human
+// ran in the verify tick). The work plane stays guidance (no edit is ever
+// blocked) but the commit tick is latched: a step may not land unless a human
 // turn intervened since the step was entered, the human granted a one-turn
 // self-approval from their literal prompt, or the turn ledger is dormant (a
 // host with no hooks grows no ledger, and the latch stays out of the way rather
 // than wedging). The ledger is a pair of flat sidecar control files: TURN
 // counts human prompts (ticked by the `plumbbob turn` hook), TICK stamps that
-// count when a step is entered — TURN > TICK means a human turn intervened.
+// count when a step is entered; TURN > TICK means a human turn intervened.
 // Five rows, evaluated in order, first hit wins; the refusal message *is* the
 // pause affordance. A standing `auto` in a settings file is never a grant: a
-// model can write that file, and a grant it can forge is no grant — the latch
+// model can write that file, and a grant it can forge is no grant; the latch
 // reads it only to say so at the pause, never to allow. It reads only
-// TURN/TICK/GRANT and isTTY — it never sniffs the host session. Named exports,
+// TURN/TICK/GRANT and isTTY; it never sniffs the host session. Named exports,
 // node builtins.
 import { readFileSync } from 'node:fs';
 import { grantPath, tickPath, turnPath } from "./sidecar.js";
 import { resolveBoolean } from "./settings.js";
 const ALLOW = { allow: true };
 /**
- * The refusal message is the affordance — it tells the model what the pause is,
+ * The refusal message is the affordance; it tells the model what the pause is,
  * how it ends (approval on the next turn lands it; `/plumbbob:build` only starts the
  * next step), and names the only legitimate grants.
  */
@@ -31,7 +31,7 @@ boundary; \`/plumbbob:build\` only starts the next step, it never lands this one
 `;
 /**
  * The plan commit gets its own wording: there is no step, no diff, and no
- * self-review at plan time — what the human approves is the plan itself.
+ * self-review at plan time; what the human approves is the plan itself.
  */
 const NO_TURN_PLAN_MESSAGE = `plumbbob: checkpoint refused — no human turn since \`start\` stamped this plan. This
 is the plan pause: present the plan, then end the turn; the human's approving
@@ -39,7 +39,7 @@ message is the tick that lets it land on the next run. (An explicit \`/plumbbob:
 step range in the human's own prompt is the only self-approval.)
 `;
 /**
- * A settings `auto` is never a grant — a model can write that file, and a grant
+ * A settings `auto` is never a grant; a model can write that file, and a grant
  * it can forge is no grant. When one is set, the refusal names it rather than
  * silently ignoring it, and points at the only self-approval that works.
  */
@@ -60,19 +60,19 @@ function ceilingMessage(ceiling) {
  */
 export function evaluateLatch(input) {
     if (input.isTTY)
-        return ALLOW; // 1 — a human at the keyboard
+        return ALLOW; // 1: a human at the keyboard
     if (input.turn === null || input.tick === null)
-        return ALLOW; // 2 — dormant ledger / hand-built diff
+        return ALLOW; // 2: dormant ledger / hand-built diff
     if (input.grant?.kind === 'auto')
-        return ALLOW; // 3 — one-turn grant the human typed
+        return ALLOW; // 3: one-turn grant the human typed
     if (input.grant?.kind === 'range' && input.step !== null) {
         if (input.step <= input.grant.ceiling)
             return ALLOW;
         return { allow: false, reason: 'ceiling', message: ceilingMessage(input.grant.ceiling) };
     }
     if (input.turn > input.tick)
-        return ALLOW; // 4 — a human turn intervened
-    // 5 — the pause (plan-worded when no step is landing). A settings `auto` never
+        return ALLOW; // 4: a human turn intervened
+    // 5: the pause (plan-worded when no step is landing). A settings `auto` never
     // allows; when one is set, the refusal notes it rather than honoring it.
     const base = input.step === null ? NO_TURN_PLAN_MESSAGE : NO_TURN_MESSAGE;
     return { allow: false, reason: 'no-turn', message: input.settingsAuto ? base + SETTINGS_AUTO_NOTE : base };
@@ -80,7 +80,7 @@ export function evaluateLatch(input) {
 /**
  * Parse a GRANT file's content (`auto` | `range <M>`).
  *
- * Anything else — including a corrupted or hand-mangled file — contributes
+ * Anything else (including a corrupted or hand-mangled file) contributes
  * nothing: no grant, never an error.
  */
 export function parseGrant(raw) {
@@ -105,7 +105,7 @@ export function checkLatch(root, step) {
         tick: readCount(tickPath(root)),
         grant: readGrant(root),
         step,
-        // Read from the settings ladder — but only to decorate the pause, never to allow.
+        // Read from the settings ladder, but only to decorate the pause, never to allow.
         settingsAuto: resolveBoolean(root, 'auto', false),
     });
 }

package/dist/lib/orient.js

@@ -1,5 +1,5 @@
 // The orientation model behind `status`: parse a live build session into the
-// where-am-I dashboard — title, phase, step list, last checkpoint, counts, and
+// where-am-I dashboard: title, phase, step list, last checkpoint, counts, and
 // one suggested next move. Pure and best-effort by design: it takes raw file
 // contents (no fs), and a malformed document degrades to fewer fields rather
 // than throwing.
@@ -20,7 +20,7 @@ function sectionLines(content, heading) {
     return lines.slice(start + 1, end);
 }
 /**
- * The build title — the first `# ` heading in intent.md, or null when absent.
+ * The build title: the first `# ` heading in intent.md, or null when absent.
  */
 export function parseTitle(intent) {
     for (const line of intent.split('\n')) {
@@ -32,12 +32,14 @@ export function parseTitle(intent) {
     return null;
 }
 /**
- * Parse the steps under `## Steps`: `N. [ |x] Title — **done when:** ...`.
+ * Parse the steps under `## Steps`: `N. [ |x] Title, **done when:** ...`
+ * (the legacy em-dash separator before the marker parses the same).
  *
- * The title is the text up to the first em dash; `planned` is true when the
- * step's block carries a `done when` criterion. Only `## Steps` is machine-read
- * as the build plan — narrative roadmap prose lives in its own section and
- * never lands here.
+ * The title is the text before the `**done when:**` marker on the opener line,
+ * trailing separator stripped; an opener without the marker falls back to the
+ * text up to the first em dash. `planned` is true when the step's block carries
+ * a `done when` criterion. Only `## Steps` is machine-read as the build plan;
+ * narrative roadmap prose lives in its own section and never lands here.
  */
 export function parseSteps(intent) {
     const lines = sectionLines(intent, '## Steps');
@@ -46,10 +48,12 @@ export function parseSteps(intent) {
         const m = /^(\d+)\.\s+\[([ xX])\]\s+(.*)$/.exec(line);
         if (m) {
             const rest = m[3] ?? '';
+            const marker = /\*\*done when:\*\*/i.exec(rest);
+            const head = marker ? rest.slice(0, marker.index) : (rest.split('—')[0] ?? rest);
             starts.push({
                 n: Number(m[1]),
                 done: (m[2] ?? ' ').toLowerCase() === 'x',
-                title: (rest.split('—')[0] ?? rest).trim(),
+                title: head.replace(/\s*[—,-]+\s*$/, '').trim(),
                 idx,
             });
         }
@@ -88,13 +92,28 @@ export function markStepDone(intent, n) {
 }
 /**
  * Count the questions still open: `- Q\d+:` openers under `## Open questions`
- * that do not say "resolved".
+ * that carry neither a resolution marker nor an unfilled scaffold body.
  *
- * The opener may carry a slug-at-birth gloss — `- Q2 (some-slug): ...` — which
- * the count reads through; sub-lines (`*plain:*`/`*lean:*`) never match.
+ * The opener may carry a slug-at-birth gloss (`- Q2 (some-slug): ...`) and the
+ * anchored form a citable question is born in:
+ * `- <a id="q2"></a>**Q2 (some-slug)**: ...`, which is what a `[Q2 (some-slug)](#q2)`
+ * reference site elsewhere in the file lands on. The count reads through both, and
+ * through any mix of them a hand-edited intent leaves mid-build; sub-lines
+ * (`*plain:*`/`*lean:*`) never match.
+ *
+ * Two rules settle the rest. "Resolved" counts as a marker only as a whole word, so
+ * a question whose opener still calls itself "unresolved" keeps counting; a bare
+ * substring read that as resolved and dropped a live hole off the dashboard. And an
+ * opener whose body has not been filled in yet, still opening on its `<...>`
+ * fill-in, is scaffold rather than a question, which is what makes a fresh build
+ * report zero rather than one.
  */
 export function parseOpenQuestions(intent) {
-    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+(?: \([^)]+\))?:/.test(l.trim()) && !/resolved/i.test(l)).length;
+    const opener = /^-\s+(?:<a id="[^"]*"><\/a>\s*)?\*{0,2}Q\d+(?: \([^)]+\))?\*{0,2}:\s*(.*)$/;
+    return sectionLines(intent, '## Open questions').filter((l) => {
+        const body = opener.exec(l.trim())?.[1];
+        return body !== undefined && !/\bresolved\b/i.test(l) && !/^<[^>]*>/.test(body);
+    }).length;
 }
 /**
  * Count the open parked items: `- [ ]` lines under `## Park list`.
@@ -122,12 +141,12 @@ export function parseLastCheckpoint(checkpoints) {
     return last;
 }
 /**
- * The SHA of the last ledger line of ANY kind — baseline, plan, or step.
+ * The SHA of the last ledger line of ANY kind: baseline, plan, or step.
  *
  * This is the reconciliation anchor for the out-of-band commit count: a commit
  * that lands after the plan but before the first step checkpoint is exactly the
  * window the reconciliation line exists for, so anchoring on step lines alone
- * would leave it invisible. `parseLastCheckpoint` stays step-only — it feeds
+ * would leave it invisible. `parseLastCheckpoint` stays step-only; it feeds
  * the "last checkpoint step N" display, where baseline/plan would be noise.
  */
 export function lastLedgerSha(checkpoints) {
@@ -162,7 +181,7 @@ function nextMove(spiking, steps, inFlight, parked) {
             return 'plan the first step — `/plumbbob:step`';
         }
         // Batch-default: the steps were planned up front, so finishing them usually
-        // means "finish up" — but `/plumbbob:step` can still add an increment if reality grew.
+        // means "finish up", but `/plumbbob:step` can still add an increment if reality grew.
         const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/plumbbob:harvest\`; then ` : '';
         return `${harvest}finish up — \`/plumbbob:finish\` (or \`/plumbbob:step\` to add another increment)`;
     }
@@ -207,7 +226,7 @@ export function formatOrientation(o) {
             return head;
         }
         // Surface the next step's detail so the human can review it (and `/plumbbob:step`-
-        // revise) before building. Only what's present — a rough step shows neither.
+        // revise) before building. Only what's present: a rough step shows neither.
         const detail = [];
         if (o.nextDoneWhen !== null) {
             detail.push(`        done when: ${o.nextDoneWhen}`);
@@ -225,7 +244,7 @@ export function formatOrientation(o) {
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
     // A neutral reconciliation note, only when there is something to reconcile:
     // commits landed since the last checkpoint that plumbbob's ledger didn't
-    // record. Informational — the human commits freely, so this never gates.
+    // record. Informational: the human commits freely, so this never gates.
     const receipts = o.outOfBand > 0
         ? [`${o.outOfBand} commit${o.outOfBand === 1 ? '' : 's'} since the last checkpoint landed outside plumbbob's ledger.`]
         : [];

package/dist/lib/reentry.js

@@ -3,8 +3,8 @@
 //
 // The failure it exists to stop is not slowness, it is unbounded recursion. A
 // repo whose `check` setting is its own full pipeline (`pnpm check`) has a gate
-// that runs its test suite; anything in that suite which gates THAT SAME REPO —
-// a test driving `checkpoint` against the process cwd — spawns a second full
+// that runs its test suite; anything in that suite which gates THAT SAME REPO
+// (a test driving `checkpoint` against the process cwd) spawns a second full
 // pipeline, whose suite spawns a third. Each generation forks wider than the
 // last, and nothing in the loop is aware there is a loop. The only thing that
 // ended the first observed occurrence was checkride's 600s per-check cap
@@ -13,7 +13,7 @@
 // It is scoped BY ROOT, and that is the whole design. A flat "a gate is
 // running" flag is wrong in the one case that matters most: plumbbob's own
 // suite legitimately gates dozens of fixture repos, and when the suite itself
-// is running under this repo's gate it inherits the marker — so a flat flag
+// is running under this repo's gate it inherits the marker, so a flat flag
 // refuses every one of them and turns a green suite red. Recursion is a repo
 // re-entering ITS OWN gate; a different root is ordinary nested work and must
 // pass through untouched.

package/dist/lib/settings.js

@@ -1,19 +1,19 @@
 // The settings ladder: a resolved setting comes from, in priority order,
-//   1. a CLI flag           — passed in by the verb (undefined when absent)
-//   2. settings.local.json  — untracked personal overlay, per-worktree
-//   3. settings.json        — tracked project defaults
-//   4. a built-in default   — supplied by the caller
+//   1. a CLI flag: passed in by the verb (undefined when absent)
+//   2. settings.local.json: untracked personal overlay, per-worktree
+//   3. settings.json: tracked project defaults
+//   4. a built-in default: supplied by the caller
 // The first defined rung wins. Both files are optional JSON; a missing or
 // malformed file contributes nothing rather than throwing, so a broken personal
 // overlay can never wedge the tool. Functional and procedural, node builtins only.
 //
-// Known keys: `check` (string — the command for the heavy verify gate, a project
-// default in settings.json) and `auto` (boolean — a personal preference, so it
+// Known keys: `check` (string: the command for the heavy verify gate, a project
+// default in settings.json) and `auto` (boolean: a personal preference, so it
 // belongs in settings.local.json). `auto` is NOT a checkpoint grant: the approval
-// latch never reads it to allow a land — a model can write this file, and a grant
-// it can forge is no grant — only to name it at the pause when set; self-approval
+// latch never reads it to allow a land (a model can write this file, and a grant
+// it can forge is no grant) only to name it at the pause when set; self-approval
 // comes solely from the human's literal `/build --auto` or a typed step range.
-// The per-worktree active-build cursor is NOT here — it lives in the STATE file
+// The per-worktree active-build cursor is NOT here: it lives in the STATE file
 // (see sidecar.ts), which keeps this overlay a human-authored file rather than
 // tool-managed state.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -34,7 +34,7 @@ export function localSettingsPath(root) {
 /**
  * Read one settings file as a plain object.
  *
- * A missing, malformed, or non-object file yields {} — an empty rung that
+ * A missing, malformed, or non-object file yields {}: an empty rung that
  * contributes nothing rather than wedging the tool.
  */
 function readSettings(path) {
@@ -61,7 +61,7 @@ function resolveSetting(root, key, flag) {
     return readSettings(settingsPath(root))[key];
 }
 /**
- * Resolve a string setting (e.g. `check`).
+ * Resolve a string setting (for example `check`).
  *
  * A missing rung, or one holding a non-string / blank value, yields the
  * caller's fallback rather than gating on garbage.
@@ -71,7 +71,7 @@ export function resolveString(root, key, fallback, flag) {
     return typeof value === 'string' && value.trim().length > 0 ? value : fallback;
 }
 /**
- * Resolve a boolean setting (e.g. `auto`). A missing or non-boolean rung
+ * Resolve a boolean setting (for example `auto`). A missing or non-boolean rung
  * yields the caller's fallback.
  */
 export function resolveBoolean(root, key, fallback, flag) {
@@ -79,10 +79,10 @@ export function resolveBoolean(root, key, fallback, flag) {
     return typeof value === 'boolean' ? value : fallback;
 }
 /**
- * Resolve a non-negative integer setting (e.g. `agentTimeout`).
+ * Resolve a non-negative integer setting (for example `agentTimeout`).
  *
  * A missing rung, or one holding a non-finite / negative / non-integer number,
- * yields the caller's fallback rather than a garbage timeout — 0 means "no
+ * yields the caller's fallback rather than a garbage timeout: 0 means "no
  * timeout", so a broken value must never silently become one.
  */
 export function resolveNumber(root, key, fallback, flag) {
@@ -90,11 +90,11 @@ export function resolveNumber(root, key, fallback, flag) {
     return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
 }
 /**
- * Resolve an object-valued setting (e.g. the `agents` slot-binding defaults)
+ * Resolve an object-valued setting (for example the `agents` slot-binding defaults)
  * across the same ladder.
  *
  * The first defined, object-typed rung wins; a missing rung, or one holding a
- * non-object / array / scalar, yields {} rather than garbage — mirrors the
+ * non-object / array / scalar, yields {} rather than garbage: mirrors the
  * string/boolean/number resolvers above. No flag rung: the caller (`agent
  * run`) merges these under the per-build harness bindings, not over a flag.
  */