@zigrivers/scaffold 2.1.2 → 2.38.0

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: 16
+order: 840
 dependencies: [api-contracts]
-outputs: [docs/reviews/review-api.md]
+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-contracts]
+knowledge-base: [review-methodology, review-api-design, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,6 +15,9 @@ Review API contracts targeting API-specific failure modes: operation coverage
 gaps, error contract incompleteness, auth/authz gaps, versioning inconsistencies,
 payload shape mismatches with domain entities, and idempotency gaps.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/api-contracts.md (required) — contracts to review
 - docs/domain-models/ (required) — for operation coverage
@@ -23,18 +27,35 @@ payload shape mismatches with domain entities, and idempotency gaps.
 ## Expected Outputs
 - docs/reviews/review-api.md — findings and resolution log
 - docs/api-contracts.md — updated with fixes
+- docs/reviews/api/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/api/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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
-- **deep**: Full multi-pass review targeting all API failure modes.
+- **deep**: Full multi-pass review targeting all API failure modes. Multi-model
+  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)**: Scale passes with depth.
+- **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.
+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: 14
+order: 820
 dependencies: [database-schema]
-outputs: [docs/reviews/review-database.md]
+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-schema]
+knowledge-base: [review-methodology, review-database-design, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,6 +15,9 @@ Review database schema targeting schema-specific failure modes: entity coverage
 gaps, normalization trade-off issues, missing indexes, migration safety, and
 referential integrity vs. domain invariants.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/database-schema.md (required) — schema to review
 - docs/domain-models/ (required) — for entity coverage
@@ -22,18 +26,35 @@ referential integrity vs. domain invariants.
 ## Expected Outputs
 - docs/reviews/review-database.md — findings and resolution log
 - docs/database-schema.md — updated with fixes
+- docs/reviews/database/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/database/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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
-- **deep**: Full multi-pass review targeting all schema failure modes.
+- **deep**: Full multi-pass review targeting all schema failure modes. Multi-model
+  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)**: Scale passes with depth.
+- **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.
+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: 18
+order: 860
 dependencies: [ux-spec]
-outputs: [docs/reviews/review-ux.md]
+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-spec]
+reads: [api-contracts]
+knowledge-base: [review-methodology, review-ux-specification, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -14,25 +16,45 @@ Review UX specification targeting UX-specific failure modes: user journey gaps,
 accessibility issues, incomplete interaction states, design system inconsistencies,
 and missing error states.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent review validation.
+
 ## Inputs
 - docs/ux-spec.md (required) — spec to review
-- docs/prd.md (required) — for journey coverage
+- docs/plan.md (required) — for journey coverage
 - docs/api-contracts.md (optional) — for data shape alignment
 
 ## Expected Outputs
 - docs/reviews/review-ux.md — findings and resolution log
 - docs/ux-spec.md — updated with fixes
+- docs/reviews/ux/review-summary.md (depth 4+) — multi-model review synthesis
+- docs/reviews/ux/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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. **mvp**: Journey 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**: 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.
+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,35 +1,41 @@
 ---
 name: ux-spec
-description: Specify UI/UX design including design system
+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: 17
+order: 850
 dependencies: [review-architecture]
 outputs: [docs/ux-spec.md]
 conditional: "if-needed"
+reads: [api-contracts, design-system]
 knowledge-base: [ux-specification]
 ---
 
 ## Purpose
-Define the user experience specification: user flows, wireframes, component
-hierarchy, interaction patterns, and design system (tokens, components, patterns).
-This is the visual and interaction blueprint for the frontend.
+Define the user experience specification: user flows, interaction state machines,
+component architecture (hierarchy and data flow), accessibility requirements, and
+responsive behavior. This is the interaction and behavior blueprint for the frontend.
+Visual tokens and component appearance are defined in `docs/design-system.md` — this
+step consumes those tokens, it does not redefine them.
 
 ## Inputs
-- docs/prd.md (required) — user requirements and personas
+- docs/plan.md (required) — user requirements and personas
 - docs/system-architecture.md (required) — frontend architecture
 - docs/api-contracts.md (optional) — data shapes for UI components
 - docs/user-stories.md (required) — user journeys driving flow design
+- docs/design-system.md (optional) — design tokens and component visual specs to reference
 
 ## Expected Outputs
 - docs/ux-spec.md — UX specification with flows, components, design system
 
 ## Quality Criteria
-- Every PRD user journey has a corresponding flow
-- Component hierarchy covers all UI states (loading, error, empty, populated)
-- Design system defines tokens (colors, spacing, typography) and base components
-- Accessibility requirements documented (WCAG level, keyboard nav, screen readers)
-- Responsive breakpoints defined with behavior per breakpoint
-- Error states documented for every user action that can fail
+- (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)
+- (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.
@@ -40,4 +46,20 @@ This is the visual and interaction blueprint for the frontend.
   system. Depth 4-5: full specification with accessibility.
 
 ## Mode Detection
-Update mode if spec exists.
+Check for docs/ux-spec.md. If it exists, operate in update mode: read existing
+flows and component hierarchy, diff against updated user stories and system
+architecture. Preserve existing interaction patterns, state machines, and
+component data flow definitions. Add new flows for new user stories or features.
+Update component hierarchy if architecture changed frontend structure. Never
+remove documented accessibility requirements.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/ux-spec.md exists
+- **Preserve**: existing user flows, interaction state machines, component
+  hierarchy, accessibility requirements, responsive breakpoint definitions
+- **Triggers for update**: user stories added or changed, architecture changed
+  frontend components, design system tokens updated, API contracts changed
+  data shapes available to UI
+- **Conflict resolution**: if a user story was rewritten, update its flow
+  in-place rather than creating a duplicate; reconcile component hierarchy
+  changes with existing state machine definitions

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: 30
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/critical-path-walkthrough.md]
+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
@@ -16,22 +17,55 @@ architecture components, database operations, and implementation tasks.
 Use story acceptance criteria as the definition of "correct behavior" when
 verifying completeness and consistency at every layer.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent journey walkthroughs — different models catch different
+spec gaps along the critical path.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
 
 ## Expected Outputs
 - docs/validation/critical-path-walkthrough.md — findings report
+- docs/validation/critical-path-walkthrough/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/critical-path-walkthrough/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  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)**: Scale thoroughness with depth.
+- **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.
+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: 27
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/cross-phase-consistency.md]
+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
@@ -14,22 +15,55 @@ Audit naming, assumptions, data flows, interface contracts across all phases.
 Ensure consistent terminology, compatible assumptions, and aligned interfaces
 between every pair of phase artifacts.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent consistency validation — different models catch different
+drift patterns.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
 
 ## Expected Outputs
 - docs/validation/cross-phase-consistency.md — findings report
+- docs/validation/cross-phase-consistency/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/cross-phase-consistency/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  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)**: Scale thoroughness with depth.
+- **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.
+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: 29
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/decision-completeness.md]
+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
@@ -15,22 +16,55 @@ significant architectural and technology decision has a corresponding ADR,
 that no two ADRs contradict each other, and that all decisions have clear
 rationale.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent decision audit — different models surface different implicit
+decisions.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
 
 ## Expected Outputs
 - docs/validation/decision-completeness.md — findings report
+- docs/validation/decision-completeness/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/decision-completeness/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  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)**: Scale thoroughness with depth.
+- **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.
+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: 32
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/dependency-graph-validation.md]
+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
@@ -15,22 +16,56 @@ Validate that the implementation task dependency graph forms a valid DAG,
 that all dependencies are satisfied before dependent tasks, and that no
 critical tasks are missing from the graph.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent graph validation — different models catch different ordering
+and completeness issues.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
 
 ## Expected Outputs
 - docs/validation/dependency-graph-validation.md — findings report
+- docs/validation/dependency-graph-validation/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/dependency-graph-validation/codex-review.json (depth 4+, if available) — raw Codex findings
+- 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
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  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)**: Scale thoroughness with depth.
+- **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.
+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