plumbbob 0.8.18 → 0.9.1

package/dist/verbs/spike.js

@@ -1,10 +1,16 @@
-// `plumbbob spike` (D18) — the spike lifecycle for a genuine fork the design
-// phase couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree +
-// `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default opts a/b)
-// and drops the SPIKE marker; the main tree stays put while you experiment in the
-// worktrees, which are hook-dormant by construction — the untracked sidecar (D17)
-// doesn't exist in a fresh checkout, so the hooks find no STATE there.
-// `spike done` removes every spike worktree + branch and clears the marker.
+// `plumbbob spike` — the spike lifecycle for a genuine fork the design phase
+// couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree and a
+// `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default options
+// a/b) and drops the SPIKE marker — one of the untracked per-build control files
+// under `.plumbbob/` that record what's in flight. The main tree stays put while
+// you experiment in the worktrees, which are hook-dormant by construction: the
+// untracked control files don't exist in a fresh checkout, so the hooks find no
+// STATE (the session sentinel) there. `spike done` removes every spike worktree
+// and branch and clears the marker.
+//
+// Every spike also leaves a durable report — `spike-NN-<slug>.md` beside
+// intent.md in the tracked `builds/<slug>/` folder — so the verdict rides the
+// branch into the PR instead of evaporating with the throwaway worktrees.
 //
 // Worktree git calls run directly here rather than via lib/git.ts (which holds the
 // shared additive read/commit helpers): worktree management is spike-local, and
@@ -15,10 +21,19 @@ 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";
+// Worktree/branch names when the caller lists none — a fork defaults to two arms.
 const DEFAULT_OPTIONS = ['a', 'b'];
-// The verbatim Verdict placeholder from templates/spike-report.md — its presence means
-// the spike's call was never recorded, which `spike done` nudges on (D70).
+/**
+ * The verbatim Verdict placeholder from templates/spike-report.md — its presence
+ * means the spike's call was never recorded, which `spike done` nudges on.
+ */
 const VERDICT_PLACEHOLDER = '*(viable | not viable | partial';
+/**
+ * Entry point for `plumbbob spike` — dispatches to open, `report`, or `done`.
+ *
+ * Requires an active session (the STATE sentinel) and resolves which build the
+ * spike belongs to before dispatching.
+ */
 export function spike(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -35,11 +50,14 @@ export function spike(cwd, args) {
     }
     return spikeStart(root, buildSlug, positionals);
 }
-// `spike report "<slug>"` (D70) — scaffold a spike report WITHOUT worktrees, for the
-// spike-as-step case (a planned step titled `spike: …`, where the increment itself is
-// the experiment). No boundary requirement and no SPIKE marker: a step in flight is
-// exactly when this runs. Provenance is `step <n>` when a STEP is in flight, else
-// `/pb-spike`.
+/**
+ * `spike report "<slug>"` — scaffold a spike report WITHOUT worktrees.
+ *
+ * Serves the spike-as-step case: a planned step titled `spike: …`, where the
+ * increment itself is the experiment. No boundary requirement and no SPIKE
+ * marker — a step in flight is exactly when this runs. Provenance is stamped
+ * `step <n>` when a step is in flight, else `/plumbbob:spike`.
+ */
 function spikeReport(root, buildSlug, positionals) {
     const slug = sanitize(positionals[0] ?? '');
     if (slug.length === 0) {
@@ -47,23 +65,32 @@ function spikeReport(root, buildSlug, positionals) {
         return 1;
     }
     const inFlight = readInFlightStep(root, buildSlug);
-    const via = inFlight !== null ? `step ${inFlight}` : '/pb-spike';
+    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`);
     return 0;
 }
-// Write a fresh spike report from the template at the next free `spike-NN-<slug>.md`
-// in the build folder, and return its path. Shared by the explicit `/pb-spike` open
-// and the spike-as-step `spike report` — one artifact, two entry points (D70).
+/**
+ * Write a fresh spike report from the template at the next free
+ * `spike-NN-<slug>.md` in the build folder, and return its path.
+ *
+ * Shared by the worktree-opening spike and the spike-as-step `spike report` —
+ * one artifact, two entry points. The CLI owns the numbering; the human never
+ * creates or numbers a report.
+ */
 function scaffoldSpikeReport(root, buildSlug, spikeSlug, via) {
     const path = nextSpikeReportPath(root, buildSlug, spikeSlug);
     const date = new Date().toISOString().slice(0, 10);
     writeFileSync(path, stampTemplate(readTemplate('spike-report.md'), { TITLE: spikeSlug, VIA: via, DATE: date }));
     return path;
 }
-// The in-flight STEP number for the build, or null — reads the STEP marker `build`
-// writes. Used to stamp a spike-as-step report's provenance.
+/**
+ * The build's in-flight step number, or null — reads the STEP marker `build`
+ * writes.
+ *
+ * Used to stamp a spike-as-step report's provenance as `step <n>`.
+ */
 function readInFlightStep(root, buildSlug) {
     try {
         const raw = readFileSync(stepPath(root, buildSlug), 'utf8').trim();
@@ -73,6 +100,14 @@ function readInFlightStep(root, buildSlug) {
         return null;
     }
 }
+/**
+ * Open a spike: one throwaway worktree + `spike/<slug>-<opt>` branch per option.
+ *
+ * Refuses when a spike is already open or a step is in flight — a spike is a
+ * deliberate fork from a settled boundary, so the current step must checkpoint
+ * or revert first. Marks the SPIKE control file and scaffolds the report before
+ * returning.
+ */
 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');
@@ -101,20 +136,26 @@ function spikeStart(root, buildSlug, positionals) {
         created.push(path);
     }
     markSpike(root, buildSlug);
-    // Scaffold the report NOW, while the worktrees live (D70): findings accrue during the
+    // 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, `/pb-spike — worktrees (${options.join(', ')})`);
+    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`);
     return 0;
 }
+/**
+ * Close the spike: remove every spike worktree and branch, clear the marker.
+ *
+ * Nudges — but never refuses — when a report's Verdict is still the template
+ * placeholder: guidance, not a gate.
+ */
 function spikeDone(root, buildSlug) {
     if (!inSpike(root, buildSlug)) {
         process.stderr.write('plumbbob: no active spike to close.\n');
         return 1;
     }
-    // Check for an unrecorded verdict BEFORE teardown (D70). The reports live in the
+    // Check for an unrecorded verdict BEFORE teardown. The reports live in the
     // build folder, not the spike worktrees, so they survive the removal — but the
     // learning that fills them does not, so this is the moment to nudge.
     const unfilled = spikeReportsMissingVerdict(root, buildSlug);
@@ -126,8 +167,8 @@ function spikeDone(root, buildSlug) {
         git(root, ['branch', '-D', branch]);
     }
     clearSpike(root, buildSlug);
-    // Guidance, not a gate (the enforce→guide pivot): a missing verdict is a nudge, and
-    // the spike still closes. Name the reports so the human knows where to write it.
+    // 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`);
@@ -138,9 +179,13 @@ function spikeDone(root, buildSlug) {
         `Record the verdict (which option won, and why) in ${where} before you \`build\`.\n`);
     return 0;
 }
-// The spike-report filenames in the build folder whose Verdict is still the template
-// placeholder — the ones `spike done` nudges on. Best-effort per file: an unreadable
-// report is skipped rather than blocking the close.
+/**
+ * The spike-report filenames in the build folder whose Verdict is still the
+ * template placeholder — the ones `spike done` nudges on.
+ *
+ * Best-effort per file: an unreadable report is skipped rather than blocking
+ * the close.
+ */
 function spikeReportsMissingVerdict(root, buildSlug) {
     const dir = buildFolder(root, buildSlug);
     return listSpikeReports(root, buildSlug).filter((name) => {
@@ -152,8 +197,11 @@ function spikeReportsMissingVerdict(root, buildSlug) {
         }
     });
 }
-// Worktree paths whose checked-out branch is under spike/ — parsed from the
-// porcelain output (blank-line-separated `worktree <path>` / `branch <ref>` blocks).
+/**
+ * Worktree paths whose checked-out branch is under spike/ — parsed from the
+ * porcelain output (blank-line-separated `worktree <path>` / `branch <ref>`
+ * blocks).
+ */
 function spikeWorktrees(root) {
     const out = git(root, ['worktree', 'list', '--porcelain']);
     const paths = [];
@@ -168,16 +216,27 @@ function spikeWorktrees(root) {
     }
     return paths;
 }
+/**
+ * List the local `spike/<slug>` branch names.
+ */
 function spikeBranches(root) {
     const out = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/spike/']);
     return out.length === 0 ? [] : out.split('\n').filter((b) => b.length > 0);
 }
+/**
+ * Slugify a raw spike name — lowercase, non-alphanumerics collapsed to dashes.
+ */
 function sanitize(raw) {
     return raw
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+/**
+ * Run a git command at `root` and return its trimmed stdout.
+ *
+ * Stderr passes through to the terminal; a non-zero exit throws.
+ */
 function git(root, args) {
     return execFileSync('git', ['-C', root, ...args], {
         encoding: 'utf8',

package/dist/verbs/start.js

@@ -1,5 +1,8 @@
-// `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, open
-// the session. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
+// `plumbbob start "<title>"` — open a session: scaffold the sidecar (the
+// `.plumbbob/` tree of build artifacts and control files), record the baseline
+// commit, and point the session at a new build. Refuses on a dirty tree (a
+// clean baseline is the contract; `--allow-dirty` overrides), an existing
+// session, or a non-git directory.
 import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { detectGate } from "../lib/check.js";
@@ -7,10 +10,27 @@ import { readTemplate, stampTemplate } from "../lib/templates.js";
 import { findRepoRoot, hasCommit, headSha, isDirty } 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";
-// D24/D32: the gate is checkride unless a `check` setting overrides it, so
-// settings.json seeds with no `check` key at all — absence IS the default. The
-// templates' {{CHECK}} line is a human-readable echo of that.
+/**
+ * Human-readable echo of the default check gate, stamped into the templates'
+ * {{CHECK}} line.
+ *
+ * The gate is checkride unless a `check` setting overrides it, so settings.json
+ * seeds with no `check` key at all — absence IS the default; this line says
+ * that in prose where the templates need it.
+ */
 const CHECK_ECHO = 'checkride (set a "check" key in .plumbbob/settings.json to override)';
+/**
+ * Open a session: validate the repo, scaffold the build folder, record the
+ * baseline commit.
+ *
+ * Refuses without a title, outside a git repo, on a commitless repo, when a
+ * session is already active, and on a dirty tree (`--allow-dirty` records the
+ * current HEAD anyway, with a data-loss warning). The default layout is a
+ * tracked `.plumbbob/builds/<slug>/` folder that rides the branch into the PR;
+ * `--local` keeps the whole sidecar untracked for repos that won't carry tool
+ * folders. Ends with a plan-time probe of the check gate so an unconfigured
+ * repo hears about it while the human is still deciding.
+ */
 export async function start(cwd, args) {
     const positionals = args.filter((a) => !a.startsWith('--'));
     const allowDirty = args.includes('--allow-dirty');
@@ -51,25 +71,28 @@ export async function start(cwd, args) {
     }
     const sha = headSha(root);
     mkdirSync(sidecarDir(root), { recursive: true });
-    // beginSession writes STATE — the session sentinel and, in its content, the cursor
-    // (D28). Point it at this build (null under --local, which has no cursor). The
-    // cursor lives in STATE, not settings.local.json, so that overlay stays human-owned.
+    // beginSession writes STATE — one file that is both the session sentinel (its
+    // existence means a session is live) and the active-build cursor (its single
+    // line names the build every verb acts on). Point it at this build — null
+    // under --local, which has no cursor. The cursor lives in STATE, not
+    // settings.local.json, so that personal overlay stays purely human-owned.
     beginSession(root, local ? null : slug);
     // Scaffold the tracked settings.json ONLY when absent, and seed it EMPTY — the
     // human owns this file once it exists (their `check` gate lives here), so a
-    // re-start must never touch it. We inject no opinions even on first create:
-    // absence of `check` already means checkride and absence of `auto` already means
-    // false (see settings.ts), so `{}` is exactly "all defaults". `auto` in
-    // particular is a personal preference that belongs in settings.local.json, not
-    // this tracked file — seeding it here was the bug that clobbered custom checks.
+    // re-start must never touch it. Inject no opinions even on first create:
+    // absence of `check` already means checkride and absence of `auto` already
+    // means false (see settings.ts), so `{}` is exactly "all defaults". `auto` in
+    // particular is a personal preference that belongs in settings.local.json,
+    // never this tracked file.
     if (!existsSync(settingsPath(root))) {
         writeFileSync(settingsPath(root), `${JSON.stringify({}, null, 2)}\n`);
     }
-    // D26: `--local` keeps today's fully-untracked flat layout (whole `.plumbbob/`
-    // excluded); the default plants a tracked, PR-riding `builds/<slug>/` folder
-    // (D26) and points the per-worktree cursor at it (D28), excluding only control
-    // files (D17). The slug is date-prefixed when derived (see datedSlug) and
-    // validated unique above — the CLI refuses, never suffixes (D38).
+    // `--local` keeps a fully-untracked flat layout (the whole `.plumbbob/`
+    // git-excluded); the default plants a tracked `builds/<slug>/` folder — the
+    // build's record (intent, build-log, checkpoints) rides its branch into the
+    // PR — and git-excludes only the per-worktree control files. The slug is
+    // date-prefixed when derived (see datedSlug) and validated unique above —
+    // the CLI refuses a collision, never auto-suffixes.
     let intentLocation;
     if (local) {
         writeFileSync(checkpointsPath(root), `baseline ${sha}\n`);
@@ -87,20 +110,23 @@ export async function start(cwd, args) {
         excludeControl(root);
         intentLocation = `.plumbbob/builds/${slug}/intent.md`;
     }
-    // The plan's entry stamp (D64): `checkpoint --plan` latches on this tick. Skipped
-    // when TURN is absent — including the known first-session seam where the hook has
-    // never ticked, which leaves that one plan commit guidance-governed. Any grant
-    // lying around is a leftover from an earlier session (a legitimate one is minted
-    // by a `/pb-build` prompt, which never runs `start`) — clear it so a stale `auto`
-    // can't self-approve this session's plan (D65: one-turn lifetime).
+    // The plan's entry stamp for the checkpoint latch: set TICK to the current
+    // TURN, so `checkpoint --plan` only lands once the harness ledger records a
+    // human turn after this moment. Skipped when TURN is absent — a hookless host
+    // grows no ledger and the latch stays dormant, which also covers a first
+    // session where the hook has never ticked; that one plan commit stays
+    // guidance-governed. Any GRANT file lying around predates this session (a
+    // legitimate one is minted by a `/build` prompt, which never runs `start`)
+    // — clear it so a stale grant can't self-approve this session's plan; a
+    // 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 plan-time gate probe (research/07 Build 2a): if checkride sees no code
-    // checks here, say so NOW — while the human is still deciding — instead of at
-    // the first checkpoint, where the gate either refuses a vacuous run or, worse,
-    // greens on the always-on repo checks alone. Guidance only: never the exit
-    // code (C1), and a configured `check` or a probe hiccup stays silent.
+    // 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
+    // checkpoint, where the gate either refuses a vacuous run or, worse, greens
+    // on the always-on repo checks alone. Guidance only: it never changes the
+    // 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' +
@@ -109,11 +135,15 @@ export async function start(cwd, args) {
     }
     return 0;
 }
-// Derived slugs carry a `YYYY-MM-DD-` prefix (local time) so `builds/` sorts
-// chronologically under `listBuilds`' plain lexical sort — ordering by
-// construction, not by titling convention. An explicit `--slug` stays verbatim
-// (D38: the CLI never rewrites what the caller chose). An untitleable title
-// yields `''` so the empty-slug guard fires instead of minting a date-only slug.
+/**
+ * Derive a `YYYY-MM-DD-<slug>` build slug from the title (local time).
+ *
+ * The date prefix makes `builds/` sort chronologically under `listBuilds`'
+ * plain lexical sort — ordering by construction, not by titling convention. An
+ * explicit `--slug` bypasses this and stays verbatim — the CLI never rewrites
+ * what the caller chose. An untitleable title yields `''` so the empty-slug
+ * guard fires instead of minting a date-only slug.
+ */
 function datedSlug(title) {
     const base = slugify(title);
     if (base.length === 0)
@@ -122,14 +152,18 @@ function datedSlug(title) {
     const pad = (n) => String(n).padStart(2, '0');
     return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${base}`;
 }
-// Read the value that follows a `--flag` in argv (e.g. `--slug my-build`), or
-// undefined when the flag is absent or trails with no value.
+/**
+ * Read the value that follows a `--flag` in argv (e.g. `--slug my-build`), or
+ * undefined when the flag is absent or trails with no value.
+ */
 function flagValue(args, flag) {
     const i = args.indexOf(flag);
     return i >= 0 ? args[i + 1] : undefined;
 }
-// Stamp a build template's `{{TITLE}}`/`{{CHECK}}` — the check is always the echo
-// constant (absence of a `check` setting IS the default, D24/D32).
+/**
+ * Stamp a build template's `{{TITLE}}`/`{{CHECK}}` — the check is always the
+ * echo constant, since an absent `check` setting IS the checkride default.
+ */
 function stampBuild(template, title) {
     return stampTemplate(template, { TITLE: title, CHECK: CHECK_ECHO });
 }

package/dist/verbs/status.js

@@ -1,4 +1,7 @@
-// `plumbbob status` — the orientation dashboard (D8/D15), or NO ACTIVE SESSION.
+// `plumbbob status` — the orientation dashboard, or NO ACTIVE SESSION. It
+// parses the live session — intent.md, the build-log, the checkpoints ledger,
+// the in-flight STEP marker — into a where-am-I view that suggests one primary
+// next move while printing the full picture, so you can always override.
 // Read-only, always exits 0. Skills pre-inject this output to gate their own
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
 import { readFileSync } from 'node:fs';
@@ -7,6 +10,9 @@ import { commitsSince, findRepoRoot } from "../lib/git.js";
 import { SLOTS, readHarnessFile, resolveAgent, } from "../lib/agents.js";
 import { buildFolder, buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { formatOrientation, lastLedgerSha, orient } from "../lib/orient.js";
+/**
+ * Read a file as utf8, or '' when it is missing or unreadable.
+ */
 function readOr(path) {
     try {
         return readFileSync(path, 'utf8');
@@ -15,6 +21,13 @@ function readOr(path) {
         return '';
     }
 }
+/**
+ * Print the orientation dashboard for the active build, plus its harness bindings.
+ *
+ * No session prints the exact `NO ACTIVE SESSION` sentinel; a session with
+ * builds but no active one lists them and points at `use`. Always exits 0 —
+ * status is a report, never a gate.
+ */
 export function status(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -33,10 +46,11 @@ export function status(cwd, args = []) {
         }
     }
     const inFlightRaw = readOr(stepPath(root, slug)).trim();
-    // The out-of-band count (D66) needs git (orient is pure), so status measures it:
-    // commits on HEAD since the last ledger line's SHA — baseline, plan, or step, so
-    // a commit landing before the first step checkpoint still surfaces. No ledger yet
-    // ⇒ nothing to reconcile against ⇒ 0.
+    // Out-of-band commits — ones that landed outside the checkpoints ledger — are
+    // surfaced here, never blocked. Counting them needs git (orient is pure), so
+    // status measures it: commits on HEAD since the last ledger line's SHA —
+    // baseline, plan, or step, so a commit landing before the first step
+    // checkpoint still surfaces. No ledger yet ⇒ nothing to reconcile against ⇒ 0.
     const checkpoints = readOr(checkpointsPath(root, slug));
     const anchor = lastLedgerSha(checkpoints);
     const orientation = orient({
@@ -51,12 +65,18 @@ export function status(cwd, args = []) {
     process.stdout.write(`${lines.join('\n')}\n`);
     return 0;
 }
-// The active build's harness bindings (D48): the agents bound to each slot, per
-// `defaults` and per step, with a warning on any bound agent that does not resolve
-// (D54 — a teammate can lack a personal agent and the loop still works). Returns []
-// when the build has no harness.json (a clean no-op) or the file binds nothing, so
-// the dashboard stays uncluttered for builds that use no agents. A broken
-// harness.json surfaces its parse error rather than hiding.
+/**
+ * The active build's harness bindings: the agents bound to each slot, per
+ * `defaults` and per step.
+ *
+ * Bindings live in `builds/<slug>/harness.json` and status is the surface that
+ * reports them — no separate `agent check` verb. Any bound agent that does not
+ * resolve gets a warning, not an error: a teammate can lack a personal agent
+ * and the loop still works. Returns [] when the build has no harness.json (a
+ * clean no-op) or the file binds nothing, so the dashboard stays uncluttered
+ * for builds that use no agents. A broken harness.json surfaces its parse
+ * error rather than hiding.
+ */
 function harnessSection(root, slug) {
     const parsed = readHarnessFile(join(buildFolder(root, slug), 'harness.json'));
     if (parsed === null)
@@ -77,9 +97,12 @@ function harnessSection(root, slug) {
         return [];
     return ['', 'harness bindings:', ...rows, ...bindingWarnings(root, harness)];
 }
-// Render a SlotBindings as `slot: name1, name2` fragments, in slot order. A slot
-// bound to no agents (an explicit "override to none") is omitted — there is nothing
-// to run and nothing to name.
+/**
+ * Render a SlotBindings as `slot: name1, name2` fragments, in slot order.
+ *
+ * A slot bound to no agents (an explicit "override to none") is omitted —
+ * there is nothing to run and nothing to name.
+ */
 function slotFragments(bindings) {
     const out = [];
     for (const slot of SLOTS) {
@@ -89,9 +112,13 @@ function slotFragments(bindings) {
     }
     return out;
 }
-// A warning line for every distinct agent bound anywhere in the harness that does
-// not resolve (D54). Deduped and sorted so the report is stable; a name bound in
-// several slots warns once.
+/**
+ * A warning line for every distinct agent bound anywhere in the harness that
+ * does not resolve.
+ *
+ * Deduped and sorted so the report is stable; a name bound in several slots
+ * warns once.
+ */
 function bindingWarnings(root, harness) {
     const names = new Set();
     for (const slot of SLOTS)