@atlashub/smartstack-cli 3.37.0 → 3.39.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,9 @@ const allDone = (tasksCompleted + tasksSkipped) === tasksTotal;
 ```bash
 # Quick build check (quiet mode)
 dotnet build --no-restore --verbosity quiet
-if [ $? -ne 0 ]; then
+BUILD_RC=$?
+# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
+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 +47,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 +67,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 +114,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 +131,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>