mandrel 2.55.0 → 2.57.0

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

@@ -1,76 +1,46 @@
 /**
- * lib/orchestration/complexity-gate.js — shape-derived complexity routing
- * (Story #4722, superseding the word-count gate of Stories #4683/#4707).
- *
- * ## Route on the work, not the words
- *
- * The original gate routed a planning seed on its **word count**
- * (`maxSeedWords`), which is the wrong proxy in both directions: a detailed
- * prompt can describe trivial work, a terse one complex work. The bench
- * cohort (mandrel-bench 2.10.0) observed both failure modes — a lite verdict
- * fired at plan time and was then lost (a swallowed label write) or ignored
- * (deliver spawned a full story-worker anyway). This module now routes on the
- * **objective shape of the authored work**, staged across the pipeline:
- *
- *   1. **Plan time — signals, not routing.** {@link buildComplexitySignals}
- *      emits advisory complexity *signals* (enumerated-artifact count,
- *      risk-heuristic hits, repo state of predicted paths, sensitive-path
- *      classes) carrying **no routing authority**. There is no word ceiling.
- *   2. **Planner judgment, ledgered.** The planner owns the
- *      trivial-vs-standard verdict ({@link resolvePlannerRouteVerdict}) —
- *      `lite` only with a recorded reason, persisted on plan state. This
- *      generalizes the former one-way `applyPlannerDowngrade` seam into the
- *      authored verdict itself; the conservative default without a recorded
- *      reason is `full`.
- *   3. **Deterministic backstop at persist.** After authoring, the work has
- *      measurable shape: {@link deriveStoryShape} reads the Story's own
- *      effort and risk — distinct change kinds, declared magnitude,
- *      uncertainty, deployable/migration span, and sensitive-path classes —
- *      against {@link STORY_SHAPE_CEILINGS}. A `lite` claim whose work exceeds
- *      them **fails closed to `full`** (`run-plan-persist.js`). Artifact
- *      cardinality is deliberately not an axis (Story #4764).
- *   4. **Deliver dispatches on topology alone.** The dispatch *mode*
- *      ({@link resolveStoryDispatchMode}) answers a different question from
- *      the route: 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. Story
- *      #5006 removed the shape derivation that survived there for reporting,
- *      since no consumer read it. The `route::lite` label is a
- *      **human-visible hint only**, never the control signal. Either way every
- *      `single-story-close.js` gate runs unchanged.
+ * lib/orchestration/complexity-gate.js — shape-derived Story routing for the
+ * deliver side (Story #4722; plan-side lite claim deleted by Story #5312).
+ *
+ * Three surfaces survive, all read at delivery time:
+ *
+ *   1. **Seed signals ({@link buildComplexitySignals}).** `/mandrel-plan`'s
+ *      context envelope carries the paths a seed predicts, their repo state
+ *      (existing paths predict refactors; missing ones predict creates) and
+ *      the `audit-rules.json` sensitive-path classes the footprint intersects.
+ *      They ground the authoring template's `changes[]` skeleton and the
+ *      `/prototype` offer; they route nothing.
+ *   2. **Story shape ({@link deriveStoryShape}).** The light path
+ *      (`deliver-light`) reads a predicted footprint's effort and risk —
+ *      distinct change kinds, declared magnitude, uncertainty,
+ *      deployable/migration span, sensitive-path classes — against
+ *      {@link STORY_SHAPE_CEILINGS} to decide whether a prompt may skip the
+ *      Story-authoring ceremony. Artifact cardinality is deliberately not an
+ *      axis (Story #4764).
+ *   3. **Dispatch mode ({@link resolveStoryDispatchMode}).** `/mandrel-deliver`
+ *      answers a different question from the route: may the engine run in the
+ *      router's own session? Only a **single-Story run** may (Story #4736).
+ *
+ * Story #5312 deleted the plan-side half: the planner's authored lite claim
+ * (`--route-downgrade-reason`), the persist-time shape backstop that
+ * validated it, the `route::lite` hint label, and the
+ * `planning.complexityGate` knobs. Persist no longer routes; every Story
+ * lands through the same engine and the same close gates, and the shape
+ * ceilings below are read only where a shape is actually decided on.
  *
  * The shape taxonomy is deliberately the one `review-depth.js` already
  * applies to the landed diff at close (`deriveChangeLevel` over the
  * `audit-rules.json` sensitive-path classes): **predicted shape at dispatch,
- * actual diff at close** — one taxonomy, two read points. And sensitivity
- * always wins: a small change whose footprint intersects a sensitive-path
- * class routes `full`, which keeps its fresh acceptance critic
- * (`ceremony-routing.js` routes a high derived level to a fresh spawn).
- *
- * ## What "lite" changes and — critically — what it never changes
- *
- * The lite route collapses the **advisory ceremony** only: the story-worker
- * sub-agent boot and the fresh acceptance-critic spawn. It **never** relaxes
- * a non-negotiable. {@link LITE_PATH_INVARIANTS} is the machine-readable
- * contract that the lite path still produces a Story ticket, still lands via
- * a PR to `main`, still runs every repo quality gate, and still honours
+ * actual diff at close** — one taxonomy, two read points. Sensitivity always
+ * wins: a small change whose footprint intersects a sensitive-path class
+ * routes `full`, which keeps its fresh acceptance critic.
+ *
+ * {@link LITE_PATH_INVARIANTS} is the machine-readable contract that the
+ * light path still produces a Story ticket, still lands via a PR to `main`,
+ * still runs every repo quality gate, and still honours
  * `rules/security-baseline.md`. Those gates run in `single-story-close.js`
  * regardless of route; the router cannot and does not switch them off.
  *
- * ## Configuration
- *
- * Operators tune the surface via `planning.complexityGate` in `.agentrc.json`:
- *
- *   - `enabled`      (default `true`) — `false` disables lite routing
- *     everywhere: persist refuses lite claims and dispatch always takes the
- *     sub-agent path.
- *   - `maxArtifacts` (default `1`)    — enumerated-artifact signal threshold;
- *     an **input signal** for the planner, no longer a deterministic router.
- *
- * `maxSeedWords` is **removed** (hard cutover): word count routes nothing.
- *
  * @typedef {'lite'|'full'} ComplexityRoute
  */
 
@@ -79,27 +49,6 @@ import path from 'node:path';
 import { extractChangePaths } from '../story-body/story-body.js';
 import { deriveChangeLevel } from './review-depth.js';
 
-/**
- * Framework defaults for the complexity-routing surface. The SSOT the config
- * schema mirror and the configuration reference both cite. `maxSeedWords` is
- * gone: seed word count carries no routing authority (Story #4722).
- */
-const DEFAULT_COMPLEXITY_GATE = Object.freeze({
-  enabled: true,
-  maxArtifacts: 1,
-});
-
-/**
- * The persisted route marker for a lite-routed Story.
- *
- * **A human-visible hint only (Story #4722)** — never the control signal.
- * Persist applies it so a lite cohort is filterable in the GitHub UI, and
- * `deliver-light` reads the Story's own shape ({@link deriveStoryShape}) when
- * it needs one. Nothing routes on the label: a lost label or an unread marker
- * cannot misroute delivery.
- */
-export const LITE_ROUTE_LABEL = 'route::lite';
-
 /**
  * Effort/risk ceilings a Story's work must fit for the `lite` route
  * ({@link deriveStoryShape}). Framework constants, not operator knobs — a
@@ -378,54 +327,6 @@ const LITE_PATH_INVARIANTS = Object.freeze({
   securityBaseline: true,
 });
 
-/**
- * Coerce a candidate ceiling into a non-negative integer, falling back to the
- * framework default for anything malformed — a stray `-1` or `NaN` must never
- * widen the lite path (fail conservative).
- *
- * @param {unknown} value
- * @param {number} fallback
- * @returns {number}
- */
-function normalizeCeiling(value, fallback) {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
-    return fallback;
-  }
-  return Math.floor(value);
-}
-
-/**
- * Resolve the effective complexity-gate config, shallow-overlaying an
- * operator `planning.complexityGate` block onto
- * {@link DEFAULT_COMPLEXITY_GATE}. Accepts the full resolved config, the bare
- * `planning` bag, or the bare `complexityGate` bag, mirroring the tolerant
- * unwrap the other routing accessors use.
- *
- * Exported for persist (`run-plan-persist.js#resolveEffectiveRoute`), which
- * consults `enabled` to refuse a planner lite claim when the gate is off —
- * the schema's documented contract. It is the only read point: Story #5006
- * removed the second one in {@link resolveStoryDispatchMode}, where the switch
- * gated a shape derivation whose result no consumer read.
- *
- * @param {object | null | undefined} config
- * @returns {{ enabled: boolean, maxArtifacts: number }}
- */
-export function resolveComplexityGate(config) {
-  const raw =
-    config?.planning?.complexityGate ?? config?.complexityGate ?? config ?? {};
-  const bag = raw && typeof raw === 'object' ? raw : {};
-  return {
-    enabled:
-      typeof bag.enabled === 'boolean'
-        ? bag.enabled
-        : DEFAULT_COMPLEXITY_GATE.enabled,
-    maxArtifacts: normalizeCeiling(
-      bag.maxArtifacts,
-      DEFAULT_COMPLEXITY_GATE.maxArtifacts,
-    ),
-  };
-}
-
 /**
  * Count top-level enumerated items (`- `, `* `, `1. `) in a free-form seed —
  * each enumerated line is one predicted artifact.
@@ -464,20 +365,17 @@ function extractPredictedPaths(text) {
 }
 
 /**
- * Build the advisory complexity **signals** for a planning seed
- * (Story #4722 AC-2). Signals, not routing: the result carries
- * `routingAuthority: false` and no `route` field — the planner reads these
- * alongside its own judgment ({@link resolvePlannerRouteVerdict}) and the
- * deterministic shape backstop validates the authored Story at persist.
- *
- *   - `artifactCount`         — enumerated items in the seed, with the
- *                               configured `maxArtifacts` threshold beside it
- *                               as one input signal.
- *   - `riskHeuristicHits`     — `planning.riskHeuristics` phrases present in
- *                               the seed (same substring matcher the
- *                               pre-mortem critic uses).
- *   - `predictedPaths` / `repoState` — path-like tokens in the seed and
- *                               which of them exist in the repo (existing
+ * Build the advisory complexity **signals** for a planning seed. Signals,
+ * not routing: the result carries `routingAuthority: false` and no `route`
+ * field — they ground the authoring template's pre-resolved `changes[]` and
+ * the `/prototype` offer, nothing else (Story #5312 deleted the risk-heuristic
+ * hits and the `planning.complexityGate` echo that used to ride alongside).
+ *
+ *   - `artifactCount`         — enumerated items in the seed, a rough width
+ *                               signal for the operator's eye only.
+ *   - `predictedPaths`        — path-like tokens the seed names, in order of
+ *                               first appearance (capped).
+ *   - `repoState`             — which predicted paths exist in the repo (existing
  *                               paths predict refactors; missing predict
  *                               creates).
  *   - `sensitivePathClasses`  — `audit-rules.json` sensitive-path classes the
@@ -489,8 +387,6 @@ function extractPredictedPaths(text) {
  *
  * @param {{
  *   seedText?: string,
- *   config?: object,
- *   riskHeuristics?: string[],
  *   cwd?: string,
  *   pathExistsFn?: (absPath: string) => boolean,
  *   injectedRules?: object,
@@ -498,37 +394,21 @@ function extractPredictedPaths(text) {
  * }} [args]
  * @returns {{
  *   artifactCount: number,
- *   maxArtifacts: number,
- *   riskHeuristicHits: string[],
  *   predictedPaths: string[],
  *   repoState: { existingPaths: string[], missingPaths: string[] },
  *   sensitivePathClasses: string[],
- *   gate: { enabled: boolean },
  *   advisory: true,
  *   routingAuthority: false,
  * }}
  */
 export function buildComplexitySignals({
   seedText = '',
-  config,
-  riskHeuristics = [],
   cwd,
   pathExistsFn = existsSync,
   injectedRules,
   selectSensitivePathClassesFn,
 } = {}) {
-  const gate = resolveComplexityGate(config);
   const text = typeof seedText === 'string' ? seedText : '';
-  const haystack = text.toLowerCase();
-
-  const riskHeuristicHits = (
-    Array.isArray(riskHeuristics) ? riskHeuristics : []
-  ).filter(
-    (phrase) =>
-      typeof phrase === 'string' &&
-      phrase.trim().length > 0 &&
-      haystack.includes(phrase.trim().toLowerCase()),
-  );
 
   const predictedPaths = extractPredictedPaths(text);
   const root = typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd();
@@ -552,60 +432,14 @@ export function buildComplexitySignals({
 
   return {
     artifactCount: countSeedArtifacts(text),
-    maxArtifacts: gate.maxArtifacts,
-    riskHeuristicHits,
     predictedPaths,
     repoState: { existingPaths, missingPaths },
     sensitivePathClasses: classes,
-    gate: { enabled: gate.enabled },
     advisory: /** @type {const} */ (true),
     routingAuthority: /** @type {const} */ (false),
   };
 }
 
-/**
- * Resolve the planner's authored trivial-vs-standard verdict
- * (Story #4722 AC-2, generalizing the former one-way `applyPlannerDowngrade`
- * seam into the verdict itself).
- *
- * The planner — not a word count — owns the judgment, and the contract keeps
- * it auditable: `lite` **only** with a non-empty recorded reason (carried on
- * `authored` and ledgered on every created Story's `story-plan-state`
- * checkpoint by persist). Absent a recorded reason the conservative default
- * stands: `full`, with `authored: null`. Pure and total.
- *
- * The verdict is a **claim**, not the decision — persist validates it against
- * the authored Story's shape ({@link deriveStoryShape}) and fails closed to
- * `full` when the shape exceeds the ceilings.
- *
- * @param {{ reason?: unknown }} [args]
- * @returns {{
- *   route: ComplexityRoute,
- *   reasons: string[],
- *   authored: Readonly<{ route: 'lite', reason: string }>|null,
- *   preserves: typeof LITE_PATH_INVARIANTS,
- * }}
- */
-export function resolvePlannerRouteVerdict({ reason } = {}) {
-  const recorded = typeof reason === 'string' ? reason.trim() : '';
-  if (recorded === '') {
-    return {
-      route: 'full',
-      reasons: [
-        'no authored lite verdict (no recorded reason) — standard full route',
-      ],
-      authored: null,
-      preserves: LITE_PATH_INVARIANTS,
-    };
-  }
-  return {
-    route: 'lite',
-    reasons: [`planner verdict: lite (recorded reason): ${recorded}`],
-    authored: Object.freeze({ route: 'lite', reason: recorded }),
-    preserves: LITE_PATH_INVARIANTS,
-  };
-}
-
 /**
  * Assemble the effort/risk shape of a footprint — the evidence
  * {@link deriveStoryShape} decides on and carries on its result.

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -13,23 +13,23 @@
  * layer — so the gate scans `type === 'story'` tickets and reads the
  * `{ path, assumption }` entries inlined on each Story body.
  *
- * Rules (one error per mismatched path):
- *   - `creates`            + path **exists**  → error (Story would clobber).
+ * Rules (one finding per mismatched path). Story #5312 demoted every
+ * mismatch but one to a **warning** the dry-run lists and the persist
+ * proceeds past — `changes[]` is an advisory sketch the deliverer revises
+ * against the real tree, so refusing a plan on it cost re-authoring rounds
+ * for a footprint nobody was bound to:
+ *   - `creates`            + path **exists**  → warning (Story may clobber).
  *   - `refactors-existing` (via `changes`) + path **absent and never
  *     tracked** at `baseBranchRef` → auto-normalized to `creates` with a
  *     logged warning (#4496 fix 5): a refactor declaration against a
- *     path with no history is deterministically a create, so rejecting it
- *     only forces a reject→amend→re-persist cycle for a mechanical rewrite.
+ *     path with no history is deterministically a create.
  *   - `refactors-existing` (via `changes`) + path **absent but present in
- *     that ref's history** → hard error naming the removing commit and, when
- *     git detects one, the rename target (Story #5265). The normalization
- *     rescues a mislabel; it must not rescue a plan authored against a file
- *     the tree deleted, which propagates into acceptance criteria nothing
- *     can satisfy. Genuine mismatches keep failing — a `references`-sourced
- *     `refactors-existing` on an absent path is a missing read dependency
- *     and stays an error.
- *   - `exists`             + path **absent** → error (read dependency missing).
- *   - `deletes`            + path **absent** → error (nothing to delete).
+ *     that ref's history** → warning naming the removing commit and, when
+ *     git detects one, the rename target (Story #5265) — a plan authored
+ *     against a file the tree deleted is worth saying out loud.
+ *   - `exists`             + path **absent** → warning (read dependency missing).
+ *   - `deletes`            + path **absent** → **error** (nothing to delete —
+ *     the one declaration a deliverer cannot act on at all).
  *
  * Wave awareness (Story #3960): the base-branch-only rules above produce
  * false signals once an earlier Story in the same epic creates (or deletes)
@@ -386,8 +386,9 @@ function predecessorMutator(index, path, predecessors) {
  * predecessors (Story #3960). Returns an envelope:
  *
  *   {
- *     errors:    string[]   // one entry per mismatch, batched per Story
- *     warnings:  string[]   // legacy/no-assumption deprecation nudges +
+ *     errors:    string[]   // a `deletes` naming an absent path, or a
+ *                           // legacy string-bullet body — the refusals
+ *     warnings:  string[]   // every other mismatch (Story #5312) +
  *                           // auto-normalization notices (#4496 fix 5)
  *     mismatches: object[]  // structured payload for downstream tooling
  *     normalizations: object[] // `refactors-existing`→`creates`
@@ -513,7 +514,7 @@ export function validateStoryFileAssumptions(opts) {
           continue;
         }
         mismatches.push(finding);
-        errors.push(renderMismatch(finding));
+        routeMismatch(finding, { errors, warnings });
         continue;
       }
       // Wave-aware concurrent-create check (Story #3960): two Stories with
@@ -541,7 +542,7 @@ export function validateStoryFileAssumptions(opts) {
             producerSlug: concurrent,
           };
           mismatches.push(conflict);
-          errors.push(renderMismatch(conflict));
+          warnings.push(renderMismatch(conflict));
         }
       }
     }
@@ -549,6 +550,20 @@ export function validateStoryFileAssumptions(opts) {
   return { errors, warnings, mismatches, normalizations };
 }
 
+/**
+ * Route one confirmed mismatch to the channel it belongs on (Story #5312):
+ * a `deletes` on an absent path is the one declaration nothing can act on and
+ * stays an error; every other mismatch is advisory and lands on `warnings`.
+ *
+ * @param {object} finding
+ * @param {{ errors: string[], warnings: string[] }} channels
+ * @returns {void}
+ */
+function routeMismatch(finding, { errors, warnings }) {
+  const channel = finding.assumption === 'deletes' ? errors : warnings;
+  channel.push(renderMismatch(finding));
+}
+
 /**
  * Route one mismatch to the errors channel or the normalization channel
  * (Story #5265).

package/.agents/scripts/lib/orchestration/light-escalation.js

@@ -76,7 +76,7 @@ function buildRerunBackstopCommand(storyId) {
  * number, or `null` when absent/malformed.
  *
  * This is the only Story context a **gate-stage** rejection can legitimately
- * claim: the signals stream is keyed on a Story id, and an `ask-operator` gate
+ * claim: the signals stream is keyed on a Story id, and an escalating gate
  * has authored no receipt yet — deliberately, since not creating one is the
  * point of that outcome. A bare prompt's rejection therefore has no stream to
  * land in, and attributing it to a fabricated id would be worse than recording
@@ -93,8 +93,8 @@ function normalizeAmendsId(amends) {
 }
 
 /**
- * Record a suitability-gate refusal (`ask-operator`) as friction, attributed to
- * the `--amends` target when there is one.
+ * Record a suitability-gate refusal (`escalate-plan`) as friction, attributed
+ * to the `--amends` target when there is one.
  *
  * @param {{
  *   gate: object,