@ikunin/sprintpilot 2.1.3 → 2.1.5

package/_Sprintpilot/bin/autopilot.js

@@ -39,6 +39,10 @@ const userCommands = require('../lib/orchestrator/user-commands');
 const divergence = require('../lib/orchestrator/divergence');
 const reportRenderer = require('../lib/orchestrator/report');
 const gitPlan = require('../lib/orchestrator/git-plan');
+const {
+  parseStatuses: parseSprintStatuses,
+  remainingFrom: remainingStoriesFrom,
+} = require('../scripts/list-remaining-stories');
 
 const { STATES } = stateMachine;
 
@@ -99,6 +103,86 @@ function safeExistsSync(p) {
   }
 }
 
+// Resolve the next pending story key from BMad's sprint-status.yaml.
+// Used by composeRuntimeState to populate state.story_key BEFORE
+// emitting PREPARE_STORY_BRANCH — without this, branchName() falls
+// back to "story/unknown" because state.story_key is null on a fresh
+// sprint (CREATE_STORY hasn't run yet; for nano there's no CREATE_STORY
+// at all and quick-dev reads sprint-status itself). Returns the first
+// non-done STORY key (filtering out epic rollup headers), or null when:
+//   - the status file doesn't exist (pre-planning)
+//   - all stories are done (sprint complete)
+//   - the file can't be parsed
+//   - the only non-done entries are epic rollups (no real stories yet)
+function resolveNextStoryKey(projectRoot) {
+  if (!projectRoot) return null;
+  const sprintStatusPath = path.join(
+    projectRoot,
+    '_bmad-output',
+    'implementation-artifacts',
+    'sprint-status.yaml',
+  );
+  if (!safeExistsSync(sprintStatusPath)) return null;
+  try {
+    const raw = fs.readFileSync(sprintStatusPath, 'utf8');
+    const stories = parseSprintStatuses(raw);
+    const remaining = remainingStoriesFrom(stories);
+    // parseStatuses returns every key under `development_status:` —
+    // including BMad's epic rollup headers (`epic-4: in-progress`).
+    // Filter them out so we don't ask the orchestrator to branch on an
+    // epic identifier (the v2.1.4 hotfix shipped without this filter and
+    // a user reported branch: story/epic-4 instead of story/4-8-...).
+    const realStories = remaining.filter(looksLikeStoryKey);
+    return realStories.length > 0 ? realStories[0] : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+// Tell story keys apart from non-story bookkeeping entries in
+// sprint-status.yaml. BMad development_status: holds three kinds of
+// entries that parseStatuses returns side-by-side:
+//
+//   1. Real stories — `4-8-realm-wide-matcher` / `epic-1-game-engine`.
+//      Always have at least one hyphen AFTER the epic identifier.
+//   2. Epic rollup headers — `epic-4` / bare `4`. The status reflects
+//      child-story rollup, not a unit of work for the autopilot.
+//   3. Retrospective entries — `4-retrospective` / `epic-4-retrospective`.
+//      Status tracks whether the per-epic retro ritual has run; not a
+//      story to dev.
+//
+// Reject (2) and (3). The v2.1.4 hotfix shipped without this filter and
+// the user reported `branch: story/epic-4` instead of the real next
+// pending story. The v2.1.5 hotfix extends the filter to retrospectives
+// after a follow-up report.
+function looksLikeStoryKey(key) {
+  if (typeof key !== 'string' || !key) return false;
+  // Retrospective entries (`-retrospective` suffix, with or without epic
+  // prefix). Match anywhere the suffix appears so `epic-4-retrospective`
+  // and `4-retrospective` are both rejected.
+  if (/-retrospective$/i.test(key)) return false;
+  // Strip any leading `epic-` prefix and require a remaining hyphen.
+  // `epic-4` → `4` → no hyphen → epic header (reject).
+  // `epic-1-game-engine` → `1-game-engine` → has hyphen → story (accept).
+  // `4-8-realm-wide-matcher` → unchanged → has hyphen → story (accept).
+  const withoutEpicPrefix = key.replace(/^epic-/i, '');
+  return withoutEpicPrefix.includes('-');
+}
+
+// Derive the epic identifier from a BMad story key. Convention:
+// `epic-N-slug` → `epic-N`; `<epic>-<story>-<slug>` → `<epic>`.
+// Returns null when the key doesn't parse cleanly. Kept in sync with
+// adapt.js#deriveEpicKey; centralized here so composeRuntimeState
+// doesn't have to import adapt's private helper.
+function deriveEpicFromStoryKey(storyKey) {
+  if (typeof storyKey !== 'string' || !storyKey) return null;
+  const epicPrefixed = storyKey.match(/^(epic-[A-Za-z0-9_]+)-/);
+  if (epicPrefixed) return epicPrefixed[1];
+  const firstSeg = storyKey.match(/^([A-Za-z0-9_]+)-/);
+  if (firstSeg) return firstSeg[1];
+  return null;
+}
+
 function persistState(updates, profile, projectRoot, story) {
   return stateStore.write(updates, profile, { projectRoot, story });
 }
@@ -114,7 +198,7 @@ function persistState(updates, profile, projectRoot, story) {
 // regardless of which CLI entrypoint composed the runtime (workflow.
 // orchestrator.md tells the LLM to call `next` directly, bypassing
 // cmdStart).
-function composeRuntimeState(persisted, profile) {
+function composeRuntimeState(persisted, profile, projectRoot) {
   // Fresh-sprint initial phase. When git settings require a per-story or
   // per-epic branch (granularity ∈ {story, epic} AND !reuse_user_branch
   // AND git.enabled !== false), boot at PREPARE_STORY_BRANCH so the very
@@ -180,11 +264,45 @@ function composeRuntimeState(persisted, profile) {
   ) {
     phase = STATES.PREPARE_STORY_BRANCH;
   }
+
+  // Resolve story_key for PREPARE_STORY_BRANCH. The branch creation step
+  // needs a known story_key (and current_epic under granularity=epic) to
+  // compute the branch name — without resolution, branchName() falls
+  // back to "story/unknown" and we'd push a useless ref to origin.
+  //
+  // Why this is needed: PREPARE_STORY_BRANCH runs BEFORE CREATE_STORY in
+  // the full flow (and NANO_QUICK_DEV picks the story itself in quick
+  // flow), so the story_key from persisted state can be null on a fresh
+  // sprint. Read sprint-status.yaml — the same source of truth bmad-
+  // create-story / bmad-quick-dev use — to look ahead and find the
+  // next pending story.
+  //
+  // If nothing is pending (pre-planning OR sprint complete OR parse
+  // failure), fall back to flowStart so the LLM gets a meaningful
+  // skill invocation. PREPARE_STORY_BRANCH with no story_key would be
+  // a confusing emission to act on.
+  let resolvedStoryKey = persisted.current_story || null;
+  let resolvedEpic = persisted.current_epic || null;
+  let resolvedStoryFilePath = persisted.story_file_path || null;
+  if (phase === STATES.PREPARE_STORY_BRANCH && !resolvedStoryKey) {
+    const next = resolveNextStoryKey(projectRoot);
+    if (next) {
+      resolvedStoryKey = next;
+      if (!resolvedEpic) resolvedEpic = deriveEpicFromStoryKey(next);
+    } else {
+      process.stderr.write(
+        `[autopilot] WARN PREPARE_STORY_BRANCH needs a next-story key but sprint-status.yaml has none pending — falling back to ${flowStart}. ` +
+          'Run BMad sprint-planning first, or set git.reuse_user_branch=true to commit on the current branch.\n',
+      );
+      phase = flowStart;
+    }
+  }
+
   return {
     phase,
-    story_key: persisted.current_story || null,
-    story_file_path: persisted.story_file_path || null,
-    current_epic: persisted.current_epic || null,
+    story_key: resolvedStoryKey,
+    story_file_path: resolvedStoryFilePath,
+    current_epic: resolvedEpic,
     ac_summary: persisted.ac_summary || null,
     prior_diagnosis: persisted.prior_diagnosis || null,
     relevant_decisions: persisted.relevant_decisions || [],
@@ -554,7 +672,7 @@ function cmdStart(opts) {
 
   // Fresh start or clean resume. `composeRuntimeState` applies the
   // profile-aware initial phase when persisted state is empty.
-  const runtime = composeRuntimeState(persisted, profile);
+  const runtime = composeRuntimeState(persisted, profile, projectRoot);
 
   const lockResult = lockUserBranchIfNeeded(runtime, profile, projectRoot);
   if (lockResult && lockResult.halt) {
@@ -580,7 +698,7 @@ function cmdNext(opts) {
   const projectRoot = resolveProjectRoot(opts);
   const { typed: profile } = resolveProfile(projectRoot, opts.profile);
   const persisted = loadState(projectRoot);
-  const runtime = composeRuntimeState(persisted, profile);
+  const runtime = composeRuntimeState(persisted, profile, projectRoot);
 
   // The LLM-driven workflow (workflow.orchestrator.md) tells the LLM to
   // call `next` directly without `start` — apply the same branch-reuse
@@ -618,7 +736,7 @@ function cmdRecord(opts) {
   const projectRoot = resolveProjectRoot(opts);
   const { typed: profile } = resolveProfile(projectRoot, opts.profile);
   const persisted = loadState(projectRoot);
-  const runtime = composeRuntimeState(persisted, profile);
+  const runtime = composeRuntimeState(persisted, profile, projectRoot);
 
   let signalJson;
   if (opts['signal-file']) {

package/_Sprintpilot/lib/orchestrator/adapt.js

@@ -397,12 +397,31 @@ function handleUserInput(state, signal, profile, sideEffects) {
 
   // One-shot dispatch (e.g. accept_alternative resolved a pending alt)?
   // Return the dispatched action in place of the state-machine's default.
+  //
+  // Sync story metadata onto newState. The dispatched action carries
+  // story_key / current_epic / story_file_path / ac_summary in its
+  // `template_slots` (and sometimes as top-level fields on git_ops).
+  // Without propagating these, accept_alternative dispatches work on
+  // a specific story but autopilot-state.yaml still shows
+  // `current_story: null` — subsequent emissions / persists / verify
+  // checks all reference the wrong story.
   const dispatch = applied.sideEffects.find((e) => e && e.kind === 'dispatch_action');
   if (dispatch && dispatch.action) {
+    const a = dispatch.action;
+    const slots = a.template_slots || {};
+    const enrichedState = {
+      ...newState,
+      story_key: newState.story_key || slots.story_key || a.story_key || null,
+      current_epic:
+        newState.current_epic || slots.current_epic || a.epic_key || null,
+      story_file_path:
+        newState.story_file_path || slots.story_file_path || null,
+      ac_summary: newState.ac_summary || slots.ac_summary || null,
+    };
     return {
-      newState,
+      newState: enrichedState,
       newProfile,
-      nextAction: { ...dispatch.action, _dispatched_via: dispatch.reason || 'user_input' },
+      nextAction: { ...a, _dispatched_via: dispatch.reason || 'user_input' },
       sideEffects,
       verdict: 'advanced',
     };

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

@@ -172,7 +172,30 @@ function nextAction(state, profile) {
   }
 
   switch (state.phase) {
-    case STATES.PREPARE_STORY_BRANCH:
+    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
@@ -187,6 +210,7 @@ function nextAction(state, profile) {
         epic_key: state.current_epic,
         profile: profile.name,
       };
+    }
     case STATES.CREATE_STORY:
       return {
         type: 'invoke_skill',

package/_Sprintpilot/manifest.yaml

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

package/package.json

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