mandrel 2.60.0 → 2.62.0

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

@@ -2,53 +2,16 @@
 /* node:coverage ignore file */
 
 /**
- * plan-context.js — step 1 of the collapsed `/mandrel-plan` pipeline.
+ * plan-context.js — build the `/mandrel-plan` authoring-context envelope from
+ * exactly one entry form (`--seed`, `--seed-file`, `--tickets`, `--amends`),
+ * write it with `stories.template.json` under `<tempRoot>/plan-<slug>/`
+ * (where `plan-persist.js` discovers the `--tickets` source ids), and print a
+ * compact JSON digest as the only stdout.
  *
- * Emits one stdout-pure JSON envelope for the `/mandrel-plan` authoring middle.
- *
- * Two operator modes (exactly one is required):
- *
- *   --seed "<text>"           Chat/text ideation. Dup search runs off the
- *                             raw seed; envelope carries `seed`.
- *
- *   --seed-file <path>        Same as --seed, but the corpus is read from
- *                             disk (audit-to-stories handoff, notes).
- *
- *   --tickets 123[,456…]      Analyze existing issue(s) into proper
- *                             Stories. Envelope carries `sourceTickets[]`.
- *
- *   --amends 123 | #123       Amendment (delta) planning. Composes a DELTA
- *                             envelope from the prior Story's body, its
- *                             acceptance criteria, and its delivered file map
- *                             instead of re-interrogating the repo from
- *                             scratch (Story #4741). Envelope carries `amends`.
- *
- * Flags:
- *   --out <path>     Override where the envelope is written (parent dirs
- *                    created). **Optional since Story #5342** — with no
- *                    `--out` the envelope lands at
- *                    `<tempRoot>/plan-<slug>/plan-context.json`, the plan
- *                    directory `/mandrel-plan` would have named by hand, and
- *                    `stories.template.json` lands beside it. That is where
- *                    `plan-persist.js` auto-discovers the `--tickets` source
- *                    ids from (Story #4554); without a captured envelope
- *                    persist cannot know a `--tickets` run happened, and
- *                    superseding degrades to the `--source-tickets` flag.
- *   --pretty         Pretty-print the written JSON envelope.
- *
- * stdout is reserved for a single JSON payload (Story #2278 discipline) —
- * the compact digest naming the written artifacts (Story #4708
- * script-output contract): `routeAllOutputToStderr()` runs before any
- * pipeline code so the stream is unconditionally parseable by `JSON.parse`.
- *
- * Exit codes:
- *   0 — envelope emitted.
- *   1 — fatal error (see stderr).
+ * Exit codes: 0 envelope emitted; 1 fatal.
  */
 
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
+// Must be the first import: fail fast before any third-party import runs.
 import './lib/runtime-deps/ensure-installed.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -69,19 +32,14 @@ import {
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
-/** Longest slug segment a default plan directory carries. */
 const PLAN_SLUG_MAX_LENGTH = 48;
 
 /**
- * Reduce free text to the hyphen-case segment a plan directory is named by.
- *
- * Deliberately lossy: the slug is a human-readable handle on a temp
- * directory, not an identity — two runs from the same seed land in the same
- * directory and the second overwrites the first, which is the idempotent
- * behaviour the operator already got from typing the same `--out` twice.
+ * Deliberately lossy: a handle, not an identity — the same seed reuses (and
+ * overwrites) the same directory.
  *
  * @param {string} raw
- * @returns {string} A non-empty hyphen-case slug (`plan` when nothing survives).
+ * @returns {string} `plan` when nothing survives.
  */
 export function slugifyPlanLabel(raw) {
   const slug = String(raw ?? '')
@@ -94,28 +52,18 @@ export function slugifyPlanLabel(raw) {
 }
 
 /**
- * Resolve where the envelope is written when the operator passed no `--out`
- * (Story #5342).
- *
- * `--out` was mandatory in practice and optional in the CLI: persist
- * auto-discovers the envelope and the `stories.template.json` beside it from
- * the plan directory, so a run without it silently lost superseding and the
- * authoring skeleton. The path it always pointed at is derivable — the
- * configured `tempRoot`, a `plan-<slug>` directory named for what is being
- * planned — so the CLI derives it rather than asking.
- *
- * Exported for tests: this is the join where a missing flag stops costing
- * the plan its source ids.
+ * Envelope path when no `--out` is given. Always written, because persist
+ * discovers source ids and the template from this directory.
  *
  * @param {object} args
- * @param {string} args.mode One of `seed` | `seed-file` | `tickets` | `amends`.
+ * @param {string} args.mode
  * @param {string} [args.seedText]
  * @param {string} [args.seedFilePath]
  * @param {number[]} [args.ticketIds]
  * @param {number} [args.amendsId]
- * @param {object} [args.config] Resolved config (for `project.paths.tempRoot`).
+ * @param {object} [args.config]
  * @param {string} [args.cwd]
- * @returns {string} Absolute path to the envelope file.
+ * @returns {string} Absolute path.
  */
 export function resolveDefaultOutPath({
   mode,
@@ -141,8 +89,6 @@ export function resolveDefaultOutPath({
 }
 
 /**
- * Parse a comma-/space-separated ticket id list into positive integers.
- *
  * @param {string} raw
  * @returns {number[]}
  */
@@ -164,8 +110,6 @@ export function parseTicketIds(raw) {
 }
 
 /**
- * Parse a single `--amends` id, tolerating a leading `#` (`#123` or `123`).
- *
  * @param {string} raw
  * @returns {number}
  */
@@ -183,11 +127,6 @@ export function parseAmendsId(raw) {
 }
 
 /**
- * Build the envelope, write it (plus the `stories.template.json` skeleton)
- * to `outPath` — or to the derived default when none was passed
- * (Story #5342) — and print the compact digest on stdout. Exported for
- * tests.
- *
  * @param {object} args
  * @returns {Promise<object>} the emitted envelope.
  */
@@ -233,11 +172,8 @@ export async function emitPlanContext({
       cwd: cwd ?? undefined,
     });
   {
-    // Script-output contract (Story #4708, AC-5): the full envelope is a
-    // ~40KB artifact that would ride resident in the transcript for every
-    // later turn. It is always captured to disk (Story #5342 derives the
-    // path when `--out` is absent), so stdout carries a compact digest
-    // naming the artifacts instead of the payload itself.
+    // The ~40KB envelope goes to disk; stdout carries only a digest so it
+    // does not ride resident in the transcript.
     await writeEnvelopeFile(resolvedOut, json);
     await writeStoriesTemplateFile(resolvedOut, envelope);
     const resolved = path.resolve(resolvedOut);
@@ -252,10 +188,7 @@ export async function emitPlanContext({
       bytes: Buffer.byteLength(json, 'utf8'),
       sourceTickets: (envelope.sourceTickets ?? []).map((t) => t.id),
       duplicates: (envelope.duplicates ?? []).length,
-      // Advisory only: signals, no route. `uiSurface` is the recorded
-      // /prototype offer — advisory, never an automatic reroute. It rides the
-      // digest because with `--out` the digest is the only thing the planner
-      // reads.
+      // Advisory signals only, never a reroute.
       complexitySignals: envelope.complexitySignals
         ? {
             artifactCount: envelope.complexitySignals.artifactCount,
@@ -264,8 +197,7 @@ export async function emitPlanContext({
             uiSurface: envelope.complexitySignals.uiSurface ?? null,
           }
         : null,
-      // Story #5312: an envelope over the planner-context ceiling is written
-      // truncated, and the digest names what was cut.
+      // Names what was cut when the envelope exceeded the context ceiling.
       truncated: envelope.truncated ?? null,
       amends: envelope.amends ? { id: envelope.amends.id } : null,
     };
@@ -275,12 +207,8 @@ export async function emitPlanContext({
 }
 
 /**
- * Persist the envelope to `--out` so `plan-persist.js` can derive the
- * `--tickets` source ids from it without an operator re-typing them.
- *
- * Writing is part of emitting, not a best-effort extra: a failed write means
- * persist will silently see no source tickets, so it throws rather than
- * warning past the problem.
+ * Throws on failure: a missing envelope makes persist silently see no source
+ * tickets.
  *
  * @param {string} outPath
  * @param {string} json
@@ -299,19 +227,11 @@ async function writeEnvelopeFile(outPath, json) {
 }
 
 /**
- * Emit the ready-to-fill Story authoring template next to the captured
- * envelope (Story #4707 — one-shot authoring). The planner copies it to
- * `stories.json` and fills the placeholders; no step of the authoring path
- * requires reading `story-body.js` source. Written on every run (Story
- * #5342), and throwing on failure for the same reason the envelope write
- * does: a silently missing template re-opens the format-discovery loop it
- * exists to close. The envelope's advisory `complexitySignals` are threaded
- * through so the skeleton's `changes[]` arrive pre-resolved to
- * creates-vs-refactors against the repo snapshot (Story #4723).
+ * Write the ready-to-fill authoring template beside the envelope, with
+ * `changes[]` pre-resolved from `complexitySignals`. Throws on failure.
  *
- * @param {string} outPath The envelope `--out` path; the template lands in
- *   the same directory as {@link STORIES_TEMPLATE_FILENAME}.
- * @param {object} [envelope] The emitted plan-context envelope.
+ * @param {string} outPath
+ * @param {object} [envelope]
  */
 async function writeStoriesTemplateFile(outPath, envelope = {}) {
   const resolved = path.resolve(
@@ -380,18 +300,14 @@ async function main() {
     mode = 'seed';
   }
 
-  // stdout is reserved for the JSON envelope: flip every Logger sink that
-  // could land on stdout to stderr BEFORE any pipeline code runs
-  // (Story #2278 — the same stdout-purity guarantee the retired pipeline
-  // gives; this CLI is emit-only so the flip is unconditional).
+  // stdout is reserved for the JSON digest.
   routeAllOutputToStderr();
 
   let config;
   let settings;
   try {
     config = resolveConfig();
-    // `settings` retains the legacy bag shape `buildAuthoringContext` and
-    // friends consume: `{ baseBranch, paths, planning, docsContextFiles }`.
+    // The bag shape `buildAuthoringContext` consumes.
     settings = {
       baseBranch: config.project?.baseBranch,
       paths: config.project?.paths,

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

@@ -1,45 +1,11 @@
 #!/usr/bin/env node
 
 /**
- * plan-critics.js — the /mandrel-plan pre-mortem dispatch verdict CLI
- * (Story #4592; pre-mortem only since Story #5312).
- *
- * The operator runs this between Author and Persist when they want the
- * pre-mortem — it is no longer a step of the `/mandrel-plan` spine. It
- * evaluates the pre-mortem dispatch condition against the draft
- * `stories.json` 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.
- *
- * The pre-mortem's external-dependency arm (Story #4700) needs the repo's own
- * manifests to tell an external scoped package from a local one, so this CLI
- * reads them (`collectRepoPackages`) and passes the specifier set down — the
- * pure evaluation modules never touch the filesystem.
- *
- * 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, folded into the plan
- *                        text the external-dependency probe scans.
- *
- * stdout is reserved for the verdict JSON (Story #2278 discipline):
- *
- *   {
- *     "premortem": { "critic": "pre-mortem", "dispatch": true, "reasons": [...] }
- *   }
- *
- * Human-readable log lines go to stderr, matching the sibling `plan-persist`.
+ * plan-critics.js — operator-run pre-mortem dispatch verdict for a draft plan,
+ * evaluated between Author and Persist, where a re-author loop can still act
+ * on it. Advisory: exits 0 on any verdict; each skip is recorded to the
+ * plan-metrics ledger so under-firing stays auditable. stdout carries only
+ * `{ "premortem": { critic, dispatch, reasons } }`.
  *
  * Exit codes: 0 success (any verdict); 1 usage/IO error.
  */
@@ -61,10 +27,8 @@ const CLI_OPTIONS = {
 
 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';
 
-/** Dependency maps a manifest can declare a package under. */
 const DEP_MAP_KEYS = [
   'dependencies',
   'devDependencies',
@@ -72,7 +36,6 @@ const DEP_MAP_KEYS = [
   'peerDependencies',
 ];
 
-/** Add a manifest's own name and every declared dependency to `names`. */
 function collectPackageIdentity(names, pkg) {
   if (typeof pkg?.name === 'string') names.add(pkg.name);
   for (const key of DEP_MAP_KEYS) {
@@ -92,7 +55,6 @@ async function readJsonIfPresent(filePath) {
   }
 }
 
-/** Normalize the `workspaces` field (array or `{ packages: [] }`) to a list. */
 function workspacePatterns(pkg) {
   const ws = pkg?.workspaces;
   if (Array.isArray(ws)) return ws;
@@ -101,9 +63,7 @@ function workspacePatterns(pkg) {
 }
 
 /**
- * Resolve `workspaces` patterns to child `package.json` paths. Handles the two
- * common shapes — a `dir/*` glob (expanded one level) and a literal path — and
- * never throws: an unreadable base directory is skipped.
+ * Handles `dir/*` (one level) and literal paths; never throws.
  *
  * @param {string} rootDir
  * @param {string[]} patterns
@@ -134,11 +94,9 @@ async function resolveWorkspaceManifestPaths(rootDir, patterns) {
 }
 
 /**
- * Gather the package specifiers the repo's own manifests declare — the set the
- * pre-mortem external-dependency probe (Story #4700) measures a scoped-package
- * reference against. Includes the root manifest's own name and dependency maps
- * plus every workspace manifest's. Best-effort: a repo with no `package.json`
- * yields `[]`, which only widens what the probe treats as external.
+ * Package specifiers the repo's own manifests (root + workspaces) declare, so
+ * the external-dependency probe can tell local from external. No manifest
+ * yields `[]`, which only widens what counts as external.
  *
  * @param {{ rootDir?: string }} [opts]
  * @returns {Promise<string[]>}
@@ -160,8 +118,6 @@ export async function collectRepoPackages({ rootDir = process.cwd() } = {}) {
 }
 
 /**
- * Read the draft artifacts the critics evaluate.
- *
  * @param {{ storiesPath: string, techSpecPath?: string|null }} paths
  * @returns {Promise<{ tickets: object[], techSpecContent: string }>}
  */
@@ -188,9 +144,7 @@ export async function loadCriticArtifacts({
 }
 
 /**
- * Log the decision and record a skip on the plan-metrics ledger. The
- * ledger write is best-effort by `appendCriticSkip`'s own contract — it can
- * never fail the plan step.
+ * The ledger write is best-effort and never fails the plan step.
  *
  * @param {{ premortem: object }} verdict
  * @param {object} config
@@ -221,10 +175,6 @@ export async function recordCriticSkips(
 }
 
 /**
- * Load the artifacts, evaluate the pre-mortem, record a skip, 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,
@@ -232,10 +182,7 @@ export async function recordCriticSkips(
  *   knownPackages?: string[],
  *   append?: typeof appendCriticSkip,
  * }} args
- * @param {string[]} [args.knownPackages] - Package specifiers the repo's own
- *   manifests declare, forwarded to the pre-mortem external-dependency probe
- *   (Story #4700). `main()` resolves them via `collectRepoPackages`; tests may
- *   pass an explicit set or omit it (defaults to `[]`).
+ * @param {string[]} [args.knownPackages]
  * @returns {Promise<{ premortem: object }>}
  */
 export async function evaluateCriticArtifacts({
@@ -266,8 +213,7 @@ async function main() {
     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.
+  // stdout is reserved for the verdict JSON.
   routeAllOutputToStderr();
 
   const verdict = await evaluateCriticArtifacts({

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

@@ -1,56 +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) → one `story-plan-state` comment (the plan summary) on
- *   every Story → 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
- *   --force-review            Operator-forced review stop before persist lands
- *
- * **Persist is one command (Story #5342).** Without `--dry-run` the CLI runs
- * the write-free dry-run first — the
- * changes[] repair, the validator, DAG, reachability, split/supersede
- * partition, Spec fold — and, when the gate list comes back clean, chains
- * straight into the real persist in the SAME invocation. A dry-run failure
- * stops before any `createIssue`, and the run lists every warning (a
- * footprint probe that disagrees with the base branch, an empty `verify[]`,
- * an open question in a body) either way. `--dry-run` still creates nothing.
- *
- * 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).
  */
@@ -137,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) {
@@ -171,16 +122,11 @@ async function loadArtifacts(paths) {
 }
 
 /**
- * Resolve the optional container-Epic request from the CLI flags.
+ * Title and goal are required together; exactly one is a usage error rather
+ * than a silent no-Epic run.
  *
- * 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.
- *
- * @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();
@@ -197,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() !== '';
@@ -222,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();
@@ -244,16 +183,13 @@ export function resolveEpicAdoptionId(values) {
 }
 
 /**
- * Assemble the `runPlanPersist` opts bag from parsed CLI values.
+ * Where envelope-derived source ids meet the engine; a break here silently
+ * un-wires `--tickets` superseding.
  *
- * 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).
- *
- * @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({
@@ -270,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
@@ -313,32 +248,10 @@ async function runPersistInvocation({
 }
 
 /**
- * The default persist path (Story #4741 AC-1/AC-3; widened to any plan by
- * Story #5312; made the default by Story #5342): 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.
- *
- * The caller reads the **second** pass's envelope, so the first pass's
- * evidence has to be carried onto it (Story #5361). The repair pass mutates
- * the loaded tickets in place, which is what makes replaying the identical
- * artifacts possible at all — and it is also why pass 2 recomputes an empty
- * `repairs[]`: by then there is nothing left to repair. The evidence is
- * preserved rather than re-derived, because re-running the repair pass would
- * report repairs the persisting pass did not make.
- *
- * 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
@@ -385,10 +298,7 @@ export async function runPersistChain({
 }
 
 /**
- * Union two evidence lists, dry-run first, dropping an entry the second pass
- * reported identically. Order is the operator's reading order; the dedupe is
- * by rendered content because a repair is a plain record and a warning is a
- * string, so two passes that noticed the same thing noticed it byte-for-byte.
+ * Ordered union, deduped by serialized content.
  *
  * @param {unknown} first
  * @param {unknown} second
@@ -410,19 +320,7 @@ function mergeEvidence(first, second) {
 }
 
 /**
- * Decide whether this invocation persists after its gates, or only validates.
- *
- * Story #5342: chaining is the default, not a flag. Every invocation that is
- * not an explicit `--dry-run` runs the gate list and then persists what it
- * passed, so the two operator round-trips collapse without anyone having to
- * remember an opt-in. Story #5361 removed the no-op alias Story #5342 had
- * kept for existing call-sites, rather than accepting and ignoring it: a flag
- * that cannot change an outcome is a shim, and `parseArgs` refuses an unknown
- * option, so passing it now fails loudly instead of reading as honoured.
- *
- * Exported for tests: this one predicate is what makes the CLI one command.
- *
- * @param {object} values Parsed `parseArgs` values.
+ * @param {object} values
  * @returns {boolean} `true` to run the gates and then persist.
  */
 export function shouldChainPersist(values) {
@@ -430,18 +328,8 @@ export function shouldChainPersist(values) {
 }
 
 /**
- * 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.
+ * 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
@@ -468,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;
@@ -485,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);