mandrel 2.0.0 → 2.1.0

package/.agents/scripts/check-prepush-recovery.js

@@ -1,90 +0,0 @@
-#!/usr/bin/env node
-/**
- * check-prepush-recovery.js — gate decision for the pre-push coverage step.
- *
- * Story #3162. The pre-push hook normally runs `coverage-capture.js` +
- * `crap:check` on every push. During a pre-v2 `story-close.js` recovery (operator
- * pushing `epic/<id>` to unblock a run after a merge-orchestrator failure),
- * a pre-existing coverage regression on `epic/<id>` — unrelated to the
- * Story under recovery — hard-blocks the push and forces a `--no-verify`
- * bypass, which violates the global "no hook bypass" rule.
- *
- * This script is the scoped escape hatch. It exits 0 ("skip coverage gate")
- * only when BOTH conditions hold:
- *
- *   1. `STORY_CLOSE_RECOVERY=1` is set in the environment.
- *   2. At least one ref being pushed has a local ref of the shape
- *      `refs/heads/epic/<id>` (parsed from the pre-push stdin protocol).
- *
- * Otherwise it exits 1 ("run coverage gate as today"). The narrow scope is
- * deliberate: a generic env-var bypass would erode the gate; tying the
- * skip to an epic-branch target keeps every other push honest.
- *
- * Stdin contract (git pre-push hook protocol): zero or more lines, each
- *   `<local_ref> <local_sha> <remote_ref> <remote_sha>`
- * separated by whitespace. Empty stdin (no refs being pushed) yields exit 1.
- */
-
-import { runAsCli } from './lib/cli-utils.js';
-
-const EPIC_REF_PATTERN = /^refs\/heads\/epic\//;
-const SKIP_LOG = '[pre-push] coverage gate skipped by STORY_CLOSE_RECOVERY';
-
-/**
- * Parse pre-push stdin into the list of local refs being pushed. Lines with
- * fewer than four whitespace-separated tokens are tolerated (git in practice
- * always emits four, but defensive parsing keeps the helper robust against
- * empty pushes and trailing whitespace).
- *
- * @param {string} stdin
- * @returns {string[]} local ref names (first token of each non-empty line)
- */
-export function parsePrePushLocalRefs(stdin) {
-  if (typeof stdin !== 'string' || stdin.length === 0) return [];
-  return stdin
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => line.split(/\s+/)[0])
-    .filter(Boolean);
-}
-
-/**
- * Pure decision function. `true` means "skip the coverage gate".
- *
- * @param {object} input
- * @param {string|undefined} input.env  value of STORY_CLOSE_RECOVERY
- * @param {string[]} input.localRefs    parsed local refs
- * @returns {boolean}
- */
-export function shouldSkipCoverageGate({ env, localRefs }) {
-  if (env !== '1') return false;
-  if (!Array.isArray(localRefs) || localRefs.length === 0) return false;
-  return localRefs.some((ref) => EPIC_REF_PATTERN.test(ref));
-}
-
-async function readStdin() {
-  if (process.stdin.isTTY) return '';
-  let data = '';
-  process.stdin.setEncoding('utf8');
-  for await (const chunk of process.stdin) data += chunk;
-  return data;
-}
-
-async function main() {
-  const stdin = await readStdin();
-  const localRefs = parsePrePushLocalRefs(stdin);
-  const skip = shouldSkipCoverageGate({
-    env: process.env.STORY_CLOSE_RECOVERY,
-    localRefs,
-  });
-  if (skip) {
-    process.stdout.write(`${SKIP_LOG}\n`);
-    process.exit(0);
-  }
-  process.exit(1);
-}
-
-runAsCli(import.meta.url, main);
-
-export const __testing = { EPIC_REF_PATTERN, SKIP_LOG };

package/.agents/scripts/lib/git-merge-orchestrator.js

@@ -1,261 +0,0 @@
-/* node:coverage ignore file -- ephemeral merge orchestrator over live git state; conflict triage tested via integration. Unit-mocking requires asserting only the mock structure */
-
-/**
- * git-merge-orchestrator.js — Ephemeral Candidate Branch Merge Logic
- *
- * Encapsulates the complete merge-and-conflict-resolution lifecycle for
- * a single Task integration candidate. Extracted from the legacy
- * integration script to satisfy SRP: the orchestrator owns only Git
- * state transitions.
- *
- * Responsibilities:
- *   - Create and tear down the ephemeral candidate branch.
- *   - Detect and triage merge conflicts (major vs minor threshold).
- *   - Auto-resolve minor conflicts (accept theirs) with audit logging.
- */
-
-import { resolveConfig } from './config-resolver.js';
-import { gitSpawn } from './git-utils.js';
-
-/**
- * Analyse conflict severity using git's binary-safe diff --check.
- *
- * @param {string} cwd - Project root.
- * @returns {{ files: number, lines: number, fileList: string[] }}
- */
-function analyzeConflicts(cwd) {
-  const unmerged = gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
-  if (!unmerged.stdout) return { files: 0, lines: 0, fileList: [] };
-
-  const fileList = unmerged.stdout.split('\n').filter(Boolean);
-  const check = gitSpawn(cwd, 'diff', '--check');
-  const markerMatches = check.stdout.match(/leftover conflict marker/g);
-
-  return {
-    files: fileList.length,
-    lines: markerMatches ? markerMatches.length : 0,
-    fileList,
-  };
-}
-
-/**
- * Merge the feature branch into the current (candidate) branch.
- * Handles conflict triage and auto-resolution.
- *
- * @param {string}   cwd           - Project root.
- * @param {string}   featureBranch - Branch name to merge in.
- * @param {Function} vlog          - `(level, context, message, meta)` warn helper for conflict triage output.
- * @param {object}   [opts]
- * @param {string}   [opts.message] - Explicit merge commit message (passed as `-m`).
- * @returns {{ merged: true } | { merged: false, major: true } | never}
- *   Returns `{ merged: true }` on clean merge or resolved minor conflicts.
- *   Returns `{ merged: false, major: true }` on major conflict (caller should exit 2).
- *   Throws on internal git errors.
- */
-/**
- * Pure: classify a conflict snapshot as `'major'` (caller aborts) or
- * `'minor'` (caller auto-resolves). Thresholds default to the values in
- * `delivery.mergeThresholds` and fall back to file=3, line=20.
- *
- * @param {{ files: number, lines: number }} conflicts
- * @param {{ files?: number, lines?: number } | undefined} thresholds
- * @returns {'major' | 'minor'}
- */
-export function classifyConflictSeverity(conflicts, thresholds = {}) {
-  const fileCap = thresholds.files ?? 3;
-  const lineCap = thresholds.lines ?? 20;
-  if (conflicts.files >= fileCap || conflicts.lines >= lineCap) return 'major';
-  return 'minor';
-}
-
-/**
- * Auto-resolve a minor merge conflict by accepting the feature-branch version
- * for each file in `conflicts.fileList`, capturing the discarded line counts
- * for the audit trailer. Side effects: shells out to git checkout/add.
- *
- * @returns {Array<{ file: string, discardedLines: number }>}
- */
-function autoResolveAcceptingTheirs(cwd, conflicts, vlog) {
-  const autoResolvedFiles = [];
-  for (const file of conflicts.fileList) {
-    const ourVersion = gitSpawn(cwd, 'show', `:2:${file}`);
-    const discardedLines = ourVersion.stdout
-      ? ourVersion.stdout.split('\n').length
-      : 0;
-    autoResolvedFiles.push({ file, discardedLines });
-    if (ourVersion.stdout) {
-      vlog(
-        'warn',
-        'integration',
-        `Auto-resolving "${file}" to theirs — discarding base version (${discardedLines} lines)`,
-        {
-          file,
-          discardedLines,
-          discardedPreview: ourVersion.stdout.substring(0, 500),
-        },
-      );
-    }
-    gitSpawn(cwd, 'checkout', '--theirs', file);
-    gitSpawn(cwd, 'add', file);
-  }
-  return autoResolvedFiles;
-}
-
-/**
- * Commit the auto-resolved working tree. When the caller supplied an explicit
- * merge message, append the audit trailer; otherwise use git's default
- * `--no-edit` message.
- */
-function commitAutoResolution(cwd, opts, autoResolvedFiles) {
-  const trailer = buildAutoResolveTrailer(autoResolvedFiles);
-  const finalMessage = opts.message ? `${opts.message}\n\n${trailer}` : null;
-  const commitArgs = finalMessage
-    ? ['commit', '-m', finalMessage]
-    : ['commit', '--no-edit'];
-  const commitResult = gitSpawn(cwd, ...commitArgs);
-  if (commitResult.status !== 0) {
-    throw new Error(`Auto-resolution commit failed: ${commitResult.stderr}`);
-  }
-}
-
-// Epic #3078: pre-commit hooks (notably lint-staged's stash/restore dance)
-// can leave `git merge --no-ff` exiting 0 without recording the commit.
-// Verify HEAD advanced; distinguish silent failure from "Already up to date".
-function classifyZeroExitMerge({
-  headBefore,
-  headAfter,
-  mergeStdout,
-  featureBranch,
-}) {
-  if (headAfter !== headBefore) return { merged: true };
-  if (/Already up to date/i.test(mergeStdout)) {
-    return { merged: true, alreadyMerged: true };
-  }
-  throw new Error(
-    `git merge --no-ff ${featureBranch} exited 0 but HEAD did not advance ` +
-      `(was ${headBefore || '<unknown>'}). Most likely a pre-commit hook ` +
-      `(commonly lint-staged) accepted the merge content into the index ` +
-      `without recording the commit. Inspect the index and any active ` +
-      `stash, commit the merge content manually if appropriate, then ` +
-      `re-run story-close with --resume. See Epic #3078 for incident notes.`,
-  );
-}
-
-export function mergeFeatureBranch(cwd, featureBranch, vlog, opts = {}) {
-  const headBefore = gitSpawn(cwd, 'rev-parse', 'HEAD').stdout;
-  const mergeArgs = ['merge', '--no-ff', featureBranch];
-  if (opts.message) mergeArgs.push('-m', opts.message);
-  const merge = gitSpawn(cwd, ...mergeArgs);
-  if (merge.status === 0) {
-    return classifyZeroExitMerge({
-      headBefore,
-      headAfter: gitSpawn(cwd, 'rev-parse', 'HEAD').stdout,
-      mergeStdout: merge.stdout,
-      featureBranch,
-    });
-  }
-
-  const conflicts = analyzeConflicts(cwd);
-
-  // `git merge` exited non-zero but the index has no unmerged entries and
-  // no leftover conflict markers. The merge either already landed (a hook
-  // emitted a non-zero exit after the merge commit was created) or was a
-  // no-op (feature branch is already an ancestor / does not exist). In
-  // both cases there is nothing to auto-resolve and nothing to commit —
-  // attempting `git commit` here fails with "nothing to commit", which
-  // turns a successful merge into a fatal and strands story-close work.
-  if (conflicts.files === 0 && conflicts.lines === 0) {
-    return { merged: true, alreadyMerged: true };
-  }
-
-  vlog('warn', 'integration', 'Merge conflict detected', {
-    files: conflicts.files,
-    lines: conflicts.lines,
-    fileList: conflicts.fileList,
-  });
-
-  // Epic #2880 / F14B: read mergeThresholds from the canonical resolved
-  // config (`delivery.mergeThresholds`). The legacy `agentSettings`
-  // pointer is gone — destructuring it throws `Cannot read properties of
-  // undefined`. The threshold block remains optional; `classifyConflict
-  // Severity` falls back to file=3/line=20 when undefined.
-  const config = resolveConfig();
-  const severity = classifyConflictSeverity(
-    conflicts,
-    config?.delivery?.mergeThresholds,
-  );
-  if (severity === 'major') {
-    gitSpawn(cwd, 'merge', '--abort');
-    return { merged: false, major: true, conflicts };
-  }
-
-  const autoResolvedFiles = autoResolveAcceptingTheirs(cwd, conflicts, vlog);
-  commitAutoResolution(cwd, opts, autoResolvedFiles);
-  return { merged: true, autoResolved: true, conflicts, autoResolvedFiles };
-}
-
-/**
- * Build a merge-commit message body + trailer documenting which files were
- * auto-resolved by accepting the feature-branch version and how many lines
- * of the base version were discarded.
- *
- * The output is split into three blocks separated by blank lines so
- * commitlint's per-line caps (`body-max-line-length` and
- * `footer-max-line-length`, both default 100) all pass:
- *
- *   1. Header sentence.
- *   2. Body prose listing each file and its discarded line count.
- *   3. `Auto-resolved-file:` trailers — one per file, path only, so the
- *      verbose line count never appears on the footer line.
- *
- * Paths that would still bust the per-line cap are middle-truncated with
- * an ellipsis. This is a last-resort safety net for pathological repo
- * layouts; the common case (short relative paths) emits the full path.
- *
- * Exported for contract testing of the cap behaviour.
- *
- * @param {Array<{ file: string, discardedLines: number }>} resolved
- * @param {{ maxLineLength?: number }} [opts]
- * @returns {string}
- */
-export function buildAutoResolveTrailer(resolved, opts = {}) {
-  const maxLineLength = opts.maxLineLength ?? 100;
-  const header =
-    'Auto-resolved-conflicts: accepted feature branch for the following file(s).';
-
-  const bodyLines = resolved.map((r) => {
-    const suffix = `: discarded ${r.discardedLines} base line(s)`;
-    const prefix = '- ';
-    const available = maxLineLength - prefix.length - suffix.length;
-    return `${prefix}${truncatePathForLine(r.file, available)}${suffix}`;
-  });
-
-  const trailerKey = 'Auto-resolved-file: ';
-  const trailerLines = resolved.map((r) => {
-    const available = maxLineLength - trailerKey.length;
-    return `${trailerKey}${truncatePathForLine(r.file, available)}`;
-  });
-
-  return `${header}\n\n${bodyLines.join('\n')}\n\n${trailerLines.join('\n')}`;
-}
-
-/**
- * Middle-truncate a path with an ellipsis so it fits within `max`
- * characters. When `max` is too small to keep any meaningful slice
- * (≤ 4 chars after the ellipsis), the leading characters win — the
- * tail is dropped and an ellipsis is appended. Pure helper, no I/O.
- *
- * @param {string} p
- * @param {number} max
- * @returns {string}
- */
-function truncatePathForLine(p, max) {
-  if (max <= 0) return '…';
-  if (p.length <= max) return p;
-  const ellipsis = '…';
-  const keep = max - ellipsis.length;
-  if (keep <= 4) return `${p.slice(0, max - 1)}${ellipsis}`;
-  const head = Math.ceil(keep / 2);
-  const tail = Math.floor(keep / 2);
-  return `${p.slice(0, head)}${ellipsis}${p.slice(p.length - tail)}`;
-}

package/.agents/scripts/lib/observability/baseline-refresh-rate.js

@@ -1,221 +0,0 @@
-/**
- * baseline-refresh-rate.js — pure reporter for the per-Epic baseline-refresh
- * commit rate (Epic #1386, Story #1400).
- *
- * The "baseline-refresh discipline" (Story #1124, Tech Spec #902) requires
- * that every Story whose merge introduces baseline drift land an explicit
- * `baseline-refresh:` commit in the same close PR (or, post Story #1398,
- * fold the refresh into the close commit itself). The 90% target — that
- * at least 90% of merged Stories per Epic land without leaving baseline
- * drift behind — needs a measurable signal so retros can spot regressions
- * before they leak into `main`.
- *
- * This module exports a single pure function that takes a fixture of
- * commit records (one per Story-attributable commit on `epic/<id>` over
- * the trailing window) and returns:
- *
- *   - per-Epic counts of `baseline-refresh:` commits
- *   - per-Epic counts of merged Stories
- *   - per-Epic percentage of merged Stories that did NOT land a
- *     baseline-refresh commit (the "clean-merge" rate)
- *
- * The caller (analyze-execution.js) is responsible for shelling out to
- * `git log` and resolving each commit to its parent Epic ID — this
- * module touches no I/O so the test fixture can pin behavior without a
- * temp git repo or stubbed spawn.
- *
- * Default window is 4 weeks (28 days). Pass `windowDays` to override
- * (e.g., `windowDays: 14` for a fortnightly retro).
- *
- * Aligned with `perf-aggregator.js`: empty input yields a well-formed
- * empty payload, malformed records are silently skipped, the function
- * never throws on bad data.
- */
-
-import { isObject } from '../json-utils.js';
-import { RESOLVES_TRAILER_RE } from '../orchestration/resolves-token.js';
-
-const BASELINE_REFRESH_PREFIX = 'baseline-refresh:';
-const DEFAULT_WINDOW_DAYS = 28;
-
-/**
- * Coerce an ISO-8601 date string to epoch ms. Returns NaN for malformed
- * input so the caller's window filter drops the record.
- */
-function toEpochMs(iso) {
-  if (typeof iso !== 'string' || iso.length === 0) return Number.NaN;
-  const ms = Date.parse(iso);
-  return Number.isFinite(ms) ? ms : Number.NaN;
-}
-
-/**
- * Classify a commit by its subject line.
- *
- *   - `baseline-refresh:` prefix → refresh commit
- *   - subject containing `(resolves #N)` → Story-merge commit
- *   - everything else → ignored (chore commits, baseline-only fixes, etc.)
- *
- * The classification is deliberately disjoint: a `baseline-refresh:`
- * commit is never counted as a Story merge, and a Story merge is never
- * counted as a baseline-refresh — even if the subject happens to mention
- * both keywords. This matches the on-the-ground convention: refreshes
- * land as their own commit (or amended into the close), Stories land as
- * `feat: ... (resolves #N)`.
- */
-function classifySubject(subject) {
-  if (typeof subject !== 'string' || subject.length === 0) return 'other';
-  if (subject.startsWith(BASELINE_REFRESH_PREFIX)) return 'refresh';
-  if (RESOLVES_TRAILER_RE.test(subject)) return 'story';
-  return 'other';
-}
-
-/**
- * Compute the trailing-window cutoff in epoch ms. Exported on the
- * exported function via the `now` option so tests can pin the clock.
- */
-function computeCutoffMs(nowMs, windowDays) {
-  const days =
-    Number.isFinite(windowDays) && windowDays > 0
-      ? windowDays
-      : DEFAULT_WINDOW_DAYS;
-  return nowMs - days * 24 * 60 * 60 * 1000;
-}
-
-/**
- * Pure reporter for the per-Epic baseline-refresh commit rate.
- *
- * @param {Iterable<{
- *   sha?: string,
- *   isoDate: string,
- *   subject: string,
- *   epicId: number | string | null,
- * }>} commits
- *   Commit records from the caller. Records missing `epicId` (the commit
- *   isn't on any Epic branch) are dropped. Records older than the window
- *   are also dropped. Order does not matter — the function aggregates by
- *   Epic regardless of input ordering.
- *
- * @param {object} [opts]
- * @param {number} [opts.windowDays] — trailing window in days (default 28).
- * @param {() => Date | number} [opts.now] — clock injector for tests.
- *   Accepts either a Date or epoch-ms; defaults to `() => Date.now()`.
- *
- * @returns {{
- *   kind: 'baseline-refresh-rate',
- *   windowDays: number,
- *   generatedAt: string,
- *   cutoffAt: string,
- *   perEpic: Array<{
- *     epicId: number | string,
- *     storyMerges: number,
- *     baselineRefreshes: number,
- *     cleanMergeRate: number,
- *   }>,
- *   totals: {
- *     storyMerges: number,
- *     baselineRefreshes: number,
- *     cleanMergeRate: number,
- *   },
- * }}
- *
- * `cleanMergeRate` is the fraction of merged Stories that did NOT need a
- * baseline-refresh commit follow-up (or amend), in `[0, 1]` rounded to
- * 4 decimal places. The 90% target is `cleanMergeRate >= 0.9`. When
- * `storyMerges === 0`, the rate is `1` (vacuously clean — no Stories,
- * no drift) so a quiet Epic doesn't show up as red.
- */
-export function computeBaselineRefreshRate(commits, opts = {}) {
-  const nowFn = opts.now ?? (() => Date.now());
-  const nowVal = nowFn();
-  const nowMs = nowVal instanceof Date ? nowVal.getTime() : Number(nowVal);
-  const windowDays =
-    Number.isFinite(opts.windowDays) && opts.windowDays > 0
-      ? Math.floor(opts.windowDays)
-      : DEFAULT_WINDOW_DAYS;
-  const cutoffMs = computeCutoffMs(nowMs, windowDays);
-
-  // Map<epicId, { storyMerges, baselineRefreshes }>. Insertion order is
-  // preserved so the output array is stable for snapshot-style assertions.
-  const perEpic = new Map();
-  const ensureBucket = (epicId) => {
-    if (!perEpic.has(epicId)) {
-      perEpic.set(epicId, { storyMerges: 0, baselineRefreshes: 0 });
-    }
-    return perEpic.get(epicId);
-  };
-
-  for (const raw of commits ?? []) {
-    if (!isObject(raw)) continue;
-    const epicId = raw.epicId;
-    if (epicId == null || epicId === '') continue;
-    const ts = toEpochMs(raw.isoDate);
-    if (!Number.isFinite(ts)) continue;
-    if (ts < cutoffMs) continue;
-
-    const klass = classifySubject(raw.subject);
-    if (klass === 'other') continue;
-
-    const bucket = ensureBucket(epicId);
-    if (klass === 'refresh') bucket.baselineRefreshes += 1;
-    else if (klass === 'story') bucket.storyMerges += 1;
-  }
-
-  const perEpicRows = [];
-  let totalStories = 0;
-  let totalRefreshes = 0;
-  for (const [epicId, counts] of perEpic) {
-    const cleanMergeRate =
-      counts.storyMerges === 0
-        ? 1
-        : Math.max(
-            0,
-            Math.min(
-              1,
-              (counts.storyMerges - counts.baselineRefreshes) /
-                counts.storyMerges,
-            ),
-          );
-    perEpicRows.push({
-      epicId,
-      storyMerges: counts.storyMerges,
-      baselineRefreshes: counts.baselineRefreshes,
-      cleanMergeRate: roundRate(cleanMergeRate),
-    });
-    totalStories += counts.storyMerges;
-    totalRefreshes += counts.baselineRefreshes;
-  }
-
-  const totalsClean =
-    totalStories === 0
-      ? 1
-      : Math.max(
-          0,
-          Math.min(1, (totalStories - totalRefreshes) / totalStories),
-        );
-
-  return {
-    kind: 'baseline-refresh-rate',
-    windowDays,
-    generatedAt: new Date(nowMs).toISOString(),
-    cutoffAt: new Date(cutoffMs).toISOString(),
-    perEpic: perEpicRows,
-    totals: {
-      storyMerges: totalStories,
-      baselineRefreshes: totalRefreshes,
-      cleanMergeRate: roundRate(totalsClean),
-    },
-  };
-}
-
-function roundRate(rate) {
-  if (!Number.isFinite(rate)) return 0;
-  return Math.round(rate * 10000) / 10000;
-}
-
-// Exported for unit tests that want to assert the classifier directly
-// without round-tripping through the aggregator.
-export const __test__ = {
-  classifySubject,
-  computeCutoffMs,
-  DEFAULT_WINDOW_DAYS,
-};