@atlashub/smartstack-cli 3.33.0 → 3.35.0

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -1,7 +1,7 @@
-# Compact Loop — Inline Execution
+# Compact Loop — Delegate to /apex
 
 > **Loaded by:** step-04 section 5 (after first full iteration)
-> **Purpose:** Execute ALL remaining tasks autonomously without stopping.
+> **Purpose:** Execute ALL remaining tasks autonomously by delegating to /apex.
 > **EXECUTION GUARANTEE:** This loop runs until ALL tasks are done, max iterations, or dead-end.
 > **ABSOLUTE RULES:**
 > - NEVER stop the loop
@@ -9,6 +9,7 @@
 > - NEVER ask for confirmation
 > - NEVER re-read step files
 > - NEVER pause between iterations
+> - NEVER generate code directly — delegate to /apex
 > - Execute A → B → C → D → back to step-04 section 1 → repeat
 
 ---
@@ -22,12 +23,122 @@ Display compact progress:
 
 ---
 
-## A. Find Eligible Tasks
+## A0. Section-Split Mode (checked BEFORE standard batching)
 
 ```javascript
 const prd = readJSON('.ralph/prd.json');
 
-// Block tasks whose dependencies failed
+if (prd._sectionSplit?.enabled) {
+  // SECTION-SPLIT: Delegate per-phase instead of per-category batch
+
+  // Find next pending phase with dependencies met
+  const nextPhase = prd._sectionSplit.phases.find(p => p.status === 'pending');
+
+  if (!nextPhase) {
+    // All phases done — check if master PRD tasks are all complete
+    goto CHECK_COMPLETION;
+  }
+
+  const depsOk = nextPhase.dependsOn.every(depIdx =>
+    prd._sectionSplit.phases[depIdx].status === 'completed'
+  );
+
+  if (!depsOk) {
+    // Phase blocked — should not happen with topological sort
+    console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
+    goto CHECK_COMPLETION;
+  }
+
+  const phaseLabel = nextPhase.type === 'foundation'
+    ? `Phase 0: Foundation (${nextPhase.entities.length} entities + migration)`
+    : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (${nextPhase.entities.length} entities)`;
+  console.log(`[{iteration}/{max}] SECTION SPLIT: ${phaseLabel}`);
+
+  // INVOKE /apex -d {nextPhase.prdFile}
+  // Apex sees a normal (smaller) PRD and executes normally
+
+  // After apex returns: merge results back into master PRD
+  // Read references/section-splitting.md sections 7-9
+  const phasePrd = readJSON(nextPhase.prdFile);
+  for (const phaseTask of phasePrd.tasks) {
+    const masterTask = prd.tasks.find(t => t.id === phaseTask.id);
+    if (masterTask) {
+      masterTask.status = phaseTask.status;
+      masterTask.completed_at = phaseTask.completed_at;
+      masterTask.commit_hash = phaseTask.commit_hash;
+      masterTask.files_changed = phaseTask.files_changed;
+      masterTask.error = phaseTask.error;
+      masterTask.validation = phaseTask.validation;
+    }
+  }
+
+  // Handle phase failure
+  if (phasePrd.tasks.some(t => t.status === 'failed')) {
+    const retryCount = nextPhase._retryCount || 0;
+    if (retryCount < 2) {
+      nextPhase.status = 'pending';
+      nextPhase._retryCount = retryCount + 1;
+      console.log(`Phase ${nextPhase.phase} had failures — retry ${retryCount + 1}/2`);
+      // Reset failed tasks in phase PRD for retry
+      for (const task of phasePrd.tasks) {
+        if (task.status === 'failed') { task.status = 'pending'; task.error = null; }
+      }
+      writeJSON(nextPhase.prdFile, phasePrd);
+    } else {
+      nextPhase.status = 'failed';
+      console.error(`Phase ${nextPhase.phase} failed after 2 retries`);
+    }
+  } else {
+    nextPhase.status = 'completed';
+  }
+
+  prd._sectionSplit.currentPhase = nextPhase.phase;
+  writeJSON('.ralph/prd.json', prd);
+
+  // → Skip to section C (commit PRD state), then D (loop back)
+  goto COMMIT_PRD;
+}
+```
+
+> **IMPORTANT:** When `_sectionSplit.enabled`, the standard category-based batching (section A below)
+> is SKIPPED. The loop delegates per-phase to apex instead of per-category-batch.
+
+---
+
+## A. Find Eligible Tasks
+
+> **Note:** This section is SKIPPED when `prd._sectionSplit?.enabled` (handled by A0 above).
+
+```javascript
+const MAX_RETRIES = 3;
+
+// RETRY: Reset failed tasks to pending if retries remain (max 3 attempts per task)
+for (const task of prd.tasks) {
+  if (task.status !== 'failed') continue;
+  const retryCount = task._retryCount || 0;
+  if (retryCount < MAX_RETRIES) {
+    task.status = 'pending';
+    task._retryCount = retryCount + 1;
+    task.error = null;
+    console.log(`RETRY [${task.id}] attempt ${retryCount + 1}/${MAX_RETRIES}: ${task.description.substring(0, 60)}`);
+  }
+}
+
+// Unblock tasks whose dependencies are no longer failed (due to retries above)
+for (const task of prd.tasks) {
+  if (task.status !== 'blocked') continue;
+  const stillBlocked = task.dependencies.some(depId => {
+    const dep = prd.tasks.find(t => t.id === depId);
+    return dep && (dep.status === 'failed' || dep.status === 'blocked');
+  });
+  if (!stillBlocked) {
+    task.status = 'pending';
+    task.error = null;
+    console.log(`UNBLOCKED [${task.id}]: dependencies resolved`);
+  }
+}
+
+// Block pending tasks whose dependencies are still failed/blocked
 for (const task of prd.tasks) {
   if (task.status !== 'pending') continue;
   const depsBlocked = task.dependencies.some(depId => {
@@ -37,6 +148,8 @@ for (const task of prd.tasks) {
   if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
 }
 
+writeJSON('.ralph/prd.json', prd);
+
 // Find ALL eligible tasks (dependencies met)
 const eligible = prd.tasks.filter(task => {
   if (task.status !== 'pending') return false;
@@ -63,463 +176,110 @@ Batch: {batch.length} [{firstCategory}] → {batch.map(t => `[${t.id}] ${t.descr
 
 ---
 
-## B. Execute Batch
-
-**For EACH task in batch:**
-
-1. Mark `task.status = 'in_progress'`, `task.started_at = now`
-2. **Read `references/category-rules.md`** for category-specific rules
-2bis. **For frontend tasks:** Also read back the original **feature.json** (via `prd.source.featurePath`) to access wireframe `componentMapping`, `columnDefs`, `layout`, `emptyState`, `rowActions`, and `i18n` keys that the PRD does NOT carry forward. The PRD only has the file list — the behavioral spec is in feature.json.
-3. Implement the task following SmartStack conventions
-4. Track `files_created` and `files_modified`
-
-**Execution cycle per task:**
-1. Generate code following category-rules.md
-2. **BUILD verification (BLOCKING per task):**
-   - Backend (domain/infra/app/api): `dotnet build --no-restore` → MUST exit 0
-   - Frontend: `npm run typecheck` → MUST exit 0
-3. If build fails → **CLASSIFY ERROR FIRST** (read `references/error-classification.md`):
-   - **Category A/B (assembly/package):** Run `dotnet add package {Name}` → `dotnet restore` → rebuild. Do NOT edit source code.
-   - **Category C (DI):** Edit DI registration file only → rebuild.
-   - **Category D (migration):** Run migration commands → rebuild.
-   - **Category E (config):** Edit config file → rebuild.
-   - **Category F (code):** Fix source code → rebuild → loop until pass.
-   - **If 2+ rebuild attempts fail on same error and Category F was chosen:** Re-classify — likely wrong category.
-4. **ARTIFACT verification (BLOCKING per task):**
-   - `files_created` MUST NOT be empty for code-generating tasks
-   - Category-specific checks (see below)
-   - IF no artifacts produced → task.status = 'failed', task.error = 'No artifacts created'
-5. Verify acceptance criteria from task description
-6. If failed after 3 attempts: `task.status = 'failed'`, `task.error = reason`, continue to next in batch
-
-**Category-specific artifact checks (step 4 above):**
-
-| Category | Artifact Check | FAIL if |
-|----------|---------------|---------|
-| `domain` | Entity .cs files exist in Domain/ | 0 files created |
-| `infrastructure` with migration | `Migrations/` folder has .cs files | No migration files |
-| `infrastructure` with seed data | Seed data .cs files exist | 0 files created |
-| `application` | Service + DTO + Validator files exist | 0 files created |
-| `api` | Controller .cs files exist + GetAll supports `?search=` | 0 files created OR GetAll without search param |
-| `frontend` | .tsx page files exist + FK fields use EntityLookup (not plain text) | 0 files created OR FK Guid field as `<input type="text">` |
-| `test` | Test project dir exists AND contains test .cs files | No test project or 0 test files |
-| `validation` | `dotnet test` exit 0 AND `dotnet build` exit 0 | Either command fails |
-
-**Category-specific triggers:**
-
-| Category | Action |
-|----------|--------|
-| `infrastructure` with `_migrationMeta` | Migration sequence: `suggest_migration` MCP → `dotnet ef migrations add` → cleanup corrupted artifacts (`for d in src/*/bin?Debug; do [ -d "$d" ] && rm -rf "$d"; done`) → `dotnet ef database update` → `dotnet build` |
-| `infrastructure` with seed data keywords | **MANDATORY:** Read `references/core-seed-data.md` → implement templates → `dotnet build` |
-| `frontend` | MCP-first: `scaffold_api_client` → `scaffold_routes` (outputFormat: clientRoutes) → **wire to App.tsx** → **LOAD `/ui-components` skill** before creating ANY page → create pages using skill patterns (SmartTable, EntityCard, CSS variables, StatusBadge) → ALL visible text via `t()` from first line → `npm run typecheck && npm run lint` → **run frontend POST-CHECKs (section 3bis below)** |
-| `test` | **Create tests:** `scaffold_tests` MCP → **Run:** `dotnet test --verbosity normal` → **Fix loop:** if fail → fix SOURCE CODE → rebuild → retest → repeat until 100% pass |
-| `validation` | `dotnet clean && dotnet restore && dotnet build` → `dotnet test` (full) → `validate_conventions` MCP |
-
-**Post-batch verification (BLOCKING — ALL must pass before commit):**
-
-1. **Backend build:**
-   ```bash
-   dotnet build --no-restore
-   ```
-   If FAIL → fix → rebuild → DO NOT commit until exit 0
-
-2. **Tests (if test tasks in batch OR after infrastructure batch):**
-   ```bash
-   TEST_PROJECT="tests/$(basename $(pwd)).Tests.Unit"
-   dotnet test "$TEST_PROJECT" --no-build --verbosity normal
-   ```
-   If FAIL → fix source code (NOT tests) → rebuild → retest → loop until 100% pass
-
-2bis. **Runtime assembly check (if api/validation tasks in batch):**
-   ```bash
-   API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
-   if [ -n "$API_PROJECT" ]; then
-     dotnet run --project "$API_PROJECT" --urls "http://localhost:5098" > /tmp/ralph-startup-check.log 2>&1 &
-     CHECK_PID=$!
-     sleep 5
-     if ! kill -0 $CHECK_PID 2>/dev/null; then
-       CRASH_OUTPUT=$(cat /tmp/ralph-startup-check.log 2>/dev/null)
-       echo "RUNTIME ASSEMBLY ERROR DETECTED"
-       # Classify per references/error-classification.md
-       # If Category A: dotnet add package → rebuild → DO NOT count as iteration failure
-     fi
-     kill $CHECK_PID 2>/dev/null
-     wait $CHECK_PID 2>/dev/null
-     rm -f /tmp/ralph-startup-check.log
-   fi
-   ```
-   If FAIL → classify error per `references/error-classification.md` → apply fix → rebuild → verify again
-
-2ter. **DI completeness (if application tasks in batch):**
-   Verify `Application/DependencyInjection.cs` registers all validators and services:
-   - Count validators in `Validators/` folder
-   - Verify `AddValidatorsFromAssemblyContaining` is present
-   - If empty/TODO → FAIL → fix DI registration → rebuild
-
-3. **Frontend (if frontend/i18n tasks in batch):**
-   ```bash
-   npm run typecheck && npm run lint
-   ```
-   If FAIL → fix → re-check → loop until pass
-
-3bis. **Frontend POST-CHECKs (BLOCKING — if frontend tasks in batch):**
-
-   > **CRITICAL:** These checks enforce /ui-components compliance, i18n, and route conventions.
-   > Without them, generated code silently regresses to raw HTML tables, hardcoded colors, and English-only text.
-
-   ```bash
-   # Resolve paths dynamically (handles web/ prefix)
-   PAGE_DIR=$(find . -path "*/src/pages" -not -path "*/node_modules/*" -type d 2>/dev/null | head -1)
-   HOOK_DIR=$(find . -path "*/src/hooks" -not -path "*/node_modules/*" -type d 2>/dev/null | head -1)
-   COMP_DIR=$(find . -path "*/src/components" -not -path "*/node_modules/*" -type d 2>/dev/null | head -1)
-   WEB_SRC=$(find . -name "App.tsx" -not -path "*/node_modules/*" -exec dirname {} \; 2>/dev/null | head -1)
-
-   if [ -n "$PAGE_DIR" ]; then
-     # BLOCKING: No raw HTML <table> — MUST use SmartTable/DataTable
-     RAW_TABLES=$(grep -rPn '<table[\s>]|<thead[\s>]|<tbody[\s>]' "$PAGE_DIR" --include="*.tsx" 2>/dev/null)
-     if [ -n "$RAW_TABLES" ]; then
-       echo "BLOCKING: Raw HTML <table> detected — MUST use SmartTable or DataTable"
-       echo "$RAW_TABLES" | head -5
-       # FIX REQUIRED before commit
-     fi
-
-     # BLOCKING: No hardcoded Tailwind colors — MUST use CSS variables
-     HARDCODED_COLORS=$(grep -rPn '(?:bg|text|border|ring)-(?:red|blue|green|yellow|orange|purple|pink|indigo|teal|cyan|emerald|violet|fuchsia|rose|amber|lime|sky|slate|gray|zinc|neutral|stone)-\d{2,3}' "$PAGE_DIR" "$COMP_DIR" --include="*.tsx" 2>/dev/null | head -10)
-     if [ -n "$HARDCODED_COLORS" ]; then
-       echo "BLOCKING: Hardcoded Tailwind colors — MUST use CSS variables (bg-[var(--bg-secondary)])"
-       echo "$HARDCODED_COLORS" | head -5
-       # FIX REQUIRED before commit
-     fi
-
-     # BLOCKING: No window.confirm() — use ConfirmDialog component
-     BAD_CONFIRM=$(grep -rPn 'window\.confirm\s*\(' "$PAGE_DIR" --include="*.tsx" 2>/dev/null | grep -v '//')
-     if [ -n "$BAD_CONFIRM" ]; then
-       echo "BLOCKING: window.confirm() detected — use ConfirmDialog component with i18n"
-       echo "$BAD_CONFIRM"
-       # FIX REQUIRED before commit
-     fi
-
-     # BLOCKING: No hardcoded English UI text in JSX
-     HARDCODED_TEXT=$(grep -rPn '>\s*(Create|Edit|Delete|Save|Cancel|Search|Loading|Error|No .* found|Are you sure|Submit|Back|Actions|Status)\s*<' "$PAGE_DIR" --include="*.tsx" 2>/dev/null | grep -v test | grep -v '//' | head -10)
-     if [ -n "$HARDCODED_TEXT" ]; then
-       echo "BLOCKING: Hardcoded English text — ALL visible text MUST use t() from useTranslation()"
-       echo "$HARDCODED_TEXT" | head -5
-       # FIX REQUIRED before commit
-     fi
-
-     # BLOCKING: No modals/drawers for forms — forms are full pages
-     MODAL_IMPORTS=$(grep -rPn "import.*\b(Modal|Dialog|Drawer|Popup|Sheet)\b" "$PAGE_DIR" --include="*.tsx" 2>/dev/null)
-     if [ -n "$MODAL_IMPORTS" ]; then
-       echo "BLOCKING: Form modals/dialogs detected — forms MUST be full pages with own URL"
-       echo "$MODAL_IMPORTS"
-       # FIX REQUIRED before commit
-     fi
-   fi
-
-   if [ -n "$HOOK_DIR" ]; then
-     # BLOCKING: Hooks must use i18n for error messages
-     HARDCODED_ERRORS=$(grep -rPn "(setError|throw new Error)\(['\"][A-Z]" "$HOOK_DIR" --include="*.ts" --include="*.tsx" 2>/dev/null | grep -v "t(" | head -10)
-     if [ -n "$HARDCODED_ERRORS" ]; then
-       echo "BLOCKING: Hardcoded error messages in hooks — MUST use t('{mod}:errors.xxx')"
-       echo "$HARDCODED_ERRORS" | head -5
-       # FIX REQUIRED before commit
-     fi
-   fi
-
-   # BLOCKING: i18n file structure — 4 languages with module-specific JSON files
-   if [ -n "$WEB_SRC" ]; then
-     I18N_DIR="$WEB_SRC/i18n/locales"
-     if [ -d "$I18N_DIR" ]; then
-       for LANG in fr en it de; do
-         if [ ! -d "$I18N_DIR/$LANG" ]; then
-           echo "BLOCKING: Missing i18n locale directory: $I18N_DIR/$LANG"
-           # FIX REQUIRED before commit
-         fi
-         MODULE_JSONS=$(find "$I18N_DIR/$LANG" -name "*.json" ! -name "common.json" ! -name "navigation.json" 2>/dev/null)
-         if [ -z "$MODULE_JSONS" ]; then
-           echo "BLOCKING: No module translation files in $I18N_DIR/$LANG/"
-           # FIX REQUIRED before commit
-         fi
-       done
-     else
-       echo "BLOCKING: Missing i18n/locales directory"
-       # FIX REQUIRED before commit
-     fi
-   fi
-
-   # Cross-validate route conventions (frontend vs backend)
-   APP_TSX=$(find . -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
-   API_CONTROLLERS=$(find . -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
-   if [ -n "$APP_TSX" ] && [ -n "$API_CONTROLLERS" ]; then
-     API_SEGMENTS=$(grep -ohP '\[Route\("api/([^"]+)"\)\]' $API_CONTROLLERS | sed 's/\[Route("api\///;s/")\]//' | tr '/' '\n' | sort -u)
-     CLIENT_PATHS=$(grep -ohP "path:\s*['\"]([^'\"]+)['\"]" "$APP_TSX" | sed "s/path:\s*['\"]//;s/['\"]//" | sort -u)
-     for SEG in $API_SEGMENTS; do
-       if echo "$SEG" | grep -qP '[a-z]+-[a-z]+'; then
-         NO_HYPHEN=$(echo "$SEG" | tr -d '-')
-         if echo "$CLIENT_PATHS" | grep -q "$NO_HYPHEN"; then
-           echo "BLOCKING: Frontend uses '$NO_HYPHEN' but backend uses '$SEG' (kebab-case mismatch)"
-           # FIX REQUIRED before commit
-         fi
-       fi
-     done
-   fi
-   ```
-   # BLOCKING: No custom entity hooks wrapping services (test-v4-014 root cause)
-   if [ -n "$HOOK_DIR" ]; then
-     CUSTOM_HOOKS=$(find "$HOOK_DIR" -name "use*.ts" -o -name "use*.tsx" 2>/dev/null | grep -iv "Preferences" | grep -v "node_modules")
-     if [ -n "$CUSTOM_HOOKS" ]; then
-       echo "BLOCKING: Custom entity hooks detected — pages MUST call services directly"
-       echo "$CUSTOM_HOOKS"
-       echo "Pattern: page useCallback → service.getAll() → setData(result.items)"
-       echo "FORBIDDEN: useEmployees(), useProjects() etc. wrapping services with useState/useEffect"
-       # FIX REQUIRED: delete custom hooks, move API calls into page components
-     fi
-   fi
-
-   # BLOCKING: No direct array types in services — MUST use PaginatedResult<T>
-   if [ -n "$WEB_SRC" ]; then
-     SVC_DIR=$(find "$WEB_SRC" -path "*/services" -not -path "*/node_modules/*" -type d 2>/dev/null | head -1)
-     if [ -n "$SVC_DIR" ]; then
-       DIRECT_ARRAYS=$(grep -rPn 'api\.get<[A-Z]\w+\[\]>' "$SVC_DIR" --include="*.ts" 2>/dev/null)
-       if [ -n "$DIRECT_ARRAYS" ]; then
-         echo "BLOCKING: Direct array response types — MUST use PaginatedResult<T>"
-         echo "$DIRECT_ARRAYS"
-         echo "Pattern: api.get<PaginatedResult<Employee>>(url) then .items in page"
-         # FIX REQUIRED before commit
-       fi
-     fi
-   fi
-
-   # BLOCKING: lazy() imports MUST have Suspense boundary in App.tsx
-   if [ -n "$APP_TSX" ]; then
-     HAS_LAZY=$(grep -c 'lazy(' "$APP_TSX" 2>/dev/null)
-     HAS_SUSPENSE=$(grep -c 'Suspense' "$APP_TSX" 2>/dev/null)
-     if [ "$HAS_LAZY" -gt 0 ] && [ "$HAS_SUSPENSE" -eq 0 ]; then
-       echo "BLOCKING: lazy() imports without <Suspense> boundary in App.tsx"
-       echo "Every lazy() page MUST be wrapped: <Suspense fallback={<PageLoader />}>"
-       # FIX REQUIRED before commit
-     fi
-   fi
-
-   If ANY POST-CHECK fails → fix the code → re-run ALL checks → loop until ALL pass.
-   **NEVER commit with failing POST-CHECKs.**
-
-3ter. **Dependency audit (if frontend tasks in batch):**
-   ```bash
-   cd {frontend_dir}
-   npm ls --depth=0 2>&1 | grep "MISSING" && echo "FAIL: missing deps" && exit 1
-   ```
-   If FAIL → `npm install {missing_packages}` → re-check → loop until pass
-
-4. **MCP validation:**
-   `mcp__smartstack__validate_conventions` ONCE for the whole batch
-
-5. **DB validation (if infrastructure/migration tasks in batch):**
-   ```bash
-   # Quick check: pending model changes after batch?
-   INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
-   API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
-   if [ -n "$INFRA_PROJECT" ] && [ -n "$API_PROJECT" ]; then
-     dotnet ef migrations has-pending-model-changes \
-       --project "$INFRA_PROJECT" \
-       --startup-project "$API_PROJECT"
-     if [ $? -ne 0 ]; then
-       echo "MIGRATION MISSING: Model has uncommitted changes"
-       # Create fix task for missing migration
-     fi
-
-     # If batch included migration tasks: verify migration applies on real SQL Server
-     DB_NAME="SmartStack_Ralph_Check_${iteration}"
-     CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
-     dotnet ef database update \
-       --connection "$CONN_STRING" \
-       --project "$INFRA_PROJECT" \
-       --startup-project "$API_PROJECT"
-     if [ $? -ne 0 ]; then
-       echo "MIGRATION BROKEN: Cannot apply migrations on SQL Server"
-       # Fix migration → rebuild → DO NOT commit until this passes
-     fi
-
-     # Cleanup temp database
-     sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$DB_NAME]; END" 2>/dev/null
-   fi
-   ```
-   If FAIL → migration is broken → fix → rebuild → DO NOT commit
-
-5bis. **Navigation section route CRUD suffix check (BLOCKING — if seed data tasks in batch):**
-   ```bash
-   # Detect /list or /detail/:id in navigation section routes
-   SEED_NAV_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*NavigationSeedData.cs" 2>/dev/null)
-   if [ -n "$SEED_NAV_FILES" ]; then
-     CRUD_ROUTES=$(grep -rn 'Route.*=.*\/list\b\|Route.*=.*\/detail' $SEED_NAV_FILES 2>/dev/null | grep -v '//.*Route')
-     if [ -n "$CRUD_ROUTES" ]; then
-       echo "BLOCKING: Navigation section routes contain /list or /detail/:id suffixes"
-       echo "Convention: list → module route (no suffix), detail → module route + /:id"
-       echo "$CRUD_ROUTES"
-       # FIX REQUIRED before commit
-     fi
-   fi
-   ```
-
-5ter. **Core Seed Data Integrity (BLOCKING — if seed data tasks in batch):**
-   ```bash
-   # Verify NavigationApplicationSeedData.cs exists
-   APP_SEED=$(find . -path "*/Seeding/Data/NavigationApplicationSeedData.cs" 2>/dev/null | head -1)
-   if [ -z "$APP_SEED" ]; then
-     echo "❌ BLOCKING: NavigationApplicationSeedData.cs NOT FOUND"
-     echo "Without this: nav_Applications empty → menu invisible → modules inaccessible"
-     echo "Fix: Generate from core-seed-data.md section 1b"
-     # Create fix task
-   fi
-
-   # Verify no hardcoded placeholders in provider
-   PROVIDER=$(find . -path "*/Seeding/*SeedDataProvider.cs" 2>/dev/null | head -1)
-   if [ -n "$PROVIDER" ]; then
-     if grep -qE '\{appLabel_|\{appDesc_|\{appIcon\}|\{ApplicationGuid\}' "$PROVIDER" 2>/dev/null; then
-       echo "❌ BLOCKING: SeedDataProvider has unresolved placeholders"
-       echo "Fix: Use NavigationApplicationSeedData.GetApplicationEntry()"
-     fi
-   fi
-
-   # Verify ApplicationRolesSeedData references real GUID
-   ROLES_SEED=$(find . -path "*/Seeding/Data/ApplicationRolesSeedData.cs" 2>/dev/null | head -1)
-   if [ -n "$ROLES_SEED" ]; then
-     if grep -q '{ApplicationGuid}' "$ROLES_SEED" 2>/dev/null; then
-       echo "❌ BLOCKING: ApplicationRolesSeedData still has {ApplicationGuid} placeholder"
-       echo "Fix: Replace with NavigationApplicationSeedData.ApplicationId"
-     fi
-   fi
-
-   # Quick startup test to verify seed data runs without exceptions
-   API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
-   if [ -n "$API_PROJECT" ] && [ -n "$APP_SEED" ]; then
-     echo "Running seed data startup test..."
-     dotnet run --project "$API_PROJECT" --urls "http://localhost:0" -- --environment Development > /tmp/ralph-seed-check.log 2>&1 &
-     SEED_PID=$!
-     sleep 10
-     if ! kill -0 $SEED_PID 2>/dev/null; then
-       SEED_LOG=$(cat /tmp/ralph-seed-check.log 2>/dev/null | tail -20)
-       echo "❌ BLOCKING: Application crashed during startup — seed data likely failed"
-       echo "Last 20 lines: $SEED_LOG"
-       # Do NOT continue to frontend/test — fix seed data first
-     else
-       echo "✓ Seed data startup test passed"
-       kill $SEED_PID 2>/dev/null
-       wait $SEED_PID 2>/dev/null
-     fi
-     rm -f /tmp/ralph-seed-check.log
-   fi
-   ```
-   If FAIL → fix seed data → rebuild → DO NOT continue to frontend/test tasks
-
-**Error resolution cycle:**
-1. Read the FULL error output (not just first line)
-2. Identify root cause: file path + line number
-3. Fix the issue in source code
-4. Rebuild/retest
-5. If still failing → repeat from step 1
-6. **NEVER** commit with failing build or tests
+## B. Delegate Batch to /apex
 
----
+> **Ralph NEVER generates code.** All code generation, MCP calls, POST-CHECKs,
+> and build verification are handled by apex.
+
+### B1. Mark Batch In-Progress
+
+```javascript
+for (const task of batch) {
+  task.status = 'in_progress';
+  task.started_at = new Date().toISOString();
+}
+writeJSON('.ralph/prd.json', prd);
+```
+
+### B2. Invoke /apex
+
+**INVOKE `/apex -d .ralph/prd.json`**
 
-## C. Commit Batch
+Apex handles everything for the current module:
+- Reads PRD, extracts context (context_code, app_name, module_code, entities, sections)
+- Executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
+- Runs full POST-CHECKs (50 checks from `references/post-checks.md`)
+- Commits per layer (atomic commits)
+- Validates with MCP (`validate_conventions`)
+- Updates task statuses in the PRD file directly
 
-### C1. Update PRD Status (MANDATORY — BEFORE git commit)
+> **FLAGS:** `-d` implies `-a` (auto, no user confirmation) and `-e` (economy, no nested teams).
 
-> **CRITICAL:** PRD status MUST be updated BEFORE committing.
-> In test-v4-005, the compact loop executed 44 tasks but NEVER updated prd.json status.
-> This broke ALL downstream guardrails (module completeness check never triggered).
+### B3. Verify Post-Apex Results
 
 ```javascript
-const now = new Date().toISOString();
-const COMMIT_HASH_PENDING = 'pending-commit'; // Updated after git commit
+// Re-read PRD after apex execution
+const updatedPrd = readJSON('.ralph/prd.json');
+const batchIds = batch.map(t => t.id);
 
-for (const task of batch) {
-  if (task.status !== 'failed') task.status = 'completed';
-  task.completed_at = now;
-  task.iteration = prd.config.current_iteration;
-  task.commit_hash = COMMIT_HASH_PENDING;
+const completed = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed').length;
+const failed = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'failed').length;
+const pending = updatedPrd.tasks.filter(t => batchIds.includes(t.id) && t.status === 'pending').length;
+
+if (failed > 0) {
+  console.log(`WARNING: ${failed} tasks failed during apex execution`);
+  // Failed tasks will be retried in next loop iteration if retries remain
 }
-prd.config.current_iteration++;
-prd.updated_at = now;
-writeJSON('.ralph/prd.json', prd);
+
+if (pending > 0) {
+  console.log(`INFO: ${pending} tasks still pending — apex may not have reached them`);
+}
+
+console.log(`Apex completed: ${completed}/${batchIds.length} tasks`);
 ```
 
-### C2. Update Progress File (MANDATORY)
+---
+
+## C. Commit PRD State
+
+### C1. Update Progress File (MANDATORY)
 
 ```javascript
-const completed = prd.tasks.filter(t => t.status === 'completed').length;
-const total = prd.tasks.length;
-const moduleName = prd.project?.module || 'unknown';
+const prdCheck = readJSON('.ralph/prd.json');
+const totalCompleted = prdCheck.tasks.filter(t => t.status === 'completed').length;
+const total = prdCheck.tasks.length;
 
-// Append to progress.txt (NOT overwrite)
 appendFile('.ralph/progress.txt',
-  `Iteration ${prd.config.current_iteration - 1}: ${batch.map(t => t.id).join('/')} COMPLETED — ` +
-  `${batch[0].category} (${batch.length} tasks). ${completed}/${total} done.\n` +
-  `  Files: ${batch.reduce((acc, t) => acc + (t.files_changed?.created?.length || 0), 0)} created\n`
+  `Iteration ${prdCheck.config.current_iteration}: Delegated to /apex — ` +
+  `${completed}/${batchIds.length} batch tasks completed. ${totalCompleted}/${total} overall.\n`
 );
 ```
 
-### C3. Git Commit
+### C2. Increment Iteration
+
+```javascript
+prdCheck.config.current_iteration++;
+prdCheck.updated_at = new Date().toISOString();
+writeJSON('.ralph/prd.json', prdCheck);
+```
+
+### C3. Git Commit (PRD state only — apex already committed code)
 
 ```bash
-# Stage all changed files from batch
-git add {all_files_from_batch}
 git add .ralph/prd.json .ralph/progress.txt
 [ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
 
 git commit -m "$(cat <<'EOF'
-feat({scope}): [{category}] {batch.length} tasks — {short summary}
+chore(ralph): update PRD state — iteration {iteration}
 
-Tasks: {task_ids} / {total}
-Iteration: {iteration}
-{module ? "Module: " + module : ""}
+Tasks: {completed}/{batch_size} completed via /apex
+Overall: {totalCompleted}/{total}
 
 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 EOF
 )"
-
-COMMIT_HASH=$(git rev-parse --short HEAD)
 ```
 
-### C4. Finalize PRD with Commit Hash
+### C4. PRD Sync Verification (HARD CHECK)
 
 ```javascript
-// Update commit hash now that we have the real one
-for (const task of batch) {
-  if (task.commit_hash === 'pending-commit') task.commit_hash = COMMIT_HASH;
-}
-prd.history.push({
-  iteration: prd.config.current_iteration - 1,
-  task_ids: batch.map(t => t.id),
-  action: 'batch-completed',
-  timestamp: now,
-  commit_hash: COMMIT_HASH,
-  notes: "{summary}"
-});
-writeJSON('.ralph/prd.json', prd);
-```
-
-### C5. PRD Sync Verification (HARD CHECK)
-
-> **MANDATORY:** Verify prd.json reflects reality before looping back.
+const prdVerify = readJSON('.ralph/prd.json');
+const actuallyCompleted = prdVerify.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed');
 
-```javascript
-const prdCheck = readJSON('.ralph/prd.json');
-const batchIds = batch.map(t => t.id);
-const actuallyCompleted = prdCheck.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed');
-
-if (actuallyCompleted.length !== batch.filter(t => t.status !== 'failed').length) {
-  console.error('PRD SYNC ERROR: Tasks executed but not marked completed in prd.json');
-  console.error(`Expected: ${batch.filter(t => t.status !== 'failed').length} completed, Got: ${actuallyCompleted.length}`);
-  // Force re-write
-  for (const task of batch) {
-    const prdTask = prdCheck.tasks.find(t => t.id === task.id);
-    if (prdTask && task.status === 'completed') prdTask.status = 'completed';
-    if (prdTask) prdTask.commit_hash = COMMIT_HASH;
-  }
-  writeJSON('.ralph/prd.json', prdCheck);
-  console.log('PRD SYNC REPAIRED');
+if (actuallyCompleted.length !== completed) {
+  console.error('PRD SYNC ERROR: Mismatch between apex results and prd.json');
+  // Force re-read — apex may have written after our read
+  // DO NOT overwrite — apex is the source of truth for task statuses
 }
 ```