@ikunin/sprintpilot 2.1.4 → 2.2.0

package/README.md

@@ -31,6 +31,17 @@ npx @ikunin/sprintpilot@latest
 /sprint-autopilot-on
 ```
 
+**Start at a specific story or epic** (v2.2.0+):
+
+```
+/sprint-autopilot-on epic 4
+/sprint-autopilot-on stories 3.1, 3.2, 4.5
+/sprint-autopilot-on 4-8-realm-wide-matcher-and-session-lock
+/sprint-autopilot-on voice identity matcher
+```
+
+The skill resolves the natural-language directive against your `sprint-status.yaml` and queues the matching stories. The autopilot runs them in order, then falls back to the normal next-pending-story flow. Ambiguous matches surface a candidate list — never picks arbitrarily.
+
 Non-interactive install:
 
 ```bash

package/_Sprintpilot/bin/autopilot.js

@@ -65,6 +65,25 @@ function help() {
       '  --profile <nano|small|medium|large|legacy>',
       '                               Override resolved profile',
       '  --help                       Show this help',
+      '',
+      'Story-selection flags (on `start` only):',
+      '  --stories <k1,k2,...>        Explicit queue of story keys to run, in',
+      '                               order. Keys must exist in sprint-status.yaml',
+      '                               and not be already done. Once the queue',
+      '                               exhausts, the orchestrator falls back to',
+      '                               its normal next-pending-story flow.',
+      '  --epic <id>                  Queue all non-done stories of the given',
+      '                               epic (id matches `epic-N` or bare `N`),',
+      '                               in sprint-status.yaml order. --stories',
+      '                               takes priority when both are given.',
+      '  --force                      Overwrite an in-flight queue. Without',
+      '                               this, --stories/--epic refuses to run',
+      '                               when current_story is set or a queue',
+      '                               already exists.',
+      '',
+      'Natural-language entry: `/sprint-autopilot-on epic 4` /',
+      '`/sprint-autopilot-on stories 3.1, 4.5` — the skill resolves the NL',
+      'directive to canonical keys and invokes `autopilot start --stories`.',
     ].join('\n'),
   );
 }
@@ -109,10 +128,11 @@ function safeExistsSync(p) {
 // 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
-// story whose status is NOT "done" (case-insensitive), or null when:
+// 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(
@@ -126,12 +146,167 @@ function resolveNextStoryKey(projectRoot) {
     const raw = fs.readFileSync(sprintStatusPath, 'utf8');
     const stories = parseSprintStatuses(raw);
     const remaining = remainingStoriesFrom(stories);
-    return remaining.length > 0 ? remaining[0] : null;
+    // 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('-');
+}
+
+// Build an explicit story queue from CLI opts (--stories / --epic).
+// Returns { queue: [], error?: string }. Either or both flags can be
+// provided; --stories is the canonical list and --epic expands to all
+// non-done stories under that epic. When both are given, --stories
+// takes priority. When neither is given, returns an empty queue
+// (orchestrator falls back to resolveNextStoryKey).
+//
+// Validation:
+//   - Every key listed in --stories must exist in sprint-status.yaml.
+//   - Every key must NOT have status 'done'.
+//   - For --epic, the epic must have at least one non-done story.
+function buildExplicitQueueFromOpts(opts, projectRoot) {
+  const rawStories = typeof opts.stories === 'string' ? opts.stories : null;
+  const rawEpic = opts.epic !== undefined && opts.epic !== null ? String(opts.epic) : null;
+  if (!rawStories && !rawEpic) return { queue: [] };
+
+  const sprintStories = readSprintStatuses(projectRoot);
+  if (!sprintStories || Object.keys(sprintStories).length === 0) {
+    return {
+      queue: [],
+      error:
+        '--stories / --epic given but sprint-status.yaml is missing or empty. ' +
+        'Run BMad sprint-planning to populate it before queuing stories.',
+    };
+  }
+
+  if (rawStories) {
+    const requested = rawStories
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (requested.length === 0) {
+      return { queue: [], error: '--stories was empty after parsing the comma-separated list.' };
+    }
+    const missing = [];
+    const alreadyDone = [];
+    const queue = [];
+    for (const key of requested) {
+      if (!Object.prototype.hasOwnProperty.call(sprintStories, key)) {
+        missing.push(key);
+        continue;
+      }
+      const status = String(sprintStories[key].status || '').trim().toLowerCase();
+      if (status === 'done') {
+        alreadyDone.push(key);
+        continue;
+      }
+      queue.push(key);
+    }
+    if (missing.length > 0 || alreadyDone.length > 0) {
+      const parts = [];
+      if (missing.length > 0) {
+        parts.push(
+          `not in sprint-status.yaml: ${missing.join(', ')}. ` +
+            'Use canonical keys (e.g. 4-8-realm-wide-matcher), not story numbers (e.g. 4.8).',
+        );
+      }
+      if (alreadyDone.length > 0) {
+        parts.push(`already done: ${alreadyDone.join(', ')}`);
+      }
+      return { queue: [], error: `--stories rejected: ${parts.join(' | ')}` };
+    }
+    return { queue };
+  }
+
+  // --epic only
+  const expanded = resolveStoriesForEpic(projectRoot, rawEpic);
+  if (expanded.length === 0) {
+    return {
+      queue: [],
+      error: `--epic ${rawEpic}: no non-done stories found in sprint-status.yaml`,
+    };
+  }
+  return { queue: expanded };
+}
+
+// Read and parse sprint-status.yaml. Returns { stories } where stories
+// is a map of {key: {status: string|null}}. Returns null on any failure
+// (missing file, parse error). Callers handle null gracefully.
+function readSprintStatuses(projectRoot) {
+  if (!projectRoot) return null;
+  const p = path.join(
+    projectRoot,
+    '_bmad-output',
+    'implementation-artifacts',
+    'sprint-status.yaml',
+  );
+  if (!safeExistsSync(p)) return null;
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    return parseSprintStatuses(raw);
+  } catch (_e) {
+    return null;
+  }
+}
+
+// Resolve all non-done story keys for the given epic id, in
+// sprint-status.yaml insertion order. Used by `autopilot start
+// --epic <id>` to expand into an explicit queue. Returns [] when:
+//   - sprint-status doesn't exist or fails to parse
+//   - no stories match the epic
+//   - all matching stories are already done
+function resolveStoriesForEpic(projectRoot, epicId) {
+  if (!epicId) return [];
+  const stories = readSprintStatuses(projectRoot);
+  if (!stories) return [];
+  const keys = Object.keys(stories);
+  const out = [];
+  for (const key of keys) {
+    if (!looksLikeStoryKey(key)) continue;
+    const derivedEpic = deriveEpicFromStoryKey(key);
+    if (derivedEpic !== epicId && derivedEpic !== `epic-${epicId}`) continue;
+    const status = String(stories[key].status || '').trim().toLowerCase();
+    if (status === 'done') continue;
+    out.push(key);
+  }
+  return out;
+}
+
 // 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
@@ -247,6 +422,20 @@ function composeRuntimeState(persisted, profile, projectRoot) {
   let resolvedStoryKey = persisted.current_story || null;
   let resolvedEpic = persisted.current_epic || null;
   let resolvedStoryFilePath = persisted.story_file_path || null;
+  // Explicit queue (populated by `autopilot start --stories` / `--epic`)
+  // takes priority over the linear resolveNextStoryKey scan: when a
+  // user specifies "start with stories 4-1, 4-2, 4-5" we honor that
+  // order regardless of what comes first in sprint-status.yaml.
+  // Forward-compat for ma.parallel_stories: the queue is the source
+  // multiple workers will pull from when the parallel-batch path is
+  // wired into the state machine.
+  const persistedQueue = Array.isArray(persisted.story_queue)
+    ? persisted.story_queue.filter((k) => typeof k === 'string' && k.length > 0)
+    : [];
+  if (!resolvedStoryKey && persistedQueue.length > 0) {
+    resolvedStoryKey = persistedQueue[0];
+    if (!resolvedEpic) resolvedEpic = deriveEpicFromStoryKey(resolvedStoryKey);
+  }
   if (phase === STATES.PREPARE_STORY_BRANCH && !resolvedStoryKey) {
     const next = resolveNextStoryKey(projectRoot);
     if (next) {
@@ -280,6 +469,10 @@ function composeRuntimeState(persisted, profile, projectRoot) {
     escalation_note: persisted.escalation_note || null,
     // Branch reuse: persisted across resumes once detected on first boot.
     user_branch: persisted.user_branch || null,
+    // Explicit story queue from `autopilot start --stories` / `--epic`.
+    // Head is the current pick; adapt.advanceState pops on story
+    // completion. Empty array means "no override; use resolveNextStoryKey."
+    story_queue: persistedQueue,
     // Land-as-you-go: pending land state survives rebase-conflict halts.
     land_pending: persisted.land_pending || null,
     // Pending alternative (propose_alternative → user_prompt) survives
@@ -311,6 +504,7 @@ function persistRuntimeState(runtime, profile, projectRoot) {
     verify_reject_count: runtime.verify_reject_count,
     consecutive_test_failures: runtime.consecutive_test_failures,
     user_branch: runtime.user_branch,
+    story_queue: Array.isArray(runtime.story_queue) ? runtime.story_queue : [],
     land_pending: runtime.land_pending,
     pending_alternative: runtime.pending_alternative || null,
   };
@@ -617,6 +811,37 @@ function cmdStart(opts) {
   const { typed: profile } = resolveProfile(projectRoot, opts.profile);
   const persisted = loadState(projectRoot);
 
+  // Build an explicit story queue from --stories / --epic flags. The
+  // user (or the LLM via /sprint-autopilot-on natural-language args)
+  // tells the orchestrator EXACTLY which stories to run, and in what
+  // order. Queue head is consumed first; resolveNextStoryKey takes
+  // over once the queue exhausts.
+  const queueBuildResult = buildExplicitQueueFromOpts(opts, projectRoot);
+  if (queueBuildResult.error) {
+    log.error(queueBuildResult.error);
+    process.stdout.write(
+      `${JSON.stringify({ error: queueBuildResult.error, kind: 'queue_validation_error' }, null, 2)}\n`,
+    );
+    return 2;
+  }
+  const explicitQueue = queueBuildResult.queue; // may be []
+
+  // Mid-sprint guard: refuse to overwrite an in-flight queue without
+  // --force. The user almost certainly wants to finish what's running
+  // before pivoting; a silent overwrite would lose state.
+  if (
+    explicitQueue.length > 0 &&
+    (persisted.current_story || (persisted.story_queue || []).length > 0) &&
+    !opts.force
+  ) {
+    const err =
+      `Sprint already in progress (current_story=${persisted.current_story || '<queue head>'}). ` +
+      `Pass --force to overwrite the queue, or finish the current story first.`;
+    log.error(err);
+    process.stdout.write(`${JSON.stringify({ error: err, kind: 'mid_sprint_queue_overwrite' }, null, 2)}\n`);
+    return 2;
+  }
+
   // Resume detection: if a prior session left a fingerprint, diff.
   const lastHalt = ledger.last({ projectRoot }, 'halt');
   if (lastHalt && lastHalt.fingerprint) {
@@ -633,6 +858,25 @@ function cmdStart(opts) {
     }
   }
 
+  // Persist the new queue BEFORE composing runtime state so the queue
+  // head is visible to composeRuntimeState's resolver.
+  if (explicitQueue.length > 0) {
+    persisted.story_queue = explicitQueue;
+    // --force overwrite also clears the prior story identity so the
+    // queue head is selected cleanly. Without this, persisted.current_
+    // story would short-circuit the queue read.
+    if (opts.force) {
+      persisted.current_story = null;
+      persisted.story_file_path = null;
+      persisted.current_epic = null;
+      persisted.current_bmad_step = null;
+    }
+    ledger.append(
+      { kind: 'story_queue_set', queue: explicitQueue, force: !!opts.force },
+      { projectRoot },
+    );
+  }
+
   // Fresh start or clean resume. `composeRuntimeState` applies the
   // profile-aware initial phase when persisted state is empty.
   const runtime = composeRuntimeState(persisted, profile, projectRoot);
@@ -849,7 +1093,7 @@ function cmdStatus(opts) {
 // ------------------------------------------------------------ main
 
 function main(argv) {
-  const { opts, positional } = parseArgs(argv, { booleanFlags: ['help'] });
+  const { opts, positional } = parseArgs(argv, { booleanFlags: ['help', 'force'] });
   if (opts.help) {
     help();
     return 0;

package/_Sprintpilot/lib/orchestrator/action-ledger.js

@@ -35,6 +35,10 @@ const VALID_KINDS = [
   'lock_acquired',
   'lock_released',
   'flush',
+  // Explicit story queue installed via `autopilot start --stories` /
+  // `--epic`. Logged once per start invocation so resume/audit can see
+  // why a queue head differs from sprint-status's natural order.
+  'story_queue_set',
 ];
 
 function isPlainObject(v) {

package/_Sprintpilot/lib/orchestrator/adapt.js

@@ -548,6 +548,23 @@ function advanceState(state, profile, newPhase, signal) {
     }
   }
 
+  // Story-completion boundary: STORY_DONE → EPIC_BOUNDARY_CHECK means
+  // the current story is committed and pushed. Pop the explicit story
+  // queue (if any) — its head was THIS story — and clear story_key so
+  // composeRuntimeState picks queue[1] (now queue[0]) on the next
+  // emission. Without this pop, composeRuntimeState would re-pick the
+  // just-completed story (via the signal-output propagation above) and
+  // loop. This block runs AFTER propagation so the clearing wins.
+  if (state.phase === STATES.STORY_DONE && newPhase === STATES.EPIC_BOUNDARY_CHECK) {
+    if (Array.isArray(state.story_queue) && state.story_queue.length > 0) {
+      next.story_queue = state.story_queue.slice(1);
+    }
+    next.story_key = null;
+    next.story_file_path = null;
+    next.current_epic = null;
+    next.ac_summary = null;
+  }
+
   return next;
 }
 

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

@@ -27,6 +27,11 @@ const CRITICAL_KEYS = new Set([
   'current_bmad_step',
   'in_worktree',
   'patch_commits',
+  // Explicit story queue populated by `autopilot start --stories <csv>`
+  // / `--epic <id>`. composeRuntimeState reads queue[0] as the next
+  // story_key; adapt.advanceState pops the head when a story completes.
+  // When empty, the orchestrator falls back to resolveNextStoryKey.
+  'story_queue',
 ]);
 
 // In-memory pending buffer. Process-scoped — flushed at story boundary or

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.1.4
+  version: 2.2.0
   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/skills/sprint-autopilot-on/SKILL.md

@@ -26,3 +26,87 @@ Follow **`./workflow.orchestrator.md`** verbatim. Flow control lives in
 
 `workflow.orchestrator.md` is the **sole authority** for the rest of the
 session.
+
+---
+
+## Natural-language entry: starting at a specific story or epic
+
+The user may invoke this skill with extra arguments specifying which
+story / epic to run, e.g.:
+
+- `/sprint-autopilot-on epic 4`
+- `/sprint-autopilot-on stories 3.1, 3.2, 4.5`
+- `/sprint-autopilot-on 4-8-realm-wide-matcher`
+- `/sprint-autopilot-on voice identity matcher`
+- `/sprint-autopilot-on starting from 4.5`
+
+Translate the natural-language directive into an explicit queue of
+canonical story keys, then call `autopilot start --stories <csv>` (or
+`--epic <id>`). The orchestrator validates the keys before running.
+
+**Resolution procedure** — do this BEFORE the first `autopilot next`:
+
+1. **Read sprint-status.yaml** at `_bmad-output/implementation-artifacts/sprint-status.yaml`.
+   If it's missing, tell the user to run BMad sprint-planning first and
+   stop — don't invoke `autopilot start`.
+
+2. **Parse the user's directive.** Match against these forms:
+
+   | User says | Resolve to |
+   |---|---|
+   | "epic 4", "epic-4", "all of epic 4" | `autopilot start --epic 4` |
+   | "stories 3.1, 3.2, 4.5", "3.1 3.2 4.5" | Match each `<epic>.<story>` to canonical keys (`3-1-*`, `3-2-*`, `4-5-*`) in sprint-status order; `autopilot start --stories <csv>` |
+   | "4-8-realm-wide-matcher" (already canonical) | `autopilot start --stories 4-8-realm-wide-matcher` |
+   | "voice identity", "matcher" (name fragment) | Search story slugs in sprint-status for fuzzy matches |
+   | "starting from 4.5" (everything from here) | Resolve `4.5` to canonical key, then queue it + every subsequent non-done story in sprint-status order: `autopilot start --stories <key1>,<key2>,...` |
+   | (no extra args) | Plain `autopilot start` — orchestrator picks the next pending story |
+
+3. **Ambiguity handling.** If a name fragment or number matches more
+   than one story, **do not pick arbitrarily**. List the candidates and
+   ask the user to disambiguate. Example:
+
+   > "voice identity" matches 3 stories:
+   > - 3-2-speaker-enrollment
+   > - 4-2b-voice-identity-matcher
+   > - 4-8-realm-wide-matcher-and-session-lock
+   > Which one(s) do you mean?
+
+   Do not invoke `autopilot start` with a guess.
+
+4. **Validation.** Every resolved key must exist in sprint-status.yaml
+   and not be `done`. The orchestrator double-checks this and errors
+   out otherwise — but verifying ahead of time gives the user clearer
+   feedback. If a key resolves to a `done` entry, mention that and ask
+   whether they meant something else.
+
+5. **Mid-sprint overwrite.** If `autopilot state` shows a sprint already
+   in progress (`current_story` is set or `story_queue` is non-empty)
+   AND the user is asking to start something different, the orchestrator
+   will refuse without `--force`. Confirm with the user before adding
+   `--force` — it discards the current story identity.
+
+6. **Continuation behavior.** Once the explicit queue exhausts, the
+   orchestrator falls back to its normal next-pending-story resolver
+   (so a user who says "epic 4" gets epic 4 done, then continues with
+   whatever comes next in sprint-status — including epic 5+). Tell the
+   user this if they ask.
+
+7. **Then proceed normally.** After `autopilot start ...` returns
+   successfully, follow `workflow.orchestrator.md` from `autopilot next`
+   onward.
+
+### Examples
+
+| Input | Resolved invocation |
+|---|---|
+| `/sprint-autopilot-on` | `autopilot start --project-root <root>` |
+| `/sprint-autopilot-on epic 4` | `autopilot start --epic 4 --project-root <root>` |
+| `/sprint-autopilot-on stories 3.1, 3.2` (after matching `3-1-game-engine`, `3-2-input-parser`) | `autopilot start --stories 3-1-game-engine,3-2-input-parser --project-root <root>` |
+| `/sprint-autopilot-on 4-8-realm-wide-matcher-and-session-lock` | `autopilot start --stories 4-8-realm-wide-matcher-and-session-lock --project-root <root>` |
+| `/sprint-autopilot-on starting from 4.5` (resolved + all-subsequent) | `autopilot start --stories 4-5-realm-config,4-8-realm-wide-matcher --project-root <root>` |
+
+Failure cases that should stop you (do NOT invoke autopilot):
+
+- `sprint-status.yaml` missing → ask the user to run sprint-planning.
+- Ambiguous match → list candidates, ask which.
+- Every resolved key is `done` → tell the user there's nothing to run.

package/package.json

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