@zigrivers/scaffold 2.28.1 → 2.38.0

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: 910
-dependencies: [tdd]
+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
@@ -30,11 +32,14 @@ independent review validation.
 - 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
@@ -42,10 +47,16 @@ independent review validation.
   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)**: Depth 1-3: scale passes with depth. Depth 4: full
-  review + one external model (if CLI available). Depth 5: full review +
-  multi-model with reconciliation.
+- **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. If multi-model review artifacts exist
-under docs/reviews/testing/, preserve prior findings still valid.
+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,10 +1,12 @@
 ---
 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: 950
 dependencies: [review-operations]
 outputs: [docs/security-review.md]
+reads: [system-architecture, api-contracts, database-schema]
 conditional: null
 knowledge-base: [security-best-practices]
 ---
@@ -12,7 +14,9 @@ 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,18 +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
-- Every API endpoint has authentication and authorization requirements specified
-- Auth/authz boundaries defined and consistent with API contracts
-- Input validation rules defined for each user-facing field (type, length, pattern)
-- Data classified by sensitivity with handling requirements
-- Secrets management approach documented (no hardcoded credentials in code)
-- Secrets management strategy defined (no secrets in code)
-- CORS policy explicitly configured per origin (not wildcard in production)
-- Rate limiting defined for public-facing endpoints with specific thresholds
-- Threat model covers all trust boundaries
-- Dependency audit strategy documented (automated scanning, update cadence)
-- 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.

package/pipeline/quality/story-tests.md

@@ -1,11 +1,12 @@
 ---
 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]
+reads: [tech-stack, coding-standards, project-structure, api-contracts, database-schema, ux-spec]
 conditional: null
 knowledge-base: [testing-strategy, user-stories]
 ---
@@ -35,14 +36,15 @@ pending/skipped — developers implement them during TDD execution.
   ACs → test cases, and layer assignments (unit/integration/e2e)
 
 ## Quality Criteria
-- Every user story in docs/user-stories.md has a corresponding test file
-- Every acceptance criterion has at least one tagged test case
+- (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
-- Test layer (unit/integration/e2e) is assigned based on AC type and architecture
+- (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

package/pipeline/specification/api-contracts.md

@@ -1,6 +1,7 @@
 ---
 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: 830
 dependencies: [review-architecture]
@@ -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

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: 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.

package/pipeline/specification/review-api.md

@@ -1,12 +1,13 @@
 ---
 name: review-api
 description: Review API contracts for completeness and consistency
+summary: "Checks that every domain operation has an endpoint, error responses include domain-specific codes, and auth requirements are specified for every route."
 phase: "specification"
 order: 840
 dependencies: [api-contracts]
 outputs: [docs/reviews/review-api.md, docs/reviews/api/review-summary.md, docs/reviews/api/codex-review.json, docs/reviews/api/gemini-review.json]
 conditional: "if-needed"
-knowledge-base: [review-methodology, review-api-design]
+knowledge-base: [review-methodology, review-api-design, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -31,11 +32,14 @@ independent review validation.
 - docs/reviews/api/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Operation coverage against domain model verified
-- Error contracts complete and consistent
-- Auth requirements specified for every endpoint
-- Versioning strategy consistent with ADRs
-- Idempotency documented for all mutating operations
+- (mvp) Operation coverage against domain model verified
+- (deep) Error contracts complete and consistent
+- (deep) Auth requirements specified for every endpoint
+- (deep) Versioning strategy consistent with ADRs
+- (deep) Idempotency documented for all mutating operations
+- (mvp) Every finding categorized P0-P3 with specific endpoint, field, and issue
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to api-contracts.md and re-validated
+- (mvp) Downstream readiness confirmed — no unresolved P0 or P1 findings remain before UX spec proceeds
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
@@ -43,10 +47,15 @@ independent review validation.
   review dispatched to Codex and Gemini if available, with graceful fallback
   to Claude-only enhanced review.
 - **mvp**: Operation coverage check only.
-- **custom:depth(1-5)**: Depth 1-3: scale passes with depth. Depth 4: full
-  review + one external model (if CLI available). Depth 5: full review +
-  multi-model with reconciliation.
+- **custom:depth(1-5)**: Depth 1: endpoint coverage and response format pass only. Depth 2: add error handling and auth requirement passes. Depth 3: add idempotency, pagination, and versioning passes. Depth 4: add external model API review. Depth 5: multi-model review with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist
 under docs/reviews/api/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-api.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/specification/review-database.md

@@ -1,12 +1,13 @@
 ---
 name: review-database
 description: Review database schema for correctness and completeness
+summary: "Verifies every domain entity has a table, constraints enforce business rules at the database level, and indexes cover all query patterns from the API contracts."
 phase: "specification"
 order: 820
 dependencies: [database-schema]
 outputs: [docs/reviews/review-database.md, docs/reviews/database/review-summary.md, docs/reviews/database/codex-review.json, docs/reviews/database/gemini-review.json]
 conditional: "if-needed"
-knowledge-base: [review-methodology, review-database-design]
+knowledge-base: [review-methodology, review-database-design, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -30,11 +31,14 @@ independent review validation.
 - docs/reviews/database/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Entity coverage verified
-- Normalization decisions justified
-- Index coverage for known query patterns verified
-- Migration safety assessed
-- Referential integrity matches domain invariants
+- (mvp) Every domain entity has a corresponding table/collection or documented denormalization rationale
+- (mvp) Normalization decisions justified
+- (deep) Index coverage for known query patterns verified
+- (deep) Migration safety assessed
+- (mvp) Referential integrity matches domain invariants
+- (mvp) Every finding categorized P0-P3 with specific table, column, and issue
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to database-schema.md and re-validated
+- (mvp) Downstream readiness confirmed — no unresolved P0 or P1 findings remain before API contracts proceed
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
@@ -42,10 +46,15 @@ independent review validation.
   review dispatched to Codex and Gemini if available, with graceful fallback
   to Claude-only enhanced review.
 - **mvp**: Entity coverage check only.
-- **custom:depth(1-5)**: Depth 1-3: scale passes with depth. Depth 4: full
-  review + one external model (if CLI available). Depth 5: full review +
-  multi-model with reconciliation.
+- **custom:depth(1-5)**: Depth 1: entity coverage and normalization pass only. Depth 2: add index strategy and migration safety passes. Depth 3: add query performance and data integrity passes. Depth 4: add external model review. Depth 5: multi-model review with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist
 under docs/reviews/database/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-database.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/specification/review-ux.md

@@ -1,12 +1,14 @@
 ---
 name: review-ux
 description: Review UX specification for completeness and usability
+summary: "Verifies every user story has a flow, accessibility requirements are met, all error states are documented, and the design system is used consistently."
 phase: "specification"
 order: 860
 dependencies: [ux-spec]
 outputs: [docs/reviews/review-ux.md, docs/reviews/ux/review-summary.md, docs/reviews/ux/codex-review.json, docs/reviews/ux/gemini-review.json]
 conditional: "if-needed"
-knowledge-base: [review-methodology, review-ux-specification]
+reads: [api-contracts]
+knowledge-base: [review-methodology, review-ux-specification, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -30,21 +32,29 @@ independent review validation.
 - docs/reviews/ux/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- User journey coverage verified against PRD
-- Accessibility compliance checked
-- All interaction states covered
-- Design system consistency verified
-- Error states present for all failure-capable actions
+- (mvp) User journey coverage verified against PRD
+- (mvp) Accessibility verified against WCAG level specified in ux-spec
+- (deep) Every user action has at minimum: loading, success, and error states documented
+- (deep) Design system consistency verified
+- (deep) Error states present for all failure-capable actions
+- (mvp) Every finding categorized P0-P3 with specific flow, screen, and issue
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to ux-spec.md and re-validated
+- (mvp) Downstream readiness confirmed — no unresolved P0 or P1 findings remain before quality phase proceeds
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
 - **deep**: Full multi-pass review. Multi-model review dispatched to Codex and
   Gemini if available, with graceful fallback to Claude-only enhanced review.
-  **mvp**: Journey coverage only.
-- **custom:depth(1-5)**: Depth 1-3: scale passes with depth. Depth 4: full
-  review + one external model (if CLI available). Depth 5: full review +
-  multi-model with reconciliation.
+- **mvp**: Journey coverage only.
+- **custom:depth(1-5)**: Depth 1: flow completeness and accessibility pass only. Depth 2: add responsive design and error state passes. Depth 3: add interaction patterns and platform consistency passes. Depth 4: add external model UX review. Depth 5: multi-model review with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist
 under docs/reviews/ux/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-ux.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/specification/ux-spec.md

@@ -1,11 +1,13 @@
 ---
 name: ux-spec
 description: Specify user flows, interaction states, component architecture, accessibility, and responsive behavior
+summary: "Maps out every user flow with all interaction states (loading, error, empty, populated), defines accessibility requirements (WCAG level, keyboard nav), and specifies responsive behavior at each breakpoint."
 phase: "specification"
 order: 850
 dependencies: [review-architecture]
 outputs: [docs/ux-spec.md]
 conditional: "if-needed"
+reads: [api-contracts, design-system]
 knowledge-base: [ux-specification]
 ---
 
@@ -27,12 +29,13 @@ step consumes those tokens, it does not redefine them.
 - docs/ux-spec.md — UX specification with flows, components, design system
 
 ## Quality Criteria
-- Every PRD user journey has a corresponding flow with all states documented
-- Component hierarchy covers all UI states (loading, error, empty, populated)
+- (mvp) Every PRD user journey has a corresponding flow with all states documented
+- (mvp) Component hierarchy covers all UI states (loading, error, empty, populated)
 - References design tokens from docs/design-system.md (does not redefine them)
-- Accessibility requirements documented (WCAG level, keyboard nav, screen readers)
-- Responsive breakpoints defined with layout behavior per breakpoint
-- Error states documented for every user action that can fail
+- (deep) Accessibility requirements documented (WCAG level, keyboard nav, screen readers)
+- (deep) Responsive breakpoints defined with layout behavior per breakpoint
+- (mvp) Error states documented for every user action that can fail
+- (deep) All documented user flows verified at responsive breakpoints (mobile, tablet, desktop) with behavior differences noted
 
 ## Methodology Scaling
 - **deep**: Full UX specification. Detailed wireframes described in prose.

package/pipeline/validation/critical-path-walkthrough.md

@@ -1,12 +1,13 @@
 ---
 name: critical-path-walkthrough
 description: Walk critical user journeys end-to-end across all specs
+summary: "Walks the most important user journeys end-to-end across every spec layer — PRD to stories to UX to API to database to tasks — and flags any broken handoffs or missing layers."
 phase: "validation"
 order: 1340
 dependencies: [implementation-plan-review, review-security]
 outputs: [docs/validation/critical-path-walkthrough.md, docs/validation/critical-path-walkthrough/review-summary.md, docs/validation/critical-path-walkthrough/codex-review.json, docs/validation/critical-path-walkthrough/gemini-review.json]
 conditional: null
-knowledge-base: [critical-path-analysis]
+knowledge-base: [critical-path-analysis, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -31,9 +32,11 @@ spec gaps along the critical path.
 - docs/validation/critical-path-walkthrough/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Top critical user journeys (all Must-have epics, minimum 3) traced end-to-end
+- (deep) Every journey verified at each layer: PRD → Story → UX → API → Architecture → DB → Task
+- (deep) Each critical path verified against story acceptance criteria for behavioral correctness
+- Missing layers or broken handoffs documented with specific gap description
+- Findings categorized P0-P3 with specific file, section, and issue for each
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Finding Disposition
@@ -54,11 +57,15 @@ proceeding without acknowledgment.
   dispatched to Codex and Gemini if available, with graceful fallback to
   Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Depth 1-3: scale thoroughness with depth. Depth 4:
-  full analysis + one external model (if CLI available). Depth 5: full
-  analysis + multi-model with reconciliation.
+- **custom:depth(1-5)**: Depth 1: identify critical path and verify task ordering. Depth 2: add dependency bottleneck analysis. Depth 3: full walkthrough simulating agent execution of critical path tasks. Depth 4: add external model simulation. Depth 5: multi-model walkthrough with divergence analysis.
 
 ## Mode Detection
 Not applicable — validation always runs fresh against current artifacts. If
 multi-model artifacts exist under docs/validation/critical-path-walkthrough/,
 they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/critical-path-walkthrough/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding

package/pipeline/validation/cross-phase-consistency.md

@@ -1,12 +1,13 @@
 ---
 name: cross-phase-consistency
 description: Audit naming, assumptions, data flows, interface contracts across all phases
+summary: "Traces every named concept (entities, fields, API endpoints) across all documents and flags any naming drift, terminology mismatches, or data shape inconsistencies."
 phase: "validation"
 order: 1310
 dependencies: [implementation-plan-review, review-security]
 outputs: [docs/validation/cross-phase-consistency.md, docs/validation/cross-phase-consistency/review-summary.md, docs/validation/cross-phase-consistency/codex-review.json, docs/validation/cross-phase-consistency/gemini-review.json]
 conditional: null
-knowledge-base: [cross-phase-consistency]
+knowledge-base: [cross-phase-consistency, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -29,9 +30,11 @@ drift patterns.
 - docs/validation/cross-phase-consistency/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Entity names are consistent across domain models, database schema, and API contracts (zero mismatches)
+- (mvp) Technology references match `docs/tech-stack.md` in all documents
+- (deep) Data flow descriptions in architecture match API endpoint definitions
+- (deep) Terminology is consistent (same concept never uses two different names)
+- Findings categorized P0-P3 with specific file, section, and issue for each
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Finding Disposition
@@ -52,11 +55,15 @@ proceeding without acknowledgment.
   dispatched to Codex and Gemini if available, with graceful fallback to
   Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Depth 1-3: scale thoroughness with depth. Depth 4:
-  full analysis + one external model (if CLI available). Depth 5: full
-  analysis + multi-model with reconciliation.
+- **custom:depth(1-5)**: Depth 1: entity name check across PRD, user stories, and domain models. Depth 2: add tech stack reference consistency. Depth 3: full terminology audit across all documents with naming collision detection. Depth 4: add external model cross-check. Depth 5: multi-model reconciliation of consistency findings.
 
 ## Mode Detection
 Not applicable — validation always runs fresh against current artifacts. If
 multi-model artifacts exist under docs/validation/cross-phase-consistency/,
 they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/cross-phase-consistency/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding

package/pipeline/validation/decision-completeness.md

@@ -1,12 +1,13 @@
 ---
 name: decision-completeness
 description: Verify all decisions are recorded, justified, non-contradictory
+summary: "Checks that every technology choice and architectural pattern has a recorded decision with rationale, and that no two decisions contradict each other."
 phase: "validation"
 order: 1330
 dependencies: [implementation-plan-review, review-security]
 outputs: [docs/validation/decision-completeness.md, docs/validation/decision-completeness/review-summary.md, docs/validation/decision-completeness/codex-review.json, docs/validation/decision-completeness/gemini-review.json]
 conditional: null
-knowledge-base: [decision-completeness]
+knowledge-base: [decision-completeness, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -30,9 +31,11 @@ decisions.
 - docs/validation/decision-completeness/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Every technology choice in `docs/tech-stack.md` has a corresponding ADR
+- (mvp) No two ADRs contradict each other
+- (deep) Every ADR has alternatives-considered section with pros/cons
+- (deep) Every ADR referenced in `docs/system-architecture.md` exists in `docs/adrs/`
+- Findings categorized P0-P3 with specific file, section, and issue for each
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Finding Disposition
@@ -53,11 +56,15 @@ proceeding without acknowledgment.
   dispatched to Codex and Gemini if available, with graceful fallback to
   Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Depth 1-3: scale thoroughness with depth. Depth 4:
-  full analysis + one external model (if CLI available). Depth 5: full
-  analysis + multi-model with reconciliation.
+- **custom:depth(1-5)**: Depth 1: verify each major tech choice has an ADR. Depth 2: add alternatives-considered check. Depth 3: full ADR completeness audit (rationale, consequences, status). Depth 4: add external model review of decision quality. Depth 5: multi-model reconciliation of decision coverage.
 
 ## Mode Detection
 Not applicable — validation always runs fresh against current artifacts. If
 multi-model artifacts exist under docs/validation/decision-completeness/,
 they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/decision-completeness/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding

package/pipeline/validation/dependency-graph-validation.md

@@ -1,12 +1,13 @@
 ---
 name: dependency-graph-validation
 description: Verify task dependency graphs are acyclic, complete, correctly ordered
+summary: "Verifies the task dependency graph has no cycles (which would deadlock agents), no orphaned tasks, and no chains deeper than three sequential dependencies."
 phase: "validation"
 order: 1360
 dependencies: [implementation-plan-review, review-security]
 outputs: [docs/validation/dependency-graph-validation.md, docs/validation/dependency-graph-validation/review-summary.md, docs/validation/dependency-graph-validation/codex-review.json, docs/validation/dependency-graph-validation/gemini-review.json]
 conditional: null
-knowledge-base: [dependency-validation]
+knowledge-base: [dependency-validation, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -30,9 +31,12 @@ and completeness issues.
 - docs/validation/dependency-graph-validation/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Task dependency graph verified as acyclic (no circular dependencies)
+- (mvp) Every task with dependencies has all dependencies present in the graph
+- (deep) Critical path identified and total estimated duration documented
+- (deep) No task is blocked by more than 3 sequential dependencies (flag deep chains)
+- (deep) Wave assignments are consistent with dependency ordering
+- Findings categorized P0-P3 with specific file, section, and issue for each
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Finding Disposition
@@ -53,11 +57,15 @@ proceeding without acknowledgment.
   dispatched to Codex and Gemini if available, with graceful fallback to
   Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Depth 1-3: scale thoroughness with depth. Depth 4:
-  full analysis + one external model (if CLI available). Depth 5: full
-  analysis + multi-model with reconciliation.
+- **custom:depth(1-5)**: Depth 1: cycle detection and basic ordering check. Depth 2: add transitive dependency completeness. Depth 3: full DAG validation with critical path identification and parallelization opportunities. Depth 4: add external model review. Depth 5: multi-model validation with optimization recommendations.
 
 ## Mode Detection
 Not applicable — validation always runs fresh against current artifacts. If
 multi-model artifacts exist under docs/validation/dependency-graph-validation/,
 they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/dependency-graph-validation/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding