@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/src/modules/xmc/workflows/testarch/trace/instructions.md

@@ -0,0 +1,1045 @@
+# Test Architect Workflow: Requirements Traceability & Quality Gate Decision
+
+**Workflow:** `testarch-trace`
+**Purpose:** Generate requirements-to-tests traceability matrix, analyze coverage gaps, and make quality gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+**Agent:** Test Architect (TEA)
+**Format:** Pure Markdown v4.0 (no XML blocks)
+
+---
+
+## Overview
+
+This workflow operates in two sequential phases to validate test coverage and deployment readiness:
+
+**PHASE 1 - REQUIREMENTS TRACEABILITY:** Create comprehensive traceability matrix mapping acceptance criteria to implemented tests, identify coverage gaps, and provide actionable recommendations.
+
+**PHASE 2 - QUALITY GATE DECISION:** Use traceability results combined with test execution evidence to make gate decisions (PASS/CONCERNS/FAIL/WAIVED) that determine deployment readiness.
+
+**Key Capabilities:**
+
+- Map acceptance criteria to specific test cases across all levels (E2E, API, Component, Unit)
+- Classify coverage status (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY)
+- Prioritize gaps by risk level (P0/P1/P2/P3) using test-priorities framework
+- Apply deterministic decision rules based on coverage and test execution results
+- Generate gate decisions with evidence and rationale
+- Support waivers for business-approved exceptions
+- Update workflow status and notify stakeholders
+
+---
+
+## Prerequisites
+
+**Required (Phase 1):**
+
+- Acceptance criteria (from story file OR provided inline)
+- Implemented test suite (or acknowledge gaps to be addressed)
+
+**Required (Phase 2 - if `enable_gate_decision: true`):**
+
+- Test execution results (CI/CD test reports, pass/fail rates)
+- Test design with risk priorities (P0/P1/P2/P3)
+
+**Recommended:**
+
+- `test-design.md` (for risk assessment and priority context)
+- `nfr-assessment.md` (for release-level gates)
+- `tech-spec.md` (for technical implementation context)
+- Test framework configuration (playwright.config.ts, jest.config.js, etc.)
+
+**Halt Conditions:**
+
+- If story lacks any implemented tests AND no gaps are acknowledged, recommend running `*atdd` workflow first
+- If acceptance criteria are completely missing, halt and request them
+- If Phase 2 enabled but test execution results missing, warn and skip gate decision
+
+---
+
+## PHASE 1: REQUIREMENTS TRACEABILITY
+
+This phase focuses on mapping requirements to tests, analyzing coverage, and identifying gaps.
+
+---
+
+### Step 1: Load Context and Knowledge Base
+
+**Actions:**
+
+1. Load relevant knowledge fragments from `{project-root}/{xiaoma_folder}/xmc/testarch/tea-index.csv`:
+   - `test-priorities-matrix.md` - P0/P1/P2/P3 risk framework with automated priority calculation, risk-based mapping, tagging strategy (389 lines, 2 examples)
+   - `risk-governance.md` - Risk-based testing approach: 6 categories (TECH, SEC, PERF, DATA, BUS, OPS), automated scoring, gate decision engine, coverage traceability (625 lines, 4 examples)
+   - `probability-impact.md` - Risk scoring methodology: probability × impact matrix, automated classification, dynamic re-assessment, gate integration (604 lines, 4 examples)
+   - `test-quality.md` - Definition of Done for tests: deterministic, isolated with cleanup, explicit assertions, length/time limits (658 lines, 5 examples)
+   - `selective-testing.md` - Duplicate coverage patterns: tag-based, spec filters, diff-based selection, promotion rules (727 lines, 4 examples)
+
+2. Read story file (if provided):
+   - Extract acceptance criteria
+   - Identify story ID (e.g., 1.3)
+   - Note any existing test design or priority information
+
+3. Read related XiaoMa artifacts (if available):
+   - `test-design.md` - Risk assessment and test priorities
+   - `tech-spec.md` - Technical implementation details
+   - `PRD.md` - Product requirements context
+
+**Output:** Complete understanding of requirements, priorities, and existing context
+
+---
+
+### Step 2: Discover and Catalog Tests
+
+**Actions:**
+
+1. Auto-discover test files related to the story:
+   - Search for test IDs (e.g., `1.3-E2E-001`, `1.3-UNIT-005`)
+   - Search for describe blocks mentioning feature name
+   - Search for file paths matching feature directory
+   - Use `glob` to find test files in `{test_dir}`
+
+2. Categorize tests by level:
+   - **E2E Tests**: Full user journeys through UI
+   - **API Tests**: HTTP contract and integration tests
+   - **Component Tests**: UI component behavior in isolation
+   - **Unit Tests**: Business logic and pure functions
+
+3. Extract test metadata:
+   - Test ID (if present)
+   - Describe/context blocks
+   - It blocks (individual test cases)
+   - Given-When-Then structure (if BDD)
+   - Assertions used
+   - Priority markers (P0/P1/P2/P3)
+
+**Output:** Complete catalog of all tests for this feature
+
+---
+
+### Step 3: Map Criteria to Tests
+
+**Actions:**
+
+1. For each acceptance criterion:
+   - Search for explicit references (test IDs, describe blocks mentioning criterion)
+   - Map to specific test files and it blocks
+   - Use Given-When-Then narrative to verify alignment
+   - Document test level (E2E, API, Component, Unit)
+
+2. Build traceability matrix:
+
+   ```
+   | Criterion ID | Description | Test ID     | Test File        | Test Level | Coverage Status |
+   | ------------ | ----------- | ----------- | ---------------- | ---------- | --------------- |
+   | AC-1         | User can... | 1.3-E2E-001 | e2e/auth.spec.ts | E2E        | FULL            |
+   ```
+
+3. Classify coverage status for each criterion:
+   - **FULL**: All scenarios validated at appropriate level(s)
+   - **PARTIAL**: Some coverage but missing edge cases or levels
+   - **NONE**: No test coverage at any level
+   - **UNIT-ONLY**: Only unit tests (missing integration/E2E validation)
+   - **INTEGRATION-ONLY**: Only API/Component tests (missing unit confidence)
+
+4. Check for duplicate coverage:
+   - Same behavior tested at multiple levels unnecessarily
+   - Flag violations of selective testing principles
+   - Recommend consolidation where appropriate
+
+**Output:** Complete traceability matrix with coverage classifications
+
+---
+
+### Step 4: Analyze Gaps and Prioritize
+
+**Actions:**
+
+1. Identify coverage gaps:
+   - List criteria with NONE, PARTIAL, UNIT-ONLY, or INTEGRATION-ONLY status
+   - Assign severity based on test-priorities framework:
+     - **CRITICAL**: P0 criteria without FULL coverage (blocks release)
+     - **HIGH**: P1 criteria without FULL coverage (PR blocker)
+     - **MEDIUM**: P2 criteria without FULL coverage (nightly test gap)
+     - **LOW**: P3 criteria without FULL coverage (acceptable gap)
+
+2. Recommend specific tests to add:
+   - Suggest test level (E2E, API, Component, Unit)
+   - Provide test description (Given-When-Then)
+   - Recommend test ID (e.g., `1.3-E2E-004`)
+   - Explain why this test is needed
+
+3. Calculate coverage metrics:
+   - Overall coverage percentage (criteria with FULL coverage / total criteria)
+   - P0 coverage percentage (critical paths)
+   - P1 coverage percentage (high priority)
+   - Coverage by level (E2E%, API%, Component%, Unit%)
+
+4. Check against quality gates:
+   - P0 coverage >= 100% (required)
+   - P1 coverage >= 90% (recommended)
+   - Overall coverage >= 80% (recommended)
+
+**Output:** Prioritized gap analysis with actionable recommendations and coverage metrics
+
+---
+
+### Step 5: Verify Test Quality
+
+**Actions:**
+
+1. For each mapped test, verify:
+   - Explicit assertions are present (not hidden in helpers)
+   - Test follows Given-When-Then structure
+   - No hard waits or sleeps
+   - Self-cleaning (test cleans up its data)
+   - File size < 300 lines
+   - Test duration < 90 seconds
+
+2. Flag quality issues:
+   - **BLOCKER**: Missing assertions, hard waits, flaky patterns
+   - **WARNING**: Large files, slow tests, unclear structure
+   - **INFO**: Style inconsistencies, missing documentation
+
+3. Reference knowledge fragments:
+   - `test-quality.md` for Definition of Done
+   - `fixture-architecture.md` for self-cleaning patterns
+   - `network-first.md` for Playwright best practices
+   - `data-factories.md` for test data patterns
+
+**Output:** Quality assessment for each test with improvement recommendations
+
+---
+
+### Step 6: Generate Deliverables (Phase 1)
+
+**Actions:**
+
+1. Create traceability matrix markdown file:
+   - Use template from `trace-template.md`
+   - Include full mapping table
+   - Add coverage status section
+   - Add gap analysis section
+   - Add quality assessment section
+   - Add recommendations section
+   - Save to `{output_folder}/traceability-matrix.md`
+
+2. Generate gate YAML snippet (if enabled):
+
+   ```yaml
+   traceability:
+     story_id: '1.3'
+     coverage:
+       overall: 85%
+       p0: 100%
+       p1: 90%
+       p2: 75%
+     gaps:
+       critical: 0
+       high: 1
+       medium: 2
+     status: 'PASS' # or "FAIL" if P0 < 100%
+   ```
+
+3. Create coverage badge/metric (if enabled):
+   - Generate badge markdown: `![Coverage](https://img.shields.io/badge/coverage-85%25-green)`
+   - Export metrics to JSON for CI/CD integration
+
+4. Update story file (if enabled):
+   - Add "Traceability" section to story markdown
+   - Link to traceability matrix
+   - Include coverage summary
+   - Add gate status
+
+**Output:** Complete Phase 1 traceability deliverables
+
+**Next:** If `enable_gate_decision: true`, proceed to Phase 2. Otherwise, workflow complete.
+
+---
+
+## PHASE 2: QUALITY GATE DECISION
+
+This phase uses traceability results to make a quality gate decision (PASS/CONCERNS/FAIL/WAIVED) based on evidence and decision rules.
+
+**When Phase 2 Runs:** Automatically after Phase 1 if `enable_gate_decision: true` (default: true)
+
+**Skip Conditions:** If test execution results (`test_results`) not provided, warn and skip Phase 2.
+
+---
+
+### Step 7: Gather Quality Evidence
+
+**Actions:**
+
+1. **Load Phase 1 traceability results** (inherited context):
+   - Coverage metrics (P0/P1/overall percentages)
+   - Gap analysis (missing/partial tests)
+   - Quality concerns (test quality flags)
+   - Traceability matrix
+
+2. **Load test execution results** (if `test_results` provided):
+   - Read CI/CD test reports (JUnit XML, TAP, JSON)
+   - Extract pass/fail counts by priority
+   - Calculate pass rates:
+     - **P0 pass rate**: `(P0 passed / P0 total) * 100`
+     - **P1 pass rate**: `(P1 passed / P1 total) * 100`
+     - **Overall pass rate**: `(All passed / All total) * 100`
+   - Identify failing tests and map to criteria
+
+3. **Load NFR assessment** (if `nfr_file` provided):
+   - Read `nfr-assessment.md` or similar
+   - Check critical NFR status (performance, security, scalability)
+   - Flag any critical NFR failures
+
+4. **Load supporting artifacts**:
+   - `test-design.md` → Risk priorities, DoD checklist
+   - `story-*.md` or `Epics.md` → Requirements context
+   - `xmc-workflow-status.md` → Workflow completion status (if `check_all_workflows_complete: true`)
+
+5. **Validate evidence freshness** (if `validate_evidence_freshness: true`):
+   - Check timestamps of test-design, traceability, NFR assessments
+   - Warn if artifacts are >7 days old
+
+6. **Check prerequisite workflows** (if `check_all_workflows_complete: true`):
+   - Verify test-design workflow complete
+   - Verify trace workflow complete (Phase 1)
+   - Verify nfr-assess workflow complete (if release-level gate)
+
+**Output:** Consolidated evidence bundle with all quality signals
+
+---
+
+### Step 8: Apply Decision Rules
+
+**If `decision_mode: "deterministic"`** (rule-based - default):
+
+**Decision rules** (based on `workflow.yaml` thresholds):
+
+1. **PASS** if ALL of the following are true:
+   - P0 coverage ≥ `min_p0_coverage` (default: 100%)
+   - P1 coverage ≥ `min_p1_coverage` (default: 90%)
+   - Overall coverage ≥ `min_overall_coverage` (default: 80%)
+   - P0 test pass rate = `min_p0_pass_rate` (default: 100%)
+   - P1 test pass rate ≥ `min_p1_pass_rate` (default: 95%)
+   - Overall test pass rate ≥ `min_overall_pass_rate` (default: 90%)
+   - Critical NFRs passed (if `nfr_file` provided)
+   - No unresolved security issues ≤ `max_security_issues` (default: 0)
+   - No test quality red flags (hard waits, no assertions)
+
+2. **CONCERNS** if ANY of the following are true:
+   - P1 coverage 80-89% (below threshold but not critical)
+   - P1 test pass rate 90-94% (below threshold but not critical)
+   - Overall pass rate 85-89%
+   - P2 coverage <50% (informational)
+   - Some non-critical NFRs failing
+   - Minor test quality concerns (large test files, inferred mappings)
+   - **Note**: CONCERNS does NOT block deployment but requires acknowledgment
+
+3. **FAIL** if ANY of the following are true:
+   - P0 coverage <100% (missing critical tests)
+   - P0 test pass rate <100% (failing critical tests)
+   - P1 coverage <80% (significant gap)
+   - P1 test pass rate <90% (significant failures)
+   - Overall coverage <80%
+   - Overall pass rate <85%
+   - Critical NFRs failing (`max_critical_nfrs_fail` exceeded)
+   - Unresolved security issues (`max_security_issues` exceeded)
+   - Major test quality issues (tests with no assertions, pervasive hard waits)
+
+4. **WAIVED** (only if `allow_waivers: true`):
+   - Decision would be FAIL based on rules above
+   - Business stakeholder has approved waiver
+   - Waiver documented with:
+     - Justification (time constraint, known limitation, acceptable risk)
+     - Approver name and date
+     - Mitigation plan (follow-up stories, manual testing)
+   - Waiver evidence linked (email, Slack thread, ticket)
+
+**Risk tolerance adjustments:**
+
+- If `allow_p2_failures: true` → P2 test failures do NOT affect gate decision
+- If `allow_p3_failures: true` → P3 test failures do NOT affect gate decision
+- If `escalate_p1_failures: true` → P1 failures require explicit manager/lead approval
+
+**If `decision_mode: "manual"`:**
+
+- Present evidence summary to team
+- Recommend decision based on rules above
+- Team makes final call in meeting/chat
+- Document decision with approver names
+
+**Output:** Gate decision (PASS/CONCERNS/FAIL/WAIVED) with rule-based rationale
+
+---
+
+### Step 9: Document Decision and Evidence
+
+**Actions:**
+
+1. **Create gate decision document**:
+   - Save to `gate_output_file` (default: `{output_folder}/gate-decision-{gate_type}-{story_id}.md`)
+   - Use structure below
+
+2. **Document structure**:
+
+```markdown
+# Quality Gate Decision: {gate_type} {story_id/epic_num/release_version}
+
+**Decision**: [PASS / CONCERNS / FAIL / WAIVED]
+**Date**: {date}
+**Decider**: {decision_mode} (deterministic | manual)
+**Evidence Date**: {test_results_date}
+
+---
+
+## Summary
+
+[1-2 sentence summary of decision and key factors]
+
+---
+
+## Decision Criteria
+
+| Criterion         | Threshold | Actual   | Status  |
+| ----------------- | --------- | -------- | ------- |
+| P0 Coverage       | ≥100%     | 100%     | ✅ PASS |
+| P1 Coverage       | ≥90%      | 88%      | ⚠️ FAIL |
+| Overall Coverage  | ≥80%      | 92%      | ✅ PASS |
+| P0 Pass Rate      | 100%      | 100%     | ✅ PASS |
+| P1 Pass Rate      | ≥95%      | 98%      | ✅ PASS |
+| Overall Pass Rate | ≥90%      | 96%      | ✅ PASS |
+| Critical NFRs     | All Pass  | All Pass | ✅ PASS |
+| Security Issues   | 0         | 0        | ✅ PASS |
+
+**Overall Status**: 7/8 criteria met → Decision: **CONCERNS**
+
+---
+
+## Evidence Summary
+
+### Test Coverage (from Phase 1 Traceability)
+
+- **P0 Coverage**: 100% (5/5 criteria fully covered)
+- **P1 Coverage**: 88% (7/8 criteria fully covered)
+- **Overall Coverage**: 92% (12/13 criteria covered)
+- **Gap**: AC-5 (P1) missing E2E test
+
+### Test Execution Results
+
+- **P0 Pass Rate**: 100% (12/12 tests passed)
+- **P1 Pass Rate**: 98% (45/46 tests passed)
+- **Overall Pass Rate**: 96% (67/70 tests passed)
+- **Failures**: 3 P2 tests (non-blocking)
+
+### Non-Functional Requirements
+
+- Performance: ✅ PASS (response time <500ms)
+- Security: ✅ PASS (no vulnerabilities)
+- Scalability: ✅ PASS (handles 10K users)
+
+### Test Quality
+
+- All tests have explicit assertions ✅
+- No hard waits detected ✅
+- Test files <300 lines ✅
+- Test IDs follow convention ✅
+
+---
+
+## Decision Rationale
+
+**Why CONCERNS (not PASS)**:
+
+- P1 coverage at 88% is below 90% threshold
+- AC-5 (P1 priority) missing E2E test for error handling scenario
+- This is a known gap from test-design phase
+
+**Why CONCERNS (not FAIL)**:
+
+- P0 coverage is 100% (critical paths validated)
+- Overall coverage is 92% (above 80% threshold)
+- Test pass rate is excellent (96% overall)
+- Gap is isolated to one P1 criterion (not systemic)
+
+**Recommendation**:
+
+- Acknowledge gap and proceed with deployment
+- Add missing AC-5 E2E test in next sprint
+- Create follow-up story: "Add E2E test for AC-5 error handling"
+
+---
+
+## Next Steps
+
+- [ ] Create follow-up story for AC-5 E2E test
+- [ ] Deploy to staging environment
+- [ ] Monitor production for edge cases related to AC-5
+- [ ] Update traceability matrix after follow-up test added
+
+---
+
+## References
+
+- Traceability Matrix: `{xiaoma_folder}/output/traceability-matrix.md`
+- Test Design: `{xiaoma_folder}/output/test-design-epic-2.md`
+- Test Results: `ci-artifacts/test-report-2025-01-15.xml`
+- NFR Assessment: `{xiaoma_folder}/output/nfr-assessment-release-1.2.md`
+```
+
+3. **Include evidence links** (if `require_evidence: true`):
+   - Link to traceability matrix
+   - Link to test execution reports (CI artifacts)
+   - Link to NFR assessment
+   - Link to test-design document
+   - Link to relevant PRs, commits, deployments
+
+4. **Waiver documentation** (if decision is WAIVED):
+   - Approver name and role (e.g., "Jane Doe, Engineering Manager")
+   - Approval date and method (e.g., "2025-01-15, Slack thread")
+   - Justification (e.g., "Time-boxed MVP, missing tests will be added in v1.1")
+   - Mitigation plan (e.g., "Manual testing by QA, follow-up stories created")
+   - Evidence link (e.g., "Slack: #engineering 2025-01-15 3:42pm")
+
+**Output:** Complete gate decision document with evidence and rationale
+
+---
+
+### Step 10: Update Status Tracking and Notify
+
+**Actions:**
+
+1. **Update workflow status** (if `append_to_history: true`):
+   - Append gate decision to `xmc-workflow-status.md` under "Gate History" section
+   - Format:
+
+     ```markdown
+     ## Gate History
+
+     ### Story 1.3 - User Login (2025-01-15)
+
+     - **Decision**: CONCERNS
+     - **Reason**: P1 coverage 88% (below 90%)
+     - **Document**: [gate-decision-story-1.3.md]({xiaoma_folder}/output/gate-decision-story-1.3.md)
+     - **Action**: Deploy with follow-up story for AC-5
+     ```
+
+2. **Generate stakeholder notification** (if `notify_stakeholders: true`):
+   - Create concise summary message for team communication
+   - Include: Decision, key metrics, action items
+   - Format for Slack/email/chat:
+
+   ```
+   🚦 Quality Gate Decision: Story 1.3 - User Login
+
+   Decision: ⚠️ CONCERNS
+   - P0 Coverage: ✅ 100%
+   - P1 Coverage: ⚠️ 88% (below 90%)
+   - Test Pass Rate: ✅ 96%
+
+   Action Required:
+   - Create follow-up story for AC-5 E2E test
+   - Deploy to staging for validation
+
+   Full Report: {xiaoma_folder}/output/gate-decision-story-1.3.md
+   ```
+
+3. **Request sign-off** (if `require_sign_off: true`):
+   - Prompt for named approver (tech lead, QA lead, PM)
+   - Document approver name and timestamp in gate decision
+   - Block until sign-off received (interactive prompt)
+
+**Output:** Status tracking updated, stakeholders notified, sign-off obtained (if required)
+
+**Workflow Complete**: Both Phase 1 (traceability) and Phase 2 (gate decision) deliverables generated.
+
+---
+
+## Decision Matrix (Quick Reference)
+
+| Scenario        | P0 Cov            | P1 Cov | Overall Cov | P0 Pass | P1 Pass | Overall Pass | NFRs | Decision     |
+| --------------- | ----------------- | ------ | ----------- | ------- | ------- | ------------ | ---- | ------------ |
+| All green       | 100%              | ≥90%   | ≥80%        | 100%    | ≥95%    | ≥90%         | Pass | **PASS**     |
+| Minor gap       | 100%              | 80-89% | ≥80%        | 100%    | 90-94%  | 85-89%       | Pass | **CONCERNS** |
+| Missing P0      | <100%             | -      | -           | -       | -       | -            | -    | **FAIL**     |
+| P0 test fail    | 100%              | -      | -           | <100%   | -       | -            | -    | **FAIL**     |
+| P1 gap          | 100%              | <80%   | -           | 100%    | -       | -            | -    | **FAIL**     |
+| NFR fail        | 100%              | ≥90%   | ≥80%        | 100%    | ≥95%    | ≥90%         | Fail | **FAIL**     |
+| Security issue  | -                 | -      | -           | -       | -       | -            | Yes  | **FAIL**     |
+| Business waiver | [FAIL conditions] | -      | -           | -       | -       | -            | -    | **WAIVED**   |
+
+---
+
+## Waiver Management
+
+**When to use waivers:**
+
+- Time-boxed MVP releases (known gaps, follow-up planned)
+- Low-risk P1 gaps with mitigation (manual testing, monitoring)
+- Technical debt acknowledged by product/engineering leadership
+- External dependencies blocking test automation
+
+**Waiver approval process:**
+
+1. Document gap and risk in gate decision
+2. Propose mitigation plan (manual testing, follow-up stories, monitoring)
+3. Request approval from stakeholder (EM, PM, QA lead)
+4. Link approval evidence (email, chat thread, meeting notes)
+5. Add waiver to gate decision document
+6. Create follow-up stories to close gaps
+
+**Waiver does NOT apply to:**
+
+- P0 gaps (always blocking)
+- Critical security issues (always blocking)
+- Critical NFR failures (performance, data integrity)
+
+---
+
+## Example Gate Decisions
+
+### Example 1: PASS (All Criteria Met)
+
+```
+Decision: ✅ PASS
+
+Summary: All quality criteria met. Story 1.3 is ready for production deployment.
+
+Evidence:
+- P0 Coverage: 100% (5/5 criteria)
+- P1 Coverage: 95% (19/20 criteria)
+- Overall Coverage: 92% (24/26 criteria)
+- P0 Pass Rate: 100% (12/12 tests)
+- P1 Pass Rate: 98% (45/46 tests)
+- Overall Pass Rate: 96% (67/70 tests)
+- NFRs: All pass (performance, security, scalability)
+
+Action: Deploy to production ✅
+```
+
+### Example 2: CONCERNS (Minor Gap, Non-Blocking)
+
+```
+Decision: ⚠️ CONCERNS
+
+Summary: P1 coverage slightly below threshold (88% vs 90%). Recommend deploying with follow-up story.
+
+Evidence:
+- P0 Coverage: 100% ✅
+- P1 Coverage: 88% ⚠️ (below 90%)
+- Overall Coverage: 92% ✅
+- Test Pass Rate: 96% ✅
+- Gap: AC-5 (P1) missing E2E test
+
+Action:
+- Deploy to staging for validation
+- Create follow-up story for AC-5 E2E test
+- Monitor production for edge cases related to AC-5
+```
+
+### Example 3: FAIL (P0 Gap, Blocking)
+
+```
+Decision: ❌ FAIL
+
+Summary: P0 coverage incomplete. Missing critical validation test. BLOCKING deployment.
+
+Evidence:
+- P0 Coverage: 80% ❌ (4/5 criteria, AC-2 missing)
+- AC-2: "User cannot login with invalid credentials" (P0 priority)
+- No tests validate login security for invalid credentials
+- This is a critical security gap
+
+Action:
+- Add P0 test for AC-2: 1.3-E2E-004 (invalid credentials)
+- Re-run traceability after test added
+- Re-evaluate gate decision after P0 coverage = 100%
+
+Deployment BLOCKED until P0 gap resolved ❌
+```
+
+### Example 4: WAIVED (Business Decision)
+
+```
+Decision: ⚠️ WAIVED
+
+Summary: P1 coverage below threshold (75% vs 90%), but waived for MVP launch.
+
+Evidence:
+- P0 Coverage: 100% ✅
+- P1 Coverage: 75% ❌ (below 90%)
+- Gap: 5 P1 criteria missing E2E tests (error handling, edge cases)
+
+Waiver:
+- Approver: Jane Doe, Engineering Manager
+- Date: 2025-01-15
+- Justification: Time-boxed MVP for investor demo. Core functionality (P0) fully validated. P1 gaps are low-risk edge cases.
+- Mitigation: Manual QA testing for P1 scenarios, follow-up stories created for automated tests in v1.1
+- Evidence: Slack #engineering 2025-01-15 3:42pm
+
+Action:
+- Deploy to production with manual QA validation ✅
+- Add 5 E2E tests for P1 gaps in v1.1 sprint
+- Monitor production logs for edge case occurrences
+```
+
+---
+
+## Non-Prescriptive Approach
+
+**Minimal Examples:** This workflow provides principles and patterns, not rigid templates. Teams should adapt the traceability and gate decision formats to their needs.
+
+**Key Patterns to Follow:**
+
+- Map criteria to tests explicitly (don't rely on inference alone)
+- Prioritize by risk (P0 gaps are critical, P3 gaps are acceptable)
+- Check coverage at appropriate levels (E2E for journeys, Unit for logic)
+- Verify test quality (explicit assertions, no flakiness)
+- Apply deterministic gate rules for consistency
+- Document gate decisions with clear evidence
+- Use waivers judiciously (business approved, mitigation planned)
+
+**Extend as Needed:**
+
+- Add custom coverage classifications
+- Integrate with code coverage tools (Istanbul, NYC)
+- Link to external traceability systems (JIRA, Azure DevOps)
+- Add compliance or regulatory requirements
+- Customize gate decision thresholds per project
+- Add manual approval workflows for gate decisions
+
+---
+
+## Coverage Classification Details
+
+### FULL Coverage
+
+- All scenarios validated at appropriate test level(s)
+- Edge cases considered
+- Both happy path and error paths tested
+- Assertions are explicit and complete
+
+### PARTIAL Coverage
+
+- Some scenarios validated but missing edge cases
+- Only happy path tested (missing error paths)
+- Assertions present but incomplete
+- Coverage exists but needs enhancement
+
+### NONE Coverage
+
+- No tests found for this criterion
+- Complete gap requiring new tests
+- Critical if P0/P1, acceptable if P3
+
+### UNIT-ONLY Coverage
+
+- Only unit tests exist (business logic validated)
+- Missing integration or E2E validation
+- Risk: Implementation may not work end-to-end
+- Recommendation: Add integration or E2E tests for critical paths
+
+### INTEGRATION-ONLY Coverage
+
+- Only API or Component tests exist
+- Missing unit test confidence for business logic
+- Risk: Logic errors may not be caught quickly
+- Recommendation: Add unit tests for complex algorithms or state machines
+
+---
+
+## Duplicate Coverage Detection
+
+Use selective testing principles from `selective-testing.md`:
+
+**Acceptable Overlap:**
+
+- Unit tests for business logic + E2E tests for user journey (different aspects)
+- API tests for contract + E2E tests for full workflow (defense in depth for critical paths)
+
+**Unacceptable Duplication:**
+
+- Same validation at multiple levels (e.g., E2E testing math logic better suited for unit tests)
+- Multiple E2E tests covering identical user path
+- Component tests duplicating unit test logic
+
+**Recommendation Pattern:**
+
+- Test logic at unit level
+- Test integration at API/Component level
+- Test user experience at E2E level
+- Avoid testing framework behavior at any level
+
+---
+
+## Integration with XiaoMa Artifacts
+
+### With test-design.md
+
+- Use risk assessment to prioritize gap remediation
+- Reference test priorities (P0/P1/P2/P3) for severity classification and gate decision
+- Align traceability with originally planned test coverage
+
+### With tech-spec.md
+
+- Understand technical implementation details
+- Map criteria to specific code modules
+- Verify tests cover technical edge cases
+
+### With PRD.md
+
+- Understand full product context
+- Verify acceptance criteria align with product goals
+- Check for unstated requirements that need coverage
+
+### With nfr-assessment.md
+
+- Load non-functional validation results for gate decision
+- Check critical NFR status (performance, security, scalability)
+- Include NFR pass/fail in gate decision criteria
+
+---
+
+## Quality Gates (Phase 1 Recommendations)
+
+### P0 Coverage (Critical Paths)
+
+- **Requirement:** 100% FULL coverage
+- **Severity:** BLOCKER if not met
+- **Action:** Do not release until P0 coverage is complete
+
+### P1 Coverage (High Priority)
+
+- **Requirement:** 90% FULL coverage
+- **Severity:** HIGH if not met
+- **Action:** Block PR merge until addressed
+
+### P2 Coverage (Medium Priority)
+
+- **Requirement:** No strict requirement (recommended 80%)
+- **Severity:** MEDIUM if gaps exist
+- **Action:** Address in nightly test improvements
+
+### P3 Coverage (Low Priority)
+
+- **Requirement:** No requirement
+- **Severity:** LOW if gaps exist
+- **Action:** Optional - add if time permits
+
+---
+
+## Example Traceability Matrix
+
+````markdown
+# Traceability Matrix - Story 1.3
+
+**Story:** User Authentication
+**Date:** 2025-10-14
+**Status:** 85% Coverage (1 HIGH gap)
+
+## Coverage Summary
+
+| Priority  | Total Criteria | FULL Coverage | Coverage % | Status  |
+| --------- | -------------- | ------------- | ---------- | ------- |
+| P0        | 3              | 3             | 100%       | ✅ PASS |
+| P1        | 5              | 4             | 80%        | ⚠️ WARN |
+| P2        | 4              | 3             | 75%        | ✅ PASS |
+| P3        | 2              | 1             | 50%        | ✅ PASS |
+| **Total** | **14**         | **11**        | **79%**    | ⚠️ WARN |
+
+## Detailed Mapping
+
+### AC-1: User can login with email and password (P0)
+
+- **Coverage:** FULL ✅
+- **Tests:**
+  - `1.3-E2E-001` - tests/e2e/auth.spec.ts:12
+    - Given: User has valid credentials
+    - When: User submits login form
+    - Then: User is redirected to dashboard
+  - `1.3-UNIT-001` - tests/unit/auth-service.spec.ts:8
+    - Given: Valid email and password hash
+    - When: validateCredentials is called
+    - Then: Returns user object
+
+### AC-2: User sees error for invalid credentials (P0)
+
+- **Coverage:** FULL ✅
+- **Tests:**
+  - `1.3-E2E-002` - tests/e2e/auth.spec.ts:28
+    - Given: User has invalid password
+    - When: User submits login form
+    - Then: Error message is displayed
+  - `1.3-UNIT-002` - tests/unit/auth-service.spec.ts:18
+    - Given: Invalid password hash
+    - When: validateCredentials is called
+    - Then: Throws AuthenticationError
+
+### AC-3: User can reset password via email (P1)
+
+- **Coverage:** PARTIAL ⚠️
+- **Tests:**
+  - `1.3-E2E-003` - tests/e2e/auth.spec.ts:44
+    - Given: User requests password reset
+    - When: User clicks reset link
+    - Then: User can set new password
+- **Gaps:**
+  - Missing: Email delivery validation
+  - Missing: Expired token handling
+  - Missing: Unit test for token generation
+- **Recommendation:** Add `1.3-API-001` for email service integration and `1.3-UNIT-003` for token logic
+
+## Gap Analysis
+
+### Critical Gaps (BLOCKER)
+
+- None ✅
+
+### High Priority Gaps (PR BLOCKER)
+
+1. **AC-3: Password reset email edge cases**
+   - Missing tests for expired tokens, invalid tokens, email failures
+   - Recommend: `1.3-API-001` (email service integration) and `1.3-E2E-004` (error paths)
+   - Impact: Users may not be able to recover accounts in error scenarios
+
+### Medium Priority Gaps (Nightly)
+
+1. **AC-7: Session timeout handling** - UNIT-ONLY coverage (missing E2E validation)
+
+## Quality Assessment
+
+### Tests with Issues
+
+- `1.3-E2E-001` ⚠️ - 145 seconds (exceeds 90s target) - Optimize fixture setup
+- `1.3-UNIT-005` ⚠️ - 320 lines (exceeds 300 line limit) - Split into multiple test files
+
+### Tests Passing Quality Gates
+
+- 11/13 tests (85%) meet all quality criteria ✅
+
+## Gate YAML Snippet
+
+```yaml
+traceability:
+  story_id: '1.3'
+  coverage:
+    overall: 79%
+    p0: 100%
+    p1: 80%
+    p2: 75%
+    p3: 50%
+  gaps:
+    critical: 0
+    high: 1
+    medium: 1
+    low: 1
+  status: 'WARN' # P1 coverage below 90% threshold
+  recommendations:
+    - 'Add 1.3-API-001 for email service integration'
+    - 'Add 1.3-E2E-004 for password reset error paths'
+    - 'Optimize 1.3-E2E-001 performance (145s → <90s)'
+```
+````
+
+## Recommendations
+
+1. **Address High Priority Gap:** Add password reset edge case tests before PR merge
+2. **Optimize Slow Test:** Refactor `1.3-E2E-001` to use faster fixture setup
+3. **Split Large Test:** Break `1.3-UNIT-005` into focused test files
+4. **Enhance P2 Coverage:** Add E2E validation for session timeout (currently UNIT-ONLY)
+
+```
+
+---
+
+## Validation Checklist
+
+Before completing this workflow, verify:
+
+**Phase 1 (Traceability):**
+- ✅ All acceptance criteria are mapped to tests (or gaps are documented)
+- ✅ Coverage status is classified (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY)
+- ✅ Gaps are prioritized by risk level (P0/P1/P2/P3)
+- ✅ P0 coverage is 100% or blockers are documented
+- ✅ Duplicate coverage is identified and flagged
+- ✅ Test quality is assessed (assertions, structure, performance)
+- ✅ Traceability matrix is generated and saved
+
+**Phase 2 (Gate Decision - if enabled):**
+- ✅ Test execution results loaded and pass rates calculated
+- ✅ NFR assessment results loaded (if applicable)
+- ✅ Decision rules applied consistently (PASS/CONCERNS/FAIL/WAIVED)
+- ✅ Gate decision document created with evidence
+- ✅ Waiver documented if decision is WAIVED (approver, justification, mitigation)
+- ✅ Workflow status updated (xmc-workflow-status.md)
+- ✅ Stakeholders notified (if enabled)
+
+---
+
+## Notes
+
+**Phase 1 (Traceability):**
+- **Explicit Mapping:** Require tests to reference criteria explicitly (test IDs, describe blocks) for maintainability
+- **Risk-Based Prioritization:** Use test-priorities framework (P0/P1/P2/P3) to determine gap severity
+- **Quality Over Quantity:** Better to have fewer high-quality tests with FULL coverage than many low-quality tests with PARTIAL coverage
+- **Selective Testing:** Avoid duplicate coverage - test each behavior at the appropriate level only
+
+**Phase 2 (Gate Decision):**
+- **Deterministic Rules:** Use consistent thresholds (P0=100%, P1≥90%, overall≥80%) for objectivity
+- **Evidence-Based:** Every decision must cite specific metrics (coverage %, pass rates, NFRs)
+- **Waiver Discipline:** Waivers require approver name, justification, mitigation plan, and evidence link
+- **Non-Blocking CONCERNS:** Use CONCERNS for minor gaps that don't justify blocking deployment (e.g., P1 at 88% vs 90%)
+- **Automate in CI/CD:** Generate YAML snippets that can be consumed by CI/CD pipelines for automated quality gates
+
+---
+
+## Troubleshooting
+
+### "No tests found for this story"
+- Run `*atdd` workflow first to generate failing acceptance tests
+- Check test file naming conventions (may not match story ID pattern)
+- Verify test directory path is correct
+
+### "Cannot determine coverage status"
+- Tests may lack explicit mapping to criteria (no test IDs, unclear describe blocks)
+- Review test structure and add Given-When-Then narrative
+- Add test IDs in format: `{STORY_ID}-{LEVEL}-{SEQ}` (e.g., 1.3-E2E-001)
+
+### "P0 coverage below 100%"
+- This is a **BLOCKER** - do not release
+- Identify missing P0 tests in gap analysis
+- Run `*atdd` workflow to generate missing tests
+- Verify with stakeholders that P0 classification is correct
+
+### "Duplicate coverage detected"
+- Review selective testing principles in `selective-testing.md`
+- Determine if overlap is acceptable (defense in depth) or wasteful (same validation at multiple levels)
+- Consolidate tests at appropriate level (logic → unit, integration → API, journey → E2E)
+
+### "Test execution results missing" (Phase 2)
+- Phase 2 gate decision requires `test_results` (CI/CD test reports)
+- If missing, Phase 2 will be skipped with warning
+- Provide JUnit XML, TAP, or JSON test report path via `test_results` variable
+
+### "Gate decision is FAIL but deployment needed urgently"
+- Request business waiver (if `allow_waivers: true`)
+- Document approver, justification, mitigation plan
+- Create follow-up stories to address gaps
+- Use WAIVED decision only for non-P0 gaps
+
+---
+
+## Related Workflows
+
+**Prerequisites:**
+- `testarch-test-design` - Define test priorities (P0/P1/P2/P3) before tracing (required for Phase 2)
+- `testarch-atdd` or `testarch-automate` - Generate tests before tracing coverage
+
+**Complements:**
+- `testarch-nfr-assess` - Non-functional requirements validation (recommended for release gates)
+- `testarch-test-review` - Review test quality issues flagged in traceability
+
+**Next Steps:**
+- If gate decision is PASS/CONCERNS → Deploy and monitor
+- If gate decision is FAIL → Add missing tests, re-run trace workflow
+- If gate decision is WAIVED → Deploy with mitigation, create follow-up stories
+
+---
+
+<!-- Powered by XIAOMA-CORE™ -->
+```