@ikunin/sprintpilot 1.0.4 → 2.0.4

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

@@ -8,23 +8,35 @@ You do NOT hardcode the workflow sequence. After each completed skill, read its
 
 **Git integration** is additive. If `_Sprintpilot/manifest.yaml` doesn't exist or `git.enabled: false`, all git operations are silently skipped and this workflow behaves identically to the stock autopilot.
 
-### Shell portability (IMPORTANT)
+### Shell portability
 
-Sprintpilot runs under any LLM CLI (Claude Code, Gemini CLI, Cursor, etc.) on any OS. The shell that executes commands may be **bash, zsh, PowerShell, or cmd** depending on platform and CLI. Shell-specific idioms will fail silently when the wrong shell is used.
+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:
 
-**When you encounter bash-style idioms below, translate them to your shell.** The table applies to **external commands** (like `git`); cmdlets have slightly different conventions.
-
-| Bash idiom | PowerShell equivalent | Meaning |
+| Idiom | Where used | Portable across |
 |---|---|---|
-| `A && B` | `A; if ($LASTEXITCODE -eq 0) { B }` (or separate commands, guarding B manually) | Run B only if A succeeded |
-| `A \|\| true` | `A; $LASTEXITCODE = 0` (or `try { A } catch {}` for cmdlets) | Run A, ignore failures |
-| `2>/dev/null` | `2>$null` | Suppress stderr |
-| `rm -rf <dir>` | `Remove-Item -Recurse -Force <dir>` | Recursive delete |
-| `if [ -f X ]; then ... fi` | `if (Test-Path -PathType Leaf X) { ... }` | File-exists check (regular file, not dir) |
+| `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 |
+|---|---|
+| `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` |
+
+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).
 
-**Safer:** when in doubt, use the cross-platform Node helpers under `_Sprintpilot/scripts/`. For ad-hoc file ops, invoke Node inline: `node -e "require('fs').rmSync('<path>', {recursive: true, force: true})"`.
+Common cross-platform inline snippets:
 
-If a step below uses `&&` to chain "run B only on A's success", and you cannot express that in one line, **run the commands separately and STOP if any step fails** — do not proceed past a failed step.
+| 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.
 
 ---
 
@@ -42,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
@@ -75,55 +88,20 @@ For everything else: decide, document briefly, continue.
 
 ## DECISION LOGGING
 
-Every non-trivial decision made during autopilot execution MUST be logged to `{decision_log_file}`. This creates an audit trail the user reviews at the end of each session.
-
-### When to log
-
-Log a decision whenever you:
-- Choose an architecture pattern, data structure, or design approach (`architecture`)
-- Select a test strategy or skip a test category (`test-strategy`)
-- Add, remove, or substitute a dependency (`dependency`)
-- Dismiss a code review finding (`review-triage`)
-- Accept and apply a code review finding (`review-accept`)
-- Recover from a HALT condition (`halt-recovery`)
-- Implement something not explicitly in the story spec (`scope`)
-- Apply a workaround for a tool limitation or false positive (`workaround`)
-
-Do NOT log routine actions (running tests, staging files, creating branches).
-
-### File format
-
-Initialize `{decision_log_file}` on first decision (if it does not exist):
-
-```yaml
-generated: {current_date}
-last_updated: {current_datetime}
-
-decisions: []
-```
+Log every non-trivial decision to `{decision_log_file}` (skip routine actions — running tests, staging files, creating branches). Create the file on first decision; update `last_updated` on every append.
 
-Append each decision as a new entry:
+**Categories:** `architecture`, `test-strategy`, `dependency`, `review-triage` (dismissed finding), `review-accept` (applied fix), `halt-recovery`, `scope` (outside story spec), `workaround`.
+**Impact:** `low` (reversible/cosmetic), `medium` (affects one component), `high` (cross-cutting or deviates from spec).
+**Phase format:** `{skill}:{sub_phase}` — e.g. `dev-story:RED`, `code-review:triage`, `autopilot:routing`.
 
+**File schema:**
 ```yaml
-  - id: {auto_increment}
-    timestamp: "{current_datetime_iso8601}"
-    story: "{current_story or sprint-level}"
-    phase: "{skill}:{sub_phase}"
-    category: {architecture|test-strategy|dependency|review-triage|review-accept|halt-recovery|scope|workaround}
-    decision: "{what was decided — one line}"
-    rationale: "{why — one line}"
-    impact: {low|medium|high}
+generated: {date}
+last_updated: {datetime}
+decisions:
+  - { id, timestamp, story, phase, category, decision, rationale, impact }
 ```
 
-**Phase format:** `dev-story:RED`, `dev-story:GREEN`, `code-review:triage`, `code-review:patch`, `autopilot:init`, `autopilot:routing`, etc.
-
-**Impact levels:**
-- `low` — easily reversible, cosmetic, or standard practice
-- `medium` — affects behavior but contained to one story/component
-- `high` — cross-cutting, hard to reverse, or deviates from spec
-
-Always update `last_updated` when appending.
-
 ---
 
 ## SKILL AUTOMATABLE REFERENCE
@@ -156,6 +134,19 @@ Resolve:
 - `project_root` = absolute path of current working directory (store for later use)
 - `session_story_limit` is loaded below from `modules/autopilot/config.yaml` (default: 3)
 
+**`{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>
@@ -171,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>
 
@@ -200,6 +230,22 @@ Resolve:
     <action>STOP</action>
   </check>
 
+  <action>**Check for `origin` remote** — run: `git remote get-url origin`
+  If the command fails (exit code != 0), no `origin` remote is configured. Set `{{has_origin}}` = false.
+  Otherwise set `{{has_origin}}` = true.
+  </action>
+  <check if="{{has_origin}} is false">
+    <action>Log: "WARN: no `origin` remote configured — running in local-only mode. Remote operations (fetch, push, PR, branch reconciliation) will be skipped. Add a remote later with: `git remote add origin <url>`"</action>
+    <action>Set `{{push_auto}}` = false</action>
+    <action>Set `{{create_pr}}` = false</action>
+    <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
@@ -217,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.
@@ -235,7 +301,8 @@ Resolve:
   </action>
 
   <action>**Branch reconciliation** — detect pushed-but-unmerged story branches.
-  Run as separate commands — **if `git fetch origin` fails (network/auth), STOP branch reconciliation and log a warning; do not operate on stale local refs**:
+  Skip this entire section if `{{has_origin}}` is false (no remote → nothing to reconcile).
+  Run as separate commands — **if `git fetch origin` fails (no remote/network/auth), STOP branch reconciliation and log a warning; do not operate on stale local refs**:
     1. `git fetch origin`
     2. `git branch -r --list "origin/{{branch_prefix}}*"`
   For each remote branch:
@@ -267,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>
 
 ---
@@ -281,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)
@@ -319,30 +388,40 @@ Resolve:
     - Update `{state_file}` with reconciled values
   </action>
 
-  <!-- Resume from a `retrospective_mode: stop` pause.
-       The user was told to run /bmad-retrospective interactively. If they
-       did, the epic is now `done` in {status_file} (or a retrospective
-       artifact exists). Otherwise, re-issue the instructions and halt. -->
+  <!-- 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`</action>
-    <action>Check whether epic `{{paused_epic_id}}` is now `done` in `{status_file}` OR an artifact exists at `{implementation_artifacts}/retrospectives/epic-{{paused_epic_id}}-*.md`</action>
+    <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>
     <check if="epic is done OR retrospective artifact exists">
-      <action>Clear `paused_at`, `paused_epic_id`, and `next_action` from `{state_file}`</action>
-      <action>Log: "Epic {{paused_epic_id}} retrospective detected — resuming autopilot"</action>
+      <action>Clear `paused_at`, `paused_epic_id`, `next_action` from `{state_file}`. Log: "Epic {{paused_epic_id}} retrospective detected — resuming autopilot".</action>
     </check>
     <check if="epic is NOT done AND no retrospective artifact">
-      <action>Report:
-      ```
-      Autopilot still paused — epic {{paused_epic_id}} retrospective not yet done.
-
-      Run `/bmad-retrospective` interactively for epic {{paused_epic_id}},
-      then re-run `/sprint-autopilot-on` to continue.
-
-      (To bypass, edit _Sprintpilot/modules/autopilot/config.yaml and set
-      retrospective_mode to `auto` or `skip`.)
-      ```
-      </action>
-      <action>STOP</action>
+      <action>Report: "Autopilot still paused — epic {{paused_epic_id}} retrospective not yet done. Run `/bmad-retrospective` interactively, then re-run `/sprint-autopilot-on`. (To bypass: set `retrospective_mode` to `auto` or `skip` in `_Sprintpilot/modules/autopilot/config.yaml`.)" Then STOP.</action>
     </check>
   </check>
 
@@ -350,22 +429,11 @@ Resolve:
 </check>
 
 <check if="state_file does NOT exist">
-  <action>Check if `{status_file}` exists — if not, invoke `bmad-sprint-planning` first</action>
-
-  <check if="{{git_enabled}} AND status_file did not exist (sprint-planning just ran)">
-    <action>Run `git fetch origin` to ensure remote refs are current</action>
-    <action>Initialize `{git_status_file}` with git_integration block:
-    ```yaml
-    # Sprintpilot — Git Status
-    git_integration:
-      enabled: true
-      base_branch: {git.base_branch from config}
-      platform: {{platform}}
-
-    stories:
-    ```
-    Note: this is the addon's own file — NEVER write git fields to sprint-status.yaml.
-    </action>
+  <action>Check if `{status_file}` exists. If NOT, do NOT jump to `bmad-sprint-planning` (Phase 4 skill, requires Phase 1–3 artifacts). Invoke `bmad-help` — "No sprint-status.yaml found. What is the current phase and which skill should run first?" — and set `{{next_skill}}` from its response. Expected routing: no PRD → `bmad-create-prd` (BLOCKER); PRD → `bmad-create-architecture`; architecture → `bmad-create-epics-and-stories`; epics → `bmad-sprint-planning`.</action>
+
+  <check if="{{git_enabled}} AND status_file did not exist AND {{next_skill}} is bmad-sprint-planning (planning just completed earlier in this flow)">
+    <action>Run `git fetch origin` — warn + skip on failure (no remote/auth/network), do not abort bootstrap.</action>
+    <action>Initialize `{git_status_file}` (addon-owned — NEVER write git fields to sprint-status.yaml) with: `git_integration: { enabled: true, base_branch: <from config>, platform: {{platform}} }` and empty `stories:`.</action>
   </check>
 
   <action>Read `{status_file}` — find all stories not yet `done`</action>
@@ -376,21 +444,14 @@ Resolve:
     - `{{session_stories_done}}` = 0
   </action>
   <action>Create master task: "Sprintpilot — Full Sprint Execution" → `in_progress`</action>
-  <action>Write initial `{state_file}`:
-  ```yaml
-  last_updated: {current_datetime}
-  current_story: null
-  current_bmad_step: null
-  completed_skill: bmad-help
-  next_skill: {{next_skill}}
-  session_stories_done: 0
-  stories_remaining: [list from sprint-status]
-  git_enabled: {{git_enabled}}
-  platform: {{platform}}
-  in_worktree: false
-  pr_base: {{base_branch}}
-  ```
+  <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
@@ -412,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>
 
@@ -464,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>` after each skill returns.
+    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`).
@@ -481,95 +687,104 @@ 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">
-  <action>**Sanitize branch name** — run:
-  `node {{project_root}}/_Sprintpilot/scripts/sanitize-branch.js "{{current_story}}" --prefix "{{branch_prefix}}" --max-length 60`
-  Output: sanitized name (without prefix). Set `{{branch_name}}` = output.
-  Full branch ref will be `{{branch_prefix}}{{branch_name}}`.
-  </action>
+<!-- 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>
 
-  <action>**Check if branch already registered** in `{status_file}` for this story.
-  If yes AND worktree already exists → skip creation (idempotent).
-  If yes AND no worktree → recovery mode (see health check).
-  If no → proceed with creation.
-  </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>**Prepare for worktree** — determine the correct branch point.
-  Run: `git fetch origin`
+  <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>
 
-  Check if there is a previous story in this epic with a pushed but unmerged branch (PR pending):
-  - Read `{git_status_file}` for earlier stories in the same epic
-  - Find the latest story branch where `push_status` = "pushed" AND `pr_url` is a valid URL
-  - Check if that branch has been merged to `{{base_branch}}`: `git merge-base --is-ancestor origin/{{branch_prefix}}<prev-branch> origin/{{base_branch}}`
+  <action>**Pick branch point.** If `{{has_origin}}` is true: `git fetch origin` (warn + continue on failure). If `{{has_origin}}` is false: skip fetch, use local refs.
 
-  If an unmerged previous story branch exists:
-  - Branch from it: `git checkout origin/{{branch_prefix}}<prev-branch>`
-  - Set `{{pr_base}}` = `{{branch_prefix}}<prev-branch>` (PR should target previous story, not main)
-  - Log: "Branching from {{branch_prefix}}<prev-branch> (PR pending merge)"
-  Otherwise:
-  - Branch from base: `git checkout origin/{{base_branch}}`
-  - Set `{{pr_base}}` = `{{base_branch}}`
+  Read `{git_status_file}` for earlier stories in this epic; find the latest with `push_status = "pushed"` AND a valid `pr_url`; check if merged to base: `git merge-base --is-ancestor origin/{{branch_prefix}}<prev-branch> origin/{{base_branch}}`.
+  - If unmerged previous story exists (requires `{{has_origin}}`): `git checkout origin/{{branch_prefix}}<prev-branch>`, set `{{pr_base}}` = `{{branch_prefix}}<prev-branch>`.
+  - Otherwise: `git checkout origin/{{base_branch}}` (or local `{{base_branch}}` if no origin), set `{{pr_base}}` = `{{base_branch}}`.
 
-  (Detached HEAD is fine — the worktree add below creates a new branch from HEAD)
+  Detached HEAD is fine — `git worktree add` below creates a new branch from HEAD.
   </action>
 
-  <action>**Create worktree** using standard git commands (works in any coding agent):
-  ```
-  git worktree add "{{project_root}}/.worktrees/{{current_story}}" -b "{{branch_prefix}}{{branch_name}}" 2>&1
-  ```
-  This creates `.worktrees/{{current_story}}/` with a new branch `{{branch_prefix}}{{branch_name}}` from HEAD.
+  <!-- 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>
 
-  If worktree add fails (branch already exists):
-  ```
-  git worktree add "{{project_root}}/.worktrees/{{current_story}}" "{{branch_prefix}}{{branch_name}}" 2>&1
-  ```
+  <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>
 
-  **If both fail** (disk full, permissions, etc.):
-  - Log: "WARN: git worktree add failed — continuing without worktree isolation"
-  - Set `{{in_worktree}}` = false
-  - Create branch manually: `git checkout -b {{branch_prefix}}{{branch_name}}`
-    If checkout also fails (branch already exists): `git checkout {{branch_prefix}}{{branch_name}}`
-    If both fail: HALT — "Could not create or switch to branch {{branch_prefix}}{{branch_name}}"
-  - Continue with the skill invocation in PROJECT_ROOT (no isolation)
-  - Git operations (commit, push, PR) still work on the branch
-  </action>
+  <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`.
 
-  <check if="worktree add succeeded">
-    <action>**Change working directory** to the worktree:
-    `cd {{project_root}}/.worktrees/{{current_story}}`
-    All subsequent file operations and commands MUST use this directory.
-    Set `{{worktree_path}}` = `{{project_root}}/.worktrees/{{current_story}}`
+  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>Run: `node {{project_root}}/_Sprintpilot/scripts/log-timing.js end --story "{{current_story}}" --phase "worktree.add" --project-root "{{project_root}}"` — ignore failures.</action>
+  </check>
 
-    <action>**Init submodules** if needed.
-    First check for `.gitmodules` (use your file-exists tool, or `node -e "process.exit(require('fs').existsSync('.gitmodules')?0:1)"`). If not present, skip this step.
-    If present, run `git submodule update --init --recursive` (give it ~30 seconds). If the command fails or hangs, warn "Submodule init failed (may need auth). Continuing without." and proceed.
+  <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>**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 worktree copy since we're now IN the worktree)</action>
+  <action>Update `{state_file}` (write to the worktree copy since cwd is now the worktree)</action>
 </check>
 
-<action>Update `{state_file}`:
-```yaml
-last_updated: {current_datetime}
-current_story: {{current_story}}
-current_bmad_step: executing
-completed_skill: {previous skill}
-next_skill: {{next_skill}}
-session_stories_done: {{session_stories_done}}
-stories_remaining: {{stories_remaining}}
-git_enabled: {{git_enabled}}
-platform: {{platform}}
-in_worktree: {{in_worktree}}
-pr_base: {{pr_base}}
-```
-</action>
+<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>
 
@@ -580,8 +795,28 @@ pr_base: {{pr_base}}
 
 <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 -->
@@ -599,7 +834,9 @@ pr_base: {{pr_base}}
     - `{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>
@@ -636,13 +873,59 @@ pr_base: {{pr_base}}
   </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>Run `git fetch origin`</action>
+  <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>
   <action>Initialize `{git_status_file}` if it doesn't exist (with git_integration block)</action>
 </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}}">
@@ -653,22 +936,10 @@ pr_base: {{pr_base}}
   </action>
 </check>
 
-<!-- GIT: Commit planning artifacts to main after planning skills -->
 <check if="{{git_enabled}} AND {{completed_skill}} is a planning skill (bmad-create-prd, bmad-create-architecture, bmad-create-ux-design, bmad-create-epics-and-stories, bmad-sprint-planning, bmad-check-implementation-readiness, bmad-create-story)">
-  <action>**Commit planning artifacts to main** — keep track of all planning decisions in git.
-  Stage all changed artifacts (ignore errors — any of these paths may not yet exist):
-  ```
-  git add _bmad-output/planning-artifacts/ _bmad-output/implementation-artifacts/ _bmad-output/stories/
-  ```
-  Check if there's anything staged; if yes, commit:
-  ```
-  git diff --cached --quiet
-  ```
-  If that exits non-zero (there are staged changes), run: `git commit -m "docs: {{completed_skill}} artifacts"`
-  Then push (log a warning if push fails; do not halt autopilot):
-  ```
-  git push origin {{base_branch}}
-  ```
+  <action>**Commit planning artifacts to main.**
+  1. `git add _bmad-output/planning-artifacts/ _bmad-output/implementation-artifacts/ _bmad-output/stories/` (ignore missing-path errors)
+  2. If `git diff --cached --quiet` exits non-zero: `git commit -m "docs: {{completed_skill}} artifacts"` then `git push origin {{base_branch}}` (warn on push failure, do not halt).
   </action>
 </check>
 
@@ -679,34 +950,23 @@ pr_base: {{pr_base}}
 
 <step n="5" goal="Determine next skill — from skill output first, bmad-help as fallback">
 
-<action>Read the output of `{{completed_skill}}`</action>
-
-<check if="output contains 'Next Steps', 'What to do next', 'Run next', or equivalent">
-  <action>Extract `{{next_skill}}` from that section</action>
-  <action>Log: "Next step from skill output: {{next_skill}}"</action>
-</check>
-
-<check if="output contains NO clear next step">
-  <action>Invoke `bmad-help` — "{{completed_skill}} just finished. What is the next required workflow step?"</action>
-  <action>Extract `{{next_skill}}` from bmad-help response</action>
-  <action>Log: "Next step from bmad-help fallback: {{next_skill}}"</action>
-</check>
+<action>Read the output of `{{completed_skill}}`. If it contains "Next Steps", "What to do next", "Run next", or equivalent, extract `{{next_skill}}` from that section. Otherwise invoke `bmad-help` — "{{completed_skill}} just finished. What is the next required workflow step?" — and extract `{{next_skill}}` from its response. Log the source ("skill output" vs "bmad-help fallback").</action>
 
-<check if="{{next_skill}} is null, empty, or signals completion (no further steps / sprint done / all done)">
-  <action>**Verify against source of truth** — re-read `{status_file}` and check for any story with status != "done"</action>
-  <check if="undone stories exist in status_file">
-    <action>Set `{{current_story}}` = first undone story from `{status_file}`</action>
-    <action>Determine `{{next_skill}}` based on that story's current status and BMAD step:
-      - If story has no story file yet → `bmad-create-story`
-      - If story file exists but status is `ready-for-dev` → `bmad-check-implementation-readiness`
-      - If story is `in-progress` and `current_bmad_step` is before `code-review` (i.e. RED or GREEN phase) → `bmad-dev-story`
-      - If story is `in-progress` and `current_bmad_step` is `code-review` or later → `bmad-code-review`
-      - Otherwise → invoke `bmad-help` for precise determination
-    </action>
-    <action>Log: "next_skill was empty but undone stories remain — resolved to {{next_skill}} for {{current_story}}"</action>
-  </check>
+<check if="{{next_skill}} is null, empty, or signals completion">
+  <action>**Verify against source of truth** — re-read `{status_file}`. If undone stories exist, set `{{current_story}}` = first one and determine `{{next_skill}}`:
+    - No story file → `bmad-create-story`
+    - Story file + status `ready-for-dev` → `bmad-check-implementation-readiness`
+    - Status `in-progress` and `current_bmad_step` before `code-review` → `bmad-dev-story`
+    - Status `in-progress` and `current_bmad_step` ≥ `code-review` → `bmad-code-review`
+    - Else → invoke `bmad-help` for precise determination
+  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>
 
@@ -752,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."
@@ -776,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`
@@ -815,37 +1088,21 @@ 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** — tracked and retryable.
-    Run:
-    ```
-    git checkout -B {{base_branch}} origin/{{base_branch}}
-    git merge {{branch_prefix}}{{branch_name}} --no-edit
-    ```
-    If succeeds:
-      - `git push origin {{base_branch}}`
-      - Set `{{merge_status}}` = "merged"
-    If fails (conflict):
-      - `git merge --abort`
-      - `git fetch origin`
-      - `git checkout -B {{base_branch}} origin/{{base_branch}}`
-      - Retry merge once: `git merge {{branch_prefix}}{{branch_name}} --no-edit`
-      - If retry succeeds: push, set `{{merge_status}}` = "merged"
-      - If retry fails: set `{{merge_status}}` = "failed"
-        Log: "WARN: merge failed for {{current_story}} — will retry on next boot"
-
-    If `{{merge_status}}` == "failed":
-      Log warning but do NOT halt. The branch is pushed and preserved.
-      Boot reconciliation (INITIALIZATION branch reconciliation) will retry on next session.
-
-    Note: `{{merge_status}}` is persisted by the full sync-status.js call later in this step (via `--merge-status`). Do NOT call sync-status.js separately here — it does full block replacement and would destroy other fields.
+    <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">
-      <action>**Cleanup worktree** for merged story — branch was merged locally, worktree is no longer needed. Ignore failures from the remove (the worktree may already be gone):
-      ```
-      git worktree remove .worktrees/{{current_story}} --force
-      git worktree prune
-      ```
-      </action>
+    <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>
   <check if="{{pr_url}} is a valid URL (not null, not SKIPPED)">
@@ -854,29 +1111,11 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
     <action>Log: "Story {{current_story}} pushed — PR awaiting review: {{pr_url}}"</action>
   </check>
 
-  <!-- Commit all implementation artifacts and status updates to main after each story -->
-  <action>**Commit story completion artifacts to main** — ensure main always reflects current sprint state.
-  ```
-  git checkout -B {{base_branch}} origin/{{base_branch}}
-  ```
-  </action>
-
-  <action>**Write git status** to addon's own file (NEVER modify sprint-status.yaml) — runs AFTER checkout to base branch so the file persists in the working tree for the commit below:
-  `node {{project_root}}/_Sprintpilot/scripts/sync-status.js --story "{{current_story}}" --git-status-file "{{project_root}}/_bmad-output/implementation-artifacts/git-status.yaml" --branch "{{branch_prefix}}{{branch_name}}" --commit "{{story_commit}}" --patch-commits "{{patch_commits_csv}}" --push-status "{{push_status}}" --merge-status "{{merge_status}}" --pr-url "{{pr_url}}" --lint-result "{{lint_result}}" --worktree "{{project_root}}/.worktrees/{{current_story}}" --platform "{{platform}}" --base-branch "{{base_branch}}"`
-  This writes to `git-status.yaml` (addon-owned). Sprint-status.yaml is BMAD-owned — updated by BMAD skills only.
-  </action>
-
-  <action>**Stage and commit artifacts** — explicitly include git-status.yaml and decision-log.yaml. Ignore errors from the `git add` (any listed path may not yet exist):
-  ```
-  git add _bmad-output/implementation-artifacts/sprint-status.yaml _bmad-output/implementation-artifacts/git-status.yaml _bmad-output/implementation-artifacts/autopilot-state.yaml _bmad-output/implementation-artifacts/decision-log.yaml _bmad-output/stories/ _bmad-output/planning-artifacts/
-  ```
-  Check if anything is staged: `git diff --cached --quiet`. If that exits non-zero, commit:
-  `git commit -m "docs: story {{current_story}} done — {{test_count}} tests{{#if pr_url}}, PR: {{pr_url}}{{/if}}"`
-  Then push (log a warning if push fails; do not halt autopilot):
-  ```
-  git push origin {{base_branch}}
-  ```
-  This ensures sprint-status.yaml, git-status.yaml, story files, and any updated artifacts are on main even when story code is on a PR branch.
+  <action>**Commit story artifacts to main** — keeps main in sync even when story code is on a PR branch.
+  1. `git checkout -B {{base_branch}} origin/{{base_branch}}`
+  2. Write git-status.yaml (addon-owned — never touch sprint-status.yaml): `node {{project_root}}/_Sprintpilot/scripts/sync-status.js --story "{{current_story}}" --git-status-file "{{project_root}}/_bmad-output/implementation-artifacts/git-status.yaml" --branch "{{branch_prefix}}{{branch_name}}" --commit "{{story_commit}}" --patch-commits "{{patch_commits_csv}}" --push-status "{{push_status}}" --merge-status "{{merge_status}}" --pr-url "{{pr_url}}" --lint-result "{{lint_result}}" --worktree "{{project_root}}/.worktrees/{{current_story}}" --platform "{{platform}}" --base-branch "{{base_branch}}"`
+  3. Stage artifacts (ignore errors for missing paths): `git add _bmad-output/implementation-artifacts/sprint-status.yaml _bmad-output/implementation-artifacts/git-status.yaml _bmad-output/implementation-artifacts/autopilot-state.yaml _bmad-output/implementation-artifacts/decision-log.yaml _bmad-output/stories/ _bmad-output/planning-artifacts/`
+  4. If `git diff --cached --quiet` exits non-zero: `git commit -m "docs: story {{current_story}} done — {{test_count}} tests{{#if pr_url}}, PR: {{pr_url}}{{/if}}"` then `git push origin {{base_branch}}` (warn on push failure, do not halt).
   </action>
 </check>
 
@@ -890,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>
@@ -897,134 +1147,34 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
   <action>Resolve `{{epic_id}}` (e.g. "1") and `{{epic_title}}` from `{status_file}` for the current epic</action>
   <action>Create task "[epic {{epic_id}}] retrospective" → `in_progress`</action>
 
-  <!-- Retrospective handling is driven by `autopilot.retrospective_mode`
-       in modules/autopilot/config.yaml. See the SKILL AUTOMATABLE REFERENCE
-       table for rationale. The external `bmad-retrospective` skill is
-       NEVER invoked from autopilot — it enters a multi-persona discussion
-       loop under some CLIs. -->
+  <!-- Retrospective: driven by `autopilot.retrospective_mode`. The external
+       `bmad-retrospective` skill is NEVER invoked from autopilot (multi-persona
+       discussion loop under some CLIs). -->
 
   <check if="{{retrospective_mode}} is auto">
-    <!-- Deterministic single-pass retrospective. No persona simulation,
-         no rounds, no external skill call. All inputs are on-disk. -->
-    <action>Collect from `{status_file}` for epic `{{epic_id}}`:
-      - list of done stories with { story-key, title, test_pass_count, patch_count }
-      - epic title, start/end dates if present
-    </action>
-    <action>Collect decision-log entries for epic `{{epic_id}}` from `{decision_log_file}` (match on `story` prefix `{{epic_id}}-` or `phase: autopilot:*` entries tagged to this epic)</action>
-    <action>Identify open risks / carry-over notes from sprint-status (any story with `notes` or `risks` fields, any `workaround` decisions in the log for this epic)</action>
-    <action>Ensure directory `{implementation_artifacts}/retrospectives/` exists</action>
-    <action>Write `{implementation_artifacts}/retrospectives/epic-{{epic_id}}-retrospective.md` using this template:
-    ```markdown
-    # Epic {{epic_id}} — {{epic_title}} — Retrospective
-
-    **Completed:** {current_date}
-    **Stories done:** {{n_done}}/{{n_total}}
-
-    ## Stories
-    {{#each stories}}
-    - **{{story-key}}** — {{title}}
-      - Tests: {{test_pass_count}}
-      - Patches applied: {{patch_count}}
-    {{/each}}
-
-    ## Key decisions
-    {{#each decisions}}
-    - [{{impact}}] {{category}}: {{decision}} — {{rationale}}
-    {{/each}}
-
-    ## Risks carried forward
-    {{#each open_risks}}
-    - {{risk}}
-    {{/each}}
-
-    ## Notes
-    Generated inline by Sprintpilot autopilot per `autopilot.retrospective_mode: auto`.
-    ```
-    </action>
-    <action>Update `{status_file}`:
-      - `epics.{{epic_id}}.status` = `done`
-      - `epics.{{epic_id}}.retrospective_path` = the retrospective file path (relative to project root)
-      - `epics.{{epic_id}}.completed_at` = {current_date}
-    </action>
-    <action>Append decision-log entry:
-      `{ category: workaround, decision: "retrospective generated inline", rationale: "autopilot.retrospective_mode=auto — avoids external skill's multi-persona loop", impact: low, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`
-    </action>
-    <action>Mark retrospective task → `completed`</action>
-    <action>Set `{{completed_skill}}` = `retrospective-auto`</action>
+    <action>Collect from `{status_file}` for epic `{{epic_id}}`: done stories `{ story-key, title, test_pass_count, patch_count }`, epic title, dates if present.</action>
+    <action>Collect decision-log entries for epic `{{epic_id}}` (match `story` prefix `{{epic_id}}-` or `phase: autopilot:*` tagged to this epic). Identify open risks / carry-over notes from any story `notes`/`risks` fields or `workaround` decisions for this epic.</action>
+    <action>Ensure `{implementation_artifacts}/retrospectives/` exists. Read template `{{project_root}}/_Sprintpilot/templates/epic-retrospective.md`, fill mustache placeholders, write to `{implementation_artifacts}/retrospectives/epic-{{epic_id}}-retrospective.md`.</action>
+    <action>Update `{status_file}`: `epics.{{epic_id}}.status = done`, `.retrospective_path = <file>`, `.completed_at = {current_date}`.</action>
+    <action>Append decision-log entry: `{ category: workaround, decision: "retrospective generated inline", rationale: "retrospective_mode=auto", impact: low, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`.</action>
+    <action>Mark retrospective task → `completed`. Set `{{completed_skill}}` = `retrospective-auto`.</action>
   </check>
 
   <check if="{{retrospective_mode}} is stop">
-    <!-- Pause autopilot so user can run /bmad-retrospective interactively.
-         On the next /sprint-autopilot-on the resume logic in step 1 will
-         detect the cleared state and move to the next epic. -->
-    <action>Update `{state_file}`:
-      - `paused_at` = `epic-complete-awaiting-retrospective`
-      - `paused_epic_id` = `{{epic_id}}`
-      - `next_action` = "run /bmad-retrospective interactively for epic {{epic_id}}, then re-run /sprint-autopilot-on"
-    </action>
-    <action>Append decision-log entry:
-      `{ category: workaround, decision: "paused for interactive retrospective", rationale: "autopilot.retrospective_mode=stop", impact: low, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`
-    </action>
-    <action>Mark retrospective task → `completed` (handed off to user)</action>
-    <action>Report:
-    ```
-    Autopilot paused — epic {{epic_id}} complete, retrospective handed off.
-
-    Per `autopilot.retrospective_mode: stop` in
-    _Sprintpilot/modules/autopilot/config.yaml, autopilot does not run the
-    retrospective automatically.
-
-    To continue:
-      1. Run `/bmad-retrospective` interactively for epic {{epic_id}}
-      2. When done, run `/sprint-autopilot-on` to resume with the next epic
-
-    State saved to: {state_file}
-    ```
-    </action>
-    <action>STOP</action>
+    <action>Update `{state_file}`: `paused_at = epic-complete-awaiting-retrospective`, `paused_epic_id = {{epic_id}}`, `next_action = "run /bmad-retrospective interactively for epic {{epic_id}}, then re-run /sprint-autopilot-on"`.</action>
+    <action>Append decision-log entry: `{ category: workaround, decision: "paused for interactive retrospective", rationale: "retrospective_mode=stop", impact: low, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`. Mark retrospective task → `completed`.</action>
+    <action>Report: "Autopilot paused — epic {{epic_id}} complete, retrospective handed off. Run `/bmad-retrospective` interactively for epic {{epic_id}}, then re-run `/sprint-autopilot-on`. State saved to: {state_file}." Then STOP.</action>
   </check>
 
   <check if="{{retrospective_mode}} is skip">
-    <!-- User opted out of retrospective. Record and move on. -->
-    <action>Update `{status_file}`:
-      - `epics.{{epic_id}}.status` = `done`
-      - `epics.{{epic_id}}.retrospective_path` = null
-      - `epics.{{epic_id}}.retrospective_skipped` = true
-      - `epics.{{epic_id}}.completed_at` = {current_date}
-    </action>
-    <action>Append decision-log entry:
-      `{ category: workaround, decision: "retrospective skipped", rationale: "autopilot.retrospective_mode=skip (NOT RECOMMENDED)", impact: medium, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`
-    </action>
-    <action>Mark retrospective task → `completed` (skipped)</action>
-    <action>Set `{{completed_skill}}` = `retrospective-skip`</action>
-    <action>Log: "Epic {{epic_id}} retrospective skipped per config — continuing with next epic"</action>
+    <action>Update `{status_file}`: `epics.{{epic_id}}.status = done`, `.retrospective_path = null`, `.retrospective_skipped = true`, `.completed_at = {current_date}`.</action>
+    <action>Append decision-log entry: `{ category: workaround, decision: "retrospective skipped", rationale: "retrospective_mode=skip (NOT RECOMMENDED)", impact: medium, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`. Mark retrospective task → `completed`. Set `{{completed_skill}}` = `retrospective-skip`.</action>
   </check>
 
-  <!-- GIT: Epic completion — suggest merge, cleanup worktrees -->
   <check if="{{git_enabled}}">
-    <action>**List all epic PR/MR URLs** from `{status_file}` for this epic's stories</action>
-    <action>Report:
-    ```
-    Epic complete — PR/MR summary:
-    {{#each epic_stories}}
-    - {{story-key}}: {{pr_url}}
-    {{/each}}
-
-    Ready to merge. Review PRs and confirm when ready.
-    ```
-    </action>
+    <action>**Epic PR summary** — list all epic PR/MR URLs from `{status_file}` and report as "Epic complete — PR/MR summary: [list]. Ready to merge — review PRs and confirm when ready."</action>
     <check if="{{cleanup_on_merge}} is true">
-      <action>**Cleanup worktrees** for completed stories:
-      For each story in this epic:
-        1. Check if worktree at `.worktrees/{{story-key}}` exists
-        2. Check if clean: `git -C .worktrees/{{story-key}} status --porcelain`
-        3. If clean → `git worktree remove .worktrees/{{story-key}}` + `git worktree prune`
-           Update `{git_status_file}` for this story: `worktree_cleaned: true`
-        4. If dirty → warn user, skip cleanup
-      </action>
-    </check>
-    <check if="{{cleanup_on_merge}} is false">
-      <action>Log: "Worktree cleanup skipped (git.worktree.cleanup_on_merge = false)"</action>
+      <action>**Cleanup worktrees** for completed stories. For each: if `.worktrees/{{story-key}}` exists, check cleanliness via `git -C .worktrees/{{story-key}} status --porcelain`. If clean → `git worktree remove` + `git worktree prune` and set `worktree_cleaned: true` in `{git_status_file}`. If dirty → warn and skip.</action>
     </check>
   </check>
 </check>
@@ -1041,21 +1191,7 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
 
 <step n="8" goal="Save state and continue">
 
-<action>Update `{state_file}`:
-```yaml
-last_updated: {current_datetime}
-current_story: {{current_story}}
-current_bmad_step: {{current_bmad_step}}
-completed_skill: {{completed_skill}}
-next_skill: {{next_skill}}
-session_stories_done: {{session_stories_done}}
-stories_remaining: {{stories_remaining}}
-git_enabled: {{git_enabled}}
-platform: {{platform}}
-in_worktree: {{in_worktree}}
-pr_base: {{pr_base}}
-```
-</action>
+<action>Update `{state_file}` with STATE_FIELDS.</action>
 
 <goto step="2">Continue execution loop</goto>
 
@@ -1090,21 +1226,14 @@ pr_base: {{pr_base}}
   </action>
 </check>
 
-<action>Update `{state_file}`:
-```yaml
-last_updated: {current_datetime}
-current_story: {{current_story}}
-current_bmad_step: {{current_bmad_step}}
-completed_skill: {{completed_skill}}
-next_skill: {{next_skill}}
-session_stories_done: {{session_stories_done}}
-stories_remaining: {{stories_remaining}}
-git_enabled: {{git_enabled}}
-platform: {{platform}}
-in_worktree: {{in_worktree}}
-pr_base: {{pr_base}}
-```
-</action>
+<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>
 
@@ -1144,143 +1273,147 @@ 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>
-<action>Run full test suite — report `N/N passed`</action>
-
-<!-- Generate project documentation after sprint completion -->
-<action>**Generate documentation** — create or update project README and docs.
-Invoke `bmad-document-project` skill to auto-generate documentation from the completed implementation.
-If the skill is not available or fails, generate a minimal README.md:
-- Project name and description (from product brief / PRD)
-- How to install (`npm install` / `pip install` / etc.)
-- How to run (`npm start` / the launch command)
-- How to test (`npm test`)
-- Architecture overview (from architecture doc if it exists)
+<!-- 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>
 
-<!-- GIT: Commit documentation and final artifacts to main -->
+<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}}">
-  <action>**Commit final artifacts and documentation to main**. Run each step; if an early step fails, STOP and log — don't proceed past a failed step. `git add` may fail for missing optional paths (`docs/`, `README.md`); ignore those path-specific errors. Failure of the final push should log a warning but not halt autopilot:
-  ```
-  git checkout -B {{base_branch}} origin/{{base_branch}}
-  git add _bmad-output/ README.md docs/
-  ```
-  Check if anything is staged: `git diff --cached --quiet`. If that exits non-zero, commit:
-  `git commit -m "docs: project documentation and final artifacts"`
-  Then: `git push origin {{base_branch}}`
-  </action>
+  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>Read `{status_file}` and collect:
-  - All completed stories grouped by epic, with their story titles
-  - Total story count, total epic count
-  - Final test count
-  - If git_enabled: all PR/MR URLs, patch counts, dismissed findings per story
+<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>Read `{decision_log_file}` and collect:
-  - All decisions with impact `medium` or `high`
-  - Count of `review-accept` entries (patches applied)
-  - Count of `review-triage` entries (findings dismissed)
-  - Total review rounds (count of code-review invocations)
-  - Per-story summary: patches applied and findings dismissed
+<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>Find the app launch command by checking (in order):
-  1. `run_gui.sh` or `run.sh` in the project root
-  2. `main.py` in the project root
-  3. Check `pyproject.toml`, `package.json`, or `setup.py` for scripts
-  Record as `{{launch_cmd}}`
+<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>
 
-<!-- GIT: Final worktree cleanup — safety net for any worktrees not cleaned during epic completion -->
-<check if="{{git_enabled}}">
-  <action>**Cleanup all remaining worktrees**:
-  Run: `git worktree list --porcelain`
-  For each worktree that is NOT the main worktree, run the following — log and continue on failure; some worktrees may already be gone:
-    `git worktree remove <path> --force`
-  Then: `git worktree prune`
-  </action>
-</check>
+<!-- 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>
 
-<!-- GIT: Release lock -->
-<check if="{{git_enabled}}">
-  <action>Release lock: `node {{project_root}}/_Sprintpilot/scripts/lock.js release`</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>
 
-<action>Delete `{state_file}` — sprint complete</action>
-<action>Mark master task "Sprintpilot — Full Sprint Execution" → `completed`</action>
+<!-- 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>
 
-<action>Report (use exact format):
-```
-╔═══════════════════════════════════════════════════════════════╗
-║                   BMAD AUTOPILOT — REPORT                     ║
-╚═══════════════════════════════════════════════════════════════╝
-
-SUMMARY
-  Stories completed : {{done_count}}/{{total_stories}}
-  Epics completed   : {{done_epics}}/{{total_epics}}
-  Total tests       : {{N}}/{{N}} passed
-{{#if git_enabled}}
-  Platform          : {{platform}}
-{{/if}}
+<!-- Generate project documentation after sprint completion -->
+<action>**Resolve stack** — set `{{stack}}` = `{ name, install_cmd, run_cmd, test_cmd }` using the first successful source:
+
+  1. **`project-context.md`** (glob `**/project-context.md`, canonical `{output_folder}/project-context.md`) — extract from "Technology Stack & Versions" and any install/run/test subsections.
+  2. **`architecture.md`** (`{planning_artifacts}/architecture.md`) — extract from "Tech Stack" / "Runtime" / "Build & Deploy" / "Commands" sections.
+  3. **Manifest heuristics** — map manifest file → stack → idiomatic commands:
+
+  | Manifest | Stack | install / run / test |
+  |---|---|---|
+  | `package.json` | Node/JS/TS | `<pm> install` / `<pm> run start\|dev\|serve` (or `node <bin>`) / `<pm> test` — `<pm>` = `pnpm`/`yarn`/`bun`/`npm` by lockfile |
+  | `pyproject.toml`, `requirements.txt`, `setup.py` | Python | `pip install -r requirements.txt` (or `-e .`) / Django `python manage.py runserver` → Flask → FastAPI `uvicorn app:app` → `python main.py`/`app.py` / `pytest` |
+  | `go.mod` | Go | `go mod download` / `go run .` (or `./cmd/<name>`) / `go test ./...` |
+  | `Cargo.toml` | Rust | `cargo build` / `cargo run` (or `--bin <name>`) / `cargo test` |
+  | `pom.xml` | Java/Kotlin (Maven) | `mvn install` / `mvn spring-boot:run` or `mvn exec:java` / `mvn test` |
+  | `build.gradle(.kts)` | Java/Kotlin (Gradle) | `./gradlew build` / `./gradlew bootRun` or `run` / `./gradlew test` |
+  | `Gemfile` | Ruby | `bundle install` / `rails server` or `bundle exec ruby <entry>` / `bundle exec rspec` |
+  | `*.csproj`/`*.sln` | .NET | `dotnet restore` / `dotnet run` (or `--project`) / `dotnet test` |
+  | `composer.json` | PHP | `composer install` / `php artisan serve` (Laravel) or `php -S localhost:8000 -t public` / `vendor/bin/phpunit` |
+  | `mix.exs` | Elixir | `mix deps.get` / `mix phx.server` or `mix run --no-halt` / `mix test` |
+  | (none of the above) | Explicit launcher | `./run.sh`/`./run_gui.sh`/`./start.sh`, `make run\|start\|dev`, `docker compose up`, `docker build` + `docker run` |
+
+  4. **No match** — all fields `null`. Downstream omits the line; never guess.
+
+  Set `{{launch_cmd}}` = `{{stack.run_cmd}}`.
+  If `{{stack}}` came from (3) and `project-context.md` exists without stack info, log: "Consider running `bmad-generate-project-context` to capture stack commands."
+</action>
 
-STORIES
-{{#each epic}}
-  Epic {{epic_number}}: {{epic_title}}
-  {{#each stories}}
-  ✓ {{story-key}}  — {{test_count}} tests{{#if pr_url}}  PR: {{pr_url}}{{/if}}
-  {{/each}}
-{{/each}}
-{{#if remaining_stories}}
-  Not started:
-  {{#each remaining_stories}}
-  · {{story-key}}
-  {{/each}}
-{{/if}}
+<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>
 
-DECISIONS REQUIRING REVIEW (high/medium impact)
-{{#each medium_high_decisions}}
-  #{{id}}  [{{impact}}] {{story}} / {{phase}}
-      {{decision}}
-      → {{rationale}}
-{{/each}}
-{{#if no_medium_high_decisions}}
-  None — all decisions were low-impact.
-{{/if}}
+<check if="{{git_enabled}}">
+  <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>
 
-  Full log: {decision_log_file}
+<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>
 
-REVIEW FINDINGS APPLIED
-  Patches applied    : {{total_patches}}
-  Findings dismissed : {{total_dismissed}}
-  Review rounds      : {{total_review_rounds}}
+<check if="{{git_enabled}}">
+  <!-- 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>
 
-CODE REVIEW SUMMARY (per story)
-{{#each completed_stories}}
-  {{story-key}} : {{patches_applied}} patches applied, {{findings_dismissed}} dismissed
-{{/each}}
+<!-- State file deletion moved to CRITICAL 7/7 above for reliability. -->
+<action>Mark master task "Sprintpilot — Full Sprint Execution" → `completed`</action>
 
-WHAT TO DO NEXT
-  1. Review decisions marked medium/high above
-{{#if has_pr_urls}}
-  2. Merge open PRs: {{pr_urls_list}}
-{{/if}}
-{{#if launch_cmd}}
-  {{next_number}}. Run the app: {{launch_cmd}}
-{{/if}}
-  {{next_number}}. Manual smoke test checklist:
-{{#each completed_stories}}
-     · [{{story-key}}] {{smoke_test_suggestion}}
-{{/each}}
-```
-</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>
 
 </step>