mandrel 2.10.0 → 2.12.0

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,37 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.12.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.11.0...mandrel-v2.12.0) (2026-07-24)
+
+
+### Performance
+
+* **orchestration:** cut deliver-path cost — inline single-Story dispatch, bounded close output, bundled reads (refs [#4736](https://github.com/dsj1984/mandrel/issues/4736)) ([#4737](https://github.com/dsj1984/mandrel/issues/4737)) ([81e62a8](https://github.com/dsj1984/mandrel/commit/81e62a87ca49add2aeb5b5a6b9ac11014edc3374))
+
+
+### Changed
+
+* **orchestration:** thread injectedRules seam through route composition layers ([#4734](https://github.com/dsj1984/mandrel/issues/4734)) ([6e1daad](https://github.com/dsj1984/mandrel/commit/6e1daadbc24210fdb34e4892c0077256f2ccd051))
+
+## [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` };

package/lib/migrations/index.js

@@ -55,6 +55,7 @@
 import { retireMiDropKnobs } from './steps/2.1.0-retire-mi-drop-knobs.js';
 import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurrency-cap.js';
 import { retireEpicAcTags } from './steps/2.2.0-retire-epic-ac-tags.js';
+import { retireMaxSeedWords } from './steps/2.11.0-retire-max-seed-words.js';
 
 /**
  * Ordered registry of migration steps. MUST stay sorted ascending by
@@ -71,6 +72,7 @@ export const migrations = [
   retireMiDropKnobs,
   retireVerifyConcurrencyCap,
   retireEpicAcTags,
+  retireMaxSeedWords,
 ];
 
 /**

package/lib/migrations/steps/2.11.0-retire-max-seed-words.js

@@ -0,0 +1,92 @@
+// lib/migrations/steps/2.11.0-retire-max-seed-words.js
+/**
+ * Story #4722 follow-up — strip the retired
+ * `planning.complexityGate.maxSeedWords` knob from a consumer's
+ * `.agentrc.json`.
+ *
+ * #4722 (PR #4725) hard-cutover-removed word-count complexity routing:
+ * the route derives from the authored Story's shape, never from seed word
+ * count, and `maxSeedWords` was dropped from the runtime AJV schema and
+ * the published mirror. The `complexityGate` block carries
+ * `additionalProperties: false`, so a consumer whose config still sets
+ * `maxSeedWords` hits a hard validation failure on upgrade, not a
+ * warning. This step strips the key before that check runs — the same
+ * contract-cutover pattern as `2.1.0-retire-mi-drop-knobs.js`.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+const AGENTRC_FILENAME = '.agentrc.json';
+
+/**
+ * @param {unknown} ctx
+ * @returns {string}
+ */
+function resolveAgentrcPath(ctx) {
+  const projectRoot = ctx?.projectRoot ?? process.cwd();
+  return path.join(projectRoot, AGENTRC_FILENAME);
+}
+
+/**
+ * @param {unknown} ctx
+ * @param {typeof nodeFs} fsImpl
+ * @returns {object | null}
+ */
+function readAgentrcConfig(ctx, fsImpl) {
+  try {
+    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object | null} config
+ * @returns {boolean}
+ */
+function hasRetiredKey(config) {
+  const gate = config?.planning?.complexityGate;
+  return Boolean(gate) && Object.hasOwn(gate, 'maxSeedWords');
+}
+
+export const retireMaxSeedWords = {
+  version: '2.11.0',
+  description:
+    'strip retired planning.complexityGate.maxSeedWords from .agentrc.json ' +
+    '(complexity routes on Story shape, never seed word count — Story #4722)',
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {boolean}
+   */
+  detect(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    return hasRetiredKey(readAgentrcConfig(ctx, fsImpl));
+  },
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @returns {void}
+   */
+  apply(ctx) {
+    const fsImpl = ctx?.fs ?? nodeFs;
+    const config = readAgentrcConfig(ctx, fsImpl);
+    if (!config) return;
+
+    const gate = config.planning?.complexityGate;
+    if (gate && Object.hasOwn(gate, 'maxSeedWords')) {
+      delete gate.maxSeedWords;
+      if (Object.keys(gate).length === 0) {
+        delete config.planning.complexityGate;
+        if (Object.keys(config.planning).length === 0) {
+          delete config.planning;
+        }
+      }
+    }
+
+    fsImpl.writeFileSync(
+      resolveAgentrcPath(ctx),
+      `${JSON.stringify(config, null, 2)}\n`,
+    );
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",