@zigrivers/scaffold 2.1.0

package/knowledge/review/review-database-schema.md

@@ -0,0 +1,229 @@
+---
+name: review-database-schema
+description: Failure modes and review passes specific to database schema design artifacts
+topics: [review, database, schema, data-modeling]
+---
+
+# Review: Database Schema
+
+The database schema translates domain entities and their relationships into persistent storage structures. It must faithfully represent domain models while also optimizing for real query patterns, enforcing invariants through constraints, and providing safe migration paths. This review uses 8 passes targeting the specific ways database schema designs fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: Entity Coverage
+
+### What to Check
+
+Every domain entity that requires persistence maps to a table, collection, or storage structure. No domain entity is missing from the schema.
+
+### Why This Matters
+
+A missing table means an entire domain concept has no home in the database. Implementing agents will either create ad hoc tables (diverging from the schema design) or try to shoehorn entities into existing tables (violating domain boundaries). Entity coverage is the most fundamental check — everything else assumes the right tables exist.
+
+### How to Check
+
+1. List every entity and aggregate root from domain models
+2. For each entity, find the corresponding table or collection in the schema
+3. Flag entities with no mapping — these are gaps
+4. Check value objects: do any require their own table (one-to-many embedded values), or are they correctly embedded in the parent entity's table?
+5. Verify domain events: if events are persisted (event sourcing, audit log), check that event storage tables exist
+6. Check reference/lookup data: enums, categories, and status values — are they stored as tables, enum types, or inline constants? Is the choice justified?
+
+### What a Finding Looks Like
+
+- P0: "'AuditLog' entity exists in domain models with defined lifecycle and attributes, but no audit_logs table appears in the schema."
+- P1: "'Address' is a value object used by three entities (User, Order, Warehouse) but there is no consistent approach — some embed it as columns, some reference a separate table."
+- P2: "Domain events are documented as 'persisted for replay' in the architecture, but no event storage table exists in the schema."
+
+---
+
+## Pass 2: Relationship Fidelity
+
+### What to Check
+
+Schema relationships (foreign keys, join tables, embedded documents) accurately reflect domain model relationships. Cardinality matches. Direction matches. No relationship is inverted, missing, or fabricated.
+
+### Why This Matters
+
+A one-to-many relationship modeled as many-to-many creates unnecessary complexity and ambiguity. A missing foreign key means referential integrity is not enforced by the database, leaving it to application code (which is less reliable). Relationship fidelity errors cause subtle bugs — the system appears to work but produces incorrect data under edge conditions.
+
+### How to Check
+
+1. For each relationship in domain models, find the corresponding schema relationship
+2. Verify cardinality: one-to-one, one-to-many, many-to-many match between domain and schema
+3. Verify direction: the foreign key is on the correct table (the "many" side in one-to-many)
+4. For many-to-many relationships, verify a join table exists with appropriate foreign keys
+5. Check for missing relationships: domain models show A relates to B, but no foreign key or join table connects them in the schema
+6. Check for fabricated relationships: schema has a foreign key between tables whose domain entities have no documented relationship
+
+### What a Finding Looks Like
+
+- P0: "Domain model shows Order has many LineItems (one-to-many), but the schema has no foreign key from line_items to orders. The relationship is unenforceable."
+- P1: "Domain model shows User has one Profile (one-to-one), but the schema implements it as one-to-many (profiles table has user_id without a unique constraint)."
+- P2: "Join table 'user_roles' exists but the domain model shows Role as a value object embedded in User, not a separate entity. Either the model or the schema should change."
+
+---
+
+## Pass 3: Normalization Justification
+
+### What to Check
+
+The normalization level of each table is justified. Deliberate denormalization has documented rationale (performance, read patterns). Accidental denormalization (duplicate data without awareness) is flagged.
+
+### Why This Matters
+
+Over-normalization causes excessive joins for common queries, degrading performance. Under-normalization causes data anomalies (update a value in one place but not another). Neither extreme is inherently wrong — but the choice must be deliberate and justified by the access patterns documented in the architecture's data flows.
+
+### How to Check
+
+1. For each table, assess its normalization level (1NF through 3NF/BCNF)
+2. Identify any tables below 3NF — is the denormalization intentional?
+3. For intentional denormalization, verify the justification references a specific query pattern or performance requirement
+4. Check for duplicate data across tables: does the same business data exist in two tables? If so, is there a synchronization mechanism?
+5. Look for tables with many nullable columns — these often indicate merged entities that should be separate tables
+6. Check computed/derived columns: are they cached values? How are they updated?
+
+### What a Finding Looks Like
+
+- P0: "Customer address is stored in both 'customers' and 'orders' tables with no documented synchronization. If a customer updates their address, historical orders show the new address instead of the address at time of order."
+- P1: "The 'orders' table stores product_name and product_price directly instead of referencing the products table. This is presumably for historical accuracy (price at time of purchase), but the rationale is not documented."
+- P2: "The 'user_stats' table has 12 computed columns (total_orders, lifetime_value, etc.) with no documentation of how or when they are recalculated."
+
+---
+
+## Pass 4: Index Coverage
+
+### What to Check
+
+Indexes cover the known query patterns from architecture data flows. Primary access paths have supporting indexes. No critical query requires a full table scan on a large table.
+
+### Why This Matters
+
+Missing indexes cause performance degradation that only appears at scale — the system works fine with test data but becomes unusable with production data volumes. Index coverage must be designed proactively based on known query patterns, not discovered reactively in production.
+
+### How to Check
+
+1. List every data flow from the architecture document that involves database reads
+2. For each read, identify the query pattern: what table, what filter columns, what sort order
+3. Verify an index exists that supports each query pattern
+4. Check for queries that filter on multiple columns: do composite indexes exist in the correct column order?
+5. Look for common patterns that always need indexes: foreign keys (for joins), status columns (for filtering), timestamp columns (for sorting/range queries), unique business identifiers
+6. Check for over-indexing: too many indexes on a write-heavy table degrade write performance
+
+### What a Finding Looks Like
+
+- P0: "Architecture data flow shows 'find all orders by customer, sorted by date' as a primary query, but orders table has no index on (customer_id, created_at)."
+- P1: "Foreign key column 'order_id' on 'line_items' table has no index. Every order retrieval with line items will require a full scan of line_items."
+- P2: "The 'events' table has 7 indexes but the architecture describes it as append-only with rare reads. Excessive indexing will slow writes."
+
+---
+
+## Pass 5: Constraint Enforcement
+
+### What to Check
+
+Database constraints enforce domain invariants where possible. NOT NULL, UNIQUE, CHECK, and FOREIGN KEY constraints reflect business rules from domain models.
+
+### Why This Matters
+
+Every invariant not enforced by the database must be enforced by application code. Application-level enforcement is less reliable: it can be bypassed by direct database access, missed in one code path, or broken during refactoring. Database constraints are the last line of defense against invalid data.
+
+### How to Check
+
+1. List every domain invariant from domain models
+2. For each invariant, determine: can it be enforced by a database constraint? (Some invariants require multi-table coordination and cannot be database-enforced)
+3. For enforceable invariants, verify the corresponding constraint exists in the schema
+4. Check NOT NULL constraints: which columns are nullable? Does that match domain model optionality?
+5. Check UNIQUE constraints: which business identifiers must be unique? Is that constraint in the schema?
+6. Check CHECK constraints: value ranges, valid states, format rules — are they enforced?
+7. Verify FOREIGN KEY constraints exist for all documented relationships
+
+### What a Finding Looks Like
+
+- P0: "Domain invariant 'email must be unique per tenant' has no UNIQUE constraint in the schema. Application code may enforce it, but concurrent requests could create duplicates."
+- P1: "Domain model says 'order status must be one of: draft, submitted, approved, shipped, delivered' but the status column is VARCHAR with no CHECK constraint."
+- P2: "Column 'quantity' on 'line_items' should have a CHECK (quantity > 0) constraint per domain invariant 'line items must have positive quantity'."
+
+---
+
+## Pass 6: Migration Safety
+
+### What to Check
+
+The migration plan handles rollbacks and data preservation. Destructive operations are identified. Data migrations are separated from schema migrations.
+
+### Why This Matters
+
+Schema migrations that cannot be rolled back are production risks. A failed deployment with an irreversible migration leaves the database in a state incompatible with both the old and new code. Data migrations mixed with schema changes make rollbacks impossible (schema can be reverted, but data transformations cannot).
+
+### How to Check
+
+1. Identify all schema changes that are destructive: dropping columns, dropping tables, changing column types, removing constraints
+2. For each destructive change, verify a rollback strategy exists (how to undo it)
+3. Check that data migrations (backfilling columns, transforming data) are separate from schema migrations
+4. Verify the migration ordering: dependencies between migrations are correct (cannot add a foreign key before the referenced table exists)
+5. Check for migrations that lock tables: ALTER TABLE on large tables can lock the table for the duration. Is this addressed (online DDL, batch processing)?
+6. Verify that the migration plan addresses zero-downtime deployment requirements if applicable
+
+### What a Finding Looks Like
+
+- P0: "Migration 005 drops the 'legacy_orders' table with no data export or rollback plan. If this migration runs and the new orders system has bugs, historical data is lost."
+- P1: "Migration 003 adds a NOT NULL column to a table with existing data but does not specify a default value or data backfill. The migration will fail on non-empty tables."
+- P2: "Migration 007 alters the type of 'amount' from INTEGER to DECIMAL. This is a potentially lossy change on large tables. Should use a blue-green column approach."
+
+---
+
+## Pass 7: Cross-Schema Consistency
+
+### What to Check
+
+If the system uses multiple databases or schemas, naming conventions, shared reference data, and cross-database relationships are consistent.
+
+### Why This Matters
+
+Multi-database architectures often evolve organically, with each database using its own conventions. When a concept (like user_id) exists in multiple databases with different types (UUID in one, integer in another) or different names (user_id vs. account_id), integration becomes fragile and error-prone.
+
+### How to Check
+
+1. List all databases or schemas in the architecture
+2. Verify naming conventions are consistent across all schemas (snake_case everywhere, or camelCase everywhere — not mixed)
+3. Check for shared identifiers: the same business entity referenced in multiple databases should use the same column name and data type
+4. Verify reference data consistency: if 'countries' or 'currencies' exist in multiple schemas, is there a single source of truth?
+5. Check for cross-database foreign key assumptions: if service A references service B's data by ID, is the ID type guaranteed to match?
+6. Verify that cross-schema query patterns are documented — direct cross-schema queries, API calls, or event-based synchronization?
+
+### What a Finding Looks Like
+
+- P0: "UserService uses UUID for user_id (CHAR(36)) but OrderService uses INTEGER for user_id. These are fundamentally incompatible — joins and references will fail."
+- P1: "Both AuthDB and MainDB have a 'users' table with overlapping but different columns. Which is the source of truth for user data?"
+- P2: "AuthDB uses snake_case (user_id) and MainDB uses camelCase (userId). Inconsistent naming will cause confusion."
+
+---
+
+## Pass 8: Downstream Readiness
+
+### What to Check
+
+The API contracts step can be built on this schema. The schema provides everything needed to design API endpoints, query patterns, and response shapes.
+
+### Why This Matters
+
+API endpoints translate database operations into client-facing contracts. If the schema cannot efficiently serve the queries that API endpoints need, the API layer must work around schema limitations — adding application-level joins, filtering, or transformations that belong in the database.
+
+### How to Check
+
+The API contracts step specifically needs:
+1. **CRUD operations** are straightforward on the schema — no endpoint requires a 5-table join for a basic read
+2. **List/search queries** have index support for filtering and pagination
+3. **Relationship traversal** is possible: "get order with its line items" does not require multiple disconnected queries
+4. **Aggregate queries** (counts, sums, averages) can be performed efficiently
+5. **Write operations** map cleanly to table inserts/updates without requiring complex multi-table transactions for basic operations
+6. **Soft delete vs. hard delete** is consistent across tables and matches API behavior expectations
+
+### What a Finding Looks Like
+
+- P0: "API will need 'get all orders for a customer with their line items and product details.' This requires joining orders -> line_items -> products, but line_items has no index on order_id, and the relationship from line_items to products is missing."
+- P1: "The schema supports 'get user by email' but the API will also need 'search users by name.' No index exists on user name columns."
+- P2: "Some tables use soft delete (deleted_at column) and some use hard delete. The API contract needs to know which approach applies to determine whether 'delete' operations return 204 or 200."

package/knowledge/review/review-domain-modeling.md

@@ -0,0 +1,288 @@
+---
+name: review-domain-modeling
+description: Failure modes and review passes specific to domain modeling artifacts
+topics: [review, domain-modeling, ddd, bounded-contexts]
+---
+
+# Review: Domain Modeling
+
+Domain models are the foundation of the entire pipeline. Every subsequent phase builds on them. A gap or error here compounds through ADRs, architecture, database schema, API contracts, and implementation tasks. This review uses 10 passes targeting the specific ways domain models fail.
+
+Follows the review process defined in `review-methodology.md`.
+
+---
+
+## Pass 1: PRD Coverage Audit
+
+### What to Check
+
+Every feature and requirement in the PRD maps to at least one domain. No PRD requirement exists without a domain home. No domain exists without PRD traceability.
+
+### Why This Matters
+
+Orphaned requirements — PRD features that no domain covers — mean the system literally cannot implement those features. Phantom domains — domains with no PRD traceability — indicate scope creep or misunderstanding of the problem space. Both cause expensive rework when discovered during implementation.
+
+### How to Check
+
+1. List every feature from the PRD (use the feature list, user stories, or requirements section)
+2. For each feature, identify which domain(s) it touches
+3. Mark features that have no domain mapping — these are orphaned
+4. List all domains and bounded contexts from the domain models
+5. For each domain, trace back to at least one PRD feature
+6. Mark domains with no PRD traceability — these are phantoms
+7. Check that non-functional requirements (performance, security, scalability) are reflected in domain constraints where relevant
+
+### What a Finding Looks Like
+
+- P0: "PRD feature 'Multi-tenant billing' has no domain mapping. No bounded context addresses tenant isolation or billing lifecycle."
+- P1: "Domain 'Analytics' has no PRD traceability. The PRD mentions reporting but not analytics as a separate concern."
+- P2: "PRD non-functional requirement 'sub-200ms API response' is not reflected in any domain model constraint."
+
+---
+
+## Pass 2: Bounded Context Integrity
+
+### What to Check
+
+Context boundaries are clean. No entity appears in multiple contexts without an explicit integration relationship. Shared kernels are documented. Anticorruption layers exist at context boundaries.
+
+### Why This Matters
+
+Leaky context boundaries are the most common domain modeling failure. When an entity like "User" appears in three contexts with slightly different meanings, implementing agents build tight coupling between modules. This causes merge conflicts, circular dependencies, and change amplification — modifying one context breaks others.
+
+### How to Check
+
+1. For each bounded context, list its entities and value objects
+2. Search for entity names that appear in multiple contexts
+3. For each shared name, determine: is it genuinely shared (shared kernel), or is it a different concept with the same name (homonym indicating a boundary)?
+4. Verify shared kernel entities have explicit documentation of what is shared and who owns changes
+5. At every context boundary, verify the integration mechanism is specified (domain events, API calls, shared database, anticorruption layer)
+6. Check that no context directly references another context's internal entities
+
+### What a Finding Looks Like
+
+- P0: "'Order' entity appears in Catalog, Checkout, and Fulfillment contexts with different attributes but no integration relationship documented."
+- P1: "Shared kernel between Auth and User Profile contexts exists but does not specify ownership of the 'email' field."
+- P2: "Context map exists but does not specify whether upstream/downstream relationships use conformist, anticorruption layer, or open host patterns."
+
+---
+
+## Pass 3: Entity vs Value Object Classification
+
+### What to Check
+
+Entities have identity and lifecycle. Value objects are immutable and compared by value. Misclassification is a common error that propagates into database schema and API design.
+
+### Why This Matters
+
+Misclassifying an entity as a value object means losing its lifecycle tracking — no history, no identity-based lookups. Misclassifying a value object as an entity means unnecessary database tables, unnecessary IDs, and unnecessary complexity. Both lead to schema rework.
+
+### How to Check
+
+For each entity, ask:
+1. Does this concept need to be tracked over time? (If not, it may be a value object)
+2. Are two instances with identical attributes the same thing or different things? (If same, it is a value object)
+3. Does this concept have a lifecycle with distinct states? (If not, it may be a value object)
+
+For each value object, ask:
+1. Would the system ever need to update this independently? (If yes, it may be an entity)
+2. Does this concept appear in domain events as a subject (not just data)? (If yes, it may be an entity)
+3. Does this concept need a unique identifier for reference? (If yes, it is an entity)
+
+### What a Finding Looks Like
+
+- P1: "'Address' is modeled as an entity with an ID, but two addresses with the same street/city/zip are semantically identical. Should be a value object."
+- P1: "'Price' is modeled as a value object, but the system needs to track price history and price changes. Should be an entity with a lifecycle."
+- P2: "'Currency' is modeled as an entity but has no lifecycle — it is a static reference value. Consider value object or reference data."
+
+---
+
+## Pass 4: Aggregate Boundary Validation
+
+### What to Check
+
+Aggregates enforce consistency boundaries. Each aggregate is the right size — large enough to enforce its invariants, small enough to avoid contention.
+
+### Why This Matters
+
+Too-large aggregates lock too much data during updates, causing concurrency bottlenecks and unnecessary transaction scope. Too-small aggregates cannot enforce their invariants, leading to inconsistent state. Wrong aggregate boundaries are the most expensive domain modeling error to fix post-implementation because they affect database schema, API contracts, and transaction boundaries.
+
+### How to Check
+
+1. For each aggregate, list its invariants (from Pass 6 if already done, or identify them now)
+2. Verify each invariant can be enforced within the aggregate's boundary without reaching into other aggregates
+3. Check for aggregates that reference other aggregates by direct object reference (should use ID reference instead)
+4. Look for aggregates with more than 5-7 entities — these are likely too large
+5. Look for invariants that span multiple aggregates — these indicate either wrong boundaries or the need for a domain service/saga
+6. Check that aggregate roots are clearly identified and that all access to aggregate internals goes through the root
+
+### What a Finding Looks Like
+
+- P0: "Invariant 'order total must equal sum of line items minus discounts' spans Order aggregate and Discount aggregate. Either Discount should be inside Order aggregate, or this invariant needs a domain service."
+- P1: "Customer aggregate contains Order history directly. This means updating an order locks the entire customer. Order should be a separate aggregate referencing Customer by ID."
+- P2: "Product aggregate root is not explicitly identified. Three entities (Product, Variant, Pricing) could each be the root."
+
+---
+
+## Pass 5: Domain Event Completeness
+
+### What to Check
+
+Every meaningful state transition produces a domain event. Events capture business-meaningful changes (not CRUD operations). Event payloads carry sufficient context for consumers.
+
+### Why This Matters
+
+Missing domain events mean downstream consumers cannot react to state changes. In event-driven architectures, missing events create invisible data synchronization gaps. Even in non-event-driven systems, domain events document the system's behavior contract — what happens when state changes.
+
+### How to Check
+
+1. For each entity with a lifecycle, trace through its state transitions
+2. Verify each transition has a corresponding domain event
+3. Check that events are named in past tense business language ("OrderPlaced" not "CreateOrder" or "OrderCreated")
+4. Verify event payloads include enough context for consumers to act without querying back to the source
+5. Check for state transitions that happen implicitly (timer-based, batch, external trigger) — these often lack events
+6. Verify events do not carry the entire entity state (anti-pattern) — they should carry what changed and context
+
+### What a Finding Looks Like
+
+- P0: "Order has states Draft, Submitted, Approved, Shipped, Delivered but only OrderPlaced and OrderShipped events exist. Missing: OrderApproved, OrderDelivered."
+- P1: "UserRegistered event carries only userId. Downstream services (email, analytics) need email address and registration source. Payload is insufficient."
+- P2: "Events use inconsistent naming: 'OrderPlaced' (past tense) vs 'ShipOrder' (imperative). Standardize to past tense."
+
+---
+
+## Pass 6: Invariant Specification
+
+### What to Check
+
+Invariants are testable assertions with clear conditions. Each specifies what must be true, when it applies, and what happens on violation.
+
+### Why This Matters
+
+Vague invariants like "orders must be valid" are unimplementable. Implementing agents need precise, testable rules to write validation logic and tests. Missing invariants mean missing validation — the system accepts invalid state.
+
+### How to Check
+
+1. For each aggregate, list all invariants
+2. For each invariant, verify it is a testable boolean assertion (not a vague statement)
+3. Check that the invariant specifies its scope: always true? Only in certain states? Only for certain entity types?
+4. Verify violation behavior is specified: reject the operation? Compensate? Log and continue?
+5. Look for implicit invariants that are obvious to domain experts but not documented (uniqueness constraints, ordering constraints, temporal constraints)
+6. Check for invariants that reference external state — these may need special handling
+
+### What a Finding Looks Like
+
+- P0: "Invariant 'an order must be valid' is not testable. What constitutes validity? Minimum one line item? Non-negative total? Valid shipping address?"
+- P1: "Uniqueness of email within an account is implied by the registration flow but not stated as an invariant. This needs explicit specification."
+- P1: "Invariant 'discount cannot exceed order total' does not specify violation behavior. Should the operation be rejected, or should the discount be capped?"
+
+---
+
+## Pass 7: Ubiquitous Language Consistency
+
+### What to Check
+
+Terminology is consistent across all domain models. No synonyms (different words for the same concept). No homonyms (same word for different concepts — these indicate a context boundary).
+
+### Why This Matters
+
+Inconsistent terminology causes implementing agents to build the wrong thing. If "Customer" means "authenticated user" in one context and "billing entity" in another without clarification, the agent picks one interpretation and builds to it. Synonyms cause duplicate implementations — two services doing the same thing under different names.
+
+### How to Check
+
+1. Build a glossary from all domain models: every noun (entity, value object, event, service)
+2. Search for synonyms: different terms that seem to mean the same thing (Customer/Client/User, Order/Purchase/Transaction)
+3. For each synonym pair, determine: truly the same concept (pick one term) or subtly different concepts (define the distinction)
+4. Search for homonyms: same term used in different contexts with different attributes or behavior
+5. For each homonym, determine: should be the same concept (align definitions) or should be different concepts (this is a context boundary — document it)
+6. Check that event names, aggregate names, and relationship names use terms from the glossary
+
+### What a Finding Looks Like
+
+- P0: "'User' means an authenticated identity in the Auth context but a customer profile in the Commerce context. This is a valid context boundary but is not documented as such."
+- P1: "Domain models use both 'Order' and 'Purchase' to refer to the same concept. Pick one and use it everywhere."
+- P2: "'Item' is used informally in narrative sections but the formal model uses 'LineItem'. Align informal usage."
+
+---
+
+## Pass 8: Cross-Domain Relationship Clarity
+
+### What to Check
+
+Relationships between domains are explicit. Direction of dependency is clear. Communication mechanism is specified.
+
+### Why This Matters
+
+Implicit cross-domain relationships become implicit runtime dependencies. If Domain A references Domain B's entities without specifying the mechanism, implementing agents create tight coupling. During implementation, this manifests as import cycles, deployment ordering issues, and cascading failures.
+
+### How to Check
+
+1. List all relationships between bounded contexts (the context map)
+2. For each relationship, verify: upstream/downstream direction, communication mechanism (events, direct API, shared database), data that flows across the boundary
+3. Check for undocumented relationships: does Domain A reference concepts from Domain B without a documented relationship?
+4. Verify that no domain depends on another domain's internal structure (only on its published interface)
+5. Look for circular dependencies between domains — these usually indicate incorrect boundaries
+6. Check that relationship multiplicity is specified (one-to-one, one-to-many, many-to-many)
+
+### What a Finding Looks Like
+
+- P0: "Billing domain references Order domain entities directly but no relationship is documented. Is Billing downstream of Orders? Does it receive events or query an API?"
+- P1: "Context map shows Inventory upstream of Orders, but Orders also writes to Inventory (stock reservation). This is a bidirectional dependency that needs explicit handling."
+- P2: "Relationship between Auth and Notification domains specifies 'events' but does not name the specific events."
+
+---
+
+## Pass 9: Downstream Readiness
+
+### What to Check
+
+The ADRs step needs specific information from domain models. Verify that information is present and sufficient.
+
+### Why This Matters
+
+ADRs make technology and pattern decisions informed by domain complexity. If domain models do not surface the constraints and characteristics that drive those decisions, ADRs are made on assumptions rather than analysis.
+
+### How to Check
+
+The ADRs step specifically needs:
+1. **Clear domain boundaries** — To decide on module/service decomposition strategy
+2. **Technology-relevant constraints** — Real-time requirements, data volume projections, consistency requirements that influence technology selection
+3. **Performance-sensitive operations** — Operations with latency, throughput, or data volume requirements that affect architecture decisions
+4. **Integration complexity** — How many cross-domain interactions exist, their frequency, their consistency requirements
+5. **Data storage characteristics** — Relational vs. document vs. graph patterns visible in the domain models
+6. **Security boundaries** — Which domains handle sensitive data, authentication, authorization
+
+For each item, verify it is explicitly present in the domain models or can be reasonably inferred.
+
+### What a Finding Looks Like
+
+- P0: "No domain model mentions data volume or throughput characteristics. The ADRs step cannot make database technology decisions without this information."
+- P1: "Real-time requirements are mentioned in the PRD but not reflected in any domain model's constraints section."
+- P2: "Data storage patterns are implicit (relational structure visible) but not explicitly stated as a constraint or preference."
+
+---
+
+## Pass 10: Internal Consistency
+
+### What to Check
+
+Cross-references resolve. Terminology does not drift within a single model. No contradictions between entity definitions and relationship diagrams.
+
+### Why This Matters
+
+Internal inconsistencies within a single domain model erode trust in the artifact. If an entity's attributes list says one thing and the relationship diagram says another, the implementing agent must guess which is correct. Cumulative small inconsistencies make the entire model unreliable.
+
+### How to Check
+
+1. For each cross-reference (entity A "references" entity B), verify entity B exists and the reference direction matches
+2. Check that entity attribute lists match what the relationship diagrams show
+3. Verify that invariants reference entities and attributes that actually exist in the model
+4. Check that domain events reference entities and state transitions defined in the model
+5. Look for terminology drift: same concept called different things in different sections of the same document
+6. Verify that aggregates contain exactly the entities they claim to contain — not more, not fewer
+
+### What a Finding Looks Like
+
+- P0: "Invariant 'PaymentAmount must not exceed OrderTotal' references PaymentAmount, but the Payment entity has an attribute called 'amount', not 'paymentAmount'."
+- P1: "Relationship diagram shows Order -> Customer as one-to-many, but the Order entity definition says 'each order belongs to one customer' (many-to-one). Direction is inverted."
+- P2: "The Inventory domain model calls the same concept 'stock level' in the overview and 'quantity on hand' in the entity definition."