@zigrivers/scaffold 2.1.2 → 2.38.0

package/pipeline/quality/operations.md

@@ -1,42 +1,71 @@
 ---
 name: operations
-description: Define operations, deployment, and dev environment strategy
+description: Define deployment pipeline, deployment strategy, monitoring, alerting, and incident response
+summary: "Designs your deployment pipeline (build, test, deploy, verify, rollback), defines monitoring metrics with alert thresholds, and writes incident response procedures with rollback instructions."
 phase: "quality"
-order: 21
+order: 930
 dependencies: [review-testing]
 outputs: [docs/operations-runbook.md]
+reads: [system-architecture, adrs, dev-env-setup, git-workflow]
 conditional: null
 knowledge-base: [operations-runbook]
 ---
 
 ## Purpose
-Define the operational strategy: CI/CD pipeline, deployment approach, monitoring
-and alerting, incident response, rollback procedures, and dev environment setup.
-This is both the production operations guide and the local development workflow.
+Define the production operational strategy: deployment pipeline (extending the
+base CI from git-workflow), deployment approach, monitoring and alerting, incident
+response, and rollback procedures. References docs/dev-setup.md for local
+development setup rather than redefining it.
 
 ## Inputs
 - docs/system-architecture.md (required) — what to deploy
-- docs/testing-strategy.md (required) — CI pipeline test stages
+- docs/tdd-standards.md (required) — CI pipeline test stages
 - docs/adrs/ (required) — infrastructure decisions
+- docs/dev-setup.md (optional) — local dev setup to reference, not redefine
+- docs/git-workflow.md (optional) — base CI pipeline to extend, not redefine
 
 ## Expected Outputs
-- docs/operations-runbook.md — operations and deployment runbook
+- docs/operations-runbook.md — production operations and deployment runbook
 
 ## Quality Criteria
-- CI/CD pipeline defined with all stages (build, test, lint, deploy)
-- Deployment strategy chosen with rollback procedure
-- Monitoring covers key metrics (latency, error rate, saturation)
-- Alerting thresholds are justified, not arbitrary
-- Dev environment setup is documented and reproducible
-- Incident response process defined
+- (mvp) Deployment pipeline extends existing CI (build, deploy, post-deploy stages)
+- (mvp) Deployment pipeline has explicit stages (build → test → deploy → verify → rollback-ready)
+- (mvp) Does not redefine base CI stages (lint, test) from git-workflow
+- (mvp) Deployment strategy chosen with rollback procedure
+- (deep) Rollback procedure tested with specific trigger conditions (e.g., error rate > X%, health check failure)
+- (deep) Runbook structured by operational scenario (deployment, rollback, incident, scaling)
+- (mvp) Monitoring covers key metrics (latency, error rate, saturation)
+- (deep) Each monitoring metric has an explicit threshold with rationale
+- (deep) Health check endpoints defined with expected response codes and latency bounds
+- (deep) Log aggregation strategy specifies retention period and searchable fields
+- (deep) Each alert threshold documents: the metric, threshold value, business impact if crossed, and mitigation action
+- References docs/dev-setup.md for local dev — does not redefine it
+- (deep) Incident response process defined
+- (deep) Recovery Time Objective (RTO) and Recovery Point Objective (RPO) documented for each critical service
+- (deep) Secret rotation procedure documented and tested
 
 ## Methodology Scaling
 - **deep**: Full runbook. Deployment topology diagrams. Monitoring dashboard
-  specs. Alert playbooks. DR plan. Capacity planning. Local dev with
-  containers matching production.
-- **mvp**: Basic CI/CD pipeline. Deploy command. How to run locally.
+  specs. Alert playbooks. DR plan. Capacity planning.
+- **mvp**: Deploy command. Basic monitoring. Rollback procedure.
 - **custom:depth(1-5)**: Depth 1-2: MVP-style. Depth 3: add monitoring and
   alerts. Depth 4-5: full runbook with DR.
 
 ## Mode Detection
-Update mode if runbook exists.
+Check for docs/operations-runbook.md. If it exists, operate in update mode:
+read existing runbook and diff against current system architecture, ADRs, and
+deployment configuration. Preserve existing deployment procedures, monitoring
+thresholds, and incident response processes. Update deployment pipeline stages
+if architecture changed. Never modify rollback procedures without user approval.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/operations-runbook.md exists
+- **Preserve**: deployment procedures, monitoring thresholds, alerting rules,
+  incident response processes, rollback procedures, environment-specific
+  configurations
+- **Triggers for update**: architecture changed deployment topology, new ADRs
+  changed infrastructure, security review identified operational requirements,
+  CI pipeline changed (new stages to extend)
+- **Conflict resolution**: if architecture changed the deployment target,
+  update deployment stages but preserve monitoring and alerting sections;
+  verify runbook does not redefine base CI stages from git-workflow.md

package/pipeline/quality/review-operations.md

@@ -1,12 +1,13 @@
 ---
 name: review-operations
 description: Review operations runbook for completeness and safety
+summary: "Verifies the full deployment lifecycle is documented, monitoring covers latency/errors/saturation, alert thresholds have rationale, and common failure scenarios have runbook entries."
 phase: "quality"
-order: 22
+order: 940
 dependencies: [operations]
-outputs: [docs/reviews/review-operations.md]
+outputs: [docs/reviews/review-operations.md, docs/reviews/operations/review-summary.md, docs/reviews/operations/codex-review.json, docs/reviews/operations/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-operations]
+knowledge-base: [review-methodology, review-operations, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,6 +15,9 @@ Review operations runbook targeting operations-specific failure modes: deploymen
 strategy gaps, missing rollback procedures, monitoring blind spots, unjustified
 alerting thresholds, missing runbook scenarios, and DR coverage gaps.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/operations-runbook.md (required) — runbook to review
 - docs/system-architecture.md (required) — for deployment coverage
@@ -21,17 +25,34 @@ alerting thresholds, missing runbook scenarios, and DR coverage gaps.
 ## Expected Outputs
 - docs/reviews/review-operations.md — findings and resolution log
 - docs/operations-runbook.md — updated with fixes
+- docs/reviews/operations/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/operations/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/operations/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Deployment lifecycle fully documented (deploy, verify, rollback)
-- Monitoring covers all critical metrics
-- Alert thresholds have rationale
-- Common failure scenarios have runbook entries
-- Dev environment parity assessed
+- (mvp) Deployment lifecycle fully documented (deploy, verify, rollback)
+- (mvp) Monitoring verified against minimum set: latency, error rate, and saturation
+- (deep) Alert thresholds have rationale
+- (deep) Common failure scenarios have runbook entries
+- (deep) Dev/staging/production environment differences documented in operations runbook
+- Every finding categorized P0-P3 with specific runbook section, metric, and issue
+- Fix plan documented for all P0/P1 findings; fixes applied to operations-runbook.md and re-validated
+- Downstream readiness confirmed — no unresolved P0 or P1 findings remain before security step proceeds
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
-- **deep**: Full multi-pass review. **mvp**: Deployment coverage only.
-- **custom:depth(1-5)**: Scale passes with depth.
+- **deep**: Full multi-pass review. Multi-model review dispatched to Codex and
+  Gemini if available, with graceful fallback to Claude-only enhanced review.
+- **mvp**: Deployment coverage only.
+- **custom:depth(1-5)**: Depth 1: monitoring and logging pass only. Depth 2: add deployment and rollback pass. Depth 3: add incident response and scaling passes. Depth 4: add external model review. Depth 5: multi-model review with reconciliation.
 
 ## Mode Detection
-Re-review mode if previous review exists.
+Re-review mode if previous review exists. If multi-model review artifacts exist
+under docs/reviews/operations/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-operations.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/quality/review-security.md

@@ -1,12 +1,14 @@
 ---
 name: review-security
 description: Review security review for coverage and correctness
+summary: "Verifies OWASP coverage is complete, auth boundaries match API contracts, every secret is accounted for, and the threat model covers all trust boundaries. Highest priority for multi-model review."
 phase: "quality"
-order: 24
+order: 960
 dependencies: [security]
-outputs: [docs/reviews/review-security.md]
+outputs: [docs/reviews/review-security.md, docs/reviews/security/review-summary.md, docs/reviews/security/codex-review.json, docs/reviews/security/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-security]
+reads: [api-contracts]
+knowledge-base: [review-methodology, review-security, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -15,6 +17,9 @@ gaps, auth/authz boundary mismatches with API contracts, secrets management gaps
 insufficient dependency audit coverage, missing threat model scenarios, and data
 classification gaps.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/security-review.md (required) — security review document
 - docs/api-contracts.md (optional) — for auth boundary alignment
@@ -23,18 +28,35 @@ classification gaps.
 ## Expected Outputs
 - docs/reviews/review-security.md — findings and resolution log
 - docs/security-review.md — updated with fixes
+- docs/reviews/security/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/security/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/security/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- OWASP coverage verified for this project
-- Auth boundaries match API contract auth requirements
-- Secrets management is complete (no gaps)
-- Dependency audit scope covers all dependencies
-- Threat model covers all trust boundaries
-- Data classification is complete
+- (mvp) OWASP coverage verified for this project
+- (deep) Auth boundaries match API contract auth requirements
+- (deep) Secrets management covers: all environment variables, API keys, database credentials, and third-party tokens
+- (deep) Dependency audit scope covers all dependencies
+- (deep) Threat model covers all trust boundaries
+- (deep) Data classification covers every entity in the domain model
+- Every finding categorized P0-P3 with specific control, boundary, and issue
+- Fix plan documented for all P0/P1 findings; fixes applied to security-review.md and re-validated
+- Downstream readiness confirmed — no unresolved P0 or P1 findings remain before planning phase proceeds
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
-- **deep**: Full multi-pass review. **mvp**: OWASP coverage check only.
-- **custom:depth(1-5)**: Scale passes with depth.
+- **deep**: Full multi-pass review. Multi-model review dispatched to Codex and
+  Gemini if available, with graceful fallback to Claude-only enhanced review.
+- **mvp**: OWASP coverage check only.
+- **custom:depth(1-5)**: Depth 1: OWASP top 10 and secrets management pass only. Depth 2: add auth boundary and input validation passes. Depth 3: add dependency audit and data protection passes. Depth 4: add external model security review. Depth 5: multi-model security review with reconciliation.
 
 ## Mode Detection
-Re-review mode if previous review exists.
+Re-review mode if previous review exists. If multi-model review artifacts exist
+under docs/reviews/security/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-security.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/quality/review-testing.md

@@ -1,12 +1,14 @@
 ---
 name: review-testing
 description: Review testing strategy for coverage gaps and feasibility
+summary: "Audits the testing strategy for coverage gaps by layer, verifies edge cases from domain invariants are tested, and checks that test environment assumptions match actual config."
 phase: "quality"
-order: 20
-dependencies: [testing-strategy]
-outputs: [docs/reviews/review-testing.md]
+order: 910
+dependencies: [tdd, system-architecture]
+outputs: [docs/reviews/review-testing.md, docs/reviews/testing/review-summary.md, docs/reviews/testing/codex-review.json, docs/reviews/testing/gemini-review.json]
+reads: [domain-modeling, system-architecture]
 conditional: null
-knowledge-base: [review-methodology, review-testing-strategy]
+knowledge-base: [review-methodology, review-testing-strategy, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,26 +16,47 @@ Review testing strategy targeting testing-specific failure modes: coverage gaps
 by layer, missing edge cases from domain invariants, unrealistic test environment
 assumptions, inadequate performance test coverage, and missing integration boundaries.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
-- docs/testing-strategy.md (required) — strategy to review
+- docs/tdd-standards.md (required) — strategy to review
 - docs/domain-models/ (required) — for invariant test case coverage
 - docs/system-architecture.md (required) — for layer coverage
 
 ## Expected Outputs
 - docs/reviews/review-testing.md — findings and resolution log
-- docs/testing-strategy.md — updated with fixes
+- docs/tdd-standards.md — updated with fixes
+- docs/reviews/testing/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/testing/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/reviews/testing/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Coverage gaps by layer identified
-- Domain invariant test cases verified
-- Test environment assumptions validated
-- Performance test coverage assessed against NFRs
-- Integration boundaries have integration tests defined
+- (mvp) Coverage gaps by layer documented with severity
+- (deep) Domain invariant test cases verified
+- (deep) Each test environment assumption verified against actual environment config or flagged as unverifiable
+- (deep) Performance test coverage assessed against NFRs
+- (deep) Integration boundaries have integration tests defined
+- Every finding categorized P0-P3 with specific test layer, gap, and issue
+- Fix plan documented for all P0/P1 findings; fixes applied to tdd-standards.md and re-validated
+- Downstream readiness confirmed — no unresolved P0 or P1 findings remain before operations step proceeds
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
-- **deep**: Full multi-pass review targeting all testing failure modes.
+- **deep**: Full multi-pass review targeting all testing failure modes. Multi-model
+  review dispatched to Codex and Gemini if available, with graceful fallback
+  to Claude-only enhanced review.
 - **mvp**: Coverage gap check only.
-- **custom:depth(1-5)**: Scale passes with depth.
+- **custom:depth(1-5)**: Depth 1: test coverage and pyramid balance pass only. Depth 2: add test quality and naming convention passes. Depth 3: add edge case coverage and CI integration passes. Depth 4: add external model review. Depth 5: multi-model review with reconciliation.
 
 ## Mode Detection
-Re-review mode if previous review exists.
+Re-review mode if docs/reviews/review-testing.md or docs/reviews/testing/
+directory exists. If multi-model review artifacts exist under
+docs/reviews/testing/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-testing.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/quality/security.md

@@ -1,18 +1,22 @@
 ---
 name: security
 description: Security review and documentation
+summary: "Conducts a security review of your entire system — OWASP Top 10 coverage, input validation rules for every user-facing field, data classification, secrets management, CORS policy, rate limiting, and a threat model covering all trust boundaries."
 phase: "quality"
-order: 23
+order: 950
 dependencies: [review-operations]
 outputs: [docs/security-review.md]
+reads: [system-architecture, api-contracts, database-schema]
 conditional: null
-knowledge-base: [security-review]
+knowledge-base: [security-best-practices]
 ---
 
 ## Purpose
 Conduct a security review of the entire system design. Document security
 controls, threat model, auth/authz approach, data protection, secrets
-management, and dependency audit strategy.
+management, and dependency audit strategy. The review covers OWASP Top 10
+analysis specific to this project's stack and architecture, plus STRIDE
+threat modeling across all trust boundaries.
 
 ## Inputs
 - docs/system-architecture.md (required) — attack surface
@@ -24,12 +28,18 @@ management, and dependency audit strategy.
 - docs/security-review.md — security review and controls document
 
 ## Quality Criteria
-- OWASP top 10 addressed for this specific project
-- Auth/authz boundaries defined and consistent with API contracts
-- Data classified by sensitivity with handling requirements
-- Secrets management strategy defined (no secrets in code)
-- Threat model covers all trust boundaries
-- Dependency audit integrated into CI
+- (mvp) OWASP top 10 addressed for this specific project
+- (mvp) Every API endpoint has authentication and authorization requirements specified
+- (mvp) Auth/authz boundaries defined and consistent with API contracts
+- (mvp) Input validation rules defined for each user-facing field: data type, maximum length, regex pattern (where applicable), and rejection error message
+- (deep) Data classified by sensitivity with handling requirements
+- (mvp) Secrets management strategy documented with rotation policy (no hardcoded secrets in code)
+- (deep) CORS policy explicitly configured per origin (not wildcard in production)
+- (deep) Rate limiting defined for public-facing endpoints with specific thresholds
+- (deep) Threat model covers all trust boundaries
+- (deep) Dependency audit strategy documented (automated scanning, update cadence)
+- (deep) Dependency audit integrated into CI
+- (deep) Secret rotation testing documented (how to rotate each secret type without downtime)
 
 ## Methodology Scaling
 - **deep**: Full threat model (STRIDE). OWASP analysis per component.
@@ -41,4 +51,20 @@ management, and dependency audit strategy.
   Depth 4-5: full security review.
 
 ## Mode Detection
-Update mode if review exists.
+Check for docs/security-review.md. If it exists, operate in update mode: read
+existing security controls and threat model, diff against current system
+architecture and API contracts. Preserve existing threat model entries, auth
+decisions, and data classification. Add new threat boundaries for new
+components. Update auth requirements if API contracts changed.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/security-review.md exists
+- **Preserve**: threat model entries, data classification matrix, auth/authz
+  decisions, secrets management strategy, dependency audit configuration,
+  compliance checklist items
+- **Triggers for update**: architecture added new components (new attack surface),
+  API contracts changed auth requirements, database schema changed data
+  sensitivity, operations runbook changed deployment security
+- **Conflict resolution**: if a new component introduces a trust boundary
+  that conflicts with existing auth approach, document both and flag for
+  user decision; never weaken existing security controls without approval

package/pipeline/quality/story-tests.md

@@ -0,0 +1,75 @@
+---
+name: story-tests
+description: Generate test skeletons from user story acceptance criteria
+summary: "Generates a test skeleton file for each user story — one pending test case per acceptance criterion, tagged with story and criterion IDs — giving agents a TDD starting point for every feature."
+phase: "quality"
+order: 915
+dependencies: [tdd, review-user-stories, review-architecture]
+outputs: [tests/acceptance/, docs/story-tests-map.md]
+reads: [tech-stack, coding-standards, project-structure, api-contracts, database-schema, ux-spec]
+conditional: null
+knowledge-base: [testing-strategy, user-stories]
+---
+
+## Purpose
+Generate test skeleton files from user story acceptance criteria, creating a
+direct, traceable link from every AC to a tagged test case. Each story produces
+a test file with one test case per acceptance criterion, tagged with story and
+AC IDs for downstream coverage verification. Test cases are created as
+pending/skipped — developers implement them during TDD execution.
+
+## Inputs
+- docs/user-stories.md (required) — stories with acceptance criteria in GWT format
+- docs/tdd-standards.md (required) — test framework, patterns, layer conventions
+- docs/tech-stack.md (required) — language, test runner, assertion library
+- docs/coding-standards.md (required) — test naming conventions
+- docs/system-architecture.md (required) — component structure for layer assignment
+- docs/project-structure.md (required) — test file location conventions
+- docs/api-contracts.md (optional) — endpoint details for API test skeletons
+- docs/database-schema.md (optional) — data layer context for integration tests
+- docs/ux-spec.md (optional) — UI component context for component tests
+
+## Expected Outputs
+- tests/acceptance/{story-id}-{slug}.test.* — one test file per story with
+  tagged pending test cases per AC
+- docs/story-tests-map.md — traceability matrix mapping stories → test files,
+  ACs → test cases, and layer assignments (unit/integration/e2e)
+
+## Quality Criteria
+- (mvp) Every user story in docs/user-stories.md has a corresponding test file
+- (mvp) Every acceptance criterion has at least one tagged test case
+- Test cases are tagged with story ID and AC ID for traceability
+- (deep) Test layer assignment: single-function ACs → unit; cross-component ACs → integration; full user journey ACs → e2e
+- Test files use the project's test framework from docs/tech-stack.md
+- All test cases are created as pending/skipped (not implemented)
+- docs/story-tests-map.md shows 100% AC-to-test-case coverage
+- Test file location follows conventions from docs/project-structure.md
+- (deep) Test data fixtures and dependencies documented for each test file
+
+## Methodology Scaling
+- **deep**: All stories get test files. Negative test cases for every happy path
+  AC. Boundary condition tests. Layer-specific skeletons (unit + integration +
+  e2e where applicable). Traceability matrix with confidence analysis.
+- **mvp**: Test files for Must-have stories only. One test case per AC. No
+  layer splitting — all tests in acceptance/ directory.
+- **custom:depth(1-5)**: Depth 1: Must-have stories only. Depth 2: add
+  Should-have. Depth 3: add negative cases. Depth 4: add boundary conditions
+  and layer splitting. Depth 5: full suite with all stories and edge cases.
+
+## Mode Detection
+Update mode if tests/acceptance/ directory exists. In update mode: add test
+files for new stories, add test cases for new ACs in existing stories, never
+delete user-implemented test logic (only add new pending cases). Update
+docs/story-tests-map.md with new mappings.
+
+## Update Mode Specifics
+- **Detect prior artifact**: tests/acceptance/ directory exists with test files
+- **Preserve**: all user-implemented test logic, existing test file names and
+  structure, story ID and AC ID tags, traceability mappings in
+  docs/story-tests-map.md
+- **Triggers for update**: user stories added or changed acceptance criteria,
+  architecture changed component structure (layer assignments may shift),
+  tdd-standards.md changed test patterns or framework
+- **Conflict resolution**: if a story's AC was reworded, update the test case
+  description but preserve any implemented test body; if layer assignment
+  changed, move the test case to the correct layer file

package/pipeline/specification/api-contracts.md

@@ -1,8 +1,9 @@
 ---
 name: api-contracts
 description: Specify API contracts for all system interfaces
+summary: "Specifies every API endpoint — request/response shapes, error codes with human-readable messages, auth requirements, pagination, and example payloads — so frontend and backend can be built in parallel."
 phase: "specification"
-order: 15
+order: 830
 dependencies: [review-architecture]
 outputs: [docs/api-contracts.md]
 conditional: "if-needed"
@@ -13,6 +14,8 @@ knowledge-base: [api-design]
 Define API contracts for all system interfaces — REST endpoints, GraphQL schema,
 WebSocket events, or inter-service communication. Each endpoint specifies request/
 response shapes, error codes, authentication requirements, and rate limits.
+Contracts serve as the definitive agreement between frontend and backend agents,
+enabling parallel development with confidence.
 
 ## Inputs
 - docs/system-architecture.md (required) — component interfaces to specify
@@ -24,12 +27,14 @@ response shapes, error codes, authentication requirements, and rate limits.
   shapes, error contracts, auth requirements
 
 ## Quality Criteria
-- Every domain operation that crosses a component boundary has an API endpoint
-- Error contracts are explicit (not just "500 Internal Server Error")
-- Authentication and authorization requirements per endpoint
-- Versioning strategy documented (if applicable)
-- Pagination, filtering, and sorting for list endpoints
-- Idempotency documented for mutating operations
+- (mvp) Every domain operation that crosses a component boundary has an API endpoint
+- (mvp) Every endpoint documents: success response code, error response codes, error response body schema, and at least 2 domain-specific error codes per endpoint with human-readable reason phrases (e.g., 400 `invalid_email`, 409 `user_already_exists`)
+- (mvp) Authentication and authorization requirements per endpoint
+- (deep) Versioning strategy documented (if applicable)
+- (deep) Pagination, filtering, and sorting for list endpoints
+- (deep) Idempotency documented for mutating operations
+- (deep) Pagination schema documented for all list endpoints (cursor or offset, page size limits, total count)
+- (mvp) Example request and response payloads included for each endpoint
 
 ## Methodology Scaling
 - **deep**: OpenAPI-style specification. Full request/response schemas with
@@ -41,4 +46,19 @@ response shapes, error codes, authentication requirements, and rate limits.
   error contracts. Depth 4-5: full OpenAPI-style spec.
 
 ## Mode Detection
-Update mode if contracts exist. Diff against architecture changes.
+Check for docs/api-contracts.md. If it exists, operate in update mode: read
+existing endpoint definitions and diff against current system architecture and
+domain models. Preserve existing endpoint paths, request/response schemas, and
+error contracts. Add new endpoints for new features or domain operations.
+Update error contracts if domain model changed validation rules. Never remove
+or rename existing endpoints without explicit user approval.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/api-contracts.md exists
+- **Preserve**: existing endpoint paths, HTTP methods, request/response schemas,
+  error codes, auth requirements, pagination patterns, versioning strategy
+- **Triggers for update**: architecture changed component boundaries, domain
+  models added new operations, ADRs changed API style or auth approach
+- **Conflict resolution**: if architecture moved an operation to a different
+  component, update the endpoint's component ownership but preserve its contract;
+  flag breaking schema changes for user review

package/pipeline/specification/database-schema.md

@@ -1,17 +1,22 @@
 ---
 name: database-schema
 description: Design database schema from domain models
+summary: "Translates your domain model into database tables with constraints that enforce business rules, indexes optimized for your API query patterns, and a reversible migration strategy."
 phase: "specification"
-order: 13
+order: 810
 dependencies: [review-architecture]
 outputs: [docs/database-schema.md]
+reads: [domain-modeling, system-architecture, adrs]
 conditional: "if-needed"
 knowledge-base: [database-design]
 ---
 
 ## Purpose
 Translate domain models into a concrete database schema. Define tables/collections,
-relationships, indexes, constraints, and migration strategy.
+relationships, indexes, constraints, and migration strategy. Every domain entity
+maps to a table with appropriate normalization, and every domain invariant is
+enforced at the database level through constraints. Indexing strategy is derived
+from the application's query patterns.
 
 ## Inputs
 - docs/domain-models/ (required) — entities and relationships to model
@@ -23,11 +28,12 @@ relationships, indexes, constraints, and migration strategy.
   constraints, and migration strategy
 
 ## Quality Criteria
-- Every domain entity maps to a table/collection (or justified denormalization)
-- Relationships match domain model relationships
-- Indexes cover known query patterns from architecture data flows
-- Constraints enforce domain invariants at the database level
-- Migration strategy handles schema evolution
+- (mvp) Every domain entity maps to a table/collection (or justified denormalization)
+- (mvp) Relationships match domain model relationships
+- (mvp) Constraints enforce domain invariants at the database level
+- (deep) Migration strategy specifies: migration tool, forward migration approach, rollback approach, and data preservation policy
+- (deep) Every migration is reversible (rollback script or equivalent exists)
+- (mvp) Indexes cover all query patterns referenced in docs/api-contracts.md (if it exists)
 
 ## Methodology Scaling
 - **deep**: Full schema specification. CREATE TABLE statements or equivalent.
@@ -38,4 +44,19 @@ relationships, indexes, constraints, and migration strategy.
   constraints. Depth 4-5: full specification with migrations.
 
 ## Mode Detection
-Update mode if schema exists. Diff against current domain models.
+Check for docs/database-schema.md. If it exists, operate in update mode: read
+existing schema and diff against current domain models in docs/domain-models/.
+Preserve existing table definitions, relationships, constraints, and migration
+history. Add new entities from updated domain models. Update indexes for new
+query patterns identified in architecture data flows. Never drop existing
+tables without explicit user approval.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/database-schema.md exists
+- **Preserve**: existing table/collection definitions, relationships, constraints,
+  migration history, index justifications, seed data strategy
+- **Triggers for update**: domain models changed (new entities or relationships),
+  ADRs changed database technology, architecture introduced new query patterns
+- **Conflict resolution**: if domain model renamed an entity, create a migration
+  that renames rather than drops and recreates; flag breaking changes for user
+  review