@atlashub/smartstack-cli 3.2.0 → 3.3.0

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

@@ -0,0 +1,670 @@
+---
+name: step-03b-compile
+description: Module specification compilation, validation, HTML deployment, and loop decision
+model: opus
+next_step: steps/step-03a-specify.md OR steps/step-04-consolidation.md (conditional)
+---
+
+> **Context files:** `_shared.md` | `_module-loop.md`
+
+# Step 3b: Specification Compilation
+
+## MANDATORY EXECUTION RULES
+
+- ALWAYS use ULTRATHINK mode
+- This step COMPILES the specification from the interactive phase (step-03a) into feature.json
+- ALWAYS validate specification completeness before writing
+- ALL communication in `{language}`
+- NEVER skip per-module validation
+- **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
+  All IDs MUST include a module prefix to guarantee application-wide uniqueness.
+  The prefix is derived from the module code initials (2-4 chars):
+    UserManagement → UM | VehicleManagement → VM | PartsInventory → PI
+    RepairManagement → RM | MaintenanceSchedule → MS | DataSync → DS
+    Notifications → NT | Dashboard → DB | Orders → OR | Customers → CU
+
+  Patterns:
+    UC-{PREFIX}-{NNN}        → UC-RM-001, UC-PI-003
+    BR-{CAT}-{PREFIX}-{NNN}  → BR-VAL-RM-001, BR-CALC-PI-002
+    FR-{PREFIX}-{NNN}        → FR-RM-001
+    OBJ-{PREFIX}-{NNN}       → OBJ-RM-001
+    AC-{PREFIX}-{NNN}        → AC-RM-001
+    RISK-{PREFIX}-{NNN}      → RISK-RM-001
+
+  NEVER use bare IDs (UC-001, BR-VAL-001) in multi-module mode.
+- **SCHEMA CONFORMITY RULE:**
+  ALL data MUST fit within the defined feature-schema.json structure.
+  NEVER create custom top-level fields (KPIDefinitions, ChartConfigurations, etc.)
+  Dashboard modules MUST use specification.dashboards[] (it exists in the schema).
+  If truly needed, use specification.extensions: {} (additionalProperties: true).
+
+## YOUR TASK
+
+Compile all data collected in step-03a into the module feature.json: write specification (8a-8l), validate, update status, deploy incremental HTML, and decide loop continuation.
+
+---
+
+### 8. Full Specification
+
+Generate the complete specification for this module. **Each subsection below includes a STRUCTURE CARD showing the EXACT JSON format. Follow them precisely.**
+
+#### 8a. Actors
+
+Inherited from application roles → mapped to module permissions.
+
+> **STRUCTURE CARD: specification.actors[]**
+> ```json
+> {
+>   "role": "Sales Manager",
+>   "description": "Creates and approves orders",
+>   "permissions": [
+>     "business.{app}.{module}.read",
+>     "business.{app}.{module}.create",
+>     "business.{app}.{module}.update"
+>   ]
+> }
+> ```
+> **MANDATORY fields:** `role`, `permissions` (array of permission paths)
+> **FORBIDDEN fields:** Do NOT use `systemRole`. Use `permissions` array.
+
+#### 8b. Use Cases (UC-{PREFIX}-NNN)
+
+Per section: list, create, read, update, delete, approve, etc.
+
+> **STRUCTURE CARD: specification.useCases[]**
+> ```json
+> {
+>   "id": "UC-{PREFIX}-001",
+>   "name": "Create Order",
+>   "primaryActor": "Sales Representative",
+>   "permission": "business.{app}.{module}.create",
+>   "preconditions": ["Customer exists", "Products in stock"],
+>   "postconditions": ["Order created with Draft status"],
+>   "mainScenario": [
+>     "1. User navigates to creation form",
+>     "2. User fills in required fields",
+>     "3. System validates data (BR-VAL-{PREFIX}-001)",
+>     "4. System creates the record",
+>     "5. System displays confirmation"
+>   ],
+>   "alternativeScenarios": [
+>     { "name": "Validation failure", "steps": ["1. System detects invalid data", "2. System highlights errors"] }
+>   ],
+>   "errorScenarios": [
+>     { "name": "Server error", "steps": ["1. System shows error message", "2. Data preserved for retry"] }
+>   ],
+>   "linkedRules": ["BR-VAL-{PREFIX}-001", "BR-WF-{PREFIX}-002"]
+> }
+> ```
+> **MANDATORY fields:** `id`, `name`, `primaryActor`, `permission`, `mainScenario`, `linkedRules`
+> **FORBIDDEN fields:** Do NOT use `actor` (use `primaryActor`), `linkedBRs` (use `linkedRules`), `linkedFRs` (not in UC, FRs link to UCs instead)
+
+#### 8c. Functional Requirements (FR-{PREFIX}-NNN)
+
+Linked to BRs and UCs.
+
+> **STRUCTURE CARD: specification.functionalRequirements[]**
+> ```json
+> {
+>   "id": "FR-{PREFIX}-001",
+>   "statement": "System MUST validate customer budget before order creation",
+>   "priority": "must|should|could",
+>   "linkedRules": ["BR-VAL-{PREFIX}-001"],
+>   "linkedUseCases": ["UC-{PREFIX}-001"],
+>   "acceptanceCriteria": [
+>     "Order rejected if total > budget",
+>     "Error message displayed with remaining budget"
+>   ]
+> }
+> ```
+> **MANDATORY fields:** `id`, `statement`, `priority`, `linkedUseCases`
+> **FORBIDDEN fields:** Do NOT use `name`/`description` (use `statement` with System MUST/SHOULD/COULD format), `linkedUCs` (use `linkedUseCases`), `linkedBRs` (use `linkedRules`)
+
+#### 8d. Permission Matrix
+
+Roles × resources × operations with full paths.
+
+> **STRUCTURE CARD: specification.permissionMatrix**
+> ```json
+> {
+>   "permissions": [
+>     { "path": "business.{app}.{module}.read", "action": "read", "description": "View records" },
+>     { "path": "business.{app}.{module}.create", "action": "create", "description": "Create new records" },
+>     { "path": "business.{app}.{module}.update", "action": "update", "description": "Update existing records" },
+>     { "path": "business.{app}.{module}.delete", "action": "delete", "description": "Delete records" },
+>     { "path": "business.{app}.{module}.export", "action": "export", "description": "Export data" }
+>   ],
+>   "roleAssignments": [
+>     { "role": "{App} Admin", "permissions": ["business.{app}.{module}.read", "business.{app}.{module}.create", "business.{app}.{module}.update", "business.{app}.{module}.delete", "business.{app}.{module}.export"] },
+>     { "role": "{App} Manager", "permissions": ["business.{app}.{module}.read", "business.{app}.{module}.create", "business.{app}.{module}.update"] },
+>     { "role": "{App} Viewer", "permissions": ["business.{app}.{module}.read"] }
+>   ]
+> }
+> ```
+> **STRUCTURE:** Object with 2 arrays: `permissions[]` and `roleAssignments[]`
+> **FORBIDDEN:** Do NOT use a flat array with `resource`/`roles` fields. Always use the nested structure above.
+
+#### 8e. Navigation
+
+Module → Sections → Resources (levels 3-4-5 of the hierarchy).
+
+> **STRUCTURE CARD: specification.navigation**
+> ```json
+> {
+>   "entries": [
+>     { "level": "module", "code": "{module}", "labels": {"fr": "...", "en": "..."}, "route": "/business/{app}/{module}", "icon": "list" },
+>     { "level": "section", "code": "list", "labels": {"fr": "Liste", "en": "List", "it": "Elenco", "de": "Liste"}, "route": "/business/{app}/{module}/list", "icon": "list" },
+>     { "level": "section", "code": "dashboard", "labels": {"fr": "Dashboard", "en": "Dashboard"}, "route": "/business/{app}/{module}/dashboard", "icon": "chart-bar", "isNew": true }
+>   ]
+> }
+> ```
+
+#### 8f. SeedData Core
+
+5 MANDATORY typed arrays — each with structured objects, NOT flat strings or objects.
+
+> **STRUCTURE CARD: specification.seedDataCore**
+> ```json
+> {
+>   "navigationModules": [
+>     { "code": "{module}", "label": "{Module Name}", "icon": "list", "route": "/business/{app}/{module}", "parentCode": "{app}", "sort": 1 }
+>   ],
+>   "navigationTranslations": [
+>     { "moduleCode": "{module}", "language": "fr", "label": "..." },
+>     { "moduleCode": "{module}", "language": "en", "label": "..." },
+>     { "moduleCode": "{module}", "language": "it", "label": "..." },
+>     { "moduleCode": "{module}", "language": "de", "label": "..." }
+>   ],
+>   "permissions": [
+>     { "path": "business.{app}.{module}.read", "action": "read", "description": "View {module}" },
+>     { "path": "business.{app}.{module}.create", "action": "create", "description": "Create {module}" }
+>   ],
+>   "rolePermissions": [
+>     { "role": "{App} Admin", "permissionPath": "business.{app}.{module}.*" },
+>     { "role": "{App} Manager", "permissionPath": "business.{app}.{module}.read" }
+>   ],
+>   "permissionConstants": [
+>     { "constantName": "{Module}Read", "path": "business.{app}.{module}.read" },
+>     { "constantName": "{Module}Create", "path": "business.{app}.{module}.create" }
+>   ]
+> }
+> ```
+> **MANDATORY:** All 5 arrays must be present. Each element must be an object, NOT a string.
+> **FORBIDDEN:** Do NOT use `navigationModule` (singular string), `permissions` as flat string array, `rolePermissions` as flat object, `permissionsConstants` as comma-separated string.
+
+#### 8g. Gherkin Scenarios
+
+BDD acceptance tests per UC.
+
+> **STRUCTURE CARD: specification.gherkinScenarios[]**
+> ```json
+> {
+>   "feature": "{Module} Management",
+>   "scenarios": [
+>     {
+>       "name": "Create a new record with valid data",
+>       "tags": ["@{module}", "@create", "@smoke"],
+>       "given": ["An authenticated user with role Manager", "No existing record with code 'TEST-001'"],
+>       "when": ["The user fills the creation form", "The user submits the form"],
+>       "then": ["The record is created with Draft status", "A success message is displayed"]
+>     }
+>   ]
+> }
+> ```
+> **STRUCTURE:** Object with `feature` string + `scenarios[]` array. Each scenario has `given`, `when`, `then` as ARRAYS of strings.
+> **FORBIDDEN:** Do NOT use flat arrays of `{uc, scenario, given, when, then}` where given/when/then are single strings.
+
+#### 8h. Validations
+
+Field validation rules per entity.
+
+> **STRUCTURE CARD: specification.validations[]**
+> ```json
+> {
+>   "entity": "Order",
+>   "field": "amount",
+>   "rules": ["required", "decimal", "min:0.01", "max:999999.99"],
+>   "errorMessageKey": "validation.{module}.amount.invalid"
+> }
+> ```
+> **MANDATORY fields:** `entity`, `field`, `rules` (array), `errorMessageKey`
+> **FORBIDDEN fields:** Do NOT use `rule` (singular string) or `message` (use `errorMessageKey`).
+
+#### 8i. Business Messages
+
+Minimum 4: success, error CRUD, error validation, error permission.
+
+> **STRUCTURE CARD: specification.messages[]**
+> ```json
+> {
+>   "code": "{MODULE}-SUCCESS-CREATE",
+>   "type": "success|error|warning|info",
+>   "title": "Record Created",
+>   "message": "The record {code} has been created successfully.",
+>   "i18nKey": "message.{module}.created"
+> }
+> ```
+> **MANDATORY fields:** `code`, `type`, `message`, `i18nKey`
+> **FORBIDDEN:** Do NOT omit `title` or `i18nKey`. Every message MUST have an i18n key.
+
+#### 8j. Entity Lifecycle
+
+State machines for entities with status/state.
+**Note:** If depth = full and 3a-state was executed, lifeCycles are already defined. Verify completeness and add any missing states/transitions.
+
+> **STRUCTURE CARD: specification.lifeCycles[]**
+> ```json
+> {
+>   "entity": "Order",
+>   "field": "status",
+>   "initialState": "draft",
+>   "states": [
+>     { "id": "draft", "displayName": "Brouillon", "color": "gray", "allowedTransitions": ["submitted"], "isTerminal": false },
+>     { "id": "submitted", "displayName": "Soumis", "color": "blue", "allowedTransitions": ["approved", "rejected"], "isTerminal": false },
+>     { "id": "approved", "displayName": "Approuvé", "color": "green", "allowedTransitions": ["archived"], "isTerminal": false },
+>     { "id": "rejected", "displayName": "Rejeté", "color": "red", "allowedTransitions": [], "isTerminal": true },
+>     { "id": "archived", "displayName": "Archivé", "color": "purple", "allowedTransitions": [], "isTerminal": true }
+>   ],
+>   "transitions": [
+>     {
+>       "from": "draft", "to": "submitted", "action": "submit",
+>       "label": { "fr": "Soumettre", "en": "Submit" },
+>       "permission": "business.{app}.{module}.update",
+>       "guards": ["BR-VAL-{PREFIX}-001"],
+>       "effects": [{ "type": "notification", "target": "role:manager", "template": "{module}-submitted" }],
+>       "confirm": true
+>     }
+>   ]
+> }
+> ```
+> **MANDATORY:** `states` MUST be an array of OBJECTS with `id`, `displayName`, `color`, `allowedTransitions`, `isTerminal`. NEVER use flat string arrays.
+> **Colors:** gray (draft/new), blue (in-progress), green (active/approved), yellow (warning/pending), orange (review), red (error/rejected), purple (archived/terminal)
+> **FORBIDDEN:** Do NOT use `states: ["Active", "Inactive"]` (flat strings), `terminalStates` (use `isTerminal: true` on each state).
+
+#### 8k. API Endpoints
+
+RESTful routes following SmartStack patterns.
+
+> **STRUCTURE CARD: specification.apiEndpoints[]**
+> ```json
+> {
+>   "method": "GET|POST|PUT|PATCH|DELETE",
+>   "path": "/api/business/{app}/{module}",
+>   "permission": "business.{app}.{module}.read",
+>   "requestDto": "Get{Module}Query",
+>   "responseDto": "{Module}Dto[]",
+>   "description": "List all records with pagination and filters"
+> }
+> ```
+> **MANDATORY fields:** `method`, `path`, `permission`, `description`
+> **Recommended:** Include `requestDto` and `responseDto` for implementation clarity.
+
+#### 8l. i18n Keys
+
+Translation keys for all UI text (4 languages: fr, en, it, de).
+
+> **STRUCTURE CARD: specification.i18nKeys**
+> ```json
+> {
+>   "title": { "fr": "{Module}", "en": "{Module}", "it": "{Module}", "de": "{Module}" },
+>   "list": { "title": { "fr": "Liste", "en": "List" }, "empty": { "fr": "Aucun enregistrement", "en": "No records" } },
+>   "create": { "title": { "fr": "Nouveau", "en": "New" } },
+>   "detail": { "title": { "fr": "Détail", "en": "Detail" } },
+>   "buttons": { "create": { "fr": "Créer", "en": "Create" }, "edit": { "fr": "Modifier", "en": "Edit" }, "delete": { "fr": "Supprimer", "en": "Delete" } },
+>   "validation": { "required": { "fr": "Ce champ est requis", "en": "This field is required" } }
+> }
+> ```
+
+### 9. Per-Module Validation
+
+> **Fused from old step-03-validate.md, run INLINE after specification.**
+
+#### 9a. Completeness Checks
+
+| Section | Minimum | Status |
+|---------|---------|--------|
+| actors | 2 | PASS/FAIL |
+| useCases | 2 | PASS/FAIL |
+| functionalRequirements | 4 | PASS/FAIL |
+| permissionMatrix | 1 resource × 2 roles | PASS/FAIL |
+| entities | 1 | PASS/FAIL |
+| wireframes | 1 per section (BLOCKING) | PASS/FAIL |
+| gherkinScenarios | 2 per UC | PASS/FAIL |
+| validations | 1 | PASS/FAIL |
+| messages | 4 | PASS/FAIL |
+| lifeCycles | 1 (if entity has status) | PASS/FAIL |
+| seedDataCore | 5 sections present | PASS/FAIL (BLOCKING) |
+
+#### 9b. Consistency Checks
+
+- Every UC has ≥1 linked FR
+- Every FR has ≥1 linked BR
+- All BR references exist in analysis.businessRules
+- All actors appear in permissionMatrix
+- Permission paths use full format: `business.{app}.{module}.{resource}.{action}`
+- rolePermissions paths match permissions paths
+- API routes use consistent prefix
+
+#### 9c. Convention Checks
+
+- UC-NNN format
+- FR-NNN format
+- BR-{CATEGORY}-NNN format
+- Entity names PascalCase
+- Field names camelCase
+- Permission paths dot-separated lowercase
+
+#### 9d. Decision
+
+IF validation PASS:
+  Display summary, ask client for confirmation
+
+IF validation FAIL:
+  Display errors, offer:
+  ```
+  options:
+    - label: "Auto-corriger"
+      description: "Corriger automatiquement les erreurs détectées"
+    - label: "Réviser manuellement"
+      description: "Revenir aux sections problématiques"
+    - label: "Forcer la validation"
+      description: "Accepter malgré les erreurs (risqué)"
+  ```
+
+#### 9e. Write Module Validation Section (MANDATORY)
+
+> **The module feature.json MUST have a `validation` section recording the results of steps 9a-9d.**
+
+```
+ba-writer.enrichSection({
+  featureId: {module_feature_id},
+  section: "validation",
+  data: {
+    validatedAt: "{ISO timestamp}",
+    completenessChecks: [
+      { "section": "useCases", "count": {count}, "minimum": 2, "status": "PASS|FAIL" },
+      { "section": "functionalRequirements", "count": {count}, "minimum": 4, "status": "PASS|FAIL" },
+      { "section": "wireframes", "count": {count}, "minimum": {section_count}, "status": "PASS|FAIL" },
+      { "section": "seedDataCore", "count": 5, "minimum": 5, "status": "PASS|FAIL" }
+    ],
+    consistencyChecks: [
+      { "check": "UC-FR linkage", "passed": {n}, "warnings": {n}, "errors": {n}, "status": "PASS|FAIL" },
+      { "check": "BR references valid", "passed": {n}, "warnings": {n}, "errors": {n}, "status": "PASS|FAIL" },
+      { "check": "Permission path format", "passed": {n}, "warnings": {n}, "errors": {n}, "status": "PASS|FAIL" }
+    ],
+    conventionChecks: [
+      { "check": "ID naming with module prefix", "status": "PASS|FAIL", "details": "..." },
+      { "check": "Entity names PascalCase", "status": "PASS|FAIL", "details": "..." }
+    ],
+    semanticChecks: [
+      { "check": "orphan-permissions", "module": "{currentModule}", "status": "PASS|WARNING|ERROR", "details": "...", "autoFixed": false },
+      { "check": "uc-sans-fr", "module": "{currentModule}", "status": "PASS|WARNING|ERROR", "details": "...", "autoFixed": false },
+      { "check": "missing-wireframes", "module": "{currentModule}", "status": "PASS|WARNING|ERROR", "details": "...", "autoFixed": false }
+    ],
+    warnings: ["List of non-blocking warnings"],
+    decision: {
+      "approved": true,
+      "reason": "All checks passed",
+      "approvalMode": "standard",
+      "approvedBy": "Client",
+      "approvedAt": "{ISO timestamp}"
+    }
+  }
+})
+```
+
+### 10. Module Summary with Roles & Permissions
+
+Display comprehensive summary:
+
+```
+═══════════════════════════════════════════════════════════
+  MODULE SPÉCIFIÉ: {currentModule} ({currentModuleIndex + 1}/{total})
+═══════════════════════════════════════════════════════════
+
+| Aspect | Valeur |
+|--------|--------|
+| Entités | {count} ({entity names}) |
+| Business Rules | {count} (VAL: X, CALC: Y, WF: Z) |
+| Use Cases | {count} (UC-001 → UC-NNN) |
+| Exigences | {count} FRs |
+| Sections | {count} ({section names}) |
+| Maquettes | {count} wireframes |
+| Permissions | {count} paths |
+| Tests Gherkin | {count} scénarios |
+| Messages | {count} |
+
+### Rôles & Permissions pour {currentModule}
+| Rôle | Permissions |
+|------|------------|
+| {App} Admin | business.{app}.{module}.* |
+| {App} Manager | read, create, update, assign |
+| {App} Contributor | read, create, update |
+| {App} Viewer | read |
+
+→ Validation: {PASS/FAIL}
+═══════════════════════════════════════════════════════════
+```
+
+Ask via AskUserQuestion:
+
+```
+question: "Le module {currentModule} est-il correctement spécifié ?"
+header: "Module"
+options:
+  - label: "Validé"
+    description: "Passer au module suivant"
+  - label: "Réviser"
+    description: "Modifier des éléments du module"
+```
+
+### 11. Write Module Feature.json
+
+```
+// Write analysis section with ALL subsections
+ba-writer.enrichSection({
+  featureId: {module_feature_id},
+  section: "analysis",
+  data: {
+    objectives: [{id, objective, metric, target}],       // from 6a
+    entities: [{name, description, attributes, relationships}],  // from 6b — SCHEMA FORMAT
+    businessRules: [{id, name, category, statement, priority, conditions, examples, testability}],  // from 7 — SCHEMA FORMAT
+    processFlow: {entryPoints, mainFlow, decisionPoints, alternativeFlows},  // from 6c
+    dataLifecycle: {retentionPeriod, archiveStrategy, gdprCompliance, states}  // from 6d
+  }
+})
+
+// Write specification section with ALL subsections
+ba-writer.enrichSection({
+  featureId: {module_feature_id},
+  section: "specification",
+  data: {
+    actors: [{role, description, permissions}],                   // 8a
+    useCases: [{id, name, primaryActor, permission, mainScenario, linkedRules}],  // 8b
+    functionalRequirements: [{id, statement, priority, linkedRules, linkedUseCases, acceptanceCriteria}],  // 8c
+    permissionMatrix: {permissions: [], roleAssignments: []},     // 8d
+    navigation: {entries: []},                                    // 8e
+    seedDataCore: {navigationModules, navigationTranslations, permissions, rolePermissions, permissionConstants},  // 8f
+    gherkinScenarios: [{feature, scenarios: [{name, tags, given, when, then}]}],  // 8g
+    validations: [{entity, field, rules, errorMessageKey}],       // 8h
+    messages: [{code, type, title, message, i18nKey}],            // 8i
+    lifeCycles: [{entity, field, initialState, states: [{id, displayName, color, allowedTransitions, isTerminal}], transitions}],  // 8j
+    apiEndpoints: [{method, path, permission, requestDto, responseDto, description}],  // 8k
+    i18nKeys: {...},                                              // 8l
+    sections: [{code, labels, route, icon, permission, wireframe, useCases, businessRules, resources}],  // from 3a-bis
+    dashboards: [{code, title, kpis, filters, refreshMode}],     // from 3d
+    uiWireframes: [{screen, section, mockup, elements, actions, componentMapping, layout}]  // from 3b
+  }
+})
+
+// Write validation results from step 9
+// (Already written in step 9e above)
+
+ba-writer.updateStatus({module_feature_id}, "specified")
+
+// Update master
+ba-writer.updateModuleStatus({feature_id}, {currentModule.code}, "specified")
+```
+
+### 11-bis. Deploy Incremental Interactive HTML (MANDATORY)
+
+> **After each module is specified, deploy/update the interactive HTML document with all available data.**
+> This allows the client to review completed modules while the next module is being specified.
+> The HTML is incrementally enriched: after module 1, only module 1 specs appear; after module 2, both appear; etc.
+
+**Source:** `html/ba-interactive.html` (relative to skill root = `~/.claude/skills/business-analyse/html/`)
+
+**Destination:** `docs/business/{app}/business-analyse/v{version}/ba-interactive.html`
+
+**Steps:**
+
+1. **Read sources:**
+   - Read the HTML template from skill directory
+   - Read the master feature.json (application level — now updated with current module status)
+   - Read EACH completed module's feature.json (including the one just specified)
+
+2. **Build FEATURE_DATA object:**
+
+   > **Use the EXACT SAME mapping defined in step-05b-deploy.md section 3.**
+   > The mapping is identical — the only difference is that `moduleSpecs` only includes completed modules.
+   > Modules not yet specified will NOT appear in `moduleSpecs` (their entry in `modules[]` will show `status: "pending"`).
+
+   Follow step-05 section 9d "Step 2: Build FEATURE_DATA object" for the complete mapping pseudocode:
+   - `metadata`, `cadrage`, `modules[]`, `dependencies[]` → from master feature.json
+   - `moduleSpecs[moduleCode]` → only for modules with status "specified" (completed so far)
+   - `consolidation` → empty `{ interactions: [], e2eFlows: [] }` (not yet consolidated)
+   - `handoff` → empty `{}` (not yet handed off)
+
+3. **Replace placeholders in template:**
+   - Serialize the FEATURE_DATA object as JSON (2-space indentation)
+   - Replace `{{FEATURE_DATA}}` with the serialized JSON
+   - Replace `{{APPLICATION_NAME}}` → `{application_name}`
+   - Replace `{{APPLICATION_ID}}` → `{feature_id}`
+   - Replace `{{VERSION}}` → `{version}`
+   - Replace `{{CREATED_AT}}` → `{ISO timestamp}`
+
+4. **Write and confirm:**
+
+```
+✓ Interactive HTML updated (incremental):
+  Path: docs/business/{app}/business-analyse/v{version}/ba-interactive.html
+  Modules included: {completedModules.length}/{totalModules} specified
+    - {completedModule1}: {uc_count} UCs, {br_count} BRs, {entity_count} entities
+    - {completedModule2}: ...
+  Remaining: {pendingModules.join(', ')} (will be added after specification)
+  → Client can open in browser to review completed modules now.
+```
+
+> **WHY incremental?** The client doesn't have to wait until handoff to start reviewing.
+> While module 2 is being specified, the client can already give feedback on module 1.
+> Each incremental deployment OVERWRITES the previous HTML (latest state always).
+> The FINAL deployment at step-05 (handoff) will include consolidation and handoff data.
+
+---
+
+### 12. Loop Decision
+
+```
+ba-writer.advanceModuleLoop({feature_id})
+→ Increments currentModuleIndex
+→ Updates completedModules
+→ Updates currentModule
+
+IF currentModuleIndex < moduleOrder.length:
+  Display: "→ Module suivant: {nextModule} ({currentModuleIndex + 1}/{total})"
+  Load: steps/step-03a-specify.md
+
+IF currentModuleIndex >= moduleOrder.length:
+  Display: "═══ Tous les modules spécifiés! Passage à la consolidation... ═══"
+  ba-writer.updateStatus({feature_id}, "specified")
+  Load: steps/step-04-consolidation.md
+```
+
+---
+
+## SELF-VERIFICATION (MANDATORY before loading next step)
+
+Before proceeding to step-03a (next module) or step-04 (consolidation), VERIFY:
+
+1. **Module feature.json has specification section** with ALL sub-sections (actors, useCases, functionalRequirements, permissionMatrix, navigation, seedDataCore, gherkinScenarios, validations, messages, lifeCycles, apiEndpoints, i18nKeys, sections, uiWireframes)
+2. **Module feature.json status** = "specified" (set by section 11)
+3. **Master modules[].status** for this module = "specified" (set by section 11)
+4. **ba-interactive.html exists** and includes data for this module (set by section 11-bis)
+
+**IF any check fails → FIX before proceeding.** Do NOT advance the module loop with incomplete data.
+
+---
+
+## SINGLE-MODULE MODE
+
+When only 1 module in moduleOrder:
+
+- Same full specification flow
+- Skip cross-module references (section 5)
+- After validation → direct to step-04-consolidation.md (auto-consolidation)
+
+---
+
+## RESUME SUPPORT
+
+IF the step is resumed (e.g., after interruption):
+
+```
+Read metadata.workflow.currentModuleIndex
+Read metadata.workflow.currentModule
+→ Resume at the correct module
+→ If module has partial data, show what exists and continue from there
+```
+
+---
+
+## CONTEXT MANAGEMENT
+
+| Loaded | Not Loaded |
+|--------|------------|
+| _shared.md | Other module feature.json (full) |
+| feature-schema.json | Questionnaires not needed |
+| Questionnaires for this module | Templates |
+| Completed modules summary (100 lines max) | React viewer files |
+
+---
+
+## STATE VARIABLES
+
+| Variable | Description |
+|----------|-------------|
+| `{currentModule}` | Current module being specified |
+| `{currentModuleIndex}` | Index in moduleOrder |
+| `{completedModules}` | Array of already specified module codes |
+| `{module_feature_id}` | Feature ID for the module-level feature.json |
+
+---
+
+## SUCCESS METRICS
+
+- All sections walked through with client
+- ASCII mockups generated and validated for EVERY section (1 wireframe per section minimum)
+- Entities defined with business attributes
+- Business rules extracted and categorized
+- Per-module validation PASS
+- Client confirmed module specification
+- Module feature.json written
+- Master updated with module status
+- **Interactive HTML deployed/updated with completed module data (incremental)**
+- Loop advanced correctly
+
+## FAILURE MODES
+
+- Validation FAIL → offer auto-correct / manual revise / force
+- Client rejects → revise specific sections
+- Cross-module reference error → clarify with client
+- Interruption → resumable via workflow state
+
+---
+
+## NEXT STEP
+
+Conditional:
+
+- IF modules remaining → Load `steps/step-03a-specify.md`
+- IF all modules done → Load `steps/step-04-consolidation.md`