mandrel 2.10.0 → 2.12.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,108 @@ 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,
+ *   injectedRules?: 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 = {},
+  injectedRules,
+}) {
+  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,
+      injectedRules,
+    });
+    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,
   };
 }
 
@@ -410,6 +458,7 @@ export async function reapStalePlanDirs({
  *     sourceTicketOrigin?: 'flag'|'envelope'|'none',
  *     closeSuperseded?: boolean,
  *     routeDowngradeReason?: string|null,
+ *     injectedRules?: object,
  *   },
  * }} input
  */
@@ -424,7 +473,6 @@ export async function runPlanPersist({
     stories: rawStories = null,
     techSpecContent = null,
     planAcceptance = null,
-    planContextEnvelope = null,
   } = artifacts ?? {};
   const {
     forceReview = false,
@@ -439,6 +487,7 @@ export async function runPlanPersist({
     sourceTicketOrigin = 'none',
     closeSuperseded = true,
     routeDowngradeReason = null,
+    injectedRules = undefined,
   } = opts;
 
   // Boundary for the plan-metrics summary below: everything this invocation
@@ -513,22 +562,29 @@ 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,
+    injectedRules,
   });
   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 +642,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

@@ -300,6 +300,9 @@ export async function readNativeBlockedBy({
  * @param {Map<number, number[]>} nativeEdges
  * @param {number[]} foreignDone Ids outside the set already satisfied.
  * @param {(msg: string) => void} [warn]
+ * @param {object} [injectedRules] Test seam forwarded to the shape
+ *   derivation — skips the `audit-rules.json` disk read. Production callers
+ *   omit it (the real manifest, memoized per process, is the default).
  * @returns {{ kind: string, stories: object[], dag: object[], done: number[] }}
  */
 export function buildStoriesEnvelope({
@@ -307,23 +310,41 @@ export function buildStoriesEnvelope({
   nativeEdges = new Map(),
   foreignDone = [],
   warn,
+  config,
+  injectedRules,
 }) {
   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.
+    //
+    // `storyCount` (Story #4736) carries the run's topology into that same
+    // decision: a run resolving exactly ONE Story is inline whatever its
+    // shape, because the isolation a sub-agent buys only matters against a
+    // concurrently-dispatched sibling. It is the resolved set size — not the
+    // undelivered remainder — so the mode a caller reads for a given `--ids`
+    // list never changes as siblings land mid-run.
+    stories: sorted.map(({ id, title, body, url, labels, state }) => ({
       id,
       title,
       url,
       labels,
       state,
-      dispatchMode: resolveStoryDispatchMode({ labels }).mode,
+      dispatchMode: resolveStoryDispatchMode({
+        body,
+        labels,
+        config,
+        storyCount: sorted.length,
+        injectedRules,
+      }).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