@atlashub/smartstack-cli 3.8.0 → 3.9.0

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

@@ -0,0 +1,259 @@
+# Category Execution Rules
+
+> **Loaded by:** step-02 (first iteration) and compact-loop.md (subsequent iterations)
+> **Purpose:** Defines execution rules, MCP tools, folder paths, and forbidden patterns per task category.
+
+---
+
+## Domain
+
+**Folder:** `Domain/Entities/{ContextPascal}/{App}/{Module}/`
+**Enums:** `Domain/Enums/{ContextPascal}/{App}/{Module}/`
+**Exceptions:** `Domain/Exceptions/{ContextPascal}/{App}/{Module}/`
+**MCP:** `validate_conventions`
+
+Rules:
+- Entity base class inheritance (AuditableEntity, IHasData, ISoftDeletable)
+- Audit fields: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy
+- Domain events for state changes
+- Value objects for composite values
+
+---
+
+## Infrastructure — EF Core Configurations
+
+**Folder:** `Infrastructure/Persistence/Configurations/{ContextPascal}/{App}/{Module}/`
+**MCP:** `validate_conventions`, `check_migrations`
+
+Rules:
+- One configuration per entity
+- Table name = plural entity name
+- All relationships explicitly configured (no convention-based)
+- Indexes on foreign keys and frequently queried fields
+- Register DbSet in ExtensionsDbContext
+
+---
+
+## Infrastructure — Migration (BLOCKING)
+
+> **CRITICAL:** After EF configs, a migration MUST be created and applied.
+> Without migrations, no database schema = no tests = no API = broken module.
+
+**Folder:** `Infrastructure/Persistence/Migrations/` (NEVER subdirectories)
+**MCP:** `suggest_migration` → get migration name
+
+Execution sequence:
+1. Call `mcp__smartstack__suggest_migration` → get standardized name
+2. `dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations`
+3. `dotnet ef database update --project src/{Infra}.csproj --startup-project src/{Api}.csproj`
+4. `dotnet build --no-restore` → verify build passes
+
+**BLOCKING:** If migration fails, DO NOT proceed. Fix the EF configs first.
+
+**Rules:**
+- NEVER create subdirectories under Migrations/
+- Always use `-o Persistence/Migrations` flag
+- One migration per module (all entities together)
+- Migration name from MCP (NEVER invented)
+
+---
+
+## Infrastructure — Seed Data (MANDATORY reference loading)
+
+**Folder:** `Infrastructure/Persistence/Seeding/Data/{Module}/`
+**MCP:** `generate_permissions` (PRIMARY), fallback to templates
+
+> **IF** task description contains "seed data", "SeedData", "NavigationModule",
+> "PermissionsSeedData", "RolesSeedData", or "IClientSeedDataProvider":
+> **THEN read `references/core-seed-data.md`** — this is MANDATORY, DO NOT improvise.
+
+**Rules:**
+- NavigationModuleSeedData.cs: deterministic GUIDs (SHA256), 4 languages (fr, en, it, de)
+- PermissionsSeedData.cs: MCP `generate_permissions` first, fallback to template
+- RolesSeedData.cs: context-based role mapping (Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R)
+- SeedConstants.cs: shared deterministic GUIDs
+- IClientSeedDataProvider: SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
+- DI: `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()`
+
+**FORBIDDEN:**
+- `Guid.NewGuid()` → use deterministic GUIDs
+- Empty seed data classes with only GUIDs and no seeding methods
+- Missing translations (must have all 4 languages)
+
+---
+
+## Infrastructure — SQL Objects
+
+**Folder:** `Infrastructure/Persistence/SqlObjects/Functions/`
+
+Rules:
+- `.sql` files with `CREATE OR ALTER` for idempotency
+- `SqlObjectHelper.cs` for embedded resource loading
+
+---
+
+## Post-Infrastructure Build Check (BLOCKING)
+
+> **After ALL infrastructure tasks (configs + migration + seed data) are done:**
+
+```bash
+dotnet build --no-restore
+```
+
+**BLOCKING:** Build MUST pass before proceeding to application/api/test/frontend.
+If build fails, fix infrastructure code first.
+
+---
+
+## Application
+
+**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/`
+**DTOs:** `Application/DTOs/{ContextPascal}/{App}/{Module}/`
+**Validators:** `Application/Validators/{ContextPascal}/{App}/{Module}/`
+**MCP:** `validate_conventions`, `scaffold_extension`
+
+Rules:
+- CQRS pattern with MediatR
+- FluentValidation for all commands
+- DTOs separate from domain entities
+- Service interfaces in Application, implementations in Infrastructure
+
+---
+
+## API
+
+**Controllers:** `Api/Controllers/{ContextShort}/{App}/{Entity}Controller.cs`
+**MCP:** `scaffold_routes`, `validate_security`
+
+**Context-to-folder mapping (`{ContextShort}`):**
+
+| NavRoute Prefix | Controller Folder |
+|-----------------|-------------------|
+| `platform.administration` | `Admin` |
+| `platform.support` | `Support` |
+| `business.*` | `Business` |
+| `personal.*` | `User` |
+
+**Rules:**
+- `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint (NOT `[Authorize]`)
+- Swagger XML documentation
+- Consistent route patterns: `api/{context}/{app}/{module}`
+- Return DTOs, never domain entities
+
+**FORBIDDEN:**
+- `[Authorize]` without specific permission → use `[RequirePermission]`
+- Returning domain entities directly
+
+---
+
+## Frontend (MCP-FIRST PROTOCOL)
+
+> **CRITICAL:** Frontend code is generated via MCP tools, NOT written from scratch.
+
+**Page hierarchy:** `src/pages/{ContextPascal}/{AppPascal}/{Module}/{Page}.tsx`
+**FORBIDDEN:** `src/pages/{Module}/` (flat structure without Context/App)
+
+**Execution sequence (IN ORDER):**
+1. `mcp__smartstack__scaffold_api_client` → API client + types + React Query hook
+2. `mcp__smartstack__scaffold_routes` → routes inside correct Layout wrapper
+3. Create pages using SmartStack components
+4. Create preferences hook: `use{Module}Preferences.ts`
+5. Generate i18n (4 languages: fr, en, it, de)
+6. `npm run typecheck` MUST pass (BLOCKING)
+
+**Components:**
+- Lists: `SmartTable` + `SmartFilter` (NOT HTML `<table>`)
+- Grids: `EntityCard` (NOT custom `<div>` cards)
+- Detail: `EntityDetailCard`, `StatusBadge`, tab layout
+- Forms: `SmartForm` with FluentValidation-backed fields
+- Dashboard: `StatCard`, Recharts components
+
+**Layout wrapper mapping:**
+
+| Context | Layout | Route path |
+|---------|--------|------------|
+| `platform.*` | `AdminLayout` | `/platform` |
+| `business.*` | `BusinessLayout` | `/business` |
+| `personal.*` | `UserLayout` | `/personal/myspace` |
+
+**CSS:** Variables ONLY → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
+
+**FORBIDDEN patterns (any = FAIL):**
+```
+import axios from 'axios'                    → use @/services/api/apiClient
+<table>...</table>                           → use SmartTable
+<div className="bg-blue-600">               → use bg-[var(--color-accent-600)]
+<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}/
+```
+
+---
+
+## I18n
+
+**Rules:**
+- 4 JSON files: fr, en, it, de
+- Identical key structures across all languages
+- All UI labels, validation messages, button text, empty states
+- Depends on frontend task completion
+
+---
+
+## Test (BLOCKING)
+
+**MCP:** `scaffold_tests`, `analyze_test_coverage`
+
+**Execution sequence:**
+
+1. **Ensure test project exists:**
+   ```bash
+   TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
+   if [ ! -d "$TEST_PROJECT" ]; then
+     dotnet new xunit -n "${PROJECT_NAME}.Tests.Unit" -o "$TEST_PROJECT"
+     dotnet add "$TEST_PROJECT" package Moq
+     dotnet add "$TEST_PROJECT" package FluentAssertions
+     for proj in src/*/*.csproj; do dotnet add "$TEST_PROJECT" reference "$proj"; done
+     dotnet sln add "$TEST_PROJECT/${PROJECT_NAME}.Tests.Unit.csproj"
+   fi
+   ```
+
+2. **Generate tests via MCP** (NOT manually):
+   - Domain: `scaffold_tests` with target_layer="domain"
+   - Service: `scaffold_tests` with target_layer="application"
+   - Controller: `scaffold_tests` with target_layer="api", test_type="integration"
+   - Security: `scaffold_tests` with test_type="security"
+
+3. **Run tests (BLOCKING):**
+   ```bash
+   dotnet build "$TEST_PROJECT" --no-restore
+   dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+   ```
+
+4. **Fix loop:** If tests fail → analyze → fix code (NOT tests) → rebuild → retest → loop until 100% pass
+
+5. **Coverage check:** `analyze_test_coverage` → must be >= 80%
+
+**Completion criteria (ALL required):**
+- Test project exists
+- Tests generated via MCP
+- `dotnet test` exits 0 (all pass)
+- Coverage >= 80%
+- No `[Fact(Skip = "...")]`
+
+---
+
+## Validation (FINAL — BLOCKING)
+
+**Execution sequence:**
+
+1. `dotnet clean && dotnet restore && dotnet build` → MUST pass
+2. `dotnet test` (full suite) → MUST pass
+3. `mcp__smartstack__validate_conventions` → 0 errors
+4. Generate validation report in progress.txt
+
+**Completion criteria:**
+- Build exit code 0
+- Test exit code 0
+- MCP validation 0 errors
+- Production ready = true

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

@@ -0,0 +1,182 @@
+# Compact Loop — Inline Execution
+
+> **Loaded by:** step-04 section 5 (after first full iteration)
+> **Purpose:** Execute all subsequent iterations inline without re-reading step files.
+> **Rule:** NEVER stop the loop. NEVER wait for user input. NEVER re-read step files.
+
+---
+
+## Loop Entry
+
+Display compact progress:
+```
+[{iteration}/{max}] {completed}/{total} done | Finding eligible tasks...
+```
+
+---
+
+## A. Find Eligible Tasks
+
+```javascript
+const prd = readJSON('.ralph/prd.json');
+
+// Block tasks whose dependencies failed
+for (const task of prd.tasks) {
+  if (task.status !== 'pending') continue;
+  const depsBlocked = task.dependencies.some(depId => {
+    const dep = prd.tasks.find(t => t.id === depId);
+    return dep && (dep.status === 'failed' || dep.status === 'blocked');
+  });
+  if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
+}
+
+// Find ALL eligible tasks (dependencies met)
+const eligible = prd.tasks.filter(task => {
+  if (task.status !== 'pending') return false;
+  return task.dependencies.every(depId => {
+    const dep = prd.tasks.find(t => t.id === depId);
+    return dep && dep.status === 'completed';
+  });
+});
+
+if (eligible.length === 0) {
+  // Dead-end or all done — return to step-04 sections 2-4
+  goto CHECK_COMPLETION;
+}
+
+// BATCH: group by category, take first group (max 5)
+const firstCategory = eligible[0].category;
+const batch = eligible.filter(t => t.category === firstCategory).slice(0, 5);
+```
+
+Display:
+```
+Batch: {batch.length} [{firstCategory}] → {batch.map(t => `[${t.id}] ${t.description.substring(0, 60)}`).join(' | ')}
+```
+
+---
+
+## B. Execute Batch
+
+**For EACH task in batch:**
+
+1. Mark `task.status = 'in_progress'`, `task.started_at = now`
+2. **Read `references/category-rules.md`** for category-specific rules
+3. Implement the task following SmartStack conventions
+4. Track `files_created` and `files_modified`
+
+**Execution cycle per task:**
+1. Generate code following category-rules.md
+2. **BUILD verification (BLOCKING per task):**
+   - 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
+
+**Category-specific triggers:**
+
+| Category | Action |
+|----------|--------|
+| `infrastructure` with `_migrationMeta` | Migration sequence: `suggest_migration` MCP → `dotnet ef migrations add` → `dotnet ef database update` → `dotnet build` |
+| `infrastructure` with seed data keywords | **MANDATORY:** Read `references/core-seed-data.md` → implement templates → `dotnet build` |
+| `frontend` | MCP-first: `scaffold_api_client` → `scaffold_routes` → create pages → `npm run typecheck && npm run lint` |
+| `test` | **Create tests:** `scaffold_tests` MCP → **Run:** `dotnet test --verbosity normal` → **Fix loop:** if fail → fix SOURCE CODE → rebuild → retest → repeat until 100% pass |
+| `validation` | `dotnet clean && dotnet restore && dotnet build` → `dotnet test` (full) → `validate_conventions` MCP |
+
+**Post-batch verification (BLOCKING — ALL must pass before commit):**
+
+1. **Backend build:**
+   ```bash
+   dotnet build --no-restore
+   ```
+   If FAIL → fix → rebuild → DO NOT commit until exit 0
+
+2. **Tests (if test tasks in batch OR after infrastructure batch):**
+   ```bash
+   TEST_PROJECT="tests/$(basename $(pwd)).Tests.Unit"
+   dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+   ```
+   If FAIL → fix source code (NOT tests) → rebuild → retest → loop until 100% pass
+
+3. **Frontend (if frontend/i18n tasks in batch):**
+   ```bash
+   npm run typecheck && npm run lint
+   ```
+   If FAIL → fix → re-check → loop until pass
+
+4. **MCP validation:**
+   `mcp__smartstack__validate_conventions` ONCE for the whole batch
+
+**Error resolution cycle:**
+1. Read the FULL error output (not just first line)
+2. Identify root cause: file path + line number
+3. Fix the issue in source code
+4. Rebuild/retest
+5. If still failing → repeat from step 1
+6. **NEVER** commit with failing build or tests
+
+---
+
+## C. Commit Batch
+
+```bash
+# Stage all changed files from batch
+git add {all_files_from_batch}
+git add .ralph/prd.json
+
+git commit -m "$(cat <<'EOF'
+feat({scope}): [{category}] {batch.length} tasks — {short summary}
+
+Tasks: {task_ids} / {total}
+Iteration: {iteration}
+{module ? "Module: " + module : ""}
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+
+COMMIT_HASH=$(git rev-parse --short HEAD)
+```
+
+**Finalize tasks in prd.json:**
+```javascript
+const now = new Date().toISOString();
+for (const task of batch) {
+  if (task.status !== 'failed') task.status = 'completed';
+  task.completed_at = now;
+  task.iteration = prd.config.current_iteration;
+  task.commit_hash = COMMIT_HASH;
+}
+prd.history.push({
+  iteration: prd.config.current_iteration,
+  task_ids: batch.map(t => t.id),
+  action: 'batch-completed',
+  timestamp: now,
+  commit_hash: COMMIT_HASH,
+  notes: "{summary}"
+});
+prd.config.current_iteration++;
+prd.updated_at = now;
+writeJSON('.ralph/prd.json', prd);
+```
+
+**Commit progress:**
+```bash
+git add .ralph/prd.json .ralph/progress.txt
+[ -f .ralph/modules-queue.json ] && git add .ralph/modules-queue.json
+git commit -m "chore(ralph): progress — iteration {iteration}"
+```
+
+---
+
+## D. Loop Back
+
+**IMMEDIATELY return to step-04 section 1 (Read Current State).**
+DO NOT stop. DO NOT wait for user. DO NOT re-read step files.
+
+The only exit conditions:
+- ALL tasks complete (all modules if multi-module)
+- Max iterations reached
+- Dead-end (all remaining blocked/failed)
+- User Ctrl+C