mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/orchestration/column-sync.js

@@ -1,37 +1,8 @@
 /**
- * ColumnSync — derive the GitHub Projects v2 Status column from an issue's
- * agent:: labels, and push the update via the provider's GraphQL surface.
- *
- * The Status field carries only the three stock GitHub options
- * (`Todo` / `In Progress` / `Done`) — granular lifecycle state lives in the
- * `agent::*` labels themselves. This mapping collapses each lifecycle label
- * onto one of those three buckets:
- *
- *   agent::review-spec → Todo
- *   agent::ready       → Todo
- *   agent::executing   → In Progress
- *   agent::closing     → In Progress
- *   agent::blocked     → In Progress (the `agent::blocked` label is the
- *                       granular signal; the board column just shows the
- *                       work is still in flight)
- *   agent::done        → Done
- *
- * No-op (soft fail) when:
- *   - `projectNumber` is not configured
- *   - The Status field or the required option is not present on the project
- *   - The issue is not a project item (e.g. orchestrator running on a fork)
- *
- * The sync is implemented as pure functions plus a thin class wrapper so
- * tests can pump a fake provider's `graphql` calls without touching live
- * GitHub.
- *
- * Located at `lib/orchestration/column-sync.js` (Story #2548) so the
- * canonical state mutator `transitionTicketState`
- * (`lib/orchestration/ticketing/state.js`) can invoke it without an
- * upward dependency into the deleted `epic-runner/` tree. Prior to #2548 this module
- * lived under `epic-runner/` and was only wired against the Epic
- * ticket — Stories and Tasks never updated their Projects v2 Status
- * column on label flips.
+ * ColumnSync — collapse an issue's `agent::*` labels onto the stock Projects
+ * v2 Status options (`Todo` / `In Progress` / `Done`) and push it via
+ * GraphQL. Soft no-op when no project is configured, the Status field or
+ * option is missing, or the issue is not on the board.
  */
 
 import { AGENT_LABELS } from '../label-constants.js';
@@ -52,11 +23,8 @@ export const LABEL_TO_COLUMN = Object.freeze({
 });
 
 /**
- * Pick the target column for a set of labels. Terminal `done` wins
- * unconditionally; otherwise any in-flight label (executing / closing /
- * blocked) collapses to `In Progress`, and parking labels (review-spec /
- * ready) collapse to `Todo`. Returns null when no `agent::*` label is
- * present so the caller can skip the sync.
+ * `done` wins, then any in-flight label, then parking labels; `null` when no
+ * `agent::*` label is present.
  */
 export function columnForLabels(labels) {
   const set = new Set(labels);
@@ -95,23 +63,14 @@ export class ColumnSync {
       null;
     this.projectOwner = opts.projectOwner ?? provider.projectOwner ?? null;
     this.logger = opts.logger ?? ctx?.logger ?? console;
-    // Resolved config bag used to locate the on-disk meta cache's tempRoot.
-    // Optional — when omitted, the cache resolves the framework-default
-    // `temp` root (Story #4252).
+    // Locates the meta cache's tempRoot; absent means the default `temp`.
     this.config = opts.config ?? ctx?.config ?? undefined;
     this._meta = null; // lazy-cached { projectId, fieldId, options: Map<name, id> }
-    // Records whether the in-process `_meta` was hydrated from the on-disk
-    // cache, so a GraphQL error against possibly-stale cached metadata can
-    // invalidate the disk entry and force a fresh resolve on the next flip
-    // (Story #4252).
+    // Disk-hydrated meta may be stale; a failed mutation then invalidates it.
     this._metaFromDiskCache = false;
   }
 
   /**
-   * Sync a single issue to the column its `agent::*` labels imply. Returns a
-   * result descriptor (`synced | skipped | failed`) so callers can log
-   * without parsing errors.
-   *
    * @param {number} issueId
    * @param {string[]} labels
    */
@@ -122,19 +81,8 @@ export class ColumnSync {
   }
 
   /**
-   * Push one issue to a column named **directly**, skipping the label
-   * derivation {@link sync} performs.
-   *
-   * Split out for the one caller whose target column cannot come from labels:
-   * a container Epic carries no `agent::*` label by construction, so
-   * {@link columnForLabels} returns `null` for it and `sync` can never move
-   * it. The Epic's column is derived from its children instead
-   * (`epic-rollup.js`) and handed here — which keeps that derivation from
-   * having to fabricate a label on the container just to reach the board, the
-   * one thing the container invariant forbids.
-   *
-   * Every skip path, the metadata cache and the stale-cache self-heal are
-   * shared with `sync` because they live here rather than in it.
+   * Set a column directly, without label derivation — for container Epics,
+   * which carry no `agent::*` label by invariant.
    *
    * @param {number} issueId
    * @param {string} column Board column name (`Todo` | `In Progress` | `Done`).
@@ -177,12 +125,8 @@ export class ColumnSync {
         },
       );
     } catch (err) {
-      // A failed mutation against metadata that came from the disk cache
-      // most likely means the board was reconfigured since the entry was
-      // written (a stale projectId / fieldId / optionId). Invalidate the
-      // disk entry so the next flip re-resolves against the live board and
-      // self-heals (Story #4252). Re-throw so the caller's existing error
-      // handling (e.g. `syncProjectStatusColumn`'s warn) is preserved.
+      // Likely a reconfigured board: drop cached meta so the next flip
+      // self-heals, and re-throw for the caller's handling.
       this.#invalidateMetaCache();
       throw err;
     }
@@ -190,9 +134,7 @@ export class ColumnSync {
   }
 
   /**
-   * The `(owner, projectNumber)` pair the disk cache is keyed by. Mirrors
-   * the owner that `#loadMeta` resolves the board against so a cache hit and
-   * a live resolve agree on the same board identity.
+   * Cache key; same owner `#loadMeta` resolves against.
    *
    * @returns {{ owner: string|null, projectNumber: number|null }}
    */
@@ -204,11 +146,8 @@ export class ColumnSync {
   }
 
   /**
-   * Invalidate the on-disk metadata cache entry for this board and drop the
-   * in-process copy, so the next `#loadMeta` re-resolves from the live
-   * board. Only fires when the current `_meta` came from the disk cache —
-   * a freshly-resolved entry that fails the mutation is a transient/live
-   * problem, not a stale-cache problem.
+   * Only disk-hydrated meta is invalidated; a fresh resolve that fails is a
+   * live problem, not a stale cache.
    */
   #invalidateMetaCache() {
     if (!this._metaFromDiskCache) return;
@@ -220,9 +159,8 @@ export class ColumnSync {
 
   async #loadMeta() {
     if (this._meta !== null) return this._meta || null;
-    // Disk cache hit short-circuits the ~2 metadata GraphQL round-trips
-    // (resolveProjectMeta) — repo-invariant board metadata persists across
-    // the cold CLI processes of a single-story delivery (Story #4252).
+    // Board meta is repo-invariant; the disk cache spares each cold CLI
+    // process the resolve round-trips.
     const cachedBoard = this.#cacheBoard;
     const cached = readProjectMetaCache({
       owner: cachedBoard.owner,
@@ -235,18 +173,9 @@ export class ColumnSync {
       return this._meta;
     }
     try {
-      // Resolve the board by walking the owner-type ladder
-      // (organization → user → viewer) via the shared resolver so the
-      // org-owned path can't drift from `workflow-audit.js`. The Status
-      // single-select field is projected alongside the board id in one
-      // round-trip. (Story #4237; org-owner support extends the
-      // user/viewer ladder added in #3560.)
+      // Shared org → user → viewer resolver; Status field in one round-trip.
       const project = await resolveProjectMeta({
         provider: this.provider,
-        // Prefer the explicit `github.projectOwner`; fall back to the repo
-        // owner so an org-owned board still gets a login to scope
-        // `organization(login:)` / `user(login:)` by even when no separate
-        // projectOwner is configured. `viewer` is always the final rung.
         owner: this.projectOwner ?? this.provider.owner ?? null,
         projectNumber: this.projectNumber,
         projectFields: `
@@ -269,9 +198,7 @@ export class ColumnSync {
         fieldId: field.id,
         options,
       };
-      // Persist the freshly-resolved, repo-invariant metadata so the next
-      // cold flip reads it from disk instead of re-paying the resolve
-      // (Story #4252). Best-effort: a write failure never blocks the sync.
+      // Best-effort; a write failure never blocks the sync.
       writeProjectMetaCache({
         owner: cachedBoard.owner,
         projectNumber: cachedBoard.projectNumber,
@@ -290,17 +217,8 @@ export class ColumnSync {
   }
 
   /**
-   * Read the live `Status` column for an issue from the Projects v2
-   * board. Returns the column name (e.g. `'Done'`, `'In Progress'`)
-   * or `null` when the issue is not on the configured project, the
-   * Status field has no current value, or the metadata cannot be
-   * resolved.
-   *
-   * Story #2876 — used by `reassertStatusColumn` to detect drift
-   * between the orchestrator's intended column and the bot-rewritten
-   * column. The labels alone don't move when the bot overwrites
-   * Status — that's the bug class we defend against — so the
-   * drift-check MUST read the live Status, not the issue labels.
+   * Live Status column, or `null`. Drift checks must read this, not labels:
+   * the Projects bot rewrites Status without touching labels.
    *
    * @param {number} issueId
    * @returns {Promise<string|null>}
@@ -336,14 +254,8 @@ export class ColumnSync {
   }
 
   async #getProjectItemId(issueId, projectId) {
-    // Walk from the issue to its projectItems and pick the one whose
-    // project.id matches the configured board. The previous implementation
-    // paginated `node(projectId).items(first: 100)` and scanned for the
-    // issue number, which silently returned null on any board with >100
-    // items — the Mandrel board crossed that cliff at ~2,300 items, so
-    // every recent ticket's Status flip became a no-op. The by-issue path
-    // is O(1) per sync and has no pagination cliff (an issue is
-    // realistically never on more than a handful of boards at once).
+    // Walk issue → projectItems, not board → items: scanning board items
+    // hits a pagination cliff on large boards; an issue is on few boards.
     const owner = this.provider.owner;
     const repo = this.provider.repo;
     if (!owner || !repo) return null;

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

@@ -1,49 +1,10 @@
 /**
- * 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 risk ({@link deriveStoryShape}).** The light path
- *      (`deliver-light`) reads a predicted footprint's **risk** — a migration
- *      paired with its consumers, and the `audit-rules.json` sensitive-path
- *      classes the footprint intersects — to decide whether a prompt may skip
- *      the Story-authoring ceremony. Effort is no longer an axis: Story #4764
- *      removed the artifact counts, and Story #5344 removed the declared
- *      effort ceilings that replaced them, because a prediction is a
- *      declaration and size is enforced against ground truth by the light
- *      path's diff backstop.
- *   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.
- *
- * The risk 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 footprint at
- * dispatch, 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 deep code review
- * (`review-depth.js`).
- *
- * 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`. That is a property of
- * `single-story-close.js`, which runs those gates regardless of route — the
- * router cannot and does not switch them off. Story #5366 deleted the frozen
- * `preserves` payload that used to restate it on every decision: nothing read
- * it, and a claim attached to a decision is not the thing that enforces it.
+ * lib/orchestration/complexity-gate.js — deliver-side Story routing: seed
+ * signals for `/mandrel-plan`, footprint risk for the light path, and
+ * inline-vs-subagent dispatch. Risk uses the same sensitive-path taxonomy
+ * `review-depth.js` applies to the landed diff at close (predicted footprint
+ * at dispatch, actual diff at close); sensitivity always wins. Close gates
+ * run regardless of route — the router cannot switch them off.
  *
  * @typedef {'lite'|'full'} ComplexityRoute
  */
@@ -53,37 +14,17 @@ import path from 'node:path';
 import { extractChangePaths } from '../story-body/story-body.js';
 import { deriveChangeLevel } from './review-depth.js';
 
-/**
- * ## Why no predicted-effort ceilings live here any more (Story #5344)
- *
- * This module used to export a frozen shape-ceilings constant — declared kinds,
- * a magnitude bucket, an uncertainty bucket, and a deployable span — which the
- * light path judged a prompt's predicted footprint against. Two rounds of
- * evidence retired them. Story #4764 had already removed the artifact counts
- * (`maxChanges`, `maxAcceptance`) because cardinality is the wrong axis in both
- * directions. Story #5313 then demoted the remaining four axes from a gate to a
- * `warnings[]` entry, at which point they decided nothing at all: every one was
- * SELF-DECLARED by the same agent asking to proceed, and an axis a caller sets
- * and no one verifies is not a measurement. Story #5344 deleted them.
- *
- * What survives is what reads something other than the caller's own claim: the
- * two absolute risk rules below (a migration paired with its consumers, and a
- * footprint intersecting a registered sensitive-path class), derived from the
- * predicted PATHS, and the diff-derived backstop that measures the actual
- * change set
- * ({@link module:lib/orchestration/light-suitability.checkLightDiffBackstop}).
- * The backstop's `LIGHT_DIFF_CEILINGS` are now the only size block on the
- * light path, and they are the only ceilings measured against ground truth.
- */
+// No predicted-size ceilings: a size the caller declares about itself is not
+// a measurement. Size is bounded only by the diff backstop
+// (`light-suitability.checkLightDiffBackstop`); the rules here read paths.
 
 /** Paths that are schema migrations rather than ordinary source. */
 const MIGRATION_PATH_RE =
   /(?:^|\/)(?:migrations?|migrate)(?:\/|$)|\.sql$|(?:^|\/)schema\.(?:prisma|rb)$/i;
 
 /**
- * Does the footprint pair a schema migration with its consumers? A migration
- * plus the code that reads through it is epic scope: the two have to land
- * together and the ordering is the design work.
+ * A migration plus the code that reads through it is epic scope: the
+ * ordering is the design work.
  *
  * @param {string[]} paths
  * @returns {boolean}
@@ -94,29 +35,10 @@ function spansMigrationAndConsumers(paths) {
 }
 
 /**
- * Stable machine-readable identifiers for every reason a footprint 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 — keying that decision off reason text
- * would make a copy-edit a routing change.
- *
- * Split two ways since Story #5344 deleted the ceiling rules
- * (`change-kinds`, `magnitude`, `uncertainty`, `deployable-span`), and the
- * grouping is the contract:
- *
- *   - **Absolute rules** — `migration-span`, `sensitive-path`. Risk, not size,
- *     and derived from the predicted PATHS rather than a self-declared bucket.
- *     No re-slicing satisfies one.
- *   - **Unknown-footprint rejections** — `no-changes`, `unreadable-changes`,
- *     `glob-footprint`, `classification-unavailable`. Nothing was judged, so
- *     there is nothing to appeal. Story #5366 deleted `no-acceptance` with
- *     the `--acceptance` flag that was its only source: the flag clamped to a
- *     floor of one, so the zero-check behind this code could never fire.
- *
- * A `lite` route carries `code: null`.
+ * Stable codes for why a footprint routes `full`; callers branch on these,
+ * never on `reasons[]` prose. Absolute risk rules (`migration-span`,
+ * `sensitive-path`) no re-slicing satisfies; the rest are unknown-footprint
+ * rejections. `lite` carries `code: null`.
  */
 export const SHAPE_CODES = Object.freeze({
   MIGRATION_SPAN: 'migration-span',
@@ -128,10 +50,7 @@ export const SHAPE_CODES = Object.freeze({
 });
 
 /**
- * Ordered **absolute risk** rules, evaluated in order; the first hit is the
- * recorded reason for a `full` route. Neither reads a bucket the caller
- * declared about itself — both are derived from the predicted paths, which is
- * exactly why they survived the Story #5344 deletion of the effort ceilings.
+ * Absolute risk rules, in order; the first hit is the `full` reason.
  *
  * @type {ReadonlyArray<{
  *   code: string,
@@ -155,9 +74,6 @@ const RISK_RULES = Object.freeze([
 ]);
 
 /**
- * First absolute risk rule the footprint violates as a `{ code, reason }`
- * pair, or `null` when it clears them all.
- *
  * @param {object} shape
  * @returns {{ code: string, reason: string }|null}
  */
@@ -171,8 +87,7 @@ function firstRiskViolation(shape) {
 }
 
 /**
- * Count top-level enumerated items (`- `, `* `, `1. `) in a free-form seed —
- * each enumerated line is one predicted artifact.
+ * Count enumerated lines (`- `, `* `, `1. `) in a seed.
  *
  * @param {string} text
  * @returns {number}
@@ -188,9 +103,7 @@ function countSeedArtifacts(text) {
 const MAX_PREDICTED_PATHS = 50;
 
 /**
- * Extract path-like tokens (at least one `/` plus a dotted extension) from a
- * free-form seed — the predicted footprint the sensitive-path and repo-state
- * signals classify.
+ * Path-like tokens (a `/` plus a dotted extension) in a seed.
  *
  * @param {string} text
  * @returns {string[]} Deduplicated, in order of first appearance.
@@ -208,25 +121,10 @@ function extractPredictedPaths(text) {
 }
 
 /**
- * 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
- *                               predicted footprint intersects (the same
- *                               taxonomy close applies to the landed diff).
- *
- * Total: never throws; a failed classification degrades to an empty class
- * list (the honest "no signal", never a verdict).
+ * Advisory signals for a planning seed — they ground the authoring
+ * template's `changes[]` and the `/prototype` offer and route nothing.
+ * Existing paths predict refactors, missing ones creates. Never throws; a
+ * failed classification yields an empty class list.
  *
  * @param {{
  *   seedText?: string,
@@ -284,10 +182,6 @@ export function buildComplexitySignals({
 }
 
 /**
- * Assemble one decision object. Module-level rather than a closure inside
- * {@link deriveStoryShape}, so each rejection family below can build its own
- * verdict through one shape.
- *
  * @param {'lite'|'full'} route
  * @param {string|null} code
  * @param {string} reason
@@ -299,10 +193,8 @@ function decide(route, code, reason, shape = null) {
 }
 
 /**
- * Read the declared footprint into path entries, or the rejection that stands
- * in for one when it cannot be read at all — the first of the three rejection
- * families {@link SHAPE_CODES} groups. Nothing has been judged at this point,
- * so neither rejection carries a shape.
+ * Read the footprint into path entries, or a shape-less rejection when it
+ * cannot be read.
  *
  * @param {unknown} changes
  * @returns {{ entries: Array<{ path: string, isGlob?: boolean }>|null, rejection: object|null }}
@@ -333,14 +225,7 @@ function readFootprintEntries(changes) {
 }
 
 /**
- * The one rejection a footprint that WAS read can still earn before any risk
- * rule is reached: an unknowable width (a glob). Returns `null` when the
- * footprint is judgeable.
- *
- * It used to have a sibling — a zero-length acceptance list — which Story
- * #5366 removed along with the `--acceptance` flag that fed it. The flag
- * clamped its own value to a floor of one, so the branch was unreachable from
- * the only caller in the tree.
+ * A glob footprint has unknowable width; `null` when judgeable.
  *
  * @param {Array<{ isGlob?: boolean }>} entries
  * @param {object} shape
@@ -359,9 +244,6 @@ function unjudgeableFootprintRejection(entries, shape) {
 }
 
 /**
- * Assemble the risk shape of a footprint — the evidence
- * {@link deriveStoryShape} decides on and carries on its result.
- *
  * @param {{
  *   paths: string[],
  *   sensitiveClasses: string[],
@@ -381,31 +263,11 @@ function buildRiskShape({ paths, sensitiveClasses }) {
 }
 
 /**
- * Derive the complexity route from a footprint's **risk** (Story #4722
- * AC-3/AC-4; re-anchored off artifact cardinality by Story #4764; the declared
- * effort ceilings deleted by Story #5344) — the single function the light
- * path's suitability gate reads, so prediction-time and close-time can never
- * disagree about what is sensitive.
- *
- * `lite` requires:
- *
- *   - a declared, parseable, glob-free `changes[]` footprint — width is not
- *     counted, but an unknown footprint cannot be classified for risk;
- *   - no migration-with-consumers span;
- *   - a footprint intersecting **no** sensitive-path class
- *     (`deriveChangeLevel`, the taxonomy close applies to the landed diff).
- *     Sensitivity always wins (AC-6): a sensitive footprint routes `full`
- *     however small or mechanical, which keeps the deep code review via
- *     `review-depth.js#resolveDepth`. Since Story #5343 it does NOT also buy a
- *     fresh acceptance critic — that owner follows the ceremony profile.
- *
- * **Size is not a rule here.** It was, and Story #5344 removed it: every size
- * axis was a bucket the caller declared about its own request, and the light
- * path's diff backstop measures the real change set afterwards. What is left
- * reads the predicted paths, which is evidence.
- *
- * Everything else — an unknown/undeclared footprint or an unreadable
- * sensitive-path manifest — fails toward `full`. Total: never throws.
+ * Route a footprint by risk. `lite` requires a declared, parseable,
+ * glob-free `changes[]`, no migration-with-consumers span, and no
+ * sensitive-path class (a sensitive footprint keeps deep code review however
+ * small). Anything unknown or unclassifiable fails toward `full`. Never
+ * throws.
  *
  * @param {{
  *   changes?: unknown,
@@ -417,9 +279,7 @@ function buildRiskShape({ paths, sensitiveClasses }) {
  *   reasons: string[],
  *   code: string|null,
  *   shape: ReturnType<typeof buildRiskShape>|null,
- * }} `code` is the stable {@link SHAPE_CODES} identifier for the rule that
- *   rejected the footprint (`null` on `lite`) — the field a caller branches
- *   on, since `reasons[]` is human prose and free to be re-worded.
+ * }}
  */
 export function deriveStoryShape({
   changes,
@@ -446,9 +306,7 @@ export function deriveStoryShape({
   }
 
   if (level !== 'low') {
-    // `deriveChangeLevel` degraded to its null fail-safe (unreadable
-    // manifest / failed selector): there is no evidence the footprint is
-    // non-sensitive, and a classification failure must never buy lite.
+    // Classification failed; that must never buy lite.
     return decide(
       'full',
       SHAPE_CODES.CLASSIFICATION_UNAVAILABLE,
@@ -466,49 +324,19 @@ export function deriveStoryShape({
 }
 
 /**
- * Decide how `/mandrel-deliver` executes a Story: **run topology, and nothing else.**
- *
- * **`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.
- *
- * **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.
- *
- * **So this function reads only `storyCount` (Story #5006).** #4829 left the
- * body parse, the shape derivation, the `route::lite` hint note and the
- * `planning.complexityGate.enabled` branch in place to populate a `route`
- * field for reporting — but the sole consumer, `resolve-stories.js`, reads
- * `.mode` and discards the rest, so every one of those inputs was a parse
- * whose result nothing could act on. A caller that wants the shape calls
- * {@link deriveStoryShape} directly, as the light path and plan-persist do.
- *
- * Inline execution removes model-side fan-out only — it changes **where** the
- * engine runs, never **what** runs. Every deterministic
- * `single-story-close.js` gate, the PR to `main`, and the
- * `story-deliver-terminal` envelope are identical in both modes; see the
- * module header's non-negotiables.
- *
- * @param {{ storyCount?: unknown }} [args] `storyCount` is the number of
- *   Stories the invoking `/mandrel-deliver` run resolved. Omitted (or not exactly 1)
- *   means the run cannot be shown sibling-free and therefore dispatches as a
- *   sub-agent — never an assumed 1.
+ * Decide where `/mandrel-deliver` runs a Story, from run topology only.
+ * `inline` claims the router's own session, which only one Story can own:
+ * sub-agent isolation matters only for concurrent dispatch (siblings race
+ * worktrees and branch refs), so a single-Story run goes inline to skip the
+ * spawn's cache-write premium. Shape must never grant inline — a multi-Story
+ * run would put several engines on one session and checkout. Only *where*
+ * changes; close gates, PR and terminal envelope are identical.
+ *
+ * @param {{ storyCount?: unknown }} [args] Anything but exactly 1 dispatches
+ *   as a sub-agent.
  * @returns {{ mode: 'inline'|'subagent', reasons: string[] }}
  */
 export function resolveStoryDispatchMode({ storyCount } = {}) {
-  // 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',