@ikunin/sprintpilot 2.1.2 → 2.1.3

package/_Sprintpilot/scripts/create-pr.js

@@ -9,8 +9,10 @@ const log = require('../lib/runtime/log');
 
 function help() {
   log.out(
-    "Usage: create-pr.js --platform <github|gitlab|bitbucket|gitea|git_only> --branch <name> --base <branch> --title 'title' --body 'body' [--base-url <url>]",
+    "Usage: create-pr.js --mode <create|checks> --platform <github|gitlab|bitbucket|gitea|git_only> --branch <name> --base <branch> [--title 'title' --body 'body'] [--wait-minutes N] [--require-approved-review] [--base-url <url>]",
   );
+  log.out('  --mode create (default) — open a PR. Requires --title.');
+  log.out('  --mode checks          — poll an existing PR for CI / review status.');
 }
 
 async function hasCli(name) {
@@ -18,6 +20,18 @@ async function hasCli(name) {
   return r.exitCode === 0;
 }
 
+// Resolve `--platform auto` to a concrete provider by probing for an
+// installed CLI in priority order. Used by both --mode create and
+// --mode checks. Returns 'git_only' when nothing is installed so the
+// downstream branches surface a clear SKIPPED exit.
+async function resolveAutoPlatform() {
+  if (await hasCli('gh')) return 'github';
+  if (await hasCli('glab')) return 'gitlab';
+  if (await hasCli('bb')) return 'bitbucket';
+  if (await hasCli('tea')) return 'gitea';
+  return 'git_only';
+}
+
 // Accept only safe path components so a hostile remote URL can't inject
 // into the REST API path. Both segments must match this pattern; the full
 // path (repo name plus any GitLab subgroup segments) must contain only
@@ -88,7 +102,9 @@ function redactAuth(text) {
 }
 
 async function main() {
-  const { opts } = parseArgs(process.argv.slice(2), { booleanFlags: ['dry-run'] });
+  const { opts } = parseArgs(process.argv.slice(2), {
+    booleanFlags: ['dry-run', 'require-approved-review'],
+  });
   if (opts.help) {
     help();
     process.exit(0);
@@ -101,12 +117,35 @@ async function main() {
   const body = opts.body || '';
   const baseUrl = opts['base-url'];
   const dryRun = !!opts['dry-run'];
+  const mode = opts.mode || 'create';
+  const waitMinutes = Number.parseFloat(opts['wait-minutes'] || '30');
+  const requireApprovedReview = !!opts['require-approved-review'];
+
+  // --mode checks: poll the platform for CI / review status of an
+  // existing PR. Required by land.js when merge_strategy=land_as_you_go +
+  // land_when ∈ {ci_pass, ci_and_review}. Distinct argument surface from
+  // --mode create (no --title needed).
+  if (mode === 'checks') {
+    if (!platform || !branch) {
+      log.error('--mode checks requires --platform and --branch');
+      process.exit(1);
+    }
+    const resolved = platform === 'auto' ? await resolveAutoPlatform() : platform;
+    await runChecksMode({ platform: resolved, branch, baseBranch, waitMinutes, requireApprovedReview, baseUrl });
+    return;
+  }
 
   if (!platform || !branch || !title) {
     log.error('--platform, --branch, and --title are required');
     process.exit(1);
   }
 
+  // Resolve `auto` to a concrete provider via CLI probing. This honors
+  // the documented default in modules/git/config.yaml#platform.provider.
+  // Without this resolution, the platform === 'github'/'gitlab'/... if-
+  // chain below falls through to "unknown platform" exit 1.
+  const resolvedPlatform = platform === 'auto' ? await resolveAutoPlatform() : platform;
+
   const remote = await tryGitStdout(['remote', 'get-url', 'origin']);
   if (!remote) {
     log.out('SKIPPED');
@@ -124,19 +163,42 @@ async function main() {
     return;
   }
 
-  if (platform === 'git_only') {
+  if (resolvedPlatform === 'git_only') {
     log.out('SKIPPED');
     log.err('INFO: No platform CLI available. Push completed. Create PR manually:');
     log.err(`  Branch: ${branch} → ${baseBranch}`);
     process.exit(2);
   }
 
-  if (platform === 'github') {
+  if (resolvedPlatform === 'github') {
     if (!(await hasCli('gh'))) {
       log.err('WARN: gh CLI not found, skipping PR creation');
       log.out('SKIPPED');
       process.exit(2);
     }
+    // Idempotency: if a PR already exists for this branch (granularity=
+    // epic re-pushes onto the same branch, or a manual resume), return
+    // its URL and exit 0 instead of hitting `gh pr create` which fails
+    // hard with "a pull request for branch X already exists".
+    //
+    // `gh pr list --head <branch> --json url --limit 1` is the canonical
+    // "PRs for this head" query. It exits 0 with `[]` when no PR exists
+    // (distinct from `gh pr view` which exits 1 for both "no PR" and
+    // "auth failed" — ambiguous). We only short-circuit on a non-empty
+    // array; any other exit falls through to `gh pr create` so transient
+    // errors don't suppress PR creation forever.
+    const existing = await tryRun(
+      'gh',
+      ['pr', 'list', '--head', branch, '--json', 'url', '--limit', '1', '--jq', '.[0].url // ""'],
+      { timeoutMs: 15_000 },
+    );
+    if (existing.exitCode === 0) {
+      const url = (existing.stdout || '').trim();
+      if (url) {
+        log.out(url);
+        return;
+      }
+    }
     const r = await tryRun(
       'gh',
       ['pr', 'create', '--base', baseBranch, '--head', branch, '--title', title, '--body', body],
@@ -144,6 +206,13 @@ async function main() {
     );
     const combined = `${r.stdout}${r.stderr}`;
     if (r.exitCode !== 0) {
+      // Backstop: gh's "already exists" error message can race with our
+      // pre-check (push lands a PR between `view` and `create`). Detect
+      // it in stderr and treat as success.
+      if (/already exists/i.test(combined)) {
+        log.out(combined.trim());
+        return;
+      }
       log.error(`gh pr create failed: ${combined.trim()}`);
       process.exit(1);
     }
@@ -151,7 +220,7 @@ async function main() {
     return;
   }
 
-  if (platform === 'gitlab') {
+  if (resolvedPlatform === 'gitlab') {
     if (!(await hasCli('glab'))) {
       log.err('WARN: glab CLI not found, skipping MR creation');
       log.out('SKIPPED');
@@ -185,7 +254,7 @@ async function main() {
     return;
   }
 
-  if (platform === 'bitbucket') {
+  if (resolvedPlatform === 'bitbucket') {
     if (await hasCli('bb')) {
       const r = await tryRun(
         'bb',
@@ -247,7 +316,7 @@ async function main() {
     process.exit(2);
   }
 
-  if (platform === 'gitea') {
+  if (resolvedPlatform === 'gitea') {
     if (await hasCli('tea')) {
       const r = await tryRun(
         'tea',
@@ -304,10 +373,112 @@ async function main() {
     process.exit(2);
   }
 
+  log.error(`unknown platform '${resolvedPlatform}'`);
+  process.exit(1);
+}
+
+// --mode checks: poll an existing PR's CI status (and optionally review
+// status) until success, failure, or timeout. Polling interval is 30s
+// with ±5s of uniform jitter; the watchdog cap is `waitMinutes`.
+//
+// Effective per-cycle wall time can be up to ~60s when `gh pr checks`
+// itself takes the full 30s of its --timeoutMs before timing out on a
+// pending check, plus a 30s±5s sleep. Therefore the actual elapsed
+// time before declaring "timed out" can exceed `waitMinutes` by up to
+// ~one cycle (~60s). Set wait-minutes with that overhead in mind.
+//
+// gh exit codes for `gh pr checks <branch>`:
+//   0 — all required checks passed
+//   8 — checks still pending (not all completed)
+//   anything else — at least one required check failed
+//
+// On non-github platforms (or when CLI is missing), exits 2 (SKIPPED) so
+// land.js can surface a user_prompt rather than blocking on a feature
+// we can't deliver.
+async function runChecksMode({ platform, branch, baseBranch, waitMinutes, requireApprovedReview, baseUrl }) {
+  // `platform` has already been resolved (auto → concrete) in main(),
+  // so we only branch on concrete provider strings here.
+  if (platform === 'github') {
+    if (!(await hasCli('gh'))) {
+      log.err('WARN: gh CLI not found, cannot poll PR checks');
+      log.out('SKIPPED');
+      process.exit(2);
+    }
+    const deadline = Date.now() + Math.max(0, waitMinutes) * 60_000;
+    let lastSummary = '';
+    while (Date.now() < deadline) {
+      const r = await tryRun('gh', ['pr', 'checks', branch], { timeoutMs: 30_000 });
+      lastSummary = (r.stdout || '').trim().split('\n').slice(0, 5).join('\n');
+      if (r.exitCode === 0) {
+        // All required checks passed. If review is required, poll for that too.
+        if (!requireApprovedReview) {
+          log.out(`checks passed for ${branch}`);
+          return;
+        }
+        const reviewOk = await pollReviewApproved(branch, deadline);
+        if (reviewOk) {
+          log.out(`checks passed + review approved for ${branch}`);
+          return;
+        }
+        log.error(`checks passed but review not approved before deadline for ${branch}`);
+        process.exit(1);
+      }
+      if (r.exitCode === 8) {
+        // Pending — wait and retry. Add ±5s jitter so concurrent
+        // autopilot sessions (e.g. ma.parallel_stories) don't pile up
+        // gh-API calls in lockstep every 30 seconds.
+        await sleep(jitteredInterval(30_000, 5_000));
+        continue;
+      }
+      // Hard failure (e.g. exit 1) — at least one required check failed.
+      log.error(`checks failed for ${branch}:\n${lastSummary}`);
+      process.exit(1);
+    }
+    log.error(`timed out after ${waitMinutes}m waiting for checks on ${branch}\n${lastSummary}`);
+    process.exit(1);
+  }
+
+  if (platform === 'gitlab' || platform === 'bitbucket' || platform === 'gitea' || platform === 'git_only') {
+    // Polling is not yet implemented for these providers. Surface a
+    // SKIPPED exit so land.js can prompt the user.
+    log.err(`INFO: --mode checks polling not yet implemented for ${platform}. Verify manually.`);
+    log.out('SKIPPED');
+    process.exit(2);
+  }
+
   log.error(`unknown platform '${platform}'`);
   process.exit(1);
 }
 
+async function pollReviewApproved(branch, deadline) {
+  while (Date.now() < deadline) {
+    const r = await tryRun(
+      'gh',
+      ['pr', 'view', branch, '--json', 'reviewDecision', '--jq', '.reviewDecision'],
+      { timeoutMs: 15_000 },
+    );
+    const decision = (r.stdout || '').trim();
+    if (decision === 'APPROVED') return true;
+    if (decision === 'CHANGES_REQUESTED') return false; // hard fail — no point waiting
+    // REVIEW_REQUIRED, empty string, or any other state → keep polling
+    // with the same ±5s jitter as the checks loop.
+    await sleep(jitteredInterval(30_000, 5_000));
+  }
+  return false;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Compute a polling interval with ±jitterMs of uniform random noise so
+// concurrent pollers (parallel autopilot sessions) don't hit gh's API
+// in lockstep.
+function jitteredInterval(baseMs, jitterMs) {
+  const delta = Math.floor((Math.random() - 0.5) * 2 * jitterMs);
+  return Math.max(1000, baseMs + delta);
+}
+
 // Export pure helpers so they can be unit-tested directly. The script
 // itself still runs `main()` when invoked as a module.
 module.exports = { parseGitRemote, redactAuth };

package/_Sprintpilot/scripts/run-step.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * run-step.js — canonical executor for a single planned step.
+ *
+ * Reads a step JSON from stdin (or --step-file <path>) and runs it
+ * honoring the documented metadata contract from workflow.orchestrator.md:
+ *
+ *   - args: string[]                — argv (no shell interpolation)
+ *   - description?: string          — for logs only
+ *   - env?: { [k]: string }         — merged into process.env for the
+ *                                     step's lifetime
+ *   - retry?: { attempts, backoff_ms: [...], on: 'network'|'never' }
+ *                                   — re-run on failure. `attempts`
+ *                                     counts ATTEMPTS including the
+ *                                     first; backoff_ms is consulted
+ *                                     between retries (using
+ *                                     backoff_ms[i] for attempt i+1, or
+ *                                     the last value if out of range).
+ *                                     `on: 'never'` disables retry
+ *                                     regardless of attempts.
+ *   - tolerate_exit_codes?: number[]
+ *                                   — non-zero exit codes treated as
+ *                                     success (idempotency for ops like
+ *                                     gh pr merge / create-pr.js SKIPPED)
+ *   - optional?: boolean            — non-zero exit logged as warning,
+ *                                     runner still exits 0 so the caller
+ *                                     continues to the next step
+ *   - timeout_ms?: number           — per-attempt timeout
+ *
+ * Exit semantics:
+ *   0 — step succeeded (real success OR tolerate match OR optional fail)
+ *   N — actual exit code of the final attempt, when neither
+ *       tolerate_exit_codes nor optional applies
+ *
+ * Why this exists: the workflow contract used to assume the LLM reads
+ * step metadata fields and honors them. That coupling let drift creep
+ * in (e.g. tolerate_exit_codes silently ignored, optional treated as
+ * fatal). A small Node executor is the source of truth so the LLM
+ * doesn't need to remember the rules — it just runs
+ * `node _Sprintpilot/scripts/run-step.js --step-file <tmpfile>` per
+ * step and inspects exit code.
+ *
+ * Signal handling: SIGINT/SIGTERM received by run-step are forwarded
+ * to the in-flight child (when one is alive) so Ctrl-C terminates
+ * the chain cleanly rather than orphaning long-running `gh`/`git`
+ * subprocesses.
+ *
+ * Usage:
+ *   echo '{"args":["git","status"]}' | node run-step.js
+ *   node run-step.js --step-file /tmp/step.json
+ */
+
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const { parseArgs } = require('../lib/runtime/args');
+
+function readStepJson(opts) {
+  if (opts['step-file']) return fs.readFileSync(opts['step-file'], 'utf8');
+  return fs.readFileSync(0, 'utf8');
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Run a single attempt of the step's argv. Returns { exitCode, error }.
+// stdin: 'ignore' so the subprocess doesn't inherit run-step's stdin
+// (which is at EOF after readStepJson consumed it) — a command that
+// reads stdin (e.g. `git commit --file=-`) would otherwise see an
+// immediate EOF and silently produce nothing.
+function runOnce(cmd, rest, env, timeoutMs, currentChildRef) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, rest, {
+      stdio: ['ignore', 'inherit', 'inherit'],
+      env,
+      timeout: timeoutMs,
+    });
+    currentChildRef.child = child;
+    child.on('error', (err) => {
+      currentChildRef.child = null;
+      resolve({ exitCode: 2, error: err });
+    });
+    child.on('close', (code, signal) => {
+      currentChildRef.child = null;
+      if (signal) {
+        // Killed by signal — treat as non-zero. spawn maps signal name
+        // to no exit code, so synthesize one (128 + signal-number ish).
+        resolve({ exitCode: 130, error: null, signal });
+      } else {
+        resolve({ exitCode: typeof code === 'number' ? code : 2, error: null });
+      }
+    });
+  });
+}
+
+function backoffFor(attemptIndex, backoffMs) {
+  if (!Array.isArray(backoffMs) || backoffMs.length === 0) return 0;
+  const idx = Math.min(attemptIndex, backoffMs.length - 1);
+  return Math.max(0, Number(backoffMs[idx]) || 0);
+}
+
+async function runStep(step) {
+  const [cmd, ...rest] = step.args;
+  // Merge env: process.env first so unspecified keys stay; step.env
+  // wins for overlapping keys. Explicit non-null + non-array check
+  // because `typeof null === 'object'` and `typeof []  === 'object'`
+  // would both pass a naive `typeof === 'object'` guard, leading to
+  // `{...null}` (empty merge) or `{...[]}` (drops env entirely).
+  const env =
+    step.env !== null &&
+    step.env !== undefined &&
+    typeof step.env === 'object' &&
+    !Array.isArray(step.env)
+      ? { ...process.env, ...step.env }
+      : process.env;
+
+  if (step.description) {
+    process.stderr.write(`[run-step] ${step.description}\n`);
+  }
+
+  const retry = step.retry || {};
+  const retryEnabled = retry && retry.on && retry.on !== 'never';
+  const maxAttempts = retryEnabled && Number.isInteger(retry.attempts) && retry.attempts > 0
+    ? retry.attempts
+    : 1;
+  const backoffMs = retryEnabled ? retry.backoff_ms : null;
+  const timeoutMs = typeof step.timeout_ms === 'number' ? step.timeout_ms : undefined;
+  const tolerated = Array.isArray(step.tolerate_exit_codes) ? step.tolerate_exit_codes : [];
+
+  const childRef = { child: null };
+  const forwardSignal = (sig) => () => {
+    if (childRef.child && !childRef.child.killed) {
+      try {
+        childRef.child.kill(sig);
+      } catch (_e) {
+        /* best-effort */
+      }
+    }
+    process.exit(130);
+  };
+  process.on('SIGINT', forwardSignal('SIGINT'));
+  process.on('SIGTERM', forwardSignal('SIGTERM'));
+
+  let lastExit = 0;
+  let lastError = null;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (attempt > 0) {
+      const wait = backoffFor(attempt - 1, backoffMs);
+      if (wait > 0) {
+        process.stderr.write(`[run-step] retry attempt ${attempt + 1}/${maxAttempts} after ${wait}ms\n`);
+        await sleep(wait);
+      } else {
+        process.stderr.write(`[run-step] retry attempt ${attempt + 1}/${maxAttempts}\n`);
+      }
+    }
+    const r = await runOnce(cmd, rest, env, timeoutMs, childRef);
+    lastExit = r.exitCode;
+    lastError = r.error;
+    if (lastError && step.optional) {
+      process.stderr.write(`[run-step] WARN optional step failed to launch: ${lastError.message}\n`);
+      return 0;
+    }
+    if (lastError) {
+      process.stderr.write(`run-step: spawn error: ${lastError.message}\n`);
+      return 2;
+    }
+    if (lastExit === 0 || tolerated.includes(lastExit)) {
+      return 0;
+    }
+    // Non-zero and not tolerated. Retry policy `on: 'network'` is a
+    // declared intent — we re-run for any failure since we can't tell
+    // a network error from a logic error by exit code alone. The
+    // orchestrator's adapt.js classifies failure kinds afterwards.
+  }
+  if (step.optional) {
+    process.stderr.write(`[run-step] WARN optional step exited ${lastExit}; continuing\n`);
+    return 0;
+  }
+  return lastExit;
+}
+
+async function main() {
+  const { opts } = parseArgs(process.argv.slice(2));
+  let raw;
+  try {
+    raw = readStepJson(opts);
+  } catch (e) {
+    process.stderr.write(`run-step: cannot read step JSON: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  let step;
+  try {
+    step = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`run-step: invalid JSON: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  if (!step || !Array.isArray(step.args) || step.args.length === 0) {
+    process.stderr.write('run-step: step.args (non-empty array) required\n');
+    process.exit(2);
+  }
+
+  const code = await runStep(step);
+  process.exit(code);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    process.stderr.write(`run-step: ${e.stack || e.message || String(e)}\n`);
+    process.exit(2);
+  });
+}
+
+module.exports = { main, runStep };
+// Keep spawnSync import alive in case external callers use it (no-op
+// reference for tooling that prunes unused imports).
+void spawnSync;

package/_Sprintpilot/skills/sprint-autopilot-on/workflow.orchestrator.md

@@ -33,12 +33,45 @@ orchestrator emits it.
 |-------------------|--------------------------------------------------------------------------------------------------|
 | `invoke_skill`    | Run the named BMad skill **verbatim from its own body** (e.g. `bmad-create-story`, `bmad-quick-dev`, `bmad-code-review`). `action.template_slots` is a parameter bag (story_key, prior_diagnosis, relevant_decisions, prior_signals_summary, …) — it's input context for BMad's skill, NOT a replacement for the skill's instructions. When `implementation_flow=quick`, you'll receive `invoke_skill: bmad-quick-dev` per story — follow BMad's `step-oneshot.md`. |
 | `run_script`      | Execute `action.command` via the host's shell-equivalent. Argv-only — no shell interpolation.    |
-| `git_op`          | Execute `action.steps` in order. The orchestrator pre-plans every git op (commit_and_push_story, merge_epic, push, fetch, create_branch) via `git-plan.js` and inlines the resulting argv sequence — each step has `args: [cmd, ...argv]`, a `description`, and an optional `retry` policy. Run each step's argv verbatim (NO shell interpolation), halt on first non-retryable failure. Never improvise the git commands or skip a step — `git push` lives in `steps`, not in `op`. |
+| `git_op`          | Execute `action.steps` in order. The orchestrator pre-plans every git op (commit_and_push_story, merge_epic, push, fetch, create_branch) via `git-plan.js` and inlines the resulting argv sequence — each step has `args: [cmd, ...argv]`, a `description`, and optional metadata fields (see below). **Required**: run each step via `_Sprintpilot/scripts/run-step.js` (see "Step metadata" below) so the metadata contract is enforced uniformly. Argv-only — NO shell interpolation. Halt on first non-retryable failure. Never improvise the git commands or skip a step — `git push` lives in `steps`, not in `op`. Empty `steps: []` (e.g. when `git.enabled: false`) means "no work, signal success." |
 | `parallel_batch`  | Dispatch each child action concurrently (M6+ hosts only — fall back to sequential otherwise).    |
 | `user_prompt`     | Ask the user `action.prompt`. Pass the answer back via `user_input` signal.                      |
 | `halt`            | Stop. Honor `action.handoff: 'sprint_finalize_pending'` by ending the session cleanly.           |
 | `noop`            | Re-loop (state machine advancing without an external effect).                                    |
 
+### Step metadata (git_op / run_script)
+
+Each step in `action.steps` may carry these optional fields. They are
+NOT defaults — only honor them when present:
+
+| Field | Meaning |
+|---|---|
+| `retry` | `{ attempts: N, backoff_ms: [...], on: 'network' \| 'never' }`. Retry transient errors per the policy. `on: 'network'` covers e.g. `git push` to a flaky remote. |
+| `optional: true` | Run the step; on non-zero exit, log a warning and **continue** to the next step rather than halting. Used for best-effort prefetches and pulls. |
+| `tolerate_exit_codes: [N, M, ...]` | Treat any of these exit codes as success (equivalent to exit 0 for halt-detection). Used for idempotent commands like `gh pr merge` (which exits non-zero when the PR is already merged) and `create-pr.js` (which returns exit 2 SKIPPED when the platform CLI is unavailable). |
+| `env: { KEY: "value", ... }` | Set environment variables for this step's process only (merged on top of inherited env). Used to target self-hosted platform instances: `GH_HOST` for GitHub Enterprise, `GITLAB_URI` for self-hosted GitLab. |
+| `description` | Human-readable summary, surface in your own logs. |
+
+**Use the runner — direct argv execution is not equivalent.** A step
+that carries ANY of `retry`, `optional`, `tolerate_exit_codes`, or
+`env` MUST be executed via `_Sprintpilot/scripts/run-step.js`. The
+runner is the source of truth for the metadata contract; honoring
+those fields by hand drifts and loses retries, env scoping, and
+exit-code tolerance. Direct execution is only acceptable for steps
+that have none of those fields.
+
+```
+echo '<step-json>' | node _Sprintpilot/scripts/run-step.js
+```
+
+Path resolution: the orchestrator runs from the project root, so the
+relative path `_Sprintpilot/scripts/run-step.js` is correct in normal
+invocations. If running from a different cwd (e.g. a worktree
+subdirectory), resolve the absolute path from the autopilot's
+`--project-root` argument.
+
+When you signal `success` after a `git_op`, include `git_steps_completed: true` only if every step ran via the runner (or hand-executed in a way equivalent to it) and either exited 0 or matched its `tolerate_exit_codes`. A step that needed `optional: true` to pass still counts as not-completed for stricter sub-steps' purposes; `git_steps_completed` reflects the strict run.
+
 ## Signals you emit
 
 Wrap everything in `{ "status": "...", ... }` and pass to
@@ -90,6 +123,7 @@ bookkeeping you'd otherwise be tempted to skip:
 
 | Phase | Bookkeeping that MUST be true before you signal `success` |
 |---|---|
+| `prepare_story_branch` | Every step in `action.steps` exited 0 — HEAD is on `action.branch` (verify with `git rev-parse --abbrev-ref HEAD`). Emitted only when `git.granularity ∈ {story, epic}` AND `git.reuse_user_branch=false`. Under `reuse_user_branch=true` this phase is skipped — the user-locked branch is detected at cmdStart instead. |
 | `create_story` | Story file has `## Acceptance Criteria` (≥1 bullet) AND a `## Tasks` (or `## Tasks/Subtasks`) section with at least one `[ ]` or `[x]` checkbox. |
 | `dev_red` / `dev_green` | Test files exist on disk; runner exit codes match the phase contract; `tests_run` matches the runner's count. |
 | `code_review` | `_bmad-output/reviews/<story_key>.md` exists; `findings[]` carries `{id, severity, category, action: 'block'\|'patch'\|'defer', rationale}` for every finding. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikunin/sprintpilot",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Sprintpilot — autopilot and multi-agent addon for BMad Method v6: git workflow, parallel agents, autonomous story execution",
   "license": "Apache-2.0",
   "repository": {