mandrel 2.27.0 → 2.29.0

package/.agents/scripts/lib/crap-baseline-join.js

@@ -0,0 +1,153 @@
+/**
+ * crap-baseline-join.js — the incremental-coverage CRAP join (Story #4981).
+ *
+ * Split out of `crap-engine.js` into its own file (rather than added inline)
+ * so the Story's join logic lands as new code, not a same-file expansion of
+ * the pre-existing scoring kernel. Imports its coordinate/formula
+ * primitives from `crap-coordinates.js` (not `crap-engine.js`) and its
+ * identity key from `crap-baseline-index.js` — both leaf modules — so this
+ * file stays a one-directional consumer with no edge back into
+ * `crap-engine.js`.
+ */
+import { methodIdentityKey } from './crap-baseline-index.js';
+import {
+  COORDINATE_ORIGINAL,
+  COORDINATE_TRANSPILED,
+  crapFormula,
+} from './crap-coordinates.js';
+
+/**
+ * Apply the standard `requireCoverage` policy to a single raw method row.
+ * The per-row half of `crap-engine.js#finalizeMethodRows`'s loop body,
+ * extracted (Story #4981) so `finalizeMethodRowsWithBaseline`, below, can
+ * apply the exact same per-row policy to a method whose file was NOT in the
+ * diff scope but whose baseline row could not be found — the fail-closed
+ * path AC-3 requires.
+ *
+ * @param {object} mr A raw row from `methodRowsFromReport`.
+ * @param {{requireCoverage: boolean, coverageAvailable: boolean}} opts
+ * @returns {{ resolved: boolean, row: object | null }} `row: null` means the
+ *   method is skipped-and-counted; `resolved` tracks the join outcome
+ *   (independent of whether the row survives the skip policy).
+ */
+export function resolveRawRow(mr, { requireCoverage, coverageAvailable }) {
+  const unresolved = mr.crap === null || mr.coverage === null;
+  const resolved = !unresolved;
+  // Unjoinable is not untested (Story #4901).
+  if (
+    mr.coordinateSystem === COORDINATE_TRANSPILED ||
+    (unresolved && (requireCoverage || !coverageAvailable))
+  ) {
+    return { resolved, row: null };
+  }
+  const coverage = unresolved ? 0 : mr.coverage;
+  const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
+  // Everything the scan decided is carried forward; this step overrides only
+  // what its own policy resolves. Spreading rather than re-listing each field
+  // is why the row's identity marker (Story #4969) and its provenance
+  // (Story #4866) survive the step without a line each to remember them —
+  // a hand-rebuilt row is how a marker silently stops reaching the baseline.
+  return {
+    resolved,
+    row: {
+      ...mr,
+      coverage,
+      crap,
+      coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
+    },
+  };
+}
+
+/**
+ * Incremental-mode join (Story #4981): resolve a file's raw method rows
+ * against its committed CRAP-baseline rows instead of requiring fresh
+ * coverage, for a file the diff did NOT touch.
+ *
+ * Rationale: `coverage-capture`'s incremental mode only runs the consumer's
+ * test suite scoped to the diff, so an untouched file's coverage entry may
+ * legitimately be absent even though nothing about that file's methods
+ * changed. Requiring a fresh join for it would either (a) skip-and-count
+ * every one of its methods under `requireCoverage: true`, weakening the
+ * gate's signal for the vast majority of the tree on every run, or (b) score
+ * them at an invented 0% under `requireCoverage: false`, manufacturing a
+ * maximal CRAP for code the diff never touched. Neither is a measurement.
+ *
+ * The join key is `${method}@${startLine}` — the per-file half of the
+ * composite identity `kinds/crap.js#crapRowKey` uses for the full baseline
+ * compare (`${path}::${method}@${startLine}`); callers pass in a
+ * per-file-scoped `baselineByKey` map so this function stays path-agnostic.
+ *
+ * **Fail-closed (AC-3).** `touched: true` (the file WAS in the diff) or a
+ * missing/empty `baselineByKey` reproduces `crap-engine.js#finalizeMethodRows`
+ * exactly — this is the pre-#4981 per-row policy, so a caller that never
+ * opts in sees byte-identical behaviour (AC-5). For an untouched file, a
+ * method whose baseline row cannot be found (new method, moved line, or a
+ * baseline that simply never carried it) is NOT invented — it falls back to
+ * the same per-row `requireCoverage` skip-and-count policy, via the shared
+ * `resolveRawRow`. A method whose coordinate system is transpiled is never
+ * resolved from the baseline either, for the same un-joinable reason
+ * `resolveRawRow` excludes it (Story #4901).
+ *
+ * @param {Array<object>} rawRows Rows from `methodRowsFromReport`, all for
+ *   the SAME file.
+ * @param {{
+ *   requireCoverage?: boolean,
+ *   coverageAvailable?: boolean,
+ *   touched?: boolean,
+ *   baselineByKey?: Map<string, {crap: number}> | null,
+ * }} [opts]
+ * @returns {{
+ *   rows: Array<object>,
+ *   skippedMethodsNoCoverage: number,
+ *   resolvedMethods: number,
+ *   totalMethods: number,
+ * }}
+ */
+export function finalizeMethodRowsWithBaseline(
+  rawRows,
+  {
+    requireCoverage = true,
+    coverageAvailable = true,
+    touched = true,
+    baselineByKey = null,
+  } = {},
+) {
+  const useBaseline = !touched && baselineByKey && baselineByKey.size > 0;
+  const rows = [];
+  let skippedMethodsNoCoverage = 0;
+  let resolvedMethods = 0;
+  let totalMethods = 0;
+  for (const mr of rawRows ?? []) {
+    totalMethods += 1;
+    if (useBaseline) {
+      const base =
+        mr.coordinateSystem === COORDINATE_TRANSPILED
+          ? undefined
+          : baselineByKey.get(methodIdentityKey(mr));
+      if (base && typeof base.crap === 'number') {
+        resolvedMethods += 1;
+        rows.push({
+          ...mr,
+          coverage: null,
+          crap: base.crap,
+          resolvedFromBaseline: true,
+          coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
+        });
+        continue;
+      }
+    }
+    // Touched file, no baseline scope, or no baseline row for this method —
+    // fail closed to the standard policy rather than inventing a verdict.
+    const resolution = resolveRawRow(mr, {
+      requireCoverage,
+      coverageAvailable,
+    });
+    if (resolution.resolved) resolvedMethods += 1;
+    if (resolution.row === null) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    rows.push(resolution.row);
+  }
+  return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
+}

package/.agents/scripts/lib/crap-coordinates.js

@@ -0,0 +1,43 @@
+/**
+ * crap-coordinates.js — the CRAP kernel's two line-coordinate-system
+ * constants and the CRAP formula itself.
+ *
+ * Deliberately dependency-free (Story #4981 split, pulled out of
+ * `crap-engine.js`): both `crap-engine.js` and `crap-baseline-join.js`
+ * need these, and having either import them from the other would close a
+ * cycle. `crap-engine.js` re-exports the two constants so its existing
+ * importers (`baselines/kinds/crap.js`, `crap-utils.js`, tests) are
+ * unaffected.
+ */
+
+/**
+ * The two line coordinate systems a CRAP row's `startLine` can be expressed
+ * in (Story #4866).
+ *
+ * `original` — the coordinates of the file a reader can open, and the ones
+ * istanbul's `fnMap` is keyed against. A JavaScript source is already in this
+ * system; a TS/TSX source reaches it only through a successful sourcemap
+ * lookup.
+ *
+ * `transpiled` — escomplex's own coordinates over the emitted JavaScript,
+ * kept only when the sourcemap has no entry originating on the method's
+ * generated line. Such a row is NOT an original-source coordinate and must
+ * never be presented as one: it cannot be joined to coverage, and it cannot
+ * be compared against a baseline row carrying the other provenance.
+ */
+export const COORDINATE_ORIGINAL = 'original';
+export const COORDINATE_TRANSPILED = 'transpiled';
+
+/**
+ * CRAP formula, exported for callers that need to derive target scores or
+ * `fixGuidance` values without re-scoring source.
+ *
+ * @param {number} cyclomatic
+ * @param {number} coverage In [0, 1].
+ * @returns {number}
+ */
+export function crapFormula(cyclomatic, coverage) {
+  const c = Number(cyclomatic) || 0;
+  const cov = Math.max(0, Math.min(1, Number(coverage) || 0));
+  return c * c * (1 - cov) ** 3 + c;
+}

package/.agents/scripts/lib/crap-engine.js

@@ -1,24 +1,21 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
+// `finalizeMethodRowsWithBaseline` (Story #4981) lives in
+// crap-baseline-join.js — `resolveRawRow`, the per-row policy it shares with
+// `finalizeMethodRows` below, is imported from there so the two stay a
+// single implementation.
+import { resolveRawRow } from './crap-baseline-join.js';
+// `COORDINATE_ORIGINAL` / `COORDINATE_TRANSPILED` / `crapFormula` (Story
+// #4866 / this module's original home) now live in crap-coordinates.js —
+// re-exported here so every existing importer of this module is unaffected.
+import {
+  COORDINATE_ORIGINAL,
+  COORDINATE_TRANSPILED,
+  crapFormula,
+} from './crap-coordinates.js';
 import { deriveMethodIdentities } from './crap-method-identity.js';
 
-/**
- * The two line coordinate systems a CRAP row's `startLine` can be expressed
- * in (Story #4866).
- *
- * `original` — the coordinates of the file a reader can open, and the ones
- * istanbul's `fnMap` is keyed against. A JavaScript source is already in this
- * system; a TS/TSX source reaches it only through a successful sourcemap
- * lookup.
- *
- * `transpiled` — escomplex's own coordinates over the emitted JavaScript,
- * kept only when the sourcemap has no entry originating on the method's
- * generated line. Such a row is NOT an original-source coordinate and must
- * never be presented as one: it cannot be joined to coverage, and it cannot
- * be compared against a baseline row carrying the other provenance.
- */
-export const COORDINATE_ORIGINAL = 'original';
-export const COORDINATE_TRANSPILED = 'transpiled';
+export { COORDINATE_ORIGINAL, COORDINATE_TRANSPILED, crapFormula };
 
 /**
  * Derive the raw per-method CRAP rows from an escomplex report.
@@ -170,33 +167,25 @@ export function finalizeMethodRows(
   let totalMethods = 0;
   for (const mr of rawRows ?? []) {
     totalMethods += 1;
-    const unresolved = mr.crap === null || mr.coverage === null;
-    if (!unresolved) resolvedMethods += 1;
-    // Unjoinable is not untested (Story #4901) — see the block comment above.
-    if (
-      mr.coordinateSystem === COORDINATE_TRANSPILED ||
-      (unresolved && (requireCoverage || !coverageAvailable))
-    ) {
+    const resolution = resolveRawRow(mr, {
+      requireCoverage,
+      coverageAvailable,
+    });
+    if (resolution.resolved) resolvedMethods += 1;
+    if (resolution.row === null) {
       skippedMethodsNoCoverage += 1;
       continue;
     }
-    const coverage = unresolved ? 0 : mr.coverage;
-    const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
-    // Everything the scan decided is carried forward; this step overrides only
-    // what its own policy resolves. Spreading rather than re-listing each field
-    // is why the row's identity marker (Story #4969) and its provenance
-    // (Story #4866) survive the step without a line each to remember them —
-    // a hand-rebuilt row is how a marker silently stops reaching the baseline.
-    rows.push({
-      ...mr,
-      coverage,
-      crap,
-      coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
-    });
+    rows.push(resolution.row);
   }
   return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
 }
 
+// The incremental-mode join (Story #4981) lives in crap-baseline-join.js;
+// re-exported here so it stays reachable from the scoring kernel's existing
+// public surface.
+export { finalizeMethodRowsWithBaseline } from './crap-baseline-join.js';
+
 /**
  * Score each method in a JavaScript source for Change Risk Anti-Patterns
  * (CRAP): `c² · (1 − cov)³ + c`, where `c` is cyclomatic complexity and `cov`
@@ -243,20 +232,6 @@ export function calculateCrapForSource(
   return methodRowsFromReport(report, coverageForFile, mapLine);
 }
 
-/**
- * CRAP formula, exported for callers that need to derive target scores or
- * `fixGuidance` values without re-scoring source.
- *
- * @param {number} cyclomatic
- * @param {number} coverage In [0, 1].
- * @returns {number}
- */
-export function crapFormula(cyclomatic, coverage) {
-  const c = Number(cyclomatic) || 0;
-  const cov = Math.max(0, Math.min(1, Number(coverage) || 0));
-  return c * c * (1 - cov) ** 3 + c;
-}
-
 /**
  * Derive the deterministic single-axis fixes that would bring a method at
  * cyclomatic complexity `c` at or under the `target` CRAP score.

package/.agents/scripts/lib/crap-utils-incremental.js

@@ -0,0 +1,113 @@
+/**
+ * crap-utils-incremental.js — small pure helpers that wire the incremental
+ * CRAP join (Story #4981) into `crap-utils.js#scanAndScore`'s per-file work
+ * queue. Split into their own file so the wiring lands as new code rather
+ * than a same-file expansion of `scanAndScore` / `scoreFileSerial`.
+ */
+import { indexBaselineRowsByFile } from './crap-baseline-index.js';
+
+/**
+ * Resolve `scanAndScore`'s `incremental` option into the two lookup
+ * structures the per-file queue build needs. Both are `null` when
+ * `incremental` is absent (full-scope, the default) — every downstream
+ * consumer treats a `null` context as "not incremental".
+ *
+ * @param {{ touchedFiles?: Set<string>|string[], baselineRows?: Array<object> } | null} incremental
+ * @returns {{ touchedFiles: Set<string>|null, baselineByFile: Map<string, Map<string, object>>|null }}
+ */
+export function resolveIncrementalContext(incremental) {
+  const touchedFiles = incremental?.touchedFiles
+    ? incremental.touchedFiles instanceof Set
+      ? incremental.touchedFiles
+      : new Set(incremental.touchedFiles)
+    : null;
+  const baselineByFile = incremental
+    ? indexBaselineRowsByFile(incremental.baselineRows)
+    : null;
+  return { touchedFiles, baselineByFile };
+}
+
+/**
+ * Merge one queued file's `touched` flag and per-file `baselineByKey` map
+ * (resolved from the `resolveIncrementalContext` output) onto its base queue
+ * item. `touched` defaults to `true` (every file is "touched" outside
+ * incremental mode, matching
+ * `crap-baseline-join.js#finalizeMethodRowsWithBaseline`'s own default).
+ *
+ * @param {object} item Base queue item (`{ abs, relPath, requireCoverage, coverageAvailable }`).
+ * @param {{ touchedFiles: Set<string>|null, baselineByFile: Map<string, Map<string, object>>|null }} ctx
+ * @returns {object} `item` plus `{ touched, baselineByKey }`.
+ */
+export function resolveQueueIncrementalFields(
+  item,
+  { touchedFiles, baselineByFile },
+) {
+  const touched = touchedFiles ? touchedFiles.has(item.relPath) : true;
+  const baselineByKey = baselineByFile
+    ? (baselineByFile.get(item.relPath) ?? new Map())
+    : null;
+  return { ...item, touched, baselineByKey };
+}
+
+/**
+ * True when `scoreFileSerial` should resolve a file's methods from the
+ * baseline rather than requiring a fresh coverage entry — an untouched file
+ * with at least one indexed baseline row.
+ *
+ * @param {boolean} touched
+ * @param {Map<string, object>|null} baselineByKey
+ * @returns {boolean}
+ */
+function isIncrementalJoinActive(touched, baselineByKey) {
+  return !touched && baselineByKey != null && baselineByKey.size > 0;
+}
+
+/**
+ * `scoreFileSerial`'s file-level skip decision, factored out whole so the
+ * incremental exception lives with the rest of this Story's branching
+ * rather than inflating the cyclomatic complexity of the pre-#4981 caller.
+ *
+ * @param {boolean} requireCoverage
+ * @param {object|null} entry Istanbul coverage entry for this file.
+ * @param {boolean} touched
+ * @param {Map<string, object>|null} baselineByKey
+ * @returns {boolean}
+ */
+export function shouldSkipFileForNoCoverage(
+  requireCoverage,
+  entry,
+  touched,
+  baselineByKey,
+) {
+  return (
+    requireCoverage &&
+    entry === null &&
+    !isIncrementalJoinActive(touched, baselineByKey)
+  );
+}
+
+/**
+ * `scanAndScore`'s serial-vs-pool routing decision. Incremental mode always
+ * routes serial (see `isIncrementalJoinActive`'s doc for why the baseline
+ * lookup Maps don't cross the worker boundary); otherwise unchanged from the
+ * pre-#4981 queue-length cutover.
+ *
+ * @param {number} queueLength
+ * @param {unknown} incremental
+ * @param {number} serialThreshold
+ * @returns {boolean}
+ */
+export function shouldRunSerial(queueLength, incremental, serialThreshold) {
+  return queueLength < serialThreshold || Boolean(incremental);
+}
+
+/**
+ * Project the `resolvedFromBaseline` marker onto a `scanAndScore` result row
+ * — present only when true, so a full-scope scan's rows are unaffected.
+ *
+ * @param {{ resolvedFromBaseline?: boolean }} mr
+ * @returns {{ resolvedFromBaseline: true } | {}}
+ */
+export function resolvedFromBaselineFlag(mr) {
+  return mr.resolvedFromBaseline === true ? { resolvedFromBaseline: true } : {};
+}

package/.agents/scripts/lib/crap-utils.js

@@ -4,11 +4,19 @@ import escomplex from 'typhonjs-escomplex';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { findCoverageEntry } from './coverage-utils.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
+import { finalizeMethodRowsWithBaseline } from './crap-baseline-join.js';
 import {
   COORDINATE_ORIGINAL,
   finalizeMethodRows,
   methodRowsFromReport,
 } from './crap-engine.js';
+import {
+  resolvedFromBaselineFlag,
+  resolveIncrementalContext,
+  resolveQueueIncrementalFields,
+  shouldRunSerial,
+  shouldSkipFileForNoCoverage,
+} from './crap-utils-incremental.js';
 import { Logger } from './Logger.js';
 import { scanDirectory } from './maintainability-utils.js';
 import {
@@ -409,6 +417,10 @@ export function analyzeOnce(source, coverageForFile, mapLine = null) {
  * `regenerateMainFromTree`) SHOULD pass the MI scan's file list here so the
  * tree is walked only once per run.
  *
+ * `incremental` (Story #4981) resolves an untouched file's methods from
+ * `crap-baseline-join.js#finalizeMethodRowsWithBaseline` instead of
+ * requiring fresh coverage; omitted (the default), behaviour is unchanged.
+ *
  * @param {{
  *   targetDirs: string[],
  *   coverage: object|null,
@@ -416,6 +428,7 @@ export function analyzeOnce(source, coverageForFile, mapLine = null) {
  *   cwd?: string,
  *   scopeFiles?: Set<string>|string[]|null,
  *   preScannedFiles?: string[]|null,
+ *   incremental?: { touchedFiles: Set<string>|string[], baselineRows: Array<object> } | null,
  * }} params
  * @returns {{
  *   rows: Array<{
@@ -439,6 +452,7 @@ export async function scanAndScore({
   scopeFiles = null,
   ignoreGlobs = [],
   preScannedFiles = null,
+  incremental = null,
 }) {
   if (!Array.isArray(targetDirs)) {
     throw new TypeError('scanAndScore: targetDirs must be an array');
@@ -460,6 +474,8 @@ export async function scanAndScore({
   }
   files.sort();
 
+  const incrementalCtx = resolveIncrementalContext(incremental);
+
   // Build the work-queue first so scopeFile filtering happens before
   // any I/O / IPC. `scannedFiles` is the in-scope count.
   // Story #2079: route every relPath through path-canon so a scan from
@@ -472,14 +488,18 @@ export async function scanAndScore({
     const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
     const relPath = canonicalisePath(rawRel);
     if (scopeSet && !scopeSet.has(relPath)) continue;
-    queue.push({ abs, relPath, requireCoverage, coverageAvailable });
+    queue.push(
+      resolveQueueIncrementalFields(
+        { abs, relPath, requireCoverage, coverageAvailable },
+        incrementalCtx,
+      ),
+    );
   }
   const scannedFiles = queue.length;
 
-  const perFile =
-    queue.length < SERIAL_THRESHOLD
-      ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
-      : await scoreFilesViaPool(queue, coverage);
+  const perFile = shouldRunSerial(queue.length, incremental, SERIAL_THRESHOLD)
+    ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
+    : await scoreFilesViaPool(queue, coverage);
 
   const rows = [];
   let skippedFilesNoCoverage = 0;
@@ -516,6 +536,7 @@ export async function scanAndScore({
         coverage: mr.coverage,
         crap: mr.crap,
         coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
+        ...resolvedFromBaselineFlag(mr),
       });
     }
   }
@@ -545,11 +566,20 @@ export async function scanAndScore({
  * CRAP rows and the MI score are derived from the same escomplex report.
  */
 function scoreFileSerial(
-  { abs, relPath, requireCoverage, coverageAvailable = true },
+  {
+    abs,
+    relPath,
+    requireCoverage,
+    coverageAvailable = true,
+    touched = true,
+    baselineByKey = null,
+  },
   coverage,
 ) {
   const entry = findCoverageEntry(coverage, relPath);
-  if (requireCoverage && entry === null) {
+  if (
+    shouldSkipFileForNoCoverage(requireCoverage, entry, touched, baselineByKey)
+  ) {
     return {
       skippedFileNoCoverage: true,
       rows: [],
@@ -575,9 +605,11 @@ function scoreFileSerial(
     prepared.mapLine,
   );
   if (parseError) return dropped;
-  const finalized = finalizeMethodRows(crapRows, {
+  const finalized = finalizeMethodRowsWithBaseline(crapRows, {
     requireCoverage,
     coverageAvailable,
+    touched,
+    baselineByKey,
   });
   return {
     skippedFileNoCoverage: false,

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([]);
   }
 }