@ikunin/sprintpilot 2.2.30 → 2.3.0

package/_Sprintpilot/lib/orchestrator/user-commands.js

@@ -19,6 +19,32 @@
 //     the stored alternative as the next action and clears the pending
 //     entry. Validation rejects this kind when no alternative is pending
 //     in state — see user-command-applier.js for the runtime check.
+//   trigger_retrospective { reason?: string }
+//     Force-routes the orchestrator into RETROSPECTIVE for the current
+//     epic regardless of `remaining_stories_in_epic`. Used when the user
+//     explicitly wants to close out an epic with deferred stories still
+//     in the queue (BMad has no formal `skipped`/`deferred` status for
+//     stories, so the orchestrator otherwise counts them as remaining
+//     and routes to next-story instead of retro).
+//
+// v2.3.0 — plan-aware mid-flight commands. These operate on
+// sprint-plan.yaml via the Phase 2 primitives. DAG-aware validation
+// lives in the applier (it needs the live plan + helper).
+//   reorder_queue { order: string[] }
+//     Rewrite priorities so the plan's pending stories match `order`.
+//     Validated against the DAG: every upstream of each story must be
+//     positioned BEFORE it OR plan-terminal. Inline edit — no phase
+//     change.
+//   add_to_sprint { story_keys: string[], position?: 'end'|'after:<key>'|<int>, issue_ids?: object }
+//     Add stories to plan.stories[]. Each key must exist in sprint-status,
+//     be non-terminal there, and not already in plan. Optional issue_ids
+//     map populates issue_id per added story.
+//   remove_from_sprint { story_keys: string[], mark_status?: 'skipped'|'deferred' }
+//     Mark stories with plan_status=skipped (default) or 'deferred'.
+//     Downstream-in-plan stories get a warning side effect.
+//   replan_sprint { reason?: string }
+//     Halt at next story_done boundary and emit invoke_skill for
+//     /sprintpilot-plan-sprint. The skill rebuilds the plan from scratch.
 //
 // Validation returns { ok: true, command } | { ok: false, errors: string[] }.
 
@@ -34,10 +60,17 @@ const COMMAND_KINDS = [
   'change_profile',
   'pause',
   'accept_alternative',
+  'trigger_retrospective',
+  // v2.3.0 — plan-aware mid-flight commands.
+  'reorder_queue',
+  'add_to_sprint',
+  'remove_from_sprint',
+  'replan_sprint',
 ];
 
 const STORY_KEY_RE = /^[A-Za-z0-9._-]{1,64}$/;
 const DECISION_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const VALID_REMOVE_STATUSES = ['skipped', 'deferred'];
 
 function isPlainObject(v) {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -73,11 +106,99 @@ function validateOne(cmd) {
     case 'abort_sprint':
     case 'force_continue':
     case 'pause':
-    case 'accept_alternative': {
+    case 'accept_alternative':
+    case 'trigger_retrospective': {
       if ('reason' in cmd && cmd.reason !== undefined && typeof cmd.reason !== 'string')
         errors.push(`${cmd.kind}.reason must be string when present`);
       break;
     }
+    case 'reorder_queue': {
+      if (!Array.isArray(cmd.order) || cmd.order.length === 0) {
+        errors.push('reorder_queue.order must be a non-empty array of story keys');
+        break;
+      }
+      const seen = new Set();
+      for (const k of cmd.order) {
+        if (!nonEmptyString(k) || !STORY_KEY_RE.test(k)) {
+          errors.push(`reorder_queue.order entry ${JSON.stringify(k)} must match [A-Za-z0-9._-]{1,64}`);
+          continue;
+        }
+        if (seen.has(k)) {
+          errors.push(`reorder_queue.order contains duplicate key ${JSON.stringify(k)}`);
+          continue;
+        }
+        seen.add(k);
+      }
+      break;
+    }
+    case 'add_to_sprint': {
+      if (!Array.isArray(cmd.story_keys) || cmd.story_keys.length === 0) {
+        errors.push('add_to_sprint.story_keys must be a non-empty array');
+        break;
+      }
+      for (const k of cmd.story_keys) {
+        if (!nonEmptyString(k) || !STORY_KEY_RE.test(k)) {
+          errors.push(
+            `add_to_sprint.story_keys entry ${JSON.stringify(k)} must match [A-Za-z0-9._-]{1,64}`,
+          );
+        }
+      }
+      if (cmd.position !== undefined && cmd.position !== null) {
+        const p = cmd.position;
+        const isEnd = p === 'end';
+        const isAfter = typeof p === 'string' && p.startsWith('after:') && p.length > 6;
+        const isInt = typeof p === 'number' && Number.isFinite(p);
+        if (!isEnd && !isAfter && !isInt) {
+          errors.push(
+            "add_to_sprint.position must be 'end', 'after:<key>', or an integer index",
+          );
+        }
+      }
+      if (cmd.issue_ids !== undefined && cmd.issue_ids !== null) {
+        if (!isPlainObject(cmd.issue_ids)) {
+          errors.push('add_to_sprint.issue_ids must be an object map { story_key: issue_id }');
+        } else {
+          for (const [k, v] of Object.entries(cmd.issue_ids)) {
+            if (!STORY_KEY_RE.test(k)) {
+              errors.push(
+                `add_to_sprint.issue_ids key ${JSON.stringify(k)} must match [A-Za-z0-9._-]{1,64}`,
+              );
+            }
+            if (typeof v !== 'string' && v !== null) {
+              errors.push(`add_to_sprint.issue_ids[${k}] must be a string or null`);
+            }
+          }
+        }
+      }
+      break;
+    }
+    case 'remove_from_sprint': {
+      if (!Array.isArray(cmd.story_keys) || cmd.story_keys.length === 0) {
+        errors.push('remove_from_sprint.story_keys must be a non-empty array');
+        break;
+      }
+      for (const k of cmd.story_keys) {
+        if (!nonEmptyString(k) || !STORY_KEY_RE.test(k)) {
+          errors.push(
+            `remove_from_sprint.story_keys entry ${JSON.stringify(k)} must match [A-Za-z0-9._-]{1,64}`,
+          );
+        }
+      }
+      if (cmd.mark_status !== undefined && cmd.mark_status !== null) {
+        if (!VALID_REMOVE_STATUSES.includes(cmd.mark_status)) {
+          errors.push(
+            `remove_from_sprint.mark_status must be one of ${VALID_REMOVE_STATUSES.join(', ')}`,
+          );
+        }
+      }
+      break;
+    }
+    case 'replan_sprint': {
+      if ('reason' in cmd && cmd.reason !== undefined && typeof cmd.reason !== 'string') {
+        errors.push('replan_sprint.reason must be string when present');
+      }
+      break;
+    }
     case 'override_decision': {
       if (!nonEmptyString(cmd.decision_id)) errors.push('override_decision.decision_id required');
       else if (!DECISION_ID_RE.test(cmd.decision_id))
@@ -118,6 +239,8 @@ function validate(input) {
 module.exports = {
   COMMAND_KINDS,
   VALID_PROFILE_NAMES,
+  VALID_REMOVE_STATUSES,
+  STORY_KEY_RE,
   validate,
   validateOne,
 };

package/_Sprintpilot/lib/orchestrator/verify.js

@@ -188,12 +188,11 @@ function runPostGreenGates(ctx) {
   }
   const cp = require('node:child_process');
   const args = [scriptAbs, '--json', '--project-root', ctx.projectRoot];
-  // Forward output_limit (v2.2.28). Pre-2.2.28 the typed-profile field
-  // existed but lint-changed.js used its hardcoded default of 100.
+  // Forward output_limit so lint-changed.js honors git.lint.output_limit.
   if (typeof ctx.profile.lint_output_limit === 'number' && ctx.profile.lint_output_limit > 0) {
     args.push('--output-limit', String(ctx.profile.lint_output_limit));
   }
-  // Forward per-language linter map (v2.2.28). Lets users reorder or
+  // Forward the per-language linter map. Users reorder priorities or
   // disable linters via git.lint.linters.{language}: [list].
   if (ctx.profile.lint_linters && typeof ctx.profile.lint_linters === 'object') {
     try {
@@ -459,10 +458,8 @@ function verifyDevGreen(state, out, ctx) {
   }
   // Post-GREEN gates: lint-changed + lint-test-pitfalls + ci-parity scan.
   // Composed pipeline lives in scripts/post-green-gates.js. Only fires
-  // when profile.lint_enabled === true. Blocking vs non-blocking
-  // governed by profile.lint_blocking. Pre-2.2.24 the script existed
-  // and was documented as "called by the orchestrator after GREEN
-  // verify" but nothing actually invoked it.
+  // when profile.lint_enabled === true. Blocking vs non-blocking is
+  // governed by profile.lint_blocking.
   const lintResult = runPostGreenGates(ctx);
   if (lintResult) {
     if (lintResult.failed && (ctx.profile && ctx.profile.lint_blocking)) {
@@ -476,17 +473,13 @@ function verifyDevGreen(state, out, ctx) {
 
 function verifyCodeReview(state, out, ctx) {
   const issues = [];
-  // bmad-code-review (.claude/skills/bmad-code-review/steps/step-04-present.md)
-  // writes findings as a "### Review Findings" subsection INSIDE the story
-  // file's Tasks/Subtasks block — NOT a separate _bmad-output/reviews/<key>.md.
-  // The pre-2.2.17 check for that file rejected every real run because the
-  // skill never creates one (recurring user pain: "review artifact missing:
-  // <path>" halts).
-  //
-  // Accept any of:
+  // bmad-code-review writes findings as a "### Review Findings"
+  // subsection inside the story file's Tasks/Subtasks block (see
+  // .claude/skills/bmad-code-review/steps/step-04-present.md). Older
+  // repo layouts also use a separate review file. Accept any of:
   //   - story file contains a `### Review Findings` section
-  //   - legacy `_bmad-output/reviews/<key>.md` exists (older repos)
-  //   - legacy `_bmad-output/implementation-artifacts/code-review-<key>.md` exists
+  //   - `_bmad-output/reviews/<key>.md` exists
+  //   - `_bmad-output/implementation-artifacts/code-review-<key>.md` exists
   // Reject only when NONE of the above exist AND the LLM didn't supply
   // findings[] inline.
   const storyKey = state.story_key || 'unknown';

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.2.30
+  version: 2.3.0
   description: Sprintpilot — autopilot and multi-agent addon for BMad Method (git workflow, parallel agents, autonomous story execution)
   bmad_compatibility: ">=6.2.0"
   modules:
@@ -24,3 +24,6 @@ addon:
     - sprintpilot-migrate
     - sprintpilot-research
     - sprintpilot-party-mode
+    - sprintpilot-plan-sprint
+    - sprintpilot-sprint-progress
+    - sprintpilot-dependency-graph

package/_Sprintpilot/modules/autopilot/profiles/_base.yaml

@@ -18,10 +18,24 @@ autopilot:
   coalesce_state_writes: true      # M3, PR 6 — batch non-critical writes, flush at story boundary
   conditional_boot_work: true      # M4, PR 7 — skip health-check + branch reconciliation on a clean repo
   cache_shared_reads: true         # M5, PR 8 — memoize sprint-status / git-status / decision-log reads per loop iteration
-  # 2.0.2 — autopilot session infers inter-story DAG once after bmad-sprint-planning
-  # and writes _Sprintpilot/sprints/dependencies.yaml. Hand-authored sidecars
-  # (no AUTO-INFERRED marker) are detected and respected.
-  auto_infer_dependencies: true
+  # 2.0.2 — original dependency-inference knob. Pre-v2.3.0 this triggered
+  # an LLM-driven inference pass once after bmad-sprint-planning and wrote
+  # `_Sprintpilot/sprints/dependencies.yaml`. v2.3.0 replaces that flow:
+  #   - The plan now lives at `_bmad-output/implementation-artifacts/sprint-plan.yaml`.
+  #   - Inference is opt-in via /sprintpilot-plan-sprint, NOT automatic.
+  #   - Greenfield runs (no plan, no --stories/--epic) execute stories in
+  #     sprint-status order — same as today's resolveNextStoryKey path.
+  # Default flipped to false; users who relied on the old behavior should
+  # set `autopilot.auto_plan_on_start: true` (see below).
+  auto_infer_dependencies: false
+
+  # v2.3.0 — when true, cmdStart emits an `invoke_skill` action for
+  # /sprintpilot-plan-sprint on first run if no sprint-plan.yaml exists.
+  # Default `false`: missing plan → fall back to sprint-status order
+  # (existing behavior). Once a plan exists, staleness is detected and
+  # re-derive runs automatically regardless of this knob — flipping back
+  # to false is a one-shot opt-out for net-new projects only.
+  auto_plan_on_start: false
 
 git:
   granularity: story               # story | epic

package/_Sprintpilot/modules/git/config.yaml

@@ -65,13 +65,18 @@ git:
     story-title: "from story file title, fallback to story-key"
     patch-title: "from review finding title, fallback to 'code review fix'"
 
-  # Linting
+  # Linting — runs after dev_green verify passes via
+  # scripts/post-green-gates.js (lint-changed + lint-test-pitfalls +
+  # ci-parity scan).
   lint:
-    enabled: true
-    blocking: false # true = lint errors halt the autopilot; false = warn only
-    output_limit: 100 # max lines of lint output injected into context
-    # Linter preference per language — first found wins.
-    # Override to force a specific tool (e.g., set typescript: [biome] to skip eslint).
+    enabled: true # gate runs only when true
+    blocking: false # true = lint errors reject verify (LLM fix-loops); false = recorded but non-gating
+    output_limit: 100 # max lines of lint output injected back into context
+    # Per-language linter preference, first-installed wins. Empty list
+    # disables linting for that language. `javascript` and `typescript`
+    # merge into a single js-ts bucket (both share eslint/biome tooling).
+    # To add a new language, add an entry here AND a matching resolver
+    # block in scripts/lint-changed.js.
     linters:
       python: [ruff, flake8, pylint]
       javascript: [eslint, biome]
@@ -87,7 +92,6 @@ git:
       plsql: [sqlfluff]
       kotlin: [ktlint, detekt]
       php: [phpstan, phpcs]
-      # To add a new language: add an entry here and a matching block in scripts/lint-changed.js
 
   # Push & PR
   push:
@@ -103,9 +107,11 @@ git:
     cleanup_on_merge: true # false = keep worktrees after epic completion for inspection
     health_check_on_boot: true # check for orphaned worktrees from crashed sessions
 
-  # Lock file (.autopilot.lock — prevents concurrent autopilot sessions)
+  # Lock file (.autopilot.lock — prevents concurrent autopilot sessions
+  # on the same project). Acquired by `autopilot start`; released by
+  # `/sprint-autopilot-off`.
   lock:
-    stale_timeout_minutes: 30 # auto-remove locks older than this
+    stale_timeout_minutes: 30 # auto-take-over locks older than this (0 disables)
 
   # Platform detection
   platform:

package/_Sprintpilot/modules/ma/config.yaml

@@ -1,30 +1,32 @@
 # Multi-Agent Configuration
 #
-# Top-level key MUST be `ma:` — resolve-profile.js merges this under the
+# Top-level key MUST be `ma:`. resolve-profile.js merges this under the
 # `ma` namespace, and profile-rules.js reads `ma.parallel_stories` /
-# `ma.max_parallel_stories`. The legacy `multi_agent:` wrapper used in
-# pre-2.2.16 versions was silently ignored (deep-merge produced
-# `resolved.ma.multi_agent.*` instead of `resolved.ma.*`).
+# `ma.max_parallel_stories`.
 
 ma:
   enabled: true
   max_parallel_review_layers: 3 # Always 3: blind, edge-case, acceptance
   max_parallel_research: 3 # Max concurrent research agents per batch
   max_parallel_analysis: 5 # Max concurrent codebase analysis agents
-  # session_story_limit NOT duplicated here — uses autopilot's single authoritative limit
+  # session_story_limit lives under autopilot.* — single source of truth.
 
-  # PR 11: intra-epic parallel story execution.
-  #   parallel_stories: true enables dispatch-layer.js on Claude Code;
-  #     other hosts silently fall back to sequential (per agent-adapter.js
-  #     detection — confidence high + supports_parallel true).
-  #   max_parallel_stories: cap on concurrent sub-agents per layer.
-  #   min_epic_duration_for_parallel_sec: skip parallelism for epics
-  #     whose estimated wall-clock is below this threshold (saves
-  #     dispatch overhead).
-  #   max_consecutive_conflicts: disable parallelism for the rest of the
-  #     session once N consecutive merge conflicts occur.
-  #   effective_parallel_floor: never drop below this mid-session even
-  #     after failure-driven concurrency reduction.
+  # Intra-epic parallel story execution.
+  #
+  # parallel_stories: true enables the dispatch-layer.js building blocks
+  # (planBatch, resolve-dag.js, merge-shards.js, agent-adapter.js). The
+  # state machine emits stories one at a time; the autopilot logs a
+  # clear notice at session start when this flag is set so behavior is
+  # unambiguous. Intra-epic parallel emission is planned for a future
+  # minor release.
+  #
+  # max_parallel_stories: cap on concurrent sub-agents per layer.
+  # min_epic_duration_for_parallel_sec: skip parallelism for epics whose
+  #   estimated wall-clock is below this threshold (saves dispatch overhead).
+  # max_consecutive_conflicts: disable parallelism for the rest of the
+  #   session once N consecutive merge conflicts occur.
+  # effective_parallel_floor: never drop below this mid-session even
+  #   after failure-driven concurrency reduction.
   parallel_stories: false
   max_parallel_stories: 2
   min_epic_duration_for_parallel_sec: 300
@@ -32,25 +34,25 @@ ma:
   max_consecutive_conflicts: 2
   effective_parallel_floor: 1
 
-  # EXPERIMENTAL: enable parallel_stories dispatch on Gemini CLI.
+  # Experimental: parallel_stories dispatch on Gemini CLI.
   #
   # Gemini CLI has a subagent primitive (invoke_subagent) but its
-  # worktree-scoped variant is not yet shipped upstream (tracker:
-  # github.com/google-gemini/gemini-cli#22967) and real-world parallelism
+  # worktree-scoped variant is tracked upstream
+  # (github.com/google-gemini/gemini-cli#22967). Real-world parallelism
   # reports serialization + quota throttling. Sprintpilot detects Gemini
   # CLI via GEMINI_CLI=1 (env, HIGH confidence) or parent process `gemini`
-  # (MEDIUM), but supports_parallel stays false by default.
+  # (MEDIUM); supports_parallel stays false by default.
   #
-  # Flip to true PER PROJECT once upstream worktree support lands (or to
-  # experiment at your own risk). Workflow logs an "experimental parallel"
-  # warning once per session when this is true AND host=gemini-cli.
+  # Flip to true PER PROJECT to opt into the experimental path. The
+  # workflow logs an "experimental parallel" warning once per session
+  # when this is true AND host=gemini-cli.
   experimental_parallel_on_gemini: false
 
-  # PR 12 — cross-epic parallelism (EXPERIMENTAL).
-  # Off by default on ALL profiles including large. Enabling requires:
+  # Cross-epic parallelism (experimental). Off by default on every
+  # profile, including large. Enabling requires:
   #   1. Both epics carry `independent: true` in dependencies.yaml.
   #   2. preflight-merge.js reports no conflicts between them.
-  #   3. max_parallel_epics is hardcoded at 2 — no tuning knob.
+  #   3. max_parallel_epics is fixed at 2 — no tuning knob.
   # A single cross-epic merge conflict in a session disables parallel_epics
   # for the rest of the session.
   parallel_epics: false

package/_Sprintpilot/scripts/dispatch-layer.js

@@ -79,10 +79,9 @@ function planLayer({ keys, maxParallel, projectRoot, branchPrefix, baseBranch })
   }
   const effectiveParallel = Math.max(1, Math.min(maxParallel | 0, dedupedKeys.length));
   // CAP: only dispatch the first `effectiveParallel` stories. The
-  // remaining keys are deferred — the autopilot loop will pick them up
-  // in the next iteration after this batch completes. Pre-2.0.8 the
-  // script created worktrees for ALL keys regardless of the cap, then
-  // the workflow spawned N agents anyway, fully ignoring --max-parallel.
+  // remaining keys are deferred — the autopilot loop picks them up
+  // in the next iteration after this batch completes. Honors
+  // --max-parallel as the upper bound on concurrent worktree creation.
   const dispatchedKeys = dedupedKeys.slice(0, effectiveParallel);
   const deferredKeys = dedupedKeys.slice(effectiveParallel);
   const worktrees = dispatchedKeys.map((key) => ({
@@ -112,10 +111,10 @@ function writePlan(projectRoot, plan) {
 }
 
 // Match git's "branch already exists" diagnostic. We retry without -b
-// only when the FIRST attempt failed for this specific reason —
-// pre-2.0.8 the bare retry fired on ANY first-attempt failure and
-// silently checked out whatever stale branch happened to exist at the
-// requested name (e.g. last week's commits from an abandoned story).
+// ONLY when the first attempt failed for this specific reason. A bare
+// retry on any other failure would silently check out whatever stale
+// branch happened to exist at the requested name (e.g. last week's
+// commits from an abandoned story).
 const BRANCH_EXISTS_RE = /a branch named .* already exists/i;
 
 function createWorktree({ projectRoot, worktree, branch, baseBranch }) {
@@ -147,11 +146,9 @@ function createWorktree({ projectRoot, worktree, branch, baseBranch }) {
   };
 }
 
-// After a worktree is created, disable gc.auto on it. The sequential
-// path in workflow.md does this at line 738; pre-2.0.8 the parallel
-// path skipped it, so concurrent sub-agents in heavy repos could
-// trigger gc on each worktree mid-dispatch. Best-effort — never block
-// dispatch on a config write.
+// After a worktree is created, disable gc.auto on it so concurrent
+// sub-agents in heavy repos don't trigger gc on each worktree mid-
+// dispatch. Best-effort — never block dispatch on a config write.
 function disableGcAutoOnWorktree(worktree) {
   spawnSync('git', ['-C', worktree, 'config', '--local', 'gc.auto', '0'], {
     encoding: 'utf8',
@@ -197,8 +194,8 @@ function dispatch({ keys, maxParallel, projectRoot, branchPrefix, baseBranch, dr
     return results;
   }
   // Real dispatch. Track successful creates so we can roll them back if
-  // a later create fails — leaving an orphan worktree + a plan file
-  // claiming it succeeded was the v2.0.7 partial-failure bug.
+  // a later create fails — partial success would leave orphan worktrees
+  // alongside a plan file that claims everything succeeded.
   const succeeded = [];
   let failureIndex = -1;
   for (let i = 0; i < plan.stories.length; i++) {