@atlashub/smartstack-cli 3.39.0 → 3.41.0

package/templates/skills/apex/references/execution-layer1-rules.md

@@ -1,96 +1,96 @@
-# Layer 1: Execution Rules — Application + API + Seed Data
-
-> **Loaded by:** step-03-execute.md (section: Layer 1)
-> **Purpose:** Critical rules for Layer 1 execution — NavRoute, permissions, validators, code generation, frontend patterns.
-
----
-
-## NavRoute and Permission Kebab-Case (CRITICAL)
-
-**ALL NavRoute segments and permission codes MUST use kebab-case for multi-word identifiers.**
-
-Root cause (test-apex-007): Controllers had `[NavRoute("humanresources.employees")]` instead of `[NavRoute("human-resources.employees")]`. This mismatched seed data routes and permission codes, causing 404s and permission denials at runtime.
-
-**Rules:**
-- NavRoute: `human-resources.employees` (NEVER `humanresources.employees`)
-- Permissions: `human-resources.employees.read` (segments MATCH NavRoute exactly)
-- Seed data codes: `human-resources` (NEVER `humanresources`)
-- C# class names stay PascalCase (`HumanResourcesController`) — only route/permission strings use kebab-case
-- POST-CHECKs 41 + 48 validate this. Fix BEFORE committing.
-
----
-
-## Controller Route Attribute (BLOCKING)
-
-**Controllers with `[NavRoute]` must NOT have `[Route]` attribute.**
-
-Root cause (test-apex-007): ALL 7 controllers had BOTH `[Route("api/...")]` AND `[NavRoute("...")]`. In SmartStack, `[NavRoute]` resolves routes dynamically from Navigation entities in the database at startup. Having `[Route]` alongside causes route conflicts → all endpoints return 404.
-
-**Rules:**
-- `[NavRoute("app.module")]` is the ONLY route attribute needed on controllers
-- **FORBIDDEN:** `[Route("api/human-resources/employees")]` alongside `[NavRoute]`
-- **FORBIDDEN:** `[Route("api/[controller]")]` alongside `[NavRoute]`
-- If generating via MCP `scaffold_extension` with `navRoute` option → output is correct (NavRoute only)
-- If generating via `/controller` skill → verify NO `[Route]` is added
-- POST-CHECK 50 validates this. Fix BEFORE committing.
-
----
-
-## Validators DI Registration (CRITICAL)
-
-After creating validators, they MUST be registered in DI. Without registration, `[FromBody]` DTOs are never validated.
-
-```csharp
-In DependencyInjection.cs (or ServiceCollectionExtensions.cs):
-  services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();
-```
-
-POST-CHECK 46 validates this. If validators exist but no DI registration → BLOCKING.
-
----
-
-## Date Fields — Use DateOnly (CRITICAL)
-
-**ALL date-only fields in DTOs MUST use `DateOnly`, NEVER `string`.**
-
-Root cause (test-apex-007): WorkLog DTO had `string Date` instead of `DateOnly Date`. This causes: no date validation, inconsistent date formats, parsing errors.
-
-**Type mapping for DTOs:**
-
-| Domain type | DTO type | Example |
-|-------------|----------|---------|
-| `DateTime` | `DateTime` | `CreatedAt`, `UpdatedAt` |
-| Date-only field | `DateOnly` | `Date`, `StartDate`, `EndDate`, `BirthDate` |
-| `string` for date | **FORBIDDEN** | Never use `string` for dates |
-| `DateTime` for date-only | **Avoid** | Use `DateOnly` when no time component needed |
-
-POST-CHECK 47 validates this. If a DTO has `string` type for a property named `*Date*` → BLOCKING.
-
----
-
-## Code Generation (if entities have codePattern != "manual")
-
-For each entity with auto-generated code pattern (from feature.json or step-02 decisions):
-
-```
-1. Create CodePatternConfig for the entity (strategy, prefix, digits from codePattern)
-2. Register ICodeGenerator<TEntity> in DependencyInjection.cs (Infrastructure layer)
-   → See references/code-generation.md for DI registration pattern
-3. Update CreateDto: REMOVE Code property (auto-generated, not user-provided)
-4. Update CreateDtoValidator: REMOVE Code regex rule (not in DTO anymore)
-5. Update service CreateAsync: inject ICodeGenerator<TEntity>, call NextCodeAsync()
-   → Code is auto-generated BEFORE entity creation
-   → See references/code-generation.md for service integration pattern
-6. Keep Code in ResponseDto (returned to frontend after creation)
-7. Keep Code in UpdateDto ONLY if code is mutable (rare — discuss with user)
-```
-
-**CRITICAL:** If `codePattern.strategy == "manual"` (or no codePattern), keep the current behavior: Code stays in CreateDto, user provides it, validator has regex rule.
-
----
-
-## Sequential vs Parallel Execution
-
-**If economy_mode:** Execute each item from the plan sequentially using skills and MCP.
-
-**If NOT economy_mode:** See `references/agent-teams-protocol.md` for parallel team-based execution with exec-backend and exec-frontend teammates.
+# Layer 1: Execution Rules — Application + API + Seed Data
+
+> **Loaded by:** step-03-execute.md (section: Layer 1)
+> **Purpose:** Critical rules for Layer 1 execution — NavRoute, permissions, validators, code generation, frontend patterns.
+
+---
+
+## NavRoute and Permission Kebab-Case (CRITICAL)
+
+**ALL NavRoute segments and permission codes MUST use kebab-case for multi-word identifiers.**
+
+Root cause (test-apex-007): Controllers had `[NavRoute("humanresources.employees")]` instead of `[NavRoute("human-resources.employees")]`. This mismatched seed data routes and permission codes, causing 404s and permission denials at runtime.
+
+**Rules:**
+- NavRoute: `human-resources.employees` (NEVER `humanresources.employees`)
+- Permissions: `human-resources.employees.read` (segments MATCH NavRoute exactly)
+- Seed data codes: `human-resources` (NEVER `humanresources`)
+- C# class names stay PascalCase (`HumanResourcesController`) — only route/permission strings use kebab-case
+- POST-CHECKs 41 + 48 validate this. Fix BEFORE committing.
+
+---
+
+## Controller Route Attribute (BLOCKING)
+
+**Controllers with `[NavRoute]` must NOT have `[Route]` attribute.**
+
+Root cause (test-apex-007): ALL 7 controllers had BOTH `[Route("api/...")]` AND `[NavRoute("...")]`. In SmartStack, `[NavRoute]` resolves routes dynamically from Navigation entities in the database at startup. Having `[Route]` alongside causes route conflicts → all endpoints return 404.
+
+**Rules:**
+- `[NavRoute("app.module")]` is the ONLY route attribute needed on controllers
+- **FORBIDDEN:** `[Route("api/human-resources/employees")]` alongside `[NavRoute]`
+- **FORBIDDEN:** `[Route("api/[controller]")]` alongside `[NavRoute]`
+- If generating via MCP `scaffold_extension` with `navRoute` option → output is correct (NavRoute only)
+- If generating via `/controller` skill → verify NO `[Route]` is added
+- POST-CHECK 50 validates this. Fix BEFORE committing.
+
+---
+
+## Validators DI Registration (CRITICAL)
+
+After creating validators, they MUST be registered in DI. Without registration, `[FromBody]` DTOs are never validated.
+
+```csharp
+In DependencyInjection.cs (or ServiceCollectionExtensions.cs):
+  services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();
+```
+
+POST-CHECK 46 validates this. If validators exist but no DI registration → BLOCKING.
+
+---
+
+## Date Fields — Use DateOnly (CRITICAL)
+
+**ALL date-only fields in DTOs MUST use `DateOnly`, NEVER `string`.**
+
+Root cause (test-apex-007): WorkLog DTO had `string Date` instead of `DateOnly Date`. This causes: no date validation, inconsistent date formats, parsing errors.
+
+**Type mapping for DTOs:**
+
+| Domain type | DTO type | Example |
+|-------------|----------|---------|
+| `DateTime` | `DateTime` | `CreatedAt`, `UpdatedAt` |
+| Date-only field | `DateOnly` | `Date`, `StartDate`, `EndDate`, `BirthDate` |
+| `string` for date | **FORBIDDEN** | Never use `string` for dates |
+| `DateTime` for date-only | **Avoid** | Use `DateOnly` when no time component needed |
+
+POST-CHECK 47 validates this. If a DTO has `string` type for a property named `*Date*` → BLOCKING.
+
+---
+
+## Code Generation (if entities have codePattern != "manual")
+
+For each entity with auto-generated code pattern (from feature.json or step-02 decisions):
+
+```
+1. Create CodePatternConfig for the entity (strategy, prefix, digits from codePattern)
+2. Register ICodeGenerator<TEntity> in DependencyInjection.cs (Infrastructure layer)
+   → See references/code-generation.md for DI registration pattern
+3. Update CreateDto: REMOVE Code property (auto-generated, not user-provided)
+4. Update CreateDtoValidator: REMOVE Code regex rule (not in DTO anymore)
+5. Update service CreateAsync: inject ICodeGenerator<TEntity>, call NextCodeAsync()
+   → Code is auto-generated BEFORE entity creation
+   → See references/code-generation.md for service integration pattern
+6. Keep Code in ResponseDto (returned to frontend after creation)
+7. Keep Code in UpdateDto ONLY if code is mutable (rare — discuss with user)
+```
+
+**CRITICAL:** If `codePattern.strategy == "manual"` (or no codePattern), keep the current behavior: Code stays in CreateDto, user provides it, validator has regex rule.
+
+---
+
+## Sequential vs Parallel Execution
+
+**If economy_mode:** Execute each item from the plan sequentially using skills and MCP.
+
+**If NOT economy_mode:** See `references/agent-teams-protocol.md` for parallel team-based execution with exec-backend and exec-frontend teammates.

package/templates/skills/apex/references/initialization-challenge-flow.md

@@ -1,110 +1,110 @@
-# Initialization — Challenge Flow & Hierarchy Definition
-
-> **Loaded by:** step-00-init.md (sections 4-5)
-> **Purpose:** Detailed flow for challenging user hierarchy assumptions and defining the 4-level navigation structure.
-
----
-
-## Challenge Questions Reference
-
-> **Complete question templates with validation:**
-> Load `references/challenge-questions.md` for the actual YAML question blocks and validation logic.
-
----
-
-## 4-Level Navigation Hierarchy (BLOCKING RULE)
-
-SmartStack uses a **4-level navigation hierarchy:**
-- **Level 1: Application** — e.g., "HumanResources", "ProjectManagement"
-- **Level 2: Module** — e.g., "Employees", "Timesheet"
-- **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.
-
----
-
-## Step 4: Validate Application Level (4a)
-
-Load application question from `references/challenge-questions.md` section 4a.
-
-**If `{app_name}` was clearly inferred from the task description:**
-- Skip question, use inferred value
-
-**If unclear:**
-- Present question with best guess as recommended option
-- Options:
-  1. "Inferred app name (Recommended)" + description
-  2. "New application" + option to create
-  3. "Existing application" + option to select from scanned projects
-- 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
-
----
-
-## Step 4b: Validate Module Level
-
-Load module question from `references/challenge-questions.md` section 4b.
-
-**If `{module_code}` was clearly inferred:**
-- Skip question
-
-**If unclear:**
-- Present question with best guess(es) as options
-- Options:
-  1. "Inferred module code (Recommended)" + from task description
-  2. "Alternative suggestions" + based on keywords
-- User selects or enters custom value
-- Store as `{module_code}` (kebab-case)
-
----
-
-## Step 4c: Define Sections (MANDATORY — at least one)
-
-Load section questions from `references/challenge-questions.md` section 4c.
-
-**BLOCKING VALIDATION:** Sections list 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"
-
-**Question format:**
-```yaml
-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."
-  → 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
-```
-
----
-
-## Delegate Mode Skip (if -d)
-
-When `/ralph-loop` invokes `/apex -d {prd_path}`, ALL hierarchy is extracted from the PRD file:
-- Skip sections 2-4 (no interactive questions)
-- Jump directly to section 3 (MCP verify)
+# Initialization — Challenge Flow & Hierarchy Definition
+
+> **Loaded by:** step-00-init.md (sections 4-5)
+> **Purpose:** Detailed flow for challenging user hierarchy assumptions and defining the 4-level navigation structure.
+
+---
+
+## Challenge Questions Reference
+
+> **Complete question templates with validation:**
+> Load `references/challenge-questions.md` for the actual YAML question blocks and validation logic.
+
+---
+
+## 4-Level Navigation Hierarchy (BLOCKING RULE)
+
+SmartStack uses a **4-level navigation hierarchy:**
+- **Level 1: Application** — e.g., "HumanResources", "ProjectManagement"
+- **Level 2: Module** — e.g., "Employees", "Timesheet"
+- **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.
+
+---
+
+## Step 4: Validate Application Level (4a)
+
+Load application question from `references/challenge-questions.md` section 4a.
+
+**If `{app_name}` was clearly inferred from the task description:**
+- Skip question, use inferred value
+
+**If unclear:**
+- Present question with best guess as recommended option
+- Options:
+  1. "Inferred app name (Recommended)" + description
+  2. "New application" + option to create
+  3. "Existing application" + option to select from scanned projects
+- 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
+
+---
+
+## Step 4b: Validate Module Level
+
+Load module question from `references/challenge-questions.md` section 4b.
+
+**If `{module_code}` was clearly inferred:**
+- Skip question
+
+**If unclear:**
+- Present question with best guess(es) as options
+- Options:
+  1. "Inferred module code (Recommended)" + from task description
+  2. "Alternative suggestions" + based on keywords
+- User selects or enters custom value
+- Store as `{module_code}` (kebab-case)
+
+---
+
+## Step 4c: Define Sections (MANDATORY — at least one)
+
+Load section questions from `references/challenge-questions.md` section 4c.
+
+**BLOCKING VALIDATION:** Sections list 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"
+
+**Question format:**
+```yaml
+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."
+  → 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
+```
+
+---
+
+## Delegate Mode Skip (if -d)
+
+When `/ralph-loop` invokes `/apex -d {prd_path}`, ALL hierarchy is extracted from the PRD file:
+- Skip sections 2-4 (no interactive questions)
+- Jump directly to section 3 (MCP verify)