mandrel 1.62.0 → 1.63.0

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

@@ -38,6 +38,42 @@ import { runCloseValidation as defaultRunCloseValidation } from '../../close-val
 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
@@ -103,13 +139,28 @@ export async function runPreMergeGates({
   // 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 =
-    Number.isInteger(epicId) &&
-    epicId > 0 &&
-    Number.isInteger(storyId) &&
-    storyId > 0 &&
-    !!bus;
+  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 });
   }
@@ -139,74 +190,27 @@ export async function runPreMergeGates({
     // `validation.failed` below). Emit the matching `close-validate.end`
     // with `ok:false` so the ledger always carries the boundary, then
     // re-throw.
-    if (emitsActive) {
-      const endedAt = typeof now === 'function' ? now() : Date.now();
-      await bus.emit('close-validate.end', {
-        epicId,
-        storyId,
-        ok: false,
-        gateCount,
-        failedGate: 'runner-error',
-        durationMs: Math.max(0, endedAt - startedAt),
-      });
-      await bus.emit('story.blocked', {
-        storyId,
-        reason: 'close-validate-failed:runner-error',
-      });
-    }
+    await emitEnd({
+      ok: false,
+      extra: { failedGate: 'runner-error' },
+      blockedReason: 'close-validate-failed:runner-error',
+    });
     throw err;
   }
   if (!validation.ok) {
-    const [first] = validation.failed;
-    const { gate, status, cwd: gateCwd } = first;
-    // Story #2250 — emit `close-validate.end` with `ok:false` BEFORE
-    // throwing so the lifecycle ledger captures the boundary even when
-    // the caller's try/catch swallows the throw. Then emit
-    // `story.blocked` with the typed `close-validate-failed:<gate>`
-    // reason so the BlockerHandler listener cascades to `epic.blocked`
-    // — failed validators MUST route through the lifecycle cascade.
-    if (emitsActive) {
-      const endedAt = typeof now === 'function' ? now() : Date.now();
-      await bus.emit('close-validate.end', {
-        epicId,
-        storyId,
-        ok: false,
-        gateCount,
-        failedGate: gate.name,
-        exitCode: status,
-        durationMs: Math.max(0, endedAt - startedAt),
-      });
-      await bus.emit('story.blocked', {
-        storyId,
-        reason: `close-validate-failed:${gate.name}`,
-      });
-    }
-    // Story #2136 / Task #2143 — surface the structured failure metadata
-    // as typed properties on the Error so callers (notably
-    // `runPreMergeGatesWithAttribution`) can pattern-match exit codes
-    // without parsing the human message. The message format is preserved
-    // byte-for-byte so the existing regex consumers in the wiring layer
-    // keep matching.
-    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;
-    throw err;
-  }
-  if (emitsActive) {
-    const endedAt = typeof now === 'function' ? now() : Date.now();
-    await bus.emit('close-validate.end', {
-      epicId,
-      storyId,
-      ok: true,
-      gateCount,
-      durationMs: Math.max(0, endedAt - startedAt),
+    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;
 }
 

package/.agents/scripts/lib/orchestration/story-close-recovery.js

@@ -197,97 +197,127 @@ function detectUncommittedWorktree({
  *
  * @returns {{ phase: string, detail: object } | null}
  */
-function detectAlreadyMerged({ cwd, storyId, epicId, lsrOut, detail, git }) {
-  if (!epicId) return null;
-
-  const storyBranch = `story-${storyId}`;
-  const epicRefs = ['origin/epic', `origin/epic/${epicId}`];
-  const probeAncestor = (storyRef, epicRef) =>
-    git.isAncestor(cwd, storyRef, epicRef)?.status === 0;
-
-  let resolvedDetail = null;
-
-  // a) local story branch still exists.
+/**
+ * Probe (a): the local `story-<id>` branch still exists and is an ancestor
+ * of `origin/epic/<id>`. Returns the resolved-detail fragment or `null`.
+ * Story #4075 — extracted from `detectAlreadyMerged`.
+ */
+function probeLocalStoryMerged({
+  cwd,
+  storyBranch,
+  epicId,
+  git,
+  probeAncestor,
+}) {
   const localStoryRef = `refs/heads/${storyBranch}`;
-  if (git.showRef && git.showRef(cwd, localStoryRef)?.status === 0) {
-    const remoteEpicRef = `origin/epic/${epicId}`;
-    if (probeAncestor(storyBranch, remoteEpicRef)) {
-      resolvedDetail = { localStoryRef: storyBranch, remoteEpicRef };
-    }
+  if (!(git.showRef && git.showRef(cwd, localStoryRef)?.status === 0)) {
+    return null;
   }
+  const remoteEpicRef = `origin/epic/${epicId}`;
+  return probeAncestor(storyBranch, remoteEpicRef)
+    ? { localStoryRef: storyBranch, remoteEpicRef }
+    : null;
+}
 
-  // b) remote story branch present and merged.
-  if (!resolvedDetail && lsrOut.length > 0) {
-    for (const epicRef of epicRefs) {
-      if (probeAncestor(`origin/${storyBranch}`, epicRef)) {
-        resolvedDetail = {
-          remoteStoryRef: `origin/${storyBranch}`,
-          remoteEpicRef: epicRef,
-        };
-        break;
-      }
+/**
+ * Probe (b): the remote `origin/story-<id>` ref is present and is an
+ * ancestor of an `origin/epic` ref. Story #4075 — extracted.
+ */
+function probeRemoteStoryMerged({
+  storyBranch,
+  epicRefs,
+  lsrOut,
+  probeAncestor,
+}) {
+  if (lsrOut.length === 0) return null;
+  for (const epicRef of epicRefs) {
+    if (probeAncestor(`origin/${storyBranch}`, epicRef)) {
+      return {
+        remoteStoryRef: `origin/${storyBranch}`,
+        remoteEpicRef: epicRef,
+      };
     }
   }
+  return null;
+}
 
-  // c) Rebased equivalents (Story #3161). Story tip is not an ancestor
-  //    of `origin/epic/<id>`, but every commit on the Story branch is
-  //    patch-equivalent (`git cherry`) to a commit already on the Epic.
-  //    Surfaces the manual-recovery case where the operator rebased
-  //    Story content directly onto `epic/<id>` so the diff is present
-  //    as commits with different SHAs and no `(resolves #<id>)` merge
-  //    commit. Without this branch, `assertMergeReachable` throws at
-  //    resume time and strands close at `agent::closing`.
-  if (!resolvedDetail && git.cherry) {
-    const candidates = [];
-    const localStoryRefName = `refs/heads/${storyBranch}`;
-    if (git.showRef && git.showRef(cwd, localStoryRefName)?.status === 0) {
-      candidates.push({ ref: storyBranch, kind: 'local' });
-    }
-    if (lsrOut.length > 0) {
-      candidates.push({ ref: `origin/${storyBranch}`, kind: 'remote' });
-    }
-    const remoteEpicRef = `origin/epic/${epicId}`;
-    for (const cand of candidates) {
-      const cherry = git.cherry(cwd, remoteEpicRef, cand.ref);
-      if (!cherry || cherry.status !== 0) continue;
-      const lines = (cherry.stdout ?? '')
-        .toString()
-        .split('\n')
-        .map((l) => l.trim())
-        .filter(Boolean);
-      if (lines.length === 0) continue;
-      if (lines.every((l) => l.startsWith('- '))) {
-        resolvedDetail = {
-          [cand.kind === 'local' ? 'localStoryRef' : 'remoteStoryRef']:
-            cand.ref,
-          remoteEpicRef,
-          via: 'rebased-equivalents',
-          equivalents: lines.length,
-        };
-        break;
-      }
+/**
+ * Probe (c): rebased equivalents (Story #3161). The Story tip is not an
+ * ancestor of `origin/epic/<id>`, but every commit on the Story branch is
+ * patch-equivalent (`git cherry`) to a commit already on the Epic — the
+ * manual-recovery case where the operator rebased Story content directly
+ * onto `epic/<id>`. Without this branch, `assertMergeReachable` throws at
+ * resume time and strands close at `agent::closing`. Story #4075 —
+ * extracted from `detectAlreadyMerged`.
+ */
+function probeRebasedEquivalents({ cwd, storyBranch, epicId, lsrOut, git }) {
+  if (!git.cherry) return null;
+  const candidates = [];
+  const localStoryRefName = `refs/heads/${storyBranch}`;
+  if (git.showRef && git.showRef(cwd, localStoryRefName)?.status === 0) {
+    candidates.push({ ref: storyBranch, kind: 'local' });
+  }
+  if (lsrOut.length > 0) {
+    candidates.push({ ref: `origin/${storyBranch}`, kind: 'remote' });
+  }
+  const remoteEpicRef = `origin/epic/${epicId}`;
+  for (const cand of candidates) {
+    const cherry = git.cherry(cwd, remoteEpicRef, cand.ref);
+    if (!cherry || cherry.status !== 0) continue;
+    const lines = (cherry.stdout ?? '')
+      .toString()
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+    if (lines.length === 0) continue;
+    if (lines.every((l) => l.startsWith('- '))) {
+      return {
+        [cand.kind === 'local' ? 'localStoryRef' : 'remoteStoryRef']: cand.ref,
+        remoteEpicRef,
+        via: 'rebased-equivalents',
+        equivalents: lines.length,
+      };
     }
   }
+  return null;
+}
 
-  // d) Merge-commit-message scan (ref-independent; Story #3327 / Epic #3316).
-  //    Both the local `story-<id>` branch and the remote `origin/story-<id>`
-  //    ref were deleted by a prior partial close run, so branches a–c have no
-  //    ref to anchor on and fall through. Recover the already-merged signal
-  //    from the Epic history itself: locate the integration commit whose
-  //    subject carries `(resolves #<id>)` / `(refs #<id>)`. Without this
-  //    branch, detection falls to FRESH and the resumed close re-enters the
-  //    pre-merge gate chain, which crashes in the scoped format-autofix step on
-  //    `git diff <epicBranch>...story-<id>` because the Story ref is gone.
-  if (!resolvedDetail) {
-    const mc = findMergeCommitForStory({ cwd, storyId, epicId, git });
-    if (mc) {
-      resolvedDetail = {
+/**
+ * Probe (d): ref-independent merge-commit-message scan (Story #3327 /
+ * Epic #3316). Both the local and remote Story refs were deleted by a prior
+ * partial close, so probes a–c have no ref to anchor on. Recover the
+ * already-merged signal from the Epic history itself by locating the
+ * integration commit whose subject carries `(resolves #<id>)` / `(refs
+ * #<id>)`. Story #4075 — extracted from `detectAlreadyMerged`.
+ */
+function probeMergeCommitMessage({ cwd, storyId, epicId, git }) {
+  const mc = findMergeCommitForStory({ cwd, storyId, epicId, git });
+  return mc
+    ? {
         via: 'merge-commit-message',
         mergeCommit: mc.sha,
         remoteEpicRef: mc.epicRef,
-      };
-    }
-  }
+      }
+    : null;
+}
+
+function detectAlreadyMerged({ cwd, storyId, epicId, lsrOut, detail, git }) {
+  if (!epicId) return null;
+
+  const storyBranch = `story-${storyId}`;
+  const epicRefs = ['origin/epic', `origin/epic/${epicId}`];
+  const probeAncestor = (storyRef, epicRef) =>
+    git.isAncestor(cwd, storyRef, epicRef)?.status === 0;
+
+  // Any one signal is enough — the local branch may have been reaped while
+  // the remote survived (or vice versa), or both refs may be gone and only
+  // the Epic merge-commit message remains. Probes run in cheapest-first
+  // order; the first to resolve wins.
+  const resolvedDetail =
+    probeLocalStoryMerged({ cwd, storyBranch, epicId, git, probeAncestor }) ??
+    probeRemoteStoryMerged({ storyBranch, epicRefs, lsrOut, probeAncestor }) ??
+    probeRebasedEquivalents({ cwd, storyBranch, epicId, lsrOut, git }) ??
+    probeMergeCommitMessage({ cwd, storyId, epicId, git });
 
   if (!resolvedDetail) return null;
   return {

package/.agents/scripts/lib/signals/detectors/common.js

@@ -34,3 +34,110 @@ export function extractTool(rec) {
   }
   return null;
 }
+
+/**
+ * Validate and normalize the shared detector argument preamble.
+ *
+ * `detectRework`, `detectRetry`, and `detectHotspot` previously shipped a
+ * near-identical guard block: the `args` object-shape `TypeError`, the
+ * `nowFn` function-type `TypeError`, the positive-integer `RangeError`s for
+ * the id fields, the non-empty-string `tracesPath` check, and the
+ * non-negative-integer `threshold` check. Story #4077 hoists that preamble
+ * here so the three detectors share one error-message contract.
+ *
+ * Error wording stays per-detector-accurate by prefixing every message with
+ * `fnName` (e.g. `detectRework: …`). Error *types* are preserved exactly:
+ * the `args`/`tracesPath`/`nowFn` guards throw `TypeError`; the id and
+ * `threshold` guards throw `RangeError`.
+ *
+ * The validated fields are gated by the `require*` flags so the same helper
+ * serves both the Story-scoped detectors (rework/retry — full preamble) and
+ * the Epic-scoped hotspot detector (only `epicId` + `nowFn`). A field that
+ * is not required is neither validated nor read.
+ *
+ * @param {object} args — the detector's raw argument object.
+ * @param {object} opts
+ * @param {string} opts.fnName — the calling detector's name, used verbatim as
+ *   the prefix on every thrown error message (e.g. `'detectRework'`).
+ * @param {boolean} [opts.requireTracesPath=true] — validate + return
+ *   `tracesPath` (non-empty string).
+ * @param {boolean} [opts.requireStoryId=true] — validate + return `storyId`
+ *   (positive integer) and the optional `taskId` (positive integer or null).
+ * @param {boolean} [opts.requireThreshold=true] — validate + return
+ *   `threshold` (non-negative integer).
+ * @returns {{
+ *   tracesPath: string|undefined,
+ *   epicId: number,
+ *   storyId: number|undefined,
+ *   taskId: number|null|undefined,
+ *   threshold: number|undefined,
+ *   nowFn: () => string,
+ * }} the normalized argument set. Fields gated off by a `require*` flag are
+ *   omitted (left `undefined`).
+ */
+export function validateDetectorArgs(args, opts) {
+  const { fnName } = opts;
+  const requireTracesPath = opts.requireTracesPath ?? true;
+  const requireStoryId = opts.requireStoryId ?? true;
+  const requireThreshold = opts.requireThreshold ?? true;
+
+  if (args == null || typeof args !== 'object') {
+    throw new TypeError(
+      `${fnName}: args must be an object with at minimum { tracesPath, epicId, storyId, threshold }; got ${args}`,
+    );
+  }
+
+  const { tracesPath, epicId, storyId, threshold } = args;
+  const taskId = args.taskId ?? null;
+
+  if (args.nowFn != null && typeof args.nowFn !== 'function') {
+    throw new TypeError(
+      `${fnName}: nowFn, when provided, must be a function (got ${typeof args.nowFn})`,
+    );
+  }
+  const nowFn = args.nowFn ?? (() => new Date().toISOString());
+
+  if (requireTracesPath) {
+    if (typeof tracesPath !== 'string' || tracesPath.length === 0) {
+      throw new TypeError(
+        `${fnName}: tracesPath must be a non-empty string (got ${tracesPath})`,
+      );
+    }
+  }
+
+  if (!isPositiveInt(epicId)) {
+    throw new RangeError(
+      `${fnName}: epicId must be a positive integer (got ${epicId})`,
+    );
+  }
+
+  if (requireStoryId) {
+    if (!isPositiveInt(storyId)) {
+      throw new RangeError(
+        `${fnName}: storyId must be a positive integer (got ${storyId})`,
+      );
+    }
+    if (taskId !== null && !isPositiveInt(taskId)) {
+      throw new RangeError(
+        `${fnName}: taskId must be a positive integer or null (got ${taskId})`,
+      );
+    }
+  }
+
+  if (requireThreshold) {
+    if (!Number.isInteger(threshold) || threshold < 0) {
+      throw new RangeError(
+        `${fnName}: threshold must be a non-negative integer (got ${threshold})`,
+      );
+    }
+  }
+
+  return {
+    tracesPath: requireTracesPath ? tracesPath : undefined,
+    epicId,
+    storyId: requireStoryId ? storyId : undefined,
+    taskId: requireStoryId ? taskId : undefined,
+    threshold: requireThreshold ? threshold : undefined,
+    nowFn,
+  };
+}

package/.agents/scripts/lib/signals/detectors/hotspot.js

@@ -73,7 +73,7 @@ import path from 'node:path';
 import { createInterface } from 'node:readline';
 import { epicTempDir } from '../../config/temp-paths.js';
 import { parseStoryBranch } from '../../git-utils.js';
-import { extractTool, isPositiveInt } from './common.js';
+import { extractTool, validateDetectorArgs } from './common.js';
 
 /**
  * Tools that mutate files. Only these contribute to the per-target edit
@@ -207,24 +207,18 @@ export function nearestRankP95(values) {
  *   p95Threshold, multiplier }`.
  */
 export async function detectHotspot(args) {
-  if (args == null || typeof args !== 'object') {
-    throw new TypeError(
-      `detectHotspot: args must be an object with at minimum { epicId, multiplier }; got ${args}`,
-    );
-  }
-  const { epicId, multiplier, tempRoot } = args;
-  if (args.nowFn != null && typeof args.nowFn !== 'function') {
-    throw new TypeError(
-      `detectHotspot: nowFn, when provided, must be a function (got ${typeof args.nowFn})`,
-    );
-  }
-  const nowFn = args.nowFn ?? (() => new Date().toISOString());
+  // Hotspot shares only the args-shape, nowFn, and epicId guards with the
+  // Story-scoped detectors — it has no tracesPath/storyId/taskId/threshold.
+  // Gate those three off and validate multiplier/tempRoot (hotspot-specific)
+  // inline below.
+  const { epicId, nowFn } = validateDetectorArgs(args, {
+    fnName: 'detectHotspot',
+    requireTracesPath: false,
+    requireStoryId: false,
+    requireThreshold: false,
+  });
+  const { multiplier, tempRoot } = args;
 
-  if (!isPositiveInt(epicId)) {
-    throw new RangeError(
-      `detectHotspot: epicId must be a positive integer (got ${epicId})`,
-    );
-  }
   if (!isPositiveNumber(multiplier)) {
     throw new RangeError(
       `detectHotspot: multiplier must be a positive number (got ${multiplier})`,

package/.agents/scripts/lib/signals/detectors/retry.js

@@ -82,7 +82,7 @@ import { createReadStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 
-import { extractTool, isPositiveInt } from './common.js';
+import { extractTool, validateDetectorArgs } from './common.js';
 
 /**
  * Documented argv-normalisation rules — emitted verbatim onto every
@@ -220,45 +220,8 @@ async function tallyFailuresByIdentity(tracesPath) {
  *   to `.agents/schemas/signal-event.schema.json`.
  */
 export async function detectRetry(args) {
-  if (args == null || typeof args !== 'object') {
-    throw new TypeError(
-      `detectRetry: args must be an object with at minimum { tracesPath, epicId, storyId, threshold }; got ${args}`,
-    );
-  }
-  const { tracesPath, epicId, storyId, threshold } = args;
-  const taskId = args.taskId ?? null;
-  if (args.nowFn != null && typeof args.nowFn !== 'function') {
-    throw new TypeError(
-      `detectRetry: nowFn, when provided, must be a function (got ${typeof args.nowFn})`,
-    );
-  }
-  const nowFn = args.nowFn ?? (() => new Date().toISOString());
-
-  if (typeof tracesPath !== 'string' || tracesPath.length === 0) {
-    throw new TypeError(
-      `detectRetry: tracesPath must be a non-empty string (got ${tracesPath})`,
-    );
-  }
-  if (!isPositiveInt(epicId)) {
-    throw new RangeError(
-      `detectRetry: epicId must be a positive integer (got ${epicId})`,
-    );
-  }
-  if (!isPositiveInt(storyId)) {
-    throw new RangeError(
-      `detectRetry: storyId must be a positive integer (got ${storyId})`,
-    );
-  }
-  if (taskId !== null && !isPositiveInt(taskId)) {
-    throw new RangeError(
-      `detectRetry: taskId must be a positive integer or null (got ${taskId})`,
-    );
-  }
-  if (!Number.isInteger(threshold) || threshold < 0) {
-    throw new RangeError(
-      `detectRetry: threshold must be a non-negative integer (got ${threshold})`,
-    );
-  }
+  const { tracesPath, epicId, storyId, taskId, threshold, nowFn } =
+    validateDetectorArgs(args, { fnName: 'detectRetry' });
 
   const counts = await tallyFailuresByIdentity(tracesPath);
 

package/.agents/scripts/lib/signals/detectors/rework.js

@@ -52,7 +52,7 @@ import { createReadStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import { createInterface } from 'node:readline';
 
-import { extractTool, isPositiveInt } from './common.js';
+import { extractTool, validateDetectorArgs } from './common.js';
 
 /**
  * Tools that mutate files. Only these contribute to the per-target edit
@@ -140,45 +140,8 @@ async function tallyEditsByTarget(tracesPath) {
  *   conforming to `.agents/schemas/signal-event.schema.json`.
  */
 export async function detectRework(args) {
-  if (args == null || typeof args !== 'object') {
-    throw new TypeError(
-      `detectRework: args must be an object with at minimum { tracesPath, epicId, storyId, threshold }; got ${args}`,
-    );
-  }
-  const { tracesPath, epicId, storyId, threshold } = args;
-  const taskId = args.taskId ?? null;
-  if (args.nowFn != null && typeof args.nowFn !== 'function') {
-    throw new TypeError(
-      `detectRework: nowFn, when provided, must be a function (got ${typeof args.nowFn})`,
-    );
-  }
-  const nowFn = args.nowFn ?? (() => new Date().toISOString());
-
-  if (typeof tracesPath !== 'string' || tracesPath.length === 0) {
-    throw new TypeError(
-      `detectRework: tracesPath must be a non-empty string (got ${tracesPath})`,
-    );
-  }
-  if (!isPositiveInt(epicId)) {
-    throw new RangeError(
-      `detectRework: epicId must be a positive integer (got ${epicId})`,
-    );
-  }
-  if (!isPositiveInt(storyId)) {
-    throw new RangeError(
-      `detectRework: storyId must be a positive integer (got ${storyId})`,
-    );
-  }
-  if (taskId !== null && !isPositiveInt(taskId)) {
-    throw new RangeError(
-      `detectRework: taskId must be a positive integer or null (got ${taskId})`,
-    );
-  }
-  if (!Number.isInteger(threshold) || threshold < 0) {
-    throw new RangeError(
-      `detectRework: threshold must be a non-negative integer (got ${threshold})`,
-    );
-  }
+  const { tracesPath, epicId, storyId, taskId, threshold, nowFn } =
+    validateDetectorArgs(args, { fnName: 'detectRework' });
 
   const counts = await tallyEditsByTarget(tracesPath);