@atlashub/smartstack-cli 4.27.0 → 4.29.0

package/templates/skills/business-analyse/questionnaire.md

@@ -53,27 +53,27 @@
 
 ### Phase de cadrage (step-01)
 
-1. **Debut :** Commencer par 01-context (contexte metier, identite application)
+1. **Début :** Commencer par 01-context (contexte métier, identité application)
 2. **Adapter :** Sauter les questions non pertinentes selon le contexte
-3. **Approfondir :** Poser des questions de relance sur les reponses vagues
-4. **Challenger :** Ne pas accepter "on verra plus tard" sur les fonctionnalites indispensables
-5. **Par lots :** Presenter 3 a 4 questions par interaction (AskUserQuestion)
+3. **Approfondir :** Poser des questions de relance sur les réponses vagues
+4. **Challenger :** Ne pas accepter "on verra plus tard" sur les fonctionnalités indispensables
+5. **Par lots :** Présenter 3 a 4 questions par interaction (AskUserQuestion)
 
 ### Phase de specification (step-03)
 
-1. **Par module :** Charger 03-data-ui pour chaque module en cours de specification
-2. **Cross-module :** Charger 05-cross-module si le module a des dependances identifiees en step-02
+1. **Par module :** Charger 03-data-ui pour chaque module en cours de spécification
+2. **Cross-module :** Charger 05-cross-module si le module a des dépendances identifiées en step-02
 
 ### Questions de relance
 
-Pour chaque reponse vague, utiliser :
+Pour chaque réponse vague, utiliser :
 - "Pouvez-vous me donner un exemple concret ?"
 - "Comment mesurez-vous cela aujourd'hui ?"
-- "Que se passe-t-il si cette regle n'est pas respectee ?"
-- "Qui est impacte par cette decision ?"
+- "Que se passe-t-il si cette règle n'est pas respectée ?"
+- "Qui est impacté par cette décision ?"
 
 ### Filtre de pertinence
 
-Chaque question conservee passe ce test :
-> "La reponse change-t-elle quelque chose dans le systeme a construire ?"
+Chaque question conservée passe ce test :
+> "La réponse change-t-elle quelque chose dans le système a construire ?"
 > Oui -> Conserver | Non -> Supprimer

package/templates/skills/business-analyse/references/consolidation-structural-checks.md

@@ -89,6 +89,21 @@ FOR each entity in analysis.entities[]:
   IF endpoints.length === 0 -> ERROR: "Entity {entity.name} has NO endpoints — missing controller"
 ```
 
+## H. Permission Granularity Check
+
+> Validates that section permission modes are respected in the generated permission data.
+
+```
+FOR each module:
+  FOR each section in anticipatedSections[]:
+    IF section.sectionType == "view" OR section.permissionMode == "inherit":
+      IF section has own permissions in seedDataCore.permissions[] -> WARNING: "Section '{code}' is type 'view' but has own permissions — should inherit from module"
+    IF section.permissionMode == "read-only":
+      IF section has create/update/delete permissions -> ERROR: "Section '{code}' is read-only but has write permissions"
+    IF section.sectionType == "primary" AND NOT section.permissionMode:
+      -> WARNING: "Primary section '{code}' missing explicit permissionMode — defaulting to 'crud'"
+```
+
 ## Result Aggregation
 
 ```json
@@ -100,6 +115,8 @@ FOR each entity in analysis.entities[]:
     { "check": "id-uniqueness", "module": "...", "status": "PASS|ERROR", "details": "..." },
     { "check": "wireframe-layout", "module": "...", "status": "PASS|ERROR", "details": "..." },
     { "check": "seeddata-translations", "module": "...", "status": "PASS|ERROR", "details": "..." }
+    ,
+    { "check": "permission-granularity", "module": "...", "status": "PASS|WARNING|ERROR", "details": "..." }
   ]
 }
 ```

package/templates/skills/business-analyse/references/spec-auto-inference.md

@@ -34,13 +34,18 @@
 
 > **RULE:** Sections = functional zones only. `create`/`edit` are separate pages with own URL routes (`/create` and `/:id/edit`). `detail` is a tabbed page reached from `list`.
 
-| featureType | Sections (functional zones) | List page includes | Form pages | Detail page tabs |
-|---|---|---|---|---|
-| data-centric | list | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations} |
-| workflow | list, approve | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
-| integration | list | grid, filters, config button | `/create` page, `/:id/edit` page | Infos, Config, Logs |
-| reporting | dashboard | — | — | — |
-| full-module | list, dashboard | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
+| featureType | Sections (functional zones) | permissionMode | List page includes | Form pages | Detail page tabs |
+|---|---|---|---|---|---|
+| data-centric | list | `crud` | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations} |
+| data-centric | (detail — implicit) | `inherit` | — | — | — |
+| workflow | list | `crud` | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
+| workflow | approve | `custom:approve,reject` | — | — | — |
+| integration | list | `crud` | grid, filters, config button | `/create` page, `/:id/edit` page | Infos, Config, Logs |
+| reporting | dashboard | `read-only` | — | — | — |
+| full-module | list | `crud` | grid, filters, create button | `/create` page, `/:id/edit` page | Infos, {relations}, Historique |
+| full-module | dashboard | `read-only` | — | — | — |
+
+> **RULE:** `detail` is NEVER a section with its own permission set. It is always `sectionType: view`, `permissionMode: inherit`. Detail pages inherit permissions from their parent module.
 
 ## Component Generation Rules
 

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -239,7 +239,7 @@ Determine the language for analysis and code generation.
 
 **Check config:**
 - Retrieve `language` from `.business-analyse/config.json`
-- Default: "fr" (Francais)
+- Default: "fr" (Français)
 
 **If not in config:**
 ```
@@ -247,7 +247,7 @@ Ask via AskUserQuestion:
   question: "Quelle langue pour l'analyse ?"
   header: "Langue"
   options:
-    - label: "Francais (fr)"
+    - label: "Français (fr)"
     - label: "English (en)"
     - label: "Italiano (it)"
     - label: "Deutsch (de)"

package/templates/skills/business-analyse/steps/step-01-cadrage.md

@@ -32,16 +32,16 @@ Frame the analysis scope at the **application level** through an interactive con
 ## EXECUTION FLOW — 5 PHASES
 
 ```
-Phase 1: ECOUTE           → Read brief + codebase pre-research + silent pre-analysis
+Phase 1: ÉCOUTE           → Read brief + codebase pre-research + silent pre-analysis
 Phase 2: REFORMULATION     → Rephrase the need back to the client for validation
 Phase 3: APPROFONDISSEMENT → Challenge assumptions with targeted questionnaires
 Phase 4: ANTICIPATION      → Suggest unexpressed needs from domain expertise
-Phase 5: PERIMETRE         → Bound scope with roles, coverage matrix (sections + resources)
+Phase 5: PÉRIMÈTRE         → Bound scope with roles, coverage matrix (sections + resources)
 ```
 
 ---
 
-## PHASE 1: ECOUTE (Listen)
+## PHASE 1: ÉCOUTE (Listen)
 
 ### 1. Read Current State
 

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?
@@ -154,18 +168,18 @@ Write via ba-writer:
     {
       "code": "Employees",
       "applicationCode": "HumanResources",
-      "name": "Employes",
+      "name": "Employés",
       "featureType": "data-centric",
       "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" }] }
       ]
     }
   ],
   "dependencies": [
-    { "from": "Absences", "to": "Employees", "description": "Une absence reference un employe" }
+    { "from": "Absences", "to": "Employees", "description": "Une absence référence un employé" }
   ]
 }
 ```

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

@@ -44,18 +44,18 @@ For each entity identified in step 02:
 ```json
 {
   "name": "Employee",
-  "description": "Represente un employe de l'entreprise",
+  "description": "Représente un employé de l'entreprise",
   "attributes": [
     { "name": "code", "type": "string", "required": true, "description": "Identifiant unique" },
-    { "name": "userId", "type": "guid", "required": true, "description": "Reference vers l'utilisateur" },
-    { "name": "departmentId", "type": "guid", "required": true, "description": "Departement d'affectation" },
+    { "name": "userId", "type": "guid", "required": true, "description": "Référence vers l'utilisateur" },
+    { "name": "departmentId", "type": "guid", "required": true, "description": "Département d'affectation" },
     { "name": "hireDate", "type": "date", "required": true, "description": "Date d'embauche" },
-    { "name": "position", "type": "string", "description": "Poste occupe" },
-    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "description": "Statut de l'employe" }
+    { "name": "position", "type": "string", "description": "Poste occupé" },
+    { "name": "status", "type": "enum", "options": ["Active", "Inactive", "OnLeave", "Terminated"], "description": "Statut de l'employé" }
   ],
   "relationships": [
-    { "target": "Department", "type": "ManyToOne", "description": "Appartient a un departement" },
-    { "target": "Contract", "type": "OneToMany", "description": "Possede plusieurs contrats" }
+    { "target": "Department", "type": "ManyToOne", "description": "Appartient à un département" },
+    { "target": "Contract", "type": "OneToMany", "description": "Possède plusieurs contrats" }
   ]
 }
 ```
@@ -69,7 +69,7 @@ For each entity/process, identify rules:
   "id": "BR-VAL-EMPLOYEES-001",
   "name": "Validation date embauche",
   "category": "validation",
-  "statement": "La date d'embauche ne peut pas etre dans le futur",
+  "statement": "La date d'embauche ne peut pas être dans le futur",
   "example": "Date embauche = 2027-01-01 → erreur car > date du jour",
   "entities": ["Employee"],
   "severity": "blocking"
@@ -85,19 +85,19 @@ For each stakeholder action:
 ```json
 {
   "id": "UC-EMPLOYEES-001",
-  "name": "Creer un employe",
+  "name": "Créer un employé",
   "actor": "Responsable RH",
   "preconditions": ["L'utilisateur a la permission HumanResources.Employees.Create"],
   "steps": [
-    "L'utilisateur ouvre la page de creation",
-    "Il remplit les champs obligatoires (nom, departement, date embauche)",
+    "L'utilisateur ouvre la page de création",
+    "Il remplit les champs obligatoires (nom, département, date embauche)",
     "Il valide le formulaire",
-    "Le systeme verifie les regles metier (BR-VAL-EMPLOYEES-001)",
-    "Le systeme cree l'employe et affiche la fiche"
+    "Le système vérifie les règles métier (BR-VAL-EMPLOYEES-001)",
+    "Le système crée l'employé et affiche la fiche"
   ],
-  "alternative": "Si les donnees sont invalides, le systeme affiche les erreurs",
+  "alternative": "Si les données sont invalides, le système affiche les erreurs",
   "businessRules": ["BR-VAL-EMPLOYEES-001"],
-  "result": "L'employe est cree avec le statut 'Actif'"
+  "result": "L'employé est créé avec le statut 'Actif'"
 }
 ```
 
@@ -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);