@zeyue0329/xiaoma-cli 1.12.0 → 1.13.0

package/src/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-04-batch-create-stories.md

@@ -0,0 +1,309 @@
+---
+name: 'step-04-batch-create-stories'
+description: 'Phase 3 — Batch create detailed story files: for each backlog story, launch an Agent subprocess running xiaoma-create-story (and ONLY that — no dev/review/test)'
+nextStepFile: './step-05-finalize.md'
+---
+
+# Step 4 of 5: Batch Create Detailed Story Files
+
+**Goal:** For every backlog story in `sprint-status.yaml`, launch an independent Agent subprocess that runs `xiaoma-create-story` to produce a detailed `{story_key}.md` file. The Agent stops immediately after story creation — it does NOT enter development, code-review, or testing.
+
+**Role:** SM (xiaomin) — Pipeline Batch Scheduler
+
+---
+
+## Core Architecture: Agent-Isolated Story Creation (Narrowed)
+
+**Why this architecture:** Each story is delegated to an independent Agent subprocess so the main scheduler stays lightweight and isolated from per-story context bloat. This mirrors the proven `auto-story-pipeline-batch` (ASB) pattern.
+
+**KEY DIFFERENCE from ASB:** ASB's Agent runs steps 02→08 (create + validate + develop + review + test + fix + complete). **THIS pipeline's Agent runs ONLY xiaoma-create-story and exits.** It is a hard error for an Agent here to enter validate-story, develop-story, code-review, test-story, fix-and-retest, or complete-story.
+
+```
+Main conversation (scheduler, minimal context)
+  ├── Agent #1 → xiaoma-create-story for Story A → returns STORY_RESULT, exits
+  ├── Agent #2 → xiaoma-create-story for Story B → returns STORY_RESULT, exits
+  ├── Agent #3 → xiaoma-create-story for Story C → returns STORY_RESULT, exits
+  └── ...until backlog queue is empty
+```
+
+### Core Rules (Strictly Follow)
+
+1. **Each story processed by independent Agent** — Use the Agent tool to launch a general-purpose subprocess, pass complete story info + paths, have the Agent run `xiaoma-create-story` end-to-end, then return a structured summary
+2. **Agent must STOP after xiaoma-create-story** — Do NOT chain into any downstream step. This is enforced in the Agent prompt with explicit hard-boundary instructions
+3. **Main loop stays lightweight** — Main scheduler only: query sprint-status → launch Agent → read result → query remaining → continue or end
+4. **Serial processing** — Process one story at a time, wait for Agent completion before next, avoid concurrent modification conflicts on `sprint-status.yaml`
+5. **Failure tolerance** — A failed Agent does NOT halt the batch; the story key goes onto a blacklist and the loop continues
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Announce Phase Entry
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════
+  Phase 3 of 3 — Batch Create Detailed Story Files
+═══════════════════════════════════════════════════
+
+Switching role to SM (xiaomin) batch scheduler...
+Using Agent subprocess isolation — each story processed independently.
+
+For each story, an independent Agent will:
+  • Read and follow xiaoma-create-story workflow
+  • Produce {implementation_artifacts}/{story_key}.md
+  • Update sprint-status.yaml status to "ready-for-dev"
+  • Return STORY_RESULT summary and EXIT
+
+⚠️  Agent will NOT enter dev/review/test — this pipeline stops at story creation.
+───────────────────────────────────────────────────
+```
+
+### 2. Initial Sprint Status Load
+
+1. Load the FULL file: `{implementation_artifacts}/sprint-status.yaml`
+2. Read ALL lines from beginning to end — do not skip
+3. Parse the `development_status:` section completely
+4. Initial counts:
+   - `{backlog_count}` — Stories with status `backlog`
+   - `{ready_count}` — Stories with status `ready-for-dev` (pre-existing files; will be SKIPPED in this phase)
+5. If `{backlog_count}` == 0:
+   - If `{ready_count}` > 0: Output INFO — "{ready_count} stories already have files at ready-for-dev (from prior runs). Nothing to create. Proceeding to Step 4." → GOTO Step 4
+   - If `{ready_count}` == 0: HALT — "Sprint status has no backlog stories. Cannot proceed."
+
+### 3. Batch Loop
+
+Repeat the following until the backlog queue is empty:
+
+#### 3.1 Find Next Processable Story
+
+1. **Fresh read from disk:** Load the FULL `{implementation_artifacts}/sprint-status.yaml` again (do NOT rely on cached in-memory state — the previous iteration's Agent updated the file)
+2. Read ALL lines from beginning to end
+3. Parse `development_status:` completely
+4. Find the FIRST story (reading top to bottom) where:
+   - Key matches pattern `<digit>-<digit>-*` (e.g., `1-2-user-auth`)
+   - NOT an epic key (`epic-N`) or retrospective (`epic-N-retrospective`)
+   - Key is NOT in `{failed_story_keys}` (skip blacklisted stories)
+   - Status value equals `backlog`
+5. If no processable backlog story found → GOTO Step 4 (queue empty)
+
+Set `{current_story_key}` = the found story key.
+
+#### 3.2 Output Per-Story Progress Header
+
+```
+───────────────────────────────────────────────────
+Creating story: {current_story_key}
+Stories created so far: {stories_created} | Failed: {stories_failed}
+───────────────────────────────────────────────────
+```
+
+#### 3.3 Launch Independent Agent Subprocess
+
+<critical>
+
+Use the **Agent tool** to launch a **general-purpose subprocess** to create this story.
+
+The Agent's prompt MUST contain the following complete information for independent work:
+
+**1. Story Information:**
+
+- Story key: `{current_story_key}`
+- Current status: `backlog`
+- Expected output file: `{implementation_artifacts}/{current_story_key}.md`
+
+**2. Configuration (inline all resolved values):**
+
+- `project_name`: `{project_name}`
+- `user_name`: `{user_name}`
+- `communication_language`: `{communication_language}`
+- `document_output_language`: `{document_output_language}`
+- `user_skill_level`: `{user_skill_level}`
+- `planning_artifacts`: `{planning_artifacts}`
+- `implementation_artifacts`: `{implementation_artifacts}`
+- `sprint_status`: `{implementation_artifacts}/sprint-status.yaml`
+- `date`: current datetime
+- `architecture_absent`: `{architecture_absent}` (boolean from step-01; controls whether Data Model subsection must default to "TBD by architect")
+
+**3. Workflow Path (single workflow, narrow scope):**
+
+- `create_story_workflow`: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+
+**4. Project Context:**
+
+- Include the actual CONTENT of `project-context.md` if it exists (pass content inline, not just the path)
+
+**5. Processing Instructions (paste verbatim into the Agent prompt):**
+
+> You are an SM (xiaomin) story-creation specialist running in an isolated subprocess. Your one and only job is to create the detailed user-story file for `{current_story_key}` by reading and following the `xiaoma-create-story` workflow at `{create_story_workflow}`.
+>
+> **Steps:**
+>
+> 1. Read the workflow at `{create_story_workflow}` completely.
+> 2. Follow ALL its `<step>` blocks (step n=1 through step n=6) sequentially. The workflow auto-discovers the next backlog story from `sprint-status.yaml` — it will land on `{current_story_key}` because that's the first backlog story.
+> 3. Produce the story file at `{implementation_artifacts}/{current_story_key}.md`.
+> 4. **APPLY THE DETAILED DESIGN OUTPUT CONTRACT below before saving** — the create-story workflow's template is intentionally lean; this contract is mandatory and supersedes the template's defaults for the Dev Notes section.
+> 5. Update `sprint-status.yaml`: set `development_status[{current_story_key}] = "ready-for-dev"`.
+> 6. Return the STORY_RESULT summary (format below) and EXIT.
+>
+> **DETAILED DESIGN OUTPUT CONTRACT (mandatory) — applies to the story's `## Dev Notes` section:**
+>
+> The Dev Notes section MUST contain these three subsections (in this order). Do NOT omit, do NOT collapse, do NOT replace with a single paragraph.
+>
+> ```
+> ### Functional Requirements Addressed
+> - List EVERY FR/feature point from prd.md (or epics.md) that this story implements
+> - For each: FR reference (e.g., "FR-3", "PRD §4.2", or epic-story acceptance criteria number) → one-line restatement
+> - If a parent epic's FR list mentions FRs that this story is logically responsible for but you cannot find concrete acceptance criteria for them, list them anyway with the note "AC missing — needs PM review"
+>
+> ### Data Model & Database Design
+> - Tables / collections / entities touched by this story (give candidate names if not yet created in the codebase)
+> - Field list per entity: name, type, nullability, constraints, indexes, foreign keys
+> - Migration / schema-change notes if the story implies new tables or column changes
+> - **Source attribution:** every claim must end with `[Source: prd.md#<section>]` or `[Source: epics.md#<epic-story>]` or `[Source: architecture.md#<section>]`
+> - **TBD policy:**
+>   - If `architecture_absent == true` AND prd.md contains data-model clues (DDL snippets, ER hints, field lists): extract them and write the schema explicitly with `[Source: prd.md#<section>]`
+>   - If `architecture_absent == true` AND no data-model clues exist anywhere: write the literal line `TBD by architect — no data-model clues in prd.md or epics.md.` Do NOT silently omit this subsection.
+>   - If `architecture_absent == false`: extract data-model from architecture.md and cite it. If architecture.md does not cover this story's entities, write `TBD by architect — architecture.md does not cover <entity>.`
+>
+> ### Implementation Logic
+> - Key interface / function signatures (TypeScript-like or pseudocode form, even if the actual language differs)
+> - Core algorithm, state machine, or event flow — numbered steps or a small block diagram in ASCII
+> - Error-handling cases and boundary conditions (list the invariants and what should happen when they break)
+> - External-service / API integration points (endpoint, method, request/response shape)
+> - **Source attribution:** every claim must cite `[Source: prd.md#<section>]`, `[Source: epics.md#<epic-story>]`, or `[Source: architecture.md#<section>]`
+> - **TBD policy:** if no source covers the required logic, write `TBD by architect — <specific question>.` rather than fabricating logic. A specific TBD is better than a confident hallucination.
+> ```
+>
+> Standard create-story Dev Notes content (architecture patterns, source-tree components, testing standards) should still be produced — append them AFTER the three mandatory subsections above (e.g., as `### Architecture Patterns`, `### Source Tree Components`, `### Testing Standards`).
+>
+> **HARD BOUNDARY — DO NOT CROSS:**
+>
+> - After `xiaoma-create-story` workflow completes (and the contract above is applied), you are DONE.
+> - Do NOT read `auto-story-pipeline/steps/step-03-validate-story.md` or any subsequent step.
+> - Do NOT enter validate-story, develop-story, code-review, test-story, fix-and-retest, complete-story, or finalize.
+> - Do NOT read or follow ANY workflow under `5-full-pipeline/` (including auto-full-pipeline, auto-prd-to-stories itself, or any other pipeline workflow). The only workflow you may read is `{create_story_workflow}`.
+> - Do NOT read or follow `auto-story-pipeline-batch/workflow.md` or `auto-story-pipeline/workflow.md` — those are batch schedulers and downstream pipelines outside your scope.
+> - Do NOT write any code, run any tests, or modify any source files outside `{planning_artifacts}` and `{implementation_artifacts}`.
+> - Do NOT touch `sprint-status.yaml` beyond setting this one story's status to `ready-for-dev`.
+> - The main scheduler handles everything after you return.
+>
+> **Execution Rules:**
+>
+> - Execute the create-story workflow's steps in exact order; do NOT skip steps.
+> - When reading the story file or sprint-status in later substeps, always perform a FRESH read from disk.
+> - Do not stop because of "milestones" or "significant progress" — continue until the story file is created and sprint-status updated.
+> - If `xiaoma-create-story` asks for any user input (e.g., the "choose story" prompt in its step n=1), automatically pick option `{current_story_key}` (or let auto-discovery proceed — it will pick the first backlog story, which is this one).
+> - When the create-story workflow's step n=6 outputs guidance like "Next Steps: Run dev agents `dev-story`", IGNORE it. That guidance is for interactive single-story mode; in this batch pipeline, the main scheduler handles next steps.
+
+**6. Return Format (Agent must produce exactly this block at the end of its output):**
+
+```
+STORY_RESULT:
+- story_key: {story_key}
+- final_status: created | failed
+- file_path: {implementation_artifacts}/{story_key}.md
+- summary: {one-line description of what was created}
+- frs_addressed: [list of FR references / PRD section refs / acceptance-criteria ids that this story covers; empty list if none claimed]
+- db_design_status: present | tbd-flagged | missing
+- impl_logic_status: present | tbd-flagged | missing
+- error: {error message if failed, empty otherwise}
+```
+
+**Status-tag semantics (the Agent must self-assess and report honestly):**
+
+- `present` — the subsection contains concrete schema/logic content with source attributions
+- `tbd-flagged` — the subsection contains a clear "TBD by architect — <reason>" line as required by the contract
+- `missing` — the subsection is absent or empty (this should NEVER happen if the contract is followed; if reported, the main scheduler will flag the story for re-creation)
+
+</critical>
+
+#### 3.4 Read Agent Result and Handle Outcome
+
+Read the Agent's returned STORY_RESULT block.
+
+**IF the Agent succeeded (`final_status: created`):**
+
+1. Verify the file actually exists at `{implementation_artifacts}/{current_story_key}.md` (defense in depth — sometimes Agents claim success without writing the file)
+   - If file missing despite `final_status: created`: treat as failure (proceed to failure branch below)
+2. Increment `{stories_created}` by 1
+3. Append to `{story_results}`: `{ story_key, final_status: "created", file_path, summary, frs_addressed, db_design_status, impl_logic_status }` — preserve ALL fields from STORY_RESULT for step-05's report
+4. If `db_design_status == "missing"` OR `impl_logic_status == "missing"`: output WARNING — "Story {current_story_key} created but reported `missing` for a mandatory subsection. step-05 will surface this in Structural Warnings."
+
+**IF the Agent failed (`final_status: failed`, no STORY_RESULT block, or file-missing case above):**
+
+1. Increment `{stories_failed}` by 1
+2. Add `{current_story_key}` to `{failed_story_keys}` (prevents infinite re-selection)
+3. Append to `{story_results}`: `{ story_key, final_status: "failed", error }`
+4. Output: "⚠️ Story {current_story_key} failed. Reason: {error}. Skipping and continuing to next story."
+5. **Do NOT halt the batch.**
+
+#### 3.5 Refresh Sprint Status and Output Checkpoint
+
+1. Re-read `{implementation_artifacts}/sprint-status.yaml` from disk (fresh read)
+2. Recount: `{backlog_count}`, `{ready_count}`
+3. Output checkpoint:
+
+```
+[Checkpoint] Stories created: {stories_created} | Failed: {stories_failed} | Backlog remaining: {backlog_count}
+Last story: {current_story_key} ({final_status})
+```
+
+4. If `{backlog_count}` > 0 (and at least one backlog story is NOT in `{failed_story_keys}`): Continue loop — return to 3.1
+5. Otherwise: GOTO Step 4 (queue empty)
+
+### 4. Determine Phase 3 Status
+
+After loop exits:
+
+- If `{stories_created}` > 0 AND `{stories_failed}` == 0: `{phase_3_status}` = "success"
+- If `{stories_created}` > 0 AND `{stories_failed}` > 0: `{phase_3_status}` = "partial"
+- If `{stories_created}` == 0 AND `{stories_failed}` > 0: `{phase_3_status}` = "failed"
+- If `{stories_created}` == 0 AND `{stories_failed}` == 0: `{phase_3_status}` = "success" (nothing to do, but not an error — e.g., all stories pre-existing)
+
+### 5. Update Master Pipeline State
+
+- `{prd_to_stories_status}` = "complete"
+- `{steps_completed}` = 4
+
+### 6. Output Phase 3 Summary
+
+```
+───────────────────────────────────────────────────
+  Phase 3 Complete — Story File Generation
+───────────────────────────────────────────────────
+
+Stories Created: {stories_created}
+Stories Failed: {stories_failed}
+Failed Story Keys: {failed_story_keys joined by comma, or "none"}
+
+Phase 3 Status: {phase_3_status}
+Master Step: 4/5
+
+Proceeding to Finalization...
+───────────────────────────────────────────────────
+```
+
+**Auto-Proceed:** YES — Do NOT wait for user input. Immediately proceed to step-05.
+
+---
+
+## NEXT STEP
+
+**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md`
+
+---
+
+## SUCCESS METRICS
+
+- Every backlog story has either: (a) a corresponding `.md` file at `ready-for-dev`, OR (b) an entry in `{failed_story_keys}` with documented error
+- Main scheduler context stayed lightweight (no per-story bloat)
+- No Agent crossed the hard boundary into dev/review/test
+- `sprint-status.yaml` reflects all successful creations
+
+## FAILURE MODES
+
+- All Agent subprocesses failing (likely indicates a workflow-installation issue)
+- An Agent ignoring the hard-boundary instruction and entering downstream steps — if observed, the main scheduler should still record STORY_RESULT and continue, but the user should be warned in the final report
+- `sprint-status.yaml` corruption from concurrent modification — mitigated by strict serial processing

package/src/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md

@@ -0,0 +1,311 @@
+---
+name: 'step-05-finalize'
+description: 'Validate all artifacts, run completion checklist, and generate the final report for business-architect review'
+nextStepFile: null
+---
+
+# Step 5 of 5: Finalize PRD-to-Stories Pipeline
+
+**Goal:** Validate all output artifacts, run the completion checklist, and generate the unified report that business architects will use to evaluate the quality of the generated user stories.
+
+**Role:** Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Validate All Artifacts
+
+Check that ALL expected output files exist:
+
+**Phase 1 — Epics Artifact:**
+
+1. `{planning_artifacts}/epics.md` — Required
+
+**Phase 2 — Sprint Planning Artifact:**
+
+2. `{implementation_artifacts}/sprint-status.yaml` — Required
+
+**Phase 3 — Story File Artifacts:**
+
+3. For each story key in sprint-status.yaml (excluding those in `{failed_story_keys}`), a corresponding file at `{implementation_artifacts}/{story_key}.md` — Required
+
+For each missing artifact:
+
+- If epics.md or sprint-status.yaml is missing: log CRITICAL FAILURE
+- If a per-story file is missing but its key is NOT in `{failed_story_keys}`: log CRITICAL FAILURE (the Agent claimed success without writing the file)
+- If a per-story file is missing AND its key IS in `{failed_story_keys}`: expected (documented failure), no action
+
+### 2. Read Final Sprint Status
+
+Fresh-read `{implementation_artifacts}/sprint-status.yaml` and parse:
+
+- `{final_epic_count}` — Number of `epic-N` entries
+- `{final_story_count}` — Total story keys matching `<digit>-<digit>-*`
+- `{final_ready_count}` — Stories with status `ready-for-dev`
+- `{final_backlog_count}` — Stories still at `backlog` (should equal `{stories_failed}` if pipeline ran fully)
+
+**Sanity check:** `{final_ready_count}` should equal `{stories_created}` + (any pre-existing ready-for-dev stories from re-runs).
+
+### 3. Run Completion Checklist
+
+If `{installed_path}/checklist.md` is readable, load it and evaluate each item against the artifacts on disk. For each failed item, append a line to the final report's "Checklist Findings" section.
+
+If checklist.md is missing, skip this section silently.
+
+### 4. Validate Story File Structure (Full Scan + Deep Subsection Check)
+
+For **EVERY** successfully created story file (NOT sampled — scan all of them):
+
+1. Read the file fully
+2. **Top-level required sections** (case-insensitive heading search):
+   - `Status` (and value contains `ready-for-dev`)
+   - `Story` (with "As a / I want / so that" pattern)
+   - `Acceptance Criteria`
+   - `Tasks` (or `Tasks / Subtasks`)
+   - `Dev Notes`
+3. **Dev Notes mandatory subsections** (the three from the step-04 Detailed Design Output Contract):
+   - `### Functional Requirements Addressed` (or case-insensitive variant matching `Functional Requirements`)
+   - `### Data Model & Database Design` (or case-insensitive variant matching any of: `Data Model`, `Database Design`, `Database Schema`, `数据模型`, `数据库设计`)
+   - `### Implementation Logic` (or case-insensitive variant matching any of: `Implementation Logic`, `Implementation Detail`, `Pseudocode`, `接口设计`, `实现逻辑`)
+4. **Subsection content quality (lightweight heuristic):**
+   - Data Model subsection: content non-empty AND (contains a table/field-list line OR contains the literal "TBD by architect")
+   - Implementation Logic subsection: content non-empty AND (contains code-fence / function signature / numbered steps OR contains the literal "TBD by architect")
+   - A subsection that contains only a heading with no body fails this check.
+
+For each story file, classify:
+
+- **Tier A — Fully Compliant:** all top-level sections present, all three Dev Notes subsections present and content-positive (no `TBD by architect`)
+- **Tier B — TBD-flagged:** all sections present, but one or more subsections contain `TBD by architect` (this is acceptable — it surfaces unknowns honestly for the architect)
+- **Tier C — Structurally Incomplete:** one or more required top-level sections missing, OR a required Dev Notes subsection missing, OR a subsection has only a heading with no body
+
+Compute the coverage tallies for the final report:
+
+- `{dev_notes_db_coverage}` = count of story files with a non-empty `Data Model & Database Design` subsection / `{stories_created}`
+- `{dev_notes_impl_coverage}` = count of story files with a non-empty `Implementation Logic` subsection / `{stories_created}`
+- `{tier_a_count}`, `{tier_b_count}`, `{tier_c_count}` for the per-tier breakdown
+
+For every Tier C file, add a line to "Structural Warnings" listing the file path and exactly which sections/subsections failed.
+
+Also cross-check `story_results` from step-04: if any story has `db_design_status: missing` or `impl_logic_status: missing` reported by the Agent, list it in Structural Warnings even if heading-based detection passed (the Agent self-reported missing content).
+
+### 4b. FR Reverse-Traceability Check
+
+This implements Must Fix #4: ensure every functional requirement in `prd.md` is referenced by at least one story file.
+
+1. **Parse PRD functional requirements:**
+   - Read `{planning_artifacts}/prd.md` fully
+   - Extract FR identifiers using these patterns (in priority order, stop after the first that yields ≥1 match):
+     a. Lines matching `^FR-?\d+\b` or `^\*\*FR-?\d+\*\*` (canonical FR-N format)
+     b. Lines under a section titled `## Functional Requirements` or `## 功能需求`, where each bullet/numbered item is treated as one FR (assign synthetic ids `FR-1`, `FR-2`, ...)
+     c. Numbered headings under `## Features` or `## 功能点` (assign synthetic ids `FEAT-1`, `FEAT-2`, ...)
+   - If no patterns match (PRD has no structured FR list): skip the rest of this section and log INFO — "PRD has no structured FR list; reverse traceability skipped. Architects should manually verify coverage from epics.md and story files."
+   - Otherwise, set `{prd_fr_inventory}` = the list of extracted FR identifiers + their short title
+
+2. **For each FR in `{prd_fr_inventory}`:**
+   - Search ALL story files (`{implementation_artifacts}/<digit>-<digit>-*.md`) for ANY of:
+     - The exact FR identifier (e.g., `FR-3`)
+     - The FR's short title text (substring match, case-insensitive, length ≥ 8 chars to avoid false positives)
+     - A `[Source: prd.md#<section>]` citation whose `<section>` matches the FR's parent section
+   - If at least one story file references the FR: mark `covered`
+   - If no story file references the FR: mark `uncovered`
+
+3. **Compute coverage:**
+   - `{fr_coverage_numerator}` = count of FRs marked `covered`
+   - `{fr_coverage_denominator}` = `len(prd_fr_inventory)`
+   - `{uncovered_frs}` = list of FR identifiers marked `uncovered`
+
+4. **For each uncovered FR:**
+   - Add a HIGH-PRIORITY line to "Structural Warnings": `Uncovered FR: {fr_id} — "{fr_title}" — NO story file references this requirement. The pipeline may have dropped this feature.`
+
+5. **Cross-check epics.md FR Coverage Map** (if `{epics_fr_count}` was set in step-02):
+   - If `{fr_coverage_denominator}` significantly differs from `{epics_fr_count}` (delta > 20%): add WARNING to Structural Warnings — "FR-Coverage-Map count ({epics_fr_count}) vs PRD-extracted FR count ({fr_coverage_denominator}) differ by >20%. epics.md may have an incomplete FR Coverage Map."
+
+### 5. Generate Final Report
+
+Set `{prd_to_stories_status}` = "complete" and `{steps_completed}` = 5 BEFORE printing.
+
+**Output:**
+
+```
+═══════════════════════════════════════════════════════════════
+  Auto PRD-to-Stories Pipeline — COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Project: {project_name}
+Date: {date}
+Master Steps Completed: {steps_completed}/5
+
+Input:
+  📋 PRD: {planning_artifacts}/prd.md
+
+Outputs:
+  📄 Epics: {planning_artifacts}/epics.md            [{phase_1_status}]
+  📊 Sprint Status: {implementation_artifacts}/sprint-status.yaml   [{phase_2_status}]
+  📁 Story Files: {implementation_artifacts}/<story_key>.md × {stories_created}  [{phase_3_status}]
+
+Phase Breakdown:
+  Phase 1 — Create Epics                 [{phase_1_status}]
+    └─ Total Epics: {final_epic_count}
+    └─ Total Stories (in epics.md): {final_story_count}
+    └─ FRs in Coverage Map: {epics_fr_count}
+
+  Phase 2 — Sprint Planning Bridge       [{phase_2_status}]
+    └─ Stories tracked: {final_story_count}
+
+  Phase 3 — Batch Story File Creation    [{phase_3_status}]
+    ├─ Stories Successfully Created: {stories_created}
+    ├─ Stories Failed: {stories_failed}
+    └─ Failed Keys: {failed_story_keys joined, or "none"}
+
+🔎 Quality Coverage (for architect review):
+  ├─ FR Coverage:                  {fr_coverage_numerator}/{fr_coverage_denominator}
+  ├─ Data Model subsection:        {dev_notes_db_coverage}/{stories_created}  (present)
+  ├─ Implementation Logic subsec:  {dev_notes_impl_coverage}/{stories_created}  (present)
+  ├─ Tier A (fully compliant):     {tier_a_count}
+  ├─ Tier B (TBD-flagged honest):  {tier_b_count}
+  └─ Tier C (structurally incomplete): {tier_c_count}   ⚠ if > 0, see Structural Warnings below
+
+Pipeline Status: {prd_to_stories_status}
+═══════════════════════════════════════════════════════════════
+
+📋 Story Files Generated (for business-architect review):
+{for each entry in story_results where final_status == "created":
+  ✅ {story_key}.md  —  {summary}
+}
+
+❌ Story Files Failed:
+{for each entry in story_results where final_status == "failed":
+  ⚠️  {story_key}  —  {error}
+}
+
+{IF "Structural Warnings" non-empty:}
+⚠️  Structural Warnings (high → low priority):
+
+  -- FR Coverage Gaps (HIGHEST priority — these features may have been dropped) --
+  {for each uncovered_fr: "Uncovered FR: {fr_id} — \"{fr_title}\" — NO story file references this. The pipeline may have dropped this feature."}
+
+  -- Structural Incompleteness (Tier C files) --
+  {for each Tier C entry: story_key — missing sections/subsections list}
+
+  -- Self-Reported Missing Content (from Agent STORY_RESULT) --
+  {for each story with db_design_status == "missing" or impl_logic_status == "missing": story_key — which subsection Agent reported missing}
+
+  -- FR Coverage Map Discrepancy (if any) --
+  {if FR-coverage-map count delta > 20%: warning text}
+
+{IF "Checklist Findings" non-empty:}
+📋 Checklist Findings:
+{for each failed item: item description}
+```
+
+### 6. Architect Review Guidance
+
+```
+───────────────────────────────────────────────────────────────
+  🎯 Next: Business-Architect Quality Review
+───────────────────────────────────────────────────────────────
+
+The pipeline stops HERE intentionally. The generated artifacts are
+the input to a manual quality review:
+
+  1. **Start with the Quality Coverage block above.**
+     - If FR Coverage < 100%: find the listed uncovered FRs FIRST — these
+       are features from prd.md that no story addresses. Run create-epics-
+       and-stories again or manually add the missing stories.
+     - If Tier C count > 0: open those files first — they have structural
+       holes that block downstream development.
+
+  2. Review epics.md for completeness vs. the input prd.md
+     (Are all PRD features represented? Right epic granularity?
+      Cross-check the FR Coverage Map section.)
+
+  3. Review each {story_key}.md for:
+     - Story statement clarity (As a / I want / so that)
+     - Acceptance Criteria testability (BDD Given/When/Then quality)
+     - Task decomposition concreteness
+     - **Data Model & Database Design subsection** — Are the tables/fields/
+       indexes/constraints concrete? If "TBD by architect", is the missing
+       piece something prd.md should have specified, or is it genuinely a
+       design decision for the architect to make now?
+     - **Implementation Logic subsection** — Are interface signatures,
+       algorithms, and error-handling concrete? Or hand-wavy?
+     - **Functional Requirements Addressed subsection** — Does it cite
+       specific FRs/sections from prd.md or epics.md?
+
+  4. Capture feedback on which dimensions are weak — feed back
+     into the create-epics-and-stories / create-story prompts
+     to improve generation quality.
+
+  5. When ready to enter development, run:
+       /xiaoma  →  load sm  →  ASB
+     (auto-story-pipeline-batch will pick up from ready-for-dev.)
+
+───────────────────────────────────────────────────────────────
+```
+
+### 7. Generate Machine-Readable Status File
+
+Write to: `{implementation_artifacts}/prd-to-stories-status.json`
+
+```json
+{
+  "pipeline": "auto-prd-to-stories",
+  "date": "{date}",
+  "project": "{project_name}",
+  "status": "{prd_to_stories_status}",
+  "master_steps_completed": 5,
+  "input": {
+    "prd": "{planning_artifacts}/prd.md"
+  },
+  "phases": {
+    "epics": {
+      "status": "{phase_1_status}",
+      "artifact": "{planning_artifacts}/epics.md",
+      "epic_count": "{final_epic_count}",
+      "story_count": "{final_story_count}"
+    },
+    "sprint_planning": {
+      "status": "{phase_2_status}",
+      "artifact": "{implementation_artifacts}/sprint-status.yaml"
+    },
+    "story_creation": {
+      "status": "{phase_3_status}",
+      "stories_created": "{stories_created}",
+      "stories_failed": "{stories_failed}",
+      "failed_story_keys": "{failed_story_keys}",
+      "quality_coverage": {
+        "fr_coverage": {
+          "covered": "{fr_coverage_numerator}",
+          "total": "{fr_coverage_denominator}",
+          "uncovered_frs": "{uncovered_frs}"
+        },
+        "data_model_present": "{dev_notes_db_coverage}",
+        "implementation_logic_present": "{dev_notes_impl_coverage}",
+        "tier_a_count": "{tier_a_count}",
+        "tier_b_count": "{tier_b_count}",
+        "tier_c_count": "{tier_c_count}"
+      }
+    }
+  }
+}
+```
+
+### 8. Pipeline Complete
+
+**Pipeline execution is COMPLETE. HALT.**
+
+---
+
+## SUCCESS METRICS
+
+- All 3 phases reported with status
+- All successfully created story files exist on disk and contain required sections
+- Final report output with architect-review guidance
+- Machine-readable status file written
+
+## FAILURE MODES
+
+- Missing epics.md or sprint-status.yaml when at least one phase claimed success
+- Story files claimed created but missing on disk
+- Failure to write the final status JSON