mandrel 2.1.0 → 2.3.0

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -0,0 +1,315 @@
+/**
+ * lib/wave-runner/live-probe.js — the state-probing adapter that feeds the
+ * ready-set kernel from live GitHub state.
+ *
+ * `selectReadySet` (`./ready-set.js`) is deliberately a pure, side-effect-free
+ * kernel: callers hand it the live Story records, the done set, and the
+ * in-flight count, and it decides. Until now the only adapter was the
+ * flag-driven one (`stories-wave-tick.js --dag/--done/--in-flight`), which
+ * pushed the *gathering* of those inputs onto the caller — in practice onto
+ * the host LLM following `/deliver`'s prose, re-seeding `--done` and counting
+ * `--in-flight` by hand every beat. That is hand-maintained accounting on the
+ * one correctness-critical path where a mistake silently wedges a run (a
+ * dropped foreign blocker) or double-dispatches a Story (a miscounted slot).
+ *
+ * This module closes that gap by **probing** the same facts the host was
+ * transcribing:
+ *
+ *   - **done** — an `agent::done` label OR a closed issue, the same predicate
+ *     `classifyStory` already applies, evaluated over live state rather than a
+ *     `--done` CSV the caller maintained across beats. Foreign blockers
+ *     (outside the delivered set) are resolved too, which is what makes
+ *     cross-run delivery work: a blocker that merged weeks ago in another run
+ *     is simply done.
+ *   - **in-flight** — derived from live `agent::executing` / `agent::closing`
+ *     labels, **unioned with the ids the host says it has dispatched**
+ *     (`--dispatched`). The label alone is not sufficient: the kernel's
+ *     contract counts "executing / closing / dispatched-not-yet-labelled" as
+ *     in-flight, and `single-story-init.js` flips `agent::executing` at step 6
+ *     of 6 — *after* a 3–6 minute worktree install. For that whole window a
+ *     dispatched Story still reads `agent::ready`, so a label-only derivation
+ *     re-emits it in the next beat's `ready[]` and the host dispatches it a
+ *     second time onto the same branch and worktree (Story #4601).
+ *   - **blocked** — the ids carrying `agent::blocked`. `classifyStory` has
+ *     always returned this class; nothing consumed it, so a blocked Story was
+ *     neither done, ready, nor in-flight and the beat reported a permanent
+ *     "waiting" (Story #4601).
+ *
+ * It is an **adapter, not a kernel change**: it gathers inputs and hands them
+ * to `selectReadySet` unchanged. The kernel stays pure and flag-driven, and
+ * the legacy flag mode stays byte-compatible.
+ *
+ * The graph resolution is **not** reimplemented here — it reuses
+ * `resolve-stories.js`'s machinery wholesale (body `depends_on` ∪ native
+ * `blocked_by` edges, foreign-blocker resolution, `files[]` footprints), so
+ * the probe and `/deliver`'s step-1 resolution cannot disagree about what
+ * depends on what.
+ *
+ * @module lib/wave-runner/live-probe
+ */
+
+import {
+  fetchStories,
+  readNativeEdges,
+  resolveForeignDone,
+  resolveStoriesProvider,
+} from '../../resolve-stories.js';
+import { AGENT_LABELS } from '../label-constants.js';
+import { buildStoriesEnvelope } from '../orchestration/resolve-stories.js';
+import { classifyStory, storyIdOf } from './ready-set.js';
+
+/**
+ * Identify the Stories that currently occupy a dispatch slot, as an id set.
+ *
+ * Two sources, unioned — which is exactly the kernel's stated contract
+ * ("executing / closing / dispatched-not-yet-labelled"):
+ *
+ *   1. **Live labels.** `classifyStory` folds `agent::executing` and
+ *      `agent::closing` into one `executing` class — both are in-flight and
+ *      neither may be re-dispatched.
+ *   2. **`dispatched`** — ids the host has spawned. This closes the init
+ *      window: `single-story-init.js` flips `agent::executing` last, after a
+ *      3–6 minute install, so between spawn and flip a dispatched Story reads
+ *      `agent::ready` and a label-only derivation hands it back as ready.
+ *
+ * `dispatched` is deliberately **not** the `--done`-style accounting probe
+ * mode retired. Three properties keep it from becoming one:
+ *
+ *   - **It is a set union, not a counter.** Re-passing an id that has since
+ *     picked up its `agent::executing` label cannot double-count a slot.
+ *   - **Live state overrules the claim.** An id the host still lists but that
+ *     now classifies `done` (or `blocked`) is dropped, so a stale entry can
+ *     never occupy a slot forever and starve the run.
+ *   - **Therefore the host's correct strategy is monotonic append**: pass
+ *     every id you have dispatched this run and never reason about removing
+ *     one. There is no drop-a-slot decision to get wrong — the probe subtracts
+ *     reality from the claim. Forgetting an id degrades to the pre-#4601
+ *     behaviour rather than to something worse.
+ *
+ * Ids outside the probed set are ignored: they are not part of this run and
+ * must not consume its cap.
+ *
+ * @param {Array<{id?: number, number?: number, labels?: string[], state?: string}>} storyRecords
+ * @param {Iterable<number>} [dispatched] Ids the host has spawned.
+ * @returns {Set<number>} In-flight Story ids.
+ */
+function deriveInFlightIds(storyRecords, dispatched = []) {
+  const claimed = new Set(dispatched);
+  const inFlight = new Set();
+  for (const rec of storyRecords) {
+    const id = storyIdOf(rec);
+    if (id === null) continue;
+    const cls = classifyStory(rec);
+    if (cls === 'executing' || (claimed.has(id) && cls === 'ready')) {
+      inFlight.add(id);
+    }
+  }
+  return inFlight;
+}
+
+/**
+ * The ids carrying `agent::blocked`.
+ *
+ * `classifyStory` has always returned a `blocked` class, but no adapter
+ * consumed it: a blocked Story was never done, never ready, and never counted
+ * in-flight, so `detectWedge` dropped it (its "undone work with no unmet
+ * blockers would have been dispatched" invariant is precisely what probe mode
+ * broke) and the beat reported exit 0 / `ready: []` / `wedged: null` forever.
+ * `/deliver` reads that as "waiting", so the `agent::blocked` HITL pause — the
+ * one runtime gate in the protocol — was never surfaced to the operator.
+ *
+ * @param {Array<{id?: number, number?: number, labels?: string[], state?: string}>} storyRecords
+ * @returns {number[]} Blocked Story ids, ascending.
+ */
+function deriveBlockedIds(storyRecords) {
+  return storyRecords
+    .filter((rec) => classifyStory(rec) === 'blocked')
+    .map((rec) => storyIdOf(rec))
+    .filter((id) => id !== null)
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Resolve the provider + repo coordinates the probe reads through.
+ *
+ * Shares `resolve-stories.js`'s provider seam, so probe mode authenticates and
+ * targets exactly the same repo `/deliver`'s resolution step does. Tests
+ * inject a stub provider instead of calling this.
+ *
+ * @param {object} [deps]
+ * @param {Function} [deps.resolveProvider] Injection seam for tests.
+ * @returns {{ provider: object, owner: string|undefined, repo: string|undefined }}
+ */
+export function createProbeContext({
+  resolveProvider = resolveStoriesProvider,
+} = {}) {
+  const { provider, config } = resolveProvider();
+  return { provider, owner: config?.github?.owner, repo: config?.github?.repo };
+}
+
+/**
+ * Probe live state for a set of Story ids and return the exact inputs
+ * `selectReadySet` consumes.
+ *
+ * Mirrors `resolve-stories.js`'s two-pass envelope build: a provisional pass
+ * yields the DAG whose foreign dependency ids are then resolved against live
+ * issue state, and the second pass folds those satisfied foreign blockers into
+ * `done[]`. Skipping that pass would withhold any Story whose blocker landed
+ * outside the delivered set — the cross-run wedge the resolver exists to fix.
+ *
+ * @param {object} args
+ * @param {number[]} args.ids            Story ids in the run.
+ * @param {object} args.provider         GitHub provider (stubbed in tests).
+ * @param {string} [args.owner]
+ * @param {string} [args.repo]
+ * @param {boolean} [args.native=true]   Read native `blocked_by` edges.
+ * @param {number[]} [args.dispatched=[]] Ids the host has spawned but may not
+ *   yet have observed labelled `agent::executing` (see `deriveInFlightIds`).
+ * @param {(msg: string) => void} [args.warn]
+ * Each returned node carries its **live labels**. That is load-bearing, not
+ * decoration: `selectReadySet` classifies from labels, so a node stripped of
+ * them reads as `ready` and an `agent::executing` Story gets re-dispatched
+ * onto a second branch while its first run is still going. The resolver's DAG
+ * projection (`{id, dependsOn, files}`) drops labels because flag mode's
+ * caller tracked in-flight itself; probe mode must put them back.
+ *
+ * @returns {Promise<{
+ *   nodes: Array<{id: number, dependsOn: number[], files: string[], labels: string[]}>,
+ *   doneIds: Set<number>,
+ *   inFlight: number,
+ *   blockedIds: number[]
+ * }>}
+ */
+export async function probeLiveState({
+  ids,
+  provider,
+  owner,
+  repo,
+  native = true,
+  dispatched = [],
+  warn,
+}) {
+  const stories = await fetchStories(provider, ids);
+  const nativeEdges = native
+    ? await readNativeEdges({ provider, stories, owner, repo })
+    : new Map();
+
+  const provisional = buildStoriesEnvelope({ stories, nativeEdges, warn });
+  const foreignDone = await resolveForeignDone({
+    provider,
+    dag: provisional.dag,
+    inSetIds: new Set(stories.map((s) => s.id)),
+  });
+  const envelope = buildStoriesEnvelope({
+    stories,
+    nativeEdges,
+    foreignDone,
+    warn: () => {},
+  });
+
+  const labelsById = new Map(stories.map((s) => [s.id, s.labels ?? []]));
+  const inFlightIds = deriveInFlightIds(stories, dispatched);
+  return {
+    nodes: envelope.dag.map((node) => ({
+      ...node,
+      labels: projectInFlightLabels(
+        labelsById.get(node.id) ?? [],
+        inFlightIds.has(node.id),
+      ),
+    })),
+    doneIds: new Set(envelope.done),
+    inFlight: inFlightIds.size,
+    blockedIds: deriveBlockedIds(stories),
+  };
+}
+
+/**
+ * Project the in-flight fact onto a node's labels, synthesizing
+ * `agent::executing` for a Story that is dispatched but not yet labelled.
+ *
+ * This is the load-bearing half of the dispatch-window fix, and it is why
+ * `inFlight` alone is not enough. The two inputs do **different** jobs inside
+ * `selectReadySet`:
+ *
+ *   - `inFlight` is only a **count**. It reserves capacity (`slots = cap −
+ *     inFlight`) and nothing more.
+ *   - **Eligibility is decided per-record by `classifyStory`**, from labels.
+ *
+ * So a dispatched-but-unlabelled Story counted only via `inFlight` still
+ * classifies `ready`, stays eligible, and — whenever a slot remains — is
+ * admitted to the very same beat that reserved a slot for it. It would be
+ * re-dispatched onto its own live branch, with the miscount merely reshaped
+ * rather than fixed. Handing the kernel the label makes it apply the rule it
+ * already has, and keeps the kernel itself untouched: the adapter's job is to
+ * supply the input the kernel's contract ("executing / closing / dispatched-
+ * not-yet-labelled") already specifies.
+ *
+ * @param {string[]} labels    The Story's live labels.
+ * @param {boolean} inFlight   Whether the Story occupies a dispatch slot.
+ * @returns {string[]} Labels, with `agent::executing` added when needed.
+ */
+function projectInFlightLabels(labels, inFlight) {
+  if (!inFlight || classifyStory({ labels }) === 'executing') return labels;
+  return [...labels, AGENT_LABELS.EXECUTING];
+}
+
+/**
+ * Validate the mode-selecting flags, keeping probe mode and the legacy
+ * flag mode mutually exclusive.
+ *
+ * The exclusion is not pedantry: `--probe-live` derives `done` and `in-flight`
+ * from live state, so honouring a caller-supplied `--done` alongside it would
+ * silently reintroduce the hand-maintained accounting probe mode exists to
+ * retire — and quietly disagree with reality when the two differ.
+ *
+ * `--dispatched` is the deliberate exception, and it is **additive rather than
+ * authoritative**: it does not replace the derived in-flight set, it is unioned
+ * into it and then filtered by live state (see `deriveInFlightIds`). It carries
+ * the one fact the host knows and GitHub does not yet — "I spawned this id, the
+ * label has not appeared yet" — so it cannot disagree with reality the way an
+ * authoritative `--in-flight <n>` could. `--in-flight` therefore stays excluded.
+ *
+ * @param {object} flags
+ * @param {boolean} [flags.probeLive]
+ * @param {string} [flags.stories]
+ * @param {string} [flags.dag]
+ * @param {string} [flags.dagFile]
+ * @param {string} [flags.done]
+ * @param {string} [flags.inFlight]
+ * @param {string} [flags.dispatched]
+ * @returns {string|null} An error message, or `null` when the flags are valid.
+ */
+export function validateProbeFlags({
+  probeLive,
+  stories,
+  dag,
+  dagFile,
+  done,
+  inFlight,
+  dispatched,
+} = {}) {
+  if (!probeLive) {
+    if (dispatched != null) {
+      return '--dispatched requires --probe-live (it augments the live-derived in-flight set; flag mode uses --in-flight <n>)';
+    }
+    return stories
+      ? '--stories requires --probe-live (it names the run to probe from live state)'
+      : null;
+  }
+  const conflicting = [
+    dag ? '--dag' : null,
+    dagFile ? '--dag-file' : null,
+    done != null ? '--done' : null,
+    inFlight != null ? '--in-flight' : null,
+  ].filter(Boolean);
+  if (conflicting.length > 0) {
+    return (
+      `--probe-live is mutually exclusive with ${conflicting.join(', ')}: it resolves the graph ` +
+      `and derives done / in-flight from live state. Drop the flag(s), or use the legacy flag mode.`
+    );
+  }
+  if (!stories) {
+    return '--probe-live requires --stories <csv> of Story ids';
+  }
+  return null;
+}

package/.agents/scripts/plan-context.js

@@ -205,7 +205,6 @@ async function main() {
     {
       cli: 'plan-context',
       mode,
-      epicId: null,
       config,
     },
     () =>

package/.agents/scripts/plan-critics.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/**
+ * plan-critics.js — the /plan critic-dispatch verdict CLI (Story #4592).
+ *
+ * `/plan` step 2.5 (between Author and Persist) runs this against the draft
+ * `stories.json`. It evaluates the consolidation + pre-mortem dispatch
+ * conditions and prints the verdict as JSON on stdout so the workflow can
+ * act on it — dispatching a fresh-context critic sub-agent and folding its
+ * findings into a re-author round **before** the plan is persisted.
+ *
+ * Why here and nowhere else. The evaluation used to run inside
+ * `run-plan-persist.js`, after authoring was finished and immediately before
+ * `createStoryIssues` — the one point in the flow where nothing can act on a
+ * `dispatch: true` verdict, because the artifacts are about to become live
+ * issues. It logged the verdict and moved on. This CLI is now the **single**
+ * evaluation point, sited where a re-author loop actually exists.
+ *
+ * Advisory by contract: a `dispatch: true` verdict routes work to the
+ * workflow, it does not gate the run. This CLI exits 0 on any verdict; only a
+ * usage/IO error is a failure. Every `dispatch: false` decision is recorded to
+ * the plan-metrics ledger (`appendCriticSkip`) so under-firing stays auditable.
+ *
+ * CLI:
+ *   --stories <file>     Required. The draft Story ticket array (JSON).
+ *   --tech-spec <file>   Optional. Shared Tech Spec carrying the
+ *                        `## Delivery Slicing` table the consolidation
+ *                        precondition reads.
+ *
+ * stdout is reserved for the verdict JSON (Story #2278 discipline):
+ *
+ *   {
+ *     "consolidation": { "critic": "consolidation", "dispatch": false, "reasons": [...] },
+ *     "premortem":     { "critic": "pre-mortem",    "dispatch": true,  "reasons": [...] },
+ *     "textHygiene":   { "critic": "text-hygiene",  "findings": [...] }
+ *   }
+ *
+ * `textHygiene` (Story #4599) is advisory-only: deterministic body lints with
+ * no dispatch semantics — its findings fold into the re-author round.
+ *
+ * Human-readable log lines go to stderr, matching the sibling `plan-persist`.
+ *
+ * Exit codes: 0 success (any verdict); 1 usage/IO error.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { evaluatePlanCritics } from './lib/orchestration/plan-critics-evaluate.js';
+import { appendCriticSkip } from './lib/orchestration/plan-metrics.js';
+
+const CLI_OPTIONS = {
+  stories: { type: 'string' },
+  'tech-spec': { type: 'string' },
+};
+
+const USAGE = 'Usage: plan-critics.js --stories <file> [--tech-spec <file>]';
+
+/** The `cli` discriminator every ledger record from this surface carries. */
+export const PLAN_CRITICS_CLI = 'plan-critics';
+
+/**
+ * Read the draft artifacts the critics evaluate.
+ *
+ * @param {{ storiesPath: string, techSpecPath?: string|null }} paths
+ * @returns {Promise<{ tickets: object[], techSpecContent: string }>}
+ */
+export async function loadCriticArtifacts({
+  storiesPath,
+  techSpecPath = null,
+}) {
+  const raw = await readFile(storiesPath, 'utf8');
+  let tickets;
+  try {
+    tickets = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse stories file "${storiesPath}" as JSON: ${err.message}`,
+    );
+  }
+  if (!Array.isArray(tickets)) {
+    throw new Error(`Stories file "${storiesPath}" must contain a JSON array.`);
+  }
+  const techSpecContent = techSpecPath
+    ? await readFile(techSpecPath, 'utf8')
+    : '';
+  return { tickets, techSpecContent };
+}
+
+/**
+ * Log each decision and record every skip on the plan-metrics ledger. The
+ * ledger write is best-effort by `appendCriticSkip`'s own contract — it can
+ * never fail the plan step.
+ *
+ * @param {{ consolidation: object, premortem: object, textHygiene?: object }} verdict
+ * @param {object} config
+ * @param {{ append?: typeof appendCriticSkip }} [deps]
+ * @returns {Promise<void>}
+ */
+export async function recordCriticSkips(
+  verdict,
+  config,
+  { append = appendCriticSkip } = {},
+) {
+  for (const decision of [verdict.consolidation, verdict.premortem]) {
+    Logger.info(
+      `[plan-critics] critic ${decision.critic}: ` +
+        `${decision.dispatch ? 'dispatch' : 'skip'} — ` +
+        decision.reasons.join('; '),
+    );
+    if (!decision.dispatch) {
+      await append(
+        {
+          critic: decision.critic,
+          reasons: decision.reasons,
+          cli: PLAN_CRITICS_CLI,
+        },
+        config,
+      );
+    }
+  }
+
+  // Text hygiene (Story #4599) is advisory-only — no dispatch semantics, so
+  // "skip" here means "zero findings". Recording that keeps the lint's
+  // fire/skip accounting on the same ledger as the dispatching critics.
+  const hygiene = verdict.textHygiene;
+  if (hygiene) {
+    const count = hygiene.findings.length;
+    Logger.info(
+      `[plan-critics] critic ${hygiene.critic}: ${count} finding(s) (advisory).`,
+    );
+    if (count === 0) {
+      await append(
+        {
+          critic: hygiene.critic,
+          reasons: ['No text-hygiene findings over the draft stories.'],
+          cli: PLAN_CRITICS_CLI,
+        },
+        config,
+      );
+    }
+  }
+}
+
+/**
+ * Load the artifacts, evaluate both critics, record the skips, and return the
+ * verdict. Exported as the CLI's whole body so tests drive it in-process with
+ * an explicit config and ledger seam.
+ *
+ * @param {{
+ *   storiesPath: string,
+ *   techSpecPath?: string|null,
+ *   config?: object,
+ *   append?: typeof appendCriticSkip,
+ * }} args
+ * @returns {Promise<{ consolidation: object, premortem: object, textHygiene: object }>}
+ */
+export async function evaluateCriticArtifacts({
+  storiesPath,
+  techSpecPath = null,
+  config = {},
+  append = appendCriticSkip,
+}) {
+  const { tickets, techSpecContent } = await loadCriticArtifacts({
+    storiesPath,
+    techSpecPath,
+  });
+  const verdict = evaluatePlanCritics({ techSpecContent, tickets, config });
+  await recordCriticSkips(verdict, config, { append });
+  return verdict;
+}
+
+async function main() {
+  const { values } = parseArgs({ options: CLI_OPTIONS });
+
+  if (!values.stories) {
+    throw new Error(USAGE);
+  }
+
+  // stdout is reserved for the verdict JSON — flip every Logger sink that
+  // could land on stdout to stderr before any evaluation runs.
+  routeAllOutputToStderr();
+
+  const verdict = await evaluateCriticArtifacts({
+    storiesPath: path.resolve(values.stories),
+    techSpecPath: values['tech-spec']
+      ? path.resolve(values['tech-spec'])
+      : null,
+    config: resolveConfig(),
+  });
+
+  process.stdout.write(`${JSON.stringify(verdict, null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'plan-critics',
+  propagateExitCode: true,
+});

package/.agents/scripts/quality-preview.js

@@ -35,18 +35,25 @@ import {
  * present without a value. Returns `null` when the flag is absent so callers
  * can fall through to the gate scripts' own diff defaults.
  *
+ * **Last occurrence wins** (Story #4603). `npm run <alias> -- --changed-since <base>`
+ * appends the operator's flag *after* any flag baked into the npm script, so a
+ * first-wins scan silently discarded the operator's base and compared against
+ * the script's hardcoded one instead — reporting a false green for a branch the
+ * gate had never actually scored. Last-wins matches the convention every
+ * mainstream CLI parser follows for repeated scalar flags, and makes the
+ * npm-alias passthrough behave the way its callers already assume.
+ *
  * @param {string[]} argv
  * @returns {string | null}
  */
 export function parseChangedSinceArg(argv) {
+  let resolved = null;
   for (let i = 0; i < argv.length; i += 1) {
-    if (argv[i] === '--changed-since') {
-      const next = argv[i + 1];
-      if (next && !next.startsWith('--')) return next;
-      return 'HEAD';
-    }
+    if (argv[i] !== '--changed-since') continue;
+    const next = argv[i + 1];
+    resolved = next && !next.startsWith('--') ? next : 'HEAD';
   }
-  return null;
+  return resolved;
 }
 
 /**