@atlashub/smartstack-cli 4.18.0 → 4.20.0

package/templates/agents/docs-context-reader.md

@@ -1,6 +1,6 @@
 ---
 name: docs-context-reader
-description: Reads project documentation (docs/business/**/feature.json, web docs, docs-manifest.json) and produces a structured summary for context injection into skills and agents
+description: Reads project documentation (docs/business/**/index.json, web docs, docs-manifest.json) and produces a structured summary for context injection into skills and agents
 color: green
 tools: Read, Glob, Grep
 model: haiku
@@ -24,10 +24,10 @@ If absent, fall back to directory scanning.
 
 **Business Analysis outputs (v3.0 - JSON format):**
 ```
-Glob: docs/business/**/business-analyse/v*/feature.json
+Glob: docs/business/**/business-analyse/v*/index.json
 ```
 
-For each feature.json found, read the JSON and extract:
+For each index.json found, read the JSON and extract:
 - `id` (FEAT-XXX)
 - `status` (draft/analysed/specified/approved/handed-off)
 - `metadata` (application, module, version, dates)

package/templates/mcp-scaffolding/frontend/nav-routes.ts.hbs

@@ -0,0 +1,133 @@
+{{!-- SmartStack NavRoute Registry Template --}}
+{{!-- Generates centralized route registry for frontend --}}
+
+/**
+ * NavRoute Registry
+ *
+ * Auto-generated by SmartStack MCP - DO NOT EDIT MANUALLY
+ * Generated: {{generatedAt}}
+ * Source: {{source}}
+ * Routes: {{routeCount}}
+ */
+
+export interface NavRoute {
+  /** NavRoute path (e.g., "administration.users") */
+  navRoute: string;
+  /** API endpoint path (e.g., "/api/administration/users") */
+  api: string;
+  /** Frontend route path (e.g., "/administration/users") */
+  web: string;
+  /** Required permissions to access this route */
+  permissions: string[];
+  /** Backend controller name */
+  controller?: string;
+  /** Supported HTTP methods */
+  methods: string[];
+}
+
+/**
+ * All registered NavRoutes
+ */
+export const ROUTES: Record<string, NavRoute> = {
+{{#each routes}}
+  '{{this.navRoute}}': {
+    navRoute: '{{this.navRoute}}',
+    api: '{{this.apiPath}}',
+    web: '{{this.webPath}}',
+    permissions: [{{#each this.permissions}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}],
+{{#if this.controller}}
+    controller: '{{this.controller}}',
+{{/if}}
+    methods: [{{#each this.methods}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}],
+  },
+{{/each}}
+};
+
+/**
+ * Get route configuration by NavRoute path
+ * @throws Error if route not found
+ */
+export function getRoute(navRoute: string): NavRoute {
+  const route = ROUTES[navRoute];
+  if (!route) {
+    throw new Error(`Route not found: ${navRoute}. Run scaffold_routes to regenerate.`);
+  }
+  return route;
+}
+
+/**
+ * Safely get route configuration, returns undefined if not found
+ */
+export function tryGetRoute(navRoute: string): NavRoute | undefined {
+  return ROUTES[navRoute];
+}
+
+/**
+ * Check if user has permission for route
+ */
+export function hasRoutePermission(navRoute: string, userPermissions: string[]): boolean {
+  const route = ROUTES[navRoute];
+  if (!route || route.permissions.length === 0) return true;
+  return route.permissions.some(p => userPermissions.includes(p));
+}
+
+/**
+ * Get all routes for an application (e.g., "administration")
+ */
+export function getRoutesByApplication(application: string): NavRoute[] {
+  return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${application}.`));
+}
+
+/**
+ * Get all routes for an application and module (e.g., "administration.users")
+ */
+export function getRoutesByModule(application: string, module: string): NavRoute[] {
+  const prefix = `${application}.${module}`;
+  return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${prefix}.`) || r.navRoute === prefix);
+}
+
+/**
+ * Get all unique applications
+ */
+export function getApplications(): string[] {
+  const applications = new Set<string>();
+  for (const route of Object.values(ROUTES)) {
+    applications.add(route.navRoute.split('.')[0]);
+  }
+  return Array.from(applications);
+}
+
+/**
+ * Get all unique modules within an application
+ */
+export function getModules(application: string): string[] {
+  const modules = new Set<string>();
+  for (const route of Object.values(ROUTES)) {
+    const parts = route.navRoute.split('.');
+    if (parts[0] === application && parts.length >= 2) {
+      modules.add(parts[1]);
+    }
+  }
+  return Array.from(modules);
+}
+
+/**
+ * Build API URL from NavRoute with optional path segments
+ */
+export function buildApiUrl(navRoute: string, ...segments: string[]): string {
+  const route = getRoute(navRoute);
+  if (segments.length === 0) return route.api;
+  return `${route.api}/${segments.join('/')}`;
+}
+
+/**
+ * Build frontend URL from NavRoute with optional path segments
+ */
+export function buildWebUrl(navRoute: string, ...segments: string[]): string {
+  const route = getRoute(navRoute);
+  if (segments.length === 0) return route.web;
+  return `${route.web}/${segments.join('/')}`;
+}
+
+// Route count for debugging
+export const ROUTE_COUNT = {{routeCount}};

package/templates/mcp-scaffolding/frontend/routes.tsx.hbs

@@ -0,0 +1,126 @@
+{{!-- SmartStack React Router Configuration Template --}}
+{{!-- Generates router configuration from NavRoute registry --}}
+
+/**
+ * React Router Configuration
+ *
+ * Auto-generated by SmartStack MCP - DO NOT EDIT MANUALLY
+ * Generated: {{generatedAt}}
+ */
+
+import React, { Suspense, lazy } from 'react';
+import { createBrowserRouter, RouteObject, Navigate } from 'react-router-dom';
+import { ROUTES } from './navRoutes.generated';
+{{#if includeGuards}}
+import { ProtectedRoute, PermissionGuard } from './guards';
+{{/if}}
+
+// ============================================================================
+// Layouts
+// ============================================================================
+
+{{#each applications}}
+import { {{capitalize this}}Layout } from '../layouts/{{capitalize this}}Layout';
+{{/each}}
+
+// ============================================================================
+// Pages (lazy loaded for code splitting)
+// ============================================================================
+
+{{#each routes}}
+const {{pageName this.navRoute}}Page = lazy(() => import('../pages/{{pagePath this.navRoute}}'));
+{{/each}}
+
+// ============================================================================
+// Loading Component
+// ============================================================================
+
+const PageLoader: React.FC = () => (
+  <div className="flex items-center justify-center h-64">
+    <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-500" />
+  </div>
+);
+
+// ============================================================================
+// Route Configuration
+// ============================================================================
+
+const routes: RouteObject[] = [
+  // Root redirect
+  {
+    path: '/',
+    element: <Navigate to="{{defaultPath}}" replace />,
+  },
+
+{{#each applicationTree}}
+  // {{uppercase @key}} Application
+  {
+    path: '{{@key}}',
+    element: <{{capitalize @key}}Layout />,
+    children: [
+{{#each this}}
+      {
+        path: '{{modulePath this.navRoute}}',
+{{#if this.permissions.length}}
+        element: (
+          <PermissionGuard permissions={ROUTES['{{this.navRoute}}'].permissions}>
+            <Suspense fallback={<PageLoader />}>
+              <{{pageName this.navRoute}}Page />
+            </Suspense>
+          </PermissionGuard>
+        ),
+{{else}}
+        element: (
+          <Suspense fallback={<PageLoader />}>
+            <{{pageName this.navRoute}}Page />
+          </Suspense>
+        ),
+{{/if}}
+      },
+{{/each}}
+    ],
+  },
+{{/each}}
+
+  // 404 Not Found
+  {
+    path: '*',
+    element: (
+      <div className="flex flex-col items-center justify-center h-screen">
+        <h1 className="text-4xl font-bold text-gray-900">404</h1>
+        <p className="mt-2 text-gray-600">Page not found</p>
+        <a href="{{defaultPath}}" className="mt-4 text-blue-600 hover:underline">
+          Return to home
+        </a>
+      </div>
+    ),
+  },
+];
+
+// ============================================================================
+// Router Export
+// ============================================================================
+
+{{#if includeGuards}}
+export const router = createBrowserRouter([
+  {
+    element: <ProtectedRoute />,
+    children: routes,
+  },
+]);
+{{else}}
+export const router = createBrowserRouter(routes);
+{{/if}}
+
+export default router;
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type { RouteObject };
+
+/**
+ * Get route configuration by NavRoute path
+ */
+export const getRouteConfig = (navRoute: string) => ROUTES[navRoute];

package/templates/skills/apex/SKILL.md

@@ -59,7 +59,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{foundation_mode}` | boolean | Foundation mode: entities-only (no services/controllers/frontend). Used by ralph-loop Phase 0. |
 | `{app_name}` | string | Application name |
 | `{module_code}` | string | Module code |
-| `{sections}` | object[] | Sections (MANDATORY, min 1) with code/labels/icon/displayOrder |
+| `{sections}` | object[] | Sections (required, 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" |
@@ -73,6 +73,17 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{needs_notification}` | boolean | Notification integration required |
 </state_variables>
 
+<state_persistence>
+
+**These variables exist only in the conversation context.** There is no file-based persistence between sessions.
+
+- Variables are set in step-00 (init) and propagated through subsequent steps via conversation context
+- If the conversation is interrupted, use `-r` (resume) — the model will re-derive state from existing files and git history
+- The `save_mode` (`-s`) flag writes step outputs to `.claude/output/apex/` but this is documentation, not resumable state
+- Delegate mode (`-d`) reads initial state from the PRD file, making it more resilient to interruptions
+
+</state_persistence>
+
 <entry_point>
 
 **FIRST ACTION:** Load `steps/step-00-init.md`
@@ -84,11 +95,11 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | Step | File | Model | Purpose |
 |------|------|-------|---------|
-| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect application, verify MCP, define hierarchy (4 levels), challenge need |
-| 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
+| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect application, verify MCP, define hierarchy (4 levels), scope validation |
+| 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (parallel Agent tool or sequential) |
 | 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-examine.md` | Opus | eXamine: MCP validation, build, 44 POST-CHECKs, acceptance criteria |
+| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 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 | Final Test Sweep: security tests, coverage, remaining failures |
@@ -98,13 +109,13 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 <apex_phases>
 **APEX = Analyze → Plan → Execute → eXamine**
 
-| Phase | Step | Obligatory | Description |
-|-------|------|------------|-------------|
-| *Init* | 00 | Yes | Setup, hierarchy, challenge the need, **scope guard** (skipped in `-d` delegate mode) |
+| Phase | Step | Required | Description |
+|-------|------|----------|-------------|
+| *Init* | 00 | Yes | Setup, hierarchy, scope validation, **scope guard** (skipped in `-d` delegate mode) |
 | **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 (5 layers: domain, seed, backend, frontend, devdata) |
-| **X** — eXamine | 04 | Yes | 3 MCP tools + 50 POST-CHECKs (6 security + 44 convention), build, acceptance criteria |
+| **X** — eXamine | 04 | Yes | 3 MCP tools + POST-CHECKs (security + convention + architecture, see post-checks.md), build, acceptance criteria |
 | *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
 | *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
 | *Final Test Sweep* | 07-08 | **Yes** | Security tests, coverage sweep, remaining failures |
@@ -115,14 +126,15 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | File | Purpose | Loaded by | Stays in context for |
 |------|---------|-----------|---------------------|
-| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01 | step-03 (do NOT re-read) |
-| `references/smartstack-layers.md` | Layer rules, skill/MCP mapping, planning templates, delegate fast path | step-02 | step-03 (do NOT re-read) |
-| `references/smartstack-frontend.md` | Frontend patterns, EntityLookup, i18n, compliance gates (sections 1-9) | step-03 | step-04 |
+| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01 | step-03 L0-L2 (released after L2) |
+| `references/smartstack-layers.md` | Layer rules, skill/MCP mapping, planning templates, delegate fast path | step-02 | step-03 L0-L2 (released after L2) |
+| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 Layer 1 | released after Layer 1 |
+| `references/smartstack-frontend.md` | Frontend patterns, EntityLookup, i18n (sections 1-6) | step-03 Layer 3 (deferred) | step-04 |
+| `references/smartstack-frontend-compliance.md` | Documentation, form testing, compliance gates (sections 7-9) | step-03 Layer 3 (deferred) | step-04 |
 | `references/challenge-questions.md` | Hierarchy rules, challenge questions, delegate mode skip | step-00 | — |
-| `references/core-seed-data.md` | Comprehensive seed data templates (navigation, permissions, roles) | step-03 (ALWAYS for Layer 1) | — |
 | `references/error-classification.md` | Build error diagnosis categories A-F | step-03 (build failure), step-04 | — |
-| `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 (if NOT economy_mode) | — |
-| `references/post-checks.md` | 6 security + 44 convention bash checks (MCP tools run first) | step-04 | — |
+| `references/parallel-execution.md` | Agent tool launch patterns, task coordination, decision matrix | step-01, step-03 (if NOT economy_mode) | — |
+| `references/post-checks.md` | Security + convention + architecture bash checks (MCP tools run first) | step-04 | — |
 
 **Context propagation rule:** Files loaded in step N remain in conversation context for step N+1. Steps mark "do NOT re-read" to avoid duplicate reads.
 </reference_files>
@@ -134,8 +146,9 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - **MCP-first** - Use MCP scaffold/validate tools before manual approaches
 - **Verify MCP at startup** - step-00 checks MCP availability
 - **Layer order** - Layer 0 (domain+infra+migration) → Layer 1 (seed data) → Layer 2 (backend+tests) → Layer 3 (frontend+tests) → Layer 4 (devdata)
-- **Agent Teams** - Parallel execution for scan (step-01) and within Layer 2/3 (step-03) for multi-entity, unless economy_mode
+- **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.
 - **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`.
@@ -171,6 +184,6 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - Build: dotnet build PASS + npm run typecheck PASS (if frontend)
 - Seed data complete as dedicated Layer 1 (navigation, permissions, roles, provider) — impossible to skip
 - Tests inline: backend tests after Layer 2, frontend tests after Layer 3
-- Final test sweep: security tests + coverage >= 80% + 100% pass rate
+- Final test sweep: security tests + coverage >= 80% + target 100% pass rate (acceptable fallback: skip with TODO after max retries)
 - Commits atomic per layer
 </success_criteria>

package/templates/skills/apex/_shared.md

@@ -52,7 +52,7 @@ Write back to {delegate_prd_path}
 
 ## MCP Tools Reference
 
-### Mandatory (every execution)
+### Required (every execution)
 
 | Tool | Purpose | Step |
 |------|---------|------|
@@ -74,14 +74,14 @@ Write back to {delegate_prd_path}
 - Section: `human-resources.employees.departments.read` (3+1)
 - Resource: `human-resources.employees.departments.export.execute` (4+1)
 
-> **CRITICAL — Permission codes use the SAME kebab-case segments as NavRoute codes.**
+> Permission codes use the SAME kebab-case segments as NavRoute codes.
 > Every dot-separated segment in a permission path is a navigation entity code.
-> Multi-word codes MUST be kebab-case: `human-resources`, NOT `humanresources`.
+> Multi-word codes must use kebab-case: `human-resources`, NOT `humanresources`.
 >
 > SmartStack.app reference: `support-client.my-tickets.read`, `administration.email-templates.read`
 >
-> **FORBIDDEN:** `humanresources.employees.read` (concatenated — no kebab-case)
-> **CORRECT:** `human-resources.employees.read` (kebab-case — matches NavRoute)
+> Do not use: `humanresources.employees.read` (concatenated — no kebab-case)
+> Correct: `human-resources.employees.read` (kebab-case — matches NavRoute)
 
 ### Generation (step-03)
 
@@ -93,7 +93,7 @@ Write back to {delegate_prd_path}
 | `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
 | `scaffold_routes` | Generate React Router routes | Frontend changes |
 
-### eXamine (step-04) — 43 POST-CHECKs
+### eXamine (step-04) — POST-CHECKs (see post-checks.md)
 
 | Tool | Purpose | Condition |
 |------|---------|-----------|
@@ -101,10 +101,10 @@ Write back to {delegate_prd_path}
 | `validate_frontend_routes` | Validate route/layout alignment | Frontend changes |
 | `validate_security` | Check security patterns | API changes |
 
-**Key BLOCKING POST-CHECKs (most common failures):**
-- **#8:** Forms must be full pages — ZERO modals/dialogs
+**Key POST-CHECKs (most common failures):**
+- **#8:** Forms must be full pages — no modals/dialogs
 - **#13:** No hardcoded Tailwind colors — use CSS variables only
-- **#6+27:** i18n in separate `locales/{lang}/{module}.json` — NEVER embedded in .ts
+- **#6+27:** i18n in separate `locales/{lang}/{module}.json` — not embedded in .ts
 - **#10:** Form pages must have `.test.tsx` companion files
 - **#28:** Pages must use `useTranslation` — no hardcoded strings
 
@@ -132,6 +132,59 @@ Write back to {delegate_prd_path}
 
 ---
 
+## Severity Labels
+
+| Label | Meaning | When to use |
+|-------|---------|-------------|
+| **BLOCKING** | Build fails or security vulnerability. Cannot proceed. | `dotnet build` / `npm typecheck` failure, OWASP violation, tenant isolation bypass |
+| **CRITICAL** | Functionally broken at runtime but compiles. | Missing DI registration, wrong route, empty translations at runtime |
+| **WARNING** | Suboptimal but works. Should fix before merge. | Missing tests, non-canonical naming, cosmetic issues |
+| **INFO** | Suggestion or best practice. Non-blocking. | Performance tips, alternative patterns |
+
+> **Rule:** Only use BLOCKING for issues that prevent compilation or create security vulnerabilities.
+> CRITICAL is for runtime failures. Everything else is WARNING or INFO.
+
+---
+
+## MCP Degraded Mode
+
+> When MCP is unavailable, fall back to manual patterns from reference files.
+
+| MCP Tool | Fallback |
+|----------|----------|
+| `validate_conventions` | Manual review against `smartstack-api.md` patterns |
+| `scaffold_extension` | Create files manually following `smartstack-api.md` entity/service/controller patterns |
+| `suggest_migration` | Name format: `{context}_v{version}_{sequence}_{Description}` (see existing migrations for version) |
+| `generate_permissions` | Write `HasData()` code manually following `core-seed-data.md` permission section |
+| `scaffold_routes` | Create `applicationRoutes` array manually following `smartstack-frontend.md` §1 |
+| `validate_frontend_routes` | Run POST-CHECK bash scripts from `post-checks.md` |
+| `validate_security` | Run security POST-CHECKs S1-S6 from `post-checks.md` |
+| `check_migrations` | Run `dotnet ef migrations has-pending-model-changes` manually |
+| `scaffold_tests` | Create test files manually following `smartstack-frontend-compliance.md` §8 patterns |
+
+---
+
+## Context Bridge for Skill Delegation
+
+> When delegating to `/controller`, `/ui-components`, `/application`, etc., pass this context block to ensure the skill has enough information.
+
+```
+Context for {skill_name}:
+- Application: {app_name}
+- Module: {module_code}
+- NavRoute: {navRoute} (e.g., "human-resources.employees")
+- Entity: {entity_name} with properties: {key_properties}
+- Tenant mode: {strict|optional|scoped|none}
+- CSS: Use CSS variables ONLY (see smartstack-frontend.md §4)
+- I18n: 4 languages (fr, en, it, de), namespace: {module-kebab}
+- Forms: Full pages with own routes, ZERO modals/drawers
+- FK fields: Use EntityLookup component (see smartstack-frontend.md §6)
+```
+
+> Adjust the template based on the skill: backend skills don't need CSS/i18n context, frontend skills don't need tenant mode details.
+
+---
+
 ## Existing Skills Delegation
 
 | Skill | When to delegate |

package/templates/skills/apex/references/analysis-methods.md

@@ -12,7 +12,7 @@ For each entity found (or to be created), identify FK relationships:
 - Record: `{ entity, fkProperty, targetEntity, isRequired }`
 
 **Why:** FK fields drive two critical requirements:
-1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>`)
+1. **Frontend:** Each FK field MUST use `<EntityLookup />` (not `<input>`, not `<select>`)
 2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
 
 See `references/smartstack-frontend.md` section 6 for EntityLookup patterns.
@@ -28,7 +28,7 @@ For each entity found (or to be created), determine the `tenantMode`:
 | `strict` | Data belongs to one tenant | Employee, Order, Invoice | `TenantId == current` |
 | `optional` | Can be shared or tenant-specific | Department, Currency, JobTitle | `TenantId == current OR TenantId == null` |
 | `scoped` | Explicit scope rules | Settings, Workflow, EmailTemplate | `TenantId == current AND Scope == current` |
-| `none` | Platform-wide (never filtered) | Navigation, Permission, User | No TenantId |
+| `none` | Shared across all tenants (not filtered) | Navigation, Permission, User | No TenantId |
 
 **Why:** Tenant mode drives EF query filters, seed data generation, and API access control.
 
@@ -41,7 +41,7 @@ For each entity found (or to be created), determine the `tenantMode`:
 For each entity found (or to be created), identify code generation needs using the following **priority order**:
 
 ```
-PRIORITY 1 — User choice from challenge questions (step-00):
+PRIORITY 1 — User choice from scope validation (step-00):
   IF {code_patterns} is set (from step-00 section 5c):
     → Use {code_patterns} for each entity
     → This is the user's explicit choice — always takes precedence
@@ -51,7 +51,7 @@ PRIORITY 2 — feature.json (from /business-analyse):
     → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
     → Record in analysis: entity has auto-generated code
 
-PRIORITY 3 — Heuristic fallback (delegate mode ONLY):
+PRIORITY 3 — Heuristic fallback (delegate mode only):
   IF delegate_mode AND no code pattern from Priority 1 or 2:
     → Apply heuristic default based on entity name:
       Invoice/Order/Receipt/PurchaseOrder → timestamp-daily
@@ -59,7 +59,7 @@ PRIORITY 3 — Heuristic fallback (delegate mode ONLY):
       Contract/Policy/Agreement → year-sequential
       Category/Status/Type (reference data) → uuid-short
       Employee/Customer/Project → sequential
-    → WARNING: heuristic applied — PRD was incomplete
+    → Note: heuristic applied — PRD was incomplete
 
 FALLBACK — Manual (safest default):
   IF none of the above apply:
@@ -67,12 +67,14 @@ FALLBACK — Manual (safest default):
     → No auto-generation, no ICodeGenerator injection
 ```
 
-**IMPORTANT:** In interactive mode (no `-d` flag), heuristics are NEVER applied silently. The user is always asked via challenge questions (step-00 section 5c). Heuristics only serve as fallback in delegate mode when the PRD is incomplete.
+**Important:** In interactive mode (no `-d` flag), heuristics are never applied silently. The user is always asked via scope validation (step-00 section 5c). Heuristics only serve as fallback in delegate mode when the PRD is incomplete.
 
 **Why:** Code generation strategy drives CreateDto structure, service injection (ICodeGenerator<T>), and DI registration.
 
 **Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
 
+
+
 ---
 
 ## Gap Analysis

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

@@ -2,11 +2,11 @@
 
 > **Referenced by:** step-00-init.md
 > Question templates for context detection, hierarchy validation, and need challenging.
-> Previously split across `challenge-questions.md` and `initialization-challenge-flow.md` — now consolidated here.
+> Consolidates all challenge questions and hierarchy validation in a single file.
 
 ---
 
-## 4-Level Navigation Hierarchy (BLOCKING RULE)
+## 4-Level Navigation Hierarchy (MANDATORY)
 
 SmartStack uses a **4-level navigation hierarchy:**
 - **Level 1: Application** — e.g., "HumanResources", "ProjectManagement"
@@ -14,7 +14,7 @@ SmartStack uses a **4-level navigation hierarchy:**
 - **Level 3: Section** — e.g., "List", "Dashboard", "Approval"
 - **Level 4: Resource** — e.g., "Export", "Settings" (optional)
 
-**BLOCKING RULE:** Every module MUST have at least one section. A module without sections produces an incomplete navigation tree, broken seed data, and missing frontend routes.
+Every module MUST have at least one section. A module without sections produces an incomplete navigation tree, broken seed data, and missing frontend routes.
 
 ---
 
@@ -61,7 +61,7 @@ questions:
 
 ## 4c. Section Selection
 
-> **BLOCKING:** This question MUST be asked. `{sections}` MUST contain at least one entry before proceeding.
+> 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)
@@ -82,7 +82,7 @@ questions:
     multiSelect: true
 ```
 
-**Validation (BLOCKING):**
+**Validation:**
 ```
 IF {sections}.length == 0:
   DISPLAY: "Every module must have at least one section. Please select or define at least one."