mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/baselines/refresh-service.js

@@ -3,14 +3,16 @@
  * (Story #2197, Epic #2173).
  *
  * `refreshBaseline()` is the single funnel through which every baseline
- * regeneration (maintainability, crap, coverage) must flow. Callers that
- * previously assembled their own envelopes and called `fs.writeFileSync`
- * MUST migrate to this entry point — Stories 3/4/5 of Epic #2173 do that
- * migration; Story #2197 only lands the service surface and tests.
+ * regeneration (maintainability, crap, coverage, duplication) must flow.
+ * Callers that previously assembled their own envelopes and called
+ * `fs.writeFileSync` MUST migrate to this entry point — Stories 3/4/5 of
+ * Epic #2173 do that migration; Story #2197 only lands the service surface
+ * and tests. Story #4944 migrated the last holdout, `duplication`.
  *
  * The service is **scoring-agnostic**: it does not itself walk the
- * filesystem to compute MI / CRAP / coverage scores. Scoring is provided
- * by the per-kind default scorers resolved lazily via `resolveDefaultScorer`
+ * filesystem to compute MI / CRAP / coverage / duplication scores. Scoring
+ * is provided by the per-kind default scorers resolved lazily via
+ * `resolveDefaultScorer`
  * (built with the project config resolved against `cwd`) and, in tests or
  * production wiring, injected via the `scorer` option for hermetic
  * determinism. The service is the policy layer:
@@ -29,7 +31,8 @@
  * Public API (Task #2203, AC-1 / AC-2 / AC-7):
  *
  *   refreshBaseline({
- *     kind,        // 'maintainability' | 'crap' | 'coverage'  REQUIRED
+ *     kind,        // 'maintainability' | 'crap' | 'coverage'
+ *                  //   | 'duplication'                       REQUIRED
  *     baseRef,     // git ref to diff against; default 'origin/main'
  *     headRef,     // git ref under inspection; default 'HEAD'
  *     scopeFiles,  // Array<string> | null
@@ -62,8 +65,9 @@
  *
  * Acceptance contract:
  *
- *   AC-1: All callers that produce a maintainability/crap/coverage baseline
- *         go through refreshBaseline(). Enforced by Task #2208 invariant.
+ *   AC-1: All callers that produce a maintainability/crap/coverage/
+ *         duplication baseline go through refreshBaseline(). Enforced by
+ *         the Task #2208 invariant.
  *   AC-2: scopeFiles=null && !fullScope -> diff-derived scope (Task #2207).
  *   AC-4: Out-of-scope rows + their updatedAt fields are preserved byte-
  *         for-byte (Task #2209).
@@ -93,6 +97,7 @@ import {
   isIgnoredByGlobs as isIgnoredByGlobsMi,
   scanDirectory as scanDirectoryMi,
 } from '../maintainability-utils.js';
+import { resolveDetectClones, scanDuplication } from './duplication-scanner.js';
 import { filterExcludedRows } from './kinds/maintainability.js';
 import { canonicalizeBaselinePath } from './path-canon.js';
 import {
@@ -108,7 +113,12 @@ const execFileAsync = promisify(nodeExecFile);
  * Kinds the refresh service knows how to dispatch. Stays in lockstep with
  * the per-kind modules under `.agents/scripts/lib/baselines/kinds/`.
  */
-const SUPPORTED_KINDS = Object.freeze(['maintainability', 'crap', 'coverage']);
+const SUPPORTED_KINDS = Object.freeze([
+  'maintainability',
+  'crap',
+  'coverage',
+  'duplication',
+]);
 
 /**
  * Per-kind file-extension predicate for diff-scope derivation (Task #2207).
@@ -125,6 +135,12 @@ const KIND_FILE_PREDICATES = Object.freeze({
   maintainability: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
   crap: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
   coverage: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
+  // Duplication shares the source-extension filter deliberately. jscpd is
+  // configured for the `javascript` format only, so a changed `.ts` file
+  // admitted here simply yields no row on either side of the merge —
+  // over-inclusive is inert, under-inclusive would silently pin a changed
+  // file's prior row. Erring wide is the safe direction.
+  duplication: (p) => /\.(?:m?[jt]sx?)$/i.test(p),
 });
 
 /**
@@ -338,6 +354,7 @@ const KIND_SCORER_BUILDERS = Object.freeze({
   maintainability: buildDefaultMaintainabilityScorer,
   crap: buildDefaultCrapScorer,
   coverage: buildDefaultCoverageScorer,
+  duplication: buildDefaultDuplicationScorer,
 });
 
 /**
@@ -384,7 +401,7 @@ export function resolveDefaultScorer(kind, { cwd } = {}) {
  * so callers (and tests) can assert what actually got scored.
  *
  * @param {{
- *   kind: 'maintainability' | 'crap' | 'coverage',
+ *   kind: 'maintainability' | 'crap' | 'coverage' | 'duplication',
  *   baseRef?: string,
  *   headRef?: string,
  *   scopeFiles?: string[] | null,
@@ -745,3 +762,44 @@ function validateOptions({ kind, scopeFiles, fullScope, writePath }) {
     );
   }
 }
+
+/**
+ * Build the default duplication scorer.
+ *
+ * **This scorer always scans the whole target tree, in every scope mode.**
+ * That is not an oversight — duplication is the only kind here whose metric
+ * is *pairwise*: a clone is a relationship between two files, and jscpd can
+ * only report it if both sides are in the corpus it was handed. Narrowing the
+ * scan to the diff would drop every clone between a changed file and an
+ * unchanged one, i.e. exactly the duplication a refactor is most likely to
+ * introduce. So the `files` argument is intentionally unused: scope narrowing
+ * for this kind is a **write-side** concern, applied by the service handing
+ * `scope` to `writer.write()`, where `mergeRowsByScope` keeps the freshly
+ * scanned rows for in-scope files and preserves the prior rows verbatim for
+ * everything else.
+ *
+ * Reads `targetDirs` / `ignoreGlobs` off `gates.duplication`, not off a
+ * flattened accessor: `resolveQuality` never lifted duplication into the
+ * legacy bag (the kind post-dates it), so `quality.duplication` is always
+ * `undefined` and reading it would silently scan nothing.
+ *
+ * @param {{ cwd: string, config?: object, quality?: object, detect?: (opts: object) => Promise<object[]> }} opts
+ * @returns {(files: string[], opts: object) => Promise<object[]>}
+ */
+function buildDefaultDuplicationScorer({ cwd, config, quality, detect } = {}) {
+  const dupCfg =
+    resolveQualityBlock({ quality, config })?.gates?.duplication ?? {};
+  const targetDirs = Array.isArray(dupCfg.targetDirs) ? dupCfg.targetDirs : [];
+  const ignoreGlobs = Array.isArray(dupCfg.ignoreGlobs)
+    ? dupCfg.ignoreGlobs
+    : [];
+  return async (_files, opts) => {
+    const effectiveCwd = opts?.cwd ?? cwd ?? process.cwd();
+    return scanDuplication({
+      targetDirs,
+      cwd: effectiveCwd,
+      ignoreGlobs,
+      detect: detect ?? resolveDetectClones(),
+    });
+  };
+}

package/.agents/scripts/lib/baselines/scope.js

@@ -1,33 +1,44 @@
 // .agents/scripts/lib/baselines/scope.js
 //
-// Story #1962 / Task #1970 — One ScopeResolution helper that the
-// `check-baselines.js` dispatcher and the per-kind regression writers
-// (Epic #1943) both consume. Routing every scope decision through this
-// single function is what guarantees read/write parity: the dispatcher
-// can never decide "diff against epic/1943" while the writer assumes
-// "full repo", because both call `resolveScope()` with the same inputs.
+// Story #1962 / Task #1970 — the ScopeResolution helper behind the
+// `check-baselines.js` dispatcher: `resolveDispatchScope` in
+// `lib/orchestration/check-baselines/phases/compare.js` is its one
+// caller. Routing the read side's scope decision through a single pure
+// function keeps the precedence rules from being re-implemented per gate.
+//
+// It is NOT the writers' resolver. `lib/baselines/refresh-service.js`
+// defines its own private `resolveScope` (Story #3658) over a different
+// input set, and the header here used to claim otherwise — a claim that
+// made the read/write pair look coupled when it is not. Corrected in
+// Story #4922.
 //
 // The resolver is intentionally pure — it takes already-extracted
-// inputs and returns a frozen ScopeResolution. CLI parsing, env
-// reading, and config loading happen in the caller; that keeps this
-// module trivially testable and prevents the precedence rules from
-// being silently re-implemented at every call site.
+// inputs and returns a frozen ScopeResolution. Env reading and config
+// loading happen in the caller; that keeps this module trivially
+// testable.
 //
 // Precedence (highest → lowest):
 //
-//   1. CLI flags — `cliFlags.fullScope: true` or `cliFlags.changedSinceRef`.
-//      Operator-typed beats anything in env/config. A CLI override of
-//      `--full-scope` wins even if the config says `'diff'`.
-//   2. Environment — `BASELINE_SCOPE` ('full' | 'diff') and
+//   1. Environment — `BASELINE_SCOPE` ('full' | 'diff') and
 //      `BASELINE_REF` (any git ref). The dispatcher reads these from
-//      `process.env` and forwards via `cliFlags.envScope` /
-//      `cliFlags.envRef` so the resolver itself never touches process
-//      state. CI usually sets these.
-//   3. Config — `configScope` ('full' | 'diff') and `configRef` (any
+//      `process.env` and forwards via `envScope` / `envRef` so the
+//      resolver itself never touches process state. CI sets these.
+//   2. Config — `configScope` ('full' | 'diff') and `configRef` (any
 //      git ref) from `delivery.quality.gateScoping` in `.agentrc.json`.
-//   4. Default — `mode='diff'` against `ref='main'`. This is the
+//   3. Default — `mode='diff'` against `ref='main'`. This is the
 //      framework-wide fallback when nothing else is configured.
 //
+// Story #4922 removed a fourth, highest-precedence layer: a
+// `cliFlags.fullScope` / `cliFlags.changedSinceRef` operator override,
+// plus the `cliFlags.changedFiles` → `files` plumbing that fed it. No
+// production caller ever populated any of the three — only this module's
+// own unit tests did — so the layer's only effect was to advertise a
+// `--full-scope` / `--changed-since` contract that `check-baselines.js`
+// does not implement, and a `files` set that no consumer read. Operators
+// who need full scope set `BASELINE_SCOPE=full`, which is what CI does.
+// (`mergeRowsByScope` below still takes a `files`-bearing scope — that
+// one comes from the refresh service's own resolver, not from here.)
+//
 // Missing-ref fallback: when the resolved mode is `'diff'` but no ref
 // is supplied at any layer, the resolver falls back to `'main'` rather
 // than producing a half-resolved scope with `ref=null`. The dispatcher
@@ -45,17 +56,8 @@
 //     kind: string,        // echoed back for caller convenience
 //     mode: 'full' | 'diff',
 //     ref:  string | null, // null in full mode; ref string in diff mode
-//     files: Set<string>,  // empty Set in full mode (sentinel for "all")
 //     source: string,      // which layer won (debug / friction signal)
 //   }
-//
-// `files` is intentionally a Set rather than an Array — callers
-// repeatedly check membership during per-row filtering, and Set lookup
-// is O(1). An empty Set in `'full'` mode means "no filter applies".
-// A non-empty Set in `'diff'` mode means "only these paths are in
-// scope" (the dispatcher pre-computes them via `git diff --name-only`
-// and forwards via `cliFlags.changedFiles`); when omitted, the writer
-// is expected to compute the diff itself against `ref`.
 
 const VALID_MODES = new Set(['full', 'diff']);
 const DEFAULT_DIFF_REF = 'main';
@@ -84,45 +86,19 @@ function asMode(v) {
 }
 
 /**
- * Coerce a candidate set/array of files to a frozen Set. Returns an
- * empty Set when the input is missing or empty.
- *
- * @param {unknown} v
- * @returns {Set<string>}
- */
-function asFilesSet(v) {
-  if (v instanceof Set) {
-    return new Set(
-      Array.from(v).filter((f) => typeof f === 'string' && f.length > 0),
-    );
-  }
-  if (Array.isArray(v)) {
-    return new Set(v.filter((f) => typeof f === 'string' && f.length > 0));
-  }
-  return new Set();
-}
-
-/**
- * Resolve a scope against the layered precedence (CLI > env > config >
+ * Resolve a scope against the layered precedence (env > config >
  * default). Pure; no I/O.
  *
  * @param {object} input
- * @param {string} input.kind         - Baseline kind (e.g. `'lint'`).
+ * @param {string} input.kind          - Baseline kind (e.g. `'lint'`).
  * @param {string} [input.configScope] - `'full'` | `'diff'` from agentrc.
  * @param {string} [input.configRef]   - Diff ref from agentrc.
- * @param {object} [input.cliFlags]    - Pre-parsed CLI / env layer.
- * @param {boolean} [input.cliFlags.fullScope]      - `--full-scope`.
- * @param {string}  [input.cliFlags.changedSinceRef] - `--changed-since <ref>`.
- * @param {string}  [input.cliFlags.envScope]        - From `BASELINE_SCOPE`.
- * @param {string}  [input.cliFlags.envRef]          - From `BASELINE_REF`.
- * @param {Iterable<string>} [input.cliFlags.changedFiles]
- *        Pre-computed diff paths (when caller already ran `git diff
- *        --name-only`). Becomes `files`; only meaningful in `'diff'` mode.
+ * @param {string} [input.envScope]    - From `BASELINE_SCOPE`.
+ * @param {string} [input.envRef]      - From `BASELINE_REF`.
  * @returns {{
  *   kind: string,
  *   mode: 'full' | 'diff',
  *   ref: string | null,
- *   files: Set<string>,
  *   source: string,
  * }}
  */
@@ -131,59 +107,34 @@ export function resolveScope(input = {}) {
     typeof input.kind === 'string' && input.kind.length > 0
       ? input.kind
       : 'unknown';
-  const cli = input.cliFlags ?? {};
-
-  // ---- Layer 1: CLI flags (highest precedence) -------------------------
-  if (cli.fullScope === true) {
-    return Object.freeze({
-      kind,
-      mode: 'full',
-      ref: null,
-      files: new Set(),
-      source: 'cli:--full-scope',
-    });
-  }
-  const cliRef = asNonEmptyString(cli.changedSinceRef);
-  if (cliRef) {
-    return Object.freeze({
-      kind,
-      mode: 'diff',
-      ref: cliRef,
-      files: asFilesSet(cli.changedFiles),
-      source: 'cli:--changed-since',
-    });
-  }
 
-  // ---- Layer 2: Environment (extracted by caller into cliFlags.env*) ---
-  const envMode = asMode(cli.envScope);
+  // ---- Layer 1: Environment (extracted by the caller) ------------------
+  const envMode = asMode(input.envScope);
   if (envMode === 'full') {
     return Object.freeze({
       kind,
       mode: 'full',
       ref: null,
-      files: new Set(),
       source: 'env:BASELINE_SCOPE=full',
     });
   }
-  const envRef = asNonEmptyString(cli.envRef);
+  const envRef = asNonEmptyString(input.envRef);
   if (envMode === 'diff' || envRef) {
     return Object.freeze({
       kind,
       mode: 'diff',
       ref: envRef ?? DEFAULT_DIFF_REF,
-      files: asFilesSet(cli.changedFiles),
       source: envRef ? 'env:BASELINE_REF' : 'env:BASELINE_SCOPE=diff',
     });
   }
 
-  // ---- Layer 3: Config (delivery.quality.gateScoping) -----------------
+  // ---- Layer 2: Config (delivery.quality.gateScoping) ------------------
   const cfgMode = asMode(input.configScope);
   if (cfgMode === 'full') {
     return Object.freeze({
       kind,
       mode: 'full',
       ref: null,
-      files: new Set(),
       source: 'config:gateScoping.scope=full',
     });
   }
@@ -193,19 +144,17 @@ export function resolveScope(input = {}) {
       kind,
       mode: 'diff',
       ref: cfgRef ?? DEFAULT_DIFF_REF,
-      files: asFilesSet(cli.changedFiles),
       source: cfgRef
         ? 'config:gateScoping.diffRef'
         : 'config:gateScoping.scope=diff',
     });
   }
 
-  // ---- Layer 4: Default ------------------------------------------------
+  // ---- Layer 3: Default ------------------------------------------------
   return Object.freeze({
     kind,
     mode: 'diff',
     ref: DEFAULT_DIFF_REF,
-    files: asFilesSet(cli.changedFiles),
     source: 'default',
   });
 }

package/.agents/scripts/lib/baselines/writer.js

@@ -261,21 +261,26 @@ export function writeFile(absPath, envelope, opts = {}) {
   // across runs and platforms. Per-kind row keys retain their natural
   // declaration order; the row sort is done by `sortRows()`.
   //
-  // Story #4775: the projection is deliberately explicit, so any per-kind
-  // envelope stamp (`scoringSemantics`, and `tsTranspilerVersion` since Story
-  // #4866) must be carried through by name or it is silently dropped on the
-  // way to disk — the stamp would then be present in memory, validated, and
-  // absent from the file it exists to protect.
+  // The projection is deliberately explicit (Story #4775): a per-kind envelope
+  // stamp reaches disk only if it is named here, so an unlisted one is present
+  // in memory, passes validation, and is absent from the file it exists to
+  // protect. That is not hypothetical — Story #4901 added `provenanceStamped`
+  // to `envelopeExtras()` and not to this list, and every baseline written
+  // between then and Story #4969 lost it at this boundary, leaving the
+  // `provenance-unstamped` axis reading an absence its own writer had
+  // manufactured.
+  //
+  // A stamp a kind does not set is simply `undefined`, and `JSON.stringify`
+  // omits an undefined-valued key — so naming all three unconditionally emits
+  // exactly what the per-key `undefined` guards used to, with nothing to
+  // half-apply when the next stamp is added.
   const canonical = {
     $schema: envelope.$schema,
     kernelVersion: envelope.kernelVersion,
     generatedAt: envelope.generatedAt,
-    ...(envelope.scoringSemantics === undefined
-      ? {}
-      : { scoringSemantics: envelope.scoringSemantics }),
-    ...(envelope.tsTranspilerVersion === undefined
-      ? {}
-      : { tsTranspilerVersion: envelope.tsTranspilerVersion }),
+    scoringSemantics: envelope.scoringSemantics,
+    tsTranspilerVersion: envelope.tsTranspilerVersion,
+    provenanceStamped: envelope.provenanceStamped,
     rollup: envelope.rollup,
     rows: envelope.rows,
   };

package/.agents/scripts/lib/changed-files.js

@@ -8,10 +8,17 @@ import { createGitInterface } from './git-utils.js';
  *
  * Pure; no I/O.
  *
+ * Module-private since Story #4944. It was exported for
+ * `diff-scope-cli.js#resolveDiffScopeFiles`, which the duplication-CLI
+ * migration deleted; the three remaining callers all live in this file, so
+ * exporting it now would ship a seam only the tests reach. Its behaviour is
+ * covered through `diffNameOnly`, which returns this function's output
+ * verbatim.
+ *
  * @param {string | null | undefined} stdout
  * @returns {string[]}
  */
-export function parseNameOnlyStdout(stdout) {
+function parseNameOnlyStdout(stdout) {
   if (!stdout) return [];
   return stdout
     .split('\n')

package/.agents/scripts/lib/cli-args.js

@@ -62,13 +62,71 @@ function parsePositiveInt(value) {
   return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
+/** The only two merge-watch postures `--merge-watch-mode` accepts. */
+const MERGE_WATCH_MODES = ['sync', 'async'];
+
+/**
+ * Parse `--merge-watch-mode` (Story #4949), the per-invocation override of
+ * `delivery.mergeWatch.mode`. Absence is preserved as `undefined` so the
+ * caller can distinguish "not supplied" (fall back to config) from an explicit
+ * posture — the same contract {@link parsePositiveInt} gives
+ * `--max-wait-seconds`.
+ *
+ * Unlike that sibling, an unrecognized value **throws** rather than degrading
+ * to absent. A `--max-wait-seconds` typo falls back to a sane bound; a
+ * `--merge-watch-mode` typo would fall back to `sync` and silently return a
+ * multi-Story run to a serialized foreground wait per close, with the wall
+ * clock as the only evidence. Parsing runs before the first close phase, so
+ * failing here costs no mutation.
+ *
+ * @param {unknown} value
+ * @returns {'sync'|'async'|undefined}
+ */
+export function parseMergeWatchMode(value) {
+  if (value == null) return undefined;
+  const mode = String(value).trim().toLowerCase();
+  if (MERGE_WATCH_MODES.includes(mode)) return mode;
+  throw new Error(
+    `--merge-watch-mode must be one of ${MERGE_WATCH_MODES.join('|')} (got "${value}")`,
+  );
+}
+
+/**
+ * {@link parseMergeWatchMode} degraded to the "absent" value instead of
+ * throwing — how the tolerant parse below treats a flag that failed
+ * validation. Reporting `undefined` is safe there and only there, because a
+ * tolerant parse never drives a pipeline: its caller surfaces the rejection
+ * as the run's failure and runs no phase at all.
+ *
+ * @param {unknown} value
+ * @returns {'sync'|'async'|undefined}
+ */
+function tolerantMergeWatchMode(value) {
+  try {
+    return parseMergeWatchMode(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Standardized CLI argument parser for sprint scripts.
  * Supports options like --epic, --story, --dry-run, --skip-dashboard.
+ *
+ * Throws when a *validating* parser rejects a flag value (currently only
+ * `--merge-watch-mode`). Callers that must not throw — an error handler
+ * needing `storyId` to report an envelope — use {@link parseSprintArgsTolerant}
+ * rather than calling this a second time inside their own catch.
+ *
  * @param {string[]} args Array of arguments (defaults to process.argv)
+ * @param {{ tolerant?: boolean }} [options] `tolerant` degrades a rejected
+ *   flag to its absent value instead of throwing. For reporting only.
  * @returns {object} Parsed and typed argument values
  */
-export function parseSprintArgs(args = process.argv) {
+export function parseSprintArgs(
+  args = process.argv,
+  { tolerant = false } = {},
+) {
   const { values, positionals } = parseArgs({
     args: args.slice(2),
     options: {
@@ -85,6 +143,10 @@ export function parseSprintArgs(args = process.argv) {
       // Story #4543 — per-run override of `delivery.mergeWatch.maxWaitSeconds`
       // (the merge wait's per-invocation bound). Absent means "use the config".
       'max-wait-seconds': { type: 'string' },
+      // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
+      // Absent means "use the config"; see `parseMergeWatchMode` for why an
+      // unrecognized value fails closed instead of degrading to absent.
+      'merge-watch-mode': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -115,6 +177,12 @@ export function parseSprintArgs(args = process.argv) {
     // headless caller with no host tool-invocation ceiling, so it lands in
     // one block instead of returning `pending` at the default 300s.
     maxWaitSeconds: parsePositiveInt(values['max-wait-seconds']),
+    // Story #4949 — per-invocation override of `delivery.mergeWatch.mode`.
+    // `undefined` when the flag is absent, which is what lets the merge wait
+    // fall back to the config; anything unrecognized throws here.
+    mergeWatchMode: tolerant
+      ? tolerantMergeWatchMode(values['merge-watch-mode'])
+      : parseMergeWatchMode(values['merge-watch-mode']),
     executor: values.executor ?? null,
     // Resolve worktree cwd from flag or env. Empty string/whitespace → null.
     cwd:
@@ -137,6 +205,52 @@ export function parseSprintArgs(args = process.argv) {
   return parsed;
 }
 
+/**
+ * Last-resort tolerant parse: the fields, or an empty bag if even the
+ * tolerant pass cannot produce one.
+ *
+ * @param {string[]} args
+ * @returns {object}
+ */
+function parseSprintArgsOrEmpty(args) {
+  try {
+    return parseSprintArgs(args, { tolerant: true });
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse argv **without ever throwing**, returning the fields alongside the
+ * rejection rather than in place of it.
+ *
+ * `parseSprintArgs` gained its first *validating* parser in
+ * {@link parseMergeWatchMode} (Story #4949), which made a latent shape in the
+ * CLI entries fatal: their catch blocks called
+ * `failedTerminalFor(err, parseSprintArgs())` — re-invoking the very parser
+ * that had just thrown. The second throw escaped the catch, so an
+ * unparseable argv produced a bare stack trace with **no terminal envelope
+ * and no friction signal**, on the two surfaces whose whole contract is that
+ * they always emit one. An error handler must not depend on an operation
+ * already known to fail.
+ *
+ * So the entries parse **once**, up front, through this wrapper: `args`
+ * carries the `storyId` and skip flags the envelope is built from, and
+ * `error` is the failure to report. The tolerant re-parse degrades **only**
+ * the flag that failed validation; every other field parses normally. Use
+ * the result to *report*, never to run a pipeline.
+ *
+ * @param {string[]} [args] Array of arguments (defaults to `process.argv`)
+ * @returns {{ args: object, error: Error|null }}
+ */
+export function parseSprintArgsTolerant(args = process.argv) {
+  try {
+    return { args: parseSprintArgs(args), error: null };
+  } catch (error) {
+    return { args: parseSprintArgsOrEmpty(args), error };
+  }
+}
+
 const SUPPORTED_FLAG_TYPES = new Set([
   'boolean',
   'ticket',