valent-pipeline 0.2.20 → 0.2.21

package/pipeline/steps/mobile/react-native.md

@@ -0,0 +1,32 @@
+# MOBILE Step: React Native Specifics
+
+This step is loaded conditionally when `{tech_stack.mobile_framework}` is `react-native`. Read before implementing.
+
+## Metro Bundler Management
+- Start Metro before any test execution: `npx react-native start --reset-cache &`
+- Monitor Metro for JS bundle errors. If bundling fails, fix the code and retry.
+- Handle port conflicts: check if port 8081 is in use before starting (`lsof -i :8081` on Mac/Linux, `netstat -ano | findstr 8081` on Windows). Kill stale Metro processes if needed.
+- Kill Metro after all tests complete.
+
+## React Native Build Configuration
+- Use `react-native.config.js` for native module auto-linking
+- Hermes engine: verify Hermes is enabled for Android (check `android/app/build.gradle` for `enableHermes: true`)
+- Flipper: disable in release builds, optional in debug
+- Fast Refresh: disable during E2E to avoid test flakiness (`--no-interactive` flag)
+
+## React Native Testing Patterns
+- Component tests: use React Native Testing Library (`@testing-library/react-native`)
+- Navigation tests: verify deep link resolution via React Navigation linking config, verify screen transitions
+- Platform-specific code: test `.android.tsx` and `.ios.tsx` variants separately when they exist
+- AsyncStorage / MMKV: clear between test suites to prevent state leakage
+
+## Native Module Considerations
+- If the story uses native modules, verify auto-linking succeeded on both platforms
+- Bridge calls must be tested with real native code, not mocks
+- Pod install (iOS): `cd ios && pod install` after adding native dependencies
+- Gradle sync (Android): `cd android && ./gradlew --refresh-dependencies` if native module issues
+
+## Area Labels for Testing
+- Use `testID` prop for React Native components (maps to `accessibilityIdentifier` on iOS, `resource-id` on Android)
+- Maestro `tapOn` uses `id:` selector which reads `testID` on both platforms
+- Follow the area label convention from uxa-spec.md: `{screen}-{section}-{element}`

package/pipeline/steps/mobile/read-inputs.md

@@ -0,0 +1,10 @@
+# MOBILE Step: Read Inputs
+
+## Step 1: Read inputs
+Read `reqs-brief.md`, `uxa-spec.md` (if UI profile active), and `qa-test-spec.md`. Understand: acceptance criteria, screen specifications, navigation flows, component hierarchy, platform-specific behaviors, Maestro flow specifications, test specifications.
+
+## Step 2: Read correction directives
+Read `{correction_directives}`. Apply all directives targeting MOBILE. Note any conflicts with default behavior and follow the directive.
+
+## Step 2b: Query Knowledge Agent (Conditional)
+If a Knowledge Agent is available in the team config, send: `[KNOWLEDGE-QUERY] What mobile patterns, navigation conventions, and platform-specific constraints should I know? Context: I am MOBILE implementing {story_id} using {tech_stack.mobile_framework}.` If no response within a reasonable time or no Knowledge Agent is spawned, proceed without.

package/pipeline/steps/mobile/write-tests.md

@@ -0,0 +1,59 @@
+# MOBILE Step: Write Tests
+
+## Step 8: Write Maestro YAML test flows
+For each AC in qa-test-spec.md, write a Maestro YAML flow file. Place flows in `e2e/maestro/` directory.
+
+Each flow file structure:
+```yaml
+appId: {app_package_name}
+name: {descriptive flow name}
+---
+- clearState
+- launchApp
+# ... test steps: tapOn, assertVisible, inputText, scroll, back, swipe, etc.
+```
+
+Rules:
+- Every flow must start with `clearState` and `launchApp`
+- Use `assertVisible` and `assertNotVisible` for assertions, not fixed-time waits
+- Use `waitForAnimationToEnd` instead of hardcoded `extendedWaitUntil` timeouts
+- Deep link tests: use `openLink` command with the URI pattern from reqs-brief
+- Screenshot capture: use `takeScreenshot` at assertion points for evidence
+
+Record in `mobile-handoff.md#maestro-flow-files`.
+
+## Step 8b: Write unit tests
+Write unit tests per qa-test-spec.md using `{tech_stack.test_framework_unit}`. Unit tests MAY mock API clients for isolated component logic. Every mocked unit test for an API-calling AC must be paired with a real-API Maestro flow for the same AC. Record in `mobile-handoff.md#test-files-written`.
+
+## Step 9: Run unit tests, verify all pass
+Run the unit test suite. All tests must pass. Record results in `mobile-handoff.md#test-results-summary`. If tests fail, fix the code -- do not skip or weaken tests.
+
+## Step 9b: App-Level Smoke Test
+
+Write one test that bootstraps the application from its entry point and asserts the story's deliverable is present and reachable. This catches "unwired entry point" bugs where a screen exists but is never registered in the navigation. Mandatory for the first mobile story in a project, recommended for all subsequent stories.
+
+Record in `mobile-handoff.md#test-files-written`.
+
+## Step 10: Run Maestro flows
+
+### Android (always)
+For each flow file:
+1. State isolation (Step 7d)
+2. Execute: `maestro test {flow_file}`
+3. Record per-flow result (pass/fail with output)
+
+### iOS (Mac only)
+For each flow file tagged as `both` or `ios`:
+1. State isolation (Step 7d, iOS variant)
+2. Execute: `maestro test {flow_file} --device {ios_simulator_name}`
+3. Record per-flow result
+
+### iOS Deferred (Windows/Linux)
+If not on Mac, record all iOS-targeted flows in `mobile-handoff.md#deferred-ios-tests` with reason "Host OS lacks iOS simulator". This is expected, not a bug.
+
+E2E tests run serially against the single emulator -- the emulator is shared mutable state. The 1.5-minute timeout per story applies to test execution time excluding emulator boot time.
+
+## Step 10b: Signal integration readiness
+When mobile code is complete and all available-platform tests pass, send to BEND via inbox:
+`[INTEGRATION-READY] Mobile code complete. Run integration tests against my app.`
+Wait for BEND's `[INTEGRATION-READY]` message before running integration verification. Once both sides are ready, verify that API calls from the app resolve correctly against BEND's running server.

package/pipeline/steps/orchestration/adopt-lead-and-create-team.md

@@ -99,7 +99,7 @@ Otherwise, substitute variables in the knowledge spawn template (`{{story_id}}`,
 
 | Wave | Spawn Trigger | Agents |
 |---|---|---|
-| 2 | QA-A sends `[HANDOFF]` (completes) | BEND, FEND, CRITIC |
+| 2 | QA-A sends `[HANDOFF]` (completes) | BEND, FEND, DATA, MCP-DEV, LIBDEV, DOCGEN, IAC, CRITIC (each only if not skipped by testing_profiles) |
 | 3 | CRITIC task becomes `in_progress` | QA-B, PMCP (if ui profile) |
 | 4 | JUDGE bug-review task becomes `in_progress` | (reserved) |
 

package/pipeline/steps/orchestration/sprint-groom.md

@@ -14,6 +14,10 @@ For each pending story in the grooming batch:
    - `api` — story has API endpoints, backend logic, or database changes
    - `ui` — story has UI components, pages, or visual elements
    - `data-pipeline` — story has ETL, data transformation, or batch processing
+   - `mcp-server` — story has MCP server tools, handlers, or protocol work
+   - `library` — story is shared library/package (exports, packaging, versioning)
+   - `document-generation` — story has document/report template or generation pipeline work
+   - `iac` — story has infrastructure work (Terraform, CloudFormation, Kubernetes, CI/CD)
 3. Write `testing_profiles: [api, ui]` (or whichever apply) to the story's backlog entry
 
 This must complete before Step 1. Downstream agents rely on `testing_profiles` to determine conditional steps.

package/pipeline/steps/orchestration/sprint-size.md

@@ -2,12 +2,17 @@
 
 **Condition:** Only execute in sprint mode (`{is_sprint_mode}` is true).
 
-## Step 1: Spawn BEND/FEND
+## Step 1: Spawn Developer Agents
 
 Scan groomed stories' `testing_profiles` in `{backlog_path}`:
 
-- Spawn BEND if any groomed story has `api` or `data-pipeline` in `testing_profiles`
+- Spawn BEND if any groomed story has `api` in `testing_profiles`
 - Spawn FEND if any groomed story has `ui` in `testing_profiles`
+- Spawn DATA if any groomed story has `data-pipeline` in `testing_profiles`
+- Spawn MCP-DEV if any groomed story has `mcp-server` in `testing_profiles`
+- Spawn LIBDEV if any groomed story has `library` in `testing_profiles`
+- Spawn DOCGEN if any groomed story has `document-generation` in `testing_profiles`
+- Spawn IAC if any groomed story has `iac` in `testing_profiles`
 
 Spawn with their normal prompt template and pass `.valent-pipeline/steps/{agent}/estimate.md` as the first step. Pass `{estimation_model}` and `{correction_directives}` (calibration directives) in the spawn context.
 
@@ -19,16 +24,18 @@ For each story with status `groomed`:
 
 1. Update status to `sizing` in `{backlog_path}`
 2. Read story's `testing_profiles` from `{backlog_path}`
-3. Dispatch based on profiles:
-   - `[api]` or `[data-pipeline]`: send story context to BEND only
-   - `[ui]` only: send story context to FEND only
-   - `[api, ui]` (fullstack): send story context to both BEND and FEND
-4. Agents write estimation files (`bend-estimation.md` and/or `fend-estimation.md`)
-5. **Record points:**
-   - Backend-only (`[api]`): `story_points = BEND estimate`
-   - Frontend-only (`[ui]`): `story_points = FEND estimate`
-   - Fullstack (`[api, ui]`): `story_points = BEND estimate + FEND estimate`
-   - Data-pipeline: `story_points = BEND estimate`
+3. Dispatch based on profiles — send story context to **every agent whose profile is present**:
+   - `api` in profiles → send to BEND
+   - `ui` in profiles → send to FEND
+   - `data-pipeline` in profiles → send to DATA
+   - `mcp-server` in profiles → send to MCP-DEV
+   - `library` in profiles → send to LIBDEV
+   - `document-generation` in profiles → send to DOCGEN
+   - `iac` in profiles → send to IAC
+   Multiple profiles can be active (e.g., `[api, data-pipeline]` sends to both BEND and DATA).
+4. Agents write estimation files (`{agent}-estimation.md`)
+5. **Record points:** sum all agent estimates for the story.
+   `story_points = sum of all agent estimates received`
 6. Update story's `story_points` field in `{backlog_path}`
 
 ## Step 3: Update Sprint State

package/pipeline/steps/orchestration/validate-story-inputs.md

@@ -33,11 +33,20 @@ Based on the story scope and project type, determine which testing profiles are
 | Story has API endpoints (backend routes, REST/GraphQL) | `api` |
 | Story has UI components (pages, components, visual changes) | `ui` |
 | Story has data pipeline work (ETL, transformations, migrations) | `data-pipeline` |
+| Story has MCP server tools, handlers, or protocol work | `mcp-server` |
+| Story is shared library/package (exports, packaging, versioning) | `library` |
+| Story has document/report template or generation pipeline work | `document-generation` |
+| Story has infrastructure work (Terraform, CloudFormation, Kubernetes, CI/CD) | `iac` |
 
 Multiple profiles can be active. Examples:
 - Backend-only story: `[api]`
 - Frontend-only story: `[ui]`
 - Fullstack story with both API and UI work: `[api, ui]`
 - Data pipeline story: `[data-pipeline]`
+- MCP server story: `[mcp-server]`
+- Library/package story: `[library]`
+- Document generation story: `[document-generation]`
+- Infrastructure story: `[iac]`
+- Fullstack story with infrastructure: `[api, ui, iac]`
 
 Set `{testing_profiles}` for use in shared context.

package/pipeline/steps/qa-a/data-pipeline.md

@@ -0,0 +1,32 @@
+# QA-A Step: Data Pipeline Testing
+
+## Pipeline Smoke Test Specification
+
+For every pipeline stage in this story, write a **Pipeline Smoke Test** table:
+
+```
+## Pipeline Smoke Tests
+
+| ID | Input Dataset | Transform Step | Expected Output | Row Count Delta | Idempotency Check |
+```
+
+Rules:
+- One row per transform stage (ingest, each transform, output)
+- Input dataset: exact description of seed data (file path, format, row count, key characteristics)
+- Transform step: the specific stage being tested
+- Expected output: key fields, values, and format QA-B must verify
+- Row count delta: expected rows in vs rows out with reason for any difference
+- Idempotency check: "Run twice, assert identical output" for every write stage
+- Minimum per pipeline: one happy path per stage, one null/malformed input, one empty input
+- Every filter/join stage MUST have a row asserting dropped rows are logged with reason
+- Checkpoint/resume: at least one test row that simulates mid-pipeline failure and verifies resume produces correct final output
+
+## Quality Gate Additions
+
+- [ ] Smoke test table covers every pipeline stage (ingest, transform, output)
+- [ ] Every filter/join has a row count delta assertion with drop reason verification
+- [ ] Idempotency test specified for every write stage
+- [ ] Null and malformed input test cases included
+- [ ] Empty input test case included
+- [ ] Checkpoint/resume test case included (if pipeline supports checkpointing)
+- [ ] Row counts verified at each stage boundary

package/pipeline/steps/qa-a/document-generation.md

@@ -0,0 +1,52 @@
+# QA-A Step: Document Generation Testing
+
+## Render Smoke Test Specification
+
+For every document template in this story, write a **Render Smoke Test** table:
+
+```
+## Render Smoke Tests
+
+| ID | Template | Input Data | Expected Output Format | Validation Check |
+```
+
+Rules:
+- One row per template + scenario (happy path + key edge cases)
+- Input Data: exact JSON payload or reference to fixture file
+- Expected Output Format: PDF, HTML, Markdown, etc. with expected MIME type
+- Validation Check: what QA-B must verify in the generated output
+- Minimum per template: one happy path with all variables populated, one with null/missing optional variables, one with edge-case data (unicode, long strings, special characters)
+
+### Variable Substitution Tests
+
+- **Normal substitution:** all required variables present and correctly typed -- verify they appear in output at expected positions
+- **Null variables:** optional variables set to null -- verify graceful handling (omitted or default value), no literal `null` in output
+- **Missing variables:** required variables omitted -- verify clear error, no unsubstituted markers (`{{varName}}`, `${varName}`, etc.) in output
+
+### Conditional Section Tests
+
+- Templates with conditional sections must have test rows for each branch (true and false conditions)
+- Templates with loops must have test rows for empty collection, single item, and multiple items
+
+### Output Format Validation
+
+- Every declared output format must have at least one test row
+- Validation must confirm correct MIME type and parseable structure (valid HTML, valid PDF, valid Markdown)
+
+### Encoding and Unicode Tests
+
+- At least one test row with CJK characters, emoji, or RTL text in variable data
+- Verify output preserves unicode correctly (no mojibake, no encoding errors)
+
+### No Unsubstituted Markers
+
+- Every test must verify that no raw template markers appear in the final output
+
+## Quality Gate Additions
+
+- [ ] Render smoke test table covers every template (happy path + null/missing + edge-case data)
+- [ ] Variable substitution tested for normal, null, and missing cases
+- [ ] Conditional sections tested for all branches
+- [ ] Every output format has at least one validation test
+- [ ] Encoding/unicode test included
+- [ ] No unsubstituted markers assertion included in every test

package/pipeline/steps/qa-a/iac.md

@@ -0,0 +1,30 @@
+# QA-A Step: Infrastructure Testing
+
+## Infrastructure Smoke Test Specification
+
+For every infrastructure resource in this story, write an **Infrastructure Smoke Test** table:
+
+```
+## Infrastructure Smoke Tests
+
+| ID | Resource | Operation | Expected State | Validation Method |
+```
+
+Rules:
+- One row per resource provisioned or modified
+- Resource: resource type and logical name (e.g., `aws_s3_bucket.data_lake`)
+- Operation: plan, apply, destroy, or drift-check
+- Expected state: the desired state after the operation (e.g., "exists with tags", "no diff on re-apply")
+- Validation method: how QA-B verifies (e.g., "terraform plan output", "aws cli describe", "policy check output")
+- Minimum per resource: one plan validation, one tagging check
+- Every story must include: plan output validation (no errors), drift check (plan after apply = no changes), tagging check (all resources tagged), security policy check (no overly permissive IAM)
+- Idempotency row required: "apply twice, second plan shows no changes"
+
+## Quality Gate Additions
+
+- [ ] Smoke test table covers every infrastructure resource (plan + tagging + security)
+- [ ] Plan output validation row present (terraform plan succeeds without errors)
+- [ ] Drift check row present (plan after apply = no changes)
+- [ ] Tagging check row present (all resources have standard tags)
+- [ ] Security policy check row present (no wildcard IAM, no hardcoded secrets)
+- [ ] Idempotency row present (apply twice = no changes)

package/pipeline/steps/qa-a/library.md

@@ -0,0 +1,42 @@
+# QA-A Step: Library Testing
+
+## Export Smoke Test Specification
+
+For every public export in this story, write an **Export Smoke Test** table:
+
+```
+## Export Smoke Tests
+
+| ID | Import Method | Module Path | Expected Export | Verification |
+```
+
+Rules:
+- One row per export + import method (CJS `require()` and ESM `import` for each export)
+- Module path: exact path from the exports map (e.g., `"./utils"`, `"."`)
+- Expected export: the named or default export and its expected type/signature
+- Verification: what to assert (typeof, instanceof, return value shape, callable, etc.)
+- Minimum per export: one CJS row, one ESM row
+- Type declaration exports must have a verification row confirming .d.ts resolution
+- Backwards compatibility: if this is an update to an existing library, include rows verifying that previously documented imports still resolve
+
+## Tree-Shaking Specification
+
+If the library declares `sideEffects: false`, write a **Tree-Shaking Test** table:
+
+```
+## Tree-Shaking Tests
+
+| ID | Import Statement | Expected Included | Expected Excluded | Verification |
+```
+
+Rules:
+- Selective import must not pull in unrelated modules
+- Bundle output must not contain code from unused exports
+- Side-effect-free imports must produce no console output or global mutations
+
+## Quality Gate Additions
+
+- [ ] Export smoke test table covers every public export (CJS + ESM rows)
+- [ ] Type declaration verification rows present for all typed exports
+- [ ] Backwards compatibility rows present for updated libraries
+- [ ] Tree-shaking tests present if sideEffects: false is declared

package/pipeline/steps/qa-a/mcp-server.md

@@ -0,0 +1,31 @@
+# QA-A Step: MCP Server Testing
+
+## Protocol Smoke Test Specification
+
+For every MCP tool in this story, write a **Protocol Smoke Test** table:
+
+```
+## Protocol Smoke Tests
+
+| ID | JSON-RPC Method | Params | Expected Result Shape | Expected Error Code |
+```
+
+Rules:
+- Initialize handshake first: `initialize` request must be the first row, verifying server info and capabilities
+- `tools/list` must follow, verifying all tools are registered with correct inputSchema
+- One `tools/call` row per tool with valid params (happy path)
+- One `tools/call` row per tool with invalid params (schema violation, expecting `-32602`)
+- Two-tier error model coverage: at least one row triggering `isError: true` (tool failure) and at least one row triggering a JSON-RPC error code (protocol failure)
+- One row for unknown tool name (expecting `-32601` Method not found or `-32602` Invalid params)
+- One row for malformed JSON-RPC (expecting `-32700` or `-32600`)
+- Expected result shape: key fields and content types QA-B must verify
+- Params: exact JSON payload for the JSON-RPC params field
+
+## Quality Gate Additions
+
+- [ ] Protocol smoke test table covers initialize handshake
+- [ ] Protocol smoke test table covers tools/list
+- [ ] Protocol smoke test table covers tools/call for every tool (happy path + error paths)
+- [ ] Two-tier error model tested: at least one JSON-RPC error code and one isError:true
+- [ ] Invalid args test included for every tool
+- [ ] Unknown tool / unknown method test included

package/pipeline/steps/qa-a/mobile-app.md

@@ -0,0 +1,59 @@
+# QA-A Step: Mobile App Testing
+
+## Maestro Flow Specification
+
+For every mobile screen/flow in this story, write a **Maestro Flow Specification** table:
+
+### Maestro Flow Specifications
+
+| ID | Flow Name | App State Setup | Steps | Expected Result | Platform |
+|----|-----------|-----------------|-------|-----------------|----------|
+
+Column rules:
+- **ID:** Sequential flow identifier (MF-001, MF-002, ...)
+- **Flow Name:** Descriptive name matching the AC being tested
+- **App State Setup:** How to reach the required starting state. Every flow starts with `clearState` + `launchApp`. If seed data is needed, specify the API call or fixture.
+- **Steps:** Sequence of Maestro actions (`launchApp`, `tapOn`, `assertVisible`, `inputText`, `scroll`, `back`, `swipe`, `openLink`, `takeScreenshot`)
+- **Expected Result:** What the user should see after the flow completes (assert conditions)
+- **Platform:** `both` (default) | `android-only` | `ios-only`
+
+### Flow Writing Rules
+
+1. Every flow MUST start with `clearState` or `launchApp` with `clearState: true` — no state carryover from previous flows
+2. Every flow MUST be independent — no ordering dependency between flows
+3. Use `assertVisible` and `assertNotVisible` for assertions, not fixed-time waits
+4. Use `waitForAnimationToEnd` for animation settling, not `extendedWaitUntil` with hardcoded durations
+5. For deep link tests, use `openLink` command with the URI pattern from reqs-brief
+6. Include `takeScreenshot` at key assertion points for evidence capture
+
+## Platform-Conditional Test Requirements
+
+For each AC, specify:
+- **Both platforms** (default): tests that verify identical behavior on Android and iOS
+- **Android-specific:** tests for Android-only behavior (hardware back button, specific permissions, Android notification channels)
+- **iOS-specific:** tests for iOS-only behavior (swipe-to-go-back, Face ID/Touch ID, iOS notification categories)
+
+Mark iOS-specific tests with `[DEFER-IOS]` if the pipeline host may be Windows/Linux. The MOBILE agent will move these to the deferred queue.
+
+## State Isolation Requirements
+
+- Every Maestro flow must be independent (no ordering dependency)
+- App state cleared between flows via `adb shell pm clear {package}` / simulator equivalent
+- If a flow requires seed data, specify the exact API call or fixture to set it up before the flow
+- If a flow requires specific permissions, specify which permissions must be pre-granted
+
+## API Integration for Mobile
+
+When a story's mobile app calls backend APIs, the spec MUST include:
+- At least one Maestro flow per API-calling AC that exercises the real API round-trip (app → API → database → response → UI update)
+- No mocked API responses in Maestro flows (Maestro does not support API interception — this is enforced by design)
+- Infrastructure prerequisite: "API server must be running before Maestro flow execution"
+
+## Quality Gate Additions
+
+- [ ] Every AC has at least one Maestro flow specification
+- [ ] State isolation documented for every flow (clearState + seed data if needed)
+- [ ] Platform-specific tests explicitly tagged (both / android-only / ios-only)
+- [ ] No flow depends on another flow's output state
+- [ ] Deep link tests included for screens with URI patterns
+- [ ] Infrastructure prerequisites documented (API server, emulator, permissions)

package/pipeline/steps/qa-b/data-pipeline.md

@@ -0,0 +1,48 @@
+# QA-B Step: Data Pipeline Testing
+
+## Pipeline Execution Tests
+
+Mandatory for all stories with data pipeline stages. Run the real pipeline against real data and real data stores.
+
+**Procedure:**
+
+1. **Seed sample data.** Per smoke test table in qa-test-spec.md. Use fixture files, seed scripts, or direct data store insertion. Include happy-path data, null/malformed records, and edge cases.
+2. **Run pipeline.** Execute the full pipeline from ingest to output. Capture all logs.
+3. **Validate row counts.** At each stage boundary, verify row counts match expected values from the smoke test table. Record actual vs expected.
+4. **Spot-check values.** For each transform stage, verify a sample of output records against expected values. Check data types, formats, null handling, and edge cases.
+5. **Re-run pipeline (idempotency).** Run the same pipeline again with the same input. Assert that the output is identical -- no duplicate rows, no changed values, no side effects from the second run.
+6. **Kill and restart (checkpoint/resume).** If the pipeline supports checkpointing: run the pipeline, kill it mid-execution (after at least one checkpoint), restart, and verify that the final output matches a clean full run.
+7. **Record results** in `## Pipeline Execution Results` of execution-report.md.
+
+**Pipeline Execution Results table:**
+
+```
+| ID | Stage | Input Rows | Expected Output Rows | Actual Output Rows | Spot-Check Values | Idempotency | Result |
+```
+
+**Row Count Reconciliation:**
+
+```
+| Stage | Input | Output | Dropped | Drop Reason | Expected Delta | Actual Delta | Match |
+```
+
+Include full pipeline logs and commands for reproducibility.
+
+**Failure handling:**
+- Pipeline fails to start: file P1 bug, record error, continue.
+- Stage produces wrong row count: file bug at appropriate priority, continue remaining stages.
+- Idempotency fails (duplicates on re-run): file P1 bug, record both run outputs.
+- Checkpoint/resume produces different output than clean run: file P1 bug, record both outputs.
+- Pipeline crashes mid-run: file P1 bug, record crash output, attempt restart.
+
+**This step cannot be skipped.** If qa-test-spec.md lacks a Pipeline Smoke Tests section, construct the table from pipeline stages in reqs-brief.md and execute.
+
+## Execution Report Additions
+
+The execution report MUST include:
+- `## Pipeline Execution Results` table with actual vs expected for every stage
+- `## Row Count Reconciliation` table showing data flow through the pipeline
+- Full pipeline execution logs
+- Pipeline start command and configuration
+- Idempotency verification results (both runs compared)
+- Checkpoint/resume verification results (if applicable)

package/pipeline/steps/qa-b/document-generation.md

@@ -0,0 +1,47 @@
+# QA-B Step: Document Generation Testing
+
+## Render Validation Tests
+
+Mandatory for all stories with document generation. Invoke the real render pipeline and validate actual output.
+
+**Procedure:**
+
+1. **Seed template and input data.** Per render smoke test table in qa-test-spec.md. Load templates and prepare input data fixtures (JSON, database records, or programmatic setup).
+2. **Invoke document generation.** Call the render pipeline with the seeded template and input data. Capture the generated output (file, buffer, or stream).
+3. **Verify output format and MIME type.** Confirm the output matches the expected format (PDF, HTML, Markdown) and has the correct MIME type.
+4. **Parse output structure.** For HTML: parse the DOM. For PDF: extract text and metadata. For Markdown: parse structure. Verify the output is well-formed and parseable.
+5. **Check variable substitution.** Verify all expected variable values appear in the output at correct positions. Verify no unsubstituted template markers (`{{varName}}`, `${varName}`, `{% raw %}`, etc.) remain.
+6. **Verify encoding.** Confirm UTF-8 encoding. Test with unicode data (CJK, emoji, RTL) and verify output preserves characters correctly -- no mojibake, no replacement characters.
+7. **Execute edge-case data tests.** Per render smoke test table: null variables, missing optional fields, empty collections, extremely long strings, special characters. Verify graceful handling.
+8. **Record results** in `## Render Validation Results` of execution-report.md.
+
+```
+## Render Validation Results
+
+| ID | Template | Input Data | Expected Format | Actual Format | Substitution Check | Encoding Check | Result |
+```
+
+Include raw generation commands and output excerpts for reproducibility.
+
+### Variable Substitution Audit
+
+After all render tests execute, build a substitution audit:
+
+| Template | Total Variables | Substituted Correctly | Null Handled | Missing Handled | Unsubstituted Markers Found |
+|----------|----------------|----------------------|--------------|-----------------|---------------------------|
+
+**Failure handling:**
+- Render pipeline fails to start: file P1 bug, record error, continue.
+- Render test fails: file bug at appropriate priority, continue remaining tests.
+- Output contains unsubstituted markers: file P1 bug -- this is a data leak / presentation defect.
+- Encoding errors (mojibake, replacement characters): file P2 bug.
+
+**This step cannot be skipped.** If qa-test-spec.md lacks a Render Smoke Tests section, construct the table from template definitions in reqs-brief.md and execute.
+
+## Execution Report Additions
+
+The execution report MUST include:
+- `## Render Validation Results` table with actual vs expected for every row
+- Variable substitution audit table
+- Raw generation commands and output excerpts
+- Encoding verification details (input data with unicode, output confirmation)

package/pipeline/steps/qa-b/iac.md

@@ -0,0 +1,44 @@
+# QA-B Step: Infrastructure Testing
+
+## Infrastructure Validation Tests
+
+Mandatory for all stories with infrastructure resources. Validate infrastructure definitions against real plan output and live state.
+
+**Procedure:**
+
+1. **Initialize.** Run `terraform init` (or equivalent) to initialize providers and modules. Verify initialization succeeds without errors.
+2. **Plan validation.** Run `terraform plan` (or equivalent). Verify no errors. Capture plan output for review.
+3. **Apply (if test environment available).** Run `terraform apply` against the test environment. Capture apply output.
+4. **Verify resources exist.** For each resource in the smoke test table, verify it exists in the target environment using CLI or API queries.
+5. **Verify tags.** For each resource, verify all standard tags are present (environment, project, owner, managed-by).
+6. **Verify IAM policies.** For each IAM role/policy, verify least-privilege: no wildcard actions, no overly broad resource scopes.
+7. **Idempotency check.** Run `terraform plan` again after apply. Expect no changes (zero diff). Any unexpected diff is a bug.
+8. **Record results** in `## Infrastructure Validation Results` of execution-report.md.
+
+**Infrastructure Validation Results table:**
+
+```
+| ID | Resource | Operation | Expected State | Actual State | Tags Valid | IAM Valid | Result |
+```
+
+Include full command output for reproducibility.
+
+**Failure handling:**
+- Init fails: file P1 bug, record error, continue.
+- Plan fails: file P1 bug, record plan output, continue.
+- Apply fails: file P1 bug, record apply output, continue.
+- Missing resource after apply: file P1 bug, continue remaining checks.
+- Missing tags: file P2 bug, continue.
+- Overly permissive IAM: file P1 bug, continue.
+- Idempotency fails (diff after apply): file P1 bug, record both plan outputs.
+
+**This step cannot be skipped.** If qa-test-spec.md lacks an Infrastructure Smoke Tests section, construct the table from infrastructure resources in reqs-brief.md and execute.
+
+## Execution Report Additions
+
+The execution report MUST include:
+- `## Infrastructure Validation Results` table with actual vs expected for every resource
+- Full terraform init/plan/apply output
+- Tag verification results per resource
+- IAM policy verification results
+- Idempotency verification (second plan output showing no changes)