@atlashub/smartstack-cli 3.8.0 → 3.10.0

package/templates/skills/business-analyse/references/robustness-checks.md

@@ -0,0 +1,538 @@
+# Robustness Checks for Business Analysis
+
+> **Objective:** Prevent incomplete specifications and broken references from reaching development.
+
+## Overview
+
+This document consolidates all robustness checks implemented across the business-analyse workflow. Each check serves to catch issues early, before they cause ralph-loop failures or runtime errors.
+
+---
+
+## Phase 1: Module Specification Checklist (Step-03d)
+
+> **When:** Before marking module status = "specified"
+> **Blocking:** YES - Module CANNOT proceed to handoff with failing checks
+
+### Purpose
+
+Ensures each module has ALL required components before being marked as "specified". Prevents incomplete modules from reaching step-04 consolidation.
+
+### Checks (30 total)
+
+#### SECTION 1: Data Model (3 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 1.1 | Entities count | ≥2 | YES | Single-entity modules are rare and likely incomplete |
+| 1.2 | Entity attributes | Each entity ≥3 attributes | YES | Entities with <3 attributes are incomplete |
+| 1.3 | Entity relationships | All entities have relationships or marked standalone | NO (WARNING) | Standalone entities should be rare |
+
+#### SECTION 2: Business Rules (3 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 2.1 | Business rules count | ≥4 | YES | Modules need validation/calculation logic |
+| 2.2 | BR categories | ≥2 categories (VAL/CALC/WF/SEC/DATA) | YES | Single-category modules likely incomplete |
+| 2.3 | BR module prefixes | All BRs use module prefix | YES | Prevents ID collisions in multi-module apps |
+
+#### SECTION 3: Use Cases & Requirements (4 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 3.1 | Use cases count | ≥6 | YES | CRUD (5) + 1 business-specific minimum |
+| 3.2 | UC module prefixes | All UCs use module prefix | YES | Prevents ID collisions |
+| 3.3 | Functional requirements count | ≥4 | YES | FRs must cover key functionality |
+| 3.4 | UC-FR linkage | Every UC has ≥1 linked FR | YES | Orphan UCs indicate incomplete requirements |
+| 3.5 | FR-BR linkage | Every FR has ≥1 linked BR | NO (WARNING) | FRs without BRs may lack validation logic |
+
+#### SECTION 4: Permissions (3 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 4.1 | Permissions count | ≥5 | YES | CRUD (4) + 1 business action minimum |
+| 4.2 | Permission format | `business.{app}.{module}.{resource}.{action}` | YES | Wrong format breaks RBAC system |
+| 4.3 | Role permissions | All roles have ≥1 permission | YES | Roles without permissions are useless |
+
+#### SECTION 5: UI & Navigation (3 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 5.1 | Sections count | ≥2 | YES | Modules need list + form minimum |
+| 5.2 | Wireframes count | 1 per section | YES | EVERY section MUST have wireframe |
+| 5.3 | Navigation entries | ≥1 | YES | Module must be accessible in menu |
+
+#### SECTION 6: I18N & Messages (3 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 6.1 | i18n keys count | ≥42 | YES | Entities, fields, messages, validation, navigation |
+| 6.2 | i18n languages | All keys have 4 languages (fr/en/nl/de) | YES | Missing translations break multi-language |
+| 6.3 | Messages count | ≥4 | YES | 1 success, 1 error, 1 warning, 1 info minimum |
+
+#### SECTION 7: Seed Data (2 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 7.1 | CORE seed data sections | All 5 sections present | YES | Missing CORE data breaks deployment |
+| 7.2 | Business seed data | Template defined | NO (WARNING) | Helps with testing |
+
+**CORE sections required:**
+1. `navigationModules`
+2. `navigationTranslations`
+3. `permissions`
+4. `rolePermissions`
+5. `permissionConstants`
+
+#### SECTION 8: API Endpoints (2 checks)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 8.1 | API endpoints count | ≥5 | YES | CRUD (5) minimum |
+| 8.2 | API permissions | Every endpoint has permission | YES | Endpoints without permissions are security holes |
+
+#### SECTION 9: Validations (1 check)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 9.1 | Validations count | ≥1 | YES | Modules need field validation rules |
+
+#### SECTION 10: Gherkin Scenarios (1 check)
+
+| # | Check | Minimum | Blocking | Rationale |
+|---|-------|---------|----------|-----------|
+| 10.1 | Gherkin scenarios count | ≥2 | NO (WARNING) | Enables automated testing |
+
+### Failure Handling
+
+**IF ANY blocking check fails:**
+
+1. **STOP** - Do NOT mark module as "specified"
+2. **DISPLAY** table of failures with details
+3. **ACTIONS:**
+   - Fix ALL blocking failures
+   - Re-run step-03d validation
+   - Proceed only when ALL blocking checks pass
+
+**Example output:**
+
+```
+═══════════════════════════════════════════════════════════════
+  MODULE SPECIFICATION INCOMPLETE - Projects
+═══════════════════════════════════════════════════════════════
+
+| Section | Check | Required | Actual | Status | Details |
+|---------|-------|----------|--------|--------|---------|
+| Business Rules | BR categories | ≥2 | 1 | ✗ FAIL | Only VAL category present |
+| Use Cases | UC count | ≥6 | 4 | ✗ FAIL | Missing business-specific UCs |
+| Wireframes | Count | 3 | 2 | ✗ FAIL | Missing wireframe for "Settings" section |
+
+ACTIONS REQUIRED:
+1. Add business rules in ≥1 other category (CALC, WF, SEC, or DATA)
+2. Add 2 more use cases (business-specific)
+3. Create wireframe for "Settings" section
+4. Re-run step-03d validation
+
+DO NOT PROCEED TO CONSOLIDATION UNTIL ALL CHECKS PASS
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 2: Cross-Module Reference Validation (Step-04)
+
+> **When:** During consolidation, before marking application as "consolidated"
+> **Blocking:** YES - Unresolved references BLOCK handoff
+
+### Purpose
+
+Verifies ALL cross-module entity references are resolvable. Prevents FK constraint violations and runtime errors during ralph-loop code generation.
+
+### Process
+
+1. **Build Entity Registry**
+   - Extract all entities from all modules
+   - Map: `{moduleCode → [entities]}`
+
+2. **Extract Cross-Module References**
+   - Scan all `entity.relationships[]` for references to other modules
+   - Format: `"ModuleName.EntityName.FieldName"` or `"ModuleName.EntityName"`
+
+3. **Validate References**
+   - ✓ Target module exists
+   - ✓ Target entity exists in target module
+   - ✓ Target field exists (if specified)
+
+4. **Validate Dependency Graph Alignment**
+   - For each cross-module reference, verify dependency edge exists
+   - Auto-fix: add missing edges (with warning)
+
+5. **Detect Circular Dependencies**
+   - BLOCKING ERROR if cycles detected
+   - User must break cycles manually
+
+### Checks
+
+| # | Check | Blocking | Failure Action |
+|---|-------|----------|----------------|
+| 1 | Target module exists | YES | BLOCKING ERROR - list invalid references |
+| 2 | Target entity exists | YES | BLOCKING ERROR - list invalid references |
+| 3 | Target field exists | NO (WARNING) | Assume PK ("Id") if not specified |
+| 4 | Dependency edge exists | NO (WARNING) | Auto-fix: add missing edge |
+| 5 | No circular dependencies | YES | BLOCKING ERROR - user must fix |
+
+### Example Output
+
+**Success:**
+
+```
+═══════════════════════════════════════════════════════════════
+  CROSS-MODULE REFERENCES VALIDATED
+═══════════════════════════════════════════════════════════════
+
+| Source Module | Source Entity | Target | Type | Status |
+|---------------|---------------|--------|------|--------|
+| TimeTracking | TimeEntry | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
+| LeaveManagement | LeaveRequest | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
+| AbsenceManagement | Absence | Projects.Employee.Id | FK (N:1) | ✓ RESOLVED |
+| Reporting | ProjectReport | Projects.Project.Id | FK (N:1) | ✓ RESOLVED |
+
+Total: 4 cross-module references
+All references RESOLVED ✓
+No circular dependencies ✓
+═══════════════════════════════════════════════════════════════
+```
+
+**Failure (unresolved reference):**
+
+```
+═══════════════════════════════════════════════════════════════
+  CROSS-MODULE REFERENCES FAILED
+═══════════════════════════════════════════════════════════════
+
+BLOCKING ERRORS:
+
+1. Module "TimeTracking": Entity "TimeEntry" references non-existent entity "Task" in module "Projects"
+   - Source: TimeEntry.taskId
+   - Target: Projects.Task (NOT FOUND)
+   - Fix: Either create "Task" entity in Projects module, or remove reference
+
+2. Module "Reporting": Entity "ProjectReport" references non-existent module "Analytics"
+   - Source: ProjectReport.analyticsId
+   - Target: Analytics.Report (module does not exist)
+   - Fix: Either create "Analytics" module, or remove reference
+
+ACTIONS REQUIRED:
+1. Fix ALL unresolved references listed above
+2. Return to step-03a for affected modules
+3. Re-run step-04 consolidation
+
+DO NOT PROCEED TO HANDOFF UNTIL ALL REFERENCES RESOLVED
+═══════════════════════════════════════════════════════════════
+```
+
+**Failure (circular dependency):**
+
+```
+═══════════════════════════════════════════════════════════════
+  CIRCULAR DEPENDENCIES DETECTED
+═══════════════════════════════════════════════════════════════
+
+BLOCKING ERROR: Cycles found in dependency graph
+
+Cycle 1: Orders → Invoices → Payments → Orders
+Cycle 2: Customers → Contacts → Customers
+
+ACTIONS REQUIRED:
+1. Break cycles by:
+   - Moving shared entities to a separate "Core" module
+   - Using event-driven communication instead of FK
+   - Removing unnecessary dependencies
+2. Return to step-02 decomposition
+3. Fix dependency graph
+4. Re-run step-03 module specification
+5. Re-run step-04 consolidation
+
+DEVELOPMENT CANNOT PROCEED WITH CIRCULAR DEPENDENCIES
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 3: Ralph Readiness Validation (Step-05c)
+
+> **When:** After artifacts deployed (step-05b), before launching /ralph-loop
+> **Blocking:** YES - Development blocked if critical checks fail
+
+### Purpose
+
+Final gate to ensure business analysis is 100% ready for implementation. Catches issues before ralph-loop starts, preventing failed development attempts.
+
+### Checks (9 categories)
+
+| # | Category | Checks | Blocking | Purpose |
+|---|----------|--------|----------|---------|
+| 1 | Module Status | All modules status = "handed-off" | YES | Incomplete modules break ralph-loop |
+| 2 | PRD Files | All PRD files exist, valid structure, file counts match | YES | Ralph-loop reads PRDs for tasks |
+| 3 | Dependency Graph | Valid, no cycles, topological order correct | YES | Determines module implementation order |
+| 4 | Cross-Module References | All references resolvable | YES | Prevents FK constraint errors |
+| 5 | Handoff Completeness | All 7 file categories, brToCodeMapping, apiEndpointSummary | YES | Missing data breaks code generation |
+| 6 | i18n Keys | All keys have 4 languages | NO (WARNING) | Missing translations won't block dev |
+| 7 | Master Feature | Status = "handed-off", handoff complete | YES | Ralph-loop needs master handoff |
+| 8 | Progress Tracker | File exists, structure valid, task count matches | NO (WARNING) | Used for progress tracking |
+| 9 | Final Readiness | Aggregate all checks, calculate score | YES if <100% | All critical checks must pass |
+
+### Readiness Score
+
+```
+Readiness Score = (passed critical checks / total critical checks) × 100%
+```
+
+**Thresholds:**
+- **100%** → READY FOR DEVELOPMENT ✓
+- **<100%** → NOT READY - FIX REQUIRED ✗
+
+### Example Output
+
+**Ready:**
+
+```
+═══════════════════════════════════════════════════════════════
+  RALPH READINESS CHECK - COMPLETE
+═══════════════════════════════════════════════════════════════
+
+Validation Summary:
+  ✓ Module status validation: PASS (5/5 modules)
+  ✓ PRD files validation: PASS (5/5 files)
+  ✓ Dependency graph validation: PASS (4 edges)
+  ✓ Cross-module references validation: PASS (4 references)
+  ✓ Handoff completeness check: PASS (5/5 modules)
+  ⚠ i18n keys validation: WARNING (1 missing translation)
+  ✓ Master feature validation: PASS
+  ✓ Progress tracker validation: PASS
+
+Readiness Score: 100% (7/7 critical checks passed, 1 warning)
+
+Status: READY FOR DEVELOPMENT ✓
+
+Next Steps:
+  1. Address warnings (optional, recommended)
+  2. Review progress tracker: .ralph/progress.txt
+  3. Launch development: /ralph-loop -r
+═══════════════════════════════════════════════════════════════
+```
+
+**Not Ready:**
+
+```
+═══════════════════════════════════════════════════════════════
+  RALPH READINESS CHECK - FAILED
+═══════════════════════════════════════════════════════════════
+
+Status: NOT READY FOR DEVELOPMENT ✗
+
+Critical Issues Found:
+  ✗ Module status validation: FAIL (1/5 modules incomplete)
+    - Reporting module status is "specified", must be "handed-off"
+    - Fix: Return to step-05a-handoff.md for Reporting module
+
+  ✗ PRD files validation: FAIL (1/5 files invalid)
+    - prd-Reporting.json has wrong structure (filesToCreate at root level)
+    - Fix: Re-run ss derive-prd --feature {path} --output .ralph/prd-Reporting.json
+
+Required Actions:
+  1. Fix all critical issues listed above
+  2. Re-run validation: load step-05c-ralph-readiness.md
+  3. Only proceed to /ralph-loop when all critical checks pass
+
+DO NOT PROCEED TO /RALPH-LOOP UNTIL ALL CRITICAL CHECKS PASS
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## Common Patterns & Best Practices
+
+### 1. Fail Fast, Fail Clear
+
+**Principle:** Detect issues as early as possible, provide clear error messages with actionable fixes.
+
+**Example:**
+- ✗ BAD: "Validation failed" (vague, no action)
+- ✓ GOOD: "Entity 'Task' not found in Projects module. Fix: Create Task entity or remove reference from TimeEntry.taskId"
+
+### 2. Progressive Validation
+
+**Principle:** Validate at each step, not just at the end.
+
+**Checkpoints:**
+- Step-03d: Module completeness (before marking "specified")
+- Step-04: Cross-module coherence (before marking "consolidated")
+- Step-05c: Development readiness (before /ralph-loop)
+
+### 3. Auto-Fix vs. Manual Fix
+
+**Auto-fix (safe):**
+- Add missing dependency edges (with warning)
+- Auto-correct casing (PascalCase, camelCase)
+- Fill default values (e.g., PK = "Id" if not specified)
+
+**Manual fix (requires user decision):**
+- Circular dependencies (how to break?)
+- Unresolved entity references (create or remove?)
+- Permission conflicts (intentional or error?)
+
+### 4. Severity Levels
+
+| Level | Symbol | Meaning | Action |
+|-------|--------|---------|--------|
+| PASS | ✓ | Check passed | Continue |
+| WARNING | ⚠ | Non-blocking issue | Recommend fix, allow continue |
+| ERROR | ✗ | Blocking issue | STOP, fix required |
+
+### 5. Display Standards
+
+**Always include in error messages:**
+1. **What failed** - Clear identification of the issue
+2. **Why it matters** - Impact if not fixed
+3. **How to fix** - Specific actionable steps
+4. **Where to go** - Which step to return to
+
+**Example:**
+
+```
+✗ BLOCKING ERROR: Cross-module reference unresolved
+
+WHAT: TimeTracking.TimeEntry references Projects.Task (NOT FOUND)
+WHY: This will cause FK constraint violation in database
+HOW TO FIX:
+  Option 1: Create "Task" entity in Projects module
+  Option 2: Remove reference from TimeEntry (change taskId to projectId)
+WHERE: Return to step-03a-data.md for TimeTracking module
+```
+
+---
+
+## Troubleshooting Guide
+
+### Issue: Module Fails Specification Checklist
+
+**Symptoms:**
+- Module has < minimum required components
+- Step-03d validation fails
+
+**Diagnosis:**
+1. Check which sections failed (entities, UCs, BRs, wireframes, etc.)
+2. Review minimum requirements per section
+
+**Fix:**
+1. Add missing components until minimums met
+2. Re-run step-03d validation
+3. Proceed only when ALL blocking checks pass
+
+---
+
+### Issue: Cross-Module Reference Unresolved
+
+**Symptoms:**
+- Step-04 reports "entity not found"
+- Cross-module FK references fail validation
+
+**Diagnosis:**
+1. Identify source module + entity
+2. Identify target module + entity
+3. Check if target entity exists in target module
+
+**Fix:**
+1. **If target entity missing:**
+   - Create target entity in target module
+   - OR remove reference from source entity
+2. **If target module missing:**
+   - Create target module
+   - OR remove reference from source entity
+3. Re-run step-04 consolidation
+
+---
+
+### Issue: Circular Dependencies Detected
+
+**Symptoms:**
+- Step-04 reports "circular dependencies"
+- Dependency graph has cycles
+
+**Diagnosis:**
+1. Identify cycle path (A → B → C → A)
+2. Analyze relationships causing cycle
+
+**Fix:**
+1. **Option 1: Create Core module**
+   - Move shared entities to new "Core" module
+   - Other modules depend on Core (no cycle)
+2. **Option 2: Use events instead of FK**
+   - Replace direct FK with event-driven communication
+   - Breaks dependency link
+3. **Option 3: Remove unnecessary dependency**
+   - Review if dependency is truly needed
+   - Remove if redundant
+4. Return to step-02, fix dependency graph
+5. Re-run step-03 for affected modules
+6. Re-run step-04 consolidation
+
+---
+
+### Issue: Ralph Readiness Check Fails
+
+**Symptoms:**
+- Step-05c reports readiness score < 100%
+- Critical checks failed
+
+**Diagnosis:**
+1. Review failed checks in summary
+2. Identify missing/invalid artifacts
+
+**Fix:**
+- **Module status incomplete:** Return to step-05a for affected module
+- **PRD files invalid:** Re-run `ss derive-prd` for affected module
+- **Handoff incomplete:** Return to step-05a, complete handoff section
+- **Cross-module refs broken:** Return to step-04, fix references
+- Re-run step-05c after fixes
+
+---
+
+## Metrics & Success Criteria
+
+### Module Specification Checklist
+
+**Target:**
+- 100% blocking checks passed
+- 0-5 warnings acceptable
+
+**Success:**
+- Module marked as "specified"
+- Ready for consolidation
+
+### Cross-Module Validation
+
+**Target:**
+- 100% references resolved
+- 0 circular dependencies
+
+**Success:**
+- Application marked as "consolidated"
+- Ready for handoff
+
+### Ralph Readiness
+
+**Target:**
+- 100% critical checks passed
+- Warnings addressed or documented
+
+**Success:**
+- Application ready for /ralph-loop
+- 0% chance of ralph-loop failure due to incomplete BA
+
+---
+
+**Last Updated:** 2026-02-08
+**Version:** 1.0
+**Author:** SmartStack CLI Team
+**Based on:** Analysis of BA session 03b76b8b-ea1c-4f1e-a636-bd46b0c33e02

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

@@ -0,0 +1,57 @@
+# Specification: Auto-Inference Rules
+
+> Reference for step-03a-data.md — convention/override depth auto-generation from entity definitions.
+
+## Entity Attribute → SmartTable Column
+
+| Attribute Type | Column Format | Sortable | Filterable | Notes |
+|---|---|---|---|---|
+| string + unique | text | yes | yes | clickAction: navigate:detail |
+| string | text | yes | yes | — |
+| enum / status | badge | yes | yes (multi-select) | colorMap from lifeCycles if exists |
+| FK:Entity | text (join .name) | yes | yes (entity-select) | Display related entity name |
+| decimal | currency | yes | no | — |
+| int | number | yes | no | — |
+| datetime | date-relative | yes | yes (date-range) | — |
+| bool | boolean | yes | yes (toggle) | — |
+| text (long) | — | no | no | Hidden in table, visible in detail |
+
+## Entity Attribute → SmartForm Field
+
+| Attribute Type | Component | Required from | Notes |
+|---|---|---|---|
+| string | Input | entity.required | — |
+| string (multiline) | TextArea | entity.required | rows: 4 |
+| enum | Select | entity.required | source: enum name |
+| FK:Entity | EntitySelect | entity.required | source: target entity, searchable |
+| decimal | NumberInput | entity.required | — |
+| int | NumberInput | entity.required | — |
+| datetime | DatePicker | entity.required | — |
+| bool | Toggle | — | default: false |
+
+## Auto-Generated Sections by featureType
+
+| featureType | Sections generated |
+|---|---|
+| data-centric | list, create, detail |
+| workflow | list, create, detail, edit |
+| integration | list, detail, config |
+| reporting | dashboard |
+| full-module | list, create, detail, edit, dashboard |
+
+## Section Generation Rules
+
+1. **list section:** SmartTable with all non-long-text attributes as columns, actions = [view, edit, delete], defaultSort = { createdAt, desc }
+2. **create section:** SmartForm with all writable attributes as fields, component inferred from type
+3. **detail section:** DetailCard with all attributes + child SmartTable for each 1:N relationship
+4. **edit section:** Same as create but pre-filled (mode: edit)
+5. **dashboard section:** Trigger 3d (dashboard specification)
+
+## Status/Lifecycle Enhancement
+
+If entity has a status/enum field AND lifeCycles exists:
+- list section: status column gets `format: badge`, `colorMap: stateMachine:{Entity}`
+- list section: rowActions get `showWhen` conditions based on state machine transitions
+- detail section: add StatusBadge resource + transition action buttons
+
+Write auto-generated sections to `specification.sections[]` via `ba-writer.enrichSection()`

package/templates/skills/business-analyse/references/ui-dashboard-spec.md

@@ -0,0 +1,85 @@
+# UI: Dashboard Specification
+
+> Reference for step-03b-ui.md — section 3d dashboard KPI and chart capture.
+
+## 3d. Dashboard Specification (if section = dashboard)
+
+When a "dashboard" section is selected, capture structured KPI and chart data **in addition** to the standard ASCII mockup.
+
+1. **Ask client for KPIs** via AskUserQuestion (batch):
+   - KPI name and metric description
+   - Visualization type: `kpi-card`, `bar`, `line`, `pie`, `area`, `donut`, `stacked-bar`
+   - Data source entity
+   - Format: `number`, `currency`, `percent`, `duration`
+   - Thresholds (warning/critical) if applicable
+
+2. **Ask client for filters:**
+   - Date range filter? Default period? (day/week/month/quarter/year)
+   - Entity-based filters? (status, category, etc.)
+
+3. **Ask client for refresh mode:**
+   - Static (load on page open)
+   - Polling (periodic refresh)
+   - SignalR (real-time push)
+
+4. **Store in specification.dashboards[]:**
+
+```json
+{
+  "code": "{module}-dashboard",
+  "title": "{Module} Dashboard",
+  "description": "Vue d'ensemble des métriques {module}",
+  "linkedUCs": ["UC-XXX"],
+  "refreshMode": "static",
+  "defaultPeriod": "month",
+  "kpis": [
+    {
+      "code": "total-items",
+      "label": "Total Items",
+      "metric": "COUNT(entity)",
+      "format": "number",
+      "visualization": "kpi-card",
+      "dataSource": "Entity",
+      "thresholds": { "warning": 100, "critical": 50 }
+    },
+    {
+      "code": "items-by-status",
+      "label": "Items by Status",
+      "metric": "COUNT(entity) GROUP BY status",
+      "format": "number",
+      "visualization": "pie",
+      "dataSource": "Entity",
+      "dimensions": ["status"]
+    }
+  ],
+  "filters": [
+    { "field": "dateRange", "type": "dateRange", "label": "Période" },
+    { "field": "status", "type": "multiselect", "label": "Statut" }
+  ],
+  "permissionsRequired": ["business.{app}.{module}.read"]
+}
+```
+
+5. **ALSO generate the standard ASCII mockup** for the dashboard with KPI cards + chart placeholders:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  {Module} > Dashboard              Période: [Ce mois ▾]     ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    ║
+║  │ KPI #1   │  │ KPI #2   │  │ KPI #3   │  │ KPI #4   │    ║
+║  │  1,234   │  │  567     │  │  89.2%   │  │  12,400  │    ║
+║  │  ↑ +12%  │  │  ↓ -3%  │  │  → 0%   │  │  ↑ +5%   │    ║
+║  └──────────┘  └──────────┘  └──────────┘  └──────────┘    ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ┌─────────────────────────┐  ┌─────────────────────────┐    ║
+║  │  [Bar Chart]            │  │  [Pie Chart]            │    ║
+║  │  Items by Month         │  │  Items by Status        │    ║
+║  │  ████                   │  │      ████████           │    ║
+║  │  ████ ████              │  │   ███      ███          │    ║
+║  │  ████ ████ ████         │  │  ██   42%    ██         │    ║
+║  └─────────────────────────┘  └─────────────────────────┘    ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Store the mockup in specification.wireframes[] AS WELL (for visual reference).