mandrel 2.20.0 → 2.22.0

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -31,15 +31,16 @@
  *      cardinality is deliberately not an axis (Story #4764).
  *   4. **Deliver re-derives.** `/deliver` computes the route from the fetched
  *      Story body via the **same** shape function at dispatch
- *      ({@link resolveStoryDispatchMode}) and honors it: a lite-shaped Story
- *      executes inline — no story-worker sub-agent boot, no fresh
- *      acceptance-critic dispatch — while every `single-story-close.js` gate
- *      runs unchanged. The `route::lite` label is a **human-visible hint
- *      only**, never the control signal: a lost label or an unread marker can
- *      no longer misroute delivery. Ahead of the shape read sits one
- *      shape-independent rule (Story #4736): a **single-Story run** is inline
- *      whatever its shape, because sub-agent isolation buys nothing when
- *      there is no concurrent sibling to isolate from.
+ *      ({@link resolveStoryDispatchMode}) and **reports** it, while the
+ *      dispatch *mode* answers a different question: may the engine run in the
+ *      router's own session? Only a **single-Story run** may (Story #4736) —
+ *      sub-agent isolation buys nothing when there is no concurrent sibling to
+ *      isolate from. Shape cannot grant that session (Story #4829): a lite body
+ *      makes work cheap, it does not conjure a second session for a sibling to
+ *      run in. The `route::lite` label is a **human-visible hint only**, never
+ *      the control signal: a lost label or an unread marker can no longer
+ *      misroute delivery. Either way every `single-story-close.js` gate runs
+ *      unchanged.
  *
  * The shape taxonomy is deliberately the one `review-depth.js` already
  * applies to the landed diff at close (`deriveChangeLevel` over the
@@ -259,23 +260,65 @@ function spansMigrationAndConsumers(paths) {
   return migrations.length > 0 && migrations.length < paths.length;
 }
 
+/**
+ * Stable machine-readable identifiers for every reason a shape routes `full` —
+ * the `code` field on a {@link deriveStoryShape} decision (Story #4815).
+ *
+ * The prose in `reasons[]` is written for a human reading a gate envelope and
+ * is free to be re-worded; a caller that must **branch** on *which* rule
+ * objected reads this code instead. That distinction is load-bearing for the
+ * light path's operator override
+ * ({@link module:lib/orchestration/light-suitability.OVERRIDABLE_SHAPE_CODES}),
+ * which may waive a size *prediction* but never a risk rule: keying that
+ * decision off reason text would make a copy-edit a security change.
+ *
+ * Split three ways, and the grouping is the contract:
+ *
+ *   - **Ceiling rules** — `change-kinds`, `magnitude`, `uncertainty`,
+ *     `deployable-span`. Coarse predictions about size, enforced for real
+ *     against ground truth by the diff backstop.
+ *   - **Absolute rules** — `migration-span`, `sensitive-path`. Risk, not size.
+ *   - **Unknown-footprint rejections** — `no-changes`, `unreadable-changes`,
+ *     `glob-footprint`, `no-acceptance`, `classification-unavailable`,
+ *     `unparseable-body`. Nothing was judged, so there is nothing to waive.
+ *
+ * A `lite` route carries `code: null`.
+ */
+export const SHAPE_CODES = Object.freeze({
+  CHANGE_KINDS: 'change-kinds',
+  MAGNITUDE: 'magnitude',
+  UNCERTAINTY: 'uncertainty',
+  DEPLOYABLE_SPAN: 'deployable-span',
+  MIGRATION_SPAN: 'migration-span',
+  SENSITIVE_PATH: 'sensitive-path',
+  NO_CHANGES: 'no-changes',
+  UNREADABLE_CHANGES: 'unreadable-changes',
+  GLOB_FOOTPRINT: 'glob-footprint',
+  NO_ACCEPTANCE: 'no-acceptance',
+  CLASSIFICATION_UNAVAILABLE: 'classification-unavailable',
+  UNPARSEABLE_BODY: 'unparseable-body',
+});
+
 /**
  * Ordered effort/risk rules, evaluated in order; the first hit is the recorded
  * reason for a `full` route. Every rule names an effort, risk, or uncertainty
  * property of the work — none counts artifacts.
  *
  * @type {ReadonlyArray<{
+ *   code: string,
  *   when: (shape: object, ceilings: typeof STORY_SHAPE_CEILINGS) => boolean,
  *   reason: (shape: object, ceilings: typeof STORY_SHAPE_CEILINGS) => string,
  * }>}
  */
 const EFFORT_RULES = Object.freeze([
   {
+    code: SHAPE_CODES.CHANGE_KINDS,
     when: (s, c) => s.kindCount > c.maxChangeKinds,
     reason: (s, c) =>
       `${s.kindCount} distinct change kinds (${s.changeKinds.join(', ')}) > maxChangeKinds ${c.maxChangeKinds} — an explicit multi-capability enumeration, not one capability; full route`,
   },
   {
+    code: SHAPE_CODES.MAGNITUDE,
     when: (s, c) =>
       MAGNITUDE_SCALE.indexOf(s.magnitude) >
       MAGNITUDE_SCALE.indexOf(c.maxMagnitude),
@@ -283,6 +326,7 @@ const EFFORT_RULES = Object.freeze([
       `declared magnitude "${s.magnitude}" > maxMagnitude "${c.maxMagnitude}" — a substantial rewrite is effort a single inline pass should not absorb, however few files it touches; full route`,
   },
   {
+    code: SHAPE_CODES.UNCERTAINTY,
     when: (s, c) =>
       UNCERTAINTY_SCALE.indexOf(s.uncertainty) >
       UNCERTAINTY_SCALE.indexOf(c.maxUncertainty),
@@ -290,16 +334,19 @@ const EFFORT_RULES = Object.freeze([
       `the shape is not determined by the request (uncertainty "${s.uncertainty}") — the design decisions /plan exists to resolve are still open; full route`,
   },
   {
+    code: SHAPE_CODES.DEPLOYABLE_SPAN,
     when: (s, c) => s.deployables.length > c.maxDeployables,
     reason: (s, c) =>
       `footprint spans ${s.deployables.length} deployables (${s.deployables.join(', ')}) > maxDeployables ${c.maxDeployables} — clearly-epic scope; full route`,
   },
   {
+    code: SHAPE_CODES.MIGRATION_SPAN,
     when: (s) => s.migrationSpan,
     reason: () =>
       'footprint pairs a migration with its consumers — clearly-epic scope; full route',
   },
   {
+    code: SHAPE_CODES.SENSITIVE_PATH,
     when: (s) => s.sensitiveClasses.length > 0,
     reason: (s) =>
       `footprint intersects sensitive-path class(es) ${s.sensitiveClasses.join(', ')} — sensitivity wins over a small shape; full route (fresh acceptance critic retained)`,
@@ -307,15 +354,18 @@ const EFFORT_RULES = Object.freeze([
 ]);
 
 /**
- * First effort/risk rule the shape violates, or `null` when it clears them all.
+ * First effort/risk rule the shape violates as a `{ code, reason }` pair, or
+ * `null` when it clears them all.
  *
  * @param {object} shape
  * @param {typeof STORY_SHAPE_CEILINGS} ceilings
- * @returns {string|null}
+ * @returns {{ code: string, reason: string }|null}
  */
 function firstEffortViolation(shape, ceilings) {
   for (const rule of EFFORT_RULES) {
-    if (rule.when(shape, ceilings)) return rule.reason(shape, ceilings);
+    if (rule.when(shape, ceilings)) {
+      return { code: rule.code, reason: rule.reason(shape, ceilings) };
+    }
   }
   return null;
 }
@@ -654,10 +704,13 @@ function buildEffortShape({
  * @returns {{
  *   route: ComplexityRoute,
  *   reasons: string[],
+ *   code: string|null,
  *   shape: ReturnType<typeof buildEffortShape>|null,
  *   ceilings: typeof STORY_SHAPE_CEILINGS,
  *   preserves: typeof LITE_PATH_INVARIANTS,
- * }}
+ * }} `code` is the stable {@link SHAPE_CODES} identifier for the rule that
+ *   rejected the shape (`null` on `lite`) — the field a caller branches on,
+ *   since `reasons[]` is human prose and free to be re-worded.
  */
 export function deriveStoryShape({
   changes,
@@ -670,9 +723,10 @@ export function deriveStoryShape({
 } = {}) {
   const ceilings = STORY_SHAPE_CEILINGS;
   const preserves = LITE_PATH_INVARIANTS;
-  const decide = (route, reason, shape = null) => ({
+  const decide = (route, code, reason, shape = null) => ({
     route,
     reasons: [reason],
+    code,
     shape,
     ceilings,
     preserves,
@@ -681,6 +735,7 @@ export function deriveStoryShape({
   if (!Array.isArray(changes) || changes.length === 0) {
     return decide(
       'full',
+      SHAPE_CODES.NO_CHANGES,
       'no changes[] declared — the footprint is unknown, so the work cannot be judged trivial; conservative full route',
     );
   }
@@ -691,6 +746,7 @@ export function deriveStoryShape({
   } catch (err) {
     return decide(
       'full',
+      SHAPE_CODES.UNREADABLE_CHANGES,
       `changes[] could not be read (${err?.message ?? err}) — unknown footprint; conservative full route`,
     );
   }
@@ -714,6 +770,7 @@ export function deriveStoryShape({
   if (entries.some((e) => e.isGlob)) {
     return decide(
       'full',
+      SHAPE_CODES.GLOB_FOOTPRINT,
       'changes[] contains a glob path — unknown footprint width; conservative full route',
       shape,
     );
@@ -721,13 +778,16 @@ export function deriveStoryShape({
   if (shape.acceptanceCount === 0) {
     return decide(
       'full',
+      SHAPE_CODES.NO_ACCEPTANCE,
       'no acceptance criteria — the contract cannot be judged trivial; conservative full route',
       shape,
     );
   }
 
   const violation = firstEffortViolation(shape, ceilings);
-  if (violation !== null) return decide('full', violation, shape);
+  if (violation !== null) {
+    return decide('full', violation.code, violation.reason, shape);
+  }
 
   if (level !== 'low') {
     // `deriveChangeLevel` degraded to its null fail-safe (unreadable
@@ -735,6 +795,7 @@ export function deriveStoryShape({
     // non-sensitive, and a classification failure must never buy lite.
     return decide(
       'full',
+      SHAPE_CODES.CLASSIFICATION_UNAVAILABLE,
       'sensitive-path classification unavailable — cannot verify the footprint is non-sensitive; conservative full route',
       shape,
     );
@@ -742,6 +803,7 @@ export function deriveStoryShape({
 
   return decide(
     'lite',
+    null,
     `trivial shape: ${shape.kindCount} change kind(s) (${shape.changeKinds.join(', ')}) ≤ ${ceilings.maxChangeKinds} across ${shape.siteCount} site(s), magnitude ${shape.magnitude} ≤ ${ceilings.maxMagnitude}, shape ${shape.uncertainty}, no epic-scope span, no sensitive-path class — inline-eligible; non-negotiables preserved`,
     shape,
   );
@@ -771,6 +833,7 @@ function deriveStoryRouteFromBody(body, opts = {}) {
       reasons: [
         `Story body is unparseable (${err?.message ?? err}) — shape unknown; conservative full route`,
       ],
+      code: SHAPE_CODES.UNPARSEABLE_BODY,
       shape: null,
       ceilings: STORY_SHAPE_CEILINGS,
       preserves: LITE_PATH_INVARIANTS,
@@ -802,27 +865,34 @@ function routeForReporting(body, opts) {
 /**
  * Decide how `/deliver` executes a Story.
  *
- * Two independent premises, checked in this order:
- *
- * 1. **Run topology (Story #4736).** A run delivering a *single* Story
- *    executes **inline**, whatever its shape. Sub-agent isolation is
- *    load-bearing only for CONCURRENT dispatch — two workers sharing a
- *    checkout would race on worktrees and branch refs — and a one-Story run
- *    has no sibling to race. It therefore pays the spawn premium (a boot is
- *    a cache WRITE at full rate, where an inline continuation is a cache read
- *    at ~10%; ~$1.43/M vs ~$1.07/M on comparable bench work) for nothing.
- *    This is a fact about the run, not about the work, so the shape gate's
- *    `enabled` switch — which governs *shape derivation* — does not reach it.
- * 2. **Shape (Story #4722 AC-4/AC-5).** For a multi-Story run, the decision
- *    comes **from the Story body's own shape**, never from the `route::lite`
- *    label: a lite-shaped Story executes inline; everything else — a
- *    full-shaped body, a missing/unparseable body, or the gate disabled via
- *    `planning.complexityGate.enabled=false` — dispatches as a sub-agent,
- *    the conservative default.
- *
- * The label is read only to report hint consistency in `reasons`: with the
- * label absent (or its write failed) a lite-shaped Story still runs inline,
- * and with the label present on a full-shaped Story the shape wins.
+ * **`inline` names one indivisible resource: the router's own session.** Two
+ * Stories cannot both own it, so exactly one premise can grant it —
+ * **run topology (Story #4736)**: a run resolving a *single* Story executes
+ * inline whatever its shape, because sub-agent isolation is load-bearing only
+ * for CONCURRENT dispatch (two workers sharing a checkout race on worktrees and
+ * branch refs) and a one-Story run has no sibling to race. It therefore pays
+ * the spawn premium (a boot is a cache WRITE at full rate, where an inline
+ * continuation is a cache read at ~10%; ~$1.43/M vs ~$1.07/M on comparable
+ * bench work) for nothing. That is a fact about the run, not about the work, so
+ * the shape gate's `enabled` switch — which governs *shape derivation* — does
+ * not reach it.
+ *
+ * **Shape cannot grant it (Story #4829).** The shape read used to return
+ * `inline` for any lite-shaped body in a multi-Story run, inheriting no
+ * topology guard. Measured twice on 2026-07-29: a two-Story and a three-Story
+ * run came back `inline` for *every* Story while `stories-wave-tick.js`
+ * reported the whole set ready under a concurrency cap of five — a router
+ * following both signals literally runs several engines over one session and
+ * one checkout, the precise hazard the sub-agent path exists to prevent. Both
+ * runs were completed only by an operator overriding the verdict by hand, which
+ * is an invariant held by judgment rather than by code. So this function has
+ * exactly **one** `inline` exit, guarded by the topology premise; every path
+ * below it returns `subagent`, and the derived shape is carried on `route` for
+ * reporting only. A lite shape makes the work cheap — it does not conjure a
+ * second session for a sibling to run in.
+ *
+ * The label is read only to report hint consistency in `reasons`; it never
+ * routes on either premise (Story #4722 AC-4/AC-5).
  *
  * Inline execution removes model-side fan-out only — it changes **where** the
  * engine runs, never **what** runs. Every deterministic
@@ -839,7 +909,8 @@ function routeForReporting(body, opts) {
  *   selectSensitivePathClassesFn?: Function,
  * }} [args] `storyCount` is the number of Stories the invoking `/deliver` run
  *   resolved. Omitted (or not a positive integer) means "unknown run size",
- *   which falls through to the shape decision — never to an assumed 1.
+ *   which cannot be shown sibling-free and therefore dispatches as a sub-agent
+ *   — never an assumed 1.
  * @returns {{ mode: 'inline'|'subagent', reasons: string[], route: ReturnType<typeof deriveStoryShape>|null }}
  */
 export function resolveStoryDispatchMode({
@@ -858,6 +929,8 @@ export function resolveStoryDispatchMode({
     ? `the ${LITE_ROUTE_LABEL} label is present (hint only — the derived shape is the control signal)`
     : `the ${LITE_ROUTE_LABEL} label is absent (hint only — the derived shape is the control signal)`;
 
+  // The ONLY `inline` exit in this function, and the guard is the whole
+  // contract: an inline verdict must mean the engine can actually run inline.
   if (storyCount === 1) {
     return {
       mode: 'inline',
@@ -894,23 +967,17 @@ export function resolveStoryDispatchMode({
     };
   }
 
+  // Past the topology guard a sibling may be dispatched concurrently, so the
+  // router's session is not available to anyone. The shape is still derived and
+  // returned on `route` — ceremony and reporting read it — but it decides
+  // nothing here: both shapes dispatch as a sub-agent.
   const route = deriveStoryRouteFromBody(body, {
     injectedRules,
     selectSensitivePathClassesFn,
   });
-  if (route.route === 'lite') {
-    return {
-      mode: 'inline',
-      reasons: [
-        `lite-shaped Story — execute deliver-story inline; no story-worker or acceptance-critic sub-agent dispatch (close gates unchanged): ${route.reasons[0]}`,
-        hintNote,
-      ],
-      route,
-    };
-  }
-  return {
-    mode: 'subagent',
-    reasons: [`full-shaped Story — ${route.reasons[0]}`, hintNote],
-    route,
-  };
+  const shapeNote =
+    route.route === 'lite'
+      ? `lite-shaped Story in a multi-Story run — the shape is inline-eligible but the router's session is not: a concurrent sibling would have to share it, racing worktrees and branch refs; sub-agent dispatch (${route.reasons[0]})`
+      : `full-shaped Story — ${route.reasons[0]}`;
+  return { mode: 'subagent', reasons: [shapeNote, hintNote], route };
 }