@atlashub/smartstack-cli 3.36.0 → 3.38.0

package/templates/skills/ralph-loop/steps/step-02-execute.md

@@ -54,160 +54,14 @@ writeJSON('.ralph/prd.json', prd);
 
 #### 3a. Parallel Mode (if `-p` flag)
 
-**IF `{parallel_mode}` == true:**
-
-##### Phase 0: Foundation (Ralph sequential)
-
-```javascript
-// Collect ALL entities from ALL modules
-const allEntities = [];
-const allModules = [];
-for (const prdFile of glob('.ralph/prd-*.json')) {
-  const modulePrd = readJSON(prdFile);
-  const moduleEntities = modulePrd.tasks
-    .filter(t => t.category === 'domain')
-    .map(t => extractEntityName(t.description));
-  allEntities.push(...moduleEntities);
-  allModules.push({
-    code: modulePrd.project.module,
-    application: modulePrd.project.application,
-    prdFile: prdFile,
-    entityCount: moduleEntities.length
-  });
-}
-
-console.log(`PARALLEL MODE: Phase 0 — Foundation`);
-console.log(`  Generating ${allEntities.length} entities from ${allModules.length} modules`);
-console.log(`  Entities: ${allEntities.join(', ')}`);
-
-// Ralph generates ALL entities via apex foundation mode
-// INVOKE: /apex --foundation -d .ralph/prd.json
-//
-// Apex will:
-// - Generate ALL entity classes
-// - Generate ALL EF configurations
-// - Register ALL DbSets in DbContext
-// - Create ONE migration with all entities
-// - Skip services/controllers/frontend/tests
-
-console.log(`Phase 0 completed. ModelSnapshot contains ${allEntities.length} entities.`);
-console.log(`Committing foundation...`);
-
-// Git commit
-// bash: git add . && git commit -m "chore(foundation): entities for all modules"
-```
-
-##### Phase 1-N: Spawn Teammates (parallel)
-
-```javascript
-// Determine granularity: 1 teammate per APPLICATION or per MODULE
-const teammates = [];
-const applicationsMap = {}; // group modules by application
-
-for (const mod of allModules) {
-  if (!applicationsMap[mod.application]) {
-    applicationsMap[mod.application] = [];
-  }
-  applicationsMap[mod.application].push(mod);
-}
-
-for (const [appName, modules] of Object.entries(applicationsMap)) {
-  if (modules.length <= 3) {
-    // 1 teammate per APPLICATION
-    teammates.push({
-      name: `apex-${kebabCase(appName)}`,
-      application: appName,
-      modules: modules.map(m => m.code),
-      prdFiles: modules.map(m => m.prdFile)
-    });
-  } else {
-    // Application has >3 modules → 1 teammate per MODULE
-    for (const mod of modules) {
-      teammates.push({
-        name: `apex-${kebabCase(appName)}-${kebabCase(mod.code)}`,
-        application: appName,
-        modules: [mod.code],
-        prdFiles: [mod.prdFile]
-      });
-    }
-  }
-}
+See `references/parallel-execution.md` for complete parallel protocol:
 
-console.log(`Spawning ${teammates.length} teammates:`);
-for (const t of teammates) {
-  console.log(`  - ${t.name}: ${t.modules.join(', ')}`);
-}
-
-// Create team
-TeamCreate({
-  team_name: `smartstack-${kebabCase(prd.project.name || 'project')}`,
-  description: `Parallel development for ${teammates.length} modules`
-});
-
-// Spawn teammates
-for (const teammate of teammates) {
-  Task({
-    subagent_type: "apex",
-    name: teammate.name,
-    team_name: `smartstack-${kebabCase(prd.project.name || 'project')}`,
-    prompt: `
-      You are teammate ${teammate.name}.
-
-      CONTEXT:
-      - Application: ${teammate.application}
-      - Modules: ${teammate.modules.join(', ')}
-      - PRD files: ${teammate.prdFiles.join(', ')}
-
-      ENTITIES ALREADY EXIST (Phase 0 completed by Ralph):
-      All entity classes, EF configurations, and migrations are already created.
-      The ModelSnapshot is complete and the database is ready.
-
-      YOUR TASK:
-      For each module, generate:
-      - Services (Application layer)
-      - Controllers (API layer)
-      - Seed data (Navigation + Permissions + Business data)
-      - Frontend (Pages + Routes + i18n for all 4 languages)
-      - Tests (Unit + Integration)
-
-      DO NOT:
-      - Create new entities (already done)
-      - Create migrations (ModelSnapshot already complete)
-
-      EXECUTE:
-      For each PRD file: invoke /apex -d {prdFile}
-      Apex will see existing entities and skip domain/infrastructure layers.
-
-      When done, send a message to team lead with results.
-    `
-  });
-}
-
-// Ralph waits for teammates to complete
-// Each teammate will send a message when done
-// Ralph collects results and proceeds to validation
-```
-
-##### Collect Results
-
-```javascript
-// Wait for all teammates to send completion messages
-// Ralph receives SendMessage from each teammate with status
-
-const teammateResults = []; // populated from teammate messages
-
-console.log(`All teammates completed:`);
-for (const result of teammateResults) {
-  console.log(`  - ${result.name}: ${result.status}`);
-}
-
-// Cleanup team
-TeamDelete();
-
-// Proceed to step-03 for global validation
-```
+**IF `{parallel_mode}` == true:**
 
-> See `references/team-orchestration.md` for full parallel execution protocol.
+1. Phase 0 (Ralph sequential): Generate ALL entities from ALL modules + ONE migration
+2. Phase 1-N (Teams parallel): Spawn teammates per application/module for services/controllers/frontend/tests
+3. Collect results from teammates
+4. Cleanup team, proceed to step-03
 
 **ELSE (not parallel mode):**
 
@@ -230,7 +84,7 @@ if (prd._sectionSplit?.enabled) {
   );
 
   if (!depsOk) {
-    console.warn(`Phase ${nextPhase.phase} blocked by incomplete dependencies`);
+    console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
     goto STEP_04;
   }
 
@@ -261,7 +115,7 @@ if (prd._sectionSplit?.enabled) {
 
 This delegates ALL remaining tasks for the current module to apex:
 
-- Apex reads the PRD, extracts context (`context_code`, `app_name`, `module_code`, `entities`, `sections`)
+- Apex reads the PRD, extracts context (`app_name`, `module_code`, `entities`, `sections`)
 - Apex executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
 - Apex runs full POST-CHECKs (50 checks from `references/post-checks.md`)
 - Apex commits per layer (atomic commits)

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

@@ -33,7 +33,10 @@ const allDone = (tasksCompleted + tasksSkipped) === tasksTotal;
 ```bash
 # Quick build check (quiet mode)
 dotnet build --no-restore --verbosity quiet
-if [ $? -ne 0 ]; then
+BUILD_RC=$?
+# Cleanup WSL Roslyn artifacts (literal bin\Debug folders)
+for d in src/*/bin?Debug bin?Debug; do [ -d "$d" ] && rm -rf "$d"; done
+if [ $BUILD_RC -ne 0 ]; then
   echo "BUILD REGRESSION detected between apex invocations"
   # Inject fix task — apex will handle the actual fix
   prd.tasks.push({ id: maxId+1, description: "Fix build regression",
@@ -45,51 +48,18 @@ fi
 
 ### 1.7. Category Completeness Check (RUNS EVERY ITERATION)
 
-> **CRITICAL:** This check runs REGARDLESS of allDone status.
-> In test-v4-005, allDone was never true (PRD status not updated), so the
-> module completeness check in section 3b never triggered, and missing
-> frontend/test categories were never detected.
+See `references/category-completeness.md` for detailed implementation.
 
 ```javascript
-const presentCategories = new Set(prd.tasks.map(t => t.category));
-const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
-const missingFromPrd = REQUIRED_CATEGORIES.filter(c => !presentCategories.has(c));
-
-if (missingFromPrd.length > 0) {
-  console.warn(`PRD MISSING CATEGORIES: ${missingFromPrd.join(', ')}`);
-
-  // Inject guardrail tasks for missing categories
-  let maxIdNum = Math.max(...prd.tasks.map(t => parseInt(t.id.replace(/[^0-9]/g, ''), 10) || 0));
-  const prefix = prd.tasks[0]?.id?.replace(/[0-9]+$/, '') || 'GUARD-';
-  const lastApiTask = prd.tasks.filter(t => t.category === 'api').pop()?.id;
-  const lastSeedDataTask = prd.tasks.filter(t => t.category === 'seedData').pop()?.id;
-
-  for (const cat of missingFromPrd) {
-    maxIdNum++;
-    const taskId = `${prefix}${String(maxIdNum).padStart(3, '0')}`;
-    prd.tasks.push({
-      id: taskId,
-      description: `[GUARDRAIL] Generate missing ${cat} layer for ${prd.project?.module || 'module'}`,
-      status: 'pending', category: cat,
-      dependencies: lastSeedDataTask ? [lastSeedDataTask] : (lastApiTask ? [lastApiTask] : []),
-      acceptance_criteria: [
-        cat === 'frontend' ? 'React pages + routes wired to App.tsx' :
-        cat === 'test' ? 'Unit + integration tests passing' :
-        `${cat} layer complete`
-      ],
-      started_at: null, completed_at: null, iteration: null,
-      commit_hash: null, files_changed: [], validation: null, error: null
-    });
-    console.log(`  Injected [${taskId}] ${cat} guardrail`);
-  }
-  writeJSON('.ralph/prd.json', prd);
+const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
 
-  // Re-count after injection
-  const newPending = prd.tasks.filter(t => t.status === 'pending').length;
-  console.log(`PRD updated: +${missingFromPrd.length} guardrails, ${newPending} pending tasks`);
+if (guardrailsNeeded.length > 0) {
+  prd.tasks.push(...guardrailsNeeded);
+  writeJSON('.ralph/prd.json', prd);
+  console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${prd.tasks.filter(t => t.status === 'pending').length} pending tasks`);
 }
 
-// Also check: artifact existence for categories with completed tasks
+// Artifact verification (check if completed tasks have files)
 const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
 const artifactChecks = {
   'frontend': () => glob.sync('**/src/pages/**/*.tsx').length > 0,
@@ -98,9 +68,13 @@ const artifactChecks = {
 };
 for (const [cat, check] of Object.entries(artifactChecks)) {
   if (completedCats.has(cat) && !check()) {
-    console.warn(`ARTIFACT MISSING: ${cat} tasks marked completed but no files found — resetting`);
+    console.warn(`ARTIFACT MISSING: ${cat} tasks marked completed but no files found — resetting 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; });
+      .forEach(t => {
+        t.status = 'pending';
+        t.error = 'Artifacts missing — re-execute';
+        t.completed_at = null;
+      });
     writeJSON('.ralph/prd.json', prd);
   }
 }
@@ -141,6 +115,8 @@ if ({team_active}) {
 
 ### 3b. Sequential Multi-Module (modules-queue.json)
 
+See `references/module-transition.md` for complete module advancement protocol.
+
 ```javascript
 const queuePath = '.ralph/modules-queue.json';
 if (fileExists(queuePath)) {
@@ -156,36 +132,8 @@ if (fileExists(queuePath)) {
     console.log(`Module ${currentModule.code}: missing categories ${missing.join(', ')} — continuing loop`);
     // Fall through to section 5 (compact loop)
   } else {
-    // Module complete — advance
-    currentModule.status = 'completed';
-    queue.completedModules++;
-    const nextIndex = queue.currentIndex + 1;
-
-    if (nextIndex < queue.totalModules) {
-      queue.currentIndex = nextIndex;
-      queue.modules[nextIndex].status = 'in-progress';
-      writeJSON(queuePath, queue);
-
-      writeJSON('.ralph/module-changed.json', {
-        fromModule: currentModule.code, toModule: queue.modules[nextIndex].code,
-        timestamp: new Date().toISOString()
-      });
-
-      prd.status = 'completed';
-      writeJSON('.ralph/prd.json', prd);
-      const nextPrd = readJSON(queue.modules[nextIndex].prdFile);
-      nextPrd.config.current_iteration = 1;
-      nextPrd.config.max_iterations = prd.config.max_iterations;
-      writeJSON('.ralph/prd.json', nextPrd);
-
-      console.log(`MODULE COMPLETE: ${currentModule.code} → NEXT: ${queue.modules[nextIndex].code}`);
-      // → step-01 (module transition)
-      return;
-    }
-
-    // ALL MODULES COMPLETE
-    writeJSON(queuePath, queue);
-    console.log(`ALL ${queue.totalModules} MODULES COMPLETE`);
+    // All categories complete — advance to next module
+    // (detailed logic in references/module-transition.md)
   }
 }
 ```

package/templates/skills/review-code/references/owasp-api-top10.md

@@ -25,7 +25,7 @@ public async Task<ActionResult<OrderDto>> Get(Guid id)
 
 // GOOD: Tenant filter via EF Core global filter + explicit check
 [HttpGet("{id}")]
-[RequirePermission(Permissions.Business.Orders.Read)]
+[RequirePermission(Permissions.Orders.Read)]
 public async Task<ActionResult<OrderDto>> Get(Guid id)
 {
     var order = await _context.Orders
@@ -76,7 +76,7 @@ public async Task<ActionResult> Update(Guid id, [FromBody] User user) { ... }
 
 // GOOD: DTO limits writable fields
 [HttpPut("{id}")]
-[RequirePermission(Permissions.Business.Users.Update)]
+[RequirePermission(Permissions.Users.Update)]
 public async Task<ActionResult> Update(Guid id, [FromBody] UpdateUserDto dto) { ... }
 
 public record UpdateUserDto(string Name, string Email); // No Role, no TenantId
@@ -117,8 +117,8 @@ public async Task<ActionResult<PaginatedResult<OrderDto>>> GetAll(
 **Risk:** Regular users access admin-level API functions.
 
 **SmartStack check:**
-- [ ] Admin endpoints use `platform.administration.*` permissions
-- [ ] Area-based routing enforced (Admin, Support, Business, User)
+- [ ] Admin endpoints use `administration.*` permissions
+- [ ] Application-based routing enforced (Administration, Support, etc.)
 - [ ] System account protection (UserType.System, UserType.LocalAdmin)
 - [ ] No permission bypass via direct URL manipulation
 
@@ -130,7 +130,7 @@ public async Task<ActionResult> Delete(Guid id) { ... }
 
 // GOOD: Explicit permission check
 [HttpDelete("{id}")]
-[RequirePermission(Permissions.Platform.Administration.Users.Delete)]
+[RequirePermission(Permissions.Administration.Users.Delete)]
 public async Task<ActionResult> Delete(Guid id) { ... }
 ```
 </api5_broken_function_auth>

package/templates/skills/review-code/references/smartstack-conventions.md

@@ -335,10 +335,10 @@ Rules:
 **NavRoute attribute** (preferred):
 ```csharp
 [ApiController]
-[NavRoute("platform.administration.users")]
+[NavRoute("administration.users")]
 public class UsersController : ControllerBase  // MUST be ControllerBase, NOT Controller
 {
-    // Routes generated from NavRoute: /api/platform/administration/users
+    // Routes generated from NavRoute: /api/administration/users
 }
 ```
 
@@ -369,14 +369,14 @@ public class UsersController : ControllerBase
 **NavRoute format:**
 - Lowercase only
 - Dot-separated hierarchy
-- Minimum 2 levels: `context.application`
-- Full path: `context.application.module`
+- Minimum 2 levels: `application.module`
+- Full path: `application.module`
 
 **Examples:**
-- `platform.administration.users`
-- `platform.administration.roles`
-- `business.crm.contacts`
-- `personal.myspace.dashboard`
+- `administration.users`
+- `administration.roles`
+- `crm.contacts`
+- `myspace.dashboard`
 </controllers>
 
 <services>
@@ -434,9 +434,9 @@ var users = await _context.Users
 - Actions: `read`, `create`, `update`, `delete`, `*` (wildcard)
 
 **Example permissions:**
-- `platform.administration.users.read`
-- `platform.administration.users.create`
-- `platform.administration.users.*` (all actions)
+- `administration.users.read`
+- `administration.users.create`
+- `administration.users.*` (all actions)
 </authorization>
 
 <input_validation>

package/templates/skills/validate-feature/references/api-smoke-tests.md

@@ -0,0 +1,140 @@
+# API Smoke Test Procedure
+
+> **Reference for:** step-04-api-smoke.md
+> **Purpose:** Validate CRUD endpoints with real HTTP requests
+> **Scope:** GET all, POST create, GET by ID, PUT update, DELETE, GET verify deleted
+
+---
+
+## Startup Sequence
+
+```bash
+# Start API on test port
+dotnet run --project {ApiProject} --urls "http://localhost:5099" > /tmp/api-smoke-output.log 2>&1 &
+API_PID=$!
+
+# Wait for readiness (with crash detection)
+API_CRASHED=false
+for i in $(seq 1 30); do
+  if ! kill -0 $API_PID 2>/dev/null; then
+    echo "API PROCESS CRASHED during startup"
+    cat /tmp/api-smoke-output.log 2>/dev/null
+    API_CRASHED=true
+    break
+  fi
+
+  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:5099/health 2>/dev/null)
+  if [ "$HTTP_CODE" != "000" ]; then
+    echo "API is ready (HTTP $HTTP_CODE)"
+    break
+  fi
+  sleep 1
+done
+
+# If API_CRASHED=true → Jump to section "Crash Classification" below
+```
+
+---
+
+## CRUD Test Sequence
+
+```bash
+# Get auth token (optional)
+TOKEN=$(curl -s -X POST http://localhost:5099/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@smartstack.io","password":"Admin123!"}' \
+  | jq -r '.token // .accessToken // empty')
+
+# Headers
+AUTH_HEADER="Authorization: Bearer $TOKEN"
+TENANT_HEADER="X-Tenant-Id: 11111111-1111-1111-1111-111111111111"
+CONTENT_TYPE="Content-Type: application/json"
+```
+
+### Test 1: GET All (expect 200)
+```bash
+curl -s -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}
+```
+
+### Test 2: POST Create (expect 201 or 200)
+```bash
+CREATED=$(curl -s -X POST \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" -H "$CONTENT_TYPE" \
+  -d '{"code":"smoke-test-01","name":"Smoke Test Entity"}' \
+  http://localhost:5099/api/{entity_code})
+ENTITY_ID=$(echo "$CREATED" | jq -r '.id // .Id')
+```
+
+### Test 3: GET By ID (expect 200)
+```bash
+curl -s -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+### Test 4: PUT Update (expect 200)
+```bash
+curl -s -X PUT -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" -H "$CONTENT_TYPE" \
+  -d '{"code":"smoke-test-01","name":"Updated Name"}' \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+### Test 5: DELETE (expect 204)
+```bash
+curl -s -X DELETE -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+### Test 6: GET Deleted (expect 404)
+```bash
+curl -s -w "\nHTTP %{http_code}" \
+  -H "$AUTH_HEADER" -H "$TENANT_HEADER" \
+  http://localhost:5099/api/{entity_code}/$ENTITY_ID
+```
+
+---
+
+## HTTP Error Classification
+
+| Status | Error | Cause | Fix |
+|--------|-------|-------|-----|
+| 401 | Unauthorized | Auth not configured | Check JWT token generation |
+| 403 | Forbidden | Permissions missing | Verify PermissionConfiguration seeding |
+| 404 | Not Found | Route not registered | Check NavRoute attribute on controller |
+| 500 | Internal Server Error | Unhandled exception | Check API startup logs |
+| Connection refused | API won't start | Startup config error | Review appsettings.json |
+
+---
+
+## Crash Classification
+
+If API process dies during startup, classify error from `/tmp/api-smoke-output.log`:
+
+| Error Pattern | Category | Fix |
+|---------------|----------|-----|
+| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | MISSING_PACKAGE | `dotnet add {ApiProject} package {Name} --version {Major.Minor.Patch}` |
+| `FileNotFoundException: Could not load file or assembly '{Name}'` | MISSING_ASSEMBLY | Check .csproj references |
+| `TypeLoadException: Could not load type '{Type}'` | VERSION_MISMATCH | Update package to correct version |
+| `MissingMethodException` | VERSION_MISMATCH | Update package |
+| `InvalidOperationException: Unable to resolve service for type '{Type}'` | MISSING_DI | Add DI registration in Program.cs |
+| `SqlException` or connection errors | DATABASE_ERROR | Check appsettings.json connection string |
+
+**For MISSING_PACKAGE:**
+1. Extract assembly name (text between single quotes)
+2. Extract version (Version=X.X.X.X segment)
+3. Map to NuGet: assembly name usually equals package name
+4. Output: `FIX: dotnet add {ApiProject} package {PackageName} --version {Major.Minor.Patch}`
+
+---
+
+## Cleanup
+
+```bash
+kill $API_PID 2>/dev/null
+wait $API_PID 2>/dev/null
+rm -f /tmp/api-smoke-output.log
+```