mandrel 1.57.0

package/.agents/scripts/lib/checks/story-init-not-backgrounded.js

@@ -0,0 +1,186 @@
+/**
+ * story-init-not-backgrounded — refuse-and-print check.
+ *
+ * Detects orchestration call sites that invoke `story-init.js` via the
+ * Bash tool's `run_in_background: true` mode (with subsequent `Monitor`
+ * waiting on completion) instead of a synchronous Bash call with a
+ * 10-minute timeout. This guards the failure mode where `Monitor`'s wait
+ * is not equivalent to script exit — a sub-agent that exits during a
+ * Monitor wait kills `story-init.js` mid-batch, leaving a half-initialized
+ * worktree and a failed wave aggregator.
+ *
+ * Scope: 'epic-deliver', 'story-close', 'retro'. The check runs at every
+ * preflight surface that has the opportunity to invoke story-init —
+ * primarily `epic-deliver`'s wave loop — and surfaces as a retro audit
+ * signal if the failure mode resurfaces during a sprint.
+ *
+ * The check is `refuse-and-print`. Auto-rewriting an orchestration call
+ * site would change runtime behavior on a script the operator may be
+ * actively iterating on; the fixCommand prints the canonical
+ * synchronous-call replacement pattern so they can apply it deliberately.
+ *
+ * Implementation note: we scan `.agents/` (markdown + js) for the
+ * juxtaposition of a `story-init.js` reference and a backgrounding token
+ * (`run_in_background: true`, the literal `Monitor` tool name as a
+ * fan-out target, or `&` shell backgrounding) within a small line window.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const SCAN_ROOT_DEFAULT = '.agents';
+const WINDOW_LINES = 20;
+
+/**
+ * Backgrounding tokens. We only match shapes that are unambiguously
+ * *invocation* syntax, never narrative prose like "do not use Monitor"
+ * (which legitimately appears in docs warning against the antipattern).
+ *
+ * - `run_in_background: true` — Bash tool's backgrounding flag.
+ * - `detached: true` — child_process.spawn options that detach the
+ *   subprocess from the parent's lifecycle, equivalent to backgrounding.
+ * - `story-init.js &` — POSIX shell ampersand backgrounding.
+ */
+const BACKGROUND_TOKENS = [
+  /run_in_background\s*:\s*true/,
+  /detached\s*:\s*true/,
+  /story-init\.js[^\n`]*[ \t]&[ \t]*(?:#|$)/m,
+];
+
+/**
+ * Walk a directory recursively, yielding absolute file paths for `.js`
+ * and `.md` sources. Skips `node_modules`, `.worktrees`, and directories
+ * starting with `.git`.
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkSources(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (
+        entry.name === 'node_modules' ||
+        entry.name === '.worktrees' ||
+        entry.name.startsWith('.git')
+      ) {
+        continue;
+      }
+      out.push(...walkSources(full));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!/\.(js|mjs|cjs|md)$/.test(entry.name)) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+/**
+ * For one file, return an array of `{ line, kind }` offences: every line
+ * referencing `story-init.js` that has a backgrounding token in the same
+ * ±WINDOW_LINES window.
+ *
+ * The check explicitly excludes the `story-init.js` file itself and any
+ * dedicated check module (this file): the source-of-truth implementation
+ * legitimately mentions itself.
+ *
+ * @param {string} file
+ * @param {string} src
+ * @returns {Array<{ line: number, kind: string }>}
+ */
+function scanFile(file, src) {
+  const offences = [];
+  // Don't flag the actual story-init script, self-references, or the
+  // parallel-tooling helper — the helper documents both Rule 2
+  // (run_in_background) and the story-init.js anti-pattern in adjacent
+  // bullets, which collides with the scanner's ±20-line window even
+  // though there is no real invocation in the prose.
+  const basename = path.basename(file);
+  if (
+    basename === 'story-init.js' ||
+    basename === 'story-init-not-backgrounded.js' ||
+    basename === 'story-init-not-backgrounded.test.js' ||
+    basename === 'parallel-tooling.md'
+  ) {
+    return offences;
+  }
+  const lines = src.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (!/story-init\.js/.test(lines[i])) continue;
+    const start = Math.max(0, i - WINDOW_LINES);
+    const end = Math.min(lines.length, i + WINDOW_LINES + 1);
+    const window = lines.slice(start, end).join('\n');
+    for (const tok of BACKGROUND_TOKENS) {
+      if (tok.test(window)) {
+        offences.push({ line: i + 1, kind: tok.source });
+        break;
+      }
+    }
+  }
+  return offences;
+}
+
+const FIX_COMMAND = [
+  '# Invoke story-init.js synchronously with a 10-minute timeout. The',
+  '# script is idempotent on partial state, so re-running after a',
+  '# half-initialized worktree is safe — but blocking on the Bash call',
+  '# is what prevents the half-init state in the first place.',
+  '#',
+  '# Replacement pattern (Bash tool):',
+  '#   Bash(timeout: 600000, command: "node .agents/scripts/story-init.js --story <id>")',
+  '#',
+  '# Do NOT use:',
+  '#   Bash(run_in_background: true, ...) + Monitor(...)',
+].join('\n');
+
+export default {
+  id: 'story-init-not-backgrounded',
+  severity: 'blocker',
+  scope: ['epic-deliver', 'story-close', 'retro'],
+  autoCorrect: 'refuse-and-print',
+
+  detect(state) {
+    const cwd = state?.cwd ?? process.cwd();
+    const root = state?.scanRoot ?? path.join(cwd, SCAN_ROOT_DEFAULT);
+    const files = walkSources(root);
+    const offences = [];
+    for (const file of files) {
+      let src;
+      try {
+        src = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      if (!/story-init\.js/.test(src)) continue;
+      const fileOffences = scanFile(file, src);
+      for (const o of fileOffences) {
+        offences.push({
+          file: path.relative(root, file).replace(/\\/g, '/'),
+          line: o.line,
+          kind: o.kind,
+        });
+      }
+    }
+    if (offences.length === 0) return null;
+    const detail = offences
+      .map((o) => `${o.file}:${o.line} — backgrounding token /${o.kind}/`)
+      .join('\n');
+    return {
+      id: 'story-init-not-backgrounded',
+      severity: 'blocker',
+      scope: state?.scope ?? 'epic-deliver',
+      summary: `${offences.length} orchestration call site(s) invoke story-init.js with Monitor backgrounding`,
+      detail,
+      fixCommand: FIX_COMMAND,
+      autoCorrectable: false,
+    };
+  },
+};

package/.agents/scripts/lib/checks/subagent-agent-tool-required.js

@@ -0,0 +1,182 @@
+/**
+ * subagent-agent-tool-required — refuse-and-print check.
+ *
+ * Detects sub-agent workflow definitions that declare access to the
+ * `Agent` tool (or otherwise document nested Agent dispatch). Nested
+ * Agent dispatch is not supported in this Claude Code, so any
+ * wave-runner-as-sub-agent or cascading fan-out design that declares
+ * `Agent` in its tool list will silently fail at runtime. The remediation
+ * is to flatten the fan-out back to the host agent and run sub-agents at
+ * one level only.
+ *
+ * Scope: 'epic-deliver', 'retro'. Surfaces as a blocker at preflight for
+ * `epic-deliver` (the fan-out site) and as audit signal at retro.
+ *
+ * The check is `refuse-and-print` — auto-rewriting a workflow's tool
+ * list would silently change runtime behavior in ways the operator may
+ * not have intended (the workflow's logic may depend on the missing
+ * tool). The fixCommand cites the flatten-fan-out remediation pattern.
+ *
+ * Implementation note: we scan `.agents/workflows/*.md` for workflow
+ * files whose frontmatter or body identifies them as a sub-agent role
+ * AND whose `tools:` declaration includes `Agent`. The marker for
+ * "sub-agent" is the phrase `sub-agent` appearing in the description /
+ * overview region. This keeps the check stable while the workflow
+ * surface evolves — the project doesn't yet have a structured
+ * `role: sub-agent` frontmatter field, and the textual marker is what
+ * the human contributors actually grep for.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const WORKFLOWS_DIR_DEFAULT = path.join('.agents', 'workflows');
+
+/**
+ * Walk a workflow directory and return absolute `.md` file paths
+ * (non-recursive — the workflows surface is one level deep; helpers/
+ * sub-directory holds procedural modules that are not invoked as
+ * sub-agents in their own right).
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function listWorkflowFiles(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(dir, e.name));
+}
+
+/**
+ * Extract the frontmatter block (between leading `---` lines) and the
+ * body. Returns `{ frontmatter, body }` strings (either may be empty).
+ *
+ * @param {string} src
+ * @returns {{ frontmatter: string, body: string }}
+ */
+function splitFrontmatter(src) {
+  if (!src.startsWith('---')) return { frontmatter: '', body: src };
+  const end = src.indexOf('\n---', 3);
+  if (end === -1) return { frontmatter: '', body: src };
+  const frontmatter = src.slice(3, end);
+  // Skip past the closing `---` and the trailing newline.
+  const bodyStart = src.indexOf('\n', end + 4);
+  const body = bodyStart === -1 ? '' : src.slice(bodyStart + 1);
+  return { frontmatter, body };
+}
+
+/**
+ * True if the workflow document declares itself as a sub-agent. We
+ * accept either the literal phrase `sub-agent` in the
+ * description/overview region or the explicit phrase `runs as a
+ * sub-agent`. The marker has to appear early in the document — past
+ * the first ~100 lines we treat the mention as historical context
+ * rather than a role declaration.
+ *
+ * @param {string} src
+ * @returns {boolean}
+ */
+function isSubAgentWorkflow(src) {
+  const head = src.split(/\r?\n/).slice(0, 100).join('\n');
+  return /\bsub-agent\b/.test(head);
+}
+
+/**
+ * Inspect a workflow's `tools:` declaration (frontmatter OR inline body
+ * note) for an `Agent` entry. Returns the offending textual fragment
+ * (for the finding's detail field), or `null` if no `Agent` tool is
+ * declared.
+ *
+ * @param {{ frontmatter: string, body: string }} parts
+ * @returns {string | null}
+ */
+function findAgentToolDeclaration(parts) {
+  const { frontmatter, body } = parts;
+  // Frontmatter YAML — match either `tools: [..., Agent, ...]` (flow
+  // style) or block style with `- Agent`.
+  const flowMatch = frontmatter.match(/tools\s*:\s*\[(.*?)\]/s);
+  if (flowMatch && /\bAgent\b/.test(flowMatch[1])) {
+    return `frontmatter tools: ${flowMatch[0].slice(0, 120)}`;
+  }
+  // Block-style: `tools:` followed by `- item` lines. Use `m` flag and
+  // tolerate the trailing item line having no newline before the
+  // frontmatter terminator.
+  const blockMatch = frontmatter.match(
+    /tools\s*:\s*\n((?:[ \t]*-[ \t]*[^\n]+\n?)+)/,
+  );
+  if (blockMatch && /^[ \t]*-[ \t]*Agent\b/m.test(blockMatch[1])) {
+    return `frontmatter tools (block): ${blockMatch[0].split('\n')[0]}`;
+  }
+  // Body: same shape, e.g. operators sometimes document the tool list
+  // in a "## Tools" section. We accept either of the YAML shapes
+  // appearing in fenced code or inline.
+  const bodyFlow = body.match(/tools\s*:\s*\[(.*?)\]/s);
+  if (bodyFlow && /\bAgent\b/.test(bodyFlow[1])) {
+    return `body tools: ${bodyFlow[0].slice(0, 120)}`;
+  }
+  const bodyBlock = body.match(/tools\s*:\s*\n((?:\s*-\s*[^\n]+\n)+)/);
+  if (bodyBlock && /^\s*-\s*Agent\b/m.test(bodyBlock[1])) {
+    return `body tools (block): ${bodyBlock[0].split('\n')[0]}`;
+  }
+  return null;
+}
+
+const FIX_COMMAND = [
+  '# Flatten fan-out to the host. Sub-agents cannot dispatch other agents.',
+  "# Remove the `Agent` entry from this workflow's `tools:` declaration,",
+  '# move any fan-out logic up to the parent / host invocation, and have',
+  '# the parent dispatch the leaf sub-agents directly.',
+  '#',
+  '# Pattern (host workflow):',
+  '#   for each child: Agent(prompt=<child workflow>, args=<id>)',
+  '#',
+  '# Pattern (sub-agent workflow):',
+  '#   tools: [Bash, Read, Edit, Grep, Glob, Write]   # NO Agent',
+].join('\n');
+
+export default {
+  id: 'subagent-agent-tool-required',
+  severity: 'blocker',
+  scope: ['epic-deliver', 'retro'],
+  autoCorrect: 'refuse-and-print',
+
+  detect(state) {
+    const cwd = state?.cwd ?? process.cwd();
+    const root = state?.scanRoot ?? path.join(cwd, WORKFLOWS_DIR_DEFAULT);
+    const files = listWorkflowFiles(root);
+    const offences = [];
+    for (const file of files) {
+      let src;
+      try {
+        src = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      if (!isSubAgentWorkflow(src)) continue;
+      const parts = splitFrontmatter(src);
+      const where = findAgentToolDeclaration(parts);
+      if (!where) continue;
+      offences.push({
+        file: path.relative(root, file).replace(/\\/g, '/'),
+        where,
+      });
+    }
+    if (offences.length === 0) return null;
+    const detail = offences.map((o) => `${o.file} — ${o.where}`).join('\n');
+    return {
+      id: 'subagent-agent-tool-required',
+      severity: 'blocker',
+      scope: state?.scope ?? 'epic-deliver',
+      summary: `${offences.length} sub-agent workflow(s) declare Agent in their tool list — nested Agent dispatch is unsupported`,
+      detail,
+      fixCommand: FIX_COMMAND,
+      autoCorrectable: false,
+    };
+  },
+};

package/.agents/scripts/lib/checks/windows-coverage-noise-floor.js

@@ -0,0 +1,92 @@
+/**
+ * windows-coverage-noise-floor — refuse-and-print warning check.
+ *
+ * Detects coverage-gate deltas that are within the Windows / Node-22
+ * noise floor — i.e., tiny fractional branch-coverage swings that vary
+ * run-to-run and would chase the gate to a different file if the
+ * operator ratcheted from a flapping CI artifact. The canonical mistake
+ * is to fetch a failing run's coverage delta and bump the baseline by
+ * that delta, which simply moves the noise floor to another file rather
+ * than stabilising the gate.
+ *
+ * Scope: 'story-close', 'retro'. The check is `warning` severity (not
+ * `blocker`) because flapping is informational — the operator decides
+ * whether to ratchet, skip, or investigate. Coverage-blocking belongs
+ * to a separate baseline-refresh gate.
+ *
+ * The check is `refuse-and-print`. A `fix()` here would mean either
+ * suppressing the flap (which silently lowers signal) or ratcheting
+ * (which is the very mistake the check exists to prevent). The
+ * fixCommand advises against ratcheting from a flapping artifact.
+ *
+ * Input shape — the check reads `state.coverage`:
+ *   {
+ *     branchDelta: number,         // signed fractional delta (e.g. 0.0015 = +0.15%)
+ *     noiseFloor?: number,         // optional override; default 0.0025
+ *     file?: string,               // optional file the delta is attributed to
+ *   }
+ *
+ * Returns null when `state.coverage` is absent (the assembler does not
+ * always populate coverage; absent input is a no-op rather than a
+ * failure).
+ */
+
+const DEFAULT_NOISE_FLOOR = 0.0025; // 0.25%
+
+const FIX_COMMAND = [
+  '# Do NOT ratchet the coverage baseline from a flapping CI artifact.',
+  '# A delta within the Windows / Node-22 noise floor (< 0.25% by default)',
+  '# is run-to-run jitter, not real coverage loss. Ratcheting in response',
+  '# moves the noise floor to a different file rather than fixing it.',
+  '#',
+  '# Instead: re-run the gate. If the delta persists across multiple runs',
+  '# in the same file, investigate the specific test that flipped — most',
+  '# often a Date.now() / Math.random() leak into the branch decision.',
+  '#',
+  '# If the delta is real but small, capture a fresh baseline-refresh',
+  '# commit deliberately, separate from the failing PR.',
+].join('\n');
+
+export default {
+  id: 'windows-coverage-noise-floor',
+  severity: 'warning',
+  scope: ['story-close', 'retro'],
+  autoCorrect: 'refuse-and-print',
+
+  detect(state) {
+    const cov = state?.coverage;
+    if (!cov || typeof cov !== 'object') return null;
+    if (typeof cov.branchDelta !== 'number' || Number.isNaN(cov.branchDelta)) {
+      return null;
+    }
+    const noiseFloor =
+      typeof cov.noiseFloor === 'number' && cov.noiseFloor > 0
+        ? cov.noiseFloor
+        : DEFAULT_NOISE_FLOOR;
+    const absDelta = Math.abs(cov.branchDelta);
+    // Within (or equal to) the floor → flapping → warning.
+    // Above the floor → real signal → return null and let the actual
+    // coverage gate decide.
+    if (absDelta > noiseFloor) {
+      return null;
+    }
+    const deltaPct = (cov.branchDelta * 100).toFixed(3);
+    const floorPct = (noiseFloor * 100).toFixed(3);
+    const fileNote = cov.file ? ` (file: ${cov.file})` : '';
+    return {
+      id: 'windows-coverage-noise-floor',
+      severity: 'warning',
+      scope: state?.scope ?? 'story-close',
+      summary: `Branch-coverage delta ${deltaPct}% is within the Windows noise floor (${floorPct}%) — likely flap, do not ratchet${fileNote}`,
+      detail: [
+        `branchDelta: ${cov.branchDelta}`,
+        `noiseFloor: ${noiseFloor}`,
+        cov.file ? `attributedFile: ${cov.file}` : null,
+      ]
+        .filter(Boolean)
+        .join('\n'),
+      fixCommand: FIX_COMMAND,
+      autoCorrectable: false,
+    };
+  },
+};

package/.agents/scripts/lib/checks/worktree-bootstrap-env.js

@@ -0,0 +1,81 @@
+/**
+ * worktree-bootstrap-env — refuse-and-print check.
+ *
+ * Detects active worktrees that are missing the `.env` or `.mcp.json`
+ * bootstrap files. These files are intentionally untracked in git, so a
+ * freshly-created worktree under `.worktrees/<story>/` does not get them
+ * unless the orchestration explicitly copies them. When they are missing,
+ * tests that read environment variables silently take a different code
+ * path.
+ *
+ * Surface: `epic-deliver` preflight and the `/diagnose` CLI. Surfaced as a
+ * warning rather than a blocker — the missing file may be a deliberate
+ * choice (e.g. a worktree that doesn't need MCP), but the operator should
+ * see the divergence from the main checkout.
+ *
+ * AutoCorrect is `refuse-and-print`. Copying `.env` between trees is
+ * defensible at the orchestration layer (`worktree.bootstrap` step) but
+ * not as a self-healing fix — the contents are project-specific and may
+ * include secrets the check explicitly never reads.
+ *
+ * Privacy: this check reads only the bootstrap *status* projection
+ * (`fs.worktreeBootstrapStatus`) which records presence per worktree, not
+ * file contents. The Finding's `detail` never exposes any env-var value.
+ */
+
+const ID = 'worktree-bootstrap-env';
+
+export default {
+  id: ID,
+  severity: 'warning',
+  scope: ['epic-deliver', 'diagnose'],
+  autoCorrect: 'refuse-and-print',
+  detect(state) {
+    const status = state?.fs?.worktreeBootstrapStatus ?? {};
+    const entries = Object.entries(status);
+    if (entries.length === 0) return null;
+    const missing = entries
+      .map(([wtPath, files]) => {
+        const missingFiles = [];
+        if (!files.dotEnv) missingFiles.push('.env');
+        if (!files.dotMcp) missingFiles.push('.mcp.json');
+        return { wtPath, missingFiles };
+      })
+      .filter((entry) => entry.missingFiles.length > 0);
+    if (missing.length === 0) return null;
+    const detailLines = missing.map(
+      (m) => `  - ${m.wtPath}: missing ${m.missingFiles.join(', ')}`,
+    );
+    return {
+      id: ID,
+      severity: 'warning',
+      scope: state?.scope ?? '',
+      summary: `${missing.length} worktree(s) missing bootstrap files (.env / .mcp.json)`,
+      detail: [
+        'Worktrees with missing bootstrap files:',
+        ...detailLines,
+        '',
+        'Tests that read these vars will silently degrade in the affected worktrees.',
+      ].join('\n'),
+      fixCommand: buildFixCommand(missing),
+      autoCorrectable: false,
+    };
+  },
+};
+
+/**
+ * Build a copy recipe the operator can run from the main checkout. Each
+ * missing file gets its own `cp` line targeting the affected worktree.
+ *
+ * @param {Array<{wtPath: string, missingFiles: string[]}>} missing
+ * @returns {string}
+ */
+function buildFixCommand(missing) {
+  const lines = [];
+  for (const { wtPath, missingFiles } of missing) {
+    for (const file of missingFiles) {
+      lines.push(`cp "${file}" "${wtPath}/${file}"`);
+    }
+  }
+  return lines.join(' && ');
+}

package/.agents/scripts/lib/checks/worktree-residue-biome.js

@@ -0,0 +1,55 @@
+/**
+ * worktree-residue-biome — refuse-and-print check.
+ *
+ * Detects partial-reap residue under `.worktrees/` where a previous Story's
+ * tree was deleted incompletely and left a nested `biome.json` behind. The
+ * root `npm run lint` walks into the orphan tree, hits the nested config,
+ * and fails. The close-time biome block is the canonical symptom.
+ *
+ * Surface: `epic-deliver` preflight, `story-close` preflight, and the
+ * `/diagnose` CLI. Surfaced as a blocker so the operator clears the residue
+ * with `rm -rf` before close re-runs the validation chain.
+ *
+ * AutoCorrect is `refuse-and-print`. Recursive deletion under `.worktrees/`
+ * is technically blessed by the README, but the residue may include
+ * partially-merged work the operator wants to inspect first. We print the
+ * exact `rm -rf` recipe rather than running it.
+ */
+
+const ID = 'worktree-residue-biome';
+
+export default {
+  id: ID,
+  severity: 'blocker',
+  scope: ['epic-deliver', 'story-close', 'diagnose', 'retro'],
+  autoCorrect: 'refuse-and-print',
+  detect(state) {
+    const orphans = state?.fs?.worktreeBiomeOrphans ?? [];
+    if (!Array.isArray(orphans) || orphans.length === 0) return null;
+    const lines = orphans.map((p) => `  - ${p}`).join('\n');
+    return {
+      id: ID,
+      severity: 'blocker',
+      scope: state?.scope ?? '',
+      summary: `${orphans.length} orphan worktree(s) with nested biome.json — root biome lint will fail`,
+      detail: `Nested biome.json files found under .worktrees/ subdirectories:\n${lines}\n\nThese block root \`npm run lint\` because biome walks into them and resolves the nested config.`,
+      fixCommand: buildFixCommand(orphans),
+      autoCorrectable: false,
+    };
+  },
+};
+
+/**
+ * Build the `rm -rf` command(s) the operator should run to clear the
+ * residue. Multiple orphans get a single chained command so it can be
+ * copy-pasted as one line.
+ *
+ * @param {string[]} orphans
+ * @returns {string}
+ */
+function buildFixCommand(orphans) {
+  if (orphans.length === 0) return '';
+  // Each path is already an absolute orphan worktree directory; deleting
+  // the whole directory is the canonical reap recipe.
+  return orphans.map((p) => `rm -rf "${p}"`).join(' && ');
+}

package/.agents/scripts/lib/cli/parse-numeric.js

@@ -0,0 +1,60 @@
+/**
+ * parse-numeric.js — shared CLI integer-flag validators (Story #2993).
+ *
+ * Extracted from `lifecycle-emit-story-dispatch.js` so future scripts that
+ * need a strict positive-integer or non-negative-integer flag value share
+ * a single validator instead of hand-rolling another `Number.parseInt`
+ * dance. Both helpers throw with a clear "required" / "must be …" message
+ * shape so a `runAsCli` boundary surfaces a clean exit-1.
+ *
+ * Contract:
+ *   - Empty / `null` / `undefined` raw values throw "is required".
+ *   - Non-integer or out-of-range values throw "must be a … integer".
+ *   - A leading `#` on the raw value is stripped (matches the ticket-ID
+ *     ergonomic on the rest of the framework).
+ *
+ * @module lib/cli/parse-numeric
+ */
+
+/**
+ * Parse a flag value as a strict positive integer (≥ 1). Leading `#` is
+ * stripped to match the `parseTicketId` ergonomic.
+ *
+ * @param {string|number|null|undefined} raw
+ * @param {string} flag  Flag label used in the thrown error message.
+ * @param {string} [tool='cli'] Optional tool prefix for the error message.
+ * @returns {number}
+ */
+export function parseRequiredPositiveInt(raw, flag, tool = 'cli') {
+  if (raw === undefined || raw === null || raw === '') {
+    throw new Error(`${tool}: ${flag} is required`);
+  }
+  const n = Number.parseInt(String(raw).replace(/^#/, ''), 10);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`${tool}: ${flag} must be a positive integer (got ${raw})`);
+  }
+  return n;
+}
+
+/**
+ * Parse a flag value as a strict non-negative integer (≥ 0). Leading `#`
+ * is NOT stripped — non-negative use cases (wave index, attempt offset)
+ * do not carry the ticket-ID convention.
+ *
+ * @param {string|number|null|undefined} raw
+ * @param {string} flag
+ * @param {string} [tool='cli']
+ * @returns {number}
+ */
+export function parseRequiredNonNegativeInt(raw, flag, tool = 'cli') {
+  if (raw === undefined || raw === null || raw === '') {
+    throw new Error(`${tool}: ${flag} is required`);
+  }
+  const n = Number.parseInt(String(raw), 10);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(
+      `${tool}: ${flag} must be a non-negative integer (got ${raw})`,
+    );
+  }
+  return n;
+}