@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/{xmc/workflows/4-implementation/auto-story-pipeline → xmc-skills/4-implementation/xiaoma-auto-story-pipeline}/steps/step-06-test-story.md

@@ -3,13 +3,14 @@ name: "step-06-test-story"
 description: "Perform functional testing with real data using QA role"
 nextStepFile: "./step-08-complete-story.md"
 nextStepFile_fail: "./step-07-fix-and-retest.md"
+kind: "quality-gate"
 ---
 
 # Step 6 of 9: QA Functional Testing
 
 **Goal:** Perform comprehensive functional testing using real data to verify all acceptance criteria are met.
 
-**Role:** QA (xiaoce) — Quality Assurance Engineer
+**Role:** Dev (xiaokai) — QA mode (functional testing)
 
 ---
 
@@ -27,10 +28,10 @@ nextStepFile_fail: "./step-07-fix-and-retest.md"
 
 ## EXECUTION SEQUENCE
 
-### 1. Switch to QA Role
+### 1. Switch to QA Mode
 
-Adopt the QA persona:
-- You are xiaoce, the QA Engineer focused on functional correctness
+Adopt the Dev agent's QA mode:
+- You are xiaokai, the Dev agent in QA mode, focused on functional correctness
 - Your mission: verify every acceptance criterion with real data
 - Zero tolerance for mock data or fake test passes
 - Test from the user's perspective — does it actually work?
@@ -53,6 +54,7 @@ Invoke the `xiaoma-qa-generate-e2e-tests` skill to generate automated test files
 - Generate API tests for any new/modified endpoints
 - Generate E2E tests for any new/modified UI features
 - Run the generated tests to verify they pass; fix any failures immediately
+- When invoking a test runner directly, target specific test files or an explicit glob — NOT a bare directory (e.g. `node --test test/foo.test.js`, not `node --test <dir>`, which errors on some Node versions and would falsely report a failed suite). Prefer the project's configured test script (e.g. `npm test`) when one exists
 
 If the project has no test framework or tests are not applicable for this story type, skip this step and proceed directly to functional verification.
 
@@ -121,10 +123,10 @@ Create a test results summary:
 ## NEXT STEP
 
 **If tests pass:**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-08-complete-story.md`
+**NEXT:** Read fully and follow: `./steps/step-08-complete-story.md`
 
 **If tests fail:**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-07-fix-and-retest.md`
+**NEXT:** Read fully and follow: `./steps/step-07-fix-and-retest.md`
 
 ---
 
@@ -190,16 +192,27 @@ Create a test results summary:
 
 ### 3. 测试覆盖率阈值 (Coverage Thresholds)
 
-**强制要求:**
-- 单元测试覆盖率: >= 75%
-- 集成测试覆盖率: >= 60%
-- 接受标准覆盖率: 100% (所有AC必须有至少1个测试)
+**配置 (Configurable via `{project-root}/_xiaoma/xmc/config.yaml`):**
 
-**如果未达到:**
+Read the following keys from config (defaults shown). If a key is absent, use the default. If the project is a type for which a metric is not meaningful (e.g., a CLI without integration tests), set the corresponding key to `null` in config to disable that threshold.
+
+- `qa.unit_coverage_threshold` — default 75 (percent)
+- `qa.integration_coverage_threshold` — default 60 (percent)
+- `qa.ac_coverage_threshold` — default 100 (percent — required)
+- `qa.enforce_coverage_thresholds` — default `true`. If `false`, missing-threshold failures are recorded as warnings instead of blocking.
+
+**强制要求 (when `enforce_coverage_thresholds` is true and thresholds are not `null`):**
+- 单元测试覆盖率: >= `{unit_coverage_threshold}` (default 75%)
+- 集成测试覆盖率: >= `{integration_coverage_threshold}` (default 60%)
+- 接受标准覆盖率: >= `{ac_coverage_threshold}` (default 100% — every AC must have at least 1 test)
+
+**如果未达到 (and enforcement is on):**
 - 不允许进入step-07
 - 回到开发阶段添加缺失的tests
 - Type: AC-Incomplete failure → 标记story为"NEEDS_MORE_TESTS"
 
+**If enforcement is off:** Log a WARNING in the QA Results section noting the gap; continue. Append to `{run_warnings}`: `[step-06] Coverage threshold not enforced (enforce_coverage_thresholds=false) for {current_story_key} — unit {unit_pct}% / integration {integration_pct}% / AC {ac_pct}%`
+
 ### 4. 记录失败详情 (Document Failures)
 
 在Story文件的"QA Results"部分记录:
@@ -233,7 +246,7 @@ Create a test results summary:
 
 ### 5. 条件通过规则 (Conditional Pass)
 
-故事可以在以下条件下**有条件通过**到step-07:
+故事可以在以下条件下**有条件通过**到step-08:
 
 ✅ **全部Type A/B失败已解决**
 ✅ **至少80%的接受标准通过** 

package/src/{xmc/workflows/4-implementation/auto-story-pipeline → xmc-skills/4-implementation/xiaoma-auto-story-pipeline}/steps/step-07-fix-and-retest.md

@@ -3,6 +3,7 @@ name: "step-07-fix-and-retest"
 description: "Fix bugs found in review/testing, then re-run tests. Self-referencing loop with max 5 iterations."
 nextStepFile: "./step-08-complete-story.md"
 nextStepFile_loop: "./step-07-fix-and-retest.md"
+kind: "loop"
 ---
 
 # Step 7 of 9: Fix and Retest
@@ -23,13 +24,25 @@ Set `{max_fix_iterations}` from config (or default 5).
 
 ## LOOP CONTROL
 
+This step uses a hybrid loop pattern:
+- `{fix_iteration}` is the canonical iteration counter (incremented once per entry to this step file).
+- The "next step → step-07" recursion in section 6 exists only to force a fresh file reload (combats long-context degradation). It is NOT a counter — the counter is `{fix_iteration}`.
+
+0. **Nil guard — initialize `{fix_iteration}` if it is unset or null.**
+   - Normal entry: step-01 initialized `{fix_iteration}` = 0, so this guard is a no-op.
+   - Resume entry: future resume modes that jump directly to step-07 (e.g., resuming a story whose status is `review` and which already has known fix work pending) may not have re-initialized the counter. To stay safe, treat unset / null as 0 here.
+   - Routed-from-step-05 entry: step-05 routes to step-07 with `{fix_iteration}` carried over from earlier in the same run; nothing to do.
+   - Action: `IF {fix_iteration} is null OR unset: set {fix_iteration} = 0`. This is idempotent and never overwrites an existing positive counter.
+
 1. Increment `{fix_iteration}` by 1
 2. **IF `{fix_iteration}` > `{max_fix_iterations}`:**
+   - Append to `{run_warnings}`: `[step-07] Max fix iterations ({max_fix_iterations}) reached for {current_story_key} — escalation dispatched (see protocol A/B/C/D)`
    - HALT — "Fix iteration limit reached ({max_fix_iterations} attempts) for story {current_story_key}. Remaining issues: {unresolved_issues}. Manual intervention required."
    - Output a summary of all fix attempts and remaining issues
    - **DO NOT CONTINUE** — This is a hard stop
+   - *(Note: this append happens before HALT so any partial-status snapshot writer downstream of a future escalation-recovery path can serialize the warning; on hard HALT the warning will not reach step-09's status JSON because step-09 does not execute.)*
 
-3. Set `{steps_completed}` = `{steps_completed}` + 1
+3. Increment `{steps_completed}` ONLY on the first entry to step-07 (when `{fix_iteration}` == 1). Subsequent loop re-entries (iterations 2..N) do NOT increment `{steps_completed}` — the step file is the same step, just re-loaded. This keeps the `{steps_completed}` semantic stable as "distinct pipeline step files executed", so the final report shows e.g. 9/9 regardless of how many fix iterations occurred.
 4. Output: "Fix Iteration {fix_iteration}/{max_fix_iterations} for story {current_story_key}"
 
 ---
@@ -52,9 +65,9 @@ Adopt the Dev persona:
    - Mixed (both code review and QA issues): → `{fix_source}` = "mixed"
 3. Record `{fix_source}` — this determines post-fix routing (see section 6)
 4. Compile a prioritized fix list:
-   - **Priority 1:** HIGH severity issues / failed acceptance criteria
+   - **Priority 1:** CRITICAL and HIGH severity issues / failed acceptance criteria (CRITICAL issues are routed here by step-05 §4 as Priority 1 — see step-05-code-review.md L47 routing contract)
    - **Priority 2:** MEDIUM severity issues / partial AC failures
-   - **Priority 3:** LOW severity issues (fix if time permits)
+   - **Priority 3:** LOW severity issues (fix if time permits; LOW may remain as documented tech debt per step-05 §4 pass criteria)
 
 ### 3. Build Fix Plan
 
@@ -90,31 +103,31 @@ After all fixes are applied:
 **IF all tests pass AND all previously failed ACs now pass:**
 - Output: "All issues resolved in fix iteration {fix_iteration}. Tests passing."
 - Determine routing based on `{fix_source}`:
-  - **IF `{fix_source}` == "code-review" or "mixed":** Run a targeted code re-check: re-verify that the specific code-review HIGH/MEDIUM issues are genuinely resolved (no full re-delegation required — do a focused inline verification of the fixed areas). If verified clean: **NEXT:** Proceed to step-08 (complete story). If new issues surface: Loop back to step-07.
-  - **IF `{fix_source}` == "qa-testing":** **NEXT:** Proceed to step-08 (complete story) directly — no additional code review needed.
+  - **IF `{fix_source}` == "code-review" or "mixed":** Run a targeted code re-check: re-verify that the specific code-review HIGH/MEDIUM issues are genuinely resolved (no full re-delegation required — do a focused inline verification of the fixed areas). If verified clean: **NEXT:** Proceed to step-08 (complete story) [frontmatter: nextStepFile]. If new issues surface: Loop back to step-07.
+  - **IF `{fix_source}` == "qa-testing":** **NEXT:** Proceed to step-08 (complete story) directly — no additional code review needed [frontmatter: nextStepFile].
 
 **IF some issues remain:**
 - Output: "Fix iteration {fix_iteration} resolved {fixed_count} issues. {remaining_count} issues remain: {remaining_list}"
-- **NEXT:** Loop back to this step (step-07) for another iteration
+- **NEXT:** Loop back to this step (step-07) for another iteration [frontmatter: nextStepFile_loop]
 
 ---
 
 ## NEXT STEP
 
 **If all issues resolved AND (`{fix_source}` == "qa-testing" OR post-fix code re-check passed):**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-08-complete-story.md`
+**NEXT:** Read fully and follow: `./steps/step-08-complete-story.md`
 
 **If all issues resolved but post-fix code re-check surfaced new issues (`{fix_source}` was "code-review" or "mixed"):**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-07-fix-and-retest.md`
+**NEXT:** Read fully and follow: `./steps/step-07-fix-and-retest.md`
 
 **If issues remain and `{fix_iteration}` <= `{max_fix_iterations}`:**
-**NEXT:** Read fully and follow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-07-fix-and-retest.md`
+**NEXT:** Read fully and follow: `./steps/step-07-fix-and-retest.md`
 
 ---
 
 ## SUCCESS METRICS
 
-- All HIGH and MEDIUM issues resolved
+- All CRITICAL, HIGH and MEDIUM issues resolved (consistent with step-05 §4 pass criteria; LOW issues may remain as documented tech debt)
 - All previously failed acceptance criteria now pass
 - Full test suite passes with no regressions
 - Fix details documented in story file
@@ -129,7 +142,9 @@ After all fixes are applied:
 
 ---
 
-## 当超过最大修复迭代次数 (Escalation Path: Beyond Max Fix Iterations)
+## Escalation Path: Beyond Max Fix Iterations (当超过最大修复迭代次数)
+
+> **English summary (normative for non-Chinese readers):** When `{fix_iteration}` exceeds `{max_fix_iterations}` (default 5), this step HALTs the pipeline and dispatches an escalation. The escalation produces (1) an Escalation Report documenting all fix attempts and root-cause analysis, (2) a notification to Story Owner/Dev (xiaokai) and Tech Lead/Architect (xiaojia), and (3) four handling options — A: Mark as BLOCKED (architectural review), B: Reduce scope (defer failing AC), C: Tech Lead deep-dive (re-route to architect), D: Fresh start (revert and re-execute step-04 onward). The Chinese sections below detail each option's state-transition contract. All four options re-enter the pipeline at a different step (A → out-of-sprint, B → step-08, C → step-07 after architect input, D → step-04). The append of `[step-07] Max fix iterations reached without convergence; escalation A/B/C/D dispatched` to `{run_warnings}` (per workflow.md prefix-tag table) happens BEFORE the HALT so downstream consumers see the escalation event.
 
 **触发条件:** `{fix_iteration}` > `{max_fix_iterations}` (默认 > 5)
 
@@ -160,7 +175,7 @@ Recommended Action: [A/B/C below]
 ### 2. 通知团队 (Owner Notification)
 
 发送通知至:
-- **Primary:** Story Owner / Scrum Master (xiaofen)
+- **Primary:** Story Owner / Dev agent (xiaokai)
 - **Secondary:** Tech Lead / Architect (xiaojia)
 
 **Notification Template:**
@@ -224,7 +239,7 @@ estimated_resolution_time: [hours]
 ### 5. 防止进度堵塞 (Prevent Sprint Blocking)
 
 - 不允许story卡在此步骤超过{max_fix_iterations} + 4小时
-- 自动移至Scrum Master队列以处理escalation
+- 自动上报以处理 escalation（由 Developer xiaokai 跟进）
 - 在sprint status中标记为"NEEDS_DECISION"
 - 不将此issue计入sprint velocity（因为未完成）
 

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps/step-08-complete-story.md

@@ -0,0 +1,174 @@
+---
+name: "step-08-complete-story"
+description: "Mark story as done, update sprint-status, and generate completion summary"
+nextStepFile: "./step-09-finalize.md"
+kind: "finalize"
+---
+
+# Step 8 of 9: Complete Story
+
+**Goal:** Mark the story as done, sync all tracking artifacts, and generate a completion summary.
+
+**Role:** Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Final Validation
+
+Before marking complete, verify all gates:
+1. **Fresh Read:** Read the COMPLETE story file at `{current_story_path}` directly from disk (not from cache or prior state). This is critical because step-07 may have modified the file (e.g., updated task checkboxes, changed story status), and you MUST verify the current on-disk state, not a stale in-memory version.
+2. Verify ALL tasks and subtasks are marked [x], [X], or [✓] (case-insensitive, all formats accepted)
+3. Verify ALL acceptance criteria have been tested and passed
+4. Verify no unresolved HIGH or MEDIUM issues remain
+5. Verify the full test suite passes
+
+If any gate fails: **DO NOT mark as done** — return to the appropriate step:
+- Incomplete tasks → step-04 (develop)
+- Failed tests → step-07 (fix and retest)
+- Unresolved review issues → step-07 (fix and retest)
+
+### 1.5. AC ↔ Test Traceability Verification (best-effort, advisory-only)
+
+Best-effort cross-document check that each acceptance criterion (AC) in the story file maps to at least one passing test in the step-06 test report. **Surface-only / non-gating** — symmetric in design to the requirement-level traceability check in `auto-requirements-pipeline/steps/step-08-finalize.md §2.4`. Failures here append a prefix-tagged warning to `{run_warnings}` but do NOT block the story from being marked done; the existing gate at §1 item 3 ("ALL acceptance criteria have been tested and passed") remains the authoritative block. The purpose is to make orphan ACs (acceptance criteria that were checked off by gate §1 item 3 but cannot be machine-linked back to a concrete test execution record) visible to downstream consumers (ASPB scheduler, auto-full-pipeline `[phase-3]` aggregator, dashboards, retro-tooling).
+
+**Procedure:**
+
+1. **Locate the test report.** Read `step-06`'s test report from the story file's "QA Results" or "Test Results" section (whichever convention is used in this project — discoverable from the story file directly). If neither section exists, or the section is empty: Append to `{run_warnings}` exactly one summary entry: `[step-08] AC-test traceability check skipped — step-06 test report not found in story file` ; then skip to §2.
+2. **Extract AC identifiers.** From the story file's "Acceptance Criteria" section, extract each AC identifier using best-effort heuristics: (a) explicit IDs like `AC1`, `AC-2`, `[AC-3]`; (b) numbered list items (`1.`, `2.`, etc.); (c) bullet list items with leading bold keywords (`**Given...**`, `**When...**`, `**Then...**`). If extraction yields zero IDs: Append to `{run_warnings}` exactly one summary entry: `[step-08] AC-test traceability check skipped — acceptance criteria section does not use a recognizable identifier convention` ; then skip to §2.
+3. **Walk the mapping.** For each extracted AC ID, search the test report for at least one passing test referencing it (by ID, by description keyword overlap ≥2 tokens, or by explicit "AC-N" annotation). Use the same loose-matching heuristic as `validate:trigger-emit-bidi` (case-insensitive, normalized whitespace).
+4. **Emit orphans.** For each AC with no matching passing test, Append to `{run_warnings}`: `[step-08] AC-test traceability orphan detected: {ac_id} has no passing test in step-06 report — manual review recommended` and continue (no halt). The §1 item 3 gate already prevented this section from being reached if any AC was outright failing; orphans here are ACs that were marked passed but cannot be machine-linked.
+5. **Continue to §2.** Regardless of orphan count, proceed to "Update Story Status". The check is observational; the gate at §1 is authoritative for halting.
+
+**Why a sub-section, not a new step:** Adding a 10th step would inflate the pipeline count and break the documented `N/9` rendering throughout step-09's completion report. A §1.5 sub-section keeps the pipeline cardinality stable while delivering the missing check. The numbering for downstream items (§2 update status, §3 sprint-status, etc.) is preserved.
+
+### 2. Update Story Status
+
+1. Update the story Status field to "done"
+2. Add completion timestamp to Dev Agent Record
+3. Add final Change Log entry: "Story completed via auto-pipeline on {date}"
+4. Save the story file
+
+### 3. Update Sprint Status
+
+1. Load the FULL file: `{sprint_status}`
+2. Find `development_status` key matching `{current_story_key}`
+3. Update `development_status[{current_story_key}]` = "done"
+4. Update `last_updated` field to current date
+5. Save file, preserving ALL comments and structure
+6. **Write safely (avoid half-written sprint-status.yaml):**
+   - Write the updated YAML to a sibling temp file in the same directory (e.g., `{sprint_status}.tmp`)
+   - Verify the temp file is non-empty and parses as valid YAML
+   - Atomically rename the temp file over `{sprint_status}` (this avoids leaving a half-written file if the process is interrupted between writes — important because step-09 reads this file again and the auto-story-pipeline-batch / auto-full-pipeline orchestrators may read it across pipeline runs)
+   - If the rename fails or YAML re-parse fails: Append to `{run_warnings}`: `[step-08] Sprint-status write failed for {current_story_key} (rename or YAML re-parse error) — manual recovery required` ; then HALT — "Sprint-status write failed for {current_story_key}. Manual recovery required: check {sprint_status} and {sprint_status}.tmp."
+
+### 4. Check Epic Completion
+
+1. Extract `{epic_num}` from `{current_story_key}` using pattern matching:
+   - Pattern: story key must match `{epic_num}-{story_num}-{name}` where epic_num and story_num are positive integers
+   - Extract: Read first numeric component before first dash
+   - Example: "1-2-user-auth" → epic_num = "1"
+   - Example: "12-3-payment-flow" → epic_num = "12"
+   - Skip keys that don't match pattern (e.g., "epic-1-retrospective" is an epic marker, not a story)
+   - If key doesn't match expected pattern: Output WARNING — "Could not extract epic number from {current_story_key}. Skipping epic completion check." and skip to section 5
+     - Append to `{run_warnings}`: `[step-08] Could not extract epic number from {current_story_key} — epic completion check skipped`
+   - If extraction fails for any reason: Continue without epic update (non-blocking)
+2. In sprint-status.yaml, find all stories for epic `{epic_num}` (pattern: `{epic_num}-*`, excluding epic markers like `epic-{epic_num}` and retrospectives like `epic-{epic_num}-retrospective`)
+3. Check if ALL stories in this epic have status "done"
+4. If all stories are done:
+   - Update `development_status[epic-{epic_num}]` = "done"
+   - Set `{epic_just_completed}` = `{epic_num}` (consumed in step-09 for retrospective recommendation)
+   - Output: "Epic {epic_num} fully completed! All stories are done."
+5. If some stories remain:
+   - Set `{epic_just_completed}` = null
+   - Output: "Epic {epic_num}: {done_in_epic}/{total_in_epic} stories completed."
+
+### 5. Generate Completion Summary
+
+Increment `{stories_completed}` by 1
+
+**QA Testing phase marker (conditional):** Step-06 (QA Testing) is bypassed when step-05 routes code-review findings directly to step-07 (`{fix_source}` == "code-review"; see step-07 §6 — code-review fixes go straight to step-08, never back through step-06). In that case render the QA Testing line in the report below as `[-] QA Testing (QA) — skipped (code-review issues routed step-05 → step-07; full QA with real data was not run for this story)` instead of `[x] QA Testing (QA)`. For every other path (`{fix_source}` unset on the clean route, or "qa-testing" / "mixed"), step-06 ran — keep `[x] QA Testing (QA)`.
+
+Output:
+```
+Story {current_story_key} — COMPLETED
+
+Summary:
+- Story: {story_title}
+- File: {current_story_path}
+- Status: done
+- Fix Iterations Used: {fix_iteration}
+- Stories Completed This Pipeline Run: {stories_completed}
+
+Pipeline Phases Completed:
+  [x] Story Creation (Dev)
+  [x] Story Validation (PM)
+  [x] Development (Dev)
+  [x] Code Review (Reviewer)
+  [x] QA Testing (QA)
+  [x] Status Updated (done)
+```
+
+### 6. Pipeline Status Update
+
+- Set `{pipeline_status}` = "story-completed"
+- Set `{steps_completed}` = `{steps_completed}` + 1
+
+### 7. Batch-Mode Result Block (conditional)
+
+**Trigger:** This section applies ONLY when this step-08 file is being executed by an Agent subprocess launched by the `auto-story-pipeline-batch` (ASPB) scheduler. The signal is behavioral, not a state variable: the ASPB scheduler's prompt explicitly instructs the Agent to "STOP after step-08 and return STORY_RESULT" (see `auto-story-pipeline-batch/workflow.md` section 2.3 part 5 "Important instructions for the Agent"). In single-story mode (no ASPB wrapper) or resume mode, skip this section and proceed to step-09 normally per the NEXT STEP below.
+
+**Why an explicit template here?** Without it, the Agent may emit STORY_RESULT but omit or empty the `warnings` field, silently dropping every prefix-tagged warning accumulated in `{run_warnings}` during step-02 → step-08. The contract defines the field; this template ensures the producer side actually populates it.
+
+**Emit the following STORY_RESULT block as the final output before exiting:**
+
+```
+STORY_RESULT:
+- story_key: {current_story_key}
+- final_status: done
+- fix_iterations_used: {fix_iteration}
+- validation_attempts: {validation_attempt}
+- files_modified: [<list of file paths modified during step-04 through step-08>]
+- summary: <one-line description of what was done>
+- error: <empty string on success; populated only if a HALT was reached>
+- warnings: {run_warnings}
+```
+
+**Serialization rules:**
+
+1. `warnings:` MUST serialize the full `{run_warnings}` list as-is — do NOT strip, reorder, or de-duplicate. Each entry must retain its `[step-NN]` prefix tag (see `auto-story-pipeline/workflow.md` → "Warning Prefix-Tag Convention" for the dictionary). If `{run_warnings}` is empty, emit `warnings: []`.
+2. `final_status` is "done" when this section executes (gate failures earlier in step-08 would have routed back to step-04/07 before reaching here). The "halted" / "failed" variants only apply when a HALT path in step-02 → step-08 returned control before reaching this section — in that case the Agent emits STORY_RESULT at the HALT site, not here.
+3. `files_modified:` is the union of files written across step-04 (dev), step-05 (review auto-fix), step-07 (fix-retest), and step-08 (story file + sprint-status.yaml).
+4. `error:` is empty on success. Reserved for downstream parsers — never omit the field.
+
+**After emitting STORY_RESULT, STOP.** Do NOT read step-09. The ASPB scheduler's section 2.4 will parse this block and section 2.4b will write the per-story archive `story-pipeline-status.{current_story_key}.json` (which is the batch-mode replacement for step-09's single-story `story-pipeline-status.json`).
+
+**Concrete sample output:** Two realistic STORY_RESULT examples (one `done` with accumulated warnings, one `halted` at step-07 max-iter) are documented in `auto-story-pipeline-batch/workflow.md` section 2.3's "Concrete examples" block (an unnumbered block following part 6 "Return Format"). Agent runners should consult those samples to verify the shape of the emitted block before committing to a particular serialization style; the scheduler accepts both YAML-list and JSON-array forms for `warnings`/`files_modified`.
+
+---
+
+## NEXT STEP
+
+**Single-story mode / resume mode:** Read fully and follow: `./steps/step-09-finalize.md`
+
+**Batch mode (ASPB subprocess):** Do NOT read step-09. Emit the STORY_RESULT block from section 7 above and exit.
+
+---
+
+## SUCCESS METRICS
+
+- Story status set to "done" in story file
+- Sprint-status.yaml updated with "done" for story key
+- Epic completion checked and updated if applicable
+- Completion summary generated
+- `{stories_completed}` counter incremented
+- **Batch mode:** STORY_RESULT block emitted with `warnings: {run_warnings}` serialized as-is (full list, prefix tags preserved); Agent exits without reading step-09
+
+## FAILURE MODES
+
+- Marking story done without verifying all gates
+- Not updating sprint-status.yaml
+- Not checking epic-level completion
+- Not generating completion summary
+- **Batch mode:** Emitting STORY_RESULT with `warnings: []` when `{run_warnings}` was non-empty (silently drops accumulated warnings — breaks the warnings plumbing); omitting the `warnings` field entirely (legacy contract — scheduler tolerates this but downstream consumers lose Phase-3 visibility); reading step-09 after section 7 was triggered (step-09 will attempt to write the single-story canonical `story-pipeline-status.json` and conflict with the per-story archive)

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/steps/step-09-finalize.md

@@ -0,0 +1,145 @@
+---
+name: "step-09-finalize"
+description: "Finalize the single-story pipeline run and output completion report."
+nextStepFile: null
+kind: "terminal"
+---
+
+# Step 9 of 9: Pipeline Finalization
+
+**Goal:** Generate the final completion report for this single-story pipeline run.
+
+**Role:** Pipeline Orchestrator
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Refresh Sprint Status
+
+1. Load the FULL file: `{sprint_status}` (fresh read from disk — do NOT rely on in-memory state from earlier steps; step-08 may have updated multiple keys including the epic marker)
+2. Read ALL lines from beginning to end — do not skip any content
+3. Recount all stories by current status (exclude epic markers like `epic-{n}` and retrospective markers like `epic-{n}-retrospective` from story counts; tally them separately if useful):
+   - `{backlog_count}` — Stories with status "backlog"
+   - `{ready_count}` — Stories with status "ready-for-dev"
+   - `{in_progress_count}` — Stories with status "in-progress"
+   - `{review_count}` — Stories with status "review"
+   - `{done_count}` — Stories with status "done"
+4. Sanity check: verify the just-completed story `{current_story_key}` has status "done" in sprint-status.yaml. If it does NOT:
+   - Output WARNING — "Sprint status for {current_story_key} is '{actual_status}', not 'done'. step-08 may not have synced. Manual review recommended."
+   - Append to `{run_warnings}` with canonical prefix tag: `[step-09] Sprint status for {current_story_key} is '{actual_status}', not 'done' — step-08 sync may have failed`
+   - Continue with report generation regardless.
+
+### 2. Generate Final Report
+
+Increment `{steps_completed}` to count step-09 itself as a distinct executed step file (mirrors the +1 pattern used by steps 02–08; without this line, a fresh run that executes all nine step files would display `8 / 9` instead of `9 / 9`, because step-09 would otherwise be silently uncounted):
+
+- Set `{steps_completed}` = `{steps_completed}` + 1
+
+**Note on `{steps_completed}` semantics:** `{steps_completed}` is the count of *distinct step files executed in THIS pipeline run*, not the total step count in the pipeline (which is always 9). A fresh run reaches 9 only when every step file executes exactly once. Common fresh runs legitimately finish below 9: a run where step-05 routes directly to step-07 skips step-06 (QA testing), and a run that needs no fixes skips step-07 (fix-and-retest) — both correctly display `8 / 9`. A value under 9 is therefore expected, not an error, because the counter tracks distinct step files actually executed. For a `resume` run (e.g., starting at step-04 because story status was "in-progress"), the value reflects only the steps actually loaded plus step-09 itself — display it relative to 9 so it is unambiguous.
+
+Output:
+```
+Auto Story Pipeline — COMPLETE
+
+Pipeline Summary:
+- Mode: {pipeline_mode}
+- Story Processed: {current_story_key}
+- Steps Executed (this run): {steps_completed} / 9
+- Fix Iterations: {fix_iteration} / {max_fix_iterations}
+- Pipeline Status: finalized
+
+Sprint Status (current):
+- Backlog: {backlog_count} remaining
+- Ready for Dev: {ready_count}
+- In Progress: {in_progress_count}
+- In Review: {review_count}
+- Done: {done_count}
+
+The automated story development pipeline has finished.
+```
+
+**IF `{epic_just_completed}` is set (signal from step-08 section 4):**
+- Output: "Epic {epic_just_completed} is now fully complete. Recommended next action: run epic-retrospective (ER) to capture lessons learned before starting the next epic. Command: `/xiaoma-retrospective` (or `ER` from the Dev (xiaokai) menu)."
+
+**IF `{backlog_count}` == 0 AND `{ready_count}` == 0 AND `{in_progress_count}` == 0 AND `{review_count}` == 0:**
+- Output: "All stories in the sprint are complete! Consider running epic-retrospective (ER) to review the work."
+
+**IF `{backlog_count}` > 0 OR `{ready_count}` > 0:**
+- Output: "There are still {backlog_count + ready_count} pending stories. Run ASPB (`/xiaoma-auto-story-pipeline-batch`) to process all remaining stories in batch mode, or run ASP again to process the next story."
+
+### 3. Generate Machine-Readable Status File
+
+Write machine-readable status to: `{implementation_artifacts}/story-pipeline-status.json`
+
+This brings parity with `auto-requirements-pipeline` (which writes `pipeline-status.json`) and enables downstream tools — including `auto-story-pipeline-batch` (ASPB) and `auto-full-pipeline` — to inspect per-story outcomes programmatically without re-parsing sprint-status.yaml.
+
+**Warnings serialization:**
+
+Read the accumulated `{run_warnings}` list and serialize it as-is into the `warnings` array — each entry MUST already carry its canonical `[step-NN]` prefix tag (see `auto-story-pipeline/workflow.md` → "Warning Prefix-Tag Convention" for the dictionary). Do NOT strip, reorder, or de-duplicate entries here; downstream consumers (ASPB scheduler, auto-full step-05-finalize) handle de-dup and 100-entry truncation in their own aggregation passes.
+
+Common sources that contribute entries to `{run_warnings}` during a typical run:
+- `[step-01]` — prerequisite probe (stale `pipeline-status.json`); incomplete story-file routing entry
+- `[step-02]` — sprint-status / on-disk inconsistency; incomplete created story retry
+- `[step-03]` — non-terminal validation iteration WARNING
+- `[step-05]` — CRITICAL finding routed to step-07; auto-fix produced regression
+- `[step-06]` — coverage threshold not enforced; type-C performance carve-out
+- `[step-07]` — max fix iterations reached / escalation dispatched
+- `[step-08]` — sprint-status write fallback; epic-completion check skipped due to unparseable story key
+- `[step-09]` — sanity-check WARNING from section 1 item 4 above (this step). (Note: this step's section 1 contains 4 numbered items, not subsections; AW2 fixed an earlier "section 1.4" reference that implied a non-existent `### 1.4` heading.)
+
+If `{run_warnings}` is empty, serialize as `[]`.
+
+```json
+{
+  "pipeline": "auto-story-pipeline",
+  "date": "{date}",
+  "project": "{project_name}",
+  "mode": "{pipeline_mode}",
+  "story_key": "{current_story_key}",
+  "story_path": "{current_story_path}",
+  "final_status": "done",
+  "steps_completed_this_run": {steps_completed},
+  "pipeline_total_steps": 9,
+  "fix_iterations_used": {fix_iteration},
+  "max_fix_iterations": {max_fix_iterations},
+  "epic_just_completed": "{epic_just_completed}",
+  "sprint_snapshot": {
+    "backlog": {backlog_count},
+    "ready_for_dev": {ready_count},
+    "in_progress": {in_progress_count},
+    "review": {review_count},
+    "done": {done_count}
+  },
+  "warnings": [
+    "[step-NN] human-readable description (see workflow.md → Warning Prefix-Tag Convention)",
+    "..."
+  ]
+}
+```
+
+If `{epic_just_completed}` is null, write `"epic_just_completed": null` (not the literal placeholder). If no warnings were captured, write `"warnings": []`. Each warning entry MUST retain its `[step-NN]` prefix tag as emitted by the source step — do not strip.
+
+**Write strategy:** Write to a temp file in the same directory (e.g., `story-pipeline-status.json.tmp`), then rename to the final name. This avoids leaving a half-written status file if the process is interrupted between writes.
+
+**HALT** — Pipeline complete.
+
+---
+
+## SUCCESS METRICS
+
+- Final sprint status refreshed from disk
+- Sanity check on `{current_story_key}` performed (warning emitted if not "done"; tagged `[step-09]` and appended to `{run_warnings}`)
+- Comprehensive completion report generated, with `{steps_completed}` rendered as `N / 9` for clarity
+- `{epic_just_completed}` signal consumed (ER recommendation emitted when set)
+- `story-pipeline-status.json` written atomically with full run metadata
+- `warnings[]` entries all carry canonical `[step-NN]` prefix tags (single-source-of-truth dictionary lives in `auto-story-pipeline/workflow.md` → "Warning Prefix-Tag Convention")
+- User informed of remaining stories and next steps
+
+## FAILURE MODES
+
+- Not refreshing sprint status before generating report
+- Skipping final report generation
+- Writing `story-pipeline-status.json` without temp-file-then-rename (risk of half-written JSON if interrupted)
+- Reporting `{steps_completed}` without the `/ 9` denominator (ambiguous in resume mode)
+- Serializing `warnings[]` entries WITHOUT the `[step-NN]` prefix (breaks ASPB / auto-full-pipeline aggregation contract — single-story mode and batch mode would diverge in warning format)