mandrel 1.90.0 → 1.92.0

package/.agents/scripts/lib/orchestration/plan-persist/summary.js

@@ -0,0 +1,191 @@
+/**
+ * summary.js — plan-persist terminal summary (Epic #4474, PR3).
+ *
+ * Owns the single `plan-summary` structured comment the collapsed persist
+ * surface upserts at terminal success, closing with the dry-run wave table.
+ * This replaces two retired round-trips of the 12-phase pipeline:
+ *
+ *   - the Phase 9 plan-time `dispatch-manifest` comment, whose claimed
+ *     consumer ("Wave Completeness Gate, /deliver Step 0.5") does not exist
+ *     — the live manifest is written at deliver time by `wave-record-io.js`
+ *     (#4474 design §3: DROP, keep the wave table as summary text only);
+ *   - the Phase 12 notify round-trip ("informational — no webhook for
+ *     planning").
+ *
+ * The wave table is computed from the validated ticket set's `depends_on`
+ * slug edges via the same `computeStoryWaves` layering the deliver-time
+ * dispatch pipeline uses, so the preview matches what `/deliver` will
+ * actually fan out (barring later manual ticket edits).
+ *
+ * @module lib/orchestration/plan-persist/summary
+ */
+
+import { computeStoryWaves } from '../dependency-analyzer.js';
+
+/**
+ * Structured-comment type for the persist summary. Registered in
+ * `ticketing/reads.js` `STRUCTURED_COMMENT_TYPES`; upsert-idempotent so a
+ * `--force`/`--resume` re-persist replaces the prior summary in place.
+ */
+export const PLAN_SUMMARY_COMMENT_TYPE = 'plan-summary';
+
+/**
+ * Compute the dry-run wave assignment for a validated ticket set.
+ *
+ * Adapts the slug-keyed ticket shape onto `computeStoryWaves`' storyGroups
+ * contract (slug → { storyId, tasks: [] }; explicit deps from `depends_on`).
+ * Under the 2-tier hierarchy Stories carry no tasks, so all edges are
+ * explicit.
+ *
+ * @param {Array<{ slug: string, title?: string, depends_on?: string[] }>} tickets
+ * @returns {Array<{ wave: number, stories: Array<{ slug: string, title: string }> }>}
+ *   Waves in execution order.
+ */
+export function buildWaveTable(tickets) {
+  const list = Array.isArray(tickets) ? tickets : [];
+  if (list.length === 0) return [];
+  const storyGroups = new Map();
+  const explicitDeps = new Map();
+  for (const t of list) {
+    storyGroups.set(t.slug, { storyId: t.slug, tasks: [] });
+    explicitDeps.set(
+      t.slug,
+      (t.depends_on ?? []).filter((dep) => typeof dep === 'string'),
+    );
+  }
+  const assignment = computeStoryWaves(storyGroups, explicitDeps);
+  const byWave = new Map();
+  for (const t of list) {
+    const wave = assignment.get(t.slug) ?? 0;
+    if (!byWave.has(wave)) byWave.set(wave, []);
+    byWave.get(wave).push({ slug: t.slug, title: t.title ?? t.slug });
+  }
+  return [...byWave.keys()]
+    .sort((a, b) => a - b)
+    .map((wave) => ({ wave, stories: byWave.get(wave) }));
+}
+
+/**
+ * Render the dry-run wave table as GitHub-flavoured markdown.
+ *
+ * @param {ReturnType<typeof buildWaveTable>} waveTable
+ * @returns {string[]} markdown lines
+ */
+function renderWaveTableLines(waveTable) {
+  if (!Array.isArray(waveTable) || waveTable.length === 0) {
+    return ['_No stories to wave (empty plan)._'];
+  }
+  const rows = waveTable.map(
+    ({ wave, stories }) =>
+      `| ${wave + 1} | ${stories.map((s) => `\`${s.slug}\``).join(', ')} |`,
+  );
+  return ['| Wave | Stories |', '| --- | --- |', ...rows];
+}
+
+/**
+ * Build the `plan-summary` structured-comment body: risk + routing +
+ * freshness + healthcheck receipts, closing with the mode-specific tail —
+ * the dry-run wave table for fan-out/amend, or the single-delivery routing
+ * record `{ deliveryShape, sliceCount, routingReasons }` (Epic #4474 PR4)
+ * for the spec-only mode.
+ *
+ * @param {{
+ *   epicId: number,
+ *   ticketCount: number,
+ *   planningRisk: { overallLevel?: string, gateDecision?: string },
+ *   reviewRouting: { decision?: string },
+ *   freshness?: { stale?: number, ambiguous?: number },
+ *   healthcheck?: { ok?: boolean, waived?: boolean, skipped?: boolean },
+ *   waveTable: ReturnType<typeof buildWaveTable>,
+ *   mode?: 'fan-out'|'single'|'amend',
+ *   planMetricsLine?: string|null,
+ *   single?: { deliveryShape: 'single', sliceCount: number|null, routingReasons: string[] }|null,
+ *   amend?: {
+ *     closed: Array<{ slug: string, issueNumber: number }>,
+ *     recreated: Array<{ slug: string, oldIssueNumber: number, issueNumber: number }>,
+ *     created: Array<{ slug: string, issueNumber: number }>,
+ *     keptCount: number,
+ *   }|null,
+ * }} input
+ * @returns {string}
+ */
+export function buildPlanSummaryCommentBody({
+  epicId,
+  ticketCount,
+  planningRisk,
+  reviewRouting,
+  freshness,
+  healthcheck,
+  waveTable,
+  mode = 'fan-out',
+  planMetricsLine = null,
+  single = null,
+  amend = null,
+}) {
+  const freshnessLine =
+    (freshness?.stale ?? 0) > 0 || (freshness?.ambiguous ?? 0) > 0
+      ? `- ⚠️ Spec freshness: ${freshness.stale} stale / ${freshness.ambiguous} ambiguous reference(s) — see the spec-freshness comment.`
+      : '- Spec freshness: clean.';
+  const healthcheckLine = healthcheck?.skipped
+    ? '- Healthcheck: skipped (test seam).'
+    : healthcheck?.ok
+      ? '- Healthcheck: passed.'
+      : `- Healthcheck: failed, waived by operator label.`;
+
+  const headLine =
+    mode === 'single'
+      ? `- Single-delivery plan (\`delivery::single\`): no Story tree — the Delivery Slicing table is the audit trail.`
+      : `- ${ticketCount} Story ticket(s) persisted across ${waveTable.length} wave(s).`;
+
+  const amendLines = amend
+    ? [
+        `- Amend delta: ${amend.created.length} added, ${amend.recreated.length} modified (closed + recreated), ${amend.closed.length} closed, ${amend.keptCount} kept untouched.`,
+      ]
+    : [];
+
+  const tail =
+    mode === 'single'
+      ? [
+          '#### Delivery routing record',
+          '',
+          '```json',
+          JSON.stringify(
+            {
+              deliveryShape: 'single',
+              sliceCount: single?.sliceCount ?? null,
+              routingReasons: single?.routingReasons ?? [],
+            },
+            null,
+            2,
+          ),
+          '```',
+          '',
+          '_Marker is inert until #4475 lands the deliver-side reader — `/deliver` still treats this Epic as fan-out until then._',
+        ]
+      : [
+          '#### Dry-run wave table',
+          '',
+          ...renderWaveTableLines(waveTable),
+          '',
+          '_Preview only — the authoritative dispatch manifest is written at deliver time (`wave-record-io.js`)._',
+        ];
+
+  return [
+    `### 📋 Plan Summary — Epic #${epicId} is \`agent::ready\``,
+    '',
+    headLine,
+    ...amendLines,
+    `- Risk: ${planningRisk?.overallLevel ?? 'unknown'} · ${planningRisk?.gateDecision ?? 'unknown'} (review routing: ${reviewRouting?.decision ?? 'unknown'}).`,
+    freshnessLine,
+    healthcheckLine,
+    // G2 measurement receipt (Epic #4474 PR1/PR7): the plan-CLI invocation
+    // ledger roll-up (turns-per-plan proxy, per-mode counts, critic skips)
+    // rides the summary comment so the cohort reader never has to pull the
+    // temp ledger off the runner's disk. Omitted when the ledger is empty.
+    ...(typeof planMetricsLine === 'string' && planMetricsLine.length > 0
+      ? [`- ${planMetricsLine}`]
+      : []),
+    '',
+    ...tail,
+  ].join('\n');
+}

package/.agents/scripts/lib/orchestration/plan-reachability.js

@@ -0,0 +1,160 @@
+/**
+ * plan-reachability.js — deterministic draft-ticket reachability check for
+ * the persist surface (Epic #4474 PR6, design §4: the 8.4 reachability
+ * critic demoted from a fresh-context sub-agent to a persist-side scan).
+ *
+ * Mirrors the mechanics of the existing `--paranoid` F7 healthcheck
+ * (`epic-plan-healthcheck.js#checkReachability`) — route-glob scan of the
+ * paths a Story declares vs the `planning.navigation.navRegistry` token
+ * list — but runs it over the **draft** ticket set inside `plan-persist.js`
+ * step 4.5, before any provider call, so an orphaned surface is caught
+ * while a one-line targeted amend is still free (nothing has been written
+ * to GitHub yet).
+ *
+ * Plan-level coverage semantics (the convergence contract): a route-adding
+ * story that never references the nav registry produces orphan surfaces —
+ * UNLESS every one of its route paths is also mentioned by some story in
+ * the plan that DOES reference the registry (the "navigation owner"). That
+ * is exactly what the documented recovery produces: the author appends the
+ * single reachability Story (which cites the orphaned routes and the nav
+ * registry) in one targeted amend, and the re-run persist passes.
+ *
+ * Silent no-op when `planning.navigation` is unconfigured (`routeGlobs`
+ * empty) — same opt-in contract as F7 / AC-13 — reported as
+ * `status: 'skipped'` so the caller can append the audit record to the
+ * plan-metrics ledger.
+ *
+ * Pure over its inputs (tickets + resolved config), no I/O.
+ */
+
+import {
+  extractStoryPaths,
+  globToRegExp,
+  resolveNavConfig,
+} from '../../epic-plan-healthcheck.js';
+
+/**
+ * Fallback tokens when `navRegistry` is unconfigured but `routeGlobs` is —
+ * identical to the F7 healthcheck's fallback, so the two checks agree on
+ * what counts as a registry reference.
+ */
+const FALLBACK_REGISTRY_TOKENS = ['nav registry', 'navigation'];
+
+/**
+ * @typedef {Object} ReachabilityOrphan
+ * @property {string} story The offending draft story's slug (or title).
+ * @property {string[]} paths The route-matching paths with no navigation
+ *   owner anywhere in the plan.
+ */
+
+/**
+ * @typedef {Object} DraftReachabilityResult
+ * @property {'skipped'|'ok'|'orphans'} status
+ * @property {string[]} reasons
+ * @property {ReachabilityOrphan[]} orphans Empty unless `status` is
+ *   `'orphans'`.
+ * @property {number} scanned Draft stories scanned (0 when skipped).
+ */
+
+/**
+ * Evaluate draft-ticket reachability against the configured navigation
+ * surface.
+ *
+ * @param {object} input
+ * @param {Array<{ slug?: string, title?: string, body?: string }>} input.tickets
+ *   The draft ticket set the persist is about to create (fan-out: the
+ *   authored `tickets.json`; amend: the merged set).
+ * @param {object} [input.config] Resolved `.agentrc.json` (threads
+ *   `planning.navigation`).
+ * @returns {DraftReachabilityResult}
+ */
+export function evaluateDraftReachability({ tickets, config }) {
+  const { routeGlobs, navRegistry } = resolveNavConfig(config);
+
+  if (routeGlobs.length === 0) {
+    return {
+      status: 'skipped',
+      reasons: ['No planning.navigation.routeGlobs configured — skipped.'],
+      orphans: [],
+      scanned: 0,
+    };
+  }
+
+  const stories = Array.isArray(tickets) ? tickets : [];
+  const matchers = routeGlobs.map(globToRegExp);
+  const registryTokens =
+    navRegistry.length > 0
+      ? navRegistry.map((t) => t.toLowerCase())
+      : FALLBACK_REGISTRY_TOKENS;
+
+  // Pass 1: per-story scan — declared paths, route matches, registry refs.
+  const scannedStories = stories.map((story) => {
+    const body = typeof story?.body === 'string' ? story.body : '';
+    const paths = extractStoryPaths(body);
+    const routePaths = paths.filter((p) => matchers.some((rx) => rx.test(p)));
+    const text = [body, story?.title ?? ''].join('\n').toLowerCase();
+    const referencesRegistry = registryTokens.some((tok) => text.includes(tok));
+    return { story, paths, routePaths, referencesRegistry };
+  });
+
+  // Pass 2: navigation owners — every path mentioned by a
+  // registry-referencing story is covered plan-wide.
+  const coveredPaths = new Set();
+  for (const s of scannedStories) {
+    if (!s.referencesRegistry) continue;
+    for (const p of s.paths) coveredPaths.add(p);
+  }
+
+  const orphans = [];
+  for (const s of scannedStories) {
+    if (s.referencesRegistry || s.routePaths.length === 0) continue;
+    const uncovered = s.routePaths.filter((p) => !coveredPaths.has(p));
+    if (uncovered.length === 0) continue;
+    orphans.push({
+      story: s.story?.slug ?? s.story?.title ?? '<unnamed story>',
+      paths: uncovered,
+    });
+  }
+
+  if (orphans.length > 0) {
+    const registryHint =
+      navRegistry.length > 0 ? navRegistry.join(', ') : 'the nav registry';
+    return {
+      status: 'orphans',
+      reasons: [
+        `${orphans.length} route-adding draft story(ies) leave orphan surfaces with no navigation owner (registry: ${registryHint}).`,
+      ],
+      orphans,
+      scanned: stories.length,
+    };
+  }
+
+  return {
+    status: 'ok',
+    reasons: [
+      `${stories.length} draft story(ies) scanned — every route-adding story has a navigation owner.`,
+    ],
+    orphans: [],
+    scanned: stories.length,
+  };
+}
+
+/**
+ * Render the named soft-failure message the persist CLI prints — the
+ * orphan-surface list plus the one-targeted-amend recovery contract.
+ *
+ * @param {DraftReachabilityResult} result A `status: 'orphans'` result.
+ * @returns {string}
+ */
+export function renderReachabilityOrphans(result) {
+  const lines = [
+    '[plan-persist] SOFT FAILURE — reachability orphans (route-glob vs navRegistry):',
+    ...result.orphans.map((o) => `  - ${o.story}: ${o.paths.join(', ')}`),
+    '',
+    'Nothing was written to GitHub. Apply ONE targeted amend to tickets.json',
+    'adding a navigation owner (at most one reachability Story per plan) that',
+    'cites the orphaned routes and the nav registry, then re-run the persist',
+    'once.',
+  ];
+  return lines.join('\n');
+}

package/.agents/scripts/lib/orchestration/plan-runner/worktree-sweep.js

@@ -1,9 +1,9 @@
 /**
  * plan-runner/worktree-sweep.js
  *
- * Reap-sweep used at the start of `/epic-plan-spec` and
- * `/epic-plan-decompose` (via `drainPendingCleanupAtBoot` in
- * `epic-plan-spec.js`, which see). Iterates the `.worktrees/story-<id>/`
+ * Reap-sweep run at plan boot (via `drainPendingCleanupAtBoot` in
+ * `lib/orchestration/epic-plan-spec/phases/drain.js`, wired into
+ * `plan-persist.js`). Iterates the `.worktrees/story-<id>/`
  * entries registered with git, looks up each parent Story, and force-removes
  * any whose Story is already closed or labeled `agent::done`.
  *

package/.agents/scripts/lib/orchestration/planning-risk.js

@@ -138,7 +138,7 @@ function resolveRequiresReview(overallLevel, axes) {
 /**
  * Derive the stable planningRisk envelope from a schema-validated planner
  * verdict. Pure derivation — schema validation happens at the read boundary
- * (`epic-plan-spec.js`), never here, so a malformed verdict fails closed
+ * (`plan-persist.js` via `loadRiskVerdict`), never here, so a malformed verdict fails closed
  * before this function runs.
  *
  * **No-BDD-runner waiver (Story #4145).** The acceptance disposition the risk

package/.agents/scripts/lib/orchestration/remote-verifier.js

@@ -0,0 +1,165 @@
+// .agents/scripts/lib/orchestration/remote-verifier.js
+/**
+ * remote-verifier.js — deterministic "is there a live, pushable remote?"
+ * evidence for the delivery entry seams. Issue #4483.
+ *
+ * `/deliver` could silently shortcut the entire orchestration — building
+ * the delivery inline and committing to local `main` without pushing —
+ * when the driving agent *perceived* the environment had no live GitHub
+ * remote. The judgment was vibes, not fact. This module gives the entry
+ * seams (`epic-deliver-preflight.js`, `single-story-init.js`) a verified
+ * probe result to record in their envelopes so the workflow can branch on
+ * `remoteVerified: true|false` deterministically: use the remote, or
+ * transition to `agent::blocked` quoting the probe output — never a
+ * silent local build.
+ *
+ * Two probes, both bounded (a hung git spawn must not park the entry
+ * seam — mirrors the `ghPrListHead` timeout contract in `finalizer.js`):
+ *
+ *   1. `git remote get-url origin`  — is an `origin` remote configured?
+ *   2. `git ls-remote origin HEAD`  — is it reachable with current auth?
+ *
+ * `remoteVerified` is true only when BOTH succeed. The CLI callers do
+ * NOT flip labels on a false result — the workflow owns the
+ * `agent::blocked` transition (same division of labour as the preflight
+ * breach handling).
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Bounded timeout for each git probe. `ls-remote` is a network call;
+ * SIGKILL at the bound so an unreachable or hanging remote degrades to a
+ * deterministic `remoteVerified: false` instead of a stuck entry seam.
+ */
+export const REMOTE_PROBE_TIMEOUT_MS = 30_000;
+
+function runProbe({ args, cwd, spawnFn, timeoutMs }) {
+  const result = spawnFn('git', args, {
+    cwd,
+    encoding: 'utf-8',
+    shell: false,
+    timeout: timeoutMs,
+    killSignal: 'SIGKILL',
+  });
+  return {
+    args: ['git', ...args].join(' '),
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? '').trim(),
+    stderr: (result.stderr ?? '').trim(),
+  };
+}
+
+/**
+ * Probe the `origin` remote for existence + reachability.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   spawnFn?: typeof spawnSync,
+ *   timeoutMs?: number,
+ * }} [opts]
+ * @returns {{
+ *   remoteVerified: boolean,
+ *   remoteUrl: string|null,
+ *   detail: string,
+ *   probes: {
+ *     getUrl: { args: string, status: number, stdout: string, stderr: string },
+ *     lsRemote: { args: string, status: number, stdout: string, stderr: string }|null,
+ *   },
+ * }}
+ */
+export function verifyRemote({
+  cwd = process.cwd(),
+  spawnFn = spawnSync,
+  timeoutMs = REMOTE_PROBE_TIMEOUT_MS,
+} = {}) {
+  const getUrl = runProbe({
+    args: ['remote', 'get-url', 'origin'],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (getUrl.status !== 0) {
+    return {
+      remoteVerified: false,
+      remoteUrl: null,
+      detail: `no 'origin' remote configured — \`${getUrl.args}\` exited ${getUrl.status}: ${getUrl.stderr || '(no stderr)'}`,
+      probes: { getUrl, lsRemote: null },
+    };
+  }
+  const remoteUrl = getUrl.stdout;
+
+  const lsRemote = runProbe({
+    args: ['ls-remote', 'origin', 'HEAD'],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (lsRemote.status !== 0 || lsRemote.stdout.length === 0) {
+    return {
+      remoteVerified: false,
+      remoteUrl,
+      detail: `'origin' (${remoteUrl}) is unreachable — \`${lsRemote.args}\` exited ${lsRemote.status}: ${lsRemote.stderr || '(empty ls-remote output)'}`,
+      probes: { getUrl, lsRemote },
+    };
+  }
+
+  return {
+    remoteVerified: true,
+    remoteUrl,
+    detail: `origin verified (${remoteUrl}); ls-remote HEAD → ${lsRemote.stdout.split(/\s+/)[0]}`,
+    probes: { getUrl, lsRemote },
+  };
+}
+
+/**
+ * Probe whether a specific branch exists on `origin` — the deterministic
+ * finalize backstop (issue #4483 fix direction 3): a delivery branch that
+ * was never pushed MUST fail finalize with an explicit blocker rather
+ * than let the run declare success.
+ *
+ * Distinct from `git-branch-lifecycle.js#branchExistsRemotely` in two
+ * load-bearing ways: the spawn is bounded (timeout + SIGKILL, so a hung
+ * remote cannot park the finalize seam) and the result carries the probe
+ * detail for the blocker envelope instead of a bare boolean.
+ *
+ * @param {{
+ *   branch: string,
+ *   cwd?: string,
+ *   spawnFn?: typeof spawnSync,
+ *   timeoutMs?: number,
+ * }} opts
+ * @returns {{ exists: boolean, detail: string }}
+ */
+export function probeRemoteBranch({
+  branch,
+  cwd = process.cwd(),
+  spawnFn = spawnSync,
+  timeoutMs = REMOTE_PROBE_TIMEOUT_MS,
+}) {
+  if (typeof branch !== 'string' || branch.length === 0) {
+    throw new TypeError('probeRemoteBranch: branch must be a non-empty string');
+  }
+  const probe = runProbe({
+    args: ['ls-remote', '--heads', 'origin', branch],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (probe.status !== 0) {
+    return {
+      exists: false,
+      detail: `\`${probe.args}\` exited ${probe.status}: ${probe.stderr || '(no stderr)'}`,
+    };
+  }
+  if (probe.stdout.length === 0) {
+    return {
+      exists: false,
+      detail: `\`${probe.args}\` found no ref — ${branch} was never pushed to origin`,
+    };
+  }
+  return {
+    exists: true,
+    detail: `${branch} on origin at ${probe.stdout.split(/\s+/)[0]}`,
+  };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js

@@ -5,6 +5,16 @@
  * subsequent fetches are cheap. A push failure raises so the caller
  * fails non-zero — the operator must resolve before retrying.
  *
+ * Issue #4483 — this phase IS the standalone path's deterministic
+ * land-or-block backstop (the counterpart to the Epic finalize seam's
+ * `delivery-branch-missing-on-origin` blocker). `git push` exits 0 only
+ * after origin has accepted the ref, so the throw below is the origin
+ * assertion: every later close phase (PR open, auto-merge, the
+ * `closeResult` success envelope) is unreachable unless the Story branch
+ * verifiably landed on origin. No post-push `ls-remote` re-probe is
+ * added because it would re-ask a question the push exit code already
+ * answered authoritatively.
+ *
  * `gitSync` is accepted as an injected dependency rather than statically
  * imported so the caller's (cache-busted) binding wins. The
  * `single-story-close.js` orchestrator owns the static import; test

package/.agents/scripts/lib/orchestration/spec-freshness.js

@@ -10,7 +10,7 @@
  *
  * `validateSpecFreshness` scans a Tech Spec body for path-shaped references,
  * probes each against `baseBranchRef` (via `git cat-file -e`), and returns a
- * `{ stale, fresh, ambiguous }` envelope. The caller (epic-plan-spec.js)
+ * `{ stale, fresh, ambiguous }` envelope. The caller (plan-persist.js)
  * uses the result to write a JSON report and post an advisory structured
  * comment on the Epic. The check is intentionally non-blocking —
  * planning continues even when stale references are present, because the

package/.agents/scripts/lib/orchestration/ticketing/bulk.js

@@ -33,7 +33,7 @@ import {
  * 5xx, transport timeouts) inside the cascade transition. Three attempts with
  * exponential backoff (250ms / 500ms / 1000ms) mirrors the budget used by
  * `gitFetchWithRetry` (see `lib/git-utils.js`) and the HTTP-client retry path
- * referenced by `epic-plan-decompose.js`. Backoff is overridable via
+ * referenced by the plan persist surface. Backoff is overridable via
  * {@link __setCascadeRetryDelays} so tests don't pay real wall-clock time.
  */
 const CASCADE_RETRY_BACKOFF_MS = [250, 500, 1000];

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -102,7 +102,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // a `clarity-gate-update` comment on the Epic when the operator approves
   // a sharpened body rewrite, recording the persistence event for audit.
   'clarity-gate-update',
-  // Story #2635 — Phase 7 Tech Spec freshness check. `epic-plan-spec.js`
+  // Story #2635 — Tech Spec freshness check. `plan-persist.js`
   // upserts a `spec-freshness` comment on the Epic listing any
   // path-shaped references that don't exist at the base branch, so the
   // operator can correct drift before Phase 8 decomposes from a stale
@@ -147,7 +147,7 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // the documented remediation actually executable
   // (assertValidStructuredCommentType would otherwise throw).
   'wave-stall',
-  // Story #3873 (Epic #3865) — `epic-plan-spec.js` upserts a `risk-verdict`
+  // Story #3873 (Epic #3865) — `plan-persist.js` upserts a `risk-verdict`
   // comment on the Epic at persist time, recording the planner-authored,
   // schema-validated risk verdict and the planningRisk envelope derived
   // from it (`deriveRiskEnvelope`). One entry per Epic; re-plans upsert in
@@ -171,6 +171,15 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   // `graduator="audit-results|code-review"` attr so the two graduators
   // upsert independent comments; re-runs upsert in place.
   'cross-repo-deferred',
+  // Epic #4474 (PR3) — `plan-persist.js` upserts a single `plan-summary`
+  // comment on the Epic at terminal persist success, carrying the risk /
+  // routing / freshness / healthcheck receipts and the dry-run wave table
+  // as closing text. Replaces the retired plan-time `dispatch-manifest`
+  // comment (whose claimed consumer did not exist — the live manifest is
+  // written at deliver time by `wave-record-io.js`) and the Phase 12
+  // notify round-trip. One entry per Epic; a --force/--resume re-persist
+  // upserts in place.
+  'plan-summary',
 ]);
 
 export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;

package/.agents/scripts/lib/plan-phase-cleanup.js

@@ -41,6 +41,22 @@ export const PHASE_TEMP_BASENAMES = Object.freeze({
     'acceptance-spec.md',
   ]),
   decompose: Object.freeze(['decomposer-context.json', 'tickets.json']),
+  // Epic #4474 (PR3) — the collapsed `plan-persist.js` surface owns every
+  // plan-phase artifact and deletes them ONLY at terminal success (after
+  // the `agent::ready` flip), fixing the mid-pipeline deletion defect where
+  // per-phase cleanup removed artifacts a `--force`/`--resume` re-persist
+  // was still entitled to reuse. `risk-verdict.json` joins the set here:
+  // the split-phase cleanup never owned it, which orphaned it in temp/.
+  // `plan-metrics.json` stays deliberately excluded (PR1) — the ledger
+  // must survive cleanup so the whole plan run is visible in one stream.
+  persist: Object.freeze([
+    'planner-context.json',
+    'techspec.md',
+    'acceptance-spec.md',
+    'risk-verdict.json',
+    'decomposer-context.json',
+    'tickets.json',
+  ]),
 });
 
 /**

package/.agents/scripts/lib/presentation/manifest-persistence.js

@@ -120,10 +120,9 @@ export function deleteLegacyFlatManifest(epicId, opts = {}) {
  * Atomic write-then-rename. On any failure, best-effort remove the `.tmp`
  * file and rethrow so the caller can surface a structured result.
  *
- * Exported so other writers (e.g. `render-manifest.js`) can route their
- * `.md` / `.json` artefact writes through the same crash-safe primitive.
+ * Internal crash-safe write primitive for the manifest artefact pair.
  */
-export function atomicWrite(finalPath, content) {
+function atomicWrite(finalPath, content) {
   const tmpPath = `${finalPath}.tmp`;
   try {
     fs.writeFileSync(tmpPath, content, 'utf8');