@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

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

@@ -0,0 +1,127 @@
+---
+name: auto-story-pipeline
+description: "Automated end-to-end story development pipeline (single story): create → validate → develop → review → test → fix → done. Use when the user says 'run auto pipeline', 'automate story development', or 'auto story pipeline'. For batch processing of all stories, use xiaoma-auto-story-pipeline-batch (ASPB) instead."
+---
+
+# Auto Story Pipeline Workflow
+
+**Goal:** Execute the complete automated story development lifecycle for a **single story** — from story creation through validation, development, code review, testing, bug fixing, and final delivery — as a single continuous pipeline.
+
+**Your Role:** Pipeline Orchestrator. You switch expert roles at each phase:
+- **Dev (xiaokai)** — Story creation and sprint coordination
+- **PM (xiaochan)** — Story validation and quality gate
+- **Dev (xiaokai)** — Code implementation and bug fixing
+- **Reviewer** — Adversarial code review
+- **Dev (xiaokai)** — Functional testing with real data
+
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- Execute ALL steps in exact order; do NOT skip steps
+- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the pipeline is COMPLETE or a HALT condition is triggered
+- Each step file loads fresh to combat "lost in the middle" context degradation
+
+> **Note:** This workflow processes a **single story** (or resumes a specific story). For batch processing of all backlog stories, use the **Auto Story Pipeline Batch** skill (`ASPB` or `/xiaoma-auto-story-pipeline-batch`), which uses Agent subprocess isolation for each story.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for focused execution across a long-running pipeline:
+
+- Each step loads fresh to prevent context loss in long sessions
+- State persists via variables passed between steps
+- Sequential progression through pipeline phases with conditional branching
+- Role switching at each phase boundary
+
+### State Variables
+
+- `{pipeline_mode}` — "single" (process next backlog story) or "resume" (resume a specific story by key)
+- `{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}`). 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, 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)
+- `{max_fix_iterations}` — Maximum fix-and-retest cycles per story (configurable via `max_fix_iterations` in config.yaml; default 5 if not set)
+- `{dev_retry}` — Dev-story retry counter used in step-04 section 3 when the delegated `xiaoma-dev-story` workflow HALTs with a fixable reason (max 2 retries; initialized lazily on first encounter, not in step-01). Bounds the dev-retry loop similarly to how `{fix_iteration}` bounds the fix loop — prevents indefinite retry on persistently unfixable HALT conditions.
+- `{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)
+- `{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)
+- `{stories_completed}` — Count of stories transitioned to "done" within this single-story pipeline run (initialized to 0 in step-01 section 3; incremented by 1 in step-08 section 5 after the story status flips to "done" in step-08 section 2; displayed in step-08's completion report). Always 0 or 1 in single-story mode; the variable exists so that a future "process-N-stories-in-a-loop" mode (currently delegated to the auto-story-pipeline-batch scheduler) can re-use the same accumulator semantics inside the inner pipeline. Note: not currently propagated to step-09 — step-09 reports `{steps_completed}` as `N / 9` and does not surface story-count, since single-story mode by definition processes at most one story.
+- `{steps_completed}` — Count of distinct pipeline step files executed in this run (initialized to 0 in step-01). Incremented at most once per step file even if a step (e.g., step-07) is re-loaded in a self-loop. Use `{fix_iteration}` (or, for step-03, `{validation_attempt}`) to track loop iterations within a single step. Reported in step-09 as `N / 9` because resume-mode runs may legitimately have N < 9.
+- `{epic_just_completed}` — Set by step-08 section 4 to the epic number when the last story in an epic transitions to "done"; otherwise null. Consumed by step-09 to recommend running epic-retrospective (ER).
+- `{run_warnings}` — Ordered list of prefix-tagged warning strings accumulated across the run. Each emitting step (step-01, step-02, step-03, step-05, step-06, step-07, step-08, plus step-09's own sanity check — step-04 develop-story is a pure-delegate orchestrator with no emitter; see prefix-tag table and cross-pipeline style note below) appends to this list using the canonical prefix tags defined in the "Warning Prefix-Tag Convention" section below. Serialized into `story-pipeline-status.json.warnings[]` by step-09 section 3. Empty list `[]` is a valid value.
+
+### Warning Prefix-Tag Convention
+
+All warnings emitted during a pipeline run are tagged with a `[step-NN]` prefix so downstream consumers (ASPB scheduler, auto-full-pipeline finalizer, dashboards, CI integrations) can filter and aggregate them uniformly. This convention is the **single source of truth** for the auto-story-pipeline family — `auto-story-pipeline-batch/workflow.md` section 2.3's "Warnings field semantics" block (an unnumbered block following part 6 "Return Format") and `auto-full-pipeline/step-05-finalize.md` (`[phase-3:{story_key}]` aggregation) both reference this table.
+
+| Prefix tag | Emitting step | Trigger examples |
+|---|---|---|
+| `[step-01]` | step-01 init-and-validate | Stale `pipeline-status.json` (status != "complete"); incomplete story file at resume entry; story marked `in-progress` with zero completed tasks |
+| `[step-02]` | step-02 create-story | Routing inconsistency (on-disk vs sprint-status); on-disk story status set but file incomplete (re-creation triggered); created story missing required sections |
+| `[step-03]` | step-03 validate-story | Validation iteration N failed but max not yet reached (advisory only — terminal NO-GO still HALTs) |
+| `[step-05]` | step-05 code-review | CRITICAL finding routed to step-07; HIGH/MEDIUM auto-fix produced new findings on re-review |
+| `[step-06]` | step-06 test-story | Coverage threshold not enforced (`enforce_coverage_thresholds=false`) |
+| `[step-07]` | step-07 fix-and-retest | Max fix iterations reached without convergence; escalation A/B/C/D dispatched |
+| `[step-08]` | step-08 complete-story | Sprint-status write fallback used; epic-completion check skipped due to unparseable key; AC-test traceability orphan (an acceptance criterion has no corresponding passing test in the step-06 report); AC-test traceability check skipped (step-06 test report missing or AC identifiers cannot be extracted) |
+| `[step-09]` | step-09 finalize | Sanity check: `{current_story_key}` not "done" in fresh sprint-status read |
+
+**Rules:**
+1. Each warning string starts with exactly one prefix tag enclosed in square brackets, followed by a single space, followed by a short human-readable description.
+2. Warnings are append-only within a run — no step retracts a warning emitted by an earlier step.
+3. step-09 section 3 writes the full list as-is into the status JSON; ASPB scheduler later wraps each entry with `[phase-3:{story_key}]` when aggregating into `full-pipeline-status.json` (no double-prefixing — the wrap is added, the original tag preserved).
+4. Free-form WARNING output to the user terminal is unchanged; the prefix tag is added when the warning is **also** appended to `{run_warnings}`. Steps may emit user-visible WARNINGs without appending to `{run_warnings}` for purely conversational hints.
+
+**Batch-mode plumbing note:** When this pipeline is executed as an Agent subprocess launched by the `auto-story-pipeline-batch` (ASPB) scheduler, **step-09 does not execute** — the scheduler's prompt instructs the Agent to STOP after step-08 and return a STORY_RESULT block. In that mode, the only exit point for `{run_warnings}` is **step-08 section 7's STORY_RESULT block**, whose `warnings:` field MUST be set to the full `{run_warnings}` list as-is (prefix tags preserved, empty `[]` valid). The ASPB scheduler then plumbs the field into the per-story archive `story-pipeline-status.{story_key}.json` (see `auto-story-pipeline-batch/workflow.md` section 2.4b), where `auto-full-pipeline/step-05-finalize` aggregates it under `[phase-3:{story_key}]`. Failure to serialize `{run_warnings}` into STORY_RESULT.warnings silently drops every Phase-3 warning at the ASPB → auto-full boundary — see step-08 section 7's "FAILURE MODES" for the three concrete anti-patterns to avoid. The producer-side template lives in step-08 section 7; this dictionary is the canonical tag source for both single-story mode (consumed at step-09 section 3) and batch mode (consumed at step-08 section 7).
+
+**Cross-pipeline style note:** The `[step-NN]` tags in this dictionary are **emitting-step** tags (axis: *which step produced the warning*). The sibling pipeline `auto-prd-to-stories` (`5-full-pipeline/auto-prd-to-stories/steps/step-05-finalize.md` §7) uses **semantic-category** tags instead (`[fr-coverage]` / `[tier-c]` / `[self-reported]` / `[fr-coverage-map]` / `[checklist]` / `[bridge-failure]` / `[warnings-truncated]`) — axis: *what kind of issue is reported*. Both styles are sanctioned; the choice is driven by pipeline shape. auto-story-pipeline has 8 distinct emitting steps (step-04 develop-story is a pure-delegate orchestrator with no emitter — see the prefix-tag table above which lists rows for step-01/02/03/05/06/07/08/09 only) so emitting-step tags carry useful filtering signal; auto-prd-to-stories has effectively 2 emitting steps so semantic tags carry more signal. A future dashboard layer that aggregates across all pipelines should treat both vocabularies as first-class and document the mapping at the dashboard side, not require either pipeline to switch styles.
+
+### Status Machine
+
+Stories progress through these states:
+- `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+
+### Step Ordering Rationale
+
+The pipeline runs: init → create → validate → develop → code-review → QA-test → fix (loop) → complete → finalize.
+
+**Why code-review (step-05) comes before QA-test (step-06):** Code review is cheaper than QA testing — it catches logic, security, and AC-implementation defects from the code itself without spinning up databases, fixtures, or test environments. Routing review failures to step-07 BEFORE running QA avoids wasting expensive QA cycles on code that has obvious defects. QA-test then validates correctness against real data, the final functional gate.
+
+**Why step-07 (fix-and-retest) is a self-looping step rather than a separate step file per iteration:** Bug-fix iteration counts vary widely per story. Keeping the loop in one step file with `{fix_iteration}` as the canonical counter (see step-07 LOOP CONTROL) avoids an N-fold explosion of step files and keeps the pipeline's "9 distinct steps" headline accurate regardless of iteration depth.
+
+**Why step-08 (complete-story) is distinct from step-09 (finalize):** step-08 is per-story bookkeeping (story status → done, sprint-status sync, epic-completion check). step-09 is per-pipeline-run reporting (sprint snapshot, machine-readable status JSON, next-action recommendations). Separating them lets resume-mode runs reuse step-08 logic without duplicating finalization concerns.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `validation` = `{skill-root}/checklist.md`
+
+### Related Workflows
+
+These existing workflows contain the detailed logic that pipeline steps delegate to:
+
+- `create_story_workflow` = `skill:xiaoma-create-story`
+- `dev_story_workflow` = `skill:xiaoma-dev-story`
+- `code_review_workflow` = `skill:xiaoma-code-review`
+- `qa_test_workflow` = `skill:xiaoma-qa-generate-e2e-tests`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+Read fully and follow: `./steps/step-01-init-and-validate.md` to begin the pipeline.

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline/xiaoma-skill-manifest.yaml

@@ -0,0 +1,27 @@
+canonicalId: xiaoma-auto-story-pipeline
+type: workflow
+description: "Automated end-to-end story development pipeline (single story). Use when the user says 'run auto pipeline', 'automate story development', or 'auto story pipeline'. For batch processing, use xiaoma-auto-story-pipeline-batch (ASPB)."
+# Additional metadata (advisory, non-normative — used by discovery tooling and downstream registries)
+agents:
+  - dev # xiaokai — owns step-01 (init/route), step-02 (create story), step-04 (develop), step-06 (test story), step-07 (fix-and-retest)
+  - pm # xiaochan — owns step-03 (validate story)
+  - reviewer # Generic reviewer persona — owns step-05 (code review)
+phase: 4-implementation
+step_count: 9
+modes:
+  - single # Default — process next backlog story
+  - resume # Resume a specific in-progress / review story by key
+prerequisites:
+  - "{implementation_artifacts}/sprint-status.yaml exists (run xiaoma-sprint-planning first)"
+  - "{implementation_artifacts}/{story_key}.md exists for resume mode"
+  - "_xiaoma/xmc/config.yaml present (XiaoMa installation)"
+  - "Delegated workflows installed: xiaoma-create-story, xiaoma-dev-story, xiaoma-code-review, xiaoma-qa-generate-e2e-tests"
+outputs:
+  - "{implementation_artifacts}/{story_key}.md  (story file with status='done')"
+  - "{implementation_artifacts}/sprint-status.yaml  (synced)"
+  - "{implementation_artifacts}/story-pipeline-status.json  (machine-readable run summary)"
+status_machine: "backlog → ready-for-dev → in-progress → review → done"
+fix_iteration_cap: 5 # Configurable via config.yaml#max_fix_iterations
+downstream:
+  - xiaoma-auto-story-pipeline-batch # ASPB scheduler invokes this pipeline as an Agent subprocess per story
+  - xiaoma-retrospective # Recommended when an epic completes (signaled via {epic_just_completed})

package/src/{xmc/workflows/4-implementation/auto-story-pipeline-batch → xmc-skills/4-implementation/xiaoma-auto-story-pipeline-batch}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: auto-story-pipeline-batch
-description: "Batch automated story development pipeline with Agent subprocess isolation. Processes ALL backlog stories sequentially, each in an independent Agent context. Use when the user says 'batch story pipeline', 'ASB', 'auto story batch', or 'batch auto pipeline'"
+name: xiaoma-auto-story-pipeline-batch
+description: "Batch automated story development pipeline with Agent subprocess isolation. Processes ALL backlog stories sequentially, each in an independent Agent context. Use when the user says 'batch story pipeline', 'ASPB', 'ASB', 'auto story batch', or 'batch auto pipeline'"
 ---
 
 Follow the instructions in [workflow.md](workflow.md).

package/src/xmc-skills/4-implementation/xiaoma-auto-story-pipeline-batch/checklist.md

@@ -0,0 +1,45 @@
+# Auto Story Pipeline Batch (ASPB) Completion Checklist
+
+Use this checklist to validate the batch pipeline completed successfully.
+
+Per-story functional validation is delegated to the underlying `auto-story-pipeline/checklist.md`, since each Agent subprocess walks the same step-02 → step-08 flow. This checklist therefore focuses on **batch-level scheduler responsibilities** that single-story mode does not exercise.
+
+## Scheduler-Level Validation
+
+- [ ] **Sprint Status Refreshed** — Final fresh-read of `{sprint_status}` performed in section 3.1 before report generation (no stale counts from mid-run memory).
+- [ ] **Queue Drained or HALT Recorded** — Either `backlog_count == 0 AND ready_count == 0` at the end, or a HALT reason is captured in the report and the batch status JSON.
+- [ ] **Failed Stories Tracked** — Every Agent return with `final_status` of `halted` / `failed` is reflected in `failed_story_keys[]` and surfaces in `story_results[]`.
+- [ ] **No Concurrent Modification** — Stories are processed serially (one Agent subprocess at a time); no parallel writes to `sprint-status.yaml`.
+
+## Per-Story Archive Validation
+
+- [ ] **Per-Story Archive Written** — For every story processed (including failed/halted), `{implementation_artifacts}/story-pipeline-status.{story_key}.json` exists.
+- [ ] **Archive Schema Complete** — Each archive contains `pipeline`, `date`, `mode: "batch-archive"`, `story_key`, `story_path`, `final_status`, `fix_iterations_used`, `validation_attempts`, `files_modified[]`, `summary`, `error`, `warnings[]`.
+- [ ] **STORY_RESULT Warnings Plumbed** — When the source Agent's STORY_RESULT contains a non-empty `warnings` array, the archive's `warnings[]` field reflects the same entries (count and order preserved, prefix tags intact). When STORY_RESULT omits the field (legacy contract), the archive falls back to `warnings: []` per the backward-compatibility rule.
+- [ ] **STORY_RESULT Sample Conformance** — Archive entries that came from a STORY_RESULT block match the field shapes documented in `auto-story-pipeline-batch/workflow.md` section 2.3's "Concrete examples" block (an unnumbered block following part 6 "Return Format") — `final_status` is one of `done`/`halted`/`failed`; `files_modified` is a deduplicated union; `error` is empty on success and populated on HALT; every `warnings[]` entry begins with a `[step-NN]` prefix tag from the canonical dictionary (`auto-story-pipeline/workflow.md` → "Warning Prefix-Tag Convention").
+- [ ] **Archive Atomic Write** — Each archive was written via temp-file-then-rename (no `.tmp` residue in `{implementation_artifacts}`).
+- [ ] **Archive Tracking List** — Every archive path appears in the main scheduler's `archived_status_files[]` list.
+- [ ] **No Single-File Overwrite** — Per-story archives use the key-suffixed filename (`story-pipeline-status.{story_key}.json`) and never write to the canonical single-story path (`story-pipeline-status.json`).
+
+## Batch-Level Machine-Readable Status
+
+- [ ] **Batch Status JSON Written** — `{implementation_artifacts}/batch-pipeline-status.json` exists with the full schema.
+- [ ] **Batch Status Schema Complete** — Top-level fields present: `pipeline`, `date`, `project`, `stories_completed`, `stories_failed`, `sprint_snapshot{}`, `story_results[]`, `failed_story_keys[]`, `archived_status_files[]`.
+- [ ] **Batch Status Atomic Write** — Written via temp-file-then-rename (no `.tmp` residue).
+- [ ] **Archived Files List Matches Disk** — Each entry in `archived_status_files[]` resolves to an existing per-story archive file.
+- [ ] **Sprint Snapshot Accurate** — `sprint_snapshot{}` counts match the final refreshed `{sprint_status}`.
+- [ ] **Partial Run Auditable** — When the batch was halted (rather than emptied queue), `batch-pipeline-status.json` was still written before exit so the partial run is auditable.
+
+## Downstream Consumer Validation
+
+- [ ] **auto-full-pipeline Compatibility** — `archived_status_files[]` is consumable by `auto-full-pipeline/step-05-finalize` as the single-source-of-truth enumeration for Phase-3 warning aggregation (no globbing required).
+- [ ] **Failed Stories Surface as Warnings** — When `failed_story_keys[]` is non-empty, downstream consumers can synthesize `[phase-3:{story_key}] story failed` warnings from this list.
+
+## Per-Story Functional Validation (Delegated)
+
+For each story processed by an Agent subprocess, the per-story checks defined in `auto-story-pipeline/checklist.md` apply:
+
+- Story Created / Validated / Implementation Complete / Tests Pass / Code Review Passed / QA Test Passed / Status Updated / Sprint Status Synced
+- Sprint-Status Write Safe / Steps Completed Rendered Unambiguously
+
+Note: the "Machine-Readable Status Written" item in `auto-story-pipeline/checklist.md` refers to step-09's `story-pipeline-status.json`. In batch mode step-09 does NOT run; that requirement is replaced by the per-story archive item above.

package/src/{xmc/workflows/4-implementation/auto-story-pipeline-batch → xmc-skills/4-implementation/xiaoma-auto-story-pipeline-batch}/workflow.md

@@ -51,18 +51,19 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
 ### Paths
 
-- `story_pipeline_path` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/auto-story-pipeline`
+- `story_pipeline_path` = `{skill-root}/../xiaoma-auto-story-pipeline` (the sibling single-story pipeline skill — installed verbatim as a sibling dir, holds the shared `steps/step-02..08` + per-story `checklist.md`)
 - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
-- `validation_checklist` = `{story_pipeline_path}/checklist.md`
+- `validation_checklist` = `{story_pipeline_path}/checklist.md` (per-story checks, passed to each Agent subprocess)
+- `batch_validation_checklist` = `./checklist.md` (batch-level scheduler checks, consumed in section 3.4)
 
 ### Related Workflows (Passed to Agent)
 
 These paths will be passed to each Agent subprocess so it can delegate to existing workflow logic:
 
-- `create_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-create-story/workflow.md`
-- `dev_story_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-dev-story/workflow.md`
-- `code_review_workflow` = `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-code-review/workflow.md`
-- `qa_test_workflow` = `{project-root}/_xiaoma/xmc/workflows/xiaoma-qa-generate-e2e-tests/workflow.md`
+- `create_story_workflow` = `skill:xiaoma-create-story`
+- `dev_story_workflow` = `skill:xiaoma-dev-story`
+- `code_review_workflow` = `skill:xiaoma-code-review`
+- `qa_test_workflow` = `skill:xiaoma-qa-generate-e2e-tests`
 
 ### Context
 
@@ -86,7 +87,7 @@ Check that the following required artifacts exist:
 2. **Sprint Status File** — `{sprint_status}` must exist
    - If missing:
      a. Output INFO — "sprint-status.yaml not found. Auto-generating via Sprint Planning..."
-     b. Read and follow the sprint-planning workflow: `{project-root}/_xiaoma/xmc/workflows/4-implementation/xiaoma-sprint-planning/workflow.md`
+     b. Read and follow the sprint-planning workflow: `skill:xiaoma-sprint-planning`
      c. After sprint-planning completes, verify `{sprint_status}` now exists
      d. If still missing: HALT — "Failed to auto-generate sprint-status.yaml. Run Sprint Planning (SP) manually."
 
@@ -136,6 +137,7 @@ Initialize tracking variables:
 - `stories_failed` = 0
 - `failed_story_keys` = [] (empty list — tracks story keys that failed, to avoid infinite loops)
 - `story_results` = [] (empty list — accumulates result summaries for the final report)
+- `archived_status_files` = [] (empty list — paths to per-story status JSON archives written in section 2.4b; consumed by auto-full-pipeline step-05-finalize for warning aggregation)
 
 Enter Step 2 to start the batch loop.
 
@@ -232,8 +234,59 @@ STORY_RESULT:
 - files_modified: [list of files]
 - summary: {one-line description of what was done}
 - error: {error message if halted/failed, empty otherwise}
+- warnings: [list of warning strings encountered during step-02 → step-08, may be empty]
 ```
 
+**Producer-side template:** The Agent-side authoritative template for filling this block lives in `auto-story-pipeline/steps/step-08-complete-story.md` section 7 "Batch-Mode Result Block (conditional)". That section instructs the Agent to serialize `{run_warnings}` directly into the `warnings` field (as-is, prefix tags preserved, empty list `[]` valid). When updating the STORY_RESULT schema, update both this section AND step-08 section 7 to keep producer and consumer aligned.
+
+**Concrete examples:** The abstract field list above can be hard to translate into emitted output. Two realistic samples follow — Agent runners should match these shapes verbatim modulo project-specific values:
+
+*Success case with accumulated warnings* (Agent reaches step-08 section 7 successfully; `{run_warnings}` collected non-empty prefix-tagged entries during step-05 / step-06 / step-08):
+
+```
+STORY_RESULT:
+- story_key: 1.3
+- final_status: done
+- fix_iterations_used: 2
+- validation_attempts: 1
+- files_modified: ["src/api/auth.ts", "src/api/auth.test.ts", "docs/stories/story-1.3.md", "_xiaoma/xmc/sprint-status.yaml"]
+- summary: Implemented OAuth refresh-token rotation; 2 fix iterations after QA flagged race on expiry boundary
+- error:
+- warnings:
+  - "[step-05] CRITICAL finding for 1.3 unresolvable inline — routed to step-07 with CRITICAL flag preserved"
+  - "[step-06] Coverage threshold not enforced (enforce_coverage_thresholds=false) for 1.3 — unit 72% / integration 58% / AC 100%"
+  - "[step-08] Could not extract epic number from 1.3 — epic completion check skipped"
+```
+
+*HALT-path case* (Agent hit a HALT condition before reaching step-08 section 7; emits STORY_RESULT at the HALT site with `final_status: halted`, captures the error, and includes whatever `{run_warnings}` had accumulated up to that point):
+
+```
+STORY_RESULT:
+- story_key: 2.1
+- final_status: halted
+- fix_iterations_used: 5
+- validation_attempts: 1
+- files_modified: ["src/billing/invoice.ts", "src/billing/invoice.test.ts", "docs/stories/story-2.1.md"]
+- summary: Max fix iterations reached on invoice rounding edge case; escalation protocol B dispatched
+- error: step-07 max-iter HALT — {fix_iteration}=5 exceeded {max_fix_iterations}=5; see escalation log
+- warnings:
+  - "[step-05] Unresolved code-review findings for 2.1 (CRITICAL/HIGH/MEDIUM counts: 0/1/3) — routed to step-07"
+  - "[step-07] Max fix iterations (5) reached for 2.1 — escalation dispatched (see protocol A/B/C/D)"
+```
+
+**Reading the samples:**
+
+- `warnings` is rendered here as a YAML-style list with quoted strings for readability; the scheduler's section 2.4b parser accepts both YAML-list and JSON-array forms.
+- Empty `error` on success is rendered as an empty value (the field is present but unset), NOT omitted. Empty `warnings` on a clean run is rendered as `warnings: []` (also acceptable: omit the field entirely — the scheduler treats absence as `[]` for backward compatibility).
+- `files_modified` is the union across step-04 → step-08 (per step-08 section 7 rule 3); duplicates removed.
+- Both samples preserve `[step-NN]` prefix tags on every warning entry — the I-series producer-side plumbing in step-01 → step-08 guarantees these tags exist when entries are appended to `{run_warnings}`.
+
+**Warnings field semantics:**
+- Each warning is a short prefix-tagged string. The **canonical prefix-tag dictionary** lives in `auto-story-pipeline/workflow.md` → "Warning Prefix-Tag Convention" and is the single source of truth shared by single-story mode (step-09) and batch mode (this scheduler). Tags include `[step-01]` through `[step-09]`; each maps to a specific emitting step. Examples: `[step-05] CRITICAL finding routed to step-07: {short description}`, `[step-06] coverage threshold not enforced (enforce_coverage_thresholds=false): unit {pct}%`, `[step-08] sprint-status write fallback used: {reason}`.
+- The Agent should collect warnings it produces during its run (typically by accumulating them in a `{run_warnings}` list as documented in the auto-story-pipeline single-story flow) and append them here; if no warnings, return an empty list.
+- The scheduler's section 2.4b will plumb `warnings[]` into the per-story archive (`story-pipeline-status.{story_key}.json`), where `auto-full-pipeline/step-05-finalize` aggregates them under the `[phase-3:{story_key}]` prefix (the wrap is added; the original `[step-NN]` tag is preserved).
+- Backward compatibility: if a legacy Agent omits the `warnings` field, the scheduler treats it as `[]` and continues without halting. If an Agent emits warnings *without* prefix tags, the scheduler does not auto-tag them — they will appear in `full-pipeline-status.json` as `[phase-3:{story_key}] <untagged text>`, which is still parseable but loses step-level filterability.
+
 </critical>
 
 ### 2.4 Read Agent Result and Handle Errors
@@ -251,6 +304,46 @@ Read the Agent's returned processing result summary.
 - **Do NOT halt the batch** — continue to the next story
 - Output: "Story {current_story_key} failed/halted. Skipping and continuing to next story."
 
+### 2.4b Archive Per-Story Status JSON (resolves single-file-overwrite risk in batch mode)
+
+The Agent subprocess executes step-02 through step-08 only — **it does NOT run step-09**, which is where single-story mode writes `story-pipeline-status.json`. Therefore, in batch mode no per-story status JSON is ever written, and `auto-full-pipeline/step-05-finalize` cannot aggregate Phase-3 warnings by story.
+
+This sub-step closes the gap. The main scheduler (not the Agent) writes a per-story status archive after each Agent returns, so:
+
+- Phase-3 warnings can be aggregated per-story by the full-pipeline finalizer.
+- A separate audit trail exists even when many stories run in one batch.
+- No conflict with single-story mode — single-story mode still writes its own `story-pipeline-status.json` via step-09; the archive files use a distinct key-suffixed filename and never overwrite the canonical path.
+
+**Write target:** `{implementation_artifacts}/story-pipeline-status.{current_story_key}.json`
+
+**Atomic write** (write to `.tmp`, then rename):
+
+```json
+{
+  "pipeline": "auto-story-pipeline-batch",
+  "date": "{date}",
+  "project": "{project_name}",
+  "mode": "batch-archive",
+  "story_key": "{current_story_key}",
+  "story_path": "{implementation_artifacts}/{current_story_key}.md",
+  "final_status": "{agent_final_status}",
+  "fix_iterations_used": "{agent_fix_iterations_used}",
+  "validation_attempts": "{agent_validation_attempts}",
+  "files_modified": ["..."],
+  "summary": "{agent_summary}",
+  "error": "{agent_error_or_empty}",
+  "warnings": "{agent_warnings_or_empty}"
+}
+```
+
+Notes for serialization:
+- Source fields from the Agent's STORY_RESULT block (section 2.3 part 6).
+- `warnings[]` is plumbed from the Agent's STORY_RESULT `warnings` field. If the Agent omits the field (legacy contract), serialize `warnings` as an empty list and continue — never halt.
+- Each warning string should retain its prefix tag (e.g. `[step-05]`, `[step-06]`); `auto-full-pipeline/step-05-finalize` will additionally wrap each entry under `[phase-3:{story_key}]` when aggregating into `full-pipeline-status.json`.
+- If writing the archive itself fails (disk full, permission error), log a WARNING but do NOT halt the batch — the canonical record is still in `sprint-status.yaml`.
+
+**Record archive in tracking list:** append `{implementation_artifacts}/story-pipeline-status.{current_story_key}.json` to `archived_status_files[]` (initialized as empty list in Step 1.3).
+
 ### 2.5 Output Progress
 
 1. Output brief one-line result for this story
@@ -315,6 +408,56 @@ The automated batch story development pipeline has finished.
 **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."
 
+### 3.3 Generate Machine-Readable Batch Status
+
+Write to: `{implementation_artifacts}/batch-pipeline-status.json` using atomic temp-file-then-rename (same approach as section 2.4b):
+
+```json
+{
+  "pipeline": "auto-story-pipeline-batch",
+  "date": "{date}",
+  "project": "{project_name}",
+  "stories_completed": "{stories_completed}",
+  "stories_failed": "{stories_failed}",
+  "sprint_snapshot": {
+    "backlog": "{backlog_count}",
+    "ready_for_dev": "{ready_count}",
+    "in_progress": "{in_progress_count}",
+    "review": "{review_count}",
+    "done": "{done_count}"
+  },
+  "story_results": [
+    {
+      "story_key": "...",
+      "final_status": "done|halted|failed",
+      "fix_iterations_used": 0,
+      "validation_attempts": 0,
+      "summary": "...",
+      "error": ""
+    }
+  ],
+  "failed_story_keys": [],
+  "archived_status_files": ["{implementation_artifacts}/story-pipeline-status.{story_key}.json", "..."]
+}
+```
+
+Notes:
+- `archived_status_files[]` lists every per-story archive written in section 2.4b. `auto-full-pipeline/step-05-finalize` reads this list to enumerate Phase-3 status JSON files without globbing — preferred over best-effort filesystem scan.
+- If batch was halted by a HALT condition (rather than emptied queue), still write this file before exiting — the partial run is auditable.
+
+### 3.4 Run Batch Completion Checklist
+
+Apply the batch-level scheduler checks from `{batch_validation_checklist}` (`./checklist.md`):
+
+1. Scheduler-Level Validation (sprint refresh, queue state, failed-story tracking, serial processing)
+2. Per-Story Archive Validation (existence, schema, atomic write, tracking list, no canonical-path overwrite)
+3. Batch-Level Machine-Readable Status (file presence, schema, atomic write, archive list integrity, sprint snapshot accuracy, partial-run auditability)
+4. Downstream Consumer Validation (auto-full-pipeline compatibility, failed-story warning synthesis)
+
+For per-story functional validation (Story Created / Tests Pass / Code Review Passed / ...), each Agent subprocess is responsible for checking `{validation_checklist}` (the auto-story-pipeline checklist) during its own step-02 → step-08 walk; the scheduler does not re-run that here.
+
+Output any failed items as WARNINGS in the final report, but do NOT alter `batch-pipeline-status.json` retroactively — the report and the JSON are immutable artifacts of this run.
+
 **HALT** — Pipeline complete.
 
 </step>

package/src/{xmc/workflows/4-implementation/auto-story-pipeline-batch → xmc-skills/4-implementation/xiaoma-auto-story-pipeline-batch}/xiaoma-skill-manifest.yaml

@@ -1,3 +1,3 @@
-canonicalId: auto-story-pipeline-batch
+canonicalId: xiaoma-auto-story-pipeline-batch
 type: workflow
-description: "Batch automated story development pipeline with Agent subprocess isolation. Each story is processed in an independent Agent context to prevent context bloat. Use when the user says 'batch story pipeline', 'ASB', 'auto story batch', or 'batch auto pipeline'"
+description: "Batch automated story development pipeline with Agent subprocess isolation. Each story is processed in an independent Agent context to prevent context bloat. Use when the user says 'batch story pipeline', 'ASPB', 'ASB', 'auto story batch', or 'batch auto pipeline'"

package/src/xmc-skills/4-implementation/xiaoma-checkpoint-preview/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: xiaoma-checkpoint-preview
+description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".'
+---
+
+# Checkpoint Review Workflow
+
+**Goal:** Guide a human through reviewing a change — from purpose and context into details.
+
+**Your Role:** You are assisting the user in reviewing a change.
+
+## Conventions
+
+- Bare paths (e.g. `step-01-orientation.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+
+- `implementation_artifacts`
+- `planning_artifacts`
+- `communication_language`
+- `document_output_language`
+
+### Step 5: Greet the User
+
+Greet the user, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Global Step Rules (apply to every step)
+
+- **Path:line format** — Every code reference must use CWD-relative `path:line` format (no leading `/`) so it is clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
+- **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections.
+- **Language** — Speak in `{communication_language}`. Write any file output in `{document_output_language}`.
+
+## FIRST STEP
+
+Read fully and follow `./step-01-orientation.md` to begin.

package/src/xmc-skills/4-implementation/xiaoma-checkpoint-preview/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-checkpoint-preview. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All stories must include testable acceptance criteria."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its final step,
+# after the review decision (approve/rework/discuss) is made. Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/4-implementation/xiaoma-checkpoint-preview/generate-trail.md

@@ -0,0 +1,38 @@
+# Generate Review Trail
+
+Generate a review trail from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.
+
+## Follow Global Step Rules in SKILL.md
+
+## INSTRUCTIONS
+
+1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats in step-01).
+2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. If total file content exceeds ~50k tokens, read only the files with the largest diff hunks in full and use hunks for the rest.
+3. If a spec exists, use its Intent section to anchor concern identification.
+4. Identify 2–5 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings.
+5. For each concern, select 1–4 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes.
+6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types).
+7. Format each stop using `path:line` per the global step rules:
+
+```
+**{Concern name}**
+
+- {one-line framing, ≤15 words}
+  `src/path/to/file.ts:42`
+```
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+## PRESENT
+
+Output after the orientation:
+
+```
+I built a review trail for this {change_type} (no author-produced trail was found):
+
+{generated trail}
+```
+
+The generated trail serves as the Suggested Review Order for subsequent steps. Set `review_mode` to `full-trail` — a trail now exists, so all downstream steps should treat it as one.
+
+If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable."