@zigrivers/scaffold 2.1.0

package/knowledge/review/review-ux-spec.md

@@ -0,0 +1,208 @@
+---
+name: review-ux-spec
+description: Failure modes and review passes specific to UI/UX specification artifacts
+topics: [review, ux, design, accessibility, responsive]
+---
+
+# Review: UX Specification
+
+The UX specification translates user journeys from the PRD and component architecture from the system architecture into concrete screens, interactions, and components. It must cover every user-facing feature, handle all interaction states (including errors and edge cases), and align with the design system. This review uses 7 passes targeting the specific ways UX specs fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: User Journey Coverage vs PRD
+
+### What to Check
+
+Every user-facing feature in the PRD has a corresponding screen, flow, or interaction in the UX spec. No PRD feature is left without a UX design.
+
+### Why This Matters
+
+Features without UX design get implemented with ad hoc interfaces. The implementing agent invents the UI on the fly, producing inconsistent interactions, unclear navigation, and confusing user flows. UX coverage is the bridge between "what the system does" (PRD) and "how the user does it" (implementation).
+
+### How to Check
+
+1. List every user-facing feature from the PRD (user stories, feature descriptions, use cases)
+2. For each feature, trace to its UX representation: which screens, which interactions, which flow?
+3. Flag features with no UX mapping — these are coverage gaps
+4. Check for PRD features that were split across multiple UX flows — is the split logical and complete?
+5. Verify that non-happy-path journeys are covered: what happens when the user makes a mistake, changes their mind, or encounters an error?
+6. Check that onboarding/first-time-use flows exist for features that require setup or learning
+
+### What a Finding Looks Like
+
+- P0: "PRD feature 'user can manage payment methods' has no corresponding screen in the UX spec. No flow for adding, editing, or removing payment methods exists."
+- P1: "PRD describes a 'password reset' flow, but the UX spec only covers the email entry step. The verification code entry, new password, and confirmation steps are missing."
+- P2: "PRD mentions 'user preferences' but the UX spec provides only a single settings screen with no detail on what preferences are available or how they are organized."
+
+---
+
+## Pass 2: Accessibility Compliance
+
+### What to Check
+
+The UX spec addresses accessibility at the specification level. WCAG compliance level is stated. Keyboard navigation is designed. Screen reader support is considered. Color contrast meets requirements.
+
+### Why This Matters
+
+Accessibility retrofitted after implementation is 5-10x more expensive than designing it in. When the UX spec does not address accessibility, implementing agents build inaccessible interfaces. Retrofitting means redesigning interaction patterns, adding ARIA attributes to components that were not designed for them, and restructuring HTML semantics.
+
+### How to Check
+
+1. Verify the target WCAG level is stated (A, AA, or AAA)
+2. For each interactive component, check: is keyboard navigation specified? (Tab order, keyboard shortcuts, focus management)
+3. Check that form elements have associated labels (not just placeholder text)
+4. Verify that interactive elements have sufficient touch target size (44x44 CSS pixels minimum)
+5. Check color usage: is information conveyed by color alone? (Must also use text, icons, or patterns)
+6. Check that screen reader behavior is specified for dynamic content (live regions, state announcements, navigation landmarks)
+7. Verify that focus management is specified for modals, dropdowns, and dynamic content changes
+
+### What a Finding Looks Like
+
+- P0: "No WCAG compliance level is stated. Implementing agents do not know what accessibility standard to target."
+- P1: "Modal dialogs do not specify focus management. When a modal opens, where does focus go? When it closes, where does focus return? Without this, keyboard users get lost."
+- P1: "Status indicators use only color (green/yellow/red) with no text or icon alternative. Users with color blindness cannot distinguish states."
+- P2: "Tab order is not specified for the main navigation. Default DOM order may not match the visual layout."
+
+---
+
+## Pass 3: Interaction State Completeness
+
+### What to Check
+
+Every interactive component has all its states defined: empty, loading, populated, error, disabled, hover, focus, active. Every user action has a clear response.
+
+### Why This Matters
+
+Implementing agents default to the "happy path populated" state when other states are not specified. The result is a UI that looks good with data but shows blank screens on empty states, has no loading indicators, and displays raw error messages. State completeness is what separates a polished UI from a prototype.
+
+### How to Check
+
+For each interactive component or data display:
+1. **Empty state** — What does it look like when there is no data? (Empty list, no results, new user with no history)
+2. **Loading state** — What does the user see while data is being fetched? (Skeleton, spinner, progressive loading)
+3. **Populated state** — The normal view with data (usually designed)
+4. **Error state** — What does the user see when a request fails? (Error message, retry button, fallback content)
+5. **Partial state** — What if some data loaded but part failed? (Component-level errors vs. page-level errors)
+6. **Disabled state** — When is the component not interactive, and what does it look like?
+7. **Edge states** — Very long text (truncation?), very large numbers (formatting?), very long lists (virtualization?)
+
+### What a Finding Looks Like
+
+- P0: "The dashboard shows charts and metrics but has no empty state design. A new user with no data will see empty chart containers with no guidance."
+- P1: "The order list component has no loading state. When orders are being fetched, the user sees either nothing or a flash of the empty state before data appears."
+- P1: "Form submission has a success state (redirect to confirmation) but no error state. What does the user see when the submission fails?"
+- P2: "No specification for how very long product names are handled in the product card. Truncation? Wrapping? Tooltip?"
+
+---
+
+## Pass 4: Design System Consistency
+
+### What to Check
+
+The UX spec uses design system tokens consistently. Colors, spacing, typography, and component styles reference the design system rather than using one-off values.
+
+### Why This Matters
+
+One-off values create visual inconsistency and maintenance burden. If one button uses `#3B82F6` and another uses `--color-primary`, they will diverge when the design system is updated. Consistent token usage means the design system is the single source of truth for visual properties.
+
+### How to Check
+
+1. Verify that a design system is referenced or defined (color tokens, spacing scale, typography scale, component library)
+2. Check that color values in the UX spec reference design system tokens, not hex values or named colors
+3. Check that spacing values reference the spacing scale, not arbitrary pixel values
+4. Check that typography (font sizes, weights, line heights) uses the type scale
+5. Verify that component specifications reference design system components, not custom one-off designs
+6. Look for visual elements that have no design system mapping — these are either gaps in the design system or violations
+
+### What a Finding Looks Like
+
+- P1: "The notification banner uses background color '#FEF3C7' which is not in the design system color tokens. Should use the warning surface token."
+- P1: "Button in the settings page has 14px padding. The design system spacing scale uses 12px and 16px. This creates visual inconsistency."
+- P2: "The modal component has a custom shadow that differs from the design system elevation tokens."
+
+---
+
+## Pass 5: Responsive Breakpoint Coverage
+
+### What to Check
+
+Behavior is defined for all responsive breakpoints. Every screen specifies how it adapts to mobile, tablet, and desktop viewports. Navigation changes across breakpoints are documented.
+
+### Why This Matters
+
+Responsive behavior that is not specified gets improvised during implementation. The implementing agent makes layout decisions on the fly, producing inconsistent responsive behavior across screens. Some screens may collapse to single-column while others try to maintain two columns, creating a jarring experience.
+
+### How to Check
+
+1. Verify that responsive breakpoints are defined (e.g., mobile < 768px, tablet 768-1024px, desktop > 1024px)
+2. For each screen, check that layout behavior is specified for each breakpoint
+3. Check navigation: does it collapse to a hamburger menu on mobile? At what breakpoint?
+4. Check data tables: how do they display on mobile? (Horizontal scroll, card layout, column hiding)
+5. Check form layouts: do multi-column forms stack on mobile?
+6. Check images and media: are they responsive? What aspect ratio at each breakpoint?
+7. Check for touch vs. pointer interactions: hover states need touch alternatives on mobile
+
+### What a Finding Looks Like
+
+- P0: "No responsive breakpoints are defined anywhere in the UX spec. Implementing agents have no guidance on how any screen should adapt to mobile."
+- P1: "The dashboard screen has a desktop layout with three columns of charts but no mobile specification. Three columns at 375px is unreadable."
+- P2: "Data table on the orders screen specifies horizontal scroll on mobile, but no indication of which columns to show vs. hide for quick scanning."
+
+---
+
+## Pass 6: Error State Handling
+
+### What to Check
+
+Every user action that can fail has a designed error state. Error messages are user-friendly. Recovery paths are clear.
+
+### Why This Matters
+
+Error handling is the most-skipped aspect of UX design. When error states are not designed, implementing agents show browser alerts, raw API error messages, or nothing at all. Users encounter errors frequently (network issues, validation failures, permissions), and the quality of error handling directly impacts user trust and task completion.
+
+### How to Check
+
+1. List every user action that involves an API call or data mutation
+2. For each action, verify an error state is designed: what does the user see on failure?
+3. Check that error messages are user-friendly (not "Error 422" or "CONSTRAINT_VIOLATION")
+4. Verify recovery paths: can the user retry? Is there a back button? Is progress lost?
+5. Check for network error handling: what happens when the user loses connectivity mid-action?
+6. Check for validation error display: inline (next to the field) or summary (top of form)?
+7. Verify that error states for destructive actions are especially clear: "delete failed" should not look like "delete succeeded"
+
+### What a Finding Looks Like
+
+- P0: "Payment processing flow has no error state design. If payment fails, what does the user see? Can they retry? Is the order in a partial state?"
+- P1: "Form validation errors are not specified as inline or summary. This is a fundamental interaction pattern decision that affects implementation architecture."
+- P2: "Network connectivity loss is not addressed. Long-running operations (file upload, report generation) need offline/reconnection handling."
+
+---
+
+## Pass 7: Component Hierarchy vs Architecture
+
+### What to Check
+
+Frontend components in the UX spec align with the frontend architecture from the system architecture document. Component boundaries match. State management aligns with the architectural approach.
+
+### Why This Matters
+
+When the UX spec designs components that do not match the architecture's component structure, implementing agents must reconcile two conflicting visions. Either they follow the UX spec (violating the architecture) or the architecture (deviating from the UX spec). Alignment prevents this conflict.
+
+### How to Check
+
+1. List frontend components from the system architecture document
+2. List UI components from the UX spec
+3. Verify alignment: do the UX spec's components map to the architecture's component boundaries?
+4. Check that data flow assumptions in the UX spec match the architecture's state management approach
+5. Verify that reusable components in the UX spec align with the architecture's component library structure
+6. Check that page-level components in the UX spec correspond to routes or views in the architecture
+7. Verify that the UX spec's component composition (which components contain which) matches the architecture's component tree
+
+### What a Finding Looks Like
+
+- P1: "The UX spec designs an 'OrderSummaryWidget' that combines order details, customer info, and payment status. The architecture separates these into three independent components (OrderComponent, CustomerComponent, PaymentComponent) with separate data sources."
+- P1: "The UX spec assumes global state for user preferences (accessible from any component), but the architecture specifies component-local state with prop drilling."
+- P2: "The UX spec's 'ProductCard' component bundles product image, price, and add-to-cart button. The architecture models 'ProductDisplay' and 'CartAction' as separate concerns."

package/knowledge/validation/critical-path-analysis.md

@@ -0,0 +1,203 @@
+---
+name: critical-path-analysis
+description: Tracing critical user journeys end-to-end across all specifications
+topics: [validation, critical-path, user-journeys, end-to-end, gaps]
+---
+
+# Critical Path Analysis
+
+Critical path analysis walks through the most important user journeys end-to-end across every specification artifact. For each journey, it verifies that every component, endpoint, query, screen, and task needed to make the journey work actually exists and is consistent.
+
+## What a Critical Path Is
+
+A critical path is a user journey that represents core functionality — the features that, if broken, would make the product unusable or fail its primary value proposition. These are not edge cases. They are the main flows that most users will execute most of the time.
+
+## Identifying Critical Journeys
+
+### Sources for Critical Journeys
+
+1. **PRD success criteria** — Any measurable outcome in the PRD implies a user journey. "Users can complete checkout in under 3 clicks" implies a checkout journey.
+2. **PRD user stories** — Primary user stories describe the most important journeys.
+3. **PRD personas** — Each persona's primary need implies a journey. A "buyer" persona implies a purchasing journey.
+4. **Architecture data flows** — Major data flows in the architecture document represent the system-level view of critical paths.
+5. **Revenue/value paths** — Journeys that directly relate to the product's revenue model or primary value proposition.
+
+### Prioritizing Which Journeys to Trace
+
+Not every user journey needs end-to-end tracing. Prioritize:
+
+1. **Happy path of core features** — The primary flow that delivers the product's main value. For an e-commerce app: browse → add to cart → checkout → payment → confirmation.
+2. **Authentication flows** — Sign up, sign in, password reset. Nearly every product has these and they touch many components.
+3. **Primary CRUD operations** — The main data creation and retrieval flows. For a project management tool: create project → add tasks → assign → update status → complete.
+4. **Cross-cutting journeys** — Flows that cross multiple bounded contexts or services. These are where integration gaps hide.
+5. **Error-recovery journeys** — What happens when payment fails? When a network request times out? When a form has validation errors?
+
+A typical project should trace 5-10 critical journeys. More than 15 usually means the scope is too broad or the granularity is too fine.
+
+## How to Trace a Journey
+
+### Step 1: Define the Journey
+
+Write a one-sentence description of the journey and list its steps from the user's perspective:
+
+```
+Journey: User registers and completes first purchase
+1. User visits landing page
+2. User clicks "Sign Up"
+3. User fills registration form (email, password)
+4. User receives verification email
+5. User clicks verification link
+6. User browses product catalog
+7. User views product detail
+8. User adds item to cart
+9. User views cart
+10. User initiates checkout
+11. User enters shipping address
+12. User enters payment information
+13. User confirms order
+14. User sees order confirmation
+15. User receives confirmation email
+```
+
+### Step 2: Map Each Step to Specifications
+
+For each step, identify the concrete artifacts that support it:
+
+| Step | UX Component | API Endpoint | Architecture Component | Database Query | Task ID |
+|------|-------------|-------------|----------------------|----------------|---------|
+| 1. Visit landing | LandingPage | GET /products/featured | ProductService | SELECT featured products | T-040 |
+| 2. Click Sign Up | SignUpForm | — | — | — | T-013 |
+| 3. Fill registration | SignUpForm | POST /auth/register | AuthService | INSERT INTO users | T-012 |
+| 4. Verification email | — | — | EmailService | INSERT INTO verification_tokens | T-016 |
+| 5. Click verify link | VerifyPage | POST /auth/verify | AuthService | UPDATE users SET verified | T-017 |
+| ... | ... | ... | ... | ... | ... |
+
+### Step 3: Check Each Mapping
+
+For each cell in the table, verify:
+
+1. **Existence** — Does the referenced artifact actually exist in the specifications? Is there actually a `POST /auth/register` endpoint in the API contracts? Is there actually a `SignUpForm` component in the UX spec?
+
+2. **Completeness** — Does the artifact cover what this step needs? Does the `POST /auth/register` endpoint accept `email` and `password`? Does it return a response that the `SignUpForm` component can use?
+
+3. **Connectivity** — Does the output of step N connect to the input of step N+1? If step 3 returns `{user, token}`, does step 6 (browse catalog) know how to use that token for authenticated requests?
+
+4. **Error handling** — What happens if this step fails? Is the failure mode documented? Is there a recovery path? If `POST /auth/register` returns 409 (email exists), does the UX spec define what the user sees?
+
+### Step 4: Identify Gaps
+
+Gaps take several forms:
+
+**Missing component** — A step requires a component that does not exist in any specification. Example: "User receives verification email" requires an email-sending service, but no such service is in the architecture.
+
+**Missing endpoint** — A step requires an API endpoint that is not in the contracts. Example: "User views cart" requires a `GET /cart` endpoint, but only `POST /cart/items` is defined.
+
+**Missing query** — A step requires a database query pattern, but no index supports it. Example: "User browses by category" requires a category-based product listing, but the products table has no category index.
+
+**Missing screen** — A step requires a UI screen or component that is not in the UX spec. Example: "User enters shipping address" requires an address form, but the UX spec jumps from cart to payment.
+
+**Missing task** — A step requires implementation work that has no task in the implementation tasks.
+
+**Broken connection** — The output of one step does not connect to the input of the next. Example: The registration endpoint returns a session cookie, but the product catalog endpoint expects a Bearer token.
+
+**Missing error path** — A step can fail, but there is no specification for what happens on failure.
+
+## Journey Tracing Template
+
+Use this template for each critical journey:
+
+```markdown
+## Journey: [Name]
+
+**Description:** [One sentence]
+**PRD Source:** [Section reference]
+**Priority:** Critical | High | Medium
+
+### Steps
+
+#### Step 1: [User action]
+- **UX:** [Component/screen] — [status: found/missing/incomplete]
+- **API:** [Endpoint] — [status]
+- **Architecture:** [Component] — [status]
+- **Data:** [Query/mutation] — [status]
+- **Task:** [Task ID] — [status]
+- **Error path:** [What happens on failure] — [status]
+- **Connection to next:** [How output feeds step 2] — [status]
+
+#### Step 2: [User action]
+...
+
+### Gaps Found
+1. [Gap description, severity, recommendation]
+2. ...
+
+### Journey Assessment
+- [ ] All steps have UX components
+- [ ] All steps have API endpoints (where applicable)
+- [ ] All steps have architecture components
+- [ ] All steps have data support (where applicable)
+- [ ] All steps have implementation tasks
+- [ ] All step-to-step connections verified
+- [ ] All error paths documented
+- [ ] End-to-end data shape consistency verified
+```
+
+## Common Gap Patterns
+
+### 1. The "Handoff Gap"
+
+Where one bounded context ends and another begins, there is often no specification for how data moves between them. The order service creates an order, but how does the fulfillment service learn about it? Is there an event? A synchronous call? A shared database?
+
+**How to find it:** Look for steps where the "Architecture Component" column changes. Each change is a boundary crossing that needs an integration mechanism.
+
+### 2. The "State Transition Gap"
+
+A user journey involves entity state changes (order: created → paid → shipped → delivered), but the specifications do not fully document all transitions, especially error transitions (paid → refunded, shipped → returned).
+
+**How to find it:** For each entity that changes state during the journey, extract the state machine and verify every transition has API support and UX feedback.
+
+### 3. The "Async Gap"
+
+Steps that involve asynchronous processing (sending email, processing payment, generating report) often lack specification for: how long the user waits, what they see while waiting, how they are notified of completion, and what happens if the async process fails.
+
+**How to find it:** Flag every step where the API response does not contain the final result (e.g., 202 Accepted, polling endpoints, WebSocket notifications).
+
+### 4. The "First-Time User Gap"
+
+Many journeys are specified assuming the user already has data (an account, items in cart, previous orders). The first-time user journey — where the system has no data for this user — often reveals missing empty states, onboarding flows, and default configurations.
+
+**How to find it:** Trace the journey assuming zero prior state. Does the product catalog work with zero products? Does the dashboard work with zero data points?
+
+### 5. The "Permission Gap"
+
+Some steps require specific permissions (admin actions, premium features), but the specifications do not define how the user acquires those permissions or what happens when they lack them.
+
+**How to find it:** For each step, ask "who is allowed to do this?" and verify that the auth model in the API contracts supports the answer.
+
+## Output Format
+
+### Summary Table
+
+```markdown
+| Journey | Steps | Gaps Found | Critical Gaps | Assessment |
+|---------|-------|-----------|---------------|------------|
+| User registration + first purchase | 15 | 4 | 1 (email service missing) | Needs work |
+| Returning user purchase | 8 | 1 | 0 | Mostly complete |
+| Admin manages products | 12 | 3 | 2 (admin auth, bulk operations) | Needs work |
+| User manages account | 6 | 0 | 0 | Complete |
+```
+
+### Detailed Findings
+
+Each gap should be reported with:
+- Which journey and step it affects
+- What is missing or inconsistent
+- What the impact would be if not fixed (agent would be unable to implement, or would implement incorrectly)
+- Recommended fix (which artifact to update, what to add)
+
+## When to Run Critical Path Analysis
+
+- After all pipeline steps (modeling through planning) are complete.
+- Before implementation tasks are finalized (gaps found here may require new tasks).
+- When PRD changes significantly (new features may introduce new critical journeys).
+- As a final check before freezing docs in the finalization phase.

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

@@ -0,0 +1,181 @@
+---
+name: cross-phase-consistency
+description: Auditing consistency across pipeline phases — naming, assumptions, data flows, interface contracts
+topics: [validation, consistency, naming, data-flow, contracts]
+---
+
+# Cross-Phase Consistency
+
+Cross-phase consistency validation ensures that artifacts produced across different pipeline phases agree with each other. Inconsistencies compound: a renamed entity in one phase propagates confusion into every downstream artifact. This document covers what to check, how to check it, and what findings look like.
+
+## Why Inconsistencies Happen
+
+Each pipeline phase is authored at a different time, possibly by different agents, with evolving understanding of the project. Common causes:
+
+- An entity gets renamed during architecture but the domain model still uses the old name.
+- A field is added to an API contract that does not exist in the database schema.
+- An ADR constrains behavior that is contradicted by a later UX specification.
+- A domain event defined in modeling is never consumed by any component in architecture.
+- Units or formats differ (e.g., timestamps as ISO strings in the API but Unix integers in the schema).
+
+## What to Check
+
+### 1. Naming Consistency
+
+Trace every named concept through all artifacts where it appears.
+
+**Process:**
+1. Extract all named entities from the domain model (aggregates, entities, value objects, events, invariants).
+2. For each name, search every downstream artifact: ADRs, architecture, schema, API contracts, UX spec, implementation tasks.
+3. Flag any spelling variations, abbreviations, or synonyms (e.g., "User" vs "Account" vs "Member" referring to the same concept).
+4. Flag any name that appears in a downstream artifact but not in the domain model (potential undocumented concept).
+
+**What findings look like:**
+- "Domain model uses `PaymentTransaction` but API contracts call it `Payment` and database schema calls it `payment_txn`."
+- "The entity `SubscriptionPlan` appears in the implementation tasks but is not in the domain model."
+
+**Resolution:** Establish one canonical name per concept. Update all artifacts to use it.
+
+### 2. Shared Assumptions
+
+Later phases often assume properties that earlier phases did not explicitly specify.
+
+**Process:**
+1. For each phase from architecture onward, identify every assumption about earlier artifacts.
+2. Verify each assumption is actually stated in the referenced artifact.
+3. Pay special attention to: cardinality (one-to-many vs many-to-many), optionality (required vs optional), ordering (ordered vs unordered), uniqueness constraints, temporal assumptions (real-time vs eventual consistency).
+
+**What findings look like:**
+- "Architecture assumes `Order` has a `status` field with enum values, but the domain model defines `Order` without specifying lifecycle states."
+- "API contracts assume paginated results, but architecture data flow diagrams show unbounded queries."
+
+**Resolution:** Either add the assumption to the source artifact or update the downstream artifact to not depend on it.
+
+### 3. Data Shape Consistency
+
+Trace a data shape from domain model through schema through API through UI.
+
+**Process:**
+1. Pick a core entity (e.g., `User`).
+2. Extract its shape from each layer:
+   - Domain model: attributes, relationships, invariants
+   - Database schema: columns, types, constraints, indexes
+   - API contract: request/response fields, types, validation rules
+   - UX spec: displayed fields, form inputs, validation messages
+3. Verify field-by-field alignment:
+   - Every domain attribute should map to a schema column (or have a documented reason for omission).
+   - Every schema column exposed externally should appear in an API contract field.
+   - Every API response field displayed to users should appear in UX spec.
+   - Types should be compatible (e.g., domain `Money` value object maps to `DECIMAL(10,2)` in schema, `string` formatted as currency in API, formatted display in UX).
+
+**What findings look like:**
+- "Domain model `Product.price` is a `Money` value object (amount + currency), but schema has only `price_cents INTEGER` — currency is missing."
+- "API returns `created_at` as ISO 8601 string but UX spec references `createdAt` as a Unix timestamp."
+
+### 4. Interface Contract Matching
+
+Verify that component interfaces defined in architecture match their implementations in API contracts and database schema.
+
+**Process:**
+1. Extract every component interface from the architecture document (method signatures, event subscriptions, data flows).
+2. For each interface, find its concrete definition in API contracts or internal service contracts.
+3. Verify:
+   - All interface methods have corresponding endpoints or functions.
+   - Parameter names and types match.
+   - Return types match.
+   - Error cases defined at the interface level are handled at the implementation level.
+
+**What findings look like:**
+- "Architecture defines `NotificationService.sendBatch(notifications[])` but API contracts only define `POST /notifications` for single notifications."
+- "Architecture component `PaymentGateway` has an `onPaymentFailed` event handler, but no component publishes `PaymentFailed` events."
+
+### 5. Data Flow Completeness
+
+Verify that data flows described in architecture are implementable with the defined APIs and schemas.
+
+**Process:**
+1. For each data flow diagram in architecture, walk through step by step.
+2. At each step, verify:
+   - The source component has an API or interface that provides the data.
+   - The target component has an API or interface that accepts the data.
+   - The data shape at the source matches the data shape at the target.
+   - Any transformation between source and target is documented.
+3. Check for orphaned components — components that appear in data flows but have no API endpoints or database tables.
+
+**What findings look like:**
+- "Data flow shows `OrderService -> InventoryService: reserve items`, but InventoryService API has no reservation endpoint."
+- "Data flow shows `AnalyticsCollector` receiving events from `UserService`, but the architecture has no event bus or pub/sub mechanism defined."
+
+### 6. Constraint Propagation
+
+ADR constraints should be respected in all downstream artifacts.
+
+**Process:**
+1. Extract all constraints from ADRs (technology choices, architectural patterns, non-functional requirements).
+2. For each constraint, verify it is reflected in relevant downstream artifacts:
+   - Technology choice ADRs should align with architecture component technology annotations.
+   - Pattern ADRs (e.g., "use event sourcing for Order aggregate") should be reflected in schema design and API contracts.
+   - NFR ADRs should have corresponding test criteria in testing strategy.
+
+**What findings look like:**
+- "ADR-007 mandates PostgreSQL, but database schema uses MongoDB-style document references."
+- "ADR-012 requires CQRS for order processing, but architecture shows a single read/write path."
+
+## How to Structure the Audit
+
+### Pass 1: Build an Entity Registry
+
+Create a table of every named concept with its appearance in each artifact:
+
+| Concept | Domain Model | ADRs | Architecture | Schema | API | UX | Tasks |
+|---------|-------------|------|-------------|--------|-----|-----|-------|
+| User | `User` entity | — | `UserService` | `users` table | `/users` resource | User Profile screen | Task #12-#15 |
+| Order | `Order` aggregate | ADR-012 CQRS | `OrderService` | `orders` table | `/orders` resource | Order History screen | Task #20-#28 |
+
+Flag any row with missing cells or naming inconsistencies.
+
+### Pass 2: Data Shape Tracing
+
+For each entity in the registry, trace its shape layer by layer. Build a field-level comparison table:
+
+| Field | Domain | Schema | API | UX |
+|-------|--------|--------|-----|-----|
+| id | UUID | `id UUID PK` | `id: string (uuid)` | hidden |
+| email | Email (value object) | `email VARCHAR(255) UNIQUE` | `email: string (email)` | text input, validated |
+| role | UserRole enum | `role VARCHAR(20) CHECK(...)` | `role: "admin" | "user"` | dropdown |
+
+Flag mismatches in type, optionality, naming, or format.
+
+### Pass 3: Flow Walking
+
+Walk each data flow end-to-end, verifying every step has concrete API/schema support.
+
+### Pass 4: Constraint Verification
+
+Cross-reference every ADR constraint against downstream artifacts.
+
+## Output Format
+
+Findings should be structured as:
+
+```
+## Finding: [Short Description]
+
+**Severity:** Critical | Major | Minor
+**Phases Involved:** [list of phases]
+**Description:** [What the inconsistency is]
+**Evidence:**
+- In [artifact]: [what it says]
+- In [artifact]: [what it says differently]
+**Recommended Fix:** [Which artifact to update and how]
+```
+
+## Common Patterns Worth Special Attention
+
+1. **Enum drift** — Enum values defined in domain model, schema, API, and UX often diverge. One phase adds a new status value without updating others.
+2. **Optionality mismatch** — Domain model says a field is required, but API contract makes it optional, or vice versa.
+3. **Orphaned events** — Domain events defined but never consumed (or consumed but never published).
+4. **Ghost requirements** — Features appear in UX spec or implementation tasks that trace to no PRD requirement.
+5. **Format divergence** — Dates, money, identifiers represented differently across layers without documented transformation rules.
+6. **Soft-delete vs hard-delete** — One phase assumes records are soft-deleted, another assumes they are gone.
+7. **Pagination assumptions** — API paginates but UX assumes all data is available; or API returns all but architecture assumed streaming.