mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/single-story-lease-guard.js

@@ -1,40 +1,7 @@
 /**
- * single-story-lease-guard.js — wire the assignee-as-lease primitive
- * (`ticket-lease.js`, Story #3480) into the standalone `/single-story-deliver`
- * path (Story #3483, Epic #3457).
- *
- * The standalone workflow has no Epic-scoped dispatch manifest to serialise
- * two operators driving the same Story, so a concurrent `single-story-init`
- * could happily clobber another operator's in-flight run. This guard closes
- * that gap by taking an exclusive, time-bounded lease on the Story ticket at
- * init and clearing it at close:
- *
- *   - `acquireStoryLease` — claim the Story for the resolved operator. A live
- *     **foreign** claim (the assignee is someone else and their heartbeat is
- *     within the TTL) is fatal: the guard throws a message naming the current
- *     owner so the operator knows who to coordinate with. Unclaimed,
- *     self-held, and stale-foreign claims all proceed (the primitive reclaims
- *     stale claims automatically).
- *   - `releaseStoryLease` — clear the Story assignment on a clean close, but
- *     only when the operator still holds it (the primitive no-ops a stale
- *     release so a late close never yanks a claim back from whoever took
- *     over).
- *
- * The guard is deliberately thin and provider-agnostic: it resolves the
- * operator handle from config and delegates assignee mutation to the pure
- * `ticket-lease.js` primitive.
- *
- * **Fail-closed (audit #3513, hard-wired by Story #5006).** The lease
- * primitive used to reclaim a foreign claim whose heartbeat was older than a
- * TTL — and with no heartbeat source, *every* foreign claim looked stale, so
- * the guard silently reclaimed any foreign assignee and was inert as a
- * concurrency guard. The guard worked around that by anchoring the heartbeat
- * to `now`; Story #5006 deleted the TTL outright, so the fail-closed
- * behaviour is now the primitive's own: a foreign assignee refuses the take
- * (naming the current owner) unless the operator passes `--steal` to forcibly
- * transfer it. A genuinely abandoned claim is cleared by hand (or `--steal`)
- * rather than raced into automatically. Unclaimed and self-held tickets still
- * proceed.
+ * Story lease for single-Story delivery: take the assignee lease at init,
+ * clear it at close, so two runs never drive one Story. Fail-closed — a
+ * foreign assignee refuses unless `--steal`.
  */
 
 import {
@@ -44,21 +11,11 @@ import {
 import { releaseLease } from './ticket-lease.js';
 
 /**
- * Resolve the operator handle used as the lease owner from resolved config.
- * Routes through the shared lease-guard kernel
- * (`lease-guard-shared.resolveOperatorFromCandidates`) so a leading `@` is
- * stripped (the assignees API expects bare logins, not `@`-prefixed mentions)
- * and the self-held-claim comparison matches. The standalone surface's
- * missing-handle policy is `'throw'` (intentional divergence from the plan
- * path's `'null'`): init has no best-effort leg that can degrade, so an
- * unowned lease must refuse immediately.
+ * Missing-handle policy is `'throw'`: init has no best-effort leg to degrade.
  *
- * @param {object} config Resolved `.agentrc.json` config.
+ * @param {object} config
  * @returns {string} Bare operator handle.
- * @throws {Error} When no `github.operatorHandle` resolves — unset, or still the
- *   shipped `@[USERNAME]` placeholder (both normalise to `null`). Without an
- *   operator identity the lease has no owner to record, so the standalone
- *   path cannot safely serialise concurrent runs.
+ * @throws {Error} When `github.operatorHandle` is unset or the placeholder.
  */
 export function resolveOperator(config) {
   return resolveOperatorFromCandidates({
@@ -74,19 +31,12 @@ export function resolveOperator(config) {
 }
 
 /**
- * Acquire (or re-affirm) the Story lease for the standalone path.
- *
- * **Fail-closed:** a foreign assignee refuses the take — the guard throws
- * naming the current owner so the operator can coordinate. Pass
- * `steal: true` (`--steal`) to forcibly transfer it. Unclaimed and self-held
- * tickets proceed without a write.
- *
  * @param {object} opts
- * @param {object} opts.provider           Ticketing provider (getTicket/updateTicket).
- * @param {number} opts.storyId            Story ticket to claim.
- * @param {object} opts.config             Resolved config (operator handle).
- * @param {string} [opts.operator]         Override the resolved operator (tests).
- * @param {boolean} [opts.steal=false]     Forcibly transfer a foreign claim.
+ * @param {object} opts.provider
+ * @param {number} opts.storyId
+ * @param {object} opts.config
+ * @param {string} [opts.operator]         Test override.
+ * @param {boolean} [opts.steal=false]
  * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
  * @throws {Error} When a foreign claim refuses the acquire (no `steal`).
  */
@@ -113,15 +63,11 @@ export async function acquireStoryLease({
 }
 
 /**
- * Release the Story lease on a clean close. No-ops (via the primitive) when
- * the operator no longer holds the claim, so a late close never steals a
- * claim back from whoever legitimately took over.
- *
  * @param {object} opts
- * @param {object} opts.provider    Ticketing provider.
- * @param {number} opts.storyId     Story ticket to release.
- * @param {object} opts.config      Resolved config (operator handle).
- * @param {string} [opts.operator]  Override the resolved operator (tests).
+ * @param {object} opts.provider
+ * @param {number} opts.storyId
+ * @param {object} opts.config
+ * @param {string} [opts.operator]  Test override.
  * @returns {Promise<{ released: boolean, owner: string|null, reason: string }>}
  */
 export async function releaseStoryLease({

package/.agents/scripts/lib/orchestration/story-body-gate.js

@@ -1,11 +1,6 @@
 /**
- * lib/orchestration/story-body-gate.js — the Story-body parse gate
- * (Story #4541), extracted from `ticket-validator.js`: the one place a
- * serialized Story body is parsed with parse failures translated into the
- * validator's operator-legible `ValidationError` shape. Both the gate that
- * refuses a plan up front (`assertStoryBodiesParse`) and the per-call
- * translating parser (`parseStoryBodyOrThrow`) the downstream validators
- * lean on live here.
+ * The one place a Story body is parsed with failures translated into a
+ * `ValidationError` naming the section and entry.
  */
 
 import { ValidationError } from '../errors/index.js';
@@ -15,16 +10,6 @@ import {
 } from '../story-body/story-body.js';
 
 /**
- * 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'`.
@@ -53,14 +38,10 @@ export function parseStoryBodyOrThrow(story) {
 }
 
 /**
- * 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.
+ * Must run before the git-probe gates, whose whitelist is the parsed body.
  *
  * @param {{ tickets: object[] }} opts
- * @throws {ValidationError} `code: 'story-body-unparseable'` on the first
- *   offending Story.
+ * @throws {ValidationError} On the first offending Story.
  */
 export function assertStoryBodiesParse({ tickets }) {
   for (const story of (tickets ?? []).filter((t) => t.type === 'story')) {

package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js

@@ -1,50 +1,17 @@
 /**
  * baseline-upward-writeback.js — persist improved maintainability rows on the
- * branch that earned them (Story #5224).
+ * branch that earned them, as one `baseline-refresh:` commit ahead of the
+ * close gates. The diff-scoped ratchet only reds on regressions, so nothing
+ * else writes an improvement back.
  *
- * The diff-scoped baseline ratchet only ever reds on a REGRESSION. A branch
- * that *improves* a file it touched is therefore waved through with its
- * committed row left describing the worse, older tree — and nothing on the
- * per-PR path ever writes it back. The only thing that notices is the nightly
- * full-scope re-score (`check-baseline-drift.js`), which had filed the same
- * one-command chore seven times before this module existed.
- *
- * The classifier already does the hard half: `kinds/kind-factory.js#classify`
- * partitions every compared row into `regressions` / `improvements` /
- * `unchanged` / `additions`, and the enforcement path forwards `improvements`
- * all the way to the report. Nothing persisted it. This module is that
- * missing half — run from the close's `close-validation` phase, ahead of the
- * gate chain, so the refreshed row lands in the branch's own PR.
- *
- * Shape borrowed from {@link ../story-close/format-autofix.js#runScopedFormatAutofix}:
- * scope to the branch's changed-file set, fold the writes into one dedicated
- * commit ahead of the gates, log the paths touched, and inject every
- * git / baseline / scoring collaborator so the unit tests never spawn git
- * (`.agents/rules/test-seams.md`).
- *
- * Four constraints bind the design, and every one of them is a "must not":
- *
- *  1. **Only `improvements` are written.** A regression must still fail the
- *     gate exactly as it does today. A write-back that could launder one
- *     makes the baseline actively worse than leaving it stale, so a regressed
- *     row is never in the written set — it is not filtered out downstream, it
- *     never enters.
- *  2. **`maintainability` only.** CRAP's drift identity is
- *     `path::method@startLine`, which re-keys whenever anything above a
- *     method moves, so the same treatment there is churn rather than signal.
- *     That is exactly why the nightly watches maintainability alone.
- *  3. **Changed files only — never a full-scope regeneration.** A full-scope
- *     write at land time would absorb unrelated drift from other branches
- *     into whichever PR happened to land next, and would fight the
- *     row-identity merge driver that exists to keep concurrent refreshes
- *     apart (Story #5215).
- *  4. **Idempotent and silent.** No empty commit; a second close over the
- *     same tree finds nothing left to improve and commits nothing.
- *
- * The authored commit carries the `baseline-refresh:` marker
- * `phases/refresh-ack.js` recognises, so the refreshed rows are vouched for
- * rather than read as fresh drift, and its subject is conventional so
- * commitlint accepts it.
+ * Invariants:
+ *  1. Only classifier `improvements` are written — a regression never enters
+ *     the written set, so it still fails the gate.
+ *  2. Maintainability only: CRAP rows re-key on `method@startLine` when code
+ *     above moves, so write-back there is churn.
+ *  3. Changed files only — a full-scope write would absorb other branches'
+ *     drift into whichever PR lands next.
+ *  4. Idempotent: no empty commit.
  */
 
 import path from 'node:path';
@@ -72,25 +39,16 @@ import {
 
 const TAG = '[baseline-writeback]';
 
-/** The one kind this module touches. See constraint 2 in the preamble. */
 const KIND = 'maintainability';
 
-/**
- * Absolute drift tolerance when the gate configures none. Mirrors
- * `drift-detector.js`'s `KIND_SPECS.maintainability.defaultTolerance`, so the
- * per-PR write-back and the nightly full-scope check agree on what counts as
- * movement rather than float noise.
- */
+/** Matches the drift detector's maintainability default tolerance. */
 const DEFAULT_TOLERANCE = 0.5;
 
-/** Files the maintainability scorer can measure at all. */
 const SCORABLE = /\.(?:m?[jt]sx?)$/i;
 
 /**
- * Reasons reported before the step scored anything, so `ran: false` means
- * exactly "a guard stopped this before any work happened" rather than the
- * softer "nothing came of it". `no-scored-rows`, `no-improvements` and
- * `unchanged` are deliberately absent: those are outcomes of a run.
+ * Skips that fire before any scoring, so `ran: false` means exactly "a guard
+ * stopped this"; outcome reasons are deliberately absent.
  */
 const GUARD_REASONS = new Set([
   'gate-disabled',
@@ -102,10 +60,7 @@ const GUARD_REASONS = new Set([
 ]);
 
 /**
- * Resolve the gate's absolute tolerance. Anything below it is float noise the
- * ratchet already refuses to red on, so writing it back would be churn — and
- * churn on a file every concurrent branch also touches is the one cost this
- * step must not add.
+ * Deltas under the tolerance are float noise; writing them is churn.
  *
  * @param {object|undefined} gate resolved `delivery.quality.gates.maintainability`
  * @returns {number}
@@ -120,17 +75,9 @@ function resolveTolerance(gate) {
 }
 
 /**
- * Read the maintainability gate block as DECLARED — `quality.gates[kind]`, not
- * the sibling `quality[kind]` projection. The two differ in exactly the two
- * fields this module reads: the projection drops `enabled` entirely and
- * flattens `tolerance` to a bare number, so reading it would silently make the
- * gate un-disablable and every configured tolerance unreadable. `evaluate.js`
- * receives this same declared block as its `gateBlock`, which is what keeps
- * the write-back's notion of "moved" identical to the gate's.
- *
- * Tolerates a resolver that throws (a malformed config under a tmp cwd). An
- * unresolvable config reads as "framework defaults", which enable the gate —
- * the same reading `projections/advisories.js#isEnabled` applies.
+ * Read the DECLARED `quality.gates[kind]` block, not the `quality[kind]`
+ * projection, which drops `enabled` and flattens `tolerance`. A resolver that
+ * throws reads as framework defaults (gate enabled).
  *
  * @param {object|undefined} config
  * @returns {object|undefined}
@@ -144,10 +91,8 @@ function resolveGate(config) {
 }
 
 /**
- * Normalise scorer output into the on-disk row shape so scored rows and
- * committed rows are directly comparable. `projectRow` is the same projection
- * the writer applies, which is what makes the two sides comparable at all.
- * A row the writer itself would refuse is dropped rather than compared.
+ * Project scorer output through the writer's own `projectRow` so scored and
+ * committed rows are comparable; unprojectable rows are dropped.
  *
  * @param {Array<object>} rows
  * @returns {Array<{ path: string, mi: number }>}
@@ -166,24 +111,10 @@ function projectRows(rows) {
 }
 
 /**
- * Select the rows this branch has genuinely improved.
- *
- * The base side is deliberately narrowed to the rows the head side actually
- * scored. `compare()` classifies a base row with no head row through the
- * kind's `removedRowPolicy`, which for maintainability pushes an
- * **improvement** ("the file is gone, so its debt is gone too"). That policy
- * is correct for a full-scope compare and catastrophic for a scoped one: every
- * untouched file in the repo would arrive here as an improvement and be
- * rewritten from a score nobody computed. Narrowing the base to the scored
- * keys means every comparison has both sides, so the removed-row arm cannot
- * fire at all — and the `head === null` guard below makes that structural
- * rather than incidental.
- *
- * `additions` — a scored file with no committed row — is likewise excluded:
- * constraint 1 admits only what the classifier calls an improvement, and a new
- * file's row is the ordinary refresh path's business, not this step's.
- *
- * Pure.
+ * The base side is narrowed to scored paths: maintainability's
+ * `removedRowPolicy` counts a missing head row as an improvement, which in a
+ * scoped compare would rewrite every untouched file. `additions` are excluded
+ * too. Pure.
  *
  * @param {{ scoredRows: Array<object>, baselineRows: Array<object>, tolerance: number }} opts
  * @returns {Array<{ path: string, mi: number }>} the head rows to persist
@@ -211,10 +142,8 @@ function selectImprovedRows({ scoredRows, baselineRows, tolerance }) {
 }
 
 /**
- * Render the commit body: one line per rewritten row, before → after. The body
- * is the durable record of what the step touched — the `Logger` line scrolls
- * out of a close transcript, this does not — and `check-baseline-drift.js`'s
- * remedy text asks a `baseline-refresh:` commit to carry a non-empty body.
+ * One before → after line per row: the durable record of what was touched
+ * (a `baseline-refresh:` commit must carry a non-empty body).
  *
  * @param {Array<{ path: string, mi: number }>} improved
  * @param {Array<object>} baselineRows
@@ -238,11 +167,9 @@ function buildCommitBody(improved, baselineRows) {
 }
 
 /**
- * Build the commit subject. Conventional (`chore(baselines): …`) so commitlint
- * accepts it, carrying the `baseline-refresh:` marker as a plain substring so
- * `refresh-ack.js#resolveRefreshTrigger` recognises it, and fixed-length in
- * everything but the Story id so it cannot drift past commitlint's 100-char
- * subject cap.
+ * Conventional for commitlint, carrying the `baseline-refresh:` marker that
+ * `refresh-ack.js` recognises, and fixed-length apart from the id so it stays
+ * under the 100-char cap.
  *
  * @param {number|string} storyId
  * @returns {string}
@@ -252,14 +179,8 @@ function buildCommitSubject(storyId) {
 }
 
 /**
- * Stage the single baseline file and commit it. Hooks must run; never pass
- * `--no-verify` (project policy).
- *
- * On a commit failure the written file is restored, because everything
- * downstream — base-sync, the push, the gate chain's own reads — assumes the
- * close left the worktree clean. A half-applied write-back that survives as an
- * uncommitted edit would silently change what the gates score without ever
- * reaching the PR.
+ * Stage and commit the baseline file with hooks enabled. On a rejected commit
+ * the file is reset to HEAD so the close leaves a clean tree.
  *
  * @param {{ cwd: string, git: Function, relPath: string, subject: string, body: string }} opts
  * @returns {{ sha: string }}
@@ -272,13 +193,8 @@ function commitBaseline({ cwd, git, relPath, subject, body }) {
       stdio: ['ignore', 'pipe', 'pipe'],
     });
   } catch (err) {
-    // `git checkout -- <path>` restores the WORKTREE from the index — and the
-    // index is exactly what the `git add` above just overwrote, so on a
-    // rejected commit it restored the file to the value it was meant to be
-    // rolled back FROM. The rollback was a no-op that looked like one, and the
-    // rewritten row survived as a staged edit into whatever the gates scored
-    // next. `restore --staged --worktree` resets both to HEAD, which is what
-    // "leave the tree as the close found it" actually means.
+    // `checkout --` would restore from the index `git add` just overwrote —
+    // a silent no-op. Reset both index and worktree to HEAD.
     git(['restore', '--staged', '--worktree', '--', relPath], {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -294,22 +210,11 @@ function commitBaseline({ cwd, git, relPath, subject, body }) {
 }
 
 /**
- * Everything that must hold before the step is allowed to score anything.
- * Returns a skip reason, or `null` to proceed.
- *
- * The branch assertion runs here — before the write, not before the commit —
- * so a mis-wired `worktreePath` can never leave a modified baseline in a tree
- * whose history we then refuse to touch.
- *
- * The dirty-tree guard is the same refusal `runScopedFormatAutofix` makes and
- * for the same reason, sharpened to one path: this step's only write target is
- * the baseline file, and it commits that file by name. An uncommitted edit
- * sitting on it — a hand-run `maintainability:reanchor`, a half-resolved merge,
- * an operator mid-edit — would be swept into a `baseline-refresh:` commit
- * authored by close and attributed to rows this branch improved. That commit is
- * the one `refresh-ack.js` VOUCHES for, so an absorbed edit is not merely
- * unrelated: it arrives pre-acknowledged, which is the precise laundering this
- * whole Story exists to close.
+ * Guards that must hold before scoring; returns a skip reason or `null`.
+ * The branch check runs before any write. The dirty-tree check refuses an
+ * uncommitted edit on the baseline file, which would otherwise be swept into
+ * a `baseline-refresh:` commit that `refresh-ack.js` vouches for — i.e.
+ * laundered.
  *
  * @param {{ gate: object|undefined, workTree: string, storyBranch: string, git: Function, changed: string[], relPath: string }} ctx
  * @returns {string|null}
@@ -324,11 +229,7 @@ function precheck({ gate, workTree, storyBranch, git, changed, relPath }) {
 }
 
 /**
- * Is the baseline file already modified in the worktree or the index?
- *
- * Fails CLOSED on an unreadable status: a step that cannot tell whether it is
- * about to absorb someone else's edit must not proceed, and skipping costs
- * only a stale upward row that the nightly full-scope re-score still catches.
+ * Fails CLOSED on unreadable status; skipping only costs a stale upward row.
  *
  * @param {{ workTree: string, git: Function, relPath: string }} ctx
  * @returns {boolean}
@@ -342,16 +243,8 @@ function isDirty({ workTree, git, relPath }) {
 }
 
 /**
- * The ref the branch's changed-file set is measured against.
- *
- * `origin/<baseBranch>` when the remote-tracking ref exists, the local branch
- * otherwise. A local `main` in a long-lived checkout — and in every Story
- * worktree, which is seeded once and never pulled again — drifts behind the
- * remote, and a stale base widens the three-dot range to include commits that
- * landed on the base after the branch forked. Every file in that widening is
- * then scored and written back by whichever Story happens to close next, which
- * is precisely the "absorb unrelated drift into the next PR" failure
- * constraint 3 in the preamble forbids.
+ * Prefer `origin/<base>`: a stale local base (worktrees never pull it) widens
+ * the three-dot range to files landed after the fork, violating invariant 3.
  *
  * @param {{ workTree: string, git: Function, baseBranch: string }} ctx
  * @returns {string}
@@ -373,14 +266,9 @@ function resolveScopeBase({ workTree, git, baseBranch }) {
 }
 
 /**
- * Persist improved maintainability rows for the files this branch changed, and
- * fold them into one `baseline-refresh:` commit on the Story branch.
- *
- * Every no-op is reported by name rather than silently: `gate-disabled`,
- * `no-changed-files`, `wrong-branch`, `dirty-tree`, `no-baseline`,
- * `no-scored-rows`, `no-improvements`, `unchanged`. The caller logs the reason and proceeds —
- * this step is never allowed to fail a close, because `check-baselines` is
- * still the gate and this is only the refresh half of the loop.
+ * Persist improved rows for the branch's changed files as one commit. Every
+ * no-op returns a named `reason`; this step never fails a close —
+ * `check-baselines` remains the gate.
  *
  * @param {{
  *   cwd: string,
@@ -425,12 +313,8 @@ export async function runBaselineUpwardWriteback({
     throw new Error('runBaselineUpwardWriteback: storyBranch is required');
 
   const workTree = worktreePath || cwd;
-  // The two format-autofix helpers below take git as `(args, opts) => stdout`;
-  // `git-utils.gitSync` is `(cwd, ...args) => trimmed stdout` and throws on a
-  // non-zero exit. Adapt rather than reach for `node:child_process` directly —
-  // the shared surface owns the stdout ceiling, `shell: false` and error
-  // normalisation, and `tests/enforcement/child-process-imports.test.js`
-  // enforces that.
+  // Adapt `gitSync(cwd, ...args)` to the `(args, opts)` shape format-autofix
+  // expects; direct `node:child_process` use is forbidden by an enforcement test.
   const git = (args, opts = {}) => gitSync(opts.cwd ?? workTree, ...args);
   const gate = resolveGate(config);
 
@@ -487,11 +371,9 @@ export async function runBaselineUpwardWriteback({
 }
 
 /**
- * Write the selected rows through the one sanctioned write funnel and commit
- * them. The already-computed rows are handed to `refreshBaseline` as its
- * scorer so the files are scored exactly once — the service still owns path
- * canonicalization, `mergeRows` (which preserves every out-of-scope row
- * byte-for-byte), rollup, envelope stamping and the atomic write.
+ * Write through `refreshBaseline` (which owns canonicalization, out-of-scope
+ * row preservation and the atomic write), passing the computed rows as its
+ * scorer so files are scored once, then commit.
  *
  * @returns {Promise<{ ran: boolean, committed: boolean, sha?: string, improvedPaths?: string[], reason?: string }>}
  */
@@ -514,9 +396,6 @@ async function persist({
     scopeFiles: improvedPaths,
     scorer: () => improved,
   });
-  // The writer short-circuits on structural equality, so `wrote: false` means
-  // the committed rows already carried these values — nothing to commit, and
-  // nothing worth a log line above debug.
   if (!wrote) return skip(logger, 'unchanged');
 
   const { sha } = commitBaseline({
@@ -535,9 +414,6 @@ async function persist({
 }
 
 /**
- * Report a no-op by name. Every skip is `info`-level: none of them is a
- * problem, and the close transcript already carries one line per phase.
- *
  * @param {object} logger
  * @param {string} reason
  */
@@ -546,11 +422,7 @@ function skip(logger, reason) {
   return { ran: !GUARD_REASONS.has(reason), committed: false, reason };
 }
 
-/**
- * Default committed-row loader — the schema-validating reader, so a baseline
- * this module would refuse to compare against is reported as `no-baseline`
- * rather than half-read.
- */
+/** Schema-validating read; an unreadable baseline reports `no-baseline`. */
 function defaultLoadBaselineRows({ cwd }) {
   try {
     return loadBaselineEnvelope(KIND, { cwd })?.rows ?? null;
@@ -559,7 +431,6 @@ function defaultLoadBaselineRows({ cwd }) {
   }
 }
 
-/** Default on-disk location of the maintainability baseline. */
 function defaultResolveWritePath({ cwd }) {
   return baselineReaderInternals.resolveBaselinePath(KIND, { cwd });
 }

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

@@ -1,35 +1,15 @@
 /**
- * context-budget-writeback.js — lock a context-budget gain in on the branch
- * that earned it (Story #5313).
+ * context-budget-writeback.js — when the tree measures under its recorded
+ * context-budget totals, write the lower totals back as one
+ * `baseline-refresh:` commit on the Story branch, so a stale total can't
+ * silently absorb the next growth.
  *
- * `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.
+ * Runs at the pre-gate seam, not post-land: the only sanctioned landing is
+ * branch → PR → `main`, so a post-land write would commit to the base branch.
  *
- * ## 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.
+ * Only a downward move is written — any growth or unbacked row skips and
+ * leaves `check-context-budget.js` to fail. Idempotent; every failure is a
+ * named skip, never a failed close.
  */
 
 import fs from 'node:fs';
@@ -47,12 +27,10 @@ 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.
+ * Carries the `baseline-refresh:` marker `refresh-ack.js` recognises.
  *
  * @param {number|string} storyId
  * @returns {string}
@@ -62,8 +40,6 @@ function buildCommitSubject(storyId) {
 }
 
 /**
- * One line per tier that moved down, before → after.
- *
  * @param {Array<{ tier: string, current: number, baseline: number }>} shrunk
  * @returns {string}
  */
@@ -78,8 +54,6 @@ function buildCommitBody(shrunk) {
 }
 
 /**
- * Report a no-op by name.
- *
  * @param {object} logger
  * @param {string} reason
  */
@@ -89,7 +63,7 @@ function skip(logger, reason) {
 }
 
 /**
- * Everything that must hold before a write. Returns a skip reason or `null`.
+ * Returns a skip reason or `null`.
  *
  * @param {{ workTree: string, storyBranch: string, git: Function, relPath: string }} ctx
  * @returns {string|null}
@@ -140,10 +114,6 @@ function commitBaseline({ workTree, git, relPath, envelope, storyId, shrunk }) {
 }
 
 /**
- * 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,