@atlashub/smartstack-cli 4.27.0 → 4.28.0

package/templates/skills/business-analyse/steps/step-02-structure.md

@@ -72,16 +72,27 @@ For each module, anticipate the navigation structure:
 For each section:
   - code (kebab-case, e.g., "list", "detail", "dashboard")
   - label (display name)
+  - sectionType: primary | functional | view | embedded
+  - permissionMode: crud | custom | read-only | inherit
   - resources: [
       { code, type (SmartTable|SmartForm|SmartCard|SmartKanban|SmartDashboard|SmartFilter), label }
     ]
 ```
 
+**Section classification rules:**
+
+| sectionType | permissionMode | When to use | Examples |
+|---|---|---|---|
+| `primary` | `crud` | Main entry point of the module, visible in menu | list |
+| `functional` | `crud` or `custom` | Independent functional zone with own access control | approve, import, planning |
+| `view` | `inherit` | Subordinate view reached from a primary section | detail, edit |
+| `embedded` | `read-only` | Widget or tab embedded in another section | dashboard (when embedded in module) |
+
 Common patterns:
-- **Data-centric module**: list (SmartTable) + detail (SmartForm)
-- **Workflow module**: list + detail + kanban (SmartKanban)
-- **Reporting module**: dashboard (SmartDashboard) + detail
-- **Full module**: list + detail + dashboard
+- **Data-centric module**: list (`primary`/`crud`) + detail (`view`/`inherit`)
+- **Workflow module**: list (`primary`/`crud`) + detail (`view`/`inherit`) + approve (`functional`/`custom`)
+- **Reporting module**: dashboard (`primary`/`read-only`) + detail (`view`/`inherit`)
+- **Full module**: list (`primary`/`crud`) + detail (`view`/`inherit`) + dashboard (`embedded`/`read-only`)
 
 ### 4. Dependency Graph
 
@@ -111,6 +122,9 @@ For EACH identified element, ask yourself:
 - Does this module need a dashboard?
 - Is the list/detail pattern sufficient or are there other views?
 - Are there workflow steps that need dedicated sections?
+- Does this section need its own access control? If not → `view` or `embedded`
+- Is this a read-only view (dashboard, balances, statistics)? If yes → `permissionMode: read-only`
+- Is this section reached by clicking a row in another section? If yes → always `view`
 
 **Resources:**
 - Is SmartTable the right component for this list?
@@ -159,8 +173,8 @@ Write via ba-writer:
       "priority": "must",
       "entities": ["Employee", "Contract"],
       "anticipatedSections": [
-        { "code": "list", "label": "Liste", "resources": [{ "code": "employees-grid", "type": "SmartTable" }] },
-        { "code": "detail", "label": "Fiche", "resources": [{ "code": "employee-form", "type": "SmartForm" }] }
+        { "code": "list", "label": "Liste", "sectionType": "primary", "permissionMode": "crud", "resources": [{ "code": "employees-grid", "type": "SmartTable" }] },
+        { "code": "detail", "label": "Fiche", "sectionType": "view", "permissionMode": "inherit", "resources": [{ "code": "employee-form", "type": "SmartForm" }] }
       ]
     }
   ],

package/templates/skills/business-analyse/steps/step-03-specify.md

@@ -123,6 +123,10 @@ Define the permission matrix:
 }
 ```
 
+**Auto-detection rules:**
+- If the cadrage mentions "export", "Excel", "CSV", or "télécharger" → automatically add `.export` permission and an export use case (UC-{PREFIX}-EXPORT)
+- If the cadrage mentions "import", "importer", "upload" → automatically add `.import` permission and an import use case (UC-{PREFIX}-IMPORT)
+
 ### F. Interface Specs — Delegated to /ba-design-ui
 
 > **Screen specifications are NOT produced in this step.**
@@ -163,6 +167,9 @@ Before advancing to step 04, verify:
 - [ ] All entity relationships reference existing entities
 - [ ] All UC business rule references exist
 - [ ] All permission paths follow the convention
+- [ ] Sections with `sectionType: view` do NOT appear in `permissionPaths` (they inherit from module)
+- [ ] Sections with `permissionMode: read-only` only have `.read` in `permissionPaths` (no create/update/delete)
+- [ ] Sections with `permissionMode: inherit` have ZERO entries in `permissionPaths`
 
 ## Transition
 

package/templates/skills/controller/references/mcp-scaffold-workflow.md

@@ -123,6 +123,26 @@ if (actualNavRoute !== permission_path) {
   console.warn(`  Got: "${actualNavRoute}"`);
   // Warning only — proceed
 }
+
+// Validate segment count
+const segments = actualNavRoute ? actualNavRoute.split('.').length : 0;
+if (segments < 2) {
+  console.error(`BLOCKING: NavRoute "${actualNavRoute}" has only ${segments} segment(s) — minimum 2 required`);
+  console.error(`  Format: "app.module" (2 segments) or "app.module.section" (3 segments)`);
+  STOP;
+}
+
+// If entity is in a section subfolder, NavRoute must have 3+ segments
+// Check: controller path has 3+ levels after Controllers/ → section-level
+const controllerDir = controllerCall.controllerFile.replace(/[^/]*$/, '');
+const depthAfterControllers = controllerDir.split('Controllers/')[1]?.split('/').filter(Boolean).length || 0;
+if (depthAfterControllers >= 2 && segments < 3) {
+  console.warn(`WARNING: Controller is in a section subfolder (depth=${depthAfterControllers})`);
+  console.warn(`  but NavRoute "${actualNavRoute}" has only ${segments} segments`);
+  console.warn(`  Expected 3 segments: "app.module.section"`);
+  console.warn(`  A 2-segment NavRoute on a section controller causes API 404s`);
+  // Warning — developer should verify and fix
+}
 ```
 
 ---

package/templates/skills/derive-prd/references/handoff-file-templates.md

@@ -30,6 +30,12 @@ From `usecases.json > useCases[]`:
 
 Include: Service per UC cluster, DTOs for API contracts, Validators (FluentValidation), Query handlers
 
+**Validator generation rules:**
+- Every entity with Create and/or Update use cases MUST have a corresponding Validator
+- Validators MUST be registered in DI (`services.AddScoped<IValidator<CreateXxxDto>, CreateXxxValidator>()`)
+- Validators MUST be injected into controllers/services that handle POST/PUT operations
+- NO TODO/placeholder comments allowed in Validators — all validation rules from business rules (BR-VAL-*) must be implemented
+
 ## 4.3 Infrastructure Files
 
 From `entities.json > entities[]`:
@@ -48,7 +54,8 @@ Generated from `usecases.json` + `entities.json`:
 
 ```json
 "api": [
-  { "path": "src/API/Controllers/{ApplicationName}/{EntityName}Controller.cs", "type": "ApiController", "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" }
+  { "path": "src/API/Controllers/{ApplicationName}/{EntityName}Controller.cs", "type": "ApiController", "navRoute": "{app-kebab}.{module-kebab}", "isSection": false, "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" },
+  { "path": "src/API/Controllers/{ApplicationName}/{ModuleName}/{SectionEntityName}Controller.cs", "type": "ApiController", "navRoute": "{app-kebab}.{module-kebab}.{section-kebab}", "isSection": true, "linkedUCs": [], "linkedFRs": [], "module": "{moduleCode}" }
 ]
 ```
 
@@ -80,6 +87,23 @@ From `screens.json > screens[]` and `usecases.json > useCases[]`:
 
 **Dashboard acceptance criteria:** Chart library (Recharts), chart types matching spec, KPI cards, filters, CSS variables, responsive layout, wireframe-matching positions.
 
+## 4.5b Notification Files (CONDITIONAL)
+
+> Generated only when `lifeCycles[].transitions[].effects[]` contains entries with `type: "notification"`.
+
+```json
+"notifications": [
+  { "path": "src/Application/Notifications/{ApplicationName}/{ModuleName}/{NotificationName}Notification.cs", "type": "Notification", "linkedUCs": [], "module": "{moduleCode}", "description": "Notification triggered by lifecycle transition" },
+  { "path": "src/Application/Notifications/{ApplicationName}/{ModuleName}/{NotificationName}NotificationHandler.cs", "type": "NotificationHandler", "linkedUCs": [], "module": "{moduleCode}", "description": "Handler that sends in-app/email notification" }
+]
+```
+
+**Generation rules:**
+- One Notification + Handler pair per unique `notification` effect in lifecycle transitions
+- NotificationName derived from transition: `{Entity}{TransitionName}` (e.g., `OrderApproved`)
+- Handler must use `INotificationService` for in-app and `IEmailService` for email type
+- Notification must include: recipient resolution, template reference, and payload mapping
+
 ## 4.6 SeedData Files
 
 **OBLIGATORY: 2 app-level CORE + per module CORE (NavigationModule + NavigationSections + Permissions + Roles) + business per module:**

package/templates/skills/derive-prd/references/handoff-seeddata-generation.md

@@ -127,7 +127,9 @@ const seedDataCore = {
               ? `/${toKebabCase(appCode)}/${toKebabCase(m.code)}/:id`
               : `/${toKebabCase(appCode)}/${toKebabCase(m.code)}/${toKebabCase(s.code)}`,
           displayOrder: (j + 1) * 10,
-          navigation: s.code === "detail" ? "hidden" : "visible"
+          navigation: s.code === "detail" ? "hidden" : "visible",
+          // Propagate permissionMode for section-level permission generation
+          permissionMode: s.permissionMode || (s.code === "detail" ? "inherit" : s.code === "dashboard" ? "read-only" : "crud")
         }))
       );
 

package/templates/skills/ralph-loop/references/category-completeness.md

@@ -191,6 +191,129 @@ for (const [cat, check] of Object.entries(artifactChecks)) {
 }
 ```
 
+## Entity-Level File Completeness Check (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** Artifact verification checked "at least one file per category"
+> but never reconciled against the **handoff contract** (`prd.implementation.filesToCreate`).
+> Result: 4/17 API endpoints were missing but the category showed "complete" because *some* controllers existed.
+
+```javascript
+// BLOCKING: Verify EVERY file from prd.implementation.filesToCreate exists on disk
+const filesToCreate = prd.implementation?.filesToCreate;
+if (filesToCreate) {
+  const handoffMissing = [];
+  const handoffPresent = [];
+
+  for (const [category, files] of Object.entries(filesToCreate)) {
+    for (const file of (files || [])) {
+      const filePath = file.path || file;
+      if (fileExists(filePath)) {
+        handoffPresent.push({ category, path: filePath });
+      } else {
+        handoffMissing.push({ category, path: filePath });
+      }
+    }
+  }
+
+  const totalHandoff = handoffPresent.length + handoffMissing.length;
+  const coveragePct = totalHandoff > 0 ? Math.round((handoffPresent.length / totalHandoff) * 100) : 100;
+  console.log(`Handoff file coverage: ${handoffPresent.length}/${totalHandoff} (${coveragePct}%)`);
+
+  if (handoffMissing.length > 0) {
+    console.error(`BLOCKING: ${handoffMissing.length} files from handoff contract missing on disk`);
+
+    // Group missing files by category for targeted remediation
+    const missingByCategory = {};
+    for (const m of handoffMissing) {
+      if (!missingByCategory[m.category]) missingByCategory[m.category] = [];
+      missingByCategory[m.category].push(m.path);
+    }
+
+    // Inject remediation tasks for each missing file
+    let maxIdNum = Math.max(...prd.tasks.map(t => {
+      const num = parseInt(t.id.replace(/[^0-9]/g, ''), 10);
+      return isNaN(num) ? 0 : num;
+    }), 0);
+    const prefix = prd.tasks[0]?.id?.replace(/[0-9]+$/, '') || 'HNDOFF-';
+
+    for (const [cat, paths] of Object.entries(missingByCategory)) {
+      for (const p of paths) {
+        // Skip if a remediation task already exists for this file
+        const alreadyExists = prd.tasks.some(t =>
+          t.description.includes(p) && t.description.includes('[HANDOFF-REMEDIATION]')
+        );
+        if (alreadyExists) continue;
+
+        maxIdNum++;
+        prd.tasks.push({
+          id: `${prefix}${String(maxIdNum).padStart(3, '0')}`,
+          description: `[HANDOFF-REMEDIATION] Create missing file: ${p}`,
+          status: 'pending',
+          category: cat,
+          dependencies: [],
+          acceptance_criteria: `File ${p} exists on disk and compiles`,
+          started_at: null, completed_at: null, iteration: null,
+          commit_hash: null, files_changed: [], validation: null, error: null
+        });
+      }
+      console.error(`  ${cat}: ${paths.length} missing — ${paths.map(p => p.split('/').pop()).join(', ')}`);
+    }
+
+    writeJSON(currentPrdPath, prd);
+  }
+} // end filesToCreate check
+```
+
+## Type Reference Verification (Cross-File Integrity)
+
+> **LESSON LEARNED (audit ba-002):** Artifact verification counted files but didn't check
+> that types referenced in code actually exist. `EmployeeListDto` was used in services
+> but the file was missing — a "phantom reference" that artifact file-counting missed.
+
+```javascript
+// After artifact checks, verify cross-file type references for completed categories
+if (completedCats.has('application') && completedCats.has('api')) {
+  const serviceFiles = glob('src/**/Services/**/*Service.cs');
+  const dtoFiles = glob('src/**/DTOs/**/*.cs');
+  const entityFiles = glob('src/**/Domain/**/*.cs');
+
+  // Extract all DTO type names from actual files
+  const existingTypes = new Set();
+  for (const f of [...dtoFiles, ...entityFiles]) {
+    const content = readFile(f);
+    const typeMatches = content.matchAll(/(?:class|record|struct|enum|interface)\s+(\w+)/g);
+    for (const m of typeMatches) existingTypes.add(m[1]);
+  }
+
+  // Check service files for references to types that don't exist
+  const phantomRefs = [];
+  for (const f of serviceFiles) {
+    const content = readFile(f);
+    // Look for Dto/Entity type references in return types and method params
+    const typeRefs = content.matchAll(/(?:<|,\s*|\(|new\s+)(\w+(?:Dto|Entity|Exception))\b/g);
+    for (const m of typeRefs) {
+      if (!existingTypes.has(m[1]) && !m[1].startsWith('I')) {
+        phantomRefs.push({ file: f, type: m[1] });
+      }
+    }
+  }
+
+  if (phantomRefs.length > 0) {
+    console.error(`PHANTOM TYPE REFERENCES DETECTED (${phantomRefs.length}):`);
+    phantomRefs.forEach(r => console.error(`  ${r.file}: references ${r.type} — TYPE DOES NOT EXIST`));
+
+    // Reset application category tasks to pending — code references non-existent types
+    prd.tasks.filter(t => t.category === 'application' && t.status === 'completed')
+      .forEach(t => {
+        t.status = 'pending';
+        t.error = `Phantom type references: ${phantomRefs.map(r=>r.type).join(', ')}`;
+        t.completed_at = null;
+      });
+    writeJSON(currentPrdPath, prd);
+  }
+}
+```
+
 ---
 
 ## Key Rules
@@ -198,4 +321,6 @@ for (const [cat, check] of Object.entries(artifactChecks)) {
 - **Inject EVERY iteration:** Not just once during load
 - **Frontend depends on seedData:** Not just API
 - **Check artifacts:** Mark tasks pending if files don't exist
+- **Check type references:** Verify types used in code actually exist (phantom reference detection)
+- **Check handoff files:** Verify EVERY file from `prd.implementation.filesToCreate` exists on disk
 - **Never skip:** This is the blocker for "missing frontend/test" failures

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -289,6 +289,35 @@ if (pending > 0) {
 console.log(`Apex completed: ${completed}/${batchIds.length} tasks`);
 ```
 
+### B3b. Post-Batch Build Verification (BLOCKING)
+
+> **LESSON LEARNED (audit ba-002):** Without build checks between batches, compilation
+> errors from early batches propagate silently through all subsequent batches.
+> The final "Build PASS" was never actually verified.
+
+```bash
+# Quick build check after each batch — BLOCKING if fails
+dotnet build --no-restore --verbosity quiet
+if [ $? -ne 0 ]; then
+  echo "BLOCKING: Build fails after batch [${firstCategory}]"
+  # Inject immediate fix task — will be picked up next iteration
+fi
+```
+
+```javascript
+if (BUILD_FAILED) {
+  const maxId = Math.max(...updatedPrd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
+  updatedPrd.tasks.push({
+    id: `FIX-${maxId+1}`,
+    description: `BLOCKING: Fix build regression after ${firstCategory} batch`,
+    status: 'pending', category: 'validation', dependencies: [],
+    acceptance_criteria: 'dotnet build passes with 0 errors'
+  });
+  writeJSON(currentPrdPath, updatedPrd);
+  // Continue to section C (commit) then D (loop) — fix task will be picked up next iteration
+}
+```
+
 ---
 
 ## C. Commit PRD State
@@ -310,27 +339,54 @@ appendFile('.ralph/progress.txt',
 
 After apex returns, check for newly skipped tasks:
 
+> **LESSON LEARNED (audit ba-002):** Individual skips in critical categories (api, test, domain,
+> infrastructure) allowed 4/17 endpoints and 74% stub tests to pass undetected. The old logic
+> only blocked when ALL tasks in a category were skipped — individual skips slipped through.
+
 ```javascript
+const CRITICAL_CATEGORIES = ['api', 'test', 'domain', 'infrastructure'];
+const MAX_SKIP_RETRIES = 3;
+
 const newlySkipped = prdCheck.tasks.filter(t =>
   batchIds.includes(t.id) && t.status === 'skipped'
 );
 if (newlySkipped.length > 0) {
   console.warn(`⚠ ${newlySkipped.length} tasks were SKIPPED by apex:`);
-  newlySkipped.forEach(t => console.warn(`  - ${t.id}: ${t.description}`));
+  newlySkipped.forEach(t => console.warn(`  - ${t.id}: ${t.description} [${t.category}]`));
 
-  // If ALL tasks in a category were skipped → BLOCKING, reset for retry
   const skippedCategories = [...new Set(newlySkipped.map(t => t.category))];
   for (const cat of skippedCategories) {
+    const isCritical = CRITICAL_CATEGORIES.includes(cat);
     const allInCat = prdCheck.tasks.filter(t => t.category === cat);
     const allSkipped = allInCat.every(t => t.status === 'skipped');
-    if (allSkipped) {
-      console.error(`BLOCKING: ALL tasks in category "${cat}" were skipped — investigate root cause`);
-      // Reset to pending for retry
-      allInCat.forEach(t => {
-        t.status = 'pending';
-        t._retryCount = (t._retryCount || 0) + 1;
-        t.error = `All tasks in category "${cat}" skipped — auto-retry`;
-      });
+
+    if (isCritical) {
+      // CRITICAL CATEGORY: Block on INDIVIDUAL skips (not just when ALL are skipped)
+      const skippedInCat = newlySkipped.filter(t => t.category === cat);
+      for (const t of skippedInCat) {
+        const retryCount = t._skipRetryCount || 0;
+        if (retryCount < MAX_SKIP_RETRIES) {
+          console.error(`BLOCKING: Task ${t.id} skipped in critical category "${cat}" — reset to pending (retry ${retryCount + 1}/${MAX_SKIP_RETRIES})`);
+          t.status = 'pending';
+          t._skipRetryCount = retryCount + 1;
+          t._retryCount = (t._retryCount || 0) + 1;
+          t.error = `Skipped in critical category "${cat}" — auto-retry ${retryCount + 1}/${MAX_SKIP_RETRIES}`;
+        } else {
+          console.error(`FAILED: Task ${t.id} skipped ${MAX_SKIP_RETRIES} times in critical category "${cat}" — marking failed`);
+          t.status = 'failed';
+          t.error = `Skipped ${MAX_SKIP_RETRIES} times in critical category "${cat}" — max retries exhausted`;
+        }
+      }
+    } else {
+      // NON-CRITICAL CATEGORY: Block only when ALL tasks in category are skipped (existing behavior)
+      if (allSkipped) {
+        console.error(`BLOCKING: ALL tasks in category "${cat}" were skipped — investigate root cause`);
+        allInCat.forEach(t => {
+          t.status = 'pending';
+          t._retryCount = (t._retryCount || 0) + 1;
+          t.error = `All tasks in category "${cat}" skipped — auto-retry`;
+        });
+      }
     }
   }
   writeJSON(currentPrdPath, prdCheck);

package/templates/skills/ralph-loop/references/module-transition.md

@@ -27,6 +27,27 @@ if (fileExists(queuePath)) {
 
   // All categories present — module is complete
   // Continue below...
+
+  // HANDOFF FILE GATE (double-security — step-04 §1.8 is primary, this is defense-in-depth)
+  // The build gate does NOT detect missing files if nothing references them (no compile error).
+  const ftc = prd.implementation?.filesToCreate;
+  if (ftc) {
+    let ftcMissing = 0;
+    const ftcDetails = [];
+    for (const [cat, files] of Object.entries(ftc)) {
+      for (const file of (files || [])) {
+        if (!fileExists(file.path || file)) {
+          ftcMissing++;
+          ftcDetails.push(`${cat}: ${(file.path || file).split('/').pop()}`);
+        }
+      }
+    }
+    if (ftcMissing > 0) {
+      console.error(`BLOCKING: ${ftcMissing} handoff files missing — cannot advance module`);
+      ftcDetails.forEach(d => console.error(`  ${d}`));
+      return; // Back to compact loop — remediation tasks already injected by category-completeness
+    }
+  }
 }
 ```
 
@@ -36,6 +57,36 @@ if (fileExists(queuePath)) {
 
 ```javascript
 if (missing.length === 0) {
+  // MANDATORY BUILD+TEST GATE before advancing module
+  // (audit ba-002: module marked "100% complete" despite build errors and security flaws)
+  const buildOk = execSync('dotnet build --no-restore --verbosity quiet').exitCode === 0;
+  if (!buildOk) {
+    console.error(`BLOCKING: Module ${currentModule.code} build fails — cannot advance to next module`);
+    const maxId = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
+    prd.tasks.push({
+      id: `GATE-${maxId+1}`, description: `BLOCKING: Fix build for module ${currentModule.code}`,
+      status: 'pending', category: 'validation', dependencies: [],
+      acceptance_criteria: 'dotnet build passes with 0 errors'
+    });
+    writeJSON(currentPrdPath, prd);
+    return; // Back to compact loop — do NOT advance
+  }
+
+  const testOk = execSync('dotnet test --no-build --verbosity quiet').exitCode === 0;
+  if (!testOk) {
+    console.error(`BLOCKING: Module ${currentModule.code} tests fail — cannot advance to next module`);
+    const maxId = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/\D/g,''))||0));
+    prd.tasks.push({
+      id: `GATE-${maxId+1}`, description: `BLOCKING: Fix tests for module ${currentModule.code}`,
+      status: 'pending', category: 'validation', dependencies: [],
+      acceptance_criteria: 'dotnet test passes with 0 failures'
+    });
+    writeJSON(currentPrdPath, prd);
+    return; // Back to compact loop — do NOT advance
+  }
+
+  console.log(`MODULE GATE PASSED: ${currentModule.code} — build OK, tests OK`);
+
   // Mark current module done
   currentModule.status = 'completed';
   queue.completedModules++;
@@ -68,6 +119,15 @@ if (missing.length === 0) {
 
     console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
 
+    // CONTEXT REFRESH: Force /compact between modules to prevent context degradation
+    // (audit ba-002: quality degraded progressively — module 2 had more errors than module 1
+    // because patterns from module 1 were lost during context compaction)
+    console.log('Forcing /compact for fresh context before next module...');
+    // The /compact command clears accumulated tool results and intermediate reasoning,
+    // preserving only key decisions and the current state. This ensures the next module
+    // starts with a clean context window instead of degraded fragments from the previous module.
+    // INVOKE /compact
+
     // Return to step-01 to load next module's tasks
     // (step-01 will detect module-changed.json and load next PRD)
     return GO_TO_STEP_01;