@atlashub/smartstack-cli 3.8.0 → 3.9.0

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

@@ -6,14 +6,11 @@ next_step: steps/step-03-commit.md
 
 # Step 2: Execute Task
 
-> **CONTEXT OPTIMIZATION:** This file is only read ONCE (first iteration).
-> After the first full iteration, ALL subsequent iterations use the COMPACT LOOP
-> in step-04-check.md section 5 which includes inline execution.
-> **DO NOT re-read this file for iterations > 1.**
+> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.
 
 ## YOUR TASK:
 
-Execute the current task(s) from prd.json. For the first iteration, execute ONE task. After the first iteration, the compact loop in step-04 handles batch execution.
+Execute the current task from prd.json. First iteration = ONE task. After that, compact loop handles batches.
 
 **ULTRA THINK about the implementation.**
 
@@ -21,11 +18,11 @@ Execute the current task(s) from prd.json. For the first iteration, execute ONE
 
 ## EXECUTION RULES:
 
-1. **ATOMIC CHANGES** - Changes should be complete and working
-2. **USE MCP** - Validate with SmartStack MCP (once per batch, not per task)
-3. **TRACK FILES** - Record every file created or modified
-4. **CHECK DEPENDENCIES** - Verify all dependencies are met before starting
-5. **BATCH ALLOWED** - Multiple tasks of the same category can be batched (max 5)
+1. **ATOMIC CHANGES** — Complete and working
+2. **USE MCP** — Validate with SmartStack MCP (once per batch)
+3. **TRACK FILES** — Record every file created or modified
+4. **CHECK DEPENDENCIES** — Verify before starting
+5. **BATCH ALLOWED** — Same category, max 5 tasks
 
 ---
 
@@ -33,737 +30,128 @@ Execute the current task(s) from prd.json. For the first iteration, execute ONE
 
 ### 1. Verify Dependencies
 
-**BEFORE starting, check all dependencies are satisfied:**
-
 ```javascript
 const prd = readJSON('.ralph/prd.json');
 const task = prd.tasks.find(t => t.id === {current_task_id});
-
 for (const depId of task.dependencies) {
   const dep = prd.tasks.find(t => t.id === depId);
   if (!dep || dep.status !== 'completed') {
-    echo `❌ BLOCKED: Task ${task.id} depends on task ${depId} (status: ${dep?.status || 'missing'})`;
-    task.status = 'blocked';
-    task.error = `Dependency task ${depId} not completed (${dep?.status})`;
+    task.status = 'blocked'; task.error = `Dependency ${depId} not completed`;
     writeJSON('.ralph/prd.json', prd);
-    STOP - return to step-01 to find next eligible task
+    STOP — return to step-01
   }
 }
 ```
 
-### 2. Mark Task as In-Progress
-
-**Update prd.json immediately:**
+### 2. Mark In-Progress
 
 ```javascript
 task.status = 'in_progress';
 task.started_at = new Date().toISOString();
-prd.updated_at = task.started_at;
 writeJSON('.ralph/prd.json', prd);
 ```
 
-### 3. Understand the Task
+### 3. Understand and Execute
 
-**ULTRA THINK:**
+**ULTRA THINK:** What needs to be done? What files? What acceptance criteria? What category?
 
-- What exactly needs to be done?
-- What files need to be created/modified?
-- What are the acceptance criteria? → `{current_task_criteria}`
-- What patterns should be followed?
-- What category is this? → `{current_task_category}`
+**Read `references/category-rules.md` for category-specific execution rules.**
 
-**Category-specific guidance:**
+Key category triggers:
 
-| Category | MCP Tools | Patterns |
-|----------|-----------|----------|
-| `domain` | `validate_conventions` | Entity base class, IHasData, audit fields |
-| `application` | `validate_conventions`, `scaffold_extension` | CQRS, MediatR, FluentValidation |
-| `infrastructure` | `check_migrations`, `suggest_migration` | EF Core config, HasData seeding, IClientSeedDataProvider, SqlObjects |
-| `api` | `scaffold_routes`, `validate_security` | Controller conventions, authorization, context-based folder hierarchy |
-| `frontend` | `validate_frontend_routes`, `scaffold_frontend_extension` | React patterns, hooks, Layout wrapper |
-| `i18n` | - | 4-language JSON structure |
-| `test` | `scaffold_tests`, `analyze_test_coverage` | xUnit, test naming conventions |
-| `validation` | `validate_conventions` | Build, test, lint checks |
+| Category | Special Action |
+|----------|---------------|
+| `infrastructure` with `_migrationMeta` | Migration sequence: MCP suggest → add → update → build |
+| `infrastructure` with seed data keywords | **MANDATORY**: Read `references/core-seed-data.md` |
+| `frontend` | MCP-first: scaffold_api_client → scaffold_routes → pages |
+| `test` | Generate via MCP → run → fix loop → 100% pass required |
+| `validation` | Clean build → full test suite → MCP validate |
 
-**Test task guidance — TDD CYCLE (MANDATORY):**
+### 4. Implement
 
-> **CRITICAL:** Tests are NOT optional. Every feature MUST have tests that pass.
-> The cycle is: Generate Code → Generate Tests → Run Tests → Fix Code → Re-run Tests → Pass.
+- Create/modify files following SmartStack conventions
+- Track: `{files_created} = []`, `{files_modified} = []`
+- Use MCP tools per category (see category-rules.md)
 
-When executing `test` category tasks, follow this EXACT sequence:
+### 5. Post-Infrastructure Build Gate (BLOCKING)
 
-**1. ENSURE TEST PROJECT EXISTS (BLOCKING)**
+**After completing ALL infrastructure tasks (configs + migration + seed data):**
 
 ```bash
-# Detect project name from solution
-PROJECT_NAME=$(basename $(pwd))
-TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
-
-if [ ! -d "$TEST_PROJECT" ]; then
-  echo "⚠️  Test project missing. Scaffolding now..."
-
-  # Create test project
-  dotnet new xunit -n "${PROJECT_NAME}.Tests.Unit" -o "$TEST_PROJECT"
-
-  # Add required packages
-  cd "$TEST_PROJECT"
-  dotnet add package Moq --version 4.20.72
-  dotnet add package FluentAssertions --version 8.3.0
-  dotnet add package Microsoft.Extensions.DependencyInjection --version 10.0.2
-  cd ../..
-
-  # Add project references to all src/ projects
-  for proj in src/*/*.csproj; do
-    dotnet add "$TEST_PROJECT" reference "$proj"
-  done
-
-  # Add test project to solution
-  dotnet sln add "$TEST_PROJECT/${PROJECT_NAME}.Tests.Unit.csproj"
-
-  echo "✅ Test project scaffolded at $TEST_PROJECT"
-fi
+dotnet build --no-restore
 ```
 
-**2. GENERATE TESTS USING MCP (DO NOT WRITE MANUALLY)**
+MUST pass before proceeding to application/api/test/frontend. Fix if fails.
 
-```javascript
-// Identify what to test based on task description
-const task = prd.tasks.find(t => t.id === {current_task_id});
-const testType = detectTestType(task.description); // "unit" | "integration" | "security"
-
-// For domain tests
-if (task.description.includes("domain entity") || task.description.includes("value object")) {
-  // Call MCP to scaffold domain tests
-  mcp__smartstack__scaffold_tests({
-    module: extractModuleName(task.description),
-    test_type: "unit",
-    target_layer: "domain",
-    target_file: identifyEntityFile(task.description)
-  });
-}
-
-// For service tests
-if (task.description.includes("service")) {
-  mcp__smartstack__scaffold_tests({
-    module: extractModuleName(task.description),
-    test_type: "unit",
-    target_layer: "application",
-    target_file: identifyServiceFile(task.description)
-  });
-}
-
-// For controller tests
-if (task.description.includes("controller") || task.description.includes("API")) {
-  mcp__smartstack__scaffold_tests({
-    module: extractModuleName(task.description),
-    test_type: "integration",
-    target_layer: "api",
-    target_file: identifyControllerFile(task.description)
-  });
-}
-
-// For security/permissions tests
-if (task.description.includes("permission") || task.description.includes("security")) {
-  mcp__smartstack__scaffold_tests({
-    module: extractModuleName(task.description),
-    test_type: "security",
-    target_layer: "api",
-    target_file: identifyControllerFile(task.description)
-  });
-}
-```
-
-**3. RUN TESTS IMMEDIATELY (BLOCKING)**
-
-```bash
-# Build test project first
-dotnet build "$TEST_PROJECT" --no-restore
-
-# Run tests with detailed output
-dotnet test "$TEST_PROJECT" --no-build --verbosity normal
+### 6. Validate with MCP
 
-# Capture exit code
-TEST_EXIT_CODE=$?
 ```
+mcp__smartstack__validate_conventions: checks: ["all"]
 
-**4. ANALYZE RESULTS AND IMPROVE (LOOP UNTIL GREEN)**
-
-```javascript
-if (TEST_EXIT_CODE !== 0) {
-  echo "❌ Tests failed. Analyzing failures...";
-
-  // Parse test output to identify failures
-  const failures = parseTestFailures(testOutput);
-
-  // CRITICAL: DO NOT PROCEED. Fix the code.
-  for (const failure of failures) {
-    echo `  - ${failure.testName}: ${failure.reason}`;
-
-    // Identify what needs fixing
-    if (failure.reason.includes("NullReferenceException")) {
-      // Fix null handling in implementation
-    } else if (failure.reason.includes("Expected") && failure.reason.includes("Actual")) {
-      // Fix logic to match expected behavior
-    } else if (failure.reason.includes("NotImplementedException")) {
-      // Implement missing method
-    }
-  }
-
-  // After fixes, RE-RUN TESTS (step 3)
-  // LOOP until TEST_EXIT_CODE === 0
-
-  // If cannot fix after 3 attempts:
-  task.status = 'failed';
-  task.error = `Tests failed after 3 fix attempts: ${failures.map(f => f.testName).join(', ')}`;
-  // STOP - do not proceed to commit
-}
-
-if (TEST_EXIT_CODE === 0) {
-  echo "✅ All tests passed!";
-  {validation_result} = "passed";
-}
+# Category-specific:
+infrastructure → mcp__smartstack__check_migrations
+api            → mcp__smartstack__validate_security
+frontend       → mcp__smartstack__validate_frontend_routes
+test           → mcp__smartstack__analyze_test_coverage
 ```
 
-**5. VERIFY TEST COVERAGE (MANDATORY ≥80%)**
-
-```javascript
-// Use MCP to analyze coverage
-const coverage = mcp__smartstack__analyze_test_coverage({
-  project_path: process.cwd(),
-  module: extractModuleName(task.description)
-});
-
-if (coverage.percentage < 80) {
-  echo `⚠️  Test coverage ${coverage.percentage}% < 80% minimum`;
-  echo `Missing coverage for: ${coverage.uncovered_files.join(', ')}`;
-
-  // Generate additional tests for uncovered code
-  for (const file of coverage.uncovered_files) {
-    mcp__smartstack__scaffold_tests({
-      module: extractModuleName(task.description),
-      test_type: "unit",
-      target_file: file
-    });
-  }
+If validation fails: fix → re-validate → do NOT proceed until clean.
 
-  // Re-run tests (go back to step 3)
-}
-
-echo `✅ Test coverage: ${coverage.percentage}% (${coverage.lines_covered}/${coverage.lines_total} lines)`;
-```
-
-**6. TEST TASK COMPLETION CRITERIA**
-
-A test task is ONLY complete when:
-- ✅ Test project exists
-- ✅ Tests generated via MCP (NOT manually written)
-- ✅ `dotnet test` exits with code 0 (all tests pass)
-- ✅ Test coverage ≥ 80%
-- ✅ No `[Fact(Skip = "...")]` present (no skipped tests)
-
-**If ANY criterion fails, task.status = 'failed' and DO NOT commit.**
-
-**Validation task guidance — FINAL VERIFICATION (BLOCKING):**
-
-> **CRITICAL:** The validation task is the LAST task in each module. It verifies the module is production-ready.
+### 7. Check Acceptance Criteria
 
-When executing `validation` category tasks, follow this EXACT sequence:
+Verify against `{current_task_criteria}`. If not met: continue working. If impossible: document in `task.error`.
 
-**1. CLEAN BUILD (MANDATORY)**
+### 8. Build & Test Verification (BLOCKING)
 
+**Backend — EVERY task (domain, infra, application, api):**
 ```bash
-echo "🔨 Running clean build..."
-
-# Clean previous builds
-dotnet clean --verbosity quiet
-
-# Restore dependencies
-dotnet restore --verbosity quiet
-
-# Build entire solution
-dotnet build --no-restore --verbosity normal
-
-BUILD_EXIT_CODE=$?
-
-if [ $BUILD_EXIT_CODE -ne 0 ]; then
-  echo "╔════════════════════════════════════════════════════════════╗"
-  echo "║  ❌ BUILD FAILED                                          ║"
-  echo "╠════════════════════════════════════════════════════════════╣"
-  echo "║  The solution does not compile.                            ║"
-  echo "║  This indicates a critical error in the code.              ║"
-  echo "╠════════════════════════════════════════════════════════════╣"
-  echo "║  CORRECTIVE ACTION:                                        ║"
-  echo "║  1. Review build errors above                              ║"
-  echo "║  2. Fix compilation errors                                 ║"
-  echo "║  3. Re-run: dotnet build                                   ║"
-  echo "║  4. Once build succeeds, Ralph will continue               ║"
-  echo "╚════════════════════════════════════════════════════════════╝"
-
-  task.status = 'failed';
-  task.error = 'Build failed. See build output for details.';
-  exit 1;
-fi
-
-echo "✅ Build succeeded";
+dotnet build --no-restore
 ```
+If FAIL → read error output → identify file:line → fix code → rebuild → loop until exit code 0.
 
-**2. RUN FULL TEST SUITE (MANDATORY)**
-
+**Test category tasks — MANDATORY execution:**
 ```bash
-echo "🧪 Running full test suite..."
-
-PROJECT_NAME=$(basename $(pwd))
-TEST_PROJECT="tests/${PROJECT_NAME}.Tests.Unit"
-
-if [ ! -d "$TEST_PROJECT" ]; then
-  echo "⚠️  WARNING: No test project found at $TEST_PROJECT";
-  echo "This module has NO tests. This is NOT recommended.";
-  task.validation = "warning: no tests";
-else
-  # Run ALL tests with detailed output
-  dotnet test "$TEST_PROJECT" --no-build --verbosity normal --logger "console;verbosity=detailed"
-
-  TEST_EXIT_CODE=$?
-
-  if [ $TEST_EXIT_CODE -ne 0 ]; then
-    echo "╔════════════════════════════════════════════════════════════╗"
-    echo "║  ❌ TESTS FAILED                                          ║"
-    echo "╠════════════════════════════════════════════════════════════╣"
-    echo "║  One or more tests are failing.                            ║"
-    echo "║  The module is NOT production-ready.                       ║"
-    echo "╠════════════════════════════════════════════════════════════╣"
-    echo "║  CORRECTIVE ACTION:                                        ║"
-    echo "║  1. Review test failures above                             ║"
-    echo "║  2. Fix the failing code or tests                          ║"
-    echo "║  3. Re-run: dotnet test                                    ║"
-    echo "║  4. Once all tests pass, Ralph will continue               ║"
-    echo "╚════════════════════════════════════════════════════════════╝"
-
-    task.status = 'failed';
-    task.error = 'Test suite failed. Module not production-ready.';
-    exit 1;
-  fi
-
-  echo "✅ All tests passed";
-fi
-```
-
-**3. MCP VALIDATION (MANDATORY)**
-
-```javascript
-echo "🔍 Running MCP validation...";
-
-// Validate SmartStack conventions
-const validation = mcp__smartstack__validate_conventions({
-  checks: ["all"]
-});
-
-if (validation.status === "error" || validation.errors.length > 0) {
-  echo "❌ MCP validation failed:";
-  for (const error of validation.errors) {
-    echo `  - ${error.file}: ${error.message}`;
-  }
-
-  task.status = 'failed';
-  task.error = `MCP validation failed: ${validation.errors.length} error(s)`;
-  exit 1;
-}
-
-if (validation.warnings.length > 0) {
-  echo "⚠️  MCP validation warnings:";
-  for (const warning of validation.warnings) {
-    echo `  - ${warning.file}: ${warning.message}`;
-  }
-  task.validation = `passed with ${validation.warnings.length} warning(s)`;
-} else {
-  task.validation = "passed";
-}
-
-echo "✅ MCP validation passed";
-```
-
-**4. GENERATE VALIDATION REPORT**
-
-```javascript
-const report = {
-  module: {current_module},
-  build: { status: "success", duration: buildDuration },
-  tests: {
-    status: TEST_EXIT_CODE === 0 ? "success" : "failed",
-    total: testStats.total,
-    passed: testStats.passed,
-    failed: testStats.failed,
-    skipped: testStats.skipped,
-    duration: testStats.duration,
-    coverage: coverage.percentage
-  },
-  mcp: {
-    status: validation.status,
-    errors: validation.errors.length,
-    warnings: validation.warnings.length
-  },
-  production_ready: (BUILD_EXIT_CODE === 0 && TEST_EXIT_CODE === 0 && validation.errors.length === 0)
-};
-
-// Append to progress.txt
-const progressEntry = `
-╔═══════════════════════════════════════════════════════════════╗
-║  MODULE VALIDATION REPORT - ${current_module}
-╠═══════════════════════════════════════════════════════════════╣
-║  Build:    ${report.build.status.toUpperCase()}
-║  Tests:    ${report.tests.passed}/${report.tests.total} passed (${report.tests.coverage}% coverage)
-║  MCP:      ${report.mcp.status.toUpperCase()} (${report.mcp.errors} errors, ${report.mcp.warnings} warnings)
-║  Production Ready: ${report.production_ready ? "YES ✅" : "NO ❌"}
-╚═══════════════════════════════════════════════════════════════╝
-`;
-appendToFile('.ralph/progress.txt', progressEntry);
-
-echo progressEntry;
-```
-
-**5. VALIDATION TASK COMPLETION CRITERIA**
-
-A validation task is ONLY complete when:
-- ✅ `dotnet build` exits with code 0
-- ✅ `dotnet test` exits with code 0 (or no test project + warning logged)
-- ✅ MCP `validate_conventions` has 0 errors
-- ✅ Production ready = true
-
-**If ANY criterion fails, task.status = 'failed', module is NOT production-ready, and Ralph STOPS.**
-
-**Infrastructure task guidance (MANDATORY directory conventions):**
-
-When executing `infrastructure` category tasks, follow these rules strictly:
-
-1. **Core seed data (navigation, permissions, roles) — CONDITIONAL REFERENCE LOADING:**
-
-   > **IF** the current task description contains "seed data", "SeedData",
-   > "NavigationModule", "PermissionsSeedData", "RolesSeedData", or "IClientSeedDataProvider":
-   > **THEN read `references/core-seed-data.md`** for COMPLETE execution guidance including:
-   > - Parameter extraction from PRD seedDataCore / task `_seedDataMeta`
-   > - MCP `generate_permissions` call sequence (primary) with fallback templates
-   > - `NavigationModuleSeedData.cs` template (deterministic GUIDs, 4 languages)
-   > - `PermissionsSeedData.cs` template (wraps MCP output)
-   > - `RolesSeedData.cs` template (context-based role mapping)
-   > - `IClientSeedDataProvider` complete implementation template
-   > - DI registration pattern
-   > - Verification checklist (BLOCKING)
-   >
-   > **This reference is MANDATORY for seed data tasks. Do NOT improvise.**
-
-   **Directory convention:** All seed data files MUST go under `Infrastructure/Persistence/Seeding/Data/{Module}/`
-   - NEVER use `Infrastructure/Data/SeedData/` or `Data/SeedData/`
-
-2. **IClientSeedDataProvider** (client projects with `extensions` DbContext):
-   - Generate at `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
-   - Register in DI: `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()`
-   - Must implement: SeedNavigationAsync, SeedPermissionsAsync, SeedRolePermissionsAsync
-   - **Complete template and rules in `references/core-seed-data.md`**
-
-3. **DevDataSeeder** for domain entity seed data:
-   - Located at `Infrastructure/Persistence/Seeding/DevDataSeeder.cs`
-   - Implements `IDevDataSeeder`, registered in DI
-
-4. **Migrations** MUST all be in `Infrastructure/Persistence/Migrations/`
-   - NEVER create subdirectories under Migrations/
-   - Always use `-o Persistence/Migrations` flag with `dotnet ef migrations add`
-
-5. **SQL Objects** go under `Infrastructure/Persistence/SqlObjects/`
-   - `Functions/` for TVFs and scalar functions (.sql files)
-   - Use `SqlObjectHelper.cs` for embedded resource loading
-   - Use `CREATE OR ALTER` in SQL files for idempotency
-
-**Frontend task guidance — MCP-FIRST PROTOCOL (MANDATORY):**
-
-> **CRITICAL:** Frontend code is generated via MCP tools, NOT written from scratch.
-> Writing plain HTML tables, custom div cards, or hardcoded Tailwind is FORBIDDEN.
-> The MCP tools produce SmartStack-compliant code automatically.
-
-**Execution sequence for frontend tasks (follow IN ORDER):**
-
-1. **Call `mcp__smartstack__scaffold_api_client`** FIRST
-   - Generates: `{entity}Api.ts` with type-safe CRUD methods + React Query hook
-   - Uses `apiClient` (NOT axios), NavRoute integration, permission checking
-   - Output: `src/services/api/{module}Api.ts`
-
-2. **Call `mcp__smartstack__scaffold_routes`** (source: "controllers", scope: "all")
-   - Updates: `navRoutes.generated.ts` + route config in App.tsx
-   - Generates: Nested routes INSIDE correct Layout wrapper
-   - Context mapping: `business.*` → `BusinessLayout`, `platform.*` → `AdminLayout`
-
-3. **Create pages using SmartStack components** (reference: `templates-frontend.md`)
-   - **List pages**: Use `SmartTable` (NOT HTML `<table>`), `SmartFilter`, `EntityCard` for grid view
-   - **Detail pages**: Use `EntityDetailCard`, `StatusBadge`, tab layout
-   - **Create/Edit pages**: Use `SmartForm` with `FluentValidation`-backed fields, tab layout
-   - **Dashboard pages**: Use `StatCard`, Recharts components
-   - Match wireframes from feature.json `specification.uiWireframes[]`
-
-4. **Create preferences hook**: `use{Module}Preferences.ts`
-   - pageSize, sortColumn, sortDirection, visibleColumns, viewMode, filters
-
-5. **Generate i18n** (4 languages: fr, en, it, de)
-   - All UI labels, validation messages, button text, empty states
-
-6. **Post-generation validation (BLOCKING)**:
-   - `npm run typecheck` MUST pass
-   - NO hardcoded colors (scan for `bg-blue-`, `text-gray-`, etc.)
-   - CSS variables ONLY: `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
-   - Routes are NESTED and INSIDE Layout wrapper
-   - All pages have loading/error/empty states
-   - API client uses `@/services/api/apiClient` (NOT `import axios`)
-   - `EntityCard` for grid views (NOT custom `<div>` cards)
-
-**FORBIDDEN patterns (any of these = FAIL the task):**
-```
-import axios from 'axios'                    → use @/services/api/apiClient
-<table>...</table>                           → use SmartTable component
-<div className="bg-blue-600">               → use bg-[var(--color-accent-600)]
-<Route path="/business/app/mod" />           → MUST be nested inside BusinessLayout
-Only fr/en translations                      → MUST have 4 languages (fr, en, it, de)
-```
-
-**Layout wrapper mapping:**
-| Context | Layout | Route path |
-|---------|--------|------------|
-| `platform.*` | `AdminLayout` | `/platform` |
-| `business.*` | `BusinessLayout` | `/business` |
-| `personal.*` | `UserLayout` | `/personal/myspace` |
-
-**Backend folder hierarchy (MANDATORY for ALL layers):**
-
-> **CRITICAL:** ALL backend files MUST be organized by `{ContextPascal}/{ApplicationName}/{ModuleName}/` hierarchy.
-> Derive from PRD `project.application` and feature.json `metadata.context`.
-> The file paths in prd.json already include this hierarchy — follow them exactly.
-
-When executing `domain`, `application`, `infrastructure`, `api`, or `test` category tasks:
-
-1. **ALL layers use context/application/module folder hierarchy:**
-
-   | Layer | Path Pattern |
-   |-------|-------------|
-   | Domain | `Domain/Entities/{ContextPascal}/{App}/{Module}/{Entity}.cs` |
-   | Domain Enums | `Domain/Enums/{ContextPascal}/{App}/{Module}/{Enum}.cs` |
-   | Domain Exceptions | `Domain/Exceptions/{ContextPascal}/{App}/{Module}/{Exception}.cs` |
-   | Application Services | `Application/Services/{ContextPascal}/{App}/{Module}/{Service}.cs` |
-   | Application DTOs | `Application/DTOs/{ContextPascal}/{App}/{Module}/{Dto}.cs` |
-   | Application Validators | `Application/Validators/{ContextPascal}/{App}/{Module}/{Validator}.cs` |
-   | Infrastructure Configs | `Infrastructure/Persistence/Configurations/{ContextPascal}/{App}/{Module}/{Config}.cs` |
-   | API Controllers | `Api/Controllers/{ContextShort}/{App}/{Entity}Controller.cs` |
-   | Tests | `Tests/Unit/Domain/{ContextPascal}/{App}/{Module}/{Tests}.cs` |
-
-2. **Controller context-to-folder mapping (`{ContextShort}`):**
-
-   | NavRoute Prefix | Controller Folder |
-   |-----------------|-------------------|
-   | `platform.administration` | `Admin` |
-   | `platform.support` | `Support` |
-   | `business.*` | `Business` |
-   | `personal.*` | `User` |
-
-3. **Reference:** SmartStack.app `Api/Controllers/` for the canonical structure
-
-### 4. Explore Context (if needed)
-
-**Use subagents sparingly:**
-
-```
-If exploration needed:
-  - Use explore-codebase agent for file discovery
-  - Use explore-docs agent for library docs
-  - Use Context7 MCP for documentation
-```
-
-**Prefer direct tool usage:**
-- Glob for file patterns
-- Grep for code search
-- Read for file contents
-
-### 5. Execute Implementation
-
-**Implement the task:**
-
-- Create/modify files as needed
-- Follow existing patterns in codebase
-- Use SmartStack conventions
-- Add appropriate logging
-- Handle errors properly
-
-**Track every file operation:**
-
-```
-{files_created}  = []   // Accumulate as you create files
-{files_modified} = []   // Accumulate as you modify files
-```
-
-**Use TodoWrite to track sub-steps:**
-
-```
-If task has multiple parts:
-  1. Create TodoWrite entries for each part
-  2. Mark in_progress as you work
-  3. Mark completed when done
-```
-
-### 6. Validate with MCP
-
-**After implementation, validate based on category:**
-
-```
-# Always run general validation
-mcp__smartstack__validate_conventions:
-  checks: ["all"]
-
-# Category-specific validation
-if category == "infrastructure":
-  mcp__smartstack__check_migrations
-
-if category == "api":
-  mcp__smartstack__validate_security
-
-if category == "frontend":
-  mcp__smartstack__validate_frontend_routes
-
-if category == "test":
-  mcp__smartstack__analyze_test_coverage
-```
-
-**Record validation result:**
-```
-{validation_result} = "passed" | "failed: {reason}"
-```
-
-**If validation fails:**
-- Fix the issues
-- Re-validate
-- Do NOT proceed until valid
-- If cannot fix: set `{validation_result} = "failed: {reason}"`
-
-### 7. Check Acceptance Criteria
-
-**Verify against `{current_task_criteria}`:**
-
-```
-ULTRA THINK: Does the implementation satisfy the acceptance criteria?
-
-Criteria: {current_task_criteria}
-
-✅ Met / ❌ Not met (explain why)
+TEST_PROJECT="tests/$(basename $(pwd)).Tests.Unit"
+dotnet build "$TEST_PROJECT" --no-restore
+dotnet test "$TEST_PROJECT" --no-build --verbosity normal
 ```
+If FAIL → analyze failing test names → fix SOURCE CODE (not tests) → rebuild → retest.
+**Loop until 100% pass — NEVER proceed with failing tests.**
 
-**If criteria NOT met:**
-- Continue working until met
-- If impossible to meet: document in `{task_error}`
-
-### 8. Run Quick Tests
-
-**If applicable:**
-
+**Frontend tasks — MANDATORY verification:**
 ```bash
-# For backend changes (domain, application, infrastructure, api)
-dotnet build --no-restore 2>&1
-
-# For frontend changes
-npm run lint && npm run typecheck
-
-# For test category
-dotnet test --filter "FullyQualifiedName~{relevant_test}"
+npm run typecheck    # TypeScript compilation — MUST exit 0
+npm run lint         # ESLint — MUST exit 0
 ```
+If FAIL → read errors → fix TSX/TS files → re-run → loop until pass.
 
-**If tests fail:**
-- Fix the failing tests
-- Re-run until passing
-- Document what was fixed
-
-### 9. Update Task State in prd.json
+**Error resolution cycle (ALL categories):**
+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: `dotnet build --no-restore` or `npm run typecheck`
+5. If still failing → repeat from step 1
+6. **NEVER** mark task completed with failing build or tests
+7. **NEVER** skip the verification — it is BLOCKING
 
-**Persist tracking data BEFORE committing:**
+### 9. Update Task State
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
-const task = prd.tasks.find(t => t.id === {current_task_id});
-
-task.files_changed = {
-  created: {files_created},
-  modified: {files_modified}
-};
+task.files_changed = { created: {files_created}, modified: {files_modified} };
 task.validation = {validation_result};
-
-// If task failed
-if ({task_failed}) {
-  task.status = 'failed';
-  task.error = '{failure_reason}';
-  task.completed_at = new Date().toISOString();
-}
-
+if ({task_failed}) { task.status = 'failed'; task.error = '{reason}'; task.completed_at = now; }
 prd.updated_at = new Date().toISOString();
 writeJSON('.ralph/prd.json', prd);
 ```
 
-**Note: `task.status` stays `"in_progress"` until step-03 confirms the commit. Only `"failed"` is set here if the task cannot be completed.**
-
----
-
-## IMPORTANT CONSTRAINTS:
-
-### What TO DO:
-- Implement exactly what the task describes
-- Follow existing patterns
-- Validate changes with MCP
-- Track all file operations
-- Check acceptance criteria
-- Write minimal, clean code
-
-### What NOT TO DO:
-- Don't implement other tasks
-- Don't refactor unrelated code
-- Don't add "nice to have" features
-- Don't skip validation
-- Don't forget to track files
-
----
-
-## OUTPUT FORMAT:
-
-```
-Task Executed:
-
-| Action | Details |
-|--------|---------|
-| Task | [{current_task_id}] {current_task_description} |
-| Category | {current_task_category} |
-| Files Created | {files_created} |
-| Files Modified | {files_modified} |
-| Validation | {validation_result} |
-| Acceptance | ✅ Criteria met |
-| Tests | ✅ Passed |
-
--> Committing changes...
-```
+Note: `task.status` stays `"in_progress"` until step-03 confirms commit. Only `"failed"` is set here.
 
 ---
 
-## ERROR HANDLING:
-
-**If task cannot be completed:**
-
-1. Document the blocker in `task.error`
-2. Set `task.status = "failed"` in prd.json
-3. Update progress.txt with learnings
-4. Proceed to step-03 to save progress (commit what was done)
-5. step-04 will handle blocked downstream tasks
-
-**If build fails:**
-
-1. Analyze error messages
-2. Fix the issues
-3. Re-build until success
-4. Then proceed
-
-**If validation fails:**
+## CONSTRAINTS:
 
-1. Fix validation issues
-2. Re-validate until clean
-3. If unfixable: document in `task.error`, set `task.validation = "failed: {reason}"`
+**DO:** Implement exactly what task describes, follow patterns, validate with MCP, track files, check criteria.
+**DON'T:** Implement other tasks, refactor unrelated code, add extras, skip validation.
 
 ---