@atlashub/smartstack-cli 2.7.0 → 2.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, APEX, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",
@@ -83,7 +83,7 @@
     "cli-table3": "^0.6.3",
     "commander": "^12.0.0",
     "fs-extra": "^11.2.0",
-    "glob": "^11.0.0",
+    "glob": "^13.0.1",
     "handlebars": "^4.7.8",
     "inquirer": "^9.2.12",
     "jsonwebtoken": "^9.0.3",

package/templates/agents/ba-writer.md

@@ -34,6 +34,7 @@ Create an initial feature.json with metadata and draft status.
    - If scope = "application": `docs/business/{app}/business-analyse/v1.0/`
    - If scope = "module": `docs/business/{app}/{module}/business-analyse/v1.0/`
 4. Generate initial feature.json with:
+   - **`$schema`**: relative path to the deployed schema file (MANDATORY — see $schema rules below)
    - id: FEAT-NNN (from config)
    - version: "1.0"
    - status: "draft"
@@ -221,6 +222,143 @@ Perform these structural checks before every write:
 - `metadata.workflow` must exist with mode, moduleOrder, currentModuleIndex
 - Each module in `modules[]` must have: code, description, status
 
+## Structural Schema Enforcement (MANDATORY)
+
+> **Before EVERY write**, validate field names against the expected schema structure below. REJECT writes containing FORBIDDEN fields. AUTO-MAP known mismatches when possible.
+
+### Module-Level Sections
+
+**analysis.entities[]** — REQUIRED fields: `name`, `description`, `attributes[]`, `relationships[]`
+- attributes[]: REQUIRED `name`, `description`, `required` | OPTIONAL `unique`, `validation`
+- relationships[]: REQUIRED `target`, `type`, `description`
+- FORBIDDEN: `type` in attributes (use `description`), `values` (use `validation`), `rules` (use `validation`)
+
+**analysis.businessRules[]** — REQUIRED: `id`, `name`, `category`, `statement`, `priority`
+- OPTIONAL: `conditions[]`, `examples[]`, `testability`
+- category values: `validation`, `calculation`, `workflow`, `security`, `data` (lowercase only)
+- FORBIDDEN: `rule` (use `name`+`statement`), `condition` singular (use `conditions[]`), `action` (use `statement` with IF/THEN/ELSE)
+- AUTO-MAP: `rule` → split into `name` (short) + `statement` (IF/THEN)
+
+**analysis.objectives[]** — REQUIRED: `id`, `description`, `measurable`
+
+**analysis.processFlow** — REQUIRED: `entryPoints[]`, `mainFlow[]`, `decisionPoints[]`
+- FORBIDDEN: `lifecycle` (that goes in specification.lifeCycles), flat step arrays
+
+**analysis.dataLifecycle** — REQUIRED: `retention`, `archival`, `deletion`, `gdprRelevant`
+
+**specification.useCases[]** — REQUIRED: `id`, `name`, `primaryActor`, `permission`, `preconditions[]`, `postconditions[]`, `mainScenario[]`
+- OPTIONAL: `alternativeScenarios[]`, `errorScenarios[]`, `linkedRules[]`
+- mainScenario[]: array of strings "1. Step description"
+- FORBIDDEN: `actor` (use `primaryActor`), `linkedBRs` (use `linkedRules`), `linkedFRs` (remove), `scenario` (use `mainScenario`)
+- AUTO-MAP: `actor` → `primaryActor`, `linkedBRs` → `linkedRules`
+
+**specification.functionalRequirements[]** — REQUIRED: `id`, `statement`, `priority`, `linkedUseCases[]`
+- OPTIONAL: `linkedRules[]`, `acceptanceCriteria[]`
+- priority values: `must`, `should`, `could`
+- FORBIDDEN: `name` (use `statement`), `description` (use `statement`), `linkedUCs` (use `linkedUseCases`), `linkedBRs` (use `linkedRules`)
+- AUTO-MAP: `name`/`description` → `statement`, `linkedUCs` → `linkedUseCases`, `linkedBRs` → `linkedRules`
+
+**specification.permissionMatrix** — REQUIRED shape: `{permissions[], roleAssignments[]}`
+- permissions[]: `{path, action, description}`
+- roleAssignments[]: `{role, permissions[]}`
+- FORBIDDEN: flat array with `resource`/`roles` fields, top-level `roles` key
+
+**specification.sections[]** — REQUIRED: `code`, `title`, `type`, `resources[]`, `wireframe`
+- resources[]: REQUIRED `code`, `type`, `entity`, `permission` | OPTIONAL `columnDefs[]`, `rowActions[]`, `defaultSort`, `defaultPageSize`, `emptyState`, `fields[]`, `formLayout`
+
+**specification.uiWireframes[]** — REQUIRED: `screen`, `section`, `mockup`, `componentMapping[]`, `layout`
+- componentMapping[]: `{wireframeElement, reactComponent}`
+- layout: `{type, regions[]}` where regions[]: `{id, position, span?, components[]}`
+- FORBIDDEN: wireframes without `layout` object
+
+**specification.lifeCycles[]** — REQUIRED: `entity`, `field`, `initialState`, `states[]`, `transitions[]`
+- states[]: REQUIRED `{id, displayName, color, allowedTransitions[], isTerminal}`
+- transitions[]: REQUIRED `{from, to, action, label, permission}` | OPTIONAL `guards[]`, `effects[]`, `confirm`
+- FORBIDDEN: flat string arrays for states (e.g., `["Active", "Inactive"]`), `terminalStates` as separate array
+
+**specification.seedDataCore** — REQUIRED 5 arrays: `navigationModules[]`, `navigationTranslations[]`, `permissions[]`, `rolePermissions[]`, `permissionConstants[]`
+- navigationModules[]: `{code, label, icon, route, parentCode, sort}`
+- navigationTranslations[]: `{moduleCode, language, label}` (4 languages: fr, en, nl, de)
+- permissions[]: `{path, action, description}`
+- rolePermissions[]: `{role, permissionPath}`
+- permissionConstants[]: `{constantName, path}`
+- FORBIDDEN: flat object, comma-separated strings, singular constants
+
+**specification.gherkinScenarios** — REQUIRED shape: `{feature, scenarios[]}`
+- scenarios[]: `{name, tags[], given[], when[], then[]}`
+- FORBIDDEN: flat array of scenario objects without wrapping `feature`
+
+**specification.validations[]** — REQUIRED: `entity`, `field`, `rule`, `errorMessageKey`
+- FORBIDDEN: missing `entity`, missing `errorMessageKey`
+
+**specification.messages[]** — REQUIRED: `code`, `type`, `title`, `i18nKey`
+- type values: `success`, `error`, `warning`, `info`
+- FORBIDDEN: missing `title`, missing `i18nKey`
+
+**specification.apiEndpoints[]** — REQUIRED: `method`, `path`, `description`, `permission`, `request`, `response`
+
+**specification.navigation** — REQUIRED: `entries[]` where each: `{code, label, icon, route, parentCode, sort}`
+
+**specification.i18nKeys[]** — REQUIRED: `key`, `fr`, `en`, `nl`, `de`
+
+**validation** — REQUIRED: `completenessChecks[]`, `consistencyChecks[]`, `semanticChecks[]`, `decision`
+- decision: `{approved, reason, checkedAt}`
+- semanticChecks[]: `{check, module?, status, details, autoFixed}`
+- status values: `PASS`, `WARNING`, `ERROR`
+
+**handoff** — REQUIRED: `complexity`, `filesToCreate`, `brToCodeMapping[]`, `apiEndpointSummary[]`, `prdFile`, `totalFiles`, `totalTasks`, `handedOffAt`
+- filesToCreate: REQUIRED 7 categories: `domain[]`, `application[]`, `infrastructure[]`, `api[]`, `frontend[]`, `seedData[]`, `tests[]`
+- brToCodeMapping[]: `{ruleId, files[], implementation}`
+- apiEndpointSummary[]: `{method, path, permission, linkedUC}`
+
+### Application-Level Sections
+
+**cadrage.stakeholders[]** — REQUIRED: `role`, `function`, `involvement`, `tasks[]`
+- OPTIONAL: `frequency`, `painPoints[]`
+- involvement values: `approver`, `decision-maker`, `consulted`, `informed`, `end-user`
+- FORBIDDEN: `expertise`, `systemRole`, `description` (use `function`)
+
+**cadrage.applicationRoles[]** — REQUIRED: `role`, `level`, `permissionPattern`
+- OPTIONAL: `description`
+- level values: `admin`, `manager`, `contributor`, `viewer`
+- FORBIDDEN: `permissions` array (use `permissionPattern` string), `isDefault`
+
+**cadrage.risks[]** — REQUIRED: `id`, `type`, `description`, `mitigation`
+- OPTIONAL: `probability`, `impact`, `priority`
+- id pattern: `RISK-NNN`
+- type values: `business`, `technical`, `organizational`
+- FORBIDDEN: `risk` as field name (use `description`), `severity` (use `priority`)
+
+**cadrage.acceptanceCriteria[]** — REQUIRED: `id`, `criterion`, `validated`
+- id pattern: `AC-NNN`
+
+**cadrage.coverageMatrix[]** — REQUIRED: `item`, `category`, `module`
+- OPTIONAL: `ucRef`, `notes`
+- category values: `mustHave`, `shouldHave`, `couldHave`, `outOfScope`, `implicit` (camelCase)
+- FORBIDDEN: `id` (no ID field), `feature` (use `item`), `priority` (use `category`)
+
+**cadrage.codebaseContext** — MUST be a string, NOT an object
+
+**modules[]** — REQUIRED: `code`, `description`, `featureType`, `dependencies[]`, `dependents[]`, `status`, `priority`, `sortOrder`, `entities[]`, `estimatedComplexity`
+- OPTIONAL: `featureJsonPath`
+- FORBIDDEN: missing `dependencies`/`dependents`/`sortOrder`
+
+**consolidation** — REQUIRED: `crossModuleInteractions[]`, `sharedEntities[]`, `permissionCoherence`, `e2eFlows[]`, `globalRiskAssessment[]`, `semanticChecks[]`, `decision`
+- crossModuleInteractions[]: `{fromModule, toModule, interactionType, description, entities[]}`
+- sharedEntities[]: `{entity, ownerModule, referencedBy[], sharedFields[]}`
+- decision: `{approved, reason, approvedBy, approvedAt}`
+- FORBIDDEN: nested `{fkReferences, sharedEntities, events}` in crossModuleInteractions, `clientApproval` string
+
+### Enforcement Process
+
+On EVERY `enrichSection()` call:
+1. **BEFORE WRITE:** Scan incoming data keys against the schema above
+2. **DETECT FORBIDDEN:** If any FORBIDDEN field found → attempt AUTO-MAP first
+3. **AUTO-MAP:** Rename known mismatches (e.g., `actor` → `primaryActor`, `rule` → `name`+`statement`)
+4. **REJECT:** If FORBIDDEN field found with no AUTO-MAP rule → BLOCK write, return error listing violations
+5. **VALIDATE REQUIRED:** If REQUIRED fields missing → BLOCK write, return error listing missing fields
+6. **LOG:** Record all auto-mappings and rejections in changelog[]
+
 ## Directory Structure
 
 ```
@@ -305,10 +443,31 @@ Before EVERY enrichSection() call for specification or handoff sections, validat
 - Block transitions that violate status workflow
 - Report missing featureId clearly
 
+## $schema Reference Rules (MANDATORY)
+
+> **Every feature.json MUST include a `$schema` field** pointing to the deployed schema file via relative path.
+> Schemas are deployed by step-00-init to: `docs/business/{app}/business-analyse/schemas/`
+
+**$schema paths by scope:**
+
+| Scope | Feature.json location | $schema value |
+|-------|----------------------|---------------|
+| application | `docs/business/{app}/business-analyse/v1.0/feature.json` | `"../schemas/application-schema.json"` |
+| module | `docs/business/{app}/{module}/business-analyse/v1.0/feature.json` | `"../../../business-analyse/schemas/feature-schema.json"` |
+
+**Rules:**
+- `$schema` is ALWAYS the FIRST field in feature.json (before `id`)
+- Path is RELATIVE from the feature.json file to the schemas directory
+- For application scope: go up 1 level (v1.0/) → into schemas/
+- For module scope: go up 3 levels (v1.0/ → business-analyse/ → {module}/) → into business-analyse/schemas/
+- If schemas directory not found → WARNING (schemas may not have been deployed by step-00)
+
 ## Example Feature.json Structure
 
+**Module-level:**
 ```json
 {
+  "$schema": "../../../business-analyse/schemas/feature-schema.json",
   "id": "FEAT-001",
   "version": "1.0",
   "status": "draft",
@@ -333,18 +492,28 @@ Before EVERY enrichSection() call for specification or handoff sections, validat
     }
   },
   "discovery": {},
-  "analysis": {
-    "businessRules": []
-  },
-  "specification": {
-    "useCases": [],
-    "functionalRequirements": [],
-    "entities": []
-  },
-  "validation": {
-    "testCases": []
-  },
+  "analysis": {},
+  "specification": {},
+  "validation": {},
   "handoff": {},
   "suggestions": []
 }
 ```
+
+**Application-level:**
+```json
+{
+  "$schema": "../schemas/application-schema.json",
+  "id": "FEAT-001",
+  "version": "1.0",
+  "status": "draft",
+  "scope": "application",
+  "metadata": { "..." },
+  "cadrage": {},
+  "modules": [],
+  "dependencyGraph": {},
+  "consolidation": {},
+  "suggestions": [],
+  "changelog": []
+}
+```

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

@@ -37,7 +37,8 @@ All BA outputs are stored in **two levels** of feature.json, enriched progressiv
 
 ### Application-Level (Master)
 **Path:** `docs/business/{app}/business-analyse/v{X.Y}/feature.json`
-**Schema:** `schemas/application-schema.json`
+**Schema:** `docs/business/{app}/business-analyse/schemas/application-schema.json` (deployed to project by step-00)
+**$schema:** `"../schemas/application-schema.json"` (relative in feature.json)
 
 | Step | Section enriched | Status after |
 |------|-----------------|--------------|
@@ -50,7 +51,8 @@ All BA outputs are stored in **two levels** of feature.json, enriched progressiv
 
 ### Module-Level (Per Module)
 **Path:** `docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
-**Schema:** `schemas/feature-schema.json`
+**Schema:** `docs/business/{app}/business-analyse/schemas/feature-schema.json` (deployed to project by step-00)
+**$schema:** `"../../../business-analyse/schemas/feature-schema.json"` (relative in feature.json)
 
 | Step | Section enriched | Status after |
 |------|-----------------|--------------|
@@ -64,7 +66,7 @@ All BA outputs are stored in **two levels** of feature.json, enriched progressiv
 - **ba-writer**: Writes/updates feature.json (create, enrichSection, updateStatus, createVersion, createApplicationFeature, advanceModuleLoop)
 - **ba-reader**: Reads feature.json (findFeature, readSection, answerQuestion, getSummaryForSkill, readApplicationContext, getCompletedModulesSummary)
 
-**Schemas:** `schemas/application-schema.json` (master) + `schemas/feature-schema.json` (module)
+**Schemas:** Deployed to project at `docs/business/{app}/business-analyse/schemas/` (9 files). Source: `schemas/` in skill directory. Every feature.json includes `$schema` relative reference.
 
 ---
 
@@ -324,12 +326,24 @@ docs/
 ├── business/
 │   └── {application}/
 │       ├── business-analyse/
+│       │   ├── schemas/                  ← JSON SCHEMAS (deployed by step-00)
+│       │   │   ├── feature-schema.json
+│       │   │   ├── application-schema.json
+│       │   │   ├── sections/
+│       │   │   │   ├── analysis-schema.json
+│       │   │   │   ├── discovery-schema.json
+│       │   │   │   ├── handoff-schema.json
+│       │   │   │   ├── metadata-schema.json
+│       │   │   │   ├── specification-schema.json
+│       │   │   │   └── validation-schema.json
+│       │   │   └── shared/
+│       │   │       └── common-defs.json
 │       │   └── v1.0/
-│       │       └── feature.json          ← APPLICATION master
+│       │       └── feature.json          ← APPLICATION master ($schema: ../schemas/application-schema.json)
 │       ├── {module1}/
 │       │   └── business-analyse/
 │       │       └── v1.0/
-│       │           └── feature.json      ← MODULE detail
+│       │           └── feature.json      ← MODULE detail ($schema: ../../../business-analyse/schemas/feature-schema.json)
 │       └── {module2}/
 │           └── business-analyse/
 │               └── v1.0/

package/templates/skills/business-analyse/schemas/sections/specification-schema.json

@@ -315,12 +315,14 @@
     },
     "lifeCycles": {
       "type": "array",
-      "description": "Per-entity state machines for entities with Status fields",
+      "description": "Per-entity state machines for entities with Status fields. Convention depth: states + allowedTransitions only. Full depth: + transitions with guards, permissions, effects.",
       "items": {
         "type": "object",
         "required": ["entity", "states"],
         "properties": {
           "entity": { "type": "string" },
+          "field": { "type": "string", "default": "status", "description": "Entity field that holds the state" },
+          "initialState": { "type": "string", "description": "State assigned on entity creation" },
           "states": {
             "type": "array",
             "items": {
@@ -330,10 +332,50 @@
                 "id": { "type": "string" },
                 "displayName": { "type": "string" },
                 "description": { "type": "string" },
+                "color": { "type": "string", "enum": ["gray", "blue", "green", "yellow", "orange", "red", "purple"], "description": "Badge color for UI rendering" },
                 "allowedTransitions": { "type": "array", "items": { "type": "string" } },
                 "isTerminal": { "type": "boolean", "default": false }
               }
             }
+          },
+          "transitions": {
+            "type": "array",
+            "description": "Detailed transition definitions (full depth). Links actions to permissions, guards (BR), and side effects.",
+            "items": {
+              "type": "object",
+              "required": ["from", "to", "action"],
+              "properties": {
+                "from": { "type": "string", "description": "Source state id" },
+                "to": { "type": "string", "description": "Target state id" },
+                "action": { "type": "string", "description": "Action verb (submit, approve, reject, cancel, archive)" },
+                "label": {
+                  "type": "object",
+                  "description": "i18n action label for UI button",
+                  "properties": {
+                    "fr": { "type": "string" },
+                    "en": { "type": "string" },
+                    "it": { "type": "string" },
+                    "de": { "type": "string" }
+                  }
+                },
+                "permission": { "type": "string", "description": "Required permission path for this transition" },
+                "guards": { "type": "array", "items": { "type": "string" }, "description": "BR-XXX references that must pass before transition" },
+                "effects": {
+                  "type": "array",
+                  "description": "Side effects triggered on successful transition",
+                  "items": {
+                    "type": "object",
+                    "required": ["type"],
+                    "properties": {
+                      "type": { "type": "string", "enum": ["notification", "email", "webhook", "field-update"], "description": "Effect type" },
+                      "target": { "type": "string", "description": "Target role, user field, or endpoint" },
+                      "template": { "type": "string", "description": "Notification/email template code" }
+                    }
+                  }
+                },
+                "confirm": { "type": "boolean", "default": false, "description": "Require user confirmation dialog before transition" }
+              }
+            }
           }
         }
       }

package/templates/skills/business-analyse/schemas/shared/common-defs.json

@@ -69,7 +69,31 @@
         "entity": { "type": "string", "description": "Primary entity this resource displays/edits" },
         "parentEntity": { "type": "string", "description": "Parent entity for child tables (e.g., RepairPart parent=Repair)" },
         "permission": { "type": "string", "description": "Permission required for this resource" },
-        "columns": { "type": "array", "items": { "type": "string" }, "description": "For SmartTable: visible columns" },
+        "columns": { "type": "array", "items": { "type": "string" }, "description": "For SmartTable: visible column names (convention depth). Use columnDefs for full depth." },
+        "columnDefs": {
+          "type": "array",
+          "description": "For SmartTable: typed column definitions (full depth). Overrides columns[] when present.",
+          "items": {
+            "type": "object",
+            "required": ["field"],
+            "properties": {
+              "field": { "type": "string", "description": "Entity attribute path (e.g., code, customer.name)" },
+              "label": {
+                "type": "object",
+                "description": "i18n column header (auto-inferred from entity attribute if omitted)",
+                "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "it": { "type": "string" }, "de": { "type": "string" } }
+              },
+              "format": { "type": "string", "enum": ["text", "number", "currency", "percent", "date", "date-relative", "badge", "boolean", "link"], "description": "Display format" },
+              "sortable": { "type": "boolean", "default": true },
+              "filterable": { "type": "boolean", "default": false },
+              "width": { "type": "integer", "description": "Column width in pixels (hint)" },
+              "clickAction": { "type": "string", "description": "Action on cell click (e.g., navigate:detail)" },
+              "colorMap": { "type": "string", "description": "For badge format: reference to lifeCycles (e.g., stateMachine:Repair) or inline object" },
+              "aggregation": { "type": "string", "enum": ["sum", "avg", "count", "min", "max"], "description": "Footer aggregation" },
+              "hidden": { "type": "boolean", "default": false, "description": "Hidden by default (user can show via column picker)" }
+            }
+          }
+        },
         "fields": {
           "type": "array",
           "description": "For SmartForm: form fields",
@@ -81,12 +105,81 @@
               "component": { "type": "string", "enum": ["Input", "TextArea", "Select", "MultiSelect", "DatePicker", "DateRangePicker", "NumberInput", "Toggle", "EntitySelect", "FileUpload", "RichText", "ColorPicker"] },
               "source": { "type": "string", "description": "Lookup table entity for Select/MultiSelect" },
               "required": { "type": "boolean" },
-              "validation": { "type": "string" }
+              "validation": { "type": "string" },
+              "default": { "type": ["string", "number", "boolean", "null"], "description": "Default value" },
+              "visibleWhen": { "type": "object", "description": "Conditional visibility: { field: value } or { field: [values] }", "additionalProperties": true },
+              "computedValue": { "type": "string", "description": "Formula for auto-calculated fields (e.g., SUM(parts.unitCost * parts.quantity))" },
+              "readOnly": { "type": "boolean", "default": false, "description": "Read-only computed field" },
+              "helpText": { "type": "string", "description": "Tooltip/help text for the field" }
+            }
+          }
+        },
+        "actions": { "type": "array", "items": { "type": "string" }, "description": "Row/item actions - simple list (convention depth). Use rowActions for full depth." },
+        "rowActions": {
+          "type": "array",
+          "description": "Conditional row actions (full depth). Overrides actions[] when present.",
+          "items": {
+            "type": "object",
+            "required": ["action"],
+            "properties": {
+              "action": { "type": "string", "description": "Action code (view, edit, delete, submit, approve)" },
+              "icon": { "type": "string", "description": "Lucide icon name" },
+              "permission": { "type": "string", "description": "Required permission (relative: read, update, delete)" },
+              "showWhen": { "type": "object", "description": "Show only when entity field matches value(s): { status: [\"draft\"] }", "additionalProperties": true },
+              "confirm": {
+                "oneOf": [
+                  { "type": "boolean" },
+                  { "type": "object", "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "it": { "type": "string" }, "de": { "type": "string" } }, "description": "i18n confirmation message" }
+                ],
+                "description": "Require confirmation dialog (true for default message, or i18n object)"
+              }
             }
           }
         },
-        "actions": { "type": "array", "items": { "type": "string" }, "description": "Row/item actions (view, edit, delete, etc.)" },
         "filters": { "type": "array", "items": { "type": "string" }, "description": "Available filter fields" },
+        "defaultSort": {
+          "type": "object",
+          "description": "Default sort configuration",
+          "properties": {
+            "field": { "type": "string" },
+            "direction": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }
+          }
+        },
+        "defaultPageSize": { "type": "integer", "default": 20, "description": "Default rows per page" },
+        "emptyState": {
+          "type": "object",
+          "description": "Empty state display when no data",
+          "properties": {
+            "icon": { "type": "string", "description": "Lucide icon name" },
+            "message": {
+              "type": "object",
+              "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "it": { "type": "string" }, "de": { "type": "string" } }
+            },
+            "createAction": { "type": "boolean", "default": false, "description": "Show a create button in empty state" }
+          }
+        },
+        "formLayout": {
+          "type": "object",
+          "description": "For SmartForm: form layout structure (tabs or sections)",
+          "properties": {
+            "type": { "type": "string", "enum": ["flat", "tabs", "sections"], "default": "flat" },
+            "tabs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["code", "label", "fields"],
+                "properties": {
+                  "code": { "type": "string" },
+                  "label": {
+                    "type": "object",
+                    "properties": { "fr": { "type": "string" }, "en": { "type": "string" }, "it": { "type": "string" }, "de": { "type": "string" } }
+                  },
+                  "fields": { "type": "array", "items": { "type": "string" }, "description": "Field names in this tab" }
+                }
+              }
+            }
+          }
+        },
         "kpis": { "type": "array", "items": { "type": "string" }, "description": "For KpiPanel: entity fields to display as KPIs" },
         "chartType": { "type": "string", "enum": ["bar", "line", "pie", "area", "donut", "stacked-bar"], "description": "For Chart resource" },
         "dataSource": { "type": "string", "description": "API endpoint or entity for data" }

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

@@ -349,6 +349,53 @@ docs_dir: "docs/business/{app}/{module}/business-analyse/v{version}"
 output_dir: same as docs_dir
 ```
 
+## Step 9-bis: Deploy JSON Schemas to Project (MANDATORY)
+
+> **The JSON Schemas MUST be present in the project alongside the generated feature.json files.**
+> Without schemas, feature.json files cannot be validated and have no structural reference.
+
+**Check if schemas already deployed:**
+```
+IF EXISTS docs/business/{app}/business-analyse/schemas/feature-schema.json:
+  Skip deployment (schemas already present)
+ELSE:
+  Deploy schemas
+```
+
+**Deploy all schema files from skill directory to project:**
+
+Source: `schemas/` (relative to skill root = `~/.claude/skills/business-analyse/schemas/`)
+Destination: `docs/business/{app}/business-analyse/schemas/`
+
+```
+Read and Write each file (preserving directory structure):
+
+docs/business/{app}/business-analyse/schemas/
+├── feature-schema.json              ← from schemas/feature-schema.json
+├── application-schema.json          ← from schemas/application-schema.json
+├── sections/
+│   ├── metadata-schema.json         ← from schemas/sections/metadata-schema.json
+│   ├── discovery-schema.json        ← from schemas/sections/discovery-schema.json
+│   ├── analysis-schema.json         ← from schemas/sections/analysis-schema.json
+│   ├── specification-schema.json    ← from schemas/sections/specification-schema.json
+│   ├── validation-schema.json       ← from schemas/sections/validation-schema.json
+│   └── handoff-schema.json          ← from schemas/sections/handoff-schema.json
+└── shared/
+    └── common-defs.json             ← from schemas/shared/common-defs.json
+```
+
+**Total: 9 files to deploy.**
+
+**Implementation:**
+1. Use Glob to find all `.json` files in `schemas/` directory (skill-relative)
+2. For each file, Read from skill directory and Write to project directory
+3. Preserve the subdirectory structure (sections/, shared/)
+
+**Store:**
+```yaml
+schemas_dir: "docs/business/{app}/business-analyse/schemas"
+```
+
 ## Step 10: Create Master feature.json
 
 Create the master feature document using ba-writer agent.
@@ -389,6 +436,7 @@ ba-writer.createApplicationFeature({
 **Result structure:**
 ```json
 {
+  "$schema": "../schemas/application-schema.json",
   "id": "{feature_id}",
   "version": "1.0",
   "status": "draft",

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

@@ -222,7 +222,75 @@ If a feature is in mustHave → it MUST have at least one UC in the correspondin
 
 ### 10. Write Cadrage to Feature.json
 
-Use ba-writer to enrich master feature.json:
+Use ba-writer to enrich master feature.json. **Follow the STRUCTURE CARDS below exactly.**
+
+> **STRUCTURE CARD: cadrage.stakeholders[]**
+> ```json
+> {
+>   "role": "Fleet Manager",
+>   "function": "Manages daily fleet operations",
+>   "involvement": "decision-maker",
+>   "tasks": ["Monitor vehicles", "Approve repairs", "Export reports"],
+>   "frequency": "Daily",
+>   "painPoints": ["Manual tracking in spreadsheets", "No real-time visibility"]
+> }
+> ```
+> **MANDATORY fields:** `role`, `function`, `involvement`, `tasks`
+> **involvement values:** `approver`, `decision-maker`, `consulted`, `informed`, `end-user`
+> **FORBIDDEN fields:** Do NOT use `expertise`, `systemRole`, `description` (use `function` instead).
+
+> **STRUCTURE CARD: cadrage.applicationRoles[]**
+> ```json
+> {
+>   "role": "{App} Admin",
+>   "description": "Full access to all modules",
+>   "level": "admin",
+>   "permissionPattern": "business.{app}.*"
+> }
+> ```
+> **MANDATORY fields:** `role`, `level`, `permissionPattern`
+> **level values:** `admin`, `manager`, `contributor`, `viewer`
+> **FORBIDDEN fields:** Do NOT use `permissions` (use `permissionPattern`), `isDefault`.
+
+> **STRUCTURE CARD: cadrage.risks[]**
+> ```json
+> {
+>   "id": "RISK-001",
+>   "type": "business|technical|organizational",
+>   "description": "CSV data may contain duplicates and errors",
+>   "probability": "high|medium|low",
+>   "impact": "high|medium|low",
+>   "priority": "critical|medium|low",
+>   "mitigation": "Data cleaning phase before import, detailed error reports"
+> }
+> ```
+> **MANDATORY fields:** `id` (pattern: RISK-NNN), `type`, `description`, `mitigation`
+> **FORBIDDEN fields:** Do NOT use `risk` (name), `severity`. Use `id` + `description` + `priority`.
+
+> **STRUCTURE CARD: cadrage.acceptanceCriteria[]**
+> ```json
+> { "id": "AC-001", "criterion": "All must-have features delivered and tested", "validated": false }
+> ```
+> **MANDATORY:** This section must NOT be omitted.
+
+> **STRUCTURE CARD: cadrage.coverageMatrix[]**
+> ```json
+> {
+>   "item": "User management with CRUD",
+>   "category": "mustHave|shouldHave|couldHave|outOfScope|implicit",
+>   "module": "Users",
+>   "ucRef": "UC-UM-001",
+>   "notes": "Foundation module, must be implemented first"
+> }
+> ```
+> **MANDATORY fields:** `item`, `category`, `module`
+> **category values:** `mustHave`, `shouldHave`, `couldHave`, `outOfScope`, `implicit` (camelCase)
+> **FORBIDDEN fields:** Do NOT use `id`, `feature`, `priority`. Use `item` + `category`.
+
+> **STRUCTURE CARD: cadrage.codebaseContext** — Must be a string, NOT an object.
+> ```json
+> "codebaseContext": "Greenfield project, no existing entities. SmartStack 2.1.0 with Extensions DbContext."
+> ```
 
 ```
 ba-writer.enrichSection({
@@ -233,18 +301,18 @@ ba-writer.enrichSection({
     asIs: {Q1.2 answer},
     toBe: {Q1.3 answer},
     trigger: {Q1.4 answer},
-    stakeholders: [{mapped from Q2.x answers}],
+    stakeholders: [{mapped from Q2.x — use STRUCTURE CARD format}],
     globalScope: {
       mustHave: [{from Q3.x}],
       shouldHave: [{from Q3.x}],
       couldHave: [{from Q3.x}],
       outOfScope: [{from Q3.x}]
     },
-    applicationRoles: [{from section 6}],
-    risks: [{from section 8}],
-    acceptanceCriteria: [{derived from scope}],
-    coverageMatrix: [{from section 9}],
-    codebaseContext: {codebase_context}
+    applicationRoles: [{from section 6 — use STRUCTURE CARD format}],
+    risks: [{from section 8 — use STRUCTURE CARD format}],
+    acceptanceCriteria: [{derived from scope — use STRUCTURE CARD format}],
+    coverageMatrix: [{from section 9 — use STRUCTURE CARD format}],
+    codebaseContext: "{string summary of codebase findings}"
   }
 })