mandrel 2.0.0 → 2.2.0

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

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/**
+ * plan-critics.js — the /plan critic-dispatch verdict CLI (Story #4592).
+ *
+ * `/plan` step 2.5 (between Author and Persist) runs this against the draft
+ * `stories.json`. It evaluates the consolidation + pre-mortem dispatch
+ * conditions 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.
+ *
+ * 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 carrying the
+ *                        `## Delivery Slicing` table the consolidation
+ *                        precondition reads.
+ *
+ * stdout is reserved for the verdict JSON (Story #2278 discipline):
+ *
+ *   {
+ *     "consolidation": { "critic": "consolidation", "dispatch": false, "reasons": [...] },
+ *     "premortem":     { "critic": "pre-mortem",    "dispatch": true,  "reasons": [...] },
+ *     "textHygiene":   { "critic": "text-hygiene",  "findings": [...] }
+ *   }
+ *
+ * `textHygiene` (Story #4599) is advisory-only: deterministic body lints with
+ * no dispatch semantics — its findings fold into the re-author round.
+ *
+ * Human-readable log lines go to stderr, matching the sibling `plan-persist`.
+ *
+ * Exit codes: 0 success (any verdict); 1 usage/IO error.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { evaluatePlanCritics } from './lib/orchestration/plan-critics-evaluate.js';
+import { appendCriticSkip } from './lib/orchestration/plan-metrics.js';
+
+const CLI_OPTIONS = {
+  stories: { type: 'string' },
+  'tech-spec': { type: 'string' },
+};
+
+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';
+
+/**
+ * Read the draft artifacts the critics evaluate.
+ *
+ * @param {{ storiesPath: string, techSpecPath?: string|null }} paths
+ * @returns {Promise<{ tickets: object[], techSpecContent: string }>}
+ */
+export async function loadCriticArtifacts({
+  storiesPath,
+  techSpecPath = null,
+}) {
+  const raw = await readFile(storiesPath, 'utf8');
+  let tickets;
+  try {
+    tickets = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse stories file "${storiesPath}" as JSON: ${err.message}`,
+    );
+  }
+  if (!Array.isArray(tickets)) {
+    throw new Error(`Stories file "${storiesPath}" must contain a JSON array.`);
+  }
+  const techSpecContent = techSpecPath
+    ? await readFile(techSpecPath, 'utf8')
+    : '';
+  return { tickets, techSpecContent };
+}
+
+/**
+ * Log each decision and record every skip on the plan-metrics ledger. The
+ * ledger write is best-effort by `appendCriticSkip`'s own contract — it can
+ * never fail the plan step.
+ *
+ * @param {{ consolidation: object, premortem: object, textHygiene?: object }} verdict
+ * @param {object} config
+ * @param {{ append?: typeof appendCriticSkip }} [deps]
+ * @returns {Promise<void>}
+ */
+export async function recordCriticSkips(
+  verdict,
+  config,
+  { append = appendCriticSkip } = {},
+) {
+  for (const decision of [verdict.consolidation, verdict.premortem]) {
+    Logger.info(
+      `[plan-critics] critic ${decision.critic}: ` +
+        `${decision.dispatch ? 'dispatch' : 'skip'} — ` +
+        decision.reasons.join('; '),
+    );
+    if (!decision.dispatch) {
+      await append(
+        {
+          critic: decision.critic,
+          reasons: decision.reasons,
+          cli: PLAN_CRITICS_CLI,
+        },
+        config,
+      );
+    }
+  }
+
+  // Text hygiene (Story #4599) is advisory-only — no dispatch semantics, so
+  // "skip" here means "zero findings". Recording that keeps the lint's
+  // fire/skip accounting on the same ledger as the dispatching critics.
+  const hygiene = verdict.textHygiene;
+  if (hygiene) {
+    const count = hygiene.findings.length;
+    Logger.info(
+      `[plan-critics] critic ${hygiene.critic}: ${count} finding(s) (advisory).`,
+    );
+    if (count === 0) {
+      await append(
+        {
+          critic: hygiene.critic,
+          reasons: ['No text-hygiene findings over the draft stories.'],
+          cli: PLAN_CRITICS_CLI,
+        },
+        config,
+      );
+    }
+  }
+}
+
+/**
+ * Load the artifacts, evaluate both critics, record the skips, 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,
+ *   config?: object,
+ *   append?: typeof appendCriticSkip,
+ * }} args
+ * @returns {Promise<{ consolidation: object, premortem: object, textHygiene: object }>}
+ */
+export async function evaluateCriticArtifacts({
+  storiesPath,
+  techSpecPath = null,
+  config = {},
+  append = appendCriticSkip,
+}) {
+  const { tickets, techSpecContent } = await loadCriticArtifacts({
+    storiesPath,
+    techSpecPath,
+  });
+  const verdict = evaluatePlanCritics({ techSpecContent, tickets, config });
+  await recordCriticSkips(verdict, config, { append });
+  return verdict;
+}
+
+async function main() {
+  const { values } = parseArgs({ options: CLI_OPTIONS });
+
+  if (!values.stories) {
+    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.
+  routeAllOutputToStderr();
+
+  const verdict = await evaluateCriticArtifacts({
+    storiesPath: path.resolve(values.stories),
+    techSpecPath: values['tech-spec']
+      ? path.resolve(values['tech-spec'])
+      : null,
+    config: resolveConfig(),
+  });
+
+  process.stdout.write(`${JSON.stringify(verdict, null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'plan-critics',
+  propagateExitCode: true,
+});

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

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

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

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