mandrel 1.68.0 → 1.70.0

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,
   };
@@ -655,6 +683,108 @@ function serializePathEntry(entry) {
   return JSON.stringify({ path: entry.path, assumption: entry.assumption });
 }
 
+/**
+ * Descriptor table for the human-readable Story-body sections, in canonical
+ * emit order (`## Goal`, `## Changes`, `## Acceptance`, `## Verify`,
+ * `## References`). Each descriptor reads one body field and returns the
+ * section's markdown block when the field is present and non-empty, or `null`
+ * to omit the section.
+ *
+ * Standardising the section ladder as a single data table makes adding a new
+ * optional section a one-line edit here rather than a new control-flow branch
+ * in {@link serialize}.
+ *
+ * @type {Array<{ field: string, render: (value: unknown) => string | null }>}
+ */
+const SERIALIZE_SECTIONS = [
+  {
+    field: 'goal',
+    render: (goal) =>
+      typeof goal === 'string' && goal.trim().length > 0
+        ? `## Goal\n${goal.trim()}`
+        : null,
+  },
+  {
+    field: 'changes',
+    render: (changes) =>
+      Array.isArray(changes) && changes.length > 0
+        ? `## Changes\n${changes.map((c) => `- ${serializePathEntry(c)}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'acceptance',
+    render: (acceptance) =>
+      Array.isArray(acceptance) && acceptance.length > 0
+        ? `## Acceptance\n${acceptance.map((a) => `- [ ] ${a}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'verify',
+    render: (verify) =>
+      Array.isArray(verify) && verify.length > 0
+        ? `## Verify\n${verify.map((v) => `- ${v}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'references',
+    render: (references) =>
+      Array.isArray(references) && references.length > 0
+        ? `## References\n${references.map((r) => `- ${serializePathEntry(r)}`).join('\n')}`
+        : null,
+  },
+];
+
+/**
+ * Build the trailing `<!-- meta: {...} -->` block carrying the fields that
+ * have no human-readable section (`wide`, `reason_to_exist`,
+ * `estimated_test_files`). Returns the empty string when no meta field is
+ * present so {@link serialize} appends nothing.
+ *
+ * Key insertion order (`wide` → `reason_to_exist` → `estimated_test_files`)
+ * is load-bearing: it fixes the serialized JSON byte sequence the parser's
+ * meta round-trip and the unit suite assert against.
+ *
+ * @param {StoryBody} body
+ * @returns {string}
+ */
+function serializeMetaBlock(body) {
+  const metaFields = {};
+  const wide = normalizeWide(body.wide);
+  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;
+  }
+  if (Object.keys(metaFields).length === 0) return '';
+  return `\n\n<!-- meta: ${JSON.stringify(metaFields)} -->`;
+}
+
+/**
+ * Build the optional `---` footer block (`parent` / `Epic` / `blocked by`
+ * lines). Returns the empty string when `opts.includeFooter` is falsy.
+ *
+ * @param {StoryBody} body
+ * @param {SerializeOptions} opts
+ * @returns {string}
+ */
+function serializeFooter(body, opts) {
+  if (!opts.includeFooter) return '';
+  const footerLines = ['---'];
+  if (opts.footer?.parent) footerLines.push(`parent: #${opts.footer.parent}`);
+  if (opts.footer?.epic) footerLines.push(`Epic: #${opts.footer.epic}`);
+  if (Array.isArray(body.depends_on)) {
+    for (const dep of body.depends_on) {
+      footerLines.push(`blocked by ${dep}`);
+    }
+  }
+  return `\n\n${footerLines.join('\n')}`;
+}
+
 /**
  * Serialize a structured {@link StoryBody} back to the canonical markdown
  * format written to GitHub issue bodies.
@@ -663,8 +793,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
@@ -679,69 +809,16 @@ export function serialize(body, opts = {}) {
   }
 
   const sections = [];
-
-  // ## Goal
-  if (typeof body.goal === 'string' && body.goal.trim().length > 0) {
-    sections.push(`## Goal\n${body.goal.trim()}`);
-  }
-
-  // ## Changes
-  if (Array.isArray(body.changes) && body.changes.length > 0) {
-    const items = body.changes
-      .map((c) => `- ${serializePathEntry(c)}`)
-      .join('\n');
-    sections.push(`## Changes\n${items}`);
-  }
-
-  // ## Acceptance
-  if (Array.isArray(body.acceptance) && body.acceptance.length > 0) {
-    const items = body.acceptance.map((a) => `- [ ] ${a}`).join('\n');
-    sections.push(`## Acceptance\n${items}`);
-  }
-
-  // ## Verify
-  if (Array.isArray(body.verify) && body.verify.length > 0) {
-    const items = body.verify.map((v) => `- ${v}`).join('\n');
-    sections.push(`## Verify\n${items}`);
-  }
-
-  // ## References (only when non-empty)
-  if (Array.isArray(body.references) && body.references.length > 0) {
-    const items = body.references
-      .map((r) => `- ${serializePathEntry(r)}`)
-      .join('\n');
-    sections.push(`## References\n${items}`);
+  for (const descriptor of SERIALIZE_SECTIONS) {
+    const block = descriptor.render(body[descriptor.field]);
+    if (block !== null) sections.push(block);
   }
 
-  let out = sections.join('\n\n');
-
-  // Meta block for fields not representable as human-readable sections.
-  const metaFields = {};
-  const wide = normalizeWide(body.wide);
-  if (wide !== null) {
-    metaFields.wide = wide;
-  }
-  if (typeof body.estimated_test_files === 'number') {
-    metaFields.estimated_test_files = body.estimated_test_files;
-  }
-  if (Object.keys(metaFields).length > 0) {
-    out += `\n\n<!-- meta: ${JSON.stringify(metaFields)} -->`;
-  }
-
-  // Footer
-  if (opts.includeFooter) {
-    const footerLines = ['---'];
-    if (opts.footer?.parent) footerLines.push(`parent: #${opts.footer.parent}`);
-    if (opts.footer?.epic) footerLines.push(`Epic: #${opts.footer.epic}`);
-    if (Array.isArray(body.depends_on)) {
-      for (const dep of body.depends_on) {
-        footerLines.push(`blocked by ${dep}`);
-      }
-    }
-    out += `\n\n${footerLines.join('\n')}`;
-  }
-
-  return out;
+  return (
+    sections.join('\n\n') +
+    serializeMetaBlock(body) +
+    serializeFooter(body, opts)
+  );
 }
 
 // ---------------------------------------------------------------------------

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -15,11 +15,28 @@ import {
  * 2-tier is the only published hierarchy after Story #4041 removed the
  * Feature tier: the prompt emits Stories only (direct Epic children) and
  * asks the planner to carry acceptance/verify as top-level ticket arrays.
+ *
+ * **Single source of the prompt body (Story #4162).** This module is the sole
+ * carrier of the full decomposer system-prompt body. The
+ * `epic-plan-decompose-author` SKILL no longer embeds a second verbatim copy —
+ * it references this rendered prompt (delivered to the host LLM in the
+ * `systemPrompt` field of the authoring context envelope built by
+ * `epic-plan-decompose/phases/context.js`) instead, so the two surfaces cannot
+ * drift. A guard test (`tests/ticket-decomposer.test.js`) fails if the SKILL
+ * re-grows a full copy of the prompt preamble.
+ *
+ * **Token-budget sizing input (Story #4162).** `maxTokenBudget` is the real
+ * one-pass delivery envelope (the task-prompt hydration cap surfaced into the
+ * authoring envelope by `context.js`, Story #3875). It is threaded into the
+ * rendered prompt as a sizing input so the planner sizes Stories against the
+ * envelope a single agent can actually deliver in one pass, rather than leading
+ * with the file-count proxy alone.
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
+  maxTokenBudget = LIMITS_DEFAULTS.maxTokenBudget,
 } = {}) {
-  return render2TierPrompt({ maxTickets });
+  return render2TierPrompt({ maxTickets, maxTokenBudget });
 }
 
 /**
@@ -28,7 +45,7 @@ export function renderDecomposerSystemPrompt({
  * on the Story body so the executing agent has everything it needs in one
  * ticket. Thematic grouping lives as prose in the Epic body / Tech Spec.
  */
-function render2TierPrompt({ maxTickets }) {
+function render2TierPrompt({ maxTickets, maxTokenBudget }) {
   // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
   // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
   const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
@@ -103,6 +120,7 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
 - **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
+- **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
 - **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 
 #### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
@@ -111,7 +129,9 @@ The serialized \`body\` string renders these markdown sections (in order):
 
 The primary question is **cohesion, not count**: *is this one coherent change with one reason to exist?* File count cannot tell a trivial ${softFiles}-file rename from a hard 3-file parser+caller+config change — so lead with the change's reason, not its size.
 
-- **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one.
+**Size against the real one-pass delivery envelope.** Each Story is delivered and self-verified by a single agent in one pass, whose context is capped by the delivery token budget \`maxTokenBudget = ${maxTokenBudget}\` tokens (the task-prompt hydration cap). Use that envelope — not the file count alone — as the leading sizing input: a Story is correctly sized when one agent can hold its full change, acceptance, and verification in a single pass within \`maxTokenBudget\`. The numeric file thresholds below are a coarse backstop on top of this envelope, not the primary signal.
+
+- **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories — or two Stories that should be one. State that sentence explicitly in the Story's \`reason_to_exist\` meta field (see STORY BODY RULES) so the consolidate critic can check it.
 - ${singleConsumerRule}
 - **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
 - **Declare \`wide\` with a one-line reason when a change is legitimately broad** (a cohesive cutover that spans many files for one reason). Declaring \`wide\` lifts the hard file-width ceiling — see below.

package/.agents/scripts/lib/test-tiers.js

@@ -33,20 +33,26 @@ const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
  * `tests` holds the framework's suite tree; `lib` holds the published CLI
  * (under `lib/cli` and `lib/migrations`) whose tests are colocated in
  * `__tests__` directories per the unit-tier convention in
- * `rules/testing-standards.md`. Without `lib` here, both the quick /
- * integration walk and the full-tier glob set miss the colocated CLI tests,
+ * `rules/testing-standards.md`. `.agents/scripts` holds the orchestration
+ * engine; some of its modules colocate tests in `__tests__` directories the
+ * same way (Story #4195). Without each root here, both the quick /
+ * integration walk and the full-tier glob set miss the colocated tests,
  * leaving that coverage dark in `npm test`. The matching full-tier globs
  * live in `FULL_TIER_GLOBS`.
  */
-const TEST_WALK_ROOTS = ['tests', 'lib'];
+const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
 
 /**
  * Glob targets for the `full` tier — one per walk root in `TEST_WALK_ROOTS`.
- * The `tests` glob is a flat recursive sweep; the `lib` glob is scoped to
- * `__tests__` subtrees so it only matches colocated tests, never the shipped
- * source modules themselves.
+ * The `tests` glob is a flat recursive sweep; the `lib` and `.agents/scripts`
+ * globs are scoped to `__tests__` subtrees so they only match colocated
+ * tests, never the shipped source modules themselves.
  */
-const FULL_TIER_GLOBS = ['tests/**/*.test.js', 'lib/**/__tests__/**/*.test.js'];
+const FULL_TIER_GLOBS = [
+  'tests/**/*.test.js',
+  'lib/**/__tests__/**/*.test.js',
+  '.agents/scripts/**/__tests__/**/*.test.js',
+];
 
 /**
  * @param {string} dir