mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/story-close/pre-merge-validation.js

@@ -1,302 +0,0 @@
-/**
- * pre-merge-validation.js — shift-left close-validation gate runner +
- * maintainability projection advisory.
- *
- * Extracted from story-close.js (Story #956, Theme A finishing touch) so the
- * close orchestrator becomes a thin CLI shell. Two responsibilities:
- *
- *   - runPreMergeGates       — drives `runCloseValidation` over the
- *                              canonical gate list (typecheck, lint, test,
- *                              format, maintainability, crap), routes
- *                              `lint`/`test` start events into the supplied
- *                              phase-timer, and throws on the first failed
- *                              gate with the gate-specific hint embedded in
- *                              the error message.
- *   - emitMaintainabilityProjection — runs the per-file MI ceiling projection
- *                              and emits the `baseline-refresh:` advisory
- *                              before the merge so the operator can ship the
- *                              refresh atomically with the Story PR.
- *
- * Both helpers take their dependencies as injectable seams so unit tests
- * pin behaviour without spawning the close script.
- */
-
-// Story #1973 / Task #1985 — direct import from the maintainability per-kind
-// module under `.agents/scripts/lib/baselines/kinds/`. Replaces the historical
-// `child_process.spawn(node check-maintainability.js)` arm of this helper:
-// the kernel-version label that used to come from the CLI's stdout is now
-// resolved in-process from the per-kind module, and the test suite's
-// no-spawn spy proves the projection path never reaches a per-kind CLI
-// subprocess.
-import * as maintainabilityKind from '../../baselines/kinds/maintainability.js';
-import { buildDefaultGates as defaultBuildDefaultGates } from '../../close-validation/gates.js';
-import {
-  formatMaintainabilityProjection as defaultFormatMaintainabilityProjection,
-  projectMaintainabilityRegressions as defaultProjectMaintainabilityRegressions,
-} from '../../close-validation/projections/maintainability.js';
-import { runCloseValidation as defaultRunCloseValidation } from '../../close-validation/runner.js';
-import { getBaselines as defaultGetBaselines } from '../../config-resolver.js';
-import { Logger as DefaultLogger } from '../../Logger.js';
-
-/**
- * Story #2250 — lifecycle emits fire only when both a positive epicId and a
- * positive storyId are present (the schema requires both) and a bus exists.
- * Legacy resume fixtures pass `storyId: null` and must run without emits.
- * Story #4075 — extracted from `runPreMergeGates`.
- */
-export function lifecycleEmitsActive({ epicId, storyId, bus }) {
-  return (
-    Number.isInteger(epicId) &&
-    epicId > 0 &&
-    Number.isInteger(storyId) &&
-    storyId > 0 &&
-    !!bus
-  );
-}
-
-/**
- * Build the typed `PRE_MERGE_GATE_FAILED` Error from the first failed gate.
- * Story #2136 / Task #2143 — failure metadata is surfaced as typed Error
- * properties so callers (notably `runPreMergeGatesWithAttribution`)
- * pattern-match exit codes without parsing the human message; the message
- * format is preserved byte-for-byte so existing regex consumers keep
- * matching. Story #4075 — extracted from `runPreMergeGates`.
- */
-export function buildGateFailureError({ gate, status, gateCwd }) {
-  const err = new Error(
-    `Pre-merge validation failed at "${gate.name}" (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
-      (gate.hint ? ` ${gate.hint}` : ''),
-  );
-  err.code = 'PRE_MERGE_GATE_FAILED';
-  err.gateName = gate.name;
-  err.exitCode = status;
-  err.gateCwd = gateCwd ?? null;
-  return err;
-}
-
-/**
- * Run the pre-merge validation gate chain. On failure throws an `Error`
- * whose message embeds the first failed gate's name, exit code, hint, and
- * the working directory the gate ran in — the `runAsCli` boundary in
- * `story-close.js` maps the throw to `process.exit(1)`. (See Story #959 —
- * close-tail scripts must throw rather than route through the logger's
- * fatal sink, so a mocked `process.exit` cannot swallow the failure
- * silently.)
- *
- * Story #1120: pass `worktreePath` (`.worktrees/story-<id>/`) so every
- * gate runs against the Story branch's post-rebase tree, not the main
- * checkout. Without it, gate spawn falls back to `cwd` (the main
- * checkout) — the legacy single-tree path remains intact.
- *
- * `phaseTimer` may be omitted; when present, lint/test starts are timed.
- *
- * Story #2250 — the gate chain is the canonical close-validate sub-phase
- * of the close-tail; this helper emits `close-validate.start` /
- * `close-validate.end` events on the supplied lifecycle bus so the
- * lifecycle ledger captures the sub-phase boundary with non-zero
- * `durationMs`. On gate failure the helper also emits `story.blocked`
- * with a typed `close-validate-failed:<gateName>` reason BEFORE throwing
- * — the existing BlockerHandler listener (Story #2241 / Task #2246)
- * cascades that to `epic.blocked`, so a failed validator routes through
- * the lifecycle cascade rather than being silently swallowed by the
- * caller's try/catch. The throw shape is preserved byte-for-byte so the
- * regex consumers in `runPreMergeGatesWithAttribution` keep matching.
- */
-export async function runPreMergeGates({
-  cwd,
-  worktreePath,
-  epicBranch,
-  config,
-  storyId,
-  epicId,
-  useEvidence = true,
-  phaseTimer,
-  bus,
-  now = Date.now,
-  logger = DefaultLogger,
-  buildDefaultGates = defaultBuildDefaultGates,
-  runCloseValidation = defaultRunCloseValidation,
-}) {
-  // Epic #2646 Story C (Task #2700) — `bus` is a hard input. The
-  // previous guarded `emitLifecycleSafe` helper that tolerated a null
-  // bus is gone. The `emitsActive` outer guard below still skips emits
-  // for legacy resume fixtures that pass `storyId: null` (those rows
-  // have no Story-scoped lifecycle), but bus must be present.
-  if (!bus || typeof bus.emit !== 'function') {
-    throw new TypeError(
-      'runPreMergeGates: bus is required (object with emit()).',
-    );
-  }
-  logger.info?.(
-    `[close-validation] Running pre-merge gates (typecheck, lint, test, format, maintainability, crap, baselines)${worktreePath ? ` in ${worktreePath}` : ''}${epicBranch ? ` against baseline ref ${epicBranch}` : ''}...`,
-  );
-  // `buildDefaultGates` reads the canonical resolved config directly:
-  // gate commands resolve from `project.commands` and the CRAP toggle
-  // from `delivery.quality.gates.crap.enabled`.
-  // Probe the coverage script from the gate execution directory (the Story
-  // worktree when present) so coverage-capture is only registered when the
-  // consumer ships `test:coverage` (#4473).
-  const gates = buildDefaultGates({
-    config,
-    epicBranch,
-    cwd: worktreePath || cwd,
-    log: (m) => logger.info?.(m),
-  });
-  const gateCount = Array.isArray(gates) ? gates.length : 0;
-  // Story #2250 — emit `close-validate.start` only when both an epicId
-  // and a storyId are present; the schema requires both, and unit
-  // fixtures that drive the helper with `storyId: null` (legacy resume
-  // tests) must continue to operate without lifecycle observability.
-  const emitsActive = lifecycleEmitsActive({ epicId, storyId, bus });
-  const startedAt = typeof now === 'function' ? now() : Date.now();
-
-  // Emit the `close-validate.end` boundary, plus the `story.blocked`
-  // cascade trigger on failure (Story #2250). No-op when emits are
-  // inactive (legacy resume fixtures with `storyId: null`).
-  const emitEnd = async ({ ok, extra = {}, blockedReason } = {}) => {
-    if (!emitsActive) return;
-    const endedAt = typeof now === 'function' ? now() : Date.now();
-    await bus.emit('close-validate.end', {
-      epicId,
-      storyId,
-      ok,
-      gateCount,
-      ...extra,
-      durationMs: Math.max(0, endedAt - startedAt),
-    });
-    if (blockedReason) {
-      await bus.emit('story.blocked', { storyId, reason: blockedReason });
-    }
-  };
-
-  if (emitsActive) {
-    await bus.emit('close-validate.start', { epicId, storyId });
-  }
-  let validation;
-  try {
-    validation = await runCloseValidation({
-      cwd,
-      worktreePath,
-      gates,
-      log: (m) => logger.info(m),
-      onGateStart: (gate) => {
-        // Only the canonical phase-enum gates drive `mark()`. Non-enum gates
-        // (`typecheck`, `format`, `check-maintainability`) share the
-        // currently-open phase's wall clock — a deliberate choice so the
-        // `phase-timings` schema stays stable against future gate churn.
-        if (phaseTimer && (gate.name === 'lint' || gate.name === 'test')) {
-          phaseTimer.mark(gate.name);
-        }
-      },
-      storyId,
-      epicId,
-      useEvidence,
-    });
-  } catch (err) {
-    // Reach this branch only when `runCloseValidation` itself throws
-    // (spawn-level catastrophe — the per-gate failures route through
-    // `validation.failed` below). Emit the matching `close-validate.end`
-    // with `ok:false` so the ledger always carries the boundary, then
-    // re-throw.
-    await emitEnd({
-      ok: false,
-      extra: { failedGate: 'runner-error' },
-      blockedReason: 'close-validate-failed:runner-error',
-    });
-    throw err;
-  }
-  if (!validation.ok) {
-    const { gate, status, cwd: gateCwd } = validation.failed[0];
-    // Story #2250 — emit the boundary + `story.blocked` cascade BEFORE
-    // throwing so the lifecycle ledger captures the boundary even when the
-    // caller's try/catch swallows the throw, and the BlockerHandler
-    // listener cascades to `epic.blocked`.
-    await emitEnd({
-      ok: false,
-      extra: { failedGate: gate.name, exitCode: status },
-      blockedReason: `close-validate-failed:${gate.name}`,
-    });
-    throw buildGateFailureError({ gate, status, gateCwd });
-  }
-  await emitEnd({ ok: true });
-  return validation;
-}
-
-/**
- * Resolve the maintainability kernel version from the per-kind module so
- * the projection log header can name the kernel currently in scope. Reads
- * are best-effort — a sentinel `'0.0.0'` from the kernel-version
- * resolver (e.g. when typhonjs-escomplex is missing under a partial
- * install) collapses to `null` so the helper never injects a misleading
- * label into the log.
- *
- * Story #1973 / Task #1985 — this is the only call site outside the
- * `baselines/` tree that touches `kinds/maintainability.js` directly; the
- * import is the load-bearing acceptance hook for "no per-kind CLI spawn"
- * because referencing `kindModule.kernelVersion` proves the helper does
- * not need to fork a subprocess to learn what kernel it is running under.
- *
- * @param {object} kindModule - Per-kind maintainability module.
- * @returns {string | null}
- */
-function resolveKernelLabel(kindModule) {
-  try {
-    const v = kindModule?.kernelVersion?.();
-    if (typeof v !== 'string' || v === '0.0.0') return null;
-    return v;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Emit the per-file MI ceiling projection advisory. Failure is non-fatal
- * (logged through `logger.warn`) — the projection is informational only,
- * and a missing baseline path skips the helper entirely.
- *
- * Story #1973 / Task #1985 — the projection no longer fans out a
- * per-kind `child_process.spawn(node check-maintainability.js)` to learn
- * the kernel context: the per-kind module under `baselines/kinds/` is
- * imported directly. The `kindModule` collaborator is injectable so unit
- * tests can pin the kernel label without touching the on-disk module.
- */
-export function emitMaintainabilityProjection({
-  cwd,
-  epicBranch,
-  storyBranch,
-  config,
-  logger = DefaultLogger,
-  getBaselines = defaultGetBaselines,
-  projectMaintainabilityRegressions = defaultProjectMaintainabilityRegressions,
-  formatMaintainabilityProjection = defaultFormatMaintainabilityProjection,
-  kindModule = maintainabilityKind,
-}) {
-  try {
-    const baselinePath = getBaselines(config)?.maintainability?.path;
-    if (!baselinePath) return;
-    const projection = projectMaintainabilityRegressions({
-      cwd,
-      epicBranch,
-      storyBranch,
-      baselinePath,
-    });
-    const advisory = formatMaintainabilityProjection(projection);
-    if (advisory) {
-      const kernel = resolveKernelLabel(kindModule);
-      if (kernel) {
-        logger.info(
-          `[close-validation] Pre-merge MI projection (kernel=${kernel}):`,
-        );
-      }
-      for (const line of advisory.split('\n')) logger.info(line);
-    } else if (projection.skipped) {
-      logger.info(
-        `[close-validation] Pre-merge MI projection skipped (${projection.skipped}).`,
-      );
-    }
-  } catch (err) {
-    logger.warn?.(
-      `[close-validation] Pre-merge MI projection failed: ${err?.message ?? err}`,
-    );
-  }
-}

package/.agents/scripts/lib/orchestration/story-close/shared-checkout-guard.js

@@ -1,163 +0,0 @@
-/**
- * shared-checkout-guard.js — cross-epic contention guard for the merge
- * phase's `git checkout <epicBranch>` in the shared main checkout
- * (Story #4460).
- *
- * `story-close.js`'s merge phase (`runFinalizeMerge` in `merge-runner.js`)
- * runs `git checkout <epicBranch>` directly in the shared main repo
- * checkout — `close-inputs.js` resolves `cwd` to `PROJECT_ROOT`, not an
- * isolated worktree. The only exclusivity guard around that shared
- * checkout is the per-Epic `epic-merge-lock.js` mutex, which only
- * serializes concurrent runs for the SAME epic. Nothing stops a
- * DIFFERENT epic's concurrently-running `story-close.js` from treating
- * the same shared checkout as scratch space at the same time.
- *
- * This was observed live: while delivering Epic #4425 Stories #4427/#4428,
- * the shared checkout repeatedly carried uncommitted stray changes
- * belonging to a concurrently-running Epic #4405 delivery (parked on
- * `epic/4405` with dirty edits), which blocked the `git checkout epic/4425`
- * merge step with a raw `error: Your local changes ... would be
- * overwritten by checkout`.
- *
- * `assertSharedCheckoutAvailable` runs immediately before that checkout
- * and fails fast with an actionable, story-close-specific diagnostic
- * instead of letting the raw git error surface. It COMPOSES with (does
- * not replace) the per-Epic lock: by the time this guard runs, the
- * caller's own epic lock is already held (acquired around the whole
- * close flow in `story-close.js`), so this guard only inspects OTHER
- * epics' lock files plus the tree's overall dirty state — it never
- * contends with same-epic concurrent runs, which continue to serialize
- * solely via `withEpicMergeLock` before this guard ever executes.
- *
- * Breadth trade-off (deliberate): the foreign-lock probe keys on the
- * OTHER epic's per-epic merge lock, which that run holds for its WHOLE
- * close flow — so any overlapping story-close of another epic trips this
- * guard even when that run never actually touches the shared checkout
- * during the overlap. The refusal is deterministic and loud (throws with
- * a diagnostic naming the holder pid), never a deadlock (no waiting),
- * and stale/dead-pid foreign locks are ignored via the pid-liveness
- * probe. Narrowing the window (a dedicated checkout-phase lock) was
- * considered and rejected: the coarse refusal is rare, cheap to retry,
- * and far simpler than a second lock tier.
- */
-
-import { findForeignActiveEpicLock as defaultFindForeignActiveEpicLock } from '../../epic-merge-lock.js';
-import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
-
-const MAX_LISTED_DIRTY_FILES = 20;
-
-function describeForeignLock(foreign) {
-  const acquired = Number.isFinite(foreign.acquiredAt)
-    ? new Date(foreign.acquiredAt).toISOString()
-    : 'an unknown time';
-  return (
-    `[story-close] shared-checkout guard: refusing to touch the shared main checkout — ` +
-    `it is currently held by epic #${foreign.epicId}'s story-close merge phase ` +
-    `(lock ${foreign.filePath}, pid ${foreign.pid}, acquired ${acquired}). ` +
-    `Wait for that epic's story-close run to finish before retrying this merge. ` +
-    `If you have independently confirmed that process is no longer running, remove ` +
-    `the lock file by hand — never force a checkout past a live foreign lock. ` +
-    `See .agents/rules/git-conventions.md § Shared-checkout contention (Story #4460).`
-  );
-}
-
-function listDirtyFiles(porcelainOutput) {
-  // `git status --porcelain` lines are `XY <path>` — a fixed 2-char status
-  // column, a space, then the path. Strip only a trailing `\r` (Windows)
-  // before slicing off that 3-char prefix; trimming the whole line first
-  // would shift the slice offset whenever the status column starts with a
-  // space (the common "unstaged modification" case), truncating the path.
-  const lines = porcelainOutput
-    .split('\n')
-    .map((line) => line.replace(/\r$/, ''))
-    .filter((line) => line.length > 0);
-  const shown = lines
-    .slice(0, MAX_LISTED_DIRTY_FILES)
-    .map((line) => line.slice(3).trim() || line);
-  const overflow = lines.length - shown.length;
-  return overflow > 0
-    ? `${shown.join(', ')}, … (+${overflow} more)`
-    : shown.join(', ');
-}
-
-function describeDirtyCheckout({ cwd, epicId, currentBranch, dirtyFiles }) {
-  return (
-    `[story-close] shared-checkout guard: refusing to check out the epic branch for ` +
-    `epic #${epicId} — the shared main checkout at ${cwd} is dirty (currently on ` +
-    `\`${currentBranch}\`). Dirty files: ${dirtyFiles}. This usually means another ` +
-    `epic's story-close run left uncommitted work in the shared checkout, or a prior ` +
-    `run crashed mid-merge. Resolve manually (stash/commit/reset in ${cwd}) before ` +
-    `retrying. See .agents/rules/git-conventions.md § Shared-checkout contention ` +
-    `(Story #4460).`
-  );
-}
-
-/**
- * Fail fast when the shared main checkout is not safely available for this
- * epic's merge-phase `git checkout <epicBranch>` — either because another
- * epic's story-close merge phase currently holds it (a live foreign lock),
- * or because it is simply dirty (regardless of whose branch is checked
- * out). Silent no-op when the checkout is clean and uncontended.
- *
- * @param {{
- *   cwd: string,
- *   epicId: number|string,
- *   gitSpawn?: typeof defaultGitSpawn,
- *   findForeignActiveEpicLock?: typeof defaultFindForeignActiveEpicLock,
- * }} opts
- * @throws {Error} with an actionable, story-close-specific diagnostic.
- */
-/**
- * Foreign-lock-only variant for the RESUME merge path (Story #4460
- * follow-up): a resume legitimately re-enters a shared checkout that is
- * dirty with THIS story's own in-progress merge, so the dirty-tree half
- * of `assertSharedCheckoutAvailable` would false-positive there. The
- * cross-epic hazard — another epic's live merge phase holding the
- * checkout — still applies and is the only probe this variant runs.
- */
-export function assertNoForeignEpicLock({
-  cwd,
-  epicId,
-  findForeignActiveEpicLock = defaultFindForeignActiveEpicLock,
-}) {
-  const foreign = findForeignActiveEpicLock(epicId, { repoRoot: cwd });
-  if (foreign) {
-    throw new Error(describeForeignLock(foreign));
-  }
-}
-
-export function assertSharedCheckoutAvailable({
-  cwd,
-  epicId,
-  gitSpawn = defaultGitSpawn,
-  findForeignActiveEpicLock = defaultFindForeignActiveEpicLock,
-}) {
-  const foreign = findForeignActiveEpicLock(epicId, { repoRoot: cwd });
-  if (foreign) {
-    throw new Error(describeForeignLock(foreign));
-  }
-
-  const statusRes = gitSpawn(cwd, 'status', '--porcelain');
-  if (statusRes.status !== 0) {
-    // Can't determine dirtiness from here — let the downstream checkout
-    // surface whatever git itself reports rather than guessing.
-    return;
-  }
-  const porcelain = statusRes.stdout || '';
-  if (porcelain.trim().length === 0) return;
-
-  const branchRes = gitSpawn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
-  const currentBranch =
-    branchRes.status === 0
-      ? (branchRes.stdout || '').trim() || 'unknown'
-      : 'unknown';
-
-  throw new Error(
-    describeDirtyCheckout({
-      cwd,
-      epicId,
-      currentBranch,
-      dirtyFiles: listDirtyFiles(porcelain),
-    }),
-  );
-}