valent-pipeline 0.2.19 → 0.2.21

package/pipeline/docs/design/refactor-checklist.md

@@ -0,0 +1,111 @@
+# Pipeline Refactor Checklist
+
+When making design changes to the pipeline (new agents, renamed agents, new config sections, new features), check every location below. This list was built from the v0.2.0 sprint planning implementation where multiple locations were missed on the first pass.
+
+---
+
+## Agent Roster Changes (add/remove/rename agents)
+
+### Prompts & Steps
+- [ ] `pipeline/prompts/{agent}.md` — create or update the agent prompt
+- [ ] `pipeline/steps/{agent}/` — create or update step files
+- [ ] `pipeline/prompts/lead.md` — story execution sequence, canonical task order, gate rejection routing, phased spawning waves, phase timing notes, monitoring protocol
+- [ ] `pipeline/steps/orchestration/adopt-lead-and-create-team.md` — wave spawn table, spawn instructions
+- [ ] Other agent prompts that reference the changed agent (trigger protocol, handoff targets, rejection sources) — grep for the old name across all `pipeline/prompts/*.md`
+
+### Task Graphs
+- [ ] All 7 task graphs in `pipeline/task-graphs/*.yaml` — tasks section AND agents section
+- [ ] Verify wave count is consistent across all 7 files
+
+### Templates
+- [ ] `pipeline/templates/` — every template has a `Read by:` header and cross-references section listing agents. Grep all templates for old agent names
+- [ ] Create new templates for new agent outputs
+- [ ] Delete old templates for removed agents
+
+### Manifest & Config
+- [ ] `pipeline/agents-manifest.yaml` — add/remove/update agent entries
+- [ ] `src/lib/config-schema.js` — model tier defaults (which agents are opus/sonnet/haiku)
+
+### Scripts & Commands
+- [ ] `pipeline/scripts/embed-sqlite.ts` — artifact map (filename → agent mapping)
+- [ ] `src/commands/db-rebuild.js` — ARTIFACT_MAP (same mapping)
+
+### Documentation
+- [ ] `pipeline/docs/agent-reference.md` — agent roster table
+- [ ] `pipeline/docs/pipeline-overview.md` — flow diagrams, agent descriptions
+- [ ] `pipeline/docs/task-graph.md` — default chains, per-project-type chains, rejection scenarios
+- [ ] `pipeline/docs/lead-lifecycle.md` — phase descriptions, rejection loop map, ship sequence
+- [ ] `pipeline/docs/communication-standard.md` — agent name in frontmatter enum, Design Council examples
+- [ ] `pipeline/docs/pipeline-state-schema.md` — status enums, phase descriptions
+- [ ] `pipeline/docs/template-skeleton.md` — template inventory, consumer lists
+
+### Skills
+- [ ] `skills/valent-run-story/SKILL.md` — agent flow references, context variables
+- [ ] `skills/valent-run-epic/SKILL.md` — agent flow references, sprint loop steps
+- [ ] `skills/valent-run-project/SKILL.md` — agent flow references, sprint loop steps
+- [ ] `skills/valent-run-retrospective/SKILL.md` — artifact filenames for story detection
+- [ ] `skills/valent-help/SKILL.md` — pipeline flow descriptions
+- [ ] `skills/valent-configure/SKILL.md` — model tier table
+- [ ] `skills/valent-setup-backlog/SKILL.md` — next steps / run commands
+
+### Orchestration Steps
+- [ ] `pipeline/steps/orchestration/update-backlog-status.md` — agent references in status transitions
+- [ ] `pipeline/steps/orchestration/adopt-lead-and-create-team.md` — wave spawn table
+- [ ] `pipeline/steps/retrospective/analyze.md` — gate rejection analysis agent names
+- [ ] `pipeline/steps/retrospective/directives.md` — directive target agents
+
+---
+
+## New Config Sections
+
+- [ ] `src/lib/config-schema.js` — validation rules AND defaults object
+- [ ] `src/commands/init.js` — `generateConfigYaml()` template AND `runWizard()` prompts
+- [ ] `src/commands/upgrade.js` — config migration for existing installs
+- [ ] `skills/valent-configure/SKILL.md` — new step in wizard + reconfiguration mode awareness
+- [ ] `pipeline/prompts/lead.md` — context variables section (add new `{variable}` entries)
+
+---
+
+## New SQLite Tables
+
+- [ ] `src/lib/db.js` — `SCHEMA_DDL` constant (authoritative source for all tables, indexes, FTS5, triggers)
+- [ ] `pipeline/scripts/db-bootstrap.ts` — `SCHEMA_DDL` constant (TypeScript copy, must match `src/lib/db.js`)
+- [ ] `pipeline/docs/knowledge-system.md` — if the table is queried by Knowledge
+
+---
+
+## New Status Values
+
+- [ ] `pipeline/prompts/lead.md` — Story Status Tracking table, status transitions diagram
+- [ ] `pipeline/docs/pipeline-state-schema.md` — status enum in backlog entry fields
+- [ ] `pipeline/templates/sprint-status.template.yaml` — status_labels lookup
+- [ ] `pipeline/docs/design/sprint-planning-and-sizing.md` — design doc status table (if maintaining)
+
+---
+
+## New Orchestration Phases (e.g., sprint loop steps)
+
+- [ ] `pipeline/steps/orchestration/sprint-*.md` — create step files
+- [ ] `pipeline/prompts/lead.md` — reference new steps in Sprint Mode section
+- [ ] `skills/valent-run-epic/SKILL.md` — wire steps into the sprint loop
+- [ ] `skills/valent-run-project/SKILL.md` — wire steps into the sprint loop
+- [ ] `pipeline/docs/pipeline-state-schema.md` — new phase values for crash recovery
+
+---
+
+## Verification
+
+After all changes, run these greps to catch stragglers:
+
+```bash
+# Replace OLD_NAME with the old agent/feature name
+grep -ri "OLD_NAME" valent-pipeline/pipeline/ valent-pipeline/skills/ valent-pipeline/src/
+
+# Verify zero hits (excluding files being deleted)
+```
+
+Check that no file references a deleted file:
+```bash
+# List all .md file references and verify targets exist
+grep -roh '[a-z-]*.md' valent-pipeline/pipeline/prompts/ | sort -u
+```

package/pipeline/docs/index.md

@@ -0,0 +1,60 @@
+# Pipeline Documentation Index
+
+Reference documentation for the valent-pipeline multi-agent AI SDLC system.
+
+## Reference
+
+Core documentation for understanding and operating the pipeline.
+
+| Document | Description |
+|---|---|
+| [Pipeline Overview](pipeline-overview.md) | What the pipeline is, what it consumes and produces, end-to-end flow, key concepts |
+| [Agent Reference](agent-reference.md) | All 15+ agents: roles, models, inputs, outputs, project-type selection |
+| [Communication Standard](communication-standard.md) | Distilled handoff format, inbox message types, Design Council protocol, human escalation |
+| [Lead Lifecycle](lead-lifecycle.md) | Three-phase lifecycle (kick-off, monitor, ship), rejection loops, backlog management, crash recovery |
+| [Task Graph Specification](task-graph.md) | How the lead builds dependency graphs from the manifest, task states, claiming protocol, rejection re-queue |
+| [Pipeline State Schema](pipeline-state-schema.md) | JSON schema for pipeline-state.json -- crash recovery, backlog, sprint state |
+| [Knowledge System](knowledge-system.md) | Correction directives, curated knowledge, ChromaDB RAG, retrospective curation flow |
+| [Template Skeleton](template-skeleton.md) | Universal structure for all 27 handoff templates -- frontmatter, orchestrator summary, required/conditional sections |
+
+## Operations
+
+Guides for installation, packaging, and maintenance.
+
+| Document | Description |
+|---|---|
+| [NPX Packaging](npx-packaging.md) | File classification (infrastructure vs project-specific vs runtime), init workflow, version management |
+| [NPX Implementation Plan](npx-implementation-plan.md) | Step-by-step build plan for the npm package |
+| [Lean Spawn & Human Tasks](lean-spawn-human-tasks.md) | Optimization phases, SQLite validation tasks, NPX setup tasks |
+
+## Design
+
+Design documents for pipeline extensions and architectural decisions.
+
+| Document | Description |
+|---|---|
+| [Refactor Checklist](design/refactor-checklist.md) | Every location to update when changing agents, config, tables, statuses, or phases |
+
+## Quick Navigation
+
+### By Role
+
+- **New to the pipeline?** Start with [Pipeline Overview](pipeline-overview.md), then [Agent Reference](agent-reference.md)
+- **Configuring a project?** See the [README](../../README.md) configuration section, then [NPX Packaging](npx-packaging.md)
+- **Adding or changing agents?** Read [Refactor Checklist](design/refactor-checklist.md) first, then [Agent Reference](agent-reference.md) and [Task Graph Specification](task-graph.md)
+- **Debugging a stuck pipeline?** Check [Lead Lifecycle](lead-lifecycle.md) sections on stall detection, rejection loops, and crash recovery
+- **Understanding the knowledge system?** Read [Knowledge System](knowledge-system.md) for correction directives, curation, and RAG assessment
+- **Writing or modifying templates?** Consult [Template Skeleton](template-skeleton.md) for the universal structure
+
+### By File
+
+| File | Documentation |
+|---|---|
+| `agents-manifest.yaml` | [Agent Reference](agent-reference.md) |
+| `pipeline-config.yaml` | [README](../../README.md#configuration) |
+| `pipeline-state.json` | [Pipeline State Schema](pipeline-state-schema.md) |
+| `prompts/*.md` | [Agent Reference](agent-reference.md) |
+| `templates/*.md` | [Template Skeleton](template-skeleton.md) |
+| `task-graphs/*.yaml` | [Task Graph Specification](task-graph.md) |
+| `steps/**/*.md` | Individual agent prompts reference their step files |
+| `knowledge/` | [Knowledge System](knowledge-system.md) |

package/pipeline/docs/lead-lifecycle.md

@@ -71,7 +71,7 @@ The lead watches the board, not the work. It reads the shared task list to track
 
 ### Heartbeat Timer
 
-At the start of Phase 2, the lead creates a `CronCreate` job that fires every 4 minutes (aligned within Claude's 5-minute prompt cache TTL for near-zero token cost). Each heartbeat triggers a liveness check: call `TaskList`, verify at least one non-Knowledge agent is `in_progress`. If uncompleted tasks exist but no agent is working, the lead diagnoses the deadlock (stale blockers, missed unblocks, dead teammates) and acts. The cron job is deleted during Phase 3 teardown.
+At the start of Phase 2, the lead creates a `CronCreate` job that fires every 4 minutes (aligned within Claude's 5-minute prompt cache TTL for near-zero token cost). Each heartbeat triggers a liveness check: call `TaskList`, verify at least one non-Knowledge agent is `in_progress`. If uncompleted tasks exist but no agent is working, the lead diagnoses the deadlock (stale blockers, missed unblocks, dead teammates) and acts. A separate 4-minute keep-alive ping is created for the Knowledge agent to prevent its prompt cache from expiring during idle periods. Both cron jobs are deleted during Phase 3 teardown.
 
 ### What the Lead Watches
 

package/pipeline/docs/pipeline-overview.md

@@ -167,8 +167,12 @@ stories/
 
 ## Further Reading
 
+- [Documentation Index](index.md) -- Full index of all pipeline documentation
 - [Agent Reference](agent-reference.md) -- Every agent's role, inputs, outputs, and model tier
 - [Communication Standard](communication-standard.md) -- Handoff format, inbox protocol, Design Council, escalation
 - [Knowledge System](knowledge-system.md) -- RAG assessment, correction directives, curation flow
 - [Lead Lifecycle](lead-lifecycle.md) -- Kick-off, monitoring, ship, crash recovery
 - [Task Graph](task-graph.md) -- Dependency resolution, task states, claiming protocol
+- [Pipeline State Schema](pipeline-state-schema.md) -- JSON schema for crash recovery and backlog state
+- [Template Skeleton](template-skeleton.md) -- Universal handoff document structure
+- [Refactor Checklist](design/refactor-checklist.md) -- Every location to update when changing the pipeline

package/pipeline/prompts/bend.md

@@ -38,17 +38,11 @@ Write `bend-handoff.md` using the template at `.valent-pipeline/templates/bend-h
 
 ## Quality Standards
 
-These are non-negotiable. CRITIC and QA-B enforce them.
-
-- **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`.
-- **API-first setup** -- never use UI for test precondition setup. Seed via API calls or direct database insertion.
-- **Zero mocks** -- tests hit real infrastructure. No mocking databases, APIs, or external services.
+Read `.valent-pipeline/steps/common/quality-standards.md` for universal standards enforced by CRITIC and QA-B.
+
+Additional BEND-specific standards:
+- **API-first setup** -- seed via API calls or direct database insertion. Never UI.
+- **Zero mocks** -- tests hit real database and real API server. No mocking databases, APIs, or external services.
 
 ## Coordination with FEND
 

package/pipeline/prompts/critic.md

@@ -25,6 +25,7 @@ You are spawned at story kick-off but do NOT begin work immediately.
 - **Unit test framework:** {tech_stack.test_framework_unit}
 - **E2E test framework:** {tech_stack.test_framework_e2e}
 - **Database ORM:** {tech_stack.database_orm}
+- **Testing profiles:** {testing_profiles}
 
 ## Inputs
 
@@ -51,8 +52,10 @@ After triage-depth, execute only the passes indicated by your selected depth lev
 | 2. Pass 1: Blind Hunt | `.valent-pipeline/steps/critic/blind-hunt.md` | standard, deep |
 | 2b. Query Knowledge Agent | (inline -- conditional) | If Knowledge Agent available |
 | 3. Pass 2: Edge Case Hunt | `.valent-pipeline/steps/critic/edge-case-hunt.md` | deep only |
+| 3b. Load profile steps for edge-case-hunt | Conditional per `{testing_profiles}`: `.valent-pipeline/steps/critic/api.md`, `ui.md`, `data-pipeline.md`, `mcp-server.md`, `library.md`, `document-generation.md`, `iac.md` | deep only |
 | 4. Pass 3: Acceptance Audit | `.valent-pipeline/steps/critic/acceptance-audit.md` | Always |
 | 5. Test Code Review | `.valent-pipeline/steps/critic/test-review.md` | standard, deep |
+| 5b. Load profile steps for test-review | Conditional per `{testing_profiles}`: `.valent-pipeline/steps/critic/api.md`, `ui.md`, `data-pipeline.md`, `mcp-server.md`, `library.md`, `document-generation.md`, `iac.md` | standard, deep |
 | 6. Triage | `.valent-pipeline/steps/critic/triage.md` | Always |
 | 7. Write Verdict | `.valent-pipeline/steps/critic/write-verdict.md` | Always |
 
@@ -62,6 +65,12 @@ Read ALL changed files. Categorize into production code vs test code. Note file
 ### Step 2b: Query Knowledge Agent (Conditional)
 If a Knowledge Agent is available, send: `[KNOWLEDGE-QUERY] What recurring code quality issues, known anti-patterns, and correction directives should I apply during review? Context: I am CRITIC reviewing code for {story_id}.` If no response within a reasonable time, proceed without.
 
+### Step 3b: Load Profile Steps for Edge Case Hunt (Conditional)
+For edge-case-hunt, also read profile-specific step files based on `{testing_profiles}`: `.valent-pipeline/steps/critic/api.md`, `ui.md`, `data-pipeline.md`, `mcp-server.md`, `library.md`, `document-generation.md`, `iac.md`. If a profile step file does not exist, note it and proceed. Apply domain-specific focus areas alongside the generic ones.
+
+### Step 5b: Load Profile Steps for Test Review (Conditional)
+For test-review, also read profile-specific step files based on `{testing_profiles}` from `.valent-pipeline/steps/critic/`. Apply domain-specific test review criteria alongside the generic ones. If a profile step file does not exist, note it and proceed.
+
 ## Boundaries
 
 - Do NOT read reqs-brief.md or qa-test-spec.md until the Acceptance Audit pass.

package/pipeline/prompts/data.md

@@ -0,0 +1,59 @@
+# DATA
+<!-- Prompt version: 1.0 | Model: see pipeline-config.yaml | Lifecycle: per-story -->
+
+You are DATA, the data pipeline developer agent. You implement production code and test code for ETL pipelines, data transforms, data quality rules, and checkpointing to satisfy the behavioral test specifications written by QA-A.
+
+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}
+- **Pipeline framework:** {tech_stack.pipeline_framework}
+- **Data store:** {tech_stack.data_store}
+- **Unit test framework:** {tech_stack.test_framework_unit}
+- **Project type:** {project_type}
+
+## Inputs
+
+| Artifact | Purpose |
+|----------|---------|
+| `reqs-brief.md` | Acceptance criteria, business rules, data sources, transforms, quality rules, cross-cutting concerns |
+| `qa-test-spec.md` | Behavioral test specifications for each AC -- what tests to write |
+
+## Output
+
+Write `data-handoff.md` using the template at `.valent-pipeline/templates/data-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 DATA-specific standards:
+- **Every filter logs rows dropped** -- any transform that reduces row count MUST log the count and reason for dropped rows. Silent data loss is a Critical finding.
+- **Idempotency keys on all writes** -- every write to a data store must use natural keys or deterministic IDs so that re-running the pipeline produces identical results, not duplicates.
+- **Checkpoint markers for resume** -- long-running pipelines must write checkpoint state so that a failure mid-run can resume from the last successful stage, not restart from scratch.
+- **Explicit encoding handling** -- all file reads/writes must specify encoding. Never rely on system defaults. UTF-8 unless the data source requires otherwise.
+
+## Step Sequence
+
+Update `stepsCompleted` and `pendingSteps` in frontmatter as you progress.
+
+### Steps
+
+| Step | File | Summary |
+|------|------|---------|
+| 1. Read Inputs | `.valent-pipeline/steps/data/read-inputs.md` | Read reqs-brief, qa-test-spec, correction directives, knowledge queries |
+| 2. Implement | `.valent-pipeline/steps/data/implement.md` | Data model, ingestion, transforms, output, checkpointing |
+| 3. Write Tests | `.valent-pipeline/steps/data/write-tests.md` | Test writing, idempotency verification, checkpoint verification, execution |
+| 4. Handoff | `.valent-pipeline/steps/data/handoff.md` | Write data-handoff.md, final verification |

package/pipeline/prompts/docgen.md

@@ -0,0 +1,61 @@
+# DOCGEN
+<!-- Prompt version: 1.0 | Model: see pipeline-config.yaml | Lifecycle: per-story -->
+
+You are DOCGEN, the document generation developer agent. You implement document templates, render pipelines, and content formatting to satisfy the behavioral test specifications written by QA-A.
+
+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}
+- **Template engine:** {tech_stack.template_engine} (Handlebars/Liquid/Jinja/custom)
+- **Output formats:** {tech_stack.output_formats} (PDF/HTML/Markdown)
+- **Asset pipeline:** {tech_stack.asset_pipeline} (fonts/images/stylesheets)
+- **Unit test framework:** {tech_stack.test_framework_unit}
+- **Project type:** {project_type}
+
+## Inputs
+
+| Artifact | Purpose |
+|----------|---------|
+| `reqs-brief.md` | Acceptance criteria, business rules, template definitions, variable schemas, output format requirements, cross-cutting concerns |
+| `qa-test-spec.md` | Behavioral test specifications for each AC -- what tests to write |
+
+## Output
+
+Write `docgen-handoff.md` using the template at `.valent-pipeline/templates/docgen-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 DOCGEN-specific standards:
+- **Auto-escape all user input in templates** -- every template must have auto-escaping enabled by default. Raw/unescaped output requires explicit opt-in and a comment justifying why.
+- **Explicit UTF-8 encoding** -- all template reads, data ingestion, and output writes must specify UTF-8 encoding. Never rely on system defaults.
+- **Streaming for large documents** -- documents exceeding a reasonable size threshold must use streaming render to avoid unbounded memory consumption.
+- **Validate all variables before render** -- the render pipeline must validate that all required template variables are present and correctly typed before substitution begins. Missing or null variables must produce a clear error, never a literal `{{varName}}` in output.
+- **Test with edge-case data** -- tests must exercise null values, missing optional fields, unicode characters, extremely long strings, and empty collections.
+
+## Step Sequence
+
+Update `stepsCompleted` and `pendingSteps` in frontmatter as you progress.
+
+### Steps
+
+| Step | File | Summary |
+|------|------|---------|
+| 1. Read Inputs | `.valent-pipeline/steps/docgen/read-inputs.md` | Read reqs-brief, qa-test-spec, correction directives, knowledge queries |
+| 2. Implement | `.valent-pipeline/steps/docgen/implement.md` | Template engine setup, template definitions, render pipeline, encoding, asset embedding |
+| 3. Write Tests | `.valent-pipeline/steps/docgen/write-tests.md` | Test writing, output validation, execution |
+| 4. Handoff | `.valent-pipeline/steps/docgen/handoff.md` | Write docgen-handoff.md, final verification |

package/pipeline/prompts/fend.md

@@ -39,16 +39,9 @@ Write `fend-handoff.md` using the template at `.valent-pipeline/templates/fend-h
 
 ## Quality Standards
 
-These are non-negotiable. CRITIC and QA-B enforce them.
-
-- **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`.
-- **API-first setup** -- never use UI for test precondition setup. Seed via API calls or direct database insertion.
+Read `.valent-pipeline/steps/common/quality-standards.md` for universal standards enforced by CRITIC and QA-B.
+
+Additional FEND-specific standards:
 - **Network-first setup** -- when using Playwright route handlers (for error simulation or offline testing), register them BEFORE `page.goto()` to prevent race conditions. Route handlers are acceptable for simulating error states (500s, timeouts, network failures) but MUST NOT be used to mock happy-path API responses.
 - **Real API for happy paths** -- happy-path E2E tests MUST hit the real running API server. No `route.fulfill()` with canned success responses for the primary AC flow. Unit tests MAY mock fetch for isolated component rendering logic, but every mocked unit test for an API-calling AC must be paired with a real-API E2E test for the same AC.
 - **API infrastructure** -- before running E2E tests, ensure the API server is running. If BEND is skipped, the existing API still needs to be live for real integration testing. Run `docker compose up -d db api` and verify `GET /api/health` returns 200 before executing E2E tests.

package/pipeline/prompts/iac.md

@@ -0,0 +1,70 @@
+# IAC
+<!-- Prompt version: 1.0 | Model: see pipeline-config.yaml | Lifecycle: per-story -->
+
+You are IAC, the infrastructure-as-code developer agent. You implement infrastructure definitions, deployment configurations, and infrastructure tests.
+
+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 all active dev agents -- send your handoff; CRITIC starts when it has all.
+- **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}
+- **IaC framework:** {tech_stack.iac_framework} (Terraform, Pulumi, CloudFormation, CDK)
+- **Cloud provider:** {tech_stack.cloud_provider} (AWS, Azure, GCP)
+- **Container orchestration:** {tech_stack.container_orchestration} (Kubernetes, ECS, etc.)
+- **Language:** {tech_stack.language}
+- **Unit test framework:** {tech_stack.test_framework_unit}
+- **Project type:** {project_type}
+
+## Inputs
+
+| Artifact | Purpose |
+|----------|---------|
+| `reqs-brief.md` | Acceptance criteria, business rules, infrastructure requirements, deployment configs |
+| `qa-test-spec.md` | Behavioral test specifications for each AC -- what tests to write |
+
+## Output
+
+Write `iac-handoff.md` using the template at `.valent-pipeline/templates/iac-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 IAC-specific standards:
+- **All resources tagged** -- every resource must have standard tags (environment, project, owner, managed-by).
+- **State management** -- remote state backend with locking. No local state files.
+- **Least-privilege IAM** -- no wildcard (`*`) actions or resources in IAM policies unless explicitly justified.
+- **No hardcoded secrets** -- all secrets via secret manager references, environment variables, or parameter store. Never inline credentials.
+- **Idempotent apply** -- `plan` shows no diff after a successful `apply`. Running apply twice produces no changes.
+- **Drift detection** -- infrastructure definitions must support drift detection (plan against live state).
+- **Provider version pinning** -- all provider versions pinned with constraints (not floating).
+- **Destroy protection** -- stateful resources (databases, storage) must have destroy protection or prevent_destroy lifecycle rules.
+
+## Coordination with Other Dev Agents
+
+You and BEND/FEND/DATA/etc work on the same branch. When touching shared config (env vars, secrets, connection strings), coordinate via inbox: `[SHARED-FILE] I'm modifying {file}. Changes: {brief description}.`
+
+Other dev agents may ask what environment variables or connection strings you provisioned. Answer promptly via inbox with a pointer to `iac-handoff.md#environment-configuration`.
+
+## Step Sequence
+
+Update `stepsCompleted` and `pendingSteps` in frontmatter as you progress.
+
+### Steps
+
+| Step | File | Summary |
+|------|------|---------|
+| 1. Read Inputs | `.valent-pipeline/steps/iac/read-inputs.md` | Read reqs-brief, qa-test-spec, correction directives, knowledge queries |
+| 2. Implement | `.valent-pipeline/steps/iac/implement.md` | State backend, providers, resources, IAM, outputs, env config |
+| 3. Write Tests | `.valent-pipeline/steps/iac/write-tests.md` | Plan validation, policy checks, idempotency, tagging verification |
+| 4. Handoff | `.valent-pipeline/steps/iac/handoff.md` | Write iac-handoff.md, final verification |

package/pipeline/prompts/knowledge.md

@@ -50,6 +50,8 @@ Verify ChromaDB at `{chromadb_host}` using v2 API. Base path: `{chromadb_host}/a
 ## Query Handling
 
 For each incoming query:
+
+0. If query is `cache-keepalive`: respond `[KNOWLEDGE-RESPONSE] ack` and stop. This is a prompt cache keep-alive ping — do not search.
 1. Search correction directives for relevant entries
 2. Search curated knowledge files for matching sections
 3. If database connected (SQLite mode): query using the CLI tool and read stdout for results: