mandrel 1.57.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js

@@ -0,0 +1,159 @@
+/**
+ * phases/auto-merge.js — enable GitHub native auto-merge on the PR.
+ *
+ * Mirrors the epic-deliver finalize call shape: squash strategy, delete
+ * the branch on merge. Non-fatal — returns `{ enabled: false, reason }`
+ * on any failure so the caller can fall back to the operator-merges-button
+ * path.
+ *
+ * Story #2990 routed the underlying `gh pr merge` call through the
+ * `lib/gh-exec.js` facade (the same shim the `providers/github/`
+ * gateways use). The `runner` seam is preserved so existing tests can
+ * inject a synchronous fake; the default runner delegates to
+ * `gh.pr.merge`, which spawns through the classified, typed-error
+ * surface instead of a raw `execFileSync('gh', …)` call.
+ */
+
+import { gh as defaultGh } from '../../../gh-exec.js';
+
+/**
+ * Enable GitHub native auto-merge on the PR. Non-fatal.
+ *
+ * @param {{
+ *   cwd: string,
+ *   prNumber: number,
+ *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
+ *   runner?: (args: string[], opts: object) => ({ status: number, stdout?: string, stderr?: string } | Promise<{ status: number, stdout?: string, stderr?: string }>),
+ * }} opts
+ * @returns {Promise<{ enabled: boolean, reason?: string }>}
+ */
+export async function enableAutoMergeWith({ cwd, prNumber, gh, runner }) {
+  const exec = runner ?? makeDefaultGhAutoMergeRunner(gh ?? defaultGh);
+  try {
+    const result = await exec(
+      [
+        'pr',
+        'merge',
+        String(prNumber),
+        '--auto',
+        '--squash',
+        '--delete-branch',
+      ],
+      { cwd },
+    );
+    if (result.status === 0) return { enabled: true };
+    return {
+      enabled: false,
+      reason: `gh-exit-${result.status}: ${(result.stderr ?? '').trim().slice(0, 200)}`,
+    };
+  } catch (err) {
+    return { enabled: false, reason: `gh-spawn-error: ${err?.message ?? err}` };
+  }
+}
+
+/**
+ * Build the default `gh pr merge` runner that adapts the async
+ * `lib/gh-exec.js` facade into the synchronous-looking
+ * `{ status, stdout, stderr }` envelope `enableAutoMergeWith` consumes.
+ *
+ * The adapter swallows non-zero exits (mapping the typed `GhExecError`
+ * carrier back to its `code` + `stderr`) because auto-merge enablement
+ * is intentionally non-fatal — the caller treats failures as "operator
+ * merges manually".
+ */
+function makeDefaultGhAutoMergeRunner(gh) {
+  return async function defaultGhAutoMergeRunner(args, _opts) {
+    // `args` always starts with `pr merge <prNumber>` — pass everything
+    // after the third element to `gh.pr.merge` as flags so the facade
+    // owns the `gh pr merge <id> …` argv assembly.
+    const [, , prIdStr, ...flags] = args;
+    try {
+      const result = await gh.pr.merge(prIdStr, flags);
+      return {
+        status: 0,
+        stdout: result?.stdout ?? '',
+        stderr: result?.stderr ?? '',
+      };
+    } catch (err) {
+      // Duck-type: any error carrying a numeric `.code` (or `.status`,
+      // which the legacy `execFileSync` shim used) + an optional
+      // `.stderr` is mapped back to the `{ status, stdout, stderr }`
+      // envelope `enableAutoMergeWith` consumes. The typed
+      // `GhExecError` carriers from `lib/gh-exec.js` already fit this
+      // shape; bare `Error`s without a code fall through to the spawn-
+      // error reason in the parent catch.
+      const numericCode =
+        typeof err?.code === 'number'
+          ? err.code
+          : typeof err?.status === 'number'
+            ? err.status
+            : null;
+      if (numericCode !== null) {
+        return {
+          status: numericCode,
+          stdout:
+            typeof err.stdout === 'string'
+              ? err.stdout
+              : (err.stdout?.toString?.() ?? ''),
+          stderr:
+            typeof err.stderr === 'string'
+              ? err.stderr
+              : (err.stderr?.toString?.() ?? String(err?.message ?? err)),
+        };
+      }
+      throw err;
+    }
+  };
+}
+
+/**
+ * Dispatch auto-merge enablement based on `--no-auto-merge`, an
+ * unparseable PR number, or a `gh` failure. Returns the structured
+ * `{ autoMergeEnabled, autoMergeReason }` pair the result envelope needs.
+ *
+ * @param {{
+ *   cwd: string,
+ *   prNumber: number|null,
+ *   prUrl: string,
+ *   noAutoMerge: boolean,
+ *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null }>}
+ */
+export async function runAutoMergePhase({
+  cwd,
+  prNumber,
+  prUrl,
+  noAutoMerge,
+  gh,
+  progress,
+}) {
+  if (noAutoMerge) {
+    progress('PR', '⏭  Auto-merge disabled (--no-auto-merge).');
+    return { autoMergeEnabled: false, autoMergeReason: 'disabled-by-flag' };
+  }
+  if (prNumber == null) {
+    progress(
+      'PR',
+      `⚠️ Auto-merge skipped: could not parse PR number from URL ${prUrl}.`,
+    );
+    return {
+      autoMergeEnabled: false,
+      autoMergeReason: 'pr-number-unparseable',
+    };
+  }
+  const result = await enableAutoMergeWith({ cwd, prNumber, gh });
+  if (result.enabled) {
+    progress(
+      'PR',
+      `✅ Auto-merge enabled on PR #${prNumber} (squash, delete-branch).`,
+    );
+    return { autoMergeEnabled: true, autoMergeReason: null };
+  }
+  progress(
+    'PR',
+    `⚠️ Auto-merge enablement failed (${result.reason}) — operator can merge manually.`,
+  );
+  return { autoMergeEnabled: false, autoMergeReason: result.reason };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js

@@ -0,0 +1,194 @@
+/**
+ * phases/base-sync.js — pre-push base-sync phase for `single-story-close`.
+ *
+ * Story #2580: sync the Story branch from `origin/<baseBranch>` before
+ * push so the PR opens with the latest base commits already integrated.
+ * Defends against the parallel-`/single-story-deliver` race where one
+ * Story's auto-merge bumps `main` while sibling Stories are mid-flight —
+ * without the sync, the lagging PRs open "behind base" and stall against
+ * the `up-to-date branch` protection rule.
+ *
+ * The sync runs INSIDE the worktree (where the Story branch is checked
+ * out); falls back to the main checkout when the worktree is absent.
+ * On a merge conflict the Story is transitioned to `agent::blocked` via
+ * `handleSyncFailure` and the caller throws — the operator resolves in
+ * the worktree and re-runs.
+ */
+
+import { syncBranchFromBase } from '../../../git/sync-from-base.js';
+import { Logger } from '../../../Logger.js';
+import { AGENT_LABELS } from '../../../label-constants.js';
+import { upsertStructuredComment } from '../../ticketing/state.js';
+
+/**
+ * Orchestrate the pre-push base-sync step: run `syncBranchFromBase`
+ * inside the worktree (or main checkout when no worktree exists). On
+ * failure, post a friction comment, flip the Story to `agent::blocked`,
+ * and throw so the caller fails non-zero. The `--skip-sync` flag is
+ * handled by the caller; this function assumes the sync is desired.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath: string|null,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   storyId: number,
+ *   provider: object,
+ *   injectedSync?: typeof syncBranchFromBase,
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ */
+export async function runBaseSyncPhase({
+  cwd,
+  worktreePath,
+  baseBranch,
+  storyBranch,
+  storyId,
+  provider,
+  injectedSync,
+  progress,
+}) {
+  const syncCwd = worktreePath ?? cwd;
+  progress(
+    'SYNC',
+    `Syncing ${storyBranch} from origin/${baseBranch} in ${syncCwd}...`,
+  );
+  const syncFn = injectedSync ?? syncBranchFromBase;
+  const syncResult = await syncFn({
+    cwd: syncCwd,
+    baseBranch,
+    log: (tag, msg) => progress(tag, msg),
+  });
+  if (!syncResult.synced) {
+    await handleSyncFailure({
+      provider,
+      storyId,
+      syncCwd,
+      baseBranch,
+      storyBranch,
+      result: syncResult,
+      progress,
+    });
+    throw new Error(
+      `[single-story-close] Base-sync failed (${syncResult.kind})` +
+        (syncResult.conflictFiles
+          ? `: conflicting files = ${syncResult.conflictFiles.join(', ')}`
+          : syncResult.stderr
+            ? `: ${syncResult.stderr.slice(0, 200)}`
+            : '') +
+        `. Story transitioned to ${AGENT_LABELS.BLOCKED}; resolve in ${syncCwd} and re-run \`/single-story-deliver\`.`,
+    );
+  }
+  progress('SYNC', `✅ Synced from origin/${baseBranch} (${syncResult.kind}).`);
+}
+
+/**
+ * Post a `friction` structured comment summarising a base-sync failure
+ * and transition the Story to `agent::blocked`. Exported for testing.
+ *
+ * @param {{
+ *   provider: object,
+ *   storyId: number,
+ *   syncCwd: string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   result: { kind: string, conflictFiles?: string[], stderr?: string },
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ */
+export async function handleSyncFailure({
+  provider,
+  storyId,
+  syncCwd,
+  baseBranch,
+  storyBranch,
+  result,
+  progress,
+}) {
+  const body = buildSyncFailureCommentBody({
+    storyId,
+    storyBranch,
+    baseBranch,
+    syncCwd,
+    result,
+  });
+
+  // Post the structured comment first so the operator's recovery
+  // surface lands even if the label flip fails. Both are best-effort:
+  // we never want a notification-side failure to mask the real reason
+  // close threw.
+  try {
+    await upsertStructuredComment(provider, storyId, 'friction', body);
+    progress('SYNC', `📝 Posted friction comment on #${storyId}.`);
+  } catch (err) {
+    Logger.warn?.(
+      `[single-story-close] ⚠️ Failed to post sync-failure friction comment on #${storyId}: ${err?.message ?? err}`,
+    );
+  }
+
+  try {
+    await provider.updateTicket(storyId, {
+      labels: {
+        add: [AGENT_LABELS.BLOCKED],
+        remove: [AGENT_LABELS.EXECUTING, AGENT_LABELS.READY, AGENT_LABELS.DONE],
+      },
+    });
+    progress('SYNC', `🚧 Flipped Story #${storyId} → ${AGENT_LABELS.BLOCKED}.`);
+  } catch (err) {
+    Logger.warn?.(
+      `[single-story-close] ⚠️ Failed to flip Story #${storyId} to ${AGENT_LABELS.BLOCKED}: ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Build the markdown body posted on a base-sync failure. Pure; exported
+ * for tests so the operator-recoverable surface stays reviewable.
+ *
+ * @param {{ storyId: number, storyBranch: string, baseBranch: string, syncCwd: string, result: { kind: string, conflictFiles?: string[], stderr?: string } }} args
+ * @returns {string}
+ */
+export function buildSyncFailureCommentBody({
+  storyId,
+  storyBranch,
+  baseBranch,
+  syncCwd,
+  result,
+}) {
+  const kind = result.kind ?? 'unknown';
+  const heading =
+    kind === 'conflict'
+      ? `Base-sync conflict on close: ${storyBranch} ↔ origin/${baseBranch}`
+      : `Base-sync failed on close (${kind}): ${storyBranch} ↔ origin/${baseBranch}`;
+  const fileList = (result.conflictFiles ?? []).map((f) => `- \`${f}\``);
+  const lines = [
+    `### ${heading}`,
+    '',
+    '`/single-story-deliver` close-validation passed, but the pre-push',
+    `sync against \`origin/${baseBranch}\` could not complete. The Story has`,
+    `been transitioned to \`agent::blocked\`. To resume:`,
+    '',
+    '```bash',
+    `cd ${syncCwd}`,
+    `git fetch origin ${baseBranch}`,
+    `git merge --no-edit origin/${baseBranch}`,
+    '# resolve any conflicts, then:',
+    `git add -A ; git commit --no-edit`,
+    '# re-run close:',
+    `node .agents/scripts/single-story-close.js --story ${storyId}`,
+    '```',
+  ];
+  if (kind === 'conflict' && fileList.length > 0) {
+    lines.push('', '**Conflicting files:**', '', ...fileList);
+  } else if (result.stderr) {
+    lines.push(
+      '',
+      '**git stderr:**',
+      '',
+      '```',
+      result.stderr.slice(0, 1000),
+      '```',
+    );
+  }
+  return lines.join('\n');
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -0,0 +1,81 @@
+/**
+ * phases/close-validation.js — run the canonical close-validation gate
+ * chain for a standalone Story.
+ *
+ * The standalone path uses the same `runCloseValidation` chain as
+ * Epic-attached Stories so the experience matches — only the baseline
+ * ref changes (`main`, not `epic/<id>`).
+ *
+ * Standalone Stories have no parent Epic, so there's no per-Epic path to
+ * scope a `validation-evidence.json` under. Pass `epicId: null` (not `0`)
+ * so the `evidenceActive` predicate in `runCloseValidation` short-circuits
+ * cleanly. `0` is rejected downstream by `validation-evidence.evidencePath`
+ * (which requires a positive integer epicId) and aborts the whole gate
+ * chain.
+ *
+ * The trade-off is that re-runs of close on the same SHA don't hit the
+ * evidence cache for standalone Stories; that's acceptable until/unless
+ * the standalone path warrants its own evidence keyspace.
+ *
+ * `runCloseValidation` and `buildDefaultGates` are accepted as injected
+ * dependencies so the parent CLI's cache-busted bindings win in tests
+ * that mock the upstream module URLs.
+ */
+
+import {
+  buildDefaultGates as defaultBuildDefaultGates,
+  runCloseValidation as defaultRunCloseValidation,
+} from '../../../close-validation.js';
+import { Logger } from '../../../Logger.js';
+
+/**
+ * Run the close-validation gate chain. Throws on first gate failure.
+ *
+ * Gates are built from the canonical resolved config (`buildDefaultGates`
+ * reads `project.commands` and `delivery.quality.gates.crap.enabled`); the
+ * `baseBranch` is forwarded as the gate `epicBranch` so the format gate's
+ * changed-file scope anchors on it.
+ *
+ * @param {{
+ *   cwd: string,
+ *   worktreePath: string|null,
+ *   config: object,
+ *   baseBranch: string,
+ *   storyId: number,
+ *   progress: (tag: string, msg: string) => void,
+ *   runCloseValidation?: typeof defaultRunCloseValidation,
+ *   buildDefaultGates?: typeof defaultBuildDefaultGates,
+ * }} args
+ */
+export async function runCloseValidationPhase({
+  cwd,
+  worktreePath,
+  config,
+  baseBranch,
+  storyId,
+  progress,
+  runCloseValidation = defaultRunCloseValidation,
+  buildDefaultGates = defaultBuildDefaultGates,
+}) {
+  progress(
+    'VALIDATE',
+    `Running close-validation gates against baseline ${baseBranch}${worktreePath ? ` in ${worktreePath}` : ''}...`,
+  );
+  const validation = await runCloseValidation({
+    cwd,
+    worktreePath,
+    gates: buildDefaultGates({ config, epicBranch: baseBranch }),
+    log: (m) => Logger.info(m),
+    storyId,
+    epicId: null,
+  });
+  if (!validation.ok) {
+    const [first] = validation.failed;
+    const { gate, status, cwd: gateCwd } = first;
+    throw new Error(
+      `[single-story-close] Gate failed: ${gate.name} (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
+        (gate.hint ? ` ${gate.hint}` : ''),
+    );
+  }
+  progress('VALIDATE', '✅ All gates passed.');
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js

@@ -0,0 +1,190 @@
+/**
+ * phases/code-review.js — Story-scope code review phase for
+ * `single-story-close`.
+ *
+ * Runs the Story-scope code review against `main`, posts the structured
+ * findings comment to the PR (not the Story issue), and adds a one-line
+ * cross-reference comment on the Story issue linking back to the PR
+ * review comment. The render header still labels the comment "Story #N"
+ * even though the post target is the PR — the PR is the comment surface,
+ * the Story is the ticket the findings *describe*.
+ *
+ * Cross-reference URL shape: GitHub serves issue comments at
+ * `<prUrl>#issuecomment-<commentId>` — the same URL pattern for PR
+ * conversation comments and issue comments, because PRs are issues at
+ * the API level.
+ *
+ * Re-exports `parsePrNumber` (delegates to `lib/github-url.js`) so
+ * existing call sites need not change. Story #3649.
+ *
+ * Critical findings cause `runStoryScopeReview` to return `halted: true`;
+ * the caller raises that to a thrown error so auto-merge is not enabled.
+ *
+ * Delegates the `runCodeReview` invocation to `runStoryReviewCore`
+ * (exported from `story-close/phases/code-review.js`) so both the
+ * Epic-attached and standalone close paths share a single invocation
+ * pattern (Story #3653).
+ */
+
+import { parsePrNumberFromUrl } from '../../../github-url.js';
+import { runStoryReviewCore } from '../../story-close/phases/code-review.js';
+import { postStructuredComment } from '../../ticketing/state.js';
+
+/**
+ * Extract the numeric PR ID from a `gh pr create` URL. The CLI returns a
+ * URL like `https://github.com/<owner>/<repo>/pull/<n>`; we want `<n>`.
+ * Returns `null` when the URL doesn't match. Exported for testing.
+ *
+ * Delegates to `parsePrNumberFromUrl` in `lib/github-url.js`.
+ * Re-exported under the original name so existing call sites and tests
+ * do not need to change. Story #3649.
+ *
+ * @param {string|null|undefined} prUrl
+ * @returns {number|null}
+ */
+export const parsePrNumber = parsePrNumberFromUrl;
+
+/**
+ * Build the cross-reference comment body posted on the Story issue when
+ * the PR-side review comment lands. Pure; exported for testing.
+ *
+ * @param {{
+ *   prUrl: string,
+ *   prNumber: number,
+ *   commentUrl: string,
+ *   severity: { critical: number, high: number, medium: number, suggestion: number },
+ * }} args
+ * @returns {string}
+ */
+export function buildStoryReviewCrossRefBody({
+  prUrl,
+  prNumber,
+  commentUrl,
+  severity,
+}) {
+  const tally =
+    `critical:${severity.critical} · high:${severity.high} · ` +
+    `medium:${severity.medium} · suggestion:${severity.suggestion}`;
+  return (
+    `🔬 Story-scope code review posted on PR [#${prNumber}](${prUrl}): ` +
+    `[view findings](${commentUrl}) — ${tally}.`
+  );
+}
+
+/**
+ * Run the Story-scope code review against `main`, post the structured
+ * findings comment to the PR, and add a one-line cross-reference comment
+ * on the Story issue linking back to the PR review comment.
+ *
+ * Failure modes:
+ *   - When `prNumber` is null (couldn't parse), the review is skipped
+ *     and the function returns `{ halted: false, skipped: true }`.
+ *   - When the runner throws, the close fails non-zero (the throw
+ *     propagates) — a Story-scope review failure is not silently
+ *     ignored.
+ *
+ * Exported for testing.
+ *
+ * @param {{
+ *   cwd: string,
+ *   storyId: number,
+ *   storyBranch: string,
+ *   baseBranch: string,
+ *   prUrl: string,
+ *   prNumber: number|null,
+ *   provider: object,
+ *   runCodeReviewFn: Function,
+ *   progress: (tag: string, msg: string) => void,
+ * }} args
+ * @returns {Promise<{
+ *   halted: boolean,
+ *   skipped?: boolean,
+ *   severity?: { critical: number, high: number, medium: number, suggestion: number },
+ *   posted?: boolean,
+ *   postedCommentId?: number|null,
+ *   crossRefPosted?: boolean,
+ * }>}
+ */
+export async function runStoryScopeReview({
+  cwd: _cwd,
+  storyId,
+  storyBranch,
+  baseBranch,
+  prUrl,
+  prNumber,
+  provider,
+  runCodeReviewFn,
+  progress,
+}) {
+  if (prNumber == null) {
+    progress(
+      'REVIEW',
+      `⏭ Story-scope review skipped: could not parse PR number from URL ${prUrl}.`,
+    );
+    return { halted: false, skipped: true };
+  }
+
+  progress(
+    'REVIEW',
+    `Running Story-scope code review for Story #${storyId} (${baseBranch}...${storyBranch}) → PR #${prNumber}...`,
+  );
+
+  const result = await runStoryReviewCore({
+    storyId,
+    baseRef: baseBranch,
+    headRef: storyBranch,
+    commentTargetId: prNumber,
+    provider,
+    progress,
+    progressTag: 'REVIEW',
+    runCodeReviewFn,
+  });
+
+  const sev = result.severity ?? {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    suggestion: 0,
+  };
+  progress(
+    'REVIEW',
+    `Findings — critical:${sev.critical} high:${sev.high} medium:${sev.medium} suggestion:${sev.suggestion}. Posted to PR #${prNumber}: ${result.posted}.`,
+  );
+
+  let crossRefPosted = false;
+  if (result.posted && Number.isInteger(result.postedCommentId)) {
+    const commentUrl = `${prUrl}#issuecomment-${result.postedCommentId}`;
+    const body = buildStoryReviewCrossRefBody({
+      prUrl,
+      prNumber,
+      commentUrl,
+      severity: sev,
+    });
+    try {
+      await postStructuredComment(provider, storyId, 'notification', body);
+      crossRefPosted = true;
+      progress(
+        'REVIEW',
+        `📝 Cross-reference comment posted on Story #${storyId} → ${commentUrl}`,
+      );
+    } catch (err) {
+      progress(
+        'REVIEW',
+        `⚠️ Failed to post Story cross-reference comment: ${err?.message ?? err}`,
+      );
+    }
+  } else if (!result.posted) {
+    progress(
+      'REVIEW',
+      '⚠️ Skipping Story cross-reference comment: PR-side review comment did not post.',
+    );
+  }
+
+  return {
+    halted: !!result.halted,
+    severity: sev,
+    posted: result.posted,
+    postedCommentId: result.postedCommentId ?? null,
+    crossRefPosted,
+  };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js

@@ -0,0 +1,70 @@
+/**
+ * phases/options.js — CLI / injection option parsing for
+ * `single-story-close`.
+ *
+ * Handles the conditional param-vs-CLI branch and all flag defaults in one
+ * place so the main `runSingleStoryClose` body stays focused on close
+ * pipeline logic. Each `??` operator counts as a branch in escomplex; the
+ * `resolveFlag` helper keeps the cyclomatic complexity tally bounded.
+ */
+
+import path from 'node:path';
+import { parseSprintArgs } from '../../../cli-args.js';
+import { PROJECT_ROOT } from '../../../config-resolver.js';
+
+/**
+ * Resolve a flag value from an explicit override, a parsed CLI arg, or a
+ * hard default.
+ *
+ * @template T
+ * @param {T|undefined} paramValue
+ * @param {T|undefined} parsedValue
+ * @param {T} defaultValue
+ * @returns {T}
+ */
+function resolveFlag(paramValue, parsedValue, defaultValue) {
+  return paramValue ?? parsedValue ?? defaultValue;
+}
+
+/**
+ * Parse and resolve all CLI / injection options for `runSingleStoryClose`.
+ *
+ * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, noFullScopeCrapParam }} raw
+ * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, noFullScopeCrap }}
+ */
+export function parseCloseOptions({
+  storyIdParam,
+  cwdParam,
+  skipValidationParam,
+  skipSyncParam,
+  noAutoMergeParam,
+  noFullScopeCrapParam,
+}) {
+  const parsed =
+    storyIdParam !== undefined
+      ? {
+          storyId: storyIdParam,
+          cwd: cwdParam ?? null,
+          skipValidation: !!skipValidationParam,
+          skipSync: !!skipSyncParam,
+          noAutoMerge: !!noAutoMergeParam,
+          noFullScopeCrap: !!noFullScopeCrapParam,
+        }
+      : parseSprintArgs();
+  return {
+    storyId: parsed.storyId,
+    cwd: path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT),
+    skipValidation: resolveFlag(
+      skipValidationParam,
+      parsed.skipValidation,
+      false,
+    ),
+    skipSync: resolveFlag(skipSyncParam, parsed.skipSync, false),
+    noAutoMerge: resolveFlag(noAutoMergeParam, parsed.noAutoMerge, false),
+    noFullScopeCrap: resolveFlag(
+      noFullScopeCrapParam,
+      parsed.noFullScopeCrap,
+      false,
+    ),
+  };
+}