@atlashub/smartstack-cli 3.21.0 → 3.23.0

package/templates/skills/business-analyse/references/naming-conventions.md

@@ -0,0 +1,245 @@
+# Naming Conventions - SmartStack
+
+> **Loaded by:** business-analyse steps when generating codes and routes
+> **Purpose:** Define transformation rules between code identifiers (PascalCase) and URL routes (kebab-case)
+
+---
+
+## Module & Application Codes
+
+### In feature.json
+
+- `modules[].code` = **PascalCase** (e.g., `"HumanResources"`, `"TimeManagement"`)
+- `metadata.application` = **PascalCase** (e.g., `"HumanResources"`)
+- Used for: C# namespaces, file paths, class names, folder structure
+
+### In URL Routes
+
+- **kebab-case lowercase** (e.g., `"/business/human-resources/employees"`)
+- Transform: `PascalCase` → `kebab-case` via helper function
+- Used for: Web URLs, navigation routes, API paths
+
+---
+
+## Transformation Rules
+
+| Source | Format | Example | Usage |
+|--------|--------|---------|-------|
+| Module code | `PascalCase` | `HumanResources` | C# files, classes, namespaces |
+| Application code | `PascalCase` | `HumanResources` | Namespaces, folders |
+| Context code | `lowercase` | `business` | URLs, routes, contexts |
+| Route path | `kebab-case` | `/business/human-resources` | Web URLs, navigation |
+| Section code | `kebab-case` | `time-tracking`, `approve` | URLs, API paths, sections |
+| Resource code | `kebab-case` | `repair-grid`, `employee-form` | Component IDs, resources |
+
+---
+
+## Why These Conventions?
+
+### PascalCase for Code
+- **C# Standard**: Namespaces, classes, properties follow PascalCase
+- **File Structure**: Matches .NET project conventions
+- **Compile-time**: Enforced by compiler and naming analyzers
+
+### kebab-case for URLs
+- **Web Standard**: Readable, SEO-friendly, case-insensitive
+- **REST API Convention**: Lowercase routes with hyphens
+- **Frontend Compatibility**: React Router, Vue Router expect lowercase
+- **Database Storage**: Navigation routes stored lowercase prevent case mismatch errors
+
+### Separation of Concerns
+- **Code Identity** ≠ **URL Identity**
+- Backend uses PascalCase internally
+- URLs transform to kebab-case at persistence layer (seed data)
+- Frontend consumes kebab-case routes from database
+
+---
+
+## Helper Functions
+
+### C# (Backend Seed Data)
+
+**Location:** `NavigationSeedData.cs` templates in core-seed-data.md
+
+**Usage:**
+```csharp
+Route = ToKebabCase($"/{contextCode}/{appCode}/{moduleCode}")
+```
+
+**Transformation Examples:**
+- `HumanResources` → `human-resources`
+- `TimeManagement` → `time-management`
+- `Projects` → `projects` (single word, no change)
+- `AI` → `ai` (acronym lowercase)
+
+**Implementation:** See `templates/skills/ralph-loop/references/core-seed-data.md` line 162
+
+### JavaScript (BA Handoff Generation)
+
+**Location:** Used in step-05a-handoff.md when building seedDataCore
+
+**Usage:**
+```javascript
+const route = `/${contextCode}/${toKebabCase(appCode)}/${toKebabCase(moduleCode)}`;
+```
+
+**Implementation:**
+```javascript
+function toKebabCase(code) {
+  return code
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+}
+```
+
+### TypeScript (Frontend MCP)
+
+**Location:** Used in scaffold_routes and validate_frontend_routes
+
+**Usage:**
+```typescript
+const webPath = `/${navRoute.split('.').map(toKebabCase).join('/')}`;
+```
+
+**Implementation:**
+```typescript
+function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase();
+}
+```
+
+---
+
+## Validation
+
+### During Generation (ralph-loop)
+
+POST-CHECK after NavigationSeedData generation:
+
+```bash
+# Detect routes with uppercase
+grep -E 'Route = "?/[^"]*[A-Z]' Infrastructure/Persistence/Seeding/Data/*/NavigationSeedData.cs
+```
+
+If match found → ERROR, routes not transformed to kebab-case.
+
+### Via MCP
+
+```bash
+validate_frontend_routes
+```
+
+**Detects:**
+- Routes with uppercase in URLs
+- Seed data routes not matching frontend expectations
+- PascalCase URLs without kebab-case conversion
+
+**Output Example:**
+```
+❌ Case mismatch detected (1 routes with uppercase):
+   Route "business.humanresources" uses PascalCase in URL.
+   Found: business/HumanResources → Expected: business/human-resources
+   Fix: Use ToKebabCase() in NavigationSeedData route generation
+```
+
+---
+
+## Common Pitfalls
+
+### ❌ Generating Routes Without Transformation
+
+**Wrong (causes 404 on menu click):**
+```csharp
+Route = $"/{contextCode}/{appCode}/{moduleCode}"
+// Result: /business/HumanResources/Projects
+```
+
+**Correct:**
+```csharp
+Route = ToKebabCase($"/{contextCode}/{appCode}/{moduleCode}")
+// Result: /business/human-resources/projects
+```
+
+### ❌ Hardcoding Routes in lowercase
+
+**Wrong (loses traceability to code):**
+```csharp
+Route = "/business/humanresources"  // Flattens multi-word into single word
+```
+
+**Correct:**
+```csharp
+Route = ToKebabCase($"/{contextCode}/{appCode}")
+// If appCode = "HumanResources" → /business/human-resources
+```
+
+### ❌ Inconsistent Section/Resource Codes
+
+**Wrong (mixing conventions):**
+```json
+{
+  "code": "TimeTracking",  // PascalCase
+  "route": "/time-tracking"  // kebab-case route doesn't match
+}
+```
+
+**Correct:**
+```json
+{
+  "code": "time-tracking",  // kebab-case from start
+  "route": "/business/human-resources/time-tracking"
+}
+```
+
+Sections and resources ALWAYS use kebab-case (no transformation needed).
+
+---
+
+## Examples
+
+### Full Hierarchy Example
+
+**BA Input (feature.json):**
+```json
+{
+  "metadata": {
+    "context": "business",
+    "application": "HumanResources"
+  },
+  "modules": [
+    { "code": "TimeManagement" },
+    { "code": "Projects" }
+  ]
+}
+```
+
+**Generated Routes (seed data):**
+```
+Application: /business/human-resources
+Module 1:    /business/human-resources/time-management
+Module 2:    /business/human-resources/projects
+```
+
+**C# Code Structure:**
+```
+src/Domain/Entities/Business/HumanResources/TimeManagement/TimeEntry.cs
+src/Application/Services/Business/HumanResources/TimeManagement/TimeEntryService.cs
+src/API/Controllers/Business/HumanResources/TimeManagementController.cs
+```
+
+**Frontend Routes (React Router):**
+```tsx
+<Route path="/business/human-resources/time-management" element={<TimeManagementPage />} />
+<Route path="/business/human-resources/projects" element={<ProjectsPage />} />
+```
+
+---
+
+## References
+
+- **Template:** `templates/skills/ralph-loop/references/core-seed-data.md`
+- **Validation:** `src/mcp/tools/validate-frontend-routes.ts`
+- **POST-CHECK:** `templates/skills/ralph-loop/steps/step-02-execute.md` (section 5)
+- **Handoff:** `templates/skills/business-analyse/steps/step-05a-handoff.md` (section 4.6)

package/templates/skills/business-analyse/references/validate-incremental-html.md

@@ -46,10 +46,11 @@ const EMBEDDED_ARTIFACTS = {
     // FOR EACH completed module: extract wireframes with RENAMED fields
     // SAFETY NET: check BOTH key names (agent may use either)
     [moduleCode]: (moduleFeature.specification.uiWireframes || moduleFeature.specification.wireframes || []).map(wf => ({
-      screen: wf.screen,
-      section: wf.section,
+      screen: wf.screen || wf.name || wf.title || wf.id || "",  // SAFETY NET: fallback name/title/id → screen
+      section: wf.section || "",
       format: wf.mockupFormat || "ascii",   // RENAME: mockupFormat → format
-      content: wf.mockup,                    // RENAME: mockup → content
+      content: wf.mockup || wf.ascii || wf.content || "",  // SAFETY NET: mockup/ascii/content → content
+      svgContent: null,  // Populated by Step 3-bis SVG generation
       description: wf.description || "",
       elements: wf.elements || [],
       actions: wf.actions || [],
@@ -74,6 +75,27 @@ const EMBEDDED_ARTIFACTS = {
 > The HTML renderer reads `format` and `content`. You MUST rename these fields.
 > Failure to rename = empty mockup display in the browser.
 
+### Step 3-bis: Generate SVG Wireframes (Parallel Task Agents)
+
+> **Purpose:** Enrich each ASCII wireframe with a professional SVG version for dual-view rendering.
+> **Cost:** ~$0.01 per wireframe (Sonnet model). Negligible for 2-6 wireframes per module.
+> **Fallback:** If ANY SVG generation fails, proceed with ASCII only (svgContent stays null).
+
+See [references/wireframe-svg-style-guide.md](wireframe-svg-style-guide.md) for the complete SVG style specification, prompt template, and orchestration process.
+
+**Process summary:**
+
+1. **Read** `references/wireframe-svg-style-guide.md` to get the prompt template
+2. **Collect** all wireframes in `EMBEDDED_ARTIFACTS.wireframes` where `content` exists and `svgContent` is null
+3. **Spawn parallel Task(sonnet) agents** — ONE per wireframe, ALL in a single message
+4. **Collect and validate** results: strip markdown fences if present, verify SVG starts with `<svg` and contains `</svg>`
+5. **Inject** valid SVGs into `EMBEDDED_ARTIFACTS.wireframes[moduleCode][index].svgContent`
+6. **Display** summary: `SVG wireframes: {generated}/{total} generated successfully`
+
+> **CRITICAL:** This step is NEVER blocking. If all SVG generations fail, deployment
+> continues with ASCII-only wireframes. The HTML renderer checks for `svgContent` before
+> showing the SVG view. SVG is an enhancement, not a requirement.
+
 ### Step 4: Replace Placeholders in Template
 
 - Serialize the FEATURE_DATA object as JSON (2-space indentation)
@@ -93,7 +115,7 @@ const EMBEDDED_ARTIFACTS = {
   Modules included: {completedModules.length}/{totalModules} specified
     - {completedModule1}: {uc_count} UCs, {br_count} BRs, {wireframe_count} wireframes
     - {completedModule2}: ...
-  Visual artifacts: {total_wireframes} wireframes embedded
+  Visual artifacts: {total_wireframes} wireframes embedded ({svg_count} with SVG, {ascii_only_count} ASCII only)
   Remaining: {pendingModules.join(', ')} (will be added after specification)
   → Client can open in browser to review completed modules now.
 ```

package/templates/skills/business-analyse/references/validation-checklist.md

@@ -139,16 +139,16 @@ const checklist = {
 
   wireframes: {
     minimum: specification.sections.length,  // 1 wireframe PER section
-    actual: specification.uiWireframes.length,
+    actual: (specification.uiWireframes || specification.wireframes || []).length,  // Check BOTH key names
     status: actual >= minimum ? "PASS" : "FAIL",
     blocking: true,
-    details: "EVERY section MUST have a wireframe (ASCII/SVG)"
+    details: "EVERY section MUST have a wireframe (ASCII/SVG). Check both uiWireframes and wireframes keys."
   },
 
   wireframeSchemaCompliance: {
     check: "All wireframes have required fields: screen, section, mockupFormat, elements[], componentMapping[], layout (object), permissionsRequired[]",
-    status: specification.uiWireframes.every(wf =>
-      wf.screen && wf.section && wf.mockupFormat &&
+    status: (specification.uiWireframes || specification.wireframes || []).every(wf =>
+      (wf.screen || wf.title) && wf.section && (wf.mockupFormat || wf.mockup || wf.ascii) &&
       Array.isArray(wf.elements) && wf.elements.length > 0 &&
       Array.isArray(wf.componentMapping) && wf.componentMapping.length > 0 &&
       typeof wf.layout === 'object' && wf.layout !== null &&
@@ -156,8 +156,9 @@ const checklist = {
     ) ? "PASS" : "FAIL",
     blocking: true,
     details: "Wireframes missing metadata render as empty frames in HTML documentation. " +
-             "Check: screen (not name/id), section, mockupFormat, elements[] non-empty, " +
-             "componentMapping[] as array of {wireframeElement, reactComponent}, layout as object (not string)"
+             "Check: screen (not name/id/title), section, mockupFormat, elements[] non-empty, " +
+             "componentMapping[] as array of {wireframeElement, reactComponent}, layout as object (not string). " +
+             "Also see references/acceptance-criteria.md for bash-verifiable checks."
   },
 
   navigation: {
@@ -240,12 +241,31 @@ const checklist = {
     details: "Modules need field validation rules"
   },
 
-  // SECTION 10: GHERKIN SCENARIOS (WARNING)
-  gherkinScenarios: {
+  // SECTION 10: GHERKIN SCENARIOS (BLOCKING for format, WARNING for count)
+  gherkinFormat: {
+    check: "gherkinScenarios is ARRAY (not single object)",
+    status: Array.isArray(specification.gherkinScenarios) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "gherkinScenarios MUST be an array [{feature, scenarios}], not a single object. " +
+             "Auto-fix: wrap in array [gherkinScenarios]. See step-03c ABSOLUTE FORMAT CHECKS."
+  },
+
+  gherkinContent: {
+    check: "Each gherkin entry has feature (string) + scenarios (array)",
+    status: (Array.isArray(specification.gherkinScenarios) &&
+      specification.gherkinScenarios.every(g => g.feature && Array.isArray(g.scenarios))
+    ) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Each gherkin entry must have {feature: string, scenarios: [{name, tags, given[], when[], then[]}]}"
+  },
+
+  gherkinScenarioCount: {
     minimum: 2,
-    actual: specification.gherkinScenarios.scenarios.length,
+    actual: (Array.isArray(specification.gherkinScenarios)
+      ? specification.gherkinScenarios.reduce((sum, g) => sum + (g.scenarios || []).length, 0)
+      : 0),
     status: actual >= minimum ? "PASS" : "FAIL",
-    blocking: false,  // WARNING only
+    blocking: false,  // WARNING only — count is advisory
     details: "Gherkin scenarios enable automated testing"
   }
 };
@@ -297,7 +317,7 @@ ELSE:
 | Seed Data | 2 | {n} | {n} | {n} |
 | API Endpoints | 2 | {n} | {n} | {n} |
 | Validations | 1 | {n} | {n} | {n} |
-| Gherkin | 1 | {n} | {n} | {n} |
+| Gherkin | 3 | {n} | {n} | {n} |
 
 TOTAL: {total_checks} checks | {passed} ✓ | {failed} ✗ | {warnings} ⚠