mandrel 2.47.0 → 2.49.0

package/.agents/scripts/lib/orchestration/epic-rollup.js

@@ -28,9 +28,18 @@
  *   3. **Never throws.** Every step degrades with a reason. A stale
  *      container costs tidiness; a delivery failed on a board mutation
  *      costs a landed Story its terminal envelope.
+ *   4. **Closure requires an authoritative child list.** Invariant 3 makes
+ *      every read degrade rather than fail, which is right for the writes
+ *      that recompute next tick and wrong for the one that does not. When
+ *      the native sub-issue read fails, the body checklist still answers
+ *      "who are the children" — but no longer "are these *all* of them",
+ *      and closing on that difference shut an Epic over 23 open children
+ *      (Story #5210). Degraded reads keep the Status and assignee writes
+ *      and lose only the close.
  *
  * @module lib/orchestration/epic-rollup
  * @see Story #5205
+ * @see Story #5210 — fail closed on a degraded child read.
  */
 
 import { Logger } from '../Logger.js';
@@ -120,6 +129,11 @@ function isClosed(issue) {
  * the list it is handed, so a silently dropped child could close a container
  * with work still open under it.
  *
+ * Note the scope: this validates the **readability of the ids it was given**,
+ * never the **completeness of the id list**. Completeness is
+ * `nativeReadFailed`'s job in {@link rollUpOneEpic} — checking only this one
+ * is what let three readable ids stand in for 58 (Story #5210).
+ *
  * @param {{ epicId: number, childIds: number[], provider: object }} opts
  * @returns {Promise<object[]|null>}
  */
@@ -214,10 +228,24 @@ async function applyClosure({ epicId, provider }) {
 /**
  * Roll one Epic up from the children it lists.
  *
- * @param {{ epic: object, childIds: number[], provider: object, columnSync: object, owner: string|null }} opts
+ * `nativeReadFailed` splits the writes by reversibility. Column and assignee
+ * are recomputed from scratch on every later tick, so applying them to a
+ * possibly-truncated list costs at most a stale board cell that self-corrects.
+ * Closure does not: it is the one write no subsequent tick undoes (invariant 2
+ * — a reopened child pulls Status back but MUST NOT reopen the issue), so it
+ * requires a child list we know to be complete.
+ *
+ * @param {{ epic: object, childIds: number[], nativeReadFailed?: boolean, provider: object, columnSync: object, owner: string|null }} opts
  * @returns {Promise<object>} Per-Epic outcome record.
  */
-async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
+async function rollUpOneEpic({
+  epic,
+  childIds,
+  nativeReadFailed = false,
+  provider,
+  columnSync,
+  owner,
+}) {
   const epicId = Number(epic?.number ?? epic?.id);
   const outcome = {
     epicId,
@@ -261,6 +289,24 @@ async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
 
   if (isClosed(epic)) return outcome;
 
+  if (nativeReadFailed) {
+    // Every child we could see has landed — but the authoritative read threw,
+    // so "every child" is exactly the claim we cannot make. `readChildren`
+    // above validates that the ids we were handed are *readable*; nothing
+    // there validates that the list is *complete*, which is how an Epic with
+    // 23 open children closed off the three its body happened to spell in the
+    // bare `- [ ] #N` form (Story #5210). Overwrites any column/owner detail
+    // deliberately: this is the reason the Epic is still pending.
+    outcome.pending = true;
+    outcome.detail = 'child-read-degraded';
+    Logger.warn(
+      `[epic-rollup] Epic #${epicId}: every child read looks done, but the ` +
+        'native sub-issue read degraded — refusing to close on a possibly ' +
+        'incomplete child list. Re-run once the API read succeeds.',
+    );
+    return outcome;
+  }
+
   const closure = await applyClosure({ epicId, provider });
   outcome.closed = closure.closed;
   outcome.pending = !closure.closed;
@@ -277,7 +323,7 @@ async function rollUpOneEpic({ epic, childIds, provider, columnSync, owner }) {
  * containers are few, and only one listing this Story is ever read further.
  *
  * @param {{ storyId: number, provider: object, skipEpicIds: Set<number> }} opts
- * @returns {Promise<Array<{ epic: object, childIds: number[] }>>}
+ * @returns {Promise<Array<{ epic: object, childIds: number[], nativeReadFailed: boolean }>>}
  */
 async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
   let epics;
@@ -304,13 +350,25 @@ async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
     // delivery expansion uses. Reading the body alone here is what made an
     // Epic whose children were linked in the GitHub UI expandable but
     // permanently unclosable.
-    const childIds = await readEpicChildIdsFrom({
+    const { ids: childIds, nativeReadFailed } = await readEpicChildIdsFrom({
       epic,
       readNativeChildIds: nativeChildReader(provider),
       onWarn: (message) => Logger.warn(message),
     });
-    if (!childIds.includes(storyId)) continue;
-    matches.push({ epic, childIds });
+    if (!childIds.includes(storyId)) {
+      // A degraded read can truncate this Story out of its own container's
+      // child list, which drops the Epic from the run entirely rather than
+      // rolling it up wrongly. Non-destructive, but silent — say so, since it
+      // is the same root cause as the refusal in `rollUpOneEpic`.
+      if (nativeReadFailed) {
+        Logger.warn(
+          `[epic-rollup] Epic #${epicId}: skipped for Story #${storyId} on a ` +
+            'degraded child read — the Story may in fact be linked to it.',
+        );
+      }
+      continue;
+    }
+    matches.push({ epic, childIds, nativeReadFailed });
   }
   return matches;
 }
@@ -374,11 +432,12 @@ export async function rollUpEpicForStory({
       owner === undefined ? resolveEpicOwner(config) : owner;
 
     const epics = [];
-    for (const { epic, childIds } of matches) {
+    for (const { epic, childIds, nativeReadFailed } of matches) {
       epics.push(
         await rollUpOneEpic({
           epic,
           childIds,
+          nativeReadFailed,
           provider,
           columnSync: sync,
           owner: resolvedOwner,

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

@@ -17,12 +17,12 @@
  * `temp/standalone/stories/story-<id>/validation-evidence.json`, so a
  * second close at unchanged HEAD short-circuits the already-passed gates.
  *
- * Format-autofix self-heal (Story #4250). The Epic path runs
- * `runScopedFormatAutofix` before the check-only gates so benign JSON/YAML
- * drift the formatter can fix is folded into a `fix(story-close):` commit
- * rather than hard-failing the format gate. The standalone path now does
- * the same, with `baseBranch` as the diff anchor and the Story worktree as
- * the commit target.
+ * Pre-gate self-heal (Stories #4250, #5224). Two best-effort steps run on the
+ * Story branch before the check-only gates score it — the scoped format
+ * autofix and the upward maintainability write-back — so whatever they commit
+ * is part of what the gates see and part of the branch's own PR. Both live in
+ * [`pre-gate-steps.js`](pre-gate-steps.js); neither can fail a close, because
+ * an authoritative gate for each runs immediately below.
  *
  * Bounded gate output (Story #4736). Every gate line goes to the run's
  * `gate-log.js` sink — an artifact under the gitignored temp tree — instead
@@ -40,25 +40,24 @@
  * `*:update` + `baseline-refresh:` remedy — advisory only, so the close
  * verdict is unchanged.
  *
- * `runCloseValidation`, `buildDefaultGates`, and `runScopedFormatAutofix`
- * are accepted as injected dependencies so the parent CLI's cache-busted
- * bindings win in tests that mock the upstream module URLs.
+ * `runCloseValidation`, `buildDefaultGates` and the pre-gate steps (whole, or
+ * their two individual collaborators) are accepted as injected dependencies so
+ * the parent CLI's cache-busted bindings win in tests that mock the upstream
+ * module URLs.
  */
 
 import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-validation/gates.js';
 import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
-import { Logger } from '../../../Logger.js';
-import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
 import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
+import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
 
 /**
  * Run the close-validation gate chain. Throws on first gate failure.
  *
- * Order (Story #4250): format-autofix self-heal → close-validation gates.
- * The autofix step scopes the formatter to the `baseBranch...storyBranch`
- * diff, commits any fix on the Story branch inside the Story worktree, and
- * is best-effort — a missing `storyBranch` (resume/legacy callers) skips it
- * with a log line rather than failing.
+ * Order: pre-gate self-heal steps → close-validation gates. The steps scope
+ * to the `baseBranch...storyBranch` diff, commit inside the Story worktree,
+ * and are best-effort — a missing `storyBranch` (resume/legacy callers) skips
+ * them with a log line rather than failing.
  *
  * Gates are built from the canonical resolved config (`buildDefaultGates`
  * reads `project.commands` and `delivery.quality.gates.crap.enabled`); the
@@ -76,7 +75,9 @@ import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
  *   progress: (tag: string, msg: string) => void,
  *   runCloseValidation?: typeof defaultRunCloseValidation,
  *   buildDefaultGates?: typeof defaultBuildDefaultGates,
- *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
+ *   runPreGateSteps?: typeof defaultRunPreGateSteps,
+ *   runScopedFormatAutofix?: Function,
+ *   runBaselineUpwardWriteback?: Function,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
  * @returns {Promise<{ gates: Record<string, 'passed'|'skipped'> }>} Per-gate
@@ -94,52 +95,22 @@ export async function runCloseValidationPhase({
   progress,
   runCloseValidation = defaultRunCloseValidation,
   buildDefaultGates = defaultBuildDefaultGates,
-  runScopedFormatAutofix = defaultRunScopedFormatAutofix,
+  runPreGateSteps = defaultRunPreGateSteps,
+  runScopedFormatAutofix,
+  runBaselineUpwardWriteback,
   createGateLogSink = defaultCreateGateLogSink,
 }) {
-  // Story #4250 — format-autofix self-heal before the check-only gates.
-  // Mirrors the Epic path (story-close/phases/gates.js): the formatter is
-  // scoped to the baseBranch...storyBranch diff, and any fix is committed on
-  // the Story branch in the Story worktree. Skipped (with a log) when no
-  // storyBranch is available so resume/legacy callers don't trip a throw.
-  if (storyBranch) {
-    progress(
-      'FORMAT',
-      `Running scoped format-autofix on ${baseBranch}...${storyBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
-    );
-    // Best-effort self-heal: a failure to even compute the diff (e.g. a
-    // missing ref) must never abort close — the format check gate downstream
-    // is the source of truth for "is the tree formatted". We log and proceed.
-    try {
-      const autofix = runScopedFormatAutofix({
-        cwd,
-        worktreePath,
-        storyId,
-        baseBranch,
-        storyBranch,
-        config,
-        logger: Logger,
-      });
-      if (autofix?.committed) {
-        progress(
-          'FORMAT',
-          `✅ Auto-applied format fix committed as ${autofix.sha} on ${storyBranch}.`,
-        );
-      } else {
-        progress(
-          'FORMAT',
-          `⏭ No format-autofix commit (${autofix?.reason ?? 'clean'}).`,
-        );
-      }
-    } catch (err) {
-      progress(
-        'FORMAT',
-        `⚠️ scoped format-autofix failed (close continues; format gate is authoritative): ${err?.message ?? err}`,
-      );
-    }
-  } else {
-    progress('FORMAT', '⏭ Skipped scoped format-autofix (no story branch).');
-  }
+  await runPreGateSteps({
+    cwd,
+    worktreePath,
+    storyId,
+    baseBranch,
+    storyBranch,
+    config,
+    progress,
+    runScopedFormatAutofix,
+    runBaselineUpwardWriteback,
+  });
 
   progress(
     'VALIDATE',

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

@@ -0,0 +1,171 @@
+/**
+ * phases/pre-gate-steps.js — the self-heal steps the standalone close runs on
+ * the Story branch *before* the check-only gate chain scores it.
+ *
+ * Two steps live here, and they share one contract that is the reason they
+ * share a module: each may author a commit on `story-<id>`, each must run
+ * ahead of the gates so its commit is part of what the gates score and part of
+ * the branch's own PR, and **neither may ever fail the close**. Downstream
+ * there is always an authoritative gate — `biome ci` for formatting,
+ * `check-baselines` for the ratchet — so a failure here is a missed
+ * opportunity to self-heal, never a verdict.
+ *
+ *   1. **Scoped format-autofix** (Story #4250) — run the formatter over the
+ *      `baseBranch...storyBranch` diff and fold any rewrite into a
+ *      `fix(story-close):` commit, so benign JSON/YAML drift that lint-staged
+ *      does not glob never reaches the check-only format gate.
+ *   2. **Upward baseline write-back** (Story #5224) — persist the
+ *      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.
+ *
+ * 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;
+ * carrying two multi-branch best-effort wrappers inline alongside that was the
+ * mass that made it the file it was. Both collaborators stay injectable — the
+ * parent CLI's cache-busted bindings must win in tests that mock the upstream
+ * module URLs — and are threaded through from the phase unchanged.
+ */
+
+import { Logger } from '../../../Logger.js';
+import { runBaselineUpwardWriteback as defaultRunBaselineUpwardWriteback } from '../../story-close/baseline-upward-writeback.js';
+import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
+
+/**
+ * Run the scoped formatter self-heal.
+ *
+ * @param {object} ctx the shared step context (see {@link runPreGateSteps})
+ * @returns {void}
+ */
+function formatAutofixStep({
+  cwd,
+  worktreePath,
+  storyId,
+  baseBranch,
+  storyBranch,
+  config,
+  progress,
+  runScopedFormatAutofix,
+}) {
+  progress(
+    'FORMAT',
+    `Running scoped format-autofix on ${baseBranch}...${storyBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
+  );
+  const autofix = runScopedFormatAutofix({
+    cwd,
+    worktreePath,
+    storyId,
+    baseBranch,
+    storyBranch,
+    config,
+    logger: Logger,
+  });
+  progress(
+    'FORMAT',
+    autofix?.committed
+      ? `✅ Auto-applied format fix committed as ${autofix.sha} on ${storyBranch}.`
+      : `⏭ No format-autofix commit (${autofix?.reason ?? 'clean'}).`,
+  );
+}
+
+/**
+ * Run the upward maintainability write-back.
+ *
+ * @param {object} ctx the shared step context (see {@link runPreGateSteps})
+ * @returns {Promise<void>}
+ */
+async function baselineWritebackStep({
+  cwd,
+  worktreePath,
+  storyId,
+  baseBranch,
+  storyBranch,
+  config,
+  progress,
+  runBaselineUpwardWriteback,
+}) {
+  const writeback = await runBaselineUpwardWriteback({
+    cwd,
+    worktreePath,
+    storyId,
+    baseBranch,
+    storyBranch,
+    config,
+    logger: Logger,
+  });
+  progress(
+    'BASELINE',
+    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'}).`,
+  );
+}
+
+/**
+ * Run one step, absorbing any throw into a progress line.
+ *
+ * The absorption is the point, not laziness about error handling: every step
+ * here is the *refresh* half of a loop whose *enforcement* half runs
+ * immediately afterwards. A step that could abort the close would convert a
+ * self-heal opportunity into an outage, and would do it on the path with the
+ * least operator attention.
+ *
+ * @param {{ tag: string, label: string, progress: Function, run: () => Promise<void>|void }} opts
+ * @returns {Promise<void>}
+ */
+async function bestEffort({ tag, label, progress, run }) {
+  try {
+    await run();
+  } catch (err) {
+    progress(
+      tag,
+      `⚠️ ${label} failed (close continues; the gate chain is authoritative): ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Run every pre-gate self-heal step for a standalone Story close.
+ *
+ * Both steps commit to `story-<id>`, so both are skipped — with a log line, not
+ * a throw — when the caller has no `storyBranch`. That is the resume/legacy
+ * path, which has no branch to commit onto and must not trip an exception for
+ * saying so.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath: string|null,
+ *   storyId: number,
+ *   baseBranch: string,
+ *   storyBranch?: string,
+ *   config: object,
+ *   progress: (tag: string, msg: string) => void,
+ *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
+ *   runBaselineUpwardWriteback?: typeof defaultRunBaselineUpwardWriteback,
+ * }} args
+ * @returns {Promise<void>}
+ */
+export async function runPreGateSteps({
+  runScopedFormatAutofix = defaultRunScopedFormatAutofix,
+  runBaselineUpwardWriteback = defaultRunBaselineUpwardWriteback,
+  ...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).');
+    return;
+  }
+  await bestEffort({
+    tag: 'FORMAT',
+    label: 'scoped format-autofix',
+    progress,
+    run: () => formatAutofixStep({ ...ctx, runScopedFormatAutofix }),
+  });
+  await bestEffort({
+    tag: 'BASELINE',
+    label: 'baseline write-back',
+    progress,
+    run: () => baselineWritebackStep({ ...ctx, runBaselineUpwardWriteback }),
+  });
+}