@atlashub/smartstack-cli 4.18.0 → 4.19.0

package/templates/skills/business-analyse/references/deploy-data-build.md

@@ -1,7 +1,7 @@
 # FEATURE_DATA & EMBEDDED_ARTIFACTS Build Reference
 
-> Reference for step-05b-deploy.md — complete mapping specification for the interactive HTML.
-> **Canonical field mapping reference:** See also `html-data-mapping.md` for the authoritative field name mapping between feature.json and HTML data objects.
+> Reference for step-05-deploy.md — complete mapping specification for the interactive HTML.
+> **Canonical field mapping reference:** See also `html-data-mapping.md` for the authoritative field name mapping between module JSON files and HTML data objects.
 
 ## FEATURE_DATA Object
 
@@ -17,15 +17,15 @@ const FEATURE_DATA = {
   cadrage: {
     // CONTEXT SECTION — merged from problem/asIs/toBe (lean cadrage)
     context: {
-      problem: master.cadrage.problem || "",           // flat string from feature.json
-      trigger: master.cadrage.trigger || "",            // flat string from feature.json
-      currentSituation: master.cadrage.asIs || "",      // flat string from feature.json
-      desiredSituation: master.cadrage.toBe || "",      // flat string from feature.json
+      problem: master.cadrage.problem || "",           // flat string from index.json
+      trigger: master.cadrage.trigger || "",            // flat string from index.json
+      currentSituation: master.cadrage.asIs || "",      // flat string from index.json
+      desiredSituation: master.cadrage.toBe || "",      // flat string from index.json
       painPoints: (master.cadrage.stakeholders || []).flatMap(s => s.painPoints || []),
       acceptanceCriteria: (master.cadrage.acceptanceCriteria || []).map(c => c.criterion)
     },
     scope: {
-      // CONVERT feature.json keys to HTML keys:
+      // CONVERT index.json keys to HTML keys:
       // mustHave → vital, shouldHave → important, couldHave → optional, outOfScope → excluded
       // CRITICAL: Preserve per-item `module` assignment from coverageMatrix (NOT modules[0])
       vital: (master.cadrage.globalScope?.mustHave || master.cadrage.coverageMatrix?.filter(i => i.category === "mustHave") || [])
@@ -107,8 +107,8 @@ const FEATURE_DATA = {
 
 ### Build Process
 
-1. Extract metadata from master feature.json
-2. Extract cadrage from master feature.json (CONVERT scope keys)
+1. Extract metadata from master index.json
+2. Extract cadrage from master index.json (CONVERT scope keys)
 3. Extract stakeholders from master.stakeholders
 4. Iterate ALL modules and populate moduleSpecs (THIS IS CRITICAL — empty moduleSpecs = BUG)
 5. For EACH module, extract: useCases, businessRules, entities, permissions, apiEndpoints
@@ -118,8 +118,8 @@ const FEATURE_DATA = {
 ## EMBEDDED_ARTIFACTS Object
 
 > **CRITICAL:** The wireframes object is keyed by moduleCode (NOT a flat array).
-> Field names MUST be renamed from feature.json: `mockupFormat` → `format`, `mockup` → `content`.
-> The HTML renderer reads `wf.format` and `wf.content` — using feature.json names will produce EMPTY mockups.
+> Field names MUST be renamed from module JSON files: `mockupFormat` → `format`, `mockup` → `content`.
+> The HTML renderer reads `wf.format` and `wf.content` — using module JSON file names will produce EMPTY mockups.
 
 ```javascript
 const EMBEDDED_ARTIFACTS = {
@@ -127,6 +127,7 @@ const EMBEDDED_ARTIFACTS = {
     // PER-MODULE keyed object (NOT a flat array)
     // FOR EACH module: extract from specification.uiWireframes[] OR specification.wireframes[] (SAFETY NET)
     // IMPORTANT: The agent may write wireframes under either key name — always check BOTH
+    // Read from module JSON files
     [moduleCode]: (moduleFeature.specification.uiWireframes || moduleFeature.specification.wireframes || []).map(wf => ({
       screen: wf.screen || wf.name || wf.title || wf.id || "",  // SAFETY NET: fallback name/title/id → screen
       section: wf.section || "",                      // e.g. "list"

package/templates/skills/business-analyse/references/deploy-modes.md

@@ -1,13 +1,13 @@
 # Deploy Mode Support & Troubleshooting
 
-> Reference for step-05b-deploy.md — mode variations and common issues.
+> Reference for step-05-deploy.md (HTML deployment) and `/derive-prd` skill (handoff + PRD generation) — mode variations and common issues.
 
 ## Mode Support
 
 ### Standard Mode
 
-Full handoff with all implementation details:
-- All 7 file categories
+Full handoff with all implementation details (via `/derive-prd`):
+- All 8 file categories (including documentation)
 - Complete BR-to-code mapping
 - Full API endpoint summary
 - Detailed prd.json
@@ -52,7 +52,7 @@ Full handoff across multiple applications within a project:
   "version": "1.0",
   "status": "handed-off",
   "applications": ["HumanResources", "EmployeeSelfService"],
-  "path": "business-analyse/v1.0/feature.json",
+  "path": "business-analyse/v1.0/index.json",
   "updatedAt": "2026-02-16T..."
 }
 ```
@@ -104,15 +104,15 @@ Full handoff across multiple applications within a project:
 
 | Issue | Resolution |
 |-------|-----------|
-| All modules missing handoff data | Return to step-05a-handoff.md. Handoff MUST be written to each module feature.json. |
-| prd.json generation failed | Verify ss derive-prd command is installed and feature.json path is correct. |
+| All modules missing handoff data | Run `/derive-prd` skill. Handoff MUST be written to each module's handoff.json. |
+| prd.json generation failed | Run `/derive-prd`. Verify ss derive-prd command is installed and index.json path is correct. |
 | progress.txt incomplete | Ensure all CORE SeedData entries are present: 2 app-level (NavigationApplication + ApplicationRoles) + per module (NavigationModule + NavigationSections + Permissions + Roles). Check topological order. |
 | BA manifest not found | Create docs/index.json if missing. Use schema provided in section 3. |
-| Manifest entries incorrect | Verify appCode, moduleCode, and version match feature.json metadata exactly. |
+| Manifest entries incorrect | Verify appCode, moduleCode, and version match index.json metadata exactly. |
 | ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
 | moduleSpecs missing from HTML | FEATURE_DATA.moduleSpecs is empty or not included in JSON. Verify each module is iterated and populated. |
-| Scope keys still show "mustHave" instead of "vital" | Conversion from feature.json keys to HTML keys failed. Check cadrage.scope conversion logic. |
+| Scope keys still show "mustHave" instead of "vital" | Conversion from JSON keys to HTML keys failed. Check cadrage.scope conversion logic. |
 | Wireframes array is empty | Verify each module has specification.uiWireframes. If missing, add wireframe stubs. |
-| dependencyGraph missing | Verify master feature.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
+| dependencyGraph missing | Verify master index.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
 | HTML opens but data blank (localStorage issue) | Clear browser localStorage. HTML will load pre-populated FEATURE_DATA on first load. |
-| Export/re-import fails | Verify exported JSON matches original feature.json schema. Validate with `/business-analyse -x --validate`. |
+| Export/re-import fails | Verify exported JSON matches original schema. Validate with `/business-analyse -x --validate`. |

package/templates/skills/business-analyse/references/detection-strategies.md

@@ -21,7 +21,7 @@ function detectReviewMode(feature_description) {
   }
 
   // Scan docs/ for most recent application
-  const applications = glob('docs/*/business-analyse/*/feature.json')
+  const applications = glob('docs/*/business-analyse/*/index.json')
     .map(path => ({
       path,
       metadata: readJSON(path).metadata,
@@ -113,7 +113,7 @@ Expected path: {expectedPath}
 
 ```javascript
 function scanExistingApplications() {
-  const featureFiles = glob('docs/*/business-analyse/*/feature.json');
+  const featureFiles = glob('docs/*/business-analyse/*/index.json');
 
   const existingApps = featureFiles.map(path => {
     const feature = readJSON(path);
@@ -155,8 +155,8 @@ interface ExistingApp {
 
 | Case | Handling |
 |------|----------|
-| No feature.json files found | Return empty array → triggers "new application" mode |
-| Corrupted feature.json | Skip file, log warning, continue scan |
+| No index.json files found | Return empty array → triggers "new application" mode |
+| Corrupted index.json | Skip file, log warning, continue scan |
 | Multiple versions of same app | Include all, sorted by updatedAt |
 | Incomplete applications (status="draft") | Include but flag in description |
 
@@ -346,8 +346,8 @@ function initiateUpdateMode(existingApp) {
     }
   };
 
-  // 3. Write new version feature.json
-  const newPath = `docs/${existingApp.app}/business-analyse/v${newVersion.version}/feature.json`;
+  // 3. Write new version index.json
+  const newPath = `docs/${existingApp.app}/business-analyse/v${newVersion.version}/index.json`;
   writeJSON(newPath, newFeature);
 
   return {

package/templates/skills/business-analyse/references/html-data-mapping.md

@@ -1,13 +1,13 @@
 # HTML Data Mapping Reference (references/html-data-mapping.md)
 
-> **Used by:** step-05b-deploy (Deploy Interactive HTML), step-03d-validate (incremental HTML)
-> **Purpose:** Exact mapping from feature.json to HTML FEATURE_DATA and EMBEDDED_ARTIFACTS objects
+> **Used by:** step-05-deploy (Deploy Interactive HTML)
+> **Purpose:** Exact mapping from module JSON files to HTML FEATURE_DATA and EMBEDDED_ARTIFACTS objects
 
 ---
 
 ## FEATURE_DATA Mapping
 
-Build a JSON object following this **exact mapping** from feature.json to the HTML data model:
+Build a JSON object following this **exact mapping** from index.json to the HTML data model:
 
 ```javascript
 {
@@ -17,16 +17,16 @@ Build a JSON object following this **exact mapping** from feature.json to the HT
     version: master.version,                            // e.g. "1.0"
     createdAt: master.metadata.createdAt,
     lastModified: master.metadata.updatedAt,
-    analysisMode: master.metadata.analysisMode || "interactive"  // always "interactive"
+    analysisMode: master.metadata.analysisMode || "interactive"  // always "interactive" in JSON format
   },
   cadrage: {
     // CONTEXT SECTION — lean format (merged from problem/asIs/toBe)
     // NOTE: 01-data-init.js has backward compat for old problem/current/vision format
     context: {
-      problem: master.cadrage.problem || "",             // flat string from feature.json
-      trigger: master.cadrage.trigger || "",              // flat string from feature.json
-      currentSituation: master.cadrage.asIs || "",        // flat string from feature.json
-      desiredSituation: master.cadrage.toBe || "",        // flat string from feature.json
+      problem: master.cadrage.problem || "",             // flat string from index.json
+      trigger: master.cadrage.trigger || "",              // flat string from index.json
+      currentSituation: master.cadrage.asIs || "",        // flat string from index.json
+      desiredSituation: master.cadrage.toBe || "",        // flat string from index.json
       painPoints: (master.cadrage.stakeholders || [])
         .flatMap(s => s.painPoints || []).join("\n"),     // aggregate all painPoints
       acceptanceCriteria: (master.cadrage.acceptanceCriteria || [])
@@ -80,7 +80,7 @@ Build a JSON object following this **exact mapping** from feature.json to the HT
     description: e.description || ""
   })),
   moduleSpecs: {
-    // FOR EACH module: read module feature.json, then map:
+    // FOR EACH module: read module index.json, then map:
     // [moduleCode]: { useCases, businessRules, entities, permissions, notes, mockupNotes }
   },
   consolidation: {
@@ -103,7 +103,7 @@ Build a JSON object following this **exact mapping** from feature.json to the HT
 
 For EACH module in `master.modules[]`:
 
-1. Read the module feature.json at `master.modules[i].featureJsonPath`
+1. Read the module index.json at `master.modules[i].featureJsonPath`
 2. Map to `moduleSpecs[moduleCode]`:
 
 ```javascript
@@ -188,16 +188,16 @@ Default: "contributor"
 
 ## EMBEDDED_ARTIFACTS Mapping
 
-> **FIELD RENAME WARNING:** feature.json stores wireframes with `mockupFormat` and `mockup` fields.
+> **FIELD RENAME WARNING:** Module JSON files store wireframes with `mockupFormat` and `mockup` fields.
 > The HTML renderer reads `format` and `content`. You MUST rename: `mockupFormat` → `format`, `mockup` → `content`.
 > Failure to rename = empty mockup display in the browser.
 
-Build a JSON object containing ALL visual artifacts from feature.json:
+Build a JSON object containing ALL visual artifacts from module JSON files (index.json):
 
 ```javascript
 {
   wireframes: {
-    // FOR EACH module: extract all wireframes from module feature.json
+    // FOR EACH module: extract all wireframes from module index.json
     // [moduleCode]: [ {screen, format, content, elements, componentMapping, layout, description} ]
   },
   e2eFlows: [
@@ -216,7 +216,7 @@ Build a JSON object containing ALL visual artifacts from feature.json:
 For EACH module in `master.modules[]`:
 
 ```javascript
-// Read the module feature.json
+// Read the module index.json file
 const moduleFeature = readModuleFeature(moduleCode);
 const wireframes = (moduleFeature.specification?.uiWireframes || []).map(wf => ({
   screen: wf.screen,                                    // e.g. "UM-list", "UM-form"
@@ -287,7 +287,7 @@ EMBEDDED_ARTIFACTS.dependencyGraph = {
 
 ---
 
-## Usage in step-05b-deploy
+## Usage in step-05-deploy
 
 1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation for readability)
 2. Serialize the EMBEDDED_ARTIFACTS object as JSON (with 2-space indentation)

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

@@ -7,7 +7,7 @@
 
 ## Module & Application Codes
 
-### In feature.json
+### In JSON files
 
 - `modules[].code` = **PascalCase** (e.g., `"HumanResources"`, `"TimeManagement"`)
 - `metadata.application` = **PascalCase** (e.g., `"HumanResources"`)
@@ -75,7 +75,7 @@ Route = ToKebabCase($"/{appCode}/{moduleCode}")
 
 ### JavaScript (BA Handoff Generation)
 
-**Location:** Used in step-05a-handoff.md when building seedDataCore
+**Location:** Used in step-05-deploy.md when building seedDataCore
 
 **Usage:**
 ```javascript
@@ -200,7 +200,7 @@ Sections and resources ALWAYS use kebab-case (no transformation needed).
 
 ### Full Hierarchy Example
 
-**BA Input (feature.json):**
+**BA Input (index.json):**
 ```json
 {
   "metadata": {
@@ -240,4 +240,4 @@ src/API/Controllers/HumanResources/TimeManagementController.cs
 - **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)
+- **Handoff:** `templates/skills/business-analyse/steps/step-05-deploy.md` (handoff section)

package/templates/skills/business-analyse/references/review-data-mapping.md

@@ -1,24 +1,24 @@
 # Review Data Mapping Reference (references/review-data-mapping.md)
 
 > **Used by:** step-06-review (Apply Review Corrections)
-> **Purpose:** Reverse mapping from ba-review.json (HTML export) back to feature.json format
+> **Purpose:** Reverse mapping from ba-review.json (HTML export) back to module JSON files format
 > **Complement of:** `references/html-data-mapping.md` (forward mapping)
 
 ---
 
 ## Overview
 
-The ba-review.json is exported from the interactive HTML with the same structure as the HTML data model. This document defines the **reverse transformation** to apply corrections back into feature.json format.
+The ba-review.json is exported from the interactive HTML with the same structure as the HTML data model. This document defines the **reverse transformation** to apply corrections back into module JSON files (index.json) format.
 
 ---
 
 ## Cadrage Reverse Mapping
 
-### Scope (HTML → feature.json)
+### Scope (HTML → index.json)
 
 ```javascript
 // HTML format: { vital: [{name, description}], important: [...], optional: [...], excluded: [...] }
-// feature.json format: { mustHave: [string], shouldHave: [string], couldHave: [string], outOfScope: [string] }
+// index.json format: { mustHave: [string], shouldHave: [string], couldHave: [string], outOfScope: [string] }
 
 reverseScope(reviewCadrage) {
   return {
@@ -30,11 +30,11 @@ reverseScope(reviewCadrage) {
 }
 ```
 
-### Stakeholders (HTML → feature.json)
+### Stakeholders (HTML → module index.json)
 
 ```javascript
 // HTML format: { role, function, tasks[], frequency, access, frustrations }
-// feature.json format: { role, function, involvement, tasks[], frequency, painPoints[] }
+// module JSON format: { role, function, involvement, tasks[], frequency, painPoints[] }
 
 const accessToInvolvement = {
   admin: "decision-maker",
@@ -62,10 +62,10 @@ reverseStakeholder(htmlStakeholder) {
 }
 ```
 
-### Problem / Vision / Current (HTML → feature.json)
+### Problem / Vision / Current (HTML → index.json)
 
 ```javascript
-// HTML has detailed sub-fields; feature.json has flat strings
+// HTML has detailed sub-fields; index.json has flat strings
 reverseProblemVision(reviewCadrage) {
   return {
     problem: reviewCadrage.problem?.description || "",
@@ -76,11 +76,11 @@ reverseProblemVision(reviewCadrage) {
 }
 ```
 
-### Risks (HTML → feature.json)
+### Risks (HTML → index.json)
 
 ```javascript
 // HTML format: { description, probability, impact, mitigation }
-// feature.json format: { id, type, description, probability, impact, mitigation }
+// index.json format: { id, type, description, probability, impact, mitigation }
 
 reverseRisks(reviewRisks, existingRisks) {
   return (reviewRisks || []).map((r, i) => {
@@ -98,11 +98,11 @@ reverseRisks(reviewRisks, existingRisks) {
 }
 ```
 
-### Acceptance Criteria (HTML → feature.json)
+### Acceptance Criteria (HTML → index.json)
 
 ```javascript
 // HTML format: success.definition (string, one criterion per line)
-// feature.json format: acceptanceCriteria[]: { id, criterion, validated }
+// index.json format: acceptanceCriteria[]: { id, criterion, validated }
 
 reverseAcceptanceCriteria(reviewSuccess, existingCriteria) {
   const lines = (reviewSuccess?.definition || "").split("\n").filter(Boolean);
@@ -121,11 +121,11 @@ reverseAcceptanceCriteria(reviewSuccess, existingCriteria) {
 
 ## Module Specifications Reverse Mapping
 
-### Use Cases (HTML → feature.json)
+### Use Cases (HTML → module index.json)
 
 ```javascript
 // HTML format: { id, name, actor, steps (newline-separated string), alternative (string) }
-// feature.json format: { id, name, primaryActor, permission, preconditions[], postconditions[], mainScenario[], alternativeScenarios[], linkedRules[] }
+// module JSON format: { id, name, primaryActor, permission, preconditions[], postconditions[], mainScenario[], alternativeScenarios[], linkedRules[] }
 
 reverseUseCase(htmlUC, existingUC) {
   return {
@@ -143,11 +143,11 @@ reverseUseCase(htmlUC, existingUC) {
 }
 ```
 
-### Business Rules (HTML → feature.json)
+### Business Rules (HTML → module index.json)
 
 ```javascript
 // HTML format: { id, name, category, statement, example (string) }
-// feature.json format: { id, name, category, statement, priority, conditions[], examples[], testability }
+// module JSON format: { id, name, category, statement, priority, conditions[], examples[], testability }
 
 reverseBusinessRule(htmlBR, existingBR) {
   return {
@@ -165,11 +165,11 @@ reverseBusinessRule(htmlBR, existingBR) {
 }
 ```
 
-### Entities (HTML → feature.json)
+### Entities (HTML → module index.json)
 
 ```javascript
 // HTML format: { name, description, attributes: [{name, description}], relationships: [string] }
-// feature.json format: { name, description, attributes: [{name, description, required}], relationships: [{target, type, description}] }
+// module JSON format: { name, description, attributes: [{name, description, required}], relationships: [{target, type, description}] }
 
 reverseEntity(htmlEntity, existingEntity) {
   return {
@@ -195,11 +195,11 @@ reverseEntity(htmlEntity, existingEntity) {
 }
 ```
 
-### Permissions (HTML → feature.json)
+### Permissions (HTML → module index.json)
 
 ```javascript
 // HTML format: permissions[] = ["Role|Action", "Role|Action", "Role|*"]
-// feature.json format: permissionMatrix = { permissions: [{path, action, description}], roleAssignments: [{role, permissions[]}] }
+// module JSON format: permissionMatrix = { permissions: [{path, action, description}], roleAssignments: [{role, permissions[]}] }
 
 const actionToPermission = {
   Consulter: "read",
@@ -252,11 +252,11 @@ reversePermissions(htmlPermissions, moduleCode, appName) {
 
 ## Modules Reverse Mapping
 
-### Module List (HTML → feature.json)
+### Module List (HTML → index.json)
 
 ```javascript
 // HTML format: modules[] = [{ code, name, description, featureType, priority, entities[], status }]
-// feature.json format: modules[] = [{ code, description, featureType, dependencies[], dependents[], status, priority, sortOrder, entities[], estimatedComplexity }]
+// index.json format: modules[] = [{ code, description, featureType, dependencies[], dependents[], status, priority, sortOrder, entities[], estimatedComplexity }]
 
 reverseModule(htmlModule, existingModule) {
   return {
@@ -279,11 +279,11 @@ reverseModule(htmlModule, existingModule) {
 
 ## Consolidation Reverse Mapping
 
-### Cross-Module Interactions (HTML → feature.json)
+### Cross-Module Interactions (HTML → index.json)
 
 ```javascript
 // HTML format: consolidation.interactions[] = [{ from, to, description }]
-// feature.json format: consolidation.crossModuleInteractions[] = [{ fromModule, toModule, interactionType, description, entities[] }]
+// index.json format: consolidation.crossModuleInteractions[] = [{ fromModule, toModule, interactionType, description, entities[] }]
 
 reverseInteraction(htmlInteraction, existingInteraction) {
   return {
@@ -296,11 +296,11 @@ reverseInteraction(htmlInteraction, existingInteraction) {
 }
 ```
 
-### E2E Flows (HTML → feature.json)
+### E2E Flows (HTML → index.json)
 
 ```javascript
 // HTML format: consolidation.e2eFlows[] = [{ name, steps: [{module, action}], actors }]
-// feature.json format: consolidation.e2eFlows[] = [{ name, steps: [{module, action, permission}] }]
+// index.json format: consolidation.e2eFlows[] = [{ name, steps: [{module, action, permission}] }]
 
 reverseE2EFlow(htmlFlow, existingFlow) {
   return {
@@ -318,7 +318,7 @@ reverseE2EFlow(htmlFlow, existingFlow) {
 
 ## Review Comments Preservation
 
-Comments from the review are stored in a new `review` section of the master feature.json:
+Comments from the review are stored in a new `review` section of the master index.json:
 
 ```javascript
 {
@@ -355,9 +355,9 @@ Comments from the review are stored in a new `review` section of the master feat
 
 When applying corrections, always try to **match existing items** before creating new ones:
 
-1. **By ID**: If the review item has an ID (UC-001, BR-VAL-001), find the same ID in feature.json
+1. **By ID**: If the review item has an ID (UC-001, BR-VAL-001), find the same ID in index.json
 2. **By name**: If no ID match, find by exact name match
 3. **New item**: If no match found, create a new item with a generated ID
-4. **Removed items**: Items present in feature.json but absent from review are marked as removed (not deleted)
+4. **Removed items**: Items present in index.json but absent from review are marked as removed (not deleted)
 
 This preserves referential integrity (linked rules, use case references) across the update.