mandrel 1.57.0

package/.agents/scripts/update-mutation-baseline.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * update-mutation-baseline.js — Refresh `baselines/mutation.json` from a
+ * fresh Stryker run (Story #1736, Task #1752 + #1753).
+ *
+ * Reads the configured mutation gate (`delivery.quality.gates.mutation`),
+ * invokes the Stryker runner from `lib/mutation/stryker-runner.js`, and
+ * atomically rewrites the baseline file with the new per-workspace
+ * mutation scores. Preserves the configured `tolerancePct` (from the
+ * gate's `tolerance.value`) so the file is self-contained — consumers
+ * don't need to read `.agentrc.json` to interpret the baseline.
+ *
+ * Exit codes:
+ *   0 — baseline refreshed (didChange true) or no change (didChange false)
+ *   0 — Stryker skipped (no config) with an explanatory line on stderr
+ *   1 — Stryker invocation failed
+ *
+ * The refresh is intentionally non-fatal when Stryker is not configured:
+ * the operator can run `npx stryker init` and re-invoke this script.
+ *
+ * DORMANT BY DESIGN (Story #3665). This script and the rest of the
+ * mutation-testing surface ship built-but-unwired: Mandrel declares no
+ * `delivery.quality.gates.mutation` block and no `stryker.conf.*`, so the
+ * gate never enters the `check-baselines` pipeline and this refresh
+ * self-skips (no Stryker config detected). The dormancy is an evaluated,
+ * intentional opt-in — not an oversight. A spike (Story #3665) concluded
+ * DEFER on activation. The essential rationale, preserved here so it does
+ * not depend on a point-in-time writeup:
+ *
+ *   - Cost model: a full `.agents/scripts` Stryker baseline is a
+ *     tens-of-minutes-to-multi-hour job even under `coverageAnalysis:
+ *     'perTest'` at `concurrency: 8`. Stryker reruns the affected test set
+ *     once per mutant (~5,000–6,500 mutants over ~19k effective LOC), and
+ *     Mandrel's tests live in a sibling `tests/` tree (not colocated with
+ *     source), so there is no cheap per-source-file partition for `perTest`
+ *     to exploit. Activation therefore belongs on a nightly `schedule`
+ *     (never per-PR), with PR-time `check-baselines` consuming the
+ *     nightly-produced baseline as a read-only ratchet.
+ *   - Baseline-shape fit: the kernel/check side keys mutation rows by
+ *     `path` (`lib/baselines/kinds/mutation.js` — per-file rows + per-
+ *     component rollup, the right fit for this single-package repo), but
+ *     this refresh writer (`lib/mutation/baseline-snapshot.js`) emits a
+ *     workspace-keyed `{ workspaces: { '*': score } }` snapshot that
+ *     collapses to one repo-wide number with zero per-file resolution.
+ *     The two shapes do not agree; activation must first reconcile this
+ *     writer to emit the kernel's path-keyed `rows[]`/`rollup` envelope.
+ *   - Prerequisites: a `node --test` Stryker runner integration (no
+ *     first-party `@stryker-mutator` plugin exists for the Node built-in
+ *     runner), the shape reconciliation above, and nightly CI plumbing —
+ *     together an Epic-sized effort, not a config flip.
+ *
+ * Re-evaluate (promote to an activation Epic) when a coverage-gamed
+ * regression ships, the project migrates to a test runner with first-party
+ * Stryker support, or an operator opts in for a specific high-risk subtree.
+ */
+
+import path from 'node:path';
+
+import { resolveDiffScope } from './lib/baselines/diff-scope-cli.js';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  getQuality,
+  PROJECT_ROOT,
+  resolveConfig,
+} from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  DEFAULT_BASELINE_PATH,
+  DEFAULT_TOLERANCE_PCT,
+  writeBaseline,
+} from './lib/mutation/baseline-snapshot.js';
+import { runStryker } from './lib/mutation/stryker-runner.js';
+
+/**
+ * Resolve the mutation gate config relevant to baseline refresh.
+ *
+ * @param {object} config Canonical resolved config (`resolveConfig()` output).
+ * @returns {{ baselinePath: string, tolerancePct: number, strykerConfigPath: string | null }}
+ */
+export function resolveMutationGate(config) {
+  const quality = getQuality(config);
+  const gate = quality.gates?.mutation ?? {};
+  const baselinePath =
+    typeof gate.baselinePath === 'string' && gate.baselinePath.length > 0
+      ? gate.baselinePath
+      : DEFAULT_BASELINE_PATH;
+  const tol = gate.tolerance;
+  const tolerancePct =
+    tol &&
+    typeof tol === 'object' &&
+    Number.isFinite(tol.value) &&
+    tol.value >= 0
+      ? tol.value
+      : DEFAULT_TOLERANCE_PCT;
+  const strykerConfigPath =
+    typeof gate.strykerConfigPath === 'string' &&
+    gate.strykerConfigPath.length > 0
+      ? gate.strykerConfigPath
+      : null;
+  return { baselinePath, tolerancePct, strykerConfigPath };
+}
+
+/**
+ * @param {{
+ *   cwd?: string,
+ *   runStrykerFn?: typeof runStryker,
+ *   writeBaselineFn?: typeof writeBaseline,
+ *   resolveConfigFn?: typeof resolveConfig,
+ *   logger?: { info?: (m: string) => void, warn?: (m: string) => void, error?: (m: string) => void },
+ * }} [opts]
+ * @returns {Promise<{ status: 0 | 1, didChange: boolean, skipped: boolean, reason?: string, baselinePath: string }>}
+ */
+export async function refreshMutationBaseline({
+  cwd = PROJECT_ROOT,
+  runStrykerFn = runStryker,
+  writeBaselineFn = writeBaseline,
+  resolveConfigFn = resolveConfig,
+  logger = Logger,
+} = {}) {
+  const config = resolveConfigFn({ cwd });
+  const gate = resolveMutationGate(config);
+  const absBaseline = path.isAbsolute(gate.baselinePath)
+    ? gate.baselinePath
+    : path.resolve(cwd, gate.baselinePath);
+
+  logger.info?.(`[mutation] refreshing baseline → ${gate.baselinePath}`);
+  const runResult = await runStrykerFn({
+    cwd,
+    configPath: gate.strykerConfigPath,
+  });
+  if (runResult.skipped) {
+    logger.info?.(
+      `[mutation] skipped — ${runResult.reason ?? 'runner reported skip'}`,
+    );
+    return {
+      status: 0,
+      didChange: false,
+      skipped: true,
+      reason: runResult.reason ?? 'runner-skip',
+      baselinePath: absBaseline,
+    };
+  }
+  if (!runResult.ok) {
+    logger.error?.(
+      `[mutation] Stryker invocation failed: ${runResult.error ?? 'unknown error'}`,
+    );
+    return {
+      status: 1,
+      didChange: false,
+      skipped: false,
+      reason: runResult.error ?? 'stryker-failed',
+      baselinePath: absBaseline,
+    };
+  }
+
+  const writeResult = writeBaselineFn(absBaseline, {
+    tolerancePct: gate.tolerancePct,
+    workspaces: runResult.byWorkspace,
+  });
+
+  if (writeResult.didChange) {
+    logger.info?.(`[mutation] baseline updated at ${gate.baselinePath}`);
+  } else {
+    logger.info?.(`[mutation] baseline unchanged at ${gate.baselinePath}`);
+  }
+
+  return {
+    status: 0,
+    didChange: writeResult.didChange,
+    skipped: false,
+    baselinePath: absBaseline,
+  };
+}
+
+async function main() {
+  // Story #1974 — `--diff-scope` accepted for CLI parity with other
+  // update-*-baseline scripts; no row-narrowing effect because mutation
+  // baseline is workspace-keyed (not file-keyed).
+  const diffScope = resolveDiffScope({ argv: process.argv.slice(2) });
+  if (diffScope) {
+    Logger.info(
+      `[mutation] --diff-scope ${diffScope.ref}: noted (informational only).`,
+    );
+  }
+  const result = await refreshMutationBaseline();
+  if (result.status !== 0) process.exit(result.status);
+}
+
+runAsCli(import.meta.url, main, { source: 'update-mutation-baseline' });

package/.agents/scripts/update-ticket-state.js

@@ -0,0 +1,107 @@
+/**
+ * .agents/scripts/update-ticket-state.js — CLI Re-export Shim
+ *
+ * Thin backward-compatibility shim. The core logic has been moved to
+ * `lib/orchestration/ticketing.js` as part of the SDK refactor.
+ *
+ * This file preserves backward compatibility for CLI usage and existing
+ * testing patterns.
+ *
+ * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
+ */
+
+import { parseArgs } from 'node:util';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  cascadeCompletion,
+  STATE_LABELS,
+  transitionTicketState,
+} from './lib/orchestration/ticketing.js';
+import { createProvider } from './lib/provider-factory.js';
+
+// ── CLI Main Block ────────────────────────────────────────────────────────
+// cli-opt-out: re-export shim with a DEBUG_MAIN escape hatch for tests; runAsCli's strict path-equality guard would block the env-flag entry path.
+if (
+  process.argv[1]?.endsWith('update-ticket-state.js') ||
+  process.env.DEBUG_MAIN
+) {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      task: { type: 'string' },
+      ticket: { type: 'string' },
+      state: { type: 'string' },
+      'remove-label': { type: 'string' },
+    },
+    strict: false,
+  });
+
+  // `--ticket` is the v5.9.0 alias for `--task` (labels can apply to any
+  // ticket type, not just Tasks). Both continue to work.
+  const idSource = values.ticket ?? values.task;
+  const ticketId = Number.parseInt(idSource, 10);
+  const state = values.state;
+  const removeLabel = values['remove-label'];
+
+  if (Number.isNaN(ticketId) || (!state && !removeLabel)) {
+    throw new Error(
+      'Usage: node update-ticket-state.js ' +
+        '(--ticket|--task) <id> ' +
+        '[--state <state> | --remove-label <label>]',
+    );
+  }
+
+  (async () => {
+    const config = resolveConfig();
+    const provider = createProvider(config);
+
+    // Label-only mutation path — no state transition. Callers that just
+    // need to drop a single label without flipping the agent::* state.
+    if (removeLabel && !state) {
+      Logger.info(
+        `[State-Sync] Removing label \`${removeLabel}\` from ticket #${ticketId}...`,
+      );
+      await provider.updateTicket(ticketId, {
+        labels: { remove: [removeLabel] },
+      });
+      Logger.info('[State-Sync] ✅ Success');
+      return;
+    }
+
+    Logger.info(
+      `[State-Sync] Transitioning ticket #${ticketId} to ${state}...`,
+    );
+    await transitionTicketState(provider, ticketId, state);
+
+    if (state === STATE_LABELS.DONE) {
+      Logger.info(`[State-Sync] Cascading completion from #${ticketId}...`);
+      const cascade = await cascadeCompletion(provider, ticketId);
+      // Hoisted out of the `for...of` initializer because typhonjs-escomplex
+      // mis-parses optional chaining there (it would zero out this file's
+      // maintainability score).
+      const cascadeFailures = cascade?.failed ?? [];
+      for (const { parentId, error } of cascadeFailures) {
+        Logger.warn(
+          `[State-Sync] ⚠️  Cascade partial-failure on parent #${parentId}: ${error}`,
+        );
+      }
+    }
+
+    // Optional secondary label removal alongside the state transition
+    // (e.g. clear `status::blocked` when transitioning back to ready).
+    if (removeLabel) {
+      await provider.updateTicket(ticketId, {
+        labels: { remove: [removeLabel] },
+      });
+    }
+
+    Logger.info('[State-Sync] ✅ Success');
+  })().catch((err) => {
+    // Re-throw as an unhandled rejection so Node exits with a non-zero
+    // status. Per orchestration-error-handling rule, orchestrator CLIs MUST
+    // surface failures via throw rather than Logger.fatal so a stubbed
+    // process.exit (in tests) does not silently mask the error.
+    throw new Error(err.message);
+  });
+}

package/.agents/scripts/validate-docs-freshness.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- pre-push docs-freshness gate; pure git-mtime walk with no testable branching beyond filesystem state */
+
+/**
+ * .agents/scripts/validate-docs-freshness.js — Documentation Freshness Gate
+ *
+ * For each doc in `delivery.docsFreshness.paths` + `project.docsContextFiles`, verify
+ * that the file was meaningfully updated during this Epic's lifecycle. A
+ * file passes when **either** of the following holds:
+ *
+ *   1. `git log --all --grep="#<epicId>" -- <file>` returns a commit —
+ *      the Epic ID was referenced in a commit message that touched the
+ *      file.
+ *   2. The file's current body contains `#<epicId>` — a human annotation
+ *      (e.g., a CHANGELOG entry) explicitly ties the change to this Epic.
+ *
+ * The prior gate accepted any diff against the base branch — a stray
+ * whitespace edit or a one-line unrelated cleanup passed, defeating the
+ * purpose of the check. Requiring an Epic-ID reference makes "did you
+ * update the docs for this Epic?" a falsifiable question instead of a
+ * checkbox.
+ *
+ * Usage:
+ *   node .agents/scripts/validate-docs-freshness.js --epic <EPIC_ID> [--base main] [--docs <comma-separated>] [--json]
+ *
+ * `--json` emits a single JSON object on stdout with
+ *   { ok, epicId, results: [{ file, pass, reason }, ...] }
+ * and suppresses the human-readable log lines. Intended for LLM/tool consumers
+ * that need to enumerate failing files without parsing log output.
+ *
+ * Exit codes:
+ *   0 — every doc has an Epic-ID reference.
+ *   1 — one or more docs have no reference.
+ *   2 — configuration error.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  getPaths,
+  PROJECT_ROOT,
+  resolveConfig,
+} from './lib/config-resolver.js';
+import { gitSpawn } from './lib/git-utils.js';
+import { Logger } from './lib/Logger.js';
+
+/**
+ * Resolve the canonical doc list for a release: `delivery.docsFreshness.paths`
+ * entries plus `project.docsContextFiles` prefixed by `project.paths.docsRoot`.
+ * Expects the full resolved config (`{ project, delivery, ... }`).
+ *
+ * @param {object} config
+ * @returns {string[]}
+ */
+export function resolveDocList(config) {
+  // Read from new shape first; fall back to the legacy shim/bag.
+  const project = config?.project ?? config;
+  const delivery = config?.delivery ?? null;
+  const docsFreshnessPaths = Array.isArray(delivery?.docsFreshness?.paths)
+    ? delivery.docsFreshness.paths
+    : Array.isArray(config?.release?.docs)
+      ? config.release.docs
+      : [];
+  const contextDocs = Array.isArray(project?.docsContextFiles)
+    ? project.docsContextFiles
+    : Array.isArray(config?.docsContextFiles)
+      ? config.docsContextFiles
+      : [];
+  const docsRoot = getPaths(config).docsRoot ?? 'docs';
+  const resolved = [
+    ...docsFreshnessPaths,
+    ...contextDocs.map((f) => path.posix.join(docsRoot, f)),
+  ];
+  return Array.from(new Set(resolved));
+}
+
+function epicRefMatcher(epicId) {
+  // Match `#N` as a standalone token. `(?!\d)` prevents `#10` from
+  // satisfying a search for `#1` — a subtle bug the prior diff-only gate
+  // never had to guard against.
+  return new RegExp(`#${epicId}(?!\\d)`);
+}
+
+function commitsMentioningEpic(docPath, epicId, cwd = PROJECT_ROOT) {
+  const res = gitSpawn(
+    cwd,
+    'log',
+    '--all',
+    `--grep=#${epicId}`,
+    '--pretty=format:%H',
+    '--',
+    docPath,
+  );
+  if (res.status !== 0) return [];
+  return (res.stdout ?? '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function fileBodyMentionsEpic(
+  docPath,
+  epicId,
+  cwd = PROJECT_ROOT,
+  readFileImpl = fs.readFileSync,
+) {
+  const abs = path.isAbsolute(docPath) ? docPath : path.join(cwd, docPath);
+  let body;
+  try {
+    body = readFileImpl(abs, 'utf8');
+  } catch {
+    return false;
+  }
+  return epicRefMatcher(epicId).test(body);
+}
+
+/**
+ * Run the freshness gate against every resolved doc. Pure; takes
+ * everything it needs as inputs so tests don't need a worktree.
+ *
+ * @param {{
+ *   epicId: number,
+ *   docs: string[],
+ *   cwd?: string,
+ *   readFileImpl?: typeof fs.readFileSync,
+ *   commitsForFile?: (doc: string, epicId: number, cwd: string) => string[],
+ * }} opts
+ * @returns {{ ok: boolean, results: Array<{ file: string, pass: boolean, reason: string }> }}
+ */
+export function runFreshnessGate({
+  epicId,
+  docs,
+  cwd = PROJECT_ROOT,
+  readFileImpl = fs.readFileSync,
+  commitsForFile = commitsMentioningEpic,
+}) {
+  const results = docs.map((file) => {
+    const commits = commitsForFile(file, epicId, cwd);
+    if (commits.length > 0) {
+      return {
+        file,
+        pass: true,
+        reason: `${commits.length} commit(s) reference Epic #${epicId}`,
+      };
+    }
+    if (fileBodyMentionsEpic(file, epicId, cwd, readFileImpl)) {
+      return {
+        file,
+        pass: true,
+        reason: `body mentions #${epicId}`,
+      };
+    }
+    return {
+      file,
+      pass: false,
+      reason: `no commit message or body reference to #${epicId}`,
+    };
+  });
+  return { ok: results.every((r) => r.pass), results };
+}
+
+/**
+ * Pure: parse argv into the normalized CLI option bag.
+ *
+ * @param {string[]} argv
+ * @returns {{ epicId: number|null, json: boolean, docsList: string[]|null }}
+ */
+export function parseFreshnessArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      epic: { type: 'string' },
+      base: { type: 'string' },
+      docs: { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+  const parsed = Number.parseInt(values.epic ?? '', 10);
+  return {
+    epicId: Number.isNaN(parsed) || parsed <= 0 ? null : parsed,
+    json: values.json === true,
+    docsList: values.docs
+      ? values.docs
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : null,
+  };
+}
+
+/** Pure: render a per-doc "ok / fail" line. */
+export function renderFreshnessLine(result) {
+  return `[docs-freshness] ${result.pass ? '✅' : '❌'} ${result.file} — ${result.reason}`;
+}
+
+/** Pure: build the failure message for the operator. */
+export function renderFreshnessFailureMessage(epicId) {
+  return (
+    `[docs-freshness] ❌ Documentation freshness gate FAILED for Epic #${epicId}.\n\n` +
+    `Update each failing file so its commit message or body references #${epicId}, ` +
+    `then re-run /epic-deliver.`
+  );
+}
+
+/** Pure: success message. */
+export function renderFreshnessSuccessMessage(epicId, count) {
+  return `[docs-freshness] ✅ All ${count} doc(s) reference Epic #${epicId}.`;
+}
+
+function reportEmptyDocs(epicId, json) {
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, epicId, results: [] })}\n`,
+    );
+    return;
+  }
+  Logger.info(
+    `[docs-freshness] ⏭  No docs configured under delivery.docsFreshness.paths or ` +
+      `project.docsContextFiles — nothing to check.`,
+  );
+}
+
+function reportGateOutcome({ epicId, json, ok, results }) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok, epicId, results })}\n`);
+    if (!ok) process.exit(1);
+    return;
+  }
+  for (const r of results) Logger.info(renderFreshnessLine(r));
+  if (ok) {
+    Logger.info(renderFreshnessSuccessMessage(epicId, results.length));
+    return;
+  }
+  Logger.error(renderFreshnessFailureMessage(epicId));
+  process.exit(1);
+}
+
+async function main() {
+  const args = parseFreshnessArgs(process.argv.slice(2));
+  if (args.epicId === null) {
+    throw new Error(
+      'Usage: node validate-docs-freshness.js --epic <EPIC_ID> [--docs a.md,b.md] [--json]',
+    );
+  }
+  const { epicId, json, docsList } = args;
+  const config = resolveConfig();
+  const docs = docsList ?? resolveDocList(config);
+  if (docs.length === 0) {
+    reportEmptyDocs(epicId, json);
+    return;
+  }
+  const { ok, results } = runFreshnessGate({ epicId, docs });
+  reportGateOutcome({ epicId, json, ok, results });
+}
+
+runAsCli(import.meta.url, main, { source: 'validate-docs-freshness' });