@atlashub/smartstack-cli 3.6.0 → 3.8.0

package/templates/skills/business-analyse/steps/{step-05d-html.md → step-05b-deploy.md}

@@ -1,16 +1,20 @@
 ---
-name: step-05d-html
-description: Deploy ba-interactive.html pre-populated with all analysis data
+name: step-05b-deploy
+description: Generate prd.json, deploy artifacts, interactive HTML
 model: sonnet
 next_step: null
 ---
 
-> **Context files:** `_shared.md`
+> **Context files:** _shared.md
 
-# Step 5d: Deploy Interactive HTML
+# Step 5b: Deploy Artifacts & Interactive HTML
 
 ## MANDATORY EXECUTION RULES
 
+- **ALWAYS** verify all module handoffs are complete before generating artifacts
+- **ALWAYS** derive prd.json from feature.json (NEVER independently)
+- **NEVER** invent entities/FRs/BRs not in feature.json
+- **ALWAYS** update BA manifest at docs/business/index.json
 - **ALWAYS** deploy ba-interactive.html PRE-POPULATED with all data
 - **ALWAYS** follow references/html-data-mapping.md EXACTLY for FEATURE_DATA and EMBEDDED_ARTIFACTS mapping
 - **FEATURE_DATA.moduleSpecs MUST be populated for EACH module** — empty moduleSpecs = BROKEN specification tabs
@@ -20,13 +24,185 @@ next_step: null
 
 ## YOUR TASK
 
-Deploy the interactive HTML document pre-populated with ALL analysis data. This is the final step of the business analysis workflow. The HTML is the client-facing deliverable for review and can be edited, enriched, and re-imported.
+Generate deployment artifacts (prd.json, progress.txt, BA manifest) and deploy the interactive HTML document pre-populated with all analysis data.
 
 ---
 
 ## EXECUTION SEQUENCE
 
-### 1. Read Source Data
+### 0. Pre-flight Verification
+
+Before generating ANY artifact, verify step-05a completed successfully:
+
+```
+FOR each module in modules[]:
+  Read module feature.json
+  IF module.handoff === {} OR module.status !== "handed-off":
+    → BLOCKING ERROR: Module {module.code} has no handoff data
+    → Return to step-05a-handoff.md
+```
+
+IF all modules have valid handoff → proceed.
+
+---
+
+### 1. Generate prd.json (PROGRAMMATIC)
+
+> **RULE:** prd.json is extracted by CLI code, **NEVER** generated by LLM.
+> The `ss derive-prd` command performs a deterministic data transformation from feature.json.
+
+**For each module:**
+
+```
+Execute: ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
+```
+
+**For consolidated view (multi-module, optional):**
+
+```
+Execute: ss derive-prd --application {masterFeaturePath}
+→ Generates .ralph/prd-{moduleCode}.json for each module
+```
+
+**Verification:** After execution, read the generated prd.json and display summary:
+
+```
+prd.json generated for module {moduleCode}:
+  - Use cases: {count}
+  - Functional requirements: {count}
+  - Business rules: {count}
+  - API endpoints: {count}
+  - Sections: {count}
+  - Files to create: {count}
+  - BR-to-code mappings: {count}
+```
+
+**Key guarantees:**
+- Source MUST reference feature.json path (traceability)
+- All data is EXACT COPY from feature.json (no transformation, no invention)
+- prd.json version: "2.0.0"
+- source.type: "ba-handoff-programmatic"
+
+**POST-CHECK (BLOCKING — DO NOT SKIP):**
+
+After `ss derive-prd` execution, read the generated prd-{moduleCode}.json and verify structural integrity:
+
+```javascript
+const prd = readJSON(`.ralph/prd-${moduleCode}.json`);
+const featureHandoff = moduleFeature.handoff.filesToCreate;
+
+// 1. Verify structure: filesToCreate MUST be under implementation (NOT root level)
+if (prd.filesToCreate && !prd.implementation?.filesToCreate) {
+  BLOCKING_ERROR("prd.json has filesToCreate at ROOT level — this is NOT from ss derive-prd");
+  BLOCKING_ERROR("Re-run: ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json");
+  STOP;
+}
+
+// 2. Verify ALL 7 categories present and match feature.json
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
+for (const cat of categories) {
+  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
+  const featureCount = featureHandoff[cat]?.length ?? 0;
+  if (prdCount !== featureCount) {
+    BLOCKING_ERROR(`${cat}: prd has ${prdCount} files but feature.json has ${featureCount}`);
+  }
+}
+```
+
+Display verification table:
+
+```
+POST-CHECK: prd-{moduleCode}.json integrity
+| Category       | feature.json | prd.json | Match |
+|----------------|-------------|----------|-------|
+| domain         | {n}         | {n}      | OK/FAIL |
+| application    | {n}         | {n}      | OK/FAIL |
+| infrastructure | {n}         | {n}      | OK/FAIL |
+| api            | {n}         | {n}      | OK/FAIL |
+| frontend       | {n}         | {n}      | OK/FAIL |
+| seedData       | {n}         | {n}      | OK/FAIL |
+| tests          | {n}         | {n}      | OK/FAIL |
+```
+
+IF ANY category shows FAIL → **STOP AND RE-RUN `ss derive-prd`**. DO NOT proceed with incomplete PRD.
+
+---
+
+### 2. Initialize Progress Tracker
+
+> **Template:** Read `templates/tpl-progress.md` for the complete progress tracker template structure.
+> Populate the template with module-specific data from feature.json handoff sections.
+
+**Progress Tracker Rules:**
+- One section per module, in topological order (dependencies first)
+- CORE SeedData ALWAYS 5 entries (mandatory)
+- Business SeedData varies by module
+- Hierarchical task structure (module -> layer -> tasks)
+- Each task is independent, assignable checkbox
+- Effort estimate per module (simple/medium/complex)
+- Summary with totals across all modules
+- Cross-module tasks only if multi-module
+
+---
+
+### 3. Update BA Manifest (MANDATORY)
+
+> **The BA manifest enables the SmartStack web app to discover and display all available business analyses.**
+> It is a JSON index file at `docs/business/index.json` that lists all feature.json files.
+
+**Path:** `docs/business/index.json` (project root relative)
+
+**Schema:**
+```json
+{
+  "version": "1.0",
+  "updatedAt": "{ISO timestamp}",
+  "analyses": [
+    {
+      "appCode": "{app_code}",
+      "appName": "{application_name}",
+      "moduleCode": null | "{module_code}",
+      "moduleName": "{module_name}",
+      "version": "{version}",
+      "status": "handed-off",
+      "featureDescription": "{feature_description}",
+      "path": "{app_code}/business-analyse/v{version}/feature.json",
+      "updatedAt": "{ISO timestamp}"
+    }
+  ]
+}
+```
+
+**Update logic:**
+
+1. Read existing manifest at `docs/business/index.json` (or create empty `{ "version": "1.0", "updatedAt": "", "analyses": [] }`)
+2. For the APPLICATION-level feature.json:
+   - Find existing entry where `appCode == {app_code}` AND `moduleCode == null` AND `version == {version}`
+   - If found: update `status`, `updatedAt`, `featureDescription`
+   - If not found: append new entry with `moduleCode: null` and `path: "{app_code}/business-analyse/v{version}/feature.json"`
+3. For EACH MODULE-level feature.json:
+   - Find existing entry where `appCode == {app_code}` AND `moduleCode == {module_code}` AND `version == {version}`
+   - If found: update `status`, `updatedAt`, `featureDescription`
+   - If not found: append new entry with `moduleCode: "{module_code}"` and `path: "{app_code}/{module_code}/business-analyse/v{version}/feature.json"`
+4. Update root `updatedAt` to current timestamp
+5. Write manifest back to `docs/business/index.json`
+
+**Display confirmation:**
+```
+✓ BA manifest updated: docs/business/index.json
+  Entries: {total_count} ({app_count} applications, {module_count} modules)
+  Web viewer: /system/docs/ba
+```
+
+**Why a manifest?**
+- The web app needs to discover available BAs without scanning the filesystem
+- Static file serving (no backend API needed)
+- Incremental updates: each handoff adds/updates only its entries
+- Consumed by the SmartStack web app BA viewer at `/system/docs/ba`
+
+---
+
+### 4. Read Source Data for HTML
 
 1. Read the HTML template from skill directory: `html/ba-interactive.html` (relative to `~/.claude/skills/business-analyse/`)
 2. Read the master feature.json (application level)
@@ -45,7 +221,7 @@ Deploy the interactive HTML document pre-populated with ALL analysis data. This
 
 ---
 
-### 2. Build FEATURE_DATA Object
+### 5. Build FEATURE_DATA Object
 
 Reference `references/html-data-mapping.md` EXACTLY. The FEATURE_DATA object must contain:
 
@@ -131,7 +307,7 @@ const FEATURE_DATA = {
 
 ---
 
-### 3. Build EMBEDDED_ARTIFACTS Object
+### 6. Build EMBEDDED_ARTIFACTS Object
 
 Extract visual artifacts and diagrams from the analysis:
 
@@ -172,7 +348,7 @@ const EMBEDDED_ARTIFACTS = {
 
 ---
 
-### 4. Replace Placeholders in Template
+### 7. Replace Placeholders in Template
 
 1. Serialize the FEATURE_DATA object as JSON (with 2-space indentation)
 2. Serialize the EMBEDDED_ARTIFACTS object as JSON (with 2-space indentation)
@@ -190,7 +366,7 @@ const EMBEDDED_ARTIFACTS = {
 
 ---
 
-### 5. Write and Verify
+### 8. Write and Verify
 
 1. Write the populated HTML to the output directory: `docs/business/{app}/business-analyse/v{version}/ba-interactive.html`
 2. Display deployment confirmation:
@@ -207,6 +383,21 @@ const EMBEDDED_ARTIFACTS = {
 
 ---
 
+## SELF-VERIFICATION (BEFORE COMPLETION)
+
+Before displaying completion, VERIFY:
+
+1. **`.ralph/prd-{module}.json`** exists for ALL modules (file size > 100 bytes each)
+2. **`.ralph/progress.txt`** exists (file size > 500 bytes)
+3. **`docs/business/index.json`** exists with correct entry count
+4. **ba-interactive.html** exists and file size > 100KB
+5. **FEATURE_DATA contains moduleSpecs** with entries for ALL modules
+6. **cadrage.scope uses HTML keys** (vital/important/optional/excluded)
+
+**IF any check fails → GENERATE the missing artifact before proceeding to completion.**
+
+---
+
 ## POST-CHECK (BLOCKING)
 
 After writing the HTML file, verify:
@@ -246,43 +437,73 @@ After writing the HTML file, verify:
 
 ---
 
-## SELF-VERIFICATION (FINAL)
+## COMPLETION
 
-Before completion, verify:
+> **IMPORTANT:** La BA ne lance JAMAIS /ralph-loop automatiquement.
+> Il peut y avoir une phase de revue/modification de la documentation entre les deux étapes.
+> L'utilisateur lance `/ralph-loop` manuellement quand il est prêt.
 
-1. **ba-interactive.html exists** at `docs/business/{app}/business-analyse/v{version}/` and file size > 100KB
-2. **FEATURE_DATA contains moduleSpecs** with entries for ALL modules (grep for `"moduleSpecs"` — if absent, the specification tabs will be broken)
-3. **cadrage.scope uses HTML keys** (vital/important/optional/excluded) — NOT feature.json keys
-4. **EMBEDDED_ARTIFACTS contains wireframes** for all modules with screen names and descriptions
-5. **All 5 metadata fields populated:** applicationName, applicationId, version, createdAt, vibeCoding
+Display completion using the template from `templates/tpl-launch-displays.md`:
 
-**IF any check fails → REGENERATE the HTML immediately.**
+```
+═══════════════════════════════════════════════════════════════
+  [OK] BUSINESS ANALYSE TERMINEE - {application_name}
+═══════════════════════════════════════════════════════════════
 
----
+Modules:   {count} ({names})
+Strategy:  {strategy}
+Files:     {total files across all modules}
+Tasks:     {total tasks} ({core_count} CORE + {biz_count} business + {dev_count} development)
+Complexity: {complexity}
+Effort:    {total_days} days ({total_hours} hours)
 
-## WHY A FINAL HTML DEPLOYMENT AT HANDOFF?
+[DIR] Artefacts générés:
+  ✓ feature.json (master + per-module) - spécification complète
+  ✓ .ralph/prd-{module}.json - task breakdown per module
+  ✓ .ralph/progress.txt - tracker de progression
+  ✓ ba-interactive.html - document de revue interactif
 
-- Step 03 already deploys the HTML incrementally after each module (partial data)
-- This final deployment adds the COMPLETE data: all modules + consolidation + handoff info
-- The client sees the FULL analysis pre-populated — including cross-module interactions and E2E flows
-- The client can review, edit, and enrich directly in the browser
-- Any client modifications can be re-imported via `-x` extraction mode
-- The HTML is standalone (no server required) with localStorage persistence
-- On first open: pre-populated data displays. After client edits: localStorage overrides
-- **NOTE:** This overwrites the incremental HTML from step-03 with the complete version
+[TARGET] Prochaines étapes:
+  1. Ouvrir ba-interactive.html dans le navigateur
+  2. Partager avec les stakeholders pour validation
+  3. Si retours --> relancer /business-analyse pour une nouvelle itération
+  4. Une fois validé, lancer le développement:
+
+     /ralph-loop -r
+
+═══════════════════════════════════════════════════════════════
+```
 
 ---
 
-## OUTPUT
+## MODE SUPPORT
+
+### Standard Mode
+
+Full handoff with all implementation details:
+- All 7 file categories
+- Complete BR-to-code mapping
+- Full API endpoint summary
+- Detailed prd.json
+- Comprehensive progress tracker
 
-The final deliverable:
+### Micro Mode (use_case = micro)
 
-- **ba-interactive.html** (deployed to docs/business/{app}/business-analyse/v{version}/)
-  - Standalone interactive HTML document for client review
-  - Pre-populated with ALL analysis data (metadata, cadrage, modules, wireframes, E2E flows)
-  - FEATURE_DATA and EMBEDDED_ARTIFACTS fully serialized as JSON variables
-  - Client can edit, add use cases, modify scope, and export JSON
-  - Re-importable via `/business-analyse -x <exported-json-path>`
+Simplified handoff with minimal scope:
+- Only essential CRUD entity + controller
+- 3 core SeedData entries (omit some optional ones)
+- Basic prd.json with simplified sections
+- Lightweight progress.txt
+- Display `/ralph-loop -r` command for later use
+
+### Delta Mode (use_case = refactoring)
+
+Focused handoff for changes:
+- Only affected modules listed
+- Reuse existing implementation patterns
+- Highlight what changed vs baseline
+- Update only affected prd.json sections
+- Progress tracker shows only delta tasks
 
 ---
 
@@ -290,6 +511,11 @@ The final deliverable:
 
 | 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. |
+| progress.txt incomplete | Ensure all 5 CORE SeedData entries are present per module. Check topological order. |
+| BA manifest not found | Create docs/business/index.json if missing. Use schema provided in section 3. |
+| Manifest entries incorrect | Verify appCode, moduleCode, and version match feature.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. |
@@ -297,30 +523,3 @@ The final deliverable:
 | dependencyGraph missing | Verify master feature.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`. |
-
----
-
-## FINAL COMPLETION
-
-```
-═══════════════════════════════════════════════════════════════
-  BUSINESS ANALYSE COMPLETE
-═══════════════════════════════════════════════════════════════
-
-All artifacts deployed:
-  ✓ feature.json (master + per-module)
-  ✓ prd.json (module-level task breakdown)
-  ✓ progress.txt (development tracker)
-  ✓ ba-interactive.html (client-facing review document)
-
-Next steps:
-  1. Share ba-interactive.html with stakeholders
-  2. Gather feedback and edits
-  3. Export modified JSON from HTML
-  4. Re-import with: /business-analyse -x <exported-json-path>
-  5. Launch development: /ralph-loop -r
-
-═══════════════════════════════════════════════════════════════
-```
-
-**Business analysis is now complete. The HTML document is ready for client review.**

package/templates/skills/business-analyse/templates/tpl-launch-displays.md

@@ -1,6 +1,6 @@
 # Skill Launch Display Templates (templates/tpl-launch-displays.md)
 
-> **Used by:** step-05c-deploy (section 5: Completion Summary)
+> **Used by:** step-05b-deploy (Completion Summary)
 > **Purpose:** User-facing display templates for BA completion
 > **Note:** No emojis - uses text markers per Claude Code conventions
 

package/templates/skills/business-analyse/templates/tpl-progress.md

@@ -1,6 +1,6 @@
 # Progress Tracker Template (templates/tpl-progress.md)
 
-> **Used by:** step-05c-deploy (section 2: Initialize Progress Tracker)
+> **Used by:** step-05b-deploy (section 2: Initialize Progress Tracker)
 > **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
 
 ## Template

package/templates/skills/ralph-loop/SKILL.md

@@ -12,11 +12,11 @@ Execute the Ralph Weegund technique - an iterative development methodology where
 <quick_start>
 **Three ways to start Ralph Loop:**
 
-1. **From Business Analysis (RECOMMENDED - NEW v6.1):**
+1. **From Business Analysis (RECOMMENDED):**
    ```bash
    /business-analyse MyFeature
-   # At the end, choose "Ralph Loop" → automatic launch
-   # No arguments needed - prd.json already generated
+   # At the end, BA offers to launch ralph-loop automatically
+   # If PRD files are missing, ralph-loop auto-recovers via ss derive-prd
    ```
 
 2. **Manual start with existing prd.json:**

package/templates/skills/ralph-loop/steps/step-00-init.md

@@ -201,7 +201,73 @@ mkdir -p .ralph/logs
 mkdir -p .ralph/reports
 ```
 
-### 4b. Detect Multi-Module PRDs (from BA Handoff)
+### 4a. Auto-Recovery: Detect BA Artifacts Without PRD (NEW)
+
+> **Scenario:** Business-analyse completed (feature.json with status="handed-off") but step-05b
+> didn't generate PRD files (context exhaustion). Ralph-loop auto-recovers by running `ss derive-prd`.
+
+**Check for BA artifacts when no PRD files exist:**
+
+```bash
+PRD_EXISTS=$(ls .ralph/prd-*.json 2>/dev/null | head -1)
+SINGLE_PRD_EXISTS=$(test -f .ralph/prd.json && echo "yes" || echo "no")
+```
+
+**IF no PRD files found (neither prd-*.json nor prd.json):**
+
+```bash
+# Search for handed-off master feature.json
+MASTER_FEATURE=$(find docs/business -maxdepth 4 -name "feature.json" -path "*/business-analyse/*" 2>/dev/null | head -1)
+```
+
+**IF master feature.json found:**
+
+```javascript
+const master = readJSON(MASTER_FEATURE);
+
+if (master.status === "handed-off" || master.handoff?.status === "handed-off") {
+  // BA completed but PRD files are missing — auto-recover
+  console.log("BA artifacts detected without PRD files — auto-recovering...");
+
+  // Display validation table
+  console.log(`
+╔══════════════════════════════════════════════════════════════════╗
+║  BA ARTIFACT VALIDATION                                          ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Master feature.json: ✅ Found (status: ${master.status})        ║
+║  Application: ${master.metadata?.application || 'unknown'}       ║
+║  Modules: ${master.modules?.length || 0}                         ║
+║  PRD files: ❌ Missing — will auto-generate                      ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Running: ss derive-prd --application ${MASTER_FEATURE}          ║
+╚══════════════════════════════════════════════════════════════════╝
+  `);
+
+  // Execute ss derive-prd to generate missing PRD files
+  // This is a deterministic CLI command (no LLM), safe to auto-run
+  exec(`ss derive-prd --application ${MASTER_FEATURE}`);
+
+  // Verify PRD files were generated
+  const newPrdFiles = glob('.ralph/prd-*.json');
+  if (newPrdFiles.length === 0) {
+    console.log("❌ ss derive-prd failed to generate PRD files");
+    console.log("   Verify: ss derive-prd is installed (npm list -g @atlashub/smartstack-cli)");
+    console.log("   Manual: ss derive-prd --application " + MASTER_FEATURE);
+    STOP;
+  }
+
+  console.log(`✅ Auto-recovered ${newPrdFiles.length} PRD files`);
+  // Continue to section 4b which will detect and queue them
+}
+```
+
+**IF master feature.json NOT found OR status ≠ "handed-off":**
+- No BA artifacts → proceed normally (step-01 will create prd.json from task description)
+
+**IF PRD files already exist:**
+- Skip auto-recovery entirely → proceed to section 4b
+
+### 4b. Detect Multi-Module PRDs (from BA Handoff or Auto-Recovery)
 
 **After creating `.ralph/` directory, check for per-module PRD files:**
 
@@ -265,6 +331,16 @@ Queue: {module codes joined by " → "}
 Starting with: {modules[0].code}
 ```
 
+6. **Display BA artifact validation (if from BA handoff):**
+```
+[CHECK] BA Artifact Validation:
+  ✓ Master feature.json: {MASTER_FEATURE} (status: handed-off)
+  ✓ Module feature.json: {module_count} modules (all handed-off)
+  ✓ PRD files: {PRD_COUNT} modules (.ralph/prd-*.json)
+  ✓ progress.txt: {exists ? "present" : "will be created"}
+  [PASS] All BA artifacts valid. Multi-module development ready.
+```
+
 **If only `.ralph/prd.json` exists (single module):**
 - Skip queue creation (backward compatible)
 - Proceed normally