@atlashub/smartstack-cli 3.10.0 → 3.12.0

package/templates/skills/debug/references/team-protocol.md

@@ -0,0 +1,232 @@
+# Team Protocol — Debug Investigation
+
+> **Loaded by:** SKILL.md phase 2 (EXPLORE)
+> **Purpose:** Coordinate parallel investigation agents for bug diagnosis.
+> **Pattern:** APEX-style (single session, parallel scan, aggregated results)
+
+---
+
+## 1. Team Creation
+
+```yaml
+TeamCreate:
+  team_name: "debug-investigate"
+  description: "Parallel bug investigation team"
+```
+
+---
+
+## 2. Teammate Spawn
+
+Spawn all teammates **in a single message** (parallel Task calls):
+
+| Teammate | Model | Scope | Tools |
+|----------|-------|-------|-------|
+| `code-investigator` | haiku | Codebase search | Read, Glob, Grep, Bash |
+| `doc-researcher` | haiku | Documentation + web | Read, Glob, Grep, WebSearch, WebFetch |
+| `data-inspector` | haiku | Database READ-ONLY | Read, Glob, Grep, Bash |
+
+**`data-inspector`**: spawn ONLY if the bug involves data, persistence, or database operations. Otherwise spawn only 2 teammates.
+
+```yaml
+# For each teammate:
+Task:
+  subagent_type: "general-purpose"
+  team_name: "debug-investigate"
+  name: "{teammate-name}"
+  model: "haiku"
+  mode: "bypassPermissions"
+  prompt: "{TEAMMATE_PROMPT}"
+```
+
+---
+
+## 3. Communication Protocol
+
+### Messages from teammates → team-lead
+
+| Message | When | Format |
+|---------|------|--------|
+| `FINDING` | Significant discovery | `FINDING: {description with file paths and line numbers}` |
+| `INVESTIGATION_COMPLETE` | Agent finished all checks | `INVESTIGATION_COMPLETE: {summary of all findings}` |
+
+**Rules:**
+- Send `FINDING` as soon as a significant discovery is made (don't wait until the end)
+- Always include **file paths with line numbers** in findings
+- Send exactly ONE `INVESTIGATION_COMPLETE` when done
+
+### Messages from team-lead → teammates
+
+| Message | When | Format |
+|---------|------|--------|
+| `LEAD_HINT` | Lead wants to orient a search | `LEAD_HINT: {new direction to investigate}` |
+
+**Rules:**
+- Lead sends hints based on cross-agent findings (e.g., code-investigator found a file, ask data-inspector to check related records)
+- Hints are optional — only when findings from one agent inform another's search
+
+### Example Flow
+
+```
+code-investigator → lead:  FINDING: NullRef at OrderService.cs:45 — Customer lookup returns null
+lead → data-inspector:     LEAD_HINT: Check if Customer records exist for OrderId=123, verify FK integrity Orders→Customers
+data-inspector → lead:     FINDING: FK broken — Order.CustomerId=99 has no matching Customer record (deleted without cascade)
+doc-researcher → lead:     FINDING: EF Core docs warn about cascade delete config — OnDelete(DeleteBehavior.Restrict) may leave orphans
+code-investigator → lead:  INVESTIGATION_COMPLETE: Source at OrderService.cs:45, no null check before Customer access
+data-inspector → lead:     INVESTIGATION_COMPLETE: 3 orphaned Orders found, TenantId OK, audit fields present
+doc-researcher → lead:     INVESTIGATION_COMPLETE: EF Core cascade delete misconfiguration documented
+```
+
+---
+
+## 4. Teammate Prompts
+
+### code-investigator
+
+```
+You are a code investigator on the debug team.
+
+## Bug Context
+Error: {error_description}
+Stack trace: {stack_trace}
+
+## Your Mission
+1. Locate the error source in code (from stack trace)
+2. Find related error handling patterns
+3. Identify similar code that works correctly (for comparison)
+4. Check recent commits on affected files (git log --oneline -10, git blame)
+5. Search for similar error patterns elsewhere in codebase
+
+## Communication Protocol
+- Send FINDING messages to team-lead for each significant discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
+- When done, send:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Code investigation done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Tools
+- Read, Glob, Grep for code search
+- Bash ONLY for: git log, git blame, git diff (NEVER for code modification)
+
+## Output
+Report file paths with line numbers. Be precise and factual.
+```
+
+### doc-researcher
+
+```
+You are a documentation researcher on the debug team.
+
+## Bug Context
+Error: {error_description}
+Libraries/frameworks in stack trace: {libraries_in_stacktrace}
+
+## Your Mission
+1. Research documentation for libraries in the stack trace
+2. Find known issues or breaking changes
+3. Find correct usage patterns
+4. Search for similar issues reported by others online
+5. Look for migration guides if version issues suspected
+
+## Communication Protocol
+- Send FINDING messages to team-lead for each discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
+- When done, send:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Doc research done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Tools
+- Read, Glob, Grep for local documentation search
+- WebSearch, WebFetch for online documentation and issue trackers
+```
+
+### data-inspector
+
+```
+You are a READ-ONLY database inspector on the debug team.
+
+## Bug Context
+Error: {error_description}
+
+## ABSOLUTE RESTRICTIONS — READ BEFORE EVERY BASH COMMAND
+YOU MUST NEVER EXECUTE:
+- INSERT, UPDATE, DELETE, MERGE, TRUNCATE
+- DROP, ALTER, CREATE, RENAME
+- EXEC, EXECUTE (stored procedures)
+- dotnet ef database update, dotnet ef migrations
+- ANY command that writes, modifies, or deletes data or schema
+
+YOU MAY ONLY EXECUTE:
+- SELECT queries
+- INFORMATION_SCHEMA queries
+- sys.* catalog views
+- sp_help, sp_helptext, sp_columns
+
+## Your Mission
+1. Find the connection string (appsettings.json, appsettings.Development.json)
+2. Check record existence and field values for affected entities
+3. Verify foreign key integrity (orphaned records)
+4. Check tenant isolation (TenantId present on all records)
+5. Verify soft delete and audit field consistency
+6. Compare actual schema vs expected EF Core model
+
+## Communication Protocol
+- Send FINDING messages to team-lead for each data anomaly:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Data issue {short}")
+- When done, send:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "DB inspection done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Tools
+- Read, Glob, Grep for connection string and config discovery
+- Bash ONLY for SELECT queries (NEVER modify data)
+
+## Output
+- Use markdown tables for query results
+- Mask sensitive data (passwords, tokens, PII)
+- Limit results with TOP/LIMIT to avoid overwhelming output
+- If a data fix is needed, DESCRIBE it — NEVER execute it
+```
+
+---
+
+## 5. Team Lead Aggregation
+
+After receiving all `INVESTIGATION_COMPLETE` messages:
+
+```
+1. Collect all FINDING messages from each agent
+2. Cross-reference findings (code issues ↔ data anomalies ↔ documentation)
+3. Build the root cause chain: symptom → immediate cause → root cause
+4. Shutdown teammates
+5. Proceed to ULTRA-THINK phase (inline)
+```
+
+---
+
+## 6. Graceful Shutdown
+
+After aggregation (or if investigation is sufficient before all complete):
+
+```yaml
+# For each teammate:
+SendMessage:
+  type: "shutdown_request"
+  recipient: "{teammate-name}"
+  content: "Investigation complete, shutting down"
+
+# Wait for shutdown_response from each, then:
+TeamDelete
+```
+
+---
+
+## 7. Decision Matrix
+
+| Condition | Action |
+|-----------|--------|
+| Simple error, obvious from stack trace | NO team — inline investigation |
+| Error involves code + data | Team: code-investigator + data-inspector |
+| Error involves unknown library | Team: code-investigator + doc-researcher |
+| Complex bug, multiple suspects | Full team: all 3 agents |
+| Performance issue (no error) | code-investigator only (profiling inline) |

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

@@ -75,10 +75,17 @@ Execution sequence:
 - IClientSeedDataProvider: SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
 - DI: `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()`
 
+**Business seed data (DevDataSeeder):**
+- ALL seeded business entities MUST include `TenantId = {tenantGuid}`
+- Reference entities (types, categories, statuses) MUST set TenantId
+- Use deterministic TenantId from SeedConstants (NEVER hardcoded inline)
+- DevDataSeeder MUST implement `IDevDataSeeder` with idempotent `SeedAsync()` method
+
 **FORBIDDEN:**
 - `Guid.NewGuid()` → use deterministic GUIDs
 - Empty seed data classes with only GUIDs and no seeding methods
 - Missing translations (must have all 4 languages)
+- Seeding business entities WITHOUT `TenantId`
 
 ---
 
@@ -118,6 +125,24 @@ Rules:
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
 
+**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")`
+- Guard checks MUST match the `allowedTransitions` from the entity's lifecycle definition
+- Delete/archive operations MUST respect terminal states (`isTerminal: true`)
+
+**Validator completeness (BLOCKING):**
+- For EVERY `Create{Entity}Validator`, a matching `Update{Entity}Validator` MUST exist
+- ALL validators MUST be registered in `Application/DependencyInjection.cs`:
+  `services.AddValidatorsFromAssemblyContaining<Create{Entity}Validator>()`
+- DependencyInjection.cs MUST NOT be empty or contain only TODO comments
+- After writing validators, VERIFY DI registration exists — if missing, add it immediately
+
+**FORBIDDEN:**
+- Empty DependencyInjection.cs with `// TODO` placeholder
+- CreateValidator without matching UpdateValidator
+- Validators not registered in DI container
+
 ---
 
 ## API
@@ -140,9 +165,15 @@ Rules:
 - Consistent route patterns: `api/{context}/{app}/{module}`
 - Return DTOs, never domain entities
 
+**Controller coverage (BLOCKING):**
+- EVERY entity in the module MUST have a controller with CRUD endpoints (GET list, GET by id, POST, PUT, DELETE)
+- Reference/lookup entities (types, categories, statuses) MUST also have controllers — they are needed for dropdowns and configuration
+- Count: `controllers created >= entities in module`. If fewer → FAIL
+
 **FORBIDDEN:**
 - `[Authorize]` without specific permission → use `[RequirePermission]`
 - Returning domain entities directly
+- Skipping controllers for reference/lookup entities
 
 ---
 
@@ -178,6 +209,18 @@ Rules:
 
 **CSS:** Variables ONLY → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
 
+**Form error handling (MANDATORY):**
+- ALL SmartForm components MUST include `onError` callback for API errors
+- Validation errors MUST be displayed inline next to the relevant field
+- API errors (4xx, 5xx) MUST show a user-friendly error notification (toast/banner)
+- Forms MUST preserve user input on error (no data loss on failed submit)
+
+**Dependency verification (BLOCKING):**
+- BEFORE writing any import, verify the package exists in `package.json`
+- If package not present: run `npm install {package}` BEFORE writing the import
+- Common missing packages: @tanstack/react-query, recharts, date-fns, react-router-dom
+- After ALL frontend tasks: run `npm ls --depth=0` to detect any MISSING dependencies
+
 **FORBIDDEN patterns (any = FAIL):**
 ```
 import axios from 'axios'                    → use @/services/api/apiClient
@@ -186,6 +229,9 @@ import axios from 'axios'                    → use @/services/api/apiClient
 <Route path="/business/app/mod" />           → MUST be nested inside Layout
 Only fr/en translations                      → MUST have 4 languages
 src/pages/{Module}/                          → MUST be src/pages/{Context}/{App}/{Module}/
+'00000000-0000-0000-0000-000000000000'       → use dynamic ID from auth context or route params
+const api = axios.create(...)                → use @/services/api/apiClient (single instance)
+useXxx with raw axios inside hooks           → hooks MUST use the shared apiClient from @/services/api
 ```
 
 ---

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -71,8 +71,25 @@ Batch: {batch.length} [{firstCategory}] → {batch.map(t => `[${t.id}] ${t.descr
    - Backend (domain/infra/app/api): `dotnet build --no-restore` → MUST exit 0
    - Frontend: `npm run typecheck` → MUST exit 0
 3. If build fails → read FULL error output → fix source code → rebuild → loop until pass
-4. Verify acceptance criteria
-5. If failed after 3 attempts: `task.status = 'failed'`, `task.error = reason`, continue to next in batch
+4. **ARTIFACT verification (BLOCKING per task):**
+   - `files_created` MUST NOT be empty for code-generating tasks
+   - Category-specific checks (see below)
+   - IF no artifacts produced → task.status = 'failed', task.error = 'No artifacts created'
+5. Verify acceptance criteria from task description
+6. If failed after 3 attempts: `task.status = 'failed'`, `task.error = reason`, continue to next in batch
+
+**Category-specific artifact checks (step 4 above):**
+
+| Category | Artifact Check | FAIL if |
+|----------|---------------|---------|
+| `domain` | Entity .cs files exist in Domain/ | 0 files created |
+| `infrastructure` with migration | `Migrations/` folder has .cs files | No migration files |
+| `infrastructure` with seed data | Seed data .cs files exist | 0 files created |
+| `application` | Service + DTO + Validator files exist | 0 files created |
+| `api` | Controller .cs files exist | 0 files created |
+| `frontend` | .tsx page files exist | 0 files created |
+| `test` | Test project dir exists AND contains test .cs files | No test project or 0 test files |
+| `validation` | `dotnet test` exit 0 AND `dotnet build` exit 0 | Either command fails |
 
 **Category-specific triggers:**
 
@@ -99,12 +116,25 @@ Batch: {batch.length} [{firstCategory}] → {batch.map(t => `[${t.id}] ${t.descr
    ```
    If FAIL → fix source code (NOT tests) → rebuild → retest → loop until 100% pass
 
+2bis. **DI completeness (if application tasks in batch):**
+   Verify `Application/DependencyInjection.cs` registers all validators and services:
+   - Count validators in `Validators/` folder
+   - Verify `AddValidatorsFromAssemblyContaining` is present
+   - If empty/TODO → FAIL → fix DI registration → rebuild
+
 3. **Frontend (if frontend/i18n tasks in batch):**
    ```bash
    npm run typecheck && npm run lint
    ```
    If FAIL → fix → re-check → loop until pass
 
+3bis. **Dependency audit (if frontend tasks in batch):**
+   ```bash
+   cd {frontend_dir}
+   npm ls --depth=0 2>&1 | grep "MISSING" && echo "FAIL: missing deps" && exit 1
+   ```
+   If FAIL → `npm install {missing_packages}` → re-check → loop until pass
+
 4. **MCP validation:**
    `mcp__smartstack__validate_conventions` ONCE for the whole batch
 

package/templates/skills/ralph-loop/references/core-seed-data.md

@@ -688,3 +688,63 @@ Before marking the task as completed, verify ALL:
 - [ ] `dotnet build` passes after generation
 
 **If ANY check fails, the task status = 'failed'.**
+
+---
+
+## 9. Business Seed Data (DevDataSeeder) — TenantId Rules
+
+> **Applies to:** Seed data for business entities (reference types, categories, statuses).
+> **NOT the same as** core seed data above (navigation, permissions, roles).
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| TenantId MANDATORY | ALL business seed entities MUST set `TenantId` |
+| Deterministic TenantId | Use `SeedConstants.DefaultTenantId` (NEVER inline GUID) |
+| DevDataSeeder pattern | Implement `IDevDataSeeder` with `SeedAsync()` method |
+| Idempotency | Each seeder MUST check `AnyAsync()` before inserting |
+| Order | DevDataSeeder `Order >= 200` (after core seed data at Order 100) |
+
+### Template (Reference Types)
+
+```csharp
+public class {Module}DevDataSeeder : IDevDataSeeder
+{
+    public int Order => 200; // After core seed data (Order 100)
+
+    public async Task SeedAsync(ExtensionsDbContext context, CancellationToken ct)
+    {
+        if (await context.Set<{EntityType}>().AnyAsync(ct)) return;
+
+        var items = new[]
+        {
+            new {EntityType}
+            {
+                Id = GenerateDeterministicGuid("{entity-type}-{code}"),
+                Code = "{code}",
+                Name = "{name}",
+                TenantId = SeedConstants.DefaultTenantId,  // MANDATORY
+                IsActive = true
+            }
+        };
+
+        context.Set<{EntityType}>().AddRange(items);
+        await context.SaveChangesAsync(ct);
+    }
+
+    private static Guid GenerateDeterministicGuid(string seed)
+    {
+        using var sha256 = System.Security.Cryptography.SHA256.Create();
+        var hash = sha256.ComputeHash(System.Text.Encoding.UTF8.GetBytes(seed));
+        return new Guid(hash.Take(16).ToArray());
+    }
+}
+```
+
+### FORBIDDEN
+
+- Seeding business entities WITHOUT `TenantId`
+- Using `Guid.NewGuid()` for TenantId
+- Omitting idempotency check (`AnyAsync`)
+- Hardcoding TenantId inline (use `SeedConstants.DefaultTenantId`)

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

@@ -48,7 +48,70 @@ mcp__context7__resolve-library-id: libraryName: "test"  → {mcp_context7} = tru
 
 If ANY fails: show error, suggest `smartstack check-mcp`, STOP.
 
-## 3. Resume Mode
+## 3. Human-in-the-Loop Checkpoint (RECOMMENDED)
+
+> **Best Practice:** Commencer en mode supervisé avant le mode autonome complet.
+
+### Why HITL First?
+
+Ralph-loop est puissant mais peut diverger si :
+- Les requirements sont ambigus
+- Les tests sont lents (>30s)
+- Le code généré ne compile pas immédiatement
+
+**Stratégie recommandée :**
+
+1. **Première itération supervisée** - Lancer manuellement la première tâche pour vérifier :
+   - La qualité du code généré
+   - Le temps d'exécution des tests
+   - La clarté des messages d'erreur
+
+2. **Mode autonome limité** - Si première itération OK, relancer avec `--max-iterations 5-10`
+
+3. **Mode autonome complet** - Une fois confiant, augmenter à `--max-iterations 50`
+
+### Checkpoint Prompt (Optional)
+
+Si vous détectez que c'est la première utilisation de ralph-loop sur ce projet (pas de `.ralph/logs/`), proposer :
+
+```javascript
+if (!dirExists('.ralph/logs') && !resume_mode) {
+  AskUserQuestion({
+    questions: [{
+      question: "Premier usage de ralph-loop détecté. Démarrer en mode supervisé ou autonome ?",
+      header: "Mode",
+      multiSelect: false,
+      options: [
+        { label: "Supervisé (recommandé)", description: "Exécuter 1 tâche, puis demander confirmation" },
+        { label: "Autonome limité", description: "Max 10 itérations automatiques" },
+        { label: "Autonome complet", description: "Jusqu'à 50 itérations (mode AFK)" }
+      ]
+    }]
+  });
+
+  if (answer === "Supervisé") {
+    max_iterations = 1;
+    console.log("Mode supervisé : 1 tâche sera exécutée. Relancez avec -r pour continuer.");
+  } else if (answer === "Autonome limité") {
+    max_iterations = Math.min(max_iterations, 10);
+  }
+}
+```
+
+### Feedback Speed Warning
+
+⚠️ **IMPORTANT :** Si vos tests prennent >30 secondes, ralph-loop peut devenir inefficace.
+
+```
+Temps test recommandés :
+  - Unitaires : <5s
+  - Intégration : <15s
+  - E2E : <30s (à exécuter en dehors du loop)
+```
+
+Si tests lents détectés (via logs), avertir l'utilisateur et suggérer de désactiver tests E2E pendant le loop.
+
+## 4. Resume Mode
 
 If `{resume_mode} = true`:
 

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -40,12 +40,20 @@ if [ -d "$TEST_PROJECT" ]; then
   dotnet test "$TEST_PROJECT" --no-build --verbosity normal
   if [ $? -ne 0 ]; then
     echo "TEST REGRESSION — creating fix task"
-    # Inject fix task into prd.json:
     prd.tasks.push({ id: maxId+1, description: "Fix test regression — all tests must pass",
       status: "pending", category: "validation", dependencies: [],
       acceptance_criteria: "dotnet test exits 0, all tests pass" });
     writeJSON('.ralph/prd.json', prd);
   fi
+else
+  # CRITICAL: Test project MUST exist if test tasks are marked completed
+  const testTasksDone = prd.tasks.filter(t => t.category === 'test' && t.status === 'completed');
+  if (testTasksDone.length > 0) {
+    echo "ARTIFACT MISSING — test tasks marked completed but no test project exists"
+    // Reset test tasks to pending and inject guardrail
+    testTasksDone.forEach(t => { t.status = 'pending'; t.error = null; t.completed_at = null; });
+    writeJSON('.ralph/prd.json', prd);
+  fi
 fi
 ```
 
@@ -99,11 +107,28 @@ if (fileExists(queuePath)) {
   const queue = readJSON(queuePath);
   const currentModule = queue.modules[queue.currentIndex];
 
-  // MODULE COMPLETENESS CHECK: verify all expected layers
+  // MODULE COMPLETENESS CHECK: verify all expected layers AND their artifacts
   const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
   const expected = ['domain', 'infrastructure', 'application', 'api', 'frontend', 'test'];
   const missing = expected.filter(c => !completedCats.has(c));
 
+  // ARTIFACT EXISTENCE CHECK: categories with completed tasks must have real files
+  const artifactChecks = {
+    'infrastructure': () => fs.existsSync('src/*/Persistence/Migrations') && fs.readdirSync('src/*/Persistence/Migrations').length > 0,
+    'test': () => fs.existsSync(`tests/${projectName}.Tests.Unit`) && glob.sync('tests/**/*Tests.cs').length > 0,
+    'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0,
+    'frontend': () => glob.sync('**/src/pages/**/*.tsx').length > 0
+  };
+  for (const [cat, check] of Object.entries(artifactChecks)) {
+    if (completedCats.has(cat) && !check()) {
+      // Tasks marked completed but artifacts missing — reset to pending
+      prd.tasks.filter(t => t.category === cat && t.status === 'completed')
+        .forEach(t => { t.status = 'pending'; t.error = 'Artifacts missing — re-execute'; t.completed_at = null; });
+      missing.push(cat);
+      console.log(`ARTIFACT RESET: ${cat} tasks reset to pending (no files found)`);
+    }
+  }
+
   if (missing.length > 0) {
     // Inject guardrail tasks for missing layers
     let maxId = Math.max(...prd.tasks.map(t => t.id));