mandrel 2.0.0 → 2.1.0

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

@@ -4,27 +4,51 @@
  * plan-persist.js — flat Story GitHub-write surface for v2 `/plan`
  * (Stage 3 — `docs/roadmap.md`).
  *
- * Given the author-written planning artifacts (`stories.json` +
- * `risk-verdict.json`, optional shared Tech Spec), this CLI validates and
- * creates Story issue(s) directly:
+ * Given the author-written planning artifacts (`stories.json`, optional shared
+ * Tech Spec), this CLI validates and creates Story issue(s) directly:
  *
- *   risk-verdict → ticket validator / DAG / capacity → reachability →
+ *   ticket validator / DAG / capacity → reachability →
  *   split-policy partition → fold/spill Spec into each Story body →
- *   createIssue(s) with type::story + agent::ready → risk-verdict +
- *   story-plan-state on every Story; plan-summary on the primary → temp
- *   cleanup.
+ *   createIssue(s) with type::story, resumably by plan fingerprint (NOT
+ *   agent::ready) → story-plan-state on every Story;
+ *   plan-summary on the primary → flip every Story to agent::ready →
+ *   comment + close superseded source tickets → temp cleanup + stale reap.
+ *
+ * Story #4542 retired the authored risk verdict: persist neither requires nor
+ * accepts one, and no plan-time step produces one. Review depth and the
+ * acceptance-critic mode are derived from the diff at close time
+ * (`review-depth.js#deriveChangeLevel`). `--force-review` is the only review
+ * gate the planner still carries, and it is an explicit operator flag.
  *
  * CLI:
- *   --stories <file>         Required Story ticket array (default length 1)
- *   --risk-verdict <file>    Required risk verdict (no deliveryShape)
- *   --tech-spec <file>       Optional shared Tech Spec folded into each Story
- *   --plan-dir <dir>         Optional temp dir deleted at terminal success
- *   --plan-acceptance <file> Optional JSON string[] for partition coverage
- *   --plan-run-id <id>       Optional plan-run token when N>1
- *   --dry-run                Assemble + validate without GitHub writes
- *   --force-review           Record operator-forced review routing
+ *   --stories <file>          Required Story ticket array (default length 1)
+ *   --tech-spec <file>        Optional shared Tech Spec folded into each Story
+ *   --plan-dir <dir>          Optional temp dir deleted at terminal success.
+ *                             Also where the `plan-context.json` envelope is
+ *                             auto-discovered from (see --plan-context)
+ *   --plan-context <file>     Optional explicit path to the `plan-context.js`
+ *                             envelope. Its `sourceTickets[]` is what makes
+ *                             `--tickets` superseding work without a flag
+ *   --plan-acceptance <file>  Optional JSON string[] for partition coverage
+ *   --source-tickets <ids>    Explicit OVERRIDE of the envelope-derived source
+ *                             ids, for hand-driven runs. Each id must be
+ *                             claimed by exactly one Story's `supersedes[]`;
+ *                             they are commented on and closed as superseded
+ *   --no-close-superseded     Keep the source tickets open (no comment, no
+ *                             close) — for a genuinely partial supersede
+ *   --dry-run                 Assemble + validate without GitHub writes
+ *   --force-review            Operator-forced review stop before persist lands
  *   --allow-over-budget / --allow-large-fan-out
  *
+ * Run `--dry-run` first. It exercises every gate — validator, DAG, capacity,
+ * budget, reachability, split/supersede partition, Spec fold — write-free, so
+ * an authoring mistake surfaces before a single issue exists.
+ *
+ * stdout is reserved for the JSON result (Story #2278 discipline, extended to
+ * this CLI by Story #4541): `routeAllOutputToStderr()` runs before any
+ * pipeline code so a headless driver can `JSON.parse` stdout unconditionally.
+ * Human-readable log lines go to stderr, matching the sibling `plan-context`.
+ *
  * Exit codes: 0 success; 1 fatal; 3 reachability orphans (nothing mutated).
  */
 
@@ -38,13 +62,17 @@ import {
   resolveConfig,
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
-import { Logger } from './lib/Logger.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
 import {
   readPlanMetrics,
   recordPlanInvocation,
   renderPlanMetricsSummaryLine,
   summarizePlanMetrics,
 } from './lib/orchestration/plan-metrics.js';
+import {
+  loadPlanContextEnvelope,
+  resolvePlanContextPath,
+} from './lib/orchestration/plan-persist/plan-context-source.js';
 import {
   runPlanPersist,
   writeCheckpointV2,
@@ -54,7 +82,7 @@ import {
   buildWaveTable,
   PLAN_SUMMARY_COMMENT_TYPE,
 } from './lib/orchestration/plan-persist/summary.js';
-import { loadRiskVerdict } from './lib/orchestration/planning/risk-verdict.js';
+import { resolveSourceTicketIds } from './lib/orchestration/plan-persist/supersede-ops.js';
 import { createProvider } from './lib/provider-factory.js';
 
 export {
@@ -67,11 +95,13 @@ export {
 
 const CLI_OPTIONS = {
   stories: { type: 'string' },
-  'risk-verdict': { type: 'string' },
   'tech-spec': { type: 'string' },
   'plan-dir': { type: 'string' },
+  'plan-context': { type: 'string' },
   'plan-acceptance': { type: 'string' },
-  'plan-run-id': { type: 'string' },
+  'source-tickets': { type: 'string' },
+  'close-superseded': { type: 'boolean', default: true },
+  'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
   'force-review': { type: 'boolean', default: false },
   'allow-over-budget': { type: 'boolean', default: false },
@@ -79,9 +109,11 @@ const CLI_OPTIONS = {
 };
 
 const USAGE =
-  'Usage: plan-persist.js --stories <file> --risk-verdict <file> ' +
-  '[--tech-spec <file>] [--plan-dir <dir>] [--plan-acceptance <file>] ' +
-  '[--plan-run-id <id>] [--dry-run] [--force-review] ' +
+  'Usage: plan-persist.js --stories <file> ' +
+  '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
+  '[--plan-acceptance <file>] ' +
+  '[--source-tickets <ids>] [--no-close-superseded] ' +
+  '[--dry-run] [--force-review] ' +
   '[--allow-over-budget] [--allow-large-fan-out]';
 
 async function readOptional(filePath, { required }) {
@@ -104,22 +136,28 @@ async function readJsonFile(filePath, label) {
   }
 }
 
-function resolveInputPaths(values) {
+/**
+ * Resolve every input path the CLI accepts, including where the
+ * `plan-context.js` envelope is discovered from. Exported for tests.
+ *
+ * @param {object} values Parsed `parseArgs` values.
+ */
+export function resolveInputPaths(values) {
+  const planDir = values['plan-dir'] ? path.resolve(values['plan-dir']) : null;
   return {
     storiesPath: path.resolve(values.stories),
-    riskVerdictPath: path.resolve(values['risk-verdict']),
     techSpecPath: values['tech-spec']
       ? path.resolve(values['tech-spec'])
       : null,
     planAcceptancePath: values['plan-acceptance']
       ? path.resolve(values['plan-acceptance'])
       : null,
-    planDir: values['plan-dir'] ? path.resolve(values['plan-dir']) : null,
+    planDir,
+    planContextPath: resolvePlanContextPath(values['plan-context'], planDir),
   };
 }
 
 async function loadArtifacts(paths) {
-  const riskVerdict = loadRiskVerdict(paths.riskVerdictPath);
   const stories = await readJsonFile(paths.storiesPath, 'stories');
   const techSpecContent = paths.techSpecPath
     ? await readOptional(paths.techSpecPath, { required: true })
@@ -127,23 +165,61 @@ async function loadArtifacts(paths) {
   const planAcceptance = paths.planAcceptancePath
     ? await readJsonFile(paths.planAcceptancePath, 'plan-acceptance')
     : null;
+  const planContextEnvelope = await loadPlanContextEnvelope(
+    paths.planContextPath,
+  );
 
-  return { stories, riskVerdict, techSpecContent, planAcceptance };
+  return {
+    stories,
+    techSpecContent,
+    planAcceptance,
+    planContextEnvelope,
+  };
 }
 
-function buildPersistOptions(values, paths) {
+/**
+ * Assemble the `runPlanPersist` opts bag from parsed CLI values.
+ *
+ * Exported for tests: this is the join where the envelope-derived source ids
+ * meet the persist engine, so a regression here silently un-wires
+ * `/plan --tickets` superseding (Story #4554).
+ *
+ * @param {object} values Parsed `parseArgs` values.
+ * @param {ReturnType<typeof resolveInputPaths>} paths
+ * @param {object|null} planContextEnvelope
+ * @returns {object} opts for `runPlanPersist`.
+ */
+export function buildPersistOptions(values, paths, planContextEnvelope) {
+  const source = resolveSourceTicketIds({
+    explicitIds: values['source-tickets'],
+    envelope: planContextEnvelope,
+  });
+
   return {
     forceReview: values['force-review'],
     allowOverBudget: values['allow-over-budget'],
     allowLargeFanOut: values['allow-large-fan-out'],
     dryRun: values['dry-run'],
-    planRunId: values['plan-run-id'],
     planDir: paths.planDir,
     skipCleanup: values['dry-run'],
+    sourceTicketIds: source.ids,
+    sourceTicketOrigin: source.origin,
+    // Default-on: `--no-close-superseded` is the explicit escape and always
+    // wins over the (default `true`) `--close-superseded`.
+    closeSuperseded:
+      values['no-close-superseded'] === true
+        ? false
+        : values['close-superseded'] !== false,
   };
 }
 
-async function runPersistInvocation({ values, config, provider, artifacts }) {
+async function runPersistInvocation({
+  values,
+  config,
+  provider,
+  artifacts,
+  metricsSince,
+}) {
   const paths = resolveInputPaths(values);
   const settings = {
     baseBranch: config.project?.baseBranch,
@@ -164,14 +240,37 @@ async function runPersistInvocation({ values, config, provider, artifacts }) {
         artifacts,
         config,
         settings,
-        opts: buildPersistOptions(values, paths),
+        opts: {
+          ...buildPersistOptions(values, paths, artifacts.planContextEnvelope),
+          metricsSince,
+        },
       }),
   );
 }
 
-async function attachPlanMetrics(result, config) {
+/**
+ * Attach the plan-metrics roll-up for **this** invocation.
+ *
+ * Two Story #4541 fixes meet here. `readPlanMetrics` is declared
+ * `(epicId, config)` but was called with `config` first, so it threw its
+ * `epicId` guard on every run and the catch below turned that into a
+ * silently missing summary — v2 persist is always Epic-less, hence the
+ * explicit `null`. And the Epic-less ledger is shared across every plan the
+ * repo has ever run, so `since` scopes the counts to the current invocation
+ * instead of reporting lifetime totals under an invocation-shaped line.
+ *
+ * This runs *after* `recordPlanInvocation` has appended this run's own
+ * record, so the summary always has at least that one entry to report.
+ *
+ * @param {object} result Mutated in place with `planMetrics`.
+ * @param {object} config
+ * @param {string} since ISO-8601 instant this invocation started.
+ */
+async function attachPlanMetrics(result, config, since) {
   try {
-    const summary = summarizePlanMetrics(await readPlanMetrics(config));
+    const summary = summarizePlanMetrics(await readPlanMetrics(null, config), {
+      since,
+    });
     if (summary) {
       result.planMetrics = summary;
       Logger.info(`[plan-persist] ${renderPlanMetricsSummaryLine(summary)}`);
@@ -184,10 +283,20 @@ async function attachPlanMetrics(result, config) {
 async function main() {
   const { values } = parseArgs({ options: CLI_OPTIONS });
 
-  if (!values.stories || !values['risk-verdict']) {
+  if (!values.stories) {
     throw new Error(USAGE);
   }
 
+  // stdout is reserved for the JSON result: flip every Logger sink that could
+  // land on stdout to stderr BEFORE any pipeline code runs (Story #2278
+  // discipline, extended here by Story #4541 — this CLI interleaved Logger
+  // lines with its own JSON, so a headless driver could not parse stdout).
+  routeAllOutputToStderr();
+
+  // Boundary for this invocation's plan-metrics roll-up — stamped before any
+  // ledger-writing work so every record this run appends falls inside it.
+  const metricsSince = new Date().toISOString();
+
   let config;
   try {
     config = resolveConfig();
@@ -206,6 +315,7 @@ async function main() {
       config,
       provider,
       artifacts,
+      metricsSince,
     });
   } catch (err) {
     if (err?.code === 'PLAN_REACHABILITY_ORPHANS') {
@@ -216,7 +326,7 @@ async function main() {
     throw err;
   }
 
-  await attachPlanMetrics(result, config);
+  await attachPlanMetrics(result, config, metricsSince);
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }

package/.agents/scripts/plan-run-epilogue.js

@@ -1,17 +1,14 @@
 #!/usr/bin/env node
 /**
- * plan-run-epilogue.js — execute the real per-run closeout for
- * `/deliver --run <planRunId>` and positional multi-Story delivers.
+ * plan-run-epilogue.js — execute the real per-run closeout for a
+ * multi-Story `/deliver`.
  *
  * Usage:
- *   node .agents/scripts/plan-run-epilogue.js --run <planRunId>
- *   node .agents/scripts/plan-run-epilogue.js --run <planRunId> --stories 1,2,3
  *   node .agents/scripts/plan-run-epilogue.js --stories 1,2,3
  *
- * When `--stories` is omitted, `--run` is required and the set is resolved
- * via plan-run labels (`state=all` so landed Stories are included).
- * When `--stories` is supplied without `--run`, an adhoc planRunId is
- * synthesized from the sorted Story ids.
+ * Keyed on the delivered id set: an `adhoc-<sorted-ids>` run id is
+ * synthesized from `--stories`. Story #4540 retired the `--run <planRunId>`
+ * label-resolution branch along with the `plan-run::<id>` label itself.
  */
 
 import './lib/runtime-deps/ensure-installed.js';
@@ -20,16 +17,10 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import {
-  fetchPlanRunIssues,
-  normalizePlanRunLabel,
-  resolvePlanRunFromIssues,
-} from './lib/orchestration/resolve-plan-run.js';
 import { runPlanRunEpilogue } from './lib/orchestration/run-epilogue.js';
 import { createProvider } from './lib/provider-factory.js';
 
 const CLI_OPTIONS = {
-  run: { type: 'string' },
   stories: { type: 'string' },
   cwd: { type: 'string' },
 };
@@ -44,13 +35,10 @@ export async function main(argv = process.argv.slice(2)) {
     options: CLI_OPTIONS,
     strict: false,
   });
-  const runFlag = typeof values.run === 'string' ? values.run.trim() : '';
   const hasStoriesFlag =
     typeof values.stories === 'string' && values.stories.trim().length > 0;
-  if (!runFlag && !hasStoriesFlag) {
-    throw new Error(
-      'Usage: node plan-run-epilogue.js (--run <planRunId> | --stories 1,2,3) [--stories 1,2,3]',
-    );
+  if (!hasStoriesFlag) {
+    throw new Error('Usage: node plan-run-epilogue.js --stories 1,2,3');
   }
   const cwd =
     typeof values.cwd === 'string' && values.cwd.trim()
@@ -59,26 +47,16 @@ export async function main(argv = process.argv.slice(2)) {
   const config = resolveConfig({ cwd });
   const provider = createProvider(config);
 
-  let stories = [];
-  if (hasStoriesFlag) {
-    stories = values.stories
-      .split(',')
-      .map((s) => Number(s.trim()))
-      .filter((n) => Number.isInteger(n) && n > 0);
-  } else {
-    const planRunLabel = normalizePlanRunLabel(runFlag);
-    const issues = await fetchPlanRunIssues(provider, {
-      planRunLabel,
-      state: 'all',
-    });
-    const envelope = resolvePlanRunFromIssues({ run: runFlag, issues });
-    stories = (envelope.stories ?? [])
-      .map((s) => Number(s?.id ?? s))
-      .filter((n) => Number.isInteger(n) && n > 0);
-  }
+  // Story #4540 retired the `--run <planRunId>` label-resolution branch
+  // along with the label itself. The epilogue is keyed on the delivered id
+  // set, and the synthesized `adhoc-<ids>` id it already used for positional
+  // runs is now the only id it needs.
+  const stories = values.stories
+    .split(',')
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isInteger(n) && n > 0);
 
-  const planRunId =
-    runFlag || `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
+  const planRunId = `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
 
   const result = await runPlanRunEpilogue({
     planRunId,
@@ -87,6 +65,8 @@ export async function main(argv = process.argv.slice(2)) {
     config,
     cwd,
   });
+  warnOnUnresolvedBase(result);
+  warnOnEmptyRollup(result);
   Logger.info(JSON.stringify(result, null, 2));
   if (result.errors?.length) {
     process.exitCode = 1;
@@ -94,4 +74,69 @@ export async function main(argv = process.argv.slice(2)) {
   return result;
 }
 
+/**
+ * Surface an unresolvable combined landed diff as a loud operator warning.
+ *
+ * The roster's changed-file set is the input the host walks its audit lenses
+ * against; a silent absence would read as "nothing changed" and the lens walk
+ * would look complete while covering nothing. Not fatal — with no diff the
+ * selector degrades to keyword-only lens selection, so the rest of the
+ * roster is still useful.
+ *
+ * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @returns {void}
+ */
+function warnOnUnresolvedBase(result) {
+  const roster = (result?.results ?? []).find(
+    (r) => r?.kind === 'audit-roster',
+  );
+  const base = roster?.baseResolution;
+  if (base?.resolved !== false) return;
+  Logger.warn(
+    `⚠️  Combined landed diff unavailable — the pre-run base sha could not be ` +
+      `resolved against \`${base.baseRef}\`: ${base.reason}\n` +
+      `    changedFiles is null (NOT an empty set). Determine the run diff by ` +
+      `hand before walking the selected lenses.`,
+  );
+}
+
+/**
+ * Surface a zero-signal roll-up over a multi-Story run as a loud operator
+ * warning (Story #4578).
+ *
+ * The failure this exists to prevent is a *reassuring* one. The roll-up read
+ * "No friction signals — nothing to follow up" for a 7-Story run that
+ * contained a mid-run git outage, a parked worker needing an operator
+ * resume, and an acceptance critic that needed four rounds. Nothing was
+ * broken in the roll-up — the stream really was empty — but the report was
+ * indistinguishable from a clean run, so the retro loop that exists to learn
+ * from a run was silently blind to that run's pain.
+ *
+ * Not fatal: a genuinely friction-free multi-Story run is possible, and this
+ * cannot tell the two apart — which is precisely why it asks the operator
+ * rather than asserting either reading.
+ *
+ * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @returns {void}
+ */
+function warnOnEmptyRollup(result) {
+  const rollup = (result?.results ?? []).find(
+    (r) => r?.kind === 'follow-up-rollup',
+  );
+  if (!rollup?.emptyRollupSuspect) return;
+  Logger.warn(
+    `⚠️  0 friction signals across ${rollup.storyCount} Stories — telemetry may not ` +
+      `have fired.\n` +
+      `    An empty roll-up is NOT evidence of a clean run: it is the same output a ` +
+      `run with\n` +
+      `    heavy friction produces when nothing recorded it. The runtime emits ` +
+      `friction from its\n` +
+      `    own observables (agent::blocked transitions, failed closes, exhausted ` +
+      `merge waits), so\n` +
+      `    zero here also means none of those fired. If this run had friction you ` +
+      `can name, that\n` +
+      `    telemetry gap is itself worth filing.`,
+  );
+}
+
 await runAsCli(import.meta.url, main);

package/.agents/scripts/post-structured-comment.js

@@ -22,10 +22,6 @@ import fs from 'node:fs/promises';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
-import {
-  outboxPathFor,
-  postCommentOrBuffer,
-} from './lib/orchestration/bookkeeping-outbox.js';
 import {
   assertValidStructuredCommentType,
   upsertStructuredComment,
@@ -41,11 +37,6 @@ Flags:
                  retro, epic-run-state, wave-0-start) (required).
   --body-file    Path to a file containing the markdown body (required).
   --provider     Provider name (default: inferred from .agentrc.json github block).
-  --buffer       Headless mode: buffer this upsert to the per-Epic bookkeeping
-                 outbox instead of posting live. Requires --epic. Drained to
-                 GitHub once at finalize by bookkeeping-reconcile.js (Epic
-                 #4476). Omit for attended runs (posts live, unchanged).
-  --epic <id>    Epic id owning the outbox (required with --buffer).
   --help         Show this message.
 `;
 
@@ -73,8 +64,6 @@ export function parseArgv(argv) {
       marker: { type: 'string' },
       'body-file': { type: 'string' },
       provider: { type: 'string' },
-      buffer: { type: 'boolean' },
-      epic: { type: 'string' },
       help: { type: 'boolean' },
     },
     strict: false,
@@ -126,33 +115,6 @@ export async function main(argv = process.argv.slice(2)) {
     : config;
   const provider = createProvider(effectiveConfig);
 
-  // Headless buffering (Epic #4476 M5): route the upsert to the per-Epic
-  // outbox instead of a live GitHub round-trip. Requires --epic to locate the
-  // outbox; finalize's bookkeeping-reconcile.js drains it once. Attended runs
-  // (no --buffer) are unchanged.
-  if (values.buffer) {
-    const epicId = Number.parseInt(values.epic ?? '', 10);
-    if (!Number.isInteger(epicId) || epicId <= 0) {
-      process.stderr.write(
-        '[post-structured-comment] --buffer requires --epic <id>.\n',
-      );
-      process.exit(2);
-    }
-    assertValidStructuredCommentType(values.marker);
-    const { buffered } = await postCommentOrBuffer({
-      provider,
-      ticketId,
-      marker: values.marker,
-      body,
-      headless: true,
-      outboxPath: outboxPathFor(epicId, config),
-    });
-    process.stdout.write(
-      `${JSON.stringify({ success: true, ticketId, type: values.marker, buffered })}\n`,
-    );
-    return;
-  }
-
   const envelope = await runPostStructuredComment({
     ticketId,
     type: values.marker,