plumbbob 0.13.1 → 0.13.3

package/dist/lib/sidecar.js

@@ -18,6 +18,7 @@
 // human-owned (check/auto): the tool only ever reads it, never rewrites it. The
 // phase the dashboard shows (DESIGN/BUILD/SPIKE) is derived, not stored: BUILD ⇔
 // a STEP is in flight, SPIKE ⇔ the SPIKE marker is present, otherwise DESIGN.
+import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { gitPath } from "./git.js";
@@ -228,6 +229,61 @@ export function pausePath(root, slug) {
 export function clearPause(root, slug) {
     rmSync(pausePath(root, slug), { force: true });
 }
+/**
+ * STOP: the stamp of the stop card `handoff --stop` last rendered whole, the
+ * range it reviews, the TURN it printed in, a hash of what the card showed,
+ * and a digest of the detail file it printed from. While a later render
+ * matches the range and the hash, handoff prints the one-line reminder;
+ * `plumbbob harvest` records the stop only from the detail the card showed,
+ * and only once a human turn has read it.
+ */
+export function stopPath(root, slug) {
+    return join(artifactDir(root, slug), 'STOP');
+}
+/**
+ * The stamp of the stop card last rendered, or null when STOP is absent or
+ * does not parse.
+ */
+export function readStop(root, slug) {
+    try {
+        const m = /^(\d+) (\d+|-) (\S+)(?: (\S+))?$/.exec(readFileSync(stopPath(root, slug), 'utf8').trim());
+        if (m === null)
+            return null;
+        return { range: Number(m[1]), turn: m[2] === '-' ? null : Number(m[2]), hash: m[3] ?? '', detail: m[4] ?? null };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record the stamp of the stop card just printed, with the digest of the
+ * detail file as it stands, which is the file the card was rendered from.
+ * Best-effort: a failed write costs one more full card on a later turn, never
+ * this turn's output or its exit code.
+ */
+export function writeStop(root, slug, stamp) {
+    try {
+        const detail = detailDigest(readFileSync(detailPath(root), 'utf8'));
+        writeFileSync(stopPath(root, slug), `${stamp.range} ${stamp.turn ?? '-'} ${stamp.hash} ${detail}\n`);
+    }
+    catch {
+        // A read-only tree or a vanished build folder: the card still renders.
+    }
+}
+/**
+ * Remove the STOP stamp: the stop's record ends the card it recorded. Absent
+ * is a no-op.
+ */
+export function clearStop(root, slug) {
+    rmSync(stopPath(root, slug), { force: true });
+}
+/**
+ * The digest a STOP stamp keeps of a detail file, so the record can tell the
+ * detail a card showed from one written after it.
+ */
+export function detailDigest(detail) {
+    return createHash('sha256').update(detail).digest('hex');
+}
 /**
  * The build's `checkpoints` ledger: the recorded SHAs of landed plan and step
  * commits, one line each.
@@ -492,7 +548,7 @@ export function grantPath(root) {
 }
 /**
  * Rewrite (or clear) the one-turn GRANT: a non-null value is the minted grant
- * (`auto` | `range M`), null clears it.
+ * (`auto` | `steps <list>`), null clears it.
  *
  * The turn hook calls this on every human prompt (minted on a match, cleared
  * otherwise) so a grant lives exactly one turn by construction. Pairing the
@@ -507,6 +563,40 @@ export function setGrant(root, grant) {
         writeFileSync(grantPath(root), `${grant}\n`);
     }
 }
+/**
+ * RUN: the range a `/plumbbob:run` the human typed is landing, written beside
+ * GRANT by the turn hook so the checkpoint that completes the range knows a
+ * run landed it. The latch never reads it.
+ */
+export function runPath(root) {
+    return join(root, DIRNAME, 'RUN');
+}
+/**
+ * The range number the RUN mark names, or null when the mark is absent or
+ * holds anything but a positive number.
+ */
+export function readRun(root) {
+    try {
+        const n = Number(readFileSync(runPath(root), 'utf8').trim());
+        return Number.isSafeInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rewrite (or clear) the RUN mark: a range number marks that range's run,
+ * null clears it. The turn hook calls this on every typed prompt, beside
+ * `setGrant`, and the delete lives here with the grant's.
+ */
+export function setRun(root, item) {
+    if (item === null) {
+        rmSync(runPath(root), { force: true });
+    }
+    else {
+        writeFileSync(runPath(root), `${item}\n`);
+    }
+}
 /**
  * PROMPT: the id of the last prompt the turn hook saw, typed or not.
  */
@@ -599,11 +689,13 @@ export function readTurn(root) {
 // ending: a decision ending closes the turn, an orientation ending appears in
 // it, and a driver ending is recorded only so that the last ending wins.
 const RELAY_TIERS = ['decision', 'orientation', 'driver'];
-// Which ending printed: handoff's six forms first, then one per transition. It
-// is what the check's reason names when the ending went missing.
+// Which ending printed: handoff's eight forms first, then one per transition.
+// It is what the check's reason names when the ending went missing.
 const RELAY_RENDERS = [
     'card',
     'reminder',
+    'stop',
+    'stop-reminder',
     'plan',
     'boundary',
     'pointer',
@@ -618,6 +710,7 @@ const RELAY_RENDERS = [
     'spike-done',
     'use',
     'order',
+    'harvest',
     'finish',
     'start',
 ];
@@ -681,10 +774,18 @@ function formatRelay(record) {
     const header = [`turn ${record.turn}`, `tier ${record.tier}`, `render ${record.render}`];
     if (record.command !== undefined)
         header.push(`command ${record.command}`);
+    if (record.owes !== undefined) {
+        header.push(`owes range ${record.owes.range} of ${record.owes.count} after step ${record.owes.step}`);
+    }
     if (record.held !== undefined)
         header.push(`held ${record.held}`);
     return `${header.join('\n')}\n\n${record.text}`;
 }
+/** The `owes` header field read back, or null when it is absent or does not parse. */
+function owedOf(field) {
+    const m = /^range (\d+) of (\d+) after step (\d+)$/.exec(field ?? '');
+    return m === null ? null : { range: Number(m[1]), count: Number(m[2]), step: Number(m[3]) };
+}
 /**
  * The recorded ending, or null when RELAY is absent or its header does not
  * parse: a record the check cannot read is no record.
@@ -712,12 +813,14 @@ export function readRelay(root) {
     if (turn === null || tier === undefined || render === undefined)
         return null;
     const command = fields.get('command');
+    const owes = owedOf(fields.get('owes'));
     const held = count(fields.get('held'));
     return {
         turn,
         tier,
         render,
         ...(command === undefined ? {} : { command }),
+        ...(owes === null ? {} : { owes }),
         ...(held === null ? {} : { held }),
         text: raw.slice(split + 2),
     };
@@ -789,6 +892,8 @@ export function excludeControl(root) {
         // never writes, and never commits.
         `${DIRNAME}/TURN`,
         `${DIRNAME}/GRANT`,
+        // The range a typed run is landing, written beside the grant.
+        `${DIRNAME}/RUN`,
         // The id of the last prompt the turn hook saw, which tells a notice folded
         // into the running turn from one that starts its own.
         `${DIRNAME}/PROMPT`,
@@ -809,6 +914,9 @@ export function excludeControl(root) {
         // The pause stamp is in-flight control too: what handoff last showed, so
         // a repeat prints the reminder. It must never ride a step commit.
         `${DIRNAME}/builds/*/PAUSE`,
+        // The stop stamp likewise: what the stop card last showed, and the turn it
+        // printed in, for the reminder and the record's latch.
+        `${DIRNAME}/builds/*/STOP`,
         // The agent-run handoff ledger is step-scoped in-flight state, not a
         // tracked artifact: it must never ride a step commit into the PR.
         `${DIRNAME}/builds/*/handoff.json`,

package/dist/verbs/build.js

@@ -8,17 +8,18 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
-import { parseBuildRanges, parseOrderedSteps, rangeStanding, rangeStart, skippedBefore } from "../lib/orient.js";
+import { parseBuildRanges, parseOrderedSteps, rangeStanding, rangeStart, skippedBefore, stopFollowUp } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 import { readGrant } from "../lib/latch.js";
 import { notice } from "../lib/notice.js";
 import { hasStep, readBuildArgs } from "../lib/steplist.js";
+import { waitingCard } from "./handoff.js";
 /**
  * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
  * Refuses a missing session, a malformed step argument, a range such as `N-M`
- * or `20,5-9` (a `/plumbbob:build` skill feature, not a CLI one), and a seam
- * that fails to parse.
+ * or `20,5-9` (a `/plumbbob:build` skill feature, not a CLI one), a stop card
+ * still waiting for its reply, and a seam that fails to parse.
  * On entry it stamps the turn ledger and the step's start time, re-renders the
  * build-log's Current step line, and names the step when it is the last one a
  * self-approval grant reaches, or, under `--auto`, a call the plan's ranges
@@ -51,6 +52,15 @@ export function build(cwd, args) {
         return 1;
     }
     const intent = readFileSync(intentPath(root, slug), 'utf8');
+    // A stop card waiting for its reply holds every step, bare or named: the
+    // step's pause would write over the range's review in the detail file before
+    // the reply recorded it. Nothing is written, and on the plan's last range the
+    // card outranks "no undone step".
+    const waiting = waitingNotice(root, slug, intent);
+    if (waiting.length > 0) {
+        process.stderr.write(waiting);
+        return 1;
+    }
     // In build order: the sequence `## Build order` declares when a refined plan
     // has one, else the numbering, so this pick and the dashboard's agree.
     const steps = parseOrderedSteps(intent);
@@ -119,6 +129,31 @@ export function build(cwd, args) {
         `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }
+/**
+ * The refusal while a stop card waits for its reply, or '' when none waits:
+ * the card, then the reply that records it. `looks good` always does, and the
+ * remedy adds the move the card's second row names, read through the same
+ * `stopFollowUp`: the next range's run, the finish on the plan's last range,
+ * or nothing more when the next run would refuse. The remedy spends a
+ * semicolon, since the refusal register keeps its one colon for the prefix.
+ */
+function waitingNotice(root, slug, intent) {
+    const card = waitingCard(root, slug, intent);
+    if (card === null) {
+        return '';
+    }
+    const follow = stopFollowUp(intent);
+    const also = follow === null
+        ? ''
+        : follow === 'finish'
+            ? ', and /plumbbob:finish records it, then writes the report'
+            : `, and /plumbbob:run records it, then runs range ${follow.range.item} of ${follow.count}`;
+    return notice({
+        fact: 'no step entered',
+        detail: [`range ${card.range} of ${card.count}'s stop card is waiting for its reply`],
+        remedy: `reply to the card; looks good records it${also}`,
+    });
+}
 /**
  * The step a range typed at the CLI starts at: its first undone step in build
  * order when the plan reads, else its first number written.

package/dist/verbs/checkpoint.js

@@ -12,7 +12,7 @@
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, hasSession, intentPath, readRun, 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";
@@ -22,7 +22,8 @@ import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commit
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
-import { boundaryEnding, planRecord, stepRecord } from "./handoff.js";
+import { boundaryEnding, detailsLink, parseDetailRange, planRecord, stepRecord } from "./handoff.js";
+import { isHarvestDetail } from "./harvest.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
  *
@@ -102,7 +103,12 @@ export async function checkpoint(cwd, args) {
     else {
         sha = headSha(root);
     }
-    clearDetail(root); // the detail is recorded in the Log below; clear it so no stale detail rides into the next step.
+    // The detail is recorded in the Log below; clear it so no stale detail rides
+    // into the next step. A stop's or a harvest's detail is the record's to
+    // clear, so it stays where it is.
+    if (!heldDetail(root)) {
+        clearDetail(root);
+    }
     appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
     const flipNotice = flipIntent(root, step);
     stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
@@ -122,9 +128,13 @@ export async function checkpoint(cwd, args) {
     // 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);
+    // A landing that completes the range a typed run marked owes the stop card:
+    // the record says so, and the relay check holds a turn that ends here.
+    const owes = landed.range !== null && readRun(root) === landed.range.item ? { range: landed.range.item, count: landed.range.count, step } : null;
     printEnding(root, {
         tier: 'orientation',
         render: 'checkpoint',
+        ...(owes === null ? {} : { owes }),
         text: ending({
             lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
             verdict: landed.verdict,
@@ -302,10 +312,11 @@ function flipIntent(root, step) {
 }
 /**
  * The lead line's trailing parenthetical: the short SHA, and where the Log
- * entry landed when one did, as the same `details:` clause Next Up carries.
+ * entry landed when one did, as the same short linked `details:` clause Next
+ * Up carries.
  */
 function leadDetail(sha, pointer) {
-    return pointer === null ? [sha.slice(0, 9)] : [sha.slice(0, 9), `details: \`${pointer}\``];
+    return pointer === null ? [sha.slice(0, 9)] : [sha.slice(0, 9), detailsLink(pointer.path, pointer.line)];
 }
 /**
  * Append the step's entry to the build-log's `## Log` section: the dated line,
@@ -314,8 +325,8 @@ function leadDetail(sha, pointer) {
  * The build's history accrues at each checkpoint instead of being reconstructed
  * at finish; the step's title is lifted from intent.md when still present.
  * Best-effort: a missing or odd build-log never blocks a checkpoint; the
- * `checkpoints` SHA is the source of truth. Returns where the line landed, as
- * `path:line` from the repo root, or null when nothing was written.
+ * `checkpoints` SHA is the source of truth. Returns where the line landed, or
+ * null when nothing was written.
  */
 function logCheckpoint(root, step, sha, record) {
     const date = new Date().toISOString().slice(0, 10);
@@ -329,8 +340,8 @@ function logPlan(root, sha, record) {
     return appendLog(root, planLogLine(new Date().toISOString().slice(0, 10), sha), record);
 }
 /**
- * Write one Log entry and say where its dated line landed (`path:line` from
- * the repo root), or null when the section is missing or the write failed.
+ * Write one Log entry and say where its dated line landed, or null when the
+ * section is missing or the write failed.
  */
 function appendLog(root, line, record) {
     try {
@@ -341,7 +352,7 @@ function appendLog(root, line, record) {
         }
         writeFileSync(path, updated);
         const at = updated.split('\n').lastIndexOf(line);
-        return at === -1 ? null : `${relative(root, path)}:${at + 1}`;
+        return at === -1 ? null : { path: relative(root, path), line: at + 1 };
     }
     catch {
         // best-effort ledger; never fail a checkpoint over the build-log.
@@ -460,13 +471,15 @@ function fallbackBody(root, step) {
  * the Log's record, and the caller clears it afterward. A missing or blank file
  * records nothing, and so does one whose header names a different step: that
  * file is a leftover, written after its own step had already landed, and
- * recording it would file one step's story under another. The plan commit
- * passes no step and takes the file as it is.
+ * recording it would file one step's story under another. A range's detail
+ * and a boundary harvest's record nothing here either: they are
+ * `plumbbob harvest`'s to record. The plan commit passes no step and takes the
+ * file as it is.
  */
 function readDetail(root, step) {
     try {
         const raw = readFileSync(detailPath(root), 'utf8').trim();
-        if (raw.length === 0) {
+        if (raw.length === 0 || (step !== null && heldDetail(root))) {
             return null;
         }
         const written = step === null ? null : parseDetailStep(raw);
@@ -476,6 +489,20 @@ function readDetail(root, step) {
         return null;
     }
 }
+/**
+ * Whether the detail file is one a step's checkpoint leaves alone: a range's,
+ * the stop card's wire, or a boundary harvest's, each read off its header and
+ * each recorded and cleared by `plumbbob harvest`.
+ */
+function heldDetail(root) {
+    try {
+        const raw = readFileSync(detailPath(root), 'utf8');
+        return parseDetailRange(raw) !== null || isHarvestDetail(raw);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The step's done-when line from intent.md, or null when absent or unreadable.
  */