mandrel 2.65.0 → 2.66.0

package/.agents/scripts/single-story-confirm-merge.js

@@ -16,8 +16,9 @@
  * @see .agents/workflows/helpers/deliver-story.md
  */
 
-import { parseArgs } from 'node:util';
-import { parseSprintArgsTolerant } from './lib/cli-args.js';
+import path from 'node:path';
+import { parseStandardCliArgs } from './lib/cli/standard-args.js';
+import { parseSprintArgs, parseSprintArgsTolerant } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { formatCliError } from './lib/error-redactor.js';
@@ -30,7 +31,7 @@ import { MERGED_FLIP_FAILED_BLOCK_CLASS } from './lib/orchestration/lifecycle/em
 import { MERGE_WAIT_GH_TIMEOUT_MS } from './lib/orchestration/merge-poll.js';
 import { parsePrNumber } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { runConfirmMergePhase as defaultRunConfirmMergePhase } from './lib/orchestration/single-story-close/phases/confirm-merge.js';
-import { parseCloseOptions } from './lib/orchestration/single-story-close/phases/options.js';
+import { assertNoRetiredFlags } from './lib/orchestration/single-story-close/phases/options.js';
 import { runPostLandTail } from './lib/orchestration/single-story-close/phases/post-land.js';
 import {
   buildTerminalEnvelope,
@@ -39,6 +40,7 @@ import {
   NEXT_COMMANDS,
   terminalFromWaitOutcome,
 } from './lib/orchestration/story-deliver-terminal.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
 import { createProvider } from './lib/provider-factory.js';
 import { confirmStoryMerged } from './lib/single-story/confirm-merge.js';
 
@@ -67,56 +69,42 @@ const USAGE =
   '                      over delivery.mergeWatch.maxWaitSeconds and the async\n' +
   '                      probe-window cap; only meaningful with --wait)';
 
-/**
- * @returns {string|undefined}
- */
-function readPrFlag() {
-  try {
-    const { values } = parseArgs({
-      args: process.argv.slice(2),
-      options: { pr: { type: 'string' } },
-      strict: false,
-    });
-    return values.pr;
-  } catch {
-    return undefined;
-  }
-}
+const CONFIRM_MERGE_FLAGS = Object.freeze({
+  pr: { type: 'string' },
+  // Resume the bounded wait; without it the CLI probes once.
+  wait: { type: 'boolean' },
+  'max-wait-seconds': { type: 'string' },
+  cwd: { type: 'string' },
+});
 
-/**
- * `--wait` resumes the bounded merge wait (`resumeLand`); without it the CLI
- * probes once, a fast flip for a merge that already happened.
- */
-function readWaitFlag() {
-  try {
-    const { values } = parseArgs({
-      args: process.argv.slice(2),
-      options: { wait: { type: 'boolean', default: false } },
-      strict: false,
-    });
-    return values.wait === true;
-  } catch {
-    return false;
-  }
+/** @returns {number|undefined} */
+function positiveIntOrUndefined(value) {
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
 
 /**
- * Per-run wait bound for `--wait`; `undefined` unless a positive integer.
+ * The close's vocabulary is validated first, so a malformed close flag fails
+ * `init` with the close's own message.
  *
- * @returns {number|undefined}
+ * @param {string[]} fullArgv
+ * @returns {object}
  */
-function readMaxWaitSecondsFlag() {
-  try {
-    const { values } = parseArgs({
-      args: process.argv.slice(2),
-      options: { 'max-wait-seconds': { type: 'string' } },
-      strict: false,
-    });
-    const parsed = Number.parseInt(String(values['max-wait-seconds']), 10);
-    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
-  } catch {
-    return undefined;
-  }
+function parseConfirmMergeArgv(fullArgv) {
+  const argv = fullArgv.slice(2);
+  assertNoRetiredFlags(argv);
+  parseSprintArgs(fullArgv);
+  const { values } = parseStandardCliArgs({
+    argv,
+    extras: CONFIRM_MERGE_FLAGS,
+  });
+  return {
+    storyId: values.storyId,
+    cwd: values.cwd,
+    pr: values.pr,
+    wait: values.wait,
+    maxWaitSeconds: positiveIntOrUndefined(values.maxWaitSeconds),
+  };
 }
 
 /**
@@ -164,199 +152,175 @@ async function logConfirmResult(result, terminal, config) {
   return { success: terminal.status !== 'failed', result, terminal };
 }
 
+/** @returns {'MERGED'|'CLOSED'|'OPEN'} */
+function confirmPrState(confirmation) {
+  if (confirmation.merged) return 'MERGED';
+  return confirmation.reason === 'pr-not-merged' ? 'CLOSED' : 'OPEN';
+}
+
+/** @returns {{ number: number, state: string }|null} */
+function confirmPr(prNumber, confirmation) {
+  if (!Number.isInteger(prNumber) || prNumber <= 0) return null;
+  return { number: prNumber, state: confirmPrState(confirmation) };
+}
+
+function confirmBlocked(blockClass, reason, nextCommand) {
+  return {
+    status: 'blocked',
+    phase: 'confirm-merge',
+    blocked: { blockClass, reason, frictionCommentId: null },
+    nextCommand,
+  };
+}
+
 /**
- * Map a confirmation onto the shared terminal envelope: done/noop → landed;
- * flip-failed → blocked (re-run this command); pr-not-merged → blocked (needs
- * a human); otherwise pending.
+ * done/noop → landed; flip-failed → blocked (re-run this command);
+ * pr-not-merged → blocked (needs a human); otherwise pending.
  */
-function buildConfirmTerminal({
-  storyId,
-  storyBranch,
-  baseBranch,
-  prNumber,
-  confirmation,
-  tail,
-  elapsedSeconds,
-}) {
-  const prState = confirmation.merged
-    ? 'MERGED'
-    : confirmation.reason === 'pr-not-merged'
-      ? 'CLOSED'
-      : 'OPEN';
-  const pr =
-    Number.isInteger(prNumber) && prNumber > 0
-      ? { number: prNumber, state: prState }
-      : null;
-  const common = { storyId, storyBranch, baseBranch, pr, elapsedSeconds };
-
+function confirmOutcomeFields({ storyId, confirmation, tail }) {
   if (confirmation.action === 'done' || confirmation.action === 'noop') {
-    return buildTerminalEnvelope({
-      ...common,
+    return {
       status: 'landed',
       phase: tail ? 'post-land' : 'done',
       tail,
       nextCommand: null,
-    });
+    };
   }
   if (confirmation.action === 'flip-failed') {
-    return buildTerminalEnvelope({
-      ...common,
-      status: 'blocked',
-      phase: 'confirm-merge',
-      blocked: {
-        blockClass: MERGED_FLIP_FAILED_BLOCK_CLASS,
-        reason:
-          'merge confirmed but the agent::closing → agent::done label write failed',
-        frictionCommentId: null,
-      },
-      nextCommand: NEXT_COMMANDS.confirmMerge(storyId),
-    });
+    return confirmBlocked(
+      MERGED_FLIP_FAILED_BLOCK_CLASS,
+      'merge confirmed but the agent::closing → agent::done label write failed',
+      NEXT_COMMANDS.confirmMerge(storyId),
+    );
   }
   if (confirmation.reason === 'pr-not-merged') {
-    return buildTerminalEnvelope({
-      ...common,
-      status: 'blocked',
-      phase: 'confirm-merge',
-      blocked: {
-        blockClass: 'api-race-other',
-        reason: 'the PR was closed without merging (state=CLOSED)',
-        frictionCommentId: null,
-      },
-      nextCommand: NEXT_COMMANDS.recover(storyId),
-    });
+    return confirmBlocked(
+      'api-race-other',
+      'the PR was closed without merging (state=CLOSED)',
+      NEXT_COMMANDS.recover(storyId),
+    );
   }
-  return buildTerminalEnvelope({
-    ...common,
+  return {
     status: 'pending',
     phase: 'confirm-merge',
     nextCommand:
       confirmation.reason === 'no-pr'
         ? NEXT_COMMANDS.recover(storyId)
         : NEXT_COMMANDS.confirmMerge(storyId),
+  };
+}
+
+function buildConfirmTerminal({
+  storyId,
+  storyBranch,
+  baseBranch,
+  prNumber,
+  confirmation,
+  tail,
+  elapsedSeconds,
+}) {
+  return buildTerminalEnvelope({
+    storyId,
+    storyBranch,
+    baseBranch,
+    pr: confirmPr(prNumber, confirmation),
+    elapsedSeconds,
+    ...confirmOutcomeFields({ storyId, confirmation, tail }),
   });
 }
 
-async function resolveConfirmPrNumber({ prParam, storyBranch, gh }) {
-  const rawPr = prParam ?? readPrFlag();
-  let prNumber = Number.parseInt(String(rawPr ?? ''), 10);
+async function resolveConfirmPrNumber({ pr, storyBranch, gh }) {
+  let prNumber = Number.parseInt(String(pr ?? ''), 10);
   if (!Number.isInteger(prNumber) || prNumber <= 0) {
     prNumber = await resolvePrNumber({ storyBranch, gh });
   }
   return Number.isInteger(prNumber) && prNumber > 0 ? prNumber : null;
 }
 
-export async function runConfirmMerge({
-  storyId: storyIdParam,
-  cwd: cwdParam,
-  pr: prParam,
-  wait: waitParam,
-  maxWaitSeconds: maxWaitSecondsParam,
-  injectedProvider,
-  injectedConfig,
-  injectedGh,
-  injectedNotify,
-  injectedReadPrMergeState,
-  runConfirmMergePhaseFn = defaultRunConfirmMergePhase,
-} = {}) {
-  const { storyId, cwd } = parseCloseOptions({
-    storyIdParam,
-    cwdParam,
-  });
-
-  if (!storyId) {
-    throw new Error(USAGE);
-  }
-  const wait = waitParam ?? readWaitFlag();
-  const maxWaitSeconds = maxWaitSecondsParam ?? readMaxWaitSecondsFlag();
-
-  const startedAtMs = Date.now();
-  const config = injectedConfig || resolveConfig({ cwd });
-  const provider = injectedProvider || createProvider(config);
-  const gh = injectedGh ?? defaultGh;
-  const storyBranch = getStoryBranch(storyId);
-  const baseBranch = config.project?.baseBranch ?? 'main';
+function elapsedSeconds(ctx) {
+  return Math.round((Date.now() - ctx.startedAtMs) / 1000);
+}
 
-  progress('INIT', `Confirming merge for standalone Story #${storyId}...`);
+async function confirmWithoutPr(ctx) {
+  progress(
+    'CONFIRM',
+    `⚠️ No PR found for ${ctx.storyBranch}; cannot confirm merge. Story stays at agent::closing.`,
+  );
+  const noPr = {
+    storyId: ctx.storyId,
+    standalone: true,
+    action: 'pending',
+    reason: 'no-pr',
+    merged: false,
+  };
+  return await logConfirmResult(
+    noPr,
+    buildConfirmTerminal({
+      storyId: ctx.storyId,
+      storyBranch: ctx.storyBranch,
+      baseBranch: ctx.baseBranch,
+      prNumber: null,
+      confirmation: noPr,
+      tail: null,
+      elapsedSeconds: elapsedSeconds(ctx),
+    }),
+    ctx.config,
+  );
+}
 
-  const prNumber = await resolveConfirmPrNumber({
-    prParam,
+/**
+ * `--wait` runs the SAME phase as close so the cumulative budget give-up
+ * (the only path to `merge.unlanded` / `agent::blocked`) is reachable from a
+ * resume. The budget is anchored at the PR's `createdAt`, so resuming does
+ * not restart the clock.
+ */
+async function resumeMergeWait(ctx) {
+  const { storyId, storyBranch, baseBranch, prNumber } = ctx;
+  const waitOutcome = await ctx.runConfirmMergePhaseFn({
+    cwd: ctx.cwd,
+    storyId,
+    storyBranch,
+    baseBranch,
+    prNumber,
+    prUrl: `${storyBranch} PR #${prNumber}`,
+    // The close already armed it.
+    autoMergeEnabled: true,
+    maxWaitSeconds: ctx.maxWaitSeconds,
+    provider: ctx.provider,
+    config: ctx.config,
+    progress,
+    injectedGh: ctx.gh,
+    injectedNotify: ctx.injectedNotify,
+    readPrMergeStateFn: ctx.injectedReadPrMergeState,
+  });
+  const terminal = terminalFromWaitOutcome({
+    waitOutcome,
+    storyId,
     storyBranch,
-    gh,
+    baseBranch,
+    prNumber,
+    prUrl: null,
+    autoMergeEnabled: true,
+    // This CLI runs no close gates.
+    gates: undefined,
+    elapsedSeconds: elapsedSeconds(ctx),
   });
-  if (prNumber == null) {
-    progress(
-      'CONFIRM',
-      `⚠️ No PR found for ${storyBranch}; cannot confirm merge. Story stays at agent::closing.`,
-    );
-    const noPr = {
+  return await logConfirmResult(
+    {
       storyId,
       standalone: true,
-      action: 'pending',
-      reason: 'no-pr',
-      merged: false,
-    };
-    return await logConfirmResult(
-      noPr,
-      buildConfirmTerminal({
-        storyId,
-        storyBranch,
-        baseBranch,
-        prNumber: null,
-        confirmation: noPr,
-        tail: null,
-        elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
-      }),
-      config,
-    );
-  }
-
-  // `--wait` runs the SAME phase as close so the cumulative budget give-up
-  // (the only path to `merge.unlanded` / `agent::blocked`) is reachable from a
-  // resume. The budget is anchored at the PR's `createdAt`, so resuming does
-  // not restart the clock.
-  if (wait) {
-    const waitOutcome = await runConfirmMergePhaseFn({
-      cwd,
-      storyId,
-      storyBranch,
-      baseBranch,
-      prNumber,
-      prUrl: `${storyBranch} PR #${prNumber}`,
-      // The close already armed it.
-      autoMergeEnabled: true,
-      maxWaitSeconds,
-      provider,
-      config,
-      progress,
-      injectedGh: gh,
-      injectedNotify,
-      readPrMergeStateFn: injectedReadPrMergeState,
-    });
-    const terminal = terminalFromWaitOutcome({
-      waitOutcome,
-      storyId,
-      storyBranch,
-      baseBranch,
-      prNumber,
-      prUrl: null,
-      autoMergeEnabled: true,
-      // This CLI runs no close gates.
-      gates: undefined,
-      elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
-    });
-    return await logConfirmResult(
-      {
-        storyId,
-        standalone: true,
-        action: waitOutcome.terminal,
-        resumed: true,
-        tail: waitOutcome.tail ?? null,
-      },
-      terminal,
-      config,
-    );
-  }
+      action: waitOutcome.terminal,
+      resumed: true,
+      tail: waitOutcome.tail ?? null,
+    },
+    terminal,
+    ctx.config,
+  );
+}
 
+async function probeMergeOnce(ctx) {
+  const { storyId, storyBranch, baseBranch, prNumber, cwd, provider, config } =
+    ctx;
   const confirmation = await confirmStoryMerged({
     provider,
     storyId,
@@ -365,9 +329,9 @@ export async function runConfirmMerge({
     cwd,
     config,
     progress,
-    injectedGh: gh,
-    injectedNotify,
-    readPrMergeStateFn: injectedReadPrMergeState,
+    injectedGh: ctx.gh,
+    injectedNotify: ctx.injectedNotify,
+    readPrMergeStateFn: ctx.injectedReadPrMergeState,
   });
 
   // The same shared land tail close runs. Gated on `merged`, not
@@ -393,7 +357,7 @@ export async function runConfirmMerge({
     prNumber,
     confirmation,
     tail,
-    elapsedSeconds: Math.round((Date.now() - startedAtMs) / 1000),
+    elapsedSeconds: elapsedSeconds(ctx),
   });
   if (confirmation.action === 'done') {
     progress('DONE', `✅ Story #${storyId} → agent::done (merged).`);
@@ -405,43 +369,108 @@ export async function runConfirmMerge({
   );
 }
 
+/** Reads no argv: `main()` parses it and passes the values in. */
+export async function runConfirmMerge({
+  storyId,
+  cwd,
+  pr,
+  wait = false,
+  maxWaitSeconds,
+  injectedProvider,
+  injectedConfig,
+  injectedGh,
+  injectedNotify,
+  injectedReadPrMergeState,
+  runConfirmMergePhaseFn = defaultRunConfirmMergePhase,
+} = {}) {
+  if (!storyId) {
+    throw new Error(USAGE);
+  }
+  const startedAtMs = Date.now();
+  const resolvedCwd = path.resolve(cwd ?? PROJECT_ROOT);
+  const config = injectedConfig || resolveConfig({ cwd: resolvedCwd });
+  const storyBranch = getStoryBranch(storyId);
+  const ctx = {
+    storyId,
+    cwd: resolvedCwd,
+    startedAtMs,
+    config,
+    provider: injectedProvider || createProvider(config),
+    gh: injectedGh ?? defaultGh,
+    storyBranch,
+    baseBranch: config.project?.baseBranch ?? 'main',
+    maxWaitSeconds,
+    injectedNotify,
+    injectedReadPrMergeState,
+    runConfirmMergePhaseFn,
+  };
+
+  progress('INIT', `Confirming merge for standalone Story #${storyId}...`);
+
+  const prNumber = await resolveConfirmPrNumber({
+    pr,
+    storyBranch,
+    gh: ctx.gh,
+  });
+  if (prNumber == null) return await confirmWithoutPr(ctx);
+  const withPr = { ...ctx, prNumber };
+  return wait ? await resumeMergeWait(withPr) : await probeMergeOnce(withPr);
+}
+
+/**
+ * A throw still emits a `failed` envelope: it is the landing surface's
+ * contract.
+ *
+ * @returns {Promise<number>}
+ */
+async function failWithEnvelope(err, phase, fullArgv) {
+  // Tolerant parse: a strict one would re-throw an argv rejection here.
+  const { args, error: argvError } = parseSprintArgsTolerant(fullArgv);
+  const storyId = Number(args.storyId);
+  // No story id: nothing to report an envelope about.
+  if (!Number.isInteger(storyId) || storyId <= 0) throw err;
+  const terminal = buildTerminalEnvelope({
+    storyId,
+    status: 'failed',
+    // An argv rejection precedes every phase.
+    phase: argvError ? 'init' : phase,
+    failure: { reason: String(err?.message ?? err) },
+    nextCommand: NEXT_COMMANDS.recover(storyId),
+    elapsedSeconds: 0,
+  });
+  Logger.error(
+    `[single-story-confirm-merge] Fatal error: ${formatCliError(err)}`,
+  );
+  emitTerminalEnvelope(terminal);
+  await emitTerminalFriction({ envelope: terminal, tool: CLI_SOURCE });
+  return exitCodeForTerminal(terminal);
+}
+
 /**
- * Exit code comes from the terminal envelope's status. A throw (e.g. a
- * transient `gh` error) still emits a `failed` envelope: the envelope is the
- * landing surface's contract.
+ * Exit code comes from the envelope's status; `runAsCli` answers `--help`.
+ *
+ * @param {string[]} fullArgv
+ * @returns {Promise<number>}
  */
-async function main() {
-  if (process.argv.includes('--help')) {
-    process.stdout.write(`${USAGE}\n`);
-    return 0;
+export async function runConfirmMergeCli(fullArgv) {
+  let options;
+  try {
+    options = parseConfirmMergeArgv(fullArgv);
+  } catch (err) {
+    return await failWithEnvelope(err, 'init', fullArgv);
   }
   try {
-    const outcome = await runConfirmMerge();
+    const outcome = await runConfirmMerge(options);
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
   } catch (err) {
-    // Tolerant parse: a strict one would re-throw an argv rejection here.
-    const { args, error: argvError } = parseSprintArgsTolerant();
-    const storyId = Number(args.storyId);
-    // No story id: nothing to report an envelope about.
-    if (!Number.isInteger(storyId) || storyId <= 0) throw err;
-    const terminal = buildTerminalEnvelope({
-      storyId,
-      status: 'failed',
-      // An argv rejection precedes every phase.
-      phase: argvError ? 'init' : 'confirm-merge',
-      failure: { reason: String(err?.message ?? err) },
-      nextCommand: NEXT_COMMANDS.recover(storyId),
-      elapsedSeconds: 0,
-    });
-    Logger.error(
-      `[single-story-confirm-merge] Fatal error: ${formatCliError(err)}`,
-    );
-    emitTerminalEnvelope(terminal);
-    await emitTerminalFriction({ envelope: terminal, tool: CLI_SOURCE });
-    return exitCodeForTerminal(terminal);
+    return await failWithEnvelope(err, 'confirm-merge', fullArgv);
   }
 }
 
+function main() {
+  return runConfirmMergeCli(process.argv);
+}
+
 runAsCli(import.meta.url, main, {
   source: CLI_SOURCE,
   propagateExitCode: true,

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -22,12 +22,12 @@ description:
 
 ## Activation
 
-Called from [`/mandrel-plan`](../../../workflows/mandrel-plan.md) during ideation when the
-operator supplies `--seed "<text>"` (or runs ideation with no seed and the host
-collects one interactively). The skill sharpens freeform intent into the
-canonical planning sections that `/mandrel-plan` then folds into a Story. There is no
-separate Epic Clarity Gate path in v2 — N=1 Story authoring with a folded
-`## Spec` is the lean default.
+Invoked directly by the operator (`idea-refine` / `ideate`), ahead of
+planning — it is not a step of
+[`/mandrel-plan`](../../../workflows/mandrel-plan.md), whose Gate #1 stops only
+for a HITL unknown or a duplicate. The skill sharpens freeform intent into the
+canonical planning sections, so a saved one-pager feeds
+`/mandrel-plan <path>` (seed-file mode) directly.
 
 ## Detailed Instructions
 

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -109,8 +109,7 @@ not a soft preference.
   convenience to work around. Confirm authenticated state with a
   `take_snapshot` before driving.
 - **No headless fallback.** The chrome-devtools MCP surface is a host-provided
-  runtime dependency. If it is unavailable, degrade with a clear error and stop
-  — never fall back to the retired headless BDD runner.
+  runtime dependency. If it is unavailable, report a clear error and stop.
 
 ## 4. Mode — Known-Scenario Sweep (`/qa-run`)
 

package/.agents/workflows/audit-architecture.md

@@ -23,10 +23,11 @@ Per the core's Scope interpretation:
 
 ## Execution strategy
 
-This is a **heavyweight lens**: dispatch it as a single `subagent_type: auditor`
-call, or fan its dimensions out per-dimension across parallel `auditor`
-subagents (parallel-tooling Rule 3) and merge under the self-cross-check.
-Sequential inline execution is the fallback (see the core's Execution strategy).
+Dispatch this lens as one `subagent_type: auditor` call. Fan its dimensions
+out across parallel `auditor` subagents (parallel-tooling Rule 3), merging
+under the self-cross-check, only when the operator explicitly asks for
+per-dimension fan-out. Sequential inline execution is the fallback (see the
+core's Execution strategy).
 
 ## Step 0: Tool-first detection (mandatory — run before any LLM dimension)
 

package/.agents/workflows/audit-documentation.md

@@ -62,11 +62,11 @@ with the config-driven target set above.
 
 ## Execution strategy
 
-This is a **heavyweight lens**: dispatch it as a single `subagent_type: auditor`
-call, or fan its per-doc / per-dimension verification out across parallel
-`auditor` subagents (parallel-tooling Rule 3) and merge under the
-self-cross-check. Sequential inline execution is the fallback (see the core's
-Execution strategy).
+Dispatch this lens as one `subagent_type: auditor` call. Fan its per-doc /
+per-dimension verification out across parallel `auditor` subagents
+(parallel-tooling Rule 3), merging under the self-cross-check, only when the
+operator explicitly asks for per-dimension fan-out. Sequential inline
+execution is the fallback (see the core's Execution strategy).
 
 ## Step 1: Deterministic Signal First