@atlashub/smartstack-cli 3.17.0 → 3.19.0

package/templates/skills/business-analyse/steps/step-05c-ralph-readiness.md

@@ -1,16 +1,17 @@
 ---
 name: step-05c-ralph-readiness
-description: Validation gate before ralph-loop - verify completeness, integrity, and readiness
-model: sonnet
+description: ULTRATHINK quality review + validation gate before ralph-loop
+model: opus
 next_step: null
 ---
 
 > **Context files:** `_shared.md`
 
-# Step 5c: Ralph Readiness Check
+# Step 5c: ULTRATHINK Quality Review & Ralph Readiness Check
 
 ## MANDATORY EXECUTION RULES
 
+- **ALWAYS** use ULTRATHINK mode for the quality review (section 0b)
 - **ALWAYS** run ALL validation checks (NEVER skip)
 - **BLOCKING RULE:** If ANY check fails → STOP, DO NOT proceed to ralph-loop
 - **ALWAYS** provide actionable fix instructions for failures
@@ -19,7 +20,7 @@ next_step: null
 
 ## YOUR TASK
 
-Perform comprehensive validation to ensure the business analysis is ready for implementation via /ralph-loop. This is a **BLOCKING** gate - all checks must pass before development can proceed.
+Perform a deep ULTRATHINK quality review of the entire business analysis output, then run comprehensive structural validation to ensure readiness for /ralph-loop. This is a **BLOCKING** gate — all checks must pass before development can proceed.
 
 ---
 
@@ -31,9 +32,177 @@ Display validation banner:
 
 ```
 ═══════════════════════════════════════════════════════════════
-  RALPH READINESS CHECK - {application_name}
+  ULTRATHINK QUALITY REVIEW & RALPH READINESS CHECK
+  {application_name}
 ═══════════════════════════════════════════════════════════════
-Validating business analysis completeness before development...
+Phase 1: Deep quality review (ULTRATHINK)...
+Phase 2: Structural validation (8 checks)...
+```
+
+---
+
+### 0b. ULTRATHINK Deep Quality Review (MANDATORY)
+
+> **This section MUST be executed in ULTRATHINK mode.**
+> Take the time to deeply analyze the ENTIRE business analysis output.
+> This is the last chance to catch quality issues before development begins.
+
+**Objective:** Perform a thorough, deep-thinking review of the business analysis quality — not just structural checks, but semantic coherence, completeness, and production-readiness.
+
+**Process:**
+
+1. **Read ALL module feature.json files** (master + each module)
+2. **Activate ULTRATHINK** and analyze the following 6 dimensions:
+
+#### Dimension 1: Specification Coherence
+
+```
+For EACH module:
+  - Do use cases (UCs) tell a coherent story?
+  - Are functional requirements (FRs) logically derived from UCs?
+  - Do business rules (BRs) cover all edge cases mentioned in UCs?
+  - Are gherkin scenarios testing the RIGHT behaviors (not trivial CRUD)?
+  - Do entity relationships make domain sense?
+
+Flag: Orphan FRs (not linked to any UC), UCs with no FR coverage,
+      BRs that don't map to any entity/field
+```
+
+#### Dimension 2: Permission & Security Model
+
+```
+For EACH module:
+  - Is the permission hierarchy logical? (admin > manager > contributor > viewer)
+  - Are there actions that should be restricted but aren't?
+  - Do API endpoints all have permissions assigned?
+  - Are there over-permissive roles? (e.g., contributor with delete access)
+  - Cross-module: can a user in Module A access data in Module B through indirect routes?
+
+Flag: Endpoints without permissions, roles with excessive access,
+      missing permission paths
+```
+
+#### Dimension 3: Data Model Integrity
+
+```
+For EACH module:
+  - Are all entity relationships bidirectional where needed?
+  - Are FK references correct (target entity exists, correct field type)?
+  - Are there missing audit fields (CreatedAt, UpdatedAt, CreatedBy)?
+  - Do lifecycle states cover all business scenarios?
+  - Are cascade delete/update rules safe? (no orphan risk)
+
+Cross-module:
+  - Are shared entity references correct?
+  - Is the dependency graph honest? (no hidden dependencies)
+
+Flag: Missing relationships, unsafe cascades, missing audit fields,
+      hidden cross-module dependencies
+```
+
+#### Dimension 4: UI/UX Completeness
+
+```
+For EACH module:
+  - Does every section have at least one wireframe?
+  - Do wireframes cover ALL use cases? (no UC without UI representation)
+  - Are navigation entries correct and complete?
+  - Do wireframe actions map to real API endpoints?
+  - Are form fields aligned with entity attributes?
+  - Are validation rules defined for all user-input fields?
+
+Flag: UCs with no wireframe, wireframes with unmapped actions,
+      missing form validations, navigation gaps
+```
+
+#### Dimension 5: i18n & Messages Quality
+
+```
+For EACH module:
+  - Are all user-facing strings covered by i18n keys?
+  - Are error messages specific enough? (not generic "Error occurred")
+  - Do validation messages reference the field name?
+  - Are success/confirmation messages present for all write operations?
+  - Are there missing translations in any language?
+
+Flag: Generic error messages, missing field-specific validations,
+      incomplete language coverage
+```
+
+#### Dimension 6: Implementation Feasibility
+
+```
+For EACH module:
+  - Is the handoff.filesToCreate list realistic? (no missing files, no impossible paths)
+  - Do brToCodeMapping entries have enough detail for generation?
+  - Are API endpoint paths following REST conventions?
+  - Are DTO structures aligned with entity attributes?
+  - Is the seed data sufficient for testing all use cases?
+  - Are there any features that would require infrastructure not in the stack?
+
+Flag: Unrealistic file counts, vague BR mappings, non-RESTful routes,
+      missing seed data for critical test scenarios
+```
+
+3. **Produce Quality Verdict:**
+
+```
+═══════════════════════════════════════════════════════════════
+  ULTRATHINK QUALITY REVIEW - RESULTS
+═══════════════════════════════════════════════════════════════
+
+| Dimension | Score | Issues |
+|-----------|-------|--------|
+| Specification Coherence | A/B/C/D | {count} issues |
+| Permission & Security | A/B/C/D | {count} issues |
+| Data Model Integrity | A/B/C/D | {count} issues |
+| UI/UX Completeness | A/B/C/D | {count} issues |
+| i18n & Messages | A/B/C/D | {count} issues |
+| Implementation Feasibility | A/B/C/D | {count} issues |
+
+Overall Quality: {A/B/C/D}
+  A = Production-ready (0 critical, ≤3 warnings)
+  B = Good (0 critical, >3 warnings)
+  C = Needs fixes (1-2 critical issues)
+  D = Major rework needed (>2 critical issues)
+```
+
+4. **Display Issues (if any):**
+
+```
+Critical Issues (MUST fix before /ralph-loop):
+  ✗ [Dimension] Issue description
+    → Fix: Specific action to resolve
+
+Warnings (SHOULD fix, not blocking):
+  ⚠ [Dimension] Issue description
+    → Recommendation: How to improve
+
+Suggestions (nice-to-have):
+  ℹ [Dimension] Suggestion
+```
+
+5. **Decision:**
+
+```
+IF overall quality = D:
+  BLOCKING ERROR: Major quality issues detected
+  → Return to appropriate step to fix critical issues
+  → DO NOT proceed to structural validation
+
+IF overall quality = C:
+  Ask via AskUserQuestion:
+    question: "Des problèmes de qualité ont été détectés. Comment souhaitez-vous procéder ?"
+    header: "Qualité"
+    options:
+      - label: "Corriger les problèmes critiques"
+        description: "Retourner aux étapes concernées pour corriger"
+      - label: "Continuer malgré les problèmes"
+        description: "Accepter les risques et poursuivre la validation structurelle"
+
+IF overall quality = A or B:
+  Display: "✓ Quality review passed — proceeding to structural validation..."
+  → Continue to section 1
 ```
 
 ---
@@ -394,10 +563,11 @@ Progress Tracker Validation:
 
 **Process:**
 
-1. Aggregate all validation results
+1. Aggregate all validation results (quality review + 7 structural checks)
 2. Calculate readiness score:
    ```
    passedChecks / totalChecks * 100
+   Quality gate: overall quality must be A or B
    ```
 
 3. Display final report:
@@ -407,17 +577,23 @@ Progress Tracker Validation:
   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)
+ULTRATHINK Quality Review:
+  Quality Score: {A/B} — {Production-ready / Good}
+  Dimensions: {6/6 reviewed}
+  Critical issues: {0}
+  Warnings: {count}
+
+Structural Validation Summary:
+  ✓ Module status validation: PASS ({n}/{n} modules)
+  ✓ PRD files validation: PASS ({n}/{n} files)
+  ✓ Dependency graph validation: PASS ({n} edges)
+  ✓ Cross-module references validation: PASS ({n} references)
+  ✓ Handoff completeness check: PASS ({n}/{n} modules)
+  ⚠ i18n keys validation: WARNING ({n} missing translation)
   ✓ Master feature validation: PASS
   ✓ Progress tracker validation: PASS
 
-Readiness Score: 100% (7/7 critical checks passed, 1 warning)
+Readiness Score: 100% (8/8 checks passed, {n} warnings)
 
 ═══════════════════════════════════════════════════════════════
 
@@ -425,23 +601,26 @@ Status: READY FOR DEVELOPMENT ✓
 
 Next Steps:
   1. Address warnings (recommended but not blocking):
-     - Add missing DE translation for "timeEntry.validation.overlapping" in TimeTracking module
+     - {list warnings from quality review + structural checks}
 
   2. Review progress tracker: .ralph/progress.txt
 
   3. When ready, launch development:
 
-     /ralph-loop -r
+     /ralph-loop
+
+     Note: Use /ralph-loop -r ONLY to resume an interrupted loop.
+           After a fresh /business-analyse, always use /ralph-loop (without -r).
 
   4. Ralph-loop will:
-     - Process modules in topological order: [Projects, TimeTracking, LeaveManagement, AbsenceManagement, Reporting]
-     - Generate 183 files across 7 layers
-     - Execute 247 tasks tracked in progress.txt
+     - Process modules in topological order: [{module list}]
+     - Generate {n} files across 7 layers
+     - Execute {n} tasks tracked in progress.txt
 
 ═══════════════════════════════════════════════════════════════
 ```
 
-**IF readiness score < 100% (critical checks failed):**
+**IF readiness score < 100% OR quality = C/D (critical checks failed):**
 
 ```
 ═══════════════════════════════════════════════════════════════
@@ -450,21 +629,24 @@ Next Steps:
 
 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
+{IF quality = C/D:}
+Quality Issues Found:
+  ✗ ULTRATHINK quality review: {C/D} — {Needs fixes / Major rework}
+    - {List critical quality issues from section 0b}
+    - Fix: Return to appropriate step (see quality review details above)
 
-  ✗ 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 docs/business/HumanResources/Reporting/business-analyse/v1.0/feature.json --output .ralph/prd-Reporting.json
+{IF structural checks failed:}
+Structural Issues Found:
+  ✗ {check name}: FAIL ({details})
+    - {specific issue}
+    - Fix: {specific action}
 
 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
+  3. Only proceed to /ralph-loop when all checks pass AND quality ≥ B
 
-DO NOT PROCEED TO /ralph-loop UNTIL ALL CRITICAL CHECKS PASS
+DO NOT PROCEED TO /ralph-loop UNTIL ALL CHECKS PASS
 ═══════════════════════════════════════════════════════════════
 ```
 
@@ -474,22 +656,25 @@ DO NOT PROCEED TO /ralph-loop UNTIL ALL CRITICAL CHECKS PASS
 
 Before displaying final report, VERIFY:
 
-1. **ALL validation checks executed** (never skip)
-2. **Results clearly marked** (PASS/FAIL/WARNING)
-3. **Actionable fixes provided** for all failures
-4. **Readiness score calculated** correctly
-5. **Next steps displayed** with exact commands
-6. **Blocking errors prevent progression** (no false positives)
+1. **ULTRATHINK quality review executed** (6 dimensions analyzed)
+2. **Quality verdict displayed** with scores per dimension
+3. **ALL 8 structural validation checks executed** (never skip)
+4. **Results clearly marked** (PASS/FAIL/WARNING)
+5. **Actionable fixes provided** for all failures
+6. **Readiness score calculated** correctly
+7. **Next steps displayed** with exact commands
+8. **Blocking errors prevent progression** (no false positives)
 
 ---
 
 ## SUCCESS CRITERIA
 
-- All 7 critical validation checks executed
+- ULTRATHINK quality review completed with overall score A or B
+- All 8 critical validation checks executed (quality review + 7 structural)
 - Clear PASS/FAIL/WARNING status for each check
 - Readiness score displayed (100% = all critical checks passed)
 - Actionable fix instructions for all failures
-- User can proceed to /ralph-loop only if readiness score = 100%
+- User can proceed to /ralph-loop only if readiness score = 100% AND quality ≥ B
 - Warnings documented but not blocking
 
 ---
@@ -498,6 +683,7 @@ Before displaying final report, VERIFY:
 
 **Why this gate matters:**
 
+- **ULTRATHINK catches semantic issues** that structural checks miss (orphan UCs, incoherent permissions, missing UI flows)
 - Prevents incomplete handoffs from reaching development
 - Catches structural issues early (PRD validation)
 - Verifies cross-module integrity before code generation
@@ -506,8 +692,7 @@ Before displaying final report, VERIFY:
 
 **When to run this gate:**
 
-- Automatically at end of step-05b-deploy.md (recommended)
-- Manually before /ralph-loop if user wants to verify
+- **Automatically at end of step-05b-deploy.md (MANDATORY)**
 - After fixing any handoff issues to re-validate
 
 **What happens if checks fail:**
@@ -515,4 +700,4 @@ Before displaying final report, VERIFY:
 - Development is BLOCKED until issues are fixed
 - User returns to appropriate step to fix issues
 - Re-run validation after fixes
-- Only proceed when all critical checks pass
+- Only proceed when all critical checks pass AND quality review passes

package/templates/skills/business-analyse/steps/step-06-review.md

@@ -262,7 +262,8 @@ Artifacts regenerated:
 
 NEXT STEPS:
 1. Open the new ba-interactive.html to verify corrections
-2. Run /ralph-loop -r to start development from the updated analysis
+2. Run /ralph-loop to start development from the updated analysis
+   (Use /ralph-loop -r ONLY to resume an interrupted loop)
 ═══════════════════════════════════════════════════════════════
 ```
 

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

@@ -12,7 +12,7 @@
 > **Version:** {version}
 > **Validated Specs:** feature.json (validation.decision = APPROVED)
 > **Source:** `docs/business/{app}/{module}/business-analyse/v{version}/feature.json`
-> **Implementation:** `/ralph-loop -r`
+> **Implementation:** `/ralph-loop`
 
 ## DEVELOPER INSTRUCTIONS
 
@@ -20,9 +20,10 @@ This document is a self-contained prompt for Claude Code.
 
 **Lancement:**
 ```
-/ralph-loop -r
+/ralph-loop
 ```
-> Pre-generated `.ralph/prd.json` with atomic task breakdown.
+> Ralph-loop auto-detects BA artifacts and derives PRD task breakdowns.
+> Use `/ralph-loop -r` only to resume an interrupted loop.
 
 ---
 
@@ -178,6 +179,6 @@ From: `feature.specification.seedDataCore` (5 core files), `feature.specificatio
 
 **Lancement:**
 ```bash
-/ralph-loop -r
+/ralph-loop
 ```
 ```

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

@@ -34,7 +34,10 @@ Effort:    {total_days} days ({total_hours} hours)
   3. Si retours --> relancer /business-analyse pour une nouvelle itération
   4. Une fois validé, lancer le développement:
 
-     /ralph-loop -r
+     /ralph-loop
+
+     Note: /ralph-loop -r sert UNIQUEMENT à reprendre une boucle interrompue.
+           Après un /business-analyse, toujours utiliser /ralph-loop (sans -r).
 
 ═══════════════════════════════════════════════════════════════
 ```

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

@@ -353,7 +353,7 @@ Feature: {FEAT-XXX} {Feature Name}
 > **Module:** business/{application}/{module}
 > **Version:** 1.0
 > **Validated Specs:** Specification v1.0 (validation.json)
-> **Implementation:** `/ralph-loop -r`
+> **Implementation:** `/ralph-loop`
 
 ## DEVELOPER INSTRUCTIONS
 
@@ -361,9 +361,10 @@ This document is a self-contained prompt for Claude Code.
 
 **Lancement:**
 ```
-/ralph-loop -r
+/ralph-loop
 ```
-> Pre-generated `.ralph/prd.json` with atomic task breakdown.
+> Ralph-loop auto-detects BA artifacts and derives PRD task breakdowns.
+> Use `/ralph-loop -r` only to resume an interrupted loop.
 
 ---
 
@@ -459,7 +460,7 @@ FRONTEND:
 
 **Lancement:**
 ```bash
-/ralph-loop -r
+/ralph-loop
 ```
 ```
 

package/templates/skills/gitflow/references/start-local-config.md

@@ -50,11 +50,14 @@ EOF
 }
 ```
 
-## 7b. Frontend: .env.local + npm script
+## 7b. Frontend: .env.standalone + npm script
+
+> **IMPORTANT**: Vite 7+ forbids `"local"` as a mode name (conflicts with `.env.local` suffix).
+> The Vite mode is `standalone`, but the npm script stays `local` for user convenience.
 
 ```bash
 [ -n "$WEB_DIR" ] && [ -f "$WEB_DIR/package.json" ] && {
-  cat > "$WEB_DIR/.env.local" << EOF
+  cat > "$WEB_DIR/.env.standalone" << EOF
 VITE_API_URL=http://localhost:${API_PORT}
 VITE_APP_ENV=local
 VITE_DEBUG=true
@@ -66,7 +69,7 @@ EOF
       const fs = require('fs');
       const pkg = JSON.parse(fs.readFileSync('$WEB_DIR/package.json', 'utf8'));
       if (!pkg.scripts.local) {
-        pkg.scripts.local = 'vite --mode local --port ${WEB_PORT}';
+        pkg.scripts.local = 'vite --mode standalone --port ${WEB_PORT}';
         fs.writeFileSync('$WEB_DIR/package.json', JSON.stringify(pkg, null, 2) + '\n');
       }
     "

package/templates/skills/gitflow/steps/step-start.md

@@ -190,7 +190,7 @@ fi
 See [references/start-local-config.md](../references/start-local-config.md) for the full configuration:
 - **Port generation:** Unique ports per branch (API: 5200+, Web: 5300+) based on branch name hash
 - **7a. Backend:** `appsettings.Local.json` (DB connection, SmartStack config, Kestrel port)
-- **7b. Frontend:** `.env.local` + `npm run local` script
+- **7b. Frontend:** `.env.standalone` + `npm run local` script (Vite mode=standalone, not "local" which conflicts with .env.local in Vite 7+)
 - **7c. Backend:** `launchSettings.json` Local profile with unique port
 - **7d. Summary:** Display configured DB name, API port, Web port
 
@@ -276,7 +276,7 @@ See [references/start-local-config.md](../references/start-local-config.md) for
 - Worktree set up (if enabled)
 - Backend local config created: `appsettings.Local.json` (if .NET API detected)
 - Backend launch profile created: `launchSettings.json` Local profile with unique port (if .NET API detected)
-- Frontend local config created: `.env.local` + `npm run local` script (if web project detected)
+- Frontend local config created: `.env.standalone` + `npm run local` script (if web project detected)
 - Ports synchronized between backend and frontend (unique per branch)
 - State stored for subsequent steps
 

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

@@ -95,8 +95,41 @@ LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS
 - `scaffold_tests` — test generation
 </mcp_requirements>
 
+<execution_guarantee>
+
+## EXECUTION GUARANTEE — READ THIS FIRST
+
+**Ralph-loop executes ALL tasks from start to finish. No exceptions.**
+
+When the user invokes `/ralph-loop`, they are giving you the instruction to:
+1. Initialize the loop (step-00)
+2. Load ALL tasks (step-01)
+3. Execute the FIRST task (step-02)
+4. Commit (step-03)
+5. Enter the COMPACT LOOP (step-04 → compact-loop.md)
+6. **Execute ALL remaining tasks autonomously** (compact loop repeats)
+7. Generate the final report (step-05)
+
+**You MUST NOT:**
+- Stop after the first task to "ask for confirmation"
+- Set `max_iterations = 1` or any reduced value
+- Ask the user to choose between supervised/autonomous mode
+- Ask the user to choose a completion promise
+- Wait for user input between iterations
+- Delegate the loop to sub-agents (except team mode)
+
+**The ONLY valid stop conditions are:**
+- ALL tasks completed (→ step-05 report)
+- `max_iterations` reached (user set via `-m N`)
+- Dead-end (all remaining blocked/failed)
+- User Ctrl+C
+
+**If you stop for any other reason, you have VIOLATED this guarantee.**
+
+</execution_guarantee>
+
 <entry_point>
-**FIRST ACTION:** Load `steps/step-00-init.md`
+**FIRST ACTION:** Load `steps/step-00-init.md` — then execute ALL steps through to step-05 without stopping.
 </entry_point>
 
 <step_files>
@@ -134,6 +167,13 @@ LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS
 
 <execution_rules>
 
+### NON-NEGOTIABLE — Autonomous Full Execution
+- **EXECUTE ALL TASKS** — from first to last, no user interaction, no pause, no confirmation
+- **NEVER ask the user** — no mode selection, no completion promise choice, no "shall I continue?"
+- **NEVER stop after first task** — the first task is just the beginning, NOT the end
+- **NEVER set max_iterations = 1** — unless the user explicitly passed `-m 1`
+
+### Loop Mechanics
 - **Single module:** Main agent runs compact loop (NEVER delegate to sub-agent)
 - **Multi-module (2+):** Team lead + module workers via TeamCreate (see references/team-orchestration.md)
 - **Load step files ONCE** — after first iteration, use compact-loop.md