mandrel 1.68.0 → 1.69.0

package/.agents/scripts/lib/wave-runner/wave-runner-error.js

@@ -4,7 +4,8 @@
  * (blocked stories, gate failures) route through `WaveTickResult`.
  *
  * Callers classify via `err.phase`: `checkpoint-missing`,
- * `checkpoint-read`, `plan-missing`, `story-fetch`, `invalid-input`.
+ * `checkpoint-read`, `old-shape-checkpoint`, `story-fetch`,
+ * `invalid-input`.
  *
  * @module lib/wave-runner/wave-runner-error
  */

package/.agents/scripts/lint-label-vocabulary.js

@@ -159,7 +159,7 @@ export function findVocabularyViolations(src, axes = KNOWN_AXES) {
   //   - `context::acceptance-spec` — canonical label, value contains a
   //     hyphen but is not at axis position.
   //   - `<type>/<slug>` — template placeholders.
-  //   - `planning.maxTickets` — config-key paths with `.`.
+  //   - `delivery.maxTokenBudget` — config-key paths with `.`.
   //   - `context.{prdId,techSpecId}` — JS destructure shapes.
   //   - `agent-protocol.md` — filenames / concept slugs.
   //

package/.agents/scripts/stories-wave-tick.js

@@ -1,16 +1,30 @@
 #!/usr/bin/env node
 
 /**
- * stories-wave-tick.js — DAG/wave engine for the top-level /deliver workflow.
+ * stories-wave-tick.js — continuous ready-set planner for the standalone
+ * `/deliver` story-list path.
  *
- * Consumes an operator-supplied dependency DAG of standalone Story IDs and
- * emits ordered execution waves. Analogous to wave-tick.js but for standalone
- * Stories (not Epic-manifest tasks).
+ * Thin **adapter** over the path-agnostic ready-set scheduling core
+ * (`lib/wave-runner/ready-set.js#selectReadySet`). It consumes an
+ * operator-supplied dependency DAG of standalone Story IDs plus the live
+ * progress of the run (which Stories are done, how many are in flight) and
+ * emits the set of Stories safe to dispatch **on this beat** — a Story
+ * becomes dispatchable the instant its own dependencies are done, under the
+ * same global concurrency cap and the same file-overlap co-dispatch guard
+ * the Epic path uses. There is no wave barrier: this no longer batches
+ * Stories into fully-draining waves; it selects continuously.
+ *
+ * The previous static wave-batch plan (group N must fully drain before
+ * group N+1 opens, via `Graph.js#assignLayers`) is gone. The scheduling
+ * kernel — adjacency derivation, the done-predicate classifier, the
+ * eligibility rule, and the overlap guard — lives once in `selectReadySet`;
+ * this file only parses input, resolves the cap, and renders the envelope.
  *
  * Usage:
  *   node .agents/scripts/stories-wave-tick.js --dag '<json>'
  *   node .agents/scripts/stories-wave-tick.js --dag-file <path>
  *   node .agents/scripts/stories-wave-tick.js --dag '<json>' --concurrency 5
+ *   node .agents/scripts/stories-wave-tick.js --dag '<json>' --done 101,103 --in-flight 1
  *
  * DAG input format (JSON):
  *   Array of { id: number, dependsOn: number[] } objects where id is a Story
@@ -18,20 +32,27 @@
  *
  * Output: one JSON object on stdout with shape:
  *   {
- *     kind: 'stories-wave-plan',
- *     waves: Array<{ waveIndex: number, stories: number[] }>,
+ *     kind: 'stories-ready-set',
+ *     ready: number[],          // Story IDs safe to dispatch on this beat
  *     totalStories: number,
  *     concurrencyCap: number,
+ *     inFlight: number,
  *     cycleError: string | null
  *   }
  *
- * The per-wave concurrency cap is resolved from the same config seam
+ * The standalone loop calls this once per beat: after each Story closes it
+ * re-runs with the closed Story added to `--done` and the live in-flight
+ * count in `--in-flight`, dispatching the returned `ready` set (already
+ * capped at `concurrencyCap − inFlight` by the core). The run is complete
+ * when every Story is in `--done` and `ready` is empty.
+ *
+ * The per-beat concurrency cap is resolved from the same config seam
  * `/deliver` uses — `resolveConfig` + `getRunners` reading
  * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
  * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
  * overrides the config-resolved value for that run only. This puts both the
- * standalone (`/deliver`) and Epic (`/deliver`) delivery paths on
- * one deterministic config source.
+ * standalone (`/deliver`) and Epic (`/deliver`) delivery paths on one
+ * deterministic config source **and** one scheduling kernel.
  *
  * On cycle detection, exits with code 2 and sets cycleError in the envelope.
  */
@@ -41,15 +62,19 @@ import { parseArgs } from 'node:util';
 
 import { runAsCli } from './lib/cli-utils.js';
 import { getRunners, resolveConfig } from './lib/config-resolver.js';
-import { assignLayers, detectCycle } from './lib/Graph.js';
+import { detectCycle } from './lib/Graph.js';
 import { Logger } from './lib/Logger.js';
+import { AGENT_LABELS } from './lib/label-constants.js';
 import { buildStoryAdjacency } from './lib/story-adjacency.js';
+import { selectReadySet } from './lib/wave-runner/ready-set.js';
 
-const HELP = `Usage: node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>]
+const HELP = `Usage: node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>] [--done <csv>] [--in-flight <n>]
 
-DAG/wave engine for standalone Story delivery. Consumes a dependency graph
-of Story IDs and emits ordered execution waves plus a resolved per-wave
-concurrency cap.
+Continuous ready-set planner for standalone Story delivery. Consumes a
+dependency graph of Story IDs plus the live run progress and emits the set
+of Stories safe to dispatch on this beat — a Story is dispatchable the
+instant its own dependencies are done — plus the resolved per-beat
+concurrency cap and the same file-overlap guard the Epic path uses.
 
 Input DAG format (JSON array):
   [{ "id": 101, "dependsOn": [] }, { "id": 102, "dependsOn": [101] }]
@@ -59,31 +84,45 @@ Each entry must include:
   dependsOn  - Array of Story IDs that must complete before this Story runs
 
 Options:
-  --concurrency <n>  Override the per-wave concurrency cap for this run only.
+  --concurrency <n>  Override the per-beat concurrency cap for this run only.
                      Must be a positive integer. When omitted, the cap is
                      resolved from delivery.deliverRunner.concurrencyCap in
                      .agentrc.json / .agentrc.local.json (default 3).
+  --done <csv>       Comma-separated Story IDs already completed this run.
+                     Their dependents become eligible; they are never
+                     re-dispatched. Defaults to empty.
+  --in-flight <n>    Count of Stories already occupying a slot (dispatched
+                     but not yet done). Subtracted from the cap to compute
+                     remaining capacity. Non-negative integer; defaults to 0.
 
 Output envelope:
   {
-    "kind": "stories-wave-plan",
-    "waves": [{ "waveIndex": 0, "stories": [101] }, ...],
+    "kind": "stories-ready-set",
+    "ready": [101],
     "totalStories": 2,
     "concurrencyCap": 3,
+    "inFlight": 0,
     "cycleError": null
   }
 
 Exit codes:
-  0 - Success, waves emitted
-  1 - Invalid input (missing/malformed DAG, invalid --concurrency)
+  0 - Success, ready set emitted
+  1 - Invalid input (missing/malformed DAG, invalid --concurrency/--in-flight/--done)
   2 - Cycle detected in dependency graph
 `;
 
 /**
  * Parse and validate the raw DAG input array.
  *
+ * Each entry must carry `{ id, dependsOn }`. An optional `files` string
+ * array (the canonical footprint shape) is preserved and forwarded to the
+ * ready-set core so the file-overlap co-dispatch guard the Epic path uses is
+ * genuinely active on the standalone path too: two ready Stories that
+ * declare an intersecting footprint are never dispatched onto parallel
+ * `story-<id>` branches in the same beat.
+ *
  * @param {unknown} raw Parsed JSON value from --dag or --dag-file.
- * @returns {{ nodes: Array<{id: number, dependsOn: number[]}>, error: string|null }}
+ * @returns {{ nodes: Array<{id: number, dependsOn: number[], files?: string[]}>, error: string|null }}
  */
 export function parseDag(raw) {
   if (!Array.isArray(raw)) {
@@ -124,30 +163,99 @@ export function parseDag(raw) {
         };
       }
     }
-    nodes.push({ id, dependsOn: [...dependsOn] });
+    const node = { id, dependsOn: [...dependsOn] };
+    if (entry.files !== undefined) {
+      if (
+        !Array.isArray(entry.files) ||
+        entry.files.some((f) => typeof f !== 'string')
+      ) {
+        return {
+          nodes: null,
+          error: `DAG entry at index ${i} (id=${id}): "files" must be an array of strings`,
+        };
+      }
+      node.files = [...entry.files];
+    }
+    nodes.push(node);
   }
   return { nodes, error: null };
 }
 
 /**
- * Build an adjacency map from parsed DAG nodes.
- * Returns Map<id, id[]> where each id maps to its dependencies.
+ * Parse a comma-separated `--done` list of Story IDs into a deduped set of
+ * positive integers. Empty / absent input yields an empty set. Rejects any
+ * token that is not a positive integer so a typo never silently drops a
+ * dependency gate.
  *
- * Delegates to the shared story-level builder
- * (`lib/story-adjacency.js#buildStoryAdjacency`) with `dropForeign: false`
- * to preserve the operator-DAG contract: a `dependsOn` id absent from the
- * input set still deepens the dependent's layer (assignLayers treats the
- * unknown id as a root).
+ * @param {string|undefined} raw
+ * @returns {{ ids: Set<number>|null, error: string|null }}
+ */
+export function parseDoneIds(raw) {
+  if (raw == null || raw === '') {
+    return { ids: new Set(), error: null };
+  }
+  const ids = new Set();
+  for (const token of String(raw).split(',')) {
+    const trimmed = token.trim();
+    if (trimmed === '') continue;
+    const num = Number(trimmed);
+    if (!Number.isInteger(num) || num <= 0) {
+      return {
+        ids: null,
+        error: `--done must be a comma-separated list of positive integers, got "${trimmed}"`,
+      };
+    }
+    ids.add(num);
+  }
+  return { ids, error: null };
+}
+
+/**
+ * Parse the raw `--in-flight` value into a non-negative integer. Absent
+ * input defaults to 0. Rejects negatives and non-integers.
  *
- * @param {Array<{id: number, dependsOn: number[]}>} nodes
- * @returns {Map<number, number[]>}
+ * @param {unknown} raw
+ * @returns {{ value: number|null, error: string|null }}
  */
-export function buildAdjacency(nodes) {
-  return buildStoryAdjacency(nodes, { dropForeign: false });
+export function parseInFlight(raw) {
+  if (raw == null) {
+    return { value: 0, error: null };
+  }
+  const num = typeof raw === 'number' ? raw : Number(raw);
+  if (!Number.isInteger(num) || num < 0) {
+    return {
+      value: null,
+      error: `--in-flight must be a non-negative integer, got "${raw}"`,
+    };
+  }
+  return { value: num, error: null };
 }
 
 /**
- * Resolve the per-wave concurrency cap.
+ * Validate a raw `--concurrency` value into a positive integer.
+ *
+ * Accepts a number or a numeric string (from the CLI). Rejects anything that
+ * is not a positive integer (zero, negative, fractional, non-numeric).
+ *
+ * @param {unknown} raw
+ * @returns {{ value: number|null, error: string|null }}
+ */
+export function parseConcurrencyOverride(raw) {
+  if (raw == null) {
+    return { value: null, error: null };
+  }
+  const num = typeof raw === 'number' ? raw : Number(raw);
+  if (!Number.isInteger(num) || num <= 0) {
+    return {
+      value: null,
+      error: `--concurrency must be a positive integer, got "${raw}"`,
+    };
+  }
+  return { value: num, error: null };
+}
+
+/**
+ * Resolve the per-beat concurrency cap.
  *
  * Mirrors the `/deliver` seam (`epic-deliver-prepare.js`): resolve the
  * project config (which deep-merges `.agentrc.local.json` over `.agentrc.json`)
@@ -173,103 +281,96 @@ export function resolveConcurrencyCap({ cwd, config, override } = {}) {
 }
 
 /**
- * Compute the wave plan from a validated adjacency map.
+ * Build the per-beat ready-set envelope from a validated DAG.
  *
- * Uses detectCycle from Graph.js to validate the DAG before computing
- * layers via assignLayers. Returns the wave envelope, carrying the resolved
- * per-wave `concurrencyCap` so the `/deliver` workflow dispatches
- * `min(wave.stories.length, concurrencyCap)` from a deterministic field rather
- * than from recalled prose.
+ * Maps each operator-DAG node onto a Story record the ready-set core
+ * understands (`{ id, dependsOn }`), tags any node already in the done set
+ * as `agent::done` so the core's classifier excludes it from the dispatch
+ * set **and** counts it as a satisfied dependency, then delegates the
+ * scheduling decision to `selectReadySet`. A cyclic operator DAG is a
+ * planning error (the core would silently never schedule the cycle), so we
+ * detect it up front via the shared `detectCycle` kernel and short-circuit
+ * with a `cycleError` and exit code 2.
  *
- * @param {Map<number, number[]>} adjacency
- * @param {number} concurrencyCap Resolved per-wave concurrency cap.
+ * @param {Array<{id: number, dependsOn: number[]}>} nodes
+ * @param {object} args
+ * @param {number} args.concurrencyCap Resolved per-beat concurrency cap.
+ * @param {Set<number>} [args.doneIds] Story IDs already completed this run.
+ * @param {number} [args.inFlight]     Stories already occupying a slot.
  * @returns {{
- *   kind: 'stories-wave-plan',
- *   waves: Array<{waveIndex: number, stories: number[]}>,
- *   totalStories: number,
- *   concurrencyCap: number,
- *   cycleError: string|null
+ *   envelope: {
+ *     kind: 'stories-ready-set',
+ *     ready: number[],
+ *     totalStories: number,
+ *     concurrencyCap: number,
+ *     inFlight: number,
+ *     cycleError: string|null
+ *   },
+ *   exitCode: number
  * }}
  */
-export function computeStoriesWavePlan(adjacency, concurrencyCap) {
-  const totalStories = adjacency.size;
+export function buildReadySetEnvelope(
+  nodes,
+  { concurrencyCap, doneIds = new Set(), inFlight = 0 },
+) {
+  const totalStories = nodes.length;
+
+  const base = {
+    kind: 'stories-ready-set',
+    ready: [],
+    totalStories,
+    concurrencyCap,
+    inFlight,
+    cycleError: null,
+  };
 
   if (totalStories === 0) {
-    return {
-      kind: 'stories-wave-plan',
-      waves: [],
-      totalStories: 0,
-      concurrencyCap,
-      cycleError: null,
-    };
+    return { envelope: base, exitCode: 0 };
   }
 
-  // Detect cycles before computing layers — a cycle is a planning error.
+  // Cycle detection before scheduling — a cycle is a planning error the
+  // operator must fix. dropForeign:false preserves the operator-DAG contract
+  // (a dependency on an id outside the supplied set is honored, not pruned),
+  // matching the same builder seam selectReadySet uses internally.
+  const adjacency = buildStoryAdjacency(nodes, { dropForeign: false });
   const cycle = detectCycle(adjacency);
   if (cycle) {
     return {
-      kind: 'stories-wave-plan',
-      waves: [],
-      totalStories,
-      concurrencyCap,
-      cycleError: `Dependency cycle detected: ${cycle.join(' → ')}. Fix the depends_on declarations before running /story-deliver.`,
+      envelope: {
+        ...base,
+        cycleError: `Dependency cycle detected: ${cycle.join(' → ')}. Fix the depends_on declarations before running /deliver.`,
+      },
+      exitCode: 2,
     };
   }
 
-  // Assign layers (wave indices) via Graph.js — wave 0 = roots (no deps).
-  const layers = assignLayers(adjacency);
+  // Map DAG nodes → Story records. Tag done nodes as agent::done so the
+  // core's classifier (a) excludes them from the dispatch set and (b) folds
+  // them into the satisfied-dependency set, making their dependents eligible.
+  // Forward any declared file footprint so the core's overlap guard fires.
+  const records = nodes.map((node) => {
+    const rec = {
+      id: node.id,
+      dependsOn: node.dependsOn,
+      labels: doneIds.has(node.id) ? [AGENT_LABELS.DONE] : [],
+    };
+    if (node.files !== undefined) rec.files = node.files;
+    return rec;
+  });
 
-  // Group story IDs by wave index, sort deterministically within each wave.
-  const waveMap = new Map();
-  for (const [storyId, waveIndex] of layers.entries()) {
-    if (!waveMap.has(waveIndex)) waveMap.set(waveIndex, []);
-    waveMap.get(waveIndex).push(storyId);
-  }
+  const ready = selectReadySet({
+    stories: records,
+    doneIds,
+    inFlight,
+    globalCap: concurrencyCap,
+  }).map((rec) => rec.id);
 
-  const maxWave = Math.max(...waveMap.keys());
-  const waves = [];
-  for (let i = 0; i <= maxWave; i++) {
-    const stories = (waveMap.get(i) ?? []).sort((a, b) => a - b);
-    if (stories.length > 0) {
-      waves.push({ waveIndex: i, stories });
-    }
-  }
-
-  return {
-    kind: 'stories-wave-plan',
-    waves,
-    totalStories,
-    concurrencyCap,
-    cycleError: null,
-  };
-}
-
-/**
- * Validate a raw `--concurrency` value into a positive integer.
- *
- * Accepts a number or a numeric string (from the CLI). Rejects anything that
- * is not a positive integer (zero, negative, fractional, non-numeric).
- *
- * @param {unknown} raw
- * @returns {{ value: number|null, error: string|null }}
- */
-export function parseConcurrencyOverride(raw) {
-  if (raw == null) {
-    return { value: null, error: null };
-  }
-  const num = typeof raw === 'number' ? raw : Number(raw);
-  if (!Number.isInteger(num) || num <= 0) {
-    return {
-      value: null,
-      error: `--concurrency must be a positive integer, got "${raw}"`,
-    };
-  }
-  return { value: num, error: null };
+  return { envelope: { ...base, ready }, exitCode: 0 };
 }
 
 /**
  * Core logic: parse DAG input, resolve the concurrency cap, validate, and
- * compute the wave plan.
+ * compute the per-beat ready set via the shared scheduling core.
  *
  * Exported for unit tests; the CLI `main` function is a thin wrapper. Tests
  * inject `config` so they never depend on a real `.agentrc`.
@@ -278,10 +379,12 @@ export function parseConcurrencyOverride(raw) {
  * @param {string} [args.dagJson]      Raw JSON string from --dag.
  * @param {string} [args.dagFile]      Path to a JSON file from --dag-file.
  * @param {string|number} [args.concurrency] Raw --concurrency override.
+ * @param {string} [args.done]         Raw --done CSV of completed Story IDs.
+ * @param {string|number} [args.inFlight] Raw --in-flight count.
  * @param {string} [args.cwd]          Repo root for config resolution.
  * @param {object} [args.config]       Pre-resolved config (test injection).
  * @returns {{
- *   envelope: {kind: string, waves: object[], totalStories: number, concurrencyCap: number, cycleError: string|null},
+ *   envelope: {kind: string, ready: number[], totalStories: number, concurrencyCap: number, inFlight: number, cycleError: string|null},
  *   exitCode: number
  * }}
  */
@@ -289,23 +392,41 @@ export function runStoriesWaveTick({
   dagJson,
   dagFile,
   concurrency,
+  done,
+  inFlight,
   cwd,
   config,
 } = {}) {
+  const inputError = (message, concurrencyCap = null, inFlightValue = 0) => ({
+    envelope: {
+      kind: 'stories-ready-set',
+      ready: [],
+      totalStories: 0,
+      concurrencyCap,
+      inFlight: inFlightValue,
+      cycleError: null,
+      inputError: message,
+    },
+    exitCode: 1,
+  });
+
   // Validate the --concurrency override before resolving config so an invalid
   // value fails fast with exit code 1 regardless of DAG validity.
   const { value: override, error: concurrencyError } =
     parseConcurrencyOverride(concurrency);
   if (concurrencyError) {
-    const envelope = {
-      kind: 'stories-wave-plan',
-      waves: [],
-      totalStories: 0,
-      concurrencyCap: null,
-      cycleError: null,
-      inputError: concurrencyError,
-    };
-    return { envelope, exitCode: 1 };
+    return inputError(concurrencyError);
+  }
+
+  const { value: inFlightValue, error: inFlightError } =
+    parseInFlight(inFlight);
+  if (inFlightError) {
+    return inputError(inFlightError);
+  }
+
+  const { ids: doneIds, error: doneError } = parseDoneIds(done);
+  if (doneError) {
+    return inputError(doneError, null, inFlightValue);
   }
 
   const concurrencyCap = resolveConcurrencyCap({ cwd, config, override });
@@ -316,67 +437,43 @@ export function runStoriesWaveTick({
     try {
       rawJson = readFileSync(dagFile, 'utf8');
     } catch (err) {
-      const envelope = {
-        kind: 'stories-wave-plan',
-        waves: [],
-        totalStories: 0,
+      return inputError(
+        `Could not read DAG file "${dagFile}": ${err.message}`,
         concurrencyCap,
-        cycleError: null,
-        inputError: `Could not read DAG file "${dagFile}": ${err.message}`,
-      };
-      return { envelope, exitCode: 1 };
+        inFlightValue,
+      );
     }
   } else if (dagJson) {
     rawJson = dagJson;
   } else {
-    const envelope = {
-      kind: 'stories-wave-plan',
-      waves: [],
-      totalStories: 0,
+    return inputError(
+      'Either --dag <json> or --dag-file <path> is required',
       concurrencyCap,
-      cycleError: null,
-      inputError: 'Either --dag <json> or --dag-file <path> is required',
-    };
-    return { envelope, exitCode: 1 };
+      inFlightValue,
+    );
   }
 
   let parsed;
   try {
     parsed = JSON.parse(rawJson);
   } catch (err) {
-    const envelope = {
-      kind: 'stories-wave-plan',
-      waves: [],
-      totalStories: 0,
+    return inputError(
+      `Invalid JSON: ${err.message}`,
       concurrencyCap,
-      cycleError: null,
-      inputError: `Invalid JSON: ${err.message}`,
-    };
-    return { envelope, exitCode: 1 };
+      inFlightValue,
+    );
   }
 
   const { nodes, error: parseError } = parseDag(parsed);
   if (parseError) {
-    const envelope = {
-      kind: 'stories-wave-plan',
-      waves: [],
-      totalStories: 0,
-      concurrencyCap,
-      cycleError: null,
-      inputError: parseError,
-    };
-    return { envelope, exitCode: 1 };
-  }
-
-  const adjacency = buildAdjacency(nodes);
-  const envelope = computeStoriesWavePlan(adjacency, concurrencyCap);
-
-  // Cycle detection → exit code 2
-  if (envelope.cycleError) {
-    return { envelope, exitCode: 2 };
+    return inputError(parseError, concurrencyCap, inFlightValue);
   }
 
-  return { envelope, exitCode: 0 };
+  return buildReadySetEnvelope(nodes, {
+    concurrencyCap,
+    doneIds,
+    inFlight: inFlightValue,
+  });
 }
 
 async function main(argv) {
@@ -386,6 +483,8 @@ async function main(argv) {
       dag: { type: 'string' },
       'dag-file': { type: 'string' },
       concurrency: { type: 'string' },
+      done: { type: 'string' },
+      'in-flight': { type: 'string' },
       help: { type: 'boolean', short: 'h' },
     },
     strict: false,
@@ -401,6 +500,8 @@ async function main(argv) {
     dagJson: values.dag,
     dagFile: values['dag-file'],
     concurrency: values.concurrency,
+    done: values.done,
+    inFlight: values['in-flight'],
   });
 
   process.stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -23,6 +23,7 @@ allowed_tools:
 - Your operations are constrained to exactly two shapes: **(1) merge two or more Stories** into one (union their `changes`/`acceptance`/`verify`/`references`, keep one coherent `goal`); **(2) rewire `depends_on`** so the edges still reference surviving sibling-Story slugs. No other mutation is permitted.
 - Consume the Tech Spec **"Delivery Slicing"** section as the authoritative target grouping when one is present: cluster the draft's Stories toward the N shippable Stories the Architect proposed. When the section is **absent**, degrade gracefully — apply only the cohesion rules below and leave the rest of the draft shape intact.
 - Apply the same cohesion heuristic the author skill leads with: **one Story = one coherent change with one reason to exist**, and the **single-consumer merge rule** (a Story whose only consumer is one sibling Story is merged into that sibling). Lead every merge decision with the change's reason, not its file count.
+- **Missing reason-to-exist check (cohesion gate).** Every draft Story body MUST carry a non-empty `reason_to_exist` meta field (the parseable form of "one Story = one coherent change with one reason to exist", encoded in the `<!-- meta: {"reason_to_exist": "..."} -->` comment and surfaced as `body.reason_to_exist` by `lib/story-body/story-body.js`). Flag any Story whose body carries **no** non-empty reason to exist: a Story that cannot state its single reason in one sentence is a cohesion smell — it is probably two Stories, or two Stories that should be merged into one. Name each flagged Story in the consolidation report so the operator sees the cohesion gap at the HITL diff gate.
 - After every merge, **rewire `depends_on`**: drop self-edges, collapse edges that now point at the absorbing Story onto itself, and re-point any edge that named a now-deleted slug at its surviving successor. Never leave a `depends_on` referencing a slug absent from the consolidated array — the validator HARD-rejects unknown deps.
 - The consolidation report MUST name each operation applied (merged slugs → surviving slug, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call.
 
@@ -95,6 +96,11 @@ Across the draft Story array, decide which Stories merge:
   single Story: union their `changes` / `acceptance` / `verify` / `references`,
   write one coherent `goal`, and keep the union of labels.
 - **Single-consumer Story** → merge into the one sibling that consumes it.
+- **Missing reason to exist** → flag any Story whose body carries no non-empty
+  `reason_to_exist` meta field. A Story that cannot name its single coherent
+  reason is a cohesion smell; record it in the report so the operator can
+  re-scope it (merge, split, or have the author supply the reason) at the HITL
+  gate.
 
 Record each decision with its one-line reason for the report.