@atlashub/smartstack-cli 4.26.0 → 4.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.26.0",
+  "version": "4.27.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/agents/ba-writer.md

@@ -18,17 +18,18 @@ Write and update granular JSON files for project-level (multi-app), application-
 - Module-level: `docs/{app}/{module}/business-analyse/v{X.Y}/index.json` + thematic files
 
 **Thematic files (v2 granular architecture):**
-- `index.json` — metadata, version, hash manifest, module registry
-- `cadrage.json` — stakeholders, problem/vision, risks, acceptance criteria
-- `entities.json` — entity definitions with attributes and relationships
-- `rules.json` — business rules with categories and conditions
-- `usecases.json` — use cases and functional requirements
-- `permissions.json` — permission matrix and role assignments
-- `screens.json` — UI wireframes and navigation
-- `validation.json` — validation rules and consistency checks
-- `handoff.json` — complexity, file catalog, BR-to-code mapping
-- `consolidation.json` — cross-module interactions and E2E flows (application-level only)
-- `review.json` — preserved review comments and change summary
+- `index.json` — metadata, version, hash manifest, module registry (ALL scopes)
+- `cadrage.json` — stakeholders, problem/vision, risks, acceptance criteria (ALL scopes)
+- `validation.json` — validation rules and consistency checks (ALL scopes)
+- `consolidation.json` — cross-module interactions and E2E flows (application/project ONLY)
+- `navigation.json` — navigation tree (application/project ONLY, created by ba-design-ui)
+- `entities.json` — entity definitions with attributes and relationships (**MODULE ONLY**)
+- `rules.json` — business rules with categories and conditions (**MODULE ONLY**)
+- `usecases.json` — use cases and functional requirements (**MODULE ONLY**)
+- `permissions.json` — permission matrix and role assignments (**MODULE ONLY**)
+- `screens.json` — UI wireframes and navigation (**MODULE ONLY**)
+- `handoff.json` — complexity, file catalog, BR-to-code mapping (**MODULE ONLY**)
+- `review.json` — preserved review comments and change summary (ALL scopes)
 
 > **Backward compatibility:** If only 1 application, the project level is NOT created. The application-level index.json remains the master.
 
@@ -62,12 +63,12 @@ Create initial index.json and empty thematic files with metadata and draft statu
    - For project scope: modules: []
    - For application scope: modules: []
    - For module scope: (no modules array)
-5. Create empty thematic files appropriate for scope:
-   - Project/application: cadrage.json, validation.json, handoff.json, consolidation.json
-     > **NOTE:** Do NOT create entities.json, rules.json, usecases.json, permissions.json, screens.json at project/application level.
-     > These thematic files contain module-specific data and are created ONLY at module level by step-03 (specify).
-     > Creating empty versions at app level causes downstream tools (derive-prd) to read empty arrays instead of module data.
-   - Module: entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, handoff.json
+5. Create empty thematic files — ONLY the files listed for the scope. Creating ANY unlisted file is a **BLOCKING ERROR**.
+   - Project: cadrage.json, validation.json, consolidation.json — **EXACTLY 3 files, NO OTHERS**
+   - Application: cadrage.json, validation.json, consolidation.json — **EXACTLY 3 files, NO OTHERS**
+   - Module: entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, handoff.json — **EXACTLY 7 files**
+
+   **FORBIDDEN at project/application level:** entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json — these exist ONLY at module level.
 6. Update `.business-analyse/config.json` with new lastFeatureId
 7. IF scope = "module" AND applicationRef provided AND moduleCode provided:
    a. Read master index.json (via applicationRef FEAT-NNN)
@@ -110,8 +111,8 @@ Create a project-level index.json for multi-application analysis. Only used when
    - fileHashes: {}
    - applications: []
    - applicationDependencyGraph: {}
-5. Create thematic files (cadrage.json, validation.json, consolidation.json)
-     > Do NOT create entities/rules/usecases/permissions/screens at project level — these exist only at module level.
+5. Create thematic files — **EXACTLY 3 files, NO OTHERS:** cadrage.json, validation.json, consolidation.json
+   **FORBIDDEN at project level:** entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json — these exist ONLY at module level.
 6. Update `.business-analyse/config.json` with new lastProjectId
 7. Deploy schemas to `docs/business-analyse/schemas/` (including project-schema.json)
 8. Return project ID (PROJ-NNN) and path
@@ -178,6 +179,10 @@ Write a complete thematic file and update its hash in index.json.
 
 **Process:**
 1. Find and read index.json (use findFeature if given ID)
+1b. **SCOPE GUARD (BLOCKING):** If index.json scope is "project" or "application", verify themeName is ALLOWED:
+    - Allowed: [cadrage, validation, consolidation, navigation, review]
+    - FORBIDDEN: [entities, rules, usecases, permissions, screens, handoff]
+    If themeName is FORBIDDEN → **REJECT with BLOCKING ERROR.** Do NOT create the file.
 2. Determine thematic filename: `{themeName}.json`
 3. Create full path: `{version_dir}/{themeName}.json`
 4. Write thematic file with pretty-print (2-space indent)
@@ -335,6 +340,20 @@ Increment the module loop counter in the master index.json.
 9. Write back index.json
 10. Return new index and whether loop is complete
 
+### cleanupAppLevelFiles
+Remove forbidden thematic files at project/application level and clean their entries from fileHashes.
+
+**Input:** featureId: FEAT-NNN
+
+**Process:**
+1. Read index.json (verify scope is "project" or "application")
+2. FORBIDDEN = [entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json]
+3. For each FORBIDDEN file: if file exists in version directory → DELETE it
+4. For each FORBIDDEN file: if referenced in fileHashes → REMOVE entry
+5. If `files` property exists in index.json: remove entries for forbidden files
+6. Update metadata.updatedAt, write index.json
+7. Return list of cleaned files
+
 ### createVersion
 Create a new version for refactoring or major changes.
 
@@ -470,43 +489,29 @@ docs/business-analyse/
   v1.0/
     index.json                          ← PROJECT metadata
     cadrage.json
-    entities.json
-    rules.json
-    usecases.json
-    permissions.json
-    screens.json
     validation.json
     consolidation.json
+    # NO entities/rules/usecases/permissions/screens/handoff — MODULE ONLY
 
 docs/{app}/business-analyse/
   v1.0/
     index.json                          ← APPLICATION metadata
     cadrage.json
-    entities.json
-    rules.json
-    usecases.json
-    permissions.json
-    screens.json
     validation.json
     consolidation.json
-  v1.1/
-    index.json
-    cadrage.json
-    entities.json
-    ...
+    navigation.json                     ← (created by ba-design-ui)
+    # NO entities/rules/usecases/permissions/screens/handoff — MODULE ONLY
 
 docs/{app}/{module}/business-analyse/
   v1.0/
     index.json                          ← MODULE metadata
-    discovery.json
-    analysis.json
-    specification.json
+    entities.json
+    rules.json
+    usecases.json
+    permissions.json
+    screens.json
     validation.json
     handoff.json
-  v1.1/
-    index.json
-    discovery.json
-    ...
 ```
 
 Versions are stored as separate directories. Each directory contains index.json + thematic files.
@@ -726,11 +731,6 @@ if (estimatedNewSize > 500 * 1024) {  // 500KB
   "fileHashes": {
     "index.json": "pqr678...",
     "cadrage.json": "stu901...",
-    "entities.json": "vwx234...",
-    "rules.json": "yza567...",
-    "usecases.json": "bcd890...",
-    "permissions.json": "efg123...",
-    "screens.json": "hij456...",
     "validation.json": "klm789...",
     "consolidation.json": "nop012..."
   },

package/templates/project/appsettings.json.template

@@ -7,10 +7,8 @@
     "FailOnMigrationError": true,
     "EnableDevSeeding": false,
     "CorsOrigins": [
-      "http://localhost:5173",
-      "http://localhost:5174",
-      "http://localhost:5175",
-      "http://localhost:6173"
+      "http://localhost:3000",
+      "http://localhost:5173"
     ]
   },
   "Jwt": {
@@ -34,7 +32,7 @@
       "SecretExpiresAt": "",
       "CallbackPath": "/api/auth/google/callback"
     },
-    "FrontendUrl": "http://localhost:6173"
+    "FrontendUrl": "http://localhost:3000"
   },
   "Session": {
     "IdleTimeoutMinutes": 20,
@@ -125,7 +123,7 @@
     "Provider": "Development",
     "FromEmail": "noreply@{{ProjectDomain}}",
     "FromName": "{{ProjectName}}",
-    "BaseUrl": "http://localhost:5173",
+    "BaseUrl": "http://localhost:3000",
     "TokenExpiration": {
       "EmailConfirmation": "24:00:00",
       "PasswordReset": "01:00:00"

package/templates/skills/apex/SKILL.md

@@ -149,6 +149,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - **Parallel Agent tool** - Parallel execution for scan (step-01) and within Layer 2/3 (step-03) for multi-entity, unless economy_mode
 - **Tests inline** - Backend tests run after Layer 2, frontend tests run after Layer 3 (max 3 fix iterations each). Step-07 = final sweep (security + coverage).
 - **Exception: seed data** — The templates in core-seed-data.md and person-extension-pattern.md are generated directly because no MCP tool covers seed data creation. This is a documented exception to the "orchestrate, never generate" rule.
+- **Frontend pages: ALWAYS via Skill("ui-components")** — economy_mode affects parallelization only, NOT whether /ui-components is called. NEVER generate .tsx pages directly, even in delegate or economy mode.
 - **Save outputs** if `{save_mode}` = true
 - **Commits per layer** - Atomic commits after each execution layer
 - **Delegate mode** (`-d`): Read PRD context, skip challenge questions, auto+economy mode implied. Used when `/ralph-loop` delegates code generation to `/apex`.

package/templates/skills/apex/references/challenge-questions.md

@@ -82,8 +82,25 @@ questions:
     multiSelect: true
 ```
 
+**Reserved codes (NOT valid sections):**
+- `detail` — auto-generated as `/:id` route when "list" section exists
+- `create` — auto-generated as `/create` route when "list" section exists
+- `edit` — auto-generated as `/:id/edit` route when "list" section exists
+
+These are **view modes**, not sections. A "list" section automatically generates 4 pages: ListPage (index), DetailPage (/:id), CreatePage (/create), EditPage (/:id/edit).
+
 **Validation:**
 ```
+RESERVED_SECTION_CODES = ["detail", "create", "edit"]
+
+IF any section.code IN RESERVED_SECTION_CODES:
+  DISPLAY: "'{section.code}' is a view mode, not a section.
+    The 'list' section automatically includes detail (/:id), create (/create),
+    and edit (/:id/edit) pages. Remove '{section.code}' from your sections."
+  → Remove the offending section(s) from the list
+  → Re-ask the sections question if {sections}.length == 0
+  → DO NOT proceed
+
 IF {sections}.length == 0:
   DISPLAY: "Every module must have at least one section. Please select or define at least one."
   → Re-ask the sections question

package/templates/skills/apex/references/post-checks.md

@@ -117,6 +117,21 @@ if [ -n "$APP_TSX" ]; then
 fi
 ```
 
+### POST-CHECK S7: Controllers must NOT use Guid.Empty for tenantId/userId (OWASP A01)
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  BAD_GUID=$(grep -Pn 'Guid\.Empty' $CTRL_FILES 2>/dev/null)
+  if [ -n "$BAD_GUID" ]; then
+    echo "BLOCKING (OWASP A01): Controller uses Guid.Empty — tenant isolation bypassed"
+    echo "$BAD_GUID"
+    echo "Fix: Use _currentTenant.TenantId from ICurrentTenantService"
+    exit 1
+  fi
+fi
+```
+
 ---
 
 ## Backend — Entity, Service & Controller Checks
@@ -154,6 +169,39 @@ fi
 
 ## Frontend — CSS, Forms, Components, I18n
 
+### POST-CHECK C3a: Frontend must not be empty if Layer 3 was planned (BLOCKING)
+
+```bash
+# If foundation_mode is false AND App.tsx exists, verify frontend was generated
+APP_TSX=$(find web/ src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Check if applicationRoutes is an empty object
+  EMPTY_ROUTES=$(grep -P "applicationRoutes.*=\s*\{[\s/]*\}" "$APP_TSX" 2>/dev/null)
+  if [ -n "$EMPTY_ROUTES" ]; then
+    echo "BLOCKING: applicationRoutes in App.tsx is empty — Layer 3 frontend was NOT executed"
+    echo "Expected: at least one application key with route definitions"
+    echo "Fix: Run Layer 3 (scaffold_routes + scaffold_extension + route wiring)"
+    exit 1
+  fi
+
+  # Check pages/ directory is not empty
+  PAGE_COUNT=$(find web/ src/ -path "*/pages/*" -name "*.tsx" -not -path "*/node_modules/*" 2>/dev/null | wc -l)
+  if [ "$PAGE_COUNT" -eq 0 ]; then
+    echo "BLOCKING: No page components found in pages/ directory"
+    echo "Fix: Generate pages via scaffold_extension or /ui-components"
+    exit 1
+  fi
+
+  # Check navRoutes.generated.ts exists
+  NAV_ROUTES=$(find web/ src/ -name "navRoutes.generated.ts" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+  if [ -z "$NAV_ROUTES" ]; then
+    echo "BLOCKING: navRoutes.generated.ts not found — scaffold_routes was never called"
+    echo "Fix: Run scaffold_routes(source: 'controllers', outputFormat: 'applicationRoutes')"
+    exit 1
+  fi
+fi
+```
+
 ### POST-CHECK C3: Translation files must exist for all 4 languages (if frontend)
 
 ```bash

package/templates/skills/apex/steps/step-03-execute.md

@@ -290,6 +290,24 @@ When launching agents for multi-entity layers:
 - Agent principal updates activeForm after each entity completion:
   `TaskUpdate(taskId: layer2_task_id, activeForm: "Building {EntityName} backend (2/5 entities)")`
 
+### Controller NavRoute Attribute (MANDATORY)
+
+After controller generation, verify `[NavRoute]` attribute is present on every controller:
+- Expected: `[NavRoute("{app_name}.{module_code}.{section_code}")]` on the controller class
+- If missing: Add it manually above `[Authorize]`
+- When calling `scaffold_extension(type: "controller")`, always pass `navRoute` in options
+- This is REQUIRED for `scaffold_routes` to auto-detect routes in Layer 3
+
+```bash
+# Quick check: all controllers must have [NavRoute] (not just [Route])
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+for f in $CTRL_FILES; do
+  if ! grep -q "\[NavRoute" "$f" && grep -q "\[Route" "$f"; then
+    echo "WARNING: $f has [Route] but no [NavRoute] — add [NavRoute] for route auto-detection"
+  fi
+done
+```
+
 ### Post-Layer 2 Build Gate
 
 ```bash
@@ -377,7 +395,18 @@ For each module:
   → All business applications use `<AppLayout />` as layout wrapper
   → See `references/frontend-route-wiring-app-tsx.md` for full Pattern A/B detection and examples
   → Verify: `mcp__smartstack__validate_frontend_routes (scope: 'routes')`
-- Pages: use /ui-components skill — follow smartstack-frontend.md patterns:
+- Pages per section: When a section exists (e.g., "list"), generate ALL 4 page types:
+  → {Section}ListPage.tsx (index route)
+  → {Section}DetailPage.tsx (/:id route) — click on list item navigates here
+  → Create{Section}Page.tsx (/create route)
+  → Edit{Section}Page.tsx (/:id/edit route)
+  "detail" is NEVER a separate section — it's the /:id route of the list section.
+- Pages: **MANDATORY — INVOKE Skill("ui-components")** for ALL page generation.
+  ⚠ BLOCKING REQUIREMENT: You MUST call Skill("ui-components") for EVERY page (.tsx).
+  NEVER generate .tsx page code directly. NEVER write page content in Agent prompts.
+  NEVER use Write tool to create pages without first calling Skill("ui-components").
+  The skill loads the full style guide + patterns (entity-card, data-table, dashboard-chart, grid-layout).
+  Follow smartstack-frontend.md patterns:
   → React.lazy() for all page imports (named export wrapping)
   → `<Suspense fallback={<PageLoader />}>` around all lazy components
   → Page structure: hooks → useEffect(load) → loading → error → content
@@ -466,7 +495,21 @@ IF NOT economy_mode AND entities.length > 1:
   # All agents launched in parallel
 
 ELSE:
-  # Agent principal handles all entities sequentially
+  # Economy mode: Agent principal handles all entities SEQUENTIALLY.
+  # MANDATORY: You MUST still call Skill("ui-components") for page generation.
+  # economy_mode only disables parallel agents — it does NOT skip /ui-components.
+  For each entity (sequentially):
+    1. MCP scaffold_api_client
+    2. MCP scaffold_routes (outputFormat: 'applicationRoutes')
+    3. Wire routes to App.tsx (Pattern A/B — see references/frontend-route-wiring-app-tsx.md)
+    4. **INVOKE Skill("ui-components")** — pass entity context:
+       - Entity: {EntityName}, Module: {ModuleName}, App: {AppName}
+       - Page types: List, Detail, Create, Edit (+ Dashboard if applicable)
+       - "CSS: Use CSS variables ONLY — bg-[var(--bg-card)], text-[var(--text-primary)]"
+       - "Forms: Create/Edit are FULL PAGES with own routes (/create, /:id/edit)"
+       - "I18n: ALL text uses t('namespace:key', 'Fallback')"
+    5. I18n: 4 JSON files (fr, en, it, de) + register namespace in i18n config
+    6. Form tests: co-located .test.tsx for Create and Edit pages
 ```
 
 ### Parallel Agents + TaskCreate Integration
@@ -495,6 +538,24 @@ When delegating to `/ui-components` skill, include explicit instructions:
 - "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`)."
 - "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."
 
+### HARD RULE — /ui-components is NON-NEGOTIABLE
+
+> **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT
+> a prior Skill("ui-components") call in this execution, the frontend layer is INVALID.
+>
+> **You MUST NOT:**
+> - Generate .tsx page code in Agent prompts and dispatch to Snipper agents
+> - Write page content directly via the Write tool
+> - Copy-paste page templates from your knowledge
+>
+> **You MUST:**
+> - Call Skill("ui-components") which loads the style guide, responsive guidelines,
+>   accessibility rules, and pattern files (entity-card, data-table, dashboard-chart, grid-layout, kanban)
+> - Let /ui-components generate all pages with correct conventions
+>
+> **Why this matters:** Without the skill, pages miss CSS variables, DataTable/EntityCard,
+> memo()/useCallback, responsive mobile-first design, and accessibility patterns.
+
 ### Frontend Tests Inline
 
 > **Tests are scaffolded and run WITHIN Layer 3, not deferred to step-07.**

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -357,13 +357,12 @@ IF workflow_mode = "project":
   })
 
   Output path: docs/business-analyse/v{version}/index.json
-  Thematic files (empty, initialized): docs/business-analyse/v{version}/*.json
+  Thematic files — EXACTLY these 3, NO OTHERS:
     - cadrage.json
     - validation.json
     - consolidation.json
-    // NOTE: entities, rules, usecases, permissions, screens are MODULE-LEVEL only.
-    // They are created by step-03 (specify) in each module directory.
-    // Do NOT create them at project/app level — empty files mislead downstream tools.
+  FORBIDDEN: entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json
+  Creating any FORBIDDEN file at project level is a BLOCKING ERROR.
 
   Store:
     project_id: string  // PROJ-NNN
@@ -394,18 +393,29 @@ ELSE:
   })
 
   Output path: docs/{app}/business-analyse/v{version}/index.json
-  Thematic files (empty, initialized): docs/{app}/business-analyse/v{version}/*.json
+  Thematic files — EXACTLY these 3, NO OTHERS:
     - cadrage.json
     - validation.json
-    - handoff.json
-    // NOTE: entities, rules, usecases, permissions, screens are MODULE-LEVEL only.
-    // They are created by step-03 (specify) in each module directory.
-    // Do NOT create them at app level — empty files mislead derive-prd and ralph-loop.
+    - consolidation.json
+  FORBIDDEN: entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json
+  Creating any FORBIDDEN file at application level is a BLOCKING ERROR.
 ```
 
 > **Note:** In project mode, per-application index.json files are created later in step-01-cadrage.
 > In single-app mode, step-02 (structure) determines if it's single or multi-module.
 
+### POST-CREATE VERIFICATION (MANDATORY)
+
+After creating thematic files, verify no forbidden files were created:
+
+```
+List all *.json files in {docs_dir}/
+Expected (project/application): [index.json, cadrage.json, validation.json, consolidation.json]
+If any file NOT in expected list is found → DELETE it immediately + log WARNING
+```
+
+This guard catches any accidental creation of module-only files at the wrong scope.
+
 ## Step 10: Update Config
 
 Update `.business-analyse/config.json` with new feature information.

package/templates/skills/business-analyse/steps/step-04-consolidate.md

@@ -423,20 +423,8 @@ ba-writer.enrichSection({
 // Update status
 ba-writer.updateStatus({feature_id}, "consolidated");
 
-// FIX H3: Clean up app-level index.json files entries
-// Only keep entries for files that actually have content at app level.
-// Module-level data lives in module directories — do NOT declare empty app-level files.
-ba-writer.enrichSection({
-  featureId: {feature_id},
-  section: "files",
-  data: {
-    // Keep only files that exist and have content at app level
-    cadrage: { path: "cadrage.json", hash: "framed", lastModified: now() },
-    validation: { path: "validation.json", hash: "consolidated", lastModified: now() }
-    // REMOVED: entities, rules, usecases, permissions, screens, handoff
-    // These exist only at module level (flat-file architecture)
-  }
-});
+// Clean up any forbidden files that may have been created at app level
+ba-writer.cleanupAppLevelFiles({ featureId: {feature_id} });
 
 // Save workflow state for resume support
 ba-writer.enrichSection({

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

@@ -306,7 +306,38 @@ appendFile('.ralph/progress.txt',
 );
 ```
 
-### C2. Increment Iteration
+### C2. Skipped Task Audit
+
+After apex returns, check for newly skipped tasks:
+
+```javascript
+const newlySkipped = prdCheck.tasks.filter(t =>
+  batchIds.includes(t.id) && t.status === 'skipped'
+);
+if (newlySkipped.length > 0) {
+  console.warn(`⚠ ${newlySkipped.length} tasks were SKIPPED by apex:`);
+  newlySkipped.forEach(t => console.warn(`  - ${t.id}: ${t.description}`));
+
+  // If ALL tasks in a category were skipped → BLOCKING, reset for retry
+  const skippedCategories = [...new Set(newlySkipped.map(t => t.category))];
+  for (const cat of skippedCategories) {
+    const allInCat = prdCheck.tasks.filter(t => t.category === cat);
+    const allSkipped = allInCat.every(t => t.status === 'skipped');
+    if (allSkipped) {
+      console.error(`BLOCKING: ALL tasks in category "${cat}" were skipped — investigate root cause`);
+      // Reset to pending for retry
+      allInCat.forEach(t => {
+        t.status = 'pending';
+        t._retryCount = (t._retryCount || 0) + 1;
+        t.error = `All tasks in category "${cat}" skipped — auto-retry`;
+      });
+    }
+  }
+  writeJSON(currentPrdPath, prdCheck);
+}
+```
+
+### C3. Increment Iteration
 
 ```javascript
 prdCheck.config.current_iteration++;
@@ -314,7 +345,7 @@ prdCheck.updated_at = new Date().toISOString();
 writeJSON(currentPrdPath, prdCheck);
 ```
 
-### C3. Git Commit (PRD state only — apex already committed code)
+### C4. Git Commit (PRD state only — apex already committed code)
 
 ```bash
 git add {currentPrdPath} .ralph/progress.txt
@@ -331,7 +362,7 @@ EOF
 )"
 ```
 
-### C4. PRD Sync Verification (HARD CHECK)
+### C5. PRD Sync Verification (HARD CHECK)
 
 > **Note:** `prdCheck` (read in C1) is the authoritative post-apex snapshot.
 > `completed` (from B3) was computed on a DIFFERENT read — do NOT mix the two.