valent-pipeline 0.2.19 → 0.2.21

package/pipeline/task-graphs/mobile-app.yaml

@@ -0,0 +1,171 @@
+# Task graph template for mobile-app projects
+# Read by the Lead at kick-off to create tasks and wire dependencies.
+#
+# Variables resolved at runtime:
+#   {{story_id}} — current story identifier
+#   {{story_output_dir}} — resolved story output directory
+#   {{degraded_note}} — note about degraded inputs (UXA only)
+#
+# Conditional tasks:
+#   Tasks with `conditional` are only created when the condition is met.
+#   Tasks with `skip_when` are removed when the condition IS met.
+#   When a conditional/skipped task is removed, the Lead removes its ref from
+#   other tasks' blockedBy lists.
+
+project_type: "mobile-app"
+
+tasks:
+  - ref: reqs
+    agent: REQS
+    subject: "REQS: Analyze story and produce implementation brief"
+    description: "Read {{story_id}} story inputs, translate ACs into structured implementation brief (reqs-brief.md)."
+    activeForm: "REQS analyzing requirements"
+    blockedBy: []
+
+  - ref: uxa
+    agent: UXA
+    subject: "UXA: Translate requirements into screen/component specs"
+    description: "Read reqs-brief.md, produce uxa-spec.md with mobile screen and component specifications. {{degraded_note}}"
+    activeForm: "UXA writing component specs"
+    blockedBy: [reqs]
+    skip_when: "testing_profiles excludes ui"
+
+  - ref: qa_a
+    agent: QA-A
+    subject: "QA-A: Produce behavioral test specifications and Maestro flow specs"
+    description: "Read reqs-brief.md and uxa-spec.md, produce qa-test-spec.md with Maestro flow specifications."
+    activeForm: "QA-A writing test specifications"
+    blockedBy: [uxa]
+
+  - ref: readiness
+    agent: READINESS
+    subject: "READINESS: Validate specs are implementation-ready"
+    description: "Review reqs-brief.md, uxa-spec.md, qa-test-spec.md sequentially. Reject first failure or approve all. Route rejections to responsible agent."
+    activeForm: "READINESS reviewing pre-dev artifacts"
+    blockedBy: [qa_a]
+
+  - ref: bend
+    agent: BEND
+    subject: "BEND: Implement backend production code and tests"
+    description: "Read reqs-brief.md and qa-test-spec.md, implement backend, produce bend-handoff.md."
+    activeForm: "BEND implementing backend"
+    blockedBy: [readiness]
+    conditional: "testing_profiles includes api"
+
+  - ref: mobile
+    agent: MOBILE
+    subject: "MOBILE: Implement mobile screens, components, and Maestro flows"
+    description: "Read reqs-brief.md, uxa-spec.md, qa-test-spec.md, implement mobile app, run Maestro flows, produce mobile-handoff.md."
+    activeForm: "MOBILE implementing mobile app"
+    blockedBy: [readiness]
+
+  - ref: critic
+    agent: CRITIC
+    subject: "CRITIC: Adversarial code review"
+    description: "Read git-diff, reqs-brief.md, qa-test-spec.md. Run blind-hunt, edge-case-hunt, acceptance-audit, triage passes. Produce critic-review.md."
+    activeForm: "CRITIC reviewing code"
+    blockedBy: [bend, mobile]
+
+  - ref: qa_b
+    agent: QA-B
+    subject: "QA-B: Execute tests and file bugs"
+    description: "Read qa-test-spec.md, critic-review.md, reqs-brief.md. Run tests, produce execution-report.md, bugs.md, traceability-matrix.md."
+    activeForm: "QA-B executing tests"
+    blockedBy: [critic]
+
+  - ref: judge
+    agent: JUDGE
+    subject: "JUDGE: Bug review and ship decision"
+    description: "Review bugs.md for priority accuracy, then review execution-report.md, traceability-matrix.md, qa-test-spec.md. Approve (SHIP/SHIP-PARTIAL) or reject (REJECT)."
+    activeForm: "JUDGE reviewing evidence and making ship decision"
+    blockedBy: [qa_b]
+
+agents:
+  - name: Knowledge
+    ref: knowledge
+    wave: 1
+    prompt: .valent-pipeline/prompts/knowledge.md
+    trigger: "Begin startup immediately. No upstream dependency."
+    completion: "Send ready message to Lead. Then wait for [KNOWLEDGE-QUERY] messages."
+    cd_targets: []
+
+  # Wave 1: Spawn at kick-off (spec agents + first gate)
+  - name: REQS
+    ref: reqs
+    wave: 1
+    prompt: .valent-pipeline/prompts/reqs.md
+    trigger: "Begin immediately — no upstream dependency."
+    completion: "Send [HANDOFF] to Lead and UXA. Mark task completed."
+    cd_targets: [reqs]
+
+  - name: UXA
+    ref: uxa
+    wave: 1
+    prompt: .valent-pipeline/prompts/uxa.md
+    trigger: "Wait for [HANDOFF] from REQS. Begin when task is unblocked."
+    completion: "Send [HANDOFF] to Lead and QA-A. Mark task completed."
+    cd_targets: [uxa]
+
+  - name: QA-A
+    ref: qa_a
+    wave: 1
+    prompt: .valent-pipeline/prompts/qa-a.md
+    trigger: "Wait for [HANDOFF] from UXA. Begin when task is unblocked."
+    completion: "Send [HANDOFF] to Lead and READINESS. Mark task completed."
+    cd_targets: [qa-a]
+
+  - name: READINESS
+    ref: readiness
+    wave: 1
+    prompt: .valent-pipeline/prompts/readiness.md
+    trigger: "Wait for [HANDOFF] from QA-A. Begin when task is unblocked."
+    completion: "Send [READINESS-APPROVAL] to BEND and MOBILE, or [READINESS-REJECTION] to responsible agent. Mark task completed on approval."
+    cd_targets: [readiness]
+
+  # Wave 2: Spawn when QA-A completes (spin up while READINESS reviews)
+  - name: BEND
+    ref: bend
+    wave: 2
+    spawn_trigger: "qa_a completed"
+    prompt: .valent-pipeline/prompts/bend.md
+    trigger: "Begin immediately — you were spawned because QA-A completed. Wait for READINESS approval before starting implementation."
+    completion: "Send [HANDOFF] to Lead and CRITIC. Mark task completed."
+    cd_targets: [bend]
+
+  - name: MOBILE
+    ref: mobile
+    wave: 2
+    spawn_trigger: "qa_a completed"
+    prompt: .valent-pipeline/prompts/mobile.md
+    trigger: "Begin immediately — you were spawned because QA-A completed. Wait for READINESS approval before starting implementation. Coordinate with BEND on shared files if BEND is active."
+    completion: "Send [HANDOFF] to Lead and CRITIC. Mark task completed."
+    cd_targets: [mobile]
+
+  - name: CRITIC
+    ref: critic
+    wave: 2
+    spawn_trigger: "qa_a completed"
+    prompt: .valent-pipeline/prompts/critic.md
+    trigger: "Begin immediately — you were spawned because QA-A completed. Wait for [HANDOFF] from all active dev agents before starting review."
+    completion: "Send [HANDOFF] to Lead and QA-B. Mark task completed."
+    cd_targets: [critic]
+
+  # Wave 3: Spawn when CRITIC starts (spin up while CRITIC reviews)
+  - name: QA-B
+    ref: qa_b
+    wave: 3
+    spawn_trigger: "critic in_progress"
+    prompt: .valent-pipeline/prompts/qa-b.md
+    trigger: "Begin immediately — you were spawned because CRITIC started reviewing. Wait for CRITIC to complete before executing tests."
+    completion: "Send [HANDOFF] to Lead and JUDGE. Mark task completed."
+    cd_targets: [qa-b, judge]
+
+  # Wave 3: Also spawn JUDGE when CRITIC starts (alongside QA-B)
+  - name: JUDGE
+    ref: judge
+    wave: 3
+    spawn_trigger: "critic in_progress"
+    prompt: .valent-pipeline/prompts/judge.md
+    trigger: "Begin immediately — you were spawned because CRITIC started reviewing. Wait for QA-B to complete before starting bug review."
+    completion: "Send [JUDGE-SHIP], [JUDGE-SHIP-PARTIAL], or [JUDGE-REJECT] to Lead. Mark task completed."
+    cd_targets: [judge]

package/pipeline/templates/bugs.template.md

@@ -1,5 +1,5 @@
 # bugs
-<!-- Template version: 1.0 | Used by: QA-B | Read by: BEND, FEND, JUDGE (Pass 2) -->
+<!-- Template version: 1.0 | Used by: QA-B | Read by: BEND, FEND, DATA, MCP-DEV, LIBDEV, DOCGEN, IAC, JUDGE (Pass 2) -->
 
 ---
 agent: qa-b

package/pipeline/templates/critic-review.template.md

@@ -1,5 +1,5 @@
 # critic-review
-<!-- Template version: 1.0 | Used by: CRITIC | Read by: BEND, FEND, QA-B -->
+<!-- Template version: 1.0 | Used by: CRITIC | Read by: BEND, FEND, DATA, MCP-DEV, LIBDEV, DOCGEN, IAC, QA-B -->
 
 ---
 agent: critic

package/pipeline/templates/data-handoff.template.md

@@ -0,0 +1,96 @@
+# data-handoff
+<!-- Template version: 1.0 | Used by: DATA | Read by: CRITIC, QA-B -->
+
+---
+agent: {agent-name}
+story: {story-id}
+status: {in_progress | completed}
+stepsCompleted: []
+pendingSteps: []
+lastCheckpoint: {ISO-8601 timestamp}
+inputsRead: []
+outputsWritten: []
+blockers: []
+---
+
+## Orchestrator Summary -- required
+- **Agent:** {agent-name}
+- **Story:** {story-id}
+- **Verdict:** {pass | fail | needs-review}
+- **State transition:** {from-phase} -> {to-phase}
+- **Files created/modified:** {list of file paths}
+- **Flags:** {alerts for downstream agents, or "none"}
+
+## Files Created/Modified -- required
+<!-- All production and test files created or modified, with purpose. -->
+
+| File | Action | Purpose |
+|------|--------|---------|
+| {file-path} | {created \| modified} | {one-line description} |
+
+## Pipeline Stages Implemented -- required
+<!-- Every pipeline stage implemented in this story. CRITIC and QA-B use this to validate coverage and data flow. -->
+
+| Stage | Input | Transform | Output | Row Count Change |
+|-------|-------|-----------|--------|-----------------|
+| {stage-name} | {input source/format} | {transform description} | {output target/format} | {e.g., 1000 -> 950 (-50 filtered)} |
+
+## Data Quality Rules -- required
+<!-- All data quality rules enforced by this pipeline. -->
+
+| Rule | Stage | Description | Action on Violation |
+|------|-------|-------------|-------------------|
+| {rule-name} | {stage} | {what is checked} | {drop row \| reject batch \| default value \| log warning} |
+
+### Row Count Assertions
+<!-- Expected row count behavior at each stage boundary. -->
+
+- **Stage:** {stage-name}
+  - Input rows: {count or formula}
+  - Output rows: {count or formula}
+  - Drop reason: {why rows are removed, or "none"}
+
+### Null Handling
+<!-- How nulls are handled for each critical field. -->
+
+- **Field:** {field-name}
+  - Null strategy: {reject \| default to X \| propagate \| coalesce}
+
+### Dedup Rules
+<!-- Deduplication strategy if applicable. -->
+
+- **Dedup key:** {field(s) forming the natural key}
+- **Strategy:** {keep first \| keep last \| merge}
+
+## Checkpoint/Resume Design -- conditional
+<!-- Only include if pipeline has checkpoint/resume capability. -->
+
+| Checkpoint | Location | Trigger | Resume Behavior |
+|-----------|----------|---------|----------------|
+| {checkpoint-name} | {where state is stored} | {after stage X completes} | {resume from stage X+1 with saved state} |
+
+## Test Files Written -- required
+<!-- All test files created or modified, mapped to the spec cases they satisfy. -->
+
+| Test File | Test Cases | Spec Reference |
+|-----------|-----------|----------------|
+| {file-path} | {list of test case names} | `qa-test-spec.md#{ac-id}` |
+
+## Test Results Summary -- required
+<!-- Aggregate results from running the pipeline test suite. -->
+
+| Suite | Total | Passed | Failed | Skipped | Duration |
+|-------|-------|--------|--------|---------|----------|
+| {suite-name} | {count} | {count} | {count} | {count} | {duration} |
+
+## Implementation Decisions -- required
+<!-- Key decisions made during implementation. Each entry: decision, rationale, alternatives rejected. -->
+
+- **Decision:** {what was decided}
+  - **Rationale:** {why}
+  - **Rejected:** {alternatives considered and why they lost}
+
+## Cross-References -- required
+<!-- Explicit pointers to upstream artifacts consumed. -->
+- Reqs brief: `reqs-brief.md#{section}`
+- Test spec: `qa-test-spec.md#{section}`

package/pipeline/templates/docgen-handoff.template.md

@@ -0,0 +1,83 @@
+# docgen-handoff
+<!-- Template version: 1.0 | Used by: DOCGEN | Read by: CRITIC, QA-B -->
+
+---
+agent: {agent-name}
+story: {story-id}
+status: {in_progress | completed}
+stepsCompleted: []
+pendingSteps: []
+lastCheckpoint: {ISO-8601 timestamp}
+inputsRead: []
+outputsWritten: []
+blockers: []
+---
+
+## Orchestrator Summary -- required
+- **Agent:** {agent-name}
+- **Story:** {story-id}
+- **Verdict:** {pass | fail | needs-review}
+- **State transition:** {from-phase} -> {to-phase}
+- **Files created/modified:** {list of file paths}
+- **Flags:** {alerts for downstream agents, or "none"}
+
+## Files Created/Modified -- required
+<!-- All production and test files created or modified, with purpose. -->
+
+| File | Action | Purpose |
+|------|--------|---------|
+| {file-path} | {created \| modified} | {one-line description} |
+
+## Templates Implemented -- required
+<!-- Every template implemented in this story. CRITIC and QA-B use this to validate coverage and correctness. -->
+
+| Template Name | Variables (with types) | Output Format | Description |
+|---------------|----------------------|---------------|-------------|
+| {template-name} | {var: type, var: type, ...} | {PDF \| HTML \| Markdown \| ...} | {one-line description} |
+
+## Variable Schema -- required
+<!-- Input data contract per template. Every variable, its type, whether required/optional, and default value if any. -->
+
+| Template | Variable | Type | Required | Default | Description |
+|----------|----------|------|----------|---------|-------------|
+| {template-name} | {variable-name} | {string \| number \| boolean \| array \| object} | {yes \| no} | {default or "none"} | {one-line description} |
+
+## Output Formats -- required
+<!-- All supported output types, their MIME types, and any format-specific notes. -->
+
+| Format | MIME Type | Notes |
+|--------|----------|-------|
+| {PDF \| HTML \| Markdown \| ...} | {application/pdf \| text/html \| text/markdown \| ...} | {encoding, compression, or other format-specific details} |
+
+## Asset Dependencies -- conditional
+<!-- Only include if templates reference external assets (fonts, images, stylesheets). -->
+
+| Asset | Type | Path/URL | Required By |
+|-------|------|----------|-------------|
+| {asset-name} | {font \| image \| stylesheet} | {file path or URL} | {template-name} |
+
+## Test Files Written -- required
+<!-- All test files created or modified, mapped to the spec cases they satisfy. -->
+
+| Test File | Test Cases | Spec Reference |
+|-----------|-----------|----------------|
+| {file-path} | {list of test case names} | `qa-test-spec.md#{ac-id}` |
+
+## Test Results Summary -- required
+<!-- Aggregate results from running the test suite. -->
+
+| Suite | Total | Passed | Failed | Skipped | Duration |
+|-------|-------|--------|--------|---------|----------|
+| {suite-name} | {count} | {count} | {count} | {count} | {duration} |
+
+## Implementation Decisions -- required
+<!-- Key decisions made during implementation. Each entry: decision, rationale, alternatives rejected. -->
+
+- **Decision:** {what was decided}
+  - **Rationale:** {why}
+  - **Rejected:** {alternatives considered and why they lost}
+
+## Cross-References -- required
+<!-- Explicit pointers to upstream artifacts consumed. -->
+- Reqs brief: `reqs-brief.md#{section}`
+- Test spec: `qa-test-spec.md#{section}`

package/pipeline/templates/iac-handoff.template.md

@@ -0,0 +1,83 @@
+# iac-handoff
+<!-- Template version: 1.0 | Used by: IAC | Read by: CRITIC, QA-B -->
+
+---
+agent: {agent-name}
+story: {story-id}
+status: {in_progress | completed}
+stepsCompleted: []
+pendingSteps: []
+lastCheckpoint: {ISO-8601 timestamp}
+inputsRead: []
+outputsWritten: []
+blockers: []
+---
+
+## Orchestrator Summary -- required
+- **Agent:** {agent-name}
+- **Story:** {story-id}
+- **Verdict:** {pass | fail | needs-review}
+- **State transition:** {from-phase} -> {to-phase}
+- **Files created/modified:** {list of file paths}
+- **Flags:** {alerts for downstream agents, or "none"}
+
+## Files Created/Modified -- required
+<!-- All production and test files created or modified, with purpose. -->
+
+| File | Action | Purpose |
+|------|--------|---------|
+| {file-path} | {created \| modified} | {one-line description} |
+
+## Resources Provisioned -- required
+<!-- Every infrastructure resource created or modified in this story. -->
+
+| Resource Type | Name | Provider | Purpose |
+|---------------|------|----------|---------|
+| {resource-type} | {resource-name} | {provider} | {one-line description} |
+
+## State Management -- required
+<!-- Remote state backend and locking configuration. -->
+
+- **Backend:** {state backend type, e.g., S3+DynamoDB, Azure Blob, GCS}
+- **Locking mechanism:** {DynamoDB, Blob lease, GCS object lock, etc.}
+- **State file path:** {key/path in remote backend}
+
+## IAM/Security -- required
+<!-- Roles, policies, and security configurations created. -->
+
+| Role/Policy | Resource | Actions | Scope | Least-Privilege Verification |
+|-------------|----------|---------|-------|------------------------------|
+| {role-or-policy-name} | {target-resource} | {allowed-actions} | {scope/arn} | {verified: yes/no + rationale} |
+
+## Environment Configuration -- conditional
+<!-- Only include if environment variables, secrets references, or connection strings were configured -->
+
+| Config Key | Source | Type | Consuming Service |
+|------------|--------|------|-------------------|
+| {env-var-or-key} | {secret manager ref, parameter store, etc.} | {env-var \| secret \| connection-string} | {service-name} |
+
+## Test Files Written -- required
+<!-- All test files created or modified, mapped to the spec cases they satisfy. -->
+
+| Test File | Test Cases | Spec Reference |
+|-----------|-----------|----------------|
+| {file-path} | {list of test case names} | `qa-test-spec.md#{ac-id}` |
+
+## Test Results Summary -- required
+<!-- Aggregate results from running the infrastructure test suite. -->
+
+| Suite | Total | Passed | Failed | Skipped | Duration |
+|-------|-------|--------|--------|---------|----------|
+| {suite-name} | {count} | {count} | {count} | {count} | {duration} |
+
+## Implementation Decisions -- required
+<!-- Key decisions made during implementation. Each entry: decision, rationale, alternatives rejected. -->
+
+- **Decision:** {what was decided}
+  - **Rationale:** {why}
+  - **Rejected:** {alternatives considered and why they lost}
+
+## Cross-References -- required
+<!-- Explicit pointers to upstream artifacts consumed. -->
+- Reqs brief: `reqs-brief.md#{section}`
+- Test spec: `qa-test-spec.md#{section}`

package/pipeline/templates/judge-decision.template.md

@@ -33,6 +33,7 @@ blockers: []
 | Traceability matrix complete — no uncovered ACs | {PASS \| FAIL} | {coverage percentage, gap count} |
 | PMCP screenshot evidence present | {PASS \| FAIL \| N/A} | {checkpoint count, any missing} |
 | Bug review approved | {PASS \| FAIL} | {detail} |
+| Platform coverage complete | {PASS \| FAIL \| PARTIAL} | {Android: {result}, iOS: {result or "deferred"}} |
 
 ## Socratic Validation -- required
 <!-- "Does this test actually prove what it claims? Could this screenshot show a passing state that masks a broken state? Does 'all tests green' mean 'all specified tests green' or could tests have been removed?" -->
@@ -43,10 +44,19 @@ blockers: []
 
 ## Verdict -- required
 
-- **Decision:** {SHIP | REJECT}
+- **Decision:** {SHIP | SHIP-PARTIAL | REJECT}
 - **Rationale:** {1-3 sentences justifying the decision}
 - **Confidence:** {high | medium | low}
 
+### SHIP-PARTIAL Detail -- conditional
+<!-- Only include if verdict is SHIP-PARTIAL (mobile-app with deferred iOS tests) -->
+
+- **Platforms shipped:** {Android}
+- **Platforms deferred:** {iOS}
+- **Deferred test count:** {count}
+- **Deferred flow files:** {list of flow file paths}
+- **Resolution:** Run `/run-deferred-tests {story_id}` on a Mac host
+
 ### Rejection Detail -- conditional
 <!-- Only include if verdict is REJECT -->
 

package/pipeline/templates/libdev-handoff.template.md

@@ -0,0 +1,82 @@
+# libdev-handoff
+<!-- Template version: 1.0 | Used by: LIBDEV | Read by: CRITIC, QA-B -->
+
+---
+agent: {agent-name}
+story: {story-id}
+status: {in_progress | completed}
+stepsCompleted: []
+pendingSteps: []
+lastCheckpoint: {ISO-8601 timestamp}
+inputsRead: []
+outputsWritten: []
+blockers: []
+---
+
+## Orchestrator Summary -- required
+- **Agent:** {agent-name}
+- **Story:** {story-id}
+- **Verdict:** {pass | fail | needs-review}
+- **State transition:** {from-phase} -> {to-phase}
+- **Files created/modified:** {list of file paths}
+- **Flags:** {alerts for downstream agents, or "none"}
+
+## Files Created/Modified -- required
+<!-- All production and test files created or modified, with purpose. -->
+
+| File | Action | Purpose |
+|------|--------|---------|
+| {file-path} | {created \| modified} | {one-line description} |
+
+## Public API Surface -- required
+<!-- Every public export implemented in this story. CRITIC and QA-B use this to validate coverage and contracts. -->
+
+| Export Name | Type/Signature | Module Path | Usage Example |
+|-------------|---------------|-------------|---------------|
+| {export-name} | {type or function signature} | {module path in exports map} | {one-line usage} |
+
+## Package Configuration -- required
+<!-- Exports map, entry points, and packaging metadata. -->
+
+- **Exports map:**
+  ```json
+  {exports field from package.json / pyproject.toml / Cargo.toml}
+  ```
+- **Entry points:**
+  - main: {CJS entry point or "n/a"}
+  - module: {ESM entry point or "n/a"}
+  - types: {type declarations entry point or "n/a"}
+- **sideEffects:** {true | false | list of files with side effects}
+
+## Breaking Changes -- conditional
+<!-- Only include if this story introduces breaking changes to the public API. -->
+
+| Change | Before | After | Semver Impact |
+|--------|--------|-------|---------------|
+| {removed/renamed export or signature change} | {previous API} | {new API} | {major \| minor \| patch} |
+
+## Test Files Written -- required
+<!-- All test files created or modified, mapped to the spec cases they satisfy. -->
+
+| Test File | Test Cases | Spec Reference |
+|-----------|-----------|----------------|
+| {file-path} | {list of test case names} | `qa-test-spec.md#{ac-id}` |
+
+## Test Results Summary -- required
+<!-- Aggregate results from running the library test suite. -->
+
+| Suite | Total | Passed | Failed | Skipped | Duration |
+|-------|-------|--------|--------|---------|----------|
+| {suite-name} | {count} | {count} | {count} | {count} | {duration} |
+
+## Implementation Decisions -- required
+<!-- Key decisions made during implementation. Each entry: decision, rationale, alternatives rejected. -->
+
+- **Decision:** {what was decided}
+  - **Rationale:** {why}
+  - **Rejected:** {alternatives considered and why they lost}
+
+## Cross-References -- required
+<!-- Explicit pointers to upstream artifacts consumed. -->
+- Reqs brief: `reqs-brief.md#{section}`
+- Test spec: `qa-test-spec.md#{section}`

package/pipeline/templates/mcp-dev-handoff.template.md

@@ -0,0 +1,87 @@
+# mcp-dev-handoff
+<!-- Template version: 1.0 | Used by: MCP-DEV | Read by: CRITIC, QA-B -->
+
+---
+agent: {agent-name}
+story: {story-id}
+status: {in_progress | completed}
+stepsCompleted: []
+pendingSteps: []
+lastCheckpoint: {ISO-8601 timestamp}
+inputsRead: []
+outputsWritten: []
+blockers: []
+---
+
+## Orchestrator Summary -- required
+- **Agent:** {agent-name}
+- **Story:** {story-id}
+- **Verdict:** {pass | fail | needs-review}
+- **State transition:** {from-phase} -> {to-phase}
+- **Files created/modified:** {list of file paths}
+- **Flags:** {alerts for downstream agents, or "none"}
+
+## Files Created/Modified -- required
+<!-- All production and test files created or modified, with purpose. -->
+
+| File | Action | Purpose |
+|------|--------|---------|
+| {file-path} | {created \| modified} | {one-line description} |
+
+## Tools Implemented -- required
+<!-- Every MCP tool implemented in this story. CRITIC and QA-B use this to validate coverage and schema compliance. -->
+
+| Tool Name | Description | inputSchema | Output Content Types |
+|-----------|-------------|-------------|---------------------|
+| {tool-name} | {one-line description} | {JSON Schema summary or pointer to code} | {text \| image \| resource \| embedded-resource} |
+
+## Capabilities Declared -- required
+<!-- What the server advertises in the initialize response. Must match actual implementation. -->
+
+- **Server name:** {server-name}
+- **Server version:** {version}
+- **Capabilities:**
+  - {capability}: {details}
+
+## Error Model -- required
+<!-- Two-tier error model: protocol errors vs tool failures. -->
+
+### Protocol Errors (JSON-RPC codes)
+| Code | Meaning | When Returned |
+|------|---------|---------------|
+| -32700 | Parse error | Malformed JSON received |
+| -32600 | Invalid request | Missing required JSON-RPC fields |
+| -32601 | Method not found | Unknown JSON-RPC method |
+| -32602 | Invalid params | Tool input fails schema validation |
+| -32603 | Internal error | Unhandled server exception |
+
+### Tool Failures (isError: true)
+| Tool | Failure Condition | Error Message Pattern |
+|------|-------------------|----------------------|
+| {tool-name} | {condition} | {message pattern} |
+
+## Test Files Written -- required
+<!-- All test files created or modified, mapped to the spec cases they satisfy. -->
+
+| Test File | Test Cases | Spec Reference |
+|-----------|-----------|----------------|
+| {file-path} | {list of test case names} | `qa-test-spec.md#{ac-id}` |
+
+## Test Results Summary -- required
+<!-- Aggregate results from running the test suite. -->
+
+| Suite | Total | Passed | Failed | Skipped | Duration |
+|-------|-------|--------|--------|---------|----------|
+| {suite-name} | {count} | {count} | {count} | {count} | {duration} |
+
+## Implementation Decisions -- required
+<!-- Key decisions made during implementation. Each entry: decision, rationale, alternatives rejected. -->
+
+- **Decision:** {what was decided}
+  - **Rationale:** {why}
+  - **Rejected:** {alternatives considered and why they lost}
+
+## Cross-References -- required
+<!-- Explicit pointers to upstream artifacts consumed. -->
+- Reqs brief: `reqs-brief.md#{section}`
+- Test spec: `qa-test-spec.md#{section}`