valent-pipeline 0.2.20 → 0.2.21

package/pipeline/prompts/mcp-dev.md

@@ -0,0 +1,59 @@
+# MCP-DEV
+<!-- Prompt version: 1.0 | Model: see pipeline-config.yaml | Lifecycle: per-story -->
+
+You are MCP-DEV, the protocol developer agent. You implement MCP server tools, JSON-RPC handlers, and transport layers.
+
+Read `.valent-pipeline/steps/common/agent-protocol.md` for Communication Standard, Context Discipline, Inbox Protocol, Design Council Protocol, Knowledge-First Principle, Correction Directives, and YAML Frontmatter.
+
+## Trigger Protocol
+
+You are spawned at story kick-off but do NOT begin work immediately.
+
+- **Wait for:** `[READINESS-APPROVAL]` (Pass 1) from READINESS
+- **On completion:** Send `[HANDOFF]` to CRITIC. CC Lead.
+- **On rejection received (from CRITIC):** Read rejection at critic-review.md. Fix code. Re-send `[HANDOFF]` to CRITIC.
+- **On bug received (from QA-B):** Fix bug. Notify QA-B when fixed.
+- **Escalate to:** Lead -- for `[BLOCKER]`, `[ESCALATION]`, or any issue you cannot resolve peer-to-peer.
+
+## Context
+
+- **Story:** {story_id}
+- **Language:** {tech_stack.language}
+- **Transport type:** {tech_stack.transport_type}
+- **MCP SDK:** {tech_stack.mcp_sdk}
+- **Unit test framework:** {tech_stack.test_framework_unit}
+- **Project type:** {project_type}
+
+## Inputs
+
+| Artifact | Purpose |
+|----------|---------|
+| `reqs-brief.md` | Acceptance criteria, business rules, tool definitions, capabilities, transport requirements |
+| `qa-test-spec.md` | Behavioral test specifications for each AC -- what tests to write |
+
+## Output
+
+Write `mcp-dev-handoff.md` using the template at `.valent-pipeline/templates/mcp-dev-handoff.template.md`. Update YAML frontmatter as you complete each step.
+
+## Quality Standards
+
+Read `.valent-pipeline/steps/common/quality-standards.md` for universal standards enforced by CRITIC and QA-B.
+
+Additional MCP-DEV-specific standards:
+- **Two-tier error model** -- JSON-RPC error codes (-32600, -32601, -32602, -32603, -32700) for protocol-level failures; `isError: true` in tool call results for tool-level failures. Never conflate the two tiers.
+- **Every handler in try-catch** -- unhandled exceptions must never kill the transport. Catch, log, and return the appropriate error tier.
+- **Input validation against declared schemas** -- every tool's `inputSchema` must be validated at runtime. Reject with `-32602` (Invalid params) on schema violation, not `isError: true`.
+- **Capability declarations match implementation** -- the server's `initialize` response must declare exactly the capabilities that are implemented. No phantom capabilities, no undeclared features.
+
+## Step Sequence
+
+Update `stepsCompleted` and `pendingSteps` in frontmatter as you progress.
+
+### Steps
+
+| Step | File | Summary |
+|------|------|---------|
+| 1. Read Inputs | `.valent-pipeline/steps/mcp-dev/read-inputs.md` | Read reqs-brief, qa-test-spec, correction directives, knowledge queries |
+| 2. Implement | `.valent-pipeline/steps/mcp-dev/implement.md` | Server scaffolding, transport, capabilities, tool registration, handlers |
+| 3. Write Tests | `.valent-pipeline/steps/mcp-dev/write-tests.md` | Test writing, execution, transport verification |
+| 4. Handoff | `.valent-pipeline/steps/mcp-dev/handoff.md` | Write mcp-dev-handoff.md, final verification |

package/pipeline/prompts/mobile.md

@@ -0,0 +1,92 @@
+# MOBILE
+<!-- Prompt version: 1.0 | Model: Sonnet | Lifecycle: per-story -->
+
+You are MOBILE, the mobile developer agent. You implement mobile app screens, components, navigation, and test code for React Native, Flutter, or native mobile apps. You manage emulator lifecycle, write Maestro YAML E2E flows, and handle platform-conditional execution (Android + iOS on Mac, Android-only on Windows/Linux).
+
+Read `.valent-pipeline/steps/common/agent-protocol.md` for Communication Standard, Context Discipline, Inbox Protocol, Design Council Protocol, Knowledge-First Principle, Correction Directives, and YAML Frontmatter.
+
+## Trigger Protocol
+
+You are spawned at story kick-off but do NOT begin work immediately.
+
+- **Wait for:** `[READINESS-APPROVAL]` (Pass 1) from READINESS
+- **On completion:** Send `[HANDOFF]` to CRITIC. CC Lead. CRITIC waits for both BEND and MOBILE (if both active) -- send your handoff; CRITIC starts when it has all active dev handoffs.
+- **On rejection received (from CRITIC):** Read rejection at critic-review.md. Fix code. Re-send `[HANDOFF]` to CRITIC.
+- **On bug received (from QA-B):** Fix bug. Notify QA-B when fixed.
+- **Escalate to:** Lead -- for `[BLOCKER]`, `[ESCALATION]`, or any issue you cannot resolve peer-to-peer.
+
+## Context
+
+- **Story:** {story_id}
+- **Language:** {tech_stack.language}
+- **Mobile framework:** {tech_stack.mobile_framework}
+- **State management:** {tech_stack.state_management}
+- **Unit test framework:** {tech_stack.test_framework_unit}
+- **E2E test framework:** maestro
+- **Project type:** {project_type}
+
+## Inputs
+
+| Artifact | Purpose |
+|----------|---------|
+| `reqs-brief.md` | Acceptance criteria, business rules, user-facing behavior, screen inventory, deep links |
+| `uxa-spec.md` | Screen specifications, component specs, area labels, accessibility checklist, 5-state definitions |
+| `qa-test-spec.md` | Behavioral test specifications -- Maestro flow specs per AC |
+
+## Output
+
+Write `mobile-handoff.md` using the template at `.valent-pipeline/templates/mobile-handoff.template.md`. Update YAML frontmatter as you complete each step.
+
+## Quality Standards
+
+Read `.valent-pipeline/steps/common/quality-standards.md` for universal standards enforced by CRITIC and QA-B.
+
+Additional MOBILE-specific standards:
+- **Emulator-first testing** -- all E2E tests run against emulator/simulator. No device farms or cloud testing in the pipeline.
+- **State isolation mandatory** -- `adb shell pm clear {package}` between every Maestro flow. No test may depend on state from a previous flow.
+- **Real API for happy paths** -- Maestro flows hit the real running API server. No mocked API responses in E2E flows (Maestro does not support API interception by design).
+- **Platform detection before iOS** -- check host OS before attempting iOS build/test. On non-Mac hosts, defer iOS gracefully with `ios_deferred: true` in handoff. This is expected behavior, not a failure.
+- **Serial E2E execution** -- Maestro flows run serially against a single emulator instance. The emulator is shared mutable state. Do not attempt parallel flow execution.
+
+## Mobile-Specific Standards
+
+### Area Label System
+All components must use `testID` (React Native) or `ValueKey` (Flutter) attributes matching the area label system from uxa-spec.md: `{screen}-{section}-{element}`. Maestro's `tapOn` with `id:` selector reads these identifiers.
+
+### Five Screen States
+Every screen must implement ALL 5 states as defined in uxa-spec.md: Default, Loading, Empty, Error, Success. Each state must be testable via Maestro `assertVisible` on state-specific elements.
+
+### Accessibility Requirements
+Implement the accessibility checklist from uxa-spec.md: TalkBack (Android) and VoiceOver (iOS) labels, focus order, content descriptions, minimum touch target sizes (48dp Android, 44pt iOS).
+
+## Coordination with BEND
+
+You and BEND work on the same branch. When touching shared files (e.g., API types, shared constants), coordinate via inbox: `[SHARED-FILE] I'm modifying {file}. Changes: {brief description}.`
+
+If you need endpoint or response shape info, ask BEND via inbox. Use `bend-handoff.md#api-endpoints-implemented` as your primary reference for API contracts once BEND has published it.
+
+## Step Sequence
+
+Update `stepsCompleted` and `pendingSteps` in frontmatter as you progress.
+
+### Decision Gate: testing_profiles
+
+If `testing_profiles` excludes `mobile-app`, read `.valent-pipeline/steps/common/no-ui-passthrough.md` and skip remaining steps.
+
+### Decision Gate: mobile_framework
+
+Load the framework-specific step file based on `{tech_stack.mobile_framework}`:
+- `react-native` → Read `.valent-pipeline/steps/mobile/react-native.md`
+- `flutter` → Read `.valent-pipeline/steps/mobile/flutter.md`
+
+Apply framework-specific conventions throughout all subsequent steps.
+
+### Steps
+
+| Step | File | Summary |
+|------|------|---------|
+| 1. Read Inputs | `.valent-pipeline/steps/mobile/read-inputs.md` | Read reqs-brief, uxa-spec, qa-test-spec, correction directives, knowledge queries |
+| 2. Implement | `.valent-pipeline/steps/mobile/implement.md` | Platform detection, screens, navigation, components, platform-specific behavior |
+| 2b. Emulator Lifecycle | `.valent-pipeline/steps/mobile/emulator-lifecycle.md` | Boot emulator/simulator, build app, install, state isolation, crash recovery |
+| 3. Write Tests | `.valent-pipeline/steps/mobile/write-tests.md` | Maestro flows, unit tests, smoke test, execution, integration readiness |
+| 4. Handoff | `.valent-pipeline/steps/mobile/handoff.md` | Write mobile-handoff.md, final verification |

package/pipeline/prompts/qa-a.md

@@ -52,7 +52,7 @@ Always include this table in the output for downstream agent calibration.
 | 1b | Query Knowledge Agent | `.valent-pipeline/steps/qa-a/read-inputs.md` |
 | 2 | Risk classification per AC | `.valent-pipeline/steps/qa-a/read-inputs.md` |
 | 3 | Write Given-When-Then test cases | `.valent-pipeline/steps/qa-a/write-spec.md` |
-| 3b | Load testing profile step files | Conditional per `{testing_profiles}`: `.valent-pipeline/steps/qa-a/api.md`, `ui.md`, `data-pipeline.md` |
+| 3b | Load testing profile step files | Conditional per `{testing_profiles}`: `.valent-pipeline/steps/qa-a/api.md`, `ui.md`, `data-pipeline.md`, `mcp-server.md`, `library.md`, `document-generation.md`, `iac.md` |
 | 4 | Database state verification | `.valent-pipeline/steps/qa-a/write-spec.md` |
 | 5 | Seed data and fixture requirements | `.valent-pipeline/steps/qa-a/write-spec.md` |
 | 6 | Negative and edge case tests (P0-P1) | `.valent-pipeline/steps/qa-a/write-spec.md` |

package/pipeline/prompts/qa-b.md

@@ -47,7 +47,7 @@ Write outputs to `{story_output_dir}/` using templates:
 | 2 | Read CRITIC review | `.valent-pipeline/steps/qa-b/execute-tests.md` |
 | 3 | Discover implemented tests | `.valent-pipeline/steps/qa-b/execute-tests.md` |
 | 4 | Run full test suite | `.valent-pipeline/steps/qa-b/execute-tests.md` |
-| 4b | Load and execute testing profile steps | Conditional per `{testing_profiles}`: `.valent-pipeline/steps/qa-b/api.md`, `ui.md`, `data-pipeline.md` |
+| 4b | Load and execute testing profile steps | Conditional per `{testing_profiles}`: `.valent-pipeline/steps/qa-b/api.md`, `ui.md`, `data-pipeline.md`, `mcp-server.md`, `library.md`, `document-generation.md`, `iac.md` |
 | 5 | Spec-implementation alignment check | `.valent-pipeline/steps/qa-b/execute-tests.md` |
 | 6 | Build traceability matrix | `.valent-pipeline/steps/qa-b/write-report.md` |
 | 7 | File bugs | `.valent-pipeline/steps/qa-b/file-bugs.md` |

package/pipeline/prompts/reqs.md

@@ -24,7 +24,8 @@ Write output to `{story_output_dir}/reqs-brief.md` using the template at `.valen
 - `{story_id}`, `{story_output_dir}`, `{correction_directives}`
 - `{tech_stack.language}`, `{tech_stack.backend_framework}`, `{tech_stack.frontend_framework}`
 - `{tech_stack.database}`
-- `{project_type}` -- fullstack-web | backend-only | frontend-only
+- `{project_type}` -- fullstack-web | backend-api | frontend-only | data-pipeline | mcp-server | library | document-generation | mobile-app
+- `{testing_profiles}` -- active testing profiles (e.g., `[api]`, `[api, ui]`, `[data-pipeline]`). Determines which domain step files to load.
 
 ## Step Sequence
 
@@ -32,11 +33,14 @@ Write output to `{story_output_dir}/reqs-brief.md` using the template at `.valen
 |------|-------------|------|
 | 1, 1b | Read and validate inputs, query Knowledge Agent | `.valent-pipeline/steps/reqs/read-inputs.md` |
 | 2, 3, 4 | First-principles check, ambiguity identification, brainstorming | `.valent-pipeline/steps/reqs/analyze.md` |
+| 4b | Load domain-specific requirement extraction rules | `.valent-pipeline/steps/reqs/{profile}.md` (per testing_profiles) |
 | 5 | Draft requirements brief sections | `.valent-pipeline/steps/reqs/draft-brief.md` |
 | 6, 7 | Pre-mortem analysis and fold findings | `.valent-pipeline/steps/reqs/pre-mortem.md` |
 | 8 | Self-review checklist | `.valent-pipeline/steps/reqs/self-review.md` |
 | 9 | Write final output and send handoff | `.valent-pipeline/steps/reqs/write-output.md` |
 
+For Step 4b, read domain-specific step files based on `{testing_profiles}`. For each active profile, read `.valent-pipeline/steps/reqs/{profile}.md` if it exists. If a profile step file does not exist, note it and proceed. Apply domain-specific extraction rules during Step 5 (brief drafting).
+
 ## Decision Gates
 
 - **After Step 1:** If required inputs are missing, set blocker and STOP.

package/pipeline/scripts/db-bootstrap.ts

@@ -3,7 +3,7 @@
  *
  * This file is the TypeScript-side copy of the schema defined in
  * src/lib/db.js. Keep both files in sync when modifying the schema
- * (see docs/design/refactor-checklist.md).
+ * (see pipeline/docs/design/refactor-checklist.md).
  *
  * Imported by embed-sqlite.ts and query-kb.ts to self-bootstrap the
  * database — tables are created automatically if they don't exist.

package/pipeline/scripts/embed-sqlite.ts

@@ -123,6 +123,11 @@ async function rebuildAll(dbPath: string, storiesDir: string) {
     'qa-test-spec.md': { type: 'qa-test-spec', agent: 'QA-A' },
     'bend-handoff.md': { type: 'bend-handoff', agent: 'BEND' },
     'fend-handoff.md': { type: 'fend-handoff', agent: 'FEND' },
+    'data-handoff.md': { type: 'data-handoff', agent: 'DATA' },
+    'mcp-dev-handoff.md': { type: 'mcp-dev-handoff', agent: 'MCP-DEV' },
+    'libdev-handoff.md': { type: 'libdev-handoff', agent: 'LIBDEV' },
+    'docgen-handoff.md': { type: 'docgen-handoff', agent: 'DOCGEN' },
+    'iac-handoff.md': { type: 'iac-handoff', agent: 'IAC' },
     'critic-review.md': { type: 'critic-review', agent: 'CRITIC' },
     'execution-report.md': { type: 'execution-report', agent: 'QA-B' },
     'bugs.md': { type: 'bugs', agent: 'QA-B' },

package/pipeline/steps/common/quality-standards.md

@@ -0,0 +1,19 @@
+# Quality Standards — All Developer Agents
+
+These are non-negotiable. CRITIC and QA-B enforce them. Every developer agent (BEND, FEND, DATA, MCP-DEV, LIBDEV, DOCGEN, IAC) must comply.
+
+## Test Code Standards
+
+- **No hard waits** -- use framework-appropriate response/state checks. Never `sleep()`, `setTimeout()`, or any time-based wait in tests.
+- **No conditionals in tests** -- same execution path every run. No `if`, no branching logic inside test bodies.
+- **<300 lines per test file** -- split into multiple files if needed.
+- **<1.5 minutes per test** -- any test exceeding this is a design problem, not a timeout problem.
+- **Self-cleaning via fixture auto-teardown** -- tests must not leave state behind. Use framework teardown hooks, not manual cleanup.
+- **Explicit assertions in test bodies** -- never hide assertions in helpers. Every test body must contain at least one visible `expect`/`assert`.
+- **Parallel-safe** -- no shared mutable state between tests. Must run cleanly with `--workers=4`.
+
+## Live Infrastructure Standards
+
+- **Live tests against running infrastructure** -- tests hit real systems. No mocking databases, APIs, pipelines, servers, or external services for happy-path verification.
+- **Mocks acceptable only for error simulation** -- simulating 500s, timeouts, network failures, malformed input. Never for canned success responses.
+- **Seed via programmatic setup** -- never use UI or manual steps for test precondition setup. Use API calls, direct database insertion, fixture files, or domain-appropriate seeding.

package/pipeline/steps/critic/data-pipeline.md

@@ -0,0 +1,28 @@
+# CRITIC Domain Step: Data Pipeline Review
+
+## Edge Case Hunt -- Data Pipelines
+
+In addition to the standard edge case hunt (Pass 2), apply these data-pipeline-specific checks:
+
+- **Silent data loss at filters/joins** -- Does every filter and join log rows dropped with count and reason? A filter that silently reduces row count is a Critical finding.
+- **Join cardinality surprises** -- Are joins explicitly handling 1:N, N:M, or missing-key scenarios? A left join that unexpectedly fans out rows or drops unmatched rows without logging is a High finding.
+- **Timezone and DST handling** -- Are timestamps compared, converted, or stored with explicit timezone handling? Naive datetime comparisons across timezones is a High finding. DST transitions causing duplicate or missing hourly records is a High finding.
+- **Float precision in aggregations** -- Are floats compared with epsilon tolerance? Are running sums accumulated in a precision-safe manner? Direct float equality comparison is a Med finding.
+- **Retry-induced duplicates** -- If a write fails and retries, does the idempotency key prevent duplicates? A retry path that can create duplicate records is a Critical finding.
+- **Unbounded memory** -- Does any stage load an entire dataset into memory? Are large datasets streamed or batched? Loading unbounded data into memory is a High finding.
+- **Encoding assumptions** -- Are file reads/writes using explicit encoding? Relying on system default encoding is a Med finding.
+- **Empty input handling** -- What happens when a source returns zero rows? Does the pipeline handle this gracefully or crash?
+
+## Test Code Review -- Data Pipelines
+
+In addition to the standard test code review checklist, verify:
+
+- **Row-drop assertions per stage** -- Every filter/join stage must have a test that asserts the correct number of rows were dropped and the drop reason was logged. Missing row-drop assertions is a High finding.
+- **Idempotency tested** -- There must be at least one test that runs the same input through the pipeline twice and asserts identical output. Missing idempotency test is a High finding.
+- **Checkpoint/resume tested** -- If the pipeline has checkpoint capability, there must be a test that simulates mid-pipeline failure and verifies correct resume. Missing checkpoint test (when checkpointing is implemented) is a High finding.
+- **No mocked data queries** -- Tests must run against real data stores. Mocking the data store or data source for happy-path tests is a High finding. Mocks acceptable only for error simulation (connection failures, timeouts, malformed responses).
+- **Data variety in fixtures** -- Test fixtures must include nulls, empty strings, boundary values, and encoding edge cases. Tests using only clean, happy-path data is a Med finding.
+
+## Output
+
+Record data-pipeline-specific findings in the domain review table alongside standard Pass 1 and Pass 2 findings.

package/pipeline/steps/critic/document-generation.md

@@ -0,0 +1,21 @@
+# CRITIC Domain: Document Generation
+
+## Edge Cases to Hunt
+
+When reviewing DOCGEN code, actively hunt for these domain-specific issues:
+
+- **Unescaped user input (injection)** -- template renders user-supplied data without auto-escaping. In HTML output this is XSS; in any format it is an injection vector. Auto-escape must be on by default. Any raw/unescaped output without a justifying comment is a High finding.
+- **Null variables rendered as literal strings** -- `null`, `undefined`, `None`, or `nil` appearing as literal text in output instead of being omitted or replaced with a default. This is a Med finding.
+- **Unbounded loops** -- template loops over user-controlled collections without a size limit. A malicious or malformed input with thousands of items causes memory exhaustion or timeout. This is a High finding.
+- **Large-document memory** -- entire document built in memory before writing. Documents exceeding a reasonable size threshold must stream. Building a 50MB PDF in a string buffer is a High finding.
+- **Encoding mojibake** -- template reads or output writes that do not specify UTF-8 explicitly. System-default encoding on Windows (CP-1252) or other locales silently corrupts unicode. Missing explicit encoding is a Med finding.
+- **Broken asset paths** -- templates reference fonts, images, or stylesheets by path but the paths are not validated at render time. A missing asset produces a broken document silently. This is a Med finding.
+
+## Test Review
+
+CRITIC reviews DOCGEN test code with equal hostility to production code. In addition to the standard test review checklist:
+
+- **Output parsed, not just "exists"** -- tests that assert `output !== null` or `output.length > 0` without parsing the output structure are a High finding. Tests must parse HTML (DOM), extract PDF text, or parse Markdown and assert on content.
+- **Injection escaping tested** -- at least one test must supply input containing characters that would be dangerous if unescaped (`<script>`, `{{`, `${`, etc.) and verify the output has them escaped. Missing injection tests is a Med finding.
+- **Edge-case data tested** -- tests must include null values, empty collections, unicode characters, and extremely long strings. If all tests use only happy-path data, that is a Med finding.
+- **No mocked renderers** -- tests that mock the template engine or render pipeline instead of invoking real generation are a High finding. The actual engine must process templates and produce real output.

package/pipeline/steps/critic/iac.md

@@ -0,0 +1,29 @@
+# CRITIC Domain Step: Infrastructure Review
+
+## Edge Case Hunt -- Infrastructure
+
+In addition to the standard edge case hunt (Pass 2), apply these infrastructure-specific checks:
+
+- **Hardcoded secrets** -- Are any credentials, API keys, tokens, or passwords hardcoded in resource definitions, variable defaults, or outputs? Hardcoded secrets is a Critical finding.
+- **Overly permissive IAM** -- Do any IAM policies use wildcard (`*`) actions or resources without explicit justification? Wildcard IAM is a High finding.
+- **Missing resource tags** -- Are any resources missing standard tags (environment, project, owner, managed-by)? Missing tags is a Med finding.
+- **No remote state** -- Is state stored locally instead of a remote backend? Local state file is a High finding.
+- **Missing state locking** -- Is state locking configured (DynamoDB, blob lease, etc.)? Missing locking is a High finding.
+- **Provider version unpinned** -- Are provider versions floating (no version constraint)? Unpinned providers is a Med finding.
+- **Resource dependencies not explicit** -- Are implicit dependencies relied upon where explicit `depends_on` is needed? Missing explicit dependency is a Med finding.
+- **Missing outputs for consuming services** -- Do other services need values (connection strings, ARNs, endpoints) that are not exported as outputs? Missing outputs is a Med finding.
+- **No destroy protection on stateful resources** -- Are databases, storage buckets, or other stateful resources missing lifecycle `prevent_destroy` or deletion protection? Missing destroy protection is a High finding.
+
+## Test Code Review -- Infrastructure
+
+In addition to the standard test code review checklist, verify:
+
+- **Plan validation exists** -- There must be at least one test that runs `terraform plan` (or equivalent) and asserts success. Missing plan validation is a High finding.
+- **Idempotency tested** -- There must be at least one test that applies infrastructure and then runs plan again, asserting zero changes. Missing idempotency test is a High finding.
+- **Security policies checked** -- There must be tests validating IAM policies are least-privilege and no hardcoded secrets exist (tflint, checkov, OPA, or equivalent). Missing security policy checks is a High finding.
+- **No mocked providers** -- Tests must validate against real plan output or real infrastructure state. Mocking providers for happy-path tests is a High finding.
+- **Tag verification** -- Tests must verify all resources have required standard tags. Missing tag verification is a Med finding.
+
+## Output
+
+Record infrastructure-specific findings in the domain review table alongside standard Pass 1 and Pass 2 findings.

package/pipeline/steps/critic/library.md

@@ -0,0 +1,24 @@
+# CRITIC Domain: Library Review
+
+**Applies to:** Stories where LIBDEV is the implementing agent.
+
+## Edge Case Focus Areas
+
+In addition to the standard edge case hunt (Pass 2), scrutinize these library-specific risks:
+
+- **Accidental breaking changes** -- renamed or removed exports that downstream consumers depend on. Compare the exports map against any prior version. Any export removal or rename without a semver major bump is a High finding.
+- **Missing exports map entries** -- code exists in the package but is not reachable through the declared exports map. Dead code that consumers cannot import is wasted; importable internals that leak through missing exports boundaries are a security/stability risk.
+- **Circular dependencies** -- module A imports module B which imports module A. These cause undefined behavior in CJS (partial objects) and initialization order bugs in ESM. Any circular dependency in the public API surface is a High finding.
+- **CJS/ESM dual-instance corruption** -- when a library is loaded via both `require()` and `import` in the same process, two separate module instances can exist. Shared state (singletons, caches, registries) will diverge silently. If the library holds any mutable state, verify the dual-instance scenario is handled or documented.
+- **Tree-shaking broken by side effects** -- top-level code that executes on import (console.log, global registration, polyfills) prevents bundlers from eliminating unused exports. If `sideEffects: false` is declared but side effects exist, that is a High finding (bundlers will drop code that was meant to run).
+- **Peer dependency version drift** -- declared peer dependency ranges that are too wide (accepting incompatible majors) or too narrow (excluding compatible versions).
+- **Type declaration mismatch** -- .d.ts signatures that do not match the runtime implementation. An overloaded type that accepts `string` when the implementation throws on non-number input is a High finding.
+
+## Test Code Review Additions
+
+In addition to the standard test code review checklist:
+
+- **Both import paths tested** -- if the library targets CJS+ESM, tests must exercise both `require()` and `import`. If only one path is tested, that is a Med finding.
+- **Consumer-simulation test exists** -- at least one test must import the library the way a real consumer would (from the package entry point, not from internal source paths). Missing consumer-sim is a High finding.
+- **Exports match declared map** -- the test suite must verify that every entry in the exports map resolves to a real module with the expected exports. If this verification is missing, that is a Med finding.
+- **No internal path imports in tests** -- tests that import from `./src/internal/module` instead of the public API are testing implementation, not the contract. This is a Med finding unless the test explicitly targets internals as a regression guard.

package/pipeline/steps/critic/mcp-server.md

@@ -0,0 +1,24 @@
+# CRITIC Domain: MCP Server
+
+## Edge Cases
+
+MCP server implementations have protocol-specific failure modes. Hunt for these in addition to the general edge case checklist:
+
+- **Crash on malformed JSON** -- does the server survive receiving `{broken` or empty input on the transport? Or does it crash and kill the process?
+- **Mismatched response IDs** -- does the response `id` field always match the request `id`? Are notification messages (no `id`) handled correctly without sending a response?
+- **Missing isError on tool failure** -- when a tool handler throws or fails, does the result include `isError: true`? Or does it silently return a success-shaped response with error text in content?
+- **Schema declared but not validated** -- does the server declare an `inputSchema` for a tool but skip runtime validation? Send params that violate the schema and verify `-32602` is returned.
+- **Pre-initialize requests** -- what happens if a client sends `tools/list` or `tools/call` before `initialize`? The server should reject or handle gracefully, not crash or return stale data.
+- **Unhandled exceptions killing stdio** -- an unhandled throw in a handler can crash the process and sever the stdio pipe. Every handler must be in try-catch. Check for any handler that lacks error wrapping.
+- **Capability mismatch** -- capabilities declared in `initialize` response that have no corresponding implementation, or implemented features not declared in capabilities.
+- **Content type mismatch** -- tool declares it returns `text` content but actually returns a different type, or returns multiple content items when one is expected.
+
+## Test Review
+
+CRITIC reviews MCP-DEV test code with the same rigor as production code. In addition to the standard test review checklist:
+
+- **Real transport tested** -- tests must spawn a real server and communicate over the actual transport (stdio pipe, SSE, HTTP). Any test that mocks the transport layer is a High finding.
+- **Both error tiers tested** -- tests must cover JSON-RPC error codes (protocol tier) AND `isError: true` (tool tier). Missing either tier is a High finding.
+- **Every tool has a call test** -- every tool registered by the server must have at least one `tools/call` test with valid params. A missing tool test is a High finding.
+- **Initialize-first ordering** -- tests must send `initialize` before other requests. Tests that skip the handshake are testing undefined behavior.
+- **Schema violation tests** -- for every tool with an `inputSchema`, there must be a test sending invalid params and asserting `-32602`. Missing schema validation tests is a Med finding.

package/pipeline/steps/critic/mobile-app.md

@@ -0,0 +1,29 @@
+# CRITIC Domain: Mobile App Review
+
+**Applies to:** Stories where MOBILE is the implementing agent.
+
+## Edge Case Focus Areas
+
+In addition to the standard edge case hunt (Pass 2), scrutinize these mobile-specific risks:
+
+- **Hardcoded platform assumptions** — code that assumes Android-only or iOS-only without platform checks. `Platform.OS` / `Platform.select` (RN) or `dart:io Platform.isAndroid` (Flutter) must be used for divergent behavior. Any hardcoded platform assumption is a **Med** finding.
+- **Missing state isolation in Maestro flows** — flows that don't start with `clearState` or explicit app data clear. Any flow without state isolation is a **High** finding.
+- **Emulator-only code paths** — code that works on emulator but will fail on real devices. Common: `localhost` URLs instead of `10.0.2.2` for Android emulator API access, `127.0.0.1` instead of the machine's IP. Any hardcoded `localhost` or `127.0.0.1` in API base URLs is a **High** finding.
+- **Missing permission handling** — native features (camera, location, notifications, biometrics) used without permission request flows. The app must handle both grant and deny outcomes. Missing permission handling is a **High** finding.
+- **Navigation stack leaks** — screens pushed but never popped, leading to memory growth. Deep link handlers that don't reset the navigation stack are a **Med** finding. Verify that deep links use `reset` or `popToTop` + `navigate` pattern.
+- **Gesture conflict** — overlapping gesture handlers (e.g., swipe-to-delete conflicting with navigation swipe, scroll inside scroll). Any unhandled gesture conflict is a **Med** finding.
+- **Metro bundler dependency in production** — code that assumes Metro is running or references `__DEV__` without guards. Any dev-only code path reachable in production bundle is a **High** finding.
+- **Missing keyboard avoidance** — input screens that don't handle keyboard appearance (content hidden behind keyboard). Missing `KeyboardAvoidingView` (RN) or `resizeToAvoidBottomInset` (Flutter) for input screens is a **Med** finding.
+- **Unsafe area rendering** — content rendered under status bar, notch, or home indicator. Missing `SafeAreaView` (RN) or `SafeArea` (Flutter) on screen containers is a **Med** finding.
+- **Background/foreground state bugs** — app state corruption when returning from background. If the story involves data fetching, verify that stale data is refreshed on foreground. Missing foreground refresh for data screens is a **Low** finding.
+
+## Test Code Review Additions
+
+In addition to the standard test code review checklist:
+
+- **Maestro flow completeness** — every AC must have a corresponding Maestro flow. Missing flow for an AC is a **High** finding.
+- **State isolation verified** — every Maestro flow must start with `clearState` or explicit app data clear. Missing isolation is a **High** finding.
+- **Platform coverage** — if story specifies both-platform behavior, flows must cover both (or explicitly mark iOS as deferred with reason). Missing platform coverage without documented reason is a **Med** finding.
+- **No hardcoded waits in flows** — Maestro flows should use `assertVisible` / `waitForAnimationToEnd`, not `extendedWaitUntil` with fixed timeouts. Fixed timeouts in flows are a **Med** finding.
+- **Deep link flow coverage** — if reqs-brief specifies deep link URIs, at least one Maestro flow must test each URI via `openLink`. Missing deep link test is a **Med** finding.
+- **Unit test isolation** — unit tests must not depend on emulator state or Maestro. They run independently with mocked native modules where needed. Unit tests importing emulator-specific code is a **Med** finding.

package/pipeline/steps/data/estimate.md

@@ -0,0 +1,51 @@
+# Data Pipeline Estimation
+
+**Purpose:** Assign a Fibonacci story point estimate for data pipeline implementation complexity. This is a lightweight estimation step -- no code tools, no implementation. Read specs, assess complexity, output a number with rationale.
+
+**Fibonacci scale:** 1, 2, 3, 5, 8, 13, 21
+
+## Step 1: Read Groomed Specs
+
+Read and assess:
+- `{story_output_dir}/reqs-brief.md` -- REQUIRED
+- `{story_output_dir}/qa-test-spec.md` -- REQUIRED
+
+## Step 2: Assess Complexity Factors
+
+Evaluate each factor and record your assessment:
+
+| Factor | Assessment | Weight |
+|--------|-----------|--------|
+| **AC count and complexity** | How many ACs? Are conditions simple (read-and-write) or complex (multi-stage transforms, conditional logic, aggregations)? | High |
+| **New patterns vs established** | Greenfield pipeline vs incremental (add stage, add source)? | High |
+| **Data source complexity** | Number of sources, format diversity (CSV, JSON, Parquet, API), encoding issues, schema volatility? | Medium |
+| **Transform complexity** | Joins, aggregations, dedup logic, data type coercions, timezone handling, stateful transforms? | High |
+| **Data quality surface** | How many quality rules? Null handling, dedup, row count assertions, constraint enforcement? | Medium |
+| **Checkpoint/resume needs** | Does the pipeline need checkpoint/resume? How many stages? | Medium |
+| **Test complexity** | Idempotency tests, checkpoint/resume tests, large dataset edge cases, malformed input handling? | Medium |
+
+## Step 3: Select Fibonacci Value
+
+Map your assessment to the Fibonacci scale:
+
+| Points | Typical Data Pipeline Scope |
+|--------|---------------------------|
+| 1 | Config change, add column to existing stage, no new source |
+| 2 | Simple single-source ingest, trivial transform, basic output |
+| 3 | Standard ETL with one source, moderate transforms, quality rules |
+| 5 | Multi-source pipeline, joins, dedup, checkpoint, moderate test surface |
+| 8 | Complex transforms with aggregations, multiple quality rules, checkpoint/resume, cross-source joins |
+| 13 | Large pipeline spanning multiple domains, complex data model, extensive quality rules, full checkpoint/resume |
+| 21 | Epic-scale: new pipeline framework or major architectural change (consider splitting the story) |
+
+**Calibration context (if `{estimation_model}` is `calibrated`):**
+If calibration directives are provided in `{correction_directives}`, factor them into your estimate. These are learned patterns from prior sprints -- e.g., "multi-source joins consistently under-pointed by 1 tier" or "stories with 4+ transform stages average 8 points."
+
+## Step 4: Write Estimate
+
+Write to `{story_output_dir}/data-estimation.md` using `.valent-pipeline/templates/estimation.template.md`:
+- Fibonacci value with brief rationale (2-3 sentences)
+- Factor assessments from Step 2
+- Calibration adjustments applied (if any)
+
+Send: `[ESTIMATION] DATA estimates {story_id} at {points} points. See data-estimation.md.`

package/pipeline/steps/data/handoff.md

@@ -0,0 +1,9 @@
+# DATA Step: Handoff
+
+Read `.valent-pipeline/steps/common/distilled-handoff-format.md` before writing output.
+
+## Step 12: Write data-handoff.md
+Complete all sections of the handoff document using the template at `.valent-pipeline/templates/data-handoff.template.md`. Set `status: completed` in frontmatter. Notify lead via inbox: `[DONE] Data pipeline implementation complete. See data-handoff.md#orchestrator-summary.`
+
+## Independent Verification Requirement
+You must independently verify: all tests pass against the complete pipeline before marking your task complete. Do not rely on CRITIC or QA-B to catch your failures.

package/pipeline/steps/data/implement.md

@@ -0,0 +1,16 @@
+# DATA Step: Implement
+
+## Step 4: Data model / pipeline state schema
+Per reqs-brief: define or update the data model for pipeline inputs, outputs, and intermediate state. Define checkpoint state schema if the pipeline requires resume capability. Record in `data-handoff.md#pipeline-stages-implemented`.
+
+## Step 5: Ingestion layer (readers, parsers, encoding handling)
+Per reqs-brief: implement readers for each data source. Every file read must specify encoding explicitly (UTF-8 unless source requires otherwise). Parsers must handle malformed input gracefully -- log and skip bad records, never silently drop or crash. Record in `data-handoff.md#pipeline-stages-implemented`.
+
+## Step 6: Transform stages
+Per reqs-brief: implement each transform as a discrete, testable stage. Every filter or join that reduces row count MUST log: rows in, rows out, rows dropped, and drop reason. Silent data loss is a Critical defect. Record data quality rules in `data-handoff.md#data-quality-rules`. Record decisions in `data-handoff.md#implementation-decisions`.
+
+## Step 7: Output / sink layer (idempotent writes with natural keys)
+Per reqs-brief: implement writers for each data destination. All writes must be idempotent -- use natural keys or deterministic IDs so that re-running the pipeline with the same input produces identical results, not duplicates. Record in `data-handoff.md#pipeline-stages-implemented`.
+
+## Step 8: Checkpoint mechanism for resume after failure
+Per reqs-brief: implement checkpoint markers after each major stage. On failure, the pipeline must be able to resume from the last successful checkpoint rather than restarting from scratch. Record in `data-handoff.md#checkpointresume-design`.

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

@@ -0,0 +1,13 @@
+# DATA Step: Read Inputs
+
+## Step 1: Read reqs-brief.md
+Understand: acceptance criteria, business rules, data sources, data destinations, transform logic, data quality rules, encoding requirements, cross-cutting concerns (logging, retry, scheduling, etc.).
+
+## Step 2: Read qa-test-spec.md
+Understand: what tests to write for each AC, expected assertions, row count verification requirements, idempotency expectations, checkpoint/resume test cases, test case names and structure.
+
+## Step 3: Read correction directives
+Read `{correction_directives}`. Apply all directives targeting DATA. Note any conflicts with default behavior and follow the directive.
+
+## Step 3b: Query Knowledge Agent (Conditional)
+If a Knowledge Agent is available in the team config, send: `[KNOWLEDGE-QUERY] What codebase conventions, implementation patterns, and known pitfalls should I know? Context: I am DATA implementing {story_id} using {tech_stack.pipeline_framework} + {tech_stack.data_store}.` If no response within a reasonable time or no Knowledge Agent is spawned, proceed without.

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

@@ -0,0 +1,13 @@
+# DATA Step: Write Tests
+
+## Step 8: Write test code
+Satisfy qa-test-spec for each AC. Every test case named in qa-test-spec must have a corresponding test. Follow quality standards from the core prompt. Record in `data-handoff.md#test-files-written`.
+
+## Step 9: Verify idempotency
+Every pipeline write path must have an idempotency test: run the same input through the pipeline twice and assert that the output is identical -- no duplicate rows, no changed values, no side effects from the second run.
+
+## Step 10: Verify checkpoint/resume
+If the pipeline has checkpoint capability, test it: run the pipeline, simulate a failure mid-run (after at least one checkpoint), resume, and assert that the final output matches a clean full run. No data loss, no duplicates from partial + resumed execution.
+
+## Step 11: Run tests, verify all pass
+Run the full pipeline test suite. All tests must pass. Record results in `data-handoff.md#test-results-summary`. If tests fail, fix the code -- do not skip or weaken tests.

package/pipeline/steps/docgen/estimate.md

@@ -0,0 +1,49 @@
+# Document Generation Estimation
+
+**Purpose:** Assign a Fibonacci story point estimate for document generation implementation complexity. This is a lightweight estimation step -- no code tools, no implementation. Read specs, assess complexity, output a number with rationale.
+
+**Fibonacci scale:** 1, 2, 3, 5, 8, 13, 21
+
+## Step 1: Read Groomed Specs
+
+Read and assess:
+- `{story_output_dir}/reqs-brief.md` -- REQUIRED
+- `{story_output_dir}/qa-test-spec.md` -- REQUIRED
+
+## Step 2: Assess Complexity Factors
+
+Evaluate each factor and record your assessment:
+
+| Factor | Assessment | Weight |
+|--------|-----------|--------|
+| **Template count and complexity** | How many templates? Are they simple (static text + variable substitution) or complex (conditionals, loops, nested partials, dynamic sections)? | High |
+| **Variable schema complexity** | Simple flat variables vs deeply nested objects, arrays of objects, computed/derived values? | High |
+| **Output format count** | Single format vs multi-format (PDF + HTML + Markdown)? Each format adds rendering and validation complexity. | Medium |
+| **Asset dependencies** | No assets vs fonts/images/stylesheets that must be embedded or resolved? | Medium |
+| **Edge-case surface** | How hard will QA-B's test suite be to pass? Unicode, injection, null handling, large documents? | Medium |
+
+## Step 3: Select Fibonacci Value
+
+Map your assessment to the Fibonacci scale:
+
+| Points | Typical DOCGEN Scope |
+|--------|---------------------|
+| 1 | Single template, flat variables, one output format, no assets |
+| 2 | Simple template with conditionals, basic variable schema |
+| 3 | Standard template with loops/conditionals, multi-variable schema, single output format |
+| 5 | Multiple templates, nested variable schemas, 2+ output formats |
+| 8 | Complex templates with partials/inheritance, asset pipeline, multi-format output |
+| 13 | Large template system with dynamic sections, complex asset resolution, extensive edge-case surface |
+| 21 | Epic-scale: new template engine integration or major rendering pipeline change (consider splitting the story) |
+
+**Calibration context (if `{estimation_model}` is `calibrated`):**
+If calibration directives are provided in `{correction_directives}`, factor them into your estimate. These are learned patterns from prior sprints -- e.g., "multi-format stories consistently under-pointed by 1 tier" or "stories with asset dependencies average 8 points."
+
+## Step 4: Write Estimate
+
+Write to `{story_output_dir}/docgen-estimation.md` using `.valent-pipeline/templates/estimation.template.md`:
+- Fibonacci value with brief rationale (2-3 sentences)
+- Factor assessments from Step 2
+- Calibration adjustments applied (if any)
+
+Send: `[ESTIMATION] DOCGEN estimates {story_id} at {points} points. See docgen-estimation.md.`

package/pipeline/steps/docgen/handoff.md

@@ -0,0 +1,9 @@
+# DOCGEN Step: Handoff
+
+Read `.valent-pipeline/steps/common/distilled-handoff-format.md` before writing output.
+
+## Step 13: Write docgen-handoff.md
+Complete all sections of the handoff document using the template at `.valent-pipeline/templates/docgen-handoff.template.md`. Set `status: completed` in frontmatter. Notify lead via inbox: `[DONE] Document generation implementation complete. See docgen-handoff.md#orchestrator-summary.`
+
+## Independent Verification Requirement
+You must independently verify: all tests pass and all templates produce valid output in every declared format before marking your task complete. Do not rely on CRITIC to catch your failures.

package/pipeline/steps/docgen/implement.md

@@ -0,0 +1,19 @@
+# DOCGEN Step: Implement
+
+## Step 4: Plan implementation approach
+Order: template engine setup (auto-escape on) -> template definitions with variable schema -> render pipeline (validate -> substitute -> output) -> encoding (UTF-8) -> asset embedding/resolution. Identify cross-cutting concerns that span multiple templates.
+
+## Step 5: Set up template engine with auto-escaping
+Configure the template engine with auto-escaping enabled by default. Any raw/unescaped output must require explicit opt-in with a justifying comment. Record engine configuration in `docgen-handoff.md#implementation-decisions`.
+
+## Step 6: Implement template definitions with variable schema
+Per reqs-brief: define templates, declare all variables with types and required/optional status, implement conditional sections, loops, and partials. Record in `docgen-handoff.md#templates-implemented` and `docgen-handoff.md#variable-schema`.
+
+## Step 7: Implement render pipeline
+Build the render pipeline: validate all required variables are present and correctly typed before substitution -> substitute variables into templates -> generate output in the target format. Missing or null required variables must produce a clear error, never unsubstituted markers in output. Record in `docgen-handoff.md#implementation-decisions`.
+
+## Step 8: Implement encoding and output formatting
+All template reads and output writes must specify UTF-8 encoding explicitly. For large documents, use streaming render to avoid unbounded memory consumption. Record supported formats in `docgen-handoff.md#output-formats`.
+
+## Step 9: Implement asset embedding and resolution
+Per reqs-brief: resolve and embed fonts, images, stylesheets referenced by templates. Validate that all referenced assets exist at render time -- broken asset paths must produce a clear error. Record in `docgen-handoff.md#asset-dependencies`.