@atlashub/smartstack-cli 3.16.0 → 3.18.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,7 +601,7 @@ 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
 
@@ -434,14 +610,14 @@ Next Steps:
      /ralph-loop -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 +626,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 +653,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 +680,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 +689,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 +697,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/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

package/templates/skills/ralph-loop/references/category-rules.md

@@ -141,6 +141,86 @@ Rules:
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
 
+**Tenant isolation (BLOCKING — SECURITY CRITICAL):**
+
+> **ROOT CAUSE (test-v4-005):** Services were generated WITHOUT TenantId filtering,
+> creating cross-tenant data leakage on ALL 70+ CRUD endpoints.
+> This is an OWASP A01 (Broken Access Control) vulnerability.
+
+- ALL queries on tenant entities MUST include `.Where(x => x.TenantId == _currentUser.TenantId)`
+- ALL entity creation MUST pass `_currentUser.TenantId` as first parameter to `Entity.Create(tenantId, ...)`
+- NEVER use `new Entity { }` without `TenantId =` — always prefer factory method `Entity.Create()`
+- NEVER use `Guid.Empty` as a placeholder for userId, tenantId, or any business identifier
+- Service constructor MUST inject `ICurrentUserService _currentUser` to access TenantId
+
+**MANDATORY Service Template (use as skeleton for ALL services):**
+
+```csharp
+public class {Entity}Service : I{Entity}Service
+{
+    private readonly IExtensionsDbContext _db;
+    private readonly ICurrentUserService _currentUser;
+
+    public {Entity}Service(IExtensionsDbContext db, ICurrentUserService currentUser)
+    {
+        _db = db;
+        _currentUser = currentUser;
+    }
+
+    public async Task<PagedResult<{Entity}Response>> GetAllAsync(/* filters */, CancellationToken ct)
+    {
+        var tenantId = _currentUser.TenantId;
+        var query = _db.{Entities}
+            .Where(x => x.TenantId == tenantId)  // ← MANDATORY tenant filter
+            .AsQueryable();
+        // ... apply filters, pagination, projection to Response DTO
+    }
+
+    public async Task<{Entity}Response?> GetByIdAsync(Guid id, CancellationToken ct)
+    {
+        var tenantId = _currentUser.TenantId;
+        var entity = await _db.{Entities}
+            .Where(x => x.TenantId == tenantId)  // ← MANDATORY tenant filter
+            .FirstOrDefaultAsync(x => x.Id == id, ct);
+        // ...
+    }
+
+    public async Task<{Entity}Response> CreateAsync(Create{Entity}Dto dto, CancellationToken ct)
+    {
+        var entity = {Entity}.Create(_currentUser.TenantId, /* dto fields */);
+        // ← TenantId as FIRST parameter
+        _db.{Entities}.Add(entity);
+        await _db.SaveChangesAsync(ct);
+        return MapToResponse(entity);
+    }
+
+    public async Task<{Entity}Response> UpdateAsync(Guid id, Update{Entity}Dto dto, CancellationToken ct)
+    {
+        var entity = await _db.{Entities}
+            .Where(x => x.TenantId == _currentUser.TenantId)  // ← MANDATORY
+            .FirstOrDefaultAsync(x => x.Id == id, ct)
+            ?? throw new NotFoundException(nameof({Entity}), id);
+        // ... update fields
+    }
+
+    public async Task DeleteAsync(Guid id, CancellationToken ct)
+    {
+        var entity = await _db.{Entities}
+            .Where(x => x.TenantId == _currentUser.TenantId)  // ← MANDATORY
+            .FirstOrDefaultAsync(x => x.Id == id, ct)
+            ?? throw new NotFoundException(nameof({Entity}), id);
+        // ...
+    }
+
+    private static {Entity}Response MapToResponse({Entity} entity) => new()
+    {
+        // Map entity fields to response DTO
+    };
+}
+```
+
+**POST-CHECK after writing ANY service:** Grep the file for `TenantId`. If 0 occurrences → FAIL, rewrite with tenant filtering.
+
 **Lifecycle-aware services:**
 - Services operating on entities with a `lifeCycle` (status field) MUST validate entity state before mutations
 - Example: `if (entity.Status == EmployeeStatus.Terminated) throw new BusinessException("Cannot update terminated employee")`
@@ -154,10 +234,31 @@ Rules:
 - DependencyInjection.cs MUST NOT be empty or contain only TODO comments
 - After writing validators, VERIFY DI registration exists — if missing, add it immediately
 
+**POST-CHECK after writing validators:**
+```bash
+# Count Create validators vs Update validators
+CREATE_COUNT=$(find . -path "*/Validators/*" -name "Create*Validator.cs" | wc -l)
+UPDATE_COUNT=$(find . -path "*/Validators/*" -name "Update*Validator.cs" | wc -l)
+if [ "$CREATE_COUNT" -ne "$UPDATE_COUNT" ]; then
+  echo "VALIDATOR MISMATCH: $CREATE_COUNT Create vs $UPDATE_COUNT Update → MUST be equal"
+  # List missing UpdateValidators and CREATE them
+fi
+```
+
+**Mapper pattern (DRY):**
+- Each service MUST include a `private static {Entity}Response MapToResponse({Entity} entity)` method
+- For complex mappings with related entities, use an extension method in `Application/Mappings/{Module}Mappings.cs`
+- NEVER duplicate mapping logic between GetAll, GetById, Create, Update — always call MapToResponse
+
 **FORBIDDEN:**
 - Empty DependencyInjection.cs with `// TODO` placeholder
 - CreateValidator without matching UpdateValidator
 - Validators not registered in DI container
+- Service query without TenantId filter (cross-tenant data leak)
+- `new Entity { }` without TenantId assignment
+- `Guid.Empty` as a business value in services or controllers
+- Entity.Create() without tenantId as first parameter
+- Duplicated mapping logic (entity→response) in multiple methods
 
 ---
 
@@ -269,9 +370,13 @@ useXxx with raw axios inside hooks           → hooks MUST use the shared apiCl
 
 **MCP:** `scaffold_tests`, `analyze_test_coverage`
 
+> **CRITICAL:** Test generation is a MANDATORY category. If the PRD has no test tasks,
+> the category completeness check (step-01 section 4b) will inject a guardrail task.
+> Test projects MUST be created as the FIRST action in this category — before generating any test files.
+
 **Execution sequence:**
 
-1. **Ensure test projects exist:**
+1. **Ensure test projects exist (FIRST — before any test generation):**
    ```bash
    # Unit test project
    UNIT_TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"