@atlashub/smartstack-cli 4.25.0 → 4.27.0

package/package.json

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

package/templates/agents/ba-writer.md

@@ -18,17 +18,18 @@ Write and update granular JSON files for project-level (multi-app), application-
 - Module-level: `docs/{app}/{module}/business-analyse/v{X.Y}/index.json` + thematic files
 
 **Thematic files (v2 granular architecture):**
-- `index.json` — metadata, version, hash manifest, module registry
-- `cadrage.json` — stakeholders, problem/vision, risks, acceptance criteria
-- `entities.json` — entity definitions with attributes and relationships
-- `rules.json` — business rules with categories and conditions
-- `usecases.json` — use cases and functional requirements
-- `permissions.json` — permission matrix and role assignments
-- `screens.json` — UI wireframes and navigation
-- `validation.json` — validation rules and consistency checks
-- `handoff.json` — complexity, file catalog, BR-to-code mapping
-- `consolidation.json` — cross-module interactions and E2E flows (application-level only)
-- `review.json` — preserved review comments and change summary
+- `index.json` — metadata, version, hash manifest, module registry (ALL scopes)
+- `cadrage.json` — stakeholders, problem/vision, risks, acceptance criteria (ALL scopes)
+- `validation.json` — validation rules and consistency checks (ALL scopes)
+- `consolidation.json` — cross-module interactions and E2E flows (application/project ONLY)
+- `navigation.json` — navigation tree (application/project ONLY, created by ba-design-ui)
+- `entities.json` — entity definitions with attributes and relationships (**MODULE ONLY**)
+- `rules.json` — business rules with categories and conditions (**MODULE ONLY**)
+- `usecases.json` — use cases and functional requirements (**MODULE ONLY**)
+- `permissions.json` — permission matrix and role assignments (**MODULE ONLY**)
+- `screens.json` — UI wireframes and navigation (**MODULE ONLY**)
+- `handoff.json` — complexity, file catalog, BR-to-code mapping (**MODULE ONLY**)
+- `review.json` — preserved review comments and change summary (ALL scopes)
 
 > **Backward compatibility:** If only 1 application, the project level is NOT created. The application-level index.json remains the master.
 
@@ -62,9 +63,12 @@ Create initial index.json and empty thematic files with metadata and draft statu
    - For project scope: modules: []
    - For application scope: modules: []
    - For module scope: (no modules array)
-5. Create empty thematic files appropriate for scope:
-   - Project/application: cadrage.json, entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, handoff.json, consolidation.json
-   - Module: discovery.json, analysis.json, specification.json, validation.json, handoff.json
+5. Create empty thematic files — ONLY the files listed for the scope. Creating ANY unlisted file is a **BLOCKING ERROR**.
+   - Project: cadrage.json, validation.json, consolidation.json — **EXACTLY 3 files, NO OTHERS**
+   - Application: cadrage.json, validation.json, consolidation.json — **EXACTLY 3 files, NO OTHERS**
+   - Module: entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, handoff.json — **EXACTLY 7 files**
+
+   **FORBIDDEN at project/application level:** entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json — these exist ONLY at module level.
 6. Update `.business-analyse/config.json` with new lastFeatureId
 7. IF scope = "module" AND applicationRef provided AND moduleCode provided:
    a. Read master index.json (via applicationRef FEAT-NNN)
@@ -107,7 +111,8 @@ Create a project-level index.json for multi-application analysis. Only used when
    - fileHashes: {}
    - applications: []
    - applicationDependencyGraph: {}
-5. Create thematic files (cadrage.json, entities.json, rules.json, usecases.json, permissions.json, screens.json, validation.json, consolidation.json)
+5. Create thematic files — **EXACTLY 3 files, NO OTHERS:** cadrage.json, validation.json, consolidation.json
+   **FORBIDDEN at project level:** entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json — these exist ONLY at module level.
 6. Update `.business-analyse/config.json` with new lastProjectId
 7. Deploy schemas to `docs/business-analyse/schemas/` (including project-schema.json)
 8. Return project ID (PROJ-NNN) and path
@@ -174,6 +179,10 @@ Write a complete thematic file and update its hash in index.json.
 
 **Process:**
 1. Find and read index.json (use findFeature if given ID)
+1b. **SCOPE GUARD (BLOCKING):** If index.json scope is "project" or "application", verify themeName is ALLOWED:
+    - Allowed: [cadrage, validation, consolidation, navigation, review]
+    - FORBIDDEN: [entities, rules, usecases, permissions, screens, handoff]
+    If themeName is FORBIDDEN → **REJECT with BLOCKING ERROR.** Do NOT create the file.
 2. Determine thematic filename: `{themeName}.json`
 3. Create full path: `{version_dir}/{themeName}.json`
 4. Write thematic file with pretty-print (2-space indent)
@@ -331,6 +340,20 @@ Increment the module loop counter in the master index.json.
 9. Write back index.json
 10. Return new index and whether loop is complete
 
+### cleanupAppLevelFiles
+Remove forbidden thematic files at project/application level and clean their entries from fileHashes.
+
+**Input:** featureId: FEAT-NNN
+
+**Process:**
+1. Read index.json (verify scope is "project" or "application")
+2. FORBIDDEN = [entities.json, rules.json, usecases.json, permissions.json, screens.json, handoff.json]
+3. For each FORBIDDEN file: if file exists in version directory → DELETE it
+4. For each FORBIDDEN file: if referenced in fileHashes → REMOVE entry
+5. If `files` property exists in index.json: remove entries for forbidden files
+6. Update metadata.updatedAt, write index.json
+7. Return list of cleaned files
+
 ### createVersion
 Create a new version for refactoring or major changes.
 
@@ -466,43 +489,29 @@ docs/business-analyse/
   v1.0/
     index.json                          ← PROJECT metadata
     cadrage.json
-    entities.json
-    rules.json
-    usecases.json
-    permissions.json
-    screens.json
     validation.json
     consolidation.json
+    # NO entities/rules/usecases/permissions/screens/handoff — MODULE ONLY
 
 docs/{app}/business-analyse/
   v1.0/
     index.json                          ← APPLICATION metadata
     cadrage.json
-    entities.json
-    rules.json
-    usecases.json
-    permissions.json
-    screens.json
     validation.json
     consolidation.json
-  v1.1/
-    index.json
-    cadrage.json
-    entities.json
-    ...
+    navigation.json                     ← (created by ba-design-ui)
+    # NO entities/rules/usecases/permissions/screens/handoff — MODULE ONLY
 
 docs/{app}/{module}/business-analyse/
   v1.0/
     index.json                          ← MODULE metadata
-    discovery.json
-    analysis.json
-    specification.json
+    entities.json
+    rules.json
+    usecases.json
+    permissions.json
+    screens.json
     validation.json
     handoff.json
-  v1.1/
-    index.json
-    discovery.json
-    ...
 ```
 
 Versions are stored as separate directories. Each directory contains index.json + thematic files.
@@ -722,11 +731,6 @@ if (estimatedNewSize > 500 * 1024) {  // 500KB
   "fileHashes": {
     "index.json": "pqr678...",
     "cadrage.json": "stu901...",
-    "entities.json": "vwx234...",
-    "rules.json": "yza567...",
-    "usecases.json": "bcd890...",
-    "permissions.json": "efg123...",
-    "screens.json": "hij456...",
     "validation.json": "klm789...",
     "consolidation.json": "nop012..."
   },

package/templates/project/appsettings.json.template

@@ -7,10 +7,8 @@
     "FailOnMigrationError": true,
     "EnableDevSeeding": false,
     "CorsOrigins": [
-      "http://localhost:5173",
-      "http://localhost:5174",
-      "http://localhost:5175",
-      "http://localhost:6173"
+      "http://localhost:3000",
+      "http://localhost:5173"
     ]
   },
   "Jwt": {
@@ -34,7 +32,7 @@
       "SecretExpiresAt": "",
       "CallbackPath": "/api/auth/google/callback"
     },
-    "FrontendUrl": "http://localhost:6173"
+    "FrontendUrl": "http://localhost:3000"
   },
   "Session": {
     "IdleTimeoutMinutes": 20,
@@ -125,7 +123,7 @@
     "Provider": "Development",
     "FromEmail": "noreply@{{ProjectDomain}}",
     "FromName": "{{ProjectName}}",
-    "BaseUrl": "http://localhost:5173",
+    "BaseUrl": "http://localhost:3000",
     "TokenExpiration": {
       "EmailConfirmation": "24:00:00",
       "PasswordReset": "01:00:00"

package/templates/skills/apex/SKILL.md

@@ -149,6 +149,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 - **Parallel Agent tool** - Parallel execution for scan (step-01) and within Layer 2/3 (step-03) for multi-entity, unless economy_mode
 - **Tests inline** - Backend tests run after Layer 2, frontend tests run after Layer 3 (max 3 fix iterations each). Step-07 = final sweep (security + coverage).
 - **Exception: seed data** — The templates in core-seed-data.md and person-extension-pattern.md are generated directly because no MCP tool covers seed data creation. This is a documented exception to the "orchestrate, never generate" rule.
+- **Frontend pages: ALWAYS via Skill("ui-components")** — economy_mode affects parallelization only, NOT whether /ui-components is called. NEVER generate .tsx pages directly, even in delegate or economy mode.
 - **Save outputs** if `{save_mode}` = true
 - **Commits per layer** - Atomic commits after each execution layer
 - **Delegate mode** (`-d`): Read PRD context, skip challenge questions, auto+economy mode implied. Used when `/ralph-loop` delegates code generation to `/apex`.

package/templates/skills/apex/references/challenge-questions.md

@@ -82,8 +82,25 @@ questions:
     multiSelect: true
 ```
 
+**Reserved codes (NOT valid sections):**
+- `detail` — auto-generated as `/:id` route when "list" section exists
+- `create` — auto-generated as `/create` route when "list" section exists
+- `edit` — auto-generated as `/:id/edit` route when "list" section exists
+
+These are **view modes**, not sections. A "list" section automatically generates 4 pages: ListPage (index), DetailPage (/:id), CreatePage (/create), EditPage (/:id/edit).
+
 **Validation:**
 ```
+RESERVED_SECTION_CODES = ["detail", "create", "edit"]
+
+IF any section.code IN RESERVED_SECTION_CODES:
+  DISPLAY: "'{section.code}' is a view mode, not a section.
+    The 'list' section automatically includes detail (/:id), create (/create),
+    and edit (/:id/edit) pages. Remove '{section.code}' from your sections."
+  → Remove the offending section(s) from the list
+  → Re-ask the sections question if {sections}.length == 0
+  → DO NOT proceed
+
 IF {sections}.length == 0:
   DISPLAY: "Every module must have at least one section. Please select or define at least one."
   → Re-ask the sections question

package/templates/skills/apex/references/post-checks.md

@@ -117,6 +117,21 @@ if [ -n "$APP_TSX" ]; then
 fi
 ```
 
+### POST-CHECK S7: Controllers must NOT use Guid.Empty for tenantId/userId (OWASP A01)
+
+```bash
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  BAD_GUID=$(grep -Pn 'Guid\.Empty' $CTRL_FILES 2>/dev/null)
+  if [ -n "$BAD_GUID" ]; then
+    echo "BLOCKING (OWASP A01): Controller uses Guid.Empty — tenant isolation bypassed"
+    echo "$BAD_GUID"
+    echo "Fix: Use _currentTenant.TenantId from ICurrentTenantService"
+    exit 1
+  fi
+fi
+```
+
 ---
 
 ## Backend — Entity, Service & Controller Checks
@@ -154,6 +169,39 @@ fi
 
 ## Frontend — CSS, Forms, Components, I18n
 
+### POST-CHECK C3a: Frontend must not be empty if Layer 3 was planned (BLOCKING)
+
+```bash
+# If foundation_mode is false AND App.tsx exists, verify frontend was generated
+APP_TSX=$(find web/ src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Check if applicationRoutes is an empty object
+  EMPTY_ROUTES=$(grep -P "applicationRoutes.*=\s*\{[\s/]*\}" "$APP_TSX" 2>/dev/null)
+  if [ -n "$EMPTY_ROUTES" ]; then
+    echo "BLOCKING: applicationRoutes in App.tsx is empty — Layer 3 frontend was NOT executed"
+    echo "Expected: at least one application key with route definitions"
+    echo "Fix: Run Layer 3 (scaffold_routes + scaffold_extension + route wiring)"
+    exit 1
+  fi
+
+  # Check pages/ directory is not empty
+  PAGE_COUNT=$(find web/ src/ -path "*/pages/*" -name "*.tsx" -not -path "*/node_modules/*" 2>/dev/null | wc -l)
+  if [ "$PAGE_COUNT" -eq 0 ]; then
+    echo "BLOCKING: No page components found in pages/ directory"
+    echo "Fix: Generate pages via scaffold_extension or /ui-components"
+    exit 1
+  fi
+
+  # Check navRoutes.generated.ts exists
+  NAV_ROUTES=$(find web/ src/ -name "navRoutes.generated.ts" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+  if [ -z "$NAV_ROUTES" ]; then
+    echo "BLOCKING: navRoutes.generated.ts not found — scaffold_routes was never called"
+    echo "Fix: Run scaffold_routes(source: 'controllers', outputFormat: 'applicationRoutes')"
+    exit 1
+  fi
+fi
+```
+
 ### POST-CHECK C3: Translation files must exist for all 4 languages (if frontend)
 
 ```bash

package/templates/skills/apex/steps/step-03-execute.md

@@ -290,6 +290,24 @@ When launching agents for multi-entity layers:
 - Agent principal updates activeForm after each entity completion:
   `TaskUpdate(taskId: layer2_task_id, activeForm: "Building {EntityName} backend (2/5 entities)")`
 
+### Controller NavRoute Attribute (MANDATORY)
+
+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]`
+- When calling `scaffold_extension(type: "controller")`, always pass `navRoute` in options
+- This is REQUIRED for `scaffold_routes` to auto-detect routes in Layer 3
+
+```bash
+# Quick check: all controllers must have [NavRoute] (not just [Route])
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+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
+done
+```
+
 ### Post-Layer 2 Build Gate
 
 ```bash
@@ -377,7 +395,18 @@ For each module:
   → All business applications use `<AppLayout />` as layout wrapper
   → See `references/frontend-route-wiring-app-tsx.md` for full Pattern A/B detection and examples
   → Verify: `mcp__smartstack__validate_frontend_routes (scope: 'routes')`
-- Pages: use /ui-components skill — follow smartstack-frontend.md patterns:
+- Pages per section: When a section exists (e.g., "list"), generate ALL 4 page types:
+  → {Section}ListPage.tsx (index route)
+  → {Section}DetailPage.tsx (/:id route) — click on list item navigates here
+  → Create{Section}Page.tsx (/create route)
+  → Edit{Section}Page.tsx (/:id/edit route)
+  "detail" is NEVER a separate section — it's the /:id route of the list section.
+- Pages: **MANDATORY — INVOKE Skill("ui-components")** for ALL page generation.
+  ⚠ BLOCKING REQUIREMENT: You MUST call Skill("ui-components") for EVERY page (.tsx).
+  NEVER generate .tsx page code directly. NEVER write page content in Agent prompts.
+  NEVER use Write tool to create pages without first calling Skill("ui-components").
+  The skill loads the full style guide + patterns (entity-card, data-table, dashboard-chart, grid-layout).
+  Follow smartstack-frontend.md patterns:
   → React.lazy() for all page imports (named export wrapping)
   → `<Suspense fallback={<PageLoader />}>` around all lazy components
   → Page structure: hooks → useEffect(load) → loading → error → content
@@ -466,7 +495,21 @@ IF NOT economy_mode AND entities.length > 1:
   # All agents launched in parallel
 
 ELSE:
-  # Agent principal handles all entities sequentially
+  # Economy mode: Agent principal handles all entities SEQUENTIALLY.
+  # MANDATORY: You MUST still call Skill("ui-components") for page generation.
+  # economy_mode only disables parallel agents — it does NOT skip /ui-components.
+  For each entity (sequentially):
+    1. MCP scaffold_api_client
+    2. MCP scaffold_routes (outputFormat: 'applicationRoutes')
+    3. Wire routes to App.tsx (Pattern A/B — see references/frontend-route-wiring-app-tsx.md)
+    4. **INVOKE Skill("ui-components")** — pass entity context:
+       - Entity: {EntityName}, Module: {ModuleName}, App: {AppName}
+       - Page types: List, Detail, Create, Edit (+ Dashboard if applicable)
+       - "CSS: Use CSS variables ONLY — bg-[var(--bg-card)], text-[var(--text-primary)]"
+       - "Forms: Create/Edit are FULL PAGES with own routes (/create, /:id/edit)"
+       - "I18n: ALL text uses t('namespace:key', 'Fallback')"
+    5. I18n: 4 JSON files (fr, en, it, de) + register namespace in i18n config
+    6. Form tests: co-located .test.tsx for Create and Edit pages
 ```
 
 ### Parallel Agents + TaskCreate Integration
@@ -495,6 +538,24 @@ When delegating to `/ui-components` skill, include explicit instructions:
 - "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`)."
 - "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."
 
+### HARD RULE — /ui-components is NON-NEGOTIABLE
+
+> **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT
+> a prior Skill("ui-components") call in this execution, the frontend layer is INVALID.
+>
+> **You MUST NOT:**
+> - Generate .tsx page code in Agent prompts and dispatch to Snipper agents
+> - Write page content directly via the Write tool
+> - Copy-paste page templates from your knowledge
+>
+> **You MUST:**
+> - Call Skill("ui-components") which loads the style guide, responsive guidelines,
+>   accessibility rules, and pattern files (entity-card, data-table, dashboard-chart, grid-layout, kanban)
+> - Let /ui-components generate all pages with correct conventions
+>
+> **Why this matters:** Without the skill, pages miss CSS variables, DataTable/EntityCard,
+> memo()/useCallback, responsive mobile-first design, and accessibility patterns.
+
 ### Frontend Tests Inline
 
 > **Tests are scaffolded and run WITHIN Layer 3, not deferred to step-07.**

package/templates/skills/ba-generate-html/references/data-build.md

@@ -63,11 +63,13 @@ const FEATURE_DATA = {
   ],
   moduleSpecs: {
     // CRITICAL: Must have ONE entry per module with ALL module data
+    // FLAT-FILE: Data comes from collected_data.modules[moduleCode] (flat files), NOT module index.json
     "{moduleCode}": {
-      useCases: module.specification.useCases || [],
-      businessRules: module.analysis.businessRules || [],
+      // const mod = collected_data.modules[moduleCode];
+      useCases: mod.usecases?.useCases || [],
+      businessRules: mod.rules?.rules || [],
       // ENTITY SAFETY NET: map fields[] → attributes[] if agent deviated from canonical format
-      entities: (module.analysis.entities || []).map(ent => ({
+      entities: (mod.entities?.entities || []).map(ent => ({
         name: ent.name,
         description: ent.description || "",
         attributes: (ent.attributes || []).length > 0
@@ -79,8 +81,8 @@ const FEATURE_DATA = {
           : (ent.fields || []).filter(f => f.foreignKey)
               .map(f => `${f.foreignKey.table} (N:1) - ${f.description || f.name}`)
       })),
-      permissions: module.specification.permissionMatrix?.permissions || [],
-      apiEndpoints: module.specification.apiEndpoints || []
+      permissions: mod.permissions?.matrix || mod.permissions?.permissions || [],
+      apiEndpoints: mod.usecases?.apiEndpoints || []
     }
   },
   consolidation: {
@@ -102,10 +104,15 @@ const FEATURE_DATA = {
 ### Build Process
 
 1. Extract metadata from master index.json
-2. Extract cadrage from master index.json (CONVERT scope keys)
-3. Extract stakeholders from master.stakeholders
+2. Extract cadrage from master cadrage.json (CONVERT scope keys)
+3. Extract stakeholders from master cadrage.stakeholders
 4. Iterate ALL modules and populate moduleSpecs (THIS IS CRITICAL — empty moduleSpecs = BUG)
-5. For EACH module, extract: useCases, businessRules, entities, permissions, apiEndpoints
+5. For EACH module, read FLAT FILES from `collected_data.modules[moduleCode]`:
+   - `entities.json` → entities
+   - `rules.json` → businessRules
+   - `usecases.json` → useCases
+   - `permissions.json` → permissions
+   - `screens.json` → wireframes
 6. Extract consolidation data (integrations, shared entities, E2E flows)
 7. Extract handoff section (complexity, strategy, module order, file counts)
 
@@ -119,10 +126,12 @@ const FEATURE_DATA = {
 const EMBEDDED_ARTIFACTS = {
   wireframes: {
     // PER-MODULE keyed object (NOT a flat array)
-    // FOR EACH module: extract from specification.uiWireframes[] OR specification.wireframes[] (SAFETY NET)
-    // IMPORTANT: The agent may write wireframes under either key name — always check BOTH
-    // Read from module JSON files
-    [moduleCode]: (moduleFeature.specification.uiWireframes || moduleFeature.specification.wireframes || []).map(wf => ({
+    // FLAT-FILE: Read from screens.json in each module directory (collected in step-01)
+    // const mod = collected_data.modules[moduleCode];
+    // const screens = mod.screens?.screens || [];
+    [moduleCode]: screens
+      .filter(s => s.wireframe || s.mockup || s.mockupFormat)
+      .map(wf => ({
       screen: wf.screen || wf.name || wf.title || wf.id || "",  // SAFETY NET: fallback name/title/id → screen
       section: wf.section || "",                      // e.g. "list"
       format: wf.mockupFormat || "ascii",             // RENAME: mockupFormat → format
@@ -160,7 +169,7 @@ const EMBEDDED_ARTIFACTS = {
 
 ### Artifact Gathering
 
-1. For EACH module: read `specification.uiWireframes[]` OR `specification.wireframes[]` (check BOTH keys — agent may use either), **rename fields** (`mockupFormat`→`format`, `mockup`/`ascii`/`content`→`content`, `screen`/`name`/`title`→`screen`), store under `wireframes[moduleCode]`
+1. For EACH module: read `screens.json` flat file from `collected_data.modules[moduleCode].screens`, filter screens with wireframe data, **rename fields** (`mockupFormat`→`format`, `mockup`/`ascii`/`content`→`content`, `screen`/`name`/`title`→`screen`), store under `wireframes[moduleCode]`
 2. Read master's `consolidation.e2eFlows[]` and build e2eFlows array with diagram generation
 3. Read master's `dependencyGraph` and build nodes/edges
 4. Serialize as JSON with 2-space indentation

package/templates/skills/ba-generate-html/references/data-mapping.md

@@ -93,29 +93,32 @@ Build a JSON object following this **exact mapping** from index.json to the HTML
 }
 ```
 
-### Module Specs Mapping
+### Module Specs Mapping (FLAT-FILE ARCHITECTURE)
 
 For EACH module in `master.modules[]`:
 
-1. Read the module index.json at `master.modules[i].featureJsonPath`
-2. Map to `moduleSpecs[moduleCode]`:
+1. Use flat file data from `collected_data.modules[moduleCode]` (loaded in step-01)
+2. Data sources: `entities.json`, `rules.json`, `usecases.json`, `permissions.json`, `screens.json`
+3. Do NOT read from `moduleIndex.specification` or `moduleIndex.analysis` — these don't exist in flat-file format
 
 ```javascript
+const mod = collected_data.modules[moduleCode];
+
 moduleSpecs[moduleCode] = {
-  useCases: (moduleFeature.specification?.useCases || []).map(uc => ({
+  useCases: (mod.usecases?.useCases || []).map(uc => ({
     name: uc.name,
     actor: uc.primaryActor,
     steps: (uc.mainScenario || []).join("\n"),           // array → newline-separated string
     alternative: (uc.alternativeScenarios || [])
       .map(a => a.name + ": " + (a.steps || []).join(", ")).join("\n")
   })),
-  businessRules: (moduleFeature.analysis?.businessRules || []).map(br => ({
+  businessRules: (mod.rules?.rules || []).map(br => ({
     name: br.name,
     category: br.category,                              // "validation"|"calculation"|"workflow"|"security"|"data"
     statement: br.statement,
     example: (br.examples || []).map(e => e.input + " → " + e.expected).join("; ")
   })),
-  entities: (moduleFeature.analysis?.entities || []).map(ent => ({
+  entities: (mod.entities?.entities || []).map(ent => ({
     name: ent.name,
     description: ent.description || "",
     attributes: (ent.attributes || []).map(a => ({
@@ -128,7 +131,7 @@ moduleSpecs[moduleCode] = {
       r.target + " (" + r.type + ") - " + (r.description || "")
     )
   })),
-  permissions: buildPermissionKeys(moduleFeature),      // see below
+  permissions: buildPermissionKeys(mod.permissions),    // see below
   notes: "",
   mockupNotes: ""  // Deprecated: wireframes now embedded separately in EMBEDDED_ARTIFACTS
 }
@@ -139,9 +142,10 @@ moduleSpecs[moduleCode] = {
 The HTML uses `"Role|Action"` format (e.g. `"RH Admin|Consulter"`):
 
 ```javascript
-function buildPermissionKeys(moduleFeature) {
+// Input: permissions object from flat file (mod.permissions), NOT moduleFeature
+function buildPermissionKeys(permissionsData) {
   const keys = [];
-  const matrix = moduleFeature.specification?.permissionMatrix;
+  const matrix = permissionsData?.matrix || permissionsData?.permissionMatrix;
   if (!matrix) return keys;
   const actionMap = { read: "Consulter", create: "Creer", update: "Modifier",
                       delete: "Supprimer", validate: "Valider", export: "Exporter",
@@ -207,25 +211,30 @@ Build a JSON object containing ALL visual artifacts from module JSON files (inde
 }
 ```
 
-### Wireframes Mapping
+### Wireframes Mapping (FLAT-FILE: from screens.json)
 
 For EACH module in `master.modules[]`:
 
 ```javascript
-// Read the module index.json file
-const moduleFeature = readModuleFeature(moduleCode);
-const wireframes = (moduleFeature.specification?.uiWireframes || []).map(wf => ({
-  screen: wf.screen,                                    // e.g. "UM-list", "UM-form"
-  section: wf.section,                                  // e.g. "list", "form"
-  format: wf.mockupFormat || "ascii",                   // "ascii" | "svg"
-  content: wf.mockup,                                   // ASCII art or SVG markup
-  description: wf.description || "",
-  elements: wf.elements || [],                          // ["DataGrid", "FilterBar", ...]
-  actions: wf.actions || [],                            // ["filter", "sort", "create", ...]
-  componentMapping: wf.componentMapping || [],          // [{ wireframeElement, reactComponent }]
-  layout: wf.layout || null,                            // { type, regions: [...] }
-  permissionsRequired: wf.permissionsRequired || []
-}));
+// Use flat file data from collected_data (loaded in step-01)
+const mod = collected_data.modules[moduleCode];
+const screens = mod.screens?.screens || [];
+
+// Extract wireframes from screens that have mockup/wireframe data
+const wireframes = screens
+  .filter(s => s.wireframe || s.mockup || s.mockupFormat)
+  .map(wf => ({
+    screen: wf.screen || wf.name || wf.id || "",        // e.g. "UM-list", "UM-form"
+    section: wf.section || "",                            // e.g. "list", "form"
+    format: wf.mockupFormat || "ascii",                   // "ascii" | "svg"
+    content: wf.mockup || wf.ascii || wf.content || "",   // ASCII art or SVG markup
+    description: wf.description || "",
+    elements: wf.elements || [],                          // ["DataGrid", "FilterBar", ...]
+    actions: wf.actions || [],                            // ["filter", "sort", "create", ...]
+    componentMapping: wf.componentMapping || [],          // [{ wireframeElement, reactComponent }]
+    layout: wf.layout || null,                            // { type, regions: [...] }
+    permissionsRequired: wf.permissionsRequired || []
+  }));
 
 // Store in artifacts object
 EMBEDDED_ARTIFACTS.wireframes[moduleCode] = wireframes;

package/templates/skills/ba-generate-html/steps/step-01-collect.md

@@ -51,7 +51,11 @@ ELSE:
     BLOCKING ERROR: "Feature status: {feature.status}, expected consolidated"
 ```
 
-### 4. Read All JSON Files
+### 4. Read All JSON Files (FLAT-FILE ARCHITECTURE)
+
+> **CRITICAL:** Module data lives in separate flat files (entities.json, usecases.json, etc.),
+> NOT inside index.json. The module index.json only contains metadata and file pointers.
+> You MUST read each flat file individually.
 
 ```
 collected_data = {
@@ -63,13 +67,18 @@ collected_data = {
 }
 
 FOR each module in master.index.modules[]:
-  moduleIndexPath = module.featureJsonPath || "{module.code}/business-analyse/v{version}/index.json"
-  moduleIndex = READ(moduleIndexPath)
+  // Resolve module directory path
+  moduleDir = "{app}/{module.code}/business-analyse/v{version}/"
+  moduleIndex = READ(moduleDir + "index.json")
 
+  // Read ALL flat files from module directory
   collected_data.modules[module.code] = {
     index: moduleIndex,
-    specification: moduleIndex.specification || {},
-    analysis: moduleIndex.analysis || {}
+    entities: READ(moduleDir + "entities.json") || { entities: [] },
+    rules: READ(moduleDir + "rules.json") || { rules: [] },
+    usecases: READ(moduleDir + "usecases.json") || { useCases: [] },
+    permissions: READ(moduleDir + "permissions.json") || { roles: [], permissions: [], matrix: [] },
+    screens: READ(moduleDir + "screens.json") || { screens: [] }
   }
 ```
 
@@ -78,7 +87,7 @@ FOR each module in master.index.modules[]:
 ```
 JSON collected:
   Master: index.json + cadrage.json
-  Modules: {module_count} module index files
+  Modules: {module_count} modules (flat files: entities, rules, usecases, permissions, screens)
 → Proceeding to data build...
 ```