mandrel 2.59.0 → 2.61.0

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

@@ -1,60 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * plan-persist.js — flat Story GitHub-write surface for v2 `/mandrel-plan`
- * (Stage 3 — `docs/roadmap.md`).
- *
- * Given the author-written planning artifacts (`stories.json`, optional shared
- * Tech Spec), this CLI validates and creates Story issue(s) directly:
- *
- *   changes[] repair → ticket validator / DAG → reachability →
- *   split-policy partition → fold Spec into each Story body →
- *   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)
- *   --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
- *   --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
- *   --chain-on-clean          Fast path (Story #4741; any plan since Story
- *                             #5312): run the write-free dry-run first, and
- *                             when it passes clean chain straight into the
- *                             real persist in the SAME invocation, collapsing
- *                             the two operator round-trips into one. A
- *                             dry-run failure stops before any createIssue.
- *                             Ignored when `--dry-run` is also set
- *   --force-review            Operator-forced review stop before persist lands
- *
- * Run `--dry-run` first. It exercises every gate — the changes[] repair, the
- * validator, DAG, reachability, split/supersede partition, Spec fold —
- * write-free, and lists every warning (a footprint probe that disagrees with
- * the base branch, an open question in a body) 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`.
+ * plan-persist.js — validate authored plan artifacts and create the Story
+ * issue(s). Without `--dry-run` it runs the write-free dry-run first and
+ * persists in the same invocation only if every gate passes. stdout carries
+ * only the JSON result; logs go to stderr.
  *
  * Exit codes: 0 success; 1 fatal; 3 reachability orphans (nothing mutated).
  */
@@ -82,12 +32,11 @@ import {
 } from './lib/orchestration/plan-persist/plan-context-source.js';
 import {
   runPlanPersist,
-  writeCheckpointV2,
+  writePlanSummaryComment,
 } from './lib/orchestration/plan-persist/run-plan-persist.js';
 import {
   buildPlanSummaryCommentBody,
   buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
 } from './lib/orchestration/plan-persist/summary.js';
 import { resolveSourceTicketIds } from './lib/orchestration/plan-persist/supersede-ops.js';
 import { createProvider } from './lib/provider-factory.js';
@@ -95,9 +44,8 @@ import { createProvider } from './lib/provider-factory.js';
 export {
   buildPlanSummaryCommentBody,
   buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
   runPlanPersist,
-  writeCheckpointV2,
+  writePlanSummaryComment,
 };
 
 const CLI_OPTIONS = {
@@ -109,7 +57,6 @@ const CLI_OPTIONS = {
   'close-superseded': { type: 'boolean', default: true },
   'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
-  'chain-on-clean': { type: 'boolean', default: false },
   'force-review': { type: 'boolean', default: false },
   'epic-title': { type: 'string' },
   'epic-goal': { type: 'string' },
@@ -120,7 +67,7 @@ const USAGE =
   'Usage: plan-persist.js --stories <file> ' +
   '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
-  '[--dry-run] [--chain-on-clean] [--force-review] ' +
+  '[--dry-run] [--force-review] ' +
   '[--epic-title <text> --epic-goal <text> | --epic <id>]';
 
 async function readOptional(filePath, { required }) {
@@ -144,9 +91,6 @@ async function readJsonFile(filePath, label) {
 }
 
 /**
- * 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) {
@@ -178,16 +122,11 @@ async function loadArtifacts(paths) {
 }
 
 /**
- * Resolve the optional container-Epic request from the CLI flags.
- *
- * Both halves are required together: an Epic with a title and no goal is a
- * container with nothing explaining the grouping, and a goal with no title
- * cannot be opened at all. Supplying exactly one is a **usage error**, not a
- * silent no-Epic run — the operator asked for a container and would otherwise
- * never learn they did not get one.
+ * Title and goal are required together; exactly one is a usage error rather
+ * than a silent no-Epic run.
  *
- * @param {object} values Parsed `parseArgs` values.
- * @returns {{ title: string, goal: string }|null} `null` when no Epic was requested.
+ * @param {object} values
+ * @returns {{ title: string, goal: string }|null}
  */
 export function resolveEpicRequest(values) {
   const title = (values['epic-title'] ?? '').trim();
@@ -204,15 +143,11 @@ export function resolveEpicRequest(values) {
 }
 
 /**
- * Refuse `--epic` alongside `--epic-title`/`--epic-goal`.
- *
- * A run either joins a container or opens one; asking for both names no
- * coherent outcome, so it is a usage error rather than a silent precedence
- * rule the operator would have to know.
+ * A run joins an Epic or opens one, never both.
  *
- * @param {object} values Parsed `parseArgs` values.
+ * @param {object} values
  * @returns {void}
- * @throws {Error} When both forms were supplied.
+ * @throws {Error}
  */
 export function assertEpicFlagsExclusive(values) {
   const adopts = (values.epic ?? '').trim() !== '';
@@ -229,14 +164,11 @@ export function assertEpicFlagsExclusive(values) {
 }
 
 /**
- * Resolve `--epic <id>`: the existing open container this run joins.
- *
- * Story #5155. Parsed here rather than deep in the engine so a typo costs a
- * usage error before any provider call — the id itself is verified against
- * live state later, before the first create.
+ * `--epic <id>` shape check before any provider call; existence is verified
+ * later against live state.
  *
- * @param {object} values Parsed `parseArgs` values.
- * @returns {number|null} `null` when no adoption was requested.
+ * @param {object} values
+ * @returns {number|null}
  */
 export function resolveEpicAdoptionId(values) {
   const raw = (values.epic ?? '').trim();
@@ -251,16 +183,13 @@ export function resolveEpicAdoptionId(values) {
 }
 
 /**
- * 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
- * `/mandrel-plan --tickets` superseding (Story #4554).
+ * Where envelope-derived source ids meet the engine; a break here silently
+ * un-wires `--tickets` superseding.
  *
- * @param {object} values Parsed `parseArgs` values.
+ * @param {object} values
  * @param {ReturnType<typeof resolveInputPaths>} paths
  * @param {object|null} planContextEnvelope
- * @returns {object} opts for `runPlanPersist`.
+ * @returns {object}
  */
 export function buildPersistOptions(values, paths, planContextEnvelope) {
   const source = resolveSourceTicketIds({
@@ -277,8 +206,7 @@ export function buildPersistOptions(values, paths, planContextEnvelope) {
     sourceTicketOrigin: source.origin,
     epic: resolveEpicRequest(values),
     adoptEpicId: resolveEpicAdoptionId(values),
-    // Default-on: `--no-close-superseded` is the explicit escape and always
-    // wins over the (default `true`) `--close-superseded`.
+    // `--no-close-superseded` always wins.
     closeSuperseded:
       values['no-close-superseded'] === true
         ? false
@@ -320,23 +248,10 @@ async function runPersistInvocation({
 }
 
 /**
- * Fast path (Story #4741 AC-1/AC-3; widened to any plan by Story #5312):
- * chain a clean dry-run into the real persist in ONE operator invocation.
- *
- * Two passes over the **same** loaded artifacts:
- *
- *   1. A write-free dry-run. Every gate runs before any `createIssue` can
- *      happen, so a validation failure — which throws or returns reachability
- *      orphans — stops here, before a single issue exists (AC-3).
- *   2. The real write, run when the dry-run passed clean. Because it replays
- *      the identical artifacts, the persisted output is byte-identical to
- *      what the dry-run validated (AC-1). The lite-route condition that used
- *      to gate this step went with the plan-side lite claim: a clean dry-run
- *      is the review the chain exists to fold.
- *
- * Exported for tests — this is where the round-trip collapse lives, so a
- * regression here silently re-opens the second operator round-trip (or
- * worse, persists a plan the dry-run never gated).
+ * Dry-run then persist over the SAME artifacts: a gate failure throws before
+ * any issue exists, and the write replays exactly what was validated. The
+ * repair pass mutates tickets in place, so pass 2 sees no repairs — carry pass
+ * 1's evidence onto the returned envelope.
  *
  * @param {{ values: object, config: object, provider: object,
  *   artifacts: object, metricsSince: string }} args
@@ -366,6 +281,14 @@ export async function runPersistChain({
     metricsSince,
     dryRun: false,
   });
+  persistResult.repairs = mergeEvidence(
+    dryResult.repairs,
+    persistResult.repairs,
+  );
+  persistResult.warnings = mergeEvidence(
+    dryResult.warnings,
+    persistResult.warnings,
+  );
   persistResult.chain = {
     attempted: true,
     persisted: true,
@@ -375,18 +298,38 @@ export async function runPersistChain({
 }
 
 /**
- * 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.
+ * Ordered union, deduped by serialized content.
  *
- * This runs *after* `recordPlanInvocation` has appended this run's own
- * record, so the summary always has at least that one entry to report.
+ * @param {unknown} first
+ * @param {unknown} second
+ * @returns {unknown[]}
+ */
+function mergeEvidence(first, second) {
+  const merged = [];
+  const seen = new Set();
+  for (const entry of [
+    ...(Array.isArray(first) ? first : []),
+    ...(Array.isArray(second) ? second : []),
+  ]) {
+    const key = JSON.stringify(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(entry);
+  }
+  return merged;
+}
+
+/**
+ * @param {object} values
+ * @returns {boolean} `true` to run the gates and then persist.
+ */
+export function shouldChainPersist(values) {
+  return values?.['dry-run'] !== true;
+}
+
+/**
+ * Attach the plan-metrics roll-up for this invocation. The Epic-less (`null`)
+ * ledger is shared by every plan run, so `since` scopes it to this one.
  *
  * @param {object} result Mutated in place with `planMetrics`.
  * @param {object} config
@@ -413,14 +356,10 @@ async function main() {
     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).
+  // stdout is reserved for the JSON result.
   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.
+  // Stamped before any ledger write so this run's records fall inside it.
   const metricsSince = new Date().toISOString();
 
   let config;
@@ -430,8 +369,7 @@ async function main() {
   } catch (err) {
     throw new Error(`Config schema validation failed:\n${err.message}`);
   }
-  // Argument-shape refusals fire before any I/O (Story #5155): a usage error
-  // the operator can see without waiting on artifact reads or a provider.
+  // Argument-shape refusals fire before any I/O.
   assertEpicFlagsExclusive(values);
   resolveEpicRequest(values);
   resolveEpicAdoptionId(values);
@@ -440,10 +378,7 @@ async function main() {
   const paths = resolveInputPaths(values);
   const artifacts = await loadArtifacts(paths);
 
-  // `--chain-on-clean` collapses the dry-run + persist operator round-trips
-  // (Story #4741). `--dry-run` always wins — an explicit dry-run never writes.
-  const useChain =
-    values['chain-on-clean'] === true && values['dry-run'] !== true;
+  const useChain = shouldChainPersist(values);
 
   let result;
   try {
@@ -482,7 +417,7 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-persist.js --stories <file> [--tech-spec <file>] [--dry-run] [options]',
     summary:
-      'Validate an authored plan and persist it as GitHub Stories. Prints the result envelope as JSON on stdout.',
+      'Validate an authored plan and persist it as GitHub Stories in one invocation (pass --dry-run to validate only). Prints the result envelope as JSON on stdout.',
     flags: [
       ['--stories <file>', 'Authored stories.json (required).'],
       ['--tech-spec <file>', 'Optional companion techspec.md.'],
@@ -493,7 +428,6 @@ runAsCli(import.meta.url, main, {
       ],
       ['--source-tickets <ids>', 'Ticket ids this plan supersedes.'],
       ['--dry-run', 'Validate and report; create nothing.'],
-      ['--chain-on-clean', 'Persist immediately when the dry run is clean.'],
       ['--no-close-superseded', 'Leave superseded source tickets open.'],
       [
         '--force-review',

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

@@ -7,9 +7,7 @@
  *   node .agents/scripts/plan-run-epilogue.js --stories 1,2,3
  *   node .agents/scripts/plan-run-epilogue.js --stories 101-104   # inclusive range
  *
- * 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.
+ * Keyed on the delivered id set via a synthesized `adhoc-<sorted-ids>` run id.
  */
 
 import './lib/runtime-deps/ensure-installed.js';
@@ -25,6 +23,8 @@ import { expandIdList } from './lib/util/parse-id-list.js';
 const CLI_OPTIONS = {
   stories: { type: 'string' },
   cwd: { type: 'string' },
+  /** Opt-in; see `run-epilogue.js` RUN_EPILOGUE_STEP_KINDS. */
+  'audit-roster': { type: 'boolean', default: false },
 };
 
 /**
@@ -34,9 +34,7 @@ const CLI_OPTIONS = {
  *   createProviderImpl?: typeof createProvider,
  *   runPlanRunEpilogueImpl?: typeof runPlanRunEpilogue,
  *   logger?: { info: Function, warn: Function },
- * }} [deps] Injectable seams; every entry defaults to the real
- *   implementation (`.agents/rules/test-seams.md` rules 1-2), so the CLI path
- *   and every production caller are unchanged.
+ * }} [deps]
  * @returns {Promise<object>}
  */
 export async function main(argv = process.argv.slice(2), deps = {}) {
@@ -51,26 +49,15 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     options: CLI_OPTIONS,
     strict: false,
   });
-  const hasStoriesFlag =
-    typeof values.stories === 'string' && values.stories.trim().length > 0;
-  if (!hasStoriesFlag) {
+  if (typeof values.stories !== 'string' || !values.stories.trim()) {
     throw new Error('Usage: node plan-run-epilogue.js --stories 1,2,3');
   }
-  const cwd =
-    typeof values.cwd === 'string' && values.cwd.trim()
-      ? values.cwd.trim()
-      : process.cwd();
+  const cwd = values.cwd?.trim() || process.cwd();
   const config = resolveConfigImpl({ cwd });
   const provider = createProviderImpl(config);
 
-  // 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.
-  // Range tokens expand here too (`--stories 101-104`): /mandrel-deliver blesses the
-  // dash range at the operator surface, so the id set the epilogue is keyed on
-  // must read the same shape. Rejecting a bad token is deliberate — the old
-  // silent filter turned a typo into an empty, wrongly-keyed rollup.
+  // Ranges expand as at the operator surface; a bad token throws rather than
+  // silently producing an empty, wrongly-keyed rollup.
   const { ids: stories, error: storiesError } = expandIdList(values.stories, {
     flag: '--stories',
     prefix: '[plan-run-epilogue] ',
@@ -87,6 +74,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     provider,
     config,
     cwd,
+    auditRoster: values['audit-roster'] === true,
   });
   warnOnUnresolvedBase(result, logger);
   warnOnEmptyRollup(result, logger);
@@ -98,13 +86,9 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 }
 
 /**
- * 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.
+ * Warn (not fatal) when the combined landed diff is unresolvable under
+ * `--audit-roster`: silence would read as "nothing changed" and the lens walk
+ * would look complete while covering nothing.
  *
  * @param {object} result - `runPlanRunEpilogue` envelope.
  * @param {{ warn: Function }} [logger]
@@ -125,20 +109,9 @@ function warnOnUnresolvedBase(result, logger = Logger) {
 }
 
 /**
- * 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.
+ * Warn on a zero-signal roll-up over a multi-Story run: it is
+ * indistinguishable from a run whose friction went unrecorded, so the
+ * operator decides which it was.
  *
  * @param {object} result - `runPlanRunEpilogue` envelope.
  * @param {{ warn: Function }} [logger]
@@ -167,7 +140,7 @@ function warnOnEmptyRollup(result, logger = Logger) {
 await runAsCli(import.meta.url, main, {
   usage: {
     invocation:
-      'node .agents/scripts/plan-run-epilogue.js --stories <id,id,...> [--cwd <path>]',
+      'node .agents/scripts/plan-run-epilogue.js --stories <id,id,...> [--cwd <path>] [--audit-roster]',
     summary:
       'Close out a delivery run: roll up the delivered Stories’ signals and report the run’s loop health.',
     flags: [
@@ -176,6 +149,10 @@ await runAsCli(import.meta.url, main, {
         'Comma-separated delivered Story ids, singles or A-B ranges (required).',
       ],
       ['--cwd <path>', 'Repository root (default: process cwd).'],
+      [
+        '--audit-roster',
+        'Also select the cross-Story audit lens roster and post plan-run-audit-roster (off by default; the host then walks every listed lens).',
+      ],
     ],
   },
 });