mandrel 2.56.0 → 2.58.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js

@@ -18,6 +18,9 @@
  *      maintainability rows this branch improved on files it touched, as a
  *      `baseline-refresh:` commit, so the committed baseline stops falling
  *      behind the tree in the upward direction.
+ *   3. **Context-budget write-back** (Story #5313) — persist the lower
+ *      documentation-tier totals this branch measured, so a trimmed tier's
+ *      gain locks in without `check-context-budget.js` ever going red on it.
  *
  * Extracted from `close-validation.js` when the second step landed. The phase
  * module's job is the gate chain, the evidence keyspace and the gate-log sink;
@@ -29,6 +32,7 @@
 
 import { Logger } from '../../../Logger.js';
 import { runBaselineUpwardWriteback as defaultRunBaselineUpwardWriteback } from '../../story-close/baseline-upward-writeback.js';
+import { runContextBudgetWriteback as defaultRunContextBudgetWriteback } from '../../story-close/context-budget-writeback.js';
 import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
 
 /**
@@ -69,22 +73,22 @@ function formatAutofixStep({
 }
 
 /**
- * Run the upward maintainability write-back.
+ * Run one of the two baseline write-backs and report it on one progress line.
+ *
+ * Both steps (Story #5224's maintainability rows, Story #5313's context-budget
+ * totals) take the same context and answer in the same shape — `committed`
+ * with a `sha`, or a named `reason` — so one wrapper serves both; `describe`
+ * renders the committed outcome in the step's own words.
  *
  * @param {object} ctx the shared step context (see {@link runPreGateSteps})
+ * @param {{ tag: string, run: Function, describe: (w: object) => string, noun: string }} step
  * @returns {Promise<void>}
  */
-async function baselineWritebackStep({
-  cwd,
-  worktreePath,
-  storyId,
-  baseBranch,
-  storyBranch,
-  config,
-  progress,
-  runBaselineUpwardWriteback,
-}) {
-  const writeback = await runBaselineUpwardWriteback({
+async function writebackStep(
+  { cwd, worktreePath, storyId, baseBranch, storyBranch, config, progress },
+  { tag, run, describe, noun },
+) {
+  const writeback = await run({
     cwd,
     worktreePath,
     storyId,
@@ -94,10 +98,10 @@ async function baselineWritebackStep({
     logger: Logger,
   });
   progress(
-    'BASELINE',
+    tag,
     writeback?.committed
-      ? `✅ Wrote back ${writeback.improvedPaths?.length ?? 0} improved maintainability row(s) as ${writeback.sha} on ${storyBranch}.`
-      : `⏭ No baseline write-back (${writeback?.reason ?? 'nothing to write'}).`,
+      ? `✅ ${describe(writeback)} as ${writeback.sha} on ${storyBranch}.`
+      : `⏭ No ${noun} (${writeback?.reason ?? 'nothing to write'}).`,
   );
 }
 
@@ -142,18 +146,24 @@ async function bestEffort({ tag, label, progress, run }) {
  *   progress: (tag: string, msg: string) => void,
  *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
  *   runBaselineUpwardWriteback?: typeof defaultRunBaselineUpwardWriteback,
+ *   runContextBudgetWriteback?: typeof defaultRunContextBudgetWriteback,
  * }} args
  * @returns {Promise<void>}
  */
 export async function runPreGateSteps({
   runScopedFormatAutofix = defaultRunScopedFormatAutofix,
   runBaselineUpwardWriteback = defaultRunBaselineUpwardWriteback,
+  runContextBudgetWriteback = defaultRunContextBudgetWriteback,
   ...ctx
 }) {
   const { storyBranch, progress } = ctx;
   if (!storyBranch) {
     progress('FORMAT', '⏭ Skipped scoped format-autofix (no story branch).');
     progress('BASELINE', '⏭ Skipped baseline write-back (no story branch).');
+    progress(
+      'BUDGET',
+      '⏭ Skipped context-budget write-back (no story branch).',
+    );
     return;
   }
   await bestEffort({
@@ -166,6 +176,26 @@ export async function runPreGateSteps({
     tag: 'BASELINE',
     label: 'baseline write-back',
     progress,
-    run: () => baselineWritebackStep({ ...ctx, runBaselineUpwardWriteback }),
+    run: () =>
+      writebackStep(ctx, {
+        tag: 'BASELINE',
+        run: runBaselineUpwardWriteback,
+        noun: 'baseline write-back',
+        describe: (w) =>
+          `Wrote back ${w.improvedPaths?.length ?? 0} improved maintainability row(s)`,
+      }),
+  });
+  await bestEffort({
+    tag: 'BUDGET',
+    label: 'context-budget write-back',
+    progress,
+    run: () =>
+      writebackStep(ctx, {
+        tag: 'BUDGET',
+        run: runContextBudgetWriteback,
+        noun: 'context-budget write-back',
+        describe: (w) =>
+          `Wrote back lower context-budget totals (${w.tiers?.join(', ')})`,
+      }),
   });
 }

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -7,7 +7,7 @@ import {
 import { runCloseValidation } from '../../close-validation/runner.js';
 import { getCiDelivery } from '../../config/ci.js';
 import { resolveConfig } from '../../config-resolver.js';
-import { getStoryBranch, gitSync } from '../../git-utils.js';
+import { getStoryBranch, gitSpawn, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
 import { emitTerminalFriction } from '../../observability/runtime-friction.js';
 import { emitTerseResult } from '../../observability/terse-result.js';
@@ -318,6 +318,11 @@ async function openAndReviewPr({
     prNumber,
     provider,
     runCodeReviewFn: injectedRunCodeReview ?? runCodeReviewDefault,
+    // The runner owns the git seam it hands its phases (same as `gitSync` to
+    // `pushStoryBranch`). The review needs it to resolve `origin/<base>` —
+    // the ref base-sync merged from — before it will score anything
+    // (Story #5325).
+    gitSpawnFn: gitSpawn,
     progress,
   });
   if (reviewOutcome.halted) {

package/.agents/scripts/lib/orchestration/story-close/context-budget-writeback.js

@@ -0,0 +1,213 @@
+/**
+ * context-budget-writeback.js — lock a context-budget gain in on the branch
+ * that earned it (Story #5313).
+ *
+ * `check-context-budget.js` used to fail a gated documentation tier that came
+ * in **under** its recorded total (Story #4872), so a Story that trimmed prose
+ * paid for the trim twice: once in the edit and once in the red gate whose
+ * only remedy was a hand-run `--update`. Story #5313 reverses that rule —
+ * shrinkage exits 0 and is reported — and this module answers the concern
+ * the rule existed for: a stale recorded total silently absorbs the next
+ * growth. When the tree the close is scoring measures under its recorded
+ * totals, the lower totals are written back into
+ * `baselines/context-budget.json` and folded into one `baseline-refresh:`
+ * commit on the Story branch, so the gain lands in the branch's own PR.
+ *
+ * ## Where it runs, and why not post-land
+ *
+ * The Story names the post-land tail. This step runs from the close's
+ * **pre-gate write-back seam** (`phases/pre-gate-steps.js`, beside the
+ * maintainability write-back of Story #5224) instead: the only sanctioned
+ * landing is the Story branch → PR → `main`, so a post-land write would have
+ * to commit straight to the base branch. Writing on the branch ahead of the
+ * gates keeps the row inside the PR the gates score and lets
+ * `refresh-ack.js` vouch for it through the same `baseline-refresh:` marker.
+ *
+ * Constraints, each a "must not":
+ *
+ *  1. **Only a downward move is written.** Growth past tolerance and an
+ *     unbacked recorded row must still fail `check-context-budget.js` exactly
+ *     as before; when either is present this step skips and the gate speaks.
+ *  2. **Idempotent and silent.** No shrink, no write, no commit.
+ *  3. **Never fails the close.** Every failure is a named skip.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  DEFAULT_TOLERANCE_BYTES,
+  buildBaseline as defaultBuildBaseline,
+  diffBudget as defaultDiffBudget,
+  loadBaseline as defaultLoadBaseline,
+} from '../../../check-context-budget.js';
+import { resolveDocTiers as defaultResolveDocTiers } from '../../doc-tiers.js';
+import { gitSync as defaultGitSync } from '../../git-utils.js';
+import { Logger as DefaultLogger } from '../../Logger.js';
+
+const TAG = '[context-budget-writeback]';
+
+/** Repo-relative location of the committed budget. */
+const BASELINE_REL_PATH = 'baselines/context-budget.json';
+
+/**
+ * Build the commit subject — conventional, carrying the `baseline-refresh:`
+ * marker `refresh-ack.js` recognises, fixed-length but for the Story id.
+ *
+ * @param {number|string} storyId
+ * @returns {string}
+ */
+function buildCommitSubject(storyId) {
+  return `chore(baselines): baseline-refresh: lower context-budget totals (story #${storyId})`;
+}
+
+/**
+ * One line per tier that moved down, before → after.
+ *
+ * @param {Array<{ tier: string, current: number, baseline: number }>} shrunk
+ * @returns {string}
+ */
+function buildCommitBody(shrunk) {
+  return [
+    'Documentation tiers this branch trimmed under their recorded totals,',
+    'written back so the budget stops holding slack the tree no longer',
+    'spends. Growth and unbacked rows are never rewritten here.',
+    '',
+    ...shrunk.map((s) => `- ${s.tier}: ${s.baseline} -> ${s.current} bytes`),
+  ].join('\n');
+}
+
+/**
+ * Report a no-op by name.
+ *
+ * @param {object} logger
+ * @param {string} reason
+ */
+function skip(logger, reason) {
+  logger.info?.(`${TAG} no write-back (${reason}).`);
+  return { ran: false, committed: false, reason };
+}
+
+/**
+ * Everything that must hold before a write. Returns a skip reason or `null`.
+ *
+ * @param {{ workTree: string, storyBranch: string, git: Function, relPath: string }} ctx
+ * @returns {string|null}
+ */
+function precheck({ workTree, storyBranch, git, relPath }) {
+  const onBranch = git(['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: workTree,
+  });
+  if (onBranch !== storyBranch) return 'wrong-branch';
+  const status = git(['status', '--porcelain', '--', relPath], {
+    cwd: workTree,
+  });
+  if (status.length > 0) return 'dirty-tree';
+  return null;
+}
+
+/**
+ * Write the envelope and fold it into one commit. On a rejected commit the
+ * file is restored so the gates score the tree the close found.
+ *
+ * @param {{ workTree: string, git: Function, relPath: string, envelope: object, storyId: number|string, shrunk: object[] }} args
+ * @returns {{ sha: string }}
+ */
+function commitBaseline({ workTree, git, relPath, envelope, storyId, shrunk }) {
+  fs.writeFileSync(
+    path.join(workTree, relPath),
+    `${JSON.stringify(envelope, null, 2)}\n`,
+  );
+  git(['add', '--', relPath], { cwd: workTree });
+  try {
+    git(
+      [
+        'commit',
+        '-m',
+        buildCommitSubject(storyId),
+        '-m',
+        buildCommitBody(shrunk),
+      ],
+      { cwd: workTree },
+    );
+  } catch (err) {
+    git(['restore', '--staged', '--worktree', '--', relPath], {
+      cwd: workTree,
+    });
+    throw err;
+  }
+  return { sha: git(['rev-parse', '--short', 'HEAD'], { cwd: workTree }) };
+}
+
+/**
+ * Write the lower context-budget totals back on the Story branch.
+ *
+ * Total: a throw anywhere is a named skip, never a failed close.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath?: string|null,
+ *   storyId: number|string,
+ *   storyBranch?: string,
+ *   config: object,
+ *   logger?: object,
+ *   gitSync?: (cwd: string, ...args: string[]) => string,
+ *   resolveDocTiersImpl?: typeof defaultResolveDocTiers,
+ *   loadBaselineImpl?: typeof defaultLoadBaseline,
+ *   diffBudgetImpl?: typeof defaultDiffBudget,
+ *   buildBaselineImpl?: typeof defaultBuildBaseline,
+ * }} opts
+ * @returns {{ ran: boolean, committed: boolean, sha?: string, tiers?: string[], reason?: string }}
+ */
+export function runContextBudgetWriteback({
+  cwd,
+  worktreePath,
+  storyId,
+  storyBranch,
+  config,
+  logger = DefaultLogger,
+  gitSync = defaultGitSync,
+  resolveDocTiersImpl = defaultResolveDocTiers,
+  loadBaselineImpl = defaultLoadBaseline,
+  diffBudgetImpl = defaultDiffBudget,
+  buildBaselineImpl = defaultBuildBaseline,
+} = {}) {
+  if (!cwd || !storyBranch) return skip(logger, 'missing-context');
+  const workTree = worktreePath || cwd;
+  const git = (args, opts = {}) => gitSync(opts.cwd ?? workTree, ...args);
+  try {
+    const blocked = precheck({
+      workTree,
+      storyBranch,
+      git,
+      relPath: BASELINE_REL_PATH,
+    });
+    if (blocked) return skip(logger, blocked);
+    const baseline = loadBaselineImpl(path.join(workTree, BASELINE_REL_PATH));
+    if (!baseline) return skip(logger, 'no-baseline');
+    const tierMap = resolveDocTiersImpl(config, { root: workTree });
+    const diff = diffBudgetImpl(tierMap, baseline);
+    if (diff.grown.length > 0 || diff.absent.length > 0) {
+      return skip(logger, 'drift-not-downward');
+    }
+    if (diff.shrunk.length === 0) return skip(logger, 'no-shrink');
+    const tolerance = Number.isFinite(baseline.toleranceBytes)
+      ? baseline.toleranceBytes
+      : DEFAULT_TOLERANCE_BYTES;
+    const { sha } = commitBaseline({
+      workTree,
+      git,
+      relPath: BASELINE_REL_PATH,
+      envelope: buildBaselineImpl(tierMap, tolerance),
+      storyId,
+      shrunk: diff.shrunk,
+    });
+    const tiers = diff.shrunk.map((s) => s.tier);
+    logger.warn?.(
+      `${TAG} wrote back lower totals for ${tiers.join(', ')} on story #${storyId}; committed as ${sha}.`,
+    );
+    return { ran: true, committed: true, sha, tiers };
+  } catch (err) {
+    return skip(logger, `failed: ${err?.message ?? err}`);
+  }
+}

package/.agents/scripts/lib/orchestration/task-body-validator.js

@@ -10,9 +10,8 @@
  * object. To make the rules below actually fire on canonical plans, a string
  * body is **parsed** back into its structured form via `parseStoryBody`
  * before the section checks run (Story #3906 — previously the validator
- * `shouldSkipTicket`-skipped every string body, so the verify-tier suffix
- * rule, vague-verb check, and non-empty-goal check never ran on any real
- * decomposition). A still-structured object body (e.g. a caller that passes
+ * `shouldSkipTicket`-skipped every string body, so the vague-verb check and
+ * non-empty-goal check never ran on any real decomposition). A still-structured object body (e.g. a caller that passes
  * the pre-serialize shape directly) is validated as-is.
  *
  * Only `type: 'story'` tickets are validated; Feature/Epic tickets and
@@ -42,44 +41,23 @@
  * array uses the same object shape and is the home for paths the Story
  * reads but does not modify (test fixtures, sibling modules, etc.).
  *
- * `body.verify` entries must either name a testing tier in parentheses
- * drawn from `VERIFY_TIER_VALUES` (e.g. `npm run test (unit)`) or be the
- * literal `manual:<reason>` escape hatch when the Story is genuinely
- * unverifiable in isolation. `verify-tier-repair.js#normalizeVerifyTiers` runs
- * first on the persist path (Story #5005) and **repairs** the entries whose
- * tier `suggestVerifyFix` can infer, so the hard error below is reserved for
- * the entries only the author can resolve.
+ * `body.verify` entries are commands, nothing more: Story #5312 deleted the
+ * `(<tier>)` suffix, the `manual:<reason>` escape and the repair pass that
+ * appended the suffix for the author. The only verify rule left is that the
+ * list is non-empty.
  *
  * The errors are batched and surfaced as a single thrown Error so the
  * planner can see every offending slug in one pass instead of fixing one
  * at a time.
  */
 
-import {
-  suggestPathEntryFix,
-  suggestVerifyFix,
-} from '../story-body/body-format-lints.js';
+import { suggestPathEntryFix } from '../story-body/body-format-lints.js';
 import {
   parse as parseStoryBody,
   StoryBodyParseError,
 } from '../story-body/story-body.js';
 import { FILE_ASSUMPTION_VALUES } from './file-assumption-enum.js';
 
-/**
- * Canonical testing-tier labels that a `verify[]` entry must name (in
- * parentheses) to pass plan-time validation. Mirrors the verify-rules contract
- * in `.agents/scripts/lib/templates/decomposer-prompts.js`.
- *
- * Entries that do not end with `(<tier>)` and are not `manual:<reason>` are
- * rejected by `collectVerifyErrors`.
- */
-export const VERIFY_TIER_VALUES = Object.freeze([
-  'unit',
-  'contract',
-  'e2e',
-  'validate',
-]);
-
 /**
  * Predicate: should the validator skip this ticket entirely? Skip when:
  *   - it is not a Story (only `type: 'story'` tickets are validated here),
@@ -91,7 +69,7 @@ export const VERIFY_TIER_VALUES = Object.freeze([
  * Story body to a markdown string, so a *string* body is NOT skipped here
  * (Story #3906) — `validateTaskBodyShape` parses it back into structured
  * form via `parseStoryBody` before applying the section rules. This is what
- * makes the verify-tier / vague-verb / non-empty-goal checks actually fire
+ * makes the non-empty-verify / vague-verb / non-empty-goal checks actually fire
  * on real plans. Features (and everything else) use narrative string bodies
  * and are skipped by the `type !== 'story'` guard.
  *
@@ -207,7 +185,6 @@ export function validateTaskBodyShape(ticket) {
   }
   errors.push(...collectChangesErrors(prefix, body.changes));
   errors.push(...collectAcceptanceErrors(prefix, body.acceptance));
-  // Tier-suffix validation is always enforced on Story bodies (2-tier world).
   errors.push(...collectVerifyErrors(prefix, body.verify));
   errors.push(...collectReferencesErrors(prefix, body.references));
   return errors;
@@ -324,15 +301,6 @@ function collectAcceptanceErrors(prefix, rawAcceptance) {
   return [];
 }
 
-/**
- * Regex that matches a valid tier suffix at the end of a verify entry:
- * a parenthesised word drawn from `VERIFY_TIER_VALUES` (e.g. `(unit)`).
- * Whitespace before the opening paren is tolerated.
- */
-const VERIFY_TIER_RE = new RegExp(
-  `\\((?:${VERIFY_TIER_VALUES.join('|')})\\)\\s*$`,
-);
-
 /**
  * @param {string} prefix
  * @param {unknown} rawVerify
@@ -342,31 +310,10 @@ function collectVerifyErrors(prefix, rawVerify) {
   const verify = Array.isArray(rawVerify) ? rawVerify : [];
   if (verify.length === 0) {
     return [
-      `${prefix}: verify must list at least one entry — author it at the ticket's top level (preferred) or in the body's ## Verify section. Use "manual:<reason>" only when truly unverifiable in isolation.`,
+      `${prefix}: verify must list at least one entry — author it at the ticket's top level (preferred) or in the body's ## Verify section.`,
     ];
   }
-  const errors = [];
-  for (const v of verify) {
-    if (typeof v !== 'string') continue;
-    if (v.startsWith('manual:')) {
-      const reason = v.slice('manual:'.length).trim();
-      if (reason === '') {
-        errors.push(
-          `${prefix}: body.verify "manual:" entry has no reason after the colon.`,
-        );
-      }
-      // manual: entries are exempt from the tier-suffix check.
-      continue;
-    }
-    if (!VERIFY_TIER_RE.test(v)) {
-      const fix = suggestVerifyFix(v);
-      const fixIt = fix === null ? '' : ` Suggested fix: "${fix}".`;
-      errors.push(
-        `${prefix}: body.verify entry must end with a tier in parentheses — one of (${VERIFY_TIER_VALUES.join('|')}). Got: "${v}".${fixIt}`,
-      );
-    }
-  }
-  return errors;
+  return [];
 }
 
 /**