mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/story-close/phases/locked-pipeline.js

@@ -41,9 +41,34 @@ import { emitSpawnTimeoutBlockedResult } from './timeout-blocked-emitter.js';
  * Run pre-merge gates and, on a clean outcome, the bounded baseline
  * auto-refresh. Returns `{ blocked }` so the locked pipeline can
  * short-circuit on a `blocked` / `blocked-timeout` gate outcome.
+ *
+ * `runPreMergeValidation` is an injectable seam (Story #3973): the
+ * forwarding of `config: ctx.config` into the gate builder is load-bearing
+ * — without it the typecheck gate ignores `project.commands.typecheck` and
+ * falls back to the hardcoded `npm run typecheck`, blocking every close for
+ * any consumer with a non-default typecheck command. The default is the
+ * module-level `runPreMergeValidation`; tests inject a spy to pin that
+ * `config` reaches the gate builder through this call site.
+ *
+ * @param {object} ctx - The locked-pipeline context bundle.
+ * @param {object} [deps] - Injectable collaborators.
+ * @param {typeof runPreMergeValidation} [deps.runPreMergeValidationFn]
+ * @param {typeof runAutoRefreshSafely} [deps.runAutoRefreshSafelyFn]
  */
-async function runGatesAndRefresh(ctx) {
-  const gateOutcome = await runPreMergeValidation({
+export async function runGatesAndRefresh(
+  ctx,
+  {
+    runPreMergeValidationFn = runPreMergeValidation,
+    runAutoRefreshSafelyFn = runAutoRefreshSafely,
+  } = {},
+) {
+  // Story #4017 — one shared cycle-state object per close cycle. The
+  // gate-failure attribution retry and the post-gates auto-refresh both
+  // funnel through `runRefreshCommit`, which keys its idempotency token
+  // off this object so each baseline kind is refreshed (scored +
+  // committed) at most once per close.
+  const cycleState = { refreshedKinds: new Set(), lastRefreshSha: null };
+  const gateOutcome = await runPreMergeValidationFn({
     cwd: ctx.cwd,
     worktreePath: ctx.worktreePath,
     epicBranch: ctx.epicBranch,
@@ -55,6 +80,7 @@ async function runGatesAndRefresh(ctx) {
     phaseTimer: ctx.phaseTimer,
     provider: ctx.provider,
     bus: ctx.bus,
+    cycleState,
   });
   if (gateOutcome?.status === 'blocked') {
     return {
@@ -82,7 +108,7 @@ async function runGatesAndRefresh(ctx) {
       }),
     };
   }
-  await runAutoRefreshSafely(
+  await runAutoRefreshSafelyFn(
     {
       storyId: ctx.storyId,
       epicId: ctx.epicId,
@@ -90,6 +116,7 @@ async function runGatesAndRefresh(ctx) {
       epicBranch: ctx.epicBranch,
       storyBranch: ctx.storyBranch,
       config: ctx.config,
+      cycleState,
     },
     { progress: ctx.progress },
   );
@@ -100,7 +127,7 @@ async function runGatesAndRefresh(ctx) {
  * Read the parent Epic's judged `planningRisk` envelope off its
  * `epic-plan-state` checkpoint so the Story-scope review can inherit the
  * Epic's review depth (Story #3940). Best-effort and total — it reuses the
- * shared `read` from `epic-plan-state-store.js` (the same reader `/epic-plan
+ * shared `read` from `epic-plan-state-store.js` (the same reader `/plan
  * --resume` and `epic-audit-prepare.js`'s `resolveRiskRoutedLenses` use, no
  * third bespoke reader) and never fails the close:
  *
@@ -110,7 +137,7 @@ async function runGatesAndRefresh(ctx) {
  *
  * A `null` result threads through `runStoryCodeReview` → `runCodeReview`
  * unchanged, so depth resolves from diff width alone (`standard`), preserving
- * today's behaviour for an Epic that skipped `/epic-plan`.
+ * today's behaviour for an Epic that skipped `/plan`.
  *
  * @param {{ provider: object, epicId: number|null|undefined, readPlanStateFn?: typeof readPlanState }} args
  * @returns {Promise<{ overallLevel?: string, axes?: Array<object> }|null>}

package/.agents/scripts/lib/orchestration/story-close/post-merge-close.js

@@ -21,14 +21,8 @@
  * read it; this helper writes the file and hands the path to the pipeline.
  */
 
-// Legacy key on the post-merge-pipeline / cleanup-reconciler input bag.
-// Built from substrings so the migrated-subsystem grep does not match it;
-// the downstream helpers live outside the migrated subsystem and will
-// rename their parameters when their own subsystems are swept.
-const LEGACY_PIPELINE_CONFIG_KEY = `orches${'tration'}`;
-
 import { mkdir, writeFile } from 'node:fs/promises';
-import { emitGhSpawnCount as defaultEmitGhSpawnCount } from '../../close-validation.js';
+import { emitGhSpawnCount as defaultEmitGhSpawnCount } from '../../close-validation/telemetry.js';
 import { storyArtifactPath, storyTempDir } from '../../config/temp-paths.js';
 import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
 import { clearActiveStoryEnv as defaultClearActiveStoryEnv } from '../../observability/active-story-env.js';
@@ -340,18 +334,11 @@ export async function runPostMergeClose({
   // in this order — see post-merge-pipeline.js. The `perf-summary` phase
   // inside the pipeline shells out to analyze-execution.js, which is the
   // single writer of the `<!-- structured:story-perf-summary -->` comment.
-  // Build the legacy-shape view that downstream out-of-subsystem helpers
-  // (post-merge-pipeline.js) still consume. The migrated cleanup-reconciler
-  // takes `delivery` directly.
-  const legacyPipelineBlock = {
-    provider: 'github',
-    github: config?.github,
-    notifications: config?.github?.notifications,
-    worktreeIsolation: deliveryBlock?.worktreeIsolation,
-    runners: { deliverRunner: deliveryBlock?.deliverRunner ?? {} },
-  };
+  // The pipeline phases take the resolved `delivery` block directly, same
+  // as the cleanup-reconciler (Story #3986 — the legacy `orchestration`-keyed
+  // input bag is gone).
   const pipelineState = await runPostMergePipeline({
-    [LEGACY_PIPELINE_CONFIG_KEY]: legacyPipelineBlock,
+    delivery: deliveryBlock,
     storyId,
     epicId,
     story,

package/.agents/scripts/lib/orchestration/story-close/pre-merge-validation.js

@@ -29,12 +29,12 @@
 // no-spawn spy proves the projection path never reaches a per-kind CLI
 // subprocess.
 import * as maintainabilityKind from '../../baselines/kinds/maintainability.js';
+import { buildDefaultGates as defaultBuildDefaultGates } from '../../close-validation/gates.js';
 import {
-  buildDefaultGates as defaultBuildDefaultGates,
   formatMaintainabilityProjection as defaultFormatMaintainabilityProjection,
   projectMaintainabilityRegressions as defaultProjectMaintainabilityRegressions,
-  runCloseValidation as defaultRunCloseValidation,
-} from '../../close-validation.js';
+} from '../../close-validation/projections/maintainability.js';
+import { runCloseValidation as defaultRunCloseValidation } from '../../close-validation/runner.js';
 import { getBaselines as defaultGetBaselines } from '../../config-resolver.js';
 import { Logger as DefaultLogger } from '../../Logger.js';
 

package/.agents/scripts/lib/orchestration/story-close-recovery.js

@@ -276,7 +276,7 @@ function detectAlreadyMerged({ cwd, storyId, epicId, lsrOut, detail, git }) {
   //    from the Epic history itself: locate the integration commit whose
   //    subject carries `(resolves #<id>)` / `(refs #<id>)`. Without this
   //    branch, detection falls to FRESH and the resumed close re-enters the
-  //    pre-merge gate chain, which crashes in `format-autofix-scoped.js` on
+  //    pre-merge gate chain, which crashes in the scoped format-autofix step on
   //    `git diff <epicBranch>...story-<id>` because the Story ref is gone.
   if (!resolvedDetail) {
     const mc = findMergeCommitForStory({ cwd, storyId, epicId, git });
@@ -431,24 +431,35 @@ export function computeRecoveryMode({ state, resume, restart } = {}) {
   };
 }
 
-function dropWorktreeIfPresent({ cwd, wtPath, progress, logger }) {
+function dropWorktreeIfPresent({
+  cwd,
+  wtPath,
+  progress,
+  logger,
+  gitSpawnFn = gitSpawn,
+}) {
   if (!fs.existsSync(wtPath)) return;
   progress('RESTART', `Removing worktree ${wtPath}`);
-  const remove = gitSpawn(cwd, 'worktree', 'remove', '--force', wtPath);
+  const remove = gitSpawnFn(cwd, 'worktree', 'remove', '--force', wtPath);
   if (remove.status !== 0) {
     logger.error(
       `[story-close] Worktree remove failed: ${remove.stderr || 'unknown'}. ` +
         'Attempting prune to clean stale registration.',
     );
   }
-  gitSpawn(cwd, 'worktree', 'prune');
+  gitSpawnFn(cwd, 'worktree', 'prune');
 }
 
-function recreateStoryBranchRef({ cwd, storyBranch, epicBranch, logger }) {
-  gitSpawn(cwd, 'branch', '-D', storyBranch);
-  const create = gitSpawn(cwd, 'branch', storyBranch, epicBranch);
+function recreateStoryBranchRef({
+  cwd,
+  storyBranch,
+  epicBranch,
+  gitSpawnFn = gitSpawn,
+}) {
+  gitSpawnFn(cwd, 'branch', '-D', storyBranch);
+  const create = gitSpawnFn(cwd, 'branch', storyBranch, epicBranch);
   if (create.status !== 0) {
-    logger.fatal(
+    throw new Error(
       `Failed to recreate ${storyBranch} from ${epicBranch}: ${create.stderr || 'unknown'}`,
     );
   }
@@ -460,13 +471,13 @@ function reseedWorktreeIfNeeded({
   storyId,
   storyBranch,
   progress,
-  logger,
+  gitSpawnFn = gitSpawn,
 }) {
   if (!wtConfig?.enabled) return;
   const wtPath = storyWorktreePath(cwd, storyId, wtConfig.root);
-  const add = gitSpawn(cwd, 'worktree', 'add', wtPath, storyBranch);
+  const add = gitSpawnFn(cwd, 'worktree', 'add', wtPath, storyBranch);
   if (add.status !== 0) {
-    logger.fatal(
+    throw new Error(
       `Failed to re-seed worktree at ${wtPath}: ${add.stderr || 'unknown'}`,
     );
   }
@@ -477,8 +488,12 @@ function reseedWorktreeIfNeeded({
  * Restart path: abort any in-progress merge, drop the worktree, delete the
  * story branch ref, and re-seed branch + worktree from the Epic branch. The
  * caller then falls through to the normal fresh-close flow.
+ *
+ * Throws (never `logger.fatal`) on a failed branch recreate or worktree
+ * re-seed, per `rules/orchestration-error-handling.md` — a failed recreate
+ * MUST NOT fall through into the worktree re-seed.
  */
-function restartStoryState({
+export function restartStoryState({
   cwd,
   orchestration,
   storyId,
@@ -486,9 +501,10 @@ function restartStoryState({
   storyBranch,
   progress = () => {},
   logger = Logger,
+  gitSpawnFn = gitSpawn,
 } = {}) {
   progress('RESTART', `Resetting prior state for Story #${storyId}...`);
-  gitSpawn(cwd, 'merge', '--abort');
+  gitSpawnFn(cwd, 'merge', '--abort');
 
   const wtConfig = orchestration?.worktreeIsolation;
   if (wtConfig?.enabled) {
@@ -497,17 +513,18 @@ function restartStoryState({
       wtPath: storyWorktreePath(cwd, storyId, wtConfig.root),
       progress,
       logger,
+      gitSpawnFn,
     });
   }
 
-  recreateStoryBranchRef({ cwd, storyBranch, epicBranch, logger });
+  recreateStoryBranchRef({ cwd, storyBranch, epicBranch, gitSpawnFn });
   reseedWorktreeIfNeeded({
     cwd,
     wtConfig,
     storyId,
     storyBranch,
     progress,
-    logger,
+    gitSpawnFn,
   });
 }
 
@@ -563,7 +580,7 @@ export function dispatchRecovery({
   restartFn = restartStoryState,
 } = {}) {
   if (resume && restart) {
-    logger.fatal('--resume and --restart are mutually exclusive');
+    throw new Error('--resume and --restart are mutually exclusive');
   }
 
   const priorPhase = detectFn({ cwd, storyId, epicId });

package/.agents/scripts/lib/orchestration/story-reachability.js

@@ -0,0 +1,47 @@
+/**
+ * lib/orchestration/story-reachability.js — Story `depends_on` graph walk.
+ *
+ * Houses the transitive-predecessor closure over the story-level
+ * `depends_on` graph. Extracted from `./ticket-validator-conflicts.js`
+ * under Story #3995 to break the `file-assumptions.js ↔
+ * ticket-validator-conflicts.js` import cycle: both the conflict gate and
+ * the wave-aware file-assumption gate need this graph traversal, so
+ * pulling it down into a dependency-free leaf lets both import it from
+ * below rather than from each other.
+ *
+ * This is a pure graph utility — no I/O, no policy. Its behaviour is
+ * unchanged from the original `computeStoryReachability`.
+ */
+
+/**
+ * Compute transitive predecessor sets over the story-level `depends_on`
+ * graph. The returned map is `Map<storySlug, Set<storySlug>>`, where the
+ * set contains every story reachable by following `depends_on` edges from
+ * the key (i.e. every story the key transitively depends on).
+ *
+ * BFS, no cycles assumed — callers must run `assertAcyclic` first.
+ *
+ * Exported so both the conflict gate (`ticket-validator-conflicts.js`)
+ * and the wave-aware file-assumption gate (`file-assumptions.js`) can
+ * reuse the same transitive-predecessor walk rather than re-deriving the
+ * `depends_on` closure.
+ */
+export function computeStoryReachability(stories) {
+  const reach = new Map();
+  for (const story of stories) reach.set(story.slug, new Set());
+  for (const story of stories) {
+    const visited = reach.get(story.slug);
+    const stack = [...(story.depends_on ?? [])];
+    while (stack.length > 0) {
+      const next = stack.pop();
+      if (!reach.has(next)) continue;
+      if (visited.has(next)) continue;
+      visited.add(next);
+      const nextStory = stories.find((s) => s.slug === next);
+      if (nextStory && Array.isArray(nextStory.depends_on)) {
+        for (const dep of nextStory.depends_on) stack.push(dep);
+      }
+    }
+  }
+  return reach;
+}

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -1,7 +1,7 @@
 /**
  * Story body schema validator (v5.33+).
  *
- * Enforces the four-section structured body shape on 3-tier Stories emitted
+ * Enforces the four-section structured body shape on 2-tier Stories emitted
  * by the decomposer. The canonical decomposition serializes every Story
  * `body` to a **markdown string** via `serialize()` from
  * `lib/story-body/story-body.js` (the decompose-author skill mandates this,
@@ -17,7 +17,7 @@
  *
  * Only `type: 'story'` tickets are validated; Feature/Epic tickets and
  * null/empty bodies pass through. There is no `type::task` ticket layer in
- * the 3-tier hierarchy (Epic → Feature → Story).
+ * the 2-tier hierarchy (Epic → Story).
  *
  * Required after parse/normalize: a non-empty `goal`, and non-empty
  * `changes`, `acceptance`, and `verify` arrays — and `changes` items must
@@ -110,7 +110,7 @@ function vagueVerbWithoutTarget(bullet) {
  *   - it has no body (null / undefined / empty-or-whitespace string — there
  *     is nothing to inspect).
  *
- * Under the 3-tier hierarchy (Epic → Feature → Story), Stories carry the
+ * Under the 2-tier hierarchy (Epic → Story), Stories carry the
  * implementation scope inline. A canonical decomposition serializes the
  * Story body to a markdown string, so a *string* body is NOT skipped here
  * (Story #3906) — `validateTaskBodyShape` parses it back into structured
@@ -127,7 +127,7 @@ function vagueVerbWithoutTarget(bullet) {
  */
 function shouldSkipTicket(ticket) {
   if (!ticket) return true;
-  // Only Stories carry an inline implementation contract in the 3-tier
+  // Only Stories carry an inline implementation contract in the 2-tier
   // world. Features (and everything else) use narrative bodies.
   if (ticket.type !== 'story') return true;
   const body = ticket.body;
@@ -197,7 +197,7 @@ export function validateTaskBodyShape(ticket) {
   }
   errors.push(...collectChangesErrors(prefix, body.changes));
   errors.push(...collectAcceptanceErrors(prefix, body.acceptance));
-  // Tier-suffix validation is always enforced on Story bodies (3-tier world).
+  // Tier-suffix validation is always enforced on Story bodies (2-tier world).
   errors.push(...collectVerifyErrors(prefix, body.verify));
   errors.push(...collectReferencesErrors(prefix, body.references));
   return errors;
@@ -359,7 +359,7 @@ function collectVerifyErrors(prefix, rawVerify) {
 }
 
 /**
- * Validate every 3-tier Story in `tickets` whose `body` is a structured
+ * Validate every 2-tier Story in `tickets` whose `body` is a structured
  * object. Returns an array of error strings (one per offending slug); empty
  * array means clean.
  *

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -96,7 +96,7 @@ export function normalizeOperatorHandle(raw) {
  * observability artifact never wedges the lease preflight.
  *
  * This is the shared liveness source the lease guards thread into
- * `acquireLease` via `heartbeatAt`; `/epic-plan` and `/epic-deliver` both
+ * `acquireLease` via `heartbeatAt`; `/plan` and `/deliver` both
  * reuse it so a live foreign claim actually refuses.
  *
  * @param {object} args

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -1,4 +1,5 @@
 import { collectStoryAssumptionEntries } from './file-assumptions.js';
+import { computeStoryReachability } from './story-reachability.js';
 
 /**
  * Cross-Story path-conflict & implicit-dependency findings.
@@ -66,7 +67,7 @@ const DEFAULT_POLICY = Object.freeze({
  *   - exact path  — `lib/orchestration/lifecycle/listeners/index.js`
  *   - `**` suffix — `**\/listeners/index.js` (matches any depth)
  */
-const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
+export const DEFAULT_REGISTRY_PATTERNS = Object.freeze([
   'lib/orchestration/lifecycle/listeners/index.js',
   '**/listeners/index.js',
   '**/handlers/index.js',
@@ -169,7 +170,7 @@ function collectStoryProducerPaths(story) {
 }
 
 /**
- * Resolve the Story-identifying slug for a 3-tier Story. A Story is its
+ * Resolve the Story-identifying slug for a 2-tier Story. A Story is its
  * own implementation unit (Epic #3238) — there is no parent Task — so the
  * producer/consumer indices key on the Story's own `slug`.
  */
@@ -186,7 +187,7 @@ function storySlugOf(story) {
  * producers.
  *
  * `taskSlug` is retained in the entry shape for finding/render
- * compatibility; in the 3-tier model it carries the Story's own slug since
+ * compatibility; in the 2-tier model it carries the Story's own slug since
  * the Story is the implementation unit.
  */
 function indexProducers(stories) {
@@ -242,38 +243,6 @@ function indexConsumers(stories, producers) {
   return consumers;
 }
 
-/**
- * Compute transitive predecessor sets over the story-level `depends_on`
- * graph. The returned map is `Map<storySlug, Set<storySlug>>`, where the
- * set contains every story reachable by following `depends_on` edges from
- * the key (i.e. every story the key transitively depends on).
- *
- * BFS, no cycles assumed — callers must run `assertAcyclic` first.
- *
- * Exported so the wave-aware file-assumption gate
- * (`file-assumptions.js`) can reuse the same transitive-predecessor walk
- * rather than re-deriving the `depends_on` closure.
- */
-export function computeStoryReachability(stories) {
-  const reach = new Map();
-  for (const story of stories) reach.set(story.slug, new Set());
-  for (const story of stories) {
-    const visited = reach.get(story.slug);
-    const stack = [...(story.depends_on ?? [])];
-    while (stack.length > 0) {
-      const next = stack.pop();
-      if (!reach.has(next)) continue;
-      if (visited.has(next)) continue;
-      visited.add(next);
-      const nextStory = stories.find((s) => s.slug === next);
-      if (nextStory && Array.isArray(nextStory.depends_on)) {
-        for (const dep of nextStory.depends_on) stack.push(dep);
-      }
-    }
-  }
-  return reach;
-}
-
 function inSameWave(reach, slugA, slugB) {
   if (slugA === slugB) return false;
   const a = reach.get(slugA);

package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js

@@ -39,15 +39,6 @@ export const DEFAULT_TASK_SIZING = Object.freeze({
   maxAcceptance: 14,
 });
 
-/**
- * Soft prose guidance for how many Stories a Feature typically decomposes
- * into before the Feature scope smells like two Features. Rendered into the
- * decomposer prompt's Feature-count sentence from this single constant so
- * the prompt prose cannot drift from the SSOT module (Story #3874). Advisory
- * only — no validator finding keys off it.
- */
-export const SOFT_STORIES_PER_FEATURE = 7;
-
 /**
  * `DELIVERABLE_GRANULARITY_GUIDANCE` is the **single source of truth** for the
  * deliverable-granularity definition of a Story (Story #3777). It is stated
@@ -339,7 +330,7 @@ function computeStorySizingFindings(story, sizing) {
  * `findings`; the AC-visible `errors[]` channel is the rendered
  * subset where `severity === 'hard'`.
  *
- * 3-tier (Epic #3238): each Story is its own implementation unit and
+ * 2-tier (Epic #3238): each Story is its own implementation unit and
  * carries the `body` (acceptance / changes / wide) that the sizing layers
  * score. There is no Task tier, so findings are computed directly over
  * `stories`.

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -200,9 +200,8 @@ function makeMemoizedGitRunner(runner) {
  * path was deleted between planning and decomposition) — refuse to decompose
  * because the resulting Task would be unimplementable as written.
  *
- * Only Tasks are scanned; Features and Stories carry narrative copy, not
- * implementation paths, and their bodies routinely reference docs/templates
- * the freshness regex would (correctly) ignore.
+ * Only Stories are scanned — they are the implementation unit; the Epic
+ * carries narrative copy, not implementation paths.
  *
  * @param {object}   opts
  * @param {object[]} opts.tickets         - Validated ticket hierarchy.
@@ -416,7 +415,6 @@ function renderMissLine({ slug, path }) {
 
 function indexTicketsBySlug(tickets) {
   const ticketBySlug = new Map();
-  const features = [];
   const stories = [];
   const slugAdjacency = new Map();
   for (const t of tickets) {
@@ -429,75 +427,37 @@ function indexTicketsBySlug(tickets) {
       ticketBySlug.set(t.slug, t);
     }
     slugAdjacency.set(t.slug, t.depends_on ?? []);
-    if (t.type === 'feature') features.push(t);
-    else if (t.type === 'story') stories.push(t);
+    if (t.type === 'story') stories.push(t);
   }
-  return { ticketBySlug, features, stories, slugAdjacency };
+  return { ticketBySlug, stories, slugAdjacency };
 }
 
-function assertEachTypePresent({ features, stories }) {
-  if (features.length === 0)
+/**
+ * 2-tier invariant (Story #4041): the decomposer emits Stories only — every
+ * ticket in the backlog must be `type: "story"` and at least one must be
+ * present. Any other type (the retired `feature`/`task` tiers, or planner
+ * hallucinations) HARD-rejects the decomposition.
+ */
+function assertAllTicketsAreStories({ tickets, stories }) {
+  const nonStories = (tickets ?? []).filter((t) => t.type !== 'story');
+  if (nonStories.length > 0) {
+    const list = nonStories
+      .map((t) => `"${t.title}" (${t.slug ?? '<no slug>'}, type: ${t.type})`)
+      .join(', ');
     throw new Error(
-      'Cross-Validation Failed: Backlog must contain at least one Feature.',
+      `Cross-Validation Failed: ${nonStories.length} ticket(s) are not Stories: ${list}. ` +
+        'The 2-tier hierarchy (Epic → Story) admits type "story" only — there is no Feature or Task tier.',
     );
+  }
   if (stories.length === 0)
     throw new Error(
       'Cross-Validation Failed: Backlog must contain at least one Story.',
     );
 }
 
-function assertHierarchy({ stories, ticketBySlug }) {
-  for (const story of stories) {
-    if (!story.parent_slug)
-      throw new Error(
-        `Cross-Validation Failed: Story "${story.title}" must have a parent_slug.`,
-      );
-    const parent = ticketBySlug.get(story.parent_slug);
-    if (!parent || parent.type !== 'feature')
-      throw new Error(
-        `Cross-Validation Failed: Story "${story.title}" parent must be a Feature.`,
-      );
-  }
-}
-
-/**
- * Deterministic invariant (Story #3777): a Feature MUST decompose into at
- * least two Stories. A single-Story Feature is the work of a Story, not a
- * Feature — the Feature wrapper is dead weight and signals decomposition at
- * module/task granularity rather than deliverable granularity. HARD-reject
- * the decomposition, naming the offending Feature(s) and telling the planner
- * to collapse them, in the same throw-on-violation style as the surrounding
- * hierarchy invariants.
- */
-function assertNoSingleStoryFeature({ features, stories }) {
-  const storyCountByParent = new Map();
-  for (const story of stories) {
-    if (!story.parent_slug) continue;
-    storyCountByParent.set(
-      story.parent_slug,
-      (storyCountByParent.get(story.parent_slug) ?? 0) + 1,
-    );
-  }
-  const undersized = features.filter(
-    (feature) => (storyCountByParent.get(feature.slug) ?? 0) < 2,
-  );
-  if (undersized.length === 0) return;
-  const list = undersized
-    .map((feature) => {
-      const count = storyCountByParent.get(feature.slug) ?? 0;
-      return `"${feature.title}" (${feature.slug}, ${count} ${count === 1 ? 'Story' : 'Stories'})`;
-    })
-    .join(', ');
-  throw new Error(
-    `Cross-Validation Failed: ${undersized.length} Feature(s) decompose into fewer than two Stories: ${list}. ` +
-      'Every Feature MUST contain at least two Stories — a single-Story Feature is the work of a Story, not a Feature. ' +
-      'Collapse each offending Feature: drop the Feature wrapper and attach its lone Story to a sibling Feature, or merge the Feature into another.',
-  );
-}
-
 /**
  * Return true when a Story object carries inline acceptance + verify
- * arrays — the 3-tier shape (Epic #3078) where the Story is itself the
+ * arrays — the inline-contract shape (Epic #3078) where the Story is itself the
  * implementation unit and acceptance / verify live on the Story body
  * rather than in child Task tickets.
  *
@@ -506,7 +466,7 @@ function assertNoSingleStoryFeature({ features, stories }) {
  * `acceptance[]` (no `verify[]`) cannot be implemented without a
  * verification handle, and a Story with only `verify[]` (no
  * `acceptance[]`) carries no observable criterion. Requiring both is the
- * inline-contract invariant every Story must satisfy in the 3-tier model.
+ * inline-contract invariant every Story must satisfy.
  */
 function hasInlineAcceptanceAndVerify(story) {
   if (story === null || typeof story !== 'object') return false;
@@ -520,7 +480,7 @@ function hasInlineAcceptanceAndVerify(story) {
 }
 
 function assertEveryStoryHasInlineContract({ stories }) {
-  // 3-tier (Epic #3078 / #3238): every Story is its own implementation
+  // Every Story is its own implementation
   // unit and MUST carry a non-empty inline contract — top-level
   // `acceptance[]` AND `verify[]`. A Story missing either is the legacy
   // 4-tier shape that expected child Tasks; there is no Task tier any
@@ -577,12 +537,9 @@ function attachFindingsAndErrors(tickets, findings, errors) {
 }
 
 export function validateAndNormalizeTickets(tickets, opts = {}) {
-  const { ticketBySlug, features, stories, slugAdjacency } =
-    indexTicketsBySlug(tickets);
+  const { ticketBySlug, stories, slugAdjacency } = indexTicketsBySlug(tickets);
 
-  assertEachTypePresent({ features, stories });
-  assertHierarchy({ stories, ticketBySlug });
-  assertNoSingleStoryFeature({ features, stories });
+  assertAllTicketsAreStories({ tickets, stories });
   assertEveryStoryHasInlineContract({ stories });
   assertNoUnknownDeps({ tickets, ticketBySlug });
 
@@ -680,9 +637,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 // Internal helpers exposed for unit tests; not part of the public surface.
 export const _internal = {
   indexTicketsBySlug,
-  assertEachTypePresent,
-  assertHierarchy,
-  assertNoSingleStoryFeature,
+  assertAllTicketsAreStories,
   assertEveryStoryHasInlineContract,
   assertNoUnknownDeps,
   assertAcyclic,