mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/knip-entry-sync.js

@@ -0,0 +1,508 @@
+/**
+ * knip-entry-sync.js — derive which top-level `.agents/scripts/*.js` CLIs are
+ * actually invoked, and diff that set against the `entry` array of whatever
+ * configuration knip itself would load (Story #5039; #5026 could only read a
+ * literal `knip.json`).
+ *
+ * Why this exists (Story #5001 → the #5012 near-miss):
+ *
+ * #5001 replaced the blanket `.agents/scripts/*.js!` entry glob with an
+ * explicit list, precisely so that a top-level CLI **nothing invokes** stops
+ * being declared live by the glob and surfaces as dead. It simultaneously
+ * promoted knip's `files` rule to `error`, so whole-file death now produces
+ * `{ file, symbol: '*' }` baseline rows.
+ *
+ * That pairing has a silent failure mode. A CLI added *after* #5001 is not in
+ * the hand-written list, so knip reads it as unreachable and emits a whole-file
+ * row for it — plus transitive rows for every lib module only that CLI imports.
+ * During #5012's delivery this produced 5 false rows (`check-baseline-scope.js`,
+ * `prune-baseline-orphans.js`, and their three `lib/baselines/*` modules). The
+ * natural remedy — accept the ratchet's diff — would have permanently recorded
+ * live, working operator CLIs as expected-dead, blinding the ratchet to their
+ * real death later. It was caught only because a base-sync conflict forced a
+ * manual read of the diff.
+ *
+ * The fix is to stop depending on a human remembering to edit the config.
+ * #5001's own wording already names the derivation rule — entries are derived
+ * "from what package.json scripts, husky hooks, .github/workflows, and the
+ * .agents workflow/skill markdown actually invoke". This module mechanizes
+ * exactly that rule and asserts it in both directions:
+ *
+ *   missing — invoked by a real caller but absent from `entry`. This is the
+ *     #5012 bug: knip will call it dead and the ratchet will offer to record
+ *     the lie.
+ *   stale — listed in `entry` but invoked by nothing. This is the blind spot
+ *     #5001 closed: a declared entry point is immortal, so its death can never
+ *     surface.
+ *
+ * Deliberately NOT a filesystem-derived list. Restoring `.agents/scripts/*.js!`
+ * — or regenerating the array from `readdirSync` — would make every file live
+ * by construction and undo #5001's AC-2. Liveness here means *invoked*, not
+ * *present*.
+ *
+ * Deliberately NOT conferred by documentation prose. `.agents/docs/**` and
+ * `docs/**` describe operator-run commands; a paragraph naming a CLI is not a
+ * caller. Three CLIs are named only in prose today
+ * (`check-baseline-drift.js`, `post-structured-comment.js`,
+ * `provision-git-hooks.js`) and #5001 recorded all of them as whole-file dead
+ * rows on purpose. Counting prose would silently resurrect them.
+ *
+ * A CLI that is only *imported* by another script (`cleanup-repo-test-temp.js`,
+ * imported by `run-tests.js` and `run-coverage.js`) is correctly neither: it is
+ * reachable through the module graph from a real entry, so knip already sees it
+ * and it must not be declared an entry point of its own.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  resolveKnipEntryPatterns,
+  __testing as resolverTesting,
+} from './knip-config-resolver.js';
+
+// Only `resolveEntrySync` and `renderEntrySyncReport` are public — they are
+// what `check-knip-entries.js` calls. Everything else is module-private and
+// reached by the suite through the `__testing` bundle at the foot of this file,
+// the same seam `source-classifier.js` and five sibling modules use. Exporting
+// the internals individually would put seven test-only symbols on the
+// production dead-export baseline and make private helpers look like API.
+
+/** Top-level CLI directory, repo-relative. */
+const SCRIPTS_DIR = path.join('.agents', 'scripts');
+
+/**
+ * Executable surfaces — a mention of a CLI here is an instruction to run it.
+ *
+ * `dirs` entries are walked recursively and filtered by `test`. `files` are
+ * read directly. Documentation trees are absent by design (see module header).
+ *
+ * @type {ReadonlyArray<{ kind: 'file' | 'dir', at: string, test?: RegExp }>}
+ */
+const INVOCATION_SURFACES = Object.freeze([
+  { kind: 'file', at: 'package.json' },
+  { kind: 'dir', at: '.husky', test: /^(?!.*[/\\]_[/\\]).*$/ },
+  { kind: 'dir', at: path.join('.github', 'workflows'), test: /\.ya?ml$/ },
+  { kind: 'dir', at: path.join('.agents', 'workflows'), test: /\.md$/ },
+  { kind: 'dir', at: path.join('.agents', 'skills'), test: /\.md$/ },
+  { kind: 'dir', at: path.join('.agents', 'agents'), test: /\.md$/ },
+  { kind: 'dir', at: path.join('.agents', 'rules'), test: /\.md$/ },
+  { kind: 'dir', at: SCRIPTS_DIR, test: /\.js$/ },
+]);
+
+/**
+ * Strip line and block comments from JavaScript source, preserving string and
+ * template literals so a `'https://…'` or a `` `${x}//y` `` is not mangled.
+ *
+ * Comments are stripped before scanning `.js` surfaces so a JSDoc paragraph
+ * that merely *names* a CLI ("superseded by `node .agents/scripts/foo.js`")
+ * cannot confer liveness on it. Several such mentions exist today; every one
+ * of them is prose about a script's internals, not a call.
+ *
+ * Replaces comment bodies with equivalent whitespace rather than deleting
+ * them, so byte offsets and line numbers survive for any future caller that
+ * wants to report a position.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+function stripJsComments(source) {
+  const text = String(source ?? '');
+  let out = '';
+  let i = 0;
+  const blank = (s) => s.replace(/[^\n]/g, ' ');
+  while (i < text.length) {
+    const two = text.slice(i, i + 2);
+    if (two === '//') {
+      const end = text.indexOf('\n', i);
+      const stop = end === -1 ? text.length : end;
+      out += blank(text.slice(i, stop));
+      i = stop;
+    } else if (two === '/*') {
+      const end = text.indexOf('*/', i + 2);
+      const stop = end === -1 ? text.length : end + 2;
+      out += blank(text.slice(i, stop));
+      i = stop;
+    } else {
+      const ch = text[i];
+      if (ch === "'" || ch === '"' || ch === '`') {
+        let j = i + 1;
+        while (j < text.length) {
+          if (text[j] === '\\') {
+            j += 2;
+            continue;
+          }
+          if (text[j] === ch) break;
+          j += 1;
+        }
+        const stop = Math.min(j + 1, text.length);
+        out += text.slice(i, stop);
+        i = stop;
+      } else {
+        out += ch;
+        i += 1;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Recursively list files under `dir`, skipping `node_modules` and `.git`.
+ *
+ * @param {string} dir absolute path
+ * @param {typeof fs} fsImpl
+ * @param {string[]} [acc]
+ * @returns {string[]} absolute file paths
+ */
+function walk(dir, fsImpl, acc = []) {
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      walk(full, fsImpl, acc);
+    } else {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+/**
+ * Read every executable surface under `repoRoot`.
+ *
+ * `.js` surfaces arrive comment-stripped; every other surface arrives verbatim.
+ * Test files are excluded: a test importing or naming a CLI does not make it
+ * invoked, which is the same test-only-importer discount `--production` applies
+ * to the dead-exports ratchet itself.
+ *
+ * @param {{ repoRoot: string, fsImpl?: typeof fs }} opts
+ * @returns {Array<{ path: string, text: string }>} repo-relative path + content
+ */
+function collectInvocationSurfaces({ repoRoot, fsImpl = fs }) {
+  const surfaces = [];
+  const push = (absolute) => {
+    const rel = path.relative(repoRoot, absolute);
+    if (rel.includes('__tests__') || /\.test\.[cm]?js$/.test(rel)) return;
+    let text;
+    try {
+      text = fsImpl.readFileSync(absolute, 'utf8');
+    } catch {
+      return;
+    }
+    surfaces.push({
+      path: rel.split(path.sep).join('/'),
+      text: rel.endsWith('.js') ? stripJsComments(text) : text,
+    });
+  };
+
+  for (const surface of INVOCATION_SURFACES) {
+    const absolute = path.join(repoRoot, surface.at);
+    if (surface.kind === 'file') {
+      push(absolute);
+      continue;
+    }
+    for (const file of walk(absolute, fsImpl)) {
+      const rel = path.relative(repoRoot, file);
+      if (surface.test && !surface.test.test(rel)) continue;
+      push(file);
+    }
+  }
+  return surfaces;
+}
+
+/**
+ * Build the two recognizers for one CLI basename.
+ *
+ * `pathLiteral` — the CLI named by its repo path (`.agents/scripts/foo.js`),
+ *   in either separator style. This is how package.json scripts, husky hooks,
+ *   workflow `run:` blocks and workflow markdown spell an invocation.
+ *
+ * `joinedSpawn` — the CLI named by bare basename as the tail of a
+ *   `path.join(…, 'scripts', 'foo.js')` construction, which is how
+ *   `lib/bootstrap/project-bootstrap.js` spawns `check-windows-git-perf.js`
+ *   into a consumer checkout. Requiring the `'scripts'` sibling argument is
+ *   what separates a real spawn from the several *data* inventories that list
+ *   the same basenames as plain array elements (`source-classifier.js`'s
+ *   `FRAMEWORK_SCRIPT_BASENAMES`, `check-lifecycle-lint.js`'s allowlist) —
+ *   those are catalogues of names, not calls.
+ *
+ * @param {string} cli basename, e.g. `check-dead-exports.js`
+ * @returns {{ pathLiteral: RegExp, joinedSpawn: RegExp }}
+ */
+function buildInvocationPatterns(cli) {
+  const escaped = cli.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return {
+    pathLiteral: new RegExp(`\\.agents[/\\\\]scripts[/\\\\]${escaped}`),
+    joinedSpawn: new RegExp(
+      `['"\`]scripts['"\`]\\s*,\\s*['"\`]${escaped}['"\`]`,
+    ),
+  };
+}
+
+/**
+ * List the top-level CLI basenames actually present in `.agents/scripts/`.
+ *
+ * @param {{ repoRoot: string, fsImpl?: typeof fs }} opts
+ * @returns {string[]} sorted basenames
+ */
+function listTopLevelClis({ repoRoot, fsImpl = fs }) {
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(path.join(repoRoot, SCRIPTS_DIR), {
+      withFileTypes: true,
+    });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.js'))
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Read the `.agents/scripts/*.js` basenames declared as knip entry points.
+ *
+ * Resolution goes through knip's own loader — see
+ * `knip-config-resolver.js` for why, and for the skipped / error / resolved
+ * contract this forwards. All this adds is the projection onto top-level CLI
+ * basenames: glob-bearing patterns are dropped, so what remains is the explicit
+ * enumeration #5001 made authoritative.
+ *
+ * The trailing `!` is knip's production-mode marker and is load-bearing, not
+ * decoration: in a `--production` run knip keeps only the suffixed entries and
+ * *negates* the rest (`WorkspaceWorker`'s `hasProductionSuffix` /
+ * `hasNoProductionSuffix` split). So an entry written without it leaves the CLI
+ * unreachable in exactly the pass that emits whole-file rows — the #5012 shape
+ * this gate exists to catch. Reading it as satisfied would point the operator
+ * away from the cause, so unsuffixed entries are reported as their own
+ * divergence rather than silently normalized. `createOptions` preserves the
+ * suffix, so the marker survives resolution.
+ *
+ * @param {{ repoRoot: string, loadKnipSession?: () => Promise<object> }} opts
+ * @returns {Promise<{
+ *   entries: string[],
+ *   unsuffixed: string[],
+ *   configFilePath: string | null,
+ *   skipped: string | null,
+ *   error: string | null,
+ * }>}
+ */
+async function readKnipEntries({ repoRoot, loadKnipSession }) {
+  const { patterns, configFilePath, skipped, error } =
+    await resolveKnipEntryPatterns({ repoRoot, loadKnipSession });
+  if (skipped || error) {
+    return { entries: [], unsuffixed: [], configFilePath, skipped, error };
+  }
+
+  const prefix = '.agents/scripts/';
+  const declared = patterns
+    .filter((e) => e.startsWith(prefix) && !e.includes('*'))
+    .map((e) => ({
+      cli: e.slice(prefix.length).replace(/!$/, ''),
+      suffixed: e.endsWith('!'),
+    }))
+    .filter((e) => !e.cli.includes('/'));
+
+  return {
+    entries: [...new Set(declared.map((e) => e.cli))].sort(),
+    unsuffixed: [
+      ...new Set(declared.filter((e) => !e.suffixed).map((e) => e.cli)),
+    ].sort(),
+    configFilePath,
+    skipped: null,
+    error: null,
+  };
+}
+
+/**
+ * Resolve the full entry-sync report for a repository.
+ *
+ * Async because knip's config loader is: a `knip.config.ts` has to be
+ * *evaluated*, not read. `EntrySync` names entry-list synchronization, not
+ * synchronous I/O, so the name still describes what this returns.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   fsImpl?: typeof fs,
+ *   loadKnipSession?: () => Promise<object>,
+ * }} opts
+ * @returns {Promise<{
+ *   error: string | null,
+ *   skipped: string | null,
+ *   configFilePath: string | null,
+ *   clis: string[],
+ *   declared: string[],
+ *   missing: Array<{ cli: string, invokers: string[] }>,
+ *   stale: string[],
+ *   phantom: string[],
+ *   unsuffixed: string[],
+ * }>}
+ *   `skipped` — nothing to check; the caller passes rather than failing.
+ *   `missing` — invoked but not declared (the #5012 bug).
+ *   `stale` — declared but invoked by nothing.
+ *   `phantom` — declared but no such file on disk (a rename left the list behind).
+ *   `unsuffixed` — declared without the `!` production marker, which knip's
+ *     production pass negates rather than honours (the #5012 bug wearing a
+ *     declared entry).
+ */
+export async function resolveEntrySync({
+  repoRoot,
+  fsImpl = fs,
+  loadKnipSession,
+}) {
+  const {
+    entries: declared,
+    unsuffixed,
+    configFilePath,
+    skipped,
+    error,
+  } = await readKnipEntries({ repoRoot, loadKnipSession });
+  const empty = {
+    skipped: null,
+    configFilePath,
+    clis: [],
+    declared,
+    missing: [],
+    stale: [],
+    phantom: [],
+    unsuffixed: [],
+  };
+  if (skipped) return { error: null, ...empty, skipped };
+  if (error) return { error, ...empty };
+
+  const clis = listTopLevelClis({ repoRoot, fsImpl });
+  if (clis.length === 0) {
+    return { error: `no CLIs found under ${SCRIPTS_DIR}`, ...empty };
+  }
+  const surfaces = collectInvocationSurfaces({ repoRoot, fsImpl });
+  const declaredSet = new Set(declared);
+
+  const missing = [];
+  const stale = [];
+  for (const cli of clis) {
+    const self = `${SCRIPTS_DIR.split(path.sep).join('/')}/${cli}`;
+    const { pathLiteral, joinedSpawn } = buildInvocationPatterns(cli);
+    const invokers = surfaces
+      .filter(
+        (s) =>
+          s.path !== self &&
+          (pathLiteral.test(s.text) ||
+            (s.path.endsWith('.js') && joinedSpawn.test(s.text))),
+      )
+      .map((s) => s.path);
+    const isDeclared = declaredSet.has(cli);
+    if (invokers.length > 0 && !isDeclared) missing.push({ cli, invokers });
+    if (invokers.length === 0 && isDeclared) stale.push(cli);
+  }
+
+  const onDisk = new Set(clis);
+  const phantom = declared.filter((cli) => !onDisk.has(cli));
+
+  return {
+    error: null,
+    skipped: null,
+    configFilePath,
+    clis,
+    declared,
+    missing,
+    stale,
+    phantom,
+    unsuffixed,
+  };
+}
+
+/**
+ * Total divergences across every direction. Single source of the gate's
+ * pass/fail arithmetic so a newly added direction cannot be counted in the
+ * report but missed by the exit code.
+ *
+ * @param {ReturnType<typeof resolveEntrySync>} report
+ * @returns {number}
+ */
+export function countDivergences(report) {
+  return (
+    report.missing.length +
+    report.stale.length +
+    report.phantom.length +
+    report.unsuffixed.length
+  );
+}
+
+/**
+ * Render the human-readable report. Each divergence names its own remedy —
+ * the whole point of the gate is that the *wrong* remedy (accepting the
+ * dead-exports ratchet's diff) is the tempting one.
+ *
+ * @param {ReturnType<typeof resolveEntrySync>} report
+ * @returns {string}
+ */
+export function renderEntrySyncReport(report) {
+  const lines = [];
+  for (const { cli, invokers } of report.missing) {
+    lines.push(
+      `+ ${cli} — invoked by ${invokers.slice(0, 3).join(', ')}${
+        invokers.length > 3 ? ` (+${invokers.length - 3} more)` : ''
+      }`,
+    );
+    lines.push(
+      `    add ".agents/scripts/${cli}!" to knip.json "entry" — until you do, knip`,
+    );
+    lines.push(
+      '    reads it as unreachable and check-dead-exports will offer a false whole-file row.',
+    );
+  }
+  for (const cli of report.stale) {
+    lines.push(
+      `- ${cli} — declared in knip.json "entry" but nothing invokes it`,
+    );
+    lines.push(
+      '    remove the entry so its death can surface, or wire up the caller.',
+    );
+  }
+  for (const cli of report.phantom) {
+    lines.push(`? ${cli} — declared in knip.json "entry" but not on disk`);
+    lines.push('    drop the stale path (the file was renamed or removed).');
+  }
+  for (const cli of report.unsuffixed) {
+    lines.push(`! ${cli} — declared in knip.json "entry" without a "!" suffix`);
+    lines.push(
+      `    write it as ".agents/scripts/${cli}!" — the production pass negates an`,
+    );
+    lines.push(
+      '    unsuffixed entry, so knip still reads the CLI as unreachable.',
+    );
+  }
+  const total = countDivergences(report);
+  lines.push(
+    `[knip-entries] clis=${report.clis.length} declared=${report.declared.length} ` +
+      `missing=${report.missing.length} stale=${report.stale.length} ` +
+      `phantom=${report.phantom.length} unsuffixed=${report.unsuffixed.length} ` +
+      `${total > 0 ? '(gate fail)' : '(ok)'}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Test-only seam. Not API: these helpers are exercised directly by
+ * `tests/check-knip-entries.test.js` so the recognizers can be pinned
+ * independently of a full fixture tree.
+ */
+export const __testing = Object.freeze({
+  buildInvocationPatterns,
+  // Re-exported from `knip-config-resolver.js` so the suite reaches the whole
+  // gate through one seam rather than importing two modules to test one gate.
+  collectEntryPatterns: resolverTesting.collectEntryPatterns,
+  collectInvocationSurfaces,
+  INVOCATION_SURFACES,
+  listTopLevelClis,
+  readKnipEntries,
+  SCRIPTS_DIR,
+  stripJsComments,
+});

package/.agents/scripts/lib/observability/metrics-ledger.js

@@ -74,7 +74,7 @@ export const MAX_LEDGER_BYTES = 1024 * 1024;
 
 /**
  * Resolve the ledger path for an Epic (or the standalone stream when
- * `epicId` is `null` — the `story-plan.js` / Epic-less healthcheck case).
+ * `epicId` is `null` — the v2 Epic-less plan/healthcheck case).
  *
  * @param {number|null} epicId
  * @param {object} [config] Resolved config (threads `project.paths.tempRoot`).

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -83,6 +83,16 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
    * ceilings recalibratable from recorded evidence.
    */
   LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
+  /**
+   * An operator overrode a Story-scope code-review critical blocker with
+   * `--override-review-block <reason>`. Deliberately its own
+   * bucket: this is the one signal that says a gate's verdict was rejected by
+   * a human who then shipped anyway, so a rising `occurrences` count is direct
+   * evidence the gate is miscalibrated rather than the code being bad. It is
+   * *not* `TOOL_DEGRADED` — the tool ran fine and produced a verdict; what
+   * failed was the verdict's usefulness.
+   */
+  REVIEW_BLOCK_OVERRIDDEN: 'review-block-overridden',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */

package/.agents/scripts/lib/observability/signal-validator.js

@@ -17,22 +17,20 @@
  * document (no hand-rolled drift). `strict: false` matches the repo's
  * other draft-07 validators (see `tests/schemas/signal-schemas.test.js`).
  *
- * A per-Epic reject tally is persisted under the Epic temp tree
- * (`temp/run-<eid>/signal-rejects.json`) so a cross-process reader (the
- * loop-health check, a follow-on Story) can surface how many records were
- * dropped. The tally is read-modify-written best-effort; a lost increment
- * under a write race is acceptable for a diagnostic counter.
+ * Story #5003 deleted the persisted per-Epic reject tally
+ * (`temp/run-<eid>/signal-rejects.json`) and its `readSignalRejectCount`
+ * reader: the tally was keyed on a positive `epicId`, and v2 Stories are
+ * standalone, so nothing ever wrote a row and nothing could ever read one.
+ * Write-time validation itself is untouched.
  */
 
 import { readFileSync } from 'node:fs';
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 
-import { runArtifactPath } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -45,8 +43,6 @@ const SCHEMA_PATH = path.resolve(
   'signal-event.schema.json',
 );
 
-const REJECT_TALLY_BASENAME = 'signal-rejects.json';
-
 /**
  * Compile the signal-event schema once. Returns `null` when the schema
  * cannot be read or compiled — the caller then treats every record as
@@ -126,79 +122,3 @@ export function validateSignal(record) {
   const message = _validate.errors?.[0]?.message ?? 'schema validation failed';
   return { valid: false, violatingField: field, message };
 }
-
-/**
- * Increment the per-Epic reject tally persisted under the Epic temp tree.
- * Best-effort and never throws: a missing/corrupt tally file resets to a
- * count of 1. When `epicId` is not a positive integer (e.g. a standalone
- * friction record with `epicId: null`) the tally write is skipped — there
- * is no Epic temp tree to anchor it to.
- *
- * @param {{ epicId: number|null|undefined, config?: object, field?: string|null }} args
- * @returns {Promise<number|null>} the new count, or null when skipped/failed.
- */
-export async function recordSignalReject({ epicId, config, field }) {
-  if (!Number.isInteger(epicId) || epicId <= 0) return null;
-  let target;
-  try {
-    target = runArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
-  } catch {
-    return null;
-  }
-  try {
-    let prior = { count: 0, lastField: null };
-    try {
-      const raw = await fs.readFile(target, 'utf8');
-      const parsed = JSON.parse(raw);
-      if (
-        parsed &&
-        typeof parsed === 'object' &&
-        Number.isFinite(parsed.count)
-      ) {
-        prior = { count: parsed.count, lastField: parsed.lastField ?? null };
-      }
-    } catch {
-      // Missing or corrupt file → start a fresh tally.
-    }
-    const next = {
-      count: prior.count + 1,
-      lastField: field ?? prior.lastField ?? null,
-      updatedAt: new Date().toISOString(),
-    };
-    await fs.mkdir(path.dirname(target), { recursive: true });
-    await fs.writeFile(target, `${JSON.stringify(next)}\n`, 'utf8');
-    return next.count;
-  } catch (err) {
-    Logger.warn(
-      `signal-validator: failed to persist reject tally for epic-${epicId}: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return null;
-  }
-}
-
-/**
- * Read the current per-Epic reject count. Cross-process readable
- * counterpart to {@link recordSignalReject}. Returns 0 when the tally
- * file is absent or unreadable.
- *
- * @param {{ epicId: number, config?: object }} args
- * @returns {Promise<number>}
- */
-export async function readSignalRejectCount({ epicId, config }) {
-  if (!Number.isInteger(epicId) || epicId <= 0) return 0;
-  let target;
-  try {
-    target = runArtifactPath(epicId, REJECT_TALLY_BASENAME, config);
-  } catch {
-    return 0;
-  }
-  try {
-    const raw = await fs.readFile(target, 'utf8');
-    const parsed = JSON.parse(raw);
-    return parsed && Number.isFinite(parsed.count) ? parsed.count : 0;
-  } catch {
-    return 0;
-  }
-}