@atlashub/smartstack-cli 4.17.1 → 4.19.0

package/templates/skills/ralph-loop/references/parallel-execution.md

@@ -63,7 +63,7 @@ git commit -m "chore(foundation): entities for all modules
 
 $(allModules.map(m => m.code).join(' + ')) — ${allEntities.length} entities
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
+Co-Authored-By: Claude AI <noreply@anthropic.com>"
 ```
 
 Result: ModelSnapshot contains all entities. Database ready for application layers.
@@ -159,7 +159,8 @@ DO NOT:
 - Modify DbContext (already done in Phase 0)
 
 EXECUTE:
-For each PRD file: invoke /apex -d {prdFile}
+For each PRD file:
+**INVOKE `/apex -d {prdFile}`**
 Apex will detect existing entities and skip domain/infrastructure layers.
 
 When done, send a message to team lead with results:
@@ -177,33 +178,32 @@ When done, send a message to team lead with results:
 
 ### 4. Wait for Teammates
 
-Ralph waits for all teammates to send completion messages:
+Ralph waits for all teammates to send completion messages via `TaskOutput`.
 
-```javascript
-const MAX_WAIT = 3600; // 1 hour timeout
-const POLL_INTERVAL = 5; // 5 seconds
-
-const teamMateResults = [];
-const deadline = Date.now() + MAX_WAIT * 1000;
-
-while (teamMateResults.length < teammates.length && Date.now() < deadline) {
-  // Check for new messages from teammates
-  const messages = getTeamMessages();
-  for (const msg of messages) {
-    if (msg.type === 'completion') {
-      teamMateResults.push(msg);
-      console.log(`  ✅ ${msg.teammate}: ${msg.status}`);
-    }
-  }
-  if (teamMateResults.length < teammates.length) {
-    sleep(POLL_INTERVAL * 1000);
-  }
-}
+> **How messaging works in Claude Code Agent Teams:**
+> - Teammates communicate by calling `SendMessage({ recipient: "team-lead", content: ... })`
+> - Ralph (team lead) receives messages automatically — there is NO polling loop
+> - Each message delivery triggers a new turn for Ralph
+> - Ralph stays idle between messages — this is normal behavior (not a hang)
+> - An idle notification does NOT mean the teammate has finished or failed
 
-if (teamMateResults.length < teammates.length) {
-  console.error(`TIMEOUT: ${teammates.length - teamMateResults.length} teammates did not complete`);
-  // Set status to 'partial'
-}
+```javascript
+// Track expected completions (set before spawning)
+const expectedCount = teammates.length;
+const results = []; // populated as SendMessage notifications arrive
+
+// Ralph's response to each incoming message:
+// - Parse content: "complete" | "failed"
+// - Push to results[]
+// - If results.length === expectedCount → proceed to section 5
+// - If "failed": log error, continue waiting for other teammates
+
+// If a teammate goes silent > 30 min:
+// → Send it a wake-up message (idle is normal, silence is not)
+// → If no response after 2 retries: mark as "timed-out" and continue
+
+console.log(`Waiting for ${expectedCount} teammates...`);
+// (Ralph is idle here — woken up by each incoming SendMessage)
 ```
 
 ### 5. Collect & Validate Results

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -91,21 +91,31 @@ Quick: `glob('.ralph/prd-*.json').length > 1` → create modules-queue.json
 
 ---
 
-## 4c. Team Orchestration (multi-module, 2+ modules)
+## 4c. Team Orchestration (multi-module LEGACY — dependency layer mode only)
+
+> **MANDATORY:** Load `references/team-orchestration.md` BEFORE creating any team.
+> The full spawn protocol (teammate prompts, wait logic, layer coordination, cleanup)
+> is defined there. Creating a team without loading it results in an empty team with no teammates.
+
+> **PARALLEL MODE (`-p`):** Team creation does NOT happen here. It happens in step-02 section 3a,
+> after step-01 loads the tasks. Sections 5-7 below (completion promise, metadata, summary) must
+> still be executed. Do NOT return early when `{parallel_mode}` is true.
 
 ```javascript
 if (PRD_COUNT > 1) {
-  // Read references/team-orchestration.md for full protocol
+  // STEP 1: Load references/team-orchestration.md NOW (before any TeamCreate call)
+  // This file contains: mode selection, Phase 0 protocol (parallel), layer protocol (legacy), cleanup.
+
   const layers = master.metadata?.workflow?.dependencyGraph?.layers;
 
-  if (layers) {
-    // PARALLEL MODE: Use Agent Teams
-    TeamCreate({ team_name: `ralph-${appName}` });
-    // Spawn teammates per layer (see reference)
-    // STOP here — team orchestration takes over
+  if (layers && !{parallel_mode}) {
+    // DEPENDENCY LAYER MODE (legacy, no -p flag): team orchestration takes over here.
+    // TeamCreate + spawn logic are defined in references/team-orchestration.md section "Dependency Layer Mode".
+    // STOP here — legacy team orchestration handles everything from this point.
     return;
   }
-  // If no layers: fall through to sequential mode
+  // PARALLEL MODE (-p): fall through to sections 5-7, team created later in step-02 section 3a.
+  // NO -p, NO layers: fall through to sequential mode (compact loop per module).
 }
 ```
 
@@ -123,7 +133,7 @@ if (!completion_promise) {
 ## 6. Collect Metadata
 
 ```bash
-CLI_VERSION=$(node -e "console.log(require('package.json').version)" 2>/dev/null || echo "unknown")
+CLI_VERSION=$(node -e "try{console.log(require('./package.json').version)}catch(e){console.log('unknown')}" 2>/dev/null || echo "unknown")
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
 PROJECT_PATH=$(pwd)
 ```

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -58,16 +58,24 @@ If `.ralph/prd.json` exists:
 
 If `.ralph/prd.json` does not exist: continue to section 1b.
 
-### 1b. BA Handoff Quality Gate (BLOCKING)
+### 1b. BA Handoff Quality Gate (BLOCKING when BA artifacts present)
 
 > **CRITICAL:** Before generating ANY tasks, verify the BA handoff is complete.
 > A missing handoff means no frontend files, no test plan, no BR-to-code mapping.
 
+> **INTENTIONAL SKIP:** If `sourceFeatureJson` is null (manual start via `{task_description}`, no BA run),
+> this quality gate is **intentionally skipped** — the loop proceeds in "manual mode" and generates tasks
+> from the task description. This is by design, not a bug. Inform the user in the summary (section 6 of step-00).
+
 ```javascript
 const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
   || findFile('docs/business/**/business-analyse/**/feature.json');
 
-if (sourceFeatureJson) {
+if (!sourceFeatureJson) {
+  // Manual mode: no BA artifacts found — skip quality gate
+  console.log('Manual mode: no BA artifacts detected — tasks will be generated from task description');
+  // Continue to section 2 (Analyze Task Description)
+} else {
   const feature = readJSON(sourceFeatureJson);
   const handoff = feature.handoff || {};
 
@@ -75,13 +83,13 @@ if (sourceFeatureJson) {
   if (handoff.status !== 'handed-off') {
     console.error(`BLOCKING: BA HANDOFF INCOMPLETE
 handoff.status = "${handoff.status || 'missing'}" (expected "handed-off")
-Run /business-analyse to complete the handoff, then re-run /ralph-loop.`);
+Run /derive-prd to generate the handoff, then re-run /ralph-loop.`);
     STOP;
   }
 
   // CHECK 2: filesToCreate must have all categories
   const filesToCreate = handoff.filesToCreate || {};
-  const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+  const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
   const missingInHandoff = requiredCategories.filter(c => !filesToCreate[c] || filesToCreate[c].length === 0);
 
   if (missingInHandoff.length > 0) {

package/templates/skills/ralph-loop/steps/step-02-execute.md

@@ -93,11 +93,16 @@ if (prd._sectionSplit?.enabled) {
     : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (services + controllers + pages + tests)`;
   console.log(`SECTION SPLIT: ${phaseLabel}`);
 
-  // INVOKE /apex -d {nextPhase.prdFile}
-  // Apex sees a normal (smaller) PRD and executes normally
+  // ↓ MANDATORY: invoke apex now (not pseudo-code — execute this skill call)
+```
+
+**INVOKE `/apex -d {nextPhase.prdFile}`**
 
-  // After apex returns: merge results into master PRD
-  // Read references/section-splitting.md sections 7-9 (execution, merging, failure handling)
+Apex sees a focused (smaller) PRD covering only this phase's scope and executes normally.
+After apex returns: merge results into master PRD.
+Read `references/section-splitting.md` sections 7-9 for execution, merging, and failure handling.
+
+```javascript
 
   nextPhase.status = 'completed';
   prd._sectionSplit.currentPhase = nextPhase.phase;

package/templates/skills/ralph-loop/steps/step-03-commit.md

@@ -52,7 +52,7 @@ chore(ralph): PRD state — iteration {iteration}, {completed}/{total} tasks
 
 Module: {current_module}
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+Co-Authored-By: Claude AI <noreply@anthropic.com>
 EOF
 )"
 

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -47,9 +47,12 @@ fi
 
 ### 1.7. Category Completeness Check (RUNS EVERY ITERATION)
 
-See `references/category-completeness.md` for detailed implementation.
+> **Implementation:** See `references/category-completeness.md` for the full `checkCategoryCompleteness()` function and artifact verification logic.
+> Do NOT duplicate the implementation here — load and execute the reference.
 
 ```javascript
+// Load references/category-completeness.md — execute checkCategoryCompleteness() as defined there
+// (includes guardrail injection AND artifact verification)
 const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
 
 if (guardrailsNeeded.length > 0) {
@@ -57,26 +60,7 @@ if (guardrailsNeeded.length > 0) {
   writeJSON('.ralph/prd.json', prd);
   console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${prd.tasks.filter(t => t.status === 'pending').length} pending tasks`);
 }
-
-// Artifact verification (check if completed tasks have files)
-const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
-const artifactChecks = {
-  'frontend': () => glob.sync('**/src/pages/**/*.tsx').length > 0,
-  'test': () => glob.sync('tests/**/*Tests.cs').length > 0,
-  'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0
-};
-for (const [cat, check] of Object.entries(artifactChecks)) {
-  if (completedCats.has(cat) && !check()) {
-    console.warn(`ARTIFACT MISSING: ${cat} tasks marked completed but no files found — resetting to pending`);
-    prd.tasks.filter(t => t.category === cat && t.status === 'completed')
-      .forEach(t => {
-        t.status = 'pending';
-        t.error = 'Artifacts missing — re-execute';
-        t.completed_at = null;
-      });
-    writeJSON('.ralph/prd.json', prd);
-  }
-}
+// Artifact verification is handled inside checkCategoryCompleteness() — see reference file.
 ```
 
 ## 2. Check Iteration Limit

package/templates/skills/ralph-loop/steps/step-05-report.md

@@ -131,13 +131,18 @@ Write to `.ralph/reports/{feature-slug}.md`:
 
 ```javascript
 // Clean up section-split temporary files
-if (prd._sectionSplit?.enabled) {
+// GUARD: only delete if the overall PRD status is 'completed'.
+// If status is 'partial' or 'failed', keep temporary PRD files so the user
+// can resume with `-r` — deleting them here would make recovery impossible.
+if (prd._sectionSplit?.enabled && prd.status === 'completed') {
   for (const phase of prd._sectionSplit.phases) {
     if (fileExists(phase.prdFile) && phase.prdFile !== '.ralph/prd.json') {
       deleteFile(phase.prdFile);
     }
   }
   delete prd._sectionSplit;
+} else if (prd._sectionSplit?.enabled && prd.status !== 'completed') {
+  console.log(`Section-split temp files preserved (status: ${prd.status}) — use /ralph-loop -r to resume`);
 }
 
 prd.updated_at = new Date().toISOString();

package/templates/skills/apex/references/agent-teams-protocol.md

@@ -1,203 +0,0 @@
-# Agent Teams Protocol — APEX
-
-> **Loaded by:** step-01 (analysis scan) and step-03 (parallel execution)
-> **Condition:** NOT economy_mode
-> **Purpose:** Reusable protocol for TeamCreate, coordination, and shutdown.
-
----
-
-## Team Creation (T08)
-
-```yaml
-TeamCreate:
-  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-layer2", "apex-layer3"
-  description: "{phase purpose}"      # e.g., "Scan SmartStack project for existing code"
-```
-
-Always provide both `team_name` and `description`.
-
----
-
-## Teammate Spawning (T12)
-
-```yaml
-Task:
-  subagent_type: "Explore" | "general-purpose"  # See assignment table below
-  team_name: "apex-{phase}"          # Must match TeamCreate
-  name: "{teammate-name}"            # e.g., "scan-backend", "entity-employee"
-  model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
-  mode: "bypassPermissions"
-  prompt: "{detailed task prompt}"
-```
-
-### Model & Agent Assignment (T02/T03/T06)
-
-| Task Type | subagent_type | Model | Justification |
-|-----------|---------------|-------|---------------|
-| Scan/read files | Explore | Sonnet | Read-only (Glob, Grep, Read) |
-| Read context (PRD, feature.json) | Explore | Sonnet | Read-only extraction |
-| Code development | general-purpose | Opus | Full tools via skills/MCP |
-| Fix/resolve | general-purpose | Opus | Requires reasoning + editing |
-
----
-
-## Task List Coordination (T10)
-
-### Task Creation (by team lead, BEFORE spawning teammates)
-
-Tasks MUST be created upfront for the full layer scope:
-
-```
-FOR EACH entity in layer:
-  TaskCreate(
-    subject: "Layer {N}: {Entity} {layer_type}",
-    description: "{detailed scope: files, skills, MCP tools}",
-    activeForm: "{Building/Creating} {Entity} {layer_type}"
-  )
-```
-
-### Task Assignment (by team lead, WHEN spawning)
-
-Include task ID and metadata context in teammate prompt:
-
-```
-"Your assigned task ID is {task_id}.
- Your metadata context: entities={entities}, layer={layer}, tools={tools}.
- Call TaskUpdate(taskId: '{task_id}', status: 'in_progress') before starting.
- Call TaskUpdate(taskId: '{task_id}', status: 'completed', metadata: { files_created: [...] }) after ENTITY_COMPLETE message."
-```
-
-### Task Monitoring (by team lead)
-
-```
-1. TaskList() — check progress after each teammate message
-2. All tasks completed → proceed to build gate
-3. Any task stuck → investigate, reassign if needed
-```
-
----
-
-## Communication (T09)
-
-**Default:** Direct messages (DM) between specific agents.
-
-```yaml
-SendMessage:
-  type: "message"                    # DM, not broadcast
-  recipient: "{teammate-name}"       # By name, not UUID
-  content: "{message}"
-  summary: "{5-10 word preview}"
-```
-
-**Broadcast:** ONLY for emergency (all-stop, critical blocker).
-
-```yaml
-SendMessage:
-  type: "broadcast"                  # Expensive: N teammates = N deliveries
-  content: "{urgent message}"
-  summary: "{critical issue summary}"
-```
-
----
-
-## Team Decomposition (C01)
-
-### Step-01 Analyze: Split by scan scope
-
-```
-scan-backend  : Domain/ + Infrastructure/ + Application/ + Api/
-scan-frontend : src/pages/ + src/components/ + src/locales/
-scan-context  : .ralph/ + docs/business/
-```
-
-### Step-03 Execute: Split by entity WITHIN a layer
-
-> **Cross-layer parallelism is FORBIDDEN.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
-> Agent teams parallelize **multi-entity work within a single layer.**
-
-```
-Layer 2 (Backend) — if multiple entities:
-  entity-{name1} : Service + DTO + Controller for Entity1
-  entity-{name2} : Service + DTO + Controller for Entity2
-  ...
-
-Layer 3 (Frontend) — if multiple entities:
-  entity-{name1} : Pages + i18n + routes for Entity1
-  entity-{name2} : Pages + i18n + routes for Entity2
-  ...
-```
-
-Each teammate has an **isolated scope** (C02): handles one entity end-to-end within the layer.
-
----
-
-## Coordination (C03)
-
-### Step-01: Lead aggregates scan results
-
-```
-1. Spawn 3 scan teammates
-2. Each reports findings via DM to lead
-3. Lead merges into unified analysis
-```
-
-### Step-03: Lead verifies between ALL 5 layers
-
-```
-1. Layer 0: lead executes (domain + infra + migration)
-2. Build gate: dotnet build → MUST PASS
-3. Layer 1: lead executes (seed data — sequential, no teams)
-4. Build gate: dotnet build → MUST PASS
-5. Layer 2: spawn entity teammates (if multi-entity) OR lead executes (if single entity)
-6. Build gate: dotnet build → MUST PASS
-7. Backend tests inline (scaffold + run + fix max 3)
-8. Layer 3: spawn entity teammates (if multi-entity) OR lead executes (if single entity)
-9. Compliance gate: 5 frontend checks → MUST PASS
-10. Frontend tests inline (scaffold + run + fix max 3)
-11. Layer 4 (optional): lead executes DevData
-```
-
----
-
-## Idle Handling (T13)
-
-Teammates go idle after every turn — this is **normal**.
-- Idle does NOT mean done or unavailable
-- Sending a message to an idle teammate wakes them up
-- Do NOT treat idle as an error
-
----
-
-## Graceful Shutdown (T11)
-
-After phase completes:
-
-```yaml
-# For each teammate:
-SendMessage:
-  type: "shutdown_request"
-  recipient: "{teammate-name}"
-  content: "Phase complete, shutting down"
-
-# Teammate responds:
-SendMessage:
-  type: "shutdown_response"
-  request_id: "{from_request}"
-  approve: true
-
-# After all confirmations:
-TeamDelete
-```
-
----
-
-## Decision Matrix
-
-| Condition | Action |
-|-----------|--------|
-| economy_mode = true | NO teams, all sequential |
-| Single entity (any layer) | NO teams, agent principal handles all |
-| Multiple entities, Layer 2 | Teams: one teammate per entity (service + controller) |
-| Multiple entities, Layer 3 | Teams: one teammate per entity (pages + i18n) |
-| Layer 0, Layer 1, Layer 4 | NO teams (sequential by nature) |
-| Analysis phase (step-01) | Teams: scan-backend + scan-frontend + scan-context |

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

@@ -1,124 +0,0 @@
-# Business Analysis - SmartStack Architecture Reference (_architecture.md)
-
-> **Loaded by:** step-01-cadrage, step-03a-data, step-05a-handoff
-> **Purpose:** Provide architectural context for relevant questions and aligned recommendations
-
----
-
-## 5 Couches (Clean Architecture)
-
-| Couche | Projet | Contenu | Impact BA |
-|--------|--------|---------|-----------|
-| **Domain** | `SmartStack.Domain` | Entites, enums, interfaces | Entites identifiees en discovery |
-| **Application** | `SmartStack.Application` | CQRS (Commands/Queries), validations, DTOs | Use cases de la specification |
-| **Infrastructure** | `SmartStack.Infrastructure` | EF Core, services externes, jobs | Integrations et contraintes techniques |
-| **API** | `SmartStack.API` | Controllers REST, permissions | Endpoints et securite |
-| **Web** | `smartstack-web` | React 19, pages, composants | UI/UX et navigation |
-
----
-
-## Classes de Base des Entites
-
-| Classe | Interface | Champs auto-inclus | Quand utiliser |
-|--------|-----------|---------------------|----------------|
-| `BaseEntity` | - | `Id` (Guid), `TenantId`, `CreatedAt`, `UpdatedAt` | **Defaut pour toute entite metier** |
-| `BaseEntity` | `IAuditableEntity` | + `CreatedBy`, `UpdatedBy` | Entite avec audit complet |
-| `SystemEntity` | - | `Id` (Guid), `CreatedAt` (pas de TenantId) | Entites systeme (navigation, permissions) |
-| `BaseEntity` | `ISoftDeletable` | + `IsDeleted`, `DeletedBy`, `DeletedAt` | Entite avec suppression logique |
-| `HierarchicalEntity` | - | + `ParentId`, `Level`, `Path` | Arborescences (categories, menus) |
-| `BaseEntity + UserId FK` | `ITenantEntity` | + `UserId` (Guid FK to User) | Person Role Extension — entity represents a person linked to User. Use `isPersonRole: true` in scaffold_extension. |
-
-> **IMPORTANT :** Ne JAMAIS proposer `CreatedBy`, `UpdatedBy`, `IsDeleted`, `TenantId` comme champs explicites — ils sont AUTOMATIQUES via la classe de base ou l'interface.
-
----
-
-## Services d'Integration Disponibles
-
-| Service | Interface | Quand le proposer |
-|---------|-----------|-------------------|
-| Notifications in-app | `INotificationService` | Alertes, evenements, rappels |
-| Workflow automatise | `IWorkflowService` | Emails transactionnels, webhooks, actions chainees |
-| Completion IA | `IAICompletionService` | Suggestions, classification, generation contenu |
-| SignalR temps reel | `IHubContext<BusinessHub>` | Mises a jour en temps reel |
-| Jobs planifies | Hangfire `IBackgroundJobClient` | Traitements differes, purges, imports |
-
----
-
-## Conventions Base de Donnees
-
-| Aspect | Convention | Exemple |
-|--------|------------|---------|
-| Schema | `core` (socle SmartStack) vs `extensions` (entites client/metier) | `core.auth_Roles`, `nav_Applications`, `supp_Tickets` |
-| Tables | `{prefix}_{EntityPlural}` (prefixe domaine + PascalCase pluriel) | `auth_Users`, `nav_Applications`, `supp_Tickets` |
-| Prefixes domaine | `auth_`, `nav_`, `cfg_`, `ref_`, `wkf_`, `ai_`, `loc_`, `lic_`, `tenant_`, `support_` | Pour un nouveau module metier : choisir un prefixe court (3-5 chars) |
-| FK | `{Entity}Id` (ex: `ClientId`, `OrderId`) | |
-| Index | `IX_{Table}_{Column}` | `IX_bik_FreeBickes_TenantId_Code` |
-| Migration | 1 migration par feature, nommee via MCP (`suggest_migration`) | `extensions_v1.0.0_001_AddFreeBicke` |
-
----
-
-## Conventions de Dossiers (Clean Architecture)
-
-| Couche | Pattern de dossiers | Exemple (module FreeBicke dans business > operations) |
-|--------|--------------------|---------------------------------------------------------|
-| **Domain** | `{Project}.Domain/Business/{Application}/{Module}/` | `Domain/Business/Operations/FreeBicke/FreeBicke.cs` |
-| **Application/DTOs** | `{Project}.Application/Business/{Application}/{Module}/DTOs/` | `Application/Business/Operations/FreeBicke/DTOs/FreeBickeDto.cs` |
-| **Application/Interfaces** | `{Project}.Application/Common/Interfaces/` | `Application/Common/Interfaces/IFreeBickeService.cs` |
-| **Infrastructure/Config** | `{Project}.Infrastructure/Persistence/Configurations/{Application}/{Module}/` | `Configurations/Operations/FreeBicke/FreeBickeConfiguration.cs` |
-| **Infrastructure/Services** | `{Project}.Infrastructure/Services/{Application}/{Module}/` | `Services/Operations/FreeBicke/FreeBickeService.cs` |
-| **Infrastructure/SeedData** | `{Project}.Infrastructure/Persistence/Seeding/Data/{Application}/{Module}/` | `Seeding/Data/Operations/FreeBicke/FreeBickeSeedData.cs` |
-| **API/Controllers** | `{Project}.Api/Controllers/Business/{Application}/` | `Controllers/Business/Operations/FreeBickeController.cs` |
-| **Frontend/Pages** | `web/src/pages/{application}/{module}/` | `pages/operations/freebicke/page.tsx` |
-| **Frontend/i18n** | `web/src/i18n/locales/{lang}/{module}.json` | `locales/fr/freebicke.json` |
-
-> **IMPORTANT :** Chaque module a son **propre sous-dossier** dans chaque couche. Ne JAMAIS mettre tous les fichiers a la racine d'une couche.
-
----
-
-## SeedData Core (Obligatoire pour chaque feature)
-
-> **Chaque nouvelle feature necessite des SeedData dans 5 fichiers core** pour etre fonctionnelle (navigation visible, permissions actives, roles assignes).
-
-| # | Fichier | Contenu | Mecanisme |
-|---|---------|---------|-----------|
-| 1 | `NavigationModuleConfiguration.cs` | Entree module dans `nav_Modules` (HasData) | EF Core Migration |
-| 2 | `NavigationTranslationConfiguration.cs` | Traductions du module (4 langues x chaque entite nav) | EF Core Migration |
-| 3 | `PermissionConfiguration.cs` | Permissions CRUD + wildcards dans `nav_Permissions` (HasData) | EF Core Migration |
-| 4 | `Permissions.cs` (Application layer) | Constantes compile-time pour `[RequirePermission]` | Code |
-| 5 | `RolePermissionConfiguration.cs` | Associations role-permission dans `auth_RolePermissions` (HasData) | EF Core Migration |
-
-**Roles par defaut pour chaque application (4 niveaux) :**
-
-| Role | Permissions | Description |
-|------|-------------|-------------|
-| **{App} Admin** | `{app}.*` (wildcard) | Acces complet a l'application |
-| **{App} Manager** | `read`, `create`, `update`, `assign` | Gestion complete sans suppression |
-| **{App} Contributor** | `read`, `create`, `update` | Contribution active |
-| **{App} Viewer** | `read` uniquement | Consultation seule |
-
-> **CRITIQUE :** Si les SeedData ne sont pas crees, le module sera invisible dans la navigation et les permissions retourneront 403.
-
----
-
-## Contraintes Non-Negociables
-
-| Contrainte | Detail |
-|------------|--------|
-| **Multi-tenant** | `TenantId` sur toute entite metier, isolation automatique |
-| **RBAC** | Permissions `{app}.{module}.{action}`, HasData pattern |
-| **CQRS** | Commands (write) et Queries (read) separes via MediatR |
-| **Validation** | FluentValidation pour toute commande |
-| **i18n** | 4 langues obligatoires (fr, en, it, de) |
-| **Soft Delete** | Pas de DELETE physique sauf purge RGPD planifiee |
-
----
-
-## Outils MCP Pertinents pour le BA
-
-| Phase BA | Outil MCP | Usage |
-|----------|-----------|-------|
-| Pre-research (01) | `analyze_extension_points` | Decouvrir modules/entites existants |
-| Pre-research (01) | `api_docs` | Consulter la documentation API existante |
-| Analyse (02) | `validate_conventions` | Verifier les noms d'entites proposes |
-| Specification (03) | `generate_permissions` | Generer la matrice de permissions |
-| Handoff (05) | `scaffold_extension` | Preparer le scaffolding |