@zeyue0329/xiaoma-cli 1.8.0 → 1.8.3

package/CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+XiaoMa-CLI (`@zeyue0329/xiaoma-cli`) is an AI-driven agile development framework/CLI tool. It installs specialized AI agent personas, workflows, and skills into a user's project directory for use with AI IDEs (Claude Code, Cursor, etc.). Node.js v20+ required.
+
+## Common Commands
+
+```bash
+# Quality gate (run before commits)
+npm run quality
+
+# Individual checks
+npm run test:schemas        # Agent YAML schema validation (Zod-based)
+npm run test:install        # Installation component tests
+npm run test:refs           # Cross-file reference validation
+npm run validate:schemas    # Schema validation (separate from test)
+npm run validate:refs       # File reference validation (strict mode)
+npm run lint                # ESLint (JS + YAML), zero warnings allowed
+npm run lint:md             # Markdown linting
+npm run format:check        # Prettier check
+npm run format:fix          # Prettier auto-fix
+
+# Test coverage
+npm run test:coverage       # c8 coverage report for schema tests
+
+# Run the CLI locally
+npm run install:xiaoma      # Run install command
+npm run xiaoma:uninstall    # Run uninstall command
+```
+
+The full `npm test` runs: test:schemas → test:refs → test:install → validate:schemas → lint → lint:md → format:check.
+
+## Architecture
+
+### Two-Layer Structure
+
+1. **`src/`** — Content modules (YAML agents, Markdown workflows, skills)
+2. **`tools/`** — CLI implementation (Node.js/CommonJS, installer, validators)
+
+### Module System
+
+Modules are defined by `module.yaml` files with configuration variables, prompts, and directory declarations:
+- **`src/core/`** — Shared skills and tasks (module code: `core`)
+- **`src/xmc/`** — XiaoMa Method module, the primary agile framework (module code: `xmc`)
+
+### Agent System (`src/xmc/agents/`)
+
+Agents are YAML files validated against a Zod schema (`tools/schema/`). Each agent defines:
+- `metadata` — id, name, title, icon, module, capabilities
+- `persona` — role, identity, communication_style, principles
+- `menu` — trigger commands pointing to workflow exec targets
+- `prompts` / `critical_actions` — optional
+
+### Workflow System (`src/xmc/workflows/`)
+
+Organized by development phase:
+- `1-analysis/` — Brainstorming, research, product brief
+- `2-plan-workflows/` — PRD creation/validation, UX design
+- `3-solutioning/` — Architecture, epics/stories, implementation readiness
+- `4-implementation/` — Sprint planning, story execution, code review, retros
+
+Each workflow has: `workflow.md` (entry point with metadata), `steps/` or `steps-{variant}/` directories, and optional `templates/` and `data/` directories.
+
+### CLI (`tools/cli/`)
+
+- **Entry**: `xiaoma-cli.js` (Commander.js) → wrapped by `xiaoma-npx-wrapper.js`
+- **Commands**: `install`, `status`, `uninstall`
+- **Installer** (`tools/cli/installers/`): Core orchestration class (~8K LOC), module manager, IDE config manager, manifest generator
+- **UI**: `@clack/prompts` for interactive terminal prompts
+
+### Skills (`src/core/skills/`)
+
+Reusable capabilities: `xiaoma-help`, `xiaoma-brainstorming`, `xiaoma-distillator`, `xiaoma-party-mode`, editorial review skills, etc.
+
+## Code Conventions
+
+- **JS**: CommonJS (`require`/`module.exports`) for all CLI/tool code
+- **YAML**: `.yaml` extension enforced by ESLint (not `.yml`); double quotes preferred
+- **Formatting**: Prettier with 140 char print width, 2-space indent, double quotes in YAML, single quotes in JS
+- **Linting**: ESLint flat config with unicorn, node, yml plugins; `--max-warnings=0`
+- **Schema validation**: Zod for agent YAML validation at `tools/schema/`
+- **Git hooks**: Husky + lint-staged (runs lint:fix and format:fix on staged files)
+
+## Testing
+
+Tests are plain Node.js scripts (no test framework), located in `test/`:
+- `test-agent-schema.js` — Validates all agent YAML against Zod schema; 50 fixtures (18 valid, 32 invalid); targets 100% coverage
+- `test-installation-components.js` — Installation flow verification
+- `test-file-refs-csv.js` — Validates cross-file references in CSV data files
+- Fixtures in `test/fixtures/agent-schema/{valid,invalid}/`

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@zeyue0329/xiaoma-cli",
-  "version": "1.8.0",
+  "version": "1.8.3",
   "description": "XiaoMa Universal AI Agent Framework",
   "keywords": [
     "agile",

package/src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-05-validate-prd.md

@@ -47,7 +47,7 @@ Invoke the `xiaoma-validate-prd` skill to validate the PRD.
 **CRITICAL PIPELINE MODE INSTRUCTIONS:**
 
 - This is running in **automated pipeline mode** — do NOT pause for user input
-- The validate-prd workflow has 13 step files in `steps-v/`: step-v-01-discovery, step-v-02-format-detection, step-v-02b-parity-check, step-v-03-density-validation, step-v-04-brief-coverage, step-v-05-measurability, step-v-06-traceability, step-v-07-implementation-leakage, step-v-08-domain-compliance, step-v-09-project-type, step-v-10-smart, step-v-11-holistic-quality, step-v-12-completeness, step-v-13-report-complete
+- The validate-prd workflow has 14 step files in `steps-v/` (step-v-02b is a conditional branch for specific PRD format detection scenarios): step-v-01-discovery, step-v-02-format-detection, step-v-02b-parity-check, step-v-03-density-validation, step-v-04-brief-coverage, step-v-05-measurability, step-v-06-traceability, step-v-07-implementation-leakage, step-v-08-domain-compliance, step-v-09-project-type, step-v-10-smart, step-v-11-holistic-quality, step-v-12-completeness, step-v-13-report-complete
 - The workflow begins with discovery-based structure extraction (step-v-01) before validation
 - When ANY step presents a menu (Continue/Fix/Skip options), automatically select **Continue** unless critical issues are detected
 - When validation identifies issues, automatically fix them in the PRD
@@ -104,3 +104,56 @@ For each iteration:
 - Introducing new issues while fixing existing ones
 - Not properly delegating to validate-prd workflow
 - Stopping to ask user for input
+
+---
+
+## 阻断性问题检查清单 (Validation Blockers Checklist)
+
+以下条件**必须全部通过** — 任何一个失败都阻断进度到step-06:
+
+- [ ] **Functional Requirements Traceability**: 所有Story都可追溯到原始需求文档
+- [ ] **Technical Feasibility**: 提议的技术栈和架构在给定时间线内可实现
+- [ ] **Business Value Definition**: 每个Epic至少有一个明确的业务价值主张
+- [ ] **Acceptance Criteria Clarity**: 所有Acceptance criteria都是SMART格式 (Specific, Measurable, Achievable, Relevant, Time-bound)
+- [ ] **Cross-Team Dependencies**: 跨team和component的所有依赖已识别、优先级排序、可协调
+- [ ] **Performance & Scalability**: 性能目标和可扩展性要求明确量化
+- [ ] **Security Review**: 安全审查已完成，没有Critical或Unmitigated issues
+- [ ] **Compliance & Legal**: 任何合规性要求（数据保护、行业标准等）都已纳入Story
+
+## 验证通过标准 (Validation Pass Criteria)
+
+PRD验证通过的充要条件:
+
+1. ✅ 所有Blockers都已检查且通过
+2. ✅ 没有超过3个Medium优先级未解决的issues
+3. ✅ 所有Critical issues都有明确的Mitigation计划
+4. ✅ PM (John) 和至少一个stakeholder已同意
+5. ✅ 文档质量评分 >= 85%
+6. ✅ Story计数 >= 5个 (如果目标是正常sprint)
+
+## 如果验证失败后超过3次迭代 (Beyond 3 Iterations Escalation)
+
+**步骤:**
+
+1. 生成详细的"Unresolved Issues Report"，按优先级分类
+2. 对于仍未解决的**Critical issues**:
+   - 立即通知Winston (Architect) 进行架构审查
+   - 可能需要回到 **step-03-architecture-analysis** 重新评估技术可行性
+3. 对于**Major issues**:
+   - John尝试通过PRD微调来修复
+   - 如果无法修复，escalate至PM决策
+4. **决策选项**:
+   - A) 接受已识别的风险，添加mitigation计划到backlog
+   - B) 修改scope以移除有问题的Story
+   - C) 延迟到下一个iteration，回到step-04重新生成PRD
+   - D) 停止管道，等待manual intervention
+
+**Escalation Notification Template:**
+```
+PRD Validation Status: FAILED AFTER 3 ITERATIONS
+Blocking Story Count: [X]
+Critical Issues: [list]
+Proposed Resolution: [A/B/C/D]
+Escalation To: [PM/Architect/Stakeholder]
+Timeline Impact: [days]
+```

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-01-init-and-validate.md

@@ -27,6 +27,11 @@ Check that the following required artifacts exist:
 3. **Planning Artifacts** — At least one of `{planning_artifacts}/*prd*.md` or `{planning_artifacts}/*architecture*.md` should exist
    - If missing: Output warning but continue — "Planning documents not found. Story creation may have limited context."
 
+4. **Requirements Pipeline Status** *(Optional — recommended check)* — If `{planning_artifacts}/pipeline-status.json` exists, read it and verify the `status` field equals "complete"
+   - If file exists AND `status` != "complete": Output WARNING — "pipeline-status.json found but requirements pipeline did not complete successfully (status: {status}). Story pipeline may proceed, but planning artifacts may be incomplete. Consider rerunning AR (Auto Requirements) first."
+   - If file does not exist: Output INFO — "pipeline-status.json not found. Assuming planning was done outside auto-requirements-pipeline. Continuing."
+   - *(Note: This is a non-blocking check. The pipeline continues regardless — it is informational only, to prevent silently working from incomplete requirements.)*
+
 ### 2. Analyze Sprint Status
 
 1. Load the FULL file: `{sprint_status}`
@@ -108,7 +113,7 @@ If `{current_story_key}` was provided via resume (user specified a specific stor
 For stories with status == "in-progress", verify minimum work has begun:
 
 1. Read the story file at `{current_story_path}`
-2. Count completed tasks: look for `[x]` markers in Tasks/Subtasks section
+2. Count completed tasks: look for `[x]`, `[X]`, or `[✓]` markers in Tasks/Subtasks section (case-insensitive match — any of these formats indicate a completed task)
 3. If completed_tasks == 0:
    - Output WARNING: "Story {current_story_key} is marked in-progress but has no completed tasks. This may indicate an abandoned development session."
    - Recommend: "Consider resetting to 'ready-for-dev' if development was not actually started."

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-02-create-story.md

@@ -2,6 +2,14 @@
 name: "step-02-create-story"
 description: "Create the user story using SM role, delegating to create-story workflow logic"
 nextStepFile: "./step-03-validate-story.md"
+input_variables:
+  - "epic_key"
+  - "story_template"
+  - "batch_mode"
+output_variables:
+  - "created_story"
+  - "story_details"
+  - "story_metadata"
 ---
 
 # Step 2 of 9: Create User Story
@@ -58,8 +66,11 @@ Key parameters to pass:
 
 After create-story workflow completes:
 1. Verify story file exists at expected path
-2. Verify story status is "ready-for-dev"
-3. Store `{current_story_path}` = path to the created story file
+2. Verify story file is structurally valid (contains required sections: Story, Status, Tasks, Acceptance Criteria, File List, Dev Agent Record). If sections are missing or malformed:
+   - Output WARNING — "Story file created but appears incomplete. Missing sections: {section_list}. Re-running create-story workflow."
+   - Retry the workflow (max 2 attempts) or HALT if retries exhausted
+3. Verify story status is "ready-for-dev"
+4. Store `{current_story_path}` = path to the created story file
 
 If creation failed:
 - HALT — "Story creation failed for {current_story_key}. Check planning artifacts and retry."

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-03-validate-story.md

@@ -25,6 +25,8 @@ Adopt the PM persona:
 
 1. Read the COMPLETE story file at `{current_story_path}`
 2. Parse all sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status
+3. Initialize validation counter: Set `{validation_attempt}` = 1
+   *(Initialize here — before the validation loop begins — so repeated loop iterations (section 3 → section 4 → loop back to section 3) do NOT accidentally reset the counter on re-entry to section 4.)*
 
 ### 3. Execute 10-Step Validation
 
@@ -43,7 +45,7 @@ Perform the following validation checks:
 
 ### 4. Analyze Validation Results
 
-Set `{validation_attempt}` = 1
+*(Note: `{validation_attempt}` was initialized to 1 in section 2. Do NOT reset it here — this section may be re-entered during the fix-and-retry loop.)*
 
 **IF validation report = GO (readiness score >= 7/10):**
 - Record validation in story file (see section 4.5)

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-04-develop-story.md

@@ -17,11 +17,18 @@ nextStepFile: "./step-05-code-review.md"
 ### 1. Switch to Dev Role
 
 Adopt the Dev persona:
-- You are Amelia, an elite full-stack developer
-- Follow patterns, ship code, run tests
-- Every response moves the project forward
-- Execute ALL steps in exact order — do NOT skip steps
-- Absolutely DO NOT stop because of "milestones" or "significant progress" — continue until ALL tasks are complete
+- **Name:** Amelia
+- **Title:** Elite Full-Stack Developer
+- **Core Purpose:** Transform story requirements into production-ready code through TDD (red-green-refactor cycle), comprehensive testing, and meticulous task completion
+- **Communication Style:** Crisp, code-focused, evidence-driven. Every pull request is accompanied by passing tests and clear commit messages
+- **Key Behaviors:**
+  - Follow existing patterns and conventions from the codebase (identified in Step 3 architecture analysis)
+  - Ship clean, tested code incrementally
+  - Run full test suite after each task
+  - Every response moves the project forward with measurable progress
+  - Execute ALL steps in exact order — do NOT skip steps
+  - Absolutely DO NOT stop because of "milestones" or "significant progress" — continue until ALL tasks are complete
+- **Quality Gate:** All tasks must be marked [x], [X], or [✓] (case-insensitive) with corresponding tests passing before considering any task "done"
 
 ### 2. Execute Story Development
 
@@ -46,8 +53,8 @@ Key parameters to pass:
 ### 3. Verify Development Output
 
 After dev-story workflow completes:
-1. Re-read the story file at `{current_story_path}`
-2. Verify ALL tasks and subtasks are marked [x] — including any `[AI-Review]` prefixed tasks from prior code review
+1. Re-read the story file at `{current_story_path}` (fresh read from disk to catch any updates during dev workflow execution)
+2. Verify ALL tasks and subtasks are marked [x], [X], or [✓] (case-insensitive) — including any `[AI-Review]` prefixed tasks from prior code review
 3. Verify story status is "review"
 4. Verify sprint-status.yaml reflects "review" for `{current_story_key}`
 5. Verify that tests actually exist for all implemented features (not just task checkboxes)

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-05-code-review.md

@@ -56,11 +56,11 @@ Key parameters to pass:
 **IF all HIGH and MEDIUM issues are fixed AND all ACs are implemented:**
 - Set story status to "review" (ready for QA)
 - Output: "Code review complete. All critical issues resolved. Proceeding to QA testing."
-- **NEXT:** Proceed to step-06 (test story)
+- **NEXT:** Proceed to step-06 (test story) [frontmatter: nextStepFile]
 
 **IF there are remaining HIGH or MEDIUM issues that could not be auto-fixed:**
 - Output the unresolved issues
-- **NEXT:** Proceed to step-07 (fix and retest) to address remaining issues
+- **NEXT:** Proceed to step-07 (fix and retest) to address remaining issues [frontmatter: nextStepFile_issues]
 
 ### 5. Pipeline Status Update
 

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-06-test-story.md

@@ -103,12 +103,13 @@ Create a test results summary:
 
 **IF all ACs pass AND no HIGH severity issues:**
 - Output: "QA testing PASSED. All {ac_count} acceptance criteria verified with real data. Proceeding to completion."
-- **NEXT:** Proceed to step-08 (complete story)
+- **NEXT:** Proceed to step-08 (complete story) [frontmatter: nextStepFile]
 
 **IF any AC fails OR HIGH severity issues found:**
 - Output: "QA testing FAILED. {ac_fail_count} acceptance criteria not met. Issues: {issue_list}"
 - Record test failures in story file under QA Results section
-- **NEXT:** Proceed to step-07 (fix and retest)
+- Set `{fix_source}` = "qa-testing" (this variable will be used in step-07 to route fixes directly to step-08 after correction, since QA issues often don't require code review re-entry)
+- **NEXT:** Proceed to step-07 (fix and retest) [frontmatter: nextStepFile_fail]
 
 ### 7. Pipeline Status Update
 
@@ -142,3 +143,111 @@ Create a test results summary:
 - Skipping acceptance criteria during testing
 - Not verifying database state after write operations
 - Marking tests as PASS without evidence
+
+---
+
+## 测试失败处理流程 (Test Failure Handling)
+
+**当任何acceptance criteria失败时:**
+
+### 1. 失败分类 (Categorize Failures)
+
+对每个失败进行分类:
+
+- **Type A - AC Failure (接受标准失败)**: 核心功能没有达到预期
+  - 示例: 应该返回值X，实际返回值Y
+  - 路由: → step-07 (fix-and-retest)
+  
+- **Type B - Data Integrity Issue (数据完整性问题)**: 数据库状态不正确
+  - 示例: 记录未保存或数据损坏
+  - 路由: → step-07 (fix-and-retest) 并标记为HIGH优先级
+  
+- **Type C - Performance Issue (性能问题)**: 功能正常但超过性能阈值
+  - 示例: API响应时间 > 2秒
+  - 路由: → step-07 (fix-and-retest) 但标记为MEDIUM优先级
+  
+- **Type D - Environment/Test Setup Issue (环境问题)**: 测试环境配置问题
+  - 示例: 数据库连接失败、假数据缺失
+  - 路由: → 修复测试环境，然后重新运行tests
+
+### 2. 重试策略 (Retry Strategy)
+
+**对于Type A和B失败:**
+- 在step-07中作为HIGH优先级修复
+- 每个Type A/B失败最多重试1次在step-06（re-run tests）
+  
+**对于Type C失败（仅性能）:**
+- 如果只有Type C失败，可以有条件地PASS
+- 但必须在story文件中记录性能问题
+- 标记为"KNOWN_PERFORMANCE_ISSUE"
+- 移至backlog作为future optimization
+- 仅在Type A/B都PASS时允许带Type C继续
+
+**对于Type D失败:**
+- 不计入fix iteration（fix-and-retest）
+- 修复测试环境
+- 立即重新运行测试
+
+### 3. 测试覆盖率阈值 (Coverage Thresholds)
+
+**强制要求:**
+- 单元测试覆盖率: >= 75%
+- 集成测试覆盖率: >= 60%
+- 接受标准覆盖率: 100% (所有AC必须有至少1个测试)
+
+**如果未达到:**
+- 不允许进入step-07
+- 回到开发阶段添加缺失的tests
+- Type: AC-Incomplete failure → 标记story为"NEEDS_MORE_TESTS"
+
+### 4. 记录失败详情 (Document Failures)
+
+在Story文件的"QA Results"部分记录:
+
+```markdown
+## QA Results
+
+**Overall Status:** FAILED - 2/5 ACs passed
+
+### Failed Tests
+- **AC#2 (Type A):** [Description] 
+  - Expected: [X]
+  - Actual: [Y]
+  - Root Cause: [Analysis]
+  - Fix Priority: HIGH
+  
+- **AC#4 (Type C):** [Performance]
+  - Threshold: 1s
+  - Actual: 2.3s
+  - Fix Priority: MEDIUM (Known issue, defer if needed)
+
+### Coverage Summary
+- Unit: 72% (Below 75% threshold)
+- Integration: 65%
+- AC Coverage: 100%
+
+### Recommended Next Step
+- Re-run step-07 to fix AC#2 (HIGH)
+- Consider Type C as known limitation unless time allows
+```
+
+### 5. 条件通过规则 (Conditional Pass)
+
+故事可以在以下条件下**有条件通过**到step-07:
+
+✅ **全部Type A/B失败已解决**
+✅ **至少80%的接受标准通过** 
+✅ **无Critical数据完整性问题**
+❌ **Type C (性能)失败不阻止进度** (但需要记录)
+❌ **测试覆盖率 < 60% 则必须返回修复**
+
+### 6. 向step-07传递信息 (Hand-off to step-07)
+
+设置以下变量供step-07使用:
+
+```
+{fix_source} = "qa-testing"
+{failure_categories} = [Type A count, Type B count, Type C count]
+{high_priority_issues} = [list]
+{performance_known_issues} = [list]  // For conditional pass scenarios
+```

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-07-fix-and-retest.md

@@ -126,3 +126,112 @@ After all fixes are applied:
 - Introducing new regressions while fixing existing issues
 - Exceeding `{max_fix_iterations}` fix iterations without resolution
 - Not running regression tests after each fix
+
+---
+
+## 当超过最大修复迭代次数 (Escalation Path: Beyond Max Fix Iterations)
+
+**触发条件:** `{fix_iteration}` > `{max_fix_iterations}` (默认 > 5)
+
+**Escalation Protocol:**
+
+### 1. 生成Escalation Report
+
+文档所有修复尝试和失败原因:
+
+```
+ESCALATION REPORT: Story {current_story_key}
+==========================================
+Status: FIX LIMIT EXCEEDED
+Fix Iterations Attempted: {max_fix_iterations}
+Unresolved Issues:
+  - [Issue 1]: [Root Cause Analysis]
+  - [Issue 2]: [Root Cause Analysis]
+  
+Pattern Analysis:
+  - Recurring issue? [Yes/No] — [Description]
+  - Root cause identified? [Yes/No]
+  - Architectural blocker? [Yes/No]
+  
+Timeline Impact: [number] days
+Recommended Action: [A/B/C below]
+```
+
+### 2. 通知团队 (Owner Notification)
+
+发送通知至:
+- **Primary:** Story Owner / Scrum Master (Mary)
+- **Secondary:** Tech Lead / Architect (Winston)
+
+**Notification Template:**
+
+```
+URGENT: Story {current_story_key} - Fix Limit Reached
+
+Summary: After {max_fix_iterations} fix iterations, the following issues remain unresolved:
+- [Issue list]
+
+Root Cause Analysis:
+- [Analysis summary]
+
+Recommended Actions:
+A) Mark as "Blocked" - Investigate architectural changes needed
+B) Reduce scope - Defer failing AC to next iteration  
+C) Re-assign to Tech Lead for deep investigation
+D) Revert changes and restart implementation from scratch
+
+Timeline: Requires decision within [4 hours / 1 day]
+Severity: BLOCKING SPRINT PROGRESS
+```
+
+### 3. 处理选项 (Handling Options)
+
+**选项 A - 标记为Blocked:**
+- 更新story状态为 `BLOCKED_INVESTIGATION`
+- 记录blocking factors
+- Escalate to Architect (Winston) for architectural review
+- 移出当前sprint backlog
+
+**选项 B - 缩小范围 (Reduce Scope):**
+- 识别哪些acceptance criteria无法在{max_fix_iterations}内完成
+- 将这些AC移至"acceptance-criteria-deferred"部分
+- 标记为"READY_FOR_TESTING"（简化的AC集合）
+- 继续进入step-08
+
+**选项 C - 重新分配 (Tech Lead Deep Dive):**
+- 暂停当前story处理
+- 分配给Tech Lead (Winston) 进行深度root cause分析
+- 预计时间: 2-4小时的深度分析
+- 结果: 要么找到fix，要么confirm需要选项A或B
+
+**选项 D - 重新开始 (Fresh Start):**
+- 回退所有代码更改到step-04开始前的状态
+- 重新执行step-04到step-07
+- 仅在其他选项都不可行时使用
+- 添加至"lessons learned"文档
+
+### 4. Story状态管理
+
+**设置Story Meta字段:**
+```
+escalation_status: ESCALATED
+escalation_date: {current_timestamp}
+escalation_owner: {person_assigned}
+recommended_action: [A/B/C/D]
+estimated_resolution_time: [hours]
+```
+
+### 5. 防止进度堵塞 (Prevent Sprint Blocking)
+
+- 不允许story卡在此步骤超过{max_fix_iterations} + 4小时
+- 自动移至Scrum Master队列以处理escalation
+- 在sprint status中标记为"NEEDS_DECISION"
+- 不将此issue计入sprint velocity（因为未完成）
+
+### 6. 恢复进度 (Recovery Process)
+
+一旦Escalation决策完成:
+- 如果选择 A: Story移至 `BLOCKED` 状态，等待Architect反馈
+- 如果选择 B: 回到step-08 (complete story)，使用简化的AC集合
+- 如果选择 C: Architect执行分析，结果完成后回到step-07
+- 如果选择 D: Story重置到step-04，重新开始整个cycle

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

@@ -17,8 +17,8 @@ nextStepFile: "./step-09-cycle-check.md"
 ### 1. Final Validation
 
 Before marking complete, verify all gates:
-1. Read the COMPLETE story file at `{current_story_path}`
-2. Verify ALL tasks and subtasks are marked [x]
+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

package/src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-09-cycle-check.md

@@ -32,10 +32,12 @@ nextStepFile: null
    - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
    - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
    - Status value equals "backlog"
+   - If found: Set `{found_status}` = "backlog"
 5. If no "backlog" story is found, search again for the FIRST story where:
    - Key matches the same pattern (not epic, not retrospective)
    - Status value equals "ready-for-dev"
    - *(Mirrors step-01's initial story selection: "backlog, or ready-for-dev if no backlog")*
+   - If found: Set `{found_status}` = "ready-for-dev"
 
 ### 3. Evaluate Next Story
 
@@ -43,6 +45,7 @@ nextStepFile: null
 - Set `{current_story_key}` = found story key
 - Set `{current_story_path}` = "" (will be set during creation/validation)
 - Set `{fix_iteration}` = 0
+- *(Note: `{found_status}` was already set in section 2 above — "backlog" or "ready-for-dev" — and is used in the progress checkpoint output below.)*
 
 **3.5. Batch Mode Progress Checkpoint**
 

package/src/xmc/workflows/4-implementation/auto-story-pipeline/workflow.md

@@ -34,9 +34,10 @@ This uses **step-file architecture** for focused execution across a long-running
 
 - `{pipeline_mode}` — "single" (one story) or "batch" (all backlog stories)
 - `{current_story_key}` — Key of story being processed (e.g., "1-2-user-auth")
-- `{current_story_path}` — Full path to current story file (derived in step-01 after resolving `{current_story_key}`; re-set in step-02 skip branch for batch cycles)
+- `{current_story_path}` — Full path to current story file (derived in step-01 after resolving `{current_story_key}`; re-set in step-02 skip branch for batch cycles). **CRITICAL:** In batch mode, this variable is reset for each story iteration (step-09 → step-02 loop). Whenever re-reading the story file in subsequent steps (e.g., step-08 final validation, step-03 re-checks), always perform a FRESH read directly from disk using this path variable. Do NOT rely on cached/stale in-memory state from earlier steps in the same cycle, as intermediate steps (step-04, step-05, step-06, step-07) may have modified the file
 - `{fix_iteration}` — Bug fix loop counter (max controlled by `{max_fix_iterations}`, default 5; reset per story)
 - `{max_fix_iterations}` — Maximum fix-and-retest cycles per story (configurable via `max_fix_iterations` in config.yaml; default 5 if not set)
+- `{fix_source}` — Origin of failures being fixed in step-07: "code-review" (step-05 routed here with unresolvable issues), "qa-testing" (step-06 routed here with test failures), or "mixed" (both code review and QA issues); set in step-07 section 2; determines post-fix routing (code-review/mixed → inline targeted re-check before step-08; qa-testing → step-08 directly)
 - `{stories_completed}` — Count of stories completed in this pipeline run
 - `{pipeline_status}` — Current pipeline phase for tracking
 - `{validation_attempt}` — Story validation attempt counter (used in step-03, max 3; re-initialized at start of step-03 for each story)
@@ -46,6 +47,7 @@ This uses **step-file architecture** for focused execution across a long-running
 - `{in_progress_count}` — Count of stories with status "in-progress" (initialized in step-01; refreshed in step-09)
 - `{review_count}` — Count of stories with status "review" (initialized in step-01; refreshed in step-09)
 - `{done_count}` — Count of stories with status "done" (initialized in step-01; refreshed in step-09)
+- `{found_status}` — Status of the next processable story found during step-09 section 2 search: "backlog" or "ready-for-dev"; explicitly set alongside `{current_story_key}` when a story is selected; used in section 3.5 progress checkpoint output; local to step-09 and not persisted between stories
 
 ### Status Machine
 

package/tools/cli/installers/install-messages.yaml

@@ -3,37 +3,7 @@
 # Edit this file to change what users see during the install process
 
 # Display at the START of installation (after logo, before prompts)
-startMessage: |
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  🎉 V6 IS HERE! Welcome to XiaoMa Method V6 - Official Stable Release!
-
-  The XiaoMa Method is now a Platform powered by the XiaoMa Method Core and Module Ecosystem!
-    - Select and install modules during setup - customize your experience
-    - New XiaoMa Method for Agile AI-Driven Development (the evolution of V4)
-    - Exciting new modules available during installation, with community modules coming soon
-    - Documentation: https://docs.xiaoma-cli.org
-
-  🌟 XiaoMa is 100% free and open source.
-    - No gated Discord. No paywalls. No gated content.
-    - We believe in empowering everyone, not just those who can pay.
-    - Knowledge should be shared, not sold.
-
-  🎤 SPEAKING & MEDIA:
-    - Available for conferences, podcasts, and media appearances
-    - Topics: AI-Native Transformation, Spec and Context Engineering, XiaoMa Method
-    - For speaking inquiries or interviews, reach out to XiaoMa on Discord!
-
-  ⭐ HELP US GROW:
-    - Star us on GitHub: https://github.com/xiaoma-code-org/XiaoMa-CLI/
-    - Subscribe on YouTube: https://www.youtube.com/@XiaoMaCode
-    - Free Community and Support: https://discord.gg/gk8jAdXWmj
-    - Donate: https://buymeacoffee.com/xiaoma
-    - Corporate Sponsorship available
-
-  Latest updates: https://github.com/xiaoma-code-org/XiaoMa-CLI/blob/main/CHANGELOG.md
-
-  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+startMessage: "欢迎使用 xiaoma 最新版,有任何问题请咨询 平台研发部-刘二杨"
 
 # No end message - install summary and next steps are rendered by the installer
 endMessage: ""

package/tools/cli/installers/lib/ide/templates/combined/gemini-task.toml

@@ -1,6 +1,6 @@
-description = "Executes the {{name}} task from the BMAD Method."
+description = "Executes the {{name}} task from the XiaoMa Method."
 prompt = """
-Execute the BMAD '{{name}}' task.
+Execute the XiaoMa '{{name}}' task.
 
 TASK INSTRUCTIONS:
 1. LOAD the task file from {project-root}/{{bmadFolderName}}/{{path}}

package/tools/cli/installers/lib/ide/templates/combined/gemini-tool.toml

@@ -1,6 +1,6 @@
-description = "Executes the {{name}} tool from the BMAD Method."
+description = "Executes the {{name}} tool from the XiaoMa Method."
 prompt = """
-Execute the BMAD '{{name}}' tool.
+Execute the XiaoMa '{{name}}' tool.
 
 TOOL INSTRUCTIONS:
 1. LOAD the tool file from {project-root}/{{bmadFolderName}}/{{path}}

package/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml

@@ -1,6 +1,6 @@
 description = '{{description}}'
 prompt = """
-Execute the BMAD '{{name}}' workflow.
+Execute the XiaoMa '{{name}}' workflow.
 
 CRITICAL: This is a structured YAML workflow. Follow these steps precisely:
 

package/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml

@@ -1,6 +1,6 @@
 description = '{{description}}'
 prompt = """
-Execute the BMAD '{{name}}' workflow.
+Execute the XiaoMa '{{name}}' workflow.
 
 CRITICAL: You must load and follow the workflow definition exactly.
 

package/tools/cli/lib/cli-utils.js

@@ -25,17 +25,17 @@ const CLIUtils = {
 
     // ASCII art logo
     const logo = [
-      '    ██████╗ ███╗   ███╗ █████╗ ██████╗ ™',
-      '    ██╔══██╗████╗ ████║██╔══██╗██╔══██╗',
-      '    ██████╔╝██╔████╔██║███████║██║  ██║',
-      '    ██╔══██╗██║╚██╔╝██║██╔══██║██║  ██║',
-      '    ██████╔╝██║ ╚═╝ ██║██║  ██║██████╔╝',
-      '    ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝╚═════╝',
+      '  ██╗  ██╗██╗ █████╗  ██████╗ ███╗   ███╗ █████╗',
+      '  ╚██╗██╔╝██║██╔══██╗██╔═══██╗████╗ ████║██╔══██╗',
+      '   ╚███╔╝ ██║███████║██║   ██║██╔████╔██║███████║',
+      '   ██╔██╗ ██║██╔══██║██║   ██║██║╚██╔╝██║██╔══██║',
+      '  ██╔╝ ██╗██║██║  ██║╚██████╔╝██║ ╚═╝ ██║██║  ██║',
+      '  ╚═╝  ╚═╝╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝',
     ]
       .map((line) => color.yellow(line))
       .join('\n');
 
-    const tagline = '    Build More, Architect Dreams';
+    const tagline = '      AI-Driven Agile Development';
 
     await prompts.box(`${logo}\n${tagline}`, `v${version}`, {
       contentAlign: 'center',

package/pipeline-optimization-report.md

@@ -1,455 +0,0 @@
-# Pipeline Optimization Report
-
-**Generated:** 2026-03-18
-**Last Updated:** 2026-03-18 (Run #2 — Incremental Analysis)
-**Scope:** auto-requirements-pipeline · auto-story-pipeline
-**Run Type:** Incremental update (previous report found; all prior optimizations verified in-place)
-
----
-
-## 1. 学习总结 — 项目整体架构
-
-### 1.1 Agent 体系
-
-| Agent | 名称 | 主要职责 | 触发 Pipeline |
-|-------|------|---------|--------------|
-| Analyst (Mary) | 业务分析师 | 需求分析、竞品研究、Requirements 挖掘 | auto-requirements-pipeline (AR) |
-| Architect (Winston) | 架构师 | 架构分析、技术设计、系统决策 | auto-requirements-pipeline |
-| PM (John) | 产品经理 | PRD创建/验证、Epic/Story拆解 | auto-requirements-pipeline |
-| SM (Bob) | Scrum Master | Story创建、Sprint规划、流程协调 | auto-story-pipeline (ASP) |
-| Dev (Amelia) | 开发者 | 代码实现、TDD、Bug修复 | auto-story-pipeline |
-| QA (Quinn) | 质量保障 | 功能测试、E2E测试、验收标准验证 | auto-story-pipeline |
-| UX Designer (Sally) | UX设计师 | 用户体验设计、界面规范 | — |
-| Tech Writer (Paige) | 技术文档 | 文档编写、图表生成 | — |
-| Quick Flow (Barry) | 快速开发 | 轻量级规格+实现一体化 | — |
-
-### 1.2 Core Skill 体系
-
-- **xiaoma-advanced-elicitation** — 高级需求挖掘技术
-- **xiaoma-brainstorming** — 结构化头脑风暴
-- **xiaoma-distillator** — 内容提炼与压缩
-- **xiaoma-editorial-review-prose/structure** — 编辑质量审查（文字风格/文档结构）
-- **xiaoma-review-adversarial-general / edge-case-hunter** — 对抗性代码审查与边界案例发现
-- **xiaoma-shard-doc / xiaoma-index-docs** — 文档分片与索引
-- **xiaoma-party-mode / xiaoma-help** — 协作模式和帮助系统
-
-### 1.3 Workflow 体系（4个阶段）
-
-| 阶段 | 核心工作流 |
-|------|-----------|
-| Phase 1 Analysis | auto-requirements-pipeline, xiaoma-create-product-brief, research |
-| Phase 2 Planning | create-prd, xiaoma-edit-prd, xiaoma-validate-prd, xiaoma-create-ux-design |
-| Phase 3 Solutioning | xiaoma-create-architecture, xiaoma-create-epics-and-stories, xiaoma-check-implementation-readiness |
-| Phase 4 Implementation | auto-story-pipeline, xiaoma-create-story, xiaoma-dev-story, xiaoma-code-review, xiaoma-sprint-planning, xiaoma-sprint-status, xiaoma-correct-course, xiaoma-retrospective |
-| 跨阶段 | xiaoma-document-project, xiaoma-generate-project-context, xiaoma-qa-generate-e2e-tests, xiaoma-quick-flow |
-
-### 1.4 Step-File 架构模式
-
-两个 pipeline 都采用相同的**step-file architecture**：每个步骤读取独立 `.md` 文件，防止长会话中的"上下文丢失"问题。状态通过变量（`{variable_name}`）在步骤间传递，文件 frontmatter 声明 `nextStepFile` 进行步骤链接。
-
----
-
-## 2. Pipeline 分析
-
-### 2.1 auto-requirements-pipeline 分析
-
-**路径：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/`
-**步骤数：** 8步
-**Agent 角色链：** Mary → Winston → John → John → John → Winston → Orchestrator
-
-#### 步骤概览
-
-| 步骤 | 职责 | Agent | 输出产物 | 质量控制 |
-|------|------|-------|---------|---------|
-| Step 01 | 初始化与验证 | Orchestrator | 无 | 前置条件检查 |
-| Step 02 | 需求分析 | Analyst (Mary) | requirements-analysis.md | 8相分析 + 最多2次自检重试 |
-| Step 03 | 架构分析 | Architect (Winston) | current-architecture-analysis.md | 6项质量标准 + 最多2次重试 |
-| Step 04 | 创建PRD | PM (John) | prd.md | 委托 create-prd workflow (15步) |
-| Step 05 | 验证PRD | PM (John) | prd.md (updated) | 委托 validate-prd workflow，最多3次迭代 |
-| Step 06 | 创建 Epics/Stories | PM (John) | epics.md | 委托 create-epics-and-stories workflow |
-| Step 07 | 创建架构设计 | Architect (Winston) | architecture.md | 委托 create-architecture workflow |
-| Step 08 | 收尾 | Orchestrator | pipeline-status.json | Checklist 验证 |
-
-#### 亮点设计
-- **零跳过策略**：步骤间不允许跳过，通过"Automatically proceed"指令强制连续执行
-- **双架构文档区分**：`current-architecture-analysis.md`（现有系统分析）vs `architecture.md`（新功能设计），设计清晰
-- **Workflow 委托模式**：复杂步骤委托给已验证的子 workflow，保持 pipeline 轻量
-- **Machine-readable 状态**：`pipeline-status.json` 使下游 (auto-story-pipeline) 可以程序化检查完成状态
-
-#### 发现的问题（优化前）
-
-| 问题 ID | 严重性 | 描述 |
-|---------|--------|------|
-| REQ-01 | HIGH | step-06 缺少 PM 角色切换（Switch to PM Role）章节，与其他步骤不一致 |
-| REQ-02 | MEDIUM | workflow.md 状态变量缺少 `{max_validation_iterations}` 的说明（仅在 step-05 内定义） |
-| REQ-03 | MEDIUM | step-08 pipeline-status.json 中迭代次数字段被错误地用字符串引号包裹（应为数字类型） |
-
----
-
-### 2.2 auto-story-pipeline 分析
-
-**路径：** `src/xmc/workflows/4-implementation/auto-story-pipeline/`
-**步骤数：** 9步
-**Agent 角色链：** Orchestrator → SM (Bob) → PM (John) → Dev (Amelia) → Adversarial Reviewer → QA (Quinn) → Orchestrator
-
-#### 步骤概览
-
-| 步骤 | 职责 | Agent | 主要操作 | 模式 |
-|------|------|-------|---------|------|
-| Step 01 | 初始化 | Orchestrator | 解析 sprint-status，确定 single/batch 模式 | 入口 |
-| Step 02 | 创建 Story | SM (Bob) | 委托 create-story workflow | 可跳过（已存在时） |
-| Step 03 | 验证 Story | PM (John) | 10步验证，最多3次自修复 | 质量门禁 |
-| Step 04 | 开发 Story | Dev (Amelia) | TDD (Red-Green-Refactor)，委托 dev-story | 核心实现 |
-| Step 05 | 代码审查 | Adversarial Reviewer | 委托 code-review，自动修复 HIGH/MEDIUM | 质量门禁 |
-| Step 06 | QA 测试 | QA (Quinn) | 真实数据测试，委托 qa-generate-e2e-tests | 验收测试 |
-| Step 07 | 修复与重测 | Dev (Amelia) | 根源修复 + 回归测试（最多 max_fix_iterations 次） | 修复循环 |
-| Step 08 | 完成 Story | Orchestrator | 更新状态、检查 Epic 完成度、生成摘要 | 收尾 |
-| Step 09 | 循环检查 | Orchestrator | Single模式结束 / Batch模式选下一个 Story | 循环控制 |
-
-#### 亮点设计
-- **状态机驱动**：`backlog → ready-for-dev → in-progress → review → done`，每个状态有明确转换规则
-- **Resume 能力**：step-01 支持 `ASP resume <story-key>` 恢复中断的故事
-- **In-Progress 检查**：针对异常 in-progress 状态（无已完成任务）给出警告而非阻塞
-- **Epic 完成度自动检查**：step-08 自动检测并更新 Epic 完成状态
-- **Batch Progress Checkpoint**：批量模式下每个故事间输出进度摘要
-
-#### 发现的问题（优化前）
-
-| 问题 ID | 严重性 | 描述 |
-|---------|--------|------|
-| STORY-01 | HIGH | step-09 批量进度检查点显示的状态计数是 step-01 初始化时的过期数据，批量处理多个 story 后信息失真 |
-| STORY-02 | HIGH | workflow.md 未文档化 `max_fix_iterations` 的可配置性（仅在 step-07 中提及可通过 config.yaml 配置） |
-| STORY-03 | MEDIUM | step-07 未区分故障来源（代码审查 vs QA 测试），修复后直接跳转 step-08，代码审查触发的修复不经过二次验证 |
-
----
-
-## 3. 优化清单
-
-### 3.1 已识别的所有优化点
-
-| 优化 ID | 目标 Pipeline | 优先级 | 描述 | 受影响文件 |
-|---------|--------------|--------|------|-----------|
-| OPT-REQ-1 | auto-requirements | HIGH | step-06 缺少"Switch to PM Role"章节，一致性缺失 | step-06-create-epics.md |
-| OPT-REQ-2 | auto-requirements | MEDIUM | workflow.md 缺少 `{max_validation_iterations}` 状态变量文档 | workflow.md |
-| OPT-REQ-3 | auto-requirements | MEDIUM | step-08 JSON 迭代次数字段类型错误（字符串 vs 数字） | step-08-finalize.md |
-| OPT-STORY-1 | auto-story | HIGH | step-09 批量进度检查点使用过期状态计数 | step-09-cycle-check.md |
-| OPT-STORY-2 | auto-story | HIGH | workflow.md 缺少 `{max_fix_iterations}` 状态变量文档 | workflow.md |
-| OPT-STORY-3 | auto-story | MEDIUM | step-07 缺少故障来源区分和基于来源的差异化路由 | step-07-fix-and-retest.md |
-| OPT-REQ-4 | auto-requirements | LOW | step-05 Section 5 中 "Proceed to step 4" 措辞歧义，应为 "Proceed to section 6" | step-05-validate-prd.md |
-| OPT-STORY-4 | auto-story | MEDIUM | step-01 Section 5 将 ready-for-dev 直接路由到 step-04，与批量模式的 step-02→step-03 路径不一致，绕过了验证门禁 | step-01-init-and-validate.md |
-
----
-
-## 4. 已实施优化
-
-### OPT-REQ-1 — step-06 新增 PM 角色切换章节
-
-**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-06-create-epics.md`
-
-**问题：** step-04（Create PRD）和 step-05（Validate PRD）都有明确的"Switch to PM Role"章节，但 step-06（Create Epics）直接从"Load Required Context"开始，缺少角色切换，导致与同类步骤不一致。
-
-**修改：**
-- 在 `## EXECUTION SEQUENCE` 下新增 `### 1. Switch to PM Role` 章节，包含 John 的角色定义和职责说明
-- 原有章节编号向后推移（原 §1→§2, §2→§3, §3→§4, §4→§5, §5→§6）
-- 新章节明确指向 Epic/Story 拆解的目的："break down the validated PRD into well-structured epics and user stories"
-
-**兼容性：** 纯添加性修改，不影响委托逻辑和文件引用。
-
----
-
-### OPT-REQ-2 — workflow.md 补充 `{max_validation_iterations}` 状态变量
-
-**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/workflow.md`
-
-**问题：** `{max_validation_iterations}` 变量仅在 step-05 内部定义，其他开发者或 LLM 阅读 workflow.md 顶层时无法了解这个变量的存在和含义。
-
-**修改：**
-- 在 State Variables 章节，紧跟 `{validation_iteration}` 之后新增 `{max_validation_iterations}` 条目
-- 说明其默认值（3）以及为何比 analysis/architecture 的限制（2次）更高（因为委托了完整的 14步 validate-prd workflow）
-
-**兼容性：** 纯文档补充，不影响任何执行逻辑。
-
----
-
-### OPT-REQ-3 — step-08 JSON 迭代计数字段改为数字类型
-
-**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-08-finalize.md`
-
-**问题：** `pipeline-status.json` 模板中：
-```json
-"iterations": {
-  "analysis": "{analysis_iteration}",   // ❌ 字符串
-  "architecture": "{architecture_iteration}",  // ❌ 字符串
-  "validation": "{validation_iteration}"  // ❌ 字符串
-}
-```
-这些值在运行时会被替换为数字，但被字符串引号包裹，导致下游工具（如 auto-story-pipeline）解析时得到字符串 "1" 而非数字 1，不利于程序化比较。
-
-**修改：** 移除三个迭代次数字段的引号：
-```json
-"iterations": {
-  "analysis": {analysis_iteration},    // ✅ 数字
-  "architecture": {architecture_iteration},  // ✅ 数字
-  "validation": {validation_iteration}   // ✅ 数字
-}
-```
-
-**兼容性：** 修改 JSON 模板格式，运行时生成的 JSON 文件语义更正确。对已生成的历史文件无影响。
-
----
-
-### OPT-STORY-1 — step-09 批量进度检查点刷新状态计数
-
-**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-09-cycle-check.md`
-
-**问题：** 在批量模式下处理第 N 个 story 时，section 3.5 的进度检查点输出的 `{backlog_count}`、`{ready_count}` 等计数仍是 step-01 初始化时的值，不反映处理过 N-1 个故事后的实际状态。
-
-例如，初始状态有 5 个 backlog story。处理完第 1 个后，`{backlog_count}` 还是 5，但实际应该是 4。这会使批量运行过程的进度摘要完全失真。
-
-**修改：** 在 section 3.5 "Batch Mode Progress Checkpoint" 的输出前，增加一个三步刷新序列：
-1. 重新加载完整 `{sprint_status}` 文件
-2. 重新计数所有状态类别，更新 5 个计数变量
-3. 输出带 "(refreshed)" 标记的进度摘要
-
-**兼容性：** 与现有批量逻辑完全兼容，仅增加了文件读取和计数步骤。不影响单故事模式。
-
----
-
-### OPT-STORY-2 — workflow.md 补充 `{max_fix_iterations}` 状态变量
-
-**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/workflow.md`
-
-**问题：** State Variables 章节只有 `{fix_iteration}`，但没有说明：
-1. 存在 `{max_fix_iterations}` 作为上限控制变量
-2. 该变量可通过 `config.yaml` 的 `max_fix_iterations` 字段自定义
-3. 各计数变量（`{backlog_count}` 等）何时被刷新
-
-**修改：**
-- 新增 `{max_fix_iterations}` 条目，说明默认值（5）和 config.yaml 配置方式
-- 更新 `{fix_iteration}` 说明，注明被 `{max_fix_iterations}` 控制、每个 story 重置
-- 更新 `{validation_attempt}` 说明，注明在 step-03 开始时重新初始化
-- 更新 5 个状态计数变量的说明，注明刷新时机（step-01 初始化，step-09 批量检查点和最终收尾时刷新）
-
-**兼容性：** 纯文档补充。
-
----
-
-### OPT-STORY-3 — step-07 区分故障来源并差异化路由
-
-**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-07-fix-and-retest.md`
-
-**问题：** step-07 在修复后一律跳转 step-08（完成 story），无论问题是来自代码审查（step-05）还是 QA 测试（step-06）。对于代码审查触发的修复，修复后的代码没有经过任何验证即直接标记完成，存在质量风险。
-
-**修改：**
-
-**Section 2 新增故障来源分类：**
-```
-{fix_source} = "code-review" | "qa-testing" | "mixed"
-```
-
-**Section 6 差异化路由逻辑：**
-- `{fix_source}` == "qa-testing"：直接跳转 step-08（QA 已通过代码审查后的测试阶段）
-- `{fix_source}` == "code-review" 或 "mixed"：在跳转前执行**轻量级内联代码复查**（不需完整委托 code-review workflow，只需重新验证修复区域的 HIGH/MEDIUM 问题是否真正解决）。若复查发现新问题则循环回 step-07。
-
-**NEXT STEP 更新：** 新增三个条件化的跳转路径，覆盖所有路由场景。
-
-**兼容性：** 引入新变量 `{fix_source}`，修改了 section 6 逻辑和 NEXT STEP。不改变正常（无问题）执行路径。
-
----
-
-### OPT-REQ-4 — step-05 Section 5 导航措辞修正
-
-**文件：** `src/xmc/workflows/1-analysis/auto-requirements-pipeline/steps/step-05-validate-prd.md`
-
-**问题：** Section 5（Validation Loop）中，当所有验证检查通过时，文本写的是 "If ALL checks pass: Proceed to step 4"。`step 4` 是歧义引用——它可能被 LLM 误解为：(a) 循环列表中的第4项（不存在），(b) 文件的 Section 4（Execute PRD Validation，即重新触发整个委托流程），或 (c) 下一节（Section 6 Validation Passed，这才是正确意图）。误解为 (b) 会导致无限重委托循环。
-
-**修改：**
-- 将 "Proceed to step 4" 改为 "Proceed to section 6 (Validation Passed)"，明确指向正确的下一节，消除歧义。
-
-**兼容性：** 纯措辞修正，不影响任何执行逻辑结构。
-
----
-
-### OPT-STORY-4 — step-01 ready-for-dev 路由与批量模式对齐
-
-**文件：** `src/xmc/workflows/4-implementation/auto-story-pipeline/steps/step-01-init-and-validate.md`
-
-**问题：** Section 5（Determine Starting Step）对 `ready-for-dev` 状态的注释是 "story already created and validated"，并将其直接路由到 step-04（develop story），**绕过了 step-03 的验证门禁**。
-
-但是，批量模式下（step-09 批量循环），`ready-for-dev` 的故事会经 step-02 路由到 step-03，再进入 step-04，这正是 step-09 注释明确说明的设计意图：
-> "step-02's section 1 skip logic will detect 'ready-for-dev' stories, skip creation, and route them to step-03 (validate) before development begins"
-
-两条路径不一致：
-- **初始/Resume 模式**（step-01）：ready-for-dev → step-04 ❌ 跳过验证
-- **批量循环**（step-09→step-02→step-03→step-04）：ready-for-dev → step-03 → step-04 ✅ 通过验证
-
-`ready-for-dev` 表示 create-story workflow 已生成故事文件，但**尚未经过 pipeline 的 step-03 质量验证**。跳过该门禁使初始模式与批量模式的质量保障不等同。
-
-**修改：**
-1. Section 5 中将 `ready-for-dev` 路由从 "Skip to step-04" 改为 "Start at step-03 (validate story)"，并更新注释说明原因
-2. NEXT STEP 章节中新增 `ready-for-dev → step-03` 的跳转条目，并将 `in-progress` 的跳转条目从 "step-04 (story status == 'ready-for-dev' or 'in-progress')" 拆分为独立的两个条目
-3. SUCCESS METRICS 更新路由映射说明（backlog→step-02, ready-for-dev→step-03, in-progress→step-04, review→step-05）
-
-**兼容性：** 此修改会让所有通过 resume 或初始 single 模式处理的 `ready-for-dev` 故事额外经过 step-03 验证。这是质量提升，不是破坏性变更。故事文件不受影响；sprint-status.yaml 状态转换顺序不变。
-
----
-
-## 5. 测试结果
-
-### 5.1 结构完整性测试
-
-| 测试项 | 状态 | 备注 |
-|--------|------|------|
-| auto-requirements-pipeline 全部 8 个 step 文件存在 | ✅ PASS | step-01 至 step-08 全部验证 |
-| auto-story-pipeline 全部 9 个 step 文件存在 | ✅ PASS | step-01 至 step-09 全部验证 |
-| 所有 step 文件 frontmatter 含有 `name` 字段 | ✅ PASS | 两个 pipeline 全部 17 个文件通过 |
-| step-06 section 编号连续（1→2→3→4→5→6） | ✅ PASS | 重编号正确 |
-| workflow.md 新增状态变量拼写正确 | ✅ PASS | max_validation_iterations, max_fix_iterations |
-| step-08 JSON 整数字段无字符串引号 | ✅ PASS | analysis/architecture/validation 三个字段 |
-
-### 5.2 逻辑流程测试
-
-**auto-requirements-pipeline 8步走查：**
-
-| 步骤 | 前置条件 | 后置状态 | 跳转目标 | 状态 |
-|------|---------|---------|---------|------|
-| Step 01 | req.md + config.yaml 存在 | initialized | Step 02 | ✅ |
-| Step 02 | req.md 可读 | requirements-analyzed | Step 03 | ✅ |
-| Step 03 | src/ 目录（可选警告） | architecture-analyzed | Step 04 | ✅ |
-| Step 04 | create-prd workflow 存在 | prd-created | Step 05 | ✅ |
-| Step 05 | validate-prd workflow 存在；最多3次迭代 | prd-validated | Step 06 | ✅ |
-| Step 06 | create-epics workflow 存在；新增 PM 角色切换 | epics-created | Step 07 | ✅ |
-| Step 07 | create-architecture workflow 存在 | architecture-created | Step 08 | ✅ |
-| Step 08 | 5个产物均存在；Checklist 执行；JSON 整数类型 | complete | HALT | ✅ |
-
-**auto-story-pipeline 9步走查（batch 模式）：**
-
-| 步骤 | 前置条件 | 后置状态 | 跳转目标 | 状态 |
-|------|---------|---------|---------|------|
-| Step 01 | sprint-status.yaml + epics.md 存在 | initialized | Step 02/04/05（状态路由） | ✅ |
-| Step 02 | current_story_key 已设置 | story-created | Step 03 | ✅ |
-| Step 03 | story file 可读；validation_attempt 在步骤内重置为1 | story-validated | Step 04 | ✅ |
-| Step 04 | dev-story workflow；TDD 流程 | development-complete | Step 05 | ✅ |
-| Step 05 | code-review workflow；auto-fix HIGH/MEDIUM | code-review-complete | Step 06 或 Step 07 | ✅ |
-| Step 06 | 真实数据测试；no mock | qa-testing-complete/failed | Step 08 或 Step 07 | ✅ |
-| Step 07 | fix_source 已分类；max_fix_iterations 控制 | — | Step 08 或循环 Step 07 | ✅ |
-| Step 08 | 全门禁通过；epic 完成检查 | story-completed | Step 09 | ✅ |
-| Step 09 (batch) | sprint-status 刷新；找下一个 story | — | Step 02（循环）或 HALT | ✅ |
-
-### 5.3 兼容性测试
-
-| 测试项 | 状态 | 备注 |
-|--------|------|------|
-| Agent 菜单引用正确（analyst → AR, sm → ASP） | ✅ PASS | 触发器名称未被修改 |
-| SKILL.md 入口文件完好 | ✅ PASS | 两个 pipeline 均指向 workflow.md |
-| xiaoma-skill-manifest.yaml 未修改 | ✅ PASS | canonicalId 一致性保留 |
-| checklist.md 与实际步骤匹配 | ✅ PASS | 需求 pipeline 8步覆盖，Story pipeline 覆盖全部产物 |
-| 关联 workflow 路径引用未被破坏 | ✅ PASS | create-prd/validate-prd/create-epics/create-architecture 引用路径完整 |
-
-### 5.4 Run #2 增量测试结果（2026-03-18）
-
-**Run #1 优化验证（6项全部确认）：**
-
-| 优化 ID | 验证状态 | 验证方法 |
-|---------|---------|---------|
-| OPT-REQ-1 | ✅ 已实施 | 读取 step-06：Section 1 "Switch to PM Role" 确认存在 |
-| OPT-REQ-2 | ✅ 已实施 | 读取 workflow.md：`{max_validation_iterations}` 条目在 State Variables 第5行 |
-| OPT-REQ-3 | ✅ 已实施 | 读取 step-08：JSON 模板 `analysis/architecture/validation` 三字段无引号 |
-| OPT-STORY-1 | ✅ 已实施 | 读取 step-09：Section 3.5 刷新逻辑 + Section 4.1 Finalization 刷新 |
-| OPT-STORY-2 | ✅ 已实施 | 读取 workflow.md：`{max_fix_iterations}` 及所有状态计数变量的说明 |
-| OPT-STORY-3 | ✅ 已实施 | 读取 step-07：`{fix_source}` 分类 + Section 6 差异化路由 |
-
-**Run #2 新优化验证：**
-
-| 测试项 | 状态 | 备注 |
-|--------|------|------|
-| step-05 Section 5 措辞已改为 "section 6 (Validation Passed)" | ✅ PASS | 读取文件第62行确认 |
-| step-01 Section 5 ready-for-dev 路由已改为 "Start at step-03" | ✅ PASS | 读取文件第124行确认 |
-| step-01 NEXT STEP 已新增 "IF starting at step-03" 独立条目 | ✅ PASS | 读取文件第138-139行确认 |
-| step-01 "in-progress" 路由条目已从组合条目中拆分出来 | ✅ PASS | 读取文件第141-142行确认 |
-| step-01 SUCCESS METRICS 路由映射说明已更新 | ✅ PASS | 读取文件最终确认 |
-
-**全部 auto-requirements-pipeline 步骤完整性（增量确认）：**
-
-| 步骤 | frontmatter `name` | nextStepFile 指向正确 | 状态 |
-|------|--------------------|-----------------------|------|
-| step-01-init-and-validate | ✅ | step-02 | ✅ |
-| step-02-requirements-analysis | ✅ | step-03 | ✅ |
-| step-03-architecture-analysis | ✅ | step-04 | ✅ |
-| step-04-create-prd | ✅ | step-05 | ✅ |
-| step-05-validate-prd（已修正） | ✅ | step-06 | ✅ |
-| step-06-create-epics（已优化） | ✅ | step-07 | ✅ |
-| step-07-create-architecture | ✅ | step-08 | ✅ |
-| step-08-finalize | ✅ | null（终止）| ✅ |
-
-**全部 auto-story-pipeline 步骤路由一致性（增量确认）：**
-
-| 触发状态 | 初始/Resume 模式路由 | 批量循环模式路由 | 一致性 |
-|---------|--------------------|--------------------|--------|
-| backlog | step-02 | step-02（via step-09）| ✅ 一致 |
-| ready-for-dev | step-03（本次修正后）| step-03（via step-02 skip）| ✅ 一致（修正前不一致） |
-| in-progress | step-04 | step-04（via step-09 resume）| ✅ 一致 |
-| review | step-05 | step-05（via step-09 resume）| ✅ 一致 |
-
----
-
-## 6. 风险评估
-
-| 风险 | 影响 | 缓解措施 |
-|------|------|---------|
-| OPT-STORY-3 引入 `{fix_source}` 新变量，旧版 LLM 可能不识别 | 中 | 轻量级内联复查设计（非强制委托）；若 fix_source 无法确定，默认走最保守路径（code-review 路由） |
-| step-07 的轻量级复查可能被 LLM 简化处理为"一律通过" | 低-中 | 步骤文件明确说明"do a focused inline verification of the fixed areas"，要求针对具体问题复查，非全量审查 |
-| step-09 刷新计数增加一次文件读取开销 | 极低 | 纯文件读取，无网络或计算开销；提升信息准确性的收益远大于成本 |
-| OPT-REQ-3 JSON 类型修改在边缘情况下可能产生语法错误 | 低 | 若 iteration 变量未被正确替换（保持 `{analysis_iteration}` 字符串），JSON 会无效；但这与改变前相同，并非新引入的问题 |
-| OPT-STORY-4 ready-for-dev 故事将额外经过 step-03 验证（Run #2 新增）| 低-极低 | 对于通过标准 create-story workflow 创建的故事，step-03 验证通常会通过（create-story 已内置质量控制）。极端情况下若 step-03 发现严重问题（readiness < 7/10），会增加修复次数，但这正是质量门禁的作用。已有 max 3 次自修复保障不无限阻塞。 |
-
----
-
-## 7. 后续建议
-
-### 7.1 短期（下一次分析周期）
-
-1. **为 auto-requirements-pipeline 增加可选的 UX 设计步骤**
-   目前 pipeline 在 PRD→Epics 之间没有 UX 设计步骤。对于前端密集型项目，可以在 step-06 之前添加 `step-05b-create-ux-design.md`，当且仅当项目类型为 UI/frontend 时触发，委托给 `xiaoma-create-ux-design` workflow。
-
-2. **为 auto-story-pipeline 增加 sprint-status 一致性验证**
-   batch 模式结束前，建议增加一个"Sprint Consistency Check"：验证 story file 中的状态字段与 sprint-status.yaml 中的状态完全一致，防止部分写入导致的状态漂移。
-
-3. **`pipeline-status.json` 被 auto-story-pipeline 读取的标准化**
-   step-01 in auto-story-pipeline 目前不读取 requirements pipeline 的 `pipeline-status.json`。建议在 step-01 的"Validate Prerequisites"中增加对 `pipeline-status.json` 的可选检查（如果存在，验证 requirements pipeline 已 complete），以防止在需求未完成时误启动 story pipeline。
-
-### 7.2 中期（架构级改进）
-
-4. **状态变量持久化**
-   当前所有状态变量（`{pipeline_status}`, `{steps_completed}` 等）仅存在于 LLM 上下文中，长会话中存在丢失风险。可以考虑将关键状态写入一个轻量的 `pipeline-run-state.json` 文件，支持从中断点恢复（类似 auto-requirements-pipeline 已有的 `pipeline-status.json`，但用于运行时状态而非完成状态）。
-
-5. **批量模式进度持久化**
-   auto-story-pipeline 批量模式处理多个 story 时，若会话意外中断，需要从头重新选择起点。可以在 step-09 循环时将 `{stories_completed}` 和已处理的 story keys 写入状态文件，支持断点续批。
-
-6. **Quality Gate 配置化**
-   目前多个质量门禁（validation score >= 7/10, max 3 validation attempts, max 5 fix iterations）是硬编码或半硬编码的。建议将这些阈值统一移至 `config.yaml`，允许项目级别的自定义。
-
-### 7.3 长期（生态级改进）
-
-7. **Pipeline 间的信号传递标准化**
-   当前两个 pipeline 的连接（requirements → story）是通过文档约定（用户手动运行 ASP）实现的。`pipeline-status.json` 为程序化连接奠定了基础，未来可以考虑一个"Master Pipeline Orchestrator"，自动在 requirements pipeline 完成后触发 sprint planning 和 story pipeline。
-
-8. **实现遥测与历史追踪**
-   目前每次运行都会覆盖输出产物。建议引入带时间戳的运行历史（如 `pipeline-runs/` 目录），记录每次运行的参数、迭代次数、成功/失败状态，支持跨版本的质量趋势分析。
-
----
-
----
-
-## 8. 运行历史
-
-| 运行次数 | 日期 | 类型 | 发现问题数 | 实施优化数 | 主要成果 |
-|---------|------|------|----------|----------|---------|
-| Run #1 | 2026-03-18 | 初始全量分析 | 6个 | 6个 | 建立基线：角色一致性、状态变量文档化、JSON类型修正、批量计数刷新、故障来源路由差异化 |
-| Run #2 | 2026-03-18 | 增量分析 | 2个 | 2个 | 导航歧义修正（step-05）、ready-for-dev 路由一致性修正（step-01） |
-
-**累计优化：8个 | 所有优化已验证在文件中实施 | 未发现破坏性变更**
-
----
-
-*报告最后更新: 2026-03-18 (Run #2) | 下次分析建议: 实施后约2周进行增量分析*