@ikunin/sprintpilot 1.0.5 → 2.0.5

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

@@ -10,17 +10,33 @@ You do NOT hardcode the workflow sequence. After each completed skill, read its
 
 ### Shell portability
 
-The executing shell may be bash, zsh, PowerShell, or cmd — translate bash idioms as needed:
+The executing shell may be bash, zsh, Git Bash (Claude Code's default on Windows), PowerShell, or cmd. The workflow itself uses dedicated Node helpers for the operations that were most fragile across shells — the few remaining shell idioms below are the ones that work uniformly under bash, zsh, Git Bash, PowerShell, and cmd:
 
-| Bash | PowerShell |
+| Idiom | Where used | Portable across |
+|---|---|---|
+| `2>&1` (merge stderr → stdout) | `git ... 2>&1` | bash, zsh, Git Bash, PowerShell, cmd |
+| `\|\|` (run-on-failure chaining) | `git switch X \|\| git checkout X` | bash, zsh, Git Bash, PowerShell ≥7, cmd |
+
+Idioms that were **previously inlined and have been replaced with Node helpers** (do NOT regress them):
+
+| Old idiom | Replaced by |
 |---|---|
-| `A && B` | `A; if ($LASTEXITCODE -eq 0) { B }` |
-| `A \|\| true` | `A; $LASTEXITCODE = 0` |
-| `2>/dev/null` | `2>$null` |
-| `rm -rf <dir>` | `Remove-Item -Recurse -Force <dir>` |
-| `if [ -f X ]; then ... fi` | `if (Test-Path -PathType Leaf X) { ... }` |
+| `git config --get K 2>/dev/null \|\| echo unset` | `git-portable.js config-get K --default unset` |
+| `git worktree list --porcelain \| grep -c '^worktree '` | `git-portable.js count-worktrees` |
+| `VAR=$(git ... rev-parse --git-common-dir)` | `git-portable.js common-dir` (output captured into `{{git_common}}`) |
+| `git add A B C 2>/dev/null \|\| true` | `git-portable.js safe-add A B C` |
 
-For cross-platform file ops prefer the Node helpers under `_Sprintpilot/scripts/`, or inline: `node -e "require('fs').rmSync('<path>', {recursive: true, force: true})"`. When a step chains commands with `&&` and you cannot express it in one line, run them separately and STOP on any failure.
+If you find yourself writing a new pipe (`\|`), POSIX redirect (`2>/dev/null`), shell substitution (`$(...)`), shell variable assignment (`VAR=value`), or POSIX-only tool (`grep`, `sed`, `awk`, `xargs`, `find -exec`), reach for a Node helper instead — either an existing script under `_Sprintpilot/scripts/`, a new helper added to `git-portable.js`, or an inline `node -e "..."` snippet (which is portable across every host).
+
+Common cross-platform inline snippets:
+
+| Need | Inline Node snippet |
+|---|---|
+| Recursive remove | `node -e "require('fs').rmSync('<path>', {recursive: true, force: true})"` |
+| File-exists check (exit 0/1) | `node -e "process.exit(require('fs').existsSync('<path>')?0:1)"` |
+| Read JSON, extract field | `node -e "console.log(JSON.parse(require('fs').readFileSync('<file>','utf8')).<field>)"` |
+
+When a step chains commands with `&&` and the chain cannot be expressed via a Node helper, run them separately and STOP on any failure.
 
 ---
 
@@ -38,6 +54,7 @@ Long autopilot runs will fill the context window. To prevent state loss:
 - **All state lives in files, never only in memory.** After every step, write progress to `{state_file}`.
 - **Story boundary = session boundary.** Never split a single story across sessions. Always finish the current story fully (dev → review → patches → done) before ending a session.
 - **Proactive session handoff.** After `{{session_story_limit}}` stories have been **fully implemented** in one session (default: 3) — meaning their complete cycle is finished (dev-story GREEN + code-review + patches + artifacts committed) — write state and tell user to start a new session with `/sprint-autopilot-on`. Configurable via `autopilot.session_story_limit` in `modules/autopilot/config.yaml`. Creating a story file does NOT count toward the limit — only finishing step 7 does. Do not wait for compaction to happen.
+- **Sprint-complete checkpoint (MANDATORY).** The moment step 2 detects `sprint_is_complete = true`, the current session NEVER runs step 10 itself. It writes `current_bmad_step = "sprint-finalize-pending"` to `{state_file}`, releases the lock, emits a handoff report, and STOPS. The next `/sprint-autopilot-on` invocation boots in a fresh context, sees the pending state, and runs step 10. This is non-negotiable because step 10 is the context-rot failure zone — its CRITICAL deterministic script calls were reliably skipped when packed into the tail of a long session.
 - **On startup: check for saved state first.** If `{state_file}` exists, this is a RESUME — read it and skip to the saved story/step. Never re-do completed work.
 
 ### Menu and interaction handling — CRITICAL
@@ -119,6 +136,17 @@ Resolve:
 
 **`{state_file}` schema** (referenced as `STATE_FIELDS` below): `last_updated`, `current_story`, `current_bmad_step`, `completed_skill`, `next_skill`, `session_stories_done`, `stories_remaining`, `git_enabled`, `platform`, `in_worktree`, `pr_base`. Always update `last_updated` on every write.
 
+**PR 6 state-write policy (`autopilot.coalesce_state_writes`):**
+
+When the resolved profile sets `autopilot.coalesce_state_writes: true` (nano/small/medium/large by default; `legacy` false), state writes route through `state-shard.js` using a `sprint`-keyed shard as the authoritative state for sprint-level fields, and per-story shards for story-scoped fields. Policy:
+
+- **Critical keys** (`current_story`, `current_bmad_step`, `in_worktree`, `patch_commits`) always go to shard via `state-shard.js batch`, which auto-flushes and writes straight through because the script recognizes them as crash-recovery keys.
+- **Non-critical fields** (test counts, file lists, next_skill, session_stories_done, stories_remaining, etc.) go to `state-shard.js batch`, accumulating in the pending buffer. Flushed at each story boundary (step 7) and session checkpoint (step 9).
+- **Merged authoritative state** (`autopilot-state.yaml`) is rebuilt via `merge-shards.js` at story boundary + session checkpoint + sprint complete.
+- **Rollback** (`coalesce_state_writes: false`): every `Update {state_file}` action writes directly to `autopilot-state.yaml` via the existing STATE_FIELDS shape — no shard indirection. This is the v1.0.5 path byte-for-byte.
+
+When the flag is `false`, the direct-write instructions below are authoritative. When `true`, substitute each `Update {state_file} with STATE_FIELDS: <changes>` with a `state-shard.js batch --story sprint --json <changes>` call, followed by a `merge-shards.js --project-root "{{project_root}}"` at the story boundary / checkpoint. The merged `autopilot-state.yaml` remains the single source of truth for resume-after-crash.
+
 ### Git integration bootstrap
 
 <action>Check if `{project-root}/_Sprintpilot/manifest.yaml` exists</action>
@@ -134,18 +162,57 @@ Resolve:
   - `{{create_pr}}` from `git.push.create_pr` (true)
   - `{{pr_template}}` from `git.push.pr_template` ("modules/git/templates/pr-body.md")
   - `{{cleanup_on_merge}}` from `git.worktree.cleanup_on_merge` (true)
+  - `{{granularity}}` from `git.granularity` ("story"). Resolver override wins below.
+  - `{{worktree_enabled}}` from `git.worktree.enabled` (true). Resolver override wins below.
+  - `{{squash_on_merge}}` from `git.squash_on_merge` (false). Resolver override wins below.
+  </action>
+  <action>**Apply profile overrides** via resolver — run each and set only if the resolver returns a value:
+  - `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get git.granularity` → override `{{granularity}}`.
+  - `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get git.worktree.enabled` → override `{{worktree_enabled}}`.
+  - `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get git.squash_on_merge` → override `{{squash_on_merge}}`.
   </action>
   <action>Read `{project-root}/_Sprintpilot/modules/autopilot/config.yaml` (if present) and set:
   - `{{session_story_limit}}` from `autopilot.session_story_limit` (default: 3). A value of 0 disables the limit (run until sprint complete).
   - `{{retrospective_mode}}` from `autopilot.retrospective_mode` (default: `auto`). Valid values: `auto` | `stop` | `skip`. Any unknown value falls back to `auto`.
   If the file or either key is missing, fall back to the defaults above.
   </action>
+  <action>**Resolve profile-driven flow** — run:
+  `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get autopilot.implementation_flow`
+  Output: `full` or `quick`. Set `{{implementation_flow}}` = output. Default to `full` if the call fails.
+  Run: `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get autopilot.session_story_limit` → override `{{session_story_limit}}` if the resolver produces a different value than config.yaml (profile overrides config silence). Same pattern for `autopilot.retrospective_mode`.
+  </action>
+  <action>**Resolve coalesce flag** — run:
+  `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get autopilot.coalesce_state_writes` → `{{coalesce_state_writes}}`. Default `false` on failure.
+  </action>
+  <!-- PR 11: detect the running host and resolve parallel-dispatch config. -->
+  <action>**Detect host agent** — run:
+  `node {{project_root}}/_Sprintpilot/scripts/agent-adapter.js detect --project-root "{{project_root}}"`
+  Parse the JSON output: set `{{host_agent}}` = host, `{{host_supports_parallel}}` = supports_parallel, `{{host_confidence}}` = confidence.
+  </action>
+  <action>**Resolve parallelism flags** via the profile resolver:
+  - `{{parallel_stories}}` from `ma.parallel_stories` (default false).
+  - `{{max_parallel_stories}}` from `ma.max_parallel_stories` (default 2).
+  - `{{experimental_parallel_on_gemini}}` from `ma.experimental_parallel_on_gemini` (default false).
+  </action>
+  <!-- Gemini CLI opt-in: when the user explicitly sets
+       experimental_parallel_on_gemini=true AND the detected host is
+       gemini-cli at HIGH confidence, promote supports_parallel=true
+       with a one-line warning. Worktree-scoped subagents aren't shipped
+       upstream yet, so this is user-opt-in-per-project. -->
+  <check if="{{experimental_parallel_on_gemini}} is true AND {{host_agent}} is gemini-cli AND {{host_confidence}} is high">
+    <action>Set `{{host_supports_parallel}}` = true</action>
+    <action>Log once: "EXPERIMENTAL: parallel_stories enabled on Gemini CLI via ma.experimental_parallel_on_gemini=true. Worktree-scoped subagents are not yet shipped upstream (gemini-cli#22967); expect possible serialization or quota throttling."</action>
+  </check>
+  <action>Silently coerce `{{parallel_stories}}` to false when `{{host_supports_parallel}}` is false OR `{{host_confidence}}` is not `high`. Log once:
+  `parallel_stories requested but host '{{host_agent}}' does not declare parallel support (confidence={{host_confidence}}); running sequentially`.
+  </action>
 </check>
 
 <check if="manifest does NOT exist">
   <action>Set `{{git_enabled}}` = false</action>
   <action>Set `{{session_story_limit}}` = 3</action>
   <action>Set `{{retrospective_mode}}` = `auto`</action>
+  <action>Set `{{implementation_flow}}` = `full`</action>
   <action>Log: "No _Sprintpilot/manifest.yaml found — running stock autopilot (no git)"</action>
 </check>
 
@@ -174,6 +241,11 @@ Resolve:
     <action>Set `{{platform}}` = "git_only"</action>
   </check>
 
+  <!-- PR 10: disable gc.auto on the main repo so git's auto-GC doesn't
+       race with concurrent worktree operations during the sprint. Save
+       the prior value so we can restore it at sprint complete (step 10). -->
+  <action>**Save + disable main-repo gc.auto**: set `{{original_gc_auto_main}}` = output of `node {{project_root}}/_Sprintpilot/scripts/git-portable.js config-get gc.auto --default unset --project-root "{{project_root}}"`, then `git -C {{project_root}} config --local gc.auto 0`.</action>
+
   <action>**Lock file** — run: `node {{project_root}}/_Sprintpilot/scripts/lock.js acquire`
   Output will be one of:
   - `ACQUIRED:<session-id>` → proceed
@@ -191,6 +263,26 @@ Resolve:
   Log: "Platform detected: {{platform}}"
   </action>
 
+  <!-- PR 7 CONDITIONAL BOOT WORK: a clean repo — main worktree only, zero
+       in-progress stories — can skip the slow health-check + branch
+       reconciliation below. Gate honored by non-legacy, non-large profiles
+       (large keeps full reconciliation for compliance/uptime reasons). -->
+  <action>Read `autopilot.conditional_boot_work` from the resolver:
+  `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get autopilot.conditional_boot_work` → `{{conditional_boot_work}}`. Default to `false` on failure.
+  </action>
+  <action>Count worktrees (cross-platform; replaces a `... | grep -c` pipe that needed POSIX shell):
+  `node {{project_root}}/_Sprintpilot/scripts/git-portable.js count-worktrees --project-root "{{project_root}}"` → `{{worktree_count}}`. The script fails open to 2 internally if git itself errors, matching the previous "fail-open to force full path" semantic.
+  </action>
+  <action>Count in-progress stories: read `{status_file}` and count stories whose status is NOT in {`done`, `backlog`}. Set `{{in_progress_count}}`. Fail-open to 1 (force full path) if the file is unreadable.</action>
+
+  <check if="{{conditional_boot_work}} is true AND {{worktree_count}} is 1 AND {{in_progress_count}} is 0">
+    <action>Log: "Boot fast-path (PR 7): clean repo — skipping health-check + branch reconciliation"</action>
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js once --story "sprint" --phase "boot.fast-path" --meta "{\"reason\":\"clean-repo\"}" --project-root "{{project_root}}"` — ignore failures.</action>
+    <action>Set `{{git_enabled}}` = true, `{{platform}}` = detected value</action>
+  </check>
+
+  <check if="NOT ({{conditional_boot_work}} is true AND {{worktree_count}} is 1 AND {{in_progress_count}} is 0)">
+
   <action>**Worktree health check** — run:
   `node {{project_root}}/_Sprintpilot/scripts/health-check.js --base-branch {{base_branch}} --status-file {{status_file}}`
   Output classifies each worktree as CLEAN_DONE, COMMITTED, STALE, DIRTY, or ORPHAN.
@@ -242,6 +334,8 @@ Resolve:
   </action>
 
   <action>Set `{{git_enabled}}` = true, `{{platform}}` = detected value</action>
+
+  </check><!-- end PR 7 conditional boot work (non-fast-path branch) -->
 </check>
 
 ---
@@ -256,7 +350,7 @@ Resolve:
   <action>Read `{state_file}` fully</action>
   <action>Extract saved state:
     - `{{current_story}}` — story in progress when last session ended
-    - `{{current_bmad_step}}` — BMAD step that was active (2–7)
+    - `{{current_bmad_step}}` — BMAD step that was active (2–7), or the reserved value `sprint-finalize-pending` meaning "the prior session detected sprint-complete and checkpointed; this session's only job is step 10"
     - `{{completed_skill}}` — last skill that ran
     - `{{next_skill}}` — next skill recommended at save time
     - `{{session_stories_done}}` = 0 (reset counter for new session)
@@ -294,6 +388,32 @@ Resolve:
     - Update `{state_file}` with reconciled values
   </action>
 
+  <!-- Already-completed short-circuit. If the prior session wrote
+       sprint-complete (CRITICAL 5/7) but crashed before the state file
+       delete (CRITICAL 7/7), this invocation would otherwise loop into
+       the finalize handoff forever. Detect it and exit cleanly. -->
+  <check if="{{current_bmad_step}} is sprint-complete">
+    <action>Delete `{state_file}` — clean up the stale terminal marker.</action>
+    <action>Report: "Sprint already complete. Nothing to do — run `bmad-sprint-planning` to plan the next sprint, then re-run `/sprint-autopilot-on`." Then STOP.</action>
+  </check>
+
+  <!-- Fresh-context finalize path. If the prior session exited with
+       current_bmad_step = "sprint-finalize-pending", this invocation's
+       ONLY job is to run step 10 with a clean window. Verify the
+       sprint is still genuinely complete before jumping; if a user
+       added new work in between, fall through to the normal loop. -->
+  <check if="{{current_bmad_step}} is sprint-finalize-pending">
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/list-remaining-stories.js --status-file "{status_file}" --format envelope` — parse stdout JSON.</action>
+    <check if="parsed .state is sprint-complete">
+      <action>Log: "Resuming for sprint finalization with fresh context (context-rot mitigation)."</action>
+      <goto step="10">Run finalization</goto>
+    </check>
+    <check if="parsed .state is NOT sprint-complete">
+      <action>Log: "sprint-finalize-pending flag was set but new work appeared since checkpoint. Clearing flag and resuming normal execution."</action>
+      <action>Update `{state_file}`: `current_bmad_step = null`.</action>
+    </check>
+  </check>
+
   <!-- Resume from a `retrospective_mode: stop` pause. -->
   <check if="{state_file}.paused_at is epic-complete-awaiting-retrospective">
     <action>Set `{{paused_epic_id}}` from `{state_file}.paused_epic_id`. Check if epic `{{paused_epic_id}}` is `done` in `{status_file}` OR an artifact exists at `{implementation_artifacts}/retrospectives/epic-{{paused_epic_id}}-*.md`.</action>
@@ -324,7 +444,14 @@ Resolve:
     - `{{session_stories_done}}` = 0
   </action>
   <action>Create master task: "Sprintpilot — Full Sprint Execution" → `in_progress`</action>
-  <action>Write initial `{state_file}` with STATE_FIELDS: `current_story = null`, `current_bmad_step = null`, `completed_skill = bmad-help`, `session_stories_done = 0`, `stories_remaining = [from sprint-status]`, `in_worktree = false`, `pr_base = {{base_branch}}`.</action>
+  <action>**Compute `{{stories_remaining}}`** deterministically — run:
+  `node {{project_root}}/_Sprintpilot/scripts/list-remaining-stories.js --status-file "{status_file}" --format envelope`
+  The helper always emits a well-formed JSON object on stdout, on every exit path:
+  `{"remaining":[...],"state":"pre-planning|sprint-in-progress|sprint-complete|parse-error"}`.
+  Parse stdout as JSON → set `{{stories_remaining}}` = `.remaining`.
+  Ignore the exit code: `.state` is authoritative and covers every case (missing file, parse error, or normal).
+  </action>
+  <action>Write initial `{state_file}` with STATE_FIELDS: `current_story = null`, `current_bmad_step = null`, `completed_skill = bmad-help`, `session_stories_done = 0`, `stories_remaining = {{stories_remaining}}`, `in_worktree = false`, `pr_base = {{base_branch}}`.</action>
   <action>Report to user:
   ```
   Sprintpilot ON
@@ -346,17 +473,89 @@ Resolve:
 
 <step n="2" goal="Main execution loop — route to correct handler">
 
-<check if="all stories in status_file are done">
-  <goto step="10">Sprint complete</goto>
+<!-- PR 12 CROSS-EPIC PARALLELISM (experimental, off by default on every
+     profile including `large`). All safety rails must pass:
+       1. ma.parallel_epics is true.
+       2. Host confidence is HIGH AND supports_parallel is true (same as
+          intra-epic gate in PR 11).
+       3. Two or more epics in dependencies.yaml declare `independent: true`.
+       4. preflight-merge.js reports NO conflicts between all pairs.
+       5. Session-scoped disable flag {{cross_epic_disabled_this_session}}
+          is false (flips true after any cross-epic merge conflict).
+     Only on the first iteration of the loop — subsequent iterations
+     don't re-preflight; they consume the cached safe_pairs list. -->
+<action>Resolve `{{parallel_epics}}` from `ma.parallel_epics` (default false) via the resolver.</action>
+<check if="{{parallel_epics}} is true AND {{host_supports_parallel}} is true AND {{host_confidence}} is high AND {{cross_epic_preflight_done}} is not true AND {{cross_epic_disabled_this_session}} is not true">
+  <action>Read `_Sprintpilot/sprints/dependencies.yaml` (if present). Extract every epic id where `epics.<id>.independent` is true. Set `{{independent_epic_ids}}` = comma-joined list of ids.</action>
+  <check if="{{independent_epic_ids}} has fewer than 2 ids">
+    <action>Log once: "cross-epic parallelism enabled but fewer than 2 epics declare `independent: true` in dependencies.yaml — running sequentially"</action>
+    <action>Set `{{cross_epic_preflight_done}}` = true, `{{cross_epic_safe_pairs}}` = []</action>
+  </check>
+  <check if="{{independent_epic_ids}} has 2 or more ids">
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/preflight-merge.js --epics "{{independent_epic_ids}}" --base "{{base_branch}}" --branch-prefix "{{branch_prefix}}" --project-root "{{project_root}}"`. Parse JSON — set `{{cross_epic_safe_pairs}}` = safe_pairs, `{{cross_epic_conflict_pairs}}` = conflict_pairs.</action>
+    <action>Log: "EXPERIMENTAL: parallel_epics preflight → safe={{cross_epic_safe_pairs.length}} conflict={{cross_epic_conflict_pairs.length}} checked=N"</action>
+    <action>Set `{{cross_epic_preflight_done}}` = true</action>
+  </check>
+</check>
+
+<!-- Authoritative "sprint complete" check. Read the status file EVERY
+     iteration via the coded helper (do not rely on stale state or LLM
+     re-parsing). The helper emits a JSON envelope on stdout on every
+     exit path, so there is no need to probe $? or stderr — .state is
+     authoritative. -->
+<action>**Recalculate `{{stories_remaining}}`** — run:
+`node {{project_root}}/_Sprintpilot/scripts/list-remaining-stories.js --status-file "{status_file}" --format envelope`
+Parse stdout as a single JSON object: `{"remaining":[...],"state":"..."}`.
+- `.state == "sprint-in-progress"` → `{{stories_remaining}}` = `.remaining`, `{{sprint_has_stories}}` = true, `{{sprint_is_complete}}` = false.
+- `.state == "sprint-complete"`    → `{{stories_remaining}}` = [],          `{{sprint_has_stories}}` = true, `{{sprint_is_complete}}` = true.
+- `.state == "pre-planning"`       → `{{stories_remaining}}` = [],          `{{sprint_has_stories}}` = false, `{{sprint_is_complete}}` = false.
+- `.state == "parse-error"`        → log warning; treat as pre-planning. NEVER declare sprint-complete on a parse failure.
+</action>
+<!-- Sprint-complete handoff. Never run step 10 in the same session that
+     first observed the sprint-complete condition — that session has
+     spent a long time in context and its tail is the context-rot zone.
+     Instead, mark the state as sprint-finalize-pending and stop; the
+     next /sprint-autopilot-on boot will route straight to step 10 (via
+     the step 1 gate) with a clean window. If we ALREADY are the
+     finalize session (current_bmad_step was sprint-finalize-pending on
+     entry), step 1 has already jumped to step 10 and we never reach
+     this check — so this gate is unambiguous. -->
+<check if="{{sprint_is_complete}} is true">
+  <action>Update `{state_file}` with STATE_FIELDS: `current_bmad_step = "sprint-finalize-pending"`, `current_story = null`, `next_skill = null`, `stories_remaining = []`, `session_stories_done = {{session_stories_done}}`.</action>
+  <action>Release autopilot lock (idempotent): `node {{project_root}}/_Sprintpilot/scripts/lock.js release` — ignore failures.</action>
+  <action>Report to user and STOP this session:
+  ```
+  Autopilot sprint-complete checkpoint
+
+  All stories are done. Pausing before finalization so step 10 runs
+  with a fresh context — this prevents late-session instruction decay
+  from skipping CRITICAL cleanup actions (commit artifacts, generate
+  docs, clean up worktrees, emit final report).
+
+  Completed {{session_stories_done}} stories this session.
+  State saved to: {state_file}
+
+  Run `/sprint-autopilot-on` once more to finalize.
+  ```
+  </action>
+  <action>HALT — do not continue the execution loop. The next invocation enters via step 1, sees `sprint-finalize-pending`, and jumps to step 10.</action>
+</check>
+<check if="{{sprint_has_stories}} is false">
+  <action>Log: "Sprint pre-planning: no stories in status file yet. Routing through bmad-help to the next planning skill (do NOT go to step 10)."</action>
 </check>
 
 <check if="{{next_skill}} is empty">
   <action>**Recover next_skill** — re-read `{status_file}`, find first story with status != "done"</action>
-  <check if="no undone stories found">
-    <goto step="10">Sprint complete</goto>
+  <check if="no undone stories found AND {{sprint_has_stories}} is true">
+    <!-- Fallback sprint-complete detection. Route through the same
+         finalize-pending handoff as the primary gate above — never
+         jump into step 10 from this long-running session. -->
+    <action>Update `{state_file}`: `current_bmad_step = "sprint-finalize-pending"`, `current_story = null`, `next_skill = null`, `stories_remaining = []`.</action>
+    <action>Release lock: `node {{project_root}}/_Sprintpilot/scripts/lock.js release` — ignore failures.</action>
+    <action>Report: "Sprint complete detected via fallback path. Pausing for fresh-context finalization — run /sprint-autopilot-on once more." Then HALT.</action>
   </check>
-  <action>Set `{{current_story}}` = first undone story from `{status_file}`</action>
-  <action>Invoke `bmad-help` — "Story {{current_story}} needs attention. What is the next required workflow step?"</action>
+  <action>If `{{sprint_has_stories}}` is true: set `{{current_story}}` = first undone story from `{status_file}`.</action>
+  <action>Invoke `bmad-help` — "Story {{current_story}} needs attention (or: sprint in planning phase — no stories yet). What is the next required workflow step?"</action>
   <action>Extract `{{next_skill}}` from bmad-help response</action>
 </check>
 
@@ -398,10 +597,83 @@ Resolve:
 
 <step n="3" goal="Prepare and execute the recommended skill">
 
+<!-- ──────────────────────────────────────────────────────────────────
+     PR 11 PARALLEL DISPATCH (gates):
+       - autopilot.parallel_stories: true (resolved at boot into
+         {{parallel_stories}})
+       - host_supports_parallel: true with high confidence (PR 11
+         agent-adapter.js — only Claude Code today)
+       - implementation_flow != quick (nano runs sequentially per epic)
+       - {{next_skill}} starts a fresh per-story flow (bmad-create-story
+         OR bmad-dev-story OR bmad-quick-dev) — never mid-story
+       - The current epic's DAG layer has width >= 2 (computed from
+         _Sprintpilot/sprints/dependencies.yaml via resolve-dag.js)
+
+     When all gates pass, the autopilot dispatches every story in the
+     current layer concurrently via the host's Agent tool — instead of
+     picking one story and running the full per-story flow sequentially.
+     This is the integration point that finally exercises the dispatcher
+     infrastructure built in PR 9 (resolve-dag) + PR 11 (dispatch-layer).
+     Without this block, parallel_stories=true had no behavioral effect.
+     ────────────────────────────────────────────────────────────────── -->
+<check if="{{parallel_stories}} is true AND {{host_supports_parallel}} is true AND {{implementation_flow}} is NOT quick AND ({{next_skill}} is bmad-create-story OR {{next_skill}} is bmad-dev-story OR {{next_skill}} is bmad-quick-dev)">
+  <action>**Compute current DAG layer.** Set `{{epic_id}}` = leading numeric segment of the FIRST undone story in `{status_file}`. Run:
+  `node {{project_root}}/_Sprintpilot/scripts/resolve-dag.js layers --epic "{{epic_id}}" --project-root "{{project_root}}"`
+  Parse stdout as a JSON array of arrays (each sub-array is one layer of story keys). Find the FIRST layer that contains at least one story whose status in `{status_file}` is NOT `done`. Filter that layer down to only the undone stories — set `{{active_layer}}` to the resulting list.</action>
+  <check if="{{active_layer}} length is 1">
+    <action>Single-story layer — no parallel benefit. Continue with normal sequential dispatch below (the standard step-3 flow picks the single story).</action>
+  </check>
+  <check if="{{active_layer}} length is 2 or more">
+    <action>**Parallel dispatch:** run:
+    `node {{project_root}}/_Sprintpilot/scripts/dispatch-layer.js --layer "{{active_layer | join(',')}}" --max-parallel "{{max_parallel_stories}}" --project-root "{{project_root}}" --branch-prefix "{{branch_prefix}}" --base-branch "{{base_branch}}"`
+    Parse stdout — captures the per-story worktree paths (`stories[*].worktree`) and the `effective_parallel` count.</action>
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story sprint --phase "dispatch.layer-{{epic_id}}" --project-root "{{project_root}}"` — ignore failures.</action>
+    <action>**Spawn N concurrent sub-agents — IMPORTANT: send a SINGLE message containing N parallel Agent tool calls (one per story).** Do NOT serialize. Each sub-agent runs the FULL per-story flow for its assigned story (bmad-create-story → bmad-check-implementation-readiness → bmad-dev-story → bmad-code-review → patches → mark done) inside its own worktree. The Agent tool calls run concurrently and the message reply contains all sub-agent results.
+
+    For each story key `K` in `{{active_layer}}`, build one Agent call with `subagent_type=general-purpose` and a self-contained prompt of the form:
+    ```
+    You are running a single story for the Sprintpilot autopilot.
+    - Project root: {{project_root}}
+    - Story key:    K
+    - Worktree:     {{project_root}}/.worktrees/K (cd into it for all work)
+    - Skill flow (full):  bmad-create-story → bmad-check-implementation-readiness → bmad-dev-story → bmad-code-review → apply patch findings → re-run tests → set status=done in {status_file}
+    - Skill flow (quick): bmad-quick-dev (single skill; nano profile)
+    Use {{implementation_flow}} = `{{implementation_flow}}` to pick which flow.
+    Track timing via `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story K --phase <phase> --project-root {{project_root}}` after each skill returns. The explicit `--project-root` is REQUIRED — without it the script falls back to cwd (the worktree), which orphans timing data. With per-story markers (2.0.5+) concurrent sub-agents writing to the same project root no longer race.
+    Return a one-line JSON summary on completion: {"story":"K", "status":"done"|"failed", "tests":"<N/M>", "notes":"<short>"}
+    ```
+
+    Wait for ALL N sub-agents to return. Collect results; abort the autopilot ONLY if a sub-agent reports a TRUE BLOCKER per the AUTOPILOT RULES.</action>
+    <action>**Merge per-story shards** after the layer completes:
+    `node {{project_root}}/_Sprintpilot/scripts/merge-shards.js --archive --project-root "{{project_root}}"` — collapses the per-story state shards into the authoritative project YAMLs and archives the layer's shards under `.archive/layer-<timestamp>/` so the next layer starts clean.</action>
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story sprint --phase "_end" --project-root "{{project_root}}"` — closes the open `dispatch.layer-{{epic_id}}` mark.</action>
+    <action>Update `{state_file}` with the new STATE_FIELDS (each completed story's status is reflected via the merge above; advance `session_stories_done` by `{{active_layer}}.length`). Then `goto step=2` to re-evaluate the loop.</action>
+    <goto step="2">Re-evaluate after parallel layer dispatch</goto>
+  </check>
+</check>
+
+<!-- PR 4 NANO ROUTING: when the active profile's implementation_flow is
+     'quick', route bmad-dev-story through bmad-quick-dev instead. Quick-dev
+     runs Implement → Review → Classify → Commit internally (BMad
+     step-oneshot.md), so bmad-create-story / bmad-check-readiness /
+     bmad-code-review are not invoked in this flow. -->
+<check if="{{implementation_flow}} is quick AND {{next_skill}} is bmad-dev-story">
+  <action>Override `{{next_skill}}` = `bmad-quick-dev`</action>
+  <action>Log: "Routing {{current_story}} through bmad-quick-dev per nano profile (implementation_flow=quick)"</action>
+</check>
+<!-- Under quick flow, autopilot never invokes bmad-create-story or
+     bmad-check-implementation-readiness; quick-dev reads AC from
+     sprint-status.yaml directly. If bmad-help proposes these skills
+     while implementation_flow=quick, skip them and advance. -->
+<check if="{{implementation_flow}} is quick AND ({{next_skill}} is bmad-create-story OR {{next_skill}} is bmad-check-implementation-readiness)">
+  <action>Log: "Skipping {{next_skill}} under quick flow (nano profile) — quick-dev reads AC directly"</action>
+  <action>Set `{{next_skill}}` = `bmad-quick-dev`</action>
+</check>
+
 <action>Set `{{completed_skill}}` = `{{next_skill}}`</action>
 <action>Create task "{{next_skill}}" → mark `in_progress`</action>
 
-<check if="{{next_skill}} is a per-story skill (bmad-dev-story, bmad-code-review, bmad-create-story)">
+<check if="{{next_skill}} is a per-story skill (bmad-dev-story, bmad-quick-dev, bmad-code-review, bmad-create-story)">
   <action>Set `{{current_story}}` = first story in `{status_file}` with status `ready-for-dev` or `in-progress`</action>
 
   <critical>**Validate story key format** — the key MUST follow the pattern `{epic}-{story}-{title-kebab}` (e.g., `1-2-user-authentication`), NOT just `{epic}-{story}` (e.g., `1-2`).
@@ -415,8 +687,23 @@ Resolve:
   <action>Create per-story step tasks if not already created</action>
 </check>
 
-<!-- GIT: Enter worktree before dev-story -->
-<check if="{{git_enabled}} AND {{next_skill}} is bmad-dev-story">
+<!-- PR 5: determine per-story epic key + title so the workflow can branch
+     per-epic under granularity=epic and decide "is this the last story
+     of the epic". Epic ID is the leading numeric segment of the story
+     key (e.g. '1-2-foo' → '1'); slug is the epic's title from sprint-
+     status.yaml (or the epic header in the epics file). Skip if empty. -->
+<action>Set `{{epic_id}}` = leading numeric segment of `{{current_story}}` (e.g. `1-2-foo` → `1`). If the key doesn't match `^\d+-`, leave `{{epic_id}}` = "".</action>
+<action>Set `{{epic_branch_name}}` = `epic-{{epic_id}}` (only used when `{{granularity}} = epic`).</action>
+<action>**Detect first vs last story of epic** — read `{status_file}` (BMAD-owned; do not modify). Find all stories with the same `{{epic_id}}`:
+  - `{{is_first_story_of_epic}}` = true if no story in this epic has status `in-progress` or `done` yet (i.e. current story is the first to enter dev-story / quick-dev).
+  - `{{is_last_story_of_epic}}` = true if this is the final undone story in the epic (after this story, all other stories in the epic are `done`).
+  Both default to true when `{{epic_id}}` = "" (single-story "epic").
+</action>
+
+<!-- GIT: Enter worktree OR create/reuse epic branch before dev-story OR quick-dev.
+     Nano's profile sets worktree.enabled=false + granularity=epic, so this
+     block falls through to in-place branching. -->
+<check if="{{git_enabled}} AND ({{next_skill}} is bmad-dev-story OR {{next_skill}} is bmad-quick-dev)">
   <action>**Sanitize branch name**: `node {{project_root}}/_Sprintpilot/scripts/sanitize-branch.js "{{current_story}}" --prefix "{{branch_prefix}}" --max-length 60`. Set `{{branch_name}}` = output. Full ref: `{{branch_prefix}}{{branch_name}}`.</action>
 
   <action>**Idempotency check** — if branch is already registered in `{status_file}` for this story AND its worktree exists, skip creation. If registered without worktree → recovery mode (see health check). Otherwise proceed.</action>
@@ -430,23 +717,74 @@ Resolve:
   Detached HEAD is fine — `git worktree add` below creates a new branch from HEAD.
   </action>
 
-  <action>**Create worktree.** Try: `git worktree add "{{project_root}}/.worktrees/{{current_story}}" -b "{{branch_prefix}}{{branch_name}}" 2>&1`. If it fails because the branch already exists, retry without `-b`: `git worktree add "{{project_root}}/.worktrees/{{current_story}}" "{{branch_prefix}}{{branch_name}}" 2>&1`.
+  <!-- PR 5: epic granularity — share one branch per epic instead of one per story.
+       Under worktree.enabled=false + granularity=epic (nano default),
+       subsequent stories of the same epic check out the epic branch in
+       place and commit there; no worktree is created. -->
+  <check if="{{granularity}} is epic">
+    <action>Override `{{branch_name}}` = `{{epic_branch_name}}` (shared across all stories in this epic).</action>
+    <check if="{{is_first_story_of_epic}} is true">
+      <action>Log: "Epic granularity: creating epic branch {{branch_prefix}}{{epic_branch_name}} for the first story of epic {{epic_id}}"</action>
+    </check>
+    <check if="{{is_first_story_of_epic}} is false">
+      <action>Log: "Epic granularity: reusing existing epic branch {{branch_prefix}}{{epic_branch_name}} for story {{current_story}}"</action>
+    </check>
+  </check>
+
+  <check if="{{worktree_enabled}} is false">
+    <action>**In-place branching** (granularity=epic or worktree.enabled=false): `git checkout -B {{branch_prefix}}{{branch_name}} 2>&1`. No worktree. Set `{{in_worktree}}` = false. Skip the worktree-add block below.</action>
+  </check>
+
+  <check if="{{worktree_enabled}} is true">
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js start --story "{{current_story}}" --phase "worktree.add" --project-root "{{project_root}}"` — ignore failures.</action>
+    <action>**Create worktree.** Try: `git worktree add "{{project_root}}/.worktrees/{{current_story}}" -b "{{branch_prefix}}{{branch_name}}" 2>&1`. If it fails because the branch already exists, retry without `-b`: `git worktree add "{{project_root}}/.worktrees/{{current_story}}" "{{branch_prefix}}{{branch_name}}" 2>&1`.
 
   If both fail (disk/permissions): log "WARN: worktree add failed — continuing without isolation", set `{{in_worktree}}` = false, and fall back to branch-only mode: `git checkout -b {{branch_prefix}}{{branch_name}}` (retry without `-b` if branch exists). HALT only if the checkout also fails. Git push/PR still work on the branch.
-  </action>
+    </action>
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js end --story "{{current_story}}" --phase "worktree.add" --project-root "{{project_root}}"` — ignore failures.</action>
+  </check>
 
-  <check if="worktree add succeeded">
+  <check if="{{worktree_enabled}} is true AND worktree add succeeded">
     <action>`cd {{project_root}}/.worktrees/{{current_story}}`. All subsequent commands run from here. Set `{{worktree_path}}` = this path.</action>
-    <action>**Init submodules** if `.gitmodules` exists (check with your file-exists tool or `node -e "process.exit(require('fs').existsSync('.gitmodules')?0:1)"`). Run `git submodule update --init --recursive` (~30s). On failure/hang: warn "Submodule init failed (may need auth). Continuing." and proceed.</action>
+    <action>**Disable gc.auto on this worktree** (PR 10): save original value `{{original_gc_auto_worktree}}` = output of `node {{project_root}}/_Sprintpilot/scripts/git-portable.js config-get gc.auto --default unset --project-root "{{project_root}}/.worktrees/{{current_story}}"`, then `git -C {{project_root}}/.worktrees/{{current_story}} config --local gc.auto 0`.</action>
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js start --story "{{current_story}}" --phase "worktree.submodule-init" --project-root "{{project_root}}"` — ignore failures.</action>
+    <action>**Init submodules** if `.gitmodules` exists (file-exists check via `node -e "process.exit(require('fs').existsSync('.gitmodules')?0:1)"`). PR 10 fast-path:
+    Resolve the main repo's common git dir into a captured variable `{{git_common}}` (cross-platform; replaces a `$(...)` shell substitution):
+    `node {{project_root}}/_Sprintpilot/scripts/git-portable.js common-dir --project-root "{{project_root}}"`. Trim trailing whitespace; the script exits 1 if git can't resolve the dir — log a warning and skip the submodule fast-path, falling through to the degraded-mode branch below.
+    For each submodule path in `.gitmodules`:
+      1. `node {{project_root}}/_Sprintpilot/scripts/submodule-lock.js acquire --submodule "<path>" --project-root "{{project_root}}"` — serializes concurrent submodule updates across worktrees.
+      2. With git ≥ 2.18 (confirmed at boot by check-prereqs): wrap the update with retry to survive ref-lock contention:
+         `node {{project_root}}/_Sprintpilot/scripts/with-retry.js -- git -C {{project_root}}/.worktrees/{{current_story}} submodule update --init --recursive --reference "{{git_common}}" --jobs=4 -- <path>`
+         With older git (degraded mode flagged by check-prereqs): fall back to `git -C ... submodule update --init --recursive -- <path>`.
+      3. `node {{project_root}}/_Sprintpilot/scripts/submodule-lock.js release --submodule "<path>" --project-root "{{project_root}}"` (best-effort, ignore failures).
+    If the loop fails or hangs: warn "Submodule init failed (may need auth). Continuing." and proceed.
+    </action>
+    <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js end --story "{{current_story}}" --phase "worktree.submodule-init" --project-root "{{project_root}}"` — ignore failures.</action>
     <action>Set `{{in_worktree}}` = true</action>
   </check>
   <action>Update `{state_file}` (write to the worktree copy since cwd is now the worktree)</action>
 </check>
 
 <action>Update `{state_file}` with STATE_FIELDS (set `current_bmad_step = executing`, `completed_skill = <previous skill>`).</action>
+<check if="{{coalesce_state_writes}} is true">
+  <action>Mirror critical keys to the shard (bypasses batching for crash-recovery correctness):
+  `node {{project_root}}/_Sprintpilot/scripts/state-shard.js batch --story sprint --json "{\"current_bmad_step\":\"executing\",\"current_story\":\"{{current_story}}\",\"completed_skill\":\"<previous skill>\"}" --project-root "{{project_root}}"` — ignore failures.
+  </action>
+</check>
 
 <!-- Autopilot menu handling rules apply — see AUTOPILOT RULES section above -->
 
+<!-- PHASE TIMING: emit start/end around every skill invocation.
+     Use `{{current_story}}` when set, else the sentinel `sprint` for
+     sprint-level skills (bmad-help, bmad-sprint-planning, etc).
+     The script is a silent no-op when autopilot.phase_timings is false. -->
+<action>Set `{{timing_story}}` = `{{current_story}}` if non-empty, else `sprint`.</action>
+<!-- Single-call timing via `mark`. The previous start/INVOKE/end triplet
+     was reliably broken in long sessions (LLM skipped the `end` call
+     ~50% of the time), so most skills had no duration recorded. `mark`
+     auto-computes the duration of the PREVIOUS phase from a small marker
+     file — one call per transition, no open-phase failure mode. -->
+<action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story "{{timing_story}}" --phase "skill.{{next_skill}}" --project-root "{{project_root}}"` — ignore failures.</action>
 <action>INVOKE `{{next_skill}}` skill using the Skill tool</action>
 <action>Mark task "{{next_skill}}" as `completed`</action>
 
@@ -457,8 +795,28 @@ Resolve:
 
 <step n="4" goal="Handle skill completion and route to next action">
 
+<!-- PR 4 NANO ROUTING: quick-dev completion handler.
+     Quick-dev's one-shot (step-oneshot.md:44) already ran Implement →
+     Review → Classify → Commit internally. Autopilot skips the external
+     bmad-code-review step and jumps straight to step 7 (mark story
+     done). Escalation safety net: if tests fail or classify severity is
+     high, flip implementation_flow to full for the rest of the session. -->
+<check if="{{completed_skill}} was bmad-quick-dev">
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js start --story "{{current_story}}" --phase "tests.run" --project-root "{{project_root}}"` — ignore failures.</action>
+  <action>Verify tests ran — if not, run them now: report `N/N passed`. Record pass/fail into `{{tests_passed}}`.</action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js end --story "{{current_story}}" --phase "tests.run" --project-root "{{project_root}}"` — ignore failures.</action>
+  <action>Read quick-dev's Classify severity from its stdout/output. If its output mentions `severity: high` or a failing classify, set `{{quickdev_severity_high}}` = true.</action>
+  <check if="{{tests_passed}} is false OR {{quickdev_severity_high}} is true">
+    <action>**Escalation** — flip the session-scoped flow to `full`: set `{{implementation_flow}}` = `full`. Do NOT write this back to config.yaml; it is session-only. Log decision: `category=scope, phase=autopilot:escalation, impact=medium, "nano story {{current_story}} triggered fallback (tests_passed={{tests_passed}}, severity_high={{quickdev_severity_high}}) — subsequent stories use full cycle"` to `{decision_log_file}`.</action>
+  </check>
+  <action>Set `{{next_skill}}` = "(none)" — quick-dev handled review + commit internally per BMad step-oneshot.md.</action>
+  <goto step="7">Mark story done</goto>
+</check>
+
 <check if="{{completed_skill}} was bmad-dev-story">
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js start --story "{{current_story}}" --phase "tests.run" --project-root "{{project_root}}"` — ignore failures.</action>
   <action>Verify tests ran — if not, run them now: report `N/N passed`</action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js end --story "{{current_story}}" --phase "tests.run" --project-root "{{project_root}}"` — ignore failures.</action>
   <action>**Log decisions** — review implementation choices made during dev-story and append entries to `{decision_log_file}` for any architecture, test-strategy, dependency, scope, or workaround decisions (see DECISION LOGGING section)</action>
 
   <!-- GIT: Lint, stage, and commit after dev-story -->
@@ -476,7 +834,9 @@ Resolve:
     - `{patch-title}` → from review finding title, fallback to "code review fix"
     Read the commit template from `git.commit_templates.story` in config (default: `feat({epic}): {story-title} ({story-key})`).
     Then run:
-    `node {{project_root}}/_Sprintpilot/scripts/stage-and-commit.js --message "feat({{epic}}): {{story-title}} ({{current_story}})" --allowlist {{project_root}}/_Sprintpilot/.secrets-allowlist`
+    `node {{project_root}}/_Sprintpilot/scripts/log-timing.js start --story "{{current_story}}" --phase "git.commit" --project-root "{{project_root}}"` (ignore failures), then
+    `node {{project_root}}/_Sprintpilot/scripts/stage-and-commit.js --message "feat({{epic}}): {{story-title}} ({{current_story}})" --allowlist {{project_root}}/_Sprintpilot/.secrets-allowlist`, then
+    `node {{project_root}}/_Sprintpilot/scripts/log-timing.js end --story "{{current_story}}" --phase "git.commit" --project-root "{{project_root}}"` (ignore failures).
     Output: commit SHA. Set `{{story_commit}}` = output.
     Warnings (secrets, large files) printed to stderr — review but don't halt unless user says to.
     </action>
@@ -513,6 +873,39 @@ Resolve:
   </action>
 </check>
 
+<check if="{{completed_skill}} was bmad-sprint-planning">
+  <!-- PR-follow-up: sprint-planning populates development_status for the
+       first time. Recalculate stories_remaining so the step-2 "sprint
+       complete" gate doesn't fire spuriously on the next iteration. -->
+  <action>**Recalculate `{{stories_remaining}}`** — run:
+  `node {{project_root}}/_Sprintpilot/scripts/list-remaining-stories.js --status-file "{status_file}" --format envelope`
+  Parse stdout as `{"remaining":[...],"state":"..."}` → `{{stories_remaining}}` = `.remaining`. Update `{state_file}` with the new value.</action>
+</check>
+
+<!-- 2.0.2: auto-infer inter-story dependencies via the autopilot's active
+     LLM session. Replaces the hand-authored dependencies.yaml step that
+     users never discovered. Gated on autopilot.auto_infer_dependencies
+     (default true on small/medium/large; false on nano and legacy).
+     The script never calls an LLM — it ingests our JSON output via stdin,
+     validates, and writes the sidecar with an AUTO-INFERRED marker.
+     Hand-authored sidecars (no marker) are detected and respected. -->
+<check if="{{completed_skill}} was bmad-sprint-planning">
+  <action>Resolve `{{auto_infer_dependencies}}` from `autopilot.auto_infer_dependencies` (default false) via:
+  `node {{project_root}}/_Sprintpilot/scripts/resolve-profile.js get autopilot.auto_infer_dependencies --project-root "{{project_root}}"`</action>
+  <check if="{{auto_infer_dependencies}} is true">
+    <action>Set `{{distinct_epic_ids}}` = sorted unique leading-numeric segments of every key in `{{stories_remaining}}` (e.g. `1-1-foo` → `1`). Skip the loop if empty (pre-planning edge case).</action>
+    <foreach var="{{epic_id}}" in="{{distinct_epic_ids}}">
+      <action>Generate the inference prompt: run `node {{project_root}}/_Sprintpilot/scripts/infer-dependencies.js scaffold-prompt --epic "{{epic_id}}" --project-root "{{project_root}}"` and capture stdout as `{{infer_prompt}}`.</action>
+      <action>**Execute the inference inline.** The prompt instructs you to read four files (sprint-status.yaml, epics.md, architecture.md, dependencies.yaml-if-present) and emit ONE JSON object with shape `{"version":1,"epic":"{{epic_id}}","dependencies":{...},"rationale":{...}}`. Read those files NOW. Reason about which stories share modules, files, or describe themselves as building on each other (the prompt's RULES section enumerates the legitimate triggers). Emit the JSON envelope. No prose, no markdown fences. Set `{{infer_json}}` to the envelope.</action>
+      <action>Pipe `{{infer_json}}` into `node {{project_root}}/_Sprintpilot/scripts/infer-dependencies.js write --epic "{{epic_id}}" --project-root "{{project_root}}"`. Parse stdout JSON.
+      - On exit 0 (`wrote: true`) → log: `"Inferred {{response.edges_inferred}} dependency edges for epic {{epic_id}} (hash {{response.hash}}; user_overrides_preserved: {{response.user_overrides_preserved}})"`.
+      - On exit 2 (`wrote: false`, `reason: existing-hand-authored`) → log: `"Existing dependencies.yaml is hand-authored — skipping LLM inference for epic {{epic_id}}; user-authored sidecar wins"`. Do NOT halt.
+      - On exit 1 (validation error) → log the error envelope verbatim, then log: `"LLM dependency inference rejected for epic {{epic_id}} — falling back to linear ordering. Re-run /sprint-autopilot-on to retry, or hand-author the sidecar."`. Do NOT halt the autopilot — `resolve-dag.js` will fall back to the `ordering` strategy on dispatch.
+      </action>
+    </foreach>
+  </check>
+</check>
+
 <check if="{{completed_skill}} was bmad-sprint-planning AND {{git_enabled}}">
   <action>If `{{has_origin}}` is true, run `git fetch origin` (log a warning on failure and continue — do not abort).
   If `{{has_origin}}` is false, skip the fetch.</action>
@@ -520,7 +913,19 @@ Resolve:
 </check>
 
 <check if="{{completed_skill}} was bmad-create-story">
-  <action>Verify story file has `- [ ]` checkboxes in Tasks/Subtasks section. If missing, re-run create-story.</action>
+  <!-- PR-follow-up (greenfield e2e fix): bmad-create-story sometimes omits
+       the Tasks/Subtasks section entirely. Re-running the skill doesn't
+       always fix it. Fall back to a deterministic script so the story
+       file ALWAYS has checkboxes dev-story can mark — no LLM prose in
+       this path. -->
+  <action>Locate the story file for `{{current_story}}` — glob
+  `_bmad-output/**/story-{{current_story}}.md` and
+  `_bmad-output/**/{{current_story}}.md`. Set `{{story_file_path}}`.
+  </action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/inject-tasks-section.js --story-file "{{story_file_path}}"`
+  — idempotent. The script checks for an existing `## Tasks` / `## Subtasks` section with at least one `- [ ]` checkbox and returns `{"action":"skip"}` if present. Otherwise it extracts every AC entry from the bounded `## Acceptance Criteria` section and appends a correctly-formatted section with one `- [ ] <AC>` bullet per entry.
+  Parse stdout JSON; the script never throws on a well-formed story file, so treat any non-zero exit as a log-and-proceed signal (the sprint can still complete without this guarantee — only the "task checkboxes marked" assertion degrades).
+  </action>
 </check>
 
 <check if="{{completed_skill}} was bmad-create-story AND {{git_enabled}}">
@@ -557,7 +962,11 @@ Resolve:
   Log: "next_skill was empty but undone stories remain — resolved to {{next_skill}} for {{current_story}}".
   </action>
   <check if="all stories in status_file are done">
-    <goto step="10">Sprint complete</goto>
+    <!-- Same finalize-pending handoff as step 2 — never run step 10 in
+         the session that first noticed sprint-complete. -->
+    <action>Update `{state_file}`: `current_bmad_step = "sprint-finalize-pending"`, `current_story = null`, `next_skill = null`, `stories_remaining = []`.</action>
+    <action>Release lock: `node {{project_root}}/_Sprintpilot/scripts/lock.js release` — ignore failures.</action>
+    <action>Report: "Sprint complete detected during skill-recovery. Pausing for fresh-context finalization — run /sprint-autopilot-on once more." Then HALT.</action>
   </check>
 </check>
 
@@ -603,6 +1012,8 @@ For any finding that is DISMISSED (contradicts AC or is a false positive):
 <action>Mark "[story] Apply patches" → `completed`</action>
 
 <!-- Re-run code review to sync sprint-status.yaml — patches resolved all findings, so code-review will now set story to done -->
+<!-- Single-call timing (mark) — see step-3 comment for rationale. -->
+<action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story "{{current_story}}" --phase "skill.bmad-code-review.rereview" --project-root "{{project_root}}"` — ignore failures.</action>
 <action>Re-invoke `bmad-code-review` using the Skill tool.
 The review layers already ran — this pass will see zero unresolved findings and set the story status to `done` in sprint-status.yaml (code-review owns that transition per step-04-present.md:92).
 Instruct: "Re-verify code review for story {{current_story}} — all patch findings have been applied. Update story status accordingly."
@@ -627,8 +1038,19 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
   - Final test count: `N/N passed`
 </action>
 
-<!-- GIT: Push, PR, exit worktree -->
-<check if="{{git_enabled}} AND {{in_worktree}}">
+<!-- PR 5: epic granularity — defer push/PR until the LAST story of the epic.
+     For intermediate stories (granularity=epic AND not is_last_story_of_epic):
+     the work is already committed to the epic branch locally via stage-and-
+     commit.js; no push or PR is attempted. The epic's last story pushes
+     the accumulated commits and opens one PR for the whole epic. -->
+<check if="{{granularity}} is epic AND {{is_last_story_of_epic}} is false">
+  <action>Log: "Epic granularity: skipping push/PR for {{current_story}} — will push at end of epic {{epic_id}}"</action>
+  <action>Set `{{push_status}}` = "deferred", `{{pr_url}}` = "DEFERRED", `{{merge_status}}` = "deferred"</action>
+  <!-- Skip the whole git-push block; fall through to the artifact-sync block below. -->
+</check>
+
+<!-- GIT: Push, PR, exit worktree (story granularity OR last story of an epic) -->
+<check if="{{git_enabled}} AND ({{granularity}} is story OR {{is_last_story_of_epic}} is true) AND ({{in_worktree}} OR {{worktree_enabled}} is false)">
   <check if="{{push_auto}} is true">
     <action>**Push branch**.
     Run: `git push -u origin {{branch_prefix}}{{branch_name}} 2>&1`
@@ -666,14 +1088,20 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
   </action>
 
   <check if="{{create_pr}} is false OR {{platform}} is git_only OR {{pr_url}} is null or SKIPPED">
-    <action>**Merge story branch to main.** If `{{has_origin}}` is false (local-only), substitute `origin/{{base_branch}}` → `{{base_branch}}` and skip all `git push origin` / `git fetch origin` calls below.
-    1. `git checkout -B {{base_branch}} origin/{{base_branch}}` then `git merge {{branch_prefix}}{{branch_name}} --no-edit`.
-    2. On success: `git push origin {{base_branch}}`, set `{{merge_status}}` = "merged".
-    3. On conflict: `git merge --abort`, `git fetch origin`, re-checkout base, retry merge once. On retry success: push + merged. On retry failure: `{{merge_status}}` = "failed", log warning, continue — the branch is preserved and boot reconciliation retries next session.
+    <action>**Merge story/epic branch to main.** If `{{has_origin}}` is false (local-only), substitute `origin/{{base_branch}}` → `{{base_branch}}` and skip all `git push origin` / `git fetch origin` calls below.
+    Choose merge strategy by `{{squash_on_merge}}` (PR 5): if true, use `git merge --squash` + single commit; otherwise standard merge commit.
+    1. `git checkout -B {{base_branch}} origin/{{base_branch}}`
+    2. If `{{squash_on_merge}}` is true:
+       `git merge --squash {{branch_prefix}}{{branch_name}}` then
+       `git commit -m "feat({{epic_id}}): epic {{epic_id}} ({{branch_prefix}}{{branch_name}})"`.
+       Otherwise: `git merge {{branch_prefix}}{{branch_name}} --no-edit`.
+    3. On success: `git push origin {{base_branch}}`, set `{{merge_status}}` = "merged".
+    4. On conflict: `git merge --abort`, `git fetch origin`, re-checkout base, retry merge once. On retry success: push + merged. On retry failure: `{{merge_status}}` = "failed", log warning, continue — the branch is preserved and boot reconciliation retries next session.
+    5. **PR 12 cross-epic conflict interlock**: if this merge conflict involved two independent epics AND `{{parallel_epics}}` is true, set `{{cross_epic_disabled_this_session}}` = true and log "EXPERIMENTAL: cross-epic merge conflict detected; disabling parallel_epics for the remainder of this session." The flag resets on next session start.
 
     `{{merge_status}}` is persisted by the sync-status.js call later in this step (via `--merge-status`). Do NOT call sync-status.js here — it does full block replacement and would destroy other fields.
     </action>
-    <check if="{{cleanup_on_merge}} is true">
+    <check if="{{cleanup_on_merge}} is true AND {{in_worktree}} is true">
       <action>**Cleanup worktree** (ignore failures — may already be gone): `git worktree remove .worktrees/{{current_story}} --force` then `git worktree prune`</action>
     </check>
   </check>
@@ -701,6 +1129,17 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
 <action>**Increment `{{session_stories_done}}` by 1** — this is the ONLY place the counter ticks up. It runs only after the story's full implementation cycle (dev-story GREEN + code-review + patches + artifacts committed + optional push/PR). Creating a story file in step 3 never increments this counter.</action>
 <action>Remove `{{current_story}}` from `{{stories_remaining}}` list</action>
 
+<!-- PR 6 STORY-BOUNDARY FLUSH: if coalescing is on, flush the sprint
+     shard's pending buffer now (writes accumulated non-critical fields
+     to the shard) and merge all shards into the authoritative
+     autopilot-state.yaml / decision-log.yaml. Fast on a single-story
+     sprint; amortized when multiple stories complete per session. -->
+<check if="{{coalesce_state_writes}} is true">
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/state-shard.js flush --story sprint --project-root "{{project_root}}"` — ignore failures.</action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/state-shard.js flush --story "{{current_story}}" --project-root "{{project_root}}"` — ignore failures (no-op if no per-story shard was ever batched).</action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/merge-shards.js --project-root "{{project_root}}"` — ignore failures. Produces merged autopilot-state.yaml + decision-log.yaml.</action>
+</check>
+
 <action>Report: "Story {{current_story}} done — N/N passing{{#if pr_url}} — PR: {{pr_url}}{{/if}}"</action>
 
 <action>Check if ALL stories in this epic are `done`</action>
@@ -788,6 +1227,13 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
 </check>
 
 <action>Update `{state_file}` with STATE_FIELDS.</action>
+<check if="{{coalesce_state_writes}} is true">
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/state-shard.js flush --story sprint --project-root "{{project_root}}"` — ignore failures.</action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/merge-shards.js --project-root "{{project_root}}"` — ignore failures.</action>
+</check>
+
+<!-- Phase-timing session snapshot (no-op if autopilot.phase_timings is false). -->
+<action>Run: `node {{project_root}}/_Sprintpilot/scripts/summarize-timings.js --session-only --format md --quiet --project-root "{{project_root}}"` — ignore failures. The stdout line is the artifact path; include it in the checkpoint report if non-empty.</action>
 
 <action>Read `{decision_log_file}` — count medium/high decisions from this session's stories</action>
 
@@ -827,15 +1273,88 @@ No work will be repeated.
 
 <step n="10" goal="Sprint complete — emit summary and next steps">
 
-<!-- GIT: Exit worktree if still in one -->
+<!-- CRITICAL-PATH-FIRST: these 6 actions MUST run before anything else in
+     step 10. They put the repo into a correct terminal state — orphan
+     worktrees removed, lock released, artifacts committed to main,
+     sprint-complete state marked, task checkboxes marked, final verification.
+     Even if the rest of step 10 is interrupted (SIGTERM, LLM improvises an
+     early summary, context exhaustion), the harness invariants hold. DO NOT
+     reorder or skip these — the order matters: worktrees-before-lock so a
+     concurrent autopilot session doesn't see orphans, lock-before-commit
+     so commits run with the repo already unlocked, etc. -->
+
+<!-- GIT: Exit worktree if still in one (prerequisite for the rest) -->
 <check if="{{in_worktree}}">
   <action>`cd {{project_root}}` — return to project root</action>
   <action>Set `{{in_worktree}}` = false</action>
 </check>
 
-<action>Verify: all stories `done`, all retrospectives `done` in `{status_file}`</action>
+<!-- Run the mark-tasks helper AS THE VERY FIRST action of step 10.
+     The LLM reliably executes the first critical action but sometimes
+     skips later ones once it feels "done" with the sprint. Putting this
+     first ensures every done-story's checkboxes get marked before the
+     LLM loses focus. -->
+<action>**[CRITICAL 1/7] Mark all done stories' Task checkboxes** — deterministic helper. Run:
+`node {{project_root}}/_Sprintpilot/scripts/mark-done-stories-tasks.js --status-file "{status_file}" --project-root "{{project_root}}"` — ignore failures. This finds every story with status="done" in sprint-status.yaml and replaces `- [ ]` with `- [x]` in its story file.
+</action>
+
+<action>**[CRITICAL 2/7] Remove autopilot-owned worktrees** — no-op if none exist. Only worktrees we created (paths inside `{{project_root}}/.worktrees/`) are removed; any user-placed worktree elsewhere is left untouched.
+<check if="{{git_enabled}}">
+  Run: `git worktree list --porcelain` to enumerate. For each worktree whose path starts with `{{project_root}}/.worktrees/`:
+  - `git worktree remove <path> --force 2>&1` (ignore failures — best-effort).
+  Then once: `git worktree prune 2>&1` (ignore failures).
+  This is the SINGLE authoritative cleanup site for autopilot-owned worktrees — do not wait for a later "safety net" cleanup that might not run.
+</check>
+</action>
+
+<action>**[CRITICAL 3/7] Release lock immediately** — before any slow operation:
+Run: `node {{project_root}}/_Sprintpilot/scripts/lock.js release` — ignore failures. Idempotent.
+</action>
+
+<action>**[CRITICAL 4/7] Commit any final artifacts + planning docs to main** — even if the rest of step 10 is interrupted. The checkout is deliberately non-destructive: we never use `-B` or `-f` (those silently wipe local commits or modifications). If the working tree is dirty, the commit step still runs; if the checkout fails, the commit is skipped with a warning rather than forced.
+<check if="{{git_enabled}}">
+  1. `git switch {{base_branch}} 2>&1 || git checkout {{base_branch}} 2>&1` (plain switch; if `{{base_branch}}` doesn't exist locally, `git checkout --track origin/{{base_branch}}` once to create it tracking origin). Never use `-B` or `-f` — they discard work.
+  2. If `{{has_origin}}` is true: `git pull --ff-only origin {{base_branch}} 2>&1` (fast-forward only; if the pull would require a merge, log a warning and continue — do NOT `reset --hard`).
+  3. Stage artifacts via the cross-platform helper (replaces `git add … 2>/dev/null || true`):
+  `node {{project_root}}/_Sprintpilot/scripts/git-portable.js safe-add _bmad-output/planning-artifacts _bmad-output/implementation-artifacts/sprint-status.yaml _bmad-output/implementation-artifacts/decision-log.yaml _bmad-output/implementation-artifacts/git-status.yaml _bmad-output/stories _bmad-output/implementation-artifacts/retrospectives --project-root "{{project_root}}"`
+  The script filters paths to those that actually exist on disk before invoking git, so missing paths are skipped silently with no shell error suppression needed.
+  4. If `git diff --cached --quiet` exits non-zero: `git commit -m "docs: sprint artifacts — planning + stories + retrospective"` then (if `{{has_origin}}` is true) `git push origin {{base_branch}}` (warn on failure, do not halt).
+</check>
+</action>
+
+<action>**[CRITICAL 5/7] Mark sprint-complete state**: update `{state_file}`: `current_bmad_step = "sprint-complete"`, `current_story = null`, `next_skill = null`, `stories_remaining = []`, `session_stories_done = {{session_stories_done}}`. This signals the test harness and any next /sprint-autopilot-on invocation that the sprint is genuinely done.</action>
+
+<action>**[CRITICAL 6/7] Verify** — run:
+`node {{project_root}}/_Sprintpilot/scripts/list-remaining-stories.js --status-file "{status_file}" --format envelope`
+Parse stdout as JSON. If `.state` is `sprint-complete` AND `.remaining` is empty, the sprint is verified complete. If `.state` is anything else (e.g. `sprint-in-progress` with leftover stories), log a warning — but do NOT revert the above actions. The worktrees are gone; the lock is released; the artifacts are committed; the state is marked complete; task checkboxes are marked. Manual recovery only.
+</action>
+
+<!-- Final terminal-state marker. Kept inside the CRITICAL block because
+     the previous "Delete state_file" action at the tail of step 10 was
+     being skipped by context-rot in long sessions (observed in e2e runs:
+     "autopilot-state.yaml still exists" warning), leaving a stale state
+     file that confused the next /sprint-autopilot-on boot. CRITICAL 5/7
+     already wrote sprint-complete as a belt-and-suspenders in case this
+     delete crashes mid-run; step 1 also short-circuits on a leftover
+     sprint-complete state so accidental re-invocation doesn't loop. -->
+<action>**[CRITICAL 7/7] Delete state_file** — `node -e "require('node:fs').rmSync('{state_file}', { force: true })"` (idempotent; never halt on failure). Removes `autopilot-state.yaml` so the next invocation starts cleanly. CRITICAL 5/7 already wrote `current_bmad_step = sprint-complete` to the same file as a crash-safe marker, so if this delete fails mid-run the next session still sees the terminal state.</action>
+
+<!-- Close the last open `mark` phase so its duration gets recorded.
+     Without this, the very last skill's duration would be lost (no
+     subsequent mark fires after sprint-complete). -->
+<action>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js mark --story sprint --phase _end --project-root "{{project_root}}"` — ignore failures.</action>
+
 <action>Run full test suite — report `N/N passed`</action>
 
+<!-- PR 6 SPRINT-COMPLETE FLUSH + ARCHIVE (no-op if coalescing is off). -->
+<check if="{{coalesce_state_writes}} is true">
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/state-shard.js flush --story sprint --project-root "{{project_root}}"` — ignore failures.</action>
+  <action>Run: `node {{project_root}}/_Sprintpilot/scripts/merge-shards.js --archive --project-root "{{project_root}}"` — ignore failures. --archive moves merged shards to .archive/layer-&lt;timestamp&gt;/ (the script generates the ISO timestamp itself; no shell `$(...)` substitution needed) so the next sprint starts clean.</action>
+</check>
+
+<!-- Final phase-timing hotspot report (no-op if autopilot.phase_timings is false). -->
+<action>Run: `node {{project_root}}/_Sprintpilot/scripts/summarize-timings.js --format md --quiet --project-root "{{project_root}}"` — ignore failures. The stdout line is the artifact path; include it in the sprint report if non-empty.</action>
+
 <!-- Generate project documentation after sprint completion -->
 <action>**Resolve stack** — set `{{stack}}` = `{ name, install_cmd, run_cmd, test_cmd }` using the first successful source:
 
@@ -866,21 +1385,32 @@ No work will be repeated.
 <action>**Generate documentation** — invoke `bmad-document-project`. If unavailable or it fails, write a minimal README using `{{stack}}`: project name + description (from brief/PRD); install/run/test lines for each non-null `{{stack.*_cmd}}` (omit lines where null); architecture overview if `architecture.md` exists.</action>
 
 <check if="{{git_enabled}}">
-  <action>**Commit final artifacts + docs to main.**
-  1. `git checkout -B {{base_branch}} origin/{{base_branch}}`
-  2. `git add _bmad-output/ README.md docs/` (ignore missing-path errors)
-  3. If `git diff --cached --quiet` exits non-zero: `git commit -m "docs: project documentation and final artifacts"` then `git push origin {{base_branch}}` (warn on push failure).
+  <action>**Commit README + docs to main** (sprint artifacts already committed in CRITICAL 4/7 above — this picks up README.md / docs/ that were generated later by bmad-document-project). Non-destructive checkout — never `-B` or `-f`:
+  1. `git switch {{base_branch}} 2>&1 || git checkout {{base_branch}} 2>&1`.
+  2. If `{{has_origin}}` is true: `git pull --ff-only origin {{base_branch}} 2>&1` (warn on non-ff; do NOT reset).
+  3. Stage docs via the cross-platform helper:
+  `node {{project_root}}/_Sprintpilot/scripts/git-portable.js safe-add README.md docs/ --project-root "{{project_root}}"`
+  (paths are filtered to those that exist; missing paths are skipped).
+  4. If `git diff --cached --quiet` exits non-zero: `git commit -m "docs: project documentation"` then (if `{{has_origin}}`) `git push origin {{base_branch}}` (warn on push failure, do not halt).
   </action>
 </check>
 
 <action>**Collect report data** from `{status_file}` (stories grouped by epic with titles, totals, final test count; PR/MR URLs, patch/dismissed counts per story if git_enabled) and `{decision_log_file}` (medium/high-impact decisions; counts of `review-accept`, `review-triage`, code-review rounds; per-story patches-applied / findings-dismissed).</action>
 
 <check if="{{git_enabled}}">
-  <action>**Cleanup remaining worktrees** (safety net): `git worktree list --porcelain` → for each non-main worktree: `git worktree remove <path> --force` then `git worktree prune` (log + continue on failure).</action>
-  <action>Release lock: `node {{project_root}}/_Sprintpilot/scripts/lock.js release`</action>
+  <!-- Worktree cleanup already ran as CRITICAL 2/7 above. Intentionally
+       no duplicate here — relying on early cleanup to avoid orphans
+       when the LLM short-circuits late actions. -->
+  <action>(No-op: worktree cleanup already executed in CRITICAL 2/7.)</action>
+  <!-- PR 10: restore main-repo gc.auto to its prior value. -->
+  <action>**Restore main-repo gc.auto**:
+  if `{{original_gc_auto_main}}` is "unset": `git config --local --unset gc.auto` (ignore failure — may already be unset).
+  else: `git config --local gc.auto {{original_gc_auto_main}}`.
+  </action>
+  <action>Belt-and-suspenders: `node {{project_root}}/_Sprintpilot/scripts/lock.js release` (already released earlier in step 10; this is idempotent and catches any race where the early release failed).</action>
 </check>
 
-<action>Delete `{state_file}` — sprint complete</action>
+<!-- State file deletion moved to CRITICAL 7/7 above for reliability. -->
 <action>Mark master task "Sprintpilot — Full Sprint Execution" → `completed`</action>
 
 <action>Read template `{{project_root}}/_Sprintpilot/templates/sprint-report.txt`, fill mustache placeholders with the collected data, and print the result verbatim as the final message.</action>