mandrel 1.68.0 → 1.69.0

package/.agents/scripts/lib/orchestration/wave-record-projection.js

@@ -1,37 +1,31 @@
 /**
- * wave-record-projection.js — pure projection helpers for the record-wave CLI.
+ * wave-record-projection.js — pure helpers for the per-Story status
+ * recorder CLI (`epic-execute-record-wave.js`).
  *
- * This module is the post-wave-record projection layer extracted from
- * `.agents/scripts/epic-execute-record-wave.js`. Every export here is pure:
- * no network I/O, no filesystem reads, no spawning. The parent CLI handles
- * the impure work (provider calls, checkpoint reads/writes, webhook emits,
- * manifest refresh) and threads the resolved inputs through these helpers
- * to produce the wave's new checkpoint record, rollup rows, and envelope
- * fields.
+ * Story #4155 (Epic #4151) — the Epic `/deliver` runtime cut over from the
+ * wave-batch scheduler to the continuous ready-set core. The post-dispatch
+ * persistence shrank with it: there is no longer a wave-level aggregation
+ * (`aggregateWaveStatus`), a `currentWave` advance (`nextCurrentWave`), a
+ * next-action classifier (`classifyWaveOutcome`), or a `projectWaveRecord`
+ * splice into a `waves[]` history. The recorder now writes each returned
+ * Story's **terminal status** into the checkpoint's flat per-Story `stories`
+ * map and re-renders the operator rollup from that map.
+ *
+ * Every export here is pure: no network I/O, no filesystem reads, no
+ * spawning. The parent CLI handles the impure work (provider calls,
+ * checkpoint reads/writes, webhook emits) and threads the resolved inputs
+ * through these helpers.
  *
  * Group the exports by responsibility:
  *
  *   - Input validation: `validateResults`, `validateReturnsEntry`,
- *     `classifyParsedReturn`, `validateEpicWave`, `validateResultsReturnsXor`,
- *     `selectInputFlag`, `resolveConcurrencyCap`.
- *   - Aggregation: `aggregateWaveStatus`, `countDoneStories`,
- *     `classifyWaveOutcome`.
- *   - Projection: `toRollupRow`, `projectWaveRecord`.
- *
- * The aggregator `projectWaveRecord` is the entry point: given the verified
- * per-Story rows, the prior checkpoint, the wave index, the resolved
- * concurrency cap, and a `titleById` map, it returns every derived shape the
- * CLI needs to (a) write the next checkpoint, (b) render `epic-run-progress`,
- * (c) classify the next slash-command action, and (d) assemble the stdout
- * envelope. It is the single source of truth for "what does the wave look
- * like after these results land?"
+ *     `classifyParsedReturn`, `validateEpic`, `selectInputFlag`.
+ *   - Normalization: `normalizeReturnsPure`.
+ *   - Projection: `toRollupRow`.
  */
 
 import { parseStoryAgentReturn } from './epic-runner/sub-agent-return.js';
 
-/** Valid wave-level rollup statuses. */
-export const VALID_RESULT_STATUSES = new Set(['complete', 'blocked', 'failed']);
-
 /** Per-Story return statuses we accept off `/deliver` sub-agents. */
 export const VALID_STORY_STATUSES = new Set(['done', 'blocked', 'failed']);
 
@@ -130,57 +124,6 @@ export function classifyParsedReturn(parsed, storyId) {
   return { ok: false, error };
 }
 
-/**
- * Aggregate validated per-Story rows into the wave-level outcome. Pure.
- *
- * @param {Array<{ storyId: number, status: string }>} results
- */
-export function aggregateWaveStatus(results) {
-  const rows = Array.isArray(results) ? results : [];
-  const failed = rows.filter((r) => r.status === 'failed');
-  const blocked = rows.filter((r) => r.status === 'blocked');
-  let status;
-  if (failed.length > 0) {
-    status = 'failed';
-  } else if (blocked.length > 0) {
-    status = 'blocked';
-  } else {
-    status = 'complete';
-  }
-  return {
-    status,
-    blockedStoryIds: blocked.map((r) => r.storyId),
-  };
-}
-
-/**
- * Classify the wave outcome into the next operator action. Pure helper —
- * exported so tests can pin each branch without touching the provider.
- *
- * @param {{ resultStatus: string, currentWave: number, totalWaves: number }} args
- */
-export function classifyWaveOutcome({ resultStatus, currentWave, totalWaves }) {
-  const remainingWaves = Math.max(
-    0,
-    Number(totalWaves) - (Number(currentWave) + 1),
-  );
-  if (resultStatus === 'blocked') {
-    return { nextAction: 'halt-blocked', remainingWaves };
-  }
-  if (resultStatus === 'failed') {
-    return { nextAction: 'halt-failed', remainingWaves };
-  }
-  if (resultStatus === 'complete') {
-    return {
-      nextAction: remainingWaves > 0 ? 'dispatch-next' : 'finalize',
-      remainingWaves,
-    };
-  }
-  throw new RangeError(
-    `classifyWaveOutcome: resultStatus "${resultStatus}" must be one of: ${[...VALID_RESULT_STATUSES].join(', ')}`,
-  );
-}
-
 /**
  * Build the rollup-row shape the unified `epic-run-progress` writer
  * consumes. Returns `{ id, title, state, blockerCommentId? }`.
@@ -197,64 +140,13 @@ export function toRollupRow(verified, titleById) {
   return row;
 }
 
-/** Pure: count Stories already marked `done` across every recorded wave. */
-export function countDoneStories(waves) {
-  return waves.reduce(
-    (acc, w) =>
-      acc +
-      (Array.isArray(w.stories)
-        ? w.stories.filter((s) => s?.state === 'done').length
-        : 0),
-    0,
-  );
-}
-
-/** Validate the core `{ epicId, wave }` invariants. Throws on bad input. */
-export function validateEpicWave(epicId, wave) {
+/** Validate the core `{ epicId }` invariant. Throws on bad input. */
+export function validateEpic(epicId) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     throw new TypeError(
       'runEpicExecuteRecordWave: --epic must be a positive integer',
     );
   }
-  if (!Number.isInteger(wave) || wave < 0) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: --wave must be a non-negative integer',
-    );
-  }
-}
-
-/** Validate the `results`/`returns` XOR. Throws on bad input. */
-export function validateResultsReturnsXor(results, returns) {
-  if (results == null && returns == null) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: either `results` or `returns` is required',
-    );
-  }
-  if (results != null && returns != null) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: pass `results` OR `returns`, not both',
-    );
-  }
-}
-
-/** Resolve the effective concurrency cap, honouring CLI > checkpoint > config. */
-export function resolveConcurrencyCap(
-  concurrencyCapOverride,
-  existing,
-  deliverRunner,
-) {
-  const cap =
-    concurrencyCapOverride ??
-    Number(existing.concurrencyCap) ??
-    Number(deliverRunner.concurrencyCap) ??
-    1;
-  if (!Number.isInteger(cap) || cap < 1) {
-    throw new RangeError(
-      `runEpicExecuteRecordWave: resolved concurrencyCap "${cap}" must be a positive integer; ` +
-        'pass --concurrency-cap or set `orchestration.runners.deliverRunner.concurrencyCap`.',
-    );
-  }
-  return cap;
 }
 
 /**
@@ -292,7 +184,7 @@ export function selectInputFlag(hasResults, hasReturns) {
  * @param {(args: { storyId: number }) => Promise<object> | object} [args.reconcile]
  *   Optional async hook used to fetch a fallback row when parsing fails. If
  *   omitted, parse failures push a placeholder `{ storyId, status: 'failed' }`
- *   row so the caller can still aggregate without I/O.
+ *   row so the caller can still record without I/O.
  */
 export async function normalizeReturnsPure({ returns, reconcile } = {}) {
   if (!Array.isArray(returns)) {
@@ -318,100 +210,3 @@ export async function normalizeReturnsPure({ returns, reconcile } = {}) {
   }
   return { results, parseFailures };
 }
-
-/**
- * Project the post-wave-record state from verified per-Story rows. Pure
- * end-to-end: every derived field the CLI needs after `verifyWaveResults`
- * lands here. The CLI hands us the verified rows, the existing checkpoint
- * (so we can splice this wave's record), the wave index, the resolved cap,
- * the manifest title map, and a `now` clock.
- *
- * Returns the union of:
- *   - the new `epic-run-state` shape (`nextWaves`, `nextCurrentWave`,
- *     `totalWaves`),
- *   - the rollup payload (`rollupRows`, `rollupWaves`),
- *   - the wave-level outcome (`status`, `blockedStoryIds`),
- *   - the slash-command next action (`nextAction`, `remainingWaves`).
- *
- * The CLI handles I/O around this projection: writing the checkpoint,
- * upserting `epic-run-progress`, emitting webhooks, refreshing the local
- * manifest. None of those impure side-effects live here.
- *
- * @param {object} args
- * @param {number} args.wave
- * @param {Array<object>} args.verified
- * @param {object} args.existing
- * @param {number} args.concurrencyCap
- * @param {Map<number, string>} args.titleById
- * @param {() => Date} [args.now]
- */
-export function projectWaveRecord({
-  wave,
-  verified,
-  existing,
-  concurrencyCap,
-  titleById,
-  now = () => new Date(),
-} = {}) {
-  if (!Number.isInteger(wave) || wave < 0) {
-    throw new TypeError(
-      'projectWaveRecord: wave must be a non-negative integer',
-    );
-  }
-  if (!existing || typeof existing !== 'object') {
-    throw new TypeError('projectWaveRecord: existing checkpoint is required');
-  }
-  if (!(titleById instanceof Map)) {
-    throw new TypeError('projectWaveRecord: titleById must be a Map');
-  }
-
-  const totalWaves = Number(existing.totalWaves ?? 0);
-  const verifiedRows = Array.isArray(verified) ? verified : [];
-
-  const { status, blockedStoryIds } = aggregateWaveStatus(verifiedRows);
-  const rollupRows = verifiedRows.map((r) => toRollupRow(r, titleById));
-
-  const priorWaves = Array.isArray(existing.waves) ? existing.waves : [];
-  const newRecord = {
-    index: wave,
-    status,
-    concurrencyCap,
-    stories: rollupRows,
-    completedAt: now().toISOString(),
-  };
-  const filtered = priorWaves.filter((w) => Number(w?.index) !== Number(wave));
-  const nextWaves = [...filtered, newRecord].sort(
-    (a, b) => Number(a.index) - Number(b.index),
-  );
-
-  const nextCurrentWave =
-    status === 'complete'
-      ? Math.min(totalWaves, wave + 1)
-      : Number(existing.currentWave ?? wave);
-
-  const rollupWaves = nextWaves.map((w) => ({
-    wave: Number(w.index),
-    concurrencyCap: Number(w.concurrencyCap) || concurrencyCap,
-    stories: Array.isArray(w.stories) ? w.stories : [],
-  }));
-
-  const { nextAction, remainingWaves } = classifyWaveOutcome({
-    resultStatus: status,
-    currentWave: wave,
-    totalWaves,
-  });
-
-  return {
-    status,
-    blockedStoryIds,
-    rollupRows,
-    newRecord,
-    priorWaves,
-    nextWaves,
-    nextCurrentWave,
-    totalWaves,
-    rollupWaves,
-    nextAction,
-    remainingWaves,
-  };
-}

package/.agents/scripts/lib/presentation/dispatch-manifest-render.js

@@ -8,23 +8,40 @@
  *
  * No top-level side effects — safe to import from tests without
  * triggering GitHub I/O.
+ *
+ * Story #4157 — each projected story's `wave` is a **render-time
+ * dependency depth** derived from the manifest's `dependsOn` edges via the
+ * shared `deriveStoryDepths` lens (`manifest-render-waves.js`, built on
+ * `assignLayers`), not the persisted `earliestWave`. Scheduling no longer
+ * stamps a wave field onto the run checkpoint (Epic #4151 / Story #4155),
+ * so the rollup re-derives depth from the dependency graph at render time.
  */
 
+import { deriveStoryDepths } from './manifest-render-waves.js';
+
 /**
  * Pure: project a full dispatch manifest into the `{ stories }` shape
  * `renderManifest` accepts. Returns the canonical, non-ungrouped story
  * rows used by the Epic-level dispatch-manifest comment.
  *
+ * The `wave` field is the render-time dependency depth (Story #4157):
+ * `deriveStoryDepths` runs `assignLayers` over the entries' `dependsOn`
+ * edges, so a Story with no in-set dependency is wave 0 and a dependent
+ * sits one layer deeper than its deepest dependency. Entries the lens
+ * cannot place (e.g. a non-integer storyId that survives the sentinel
+ * filter) fall back to `-1`.
+ *
  * @param {object} manifest
  * @returns {{ storyId: number|string, wave: number, title: string }[]}
  */
 export function projectStoriesFromManifest(manifest) {
   const storyManifest = manifest?.storyManifest ?? [];
+  const depths = deriveStoryDepths(storyManifest);
   return storyManifest
     .filter((s) => s && s.storyId !== '__ungrouped__')
     .map((s) => ({
       storyId: s.storyId,
-      wave: s.earliestWave ?? -1,
+      wave: depths.get(s.storyId) ?? -1,
       title: s.storyTitle ?? s.storySlug ?? '',
     }));
 }

package/.agents/scripts/lib/presentation/manifest-render-waves.js

@@ -17,15 +17,81 @@
  * Imports the small pure helpers from `manifest-helpers.js` — the
  * formatter re-exports them so existing call-sites that read these
  * names off `manifest-formatter.js` keep working.
+ *
+ * Story #4157 — the per-wave grouping key is now a **render-time
+ * dependency depth** derived from each Story entry's `dependsOn` edges via
+ * `assignLayers` (`lib/Graph.js`), not the persisted `earliestWave` field
+ * the planner stamped on the manifest. Scheduling no longer persists waves
+ * onto the run checkpoint (Epic #4151 / Story #4155), so the rollup
+ * re-derives depth from the dependency graph at the moment it renders. The
+ * shared `deriveStoryDepths` lens below is the single home for that
+ * derivation; `dispatch-manifest-render.js` imports it so both
+ * operator-facing surfaces group by the same render-time depths.
  */
 
+import { assignLayers } from '../Graph.js';
 import { AGENT_LABELS } from '../label-constants.js';
+import { buildStoryAdjacency } from '../story-adjacency.js';
 import {
   deriveStorySymbol,
   deriveWaveStatus,
   waveHeadingText,
 } from './manifest-helpers.js';
 
+// ---------------------------------------------------------------------------
+// Render-time dependency-depth lens (Story #4157)
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a render-time dependency depth for every Story entry in a
+ * `storyManifest`, keyed by storyId.
+ *
+ * The depth is computed by feeding the entries' `dependsOn` edges through
+ * the canonical `buildStoryAdjacency` builder (the same one the dispatch
+ * pipeline and `stories-wave-tick.js` use) and then `assignLayers`
+ * (`lib/Graph.js`): a Story with no dependency edges is depth 0, and a
+ * Story sits one layer deeper than its deepest in-set dependency. This
+ * replaces the planner's persisted `earliestWave` as the grouping key so
+ * the rollup renders correctly from the per-Story checkpoint shape, which
+ * no longer carries a wave field (Epic #4151 / Story #4155).
+ *
+ * `buildStoryAdjacency` reads each entry's id from `id ?? number`, so the
+ * entries are adapted to expose `id: storyId` and `dependsOn`. Foreign
+ * edges (pointing outside the supplied entry set) are dropped — the
+ * default `dropForeign: true` — so the DAG stays closed over the rendered
+ * Stories and depth never deepens on a reference the rollup cannot show.
+ * The ungrouped sentinel (`storyId === '__ungrouped__'`) and any non-object
+ * entry are skipped; they never participate in the graph.
+ *
+ * Pure: no IO, no clock. Returns a `Map<storyId, depth>` covering exactly
+ * the graph-eligible entries.
+ *
+ * @param {object[]} storyManifest
+ * @returns {Map<number|string, number>}
+ */
+export function deriveStoryDepths(storyManifest) {
+  if (!Array.isArray(storyManifest)) return new Map();
+  const eligible = storyManifest.filter(
+    (s) =>
+      s !== null &&
+      typeof s === 'object' &&
+      s.storyId !== '__ungrouped__' &&
+      Number.isInteger(Number(s.storyId)),
+  );
+  const records = eligible.map((s) => ({
+    id: Number(s.storyId),
+    dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn : [],
+  }));
+  const adjacency = buildStoryAdjacency(records);
+  const layers = assignLayers(adjacency);
+
+  const depths = new Map();
+  for (const s of eligible) {
+    depths.set(s.storyId, layers.get(Number(s.storyId)) ?? 0);
+  }
+  return depths;
+}
+
 // ---------------------------------------------------------------------------
 // ---------------------------------------------------------------------------
 
@@ -90,14 +156,20 @@ function pickWaveTail(status, waveIdx, sortedWaves, storyCount) {
  * (a Story is "done" when it carries `agent::done`) — the unit
  * `deriveWaveStatus` consumes.
  *
+ * Story #4157 — the bucket key is the render-time dependency depth from
+ * `depths` (keyed by storyId), not the persisted `earliestWave`. The
+ * ungrouped sentinel and any entry the lens could not place fall into the
+ * `-1` "Ungrouped" bucket so they still render.
+ *
  * @param {object[]} waveStories
+ * @param {Map<number|string, number>} depths
  * @returns {{ waveGroups: Map<number, object[]>, waveStats: Map<number, { total: number, done: number }> }}
  */
-function groupStoriesByWave(waveStories) {
+function groupStoriesByWave(waveStories, depths) {
   const waveGroups = new Map();
   const waveStats = new Map();
   for (const story of waveStories) {
-    const w = story.earliestWave ?? -1;
+    const w = depths.get(story.storyId) ?? -1;
     if (!waveGroups.has(w)) {
       waveGroups.set(w, []);
       waveStats.set(w, { total: 0, done: 0 });
@@ -126,7 +198,8 @@ export function renderNestedWaveSections(storyManifest) {
     validateWaveSection('story', s),
   );
 
-  const { waveGroups, waveStats } = groupStoriesByWave(waveStories);
+  const depths = deriveStoryDepths(waveStories);
+  const { waveGroups, waveStats } = groupStoriesByWave(waveStories, depths);
   const sortedWaves = [...waveGroups.keys()].sort((a, b) => a - b);
   const lines = [];
 
@@ -230,4 +303,4 @@ function renderImplicitDepBullet(finding) {
 
 // Test-only: surface the private predicate so the sibling unit test can
 // exercise each branch without going through the full renderer.
-export const __testables = { validateWaveSection };
+export const __testables = { validateWaveSection, groupStoriesByWave };

package/.agents/scripts/lib/story-adjacency.js

@@ -1,18 +1,21 @@
 /**
  * lib/story-adjacency.js — the single story-level adjacency builder.
  *
- * All three wave-computation wrappers bottom out in the shared
- * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` /
- * `computeWaves`), but each historically re-implemented the step that
- * turns a list of Story records into the `Map<storyId, number[]>`
- * adjacency the kernel consumes. This module is now the one home for
- * that step; the consumers are:
+ * Both Epic-path wave-computation wrappers bottom out in the shared
+ * `lib/Graph.js` kernel (`detectCycle` / `assignLayers` / `computeWaves`),
+ * but each historically re-implemented the step that turns a list of Story
+ * records into the `Map<storyId, number[]>` adjacency the kernel consumes.
+ * This module is now the one home for that step; the consumers are:
  *
  *   - `lib/orchestration/epic-runner/phases/build-wave-dag.js`
  *     (`buildStoryDag` → `computeWaves`)
  *   - `lib/orchestration/dispatch-pipeline.js`
  *     (`buildStoryDispatchGraph` → `computeStoryWaves`)
- *   - `stories-wave-tick.js` (`buildAdjacency` → `assignLayers`)
+ *   - `lib/wave-runner/ready-set.js` (`selectReadySet`, the path-agnostic
+ *     continuous scheduler the standalone `stories-wave-tick.js` adapter
+ *     and the Epic path both dispatch through)
+ *   - `stories-wave-tick.js` (for cycle detection, before delegating
+ *     selection to `selectReadySet`)
  *
  * Dependency source order (must stay aligned with manifest-builder.js so
  * the dispatch manifest and runtime wave scheduling never disagree):
@@ -45,9 +48,10 @@ import { parseBlockedBy } from './dependency-parser.js';
  * @param {boolean} [opts.dropForeign=true] When true (the default,
  *   matching the Epic-scoped wrappers), edges pointing at ids outside
  *   the supplied story set are dropped so the DAG stays closed over the
- *   scheduled set. `stories-wave-tick.js` passes `false` to preserve its
- *   historical operator-DAG contract, where a dependency on an id absent
- *   from the input still deepens the dependent's layer.
+ *   scheduled set. The standalone path (`stories-wave-tick.js` and the
+ *   `selectReadySet` core) passes `false` to preserve the operator-DAG
+ *   contract, where a dependency on an id absent from the input is treated
+ *   as not-yet-done and withholds the dependent until it completes.
  * @returns {Map<number, number[]>}
  */
 export function buildStoryAdjacency(stories, { dropForeign = true } = {}) {

package/.agents/scripts/lib/story-body/story-body.js

@@ -16,6 +16,7 @@
  *   verify:              string[],         // exact commands / tier annotation
  *   references:          PathEntry[],      // read-only paths (optional)
  *   wide:                { reason } | null,// declared-wide footprint (optional)
+ *   reason_to_exist:     string | null,    // one-sentence cohesion reason (optional)
  *   depends_on:          string[],         // blocker story slugs or #ids
  *   estimated_test_files: number | null,   // absent → null (informational)
  * }
@@ -69,6 +70,7 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  * @property {string[]}      verify              - Exact commands with tier annotation.
  * @property {PathEntry[]}   references          - Read-only paths (may be empty).
  * @property {{ reason: string }|null} wide      - Declared-wide footprint (reason), or null.
+ * @property {string|null}   reason_to_exist     - One-sentence cohesion reason ("why this Story exists"), or null.
  * @property {string[]}      depends_on          - Blocking story slugs / issue refs.
  * @property {number|null}   estimated_test_files - Test surface count or null.
  */
@@ -246,10 +248,14 @@ const META_BLOCK_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
  * defaults instead of throwing.
  *
  * @param {string} markdown
- * @returns {{ wide: { reason: string }|null, estimated_test_files: number|null }}
+ * @returns {{ wide: { reason: string }|null, reason_to_exist: string|null, estimated_test_files: number|null }}
  */
 function extractMeta(markdown) {
-  const result = { wide: null, estimated_test_files: null };
+  const result = {
+    wide: null,
+    reason_to_exist: null,
+    estimated_test_files: null,
+  };
   const match = markdown.match(META_BLOCK_RE);
   if (!match) return result;
 
@@ -263,12 +269,29 @@ function extractMeta(markdown) {
   if (parsed === null || typeof parsed !== 'object') return result;
 
   result.wide = normalizeWide(parsed.wide);
+  result.reason_to_exist = normalizeReasonToExist(parsed.reason_to_exist);
   if (typeof parsed.estimated_test_files === 'number') {
     result.estimated_test_files = parsed.estimated_test_files;
   }
   return result;
 }
 
+/**
+ * Normalize a raw `reason_to_exist` value to a non-empty trimmed string or
+ * `null`. The field is the machine-checkable form of the cohesion rule
+ * ("one Story = one coherent change with one reason to exist"): the
+ * `epic-plan-consolidate` critic flags any Story whose body carries no
+ * non-empty reason. An empty or non-string value is treated as absent.
+ *
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+function normalizeReasonToExist(raw) {
+  if (typeof raw !== 'string') return null;
+  const reason = raw.trim();
+  return reason.length === 0 ? null : reason;
+}
+
 /**
  * Normalize a raw `wide` declaration to the canonical `{ reason }` shape or
  * `null`. A `wide` declaration is only honoured when it carries a non-empty
@@ -382,6 +405,7 @@ function parseLegacyStringBody(input, preamble, footer) {
     verify: [],
     references: [],
     wide: null,
+    reason_to_exist: null,
     depends_on: extractBlockedBy(footer),
     estimated_test_files: null,
   };
@@ -526,6 +550,7 @@ export function parse(input) {
   const meta = extractMeta(input);
   const estimated_test_files = meta.estimated_test_files;
   const wide = meta.wide;
+  const reason_to_exist = meta.reason_to_exist;
   if (estimated_test_files === null) {
     warnings.push(
       'test-surface-unestimated: estimated_test_files not present.',
@@ -539,6 +564,7 @@ export function parse(input) {
     verify,
     references,
     wide,
+    reason_to_exist,
     depends_on: dependsOn,
     estimated_test_files,
   };
@@ -597,6 +623,7 @@ function parseStructuredObject(obj) {
   }
 
   const wide = normalizeWide(obj.wide);
+  const reason_to_exist = normalizeReasonToExist(obj.reason_to_exist);
 
   // depends_on: may be at top level or in body
   const rawDeps = Array.isArray(obj.depends_on) ? obj.depends_on : [];
@@ -621,6 +648,7 @@ function parseStructuredObject(obj) {
     verify,
     references,
     wide,
+    reason_to_exist,
     depends_on,
     estimated_test_files,
   };
@@ -663,8 +691,8 @@ function serializePathEntry(entry) {
  * `## Goal`, `## Changes`, `## Acceptance`, `## Verify`, `## References`
  * (omitted when empty).
  *
- * `wide` and `estimated_test_files` are emitted as a fenced
- * `<!-- meta -->` comment block so round-trips preserve them without
+ * `wide`, `reason_to_exist`, and `estimated_test_files` are emitted as a
+ * fenced `<!-- meta -->` comment block so round-trips preserve them without
  * polluting the human-readable body.
  *
  * @param {StoryBody} body
@@ -721,6 +749,10 @@ export function serialize(body, opts = {}) {
   if (wide !== null) {
     metaFields.wide = wide;
   }
+  const reasonToExist = normalizeReasonToExist(body.reason_to_exist);
+  if (reasonToExist !== null) {
+    metaFields.reason_to_exist = reasonToExist;
+  }
   if (typeof body.estimated_test_files === 'number') {
     metaFields.estimated_test_files = body.estimated_test_files;
   }