mandrel 1.93.0 → 2.0.0

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

@@ -1,97 +1,44 @@
 #!/usr/bin/env node
 
 /**
- * plan-persist.js — single GitHub-write surface for the collapsed /plan
- * flow (Epic #4474, PR3 — design §1 Step 3).
+ * plan-persist.js — flat Story GitHub-write surface for v2 `/plan`
+ * (Stage 3 — `docs/roadmap.md`).
  *
- * Supersedes the retired 12-phase pipeline's separate persist halves
- * (Epic #4474 PR7 — the delegate CLIs are import shims now, deleted next
- * release). Given the author-written planning artifacts
- * (Tech Spec, optional Acceptance Table, risk verdict, tickets JSON), this
- * CLI performs every GitHub mutation of the plan flow in one ordered,
- * fail-closed pass:
+ * Given the author-written planning artifacts (`stories.json` +
+ * `risk-verdict.json`, optional shared Tech Spec), this CLI validates and
+ * creates Story issue(s) directly:
  *
- *   section gate → risk-verdict + mode-coherence → ticket validator /
- *   file-assumption gate / DAG / budget → (ideation: open the Epic) →
- *   Epic lease → managed sections + risk comment + freshness advisory →
- *   story creation (structural reconciler) → inline healthcheck →
- *   single terminal `agent::ready` flip (no intermediate
- *   `agent::review-spec`) → checkpoint v2 + `plan-summary` comment with
- *   the dry-run wave table → temp cleanup at terminal success only.
+ *   risk-verdict → 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.
  *
- * Modes:
- *   --epic <id>          Persist against an existing Epic. Artifact paths
- *                        default to the per-Epic temp tree
- *                        (`temp/epic-<id>/techspec.md`, `risk-verdict.json`,
- *                        `tickets.json`, and `acceptance-spec.md` when
- *                        present).
- *   --one-pager <path>   Ideation mode: render + open the Epic from a
- *                        sharpened one-pager first (folds the former
- *                        Phase 3/4 steps in). Artifact paths must be
- *                        explicit (there is no Epic id to derive them from).
- *
- * Modes (Epic #4474 PR4, design §2 mode matrix): the risk verdict's
- * optional `deliveryShape` field selects between the full fan-out persist
- * (default; requires tickets) and the spec-only single-delivery variant
- * (`deliveryShape: "single"`; NO tickets — the ticket validator + DAG are
- * skipped, fenced by construction, and the `delivery::single` routing
- * marker is applied instead of a Story tree; inert until #4475 lands the
- * deliver-side reader). `--amend` selects the change-request delta path:
- * tickets carry `op: add|modify|keep|close` and the persist maps the ops
- * onto the existing tree.
- *
- * Flags:
- *   --force              Deliberate re-persist: overwrite managed sections,
- *                        close + recreate the story tree (reconciler
- *                        --explicit-delete). Reuses on-disk artifacts —
- *                        cleanup is deferred to terminal success, so a
- *                        failed run leaves them in place.
- *   --resume             Continue a partial persist after a crash
- *                        (rate-limit, network): sections short-circuit
- *                        idempotently, the reconciler creates only the
- *                        missing slugs from its per-slug state ledger.
- *   --amend              Change-request delta persist: every ticket carries
- *                        `op: add|modify|keep|close`; close-and-recreate is
- *                        scoped to modify/close slugs only, keeps are
- *                        untouched, and the DAG is validated over the
- *                        merged set.
- *   --explicit-delete    Confirm the close ops of an --amend plan (mirrors
- *                        epic-reconcile.js). Without it, an amend carrying
- *                        close ops prints the dry-run diff and exits 2.
- *   --steal              Force-transfer a live foreign Epic-lease claim.
- *   --force-review       Operator-forced review routing (recorded in the
- *                        checkpoint's reviewRouting envelope).
+ * 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
  *   --allow-over-budget / --allow-large-fan-out
- *                        Same overrides as the retired split persist.
  *
- * Exit codes: 0 — persist complete, Epic is `agent::ready`; 1 — fatal
- * error (see stderr); 2 — amend close ops require --explicit-delete (the
- * dry-run diff is printed; nothing was mutated); 3 — reachability orphans
- * (Epic #4474 PR6 named soft failure: the deterministic route-glob vs
- * `planning.navigation.navRegistry` scan found route-adding draft stories
- * with no navigation owner — the orphan-surface list is printed, nothing
- * was mutated; apply one targeted amend and re-run the persist once). The
- * Epic lease is released on every exit path.
+ * Exit codes: 0 success; 1 fatal; 3 reachability orphans (nothing mutated).
  */
 
-// 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).
 import './lib/runtime-deps/ensure-installed.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { runAsCli } from './lib/cli-utils.js';
-import { epicArtifactPath } from './lib/config/temp-paths.js';
 import {
-  PROJECT_ROOT,
   resolveConfig,
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import { drainPendingCleanupAtBoot } from './lib/orchestration/epic-plan-spec/phases/drain.js';
-import { loadRiskVerdict } from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
 import {
   readPlanMetrics,
   recordPlanInvocation,
@@ -99,7 +46,6 @@ import {
   summarizePlanMetrics,
 } from './lib/orchestration/plan-metrics.js';
 import {
-  resolveDeliveryMode,
   runPlanPersist,
   writeCheckpointV2,
 } from './lib/orchestration/plan-persist/run-plan-persist.js';
@@ -108,128 +54,139 @@ import {
   buildWaveTable,
   PLAN_SUMMARY_COMMENT_TYPE,
 } from './lib/orchestration/plan-persist/summary.js';
+import { loadRiskVerdict } from './lib/orchestration/planning/risk-verdict.js';
 import { createProvider } from './lib/provider-factory.js';
 
-// Re-exports for the stable public API (tests import through the CLI
-// module, mirroring the plan-context.js CLI-shell shape).
 export {
   buildPlanSummaryCommentBody,
   buildWaveTable,
   PLAN_SUMMARY_COMMENT_TYPE,
-  resolveDeliveryMode,
   runPlanPersist,
   writeCheckpointV2,
 };
 
-export const EPIC_FROM_IDEA_TEMPLATE_PATH = path.resolve(
-  PROJECT_ROOT,
-  '.agents',
-  'templates',
-  'epic-from-idea.md',
-);
-
 const CLI_OPTIONS = {
-  epic: { type: 'string' },
-  'one-pager': { type: 'string' },
-  'tech-spec': { type: 'string' },
-  'acceptance-table': { type: 'string' },
+  stories: { type: 'string' },
   'risk-verdict': { type: 'string' },
-  tickets: { type: 'string' },
-  force: { type: 'boolean', default: false },
-  resume: { type: 'boolean', default: false },
-  steal: { type: 'boolean', default: false },
+  'tech-spec': { type: 'string' },
+  'plan-dir': { type: 'string' },
+  'plan-acceptance': { type: 'string' },
+  'plan-run-id': { type: 'string' },
+  'dry-run': { type: 'boolean', default: false },
   'force-review': { type: 'boolean', default: false },
   'allow-over-budget': { type: 'boolean', default: false },
   'allow-large-fan-out': { type: 'boolean', default: false },
-  amend: { type: 'boolean', default: false },
-  'explicit-delete': { type: 'boolean', default: false },
 };
 
 const USAGE =
-  'Usage: plan-persist.js (--epic <EpicId> | --one-pager <file>) ' +
-  '[--tech-spec <file>] [--acceptance-table <file>] [--risk-verdict <file>] ' +
-  '[--tickets <file>] [--force | --resume | --amend [--explicit-delete]] ' +
-  '[--steal] [--force-review] [--allow-over-budget] [--allow-large-fan-out]';
+  '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] ' +
+  '[--allow-over-budget] [--allow-large-fan-out]';
 
-/**
- * Parse `--epic`; returns null when absent (ideation mode).
- */
-function parseEpicId(rawEpic) {
-  if (rawEpic === undefined) return null;
-  const epicId = Number.parseInt(rawEpic, 10);
-  if (Number.isNaN(epicId)) {
-    throw new Error(
-      `Invalid epic ID: "${rawEpic}" — must be a number.\n${USAGE}`,
-    );
+async function readOptional(filePath, { required }) {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (err) {
+    if (!required && err?.code === 'ENOENT') return null;
+    throw new Error(`Cannot read ${filePath}: ${err.message}`);
   }
-  return epicId;
 }
 
-/**
- * Resolve the artifact file paths. Existing-Epic mode defaults each path to
- * the per-Epic temp tree — the same locations the authoring skill writes to
- * — so a `--force`/`--resume` re-persist reuses the on-disk artifacts with
- * no re-typing (they survive until terminal success now that cleanup is
- * deferred). Ideation mode has no Epic id to derive from, so the paths must
- * be explicit.
- */
-function resolveArtifactPaths({ epicId, values, config }) {
-  const fallback = (basename) =>
-    epicId === null ? undefined : epicArtifactPath(epicId, basename, config);
-  const techSpecPath = values['tech-spec'] ?? fallback('techspec.md');
-  const riskVerdictPath =
-    values['risk-verdict'] ?? fallback('risk-verdict.json');
-  const ticketsPath = values.tickets ?? fallback('tickets.json');
-  const acceptancePath =
-    values['acceptance-table'] ?? fallback('acceptance-spec.md');
-  if (!techSpecPath || !riskVerdictPath) {
+async function readJsonFile(filePath, label) {
+  const raw = await readOptional(filePath, { required: true });
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
     throw new Error(
-      `Missing artifact path(s): ideation mode requires explicit --tech-spec and --risk-verdict.\n${USAGE}`,
+      `Failed to parse ${label} file "${filePath}" as JSON: ${err.message}`,
     );
   }
+}
+
+function resolveInputPaths(values) {
   return {
-    techSpecPath,
-    riskVerdictPath,
-    ticketsPath,
-    acceptancePath,
-    acceptanceExplicit: values['acceptance-table'] !== undefined,
-    ticketsExplicit: values.tickets !== undefined,
+    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,
   };
 }
 
-async function readOptional(filePath, { required }) {
+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 })
+    : null;
+  const planAcceptance = paths.planAcceptancePath
+    ? await readJsonFile(paths.planAcceptancePath, 'plan-acceptance')
+    : null;
+
+  return { stories, riskVerdict, techSpecContent, planAcceptance };
+}
+
+function buildPersistOptions(values, paths) {
+  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'],
+  };
+}
+
+async function runPersistInvocation({ values, config, provider, artifacts }) {
+  const paths = resolveInputPaths(values);
+  const settings = {
+    baseBranch: config.project?.baseBranch,
+    paths: config.project?.paths,
+    planning: config.planning,
+    docsContextFiles: config.project?.docsContextFiles,
+  };
+
+  return recordPlanInvocation(
+    {
+      cli: 'plan-persist',
+      mode: values['dry-run'] ? 'dry-run' : 'persist',
+      config,
+    },
+    () =>
+      runPlanPersist({
+        provider,
+        artifacts,
+        config,
+        settings,
+        opts: buildPersistOptions(values, paths),
+      }),
+  );
+}
+
+async function attachPlanMetrics(result, config) {
   try {
-    return await readFile(filePath, 'utf8');
+    const summary = summarizePlanMetrics(await readPlanMetrics(config));
+    if (summary) {
+      result.planMetrics = summary;
+      Logger.info(`[plan-persist] ${renderPlanMetricsSummaryLine(summary)}`);
+    }
   } catch (err) {
-    if (!required && err?.code === 'ENOENT') return null;
-    throw new Error(`Cannot read ${filePath}: ${err.message}`);
+    Logger.warn(`[plan-persist] plan-metrics summary skipped: ${err.message}`);
   }
 }
 
 async function main() {
   const { values } = parseArgs({ options: CLI_OPTIONS });
 
-  if (values.force && values.resume) {
-    throw new Error('--force and --resume are mutually exclusive.');
-  }
-  if (values.amend && (values.force || values.resume)) {
-    throw new Error(
-      '--amend is mutually exclusive with --force/--resume — the amend ' +
-        'delta is already an incremental re-persist.',
-    );
-  }
-
-  const epicId = parseEpicId(values.epic);
-  const onePagerPath = values['one-pager'];
-  if (epicId === null && !onePagerPath) {
+  if (!values.stories || !values['risk-verdict']) {
     throw new Error(USAGE);
   }
-  if (epicId !== null && onePagerPath) {
-    throw new Error(
-      '--epic and --one-pager are mutually exclusive (ideation mode opens ' +
-        `the Epic itself).\n${USAGE}`,
-    );
-  }
 
   let config;
   try {
@@ -238,123 +195,19 @@ async function main() {
   } catch (err) {
     throw new Error(`Config schema validation failed:\n${err.message}`);
   }
-  const settings = {
-    baseBranch: config.project?.baseBranch,
-    paths: config.project?.paths,
-    planning: config.planning,
-    docsContextFiles: config.project?.docsContextFiles,
-  };
   const provider = createProvider(config);
+  const paths = resolveInputPaths(values);
+  const artifacts = await loadArtifacts(paths);
 
+  let result;
   try {
-    await drainPendingCleanupAtBoot({
-      repoRoot: PROJECT_ROOT,
+    result = await runPersistInvocation({
+      values,
       config,
       provider,
+      artifacts,
     });
   } catch (err) {
-    Logger.warn(`[plan-persist] pending-cleanup drain skipped: ${err.message}`);
-  }
-
-  const {
-    techSpecPath,
-    riskVerdictPath,
-    ticketsPath,
-    acceptancePath,
-    acceptanceExplicit,
-    ticketsExplicit,
-  } = resolveArtifactPaths({ epicId, values, config });
-
-  // Deterministic local reads + validation before any GitHub call. A
-  // malformed risk verdict fails closed here (Epic #3865); the section
-  // gate itself runs first inside runPlanPersist.
-  const techSpecContent = await readOptional(techSpecPath, { required: true });
-  const riskVerdict = loadRiskVerdict(riskVerdictPath);
-  // Tickets are mode-dependent (#4474 PR4): required when explicitly
-  // passed or in --amend mode; otherwise best-effort — a single-delivery
-  // plan authors no tickets file at all, and the mode-coherence gate
-  // (`resolveDeliveryMode`) hard-errors on every contradictory combination
-  // (including a stale tickets.json next to a `deliveryShape: "single"`
-  // verdict).
-  const ticketsRequired = ticketsExplicit || values.amend;
-  const ticketsRaw = ticketsPath
-    ? await readOptional(ticketsPath, { required: ticketsRequired })
-    : null;
-  let tickets = null;
-  if (ticketsRaw !== null) {
-    try {
-      tickets = JSON.parse(ticketsRaw);
-    } catch (err) {
-      throw new Error(
-        `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
-      );
-    }
-  }
-  // Acceptance table: explicit path is required to exist; the per-Epic
-  // default is best-effort (absent file → no acceptance section, matching
-  // the waived/none dispositions).
-  const acceptanceSpecContent = acceptancePath
-    ? await readOptional(acceptancePath, { required: acceptanceExplicit })
-    : null;
-  const onePagerContent = onePagerPath
-    ? await readOptional(onePagerPath, { required: true })
-    : null;
-  const templateContent = onePagerContent
-    ? await readOptional(EPIC_FROM_IDEA_TEMPLATE_PATH, { required: true })
-    : null;
-
-  // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode. Ideation runs
-  // have no Epic id at entry, so they stamp on the standalone stream.
-  const mode = values.amend
-    ? 'amend'
-    : values.resume
-      ? 'resume'
-      : values.force
-        ? 'force'
-        : 'persist';
-  let result;
-  try {
-    result = await recordPlanInvocation(
-      { cli: 'plan-persist', mode, epicId, config },
-      () =>
-        runPlanPersist({
-          epicId,
-          provider,
-          artifacts: {
-            techSpecContent,
-            acceptanceSpecContent,
-            riskVerdict,
-            tickets,
-            onePagerContent,
-            templateContent,
-          },
-          config,
-          settings,
-          opts: {
-            force: values.force,
-            resume: values.resume,
-            amend: values.amend,
-            explicitDelete: values['explicit-delete'],
-            steal: values.steal,
-            forceReview: values['force-review'],
-            allowOverBudget: values['allow-over-budget'],
-            allowLargeFanOut: values['allow-large-fan-out'],
-          },
-        }),
-    );
-  } catch (err) {
-    // Amend close-op confirmation gate (exit 2, mirroring the
-    // epic-reconcile.js contract): print the dry-run diff so the operator
-    // reviews exactly what would close, mutate nothing, and exit 2 so
-    // non-interactive callers can branch on the code.
-    if (err?.code === 'PLAN_AMEND_EXPLICIT_DELETE_REQUIRED') {
-      process.stdout.write(`${err.diff}\n\n${err.message}\n`);
-      process.exitCode = 2;
-      return;
-    }
-    // Reachability soft failure (#4474 PR6): the orphan-surface list is the
-    // message; nothing was mutated (the check runs before any provider
-    // call). Exit 3 so non-interactive callers can branch on the code.
     if (err?.code === 'PLAN_REACHABILITY_ORPHANS') {
       process.stdout.write(`${err.message}\n`);
       process.exitCode = 3;
@@ -363,19 +216,7 @@ async function main() {
     throw err;
   }
 
-  // Surface the whole plan run's invocation ledger in the persist summary
-  // (#4474 PR1). Additive and best-effort.
-  try {
-    const summary = summarizePlanMetrics(
-      await readPlanMetrics(result.epicId, config),
-    );
-    if (summary) {
-      result.planMetrics = summary;
-      Logger.info(`[plan-persist] ${renderPlanMetricsSummaryLine(summary)}`);
-    }
-  } catch (err) {
-    Logger.warn(`[plan-persist] plan-metrics summary skipped: ${err.message}`);
-  }
+  await attachPlanMetrics(result, config);
 
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * plan-run-epilogue.js — execute the real per-run closeout for
+ * `/deliver --run <planRunId>` and positional multi-Story delivers.
+ *
+ * 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.
+ */
+
+import './lib/runtime-deps/ensure-installed.js';
+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' },
+};
+
+/**
+ * @param {string[]} [argv]
+ * @returns {Promise<object>}
+ */
+export async function main(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    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]',
+    );
+  }
+  const cwd =
+    typeof values.cwd === 'string' && values.cwd.trim()
+      ? values.cwd.trim()
+      : process.cwd();
+  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);
+  }
+
+  const planRunId =
+    runFlag || `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
+
+  const result = await runPlanRunEpilogue({
+    planRunId,
+    stories,
+    provider,
+    config,
+    cwd,
+  });
+  Logger.info(JSON.stringify(result, null, 2));
+  if (result.errors?.length) {
+    process.exitCode = 1;
+  }
+  return result;
+}
+
+await runAsCli(import.meta.url, main);

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

@@ -22,6 +22,10 @@ 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,
@@ -37,6 +41,11 @@ 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.
 `;
 
@@ -64,6 +73,8 @@ 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,
@@ -115,6 +126,33 @@ 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,