# Category Ordering & Dependency Rules

> **Loaded by:** step-02 (task ordering validation) and compact-loop.md (batch grouping)
> **Purpose:** Defines execution order, dependencies, and batch grouping rules.
> **Note:** All execution rules, MCP tool usage, conventions, and POST-CHECKs are in `/apex` references.

---

## Execution Order

Tasks MUST be executed in this order. Each category depends on the previous ones.

| Order | Category | Depends On | Description |
|-------|----------|------------|-------------|
| 0 | `domain` | — | Entities, enums, value objects |
| 1 | `infrastructure` | domain | EF configs, migrations, seed data |
| 2 | `application` | infrastructure | Services, DTOs, validators, DI |
| 3 | `api` | application | Controllers, route attributes |
| 4 | `seedData` | api | Navigation, permissions, roles, dev data |
| 5 | `frontend` | seedData | Pages, routes, i18n, components |
| 6 | `test` | frontend | Unit tests, integration tests, coverage |

> **Key dependency:** `frontend` depends on `seedData` (not just `api`).
> Navigation seed data drives the menu — without it, frontend routes have no menu entries.

---

## Dependency Rules

1. **A task can only start when ALL its dependencies are `completed`**
2. **If a dependency is `failed` or `blocked`, the task becomes `blocked`**
3. **Cross-category dependencies are implicit** — domain before infrastructure, etc.
4. **Same-category tasks MAY run in parallel** (batched together)
5. **PRD `dependencies[]` array overrides implicit ordering** — explicit deps always checked first

---

## Person Role Entities

Entities with `personRoleConfig` (Person Extension Pattern) have a special architectural requirement:

- **ICoreDbContext access required**: Person Extension entities need to read User data from the core schema
- This is an **exception** to the normal pattern where extension entities only use `IExtensionsDbContext`
- Service must inject BOTH `IExtensionsDbContext` (for the entity) AND `ICoreDbContext` (for User reads)
- Service must `Include(x => x.User)` on all queries
- For mandatory mode: search on `User.FirstName`, `User.LastName`, `User.Email`
- For optional mode: search with fallback (`User?.FirstName ?? x.FirstName`)

---

## Batch Grouping Rules

When selecting tasks for a batch:

1. **Group by category** — take the first eligible category with pending tasks
2. **Max batch size: 5 tasks** — prevents overloading a single apex invocation
3. **Same category only** — never mix domain + infrastructure in one batch
4. **Order within batch: by task ID** (ascending) — preserves PRD creation order

```javascript
const eligible = prd.tasks.filter(/* pending + deps met */);
const firstCategory = eligible[0].category;
const batch = eligible.filter(t => t.category === firstCategory).slice(0, 5);
```

---

## PRD Category Completeness

A valid PRD MUST contain tasks in these categories:

- `domain` — at least 1 entity task
- `infrastructure` — at least 1 EF config + migration task
- `application` — at least 1 service task
- `api` — at least 1 controller task
- `seedData` — at least 1 navigation/permission task
- `frontend` — at least 1 page task
- `test` — at least 1 test task

If any category is missing, ralph step-01 injects a guardrail task.

---

## Section-Level Splitting (>4 Entities)

When a module has many entities, a single `/apex -d` call saturates the context window.
Section-level splitting breaks the module into smaller, manageable phases.

**Activation threshold:** `> 4 domain tasks` AND `> 1 architecture section`

| Phase | Content | Depends On |
|-------|---------|------------|
| Phase 0 | ALL domain + infrastructure + migration + module seed data | — |
| Phase 1 | Section A: services, controllers, section seed, pages, i18n, tests | Phase 0 |
| Phase 2 | Section B: idem | Phase 0 (+ Phase 1 if FK cross-section) |
| Phase N | Section N: idem | Phase 0 (+ earlier phases if FK) |
| Final | Cross-validation (dotnet build, typecheck, MCP validate) | All phases |

**Key rules:**
- Phase 0 creates ALL entity classes + ALL EF configs + ONE migration (avoids ModelSnapshot conflicts)
- Section phases NEVER create entities or migrations — only services, controllers, pages on top
- FK cross-section dependencies determine section execution order (topological sort)
- Orphan entities (not in any section) are included in Phase 0 with their services/controllers
- Each phase produces a temporary PRD file: `.ralph/prd-{module}-phase0.json`, `.ralph/prd-{module}-section-{code}.json`
- Temporary PRD files are cleaned up in step-05 (report)

**Backward compatible:** Modules with `<= 4 domain tasks` or `1 section` → standard execution, zero impact.

See `references/section-splitting.md` for full detection, mapping, and execution logic.
