mandrel 2.10.0 → 2.11.0

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

@@ -3,11 +3,12 @@ import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
 import { Logger } from '../Logger.js';
-import {
-  parse as parseStoryBody,
-  StoryBodyParseError,
-} from '../story-body/story-body.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
+import { computeSpecBudgetFindings } from './spec-budget.js';
+import {
+  assertStoryBodiesParse,
+  parseStoryBodyOrThrow,
+} from './story-body-gate.js';
 import {
   computeConflictFindings,
   renderHardConflictError,
@@ -46,63 +47,6 @@ function collectPathsFromText(text, paths) {
   }
 }
 
-/**
- * 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'`.
- */
-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.
- */
-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);
-  }
-}
-
 /**
  * Resolve every acceptance line a Story declares, across both authoring
  * shapes (Story #4541).
@@ -721,7 +665,19 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
     stories,
     policy: opts.conflictPolicy,
   });
-  const findings = [...sizingFindings, ...conflictFindings];
+  // Advisory `## Spec` word-budget pass (Story #4723) — soft findings only,
+  // surfaced as warnings here and via the persist soft-finding channel;
+  // never promoted to `errors[]`, so an over-budget Spec cannot fail the
+  // persist. Runs after `assertStoryBodiesParse`, so string bodies parse.
+  const specBudgetFindings = computeSpecBudgetFindings({ stories });
+  for (const finding of specBudgetFindings) {
+    Logger.warn(`[ticket-validator] spec-word-budget: ${finding.message}`);
+  }
+  const findings = [
+    ...sizingFindings,
+    ...conflictFindings,
+    ...specBudgetFindings,
+  ];
   const CONFLICT_KINDS = new Set([
     'shared-editor',
     'implicit-cross-story-dep',

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

@@ -124,7 +124,7 @@ export async function emitPlanContext({
     // later turn. When it is captured to disk anyway, stdout carries a
     // compact digest naming the artifact instead of the payload itself.
     await writeEnvelopeFile(outPath, json);
-    await writeStoriesTemplateFile(outPath);
+    await writeStoriesTemplateFile(outPath, envelope);
     const resolved = path.resolve(outPath);
     const digest = {
       digest: 'plan-context',
@@ -137,7 +137,16 @@ export async function emitPlanContext({
       bytes: Buffer.byteLength(json, 'utf8'),
       sourceTickets: (envelope.sourceTickets ?? []).map((t) => t.id),
       duplicates: (envelope.duplicates ?? []).length,
-      complexityRoute: envelope.complexityRoute?.route ?? null,
+      // Advisory only (Story #4722): signals, no route — the planner owns
+      // the trivial-vs-standard verdict and persist validates it by shape.
+      complexitySignals: envelope.complexitySignals
+        ? {
+            artifactCount: envelope.complexitySignals.artifactCount,
+            riskHeuristicHits: envelope.complexitySignals.riskHeuristicHits,
+            sensitivePathClasses:
+              envelope.complexitySignals.sensitivePathClasses,
+          }
+        : null,
     };
     stdout.write(`${JSON.stringify(digest)}\n`);
   } else {
@@ -177,18 +186,27 @@ async function writeEnvelopeFile(outPath, json) {
  * requires reading `story-body.js` source. Written whenever `--out` is
  * passed, and throwing on failure for the same reason the envelope write
  * does: a silently missing template re-opens the format-discovery loop it
- * exists to close.
+ * exists to close. The envelope's advisory `complexitySignals` are threaded
+ * through so the skeleton's `changes[]` arrive pre-resolved to
+ * creates-vs-refactors against the repo snapshot (Story #4723).
  *
  * @param {string} outPath The envelope `--out` path; the template lands in
  *   the same directory as {@link STORIES_TEMPLATE_FILENAME}.
+ * @param {object} [envelope] The emitted plan-context envelope.
  */
-async function writeStoriesTemplateFile(outPath) {
+async function writeStoriesTemplateFile(outPath, envelope = {}) {
   const resolved = path.resolve(
     path.dirname(path.resolve(outPath)),
     STORIES_TEMPLATE_FILENAME,
   );
   try {
-    await writeFile(resolved, renderStoriesTemplate(), 'utf8');
+    await writeFile(
+      resolved,
+      renderStoriesTemplate({
+        complexitySignals: envelope?.complexitySignals ?? null,
+      }),
+      'utf8',
+    );
   } catch (err) {
     throw new Error(
       `[plan-context] cannot write stories template to ${resolved}: ${err.message}`,

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

@@ -209,6 +209,7 @@ async function main() {
     stories,
     nativeEdges,
     warn: (m) => Logger.warn(m),
+    config,
   });
   const foreignDone = await resolveForeignDone({
     provider,
@@ -220,6 +221,7 @@ async function main() {
     nativeEdges,
     foreignDone,
     warn: () => {},
+    config,
   });
 
   process.stdout.write(

package/.agents/workflows/deliver.md

@@ -25,6 +25,8 @@ blocker resolved against its real issue state). You never hand it a graph, and
 there is no batch label — which is what lets you deliver Stories **across plan
 runs and over time**. The `plan-run::<id>` grouping label is filter metadata
 only — never a resolution input (there is no `--run` or `--dep` axis).
+Per-Story routes are **body-derived** too (#4722); `route::lite` is a hint
+only.
 
 ## Inputs
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -30,10 +30,19 @@ mid-delivery, and evaluates the actual work product.
 
 ## Per round
 
-1. **Eval pass (fresh context, independent of the author).** Run a **separate
-   critic pass** — a fresh-context sub-agent (`Agent` tool), *not* a
-   continuation of your implementing turn — so the evaluator does not grade its
-   own homework.
+1. **Eval pass — one verdict-owner per cluster (Story #4723).** Exactly
+   **one** pass authors each cluster's verdict: the **fresh-context critic**
+   when the ceremony routing below resolves `fresh` (a sub-agent via the
+   `Agent` tool, *not* a continuation of your implementing turn — the
+   evaluator does not grade its own homework), or the **inline self-eval**
+   when it resolves `inline`. The resolved decision names the owner
+   explicitly (`verdictOwner: 'fresh-critic' | 'inline-self-eval'` from
+   `resolveCeremonyForRisk`). **Never run both**, and never run a
+   preliminary self-assessment pass before dispatching the fresh critic —
+   the redundant pre-pass buys no measurable quality and roughly triples
+   the acceptance-block cost. Step 2's gate is the deterministic **scorer**
+   of the one authored verdict, not a second (or third) pass over the
+   criteria.
 
    > **Sub-agent type + derived-level ceremony (Epic #4478, M7-B).** When
    > `delivery.routing.roleScopedAgents` is enabled (the **default**), dispatch
@@ -129,7 +138,9 @@ mid-delivery, and evaluates the actual work product.
      one `{ index, criterion, verdict: met|partial|unmet, evidence,
      verifyEvidence[] }` record per acceptance item.
 2. **Decide.** Run the gate against the verdict (the caller's Step 1a names the
-   exact invocation — omit `--epic`):
+   exact invocation — omit `--epic`). The gate **scores the single verdict
+   the round's owner authored** — schema validation, round cap, decision —
+   and never re-scores the criteria itself (Story #4723):
 
    ```bash
    node <main-repo>/.agents/scripts/acceptance-eval.js \

package/.agents/workflows/helpers/deliver-reference.md

@@ -51,19 +51,23 @@ probe logs a warning and leans on init's lease refusal alone.
 
 ## Dispatch mechanics (role-scoped by default)
 
-**Lite-routed Stories execute inline (Story #4707).** Before spawning anything,
+**Lite-shaped Stories execute inline (Story #4722).** Before spawning anything,
 read the Story's `dispatchMode` from the resolver envelope
 (`stories[].dispatchMode`, derived by `resolveStoryDispatchMode` in
-`lib/orchestration/complexity-gate.js` from the persisted `route::lite`
-marker): a Story with `dispatchMode: "inline"` executes
+`lib/orchestration/complexity-gate.js` **from the fetched Story body's own
+shape** — `changes[]` count, acceptance count, creates-vs-refactors mix, and
+sensitive-path classes; the `route::lite` label is a human-visible hint only,
+never the control signal, so a lost or never-written label cannot misroute
+delivery): a Story with `dispatchMode: "inline"` executes
 [`deliver-story.md`](deliver-story.md) **inline in this session** — no
 `story-worker` sub-agent boot and no fresh acceptance-critic sub-agents
 (sub-agent boots are the dominant deliver-phase token cost at trivial scope) —
 threading the same `docsDigestPath` / `checklistPath` / change-set discipline
 as a spawned worker. Inline removes model-side fan-out only: every
 `single-story-close.js` gate, the PR to `main`, and the terminal envelope are
-identical. A Story without the marker (or with unreadable labels) takes the
-standard sub-agent path.
+identical. Everything else — a full-shaped body, a missing/unparseable body,
+or a footprint intersecting a sensitive-path class (sensitivity wins and
+keeps the fresh acceptance critic) — takes the standard sub-agent path.
 
 **Dispatch each `ready` Story (role-scoped by default).** When
 `delivery.routing.roleScopedAgents` is enabled (the **default**) and the host

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -125,8 +125,7 @@ The v2 engine's trait table:
 | Spec / slices | Folded `## Spec` + optional `## Slicing` checkpoints in-session |
 | Ceremony | Per-Story, routed off the derived change level via `ceremony-routing.js` |
 
-**Ceremony-lite Stories still land through this engine unchanged (Story #4683).** A Story that `/plan` routed onto the ceremony-lite path (its
-`complexityRoute.route === "lite"`) collapses only the *advisory* plan/deliver
+**Ceremony-lite Stories still land through this engine unchanged (Story #4683).** A lite-routed Story collapses only the *advisory* plan/deliver
 ceremony — the fresh-critic / Tech-Spec authoring a one-artifact scope does
 not earn. It does **not** get a cheaper landing: the close-validation gates
 (lint / test / format / coverage / CRAP / maintainability), the PR to `main`,
@@ -134,15 +133,22 @@ and the `rules/security-baseline.md` MUSTs all run exactly as for a
 full-ceremony Story. The lite route's `preserves` field is the machine-readable
 record of those non-negotiables; there is no lite-specific gate bypass.
 
-**The lite route persists to delivery as the `route::lite` label (Story #4707).** Persist stamps every Story of a lite-routed plan with that marker
-(and ledgers the route — including any audited planner-downgrade reason — on
-its `story-plan-state` checkpoint); a full-routed Story carries no marker.
-`/deliver` reads the label via `resolveStoryDispatchMode`
-(`lib/orchestration/complexity-gate.js`) and executes a lite Story
-**inline in the deliver session** — no `story-worker` sub-agent boot, and
-the Step 1a acceptance self-eval runs its critics **inline** (no
+**Deliver derives the route from the Story body's shape (Story #4722).**
+Persist stamps a lite cohort's Stories with the `route::lite` label as a
+*human-visible hint only* (and ledgers the authored verdict — recorded
+reason plus per-Story shape evidence — on the `story-plan-state`
+checkpoint); the label is never the control signal. `/deliver` computes the
+route from the fetched Story body via `resolveStoryDispatchMode`
+(`lib/orchestration/complexity-gate.js`) — the same shape taxonomy
+`deriveChangeLevel` applies to the landed diff at close: `changes[]` count,
+acceptance count, creates-vs-refactors mix, sensitive-path classes. A
+lite-shaped Story executes **inline in the deliver session** — even when the
+label is absent or its write failed — with no `story-worker` sub-agent boot,
+and the Step 1a acceptance self-eval runs its critics **inline** (no
 fresh-context acceptance-critic sub-agent dispatch; sub-agent boots are the
-dominant deliver-phase token cost at trivial scope). Inline execution
+dominant deliver-phase token cost at trivial scope). A footprint
+intersecting a sensitive-path class derives `full` — sensitivity wins, and
+the Story keeps its fresh acceptance critic. Inline execution
 changes the isolation only: the engine, every script gate, and the
 terminal envelope are byte-identical either way.
 
@@ -175,6 +181,20 @@ directly.
 
 ### Step 1a — self-eval mechanics
 
+**One verdict-owner per cluster (Story #4723).** The ceremony routing's
+resolved decision names each cluster's single verdict owner
+(`verdictOwner: 'fresh-critic' | 'inline-self-eval'` from
+`resolveCeremonyForRisk`): the fresh maker-blind critic when sensitivity
+routes the cluster `fresh`, the contract-identical inline self-eval when it
+routes `inline`. Exactly one pass authors the verdict — never both, and
+never a preliminary self-assessment pass before dispatching the fresh
+critic (the redundant pre-pass buys no measurable quality and roughly
+triples the acceptance-block cost). `acceptance-eval.js` is the
+deterministic **scorer** of that one authored verdict — schema validation,
+round cap, proceed / redraft / block — not an independent additional pass
+over the criteria. The M4-B floor holds: one verdict per cluster, the
+cluster count owned by `acceptance-clusters.js` alone.
+
 **Critic evidence-share (Story #4250).** When the critic runs a `verify[]`
 command that is byte-identical to a close gate (`lint` / `typecheck`), it
 records the pass into the Story evidence keyspace via `--standalone` so
@@ -227,8 +247,8 @@ Resolve fresh-vs-inline acceptance critics per AC-cluster with
 floor forces `fresh`). Review depth reads the same derived level via
 `review-depth.js` inside close, so the two decisions cannot disagree.
 
-**Lite-route override (Story #4707).** When the Story carries the
-`route::lite` marker (`resolveStoryDispatchMode` → `inline`), run every
+**Lite-route override (Story #4722).** When the Story's body derives the
+lite shape (`resolveStoryDispatchMode` → `inline`), run every
 acceptance critic **inline** — do not spawn fresh-context critic sub-agents
 regardless of what the profile would otherwise resolve. The self-eval rigor
 (scoring each `acceptance[]` item against the one computed change set, with

package/.agents/workflows/helpers/deliver-story.md

@@ -14,8 +14,9 @@ description:
 
 ## Overview
 
-The **one** delivery engine in v2 — every Story (`route::lite` runs
-inline with inline critics; engine, gates, envelope byte-identical):
+The **one** delivery engine in v2 — every Story (a lite-**shaped** Story
+runs inline with inline critics, #4722; engine, gates, envelope
+byte-identical):
 
 ```text
 single-story-init.js → implement + commits → derived-level ceremony
@@ -74,7 +75,7 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
 Follow the single-homed include
-[`acceptance-self-eval.md`](acceptance-self-eval.md) (fresh-context critic,
+[`acceptance-self-eval.md`](acceptance-self-eval.md) (single verdict-owner,
 `verify[]`-as-evidence, proceed / redraft / block). Gate invocation (omit
 `--epic`):
 

package/.agents/workflows/helpers/plan-reference.md

@@ -1,52 +1,87 @@
 # /plan — on-demand reference appendix
 
 > **Applies when:** you are executing [`/plan`](../plan.md) and hit one of the
-> situations below — the ceremony-lite route, `--tickets` supersede authoring,
-> critic dispatch detail, a failed persist, or source-id resolution. The spine
-> stays resident; this file is read on demand.
-
-## Ceremony-lite complexity gate (`complexityRoute`)
-
-The envelope's `complexityRoute` field is a **deterministic, conservative**
-plan-time gate (Story #4683) that routes a genuinely trivial single-artifact
-seed onto a collapsed path so it stops paying the full two-session
-plan/deliver ceremony that measurably buys no quality at that size:
-
-- **`route: "lite"`** — a trivial scope (seed ≤ `maxSeedWords` words **and** ≤
-  `maxArtifacts` enumerated items). Collapse the ceremony: author **one minimal
-  Story** and skip the fresh-critic / Tech-Spec ceremony a one-artifact scope
-  does not earn. The lite route is **not** licence to drop a non-negotiable —
-  its `preserves` field enumerates exactly what still holds: the Story ticket,
-  the PR-to-`main` landing, every repo quality gate, and the security baseline.
-  Those gates still run in `single-story-close.js` regardless of route.
-- **`route: "full"`** — everything else. The gate fails toward `full` on any
-  doubt (empty seed, over the word ceiling, a multi-capability enumeration, or
-  the gate disabled via `planning.complexityGate.enabled=false`), so a real
-  capability slice never loses ceremony. Author normally under the split policy.
-
-**Planner downgrade (audited, Story #4707).** Seed word count is a poor
-complexity proxy, so a `full` verdict you judge genuinely trivial (one
-artifact, one obvious change) may be downgraded to `lite` — but **only** by
-passing `--route-downgrade-reason "<why>"` to persist. The reason is recorded
-on every created Story's `story-plan-state` checkpoint, making the judgment
-auditable; without a recorded reason the deterministic verdict stands, and the
-gate itself is unchanged (it still fails toward `full`).
-
-**The route persists with the Story (Story #4707).** Persist labels every
-Story of a lite-routed plan with the **`route::lite`** marker and ledgers the
-route (including any downgrade reason) on its `story-plan-state` checkpoint;
-a full-routed Story carries no marker. `/deliver` reads the marker to execute
-a lite Story **inline** — no story-worker or acceptance-critic sub-agent
-boots — while every `single-story-close.js` gate runs unchanged. The
-`route::*` axis is runtime-derived: hand-authored `route::*` entries in
-`labels[]` are dropped by persist.
-
-The threshold and its override knob (`planning.complexityGate.{enabled,
-maxSeedWords, maxArtifacts}`) are documented in
-[`.agents/docs/configuration.md`](../../docs/configuration.md) under
-`### planning`; the defaults live on `DEFAULT_COMPLEXITY_GATE` in
+> situations below — shape-derived complexity routing, `--tickets` supersede
+> authoring, critic dispatch detail, a failed persist, or source-id
+> resolution. The spine stays resident; this file is read on demand.
+
+## Shape-derived complexity routing (`complexitySignals`)
+
+Complexity routes on the **objective shape of the authored work**, never on
+seed word count (Story #4722 — a detailed prompt can describe trivial work, a
+terse one complex work; `maxSeedWords` is removed). The pipeline stages the
+decision:
+
+- **Signals, not routing.** The envelope's `complexitySignals` field is
+  advisory only (`routingAuthority: false`): enumerated-artifact count (with
+  the configured `maxArtifacts` threshold beside it as one input),
+  `planning.riskHeuristics` phrases present in the seed, the repo state of
+  predicted paths (existing paths predict refactors; missing predict
+  creates), and the `audit-rules.json` sensitive-path classes the predicted
+  footprint intersects.
+- **You author the verdict.** Judge the signals: a genuinely trivial scope
+  (small additive footprint, no risk hits, no sensitive class) earns a `lite`
+  claim via `plan-persist.js --route-downgrade-reason "<why>"`. The reason is
+  recorded on every created Story's `story-plan-state` checkpoint, making the
+  judgment auditable; without a recorded reason the conservative default
+  (`full`) stands.
+- **Persist backstops the claim deterministically.** After authoring, the
+  work has measurable shape, so persist validates the `lite` claim against
+  each Story's own shape — `changes[]` count, acceptance-criteria count,
+  creates-vs-refactors mix, glob-free footprint, and sensitive-path classes,
+  against the framework `STORY_SHAPE_CEILINGS` — and **fails closed to
+  `full`** when any Story exceeds them (the refusal is ledgered on the
+  checkpoint too). The lite route is **not** licence to drop a
+  non-negotiable — every decision's `preserves` field enumerates what still
+  holds: the Story ticket, the PR-to-`main` landing, every repo quality gate,
+  and the security baseline. Those gates run in `single-story-close.js`
+  regardless of route.
+
+**The label is a hint; deliver re-derives (Story #4722).** Persist labels a
+lite cohort's Stories with **`route::lite`** as a *human-visible hint only* —
+`/deliver` computes the route from each fetched Story body via the same shape
+function at dispatch, so neither a lost label nor an unread marker can
+misroute delivery: a lite-shaped Story executes **inline** (no story-worker
+or acceptance-critic sub-agent boots) even with the label absent, and a
+sensitive-footprint Story routes `full` and keeps its fresh critic even with
+the label present. The `route::*` axis stays runtime-derived: hand-authored
+`route::*` entries in `labels[]` are dropped by persist.
+
+The knobs (`planning.complexityGate.{enabled, maxArtifacts}`) are documented
+in [`.agents/docs/configuration.md`](../../docs/configuration.md) under
+`### planning`; the defaults live on `DEFAULT_COMPLEXITY_GATE` and the shape
+ceilings on `STORY_SHAPE_CEILINGS` in
 [`lib/orchestration/complexity-gate.js`](../../scripts/lib/orchestration/complexity-gate.js).
 
+## Correct-by-construction authoring template (Story #4723)
+
+`plan-context.js --out` writes `stories.template.json` as a
+**correct-by-construction** skeleton, built from the same repo snapshot the
+`complexitySignals` probed:
+
+- **`verify[]` placeholders already end with a valid `(tier)` tag.** Keep
+  every filled entry's trailing tag one of `(unit)` / `(contract)` /
+  `(e2e)` / `(validate)` (or use the `manual:<reason>` escape) — a tierless
+  entry is exactly the mechanical persist round-trip the template exists to
+  prevent.
+- **`changes[]` arrive pre-resolved to creates-vs-refactors.** Every path
+  the seed predicted is probed against the repo: an existing path is
+  emitted with `assumption: "refactors-existing"`, a missing one with
+  `assumption: "creates"`. Trust the pre-resolved assumption — verify
+  against the repo before overriding one (authoring `creates` for a file
+  that exists at base is a validator rejection). The persist gates stay
+  authoritative: they probe the base branch ref, not the working tree.
+- **Keep `## Spec` near contract-level prose.** Persist emits an
+  **advisory** warning past ~250 words (`SPEC_SOFT_WORD_BUDGET`) — it never
+  fails the persist, but it is the nudge toward the #4707 contract-level
+  Spec (interfaces, invariants, load-bearing constraints; no per-file
+  behavior narration). The hard fail-closed ceiling (~1500 tokens,
+  `spec-spill.js`) is unchanged.
+
+A faithfully-filled skeleton — placeholders replaced, pre-resolved entries
+kept, tags valid — passes the persist ticket validators with no
+round-trip.
+
 ## Tickets mode — authoring `supersedes[]`
 
 In `--tickets` mode each Story carries a top-level `supersedes` array claiming

package/.agents/workflows/plan.md

@@ -32,7 +32,7 @@ Epic/Story router, no scope-triage `epic|story` verdict:
 | `--tickets <ids>` | Issue ids to analyze; closed as superseded at persist. |
 | `--no-close-superseded` | Keep the source issues open — no supersede comment, no close. |
 | `--force-review` | STOP at gate #2 for operator review — the only review gate (Story #4542). |
-| `--route-downgrade-reason "<text>"` | Audited `full`→`lite` downgrade (Story #4707), ledgered per Story. |
+| `--route-downgrade-reason "<text>"` | Authored `lite` verdict + reason (Story #4722), ledgered per Story; shape-validated, fails closed to `full`. |
 | `--allow-over-budget` | Permit a plan exceeding `maxTickets`. |
 | `--yes` | Non-interactive: auto-proceed gate #1 and gate #2 HITL waits. |
 | `--dry-run` | Author + validate without GitHub writes; run as a pre-pass. |
@@ -66,11 +66,11 @@ authoring skeleton step 2 starts from.
 
 The envelope carries docs context, codebase snapshot, the story-author
 prompt, `sourceTickets[]`, `duplicates[]` (open **Stories** overlapping the
-seed — never Epics), and the `complexityRoute` signal:
-`"lite"` (trivial single-artifact scope — author one minimal Story, skip
-fresh-critic / Tech-Spec ceremony; every close gate still runs) or `"full"`
-(everything else; fails toward `full` on any doubt). Detail:
-[`helpers/plan-reference.md` § Ceremony-lite gate](helpers/plan-reference.md).
+seed — never Epics), and advisory `complexitySignals` (**no routing
+authority**, Story #4722). A genuinely trivial scope earns
+`--route-downgrade-reason "<why>"` at persist — shape-validated, failing
+closed to `full`. Detail:
+[`helpers/plan-reference.md` § Shape-derived routing](helpers/plan-reference.md).
 Under `--yes`, do not ask free-form operator questions — unresolved
 unknowns land in Key Assumptions.
 
@@ -79,8 +79,9 @@ duplicate-candidate review. Under `--yes`, auto-proceed.
 
 ### 2. Author
 
-**One-shot authoring (Story #4707).** Start from `stories.template.json`
-(or the skeleton below); author `stories.json` in one pass. `body` is a
+**One-shot authoring (Story #4707).** Start from `stories.template.json`;
+author `stories.json` in one pass. Entries are pre-resolved (#4723); keep
+tiers/assumptions valid. `body` is a
 markdown string **or** a structured object; persist parses either,
 serializes the canonical markdown, and syncs the top-level `acceptance[]` /
 `verify[]` into the body — never dual-author those lists.
@@ -182,7 +183,7 @@ persist, re-run the same command; never hand-delete issues.
 
 - [`/deliver`](deliver.md) — delivery entry point.
 - [`/audit-to-stories`](audit-to-stories.md) — audit findings → plan seed.
-- [`helpers/plan-reference.md`](helpers/plan-reference.md) — ceremony-lite,
-  supersede, critic, and persist-resume detail.
+- [`helpers/plan-reference.md`](helpers/plan-reference.md) — on-demand
+  detail.
 - [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) — optional
   split-advisory notes only (no routing verdict).

package/docs/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.11.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.10.0...mandrel-v2.11.0) (2026-07-23)
+
+
+### Added
+
+* **migration:** strip retired planning.complexityGate.maxSeedWords on consumer upgrade ([#4729](https://github.com/dsj1984/mandrel/issues/4729)) ([fd75b54](https://github.com/dsj1984/mandrel/commit/fd75b54b0f7390a3d562a25e90cbe6c5911b4f66))
+* route on the work, not the words — shape-derived complexity routing honored end-to-end (refs [#4722](https://github.com/dsj1984/mandrel/issues/4722)) ([#4725](https://github.com/dsj1984/mandrel/issues/4725)) ([f166ca1](https://github.com/dsj1984/mandrel/commit/f166ca14785bad97657fdda0f41e282e47db2ea3))
+* single-owner acceptance verification + plan-template hardening ([#4723](https://github.com/dsj1984/mandrel/issues/4723)) ([#4728](https://github.com/dsj1984/mandrel/issues/4728)) ([954f55a](https://github.com/dsj1984/mandrel/commit/954f55aedda3199d1fdd48b11884a9513012e2c4))
+
+
+### Fixed
+
+* **doctor:** include .agents/local/workflows/ in the commands-in-sync expected set (refs [#4724](https://github.com/dsj1984/mandrel/issues/4724)) ([#4726](https://github.com/dsj1984/mandrel/issues/4726)) ([b96dcd4](https://github.com/dsj1984/mandrel/commit/b96dcd446879a9da28e8d86c1a493c2bae62d2c8))
+
+
+### Changed
+
+* **orchestration:** extract spec-budget and story-body parse gate from ticket-validator ([#4730](https://github.com/dsj1984/mandrel/issues/4730)) ([fb0c3c3](https://github.com/dsj1984/mandrel/commit/fb0c3c31795f6178b2ba740b2fb00760921e1178))
+
 ## [2.10.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.9.0...mandrel-v2.10.0) (2026-07-23)
 
 

package/lib/cli/registry.js

@@ -225,10 +225,20 @@ function runGhAuth({ runner = spawn, env = process.env } = {}) {
 // ---------------------------------------------------------------------------
 
 /**
- * Dry-run the sync-claude-commands logic: compare `.agents/workflows/*.md`
- * sources to the generated flat command tree `.claude/commands/*.md`
- * destinations and report parity (the projection is a flat `/<name>` command
- * surface; the #3576 plugin projection was reverted).
+ * Dry-run the sync-claude-commands logic: compare the union of the two
+ * projection sources — `.agents/workflows/*.md` (the installed payload) and
+ * `.agents/local/workflows/*.md` (consumer-authored, prune-exempt, projected
+ * since 1.75.0 / #4244) — to the generated flat command tree
+ * `.claude/commands/*.md` destinations and report parity (the projection is
+ * a flat `/<name>` command surface; the #3576 plugin projection was
+ * reverted). A dest command backed only by a local workflow is in sync, not
+ * stale (#4721).
+ *
+ * Union semantics mirror the sync script's payload-wins shadowing (`byRel`):
+ * a basename projects iff at least one source's copy is non-excluded — an
+ * excluded payload copy never enters `byRel`, so it does not shadow a
+ * projectable local copy. Filtering each source dir independently and
+ * unioning the surviving basenames reproduces that exactly.
  *
  * Resolution anchor (Story #3588): the root defaults to `process.cwd()` —
  * the consumer project directory where `mandrel sync` materializes both
@@ -272,28 +282,35 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
       }
     });
 
-  const srcDir = path.join(root, '.agents', 'workflows');
+  const srcDirs = [
+    path.join(root, '.agents', 'workflows'),
+    path.join(root, '.agents', 'local', 'workflows'),
+  ];
   const destDir = path.join(root, '.claude', 'commands');
 
   // Only top-level .md files are synced (helpers/ subdirectory excluded by
   // the sync script — they are path-included modules, not slash commands).
   // Workflows whose frontmatter carries `command: false` (#4482) opt out of
-  // projection and must not count toward the expected command set.
-  const sources = listDir(srcDir)
-    .filter((f) => !f.startsWith('.'))
-    .filter((f) => {
+  // projection and must not count toward the expected command set. An absent
+  // local dir degrades to [] via the listDir catch, so payload-only
+  // consumers are unchanged.
+  const expected = new Set();
+  for (const srcDir of srcDirs) {
+    for (const f of listDir(srcDir)) {
+      if (f.startsWith('.')) continue;
       const content = readSource(path.join(srcDir, f));
-      return content == null || !isCommandExcluded(content);
-    })
-    .sort();
+      if (content != null && isCommandExcluded(content)) continue;
+      expected.add(f);
+    }
+  }
+  const sources = [...expected].sort();
   const dests = listDir(destDir)
     .filter((f) => !f.startsWith('.'))
     .sort();
 
-  const srcSet = new Set(sources);
   const dstSet = new Set(dests);
   const missing = sources.filter((f) => !dstSet.has(f));
-  const extra = dests.filter((f) => !srcSet.has(f));
+  const extra = dests.filter((f) => !expected.has(f));
 
   if (missing.length === 0 && extra.length === 0) {
     return { ok: true, detail: `${sources.length} commands up to date` };