@ikunin/sprintpilot 2.1.2 → 2.1.4

package/_Sprintpilot/lib/orchestrator/land.js

@@ -71,18 +71,28 @@ function planLand(state, profile, options) {
     description: `snapshot stack for ${branch}`,
   });
 
-  // Step 2: wait for CI / review depending on land_when.
+  // Step 2: wait for CI / review depending on land_when. Honors
+  // git.platform.provider (forwarded via --platform) so non-github
+  // providers route to the correct CLI / API path inside create-pr.js.
   if (landWhen === 'ci_pass' || landWhen === 'ci_and_review') {
+    const platform = (profile.platform_provider || options.platform || 'auto');
     const checkArgs = [
       'node',
       createPr,
       '--mode',
       'checks',
+      '--platform',
+      platform,
       '--branch',
       branch,
+      '--base',
+      baseBranch,
       '--wait-minutes',
       String(waitMinutes),
     ];
+    if (profile.platform_base_url) {
+      checkArgs.push('--base-url', profile.platform_base_url);
+    }
     if (landWhen === 'ci_and_review') {
       checkArgs.push('--require-approved-review');
     }

package/_Sprintpilot/lib/orchestrator/profile-rules.js

@@ -18,6 +18,10 @@ const VALID_RETRO_MODES = ['auto', 'stop', 'skip'];
 const VALID_GRANULARITIES = ['story', 'epic'];
 const VALID_MERGE_STRATEGIES = ['stacked', 'land_as_you_go'];
 const VALID_LAND_WHENS = ['no_wait', 'ci_pass', 'ci_and_review'];
+const VALID_PLATFORM_PROVIDERS = ['auto', 'github', 'gitlab', 'bitbucket', 'gitea', 'git_only'];
+
+const DEFAULT_COMMIT_TEMPLATE_STORY = 'feat({epic}): {story-title} ({story-key})';
+const DEFAULT_COMMIT_TEMPLATE_PATCH = 'fix({story-key}): {patch-title}';
 
 // Per-profile defaults for fields the orchestrator manages directly
 // (verify_reject_budget, retry_budget_per_action). These are orchestrator-
@@ -59,6 +63,16 @@ function coerceEnum(v, allowed, fallback) {
   return fallback;
 }
 
+// Compute land_wait_minutes (default 30) and epic_merge_wait_minutes
+// (falls back to land_wait_minutes). Kept as a helper so the fallback
+// chain is readable; inlining produced a nested coerceInt call that
+// was hard to scan.
+function resolveWaitMinutes(resolved) {
+  const land = coerceInt(get(resolved, 'git.land_wait_minutes'), 30);
+  const epic = coerceInt(get(resolved, 'git.epic_merge_wait_minutes'), land);
+  return { land_wait_minutes: land, epic_merge_wait_minutes: epic };
+}
+
 // Convert the flat resolved-config tree (from resolve-profile.js) into a
 // typed Profile. Missing keys fall back to documented defaults.
 function flatToProfile(resolved, profileName) {
@@ -90,7 +104,7 @@ function flatToProfile(resolved, profileName) {
       'stacked',
     ),
     land_when: coerceEnum(get(resolved, 'git.land_when'), VALID_LAND_WHENS, 'ci_pass'),
-    land_wait_minutes: coerceInt(get(resolved, 'git.land_wait_minutes'), 30),
+    ...resolveWaitMinutes(resolved),
     base_branch:
       typeof get(resolved, 'git.base_branch') === 'string'
         ? get(resolved, 'git.base_branch')
@@ -99,6 +113,53 @@ function flatToProfile(resolved, profileName) {
       typeof get(resolved, 'git.branch_prefix') === 'string'
         ? get(resolved, 'git.branch_prefix')
         : 'story/',
+    // git.enabled — when false, every `git_op` action emitted by the
+    // state machine is replaced with a `noop` at decorateGitOp time.
+    // Used for evaluation / dry-run setups where the user wants the
+    // BMad cycle to run but doesn't want any commits / pushes / PRs.
+    enabled: coerceBool(get(resolved, 'git.enabled'), true),
+    // git.push.auto — when false, planCommitAndPush drops the push
+    // steps (both story-branch and base-branch). Branches stay local.
+    push_auto: coerceBool(get(resolved, 'git.push.auto'), true),
+    // git.push.create_pr — when true (and merge_strategy=stacked),
+    // planCommitAndPush appends a `create-pr.js` step after the push so
+    // each story branch gets one PR opened automatically. land_as_you_go
+    // already opens its own PRs via land.js, so this knob doesn't gate
+    // that path.
+    push_create_pr: coerceBool(get(resolved, 'git.push.create_pr'), true),
+    pr_template_path:
+      typeof get(resolved, 'git.push.pr_template') === 'string'
+        ? get(resolved, 'git.push.pr_template')
+        : null,
+    // Commit message templates. Placeholders expanded in git-plan.js:
+    //   {story-key}    — state.story_key
+    //   {epic}         — state.current_epic (or derived from story_key)
+    //   {story-title}  — state.ac_summary or story_key as fallback
+    //   {patch-title}  — set on patch commits (bmad-dev-story owns those)
+    commit_template_story:
+      typeof get(resolved, 'git.commit_templates.story') === 'string'
+        ? get(resolved, 'git.commit_templates.story')
+        : DEFAULT_COMMIT_TEMPLATE_STORY,
+    commit_template_patch:
+      typeof get(resolved, 'git.commit_templates.patch') === 'string'
+        ? get(resolved, 'git.commit_templates.patch')
+        : DEFAULT_COMMIT_TEMPLATE_PATCH,
+    // git.max_branch_length — branchName() truncates long branch names
+    // (story keys + prefix) to this length with a 6-char hash suffix to
+    // keep the name unique. Honors the contract advertised in config.yaml.
+    max_branch_length: coerceInt(get(resolved, 'git.max_branch_length'), 60),
+    // git.platform.provider + base_url — forwarded to create-pr.js when
+    // the orchestrator opens or polls PRs. 'auto' delegates platform
+    // detection to create-pr.js (currently defaults to github).
+    platform_provider: coerceEnum(
+      get(resolved, 'git.platform.provider'),
+      VALID_PLATFORM_PROVIDERS,
+      'auto',
+    ),
+    platform_base_url:
+      typeof get(resolved, 'git.platform.base_url') === 'string'
+        ? get(resolved, 'git.platform.base_url')
+        : null,
     parallel_stories: coerceBool(get(resolved, 'ma.parallel_stories'), false),
     max_parallel_stories: coerceInt(get(resolved, 'ma.max_parallel_stories'), 2),
     fallback_on_tests_fail: coerceBool(
@@ -161,6 +222,9 @@ module.exports = {
   VALID_GRANULARITIES,
   VALID_MERGE_STRATEGIES,
   VALID_LAND_WHENS,
+  VALID_PLATFORM_PROVIDERS,
+  DEFAULT_COMMIT_TEMPLATE_STORY,
+  DEFAULT_COMMIT_TEMPLATE_PATCH,
   ORCHESTRATOR_DEFAULTS_BY_PROFILE,
   flatToProfile,
   escalateOnFailure,

package/_Sprintpilot/lib/orchestrator/state-machine.js

@@ -41,6 +41,14 @@
 'use strict';
 
 const STATES = Object.freeze({
+  // PREPARE_STORY_BRANCH — emitted as the first state of a fresh story
+  // when the active git settings require a per-story or per-epic branch
+  // (granularity ∈ {story, epic} AND !reuse_user_branch). Resolves to a
+  // git_op with op: 'create_branch' so the story file itself is authored
+  // on the story branch. Under `reuse_user_branch: true` this state is
+  // skipped and CREATE_STORY / NANO_QUICK_DEV runs directly on the
+  // user-locked branch.
+  PREPARE_STORY_BRANCH: 'prepare_story_branch',
   CREATE_STORY: 'create_story',
   CHECK_READINESS: 'check_readiness',
   DEV_RED: 'dev_red',
@@ -54,6 +62,16 @@ const STATES = Object.freeze({
   // story's PR into base. Skipped (STORY_DONE → EPIC_BOUNDARY_CHECK directly)
   // under the default 'stacked' strategy.
   STORY_LAND: 'story_land',
+  // MERGE_EPIC — entered from EPIC_BOUNDARY_CHECK when:
+  //   • end-of-epic (remaining_stories_in_epic === 0)
+  //   • granularity === 'epic'
+  //   • merge_strategy === 'stacked'
+  //   • push_auto === true, has_origin !== false, !reuse_user_branch
+  // Closes out the epic branch by either merging its PR (push_create_pr=
+  // true) or local-merging directly to base (push_create_pr=false). The
+  // existing planMergeEpic builds the local-merge sequence; planMergeEpicPr
+  // builds the gh-cli sequence.
+  MERGE_EPIC: 'merge_epic',
   EPIC_BOUNDARY_CHECK: 'epic_boundary_check',
   RETROSPECTIVE: 'retrospective',
   SPRINT_FINALIZE_PENDING: 'sprint_finalize_pending',
@@ -68,6 +86,7 @@ const TERMINAL_STATES = new Set([STATES.SPRINT_FINALIZE_PENDING]);
 // edges (e.g. patch_apply only when findings.action==='patch') are
 // enforced in `nextStateAfterSuccess`.
 const FULL_FLOW_SUCCESSORS = {
+  [STATES.PREPARE_STORY_BRANCH]: [STATES.CREATE_STORY],
   [STATES.CREATE_STORY]: [STATES.CHECK_READINESS],
   [STATES.CHECK_READINESS]: [STATES.DEV_RED],
   [STATES.DEV_RED]: [STATES.DEV_GREEN],
@@ -77,16 +96,39 @@ const FULL_FLOW_SUCCESSORS = {
   [STATES.PATCH_RETEST]: [STATES.CODE_REVIEW, STATES.STORY_DONE], // conditional (re-review if still blocking)
   [STATES.STORY_DONE]: [STATES.STORY_LAND, STATES.EPIC_BOUNDARY_CHECK], // STORY_LAND only under land_as_you_go
   [STATES.STORY_LAND]: [STATES.EPIC_BOUNDARY_CHECK],
-  [STATES.EPIC_BOUNDARY_CHECK]: [STATES.RETROSPECTIVE, STATES.CREATE_STORY, STATES.SPRINT_FINALIZE_PENDING],
-  [STATES.RETROSPECTIVE]: [STATES.CREATE_STORY, STATES.SPRINT_FINALIZE_PENDING],
+  [STATES.EPIC_BOUNDARY_CHECK]: [
+    STATES.MERGE_EPIC,
+    STATES.RETROSPECTIVE,
+    STATES.PREPARE_STORY_BRANCH,
+    STATES.CREATE_STORY,
+    STATES.SPRINT_FINALIZE_PENDING,
+  ],
+  [STATES.MERGE_EPIC]: [STATES.RETROSPECTIVE, STATES.SPRINT_FINALIZE_PENDING],
+  [STATES.RETROSPECTIVE]: [
+    STATES.PREPARE_STORY_BRANCH,
+    STATES.CREATE_STORY,
+    STATES.SPRINT_FINALIZE_PENDING,
+  ],
 };
 
 const NANO_FLOW_SUCCESSORS = {
+  [STATES.PREPARE_STORY_BRANCH]: [STATES.NANO_QUICK_DEV],
   [STATES.NANO_QUICK_DEV]: [STATES.STORY_DONE],
   [STATES.STORY_DONE]: [STATES.STORY_LAND, STATES.EPIC_BOUNDARY_CHECK],
   [STATES.STORY_LAND]: [STATES.EPIC_BOUNDARY_CHECK],
-  [STATES.EPIC_BOUNDARY_CHECK]: [STATES.RETROSPECTIVE, STATES.NANO_QUICK_DEV, STATES.SPRINT_FINALIZE_PENDING],
-  [STATES.RETROSPECTIVE]: [STATES.NANO_QUICK_DEV, STATES.SPRINT_FINALIZE_PENDING],
+  [STATES.EPIC_BOUNDARY_CHECK]: [
+    STATES.MERGE_EPIC,
+    STATES.RETROSPECTIVE,
+    STATES.PREPARE_STORY_BRANCH,
+    STATES.NANO_QUICK_DEV,
+    STATES.SPRINT_FINALIZE_PENDING,
+  ],
+  [STATES.MERGE_EPIC]: [STATES.RETROSPECTIVE, STATES.SPRINT_FINALIZE_PENDING],
+  [STATES.RETROSPECTIVE]: [
+    STATES.PREPARE_STORY_BRANCH,
+    STATES.NANO_QUICK_DEV,
+    STATES.SPRINT_FINALIZE_PENDING,
+  ],
 };
 
 // Build instruction template content slots from state + profile. This is the
@@ -130,6 +172,45 @@ function nextAction(state, profile) {
   }
 
   switch (state.phase) {
+    case STATES.PREPARE_STORY_BRANCH: {
+      // Safety net: PREPARE_STORY_BRANCH needs a known story_key (and,
+      // under granularity=epic, a current_epic) so git-plan.branchName
+      // can compute a real branch. composeRuntimeState resolves these
+      // from sprint-status.yaml before we get here — but if BOTH are
+      // null (sprint-status was empty, unreadable, or doesn't exist
+      // yet) we'd emit `branch: story/unknown` and confuse the runner.
+      // Emit a user_prompt instead so the user fixes the upstream
+      // condition (run BMad sprint-planning) rather than acting on a
+      // garbage action.
+      const haveStoryKey = !!state.story_key;
+      const haveEpicForBranch =
+        profile.granularity === 'epic' && !!state.current_epic;
+      if (!haveStoryKey && !haveEpicForBranch) {
+        return {
+          type: 'user_prompt',
+          phase: state.phase,
+          reason: 'prepare_story_branch_no_story_key',
+          prompt:
+            'PREPARE_STORY_BRANCH was emitted but the orchestrator could not resolve a next story_key from sprint-status.yaml. ' +
+            'Either run BMad sprint-planning to populate sprint-status.yaml, set `git.reuse_user_branch: true` in modules/git/config.yaml to commit on the current branch, ' +
+            'or set `git.enabled: false` for a dry run without git operations.',
+        };
+      }
+      // The edge layer (autopilot.js#decorateGitOp) inlines the planned
+      // argv steps via git-plan.js#planCreateBranch. It also probes git
+      // for branch existence and threads `state.branch_exists` through
+      // so the plan can degrade `git switch -c` to `git switch` when the
+      // branch already exists (e.g. second story under granularity=epic,
+      // or resume after partial failure).
+      return {
+        type: 'git_op',
+        phase: state.phase,
+        op: 'create_branch',
+        story_key: state.story_key,
+        epic_key: state.current_epic,
+        profile: profile.name,
+      };
+    }
     case STATES.CREATE_STORY:
       return {
         type: 'invoke_skill',
@@ -194,6 +275,19 @@ function nextAction(state, profile) {
         story_key: state.story_key,
         profile: profile.name,
       };
+    case STATES.MERGE_EPIC:
+      // Edge layer (decorateGitOp) inlines the argv steps via
+      // git-plan.js#planMergeEpic. The plan branches internally on
+      // profile.push_create_pr to choose `gh pr merge --squash` vs the
+      // local-merge sequence.
+      return {
+        type: 'git_op',
+        phase: state.phase,
+        op: 'merge_epic',
+        story_key: state.story_key,
+        epic_key: state.current_epic,
+        profile: profile.name,
+      };
     case STATES.STORY_LAND:
       // Land-as-you-go: orchestrator plumbing emits a `run_script` that
       // wraps the existing stack-snapshot.js + land-this-pr.js scripts.
@@ -288,6 +382,13 @@ function nextStateAfterSuccess(currentState, profile, signal) {
 function deterministicNext(state, profile, output) {
   const phase = state.phase;
   switch (phase) {
+    case STATES.PREPARE_STORY_BRANCH: {
+      // Branch is on disk → enter the actual story work (flow-dependent).
+      const next = profile.implementation_flow === 'quick'
+        ? STATES.NANO_QUICK_DEV
+        : STATES.CREATE_STORY;
+      return { chosen: next, allValid: [next] };
+    }
     case STATES.CREATE_STORY:
       return { chosen: STATES.CHECK_READINESS, allValid: [STATES.CHECK_READINESS] };
     case STATES.CHECK_READINESS:
@@ -330,6 +431,12 @@ function deterministicNext(state, profile, output) {
       const sprintDone = !!state.sprint_is_complete;
       // End of epic?
       if (remainingInEpic <= 0) {
+        // Epic merge: granularity=epic + stacked + autoremote-push +
+        // !reuse_user_branch + git enabled → close out the epic branch
+        // (MERGE_EPIC) before retrospective / next-epic routing.
+        if (epicMergeNeeded(profile)) {
+          return { chosen: STATES.MERGE_EPIC, allValid: [STATES.MERGE_EPIC] };
+        }
         if (profile.retrospective_mode === 'skip') {
           return {
             chosen: sprintDone ? STATES.SPRINT_FINALIZE_PENDING : nextStoryStart(profile),
@@ -341,6 +448,22 @@ function deterministicNext(state, profile, output) {
       // More stories in the same epic.
       return { chosen: nextStoryStart(profile), allValid: [nextStoryStart(profile)] };
     }
+    case STATES.MERGE_EPIC: {
+      const sprintDone = !!state.sprint_is_complete;
+      const successor = nextStoryStart(profile);
+      // Structurally-valid successors per FULL/NANO_FLOW_SUCCESSORS:
+      // [RETROSPECTIVE, SPRINT_FINALIZE_PENDING]. Include the next-story
+      // start under retro=skip so the hint tiebreaker can route to it
+      // when the LLM has a strong opinion.
+      const allValid = [STATES.RETROSPECTIVE, STATES.SPRINT_FINALIZE_PENDING, successor];
+      if (profile.retrospective_mode === 'skip') {
+        return {
+          chosen: sprintDone ? STATES.SPRINT_FINALIZE_PENDING : successor,
+          allValid,
+        };
+      }
+      return { chosen: STATES.RETROSPECTIVE, allValid };
+    }
     case STATES.RETROSPECTIVE: {
       const sprintDone = !!state.sprint_is_complete;
       const chosen = sprintDone ? STATES.SPRINT_FINALIZE_PENDING : nextStoryStart(profile);
@@ -355,13 +478,66 @@ function deterministicNext(state, profile, output) {
   }
 }
 
+// nextStoryStart(profile) — the first phase of a fresh story.
+//
+// Under settings that require a per-story or per-epic branch
+// (granularity ∈ {story, epic} AND !reuse_user_branch) the very first
+// phase is PREPARE_STORY_BRANCH so the branch exists before the story
+// file is authored. Otherwise we skip straight to the flow-appropriate
+// implementation step.
+//
+// The `reuse_user_branch: true` path is handled by autopilot.js#cmdStart
+// which detects the current branch and locks it in via state.user_branch;
+// PREPARE_STORY_BRANCH is unnecessary in that mode (every story commits
+// to the same already-checked-out branch).
+// epicMergeNeeded(profile) — true when EPIC_BOUNDARY_CHECK at end-of-epic
+// should route through MERGE_EPIC instead of jumping straight to
+// retrospective / next-story. Matches the same triggers as the per-story
+// PR/merge in planCommitAndPush, just shifted to the epic-branch flow.
+function epicMergeNeeded(profile) {
+  return (
+    profile &&
+    profile.enabled !== false &&
+    !profile.reuse_user_branch &&
+    profile.granularity === 'epic' &&
+    (profile.merge_strategy || 'stacked') === 'stacked' &&
+    profile.push_auto !== false &&
+    profile.has_origin !== false
+  );
+}
+
+// shouldSkipVerifyWhenGitDisabled(phase) — true when verify.js should
+// be bypassed under `git.enabled: false`. This covers phases that emit
+// a git_op (PREPARE_STORY_BRANCH, STORY_DONE, MERGE_EPIC) and STORY_LAND
+// (which emits a run_script but reports the same kind of post-merge
+// bookkeeping that requires git operations to have happened).
+//
+// Centralizing the list here means new phases of either kind won't
+// silently miss the verify-skip wiring — add them to the set below.
+// (Previously named `isGitOpPhase`; renamed because STORY_LAND is not
+// strictly a git_op and the old name lied.)
+const GIT_INTERACTING_PHASES = new Set([
+  STATES.PREPARE_STORY_BRANCH,
+  STATES.STORY_DONE,
+  STATES.MERGE_EPIC,
+  STATES.STORY_LAND,
+]);
+function shouldSkipVerifyWhenGitDisabled(phase) {
+  return GIT_INTERACTING_PHASES.has(phase);
+}
+
 function nextStoryStart(profile) {
+  const needsBranchPrep =
+    !profile.reuse_user_branch &&
+    (profile.granularity === 'story' || profile.granularity === 'epic');
+  if (needsBranchPrep) return STATES.PREPARE_STORY_BRANCH;
   return profile.implementation_flow === 'quick' ? STATES.NANO_QUICK_DEV : STATES.CREATE_STORY;
 }
 
 // Best-effort mapping from a next_skill_hint string (e.g. "bmad-code-review")
 // to a phase identifier. Used only as a tiebreaker.
 const HINT_TO_PHASE = {
+  prepare_story_branch: STATES.PREPARE_STORY_BRANCH,
   'bmad-create-story': STATES.CREATE_STORY,
   'bmad-check-implementation-readiness': STATES.CHECK_READINESS,
   'bmad-dev-story:red': STATES.DEV_RED,
@@ -372,6 +548,7 @@ const HINT_TO_PHASE = {
   'bmad-retrospective': STATES.RETROSPECTIVE,
   'bmad-quick-dev': STATES.NANO_QUICK_DEV,
   story_done: STATES.STORY_DONE,
+  merge_epic: STATES.MERGE_EPIC,
   sprint_finalize_pending: STATES.SPRINT_FINALIZE_PENDING,
 };
 
@@ -396,6 +573,8 @@ module.exports = {
   nextStateAfterSuccess,
   // Exposed for adapt.js to construct fresh-story states.
   nextStoryStart,
+  // Exposed for autopilot.js verify-skip routing.
+  shouldSkipVerifyWhenGitDisabled,
   // Exposed for tests / inspection.
   buildTemplateSlots,
   HINT_TO_PHASE,

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.1.2
+  version: 2.1.4
   description: Sprintpilot — autopilot and multi-agent addon for BMad Method (git workflow, parallel agents, autonomous story execution)
   bmad_compatibility: ">=6.2.0"
   modules:

package/_Sprintpilot/modules/git/config.yaml

@@ -40,6 +40,14 @@ git:
   # the orchestrator halts and prompts the user.
   land_wait_minutes: 30
 
+  # Max minutes to wait for CI green on the epic branch before MERGE_EPIC
+  # invokes `gh pr merge`. Only consulted under granularity=epic +
+  # merge_strategy=stacked. Falls back to `land_wait_minutes` if unset,
+  # so existing configs with only the land knob keep working. Effective
+  # wall time can exceed this by up to ~60s due to the polling cycle
+  # (gh pr checks timeout + 30s±5s sleep) — see create-pr.js#runChecksMode.
+  epic_merge_wait_minutes: 30
+
   # Branch naming
   branch_prefix: "story/" # prefix for story branches (e.g., story/1-2-user-auth)
   max_branch_length: 60 # truncate + 6-char hash if longer