@atlashub/smartstack-cli 4.48.0 → 4.49.0

package/.documentation/testing-ba-e2e.md

@@ -2,7 +2,7 @@
 
 ## Vue d'ensemble
 
-Infrastructure de tests E2E pour valider le pipeline complet **Business Analyse → Handoff → PRD extraction → Ralph Loop**.
+Infrastructure de tests E2E pour valider le pipeline complet **Business Analyse → Handoff → PRD extraction → `/business-analyse-develop`**.
 
 **Garanties :**
 - ✅ Validation déterministe du handoff
@@ -25,11 +25,15 @@ tests/ba/
 │       ├── Products/
 │       └── Orders/
 │
-└── e2e/                          # Test suites E2E
+├── chain-integrity.test.ts              # Intégrité chaîne BA → Handoff → PRD (55 tests)
+│
+└── e2e/                                 # Test suites E2E
     ├── handoff-validation.test.ts       # Validation handoff section
     ├── prd-extraction-simple.test.ts    # Extraction module simple
     ├── prd-extraction-medium.test.ts    # Extraction module lifecycle
-    └── full-pipeline.test.ts            # Pipeline complet BA → Ralph Loop
+    ├── full-pipeline.test.ts            # Pipeline complet BA → PRD → develop
+    ├── task-generation.test.ts          # Génération de tâches depuis PRD
+    └── unified-prd.test.ts             # Extraction PRD unifié (dual-mode v2/v3)
 ```
 
 ---
@@ -140,7 +144,7 @@ tests/ba/
 
 ### 4. full-pipeline.test.ts
 
-**Objectif:** Tester pipeline complet BA → Ralph Loop.
+**Objectif:** Tester pipeline complet BA → Handoff → PRD → `/business-analyse-develop`.
 
 **Scénarios:**
 
@@ -148,10 +152,10 @@ tests/ba/
 1. Load feature.json (status = "handed-off")
 2. Validate handoff section complet
 3. Extract prd.json déterministe
-4. Write prd.json to .ralph/
+4. Write prd.json to .prd/
 5. Read back prd.json (verify integrity)
-6. Verify all required sections for Ralph Loop
-7. Verify prd.json meets Ralph Loop requirements (7 categories, BR mappings, CORE seedData)
+6. Verify all required sections for `/business-analyse-develop`
+7. Verify prd.json meets requirements (8 categories incl. `documentation`, BR mappings, CORE seedData)
 
 **Medium Module Pipeline with Lifecycle:**
 1. Load medium feature with lifecycle
@@ -159,7 +163,7 @@ tests/ba/
 3. Extract prd.json with lifecycle preserved
 4. Verify lifecycle transitions mapped to BR
 5. Verify lifecycle states match seedData
-6. Write prd.json to .ralph/
+6. Write prd.json to .prd/
 
 **Reproducibility Test:**
 - Multiple extractions = identical prd.json (sans timestamp)
@@ -168,11 +172,56 @@ tests/ba/
 - Missing optional namespace handled gracefully
 - Empty arrays handled gracefully
 
-**Integration with Ralph Loop:**
+**Integration with `/business-analyse-develop`:**
 - All required information present (entities, UCs, BRs, endpoints, permissions, filesToCreate, BR mappings, CORE seedData)
 - Use cases linked to API endpoints
 - Business rules linked to use cases
 
+### 5. chain-integrity.test.ts
+
+**Objectif:** Valider l'intégrité de la chaîne complète BA → Handoff → PRD.
+
+**Scénarios (55 tests, 9 parties):**
+- Part 1: Fichiers skill BA existent et sont structurés correctement
+- Part 2: Fichiers skill handoff existent et sont structurés correctement
+- Part 3: Cohérence des références inter-steps (next_step valides)
+- Part 4: Schémas JSON valides et présents
+- Part 5: POST-CHECKs exécutables dans les steps critiques
+- Part 6: Références aux fonctions d'extraction (extractPrd, extractUnifiedPrd)
+- Part 7: Cohérence fixtures ↔ schéma feature-json
+- Part 8: Imports et exports du module prd-extractor
+- Part 9: Silent failure guards (détection parse-error avant fallback)
+
+### 6. task-generation.test.ts
+
+**Objectif:** Tester la génération de tâches depuis le PRD.
+
+**Scénarios (26 tests):**
+- Génération de tâches depuis PRD simple (module Orders)
+- Génération de tâches depuis PRD medium (module Invoices avec lifecycle)
+- Validation intégrité des tâches (`validateTaskIntegrity()`)
+- Tâches couvrent toutes les entités
+- Tâches couvrent tous les use cases
+- Tâches ont des dépendances valides (pas de cycles)
+- Ordre topologique respecté
+- Tâches lifecycle incluent les transitions
+
+### 7. unified-prd.test.ts
+
+**Objectif:** Tester `extractUnifiedPrd()` — extraction PRD dual-mode v2/v3.
+
+**Scénarios (24 tests):**
+- Extraction PRD v3.0 (task-oriented) depuis feature simple
+- Extraction PRD v3.0 depuis feature medium avec lifecycle
+- Structure v3.0 : `$version: "3.0.0"`, tâches intégrées
+- `validatePrdCompleteness()` : PRD complet passe
+- `validatePrdCompleteness()` : PRD incomplet signale erreurs
+- `getPrdFileCounts()` : comptage correct par catégorie
+- Fallback v2.0 quand extractPrd() appelé directement
+- Cohérence entre v2 et v3 (mêmes données source)
+- Metadata préservé (application, module, namespace)
+- Traçabilité source (extractedAt, featureJsonPath)
+
 ---
 
 ## Exécution des Tests
@@ -302,7 +351,7 @@ describe('My Test Suite', () => {
     const feature = await fs.readJson(join(fixturesDir, 'my-feature.json')) as ModuleFeatureJson;
     const prd = extractPrd(feature, 'my-feature.json', 'MyCompany.MyApp');
 
-    expect(prd.version).toBe('2.0.0');
+    expect(prd.version).toBeDefined();
     expect(prd.project.module).toBe('MyModule');
     // ... more assertions
   });
@@ -377,14 +426,18 @@ jobs:
 
 | Fichier | Couverture Cible |
 |---------|-----------------|
-| `src/utils/prd-extractor.ts` | 100% |
-| `src/commands/derive-prd.ts` | 90% |
+| `src/utils/prd-extractor.ts` — `extractPrd()` | 100% |
+| `src/utils/prd-extractor.ts` — `extractUnifiedPrd()` | 100% |
+| `src/utils/prd-extractor.ts` — `validatePrdCompleteness()` | 100% |
+| `src/utils/prd-extractor.ts` — `validateTaskIntegrity()` | 100% |
+| `src/utils/prd-extractor.ts` — `getPrdFileCounts()` | 100% |
+| `src/commands/business-analyse-handoff.ts` | 90% |
 | `templates/skills/business-analyse/**/*.md` | N/A (documentation) |
 
 ### KPIs Tests
 
-- **Total tests:** ~60 scénarios
-- **Temps d'exécution:** < 10s
+- **Total tests:** 168 scénarios (7 test suites)
+- **Temps d'exécution:** < 2s
 - **Fixtures:** 3 (simple/medium/complex)
 - **Couverture code:** > 95% sur extraction pipeline
 
@@ -435,22 +488,20 @@ export default defineConfig({
 ### Phase 1 ✅ (Implémenté)
 - Infrastructure Vitest
 - 3 fixtures (simple/medium/complex)
-- 4 test suites (handoff-validation, prd-extraction x2, full-pipeline)
+- 7 test suites (handoff-validation, prd-extraction x2, full-pipeline, chain-integrity, task-generation, unified-prd)
 - Scripts npm
 - Documentation
 
-### Phase 2 (Futur)
+### Phase 2 (À planifier)
 - Tests pour mode `--application` (extraction multi-modules)
-- Tests pour mode `--strict`
-- Tests pour cross-module dependencies
+- Tests pour flag `--v4` (PRD spec-oriented)
+- Tests pour `extractUnifiedPrd()` edge cases
 - Performance benchmarks (extraction < 100ms)
-- Tests pour ba-interactive.html extraction
 
 ### Phase 3 (Futur)
-- Tests E2E Ralph Loop integration (mock Ralph Loop server)
-- Tests pour step-05-handoff.md (génération handoff)
-- Tests pour derive-prd CLI (end-to-end avec fs.existsSync)
-- Tests pour validation schema (feature-schema.json)
+- Tests E2E `/business-analyse-develop` integration (mock `/apex -d`)
+- Tests pour `/business-analyse-handoff` CLI (end-to-end avec fs)
+- Tests pour validation schema v5.0 (`feature-schema.json`)
 
 ---
 
@@ -459,4 +510,5 @@ export default defineConfig({
 - [prd-json v2.0.0 Reference](./prd-json-v2.0.0.md)
 - [Feature JSON Schema](../templates/skills/business-analyse/schemas/feature-schema.json)
 - [Business Analyse Skill](../templates/skills/business-analyse/SKILL.md)
-- [Ralph Loop Documentation](../templates/skills/ralph-loop/SKILL.md)
+- [Business Analyse Develop](../templates/skills/business-analyse-develop/SKILL.md)
+- [Business Analyse Handoff](../templates/skills/business-analyse-handoff/SKILL.md)

package/package.json

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

package/templates/agents/gitflow/init.md

@@ -240,6 +240,28 @@ Check the result. If FAIL, report to user and suggest manual intervention.
 
 ---
 
+## STEP 3b: DETECT PROJECT VERSION
+
+Read `references/init-version-detection.md` and execute the version detection script.
+
+The script detects the project version with this priority:
+1. `*.csproj` `<Version>` tag
+2. `Directory.Build.props` `<Version>` tag
+3. `package.json` `"version"` field
+4. `VERSION` file
+5. Latest git tag (stripped of `v` prefix)
+6. Fallback: `0.0.0`
+
+Store the result as `{VERSION}`.
+
+**CRITICAL:** `{VERSION}` is the PROJECT version (e.g., "0.0.0", "1.2.3").
+It is NOT the config schema version ("2.1.0" on line 1 of config.json).
+These are two different things:
+- `"version": "2.1.0"` = config file format version (FIXED, do not change)
+- `"versioning.current": "{VERSION}"` = project semver version (DETECTED)
+
+---
+
 ## STEP 4: WRITE CONFIG
 
 Write `.claude/gitflow/config.json` in develop worktree using the Write tool.
@@ -257,6 +279,10 @@ MAIN_DIR    = organized → "01-Main"  | simple → "main"  | disabled → "."
 DEVELOP_DIR = organized → "02-Develop" | simple → "develop" | disabled → "."
 ```
 
+> **TWO DIFFERENT VERSIONS:** `"version": "2.1.0"` below is the CONFIG SCHEMA version (always 2.1.0).
+> `"versioning.current": "{VERSION}"` is the PROJECT version (detected in step 3b).
+> Do NOT confuse them. Do NOT use "2.1.0" as the project version.
+
 ```json
 {
   "version": "2.1.0",

package/templates/skills/apex/references/parallel-execution.md

@@ -91,12 +91,28 @@ Agent principal aggregates all results after all agents complete.
 
 ```
 Layer 2 (Backend) — if multiple entities:
+  # AGENT BOUNDARY: Snipper agents do NOT have access to MCP tools.
+  # Services, DTOs, controllers MUST be scaffolded by the principal agent via MCP.
+  # Snipper agents handle ONLY: business logic, validators, code-gen wiring.
+
+  # PHASE A — Sequential: MCP scaffolding (principal agent)
+  For each entity:
+    mcp__smartstack__scaffold_extension(type: "dto", name: "{Entity}", options: { navRoute: "..." })
+    mcp__smartstack__scaffold_extension(type: "controller", name: "{Entity}", options: { navRoute: "..." })
+    Verify NavRoute on generated controller (bash)
+
+  # PHASE B — Parallel: post-scaffold adjustments (Snipper agents)
   Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 2 backend for {Entity1}: service, DTO, controller, validators...')
+    prompt='Adjust Layer 2 backend for {Entity1}: service logic, validators, code-gen wiring.
+            DO NOT regenerate controller/DTO — already created by MCP.')
   Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 2 backend for {Entity2}: service, DTO, controller, validators...')
+    prompt='Adjust Layer 2 backend for {Entity2}: service logic, validators, code-gen wiring.
+            DO NOT regenerate controller/DTO — already created by MCP.')
   # Launched in parallel in a single message
 
+  # PHASE C — Sequential: DI registration (principal agent)
+  # Register all services + validators in DependencyInjection.cs (single pass, no conflicts)
+
 Layer 3 (Frontend) — if multiple entities:
   # ⛔ AGENT BOUNDARY: Snipper agents do NOT have access to Skill().
   # Pages (.tsx) MUST be generated by the principal agent via Skill("ui-components").
@@ -138,7 +154,9 @@ Each agent has an **isolated scope**: handles one entity end-to-end within the l
 2. Build gate: dotnet build → MUST PASS
 3. Layer 1: agent principal executes (seed data — sequential, no parallel agents)
 4. Build gate: dotnet build → MUST PASS
-5. Layer 2: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
+5. Layer 2 Phase A: principal scaffolds ALL entities via MCP (dto + controller per entity)
+5b. Layer 2 Phase B: launch Snipper agents for post-scaffold adjustments (parallel)
+5c. Layer 2 Phase C: principal registers all DI in DependencyInjection.cs (single pass)
 6. Build gate: dotnet build → MUST PASS
 7. Backend tests inline (scaffold + run + fix max 3)
 8. Layer 3 Phase A: launch Snipper agents for infra (api-client, routes, i18n) — NOT pages
@@ -163,7 +181,7 @@ There is no idle state to manage — the agent principal simply waits for result
 |-----------|--------|
 | economy_mode = true | NO parallel agents, all sequential |
 | Single entity (any layer) | NO parallel agents, agent principal handles all |
-| Multiple entities, Layer 2 | Parallel: one Snipper agent per entity (service + controller) |
+| Multiple entities, Layer 2 | Phase A: principal scaffolds via MCP (sequential). Phase B: Snipper for business logic (parallel). Phase C: principal DI registration (sequential) |
 | Multiple entities, Layer 3 | Parallel: Snipper agents for infra (api-client, routes, i18n) — pages by principal via Skill("ui-components") |
 | Layer 0, Layer 1, Layer 4 | NO parallel agents (sequential by nature) |
 | Analysis phase (step-01) | Parallel: 2-3 Explore agents (backend + frontend + context) |

package/templates/skills/apex/steps/step-00-init.md

@@ -57,6 +57,43 @@ When `-d {prd_path}` is used, extract all context from PRD file and skip section
 - `{needs_migration}` = any tasks with _migrationMeta
 - `{has_dependencies}` = prd.tasks.some(t => t.dependencies.length > 0) ? "references" : "none"
 
+**Fallback extraction (if prd.project is absent — e.g. PRD v3.0.0 with metadata format):**
+- `{app_name}` = prd.metadata?.applicationCode || prd.project?.application
+- `{module_code}` = prd.metadata?.moduleCode || prd.project?.module
+- `{entities}` = prd.implementation?.filesToCreate?.domain?.filter(f => f.type === 'Entity').map(f => extractEntityName(f.path)) || domain tasks fallback
+- `{sections}` = prd.implementation?.filesToCreate?.seedData?.filter(f => f.path.includes('NavigationSectionSeedData')).length > 0 ? extractSectionsFromSeedDataPaths(prd) : []
+- `{needs_seed_data}` = (prd.implementation?.filesToCreate?.seedData?.length || 0) > 0
+- `{needs_migration}` = (prd.implementation?.filesToCreate?.infrastructure?.length || 0) > 0
+
+**Specification Files Loading (if prd.specificationFiles present):**
+
+```javascript
+if (prd.specificationFiles) {
+  const specsDir = path.dirname(delegate_prd_path); // .ralph/
+  const specFiles = prd.specificationFiles;
+
+  // Store loading plan for layer-specific consumption
+  specification_loading_plan = {
+    layer0_domain:   [specFiles.entities],
+    layer1_seed:     [specFiles.entities, specFiles.permissions],
+    layer2_backend:  [specFiles.rules, specFiles.usecases],
+    layer3_frontend: [specFiles.screens, specFiles.usecases]
+  };
+
+  // Verify all companion files exist
+  for (const [layer, files] of Object.entries(specification_loading_plan)) {
+    for (const file of files) {
+      const filePath = path.join(specsDir, file);
+      if (!fileExists(filePath)) {
+        console.warn(`WARNING: Companion file missing for ${layer}: ${filePath}`);
+      }
+    }
+  }
+}
+```
+
+Each layer step (step-03a through step-03d) will load its companion files at the start. This provides full BA specifications (entity attributes, BR formulas, UC steps, screen columns) without loading the entire spec corpus.
+
 **Jump to:** section 3 (MCP verify) → section 6 (determine needs) → section 9 (summary)
 
 ---
@@ -231,6 +268,7 @@ Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
 Code: {code_patterns summary} | PRD: {prd_path||none} | Feature: {feature_path||none}
 Flags: {active_flags} | MCP: {available|degraded} | Needs: {migration/seed/workflow/notification}
+Specs: {specification_loading_plan ? 'companion files available (layer-specific loading)' : 'none'}
 NEXT STEP: step-01-analyze
 ```
 

package/templates/skills/apex/steps/step-03a-layer0-domain.md

@@ -9,6 +9,27 @@ parent_step: steps/step-03-execute.md
 
 ## Layer 0 — Domain + Infrastructure (sequential, agent principal)
 
+### Companion Specs Loading (delegate mode)
+
+```javascript
+if (delegate_mode && specification_loading_plan) {
+  const specsDir = path.dirname(delegate_prd_path);
+  // Layer 0 loads: entities companion
+  for (const file of specification_loading_plan.layer0_domain) {
+    const specPath = path.join(specsDir, file);
+    if (fileExists(specPath)) {
+      const specData = readJSON(specPath);
+      // specData.entities[] contains full attribute definitions:
+      //   { name, type, required, validation, defaultValue, relationships[] }
+      // Use these for entity scaffolding instead of just entity names
+      console.log(`Loaded ${specPath}: ${(specData.entities || []).length} entities with full attributes`);
+    }
+  }
+}
+```
+
+> When companion specs are loaded, use `specData.entities[].attributes[]` for entity property definitions (type, required, validation, defaultValue) instead of inferring from task descriptions. This ensures oneshot generation with correct types and constraints.
+
 ### Task Progress
 TaskUpdate(taskId: layer0_task_id, status: "in_progress")
 TaskUpdate(taskId: progress_tracker_id,

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -9,6 +9,31 @@ parent_step: steps/step-03-execute.md
 
 ## Layer 1 — Seed Data (DEDICATED LAYER — sequential, agent principal)
 
+### Companion Specs Loading (delegate mode)
+
+```javascript
+if (delegate_mode && specification_loading_plan) {
+  const specsDir = path.dirname(delegate_prd_path);
+  // Layer 1 loads: entities + permissions companions
+  for (const file of specification_loading_plan.layer1_seed) {
+    const specPath = path.join(specsDir, file);
+    if (fileExists(specPath)) {
+      const specData = readJSON(specPath);
+      if (specData.entities) {
+        // Use entities[].seedValues[] for business seed data generation
+        console.log(`Loaded entities: ${specData.entities.length} entities`);
+      }
+      if (specData.permissionPaths || specData.roles) {
+        // Use full permission structure for PermissionsSeedData and RolesSeedData
+        console.log(`Loaded permissions: ${(specData.permissionPaths || []).length} paths, ${(specData.roles || []).length} roles`);
+      }
+    }
+  }
+}
+```
+
+> When companion specs are loaded, use `specData.permissionPaths[]` for exact permission paths and `specData.roles[]` for role definitions instead of generating from conventions. This ensures permission seed data matches BA specifications exactly.
+
 ### Task Progress
 TaskUpdate(taskId: layer1_task_id, status: "in_progress")
 TaskUpdate(taskId: progress_tracker_id,
@@ -157,6 +182,39 @@ Generate all files from scratch using `references/core-seed-data.md` templates:
 
 ---
 
+### Startup Pipeline Wiring (ONCE per project)
+
+> **CRITICAL:** Seed data files are useless without startup execution.
+> Reference: SmartStack.app `SmartStackExtensions.cs` → `InitializeSmartStackAsync()` → `RunClientSeedDataProvidersAsync()`
+
+```
+Glob("**/Program.cs") → Read Program.cs
+
+IF Program.cs calls `InitializeSmartStackAsync()`:
+  → Seed data pipeline is already wired ✅
+
+ELSE IF Program.cs ONLY calls `MigrateAsync()` without seed data execution:
+  → Add seed data provider execution AFTER MigrateAsync():
+
+  After `await extDb.Database.MigrateAsync();`:
+    var seedProviders = scope.ServiceProvider
+        .GetServices<IClientSeedDataProvider>()
+        .OrderBy(s => s.Order).ToList();
+    foreach (var provider in seedProviders)
+    {
+        var coreDb = scope.ServiceProvider.GetRequiredService<ICoreDbContext>();
+        await provider.SeedNavigationAsync(coreDb, CancellationToken.None);
+        await provider.SeedRolesAsync(coreDb, CancellationToken.None);
+        await provider.SeedPermissionsAsync(coreDb, CancellationToken.None);
+        await provider.SeedRolePermissionsAsync(coreDb, CancellationToken.None);
+    }
+
+  Add using: SmartStack.Application.Common.Interfaces.Seeding
+  → ONE-TIME wiring. Future modules just add DI registrations.
+```
+
+---
+
 ### Post-Layer 1 Verification Checklist
 
 > **Before the build gate, verify ALL new scope elements are covered:**
@@ -169,6 +227,8 @@ For each section in {sections} from step-00:
   ✓ PermissionsSeedData has HasData() for each permission
   ✓ RolesSeedData maps all 4 roles to section permissions
   ✓ {App}SeedDataProvider references all seed data classes
+  ✓ Program.cs executes seed data providers after MigrateAsync()
+  ✓ DI registers: services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()
 
 IF any check fails → fix BEFORE build gate
 ```

package/templates/skills/apex/steps/step-03c-layer2-backend.md

@@ -9,6 +9,37 @@ parent_step: steps/step-03-execute.md
 
 ## Layer 2 — Backend (Services + Controllers)
 
+### Companion Specs Loading (delegate mode)
+
+```javascript
+if (delegate_mode && specification_loading_plan) {
+  const specsDir = path.dirname(delegate_prd_path);
+  // Layer 2 loads: rules + usecases companions
+  for (const file of specification_loading_plan.layer2_backend) {
+    const specPath = path.join(specsDir, file);
+    if (fileExists(specPath)) {
+      const specData = readJSON(specPath);
+      if (specData.rules) {
+        // Full rule definitions: statement, example, formula, conditions
+        // Use for: Validator rules (BR-VAL-*), calculation logic (BR-CALC-*), workflow guards (BR-WF-*)
+        console.log(`Loaded rules: ${specData.rules.length} business rules with full definitions`);
+      }
+      if (specData.useCases || specData.usecases) {
+        const ucs = specData.useCases || specData.usecases;
+        // Full UC definitions: steps[], preconditions[], result, alternativeFlows
+        // Use for: Service method implementation, controller actions, error handling
+        console.log(`Loaded usecases: ${ucs.length} use cases with steps and preconditions`);
+      }
+    }
+  }
+}
+```
+
+> When companion specs are loaded:
+> - **BR-VAL-*** rules: use `rule.statement` + `rule.conditions[]` to implement FluentValidation rules with exact business logic
+> - **BR-CALC-*** rules: use `rule.formula` to implement calculation methods with the exact formula
+> - **Use cases**: use `uc.steps[]` to implement service methods following the exact flow, and `uc.preconditions[]` for guard clauses
+
 ### Task Progress
 TaskUpdate(taskId: layer2_task_id, status: "in_progress")
 TaskUpdate(taskId: progress_tracker_id,
@@ -22,6 +53,28 @@ TaskUpdate(taskId: progress_tracker_id,
 > - DateOnly vs string for DTO date fields
 > - Code generation patterns (ICodeGenerator<T> registration, see references/code-generation.md)
 
+### HARD RULE — MCP scaffold_extension is NON-NEGOTIABLE for backend generation
+
+> **VIOLATION CHECK:** If ANY service, controller, or DTO file was created by Write tool
+> WITHOUT a prior MCP scaffold_extension call in this execution, the backend layer is INVALID.
+>
+> **You MUST NOT:**
+> - Generate service/controller/DTO code in Agent prompts and dispatch to Snipper agents
+> - Write controller content directly via the Write tool
+> - Copy-paste controller templates from your knowledge
+>
+> **You MUST:**
+> - Call MCP scaffold_extension for each entity (service, DTO, controller)
+> - Let MCP generate all files with correct NavRoute, permissions, conventions
+>
+> **Why this matters:** Without MCP, controllers get both [Route] and [NavRoute] (causes 404s),
+> NavRoute typos, incorrect permission scoping, and missing convention compliance.
+>
+> **Agent boundary rule:** Snipper sub-agents DO NOT have access to MCP tools.
+> Therefore, MCP scaffolding MUST NEVER be delegated to Snipper agents.
+> MCP calls are ALWAYS executed by the principal agent.
+> Snipper agents handle: DI registration, business logic adjustments, validator customization.
+
 ### Backend Tasks (sequential or parallel within layer)
 
 - Services/DTOs: MCP scaffold_extension
@@ -63,32 +116,65 @@ For each entity where {code_patterns} defines strategy != "manual":
 | /notification | In-app or email notifications | trigger, recipients, template |
 | /workflow | Automated workflows | trigger, steps, conditions |
 
-### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
+### If NOT economy_mode AND multiple entities: Phased Execution
 
 > **Protocol:** See `references/parallel-execution.md`
+> **AGENT BOUNDARY:** Snipper agents do NOT have access to MCP tools or Bash.
+> MCP scaffolding and bash validation MUST be executed by the principal agent.
+
+#### Phase A — Sequential: MCP scaffolding (principal agent)
+
+For each entity, the principal agent calls MCP directly:
 
 ```
 IF NOT economy_mode AND entities.length > 1:
+
+  FOR EACH entity in entities:
+    1. mcp__smartstack__scaffold_extension(type: "dto", name: "{Entity}", options: { navRoute: "{navRoute}" })
+    2. mcp__smartstack__scaffold_extension(type: "controller", name: "{Entity}", options: { navRoute: "{navRoute}" })
+
+    # Immediate NavRoute verification (principal has Bash access)
+    3. Verify: [NavRoute] present, [Route] absent, segment count >= 2
+       If [Route] found alongside [NavRoute] → remove [Route] immediately
+       If [NavRoute] missing → add it with correct value
+```
+
+#### Phase B — Parallel: post-scaffold adjustments (Snipper agents)
+
+After ALL Phase A scaffolding completes, launch Snipper agents in parallel:
+
+```
   For each entity, launch in parallel (single message):
     Agent(subagent_type='Snipper', model='opus',
-      prompt='Execute Layer 2 backend for {EntityName}:
-        - Application service/DTO: MCP scaffold_extension
-        - Controller: /controller skill or MCP scaffold_extension
-        - IMPORTANT: GetAll endpoint MUST support ?search= parameter
-        - Validators: FluentValidation + DI registration
+      prompt='Adjust Layer 2 backend for {EntityName}:
+        - Service: implement business logic in {EntityName}Service (FK patterns, search, inline Select)
+        - Validator: customize FluentValidation rules for Create{EntityName}Dto and Update{EntityName}Dto
         - CODE GENERATION: {code_patterns[EntityName] summary — e.g., "strategy: sequential, prefix: emp, digits: 5" or "manual"}
           If strategy != "manual": read references/code-generation.md, then:
-          → Register ICodeGenerator<{EntityName}> in DI (DependencyInjection.cs) with CodePatternConfig matching {code_patterns}
-          → Inject ICodeGenerator<{EntityName}> in {EntityName}Service, use _codeGenerator.NextCodeAsync(ct) in CreateAsync
-          → Remove Code from Create{EntityName}Dto (auto-generated, not user-provided)
-          → Keep Code in {EntityName}ResponseDto
+          → Inject ICodeGenerator<{EntityName}> in {EntityName}Service constructor
+          → Use _codeGenerator.NextCodeAsync(ct) in CreateAsync
+          → Remove Code from Create{EntityName}Dto, keep in {EntityName}ResponseDto
           → Create{EntityName}Validator: NO Code rule. Update{EntityName}Validator: Code rule with regex ^[a-z0-9_-]+$
         - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
-        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
+        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.
+
+        DO NOT regenerate controller or DTO files — already created by MCP in Phase A.
+        DO NOT add [Route] attribute — NavRoute is already set correctly.
+        Files already created: {list of paths from Phase A}')
   # All agents launched in parallel
+```
+
+#### Phase C — Sequential: shared file edits (principal agent)
+
+After ALL Phase B agents complete, the principal agent handles shared-file edits:
+
+```
+  1. DependencyInjection.cs: register ALL services + validators in a single pass
+     → Avoids concurrent edit conflicts on shared file
+  2. Code-generation DI: register ICodeGenerator<T> for each entity with strategy != "manual"
 
 ELSE:
-  # Agent principal handles all entities sequentially
+  # Agent principal handles all entities sequentially (economy_mode or single entity)
 ```
 
 ### Parallel Agents + TaskCreate Integration
@@ -105,7 +191,7 @@ When launching agents for multi-entity layers:
 
 After controller generation, verify `[NavRoute]` attribute is present on every controller:
 - Expected: `[NavRoute("{app_name}.{module_code}.{section_code}")]` on the controller class
-- If missing: Add it manually above `[Authorize]`
+- If missing: Add it manually above `[Microsoft.AspNetCore.Authorization.Authorize]`
 - When calling `scaffold_extension(type: "controller")`, always pass `navRoute` in options
 - This is REQUIRED for `scaffold_routes` to auto-detect routes in Layer 3
 
@@ -121,6 +207,9 @@ After controller generation, verify `[NavRoute]` attribute is present on every c
    - **If a controller is in a section subfolder** (e.g., `Controllers/{App}/Employees/ContractsController.cs`) **but has only 2 segments** → the API route will be wrong → 404. It MUST have 3 segments.
    - 0 dots = INVALID → BLOCK
 
+> **Execution context:** These bash scripts run from the PRINCIPAL AGENT after Phase C.
+> Snipper agents cannot execute Bash. Do NOT include these checks in Snipper prompts.
+
 ```bash
 # Quick validation
 CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
@@ -149,6 +238,9 @@ for f in $CTRL_FILES; do
   if ! grep -q "\[NavRoute" "$f" && grep -q "\[Route" "$f"; then
     echo "WARNING: $f has [Route] but no [NavRoute] — add [NavRoute] for route auto-detection"
   fi
+  if grep -q "\[NavRoute" "$f" && grep -q "\[Route(" "$f"; then
+    echo "WARNING: $f has BOTH [Route] and [NavRoute] — remove [Route] (causes 404s)"
+  fi
 done
 ```
 
@@ -181,6 +273,25 @@ for ENTITY in $ENTITIES; do
     echo "BLOCKING: $CTRL has NO route attribute at all"
     echo "Fix: Add [NavRoute(\"{app}.{module}.{section}\")] from naming rules"
   fi
+
+  if [ "$HAS_NAVROUTE" -gt 0 ] && [ "$HAS_ROUTE" -gt 0 ]; then
+    echo "BLOCKING: $CTRL has BOTH [Route] and [NavRoute] — causes 404s"
+    echo "Fix: Remove [Route(\"...\")], keep only [NavRoute(\"...\")]"
+  fi
+done
+
+# Check NavRoute uniqueness across generated controllers
+ALL_NAVROUTES=""
+for ENTITY in $ENTITIES; do
+  CTRL=$(find src/ -path "*/Controllers/*" -name "${ENTITY}*Controller.cs" 2>/dev/null | head -1)
+  [ -z "$CTRL" ] && continue
+  NR=$(grep -oP '\[NavRoute\("\K[^"]+' "$CTRL" 2>/dev/null || true)
+  [ -z "$NR" ] && continue
+  if echo "$ALL_NAVROUTES" | grep -qx "$NR"; then
+    echo "BLOCKING: Duplicate NavRoute '$NR' on $CTRL — each controller needs a unique NavRoute"
+  fi
+  ALL_NAVROUTES="$ALL_NAVROUTES
+$NR"
 done
 ```