refactor(quick-dev): tighten story-key resolution prompt

Remove mechanical details the LLM can infer; keep only the
collision-prevention constraint.

docs/cs/explanation/analysis-phase.md

@@ -5,66 +5,66 @@ sidebar:
   order: 1
 ---
 
-Fáze analýzy (fáze 1) vám pomůže jasně promyslet váš produkt, než se zavážete k jeho budování. Každý nástroj v této fázi je volitelný, ale pokud analýzu úplně vynecháte, váš PRD bude postavený na domněnkách místo na poznatcích.
+Fáze analýzy (fáze 1) vám pomůže jasně si promyslet váš produkt, než se pustíte do jeho tvorby. Každý nástroj v této fázi je volitelný, ale úplné vynechání analýzy znamená, že váš PRD je postaven na předpokladech namísto vhledu.
 
 ## Proč analýza před plánováním?
 
-PRD odpovídá na otázku „co bychom měli vybudovat a proč?“. Když do něj vložíte vágní úvahy, dostanete vágní PRD — a každý následující dokument tu vágnost zdědí. Architektura postavená na slabém PRD udělá špatné technické sázky. Stories odvozené ze slabé architektury minou hraniční případy. Náklady se vrší.
+PRD odpovídá na otázku „Co bychom měli postavit a proč?“. Pokud jej nakrmíte vágním myšlením, získáte vágní PRD — a každý navazující dokument tuto vágnost zdědí. Architektura postavená na slabém PRD sází na špatnou techniku. Příběhy odvozené ze slabé architektury opomíjejí okrajové případy. Náklady se zvyšují.
 
-Analytické nástroje existují proto, aby váš PRD byl ostrý. Útočí na problém z různých úhlů — kreativní průzkum, realita trhu, jasnost ohledně zákazníka, proveditelnost — takže když si sednete s PM agentem, víte, co stavíte a pro koho.
+Existují analytické nástroje, které vám PRD zostří. Napadají problém z různých úhlů — kreativní průzkum, realita trhu, jasnost zákazníka, proveditelnost — takže v době, kdy sedíte s agentem PM, víte, co a pro koho stavíte.
 
 ## Nástroje
 
 ### Brainstorming
 
-**Co to je.** Facilitované kreativní sezení využívající osvědčené techniky ideace. AI působí jako kouč, který z vás tahá nápady prostřednictvím strukturovaných cvičení — negeneruje nápady za vás.
+**Co to je.** Zprostředkované tvůrčí sezení s využitím osvědčených technik generování nápadů. AI funguje jako kouč, který z vás tahá nápady prostřednictvím strukturovaných cvičení — negeneruje nápady za vás.
 
-**Proč je tu.** Surové nápady potřebují prostor k rozvoji, než se uzamknou do požadavků. Brainstorming ten prostor vytváří. Je obzvlášť cenný, když máte problémovou doménu, ale žádné jasné řešení, nebo když chcete prozkoumat více směrů, než se zavážete.
+**Proč je to tady.** Neotřelé nápady potřebují prostor pro rozvoj, než se zakotví v požadavcích. Brainstorming tento prostor vytváří. Je cenný zejména tehdy, když máte problémovou oblast, ale nemáte jasné řešení, nebo když chcete prozkoumat více směrů, než se k něčemu zavážete.
 
-**Kdy ho použít.** Máte mlhavou představu o tom, co chcete vybudovat, ale ještě jste ji nevykrystalizovali do konkrétního konceptu. Nebo máte koncept, ale chcete ho otestovat proti alternativám.
+**Kdy jej použít.** Máte nejasnou představu o tom, co chcete vytvořit, ale nemáte vykrystalizovaný koncept. Nebo máte koncept, ale chcete ho otestovat pod tlakem oproti alternativám.
 
-Viz [Brainstorming](./brainstorming.md) pro podrobnější pohled na průběh sezení.
+Viz [Brainstorming](./brainstorming.md), kde se dozvíte, jak relace fungují.
 
-### Výzkum (tržní, doménový, technický)
+### Výzkum (trhu, domény, technický)
 
-**Co to je.** Tři cílené výzkumné workflow zkoumající různé dimenze vašeho nápadu. Tržní výzkum prozkoumá konkurenci, trendy a nálady uživatelů. Doménový výzkum buduje odborné znalosti a terminologii. Technický výzkum hodnotí proveditelnost, architektonické možnosti a přístupy k implementaci.
+**Co to je.** Tři cílené pracovní postupy výzkumu, které zkoumají různé rozměry vašeho nápadu. Výzkum trhu zkoumá konkurenci, trendy a nálady uživatelů. Doménový výzkum vytváří odborné znalosti v daném oboru a terminologii. Technický výzkum hodnotí proveditelnost, možnosti architektury a přístupy k implementaci.
 
-**Proč je tu.** Budovat na domněnkách je nejrychlejší cesta k vytvoření něčeho, co nikdo nepotřebuje. Výzkum uzemní váš koncept v realitě — jací konkurenti už existují, s čím uživatelé skutečně bojují, co je technicky proveditelné a jaká specifická odvětvová omezení vás čekají.
+**Proč je to tady.** Stavět na předpokladech je nejrychlejší způsob, jak vytvořit něco, co nikdo nepotřebuje. Výzkum zakládá váš koncept na realitě — co již existuje u konkurence, s čím uživatelé skutečně bojují, co je technicky proveditelné a jakým omezením specifickým pro dané odvětví budete čelit.
 
-**Kdy ho použít.** Vstupujete do neznámé domény, tušíte, že existují konkurenti, ale ještě jste je nezmapovali, nebo váš koncept závisí na technických schopnostech, které jste dosud neověřili. Spusťte jeden, dva nebo všechny tři — každý stojí samostatně.
+**Kdy ho použít.** Vstupujete do neznámé oblasti, tušíte, že konkurence existuje, ale nemáte ji zmapovanou, nebo váš koncept závisí na technických možnostech, které nemáte ověřené. Proveďte jeden, dva nebo všechny tři — každý z nich je samostatný.
 
 ### Product Brief
 
-**Co to je.** Řízená discovery session, která vytvoří 1–2stránkový executive summary vašeho produktového konceptu. AI působí jako kolaborativní Business Analyst a pomáhá vám formulovat vizi, cílovou skupinu, hodnotovou nabídku a rozsah.
+**Co to je.** Řízené zjišťovací sezení, jehož výsledkem je 1–2stránkové shrnutí vašeho konceptu produktu. AI funguje jako spolupracující obchodní analytik, který vám pomůže formulovat vizi, cílovou skupinu, nabídku hodnoty a rozsah.
 
-**Proč je tu.** Product brief je mírnější cesta do plánování. Zachytí vaši strategickou vizi ve strukturovaném formátu, který přímo vstupuje do tvorby PRD. Funguje nejlépe, když už jste si svým konceptem poměrně jistí — víte, kdo je zákazník, jaký je problém a přibližně co chcete vybudovat. Brief toto myšlení organizuje a zaostří.
+**Proč tu je.** Produktový brief je jemnější cestou k plánování. Zachycuje vaši strategickou vizi ve strukturovaném formátu, který se přímo promítá do tvorby PRD. Nejlépe funguje, když jste již o svém konceptu přesvědčeni — znáte zákazníka, problém a zhruba víte, co chcete vytvořit. Brief tyto úvahy uspořádá a vyostří.
 
-**Kdy ho použít.** Váš koncept je poměrně jasný a chcete ho efektivně zdokumentovat před vytvořením PRD. Jste si jistí směrem a nepotřebujete, aby vaše předpoklady byly agresivně zpochybňovány.
+**Kdy jej použít.** Váš koncept je relativně jasný a chcete jej efektivně zdokumentovat ještě před vytvořením PRD. Jste si jisti svým směřováním a nepotřebujete své předpoklady agresivně zpochybňovat.
 
 ### PRFAQ (Working Backwards)
 
-**Co to je.** Metodologie Working Backwards od Amazonu adaptovaná jako interaktivní výzva. Napíšete tiskovou zprávu oznamující váš hotový produkt dříve, než existuje jediný řádek kódu, a pak odpovíte na nejtěžší otázky, které by zákazníci a stakeholdeři položili. AI působí jako neúnavný, ale konstruktivní produktový kouč.
+**Co to je.** Metodika Working Backwards společnosti Amazon upravená jako interaktivní výzva. Napíšete tiskovou zprávu oznamující váš hotový produkt dříve, než existuje jediný řádek kódu, a pak odpovíte na nejtěžší otázky, které by vám zákazníci a zainteresované strany položili. Umělá inteligence funguje jako neúprosný, ale konstruktivní produktový kouč.
 
-**Proč je tu.** PRFAQ je náročnější cesta do plánování. Vynucuje si jasnost zaměřenou na zákazníka tím, že vás nutí obhájit každé tvrzení. Pokud nedokážete napsat přesvědčivou tiskovou zprávu, produkt není připravený. Pokud odpovědi na FAQ odhalí mezery, jsou to mezery, které byste jinak objevili mnohem později — a mnohem dráž — během implementace. Tato výzva odhalí slabé myšlení brzy, když je oprava nejlevnější.
+**Proč je to tady.** PRFAQ je přísná cesta k plánování. Vynucuje si jasnost v zájmu zákazníka tím, že vás nutí obhájit každé tvrzení. Pokud nedokážete napsat přesvědčivou tiskovou zprávu, produkt není připraven. Pokud odpovědi na časté dotazy zákazníků odhalí nedostatky, jsou to nedostatky, které byste objevili mnohem později — a nákladněji — při implementaci. Hozená rukavice odhalí slabé myšlení v rané fázi, kdy je nejlevnější ho opravit.
 
-**Kdy ho použít.** Chcete svůj koncept podrobit zátěžovému testu, než vynaložíte zdroje. Nejste si jistí, zda to uživatele skutečně bude zajímat. Chcete ověřit, že dokážete formulovat jasnou, obhajitelnou hodnotovou nabídku. Nebo prostě chcete disciplínu Working Backwards k zaostření svého myšlení.
+**Kdy ji použít.** Před vyčleněním zdrojů chcete, aby váš koncept prošel zátěžovým testem. Nejste si jisti, zda to uživatele bude skutečně zajímat. Chcete si ověřit, že dokážete formulovat jasnou a obhajitelnou nabídku hodnoty. Nebo si prostě chcete disciplínou Working Backwards zpřesnit své myšlení.
 
 ## Který nástroj bych měl použít?
 
 | Situace | Doporučený nástroj |
-| --------- | ------------------ |
+| --------- | ---------------- |
-| „Mám vágní nápad, nevím kde začít“ | Brainstorming |
+| „Mám nejasný nápad, ale nevím, kde začít“ | Brainstorming |
-| „Potřebuji pochopit trh, než se rozhodnu“ | Výzkum |
+| „Než se rozhodnu, potřebuji pochopit trh“ | Výzkum |
-| „Vím, co chci vybudovat, jen to potřebuji zdokumentovat“ | Product Brief |
+| „Vím, co chci vytvořit, jen to potřebuji zdokumentovat“ | Product Brief |
-| „Chci se ujistit, že tento nápad skutečně stojí za budování“ | PRFAQ |
+| „Chci se ujistit, že tento nápad skutečně stojí za vybudování“ | PRFAQ |
-| „Chci prozkoumat, pak ověřit, pak zdokumentovat“ | Brainstorming → Výzkum → PRFAQ nebo Brief |
+| „Chci prozkoumat, pak ověřit a pak zdokumentovat“ | Brainstorming → Výzkum → PRFAQ nebo Brief |
 
-Product Brief a PRFAQ oba vytvářejí vstup pro PRD — vyberte si podle toho, jak velkou výzvu chcete. Brief je kolaborativní discovery. PRFAQ je náročný zátěžový test. Oba vás dovedou ke stejnému cíli; PRFAQ testuje, zda si váš koncept zaslouží tam dojít.
+Product Brief i PRFAQ jsou vstupem pro PRD — vyberte si jeden z nich podle toho, jak moc chcete být nároční. Brief je společným objevováním. PRFAQ je hozená rukavice. Obojí vás dovede ke stejnému cíli; PRFAQ testuje, zda si váš koncept zaslouží se tam dostat.
 
-:::tip[Nejste si jistí?]
+:::tip[Nejste si jisti?]
-Spusťte `bmad-help` a popište svou situaci. Doporučí vám správný výchozí bod na základě toho, co jste už udělali a čeho chcete dosáhnout.
+Spusťte `bmad-help` a popište svou situaci. Doporučí vám správný výchozí bod na základě toho, co jste již udělali a čeho se snažíte dosáhnout.
 :::
 
-## Co následuje po analýze?
+## Co se stane po analýze?
 
-Výstupy analýzy přímo vstupují do fáze 2 (plánování). Workflow tvorby PRD přijímá product briefy, PRFAQ dokumenty, výzkumná zjištění a záznamy z brainstormingu jako vstupy — syntetizuje vše, co jste vytvořili, do strukturovaných požadavků. Čím důkladnější analýzu provedete, tím ostřejší bude váš PRD.
+Výstupy analýzy se přímo promítají do fáze 2 (plánování). Pracovní postup PRD přijímá jako vstupy produktové briefy, dokumenty PRFAQ, výsledky výzkumu a zprávy z brainstormingu — syntetizuje vše, co jste vytvořili, do strukturovaných požadavků. Čím více analýz provedete, tím ostřejší bude vaše PRD.

src/bmm-skills/4-implementation/bmad-code-review/steps/step-02-review.md

@@ -10,6 +10,7 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 - The Blind Hunter subagent receives NO project context — diff only.
 - The Edge Case Hunter subagent receives diff and project read access.
 - The Acceptance Auditor subagent receives diff, spec, and context docs.
+- All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
 

src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -1,6 +1,7 @@
 ---
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 spec_file: '' # set at runtime for both routes before leaving this step
+story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
 ---
 
 # Step 1: Clarify and Route
@@ -20,7 +21,7 @@ Before listing artifacts or prompting the user, check whether you already know t
 
 1. Explicit argument
    Did the user pass a specific file path, spec name, or clear instruction this message?
-   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
    - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
 
 2. Recent conversation
@@ -29,13 +30,19 @@ Before listing artifacts or prompting the user, check whether you already know t
 
 3. Otherwise — scan artifacts and ask
    - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
-     - If `draft` selected: Set `spec_file`. **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
+     - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
-     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
+     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md`
-     - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
+     - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md`
    - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
 
 Never ask extra questions if you already understand what the user intends.
 
+### Story-key resolution
+
+This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset.
+
+If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple).
+
 ## INSTRUCTIONS
 
 1. Load context.
@@ -45,7 +52,7 @@ Never ask extra questions if you already understand what the user intends.
 
      **A) Epic story path** — if the intent is clearly an epic story:
 
-     1. Identify the epic number and (if present) the story number. If you can't identify an epic number, use path B.
+     1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
 
      2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
         - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
@@ -59,6 +66,8 @@ Never ask extra questions if you already understand what the user intends.
 
      5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
 
+     6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now.
+
      **B) Freeform path** — if the intent is not an epic story:
      - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
        - **PRD** (`*prd*`) — product requirements and success criteria

src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md

@@ -24,6 +24,8 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava
 
 Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
 
+Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
+
 If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
 
 Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.

src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -9,6 +9,7 @@ specLoopIteration: 1
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - Review subagents get NO conversation context.
+- All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
 

src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md

@@ -48,16 +48,25 @@ Format each stop as framing first, link on the next indented line:
 
 When there is only one concern, omit the bold label — just list the stops directly.
 
-### Commit and Present
+### Mark Spec Done
 
-1. Change `{spec_file}` status to `done` in the frontmatter.
+Change `{spec_file}` status to `done` in the frontmatter.
-2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+
-3. Open the spec in the user's editor so they can click through the Suggested Review Order:
+Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
+
+### Commit and Open
+
+1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+2. Open the spec in the user's editor so they can click through the Suggested Review Order:
    - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
    - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
-4. Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
+
-   - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+### Display Summary
-   - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+
-   - Offer to push and/or create a pull request.
+Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
+
+- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+- Offer to push and/or create a pull request.
 
 Workflow complete.

src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

@@ -13,11 +13,13 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 ### Implement
 
+Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
+
 Implement the clarified intent directly.
 
 ### Review
 
-Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
 
 ### Classify
 
@@ -39,6 +41,8 @@ Write `{spec_file}` using `./spec-template.md`. Fill only these sections — del
 2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
 3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
 
+Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
+
 ### Commit
 
 If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.

src/bmm-skills/4-implementation/bmad-quick-dev/sync-sprint-status.md

@@ -0,0 +1,19 @@
+# Sync Sprint Status
+
+Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from any route (plan-code-review, one-shot, future routes) with a `{target_status}` parameter.
+
+## Preconditions
+
+Skip this entire file (return to caller) if ANY of:
+- `{story_key}` is unset
+- `{sprint_status}` does not exist on disk
+
+## Instructions
+
+1. Load the FULL `{sprint_status}` file.
+2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
+3. **Idempotency check.** If `development_status[{story_key}]` is already at `{target_status}` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
+4. Set `development_status[{story_key}]` to `{target_status}`.
+5. **Epic lift (only when `{target_status}` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `{target_status}` is not `in-progress`.
+6. Refresh `last_updated` to the current date.
+7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES.

src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md

@@ -65,6 +65,7 @@ Load and read full config from `{main_config}` and resolve:
 - `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as system-generated current datetime
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
 - `project_context` = `**/project-context.md` (load if exists)
 - CLAUDE.md / memory files (load if exist)