@atlashub/smartstack-cli 3.39.0 → 3.40.0

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

@@ -1,185 +1,185 @@
-# Category Completeness Check
-
-> **Reference for:** step-01-task.md section 4b and step-04-check.md section 1.7
-> **Purpose:** Ensure PRD contains tasks for ALL required categories before/during execution
-> **Frequency:** On load (step-01) and every iteration (step-04)
-
----
-
-## The Problem
-
-**Test-v4-005 Failure Mode:**
-- PRD generated with only backend categories (domain, infrastructure, application, api, seedData)
-- Frontend and test categories were entirely absent
-- Result: 0 frontend pages, 0 tests generated across 3 modules
-- Root cause: No guardrail detection during load
-
-## The Solution: Required Categories
-
-**CRITICAL:** Every PRD MUST have tasks for these categories:
-
-```javascript
-const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
-```
-
-> **Why seedData is required:**
-> - Without it: Navigation/Permissions are not seeded
-> - Result: Frontend/test tasks execute against empty database
-> - Guardrail must inject NavigationApplicationSeedData, ApplicationRolesSeedData, etc.
-
----
-
-## Completeness Check Function
-
-```javascript
-function checkCategoryCompleteness(prd) {
-  const presentCategories = new Set(prd.tasks.map(t => t.category));
-  const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
-  const missingCategories = REQUIRED_CATEGORIES.filter(c => !presentCategories.has(c));
-
-  if (missingCategories.length === 0) {
-    return { missing: [], guardrailsNeeded: [] };
-  }
-
-  console.warn(`⚠ PRD MISSING CATEGORIES: ${missingCategories.join(', ')}`);
-
-  // Calculate max ID for new guardrails
-  let maxIdNum = Math.max(...prd.tasks.map(t => {
-    const num = parseInt(t.id.replace(/[^0-9]/g, ''), 10);
-    return isNaN(num) ? 0 : num;
-  }), 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;
-
-  // Dependency chain: domain → infrastructure → application → api → seedData → frontend → test
-  // Frontend MUST depend on seedData (navigation/permissions must be seeded first)
-  const frontendDep = lastSeedDataTask || lastApiTask;
-
-  const guardrailTasks = [];
-
-  for (const cat of missingCategories) {
-    maxIdNum++;
-    const taskId = `${prefix}${String(maxIdNum).padStart(3, '0')}`;
-
-    // Determine dependencies based on category order
-    let deps;
-    if (cat === 'seedData') {
-      deps = [lastApiTask]; // seedData depends on API infrastructure
-    } else if (cat === 'frontend') {
-      deps = [frontendDep]; // frontend depends on seedData (navigation must be seeded)
-    } else if (cat === 'test') {
-      deps = [frontendDep]; // test depends on seedData too
-    } else {
-      deps = [];
-    }
-
-    const guardrailTask = {
-      id: taskId,
-      description: `[GUARDRAIL] Generate ${cat} layer for ${prd.project?.module || 'module'}`,
-      status: 'pending',
-      category: cat,
-      dependencies: deps,
-      acceptance_criteria: determineAcceptanceCriteria(cat),
-      started_at: null,
-      completed_at: null,
-      iteration: null,
-      commit_hash: null,
-      files_changed: [],
-      validation: null,
-      error: null
-    };
-
-    guardrailTasks.push(guardrailTask);
-  }
-
-  return { missing: missingCategories, guardrailsNeeded: guardrailTasks };
-}
-
-function determineAcceptanceCriteria(category) {
-  const criteria = {
-    domain: 'Entity classes created with required properties',
-    infrastructure: 'EF Core configs, migrations created, dotnet build passes',
-    application: 'Service classes implementing business logic',
-    api: 'REST controllers with [RequirePermission] attributes',
-    seedData: 'NavigationApplicationSeedData + ApplicationRolesSeedData + PermissionsSeedData created, IClientSeedDataProvider wired, startup test passes',
-    frontend: 'React pages created via MCP scaffold_api_client + scaffold_routes, wired to App.tsx, navigation seed data verified in DB',
-    test: 'Unit + Integration test projects created, scaffold_tests MCP called, dotnet test passes'
-  };
-  return criteria[category] || `${category} layer fully implemented per category-rules.md`;
-}
-```
-
-## Application in step-01
-
-```javascript
-// After loading prd.json or generating tasks
-const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
-
-if (guardrailsNeeded.length > 0) {
-  console.log(`PRD updated: ${prd.tasks.length} → ${prd.tasks.length + guardrailsNeeded.length} tasks (${guardrailsNeeded.length} guardrails added)`);
-  prd.tasks.push(...guardrailsNeeded);
-
-  // Update frontendDep for any frontend guardrail if seedData was just injected
-  if (missing.includes('seedData')) {
-    const seedDataGuard = guardrailsNeeded.find(t => t.category === 'seedData');
-    const frontendGuard = prd.tasks.find(t => t.category === 'frontend' && t.description.includes('[GUARDRAIL]'));
-    if (frontendGuard && seedDataGuard) {
-      frontendGuard.dependencies = [seedDataGuard.id];
-    }
-  }
-
-  writeJSON('.ralph/prd.json', prd);
-}
-```
-
-## Application in step-04 (every iteration)
-
-```javascript
-// RUNS EVERY ITERATION — not just once
-const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
-
-if (guardrailsNeeded.length > 0) {
-  prd.tasks.push(...guardrailsNeeded);
-  writeJSON('.ralph/prd.json', prd);
-
-  const newPending = prd.tasks.filter(t => t.status === 'pending').length;
-  console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${newPending} pending tasks`);
-}
-```
-
-## Artifact Verification
-
-After category check, verify artifacts actually exist for completed tasks:
-
-```javascript
-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,
-  'test': () => glob.sync('tests/**/*Tests.cs').length > 0,
-  'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0
-};
-
-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 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;
-      });
-    writeJSON('.ralph/prd.json', prd);
-  }
-}
-```
-
----
-
-## Key Rules
-
-- **Inject EVERY iteration:** Not just once during load
-- **Frontend depends on seedData:** Not just API
-- **Check artifacts:** Mark tasks pending if files don't exist
-- **Never skip:** This is the blocker for "missing frontend/test" failures
+# Category Completeness Check
+
+> **Reference for:** step-01-task.md section 4b and step-04-check.md section 1.7
+> **Purpose:** Ensure PRD contains tasks for ALL required categories before/during execution
+> **Frequency:** On load (step-01) and every iteration (step-04)
+
+---
+
+## The Problem
+
+**Test-v4-005 Failure Mode:**
+- PRD generated with only backend categories (domain, infrastructure, application, api, seedData)
+- Frontend and test categories were entirely absent
+- Result: 0 frontend pages, 0 tests generated across 3 modules
+- Root cause: No guardrail detection during load
+
+## The Solution: Required Categories
+
+**CRITICAL:** Every PRD MUST have tasks for these categories:
+
+```javascript
+const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
+```
+
+> **Why seedData is required:**
+> - Without it: Navigation/Permissions are not seeded
+> - Result: Frontend/test tasks execute against empty database
+> - Guardrail must inject NavigationApplicationSeedData, ApplicationRolesSeedData, etc.
+
+---
+
+## Completeness Check Function
+
+```javascript
+function checkCategoryCompleteness(prd) {
+  const presentCategories = new Set(prd.tasks.map(t => t.category));
+  const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
+  const missingCategories = REQUIRED_CATEGORIES.filter(c => !presentCategories.has(c));
+
+  if (missingCategories.length === 0) {
+    return { missing: [], guardrailsNeeded: [] };
+  }
+
+  console.warn(`⚠ PRD MISSING CATEGORIES: ${missingCategories.join(', ')}`);
+
+  // Calculate max ID for new guardrails
+  let maxIdNum = Math.max(...prd.tasks.map(t => {
+    const num = parseInt(t.id.replace(/[^0-9]/g, ''), 10);
+    return isNaN(num) ? 0 : num;
+  }), 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;
+
+  // Dependency chain: domain → infrastructure → application → api → seedData → frontend → test
+  // Frontend MUST depend on seedData (navigation/permissions must be seeded first)
+  const frontendDep = lastSeedDataTask || lastApiTask;
+
+  const guardrailTasks = [];
+
+  for (const cat of missingCategories) {
+    maxIdNum++;
+    const taskId = `${prefix}${String(maxIdNum).padStart(3, '0')}`;
+
+    // Determine dependencies based on category order
+    let deps;
+    if (cat === 'seedData') {
+      deps = [lastApiTask]; // seedData depends on API infrastructure
+    } else if (cat === 'frontend') {
+      deps = [frontendDep]; // frontend depends on seedData (navigation must be seeded)
+    } else if (cat === 'test') {
+      deps = [frontendDep]; // test depends on seedData too
+    } else {
+      deps = [];
+    }
+
+    const guardrailTask = {
+      id: taskId,
+      description: `[GUARDRAIL] Generate ${cat} layer for ${prd.project?.module || 'module'}`,
+      status: 'pending',
+      category: cat,
+      dependencies: deps,
+      acceptance_criteria: determineAcceptanceCriteria(cat),
+      started_at: null,
+      completed_at: null,
+      iteration: null,
+      commit_hash: null,
+      files_changed: [],
+      validation: null,
+      error: null
+    };
+
+    guardrailTasks.push(guardrailTask);
+  }
+
+  return { missing: missingCategories, guardrailsNeeded: guardrailTasks };
+}
+
+function determineAcceptanceCriteria(category) {
+  const criteria = {
+    domain: 'Entity classes created with required properties',
+    infrastructure: 'EF Core configs, migrations created, dotnet build passes',
+    application: 'Service classes implementing business logic',
+    api: 'REST controllers with [RequirePermission] attributes',
+    seedData: 'NavigationApplicationSeedData + ApplicationRolesSeedData + PermissionsSeedData created, IClientSeedDataProvider wired, startup test passes',
+    frontend: 'React pages created via MCP scaffold_api_client + scaffold_routes, wired to App.tsx, navigation seed data verified in DB',
+    test: 'Unit + Integration test projects created, scaffold_tests MCP called, dotnet test passes'
+  };
+  return criteria[category] || `${category} layer fully implemented per category-rules.md`;
+}
+```
+
+## Application in step-01
+
+```javascript
+// After loading prd.json or generating tasks
+const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
+
+if (guardrailsNeeded.length > 0) {
+  console.log(`PRD updated: ${prd.tasks.length} → ${prd.tasks.length + guardrailsNeeded.length} tasks (${guardrailsNeeded.length} guardrails added)`);
+  prd.tasks.push(...guardrailsNeeded);
+
+  // Update frontendDep for any frontend guardrail if seedData was just injected
+  if (missing.includes('seedData')) {
+    const seedDataGuard = guardrailsNeeded.find(t => t.category === 'seedData');
+    const frontendGuard = prd.tasks.find(t => t.category === 'frontend' && t.description.includes('[GUARDRAIL]'));
+    if (frontendGuard && seedDataGuard) {
+      frontendGuard.dependencies = [seedDataGuard.id];
+    }
+  }
+
+  writeJSON('.ralph/prd.json', prd);
+}
+```
+
+## Application in step-04 (every iteration)
+
+```javascript
+// RUNS EVERY ITERATION — not just once
+const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
+
+if (guardrailsNeeded.length > 0) {
+  prd.tasks.push(...guardrailsNeeded);
+  writeJSON('.ralph/prd.json', prd);
+
+  const newPending = prd.tasks.filter(t => t.status === 'pending').length;
+  console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${newPending} pending tasks`);
+}
+```
+
+## Artifact Verification
+
+After category check, verify artifacts actually exist for completed tasks:
+
+```javascript
+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,
+  'test': () => glob.sync('tests/**/*Tests.cs').length > 0,
+  'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0
+};
+
+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 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;
+      });
+    writeJSON('.ralph/prd.json', prd);
+  }
+}
+```
+
+---
+
+## Key Rules
+
+- **Inject EVERY iteration:** Not just once during load
+- **Frontend depends on seedData:** Not just API
+- **Check artifacts:** Mark tasks pending if files don't exist
+- **Never skip:** This is the blocker for "missing frontend/test" failures

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

@@ -1,96 +1,96 @@
-# Category Ordering & Dependency Rules
-
-> **Loaded by:** step-02 (task ordering validation) and compact-loop.md (batch grouping)
-> **Purpose:** Defines execution order, dependencies, and batch grouping rules.
-> **Note:** All execution rules, MCP tool usage, conventions, and POST-CHECKs are in `/apex` references.
-
----
-
-## Execution Order
-
-Tasks MUST be executed in this order. Each category depends on the previous ones.
-
-| Order | Category | Depends On | Description |
-|-------|----------|------------|-------------|
-| 0 | `domain` | — | Entities, enums, value objects |
-| 1 | `infrastructure` | domain | EF configs, migrations, seed data |
-| 2 | `application` | infrastructure | Services, DTOs, validators, DI |
-| 3 | `api` | application | Controllers, route attributes |
-| 4 | `seedData` | api | Navigation, permissions, roles, dev data |
-| 5 | `frontend` | seedData | Pages, routes, i18n, components |
-| 6 | `test` | frontend | Unit tests, integration tests, coverage |
-
-> **Key dependency:** `frontend` depends on `seedData` (not just `api`).
-> Navigation seed data drives the menu — without it, frontend routes have no menu entries.
-
----
-
-## Dependency Rules
-
-1. **A task can only start when ALL its dependencies are `completed`**
-2. **If a dependency is `failed` or `blocked`, the task becomes `blocked`**
-3. **Cross-category dependencies are implicit** — domain before infrastructure, etc.
-4. **Same-category tasks MAY run in parallel** (batched together)
-5. **PRD `dependencies[]` array overrides implicit ordering** — explicit deps always checked first
-
----
-
-## Batch Grouping Rules
-
-When selecting tasks for a batch:
-
-1. **Group by category** — take the first eligible category with pending tasks
-2. **Max batch size: 5 tasks** — prevents overloading a single apex invocation
-3. **Same category only** — never mix domain + infrastructure in one batch
-4. **Order within batch: by task ID** (ascending) — preserves PRD creation order
-
-```javascript
-const eligible = prd.tasks.filter(/* pending + deps met */);
-const firstCategory = eligible[0].category;
-const batch = eligible.filter(t => t.category === firstCategory).slice(0, 5);
-```
-
----
-
-## PRD Category Completeness
-
-A valid PRD MUST contain tasks in these categories:
-
-- `domain` — at least 1 entity task
-- `infrastructure` — at least 1 EF config + migration task
-- `application` — at least 1 service task
-- `api` — at least 1 controller task
-- `seedData` — at least 1 navigation/permission task
-- `frontend` — at least 1 page task
-- `test` — at least 1 test task
-
-If any category is missing, ralph step-01 injects a guardrail task.
-
----
-
-## Section-Level Splitting (>4 Entities)
-
-When a module has many entities, a single `/apex -d` call saturates the context window.
-Section-level splitting breaks the module into smaller, manageable phases.
-
-**Activation threshold:** `> 4 domain tasks` AND `> 1 architecture section`
-
-| Phase | Content | Depends On |
-|-------|---------|------------|
-| Phase 0 | ALL domain + infrastructure + migration + module seed data | — |
-| Phase 1 | Section A: services, controllers, section seed, pages, i18n, tests | Phase 0 |
-| Phase 2 | Section B: idem | Phase 0 (+ Phase 1 if FK cross-section) |
-| Phase N | Section N: idem | Phase 0 (+ earlier phases if FK) |
-| Final | Cross-validation (dotnet build, typecheck, MCP validate) | All phases |
-
-**Key rules:**
-- Phase 0 creates ALL entity classes + ALL EF configs + ONE migration (avoids ModelSnapshot conflicts)
-- Section phases NEVER create entities or migrations — only services, controllers, pages on top
-- FK cross-section dependencies determine section execution order (topological sort)
-- Orphan entities (not in any section) are included in Phase 0 with their services/controllers
-- Each phase produces a temporary PRD file: `.ralph/prd-{module}-phase0.json`, `.ralph/prd-{module}-section-{code}.json`
-- Temporary PRD files are cleaned up in step-05 (report)
-
-**Backward compatible:** Modules with `<= 4 domain tasks` or `1 section` → standard execution, zero impact.
-
-See `references/section-splitting.md` for full detection, mapping, and execution logic.
+# Category Ordering & Dependency Rules
+
+> **Loaded by:** step-02 (task ordering validation) and compact-loop.md (batch grouping)
+> **Purpose:** Defines execution order, dependencies, and batch grouping rules.
+> **Note:** All execution rules, MCP tool usage, conventions, and POST-CHECKs are in `/apex` references.
+
+---
+
+## Execution Order
+
+Tasks MUST be executed in this order. Each category depends on the previous ones.
+
+| Order | Category | Depends On | Description |
+|-------|----------|------------|-------------|
+| 0 | `domain` | — | Entities, enums, value objects |
+| 1 | `infrastructure` | domain | EF configs, migrations, seed data |
+| 2 | `application` | infrastructure | Services, DTOs, validators, DI |
+| 3 | `api` | application | Controllers, route attributes |
+| 4 | `seedData` | api | Navigation, permissions, roles, dev data |
+| 5 | `frontend` | seedData | Pages, routes, i18n, components |
+| 6 | `test` | frontend | Unit tests, integration tests, coverage |
+
+> **Key dependency:** `frontend` depends on `seedData` (not just `api`).
+> Navigation seed data drives the menu — without it, frontend routes have no menu entries.
+
+---
+
+## Dependency Rules
+
+1. **A task can only start when ALL its dependencies are `completed`**
+2. **If a dependency is `failed` or `blocked`, the task becomes `blocked`**
+3. **Cross-category dependencies are implicit** — domain before infrastructure, etc.
+4. **Same-category tasks MAY run in parallel** (batched together)
+5. **PRD `dependencies[]` array overrides implicit ordering** — explicit deps always checked first
+
+---
+
+## Batch Grouping Rules
+
+When selecting tasks for a batch:
+
+1. **Group by category** — take the first eligible category with pending tasks
+2. **Max batch size: 5 tasks** — prevents overloading a single apex invocation
+3. **Same category only** — never mix domain + infrastructure in one batch
+4. **Order within batch: by task ID** (ascending) — preserves PRD creation order
+
+```javascript
+const eligible = prd.tasks.filter(/* pending + deps met */);
+const firstCategory = eligible[0].category;
+const batch = eligible.filter(t => t.category === firstCategory).slice(0, 5);
+```
+
+---
+
+## PRD Category Completeness
+
+A valid PRD MUST contain tasks in these categories:
+
+- `domain` — at least 1 entity task
+- `infrastructure` — at least 1 EF config + migration task
+- `application` — at least 1 service task
+- `api` — at least 1 controller task
+- `seedData` — at least 1 navigation/permission task
+- `frontend` — at least 1 page task
+- `test` — at least 1 test task
+
+If any category is missing, ralph step-01 injects a guardrail task.
+
+---
+
+## Section-Level Splitting (>4 Entities)
+
+When a module has many entities, a single `/apex -d` call saturates the context window.
+Section-level splitting breaks the module into smaller, manageable phases.
+
+**Activation threshold:** `> 4 domain tasks` AND `> 1 architecture section`
+
+| Phase | Content | Depends On |
+|-------|---------|------------|
+| Phase 0 | ALL domain + infrastructure + migration + module seed data | — |
+| Phase 1 | Section A: services, controllers, section seed, pages, i18n, tests | Phase 0 |
+| Phase 2 | Section B: idem | Phase 0 (+ Phase 1 if FK cross-section) |
+| Phase N | Section N: idem | Phase 0 (+ earlier phases if FK) |
+| Final | Cross-validation (dotnet build, typecheck, MCP validate) | All phases |
+
+**Key rules:**
+- Phase 0 creates ALL entity classes + ALL EF configs + ONE migration (avoids ModelSnapshot conflicts)
+- Section phases NEVER create entities or migrations — only services, controllers, pages on top
+- FK cross-section dependencies determine section execution order (topological sort)
+- Orphan entities (not in any section) are included in Phase 0 with their services/controllers
+- Each phase produces a temporary PRD file: `.ralph/prd-{module}-phase0.json`, `.ralph/prd-{module}-section-{code}.json`
+- Temporary PRD files are cleaned up in step-05 (report)
+
+**Backward compatible:** Modules with `<= 4 domain tasks` or `1 section` → standard execution, zero impact.
+
+See `references/section-splitting.md` for full detection, mapping, and execution logic.