@atlashub/smartstack-cli 4.26.0 → 4.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.26.0",
+  "version": "4.28.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/core-seed-data.md

@@ -274,7 +274,7 @@ public static class {ModulePascal}NavigationSeedData
             Description = "{desc_en}",
             Icon = "{icon}",              // Lucide React icon name
             IconType = IconType.Lucide,
-            Route = ToKebabCase($"/{appCode}/{moduleCode}"),
+            Route = ToKebabCase($"/{appCode}/{moduleCode}"),  // Absolute path for sidebar navigation (App.tsx routes are RELATIVE to module root)
             DisplayOrder = {displayOrder},
             IsActive = true
         };
@@ -731,13 +731,33 @@ public class PermissionSeedEntry
 }
 ```
 
-### Step C2: Section-Level Permissions (CONDITIONAL: only if `navSections[]` defined)
+### Step C2: Section-Level Permissions (CONDITIONAL — filtered by `permissionMode`)
 
 > When `seedDataCore.navigationSections` exists and is non-empty in feature.json,
 > add section-level permission GUIDs and entries to `PermissionsSeedData.cs`.
+>
+> **Permission generation is conditional on each section's `permissionMode`:**
+>
+> | permissionMode | Permissions generated |
+> |---|---|
+> | `crud` | wildcard + read + create + update + delete |
+> | `custom:action1,action2` | wildcard + read + custom actions |
+> | `read-only` | read only (NO CRUD wildcard) |
+> | `inherit` | NO section-level permissions (inherits from module) |
+>
+> **Default inference (when `permissionMode` is absent):**
+> - `code === "detail"` → `inherit`
+> - `code === "dashboard"` → `read-only`
+> - otherwise → `crud`
+>
+> **IMPORTANT:** Sections with `permissionMode: inherit` MUST be skipped entirely.
+> Do NOT generate any permission GUIDs, entries, or constants for them.
 
 ```csharp
 // --- Add to {ModulePascal}PermissionsSeedData class AFTER module-level permissions ---
+// FILTER: Only generate for sections where permissionMode is NOT "inherit"
+// For "read-only" sections: generate ONLY ReadPermId (no Wildcard, Create, Update, Delete)
+// For "custom:x,y" sections: generate Wildcard + Read + custom action GUIDs
 
 // Section-level permissions (for each section in navSections[])
 public static readonly Guid {SectionPascal}WildcardPermId = Guid.NewGuid();
@@ -1155,8 +1175,10 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
     {
         // Check idempotence — verify by Code (roles may already exist from SmartStack core)
+        // Scope by ApplicationId — without this, roles from OTHER apps cause false positives
         var existingRoleCodes = await context.Roles
-            .Where(r => r.Code == "admin" || r.Code == "manager" || r.Code == "contributor" || r.Code == "viewer")
+            .Where(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId
+                && (r.Code == "admin" || r.Code == "manager" || r.Code == "contributor" || r.Code == "viewer"))
             .Select(r => r.Code)
             .ToListAsync(ct);
 
@@ -1213,8 +1235,9 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         // Application-scoped roles (admin, manager, contributor, viewer) are created by
         // SeedRolesAsync() above. System roles use their own IDs that do not match
         // DeterministicGuid("role:admin").
+        // Load THIS application's roles + system roles only
         var roles = await context.Roles
-            .Where(r => r.ApplicationId != null || r.IsSystem)
+            .Where(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId || r.IsSystem)
             .ToListAsync(ct);
 
         // Resolve permissions

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

@@ -117,10 +117,136 @@ 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
+```
+
+### POST-CHECK S8: Write endpoints must NOT use Read permissions (BLOCKING)
+
+> **Source:** audit ba-002 finding C1 — Cancel endpoint (POST) used `Permissions.Absences.Read`,
+> allowing any reader to cancel absences. Write operations MUST use write permissions.
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    # Extract blocks: find each method with Http verb + RequirePermission
+    # Check POST/PUT/DELETE/PATCH endpoints that use *.Read permission
+    WRITE_WITH_READ=$(grep -Pn '\[(HttpPost|HttpPut|HttpDelete|HttpPatch)' "$f" | while read -r line; do
+      LINE_NUM=$(echo "$line" | cut -d: -f1)
+      # Look within 5 lines for RequirePermission with .Read
+      sed -n "$((LINE_NUM-2)),$((LINE_NUM+5))p" "$f" | grep -P 'RequirePermission.*\.Read\b' | head -1
+    done)
+    if [ -n "$WRITE_WITH_READ" ]; then
+      echo "BLOCKING: Write endpoint uses Read permission in $f"
+      echo "$WRITE_WITH_READ"
+      echo "Fix: POST/PUT/DELETE/PATCH endpoints must use Create/Update/Delete permissions, never Read"
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK S9: FK relationships must enforce tenant isolation (BLOCKING)
+
+> **Source:** audit ba-002 finding C5 — Department.ManagerId FK referenced Employee without
+> tenant constraint, allowing cross-tenant data leakage through navigation properties.
+
+```bash
+CONFIG_FILES=$(find src/ -path "*/Configurations/*" -name "*Configuration.cs" 2>/dev/null)
+if [ -n "$CONFIG_FILES" ]; then
+  for f in $CONFIG_FILES; do
+    # Check if entity implements ITenantEntity
+    ENTITY_NAME=$(grep -oP 'IEntityTypeConfiguration<(\w+)>' "$f" | grep -oP '<\K[^>]+')
+    if [ -z "$ENTITY_NAME" ]; then continue; fi
+
+    # Check if the entity is tenant-scoped (has TenantId in its properties or base class)
+    ENTITY_FILE=$(find src/ -path "*/Domain/*" -name "${ENTITY_NAME}.cs" 2>/dev/null | head -1)
+    if [ -z "$ENTITY_FILE" ]; then continue; fi
+
+    IS_TENANT=$(grep -cE 'ITenantEntity|BaseEntity|TenantId' "$ENTITY_FILE")
+    if [ "$IS_TENANT" -eq 0 ]; then continue; fi
+
+    # For tenant entities, check FK relationships point to other tenant entities
+    # Warning: FK to non-tenant entity from tenant entity = potential cross-tenant leak
+    FK_TARGETS=$(grep -oP 'HasOne<(\w+)>|HasOne\(e\s*=>\s*e\.(\w+)\)' "$f" | grep -oP '\w+(?=>|\))' | sort -u)
+    for TARGET in $FK_TARGETS; do
+      TARGET_FILE=$(find src/ -path "*/Domain/*" -name "${TARGET}.cs" 2>/dev/null | head -1)
+      if [ -n "$TARGET_FILE" ]; then
+        TARGET_IS_TENANT=$(grep -cE 'ITenantEntity|BaseEntity|TenantId' "$TARGET_FILE")
+        if [ "$TARGET_IS_TENANT" -gt 0 ]; then
+          # Both are tenant entities — verify the FK has a composite or filtered relationship
+          # At minimum, warn that cross-tenant reference is possible without query filter
+          HAS_QUERY_FILTER=$(grep -c 'HasQueryFilter' "$f")
+          if [ "$HAS_QUERY_FILTER" -eq 0 ]; then
+            echo "WARNING: $f — FK from tenant entity $ENTITY_NAME to tenant entity $TARGET without HasQueryFilter"
+            echo "Cross-tenant data leakage possible if FK is assigned without tenant validation"
+            echo "Fix: Add tenant validation in service layer before assigning FK, or use composite FK (TenantId + EntityId)"
+          fi
+        fi
+      fi
+    done
+  done
+fi
+```
+
 ---
 
 ## Backend — Entity, Service & Controller Checks
 
+### POST-CHECK V1: Controllers with POST/PUT must have corresponding Validators (BLOCKING)
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    # Check if controller has POST or PUT endpoints
+    HAS_WRITE=$(grep -cE "\[Http(Post|Put)\]" "$f")
+    if [ "$HAS_WRITE" -gt 0 ]; then
+      # Extract DTO names from POST/PUT method parameters
+      DTOS=$(grep -oP '(?:Create|Update)\w+Dto' "$f" | sort -u)
+      for DTO in $DTOS; do
+        VALIDATOR_NAME=$(echo "$DTO" | sed 's/Dto$/Validator/')
+        VALIDATOR_FILE=$(find src/ -path "*/Validators/*" -name "${VALIDATOR_NAME}.cs" 2>/dev/null)
+        if [ -z "$VALIDATOR_FILE" ]; then
+          echo "BLOCKING: Controller $f uses $DTO but no ${VALIDATOR_NAME}.cs found"
+          echo "Fix: Create Validator with FluentValidation rules from business rules"
+          exit 1
+        fi
+      done
+    fi
+  done
+fi
+```
+
+### POST-CHECK V2: Validators must be registered in DI (WARNING)
+
+```bash
+VALIDATOR_FILES=$(find src/ -path "*/Validators/*" -name "*Validator.cs" 2>/dev/null)
+if [ -n "$VALIDATOR_FILES" ]; then
+  DI_FILE=$(find src/ -name "DependencyInjection.cs" -o -name "ServiceCollectionExtensions.cs" 2>/dev/null | head -1)
+  if [ -n "$DI_FILE" ]; then
+    for f in $VALIDATOR_FILES; do
+      VALIDATOR_NAME=$(basename "$f" .cs)
+      if ! grep -q "$VALIDATOR_NAME" "$DI_FILE"; then
+        echo "WARNING: Validator $VALIDATOR_NAME not registered in DI: $DI_FILE"
+      fi
+    done
+  fi
+fi
+```
+
 ### POST-CHECK C1: Navigation routes must be full paths starting with /
 
 ```bash
@@ -154,6 +280,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
@@ -1611,6 +1770,120 @@ if [ -n "$ENTITY_FILES" ]; then
 fi
 ```
 
+### POST-CHECK C49: Route Ordering in App.tsx — static before dynamic (BLOCKING)
+
+> **Source:** Dashboard 404 bug — `:id` route declared before `dashboard` route in applicationRoutes,
+> React Router matched `dashboard` as an `id` parameter → page not found.
+
+```bash
+APP_TSX=$(find web/ src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Extract all route paths from applicationRoutes in order
+  ROUTE_PATHS=$(grep -oP "path:\s*'([^']+)'" "$APP_TSX" | sed "s/path: '//;s/'//")
+  FAIL=false
+  PREV_PREFIX=""
+  PREV_IS_DYNAMIC=false
+
+  while IFS= read -r ROUTE; do
+    [ -z "$ROUTE" ] && continue
+    # Extract prefix (everything before last segment)
+    PREFIX=$(echo "$ROUTE" | sed 's|/[^/]*$||')
+    LAST_SEGMENT=$(echo "$ROUTE" | grep -oP '[^/]+$')
+    IS_DYNAMIC=$(echo "$LAST_SEGMENT" | grep -c '^:')
+
+    # Check: if previous route was dynamic and current route is static with same prefix
+    if [ "$PREV_IS_DYNAMIC" = true ] && [ "$IS_DYNAMIC" -eq 0 ] && [ "$PREFIX" = "$PREV_PREFIX" ]; then
+      echo "BLOCKING: Static route '$ROUTE' is AFTER a dynamic route with prefix '$PREFIX' in App.tsx"
+      echo "  React Router will match the dynamic route first → '$ROUTE' is unreachable (404)"
+      echo "  Fix: Move static routes BEFORE dynamic routes within the same prefix group"
+      FAIL=true
+    fi
+
+    PREV_PREFIX="$PREFIX"
+    if [ "$IS_DYNAMIC" -gt 0 ]; then
+      PREV_IS_DYNAMIC=true
+    else
+      PREV_IS_DYNAMIC=false
+    fi
+  done <<< "$ROUTE_PATHS"
+
+  # Also check: Navigate (redirect) routes must be at the end
+  REDIRECT_LINE=$(grep -n "Navigate" "$APP_TSX" | head -1 | cut -d: -f1)
+  if [ -n "$REDIRECT_LINE" ]; then
+    ROUTES_AFTER=$(tail -n +"$((REDIRECT_LINE+1))" "$APP_TSX" | grep -cP "path:\s*'" 2>/dev/null)
+    if [ "$ROUTES_AFTER" -gt 0 ]; then
+      echo "WARNING: Route definitions found AFTER Navigate redirect — redirects should be LAST"
+    fi
+  fi
+
+  if [ "$FAIL" = true ]; then
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK C50: NavRoute Uniqueness — no duplicate NavRoute values (BLOCKING)
+
+> **Source:** Two controllers sharing the same NavRoute causes routing conflicts — one endpoint
+> silently overrides the other → 404 on the shadowed controller.
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  # Extract all NavRoute values with their file paths
+  NAVROUTES=$(grep -Pn '\[NavRoute\("([^"]+)"\)' $CTRL_FILES 2>/dev/null | sed 's/.*\[NavRoute("\([^"]*\)").*/\1/' | sort)
+  DUPLICATES=$(echo "$NAVROUTES" | uniq -d)
+  if [ -n "$DUPLICATES" ]; then
+    echo "BLOCKING: Duplicate NavRoute values detected:"
+    for DUP in $DUPLICATES; do
+      echo "  NavRoute: $DUP"
+      grep -l "\[NavRoute(\"$DUP\")\]" $CTRL_FILES 2>/dev/null | while read -r f; do
+        echo "    - $f"
+      done
+    done
+    echo "  Fix: Each controller MUST have a unique NavRoute value"
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK C51: NavRoute Segments vs Controller Hierarchy (WARNING)
+
+> **Source:** ContractsController in `Controllers/{App}/Employees/` subfolder had NavRoute
+> `human-resources.contracts` (2 segments) instead of `human-resources.employees.contracts`
+> (3 segments) → API resolved to wrong path → 404 on contracts endpoints.
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    NAVROUTE=$(grep -oP '\[NavRoute\("\K[^"]+' "$f")
+    if [ -z "$NAVROUTE" ]; then continue; fi
+
+    DOTS=$(echo "$NAVROUTE" | tr -cd '.' | wc -c)
+
+    # Count directory depth after Controllers/
+    # e.g., Controllers/HumanResources/Employees/ContractsController.cs = depth 2 (section)
+    REL_PATH=$(echo "$f" | sed 's|.*/Controllers/||')
+    DIR_DEPTH=$(echo "$REL_PATH" | tr '/' '\n' | wc -l)
+    # DIR_DEPTH: 2 = module level (App/Controller.cs), 3 = section level (App/Module/Controller.cs)
+
+    if [ "$DIR_DEPTH" -ge 3 ] && [ "$DOTS" -le 1 ]; then
+      echo "WARNING: Controller in section subfolder but NavRoute has only $((DOTS+1)) segments"
+      echo "  File: $f"
+      echo "  NavRoute: $NAVROUTE"
+      echo "  Expected: 3+ segments (app.module.section) for controllers in section subfolders"
+      echo "  Fix: Update NavRoute to include the module segment (e.g., 'app.module.section')"
+    fi
+
+    if [ "$DOTS" -eq 0 ]; then
+      echo "BLOCKING: NavRoute '$NAVROUTE' has only 1 segment (minimum 2 required): $f"
+      exit 1
+    fi
+  done
+fi
+```
+
 ---
 
 ## Architecture — Clean Architecture Layer Isolation
@@ -1737,6 +2010,63 @@ if [ -n "$CTRL_FILES" ]; then
 fi
 ```
 
+### POST-CHECK A8: API endpoints must match handoff apiEndpointSummary (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** 4/17 API endpoints (export, calculate, balance upsert, year-end)
+> were missing but all API tasks were marked COMPLETE. This check reconciles actual controller
+> endpoints against the handoff contract.
+
+```bash
+# Read apiEndpointSummary from PRD and verify each operation exists in controllers
+PRD_FILE=".ralph/prd.json"
+if [ ! -f "$PRD_FILE" ]; then
+  # Try module-specific PRD
+  if [ -f ".ralph/modules-queue.json" ]; then
+    PRD_FILE=$(cat .ralph/modules-queue.json | grep -o '"prdFile":"[^"]*"' | tail -1 | cut -d'"' -f4)
+  fi
+fi
+
+if [ -f "$PRD_FILE" ]; then
+  # Extract operation names from apiEndpointSummary
+  OPERATIONS=$(cat "$PRD_FILE" | grep -o '"operation"\s*:\s*"[^"]*"' | cut -d'"' -f4 2>/dev/null)
+
+  if [ -n "$OPERATIONS" ]; then
+    CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+    MISSING_OPS=""
+    TOTAL_OPS=0
+    FOUND_OPS=0
+
+    for op in $OPERATIONS; do
+      TOTAL_OPS=$((TOTAL_OPS + 1))
+      FOUND=false
+      if [ -n "$CTRL_FILES" ]; then
+        for f in $CTRL_FILES; do
+          if grep -q "$op" "$f" 2>/dev/null; then
+            FOUND=true
+            break
+          fi
+        done
+      fi
+      if [ "$FOUND" = true ]; then
+        FOUND_OPS=$((FOUND_OPS + 1))
+      else
+        MISSING_OPS="$MISSING_OPS $op"
+      fi
+    done
+
+    if [ -n "$MISSING_OPS" ]; then
+      echo "BLOCKING: API endpoints missing from controllers (handoff contract violation)"
+      echo "Found: $FOUND_OPS/$TOTAL_OPS operations"
+      echo "Missing operations:$MISSING_OPS"
+      echo "Fix: Implement missing endpoints in the appropriate Controller"
+      exit 1
+    else
+      echo "POST-CHECK A8: OK — $FOUND_OPS/$TOTAL_OPS API operations found"
+    fi
+  fi
+fi
+```
+
 ---
 
 ## Summary