mandrel 2.10.0 → 2.11.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -26,7 +26,7 @@ import {
   renderTechSpecSystemPrompt,
 } from '../templates/spec-author-prompts.js';
 import { concurrentMap } from '../util/concurrent-map.js';
-import { buildComplexityRouteSignal } from './complexity-gate.js';
+import { buildComplexitySignals } from './complexity-gate.js';
 import { parseDeliverySlicingTable } from './consolidation-precondition.js';
 import { buildDocsDigest } from './docs-digest.js';
 import { buildAuthoringContext } from './planning/authoring-context.js';
@@ -144,6 +144,41 @@ export const TICKET_SCHEMA_DESCRIPTOR = Object.freeze({
  */
 export const STORIES_TEMPLATE_FILENAME = 'stories.template.json';
 
+/**
+ * Build the template's `changes[]` entries from the envelope's advisory
+ * complexity signals (Story #4723). Each seed-predicted path is
+ * pre-resolved to its creates-vs-refactors assumption against the repo
+ * snapshot the signals already probed: a path present in the repo is a
+ * `refactors-existing`, a missing one is a `creates`. Order follows
+ * `predictedPaths` (first appearance in the seed). Falls back to the
+ * single instructive placeholder entry when the seed predicted no paths.
+ *
+ * @param {{
+ *   predictedPaths?: string[],
+ *   repoState?: { existingPaths?: string[], missingPaths?: string[] },
+ * }|null|undefined} complexitySignals
+ * @returns {Array<{ path: string, assumption: string }>}
+ */
+function buildTemplateChanges(complexitySignals) {
+  const predicted = Array.isArray(complexitySignals?.predictedPaths)
+    ? complexitySignals.predictedPaths.filter(
+        (p) => typeof p === 'string' && p.length > 0,
+      )
+    : [];
+  if (predicted.length === 0) {
+    return [{ path: 'path/to/file.ext', assumption: 'refactors-existing' }];
+  }
+  const existing = new Set(
+    Array.isArray(complexitySignals?.repoState?.existingPaths)
+      ? complexitySignals.repoState.existingPaths
+      : [],
+  );
+  return predicted.map((path) => ({
+    path,
+    assumption: existing.has(path) ? 'refactors-existing' : 'creates',
+  }));
+}
+
 /**
  * Render the ready-to-fill `stories.json` authoring template (Story #4707).
  *
@@ -158,12 +193,23 @@ export const STORIES_TEMPLATE_FILENAME = 'stories.template.json';
  * / `verify[]` live at the ticket's top level — the machine contract persist
  * syncs into the body.
  *
+ * Correct-by-construction skeleton (Story #4723): the emitted `verify[]`
+ * placeholder already ends with a valid `(tier)` tag (swap `(unit)` for
+ * `(contract)` / `(e2e)` / `(validate)` where appropriate), and when the
+ * envelope's `complexitySignals` predicted a footprint the `changes[]`
+ * entries arrive pre-resolved to creates-vs-refactors against the repo
+ * snapshot — a faithfully-filled skeleton passes the persist ticket
+ * validators without a mechanical round-trip. The persist gates stay
+ * authoritative (they probe the base branch ref, not the working tree).
+ *
  * Pure and deterministic; the output is valid JSON (parseable as-is), with
  * instructive placeholder values rather than comments.
  *
+ * @param {{ complexitySignals?: object|null }} [opts] Envelope signals to
+ *   pre-resolve the skeleton against; omit for the bare placeholder shape.
  * @returns {string} Pretty-printed JSON template content.
  */
-export function renderStoriesTemplate() {
+export function renderStoriesTemplate({ complexitySignals = null } = {}) {
   const template = [
     {
       slug: 'fill-hyphen-case-slug',
@@ -176,11 +222,9 @@ export function renderStoriesTemplate() {
           'codes, security invariants, and load-bearing constraints with ' +
           'their why. Implementation choices belong to the deliverer unless ' +
           'load-bearing. No per-file behavior paragraphs, no current-state ' +
-          'narration. Delete this field when acceptance[] carries the whole ' +
-          'contract.',
-        changes: [
-          { path: 'path/to/file.ext', assumption: 'refactors-existing' },
-        ],
+          'narration. Keep it under ~250 words (soft advisory budget). ' +
+          'Delete this field when acceptance[] carries the whole contract.',
+        changes: buildTemplateChanges(complexitySignals),
         non_goals: [],
         reason_to_exist:
           'Fill: the single coherent reason this Story exists (one sentence).',
@@ -188,7 +232,9 @@ export function renderStoriesTemplate() {
       acceptance: [
         'Fill: a testable, observable criterion (a command exits 0, a file exists, a test matches)',
       ],
-      verify: ['Fill: exact command or test path (unit|contract|e2e|validate)'],
+      verify: [
+        'Fill: exact command or test path — keep the trailing tier tag valid: unit, contract, e2e, or validate (unit)',
+      ],
       depends_on: [],
     },
   ];
@@ -540,7 +586,15 @@ async function buildSeedFileModeEnvelope({
   return {
     mode: modeLabel,
     seed: { path: seedFilePath ?? null, content },
-    complexityRoute: buildComplexityRouteSignal({ seedText: content, config }),
+    // Advisory complexity signals only (Story #4722): no route, no routing
+    // authority. The planner authors the trivial-vs-standard verdict; persist
+    // validates a lite claim against the authored Story's shape.
+    complexitySignals: buildComplexitySignals({
+      seedText: content,
+      config,
+      riskHeuristics: heuristics,
+      cwd,
+    }),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,
@@ -694,7 +748,12 @@ async function buildTicketsModeEnvelope({
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
-    complexityRoute: buildComplexityRouteSignal({ seedText: seed, config }),
+    complexitySignals: buildComplexitySignals({
+      seedText: seed,
+      config,
+      riskHeuristics: heuristics,
+      cwd,
+    }),
     duplicates,
     docsContext,
     codebaseSnapshot: authoring.codebaseSnapshot,

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -44,7 +44,12 @@ import { anchorTempRoot, tempRootFrom } from '../../config/temp-paths.js';
 import { getLimits, PROJECT_ROOT } from '../../config-resolver.js';
 import { gitSpawn } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
-import { applyPlannerDowngrade, LITE_ROUTE_LABEL } from '../complexity-gate.js';
+import {
+  deriveStoryShape,
+  LITE_ROUTE_LABEL,
+  resolveComplexityGate,
+  resolvePlannerRouteVerdict,
+} from '../complexity-gate.js';
 import {
   appendCriticSkip,
   readPlanMetrics,
@@ -264,65 +269,105 @@ async function renderRunScopedPlanMetricsLine({
 
 /**
  * Resolve the plan's **effective** complexity route for persist
- * (Story #4707).
+ * (Story #4722, superseding the envelope-verdict model of Story #4707).
+ *
+ * Two staged inputs, no word count anywhere:
  *
- * The deterministic verdict rides in on the captured plan-context envelope's
- * `complexityRoute`. Layered on top is the audited planner downgrade: a
- * `full` verdict downgrades to `lite` **only** when the operator/planner
- * passed `--route-downgrade-reason` with a non-empty reason
- * (`applyPlannerDowngrade` — absent a recorded reason the deterministic
- * verdict stands, and the gate itself still fails toward `full`).
+ *   1. **The planner's authored verdict** — `--route-downgrade-reason` is the
+ *      lite claim's recorded reason (`resolvePlannerRouteVerdict`). No
+ *      recorded reason means no claim: the plan persists as standard `full`
+ *      and nothing is ledgered (`null`).
+ *   2. **The deterministic shape backstop** — a lite claim is validated
+ *      against every assembled Story's own shape (`deriveStoryShape` over its
+ *      `changes[]`, acceptance count, creates-vs-refactors mix, and
+ *      sensitive-path classes). Any Story exceeding the ceilings **fails the
+ *      claim closed to `full`** — the honest gate: after authoring, the work
+ *      has measurable shape, so complexity is read from the work, not guessed
+ *      from the seed.
  *
  * The resolved route decides whether the created Stories carry the
- * {@link LITE_ROUTE_LABEL} marker and a `route` block on their
- * `story-plan-state` checkpoint — the persisted, ledgered record `/deliver`
- * reads. A full route persists **no** marker and no checkpoint block:
- * absence is the conservative default.
+ * {@link LITE_ROUTE_LABEL} **hint** (never the control signal — `/deliver`
+ * re-derives the route from the Story body's shape) and the `route` block
+ * ledgered on their `story-plan-state` checkpoint, including the authored
+ * verdict, its recorded reason, and the per-Story shape evidence. A refused
+ * claim is ledgered too (route `full` with the refusal reasons), so the
+ * judgment stays auditable either way.
  *
  * Module-private: reachable end to end through {@link runPlanPersist}
  * (whose result reports the resolved route), so there is no test-only
  * export to leave production-dead.
  *
- * @param {{ planContextEnvelope?: object|null, routeDowngradeReason?: string|null }} args
- * @returns {{ route: 'lite'|'full', reasons: string[], downgraded: { from: 'full', reason: string }|null }|null}
- *   `null` when no envelope carried a verdict (nothing to persist).
+ * @param {{
+ *   stories: ReturnType<typeof assemblePlanStories>['stories'],
+ *   routeDowngradeReason?: string|null,
+ *   config?: object,
+ * }} args
+ * @returns {{
+ *   route: 'lite'|'full',
+ *   reasons: string[],
+ *   authored: { route: 'lite', reason: string },
+ *   shape: Array<{ slug: string, route: string, reasons: string[], shape: object|null }>,
+ * }|null} `null` when the planner authored no verdict (nothing to persist).
  */
 function resolveEffectiveRoute({
-  planContextEnvelope = null,
+  stories,
   routeDowngradeReason = null,
-} = {}) {
-  const verdict = planContextEnvelope?.complexityRoute ?? null;
-  if (!verdict || typeof verdict !== 'object') {
-    if (
-      typeof routeDowngradeReason === 'string' &&
-      routeDowngradeReason.trim() !== ''
-    ) {
-      Logger.warn(
-        '[plan-persist] --route-downgrade-reason was passed but no captured ' +
-          'plan-context envelope carries a complexityRoute verdict — there ' +
-          'is no full verdict to downgrade, so the plan persists as full ' +
-          '(no route marker).',
-      );
-    }
-    return null;
+  config = {},
+}) {
+  const verdict = resolvePlannerRouteVerdict({ reason: routeDowngradeReason });
+  if (verdict.route !== 'lite') return null;
+
+  // The schema's documented contract: with the gate disabled
+  // (`planning.complexityGate.enabled=false`), persist refuses lite claims —
+  // the same switch dispatch reads (`resolveStoryDispatchMode` falls back to
+  // sub-agent), so neither read point can honor a lite claim the operator
+  // has switched off. The refusal is ledgered like any other, keeping the
+  // judgment auditable.
+  if (!resolveComplexityGate(config).enabled) {
+    return {
+      route: 'full',
+      reasons: [
+        'planner lite verdict refused: complexity routing is disabled ' +
+          '(planning.complexityGate.enabled=false)',
+      ],
+      authored: verdict.authored,
+      shape: [],
+    };
   }
-  const effective = applyPlannerDowngrade(verdict, {
-    reason: routeDowngradeReason,
+
+  const perStory = (Array.isArray(stories) ? stories : []).map((story) => {
+    const derived = deriveStoryShape({
+      changes: story.bodyObject?.changes,
+      acceptance: story.acceptance,
+    });
+    return {
+      slug: story.slug,
+      route: derived.route,
+      reasons: derived.reasons,
+      shape: derived.shape,
+    };
   });
-  if (
-    typeof routeDowngradeReason === 'string' &&
-    routeDowngradeReason.trim() !== '' &&
-    effective.downgraded == null
-  ) {
-    Logger.warn(
-      '[plan-persist] --route-downgrade-reason had no effect: the envelope ' +
-        `verdict is already "${verdict.route}" — nothing to downgrade.`,
-    );
+  const offenders = perStory.filter((entry) => entry.route !== 'lite');
+  if (offenders.length > 0) {
+    return {
+      route: 'full',
+      reasons: [
+        `planner lite verdict refused: ${offenders.length} of ${perStory.length} ` +
+          'Story(ies) exceed the lite shape ceilings — failing closed to full',
+        ...offenders.map((entry) => `${entry.slug}: ${entry.reasons[0]}`),
+      ],
+      authored: verdict.authored,
+      shape: perStory,
+    };
   }
   return {
-    route: effective.route === 'lite' ? 'lite' : 'full',
-    reasons: Array.isArray(effective.reasons) ? effective.reasons : [],
-    downgraded: effective.downgraded ?? null,
+    route: 'lite',
+    reasons: [
+      ...verdict.reasons,
+      'shape backstop: every authored Story fits the lite shape ceilings',
+    ],
+    authored: verdict.authored,
+    shape: perStory,
   };
 }
 
@@ -424,7 +469,6 @@ export async function runPlanPersist({
     stories: rawStories = null,
     techSpecContent = null,
     planAcceptance = null,
-    planContextEnvelope = null,
   } = artifacts ?? {};
   const {
     forceReview = false,
@@ -513,22 +557,28 @@ export async function runPlanPersist({
     sourceTicketIds,
   });
 
-  // Effective complexity route (Story #4707): envelope verdict, plus the
-  // audited planner downgrade when --route-downgrade-reason was recorded.
-  // Lite persists the `route::lite` marker + a checkpoint block; full
-  // persists nothing.
+  // Effective complexity route (Story #4722): the planner's authored lite
+  // verdict (recorded reason), validated against every assembled Story's own
+  // shape — a claim exceeding the shape ceilings fails closed to full. Lite
+  // persists the `route::lite` HINT label + a checkpoint route block; a
+  // refused claim ledgers the refusal (no label); no claim persists nothing.
   const route = resolveEffectiveRoute({
-    planContextEnvelope,
+    stories,
     routeDowngradeReason,
+    config,
   });
   const isLiteRoute = route?.route === 'lite';
   if (isLiteRoute) {
     Logger.info(
-      `[plan-persist] ceremony-lite route: created Stories carry the ` +
-        `${LITE_ROUTE_LABEL} marker` +
-        (route.downgraded
-          ? ` (planner downgrade, recorded reason: ${route.downgraded.reason})`
-          : ' (deterministic gate verdict)'),
+      `[plan-persist] ceremony-lite route upheld by the shape backstop: ` +
+        `created Stories carry the ${LITE_ROUTE_LABEL} hint ` +
+        `(recorded reason: ${route.authored.reason}). /deliver re-derives ` +
+        'the route from each Story body — the label is never the control signal.',
+    );
+  } else if (route) {
+    Logger.warn(
+      `[plan-persist] ${route.reasons.join('; ')} — persisting as full ` +
+        '(no route hint label).',
     );
   }
 
@@ -586,10 +636,11 @@ export async function runPlanPersist({
             id: createdStory.id,
           })),
         },
-        // Ledger the lite route — including any planner downgrade and its
-        // recorded reason — on plan state (Story #4707). A full route writes
-        // no block: absence of the marker is the full path.
-        ...(isLiteRoute ? { route } : {}),
+        // Ledger the authored route verdict — the recorded reason and the
+        // per-Story shape evidence, including a shape-refused claim — on plan
+        // state (Story #4722). No authored verdict writes no block: absence
+        // is the standard full path.
+        ...(route ? { route } : {}),
       });
     }
     await upsertStructuredComment(

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -46,7 +46,11 @@ export const PLAN_RUN_LABEL_PREFIX = 'plan-run::';
 /** Stable color for the cohort grouping label (`ensureLabels`). */
 const PLAN_RUN_LABEL_COLOR = '#C5DEF5';
 
-/** Stable color for the `route::lite` ceremony-route marker (Story #4707). */
+/**
+ * Stable color for the `route::lite` ceremony-route hint (Story #4707;
+ * hint-only since Story #4722 — `/deliver` re-derives the route from the
+ * Story body's shape).
+ */
 const LITE_ROUTE_LABEL_COLOR = '#D4C5F9';
 
 /** Length of the derived plan-run id (hex chars). */
@@ -694,9 +698,10 @@ async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
  * route, and an opaque derived label never exists yet.
  *
  * **Non-fatal by design**, matching the native-blocked_by mirroring posture:
- * neither label is load-bearing for correctness (grouping is cosmetic; a
- * missing route marker degrades a lite Story to the standard — safer —
- * sub-agent dispatch), so it is never a reason to fail persist. On an ensure
+ * neither label is load-bearing for correctness (grouping is cosmetic, and
+ * the route label is a human-visible hint only — `/deliver` re-derives the
+ * route from the Story body's shape, Story #4722), so it is never a reason
+ * to fail persist. On an ensure
  * failure (throw, or the label reported `missing` by the post-loop
  * reconcile) the create loop proceeds **without** the label — applying an
  * unensured label could fail the issue create itself, and the Stories matter
@@ -782,15 +787,16 @@ async function ensurePersistLabel({
  * every id is known (Story #4544), so plan-created order stops depending on
  * prose. That pass is non-fatal — see `mirrorNativeDependencyEdges`.
  *
- * **A lite-routed cohort carries the `route::lite` marker** (Story #4707).
- * When the caller resolves the plan's effective complexity route to `lite`
- * (envelope verdict, or an audited planner downgrade), it passes the marker
- * via `opts.routeLabel` and every created Story carries it — the persisted,
- * `/deliver`-readable form of the route (`resolveStoryDispatchMode`). A
- * full-routed plan passes nothing and its Stories carry **no** route marker.
- * Like the cohort label, the ensure is non-fatal: a Story created without
- * the marker degrades to the standard sub-agent dispatch, never to a skipped
- * gate.
+ * **A lite-routed cohort carries the `route::lite` hint** (Story #4707,
+ * hint-only since Story #4722). When the caller resolves the plan's
+ * effective complexity route to `lite` (the planner's recorded verdict,
+ * upheld by the shape backstop), it passes the label via `opts.routeLabel`
+ * and every created Story carries it — a **human-visible hint only**, never
+ * the control signal: `/deliver` re-derives the route from each Story body's
+ * own shape (`resolveStoryDispatchMode`), so a lost or failed label write
+ * cannot misroute delivery. A full-routed plan passes nothing and its
+ * Stories carry **no** route label. Like the cohort label, the ensure is
+ * non-fatal — the label is cosmetic either way.
  *
  * @param {object} args
  * @param {object} args.provider
@@ -857,8 +863,8 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       label: routeLabel,
       color: LITE_ROUTE_LABEL_COLOR,
       description:
-        'Ceremony-lite route marker: /deliver executes this Story inline ' +
-        '(no sub-agent fan-out); every close gate runs unchanged.',
+        'Ceremony-lite hint (human-visible only): /deliver re-derives the ' +
+        'route from the Story body shape; every close gate runs unchanged.',
       role: 'route-marker',
     }));
 

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -307,23 +307,27 @@ export function buildStoriesEnvelope({
   nativeEdges = new Map(),
   foreignDone = [],
   warn,
+  config,
 }) {
   const sorted = [...stories].sort((a, b) => a.id - b.id);
   const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
   return {
     kind: 'stories',
-    // `dispatchMode` (Story #4707): the resolver derives the per-Story
-    // execution mode from the persisted `route::lite` marker so `/deliver`
-    // reads one field — `inline` (lite: no story-worker / acceptance-critic
-    // sub-agent boots) or `subagent` (everything else, the conservative
-    // default). Model-side fan-out only; close gates are untouched.
-    stories: sorted.map(({ id, title, url, labels, state }) => ({
+    // `dispatchMode` (Story #4722): the resolver derives the per-Story
+    // execution mode from the fetched Story BODY's own shape (the shared
+    // shape function in `complexity-gate.js`) so `/deliver` reads one field —
+    // `inline` (lite-shaped: no story-worker / acceptance-critic sub-agent
+    // boots) or `subagent` (everything else, the conservative default). The
+    // `route::lite` label is a human-visible hint only, never the control
+    // signal: a lost label cannot misroute delivery. Model-side fan-out
+    // only; close gates are untouched.
+    stories: sorted.map(({ id, title, body, url, labels, state }) => ({
       id,
       title,
       url,
       labels,
       state,
-      dispatchMode: resolveStoryDispatchMode({ labels }).mode,
+      dispatchMode: resolveStoryDispatchMode({ body, labels, config }).mode,
     })),
     dag: storiesToDag(sorted, nativeEdges, warn),
     done: [...new Set([...inSetDone, ...foreignDone])].sort((a, b) => a - b),

package/.agents/scripts/lib/orchestration/review-depth.js

@@ -74,10 +74,15 @@ export const DEFAULT_DIFF_WIDTH = Object.freeze({
  * changed-file set intersect any sensitive-path class registered in
  * `audit-rules.json`?
  *
- * This is the **single source** of the derived level — both the review depth
- * ({@link resolveDepth}) and the acceptance-critic fresh-vs-inline routing
- * (`ceremony-routing.js#resolveCeremonyForRisk`) consume what this returns, so
- * the two ceremony decisions can never disagree about how risky a change is.
+ * This is the **single source** of the derived level — the review depth
+ * ({@link resolveDepth}), the acceptance-critic fresh-vs-inline routing
+ * (`ceremony-routing.js#resolveCeremonyForRisk`), and the dispatch-side
+ * complexity routing (`complexity-gate.js#deriveStoryShape`, Story #4722)
+ * all consume what this returns, so no ceremony decision can disagree about
+ * how risky a change is. Dispatch reads the **predicted** shape (the Story's
+ * declared `changes[]` footprint) and close reads the **actual** diff — one
+ * taxonomy, two read points, which is what keeps a lite-shaped Story whose
+ * footprint touches a sensitive path on the full route with its fresh critic.
  *
  * Returns `null` — the fail-safe "no derivable signal" level — when the change
  * set is empty/unknown or the manifest cannot be read. Both downstream

package/.agents/scripts/lib/orchestration/spec-budget.js

@@ -0,0 +1,78 @@
+/**
+ * lib/orchestration/spec-budget.js — the soft `## Spec` word-budget pass
+ * (Story #4723), extracted from `ticket-validator.js` so the advisory
+ * length nudge lives beside neither the hard validators nor their error
+ * channel: everything here is `'soft'` by construction and can never fail
+ * a persist.
+ */
+
+import { parse as parseStoryBody } from '../story-body/story-body.js';
+
+/**
+ * Soft advisory word budget for a Story's inline `## Spec` (Story #4723).
+ * ~250 words is the #4707 contract-level-prose target: interfaces,
+ * invariants, and load-bearing constraints — not route-by-route behavior
+ * narration. Distinct from the hard ~1500-token fail-closed ceiling in
+ * `spec-spill.js`: this budget only warns; it never fails the persist.
+ */
+export const SPEC_SOFT_WORD_BUDGET = 250;
+
+/**
+ * Resolve a Story's Spec prose across both authoring shapes: the canonical
+ * serialized string body (parsed; `## Spec` text block) and the
+ * pre-serialize structured object body (`body.spec`). Returns `''` when
+ * absent — or when a string body does not parse: this pass is advisory, so
+ * an unreadable body contributes no finding here and is left to the hard
+ * parse gate (`assertStoryBodiesParse`) to reject.
+ *
+ * @param {object} story
+ * @returns {string}
+ */
+function resolveSpecText(story) {
+  const body = story?.body;
+  if (typeof body === 'string' && body.trim().length > 0) {
+    let spec;
+    try {
+      spec = parseStoryBody(body).body.spec;
+    } catch {
+      return '';
+    }
+    return typeof spec === 'string' ? spec : '';
+  }
+  if (body !== null && typeof body === 'object') {
+    return typeof body?.spec === 'string' ? body.spec : '';
+  }
+  return '';
+}
+
+/**
+ * Advisory `## Spec` length pass (Story #4723). Emits one `'soft'` finding
+ * per Story whose Spec prose exceeds {@link SPEC_SOFT_WORD_BUDGET} words,
+ * nudging the author toward contract-level prose (#4707). Soft only — the
+ * findings never reach the validator's `errors[]` channel, so an
+ * over-budget Spec never fails the persist.
+ *
+ * @param {{ stories: object[] }} opts
+ * @returns {object[]} Zero or more `spec-word-budget` findings.
+ */
+export function computeSpecBudgetFindings({ stories }) {
+  const findings = [];
+  for (const story of stories ?? []) {
+    const words = resolveSpecText(story).split(/\s+/).filter(Boolean).length;
+    if (words <= SPEC_SOFT_WORD_BUDGET) continue;
+    findings.push({
+      kind: 'spec-word-budget',
+      severity: 'soft',
+      ticketSlug: story.slug ?? '<unknown>',
+      words,
+      budget: SPEC_SOFT_WORD_BUDGET,
+      message:
+        `Story "${story.slug ?? '<unknown>'}" ## Spec is ~${words} words ` +
+        `(soft budget ${SPEC_SOFT_WORD_BUDGET}). Prefer contract-level prose ` +
+        '(interfaces, invariants, load-bearing constraints with their why) ' +
+        'over per-file behavior narration — advisory only; the persist ' +
+        'proceeds.',
+    });
+  }
+  return findings;
+}

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

@@ -0,0 +1,72 @@
+/**
+ * lib/orchestration/story-body-gate.js — the Story-body parse gate
+ * (Story #4541), extracted from `ticket-validator.js`: the one place a
+ * serialized Story body is parsed with parse failures translated into the
+ * validator's operator-legible `ValidationError` shape. Both the gate that
+ * refuses a plan up front (`assertStoryBodiesParse`) and the per-call
+ * translating parser (`parseStoryBodyOrThrow`) the downstream validators
+ * lean on live here.
+ */
+
+import { ValidationError } from '../errors/index.js';
+import {
+  parse as parseStoryBody,
+  StoryBodyParseError,
+} from '../story-body/story-body.js';
+
+/**
+ * Parse a Story's serialized markdown body, translating a
+ * `StoryBodyParseError` into a `ValidationError` that names the offending
+ * **section** and **entry** (Story #4541).
+ *
+ * `StoryBodyParseError` already carries `field` (the section the parser was
+ * reading) and `raw` (the entry text that failed); this lifts both into an
+ * operator-legible message and a structured `violation` payload so an
+ * authoring loop can point at the exact bullet instead of re-deriving it
+ * from a downstream freshness miss.
+ *
+ * @param {object} story Story whose `body` is a non-empty markdown string.
+ * @returns {object} The structured body.
+ * @throws {ValidationError} `code: 'story-body-unparseable'`.
+ */
+export function parseStoryBodyOrThrow(story) {
+  try {
+    return parseStoryBody(story.body).body;
+  } catch (err) {
+    if (!(err instanceof StoryBodyParseError)) throw err;
+    const slug = story.slug ?? '<unknown>';
+    const section = err.field ?? 'body';
+    const entry = err.raw ?? null;
+    const entryLine = entry === null ? '' : `\n      entry: ${entry}`;
+    const violation = { slug, section, entry, reason: err.message };
+    const error = new ValidationError(
+      `Cross-Validation Failed: Story "${slug}" has an unparseable body — ` +
+        `the ## ${section} section could not be read: ${err.message}` +
+        `${entryLine}\n\nFix the offending entry; this is a malformed body, ` +
+        'not a stale path reference.',
+      { violations: [violation] },
+    );
+    error.code = 'story-body-unparseable';
+    error.violations = [violation];
+    throw error;
+  }
+}
+
+/**
+ * Refuse the plan when any Story's serialized body cannot be parsed, before
+ * either git-probe gate runs (Story #4541). Ordering matters: the freshness
+ * gate consults `body.changes` for its net-new whitelist, so an unparseable
+ * body used to reach the operator as a freshness miss naming declared paths.
+ *
+ * @param {{ tickets: object[] }} opts
+ * @throws {ValidationError} `code: 'story-body-unparseable'` on the first
+ *   offending Story.
+ */
+export function assertStoryBodiesParse({ tickets }) {
+  for (const story of (tickets ?? []).filter((t) => t.type === 'story')) {
+    if (typeof story.body !== 'string' || story.body.trim().length === 0) {
+      continue;
+    }
+    parseStoryBodyOrThrow(story);
+  }
+}

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

@@ -829,6 +829,12 @@ export function renderHardConflictError(finding) {
   if (finding.kind === 'missing-bdd-scaffold') {
     return `Missing BDD scaffold: Story "${finding.consumer.storySlug}" verifies against "${finding.path}" (created by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but "${finding.consumer.storySlug}" has no depends_on path to "${finding.producer.storySlug}" — the .feature file is scaffolded in the same wave (or later), so verification runs before the file exists. Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story so the scaffold lands in an earlier wave.`;
   }
+  // Findings from other passes (sizing, spec-word-budget) carry their own
+  // message — render it rather than a shape-blind generic line, so the soft
+  // surface (`surfaceSoftConflictFindings`) stays legible for every kind.
+  if (typeof finding.message === 'string' && finding.message.length > 0) {
+    return finding.message;
+  }
   return `Conflict finding ${finding.kind} on path "${finding.path ?? '<unknown>'}".`;
 }