mandrel 1.62.0 → 1.63.0

package/.agents/scripts/lib/orchestration/code-review.js

@@ -463,203 +463,241 @@ function resolveScopeEnvelope(opts, config) {
  *   blockerReason: string|null,
  * }>}
  */
-export async function runCodeReview(opts = {}) {
+/**
+ * Resolve the human-facing provider name from the resolved code-review
+ * config. Chain configs render as `chain[a,b,...]`; a single-provider
+ * config renders its `provider` string; everything else falls back to
+ * `'native'`. Story #4075 — extracted from `runCodeReview`.
+ */
+function resolveProviderName(codeReviewConfig) {
+  const isChainConfig =
+    codeReviewConfig &&
+    Array.isArray(codeReviewConfig.providers) &&
+    codeReviewConfig.providers.length > 0;
+  if (isChainConfig) {
+    return `chain[${codeReviewConfig.providers
+      .map((p) => p?.name ?? '?')
+      .join(',')}]`;
+  }
+  return (
+    (codeReviewConfig && typeof codeReviewConfig.provider === 'string'
+      ? codeReviewConfig.provider
+      : null) ?? 'native'
+  );
+}
+
+/**
+ * Build the provider `runReview` input, resolving the review depth from the
+ * judged risk envelope's `overallLevel` and the mechanical changed-file
+ * count of the diff under review (Story #3876 / #3938). The depth is an
+ * input-only signal (light → standard → deep) and never touches the output
+ * envelope or the posted comment. Absent risk envelope + unknown width →
+ * `standard`. Story #4075 — extracted from `runCodeReview`.
+ */
+function buildReviewInput({ opts, config, scope, ticketId, baseRef, headRef }) {
+  const changedFileCount =
+    typeof opts.changedFileCount === 'number'
+      ? opts.changedFileCount
+      : countChangedFiles({ baseRef, headRef, gitSpawnFn: opts.gitSpawnFn });
+  const depth = resolveDepth({
+    overallLevel: opts.planningRisk?.overallLevel,
+    changedFileCount,
+    sizing: resolveTaskSizing(config),
+  });
+  return {
+    scope,
+    ticketId,
+    baseRef,
+    headRef,
+    labels: Array.isArray(opts.ticketLabels) ? opts.ticketLabels : [],
+    depth,
+  };
+}
+
+/**
+ * Feature-detect manual-prompt providers (Story #2871). Legacy
+ * single-adapter providers don't carry `getPromptMessages`, so the
+ * empty-array fallback keeps the old snapshot byte-stable; a throw is
+ * logged and degraded to empty.
+ */
+async function resolvePromptMessages(reviewProvider, reviewInput, logger) {
+  if (typeof reviewProvider.getPromptMessages !== 'function') return [];
+  try {
+    const out = await reviewProvider.getPromptMessages(reviewInput);
+    return Array.isArray(out) ? out : [];
+  } catch (err) {
+    logger?.warn?.(
+      `[code-review] getPromptMessages threw; treating as empty. ${
+        err?.message ?? err
+      }`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Upsert the rendered report as a structured comment. Posting failure is
+ * non-fatal: it is logged and surfaced via `posted: false`. Story #4075 —
+ * extracted from `runCodeReview`.
+ */
+async function postReviewComment({
+  upsertCommentFn,
+  provider,
+  commentTargetId,
+  report,
+  logger,
+}) {
+  try {
+    const postResult = await upsertCommentFn(
+      provider,
+      commentTargetId,
+      'code-review',
+      report,
+    );
+    const postedCommentId =
+      typeof postResult?.commentId === 'number'
+        ? postResult.commentId
+        : typeof postResult?.id === 'number'
+          ? postResult.id
+          : null;
+    logger?.info?.(
+      `[code-review] Posted structured comment to #${commentTargetId}.`,
+    );
+    return { posted: true, postedCommentId };
+  } catch (err) {
+    logger?.warn?.(
+      `[code-review] Failed to upsert structured comment on #${commentTargetId}: ${err?.message ?? err}`,
+    );
+    return { posted: false, postedCommentId: null };
+  }
+}
+
+/**
+ * Run the review pipeline (resolve provider → runReview → prompt messages →
+ * render → post comment) and shape the `status: 'ok'` result. Pure of the
+ * lifecycle-boundary concern — `runCodeReview` owns the start/end emit pair.
+ * Story #4075 — extracted to keep both bodies below the CC must-fix band.
+ */
+async function executeReviewPipeline({ opts, config, envelope }) {
   const {
     provider,
     logger,
-    bus,
-    now = Date.now,
     reviewProvider: injectedReviewProvider,
-    resolveConfigFn = resolveConfig,
     createReviewProviderFn = createReviewProvider,
     upsertCommentFn = upsertStructuredComment,
     renderFindingsFn = renderFindings,
   } = opts;
+  const { scope, ticketId, baseRef, headRef, commentTargetId } = envelope;
+
+  const codeReviewConfig = config?.delivery?.codeReview ?? null;
+  const providerName = resolveProviderName(codeReviewConfig);
+  const reviewProvider =
+    injectedReviewProvider ?? createReviewProviderFn(codeReviewConfig);
+
+  logger?.info?.(
+    `[code-review] Running ${providerName} adapter for ${scope === 'epic' ? 'Epic' : 'Story'} #${ticketId} (${baseRef}...${headRef})...`,
+  );
+
+  const reviewInput = buildReviewInput({
+    opts,
+    config,
+    scope,
+    ticketId,
+    baseRef,
+    headRef,
+  });
+
+  const findings = await reviewProvider.runReview(reviewInput);
+  if (!Array.isArray(findings)) {
+    throw new TypeError(
+      `[code-review] Review provider "${providerName}" returned a non-array; expected Finding[].`,
+    );
+  }
+
+  const promptMessages = await resolvePromptMessages(
+    reviewProvider,
+    reviewInput,
+    logger,
+  );
+
+  const severity = countBySeverity(findings);
+  const halted = severity.critical > 0;
+  const report = renderFindingsFn({
+    scope,
+    ticketId,
+    baseRef,
+    headRef,
+    findings,
+    provider: providerName,
+    promptMessages,
+  });
+
+  const { posted, postedCommentId } = await postReviewComment({
+    upsertCommentFn,
+    provider,
+    commentTargetId,
+    report,
+    logger,
+  });
+
+  return {
+    status: 'ok',
+    severity,
+    report,
+    posted,
+    postedCommentId,
+    commentTargetId,
+    halted,
+    blockerReason: halted
+      ? `code-review reported ${severity.critical} critical blocker(s)`
+      : null,
+  };
+}
+
+export async function runCodeReview(opts = {}) {
+  const { bus, now = Date.now, resolveConfigFn = resolveConfig } = opts;
 
   const config = resolveConfigFn();
   const envelope = resolveScopeEnvelope(opts, config);
-  const { scope, ticketId, baseRef, headRef, commentTargetId } = envelope;
+  const { scope } = envelope;
 
   // Epic-scope lifecycle ledger requires `bus`; Story-scope sits outside
   // the Epic lifecycle so the bus is optional there. A caller without a
   // bus on the Story path still gets the full review semantics — only the
   // `code-review.start`/`.end` events are suppressed.
-  const requiresBus = scope === 'epic';
-  if (requiresBus && (!bus || typeof bus.emit !== 'function')) {
+  if (scope === 'epic' && (!bus || typeof bus.emit !== 'function')) {
     throw new TypeError('runCodeReview: bus is required (object with emit()).');
   }
   const ledgerEnabled =
     scope === 'epic' && bus && typeof bus.emit === 'function';
 
   const startedAt = typeof now === 'function' ? now() : Date.now();
+  // Emit the matched `code-review.end` boundary; the ledger must always
+  // show a start/end pair (even on adapter throw, where `result` is the
+  // canonical `{ status: 'invalid' }`).
+  const emitEnd = async (result) => {
+    if (!ledgerEnabled) return;
+    const endedAt = typeof now === 'function' ? now() : Date.now();
+    await bus.emit(
+      'code-review.end',
+      buildCodeReviewEndPayload({
+        epicId: envelope.epicIdForLedger,
+        result,
+        durationMs: Math.max(0, endedAt - startedAt),
+      }),
+    );
+  };
+
   if (ledgerEnabled) {
     await bus.emit('code-review.start', { epicId: envelope.epicIdForLedger });
   }
 
   try {
-    const codeReviewConfig = config?.delivery?.codeReview ?? null;
-    const isChainConfig =
-      codeReviewConfig &&
-      Array.isArray(codeReviewConfig.providers) &&
-      codeReviewConfig.providers.length > 0;
-    const providerName = isChainConfig
-      ? `chain[${codeReviewConfig.providers
-          .map((p) => p?.name ?? '?')
-          .join(',')}]`
-      : ((codeReviewConfig && typeof codeReviewConfig.provider === 'string'
-          ? codeReviewConfig.provider
-          : null) ?? 'native');
-    const reviewProvider =
-      injectedReviewProvider ?? createReviewProviderFn(codeReviewConfig);
-
-    const scopeLabel = scope === 'epic' ? 'Epic' : 'Story';
-    logger?.info?.(
-      `[code-review] Running ${providerName} adapter for ${scopeLabel} #${ticketId} (${baseRef}...${headRef})...`,
-    );
-
-    const ticketLabels = Array.isArray(opts.ticketLabels)
-      ? opts.ticketLabels
-      : [];
-    // Story #3876 / #3938 — resolve the review depth from BOTH the judged risk
-    // envelope's `overallLevel` and the mechanical changed-file count of the
-    // diff under review, then thread it into the provider's `runReview` input.
-    // The depth is an input-only signal: it tells the provider how thorough to
-    // be (light → standard → deep) and never touches the output envelope or the
-    // posted structured comment. The changed-file count is enumerated from the
-    // same `baseRef...headRef` diff the native provider reviews; a count that
-    // cannot be determined is the neutral "width unknown" signal that neither
-    // escalates to `deep` nor blocks `light`. The `sizing` thresholds honour
-    // the operator's `planning.taskSizing` override. Absent risk envelope +
-    // unknown width → `standard` (the neutral default), preserving the
-    // pre-change behaviour for callers that pass no risk envelope.
-    const changedFileCount =
-      typeof opts.changedFileCount === 'number'
-        ? opts.changedFileCount
-        : countChangedFiles({
-            baseRef,
-            headRef,
-            gitSpawnFn: opts.gitSpawnFn,
-          });
-    const depth = resolveDepth({
-      overallLevel: opts.planningRisk?.overallLevel,
-      changedFileCount,
-      sizing: resolveTaskSizing(config),
-    });
-    const reviewInput = {
-      scope,
-      ticketId,
-      baseRef,
-      headRef,
-      labels: ticketLabels,
-      depth,
-    };
-
-    const findings = await reviewProvider.runReview(reviewInput);
-
-    if (!Array.isArray(findings)) {
-      throw new TypeError(
-        `[code-review] Review provider "${providerName}" returned a non-array; expected Finding[].`,
-      );
-    }
-
-    // Story #2871 — feature-detect manual-prompt providers. Legacy
-    // single-adapter providers don't carry `getPromptMessages`, so the
-    // empty-array fallback keeps the old snapshot byte-stable.
-    let promptMessages = [];
-    if (typeof reviewProvider.getPromptMessages === 'function') {
-      try {
-        const out = await reviewProvider.getPromptMessages(reviewInput);
-        promptMessages = Array.isArray(out) ? out : [];
-      } catch (err) {
-        logger?.warn?.(
-          `[code-review] getPromptMessages threw; treating as empty. ${
-            err?.message ?? err
-          }`,
-        );
-        promptMessages = [];
-      }
-    }
-
-    const severity = countBySeverity(findings);
-    const halted = severity.critical > 0;
-    const blockerReason = halted
-      ? `code-review reported ${severity.critical} critical blocker(s)`
-      : null;
-
-    const report = renderFindingsFn({
-      scope,
-      ticketId,
-      baseRef,
-      headRef,
-      findings,
-      provider: providerName,
-      promptMessages,
-    });
-
-    let posted = false;
-    let postedCommentId = null;
-    try {
-      const postResult = await upsertCommentFn(
-        provider,
-        commentTargetId,
-        'code-review',
-        report,
-      );
-      posted = true;
-      const rawId =
-        typeof postResult?.commentId === 'number'
-          ? postResult.commentId
-          : typeof postResult?.id === 'number'
-            ? postResult.id
-            : null;
-      postedCommentId = rawId;
-      logger?.info?.(
-        `[code-review] Posted structured comment to #${commentTargetId}.`,
-      );
-    } catch (err) {
-      logger?.warn?.(
-        `[code-review] Failed to upsert structured comment on #${commentTargetId}: ${err?.message ?? err}`,
-      );
-      posted = false;
-    }
-
-    const result = {
-      status: 'ok',
-      severity,
-      report,
-      posted,
-      postedCommentId,
-      commentTargetId,
-      halted,
-      blockerReason,
-    };
-    if (ledgerEnabled) {
-      const endedAt = typeof now === 'function' ? now() : Date.now();
-      await bus.emit(
-        'code-review.end',
-        buildCodeReviewEndPayload({
-          epicId: envelope.epicIdForLedger,
-          result,
-          durationMs: Math.max(0, endedAt - startedAt),
-        }),
-      );
-    }
+    const result = await executeReviewPipeline({ opts, config, envelope });
+    await emitEnd(result);
     return result;
   } catch (err) {
-    // Surface the closing boundary even on adapter throw — the ledger
-    // must always show a matched start/end pair. `status: 'invalid'`
-    // is the canonical "could not complete" value.
-    if (ledgerEnabled) {
-      const endedAt = typeof now === 'function' ? now() : Date.now();
-      await bus.emit(
-        'code-review.end',
-        buildCodeReviewEndPayload({
-          epicId: envelope.epicIdForLedger,
-          result: { status: 'invalid' },
-          durationMs: Math.max(0, endedAt - startedAt),
-        }),
-      );
-    }
+    await emitEnd({ status: 'invalid' });
     throw err;
   }
 }

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/creation.js

@@ -1,14 +1,15 @@
 /**
- * creation.js — sub-issue link reconciliation, Epic label transitions, and
- * the advisory ticket-cap warning used by the reconciler-based persist flow
- * (`persist.js`).
+ * creation.js — sub-issue link reconciliation, Epic label transitions,
+ * the advisory ticket-cap warning, and the blocked-by dependency wiring
+ * used by the reconciler-based persist flow (`persist.js`).
  *
- * Exports: `reconcileSubIssueLinks`, `setEpicLabel`,
- * `warnTicketCapNearLimit`.
+ * Exports: `reconcileSubIssueLinks`, `setBlockedByDependencies`,
+ * `setEpicLabel`, `warnTicketCapNearLimit`.
  *
  * @module lib/orchestration/epic-plan-decompose/phases/creation
  */
 
+import { applyBlockedByDependencies } from '../../../../providers/github/blocked-by-add.js';
 import { Logger } from '../../../Logger.js';
 import { AGENT_LABELS } from '../../../label-constants.js';
 
@@ -36,6 +37,71 @@ export async function reconcileSubIssueLinks(epicId, provider) {
   );
 }
 
+/**
+ * Translate each Story's `dependsOn` slug list into native GitHub "blocked
+ * by" dependency edges. Best-effort and non-fatal: individual edge failures
+ * are logged as warnings and do not abort the decompose phase.
+ *
+ * Requires the provider to expose `owner`, `repo`, `_gh`, and `getTicket`.
+ * No-ops silently when any required surface is absent so callers remain
+ * safe across provider stubs.
+ *
+ * @param {number} epicId
+ * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
+ * @param {object} spec — the parsed YAML spec (has `.stories[*].dependsOn`).
+ * @param {object} stateMapping — slug → `{ issueNumber }` from the reconciler state.
+ */
+export async function setBlockedByDependencies(
+  epicId,
+  provider,
+  spec,
+  stateMapping,
+) {
+  const stories = Array.isArray(spec?.stories) ? spec.stories : [];
+  const hasDeps = stories.some(
+    (s) => Array.isArray(s.dependsOn) && s.dependsOn.length > 0,
+  );
+  if (!hasDeps) return;
+
+  if (
+    !provider?.owner ||
+    !provider?.repo ||
+    !provider?._gh ||
+    typeof provider.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      `[Decomposer] setBlockedByDependencies: provider missing required surface (owner/repo/_gh/getTicket); skipping.`,
+    );
+    return;
+  }
+
+  Logger.info(
+    `[Decomposer] Setting native blocked-by dependency edges for Epic #${epicId}...`,
+  );
+
+  // Build a slug → issueNumber map from the reconciler state mapping.
+  const slugToIssueNumber = {};
+  for (const [slug, entry] of Object.entries(stateMapping ?? {})) {
+    if (typeof entry?.issueNumber === 'number') {
+      slugToIssueNumber[slug] = entry.issueNumber;
+    }
+  }
+
+  const result = await applyBlockedByDependencies({
+    stories,
+    slugToIssueNumber,
+    getTicket: (n) => provider.getTicket(n),
+    owner: provider.owner,
+    repo: provider.repo,
+    gh: provider._gh,
+  });
+
+  const { edgesAdded, edgesSkipped, edgesFailed, storiesProcessed } = result;
+  Logger.info(
+    `[Decomposer] blocked-by edges: ${edgesAdded} added, ${edgesSkipped} already present, ${edgesFailed} failed (${storiesProcessed} stories with deps processed).`,
+  );
+}
+
 export async function setEpicLabel(provider, epicId, targetLabel) {
   const planningLabels = [AGENT_LABELS.REVIEW_SPEC, AGENT_LABELS.READY];
   await provider.updateTicket(epicId, {

package/.agents/scripts/lib/orchestration/epic-plan-decompose/phases/persist.js

@@ -29,7 +29,7 @@ import {
   PLANNING_HEALTHCHECK_WAIVED,
 } from '../../../label-constants.js';
 import { cleanupPhaseTempFiles } from '../../../plan-phase-cleanup.js';
-import { writeSpec } from '../../../spec/index.js';
+import { loadState, writeSpec } from '../../../spec/index.js';
 import {
   assertNoOpenPlanChildren,
   releaseEpicPlanLease,
@@ -38,6 +38,7 @@ import { renderSpec } from '../../spec-renderer.js';
 import { renderHardConflictError } from '../../ticket-validator-conflicts.js';
 import {
   reconcileSubIssueLinks,
+  setBlockedByDependencies,
   setEpicLabel,
   warnTicketCapNearLimit,
 } from './creation.js';
@@ -59,7 +60,7 @@ import { RECONCILE_CLI, spawnReconcilerApply } from './reconcile-spawn.js';
  * @param {import('../../../ITicketingProvider.js').ITicketingProvider} provider
  * @param {{ tickets: Array<object> }} payload
  * @param {object} config
- * @param {{ force?: boolean, resume?: boolean, allowOverBudget?: boolean, allowLargeFanOut?: boolean, fanOutCounter?: (arg: { path: string }) => number, spawnSync?: typeof defaultSpawnSync, reconcileCli?: string, writeSpecFn?: typeof writeSpec, renderSpecFn?: typeof renderSpec, cwd?: string, runHealthcheckFn?: typeof defaultRunPlanHealthcheck, skipHealthcheck?: boolean }} [opts]
+ * @param {{ force?: boolean, resume?: boolean, allowOverBudget?: boolean, allowLargeFanOut?: boolean, fanOutCounter?: (arg: { path: string }) => number, spawnSync?: typeof defaultSpawnSync, reconcileCli?: string, writeSpecFn?: typeof writeSpec, renderSpecFn?: typeof renderSpec, loadStateFn?: typeof loadState, cwd?: string, runHealthcheckFn?: typeof defaultRunPlanHealthcheck, skipHealthcheck?: boolean }} [opts]
  */
 export async function runDecomposePhase(
   epicId,
@@ -76,6 +77,7 @@ export async function runDecomposePhase(
     reconcileCli = RECONCILE_CLI,
     writeSpecFn = writeSpec,
     renderSpecFn = renderSpec,
+    loadStateFn = loadState,
     cwd = PROJECT_ROOT,
     runHealthcheckFn = defaultRunPlanHealthcheck,
     skipHealthcheck = false,
@@ -170,6 +172,18 @@ export async function runDecomposePhase(
   // re-establish missing native links before flipping the Epic to ready.
   await reconcileSubIssueLinks(epicId, provider);
 
+  // Story #4067 — translate `depends_on` edges into native GitHub "blocked
+  // by" dependencies so maintainers see blocking relationships in the UI.
+  // Best-effort and non-fatal: the reconciler has already written the state
+  // file, so we load it here to get the authoritative slug→issueNumber map.
+  const postReconcileState = loadStateFn(epicId);
+  await setBlockedByDependencies(
+    epicId,
+    provider,
+    spec,
+    postReconcileState.mapping,
+  );
+
   const checkpoint = await recordCheckpoint(provider, epicId, tickets);
 
   // Story #2921 (Epic #2880 F7) — `agent::ready` handoff gate. The

package/.agents/scripts/lib/orchestration/epic-runner/progress-signals/component-drift.js

@@ -1,3 +1,4 @@
+import nodeFs from 'node:fs';
 import path from 'node:path';
 import { resolveComponents } from '../../../baselines/components.js';
 import { componentOrder } from './_bullet-format.js';
@@ -70,7 +71,7 @@ export function walkComponentRegressions(params = {}, spec) {
  *   metadata?: Record<string, unknown>,
  * }} opts
  */
-export function createSnapshotStore({ fs, baselinePath, metadata = {} }) {
+function createSnapshotStore({ fs, baselinePath, metadata = {} }) {
   return {
     persist(scores) {
       if (!fs.writeFileSync) return;
@@ -101,3 +102,102 @@ export function createSnapshotStore({ fs, baselinePath, metadata = {} }) {
     },
   };
 }
+
+/**
+ * Shared per-file/per-method drift-detector skeleton for the progress-signal
+ * detectors (Story #4076). `crap-drift.js` and `maintainability-drift.js`
+ * previously duplicated the same `{ baselinePath, captureBaseline,
+ * loadBaseline, detect }` shape — identical snapshot-store wiring, identical
+ * "distinct from canonical baseline" framing, and identical
+ * swallow-and-warn resilience. The only divergence is the per-axis scoring
+ * (`scoreFile`), the snapshot value extracted from a score (`captureScore`),
+ * and the per-detect comparison that emits bullets (`detect`). Both detectors
+ * now supply those deltas to this factory, mirroring the "shared walker +
+ * per-axis delta" pattern already established by `walkComponentRegressions`.
+ *
+ * The factory owns:
+ *
+ *   - `fs` / `cwd` / `files` resolution from `opts`.
+ *   - The `<cwd>/<baselineDir>/<baselineFilename>` baseline path and the
+ *     `createSnapshotStore` wiring (with caller-supplied `metadata`).
+ *   - The in-memory `baseline` cache and the `captureBaseline` /
+ *     `loadBaseline` lifecycle.
+ *
+ * The caller owns:
+ *
+ *   - `scoreFile(relPath, ctx)` — returns the per-file score (any shape) or
+ *     `null` when the file can't be scored. `ctx` is whatever
+ *     `beforeScore()` returned for this pass (e.g. a coverage map), or
+ *     `undefined` when `beforeScore` is omitted.
+ *   - `captureScore(score)` — maps a `scoreFile` result to the value
+ *     persisted in the snapshot (e.g. extract `crap` from each method row).
+ *   - `detect({ baseline, scoreFile })` — async; returns the bullet list.
+ *     Receives the loaded baseline and a `scoreFile(relPath)` bound to this
+ *     pass's score context so the per-axis compare stays free of plumbing.
+ *   - `beforeScore()` (optional) — runs once per `captureBaseline` / `detect`
+ *     pass and returns the score context threaded into `scoreFile`.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   files?: string[],
+ *   fs?: { readFileSync?: Function, writeFileSync?: Function, mkdirSync?: Function, existsSync?: Function },
+ *   baselineDir?: string,
+ *   baselineFilename: string,
+ *   metadata?: Record<string, unknown>,
+ *   beforeScore?: () => unknown,
+ *   scoreFile: (relPath: string, ctx: unknown) => unknown,
+ *   captureScore: (score: unknown) => unknown,
+ *   detect: (args: { baseline: Record<string, unknown>, scoreFile: (relPath: string) => unknown }) => Promise<string[]>,
+ * }} opts
+ */
+export function createDriftDetector(opts = {}) {
+  const fs = opts.fs ?? nodeFs;
+  const cwd = opts.cwd ?? process.cwd();
+  const files = Array.isArray(opts.files) ? [...opts.files] : [];
+  const baselineDir = opts.baselineDir ?? '.agents/state';
+  const baselinePath = path.join(cwd, baselineDir, opts.baselineFilename);
+  const beforeScore = opts.beforeScore ?? (() => undefined);
+  const scoreFile = opts.scoreFile;
+  const captureScore = opts.captureScore;
+  const runDetect = opts.detect;
+  const store = createSnapshotStore({
+    fs,
+    baselinePath,
+    metadata: opts.metadata ?? {},
+  });
+
+  let baseline = null;
+
+  return {
+    get baselinePath() {
+      return baselinePath;
+    },
+
+    captureBaseline() {
+      const ctx = beforeScore();
+      const snapshot = {};
+      for (const f of files) {
+        const score = scoreFile(f, ctx);
+        if (score == null) continue;
+        snapshot[f] = captureScore(score);
+      }
+      baseline = snapshot;
+      store.persist(snapshot);
+      return snapshot;
+    },
+
+    loadBaseline() {
+      baseline = store.load();
+      return baseline;
+    },
+
+    async detect() {
+      if (!baseline) return [];
+      const ctx = beforeScore();
+      return runDetect({
+        baseline,
+        scoreFile: (relPath) => scoreFile(relPath, ctx),
+      });
+    },
+  };
+}