@zeyue0329/xiaoma-cli 1.13.0 → 1.15.0

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/steps/step-03-bridge-sprint-planning.md

@@ -2,13 +2,14 @@
 name: "step-03-bridge-sprint-planning"
 description: "Bridge phase: auto-run sprint planning to generate sprint-status.yaml from epics, connecting requirements analysis output to story development input"
 nextStepFile: "./step-04-run-story-pipeline.md"
+kind: "bridge"
 ---
 
 # Step 3 of 5: Bridge — Sprint Planning
 
 **Goal:** Generate `sprint-status.yaml` from the epics produced in Phase 1. This bridges the requirements analysis output to the story development pipeline input. Without this step, the story pipeline cannot determine which stories to process.
 
-**Role:** SM (xiaomin) — Scrum Master generating sprint tracking
+**Role:** Dev (xiaokai) — Sprint-Planning (SP) mode generating sprint tracking
 
 ---
 
@@ -42,7 +43,7 @@ Also check for sharded epics format (safety net only — the auto-requirements-p
 
 ### 3. Execute Sprint Planning Workflow
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+Read fully and follow: `skill:xiaoma-sprint-planning`
 
 **Critical Full Pipeline Mode Instructions:**
 
@@ -58,19 +59,71 @@ Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xi
 - When the workflow outputs "Next Steps" guidance at the end, **ignore it** — the next steps are handled by THIS full pipeline automatically
 - **Complete ALL steps without stopping**
 
-### 4. Verify Sprint Status Output
+**Capture errors:** record any HALT message or fatal error emitted by the sprint-planning workflow into `{sprint_planning_error}` (empty string if none).
+
+### 4. Verify Sprint Status Output (with Bridge-Failure Fallback)
 
 After sprint planning completes, verify:
 
-1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist
-   - If missing: HALT — "Sprint planning failed to generate sprint-status.yaml. Check epics format and retry."
+1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist.
 
 2. **Content Validation** — Read the generated file and verify:
    - Contains `development_status:` section
    - Contains at least one story entry (not just epic entries)
    - Valid YAML syntax
 
-3. **Count Stories** — Parse and count:
+3. **Bridge-Failure Fallback (preserves Phase 1 work; allows resume):**
+
+   If `{implementation_artifacts}/sprint-status.yaml` is missing OR fails content validation, **do NOT silently HALT**. Phase 1 has already produced expensive artifacts (PRD, epics, architecture); losing the run context here would force re-running Phase 1. Instead:
+
+   a. Write a structured failure marker to `{implementation_artifacts}/bridge-failure.json` (atomic temp-file-then-rename):
+
+      ```json
+      {
+        "pipeline": "auto-full-pipeline",
+        "stage": "step-03-bridge-sprint-planning",
+        "date": "{date}",
+        "failure_reason": "sprint-status.yaml missing or invalid after sprint-planning workflow returned",
+        "sprint_planning_error": "{sprint_planning_error}",
+        "validation_signals": {
+          "file_exists": false_or_true,
+          "yaml_valid": false_or_true,
+          "has_development_status": false_or_true,
+          "story_entries_present": false_or_true
+        },
+        "phase_1_artifacts_preserved": {
+          "prd": "{planning_artifacts}/prd.md",
+          "epics": "{planning_artifacts}/epics.md",
+          "architecture": "{planning_artifacts}/architecture.md",
+          "pipeline_status": "{planning_artifacts}/pipeline-status.json"
+        },
+        "recovery_instructions": [
+          "1. Inspect epics.md for malformed epic/story structure (most common cause).",
+          "2. Run /xiaoma-sprint-planning (SP) manually with the same epics.md to reproduce the error in isolation.",
+          "3. Once sprint-status.yaml is healthy, re-run auto-full-pipeline; step-01 resume detection will skip Phase 1 (artifacts intact) and proceed directly to Phase 3."
+        ]
+      }
+      ```
+
+   b. Set `{phase_2_status}` = "failed"; do NOT advance `{phase_3_status}`.
+
+   c. HALT with this exact user-facing message — **be specific about resume mechanics**, since the value of preserving Phase 1 is wasted if the user thinks they must restart:
+
+      ```
+      ❌ Phase 2 (Sprint Planning Bridge) failed.
+
+      Sprint planning produced no usable sprint-status.yaml. Failure marker written to:
+        {implementation_artifacts}/bridge-failure.json
+
+      ✅ Phase 1 artifacts are preserved (PRD, epics, architecture, pipeline-status.json).
+
+      🔄 Recovery:
+        1. Fix the underlying cause (likely malformed epics.md — see bridge-failure.json for details).
+        2. Run /xiaoma-sprint-planning (SP) manually to confirm sprint-status.yaml generates cleanly.
+        3. Re-run /xiaoma-auto-full-pipeline. Resume detection in step-01 will skip Phase 1 and pick up at Phase 2.
+      ```
+
+4. **Count Stories** (only if validation passed) — Parse and count:
    - Total epics
    - Total stories
    - Stories in "backlog" status (should be all stories for a fresh run)
@@ -114,6 +167,7 @@ Proceeding to Phase 3 — Story Development Pipeline (batch mode)...
 ## FAILURE MODES
 
 - Epics file missing or unreadable
-- Sprint planning workflow fails
-- Generated sprint-status.yaml is malformed or empty
-- No story entries found in sprint status
+- Sprint planning workflow fails — but instead of bare HALT, a structured `bridge-failure.json` marker is written and Phase 1 artifacts are preserved for resume
+- Generated sprint-status.yaml is malformed or empty — same fallback path
+- No story entries found in sprint status — same fallback path
+- Failing to write `bridge-failure.json` atomically (would leave a half-written marker; use temp-file-then-rename)

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/steps/step-04-run-story-pipeline.md

@@ -2,6 +2,7 @@
 name: "step-04-run-story-pipeline"
 description: "Execute the auto-story-pipeline-batch to develop, review, test, and deliver all stories using Agent subprocess isolation"
 nextStepFile: "./step-05-finalize.md"
+kind: "orchestrator"
 ---
 
 # Step 4 of 5: Execute Story Development Pipeline (Batch)
@@ -42,7 +43,7 @@ Delegating to auto-story-pipeline-batch...
 
 ### 2. Execute Auto Story Pipeline Batch
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline-batch/workflow.md`
+Read fully and follow: `skill:xiaoma-auto-story-pipeline-batch`
 
 **Critical Full Pipeline Mode Instructions:**
 

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/steps/step-05-finalize.md

@@ -2,6 +2,7 @@
 name: "step-05-finalize"
 description: "Generate unified completion report across both phases, validate all artifacts, and provide final summary"
 nextStepFile: null
+kind: "terminal"
 ---
 
 # Step 5 of 5: Finalize Full Pipeline
@@ -39,7 +40,7 @@ For each missing artifact, log a warning. If PRD, Epics, or sprint-status.yaml a
 
 ### 2. Run Completion Checklist
 
-Load and evaluate: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline/checklist.md`
+Load and evaluate: `./checklist.md`
 
 Mark each item as passed or failed based on artifact verification and phase status tracking.
 
@@ -58,6 +59,19 @@ Mark each item as passed or failed based on artifact verification and phase stat
 - Phase 3 stories completed: `{stories_completed}`
 - Phase 3 total fix iterations across all stories
 
+**From sub-pipeline status JSON files (fresh read from disk; tolerate missing files):**
+
+- Phase 1 — `{planning_artifacts}/pipeline-status.json`:
+  - Capture `readiness_status` (one of `ready` / `gaps` / `blocked` / `not_checked`) — set `{phase_1_readiness}` accordingly; default to `not_checked` if file or field absent.
+  - Append every entry from its `warnings[]` to the master warnings list with prefix `[phase-1] `. Note (compatibility): auto-requirements-pipeline now emits prefix-tagged entries (each beginning with a `[step-NN]` tag from its own dictionary — see `auto-requirements-pipeline/workflow.md` "Warning Prefix-Tag Convention"), so the aggregated form here will be `[phase-1] [step-NN] <description>`. Do NOT strip the inner `[step-NN]` tag — the additive wrap is intentional and downstream consumers can pattern-match on either depth. Entries from older runs (pre-L-series) that lack the inner tag still wrap correctly and remain readable.
+- Phase 3 — per-story `{implementation_artifacts}/story-pipeline-status.{story_key}.json` archives (written by auto-story-pipeline-batch section 2.4b):
+  - **Preferred path:** Read `{implementation_artifacts}/batch-pipeline-status.json` (written by ASPB section 3.3). Take its `archived_status_files[]` field — a guaranteed-complete list of every per-story status JSON written during the batch. Read each file and aggregate.
+  - **Fallback path:** If `batch-pipeline-status.json` is missing (older ASPB / single-story mode), look for the single canonical `{implementation_artifacts}/story-pipeline-status.json` written by auto-story-pipeline/step-09 (best-effort snapshot of the LAST story only — accept this limitation and log INFO that aggregation is partial).
+  - For each file, append every entry from its `warnings[]` with prefix `[phase-3:{story_key}] ` to the master warnings list.
+  - Sum `fix_iterations_used` across all available status files into `{total_fix_iterations}` (overrides the rougher in-memory estimate above when available).
+  - Also read `{implementation_artifacts}/batch-pipeline-status.json` `failed_story_keys[]`; for each failed story emit a synthetic warning `[phase-3:{story_key}] story halted/failed during batch — see story file or archive for details.` so failures surface in the master warning list even if no per-story `warnings[]` was populated.
+- De-duplicate the master warnings list (preserve first occurrence) and cap at 100 entries; if truncated, append a final summary entry `"... ({n_more} more warnings truncated)"`.
+
 ### 4. Generate Unified Completion Report
 
 Set `{full_steps_completed}` = 5 and `{full_pipeline_status}` = "complete" now, before printing, so the report reflects the final accurate values.
@@ -107,6 +121,7 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
   "phases": {
     "requirements": {
       "status": "{phase_1_status}",
+      "readiness_status": "{phase_1_readiness}",
       "artifacts": {
         "requirements_analysis": "{planning_artifacts}/requirements-analysis.md",
         "architecture_analysis": "{planning_artifacts}/current-architecture-analysis.md",
@@ -132,10 +147,19 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
       "epics_total": "{total_epic_count}",
       "total_fix_iterations": "{total_fix_iterations}"
     }
-  }
+  },
+  "warnings": [
+    "{aggregated_warning_1}",
+    "{aggregated_warning_2}"
+  ]
 }
 ```
 
+Notes for serialization:
+- `readiness_status` is sourced from Phase 1's `pipeline-status.json`. If that file or field is missing, write the literal string `"not_checked"`.
+- `warnings` is the aggregated, de-duplicated list assembled in section 3 (with `[phase-1] ` / `[phase-3:{story_key}] ` prefixes preserved). Write `[]` if empty.
+- Use temp-file-then-rename for the write (write to `full-pipeline-status.json.tmp`, then atomic rename) to avoid partial writes.
+
 ### 6. Provide Next Steps
 
 **If all stories completed ({phase_3_status} == "success"):**
@@ -182,7 +206,9 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
 - All 3 phases completed successfully
 - All planning artifacts verified
 - All stories developed and marked "done"
-- Machine-readable full-pipeline-status.json generated
+- Machine-readable full-pipeline-status.json generated with aggregated warnings and `readiness_status` from Phase 1
+- Sub-pipeline status JSON files (Phase 1 `pipeline-status.json`, Phase 3 `story-pipeline-status.json`) consumed when available
+- Atomic temp-file-then-rename write used for `full-pipeline-status.json`
 - Unified completion report generated
 - Next steps provided
 
@@ -192,3 +218,4 @@ Write to: `{implementation_artifacts}/full-pipeline-status.json`
 - Partial story completion not properly reported
 - Not providing next steps for partial/failed completions
 - Not generating machine-readable status file
+- Silently dropping sub-pipeline warnings (Phase 1 / Phase 3) — the aggregated `warnings[]` must reflect all upstream signals

package/src/{xmc/workflows/5-full-pipeline/auto-full-pipeline → xmc-skills/5-full-pipeline/xiaoma-auto-full-pipeline}/workflow.md

@@ -12,9 +12,9 @@ description: "Fully automated requirements-to-delivery pipeline: requirements an
 - **Phase 1 — Requirements Analysis** (delegates to auto-requirements-pipeline)
   - Analyst (xiaofen) → Architect (xiaojia) → PM (xiaochan) → Architect (xiaojia)
 - **Phase 2 — Bridge** (sprint planning)
-  - SM (xiaomin) — Generate sprint tracking from epics
+  - Dev (xiaokai) — Generate sprint tracking from epics
 - **Phase 3 — Story Development** (delegates to auto-story-pipeline-batch)
-  - SM (xiaomin) → PM (xiaochan) → Dev (xiaokai) → Reviewer → QA (xiaoce)
+  - Dev (xiaokai) → PM (xiaochan) → Dev (xiaokai) → Reviewer → Dev (xiaokai)
 
 - Communicate all responses in {communication_language} and generate all documents in {document_output_language}
 - Execute ALL steps in exact order; do NOT skip steps
@@ -91,11 +91,10 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline`
-- `requirements_pipeline` = `{project-root}/_xiaoma/xmc/workflows/1-analysis/auto-requirements-pipeline/workflow.md`
-- `sprint_planning_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
-- `story_pipeline_batch` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline-batch/workflow.md`
-- `validation` = `{installed_path}/checklist.md`
+- `requirements_pipeline` = `skill:xiaoma-auto-requirements-pipeline`
+- `sprint_planning_workflow` = `skill:xiaoma-sprint-planning`
+- `story_pipeline_batch` = `skill:xiaoma-auto-story-pipeline-batch`
+- `validation` = `{skill-root}/checklist.md`
 
 ### Context
 
@@ -105,4 +104,4 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ## EXECUTION
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-full-pipeline/steps/step-01-init-and-validate.md` to begin the pipeline.
+Read fully and follow: `./steps/step-01-init-and-validate.md` to begin the pipeline.

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/checklist.md

@@ -41,3 +41,7 @@ Use this checklist to validate the PRD-to-Stories pipeline completed successfull
 - [ ] **Phase Boundary Summaries Output** — End-of-phase state snapshots logged for context-recovery
 - [ ] **Final Report Generated** — step-05 produced a unified completion report listing all artifacts and counts
 - [ ] **Artifact Consistency** — `sprint-status.yaml` story keys match story files on disk one-to-one (allowing for documented failures)
+- [ ] **Machine-Readable Status Written** — `{implementation_artifacts}/prd-to-stories-status.json` exists, parses as valid JSON, and contains all required top-level fields (`pipeline`, `date`, `project`, `status`, `master_steps_completed`, `input`, `phases`, `warnings`)
+- [ ] **Atomic Status Write** — `prd-to-stories-status.json` was written via temp-file-then-rename (no leftover `.tmp` file in `{implementation_artifacts}/`)
+- [ ] **Warnings Aggregated in Status JSON** — Structural Warnings from the human report (FR-coverage gaps, Tier C entries, self-reported missing subsections, FR-Coverage-Map discrepancies, checklist findings) are also present in `prd-to-stories-status.json#warnings` with prefix tags
+- [ ] **Bridge-Failure Marker (if Phase 2 failed)** — When `{phase_2_status} == "failed"`, `{implementation_artifacts}/bridge-failure.json` exists with the schema documented in step-03 (failure_reason, sprint_planning_error, validation_signals, phase_1_artifacts_preserved, recovery_instructions). When `{phase_2_status} == "success"`, this file should NOT exist (or is leftover from a prior failed run and is documented in `warnings[]`).

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-01-init-and-validate.md

@@ -2,6 +2,7 @@
 name: 'step-01-init-and-validate'
 description: 'Validate prd.md and sub-workflow paths, initialize PRD-to-Stories pipeline state variables, and prepare for execution'
 nextStepFile: './step-02-create-epics.md'
+kind: 'init'
 ---
 
 # Step 1 of 5: Initialize and Validate Environment
@@ -40,16 +41,16 @@ Read config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 Check that all delegated sub-workflows are readable:
 
-1. **Create Epics & Stories** — `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md`
+1. **Create Epics & Stories** — `skill:xiaoma-create-epics-and-stories`
    - If missing: HALT — "xiaoma-create-epics-and-stories workflow not found. Verify XiaoMa installation is complete."
 
-2. **Sprint Planning** — `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+2. **Sprint Planning** — `skill:xiaoma-sprint-planning`
    - If missing: HALT — "xiaoma-sprint-planning workflow not found. Verify XiaoMa installation is complete."
 
-3. **Create Story** — `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+3. **Create Story** — `skill:xiaoma-create-story`
    - If missing: HALT — "xiaoma-create-story workflow not found. Verify XiaoMa installation is complete."
 
-4. **Checklist** — `{installed_path}/checklist.md` must be readable for step-05 self-check.
+4. **Checklist** — `{skill-root}/checklist.md` must be readable for step-05 self-check.
    - If missing: Output WARNING — "checklist.md not found; final self-check will be skipped."
 
 ### 4. Check Existing Artifacts (Informational)
@@ -117,8 +118,8 @@ Language: {communication_language} / {document_output_language}
 
 Pipeline Phases (stops BEFORE development):
   ⬜ Phase 1 — Create Epics (PM xiaochan, delegates to xiaoma-create-epics-and-stories)
-  ⬜ Phase 2 — Sprint Planning Bridge (SM xiaomin, delegates to xiaoma-sprint-planning)
-  ⬜ Phase 3 — Batch Create Story Files (SM xiaomin, N Agent subprocesses)
+  ⬜ Phase 2 — Sprint Planning Bridge (Dev xiaokai, delegates to xiaoma-sprint-planning)
+  ⬜ Phase 3 — Batch Create Story Files (Dev xiaokai, N Agent subprocesses)
 
 Finalization: Step 5 — Unified completion report for business-architect review
 
@@ -135,7 +136,7 @@ Master Step: 1/5
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-02-create-epics.md`
+**NEXT:** Read fully and follow: `./steps/step-02-create-epics.md`
 
 ---
 

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-02-create-epics.md

@@ -2,6 +2,7 @@
 name: 'step-02-create-epics'
 description: 'Phase 1 — PM role creates epics and stories from prd.md by delegating to create-epics-and-stories workflow'
 nextStepFile: './step-03-bridge-sprint-planning.md'
+kind: 'orchestrator'
 ---
 
 # Step 2 of 5: Create Epics and Stories
@@ -56,7 +57,7 @@ Load these artifacts in order:
 
 Before delegating, verify the required workflow exists:
 
-1. Check that `{project-root}/_xiaoma/xmc/workflows/3-solutioning/xiaoma-create-epics-and-stories/workflow.md` is readable
+1. Check that `skill:xiaoma-create-epics-and-stories` is readable
 2. If workflow is missing:
    - HALT — "Required workflow not found: `xiaoma-create-epics-and-stories`. Verify XiaoMa installation is complete."
 
@@ -136,7 +137,7 @@ Proceeding to Phase 2 — Sprint Planning Bridge...
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-03-bridge-sprint-planning.md`
+**NEXT:** Read fully and follow: `./steps/step-03-bridge-sprint-planning.md`
 
 ---
 

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-03-bridge-sprint-planning.md

@@ -2,13 +2,14 @@
 name: 'step-03-bridge-sprint-planning'
 description: 'Phase 2 bridge: auto-run sprint planning to generate sprint-status.yaml from epics, connecting epics output to per-story creation input'
 nextStepFile: './step-04-batch-create-stories.md'
+kind: 'bridge'
 ---
 
 # Step 3 of 5: Bridge — Sprint Planning
 
 **Goal:** Generate `sprint-status.yaml` from the epics produced in Phase 1. This bridges the epic breakdown to the per-story file generation in Phase 3. Without this step, Phase 3 cannot determine which stories to process.
 
-**Role:** SM (xiaomin) — Scrum Master generating sprint tracking
+**Role:** Dev (xiaokai) — Sprint-Planning (SP) mode generating sprint tracking
 
 ---
 
@@ -23,7 +24,7 @@ nextStepFile: './step-04-batch-create-stories.md'
   Phase 2 of 3 — Sprint Planning Bridge
 ═══════════════════════════════════════════════════
 
-Switching role to SM (xiaomin)...
+Switching to Sprint-Planning mode (xiaokai)...
 Generating sprint-status.yaml from epics...
 This bridges epics → per-story file generation.
 ───────────────────────────────────────────────────
@@ -41,17 +42,17 @@ Also check for sharded epics format (safety net only — Phase 1 produces a sing
 - If sharded version found, proceed — the sprint planning workflow handles both formats
 - If neither format found: HALT — "No epics found in any format. Phase 1 may have failed."
 
-### 3. Switch to SM Role
+### 3. Switch to Sprint-Planning Mode
 
-Adopt the SM (xiaomin) persona:
+Adopt the Dev agent's Sprint-Planning mode:
 
-- You are xiaomin, the Technical Scrum Master + Story Preparation Specialist
+- You are xiaokai, the Dev agent applying Technical Scrum Master + Story Preparation discipline
 - Your purpose is to translate the epic breakdown into a sprint-status tracking file
 - Communication style: Crisp and checklist-driven
 
 ### 4. Execute Sprint Planning Workflow
 
-Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+Read fully and follow: `skill:xiaoma-sprint-planning`
 
 **Critical Pipeline Mode Instructions:**
 
@@ -68,19 +69,71 @@ Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xi
 - When the workflow outputs "Next Steps" guidance at the end, **ignore it** — the next steps are handled by THIS pipeline automatically
 - **Complete ALL steps without stopping**
 
-### 5. Verify Sprint Status Output
+**Capture errors:** record any HALT message or fatal error emitted by the sprint-planning workflow into `{sprint_planning_error}` (empty string if none). Used by the Bridge-Failure Fallback below.
+
+### 5. Verify Sprint Status Output (with Bridge-Failure Fallback)
 
 After sprint planning completes, verify:
 
-1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist
-   - If missing: HALT — "Sprint planning failed to generate sprint-status.yaml. Check epics format and retry."
+1. **Sprint Status File** — `{implementation_artifacts}/sprint-status.yaml` must exist.
 
 2. **Content Validation** — Read the generated file and verify:
    - Contains `development_status:` section
    - Contains at least one story entry (key matches `<digit>-<digit>-*` pattern, not just epic entries)
    - Valid YAML syntax
 
-3. **Count Stories** — Parse and count:
+3. **Bridge-Failure Fallback (preserves Phase 1 epics; allows resume):**
+
+   If `{implementation_artifacts}/sprint-status.yaml` is missing OR fails content validation, **do NOT silently HALT**. Phase 1 has already produced `epics.md`; losing the run context here would force re-running Phase 1 and re-generating epics. Instead:
+
+   a. Write a structured failure marker to `{implementation_artifacts}/bridge-failure.json` (atomic temp-file-then-rename):
+
+      ```json
+      {
+        "pipeline": "auto-prd-to-stories",
+        "stage": "step-03-bridge-sprint-planning",
+        "date": "{date}",
+        "failure_reason": "sprint-status.yaml missing or invalid after sprint-planning workflow returned",
+        "sprint_planning_error": "{sprint_planning_error}",
+        "validation_signals": {
+          "file_exists": false_or_true,
+          "yaml_valid": false_or_true,
+          "has_development_status": false_or_true,
+          "story_entries_present": false_or_true
+        },
+        "phase_1_artifacts_preserved": {
+          "prd": "{planning_artifacts}/prd.md",
+          "epics": "{planning_artifacts}/epics.md"
+        },
+        "recovery_instructions": [
+          "1. Inspect epics.md for malformed epic/story structure (most common cause).",
+          "2. Run /xiaoma-sprint-planning (SP) manually with the same epics.md to reproduce the error in isolation.",
+          "3. Once sprint-status.yaml is healthy, re-run auto-prd-to-stories; step-01 will detect epics.md exists and proceed directly to Phase 2 → 3."
+        ]
+      }
+      ```
+
+      Write strategy (atomic): write to `bridge-failure.json.tmp` first; verify JSON parses; rename to `bridge-failure.json`. Failure to write the marker is a WARNING (logged) — proceed with the HALT below regardless, since the human-readable HALT message already contains the critical information.
+
+   b. Set `{phase_2_status}` = "failed"; do NOT advance `{phase_3_status}`.
+
+   c. HALT with this exact user-facing message — **be specific about resume mechanics**, since the value of preserving Phase 1 epics is wasted if the user thinks they must restart:
+
+      ```
+      ❌ Phase 2 (Sprint Planning Bridge) failed.
+
+      Sprint planning produced no usable sprint-status.yaml. Failure marker written to:
+        {implementation_artifacts}/bridge-failure.json
+
+      ✅ Phase 1 artifact (epics.md) is preserved.
+
+      🔄 Recovery:
+        1. Fix the underlying cause (likely malformed epics.md — see bridge-failure.json for details).
+        2. Run /xiaoma-sprint-planning (SP) manually to confirm sprint-status.yaml generates cleanly.
+        3. Re-run /xiaoma-auto-prd-to-stories. step-01 already treats epics.md as informational; pipeline will skip re-creation and pick up at Phase 2.
+      ```
+
+4. **Count Stories** (only if validation passed) — Parse and count:
    - `{epic_count}` — Number of `epic-N` entries
    - `{story_count}` — Total story keys matching `<digit>-<digit>-*`
    - `{backlog_count}` — Stories with status `backlog`
@@ -124,7 +177,7 @@ Proceeding to Phase 3 — Batch Story File Generation...
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-04-batch-create-stories.md`
+**NEXT:** Read fully and follow: `./steps/step-04-batch-create-stories.md`
 
 ---
 
@@ -138,6 +191,7 @@ Proceeding to Phase 3 — Batch Story File Generation...
 ## FAILURE MODES
 
 - Epics file missing or unreadable
-- Sprint planning workflow fails
-- Generated sprint-status.yaml is malformed or empty
-- No story entries found in sprint status
+- Sprint planning workflow fails — instead of bare HALT, a structured `bridge-failure.json` marker is written and Phase 1 `epics.md` is preserved for resume
+- Generated sprint-status.yaml is malformed or empty — same fallback path
+- No story entries found in sprint status — same fallback path (the explicit "no processable stories" HALT at the end of section 5 also routes through here when sprint-status.yaml exists but contains no story keys)
+- Failing to write `bridge-failure.json` atomically (would leave a half-written marker; use temp-file-then-rename)

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

@@ -2,13 +2,14 @@
 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'
+kind: 'orchestrator'
 ---
 
 # 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
+**Role:** Dev (xiaokai) — Pipeline Batch Scheduler (Story-Preparation mode)
 
 ---
 
@@ -47,7 +48,7 @@ Main conversation (scheduler, minimal context)
   Phase 3 of 3 — Batch Create Detailed Story Files
 ═══════════════════════════════════════════════════
 
-Switching role to SM (xiaomin) batch scheduler...
+Switching to Dev (xiaokai) batch scheduler (Story-Preparation mode)...
 Using Agent subprocess isolation — each story processed independently.
 
 For each story, an independent Agent will:
@@ -128,7 +129,7 @@ The Agent's prompt MUST contain the following complete information for independe
 
 **3. Workflow Path (single workflow, narrow scope):**
 
-- `create_story_workflow`: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
+- `create_story_workflow`: `skill:xiaoma-create-story`
 
 **4. Project Context:**
 
@@ -136,7 +137,7 @@ The Agent's prompt MUST contain the following complete information for independe
 
 **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}`.
+> You are xiaokai, the Dev agent in Story-Preparation mode, 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:**
 >
@@ -291,7 +292,7 @@ Proceeding to Finalization...
 
 ## NEXT STEP
 
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md`
+**NEXT:** Read fully and follow: `./steps/step-05-finalize.md`
 
 ---
 

package/src/{xmc/workflows/5-full-pipeline/auto-prd-to-stories → xmc-skills/5-full-pipeline/xiaoma-auto-prd-to-stories}/steps/step-05-finalize.md

@@ -2,6 +2,7 @@
 name: 'step-05-finalize'
 description: 'Validate all artifacts, run completion checklist, and generate the final report for business-architect review'
 nextStepFile: null
+kind: 'terminal'
 ---
 
 # Step 5 of 5: Finalize PRD-to-Stories Pipeline
@@ -49,7 +50,7 @@ Fresh-read `{implementation_artifacts}/sprint-status.yaml` and parse:
 
 ### 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 `{skill-root}/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.
 
@@ -96,9 +97,9 @@ This implements Must Fix #4: ensure every functional requirement in `prd.md` is
 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`, ...)
+     a. FR identifiers appearing anywhere in the document matching `FR-?\d+` (canonical `FR-3`) **OR** `FR-[A-Z]+-\d+` (domain-scoped `FR-TENANT-01`, `FR-PROFILE-04` — the format produced by xiaoma-create-epics-and-stories / xiaoma-prd), where the `FR` is **NOT preceded by another letter** — i.e. match `(?<![A-Za-z])FR-…` so that `NFR-PERF-01` and other `NFR-` non-functional-requirement ids are **excluded** (they belong to the NFR inventory, not FR coverage). Collect the **unique set**; if ≥1 match, use these real identifiers as the inventory.
+     b. Lines under a section **whose heading contains** `Functional Requirements` or `功能需求` (match the substring — do NOT require an exact heading; real PRDs number their headings, e.g. `## 8. Functional Requirements`). If the bullets under it carry real `FR-…` ids, use those; otherwise treat each bullet/numbered item as one FR (assign synthetic ids `FR-1`, `FR-2`, ...).
+     c. Numbered headings under a section whose heading contains `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
 
@@ -238,7 +239,7 @@ the input to a manual quality review:
      to improve generation quality.
 
   5. When ready to enter development, run:
-       /xiaoma  →  load sm  →  ASB
+       /xiaoma  →  load dev  →  ASB
      (auto-story-pipeline-batch will pick up from ready-for-dev.)
 
 ───────────────────────────────────────────────────────────────
@@ -248,6 +249,36 @@ the input to a manual quality review:
 
 Write to: `{implementation_artifacts}/prd-to-stories-status.json`
 
+**Assemble `{warnings[]}` (single source of truth for downstream consumption):** Before writing, build a deduplicated, prefix-tagged warning list that mirrors the human "Structural Warnings" block — so external tools, dashboards, and the architect-review process can consume warnings without re-parsing the report text:
+
+- `[fr-coverage] Uncovered FR: {fr_id} — "{fr_title}"` (one entry per item in `{uncovered_frs}`)
+- `[tier-c] {story_key}: missing {section_list}` (one entry per Tier C story file)
+- `[self-reported] {story_key}: Agent reported db_design_status / impl_logic_status = missing` (from `story_results` cross-check)
+- `[fr-coverage-map] Map count ({epics_fr_count}) vs PRD-extracted FR count ({fr_coverage_denominator}) differ by >20%` (when applicable)
+- `[checklist] {failed_item}` (one entry per failed checklist item from section 3)
+- `[bridge-failure] sprint-planning workflow failed: {sprint_planning_error}` (only present if `{implementation_artifacts}/bridge-failure.json` exists from a previous failed run — informational, indicates resume scenario)
+
+Cap the list at 100 entries; if exceeded, truncate and append `[warnings-truncated] {N} additional warnings omitted`.
+
+> **Cross-pipeline note on prefix style:** The tags above
+> (`[fr-coverage]`, `[tier-c]`, `[self-reported]`, `[fr-coverage-map]`,
+> `[checklist]`, `[bridge-failure]`, `[warnings-truncated]`) are **semantic
+> category** tags — they describe *what kind of issue* the warning represents.
+> They are intentionally different from the `[step-NN]` **emitting-step** tags
+> used by `auto-story-pipeline/workflow.md` (Warning Prefix-Tag Convention)
+> and `auto-requirements-pipeline/workflow.md` (Warning Prefix-Tag
+> Convention), which describe *which step produced* the warning. Both
+> styles are valid; auto-prd-to-stories chose semantic tags because every
+> warning here originates from one of two steps (step-04 cross-checks,
+> step-05 finalize aggregation), so source-of-emission carries little signal
+> — issue *category* is the more useful axis. When `auto-full-pipeline`
+> step-05 finalize aggregates Phase-2 warnings, the auto-prd-to-stories tags
+> are preserved as-is and wrapped with `[phase-2]` (parallel to the
+> `[phase-1]`/`[phase-3:{story_key}]` wrap for the other pipelines). A
+> future dashboard layer could map between the two styles by treating
+> `[fr-coverage]` and friends as if they were emitted by step-05; the
+> mapping is documented here as the canonical translation point.
+
 ```json
 {
   "pipeline": "auto-prd-to-stories",
@@ -287,10 +318,18 @@ Write to: `{implementation_artifacts}/prd-to-stories-status.json`
         "tier_c_count": "{tier_c_count}"
       }
     }
-  }
+  },
+  "warnings": "{warnings[]}"
 }
 ```
 
+**Write strategy (atomic — temp-file-then-rename):**
+
+1. Write the JSON to `{implementation_artifacts}/prd-to-stories-status.json.tmp` first.
+2. Verify the temp file parses as JSON.
+3. Atomically `rename()` to `{implementation_artifacts}/prd-to-stories-status.json`.
+4. If the rename fails (e.g., cross-device `EXDEV`, unlikely since the temp file is in the same directory): log WARNING with the temp-file path and recovery instruction, but do NOT block the pipeline — the human-readable report and JSON content are already produced.
+
 ### 8. Pipeline Complete
 
 **Pipeline execution is COMPLETE. HALT.**
@@ -302,10 +341,11 @@ Write to: `{implementation_artifacts}/prd-to-stories-status.json`
 - 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
+- Machine-readable status file written **atomically** (temp-file-then-rename) with `warnings[]` field aggregated from FR-coverage gaps, Tier C files, Agent self-reports, FR-Coverage-Map discrepancy, checklist findings, and (when present) bridge-failure marker
 
 ## 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
+- Failure to atomically write the final status JSON (leaves a `prd-to-stories-status.json.tmp` for inspection; report content is unaffected)
+- `warnings[]` aggregator misses a category — caught by the cross-check between the human "Structural Warnings" block and the JSON warnings array