@atlashub/smartstack-cli 4.32.0 → 4.34.0

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -0,0 +1,300 @@
+---
+name: step-03d-layer3-frontend
+description: "Layer 3: Frontend pages, i18n, routes, documentation, and tests"
+model: opus
+parent_step: steps/step-03-execute.md
+---
+
+# Layer 3 — Frontend (Pages + I18n + Documentation)
+
+### ⛔ HARD RULE — /ui-components is NON-NEGOTIABLE (read BEFORE any Layer 3 action)
+
+> **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.
+>
+> **Agent boundary rule:** Snipper sub-agents DO NOT have access to the Skill tool.
+> Therefore, .tsx page generation MUST NEVER be delegated to Snipper agents.
+> Pages are ALWAYS generated by the principal agent via Skill("ui-components").
+> Snipper agents handle: API clients, routes, wiring, i18n, tests — NOT pages.
+
+### Load Frontend References (deferred from top of step)
+
+- Read `references/smartstack-frontend.md` now — lazy loading, i18n, page structure, CSS variables, EntityLookup (sections 1-6)
+- Read `references/smartstack-frontend-compliance.md` now — documentation, form testing, compliance gates (sections 7-9)
+
+### Pre-flight: Shared component existence check
+
+Before generating any page, verify shared components exist:
+
+```
+Glob("src/components/ui/DataTable.*")
+Glob("src/components/ui/EntityCard.*")
+Glob("src/components/ui/PageLoader.*")
+Glob("src/components/ui/EntityLookup.*")
+```
+
+If ANY shared component is MISSING:
+  → Log warning: "Shared component {Component} not found — will be generated locally"
+  → When invoking Skill("ui-components"), add instruction:
+    "MISSING SHARED COMPONENTS: {list}. Generate these locally in src/components/ui/"
+
+**EntityLookup special handling (FK fields):**
+If ANY entity has FK Guid fields (e.g., EmployeeId, DepartmentId) AND EntityLookup is missing:
+  → Include EntityLookup generation in the Skill("ui-components") invocation
+  → Add to the skill prompt: "MISSING SHARED COMPONENT: EntityLookup. Generate EntityLookup in src/components/ui/EntityLookup.tsx"
+  → The /ui-components skill has the EntityLookup pattern in smartstack-frontend.md section 6
+  → Critical requirement for the skill: response parsing MUST use `(res.data.items || res.data).map(mapOption)`
+  → Verify after generation: the component MUST contain `(res.data.items || res.data).map(mapOption)` — if not, fix it
+  → Do NOT generate EntityLookup manually via Write tool — always via Skill("ui-components")
+
+### Task Progress
+TaskUpdate(taskId: layer3_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 3",
+  activeForm: "Executing Layer 3")
+
+> **Frontend patterns** are in `references/smartstack-frontend.md` (already loaded above):
+> - API client generation (MCP scaffold_api_client)
+> - Route scaffolding (MCP scaffold_routes) — section 1 + 3b
+> - Page types (ListPage, DetailPage, CreatePage, EditPage) — section 3
+> - FK field handling (EntityLookup component) — section 6
+> - Form structure (no modals — all full pages) — section 3b
+> - Detail page tabs (local state only) — section 3 "Tab Behavior Rules"
+> - Testing patterns (co-located form tests) — section 8
+> - Section-level routes and permissions — section 3b
+> - I18n JSON structure and registration — section 2
+> - Compliance gates (5 mandatory checks) — section 9
+
+### Frontend Tasks (sequential or parallel within layer)
+
+For each module:
+- API client: MCP scaffold_api_client
+- Routes — TWO mandatory steps:
+  1. Generate registry: MCP scaffold_routes (source: 'controllers', outputFormat: 'componentRegistry', dryRun: false)
+     → Creates/updates componentRegistry.generated.ts + navRoutes.generated.ts
+  2. Verify PageRegistry registration (see below)
+- 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
+  → CSS variables only: bg-[var(--bg-card)], text-[var(--text-primary)]
+  → DataTable/EntityCard (not raw HTML `<table>`)
+  → If entity has FK Guid fields: generate EntityLookup component in @/components/ui/EntityLookup (see smartstack-frontend.md section 6)
+  → Dashboard pages: generate StatCard + ChartCard locally (see ui-components patterns/dashboard-chart.md)
+- Form pages: Create/Edit forms are full pages with own routes:
+  → EntityCreatePage.tsx with route /{module}/create
+  → EntityEditPage.tsx with route /{module}/:id/edit
+  → Zero modals/popups/drawers/dialogs for forms
+  → Back button with navigate(-1) on every form page
+  → See smartstack-frontend.md section 3b for templates
+- Tabs on detail pages: Tabs must switch content locally:
+  → Tab click handler: setActiveTab(tabKey) only — do not navigate() to another page
+  → Tab content: render inline with {activeTab === 'tabKey' && <TabContent />}
+  → Sub-resource data: fetch via API filtered by parent ID, display in tab panel
+  → Do not use navigate('../leaves?employee=${id}') in tab handler
+  → See smartstack-frontend.md section 3 'Tab Behavior Rules'
+- FK fields: Foreign key Guid fields (e.g., EmployeeId) must use EntityLookup:
+  → Do not render FK fields as `<input>` — users cannot type GUIDs
+  → Do not render FK fields as `<select>` — even with API-loaded options, `<select>` is not acceptable
+  → Only use `<EntityLookup />` from @/components/ui/EntityLookup for searchable selection
+  → Each FK field needs: apiEndpoint, mapOption (display name), search support on backend
+  → Do not use `<select value={formData.departmentId}>`, `<option value={dept.id}>`, `e.target.value` for FK fields
+  → See smartstack-frontend.md section 6 for the full EntityLookup pattern
+<!-- TODO A12: Replace direct i18n generation with MCP scaffold_i18n when B4 is ready -->
+- I18n: Generate 4 JSON files per module namespace (fr, en, it, de)
+  → Follow JSON template from smartstack-frontend.md
+  → Keys: actions, labels, errors, validation, columns, form, messages, empty
+  → All t() calls must use namespace prefix + fallback: t('ns:key', 'Default text')
+  → **Register namespace in i18n config** (critical — POST-CHECK C39 catches this, but fix it now):
+    1. Find i18n config: `Glob("src/**/i18n/config.ts")` or `index.ts` or `i18n.ts`
+    2. Read the config → find the resources/ns registration pattern
+    3. Add the new namespace import + registration for all 4 languages
+    4. If config uses dynamic imports: add namespace to the `ns` array
+    5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
+- Permissions: Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
+  then also call MCP generate_permissions for each section (3 segments: {app}.{module}.{section}).
+- Section routes: Ensure navigation seed data has ComponentKey matching PageRegistry keys.
+  ComponentKey convention: `{app_code}.{module_code}.{section_code}` (dot-separated, lowercase).
+  DynamicRouter generates the URL paths from seed data Route field.
+- MUST use src/pages/{App}/{Module}/ hierarchy (NOT flat)
+
+### Documentation (after frontend pages exist)
+
+> **After frontend pages are created, generate module documentation via `/documentation` skill.**
+
+```
+Invoke /documentation {module_code} --type user
+
+This generates:
+- src/pages/docs/business/{app}/{module}/doc-data.ts (data file)
+- src/pages/docs/business/{app}/{module}/index.tsx (page wrapper)
+- src/i18n/locales/fr/docs-{app}-{module}.json (French doc translations)
+- Updates App.tsx routing for doc page
+- Updates docs-manifest.json
+```
+
+**Verify DocToggleButton presence in list/detail pages:**
+- Every `*ListPage.tsx` and `*DetailPage.tsx` MUST import and render `DocToggleButton` in their header
+- Import: `import { DocToggleButton } from '@/components/docs/DocToggleButton';`
+- Placement: inside the header actions area (see `smartstack-frontend.md` section 7)
+
+### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
+
+> **Protocol:** See `references/parallel-execution.md`
+
+```
+IF NOT economy_mode AND entities.length > 1:
+  # PHASE A — Parallel: infrastructure frontend (NO page generation)
+  # Snipper agents DO NOT have access to the Skill tool, so they CANNOT call /ui-components.
+  # Pages MUST be generated by the principal agent in Phase B.
+  For each entity, launch in parallel (single message):
+    Agent(subagent_type='Snipper', model='opus',
+      prompt='Execute Layer 3 INFRASTRUCTURE for {EntityName}:
+        **MANDATORY: Read references/smartstack-frontend.md FIRST**
+        - API client: MCP scaffold_api_client
+        - Routes: MCP scaffold_routes (outputFormat: "componentRegistry", dryRun: false)
+          → MUST generate componentRegistry.generated.ts + navRoutes.generated.ts
+        - Verify: componentRegistry.generated.ts has PageRegistry.register() for new pages
+        - Verify: main.tsx imports componentRegistry.generated (one-time check)
+        - NO manual App.tsx wiring needed — DynamicRouter handles routing
+        - I18n: 4 JSON files (fr, en, it, de) + REGISTER namespace in i18n config
+        - DO NOT generate any .tsx page files — pages are handled by the principal agent
+        - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
+        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
+  # Wait for all agents to complete
+
+  # PHASE B — Sequential: pages via /ui-components (principal agent)
+  # Snipper agents cannot call Skill() — only the principal agent can.
+  For each entity (sequentially):
+    **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)"
+      - "FK FIELDS: EntityLookup for ALL FK Guid fields"
+      - "I18n: ALL text uses t('namespace:key', 'Fallback')"
+    Generate form tests: co-located .test.tsx for Create and Edit pages
+
+ELSE:
+  # 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: 'componentRegistry')
+    3. Verify PageRegistry registration (componentRegistry.generated.ts)
+       No manual App.tsx wiring needed — DynamicRouter resolves at runtime
+    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
+
+When launching agents for multi-entity layers:
+- Each agent receives its task ID and metadata context in the prompt
+- Agent must call TaskUpdate(status: "in_progress") before starting
+- Agent must call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done
+- Agent principal monitors via TaskList() after all agents complete
+- Agent principal updates activeForm after each entity completion:
+  `TaskUpdate(taskId: layer3_task_id, activeForm: "Building {EntityName} frontend (2/5 entities)")`
+
+### Frontend Compliance Gate
+
+> See `references/smartstack-frontend-compliance.md` section 9 "Compliance Gates" for all 6 required checks:
+> 1. CSS Variables (theme system)
+> 2. Forms as Pages (zero modals/drawers/slide-overs)
+> 3. I18n File Structure (4 languages, separate JSON files)
+> 4. Lazy Loading (React.lazy() — no static imports)
+> 5. useTranslation in Pages (all text translated)
+> 6. SmartStack Components (no raw HTML tables — DataTable/EntityCard required)
+
+Do not commit frontend changes until all 6 gates pass.
+
+When delegating to `/ui-components` skill, include explicit instructions:
+- "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`."
+- "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/`."
+
+### Frontend Tests Inline
+
+> **Tests are scaffolded and run WITHIN Layer 3, not deferred to step-07.**
+
+```
+1. Scaffold frontend tests:
+   → For each module with create/edit pages:
+     → Generate EntityCreatePage.test.tsx and EntityEditPage.test.tsx
+     → Co-located next to the page component (NOT in __tests__/ folder)
+     → Cover: rendering, validation, submit, pre-fill, navigation, errors
+     → Tools: Vitest + React Testing Library + @testing-library/user-event
+     → Mock API: vi.mock() or MSW — NEVER real API calls
+
+2. Run tests:
+   WEB_DIR=$(find . -name "vitest.config.ts" -not -path "*/node_modules/*" -exec dirname {} \; 2>/dev/null | head -1)
+   if [ -n "$WEB_DIR" ]; then
+     (cd "$WEB_DIR" && npm run test)
+   fi
+
+3. Fix loop (max 3 iterations):
+   IF tests fail:
+     → Identify root cause (ALWAYS code bug, not test bug)
+     → Fix production CODE
+     → Re-run tests
+     → Repeat until pass or max 3
+
+4. If still failing after 3 iterations: note failures, continue.
+   Step-07 "Final Test Sweep" will handle remaining failures.
+```
+
+### Typecheck Gate
+
+```bash
+npm run typecheck
+```
+
+Must pass before commit.
+
+TaskUpdate(taskId: layer3_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
+### Layer 3 Commits
+
+```
+feat({module}): [frontend] pages, routes, i18n, documentation
+test({module}): frontend form tests
+```
+
+---
+
+## NEXT SUB-STEP
+
+Load `steps/step-03e-layer4-devdata.md`

package/templates/skills/apex/steps/step-03e-layer4-devdata.md

@@ -0,0 +1,44 @@
+---
+name: step-03e-layer4-devdata
+description: "Layer 4: Development test data (optional)"
+model: opus
+parent_step: steps/step-03-execute.md
+---
+
+## Layer 4 — DevData (optional)
+
+### Task Progress
+IF layer4 task exists: TaskUpdate(taskId: layer4_task_id, status: "in_progress")
+IF layer4 task exists: TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 4",
+  activeForm: "Executing Layer 4")
+
+> **Business test data for development/demo environments.**
+> Skip this layer if no meaningful test data is needed.
+
+```
+1. Create DevDataSeeder:
+   → Infrastructure/Persistence/Seeding/DevData/{Module}DevDataSeeder.cs
+   → ALL entities MUST include TenantId
+   → Realistic business data for demo purposes
+
+2. Build gate:
+   dotnet build → MUST PASS
+```
+
+<!-- TODO A13: Replace with MCP scaffold_extension(type: "devdata") when B5 is ready -->
+
+IF layer4 task exists: TaskUpdate(taskId: layer4_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
+### Layer 4 Commit (if applicable)
+
+```
+feat({module}): [devdata] test data for development
+```
+
+---
+
+## SUB-STEPS COMPLETE
+
+Return to `steps/step-03-execute.md` for PRD State Update, State Auto-Save, and routing to step-04.

package/templates/skills/apex/steps/step-04-examine.md

@@ -16,15 +16,8 @@ next_step: steps/step-05-deep-review.md
 
 ## 0. Task Progress
 
-### Progress Tracker Update
-```
-TaskUpdate(taskId: progress_tracker_id,
-  description: "Module: {module_code}. Current: step-04 (eXamine)",
-  activeForm: "Validating conventions")
-```
-
-### eXamine Task Lifecycle
 ```
+TaskUpdate(taskId: progress_tracker_id, description: "Module: {module_code}. Current: step-04 (eXamine)", activeForm: "Validating conventions")
 TaskUpdate(taskId: examine_task_id, status: "in_progress")
 ```
 
@@ -34,64 +27,41 @@ TaskUpdate(taskId: examine_task_id, status: "in_progress")
 
 ```
 Call: mcp__smartstack__validate_conventions
-
-Expected: 0 errors
-If errors found:
-  → Fix each error (use appropriate skill/MCP)
-  → Re-validate until 0 errors
+Expected: 0 errors. Fix and re-validate if any found.
 ```
 
----
-
 ## 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
+Verify: Migration exists, no pending 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
+- Routes nested in correct Layout wrapper
+- Route paths match controller patterns, include module segment
 - No orphan routes
-- Route paths include module segment (e.g., 'employee-management/employees', NOT just 'employees')
-  → Compare frontend route paths in App.tsx against backend NavigationSeedData routes
-  → If backend defines route /app/module/section, frontend must use module/section (relative)
+- Compare frontend routes (componentRegistry.generated.ts or App.tsx) against backend NavigationSeedData routes
 ```
 
-### 3b. Frontend Page Completeness
-
-> POST-CHECKs C4, C5, and C6 in `references/post-checks.md` cover this verification (dead navigation links, missing Create/Edit pages, missing test files). Executed in section 6b below.
->
-> ROOT CAUSE (test-v4-015): Frontend generation created List + Detail pages but SKIPPED Create + Edit pages → white screen / 404.
-
-**If ANY check fails → return to step-03 to generate the missing pages, tests, or routes.**
+> **Page completeness:** POST-CHECKs C4, C5, C6 (dead links, missing Create/Edit, missing tests) executed in section 6b.
+> **If ANY check fails → return to step-03.**
 
 ---
 
 ## 4. Build Verification
 
 ```bash
-# Backend
 dotnet clean && dotnet restore && dotnet build
-# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
-
-# Frontend (if applicable)
-npm run typecheck
+npm run typecheck  # if applicable
 ```
 
-Both must pass. If failure, classify error per `references/error-classification.md` (categories A-F).
+Both must pass. Classify errors per `references/error-classification.md` (A-F).
 
 ---
 
@@ -101,30 +71,22 @@ Both must pass. If failure, classify error per `references/error-classification.
 INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
 API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
 
-# Pending model changes check (BLOCKING if pending)
-dotnet ef migrations has-pending-model-changes \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$API_PROJECT"
+# Check pending model changes
+dotnet ef migrations has-pending-model-changes --project "$INFRA_PROJECT" --startup-project "$API_PROJECT"
 
-# Migration application test (SQL Server LocalDB)
+# Apply to SQL Server LocalDB
 DB_NAME="SmartStack_Apex_Examine_$(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"
+dotnet ef database update --connection "Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;" --project "$INFRA_PROJECT" --startup-project "$API_PROJECT"
 
-# Integration tests on real SQL Server (if project exists)
+# Run integration tests if present
 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
+[ -n "$INT_TEST_PROJECT" ] && dotnet test "$INT_TEST_PROJECT" --no-build --verbosity normal
 
 # Cleanup
 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
 ```
 
-If migration fails on SQL Server (common: SQLite-only syntax, column type mismatches, missing FK targets), fix the DbContext or migration first.
+If migration fails (SQLite-only syntax, type mismatches, missing FK targets), fix the DbContext or migration first.
 
 ---
 
@@ -132,137 +94,95 @@ If migration fails on SQL Server (common: SQLite-only syntax, column type mismat
 
 | File | Checks |
 |------|--------|
-| NavigationApplicationSeedData | MUST be first, 4 lang translations |
-| ApplicationRolesSeedData | 4 roles (admin, manager, contributor, viewer), references NavigationApplicationSeedData.ApplicationId |
-| NavigationModuleSeedData | 4 languages (fr, en, it, de), GetModuleEntry + GetTranslationEntries |
-| ↳ Section methods (same file) | (conditional: if sections exist) GetSectionEntries + GetSectionTranslationEntries, 4 languages, random GUIDs, query actual module from DB for FK |
-| ↳ Resource methods (same file) | (conditional: if resources exist) GetResourceEntries + resource translations, 4 languages, random GUIDs, query actual section from DB for FK |
-| Permissions.cs | Static constants class with `public static class {Module} { Read, Create, Update, Delete }`, paths match PermissionsSeedData |
-| PermissionsSeedData | MCP generate_permissions used, paths match Permissions.cs, wildcard + CRUD |
-| RolesSeedData | Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R. Role-permission entries reference permission paths from PermissionsSeedData |
-| IClientSeedDataProvider | 4 Seed methods (Navigation, Roles, Permissions, RolePermissions), idempotent, factory methods, SaveChanges per group |
+| NavigationApplicationSeedData | 4 lang translations |
+| ApplicationRolesSeedData | 4 roles, references NavigationApplicationSeedData.ApplicationId |
+| NavigationModuleSeedData | 4 languages, GetModuleEntry + translations |
+| ↳ Section methods | GetSectionEntries + translations, 4 languages, random GUIDs |
+| ↳ Resource methods | GetResourceEntries + translations, 4 languages, random GUIDs |
+| Permissions.cs | Static class with Read/Create/Update/Delete constants, match PermissionsSeedData |
+| PermissionsSeedData | MCP generate_permissions, paths match Permissions.cs |
+| RolesSeedData | Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R |
+| IClientSeedDataProvider | 4 Seed methods, idempotent, SaveChanges per group |
 | DI Registration | `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()` |
 
 ---
 
 ## 6b. POST-CHECKs
 
-> **MCP FIRST:** Run `validate_conventions`, `validate_security`, and `validate_frontend_routes` before bash checks.
-> These 3 MCP tools cover ~10 additional checks automatically.
-
-Load and execute all checks from `references/post-checks.md` (security + convention + architecture checks).
+**MCP FIRST:** Run `validate_conventions`, `validate_security`, `validate_frontend_routes` (covers ~10 checks).
 
-If any POST-CHECK fails, fix in step-03 and re-validate.
+Execute all checks from `references/post-checks.md`. If any fails, fix in step-03 and re-validate.
 
 ---
 
 ## 7. Acceptance Criteria POST-CHECK
 
-For each AC inferred in step-01:
-
+For each AC from step-01:
 ```
-AC1: {criterion} → PASS / FAIL (evidence: {file:line or test})
-AC2: {criterion} → PASS / FAIL (evidence: {file:line or test})
+AC1: {criterion} → PASS / FAIL (evidence)
 ...
 ```
-
-**All ACs must PASS. If any FAIL, go back to step-03 to fix.**
+**All ACs must PASS. If any FAIL, return to step-03.**
 
 ---
 
 ## 8. eXamine Summary
 
-```
 **APEX SmartStack - eXamine Complete**
 
-| Layer | Status | Details |
-|-------|--------|---------|
-| Layer 0 — Domain + Infrastructure | PASS / N/A | Entities, EF configs, migration, build gate |
-| Layer 1 — Seed Data | PASS / N/A | Navigation, permissions, roles, provider, build gate |
-| Layer 2 — Backend | PASS / N/A | Services, controllers, build gate, inline tests |
-| Layer 3 — Frontend | PASS / N/A | Pages, i18n, docs, compliance gate, inline tests |
-| Layer 4 — DevData | PASS / N/A / SKIPPED | Optional test data |
-
-| Category | Checks | Status |
-|----------|--------|--------|
-| MCP conventions | validate_conventions | PASS (0 errors) |
-| Build | dotnet build + npm typecheck | PASS |
-| EF Core | migrations, pending changes, SQL Server apply | PASS / N/A |
-| DB tests | Integration tests on SQL Server | PASS / N/A |
-| Frontend | routes, lazy loading, forms as pages, i18n (4 langs + keys) | PASS / N/A |
-| Security | TenantId filter, RequirePermission, no Guid.Empty, no !.Value | PASS / N/A |
-| Seed data | completeness, random GUIDs (Guid.NewGuid()), no ContextId/RoleId constants | PASS / N/A |
-| Code quality | PaginatedResult, EntityLookup (no FK select/input), CSS vars, search param | PASS / N/A |
-| Migration completeness | ModelSnapshot covers ALL DbSet entities (POST-CHECK C38, C42) | PASS / N/A |
-| NavRoute kebab-case | NavRoute + permissions use kebab-case (POST-CHECK C34) | PASS / N/A |
-| DateOnly DTOs | Date fields use DateOnly not string (POST-CHECK C41) | PASS / N/A |
-| I18n registration | Namespaces registered in i18n config (POST-CHECK C39) | PASS / N/A |
-| Validators DI | FluentValidation registered in DI (POST-CHECK C40) | PASS / N/A |
-| Route/NavRoute conflict | No [Route] alongside [NavRoute] on controllers (POST-CHECK C43) | PASS / N/A |
-| Route module segment | Frontend routes include module segment matching seed data (POST-CHECK C52) | PASS / N/A |
-| Role-permission matrix | Admin=wildcard, Manager=CRU, Contributor=CR, Viewer=R (POST-CHECK C44) | PASS / N/A |
-| PermissionAction enum | No Enum.Parse, only typed enum values 0-10 (POST-CHECK C45) | PASS / N/A |
-| Navigation translations | 4 langs per level, section/resource translations present (POST-CHECK C46) | PASS / N/A |
-| Inline tests (Layer 2) | Backend unit + integration tests | PASS / N/A |
-| Inline tests (Layer 3) | Frontend form tests | PASS / N/A |
-| POST-CHECKs | 3 MCP tools + bash checks (security + convention + architecture) | PASS / N/A |
-| Acceptance criteria | AC1..ACn | {X}/{Y} PASS |
-```
+| Layer | Status |
+|-------|--------|
+| Layer 0 — Domain + Infrastructure | PASS / N/A |
+| Layer 1 — Seed Data | PASS / N/A |
+| Layer 2 — Backend | PASS / N/A |
+| Layer 3 — Frontend | PASS / N/A |
+| Layer 4 — DevData | PASS / N/A / SKIPPED |
+
+| Category | Status |
+|----------|--------|
+| MCP conventions | PASS (0 errors) |
+| Build (dotnet + npm) | PASS |
+| EF Core (migrations, SQL Server) | PASS / N/A |
+| Integration tests | PASS / N/A |
+| Frontend routes + i18n | PASS / N/A |
+| Security checks | PASS / N/A |
+| Seed data completeness | PASS / N/A |
+| Code quality | PASS / N/A |
+| NavRoute kebab-case | PASS / N/A |
+| DateOnly DTOs | PASS / N/A |
+| I18n registration | PASS / N/A |
+| FluentValidation DI | PASS / N/A |
+| Route/NavRoute conflict | PASS / N/A |
+| Role-permission matrix | PASS / N/A |
+| Navigation translations (4 langs) | PASS / N/A |
+| Inline tests | PASS / N/A |
+| POST-CHECKs | PASS / N/A |
+| Acceptance criteria | {X}/{Y} PASS |
 
 ---
 
-## 9. Save Output (if save_mode)
+## 8b. Runtime Validation
 
-Write to `{output_dir}/04-examine.md` with validation results.
+For runtime validation (if NOT foundation/economy mode): Run `/validate-feature {EntityName}` (OPTIONAL but RECOMMENDED).
 
 ---
 
-## 10. Route to Next Step — FINAL TEST SWEEP
-
-> **Note:** Backend tests (Layer 2) and frontend tests (Layer 3) have already been scaffolded and run inline.
-> Step-07 "Final Test Sweep" handles: security tests, coverage analysis, cross-layer scenarios, and remaining failures.
+## 9. Route to Next Step
 
 ```
-IF examine_mode (-x flag):
-  → Load steps/step-05-deep-review.md (adversarial review)
-  → Then step-06 (resolve) if findings need fixing
-  → Then step-07 (Final Test Sweep) — ALWAYS
+IF examine_mode: Load step-05 → step-06 → step-07
+ELSE: Load step-07-tests.md
 
-ELSE:
-  → Load steps/step-07-tests.md — IMMEDIATELY after eXamine completes
-```
-
-**RULE:** The APEX workflow is NOT complete until steps 07-08 execute.
-The success criteria require: "Tests: 100% pass, >= 80% coverage" — step-07 verifies coverage and adds security tests.
-
-### eXamine Task Lifecycle — Completion
-```
 TaskUpdate(taskId: examine_task_id, status: "completed")
 ```
 
-**NEXT ACTION:** Load `steps/step-07-tests.md` now.
+**RULE:** APEX requires steps 07-08 (100% tests, >= 80% coverage).
 
----
-
-## 11. PRD Final Reconciliation (delegate mode only)
-
-> **After all validation passes**, ensure the PRD file reflects the completed state.
+## 10. PRD Reconciliation (delegate mode)
 
 ```
-IF delegate_mode:
-  Read {delegate_prd_path}
-
-  For ALL tasks belonging to this module:
-    IF task was executed by apex AND all checks passed:
-      Verify task.status == 'completed'
-    IF task was NOT in scope (different module):
-      Leave unchanged
-
-  Set prd.updated_at = new Date().toISOString()
-
-  If ALL module tasks completed:
-    Set prd.status = 'completed' (if single module)
-    OR leave prd.status = 'in_progress' (if multi-module, other modules remain)
-
-  Write back to {delegate_prd_path}
+For all tasks in module:
+  IF executed AND checks passed: Set task.status = 'completed'
+Set prd.updated_at = now
+If all done: Set prd.status = 'completed' (single) or 'in_progress' (multi)
 ```