@atlashub/smartstack-cli 3.25.0 → 3.26.0

package/package.json

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

package/templates/skills/apex/SKILL.md

@@ -33,7 +33,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | Flag | Description |
 |------|-------------|
 | `-a` | Auto mode: skip confirmations |
-| `-x` | Examine mode: adversarial code review |
+| `-x` | Deep review: adversarial code review (beyond step-04 automated checks) |
 | `-s` | Save mode: output to `.claude/output/apex/` |
 | `-t` | Test mode: scaffold + run tests via MCP |
 | `-e` | Economy mode: no subagents |
@@ -57,11 +57,17 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{context_code}` | string | "business", "platform", "personal" |
 | `{app_name}` | string | Application name |
 | `{module_code}` | string | Module code |
-| `{sections}` | string[] | Sections being added/modified |
+| `{sections}` | object[] | Sections (MANDATORY, min 1) with code/labels/icon/displayOrder |
+| `{entities}` | string[] | Main entities to manage (from need-challenge) |
+| `{module_complexity}` | string | "simple-crud", "crud-rules", "crud-workflow", "complex" |
+| `{has_dependencies}` | string | "none", "references", "unknown" |
+| `{key_properties}` | string[] | Key business properties mentioned by user |
 | `{prd_path}` | string? | `.ralph/prd-{module}.json` if exists |
 | `{feature_path}` | string? | `docs/business/.../feature.json` if exists |
 | `{needs_seed_data}` | boolean | Seed data creation required |
 | `{needs_migration}` | boolean | EF Core migration required |
+| `{needs_workflow}` | boolean | Workflow integration required |
+| `{needs_notification}` | boolean | Notification integration required |
 </state_variables>
 
 <entry_point>
@@ -75,17 +81,32 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | Step | File | Model | Purpose |
 |------|------|-------|---------|
-| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect SmartStack context, verify MCP |
+| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect context, verify MCP, define hierarchy (5 levels), challenge need |
 | 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
 | 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
 | 03 | `steps/step-03-execute.md` | Opus | Orchestrate execution via skills and MCP |
-| 04 | `steps/step-04-validate.md` | Opus | MCP validation, build, seed data check |
-| 05 | `steps/step-05-examine.md` | Opus | Adversarial review (if -x) |
+| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 21 POST-CHECKs, acceptance criteria |
+| 05 | `steps/step-05-deep-review.md` | Opus | Deep Review: adversarial code review (if -x) |
 | 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
 | 07 | `steps/step-07-tests.md` | Opus | Scaffold tests via MCP (if -t) |
 | 08 | `steps/step-08-run-tests.md` | Opus | Run tests until 100% pass (if -t) |
 </step_files>
 
+<apex_phases>
+**APEX = Analyze → Plan → Execute → eXamine**
+
+| Phase | Step | Obligatory | Description |
+|-------|------|------------|-------------|
+| *Init* | 00 | Yes | Setup, hierarchy, challenge the need |
+| **A** — Analyze | 01 | Yes | Explore existing code |
+| **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
+| **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP |
+| **X** — eXamine | 04 | Yes | 21 POST-CHECKs, MCP validation, build, acceptance criteria |
+| *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
+| *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
+| *Tests* | 07-08 (if -t) | No | Scaffold and run tests |
+</apex_phases>
+
 <reference_files>
 **Loaded conditionally by steps that need them:**
 

package/templates/skills/apex/_shared.md

@@ -30,7 +30,7 @@
 
 | Tool | Purpose | Step |
 |------|---------|------|
-| `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (validate) |
+| `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (examine) |
 
 ### Generation (step-03)
 
@@ -42,7 +42,7 @@
 | `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
 | `scaffold_routes` | Generate React Router routes | Frontend changes |
 
-### Validation (step-04)
+### eXamine (step-04)
 
 | Tool | Purpose | Condition |
 |------|---------|-----------|
@@ -65,7 +65,7 @@
 | `suggest_test_scenarios` | Suggest test scenarios |
 | `analyze_test_coverage` | Check coverage percentage |
 
-### Review (step-05, if -x)
+### Deep Review (step-05, if -x)
 
 | Tool | Purpose |
 |------|---------|

package/templates/skills/apex/references/agent-teams-protocol.md

@@ -22,7 +22,7 @@ Always provide both `team_name` and `description`.
 
 ```yaml
 Task:
-  subagent_type: "general-purpose"
+  subagent_type: "Explore" | "general-purpose"  # See assignment table below
   team_name: "apex-{phase}"          # Must match TeamCreate
   name: "{teammate-name}"            # e.g., "scan-backend", "exec-frontend"
   model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
@@ -30,14 +30,14 @@ Task:
   prompt: "{detailed task prompt}"
 ```
 
-### Model Assignment (T02/T06)
+### Model & Agent Assignment (T02/T03/T06)
 
-| Task Type | Model | Justification |
-|-----------|-------|---------------|
-| Scan/read files | Sonnet | Read-only, no analysis needed |
-| Read context (PRD, feature.json) | Sonnet | Read-only extraction |
-| Code development | Opus | Complex generation via skills/MCP |
-| Fix/resolve | Opus | Requires reasoning |
+| Task Type | subagent_type | Model | Justification |
+|-----------|---------------|-------|---------------|
+| Scan/read files | Explore | Sonnet | Read-only (Glob, Grep, Read) |
+| Read context (PRD, feature.json) | Explore | Sonnet | Read-only extraction |
+| Code development | general-purpose | Opus | Full tools via skills/MCP |
+| Fix/resolve | general-purpose | Opus | Requires reasoning + editing |
 
 ---
 

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

@@ -0,0 +1,165 @@
+# Challenge Questions — APEX
+
+> **Referenced by:** step-00-init.md
+> Question templates for context detection, hierarchy validation, and need challenging.
+
+---
+
+## Context Detection (section 2)
+
+If hierarchy cannot be inferred, ask the user:
+
+```yaml
+questions:
+  - header: "Context"
+    question: "What is the SmartStack context for this work?"
+    options:
+      - label: "Business (Recommended)"
+        description: "Business application module"
+      - label: "Platform"
+        description: "Platform administration or support"
+      - label: "Personal"
+        description: "Personal user space"
+    multiSelect: false
+```
+
+---
+
+## 4a. Application Validation
+
+If `{app_name}` was NOT clearly inferred from the task description:
+
+```yaml
+questions:
+  - header: "Application"
+    question: "Which application does this module belong to?"
+    options:
+      - label: "<best guess from task> (Recommended)"
+        description: "Inferred from your task description"
+      - label: "New application"
+        description: "Create a new application in the {context_code} context"
+      - label: "Existing application"
+        description: "Add to an existing application (specify in Other)"
+    multiSelect: false
+```
+
+If "New application": collect `{app_name}`, `{app_code}`, `{app_icon}`, `{app_labels}` (4 langs).
+If "Existing application": scan `**/Seeding/Data/**/NavigationApplicationSeedData.cs` and present discovered apps.
+
+---
+
+## 4b. Module Validation
+
+If `{module_code}` was NOT clearly inferred from the task description:
+
+```yaml
+questions:
+  - header: "Module"
+    question: "What is the module code? (kebab-case, e.g., 'order-management', 'employees')"
+    options:
+      - label: "<inferred module code> (Recommended)"
+        description: "Inferred from your task description"
+      - label: "<alternative suggestion>"
+        description: "Alternative based on keywords"
+    multiSelect: false
+```
+
+---
+
+## 4c. Section Selection
+
+> **BLOCKING:** This question MUST be asked. `{sections}` MUST contain at least one entry before proceeding.
+
+Infer section suggestions from:
+1. Task description (extract nouns/concepts that suggest functional sub-areas)
+2. PRD/feature.json if available (module.sections)
+3. Common patterns: "list" (default for simple CRUD), "dashboard", "settings", "reports"
+
+```yaml
+questions:
+  - header: "Sections"
+    question: "What sections should the module '{module_code}' contain? (Select at least one — use 'Other' to add custom sections)"
+    options:
+      - label: "<inferred section 1>"
+        description: "Primary functional area based on module purpose"
+      - label: "<inferred section 2>"
+        description: "Secondary functional area"
+      - label: "<inferred section 3>"
+        description: "Additional area inferred from context"
+    multiSelect: true
+```
+
+**Validation (BLOCKING):**
+```
+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
+  → DO NOT proceed to next step
+```
+
+**Store for each section:**
+```yaml
+sections:
+  - code: "section-kebab"
+    labels: { fr: "...", en: "...", it: "...", de: "..." }
+    icon: "LucideIconName"
+    displayOrder: 10
+```
+
+---
+
+## 5a. Entity Scope & Relationships
+
+```yaml
+questions:
+  - header: "Entities"
+    question: "What are the main entities this module manages? (e.g., 'Order, OrderLine, OrderStatus')"
+    options:
+      - label: "<inferred primary entity>"
+        description: "Main entity inferred from module name"
+      - label: "<inferred primary + secondary>"
+        description: "Primary entity plus related entities from context"
+      - label: "Only the primary entity"
+        description: "Simple module — single entity '{module_code}' with standard CRUD"
+    multiSelect: false
+  - header: "Complexity"
+    question: "What best describes this module's behavior?"
+    options:
+      - label: "Simple CRUD (Recommended)"
+        description: "Standard list/create/edit/delete — no special business logic"
+      - label: "CRUD + Business rules"
+        description: "CRUD with validations, computed fields, status transitions, or constraints"
+      - label: "CRUD + Workflow/Notifications"
+        description: "CRUD with automated actions (emails, approvals, webhooks)"
+      - label: "Complex module"
+        description: "Multiple interrelated entities with specific business logic"
+    multiSelect: false
+```
+
+---
+
+## 5b. Dependencies & Key Properties
+
+```yaml
+questions:
+  - header: "Dependencies"
+    question: "Does this module reference entities from other existing modules?"
+    options:
+      - label: "No dependencies"
+        description: "Standalone module — no FK relationships to other modules"
+      - label: "Yes, has FK references"
+        description: "References entities from other modules (specify in Other)"
+      - label: "Not sure yet"
+        description: "Will determine during analysis — may require EntityLookup components"
+    multiSelect: false
+  - header: "Key fields"
+    question: "Beyond standard fields (Id, TenantId, Audit), what are the key business properties of the main entity?"
+    options:
+      - label: "<inferred properties from context>"
+        description: "Properties inferred from module purpose"
+      - label: "Standard fields only"
+        description: "I'll define properties later during implementation"
+      - label: "I have specific requirements"
+        description: "Describe your fields in 'Other'"
+    multiSelect: false
+```

package/templates/skills/apex/{steps/step-04-validate.md → references/post-checks.md}

@@ -1,145 +1,6 @@
----
-name: step-04-validate
-description: MCP validation, build verification, seed data check, acceptance criteria
-model: opus
-prev_step: steps/step-03-execute.md
-next_step: steps/step-05-examine.md
----
-
-# Step 4: Validate
-
-**Goal:** Verify everything works. MCP conventions, build, seed data, acceptance criteria.
-
----
-
-## 1. MCP Convention Validation
-
-```
-Call: mcp__smartstack__validate_conventions
-
-Expected: 0 errors
-If errors found:
-  → Fix each error (use appropriate skill/MCP)
-  → Re-validate until 0 errors
-```
-
----
-
-## 2. EF Core Migration Check (if needs_migration)
-
-```
-Call: mcp__smartstack__check_migrations
-
-Verify:
-- Migration exists and is applied
-- No pending model changes
-- ModelSnapshot matches
-```
-
----
-
-## 3. Frontend Route Validation (if frontend modified)
-
-```
-Call: mcp__smartstack__validate_frontend_routes
-
-Verify:
-- Routes nested inside correct Layout wrapper
-- Route paths match controller patterns
-- No orphan routes
-```
-
----
-
-## 4. Build Verification
-
-```bash
-# Cleanup corrupted EF Core design-time artifacts (Roslyn BuildHost bug on Windows)
-for d in src/*/bin?Debug; do [ -d "$d" ] && echo "Removing corrupted artifact: $d" && rm -rf "$d"; done
-
-# Backend
-dotnet clean && dotnet restore && dotnet build
-
-# Frontend (if applicable)
-npm run typecheck
-```
-
-**BLOCKING:** Both must pass. If failure, fix and retry.
-
----
-
-## 5. Database & Migration Validation (if needs_migration)
-
-### 5a. Pending Model Changes Check
-
-```bash
-INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
-API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
-
-dotnet ef migrations has-pending-model-changes \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$API_PROJECT"
-```
-
-**BLOCKING** if pending changes detected → migration is missing.
-
-### 5b. Migration Application Test (SQL Server LocalDB)
-
-```bash
-DB_NAME="SmartStack_Apex_Validate_$(date +%s)"
-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"
-```
-
-**BLOCKING** if migration fails on SQL Server. Common issues:
-- SQLite-only syntax in migrations (fix: regenerate migration)
-- Column type mismatches (fix: update EF configuration)
-- Missing foreign key targets (fix: reorder migrations)
-
-### 5c. Integration Tests on Real SQL Server
-
-```bash
-# Integration tests use DatabaseFixture → real SQL Server LocalDB
-# This validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs
-INT_TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
-if [ -n "$INT_TEST_PROJECT" ]; then
-  dotnet test "$INT_TEST_PROJECT" --no-build --verbosity normal
-fi
-```
-
-Tests running against SQL Server catch issues that SQLite misses:
-- Case sensitivity in string comparisons
-- Date/time function differences
-- IDENTITY vs AUTOINCREMENT behavior
-- Global query filter translation to T-SQL
-
-### 5d. Cleanup
-
-```bash
-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
-```
-
----
-
-## 6. Seed Data Completeness Check (if needs_seed_data)
-
-| File | Checks |
-|------|--------|
-| NavigationApplicationSeedData | MUST be first, deterministic GUID, 4 lang translations |
-| NavigationModuleSeedData | Deterministic GUIDs (SHA256), 4 languages, GetModuleEntry + GetTranslationEntries |
-| PermissionsSeedData | MCP generate_permissions used, paths match Permissions.cs, wildcard + CRUD |
-| RolesSeedData | Admin=wildcard, Manager=CRU, Contributor=CR, Viewer=R |
-| IClientSeedDataProvider | 3 Seed methods, idempotent, factory methods, SaveChanges per group |
-| DI Registration | `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()` |
-
----
-
-## 6b. BLOCKING POST-CHECKs (bash verification on real files)
+# BLOCKING POST-CHECKs
 
+> **Referenced by:** step-04-examine.md (section 6b)
 > These checks run on the actual generated files. Model-interpreted checks are unreliable.
 
 ### POST-CHECK 1: Navigation routes must be full paths starting with /
@@ -210,15 +71,17 @@ if [ -n "$SEED_FILES" ]; then
 fi
 ```
 
-### POST-CHECK 5: Services must inject ICurrentUser
+### POST-CHECK 5: Services must inject ICurrentTenantService (tenant isolation)
 
 ```bash
 SERVICE_FILES=$(find src/ -path "*/Services/*" -name "*Service.cs" ! -name "I*Service.cs" 2>/dev/null)
 if [ -n "$SERVICE_FILES" ]; then
   for f in $SERVICE_FILES; do
-    if ! grep -q "ICurrentUser" "$f"; then
-      echo "BLOCKING: Service missing ICurrentUser injection: $f"
-      echo "All services MUST inject ICurrentUser for tenant isolation"
+    # Accept either ICurrentTenantService or ICurrentUser (legacy) for tenant context
+    if ! grep -qE "ICurrentTenantService|ICurrentUser" "$f"; then
+      echo "BLOCKING: Service missing tenant context injection: $f"
+      echo "All services MUST inject ICurrentTenantService for tenant isolation"
+      echo "Pattern: private readonly ICurrentTenantService _currentTenant;"
       exit 1
     fi
   done
@@ -509,81 +372,86 @@ if [ -n "$CREATE_VALIDATORS" ]; then
 fi
 ```
 
-**If ANY POST-CHECK fails → fix in step-03, re-validate.**
-
----
-
-## 7. Acceptance Criteria POST-CHECK
-
-For each AC inferred in step-01:
-
-```
-AC1: {criterion} → PASS / FAIL (evidence: {file:line or test})
-AC2: {criterion} → PASS / FAIL (evidence: {file:line or test})
-...
-```
-
-**All ACs must PASS. If any FAIL, go back to step-03 to fix.**
-
----
-
-## 8. Validation Summary
+### POST-CHECK 19: SeedConstants must NOT contain ContextId (pre-seeded by SmartStack core)
 
+```bash
+# NavigationContext IDs (business, platform, personal) are pre-seeded by SmartStack core
+# with hardcoded GUIDs. Client code MUST look them up by code at runtime, NEVER generate them.
+SEED_CONST_FILES=$(find src/ -path "*/Seeding/*" -name "SeedConstants.cs" 2>/dev/null)
+SEED_ALL_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*.cs" 2>/dev/null)
+if [ -n "$SEED_CONST_FILES" ]; then
+  BAD_CONTEXT_ID=$(grep -Pn 'ContextId\s*=' $SEED_CONST_FILES 2>/dev/null)
+  if [ -n "$BAD_CONTEXT_ID" ]; then
+    echo "BLOCKING: SeedConstants must NOT contain a ContextId constant"
+    echo "NavigationContext IDs are pre-seeded by SmartStack core with hardcoded GUIDs"
+    echo "Fix: Remove ContextId from SeedConstants. In SeedDataProvider, query:"
+    echo "  var ctx = await db.NavigationContexts.FirstOrDefaultAsync(c => c.Code == \"business\", ct);"
+    echo "$BAD_CONTEXT_ID"
+    exit 1
+  fi
+fi
+if [ -n "$SEED_ALL_FILES" ]; then
+  BAD_CTX_GUID=$(grep -Pn 'DeterministicGuid\("nav:(business|platform|personal)"\)' $SEED_ALL_FILES 2>/dev/null)
+  if [ -n "$BAD_CTX_GUID" ]; then
+    echo "BLOCKING: Deterministic GUID for NavigationContext detected"
+    echo "Context IDs (business, platform, personal) are pre-seeded by SmartStack core"
+    echo "Fix: Look up context by code at runtime in SeedDataProvider.SeedNavigationAsync()"
+    echo "$BAD_CTX_GUID"
+    exit 1
+  fi
+fi
 ```
-**APEX SmartStack - Validation Complete**
-
-| Check | Status |
-|-------|--------|
-| MCP validate_conventions | PASS (0 errors) |
-| EF Core migrations | PASS / N/A |
-| DB: Migrations apply (SQL Server) | PASS / N/A |
-| DB: Integration tests (SQL Server) | PASS / N/A |
-| Frontend routes | PASS / N/A |
-| dotnet build | PASS |
-| npm typecheck | PASS / N/A |
-| Seed data | PASS / N/A |
-| I18n: 4 languages per namespace | PASS / N/A |
-| Lazy loading: no static page imports | PASS / N/A |
-| Forms: full pages, zero modals | PASS / N/A |
-| Forms: create/edit pages exist | PASS / N/A |
-| Forms: test files exist | PASS / N/A |
-| FK fields: EntityLookup, no plain text | PASS / N/A |
-| APIs: search parameter on GetAll | PASS / N/A |
-| CSS variables: no hardcoded colors | PASS / N/A |
-| Routes: seed data vs frontend match | PASS / N/A |
-| HasQueryFilter: no Guid.Empty pattern | PASS / N/A |
-| GetAll: PaginatedResult required | PASS / N/A |
-| I18n: required key structure | PASS / N/A |
-| Entities: IAuditableEntity + validators | PASS / N/A |
-| Acceptance criteria | {X}/{Y} PASS |
-```
-
----
-
-## 9. Save Output (if save_mode)
-
-Write to `{output_dir}/04-validate.md` with validation results.
-
----
 
-## 10. Route to Next Step
+### POST-CHECK 20: RolePermission seed data must NOT use deterministic role GUIDs
 
+```bash
+# System roles (admin, manager, contributor, viewer) are pre-seeded by SmartStack core.
+# RolePermission mappings MUST look up roles by Code at runtime, NEVER use deterministic GUIDs.
+SEED_ALL_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*.cs" 2>/dev/null)
+SEED_CONST_FILES=$(find src/ -path "*/Seeding/*" -name "SeedConstants.cs" 2>/dev/null)
+if [ -n "$SEED_ALL_FILES" ]; then
+  BAD_ROLE_GUID=$(grep -Pn 'DeterministicGuid\("role:' $SEED_ALL_FILES $SEED_CONST_FILES 2>/dev/null)
+  if [ -n "$BAD_ROLE_GUID" ]; then
+    echo "BLOCKING: Deterministic GUID for role detected (e.g., DeterministicGuid(\"role:admin\"))"
+    echo "System roles are pre-seeded by SmartStack core with their own IDs"
+    echo "Fix: In SeedRolePermissionsAsync(), look up roles by Code:"
+    echo "  var roles = await context.Roles.Where(r => r.IsSystem || r.ApplicationId != null).ToListAsync(ct);"
+    echo "  var role = roles.FirstOrDefault(r => r.Code == mapping.RoleCode);"
+    echo "$BAD_ROLE_GUID"
+    exit 1
+  fi
+fi
+# Also check for GenerateRoleGuid usage in RolePermission mapping files (not in ApplicationRolesSeedData itself)
+ROLE_PERM_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*RolesSeedData.cs" 2>/dev/null)
+if [ -n "$ROLE_PERM_FILES" ]; then
+  BAD_ROLE_REF=$(grep -Pn 'GenerateRoleGuid|GetAdminRoleId|GetManagerRoleId|GetViewerRoleId|GetContributorRoleId' $ROLE_PERM_FILES 2>/dev/null)
+  if [ -n "$BAD_ROLE_REF" ]; then
+    echo "WARNING: RolesSeedData uses hardcoded role GUID helpers instead of Code-based lookup"
+    echo "Fix: Use RoleCode string (e.g., 'admin') and resolve in SeedRolePermissionsAsync()"
+    echo "$BAD_ROLE_REF"
+  fi
+fi
 ```
-IF examine_mode = true:
-  → Load steps/step-05-examine.md
 
-ELSE IF test_mode = true:
-  → Load steps/step-07-tests.md
+### POST-CHECK 21: Services must NOT use TenantId!.Value (null-forgiving crash pattern)
 
-ELSE IF pr_mode = true:
-  → Create PR and show final summary
-
-ELSE:
-  → Show final summary and exit
+```bash
+# The !.Value pattern on Guid? throws InvalidOperationException (500) instead of clean 401
+SERVICE_FILES=$(find src/ -path "*/Services/*" -name "*Service.cs" ! -name "I*Service.cs" 2>/dev/null)
+if [ -n "$SERVICE_FILES" ]; then
+  BAD_PATTERN=$(grep -Pn 'TenantId!\s*\.Value|TenantId!\s*\.ToString|\.TenantId!' $SERVICE_FILES 2>/dev/null)
+  if [ -n "$BAD_PATTERN" ]; then
+    echo "BLOCKING: Services use TenantId!.Value — causes 500 instead of 401 when tenant context is missing"
+    echo "$BAD_PATTERN"
+    echo ""
+    echo "Fix: Replace with guard clause at the start of every method:"
+    echo "  var tenantId = _currentTenant.TenantId"
+    echo "      ?? throw new UnauthorizedAccessException(\"Tenant context is required\");"
+    echo ""
+    echo "This produces a clean 401 via GlobalExceptionHandlerMiddleware instead of an opaque 500."
+    exit 1
+  fi
+fi
 ```
 
----
-
-## FINAL SUMMARY (if no more steps)
-
-Display: task, context, files created/modified, validation status, commits count, next steps (git diff, dotnet test, deploy).
+**If ANY POST-CHECK fails → fix in step-03, re-validate.**