mandrel 2.27.0 → 2.28.0

package/.agents/docs/execution-reference.md

@@ -96,18 +96,28 @@ over-ceiling envelope or an over-budget Story count.
 - **`PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`** (`lib/orchestration/plan-context.js`):
   256 KB (≈64K tokens at the ≈4-chars/token estimate) on the serialized
   envelope `buildPlanContext` assembles, checked at the single choke point
-  every mode returns through. A measured seed-mode envelope on this repo is
-  ~120 KB — `docsContext` (~63 KB) and `systemPrompts` (~54 KB) are the whole
-  of it, every other field under 1 KB — so the ceiling carries roughly 2×
-  headroom. Story #4811 retired the codebase snapshot that used to sit
-  alongside them, leaving the operator-supplied seed the only unbounded
-  contributor.
-- **On refusal**, the error names the envelope's largest fields. Trim the seed,
-  or plan fewer `--tickets` source issues in one run. The seed is carried
-  **verbatim** by design — it
-  is the operator's request, and summarizing it silently would degrade planning
-  quality precisely when the input is richest — so there is no elision path to
-  fall back on. Raising the ceiling needs a measured justification.
+  every mode returns through. A measured seed-mode envelope on this repo's
+  thin `.feature` corpus is ~120 KB — `docsContext` (~63 KB) and
+  `systemPrompts` (~54 KB) are the bulk of the fixed floor, every other field
+  under 1 KB. That is **not** representative of every consumer: Story #4977
+  measured `bddScenarios` at 118 KB on a consumer with a mature Gherkin
+  corpus — larger than `docsContext` and `systemPrompts` combined, leaving
+  ~5.5% headroom instead of ~2×. `bddScenarios` is now truncated to
+  `BDD_SCENARIOS_BYTE_BUDGET` (`lib/bdd-scenario-budget.js`, ≤24 KB,
+  reported via `truncated` / `totalScenarios` / `includedScenarios` rather
+  than silently dropped) before it reaches the envelope, deliberately a fixed
+  framework constant rather than an `.agentrc.json` knob — the same reasoning
+  Story #4811 applied when it retired the codebase snapshot. The
+  operator-supplied seed remains the one field with no cap and no elision
+  path.
+- **On refusal**, the error names the envelope's largest fields and the
+  remedy that follows the single largest one (`OVERSIZE_FIELD_REMEDIES` in
+  `plan-context.js`) — trim the seed, plan fewer `--tickets` source issues in
+  one run, or trim `docsContextFiles`, depending on which field actually blew
+  the budget. The seed itself is carried **verbatim** by design — it is the
+  operator's request, and summarizing it silently would degrade planning
+  quality precisely when the input is richest — so it alone has no elision
+  path to fall back on. Raising the ceiling needs a measured justification.
 
 ### Session-mass capacity (plan-time sizing)
 

package/.agents/scripts/lib/bdd-scenario-budget.js

@@ -0,0 +1,68 @@
+/**
+ * bdd-scenario-budget.js — envelope byte budget for the `bddScenarios`
+ * `/plan` context-envelope field (Story #4977).
+ *
+ * `bdd-scenario-scanner.js`'s `scanBddScenarios` stays a faithful, uncapped
+ * index of the project's `.feature` corpus — that scan is also used
+ * directly by `lib/qa/resolve-selection.js`, which needs the full set. The
+ * cap belongs at the envelope boundary instead, in its own module: on a
+ * consumer with a mature Gherkin corpus, `bddScenarios` grew to 118 KB —
+ * larger than `docsContext` and `systemPrompts` combined — consuming
+ * nearly the entire `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` headroom on its
+ * own and blocking `/audit-to-stories`' single-plan path entirely.
+ *
+ * Deliberately a fixed framework constant rather than an `.agentrc.json`
+ * knob: Story #4541 retired the one operator-tunable planner-context budget
+ * (`planning.context.maxBytes`) because a cap the operator can raise past
+ * what the model can read fails silently again, and the same reasoning
+ * applies here.
+ */
+
+/**
+ * Byte budget for the capped `bddScenarios` envelope field. Sized well
+ * under `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING` (256 KB) — this is one of
+ * several envelope fields, not the whole budget. At the measured ~337
+ * bytes/scenario average (Story #4977 evidence, a mature Gherkin corpus),
+ * 24 KB holds roughly 70 scenarios before truncating.
+ *
+ * Deliberately module-private: the only production consumer is
+ * {@link capBddScenarios} below via the `opts.byteBudget` default. Tests
+ * assert the resulting behavior (truncation, order, fit) rather than
+ * importing this value directly, so it carries no public export the
+ * `--production` dead-exports ratchet would otherwise flag as test-only.
+ */
+const BDD_SCENARIOS_BYTE_BUDGET = 24_000;
+
+/**
+ * Truncate a scenario index to a byte budget, deterministically (scan
+ * order — file walk order, then in-file order — never re-sorted), and
+ * report what was dropped rather than truncating silently.
+ *
+ * @param {Array<object>} scenarios Full scan output (order preserved).
+ * @param {{ byteBudget?: number }} [opts]
+ * @returns {{
+ *   scenarios: Array<object>,
+ *   totalScenarios: number,
+ *   includedScenarios: number,
+ *   truncated: boolean,
+ * }}
+ */
+export function capBddScenarios(scenarios, opts = {}) {
+  const byteBudget = opts.byteBudget ?? BDD_SCENARIOS_BYTE_BUDGET;
+  const list = Array.isArray(scenarios) ? scenarios : [];
+  let bytes = 0;
+  let cut = list.length;
+  for (let i = 0; i < list.length; i += 1) {
+    bytes += Buffer.byteLength(JSON.stringify(list[i]), 'utf-8');
+    if (bytes > byteBudget) {
+      cut = i;
+      break;
+    }
+  }
+  return {
+    scenarios: list.slice(0, cut),
+    totalScenarios: list.length,
+    includedScenarios: cut,
+    truncated: cut < list.length,
+  };
+}

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

@@ -46,15 +46,22 @@ import { buildDecomposerSystemPrompt } from './planning/decomposer-context.js';
  * body and ship the raw seed on `seed.content` instead — the budget bounded
  * a field that never left the function.
  *
- * A measured seed-mode envelope on this repo is ~120 KB, dominated by the
- * digest-first `docsContext` (~63 KB inline digest) and the rendered
- * `systemPrompts` (~54 KB); every other field is under 1 KB. Story #4811
- * retired the tier-capped codebase snapshot that used to sit alongside them
- * (~35 KB skinny here). The seed itself is operator-supplied, carried
- * verbatim, and is the only unbounded contributor. 256 KB (~64K tokens at the
- * ≈4-chars/token estimate) leaves roughly 2× headroom over that measurement
- * while staying well under the session budget. The test suite asserts
- * serialized envelopes stay under this value — raise it only with a measured
+ * A measured seed-mode envelope on this repo (a thin `.feature` corpus) is
+ * ~120 KB, dominated by the digest-first `docsContext` (~63 KB inline
+ * digest) and the rendered `systemPrompts` (~54 KB); every other field is
+ * under 1 KB. Story #4811 retired the tier-capped codebase snapshot that
+ * used to sit alongside them (~35 KB skinny here). This measurement is
+ * **not** representative of every consumer, though: Story #4977 found
+ * `bddScenarios` at 118 KB on a consumer with a mature Gherkin corpus —
+ * larger than `docsContext` and `systemPrompts` combined, consuming nearly
+ * all of the ceiling's headroom on its own, because the scanner applied no
+ * cap. `bddScenarios` is now truncated to `BDD_SCENARIOS_BYTE_BUDGET`
+ * (`lib/bdd-scenario-budget.js`, ≤24 KB) before it reaches this envelope,
+ * so the seed remains the only field this ceiling leaves genuinely
+ * unbounded. 256 KB (~64K tokens at the ≈4-chars/token estimate) leaves
+ * roughly 2× headroom over the fixed-floor measurement above while staying
+ * well under the session budget. The test suite asserts serialized
+ * envelopes stay under this value — raise it only with a measured
  * justification.
  */
 export const PLAN_CONTEXT_ENVELOPE_BYTE_CEILING = 256_000;
@@ -62,6 +69,31 @@ export const PLAN_CONTEXT_ENVELOPE_BYTE_CEILING = 256_000;
 /** Fields named in the over-ceiling error, to point at what to trim. */
 const OVERSIZE_REPORT_FIELDS = 3;
 
+/**
+ * Per-field remedy for the over-ceiling refusal, keyed by envelope field
+ * name. Story #4977 — the refusal used to hardcode "trim the seed, or plan
+ * fewer --tickets" regardless of which field actually blew the budget; on a
+ * consumer with a mature Gherkin corpus the dominant field was
+ * `bddScenarios` (repo-derived, not seed-derived), and "trim the seed" was a
+ * dead lever the operator had no way to act on. The remedy now follows the
+ * single largest field.
+ */
+const OVERSIZE_FIELD_REMEDIES = Object.freeze({
+  seed: 'Trim the seed text — it is carried verbatim by design and is the one field with no elision path.',
+  sourceTickets:
+    'Plan fewer --tickets source issues in one run — each source ticket body is carried verbatim.',
+  epic: 'Plan fewer --tickets source issues in one run, or re-plan with a shorter Epic body.',
+  bddScenarios:
+    "The project's .feature corpus is already capped near BDD_SCENARIOS_BYTE_BUDGET (lib/bdd-scenario-budget.js) — if this still dominates, another field is unusually small; check the full field breakdown.",
+  docsContext:
+    'Trim project.docsContextFiles — docsContext is a digest built from those files.',
+  systemPrompts:
+    'This field is a fixed framework prompt, not operator content — if it dominates, file a framework-gap issue rather than trying to trim it.',
+});
+
+const DEFAULT_OVERSIZE_REMEDY =
+  'Trim the seed, or plan fewer --tickets source issues in one run.';
+
 /**
  * Fail closed when an assembled envelope exceeds
  * {@link PLAN_CONTEXT_ENVELOPE_BYTE_CEILING}.
@@ -97,22 +129,26 @@ function assertPlanContextWithinCeiling(envelope, opts = {}) {
   const bytes = Buffer.byteLength(JSON.stringify(envelope) ?? '', 'utf-8');
   if (bytes <= ceiling) return envelope;
 
-  const largest = Object.entries(envelope)
+  const sortedFields = Object.entries(envelope)
     .map(([field, value]) => [
       field,
       Buffer.byteLength(JSON.stringify(value) ?? '', 'utf-8'),
     ])
-    .sort((a, b) => b[1] - a[1])
+    .sort((a, b) => b[1] - a[1]);
+
+  const largest = sortedFields
     .slice(0, OVERSIZE_REPORT_FIELDS)
     .map(([field, size]) => `${field} (${Math.round(size / 1024)} KB)`)
     .join(', ');
 
+  const topField = sortedFields[0]?.[0];
+  const remedy = OVERSIZE_FIELD_REMEDIES[topField] ?? DEFAULT_OVERSIZE_REMEDY;
+
   throw new Error(
     `[plan-context] the assembled "${envelope?.mode}" envelope is ` +
       `${Math.round(bytes / 1024)} KB, over the ` +
       `${Math.round(ceiling / 1024)} KB planner-context ceiling. Largest ` +
-      `fields: ${largest}. Trim the seed, or plan fewer --tickets source ` +
-      'issues in one run. Raising the ceiling needs a measured ' +
+      `fields: ${largest}. ${remedy} Raising the ceiling needs a measured ` +
       'justification — see PLAN_CONTEXT_ENVELOPE_BYTE_CEILING.',
   );
 }

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -12,6 +12,7 @@ import {
   resolveFeatureRoots,
   verifyBddRunnerPendingTag,
 } from '../../bdd-runner-detect.js';
+import { capBddScenarios } from '../../bdd-scenario-budget.js';
 import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
 import { getPaths, PROJECT_ROOT } from '../../config-resolver.js';
 import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
@@ -73,18 +74,24 @@ async function buildPlanningDocsContext({ seedIssueId, settings, cwd }) {
 /**
  * Story #2637 — index existing BDD scenarios so the Acceptance Engineer step
  * can annotate planned ACs with matches from the project's `.feature` files.
- * Empty array when the project has not adopted BDD; the scanner is
- * best-effort and never throws on filesystem errors.
+ * Empty (capped-shape) result when the project has not adopted BDD; the
+ * scanner is best-effort and never throws on filesystem errors.
  *
- * @returns {Array<object>}
+ * Story #4977 — the scan itself stays uncapped (a faithful `.feature`
+ * index), but the envelope-bound result is truncated to
+ * `BDD_SCENARIOS_BYTE_BUDGET` via `capBddScenarios` so a mature Gherkin
+ * corpus cannot alone consume the `/plan` context-envelope ceiling. Callers
+ * needing the raw count read `totalScenarios` vs `includedScenarios`.
+ *
+ * @returns {ReturnType<typeof capBddScenarios>}
  */
 function scanBddScenariosBestEffort() {
   try {
     const featureRoots = resolveFeatureRoots({ cwd: PROJECT_ROOT });
-    return scanBddScenarios({ featureRoots });
+    return capBddScenarios(scanBddScenarios({ featureRoots }));
   } catch (err) {
     Logger.warn(`[plan-context] BDD scenario scan skipped: ${err.message}`);
-    return [];
+    return capBddScenarios([]);
   }
 }
 

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.28.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.27.0...mandrel-v2.28.0) (2026-08-03)
+
+
+### Fixed
+
+* uncapped bddScenarios consumes the /plan envelope ceiling; blocks /audit-to-stories' single-plan path entirely ([#4977](https://github.com/dsj1984/mandrel/issues/4977)) ([#4978](https://github.com/dsj1984/mandrel/issues/4978)) ([c8b2731](https://github.com/dsj1984/mandrel/commit/c8b27312e67b138567e4e41789871e3911c7a8cb))
+
 ## [2.27.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.26.0...mandrel-v2.27.0) (2026-08-03)
 
 

package/package.json

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