pi-maestro-flow 0.2.0 → 0.3.0

package/workflows/business-test.md

@@ -0,0 +1,574 @@
+# Business Test Workflow (PRD-Forward)
+
+Validate built features against PRD acceptance criteria through automated multi-layer business testing with requirement traceability, fixture generation, and feedback loop.
+
+PRD-forward: starts from REQ-*.md acceptance criteria, not from code coverage gaps.
+Progressive layers: L1 Interface Contract -> L2 Business Rule -> L3 Business Scenario (E2E).
+Generator-Critic loop: max 3 iterations per layer to distinguish test defects from code defects.
+
+**Philosophy: Business rules are the source of truth. Code must satisfy them, not the other way around.**
+
+---
+
+### Step 1: Resolve Target & Load Spec Package
+
+**Parse arguments:**
+
+| Input | Result |
+|-------|--------|
+| No arguments | Error E001 |
+| Phase number | Resolve `.workflow/phases/{NN}-{slug}/` |
+| `--spec SPEC-xxx` | Explicit spec reference |
+| `--layer L1\|L2\|L3` | Run only specific layer |
+| `--gen-code` | Generate framework-specific test classes |
+| `--dry-run` | Extract scenarios only, don't execute |
+| `--re-run` | Re-run only previously failed scenarios |
+| `--auto` | Skip interactive confirmations |
+
+**Load spec package:**
+
+```
+1. Read ${PHASE_DIR}/index.json -> extract blueprint_ref (if present)
+2. IF --spec provided: SPEC_DIR = .workflow/blueprint/{blueprint_ref}/
+   ELSE IF index.json.blueprint_ref: SPEC_DIR = .workflow/blueprint/{blueprint_ref}/
+   ELSE: try .workflow/blueprint/SPEC-*/ (most recent)
+
+3. IF SPEC_DIR found:
+   - Read requirements/_index.md (requirement summary + traceability matrix)
+   - Read all requirements/REQ-*.md (functional requirements with acceptance criteria)
+   - Read all requirements/NFR-*.md (non-functional requirements)
+   - Read architecture/_index.md (API endpoints, data model, state machines)
+   - Read epics/EPIC-*.md (user stories -> E2E scenario source)
+   SPEC_MODE = "full"
+
+4. IF no spec package found (DEGRADED MODE):
+   - Read index.json.success_criteria
+   - Read plan.json tasks with convergence.criteria
+   - Read .summaries/TASK-*-summary.md for implemented behavior
+   SPEC_MODE = "degraded"
+   Display: "No spec package found. Using success_criteria + plan.json for scenario extraction (degraded mode)."
+```
+
+Check for existing business test session:
+```bash
+ls ${PHASE_DIR}/.tests/business/business-test-report.json 2>/dev/null
+```
+
+If session exists AND `--re-run`: load previous report, filter to failed/blocked scenarios only.
+If session exists AND no `--re-run`: offer resume or restart.
+
+---
+
+### Step 2: Extract Business Test Scenarios from PRD
+
+**Full mode (SPEC_MODE = "full"):**
+
+For each `REQ-NNN-{slug}.md`:
+
+1. Parse `## Acceptance Criteria` section
+2. Extract each numbered criterion as a test scenario seed
+3. Map RFC 2119 keywords to test priority:
+
+| Keyword | Priority | Failure Severity |
+|---------|----------|-----------------|
+| MUST / MUST NOT / SHALL / SHALL NOT | critical | blocker |
+| SHOULD / SHOULD NOT / RECOMMENDED | high | major |
+| MAY / OPTIONAL | medium | minor |
+
+4. Classify scenario into layer:
+
+| Source | Layer | Category |
+|--------|-------|----------|
+| Architecture API endpoints + REQ AC about request/response | L1 | api_contract |
+| REQ AC about business logic, validation, state changes | L2 | business_rule |
+| REQ AC about state transitions (from architecture state machines) | L2 | state_transition |
+| Epic user stories (multi-step flows) | L3 | user_flow |
+| NFR performance/security constraints | L2 | non_functional |
+
+5. Generate scenario:
+```json
+{
+  "id": "BT-{NNN}",
+  "req_ref": "REQ-{NNN}:AC-{N}",
+  "layer": "L1|L2|L3",
+  "priority": "critical|high|medium",
+  "name": "descriptive name derived from AC text",
+  "category": "api_contract|business_rule|state_transition|user_flow|non_functional",
+  "endpoint": "METHOD /path (if L1)",
+  "input": { "$fixture_ref": "REQ-{NNN}/valid|invalid|boundary/name" },
+  "expected": {
+    "status": 200,
+    "body_contains": [],
+    "behavior": "description of expected outcome"
+  },
+  "preconditions": ["list of required state"],
+  "postconditions": ["list of expected state changes"],
+  "mock_services": ["list of services to mock for isolation"]
+}
+```
+
+**Degraded mode (SPEC_MODE = "degraded"):**
+
+- Extract scenarios from `index.json.success_criteria` (each criterion -> one L2 scenario)
+- Extract from `plan.json` task convergence criteria (each criterion -> one L1 or L2 scenario)
+- Extract from summaries (each implemented behavior -> one L1 scenario)
+- All scenarios default to priority: "high"
+- No L3 scenarios in degraded mode (no Epic stories available)
+
+---
+
+### Step 3: Generate Test Data (Fixtures)
+
+For each REQ with data model definitions:
+
+**Tier 1: Schema-derived fixtures**
+```
+FOR each entity in REQ data model:
+  valid: object satisfying all field constraints
+  invalid: one variant per constraint violation:
+    - null_required: set required field to null
+    - empty_string: set string field to ""
+    - overflow: exceed max length or max value
+    - wrong_type: provide string where number expected, etc.
+  boundary: edge value variants:
+    - min_value: exact minimum
+    - max_value: exact maximum
+    - min_minus_one: minimum - 1
+    - max_plus_one: maximum + 1
+```
+
+**Tier 2: Acceptance-criteria-derived expectations**
+```
+FOR each "MUST return X when Y" in acceptance criteria:
+  fixture: { input: Y, expected: X }
+FOR each "MUST validate Z":
+  fixture: { input: invalid_Z, expected: validation_error }
+FOR each "SHOULD support W":
+  fixture: { input: W_params, expected: W_result }
+```
+
+**Tier 3: Business-scenario-derived data sets (L3 only)**
+```
+FOR each Epic user story:
+  scenario_pack: coordinated data set across story steps
+  Example: { user: registered_user, order: valid_order, payment: valid_card }
+  Entity IDs and relationships pre-coordinated across steps
+```
+
+**Microservice mock data:**
+```
+FOR each API endpoint in architecture/_index.md:
+  mock_contract: { request_pattern, response_fixture }
+  Used for: L2 WireMock stubs, L3 service isolation
+```
+
+Organize fixtures by REQ:
+```json
+{
+  "REQ-001": {
+    "valid": [{ "name": "standard_user", "data": {...} }],
+    "invalid": [{ "name": "missing_email", "data": {...}, "expected_error": "email is required" }],
+    "boundary": [{ "name": "max_length_name", "data": {...} }]
+  }
+}
+```
+
+---
+
+### Step 4: Write Test Plan & Confirm
+
+**Archive previous business test artifacts** before writing:
+```
+IF file exists "${PHASE_DIR}/.tests/business/business-test-plan.json":
+  mkdir -p "${PHASE_DIR}/.history"
+  TIMESTAMP = format(now(), "YYYY-MM-DDTHH-mm-ss")
+  mv "${PHASE_DIR}/.tests/business/business-test-plan.json" "${PHASE_DIR}/.history/business-test-plan-${TIMESTAMP}.json"
+```
+
+Write `business-test-plan.json` to `.tests/business/`:
+```json
+{
+  "phase": "{phase}",
+  "blueprint_ref": "{SPEC_DIR name or 'degraded'}",
+  "spec_mode": "full|degraded",
+  "generated_at": "{ISO timestamp}",
+  "layers": {
+    "L1": { "scenario_count": N, "priority_distribution": { "critical": X, "high": Y, "medium": Z } },
+    "L2": { "scenario_count": N, "priority_distribution": {...} },
+    "L3": { "scenario_count": N, "priority_distribution": {...} }
+  },
+  "scenarios": [ ... ],
+  "fixtures": { ... },
+  "mock_contracts": [ ... ],
+  "requirement_coverage_plan": {
+    "requirements_targeted": ["REQ-001", "REQ-002"],
+    "requirements_skipped": [],
+    "skip_reasons": {}
+  }
+}
+```
+
+**If not `--auto`:**
+
+Display plan summary:
+```
+=== BUSINESS TEST PLAN ===
+Spec mode:   {full|degraded}
+Requirements: {N} targeted, {M} skipped
+
+Layer Distribution:
+  L1 Interface:  {N} scenarios ({X} critical, {Y} high)
+  L2 Business:   {N} scenarios ({X} critical, {Y} high)
+  L3 E2E:        {N} scenarios ({X} critical, {Y} high)
+
+Fixtures: {N} REQs × {avg} variants = {total} data sets
+
+Proceed? (yes/edit/cancel)
+```
+
+Wait for user confirmation. If "edit": let user modify plan interactively.
+
+**If `--dry-run`:** Stop here, report plan.
+
+---
+
+**GATE Step 4→5**: REQUIRED `business-test-plan.json` written and user-confirmed before test generation; BLOCKED if plan missing or unconfirmed.
+
+### Step 5: Generate Test Code (if --gen-code)
+
+**Detect project tech stack:**
+```
+IF file exists ".workflow/project.md":
+  tech = parse Tech Stack section from project.md
+ELSE:
+  Scan project for indicators (pom.xml -> Java, package.json -> Node, etc.)
+```
+
+**Generate framework-specific test classes:**
+
+| Stack | L1 | L2 | L3 |
+|-------|----|----|-----|
+| Java/Spring Boot | RestAssured + MockMvc | JUnit 5 Parameterized + WireMock | TestContainers |
+| TypeScript/Node | supertest + vitest | vitest + nock | playwright/cypress |
+| Python | httpx + pytest | pytest + responses | pytest + selenium |
+
+**Generation rules:**
+- Follow existing test patterns (discover from codebase, same as test-gen Step 1)
+- Each test method has `@DisplayName` (or equivalent) with REQ-NNN:AC-N reference
+- Each test class has layer marker (`@Tag("business-L1")` or equivalent)
+- Test files placed in `.tests/business/{layer}/` directory
+
+**If no `--gen-code`:** Scenarios remain as structured JSON for AI agent execution mode (Step 6).
+
+---
+
+### Step 6: Execute Tests (Progressive L1 -> L2 -> L3)
+
+**Fail-fast rule:**
+- If L1 has ANY "critical" priority failure -> STOP. Do not proceed to L2.
+- If L2 has ANY "critical" priority failure -> STOP. Do not proceed to L3.
+- "high" and "medium" failures do NOT block next layer.
+
+**For each layer (starting from `--layer` if specified, else L1):**
+
+Run Generator-Critic loop (max 3 iterations):
+
+**Iteration 1: Execute all scenarios**
+
+`--gen-code` mode:
+```bash
+# Run generated test classes for current layer
+{test_command} --testPathPattern="business-{layer}" 2>&1 | tail -50
+```
+
+Agent execution mode:
+```
+FOR each scenario in current layer:
+  Execute scenario against running application
+  Record: { status, actual_response, duration_ms, error_detail }
+```
+
+**Critic phase: Classify failures**
+
+For each failed scenario:
+```
+Analyze failure evidence -> classify as:
+
+| Classification | Meaning | Action |
+|---------------|---------|--------|
+| test_defect | Test itself is wrong (wrong endpoint, bad fixture) | Auto-fix test in next iteration |
+| code_defect | Business rule violated (actual != expected per REQ) | Record as failure |
+| env_issue | Service down, config missing, timeout | Record as blocked |
+```
+
+**Iteration 2: Re-run with fixed tests**
+- Fix test_defects from iteration 1
+- Re-run ALL scenarios (not just failed ones — catch regressions)
+
+**Iteration 3: Final confirmation**
+- Remaining failures = confirmed code_defects
+- All test_defects should be resolved
+- Blocked scenarios marked with env_issue reason
+
+Record results per iteration in `.tests/business/test-results-iter-{N}.json`.
+
+---
+
+### Step 7: Build Traceability Matrix
+
+Map each scenario result back to requirement:
+
+```
+FOR each REQ in requirements targeted:
+  req_results = {
+    req_id: "REQ-NNN",
+    title: REQ.title,
+    total_criteria: count of AC in REQ,
+    criteria_results: []
+  }
+
+  FOR each AC in REQ:
+    scenarios_for_ac = filter scenarios where req_ref == "REQ-NNN:AC-{N}"
+    ac_status = "passed" if ALL scenarios passed
+                "failed" if ANY scenario failed
+                "blocked" if ANY blocked and none failed
+                "untested" if no scenarios mapped
+
+    req_results.criteria_results.push({
+      ac_id: "AC-{N}",
+      description: AC text,
+      priority: mapped from RFC 2119 keyword,
+      status: ac_status,
+      tests: [scenario IDs],
+      failure: { expected, actual, evidence } if failed
+    })
+
+  req_results.coverage_pct = passed_criteria / total_criteria * 100
+  req_results.verdict = "verified" if all MUST+SHOULD passed
+                        "partial" if some failed
+                        "unverified" if all failed or untested
+```
+
+---
+
+### Step 8: Generate Reports
+
+**Archive previous reports:**
+```
+IF file exists "${PHASE_DIR}/.tests/business/business-test-report.json":
+  mkdir -p "${PHASE_DIR}/.history"
+  TIMESTAMP = format(now(), "YYYY-MM-DDTHH-mm-ss")
+  mv report and summary to .history/
+```
+
+Write `.tests/business/business-test-report.json`:
+```json
+{
+  "phase": "{phase}",
+  "blueprint_ref": "{spec reference}",
+  "spec_mode": "full|degraded",
+  "completed_at": "{ISO timestamp}",
+  "execution_mode": "gen-code|agent",
+  "iterations": {
+    "L1": { "count": N, "converged": true },
+    "L2": { "count": N, "converged": true },
+    "L3": { "count": N, "converged": false }
+  },
+  "layers": {
+    "L1": { "total": N, "passed": P, "failed": F, "blocked": B, "pass_rate": 95.0 },
+    "L2": { "total": N, "passed": P, "failed": F, "blocked": B, "pass_rate": 87.5 },
+    "L3": { "total": N, "passed": P, "failed": F, "blocked": B, "pass_rate": 100.0 }
+  },
+  "requirement_coverage": [
+    {
+      "req_id": "REQ-001",
+      "title": "...",
+      "total_criteria": 5,
+      "criteria_results": [
+        {
+          "ac_id": "AC-1",
+          "description": "...",
+          "priority": "critical",
+          "status": "passed|failed|blocked|untested",
+          "tests": ["BT-001", "BT-002"],
+          "failure": null
+        }
+      ],
+      "coverage_pct": 80.0,
+      "verdict": "verified|partial|unverified"
+    }
+  ],
+  "failures": [
+    {
+      "id": "BF-001",
+      "test_id": "BT-005",
+      "req_ref": "REQ-001:AC-3",
+      "layer": "L1",
+      "severity": "critical",
+      "classification": "code_defect",
+      "description": "...",
+      "expected": "...",
+      "actual": "...",
+      "fix_suggestion": {
+        "file": "src/...",
+        "line": 42,
+        "direction": "Add null guard for..."
+      }
+    }
+  ],
+  "summary": {
+    "total_requirements": 10,
+    "fully_verified": 8,
+    "partially_verified": 1,
+    "unverified": 1,
+    "coverage_pct": 85.0,
+    "total_scenarios": 30,
+    "total_passed": 26,
+    "total_failed": 3,
+    "total_blocked": 1
+  }
+}
+```
+
+Write `.tests/business/business-test-summary.md`:
+```markdown
+---
+phase: {phase}
+blueprint_ref: {spec reference}
+completed_at: {ISO timestamp}
+verdict: passed|gaps_found
+---
+
+# Business Test Results
+
+## Requirement Coverage
+
+| REQ | Title | AC Total | Passed | Failed | Coverage | Verdict |
+|-----|-------|----------|--------|--------|----------|---------|
+| REQ-001 | ... | 5 | 4 | 1 | 80% | partial |
+| REQ-002 | ... | 3 | 3 | 0 | 100% | verified |
+
+## Layer Results
+
+| Layer | Total | Passed | Failed | Blocked | Pass Rate |
+|-------|-------|--------|--------|---------|-----------|
+| L1 Interface | 10 | 9 | 1 | 0 | 90.0% |
+| L2 Business | 15 | 13 | 1 | 1 | 86.7% |
+| L3 E2E | 5 | 5 | 0 | 0 | 100.0% |
+
+## Failures
+
+### BF-001: REQ-001:AC-3 (critical)
+- Layer: L1
+- Expected: 201 Created with user object
+- Actual: 400 Bad Request
+- Fix: Add email validation bypass for internal accounts (src/auth.ts:42)
+
+## Next Steps
+{routing suggestion}
+```
+
+Update `index.json` with business_test section:
+```json
+{
+  "business_test": {
+    "status": "passed|gaps_found",
+    "spec_mode": "full|degraded",
+    "req_coverage_pct": 85.0,
+    "layers": {
+      "L1": { "pass_rate": 90.0 },
+      "L2": { "pass_rate": 86.7 },
+      "L3": { "pass_rate": 100.0 }
+    },
+    "failures": [
+      { "id": "BF-001", "req_ref": "REQ-001:AC-3", "severity": "critical" }
+    ]
+  }
+}
+```
+
+---
+
+**GATE Step 8→9**: Glob `${PHASE_DIR}/.tests/business/business-test-report.json` MUST exist before Step 9 issue creation; BLOCKED if missing.
+
+### Step 9: Feedback Loop
+
+**Auto-create issues from failures:**
+```
+FOR each failure in report.failures:
+  mkdir -p ".workflow/issues"
+
+  today = format(now(), "YYYYMMDD")
+  counter = next available sequence for today
+
+  issue = {
+    id: "ISS-{today}-{counter:03d}",
+    title: "Business Test: " + failure.req_ref + " - " + failure.description (truncated 100 chars),
+    status: "registered",
+    priority: severity_to_priority(failure.severity),
+    severity: failure.severity,
+    source: "business-test",
+    phase_ref: PHASE_NUM,
+    gap_ref: failure.id,
+    description: "Business test failed for " + failure.req_ref + ". Expected: " + failure.expected + ". Actual: " + failure.actual,
+    fix_direction: failure.fix_suggestion.direction,
+    context: {
+      location: failure.fix_suggestion.file + ":" + failure.fix_suggestion.line,
+      suggested_fix: failure.fix_suggestion.direction,
+      notes: "req_ref: " + failure.req_ref + ", layer: " + failure.layer
+    },
+    tags: ["business-test", failure.layer],
+    affected_components: [failure.fix_suggestion.file],
+    feedback: [],
+    issue_history: [],
+    created_at: now(),
+    updated_at: now(),
+    resolved_at: null,
+    resolution: null
+  }
+  Append JSON line to .workflow/issues/issues.jsonl
+```
+
+**Report:**
+```
+=== BUSINESS TEST RESULTS ===
+Phase:       {phase_name}
+Spec mode:   {full|degraded}
+
+Requirement Coverage: {coverage_pct}%
+  Verified:    {fully_verified}/{total_requirements}
+  Partial:     {partially_verified}
+  Unverified:  {unverified}
+
+Layer Results:
+  L1 Interface:  {pass_rate}% ({passed}/{total})
+  L2 Business:   {pass_rate}% ({passed}/{total})
+  L3 E2E:        {pass_rate}% ({passed}/{total})
+
+Failures: {failure_count} ({blocker_count} blockers)
+Issues:   {issue_count} auto-created
+
+Files:
+  {PHASE_DIR}/.tests/business/business-test-plan.json
+  {PHASE_DIR}/.tests/business/business-test-report.json
+  {PHASE_DIR}/.tests/business/business-test-summary.md
+
+Next steps:
+  {suggested_next_command}
+```
+
+**Next step routing:**
+
+| Result | Suggestion |
+|--------|------------|
+| All requirements verified | Skill({ skill: "maestro-phase-transition", args: "{phase}" }) |
+| Failures found | Skill({ skill: "quality-debug", args: "--from-business-test {phase}" }) |
+| `--re-run` all pass after fix | Skill({ skill: "maestro-execute", args: "{phase}" }) |
+| Low coverage (< 60%) | Skill({ skill: "quality-auto-test", args: "{phase}" }) |
+| Need integration tests | Skill({ skill: "quality-auto-test", args: "{phase}" }) |
+
+**Closure criteria:**
+A requirement is marked "verified" ONLY when:
+- ALL acceptance criteria with MUST/SHALL keywords: passed
+- ALL acceptance criteria with SHOULD keywords: passed
+- No blocker-severity failures remain for this requirement

package/workflows/chinese-response.md

@@ -0,0 +1,25 @@
+# 中文回复准则
+
+## 核心原则
+
+- 所有回复使用简体中文
+- 技术术语保留英文，首次出现可添加中文解释
+- 代码变量名保持英文，注释使用中文
+
+## 格式规范
+
+- 中英文/数字间加空格：`使用 TypeScript 开发`、`共 3 个文件`
+- 使用中文标点：，。！？：；
+- 代码/命令用反引号：`npm install`
+
+## Git Commit
+
+- 使用中文提交信息
+- 格式：`类型: 简短描述`
+- 类型：feat/fix/refactor/docs/test/chore
+
+## 保持英文
+
+- 代码文件内容
+- 错误信息和日志
+- 文件路径和命令