mandrel 1.57.0

package/.agents/scripts/lib/branch-name-guard.js

@@ -0,0 +1,98 @@
+/**
+ * branch-name-guard.js — Canonical branch-name safety assertion.
+ *
+ * Single source of truth for "is this string safe to forward to a `git`
+ * subprocess as a branch name?". Consolidates the duplicated assertion
+ * logic that previously lived in `git-branch-lifecycle.js` and
+ * `git-branch-cleanup.js`, so the two sites cannot drift apart.
+ *
+ * The default check is the **union** of every assertion either previous
+ * site performed:
+ *   - reject `null` / `undefined` / non-string values
+ *   - reject empty string
+ *   - reject any character outside `[a-zA-Z0-9._\-/]` (catches whitespace,
+ *     shell metacharacters, glob characters, etc.)
+ *   - reject leading `-` (would otherwise be parsed as a CLI flag by git,
+ *     even though the regex character class allows hyphens elsewhere)
+ *
+ * Callers performing destructive operations (`branch -D`, `push --delete`)
+ * can opt into the protected-branch deny list by passing `{ protected: true }`,
+ * which additionally rejects `main`, `master`, `HEAD`, and any name
+ * starting with `refs/`.
+ *
+ * All exports are pure: they read no config, spawn no subprocesses, and
+ * make no network calls.
+ */
+
+import { isSafeBranchComponent } from './dependency-parser.js';
+
+/**
+ * Names that must never be forwarded to a destructive git operation.
+ * The set is exposed as a frozen object so callers can introspect.
+ */
+export const PROTECTED_BRANCH_NAMES = Object.freeze(['main', 'master', 'HEAD']);
+
+/**
+ * Pure predicate: returns `true` iff `name` is safe to forward to a git
+ * subprocess as a branch name. Does not throw.
+ *
+ * @param {unknown} name
+ * @param {{ protected?: boolean }} [opts]
+ *   When `opts.protected` is `true`, additionally reject `main`,
+ *   `master`, `HEAD`, and `refs/*` (used by destructive callers).
+ * @returns {boolean}
+ */
+export function isSafeBranchName(name, opts = {}) {
+  if (typeof name !== 'string') return false;
+  if (name.length === 0) return false;
+  if (name.startsWith('-')) return false;
+  if (!isSafeBranchComponent(name)) return false;
+  if (opts.protected) {
+    if (PROTECTED_BRANCH_NAMES.includes(name)) return false;
+    if (name.startsWith('refs/')) return false;
+  }
+  return true;
+}
+
+/**
+ * Throwing assertion for one or more branch names. Use this from any
+ * helper that is about to forward `name` to git. The error message
+ * includes the offending value verbatim so operators can grep logs.
+ *
+ * Pass `{ protected: true }` as the **last argument** to additionally
+ * reject `main` / `master` / `HEAD` / `refs/*` — recommended for any
+ * caller about to invoke a destructive git operation.
+ *
+ * @param {...(unknown | { protected?: boolean })} args
+ * @throws {Error} when any name fails {@link isSafeBranchName}.
+ * @returns {void}
+ */
+export function assertBranchSafe(...args) {
+  let opts = {};
+  let names = args;
+  const last = args[args.length - 1];
+  if (
+    last !== null &&
+    typeof last === 'object' &&
+    !Array.isArray(last) &&
+    ('protected' in last || Object.keys(last).length === 0)
+  ) {
+    opts = last;
+    names = args.slice(0, -1);
+  }
+  for (const name of names) {
+    if (!isSafeBranchName(name, opts)) {
+      const repr = typeof name === 'string' ? `"${name}"` : String(name);
+      const protectedNote = opts.protected
+        ? ' This site rejects protected refs (main, master, HEAD, refs/*).'
+        : '';
+      throw new Error(
+        `[branch-name-guard] Unsafe branch name detected: ${repr}. ` +
+          'Branch names must be non-empty strings containing only ' +
+          'alphanumeric characters, hyphens, underscores, dots, and ' +
+          'slashes, and must not begin with "-".' +
+          protectedNote,
+      );
+    }
+  }
+}

package/.agents/scripts/lib/c8-cli-path.js

@@ -0,0 +1,21 @@
+/**
+ * Resolves c8's CLI entry point so callers can spawn it via
+ * `process.execPath <c8Cli>` (shell:false) instead of routing through
+ * the `npx.cmd` shim, which would force shell:true under
+ * CVE-2024-27980's .cmd/.bat policy and re-open CWE-78.
+ *
+ * `bin/c8.js` is not exported from c8's package.json, so the lookup
+ * goes through `package.json` (always in the exports map) and
+ * `path.join` to its sibling bin file.
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+export const C8_CLI = path.join(
+  path.dirname(require.resolve('c8/package.json')),
+  'bin',
+  'c8.js',
+);

package/.agents/scripts/lib/changed-files.js

@@ -0,0 +1,184 @@
+import { createGitInterface } from './git-utils.js';
+
+/**
+ * Parse the stdout from `git diff --name-only` into a normalized file list.
+ * Trims whitespace, drops blank lines, and converts backslash separators to
+ * forward slashes so set-membership checks line up with the paths produced by
+ * `scanAndScore` and `calculateAll` on Windows checkouts.
+ *
+ * Pure; no I/O.
+ *
+ * @param {string | null | undefined} stdout
+ * @returns {string[]}
+ */
+export function parseNameOnlyStdout(stdout) {
+  if (!stdout) return [];
+  return stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => line.replace(/\\/g, '/'));
+}
+
+/**
+ * Low-level helper: run `git diff --name-only <range>` and return the
+ * forward-slash-normalised file list. Throws on non-zero git exit so callers
+ * that must fail-closed can propagate the error; callers that prefer
+ * best-effort behaviour wrap this in a try/catch.
+ *
+ * Accepts either a pre-built `range` string **or** `baseRef`+`headRef`
+ * (assembled into `<baseRef>...<headRef>` when `threeDot` is true, or
+ * `<baseRef>..<headRef>` otherwise). When both `range` and
+ * `baseRef`/`headRef` are supplied, `range` takes precedence.
+ *
+ * The `gitSpawn` injection matches the signature used by `createGitInterface`:
+ * `(cwd: string, ...gitArgs: string[]) => { status: number, stdout: string, stderr: string }`.
+ * Production callers omit it (the default uses `createGitInterface({})`);
+ * tests pass a stub.
+ *
+ * @param {object} params
+ * @param {string} [params.range]         Pre-built range string (e.g. `"epic/3599...story-3636"`).
+ * @param {string} [params.baseRef]       Left-hand ref — used when `range` is absent.
+ * @param {string} [params.headRef='HEAD'] Right-hand ref — used when `range` is absent.
+ * @param {boolean} [params.threeDot=true] Use three-dot (`...`) merge-base semantics
+ *   when `range` is absent. Set to `false` for a two-dot direct diff.
+ * @param {string} [params.cwd=process.cwd()]
+ * @param {((cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string }) | null} [params.gitSpawn]
+ * @returns {string[]} Forward-slash-normalised repo-relative paths.
+ * @throws {Error} When git exits non-zero.
+ */
+export function diffNameOnly({
+  range,
+  baseRef,
+  headRef = 'HEAD',
+  threeDot = true,
+  cwd = process.cwd(),
+  gitSpawn,
+} = {}) {
+  const resolvedRange =
+    range ?? `${baseRef}${threeDot ? '...' : '..'}${headRef}`;
+  const spawnFn = gitSpawn ?? createGitInterface({}).gitSpawn;
+  const res = spawnFn(cwd, 'diff', '--name-only', resolvedRange);
+  if (res.status !== 0) {
+    const detail = res.stderr || res.stdout || `exit ${res.status}`;
+    throw new Error(
+      `[diff-name-only] git diff --name-only ${resolvedRange} failed: ${detail}`,
+    );
+  }
+  return parseNameOnlyStdout(res.stdout);
+}
+
+/**
+ * Resolve the list of files changed since `ref` relative to the current HEAD.
+ *
+ * Used by `check-crap.js` and `check-maintainability.js` to implement the
+ * `--changed-since <ref>` diff-scoped mode — the quality gates limit both
+ * scoring and comparison to this file set so the pre-push / PR CI feedback
+ * loop stays fast on large consumer repos.
+ *
+ * Semantics:
+ *   - Runs `git diff --name-only <ref>...HEAD` so the comparison is against
+ *     the merge-base (three-dot range). This matches how GitHub computes the
+ *     "files changed" view for a PR and deliberately excludes anything that
+ *     was merged into the base branch after the PR branched off.
+ *   - Returns relative paths with forward-slash separators so set-membership
+ *     checks line up with the normalized paths produced by `scanAndScore` and
+ *     `calculateAll` on Windows checkouts.
+ *   - A non-zero git exit is surfaced as a thrown Error — `--changed-since`
+ *     must **never** silently degrade to "no regressions found"; that is the
+ *     entire reason the CLIs fail closed on a bad ref.
+ *
+ * @param {object} [params]
+ * @param {string} [params.ref='main']         The ref to diff against.
+ * @param {string} [params.cwd=process.cwd()]  Repo working directory.
+ * @param {ReturnType<typeof createGitInterface>} [params.git] Injected git
+ *   interface — production callers omit this; tests pass a mock.
+ * @returns {string[]} Relative, forward-slash-normalized file paths. Order is
+ *   whatever `git diff --name-only` produces (stable per invocation).
+ * @throws {Error} When git exits non-zero (unresolvable ref, corrupt repo,
+ *   etc.). The error message names the ref so the operator can react without
+ *   re-reading the CLI flags.
+ */
+export function getChangedFiles({
+  ref = 'main',
+  cwd = process.cwd(),
+  git,
+} = {}) {
+  const gitIface = git ?? createGitInterface({});
+  const res = gitIface.gitSpawn(cwd, 'diff', '--name-only', `${ref}...HEAD`);
+  if (res.status !== 0) {
+    const detail = res.stderr || res.stdout || `exit ${res.status}`;
+    throw new Error(
+      `[changed-since] unable to resolve ref "${ref}": ${detail}`,
+    );
+  }
+  return parseNameOnlyStdout(res.stdout);
+}
+
+/**
+ * Resolve paths in the index (staged for commit). Used by `quality-preview
+ * --staged` so pre-commit gates score only the commit payload, not unstaged
+ * working-tree edits.
+ *
+ * Semantics:
+ *   - Runs `git diff --name-only --cached`.
+ *   - Returns forward-slash-normalized repo-relative paths.
+ *   - Non-zero git exit throws — staged mode must not silently widen scope.
+ *
+ * @param {object} [params]
+ * @param {string} [params.cwd=process.cwd()]
+ * @param {ReturnType<typeof createGitInterface>} [params.git]
+ * @returns {string[]}
+ */
+export function getStagedFiles({ cwd = process.cwd(), git } = {}) {
+  const gitIface = git ?? createGitInterface({});
+  const res = gitIface.gitSpawn(cwd, 'diff', '--name-only', '--cached');
+  if (res.status !== 0) {
+    const detail = res.stderr || res.stdout || `exit ${res.status}`;
+    throw new Error(`[staged] unable to read cached diff: ${detail}`);
+  }
+  return parseNameOnlyStdout(res.stdout);
+}
+
+/**
+ * Resolve the file set for quality-preview runners.
+ *
+ * When `staged` is true, only index paths are returned and `changedSinceRef`
+ * is ignored. Otherwise a `changedSinceRef` limits to that three-dot diff;
+ * when both are absent the caller runs in full-repo mode (`scopeSet: null`).
+ *
+ * @param {object} [params]
+ * @param {boolean} [params.staged=false]
+ * @param {string | null} [params.changedSinceRef=null]
+ * @param {string} [params.cwd=process.cwd()]
+ * @param {ReturnType<typeof createGitInterface>} [params.git]
+ * @returns {{
+ *   scopeSet: Set<string> | null,
+ *   scope: 'staged' | 'diff' | 'full',
+ *   diffRef: string | null,
+ * }}
+ */
+export function resolvePreviewScope({
+  staged = false,
+  changedSinceRef = null,
+  cwd = process.cwd(),
+  git,
+} = {}) {
+  if (staged) {
+    const files = getStagedFiles({ cwd, git });
+    return { scopeSet: new Set(files), scope: 'staged', diffRef: null };
+  }
+  if (changedSinceRef) {
+    try {
+      const files = getChangedFiles({ ref: changedSinceRef, cwd, git });
+      return {
+        scopeSet: new Set(files),
+        scope: 'diff',
+        diffRef: changedSinceRef,
+      };
+    } catch {
+      return { scopeSet: new Set(), scope: 'diff', diffRef: changedSinceRef };
+    }
+  }
+  return { scopeSet: null, scope: 'full', diffRef: null };
+}

package/.agents/scripts/lib/checks/baseline-drift-main-checkout.js

@@ -0,0 +1,104 @@
+/**
+ * baseline-drift-main-checkout — refuse-and-print check.
+ *
+ * Detects the close-validation-main-drift failure mode where `story-close`
+ * (or any close-validation step) runs against the **main checkout** while a
+ * corresponding worktree exists. The active branch in the main checkout is
+ * usually drifted from the Story branch by stale formatting / MI-baseline
+ * commits, and the close validation then refuses to merge.
+ *
+ * Pre-existing epic-branch format drift blocks every story close when the
+ * validator hits the main checkout.
+ *
+ * Surface: `story-close` preflight and the `/diagnose` CLI. Surfaced as a
+ * blocker — if the validator is running against the wrong tree, none of the
+ * downstream gates are reliable.
+ *
+ * AutoCorrect is `refuse-and-print`. The fix is for the *operator* to `cd`
+ * into the worktree; an auto-fix would mutate the process's cwd, which is
+ * a footgun no other check assumes.
+ *
+ * Detection logic:
+ *   1. If headRef is not a story branch (`story-<n>`), the check does not
+ *      apply — only story-close runs in this scope, and only against a
+ *      story branch. Returns null.
+ *   2. If a worktree at `.worktrees/<headRef>/` does NOT exist, the check
+ *      cannot say anything — the operator may legitimately be running in
+ *      single-tree mode. Returns null.
+ *   3. If the active cwd is the worktree path, all good. Returns null.
+ *   4. Otherwise the validator is running against a different tree (the
+ *      main checkout) while the worktree exists. Returns a blocker with
+ *      the `cd <worktree>` recipe.
+ */
+
+import path from 'node:path';
+import { isStoryBranch as isFlatStoryBranch } from '../git-utils.js';
+
+const ID = 'baseline-drift-main-checkout';
+
+export default {
+  id: ID,
+  severity: 'blocker',
+  scope: ['story-close', 'diagnose'],
+  autoCorrect: 'refuse-and-print',
+  detect(state) {
+    const headRef = state?.git?.headRef ?? null;
+    if (!headRef || !isStoryBranch(headRef)) return null;
+    const worktreePaths = state?.fs?.worktreePaths ?? [];
+    if (!Array.isArray(worktreePaths) || worktreePaths.length === 0) {
+      return null;
+    }
+    const expected = worktreePaths.find((p) => path.basename(p) === headRef);
+    if (!expected) return null; // worktree for this branch doesn't exist
+    const cwd = state?.cwd ?? '';
+    if (samePath(cwd, expected)) return null; // already in the worktree
+    return {
+      id: ID,
+      severity: 'blocker',
+      scope: state?.scope ?? '',
+      summary: `Close-validation running outside worktree (cwd: ${cwd}, expected: ${expected})`,
+      detail: [
+        `The active branch is ${headRef} and a worktree exists at ${expected},`,
+        `but the current working directory is ${cwd}.`,
+        '',
+        'Close-validation must run inside the Story worktree — the main checkout',
+        'may carry stale formatting or MI-baseline drift that will fail validation',
+        'even when the Story branch is clean.',
+      ].join('\n'),
+      fixCommand: `cd "${expected}"`,
+      autoCorrectable: false,
+    };
+  },
+};
+
+/**
+ * Story branches use a flat `story-<n>` shape; the older
+ * `story/epic-<id>/<n>` layout no longer applies. Accept both for forward
+ * compatibility.
+ *
+ * @param {string} ref
+ * @returns {boolean}
+ */
+function isStoryBranch(ref) {
+  return isFlatStoryBranch(ref) || /^story\/epic-\d+\/\d+$/.test(ref);
+}
+
+/**
+ * Compare two paths normalized for the platform. Windows is case-insensitive
+ * and uses backslashes; POSIX is case-sensitive. We normalize both sides
+ * with `path.resolve` so the comparison is stable regardless of trailing
+ * separators or `./` prefixes.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function samePath(a, b) {
+  if (!a || !b) return false;
+  const na = path.resolve(a);
+  const nb = path.resolve(b);
+  if (process.platform === 'win32') {
+    return na.toLowerCase() === nb.toLowerCase();
+  }
+  return na === nb;
+}

package/.agents/scripts/lib/checks/core-bare-clean.js

@@ -0,0 +1,48 @@
+/**
+ * core-bare-clean — refuse-and-print blocker check.
+ *
+ * Asserts that `git config core.bare` on the main checkout is NOT set
+ * to `true`. This guards the old failure mode where an `npm test` path
+ * mis-set `core.bare=true` on the main checkout, after which
+ * `story-close.js`'s post-rebase `git checkout` aborted with
+ * `fatal: this operation must be run in a work tree`. `cleanGitEnv`
+ * already lands the live fix; this check is the regression guard.
+ *
+ * Severity is `blocker` because story-close cannot recover on its own
+ * — the operator must run `git config --unset core.bare` (or rely on
+ * `cleanGitEnv` to do it before the rebase). The check is
+ * refuse-and-print: the `fixCommand` is the literal unset, and the
+ * operator runs it deliberately. We do not auto-fix because mutating
+ * the parent repo's git config from a check is exactly the
+ * "no commits to integration branches" cousin of the autoCorrect
+ * disallowed list — config writes outside the local worktree boundary.
+ *
+ * Detection reads `state.git.coreBare`, the string returned by
+ * `git config --get core.bare` (or `null` when unset). The check fires
+ * when the string is the literal `'true'`.
+ */
+export default {
+  id: 'core-bare-clean',
+  severity: 'blocker',
+  scope: ['story-close', 'retro'],
+  autoCorrect: 'refuse-and-print',
+  detect(state) {
+    const coreBare = state?.git?.coreBare;
+    if (coreBare !== 'true') return null;
+    return {
+      id: 'core-bare-clean',
+      severity: 'blocker',
+      scope: state?.scope ?? 'story-close',
+      summary:
+        'core.bare=true on main checkout; story-close post-rebase checkout will abort',
+      detail: [
+        'cleanGitEnv normally unsets this before the rebase. If you are',
+        'seeing this surface, cleanGitEnv did not run (e.g. a pre-fix code',
+        'path) or the value was re-set after it ran. Unset it manually and',
+        're-run the close.',
+      ].join('\n'),
+      fixCommand: 'git config --unset core.bare  # or rely on cleanGitEnv',
+      autoCorrectable: false,
+    };
+  },
+};

package/.agents/scripts/lib/checks/epic-merge-lock-stale.js

@@ -0,0 +1,54 @@
+/**
+ * epic-merge-lock-stale — refuse-and-print warning check.
+ *
+ * Detects orphan `epic-<id>.merge.lock` files left behind by a crashed
+ * or hung `withEpicMergeLock()` holder. The live serialization path is
+ * owned by `lib/epic-merge-lock.js` itself; this check intentionally
+ * does NOT serialize against it. Instead, at preflight time it probes
+ * the lock file for each known epic and surfaces a warning when:
+ *
+ *   - the lock file exists, AND
+ *   - the recorded holder PID is not alive (per `process.kill(pid, 0)`).
+ *
+ * Severity is `warning` rather than `blocker` because the live lock
+ * implementation already steals stale locks on its own (per
+ * `tryStealStale()` in epic-merge-lock.js). Surfacing the residue
+ * earlier just helps operators diagnose hung CI runs before they
+ * snowball into wave-aggregation timeouts. The fix is a literal
+ * `rm <lockPath>` — refuse-and-print so the operator runs it
+ * deliberately.
+ *
+ * Reads `state.fs.epicMergeLocks`, a map of `epicId → { exists, pid,
+ * holderAlive, path, ... }` populated by state.js.
+ */
+export default {
+  id: 'epic-merge-lock-stale',
+  severity: 'warning',
+  scope: ['story-close', 'retro'],
+  autoCorrect: 'refuse-and-print',
+  detect(state) {
+    const locks = state?.fs?.epicMergeLocks ?? {};
+    for (const [epicId, info] of Object.entries(locks)) {
+      if (!info?.exists) continue;
+      if (info.holderAlive) continue;
+      // Lock exists and the holder PID is not alive — orphan.
+      return {
+        id: 'epic-merge-lock-stale',
+        severity: 'warning',
+        scope: state?.scope ?? 'story-close',
+        summary: `Orphan epic merge lock for epic/${epicId} (holder PID ${info.pid ?? 'unknown'} not alive)`,
+        detail: [
+          `lock path: ${info.path}`,
+          `holder pid: ${info.pid ?? 'unknown'}`,
+          info.acquiredAt
+            ? `acquired at: ${new Date(info.acquiredAt).toISOString()}`
+            : 'acquired at: unknown',
+          'The live lock will steal this on next contention, but the residue can be cleared manually.',
+        ].join('\n'),
+        fixCommand: `rm "${info.path}"`,
+        autoCorrectable: false,
+      };
+    }
+    return null;
+  },
+};