@ikunin/sprintpilot 2.2.31 → 2.3.0

package/_Sprintpilot/skills/sprintpilot-plan-sprint/workflow.md

@@ -0,0 +1,435 @@
+# Sprintpilot — Sprint Plan Generation
+
+## Purpose
+
+Build (or refresh) `_bmad-output/implementation-artifacts/sprint-plan.yaml`
+— the authoritative sprint plan that drives autopilot story selection,
+DAG-aware reordering, and external-tracker integration. Infers per-epic
++ cross-epic dependencies via piped LLM envelopes (validated server-side
+by `infer-dependencies.js`), lets the user curate which stories belong
+in the active plan, and persists everything atomically.
+
+## Prerequisites
+
+| Artifact | Path | Required |
+|---|---|---|
+| BMad sprint-status | `_bmad-output/implementation-artifacts/sprint-status.yaml` | yes |
+| BMad epics | `_bmad-output/planning-artifacts/epics.md` | yes |
+| BMad architecture | `_bmad-output/planning-artifacts/architecture.md` | yes |
+
+If any required prerequisite is missing, halt with a `user_prompt`
+naming the missing file and the BMad skill that produces it
+(`bmad-sprint-planning`, `bmad-create-epics-and-stories`,
+`bmad-create-architecture`). Do NOT attempt the workflow without them.
+
+## Outputs
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `sprint-plan.yaml` | `_bmad-output/implementation-artifacts/` | Authoritative plan (read by autopilot + resolve-dag) |
+| `sprint-plan-dag.mmd` | `_bmad-output/implementation-artifacts/` | Rendered mermaid DAG (refreshed on every plan write) |
+| Archived legacy | `.archive/dependencies.yaml.migrated` | If a pre-v2.3.0 `_Sprintpilot/sprints/dependencies.yaml` existed |
+
+## Conventions used below
+
+- `<root>` = the project root passed via `--project-root` (or `cwd`).
+- All scripts live under `_Sprintpilot/scripts/` — invoke via `node <path>`.
+- LLM envelopes are JSON; you produce them, the script validates them.
+- On any 3-iteration validation failure (per-epic OR cross-epic), the
+  skill writes `_bmad-output/implementation-artifacts/sprint-plan.yaml.partial`
+  with the last attempted envelope + errors header, writes the sentinel
+  `.sprint-plan-validation-failed`, and halts with a `user_prompt`
+  asking the user to inspect the partial.
+
+---
+
+## Step 1 — Load Inputs
+
+<action>Verify the three required artifacts exist:
+- `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- `_bmad-output/planning-artifacts/epics.md`
+- `_bmad-output/planning-artifacts/architecture.md`
+
+If any is missing, halt with a `user_prompt` naming what's missing.</action>
+
+<action>Read each into memory. Parse epics.md for the list of epic IDs.
+Parse sprint-status.yaml for the list of story keys under
+`development_status:` (or `stories:` for the alternate shape).</action>
+
+<action>Read the existing plan if present:
+```
+node _Sprintpilot/scripts/sprint-plan.js read --project-root <root>
+```
+Note: `exists: true/false` + the full plan body when present. Used by
+Step 3 to compute staleness and decide which epics need re-inference.</action>
+
+---
+
+## Step 2 — Migrate Legacy Dependencies (One-Shot)
+
+<action>Check whether a pre-v2.3.0 sidecar exists at
+`_Sprintpilot/sprints/dependencies.yaml`. If it does AND `sprint-plan.yaml`
+is absent OR has an empty `dependencies.stories` block, run the
+one-shot migration:
+```
+node _Sprintpilot/scripts/infer-dependencies.js migrate --project-root <root>
+```
+The migrate command imports the legacy `stories:` + `overrides:` blocks
+into the new plan, drops the legacy `epics:` block with a warning,
+and moves the old file to `.archive/dependencies.yaml.migrated`.
+
+If `migrated: false` and `reason: 'no_legacy_file'` — proceed silently.
+If `migrated: false` for any other reason — surface the message in a
+`user_prompt` and ask whether to continue with a fresh plan.</action>
+
+---
+
+## Step 3 — Staleness Check
+
+<action>Compute which epics need re-inference. The cheap way is to
+ask the orchestrator helper:
+```
+node -e "
+const m = require('./_Sprintpilot/lib/orchestrator/sprint-plan.js');
+console.log(JSON.stringify(m.planStaleness({projectRoot: process.cwd()})));
+"
+```
+Returns `{ stale: bool, reason, missing_keys?, removed_keys? }`.
+
+Decision matrix:
+
+| stale | reason | action |
+|---|---|---|
+| false | — | Skip Step 4 entirely (plan is fresh). Go to Step 5 unless invoked via /sprintpilot-plan-sprint with a "rebuild from scratch" intent. |
+| true | `missing` | Run Step 4 for EVERY epic in epics.md. |
+| true | `migration_needed` | Step 2 should have handled this — re-check; if still missing, run Step 4 for every epic. |
+| true | `added_stories` | Run Step 4 only for the epics whose stories appear in `missing_keys`. |
+| true | `removed_stories` | Run Step 4 for the epics affected (a missing story means the per-epic graph for that epic is stale). |
+| true | `corrupt` | Halt with a `user_prompt` showing the corruption error + offering archive+regenerate. |
+
+For hand-authored plans (no AUTO-INFERRED marker AND user-direct invocation
+of /sprintpilot-plan-sprint without explicit "rebuild" intent), confirm
+with a `user_prompt` before regenerating: "An existing plan has hand
+edits in the `dependencies` block. Proceed with regeneration (loses the
+edits) or skip per-epic inference and just refresh DAG render?"</action>
+
+---
+
+## Step 4 — Per-Epic Inference
+
+<action>For each epic that needs (re-)inference, run a tight loop:
+
+1. Generate the prompt:
+   ```
+   node _Sprintpilot/scripts/infer-dependencies.js scaffold-prompt --epic <id> --project-root <root>
+   ```
+   Stdout is the literal prompt — feed it back to yourself in chat as
+   the "next user message" to infer the dependencies. Read the four
+   files the prompt names; do not improvise based on memory.
+
+2. Produce a JSON envelope of the EXACT shape:
+   ```json
+   {
+     "version": 1,
+     "epic": "<id>",
+     "dependencies": { "<story-key>": ["<dep-key>", ...] },
+     "rationale":   { "<story-key>": "1 sentence quoting the AC/file/architecture line" }
+   }
+   ```
+   Stories with NO inbound deps are omitted from `dependencies`. Every
+   listed key needs a non-empty rationale. Cross-epic edges go through
+   Step 5 — don't put them here.
+
+3. Validate via dry-run:
+   ```
+   echo '<envelope>' | node _Sprintpilot/scripts/infer-dependencies.js dry-run --epic <id> --project-root <root>
+   ```
+   On `valid: true`, proceed. On `valid: false`, the response carries
+   an `errors[]` array — fix the envelope and retry. Max 3 iterations
+   per epic. On 3rd failure, save the partial + sentinel and halt
+   (see "Conventions" above).
+
+4. Commit the envelope:
+   ```
+   echo '<envelope>' | node _Sprintpilot/scripts/infer-dependencies.js write --epic <id> --project-root <root>
+   ```
+   `wrote: true, edges_inferred, edges_added, edges_removed` confirms
+   success. The script writes into `plan.dependencies.stories.*` while
+   preserving entries for other epics and the `overrides:` block.</action>
+
+---
+
+## Step 5 — Cross-Epic Detection
+
+<action>Now that per-epic edges are in place, ask the LLM whether
+any edges cross epic boundaries:
+
+1. Generate the cross-epic prompt:
+   ```
+   node _Sprintpilot/scripts/infer-dependencies.js scaffold-prompt --cross-epic --project-root <root>
+   ```
+
+2. Produce a JSON envelope:
+   ```json
+   {
+     "version": 1,
+     "cross_epic_deps": [
+       { "from_story": "<key>", "to_story": "<key>", "rationale": "<≤200 chars>" }
+     ]
+   }
+   ```
+   `from_story` depends on `to_story`. Both keys must belong to
+   DIFFERENT epics. If no cross-epic deps detected, send
+   `cross_epic_deps: []`.
+
+3. Validate via dry-run:
+   ```
+   echo '<envelope>' | node _Sprintpilot/scripts/infer-dependencies.js dry-run --cross-epic --project-root <root>
+   ```
+   Validator checks: keys exist in sprint-status, from/to epics differ,
+   rationale present (≤200 chars), no duplicate of per-epic edges,
+   no cycle in the combined graph. Max 3 iterations.
+
+4. Present each surviving edge to the user with its rationale:
+   ```
+   Cross-epic edge detected:
+     2-1-foo depends on 1-3-add-auth
+     Rationale: needs auth context from 1-3 before integration
+     [a] accept  [r] reject  [s] skip remaining edges
+   ```
+   Accept-all, reject-all, or per-edge. Rejected edges drop out;
+   accepted edges go through to write.
+
+5. Commit accepted edges:
+   ```
+   echo '<accepted envelope>' | node _Sprintpilot/scripts/infer-dependencies.js write-cross-epic --project-root <root>
+   ```</action>
+
+---
+
+## Step 6 — Issue Tracker Setup (Optional)
+
+<action>Ask the user (single user_prompt):
+> "Do you want to link stories to an external issue tracker
+> (Jira / Linear / GitHub / GitLab)? [y/N]"
+
+On `n` or skip — proceed to Step 7 without writing the `issue_tracker:`
+block.
+
+On `y` — collect:
+- `provider`: one of `jira`, `linear`, `github`, `gitlab`
+- `base_url`: full URL prefix (e.g., `https://co.atlassian.net`)
+- `project_key`: the tracker's project key (e.g., `PROJ` for Jira)
+
+Then call the sprint-plan primitive. Currently the simplest path is
+to read the plan, set `plan.issue_tracker = { provider, base_url, project_key }`,
+and write the whole plan back via `node _Sprintpilot/scripts/sprint-plan.js write`
+(piping the modified plan to stdin). The script validates schema and writes
+atomically.</action>
+
+---
+
+## Step 7 — Issue ID Capture (Optional)
+
+<action>Ask the user (single user_prompt):
+> "Capture external issue IDs for each epic/story? [Y]es / [n]o
+>  / [s]kip remaining for this epic / [p]attern (sequential IDs)"
+
+On `n` — proceed to Step 8 without setting any `issue_id` fields.
+
+On `Y` — loop through epics and stories. For each entity:
+> "Issue ID for epic 1 (or skip)?"
+> "Issue ID for story 1-3-add-auth (or skip)?"
+
+`p` mode prompts once for a prefix (e.g., `PROJ-`) + starting number;
+the skill assigns sequential IDs (`PROJ-100`, `PROJ-101`, …).
+
+**Validation rules** — `setIssueId` rejects these inputs (re-prompt if
+they appear; don't retry the same value):
+- Any of: `[ ] < > | ; & \n \r` or ASCII control characters
+- Any Unicode RTL/LTR override marks (`‪`–`‮`, `⁦`–`⁩`)
+- Length > 200 chars
+
+Legitimate tracker IDs from Jira (`PROJ-101`), Linear (`LIN-42`),
+GitHub (`org/repo#123`), and GitLab don't contain any of these. If a
+user enters something like `PROJ;101` or pastes a URL with embedded
+brackets, the validator throws — show the error and ask for a clean
+ID. Don't loop on the same broken input.
+
+For each captured ID, update the plan via read → mutate → write. The
+relevant primitive is `setIssueId(entity_key, issue_id, { projectRoot })`
+in `sprint-plan.js`; from this skill the simplest path is to bulk-edit
+the plan in memory and write it once at the end of the loop.
+
+Bulk skip options ensure this step doesn't become tedious on sprints
+with many stories.</action>
+
+---
+
+## Step 8 — Finalize Dependencies in Plan
+
+<action>By this point Steps 4 + 5 have written `plan.dependencies.stories`
+and `plan.cross_epic_deps`. Step 6/7 may have edited `issue_tracker`
+and per-entity `issue_id`. Re-read the plan once to confirm:
+```
+node _Sprintpilot/scripts/sprint-plan.js read --project-root <root>
+```
+The plan should validate cleanly. If `exists: true, error: ...` →
+something went wrong; halt with the error.</action>
+
+---
+
+## Step 9 — Build the Sprint-Wide DAG
+
+<action>Compute the topological layering for presentation:
+```
+node _Sprintpilot/scripts/resolve-dag.js graph --project-root <root>
+```
+Returns `{ nodes, edges, layers, width, cycle }`. If `cycle.length > 0`,
+the combined intra + cross-epic graph has a cycle (validator should
+have caught this earlier; if reached, halt with the offending nodes
+and ask the user to remove the bad edge).</action>
+
+---
+
+## Step 10 — Present the DAG
+
+<action>Render a text-mode topological tree to the user:
+```
+Layer 1 (parallel-eligible width: <N>):
+  - 1-1-bootstrap
+  - 2-1-foo                          ← cross-epic upstream of 1-3
+Layer 2:
+  - 1-2-models
+Layer 3:
+  - 1-3-add-auth  (depends on: 1-1, 1-2, 2-1)
+...
+```
+
+Highlight cross-epic edges with `←` or `cross-epic →` annotations.
+Show summary stats: total stories, total epics, max layer width
+(indicates parallel potential for v2.4.0), count of missing issue IDs.</action>
+
+<action>Also write the mermaid DAG file for visual review:
+```
+node _Sprintpilot/scripts/resolve-dag.js render --format mermaid --project-root <root>
+```
+Report the path to the user:
+> "DAG rendered to `_bmad-output/implementation-artifacts/sprint-plan-dag.mmd`
+> — preview in any markdown viewer (GitHub, VS Code with Mermaid Preview, etc.)."</action>
+
+---
+
+## Step 11 — Curation
+
+<action>Ask the user which stories belong in this sprint plan:
+> "Which stories do you want to run in this sprint?
+>  Default: ALL non-done stories.
+>  [Enter] accept default  [e] edit selection  [a:KEY] add  [r:KEY] remove"
+
+`Default: ALL non-done` means every story in sprint-status whose
+status is not `done`. Excluded stories carry `plan_status: excluded`
+in the plan — they remain visible in the file for context (e.g., as
+upstreams of included stories) but are NOT picked by the queue resolver.</action>
+
+<action>On `e` (edit), present a numbered list with `[x]` for included
+and `[ ]` for excluded; the user toggles entries by number.</action>
+
+---
+
+## Step 12 — Validate Selection
+
+<action>For each story marked included, every transitive upstream
+(intra-epic AND cross-epic) must be either ALSO included OR already
+done in sprint-status. Compute via the orchestrator helper:
+```
+node -e "
+const m = require('./_Sprintpilot/lib/orchestrator/sprint-plan.js');
+const plan = require('./_Sprintpilot/scripts/sprint-plan.js').read({projectRoot: process.cwd()});
+const proposed = [/* user-selected keys */];
+console.log(JSON.stringify(m.validateOrdering(proposed, plan, {projectRoot: process.cwd()})));
+"
+```
+Returns `{ valid, violations: [{story, upstream, suggestion}] }`.
+
+On `valid: false`, present each violation:
+> "Story `1-3-add-auth` (included) depends on `1-1-bootstrap` which is
+>  not in the plan and not done. Options:
+>  [a] add `1-1-bootstrap` to the plan
+>  [r] remove `1-3-add-auth` from the plan
+>  [x] exclude `1-3-add-auth` (keeps it visible but won't run)"
+
+Loop until `valid: true`. Excluded stories carry `plan_status: excluded`
+and the validator treats them as terminal.</action>
+
+---
+
+## Step 13 — Write Plan
+
+<action>Build the final plan object in memory:
+- `schema_version: 1`
+- `source: 'skill' | 'auto' | 'cli'` (use `auto` when invoked via
+  `template_slots.auto: true`, `skill` otherwise)
+- `plan_id`: keep existing if re-running; generate fresh on first
+  curation
+- `epics: []` — per-epic metadata captured in Step 1 (id, title)
+- `stories: []` — per-story entries with `key`, `epic`, `title`,
+  `plan_status` (`pending` for included, `excluded` for excluded),
+  `issue_id` (from Step 7), `priority` (1-indexed in topological order),
+  `upstream` (denormalized from `plan.dependencies.stories.<key>.depends_on`),
+  `cross_epic_upstream` (denormalized from `plan.cross_epic_deps`),
+  `added_by: 'skill'`, `added_at`
+- `dependencies`, `cross_epic_deps`, `overrides`, `notes` — preserved
+  from Steps 4-7
+- `status.last_run_outcome: 'success'`, `status.last_run_at: <now>`,
+  `status.last_error: null`
+
+Pipe to write:
+```
+echo '<plan-json>' | node _Sprintpilot/scripts/sprint-plan.js write --project-root <root>
+```
+The script validates schema, stamps `generated`, and atomically writes
+via tmp+rename.</action>
+
+<action>Re-render the DAG to reflect any curation changes:
+```
+node _Sprintpilot/scripts/resolve-dag.js render --format mermaid --project-root <root>
+```</action>
+
+---
+
+## Step 14 — Report
+
+<action>Summarize what was written:
+> "Sprint plan written to
+> `_bmad-output/implementation-artifacts/sprint-plan.yaml`.
+>
+> - **N** stories planned (M epics)
+> - **X** cross-epic edges
+> - **Y** stories excluded (kept for context)
+> - **Z** stories without issue IDs
+>
+> First 5 in execution order:
+>   1. 1-1-bootstrap
+>   2. 1-2-models
+>   3. ...
+>
+> Run `/sprint-autopilot-on` to begin execution, or
+> `/sprintpilot-plan-sprint` again to refine."</action>
+
+<action>If invoked via `template_slots.auto: true` or `replan: true`,
+keep the summary shorter (1-2 sentences) and return cleanly so the
+autopilot session resumes; do not block on confirmation.</action>
+
+---
+
+## Failure modes
+
+| Symptom | Recovery |
+|---|---|
+| Prerequisite artifact missing | Halt with `user_prompt` naming the missing file + the BMad skill that produces it. |
+| 3 consecutive validation failures (per-epic OR cross-epic) | Save `sprint-plan.yaml.partial` + `.sprint-plan-validation-failed` sentinel; halt asking the user to inspect. |
+| Cycle in combined intra+cross graph | Halt with the offending nodes; ask the user to remove or re-rationalize the bad edge. |
+| Plan write fails (disk full, permission) | The atomic tmp+rename is all-or-nothing — no torn state. Halt with the error message. |
+| `sprint-plan.yaml` corrupt on entry to Step 3 | Offer archive+regenerate via `user_prompt`. |
+| Skill invoked but `sprint-status.yaml` is empty | No stories to plan; halt and ask the user to run `bmad-sprint-planning` first. |

package/_Sprintpilot/skills/sprintpilot-sprint-progress/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: sprintpilot-sprint-progress
+description: 'Synthesize current sprint execution progress with LLM-layered judgment. Reads sprint-plan.yaml, sprint-status.yaml, and the autopilot ledger via `autopilot progress`; highlights stalls, repeated verify failures, retry loops, and stuck phases; suggests the next action (continue, narrow to a specific story, reorder, replan, abort). Use when you want a quick health check between autopilot sessions without scrolling through the raw ledger.'
+---
+
+## STOP — read this entire file before doing anything
+
+This skill is a **read-only diagnostic**. It does not change sprint-plan.yaml,
+sprint-status.yaml, or any persisted autopilot state. The goal is to produce
+a concise human-readable summary of where execution stands and what (if
+anything) the user should do about it.
+
+Follow **`./workflow.md`** verbatim. The three steps it lists are:
+
+1. Collect the structured snapshot via `autopilot progress --json`.
+2. Pull recent ledger entries for halt / verify / step context.
+3. Synthesize a brief progress report with LLM judgment + one
+   recommended next action.
+
+### Never improvise
+
+- **No file writes.** This skill is observational. If the user wants to
+  reorder, add stories, mark something skipped, or replan — point them
+  at the appropriate user_input command or `/sprintpilot-plan-sprint`.
+  Don't try to fix things from this skill.
+- **No state interpretation beyond what's in the ledger.** Don't
+  speculate about why a verify failed — just report what the ledger
+  says and recommend the user look at the relevant file.
+- **No long-form output by default.** Default mode is ≤15 lines. If
+  the user asks for more detail, narrow to a story and read its
+  recent step events.
+
+### When to invoke
+
+- Between autopilot sessions to check whether anything halted that
+  needs intervention.
+- When you (the LLM) just finished a long batch of stories and want
+  to know if anything's stuck before suggesting next moves.
+- When the user asks "how's the sprint going?" / "where are we?" /
+  "is autopilot stuck?".
+
+### When NOT to invoke
+
+- For machine-readable output: call
+  `node _Sprintpilot/bin/autopilot.js progress --json` directly. This
+  skill adds LLM synthesis on top — pure JSON consumers don't need it.
+- For full sprint reports: that's `bmad-sprint-status` (BMad-native,
+  reads sprint-status.yaml only).
+- For build / deploy / CI status: not this skill's domain.
+
+---
+
+Follow the instructions in ./workflow.md.

package/_Sprintpilot/skills/sprintpilot-sprint-progress/workflow.md

@@ -0,0 +1,169 @@
+# Sprintpilot — Sprint Progress Check
+
+## Purpose
+
+Produce a concise health check of the current sprint's autopilot
+execution. Reads the structured progress snapshot, recent halts /
+verify failures, and step-level events; layers brief judgment on top
+to highlight what (if anything) needs attention.
+
+## Outputs
+
+- A ≤15-line human-readable summary printed to chat.
+- A single recommended next action (or "nothing to do — autopilot is
+  healthy / idle").
+
+No file writes. No state mutations.
+
+## Conventions
+
+- `<root>` = project root (where `_bmad-output/` lives).
+- All shell-outs use `node` (no global install assumed).
+- On any error (no plan, missing ledger, etc.), degrade gracefully —
+  print what you DO know and skip the parts you don't. The user gets
+  a partial answer rather than a halt.
+
+---
+
+## Step 1 — Collect the Structured Snapshot
+
+<action>Run the progress CLI in JSON mode:
+```
+node _Sprintpilot/bin/autopilot.js progress --project-root <root> --json
+```
+Parse the response. Key fields:
+- `plan_present` — false → project running in sprint-status order; the
+  rest of the analysis is naturally lighter.
+- `plan_id`
+- `current_story` / `current_step`
+- `sprint_progress` — `{ total, done, pending, skipped, excluded, source }`
+- `recent_events` — last 3 `story_step_*` ledger entries.
+
+Don't fail if the command exits non-zero (e.g., missing project root).
+Capture stderr and treat as "unknown progress" — proceed with Step 2
+which still produces useful output.</action>
+
+---
+
+## Step 2 — Pull Recent Halt / Verify Context
+
+<action>Read the tail of the ledger to identify any unresolved
+halts, verify rejections, or repeated step-failure loops. Inline node
+is the lightest path:
+
+```
+node -e "
+const l = require('./_Sprintpilot/lib/orchestrator/action-ledger.js');
+const entries = l.read({projectRoot: process.cwd()}, {limit: 40});
+const interesting = entries.filter(e =>
+  e.kind === 'halt' ||
+  e.kind === 'verify_rejected' ||
+  e.kind === 'plan_exhausted' ||
+  e.kind === 'plan_reorder_rejected' ||
+  e.kind === 'auto_derive_emitted' ||
+  e.kind === 'plan_migrated'
+);
+process.stdout.write(JSON.stringify(interesting));
+"
+```
+
+Look for:
+- **`halt` with reason in {`autopilot_lock_held`, `worktree_orphans_detected`,
+  `plan_exhausted`, `user_pause`, `user_replan_sprint`, `user_abort_sprint`}**
+  — autopilot is stopped and needs user attention.
+- **`verify_rejected` with `consecutive >= 3`** — autopilot is stuck in
+  a retry loop; the LLM may need to re-read the failing artifact.
+- **`plan_reorder_rejected`** — a recent reorder violated the DAG;
+  the user has unresolved input pending.
+- **Repeated `story_step_started` for the same story+phase without
+  matching `story_step_completed`** — phase entered but never finished;
+  could indicate a wedged session.
+
+Don't fail if the ledger is empty (greenfield project, never run).
+Just note "no execution history yet" and proceed.</action>
+
+---
+
+## Step 3 — Synthesize the Report
+
+<action>Render a single brief block to chat following this template
+(omit any line that doesn't apply):
+
+```
+Sprint progress
+  Plan:     <plan_id> — <done>/<total> done (<pending> pending,
+            <skipped> skipped, <excluded> excluded)
+  Bar:      [=====     ] <pct>%
+  Tracker:  <linked>/<total> stories linked to <provider> (<project_key>)   ← only when issue_tracker set
+  Current:  <story_key> [<issue_id>] (step: <phase>)   OR   "idle"
+            ↑ issue_id bracket only when set on this story
+  Recent:   <kind> <story> [<issue_id>] / <phase> (<elapsed>s ago)
+            <kind> <story> [<issue_id>] / <phase> (<elapsed>s ago)
+
+Health:    <one of: HEALTHY | STALLED | NEEDS-INPUT | EXHAUSTED | NO-PLAN>
+Reason:    <one short sentence>
+Suggest:   <one concrete next action OR "continue running">
+```
+
+The `autopilot progress --json` response carries the lookup data:
+- `current_issue_id` — the issue_id of the currently-running story (or null).
+- `issue_tracking` — `{provider, project_key, base_url, total, linked, coverage}`
+  when an issue_tracker is configured; null otherwise (omit the Tracker
+  line entirely when null — don't surface zeros as noise).
+- Each `recent_events[]` entry carries an `issue_id` field (or null).
+
+Always include the `[<issue_id>]` bracket when the field is non-null;
+omit it when null. Don't write "[no issue]" or similar — silence
+communicates "not tracked" cleanly.
+
+**Health classification:**
+
+| Signal | Health | Suggest |
+|---|---|---|
+| `plan_present=false` AND no halts in last 40 | NO-PLAN | "Continue in sprint-status order, or run /sprintpilot-plan-sprint to enable dependency-aware ordering." |
+| Most-recent halt is `plan_exhausted` | EXHAUSTED | "Run /sprintpilot-plan-sprint to add more stories, or `autopilot start --no-auto-plan` to continue in sprint-status order." |
+| Most-recent halt is `user_pause` | NEEDS-INPUT | "Resume with `autopilot start`." |
+| Most-recent halt is `user_replan_sprint` | NEEDS-INPUT | "Next `autopilot start` will invoke /sprintpilot-plan-sprint." |
+| `verify_rejected` with `consecutive >= 3` in last 5 entries | STALLED | "Inspect the failing artifact named in `verify_result.issues`; consider `user_input { kind: 'force_continue' }` only if you've manually resolved the issue." |
+| `plan_reorder_rejected` more recent than any subsequent reorder_queue | NEEDS-INPUT | "Reorder violations exist; revise the order to respect the DAG before sending another reorder_queue." |
+| No halts, current_story present, current_step is a valid phase | HEALTHY | "Continue running; nothing requires attention." |
+| No halts, no current_story, sprint_progress.pending > 0 | HEALTHY | "Run `autopilot start` to pick up the next pending story." |
+| No halts, no current_story, sprint_progress.pending == 0 | HEALTHY | "Sprint complete; consider running the bmad-retrospective skill if not already done." |
+
+Default to HEALTHY when classification is ambiguous — don't manufacture
+alarm.</action>
+
+<action>If the user invoked the skill with a story name argument
+(e.g., `/sprintpilot-sprint-progress 1-3-add-auth`), also call:
+```
+node _Sprintpilot/bin/autopilot.js progress --project-root <root> --story <story-key> --json
+```
+And append a one-block "Story detail" section showing that story's
+plan entry. When `issue_id` is non-null, prominently display it on its
+own line (it's the primary cross-reference back to the user's issue
+tracker):
+
+```
+Story: <story_key>
+  Issue:        <issue_id>       ← omit line when null
+  Epic:         <epic>
+  Plan status:  <plan_status>
+  BMad status:  <bmad_status>
+  Priority:     <priority>
+  Current step: <current_step>   ← omit when not running
+  Completed:    <completed_at>   ← omit when not done
+```
+
+Do not repeat the full sprint summary in this mode — just the focused
+story block.</action>
+
+---
+
+## Failure modes
+
+| Symptom | Recovery |
+|---|---|
+| `autopilot progress` exits non-zero (missing project root, etc.) | Capture stderr; print "Progress CLI unavailable: <stderr first line>"; still attempt Step 2. |
+| Ledger file missing | Print "No execution history yet — sprint hasn't started"; skip Step 2 analysis; suggest `autopilot start`. |
+| Plan file corrupt | Print "sprint-plan.yaml unreadable (run `node _Sprintpilot/scripts/sprint-plan.js read --project-root .` to inspect)"; do NOT auto-archive — that's user's call. |
+| Recent ledger has 0 entries | Note "Ledger is empty — autopilot hasn't run yet or was reset"; skip halt analysis. |