# Model Doc → Model Code Parity Check

## Context

Module: {{MODULE_NAME}}
Model docs: {{MODEL_DOCS}}
Model code: {{MODEL_CODE}}

## Instructions

1. Read ALL model docs at the paths above
2. Read ALL model code files at the paths above
3. For each model doc, extract fields, types, required/optional, relationships, state transitions, and descriptions
4. For each model code file, extract `createEntityType()` fields, status enums, foreign keys, and `.description()` calls
5. Run every parity check below against each model
6. Return results as JSON per the Output Format section

## Extraction: Model Docs

From each model doc, extract:

- **Fields**: name, type, required vs optional
- **Relationships**: foreign key fields and their target entities
- **State transitions**: status enum values from state diagrams
- **Constraints**: uniqueness, validation rules
- **Descriptions**: field-level descriptions

## Extraction: Model Code

From each model code file (`db/*.ts`), extract:

- **Fields**: in `createEntityType()` or equivalent
- **Status enums**: base statuses + additional statuses
- **Foreign keys**: references to other entity types
- **Descriptions**: `.description()` calls on fields

## Parity Checks

For each model:

| Check ID           | Question                                                         |
| ------------------ | ---------------------------------------------------------------- |
| field_coverage     | Does code include all fields from model doc?                     |
| type_accuracy      | Do field types in code match doc specification?                  |
| required_fields    | Are required fields enforced (no default, not nullable)?         |
| relationship_impl  | Are foreign key fields implemented for documented relationships? |
| cross_module_fk    | Are cross-module FK type params required (not optional) in `CreateTypeParams`, and used directly without `??` fallback in `.relation()`? |
| state_transitions  | Does status enum include all documented states?                  |
| lifecycle_usage    | Does model import from `.lifecycle.generated.ts` and use `lifecycle.states` for the status enum (instead of a hardcoded array)? |
| field_descriptions | Do `.description()` calls match doc field descriptions?          |

### How to Check

1. List all fields from model doc
2. Find corresponding field in `createEntityType()` code
3. Compare type, required/optional, description
4. Check status enum values against state diagram
5. Verify foreign key fields exist for all documented relationships

## Common Gap Patterns

- **Missing fields**: Doc specifies field but not in code
- **Type mismatches**: Doc says string, code uses number
- **Missing status values**: State diagram shows state not in enum
- **Missing relationships**: Doc shows FK but not implemented
- **Missing descriptions**: Doc has field description but no `.description()`
- **Optional cross-module FK params**: Cross-module type param is `?` optional in `CreateTypeParams` or uses `?? stub` fallback in `.relation()` — should be required and used directly
- **Hardcoded status enum**: Model has a State Transitions table in doc but uses a hardcoded array instead of importing from `.lifecycle.generated.ts`

## Output Format

Return a JSON object:

```json
{
  "check_type": "model-doc-code-parity",
  "module": "{{MODULE_NAME}}",
  "gaps": [...],
  "inconsistencies": [...],
  "summary": { "total_checks": N, "passed": N, "failed": N, "skipped": N }
}
```

See [impl-parity-report-format.md](impl-parity-report-format.md) for field definitions.
