@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/apex/references/error-classification.md

@@ -1,144 +1,144 @@
-# Error Classification Reference
-
-> **Loaded by:** apex step-03-execute (build failure) and step-04-examine (validation)
-> **Purpose:** Classify build and runtime errors to apply the correct fix strategy.
-> **Key insight:** Not all errors are code errors. Package/config errors require different fixes than code errors.
-> **Moved from:** `ralph-loop/references/error-classification.md` (delegation refactoring)
-
----
-
-## Error Categories
-
-### Category A: Missing NuGet Package (FIX = `dotnet add package`)
-
-> **These errors CANNOT be fixed by editing source code. Do NOT waste iterations trying.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | `Could not load file or assembly 'Microsoft.Extensions.Http.Resilience, Version=10.2.0.0'` | `dotnet add package {Name} --version {V.Major}.{V.Minor}.{V.Patch}` |
-| `error CS0246: The type or namespace name '{Type}' could not be found` (after restore) | `The type or namespace name 'Polly' could not be found` | `dotnet add package {PackageName}` |
-| `error NU1101: Unable to find package {Name}` | Package source misconfigured | Check `nuget.config` sources |
-
-**Detection heuristic:** If `dotnet build` fails with CS0246 and the missing type is NOT in any project file (grep across `src/`), it is a missing package, not a missing `using` statement.
-
-**Fix procedure:**
-1. Extract package name from error message
-2. Run `dotnet add {TargetProject} package {PackageName}`
-3. Run `dotnet restore`
-4. Rebuild -- if still failing, the version may need to be pinned
-
----
-
-### Category B: Version Mismatch (FIX = update package version)
-
-> **These errors CANNOT be fixed by editing source code.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | Type exists in different version | `dotnet add package {Asm} --version {CorrectVersion}` |
-| `MissingMethodException: Method not found: '{Method}'` | Method signature changed between versions | Update to version that has the method |
-| `NU1605: Detected package downgrade` | Version conflict in dependency tree | Align all references to same version |
-| `FileLoadException: Could not load file or assembly '{Name}'. The located assembly's manifest definition does not match the assembly reference.` | Wrong version loaded | Pin correct version in .csproj |
-
-**Fix procedure:**
-1. Identify the assembly/package name
-2. Run `dotnet list package --include-transitive` to see actual resolved version
-3. If conflict: add explicit `<PackageReference>` with correct version
-4. Rebuild
-
----
-
-### Category C: Missing DI Registration (FIX = edit DI configuration)
-
-> **These errors require editing `DependencyInjection.cs` or `Program.cs`, NOT the service/interface code.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `InvalidOperationException: Unable to resolve service for type '{Interface}'` | Missing `services.AddScoped<IFoo, Foo>()` | Add DI registration |
-| `InvalidOperationException: No service for type '{Type}' has been registered` | Same as above | Same |
-| `InvalidOperationException: Unable to resolve service for type '{Type}' while attempting to activate '{Consumer}'` | Consumer's dependency not registered | Register the missing dependency |
-
-**Fix procedure:**
-1. Extract the interface/type name from error
-2. Find the implementation class (grep for `class.*: {Interface}`)
-3. Add `services.AddScoped<{Interface}, {Implementation}>()` to appropriate DI file
-4. Rebuild
-
----
-
-### Category D: Database/Migration (FIX = run migration commands)
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `SqlException: Invalid object name '{TableName}'` | Table does not exist | `dotnet ef database update` |
-| `SqlException: Invalid column name '{Column}'` | Column not in schema | Create and apply migration |
-| `RelationalEventId.PendingModelChangesWarning` | Model changed, no migration | `dotnet ef migrations add {Name}` |
-
----
-
-### Category E: Configuration (FIX = edit appsettings.json)
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `InvalidOperationException: The ConnectionString property has not been initialized` | Missing connection string | Add to `appsettings.json` |
-| `ArgumentNullException: Value cannot be null. (Parameter 'connectionString')` | Same | Same |
-| `OptionsValidationException: Validation failed for '{Section}'` | Missing required config section | Add section to `appsettings.json` |
-
----
-
-### Category F: Code Error (FIX = edit source code)
-
-> **Only this category should trigger code editing in ralph-loop iterations.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `error CS0246` + type IS in a project file | Missing `using` statement | Add `using {Namespace};` |
-| `error CS1061` | Method does not exist on type | Fix method call or add method |
-| `error CS0103` | Name does not exist in current context | Fix variable/method reference |
-| `error CS0029` | Cannot implicitly convert type | Fix type mismatch |
-| Test assertion failures | `Assert.Equal` fails | Fix source code (not tests) |
-
----
-
-## Decision Tree
-
-When a build or runtime error occurs, follow this tree:
-
-```
-BUILD/RUNTIME ERROR
-  |
-  +-- Contains "Could not load file or assembly" ?
-  |     YES -> Category A or B (NEVER edit source code)
-  |     Extract package name -> dotnet add package -> rebuild
-  |
-  +-- Contains "Unable to resolve service" ?
-  |     YES -> Category C (edit DI config ONLY)
-  |     Find implementation -> add registration -> rebuild
-  |
-  +-- Contains "SqlException" or "Invalid object name" ?
-  |     YES -> Category D (run migrations)
-  |     dotnet ef migrations add / database update
-  |
-  +-- Contains "ConnectionString" or "OptionsValidation" ?
-  |     YES -> Category E (edit config files)
-  |
-  +-- error CS#### (C# compiler error) ?
-  |     YES -> Is the missing type in ANY project file?
-  |           NO  -> Category A (missing package)
-  |           YES -> Category F (fix source code)
-  |
-  +-- Test failure (Assert/Expected) ?
-        YES -> Category F (fix source code, NOT tests)
-```
-
----
-
-## Ralph-Loop Integration Rules
-
-1. **Before ANY code fix attempt:** Classify the error using the decision tree above
-2. **Categories A, B:** Run package commands IMMEDIATELY. Do NOT count as a "fix iteration"
-3. **Category C:** Edit DI file only. One targeted fix, rebuild, verify
-4. **Category D:** Run migration commands. Do NOT edit code
-5. **Category E:** Edit config file only
-6. **Category F:** Normal ralph-loop code fix iteration
-7. **If 2+ consecutive iterations fail on same error after code fixes -> re-classify** (likely wrong category)
+# Error Classification Reference
+
+> **Loaded by:** apex step-03-execute (build failure) and step-04-examine (validation)
+> **Purpose:** Classify build and runtime errors to apply the correct fix strategy.
+> **Key insight:** Not all errors are code errors. Package/config errors require different fixes than code errors.
+> **Moved from:** `ralph-loop/references/error-classification.md` (delegation refactoring)
+
+---
+
+## Error Categories
+
+### Category A: Missing NuGet Package (FIX = `dotnet add package`)
+
+> **These errors CANNOT be fixed by editing source code. Do NOT waste iterations trying.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | `Could not load file or assembly 'Microsoft.Extensions.Http.Resilience, Version=10.2.0.0'` | `dotnet add package {Name} --version {V.Major}.{V.Minor}.{V.Patch}` |
+| `error CS0246: The type or namespace name '{Type}' could not be found` (after restore) | `The type or namespace name 'Polly' could not be found` | `dotnet add package {PackageName}` |
+| `error NU1101: Unable to find package {Name}` | Package source misconfigured | Check `nuget.config` sources |
+
+**Detection heuristic:** If `dotnet build` fails with CS0246 and the missing type is NOT in any project file (grep across `src/`), it is a missing package, not a missing `using` statement.
+
+**Fix procedure:**
+1. Extract package name from error message
+2. Run `dotnet add {TargetProject} package {PackageName}`
+3. Run `dotnet restore`
+4. Rebuild -- if still failing, the version may need to be pinned
+
+---
+
+### Category B: Version Mismatch (FIX = update package version)
+
+> **These errors CANNOT be fixed by editing source code.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | Type exists in different version | `dotnet add package {Asm} --version {CorrectVersion}` |
+| `MissingMethodException: Method not found: '{Method}'` | Method signature changed between versions | Update to version that has the method |
+| `NU1605: Detected package downgrade` | Version conflict in dependency tree | Align all references to same version |
+| `FileLoadException: Could not load file or assembly '{Name}'. The located assembly's manifest definition does not match the assembly reference.` | Wrong version loaded | Pin correct version in .csproj |
+
+**Fix procedure:**
+1. Identify the assembly/package name
+2. Run `dotnet list package --include-transitive` to see actual resolved version
+3. If conflict: add explicit `<PackageReference>` with correct version
+4. Rebuild
+
+---
+
+### Category C: Missing DI Registration (FIX = edit DI configuration)
+
+> **These errors require editing `DependencyInjection.cs` or `Program.cs`, NOT the service/interface code.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `InvalidOperationException: Unable to resolve service for type '{Interface}'` | Missing `services.AddScoped<IFoo, Foo>()` | Add DI registration |
+| `InvalidOperationException: No service for type '{Type}' has been registered` | Same as above | Same |
+| `InvalidOperationException: Unable to resolve service for type '{Type}' while attempting to activate '{Consumer}'` | Consumer's dependency not registered | Register the missing dependency |
+
+**Fix procedure:**
+1. Extract the interface/type name from error
+2. Find the implementation class (grep for `class.*: {Interface}`)
+3. Add `services.AddScoped<{Interface}, {Implementation}>()` to appropriate DI file
+4. Rebuild
+
+---
+
+### Category D: Database/Migration (FIX = run migration commands)
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `SqlException: Invalid object name '{TableName}'` | Table does not exist | `dotnet ef database update` |
+| `SqlException: Invalid column name '{Column}'` | Column not in schema | Create and apply migration |
+| `RelationalEventId.PendingModelChangesWarning` | Model changed, no migration | `dotnet ef migrations add {Name}` |
+
+---
+
+### Category E: Configuration (FIX = edit appsettings.json)
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `InvalidOperationException: The ConnectionString property has not been initialized` | Missing connection string | Add to `appsettings.json` |
+| `ArgumentNullException: Value cannot be null. (Parameter 'connectionString')` | Same | Same |
+| `OptionsValidationException: Validation failed for '{Section}'` | Missing required config section | Add section to `appsettings.json` |
+
+---
+
+### Category F: Code Error (FIX = edit source code)
+
+> **Only this category should trigger code editing in ralph-loop iterations.**
+
+| Error Pattern | Example | Fix |
+|--------------|---------|-----|
+| `error CS0246` + type IS in a project file | Missing `using` statement | Add `using {Namespace};` |
+| `error CS1061` | Method does not exist on type | Fix method call or add method |
+| `error CS0103` | Name does not exist in current context | Fix variable/method reference |
+| `error CS0029` | Cannot implicitly convert type | Fix type mismatch |
+| Test assertion failures | `Assert.Equal` fails | Fix source code (not tests) |
+
+---
+
+## Decision Tree
+
+When a build or runtime error occurs, follow this tree:
+
+```
+BUILD/RUNTIME ERROR
+  |
+  +-- Contains "Could not load file or assembly" ?
+  |     YES -> Category A or B (NEVER edit source code)
+  |     Extract package name -> dotnet add package -> rebuild
+  |
+  +-- Contains "Unable to resolve service" ?
+  |     YES -> Category C (edit DI config ONLY)
+  |     Find implementation -> add registration -> rebuild
+  |
+  +-- Contains "SqlException" or "Invalid object name" ?
+  |     YES -> Category D (run migrations)
+  |     dotnet ef migrations add / database update
+  |
+  +-- Contains "ConnectionString" or "OptionsValidation" ?
+  |     YES -> Category E (edit config files)
+  |
+  +-- error CS#### (C# compiler error) ?
+  |     YES -> Is the missing type in ANY project file?
+  |           NO  -> Category A (missing package)
+  |           YES -> Category F (fix source code)
+  |
+  +-- Test failure (Assert/Expected) ?
+        YES -> Category F (fix source code, NOT tests)
+```
+
+---
+
+## Ralph-Loop Integration Rules
+
+1. **Before ANY code fix attempt:** Classify the error using the decision tree above
+2. **Categories A, B:** Run package commands IMMEDIATELY. Do NOT count as a "fix iteration"
+3. **Category C:** Edit DI file only. One targeted fix, rebuild, verify
+4. **Category D:** Run migration commands. Do NOT edit code
+5. **Category E:** Edit config file only
+6. **Category F:** Normal ralph-loop code fix iteration
+7. **If 2+ consecutive iterations fail on same error after code fixes -> re-classify** (likely wrong category)

package/templates/skills/apex/references/examine-build-validation.md

@@ -1,82 +1,82 @@
-# Examine Build & Migration Validation
-
-> **Loaded by:** step-04-examine.md (sections 4-5)
-> **Purpose:** Build verification, migration validation, database testing procedures.
-
----
-
-## Build Verification
-
-```bash
-# Backend
-dotnet clean && dotnet restore && dotnet build
-# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
-
-# Frontend (if applicable)
-npm run typecheck
-```
-
-**BLOCKING:** Both must pass. If failure, classify error per `references/error-classification.md`:
-- Category A (missing package) → `dotnet add package` → rebuild
-- Category B (assembly conflict) → resolve version → rebuild
-- Category C (DI missing) → fix DI registration → rebuild
-- Category D (migration broken) → fix migration → rebuild
-- Category E (config) → fix config → rebuild
-- Category F (source code) → fix code → rebuild
-
----
-
-## Migration Validation (if needs_migration)
-
-### Pending Model Changes Check
-
-```bash
-INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
-API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
-
-dotnet ef migrations has-pending-model-changes \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$API_PROJECT"
-```
-
-**BLOCKING** if pending changes detected → migration is missing.
-
-### Migration Application Test (SQL Server LocalDB)
-
-```bash
-DB_NAME="SmartStack_Apex_Examine_$(date +%s)"
-CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
-
-dotnet ef database update \
-  --connection "$CONN_STRING" \
-  --project "$INFRA_PROJECT" \
-  --startup-project "$API_PROJECT"
-```
-
-**BLOCKING** if migration fails on SQL Server. Common issues:
-- SQLite-only syntax in migrations (fix: regenerate migration)
-- Column type mismatches (fix: update EF configuration)
-- Missing foreign key targets (fix: reorder migrations)
-
-### Integration Tests on Real SQL Server
-
-```bash
-# Integration tests use DatabaseFixture → real SQL Server LocalDB
-# This validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs
-INT_TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
-if [ -n "$INT_TEST_PROJECT" ]; then
-  dotnet test "$INT_TEST_PROJECT" --no-build --verbosity normal
-fi
-```
-
-Tests running against SQL Server catch issues that SQLite misses:
-- Case sensitivity in string comparisons
-- Date/time function differences
-- IDENTITY vs AUTOINCREMENT behavior
-- Global query filter translation to T-SQL
-
-### Cleanup
-
-```bash
-sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$DB_NAME]; END" 2>/dev/null
-```
+# Examine Build & Migration Validation
+
+> **Loaded by:** step-04-examine.md (sections 4-5)
+> **Purpose:** Build verification, migration validation, database testing procedures.
+
+---
+
+## Build Verification
+
+```bash
+# Backend
+dotnet clean && dotnet restore && dotnet build
+# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
+
+# Frontend (if applicable)
+npm run typecheck
+```
+
+**BLOCKING:** Both must pass. If failure, classify error per `references/error-classification.md`:
+- Category A (missing package) → `dotnet add package` → rebuild
+- Category B (assembly conflict) → resolve version → rebuild
+- Category C (DI missing) → fix DI registration → rebuild
+- Category D (migration broken) → fix migration → rebuild
+- Category E (config) → fix config → rebuild
+- Category F (source code) → fix code → rebuild
+
+---
+
+## Migration Validation (if needs_migration)
+
+### Pending Model Changes Check
+
+```bash
+INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
+API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
+
+dotnet ef migrations has-pending-model-changes \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**BLOCKING** if pending changes detected → migration is missing.
+
+### Migration Application Test (SQL Server LocalDB)
+
+```bash
+DB_NAME="SmartStack_Apex_Examine_$(date +%s)"
+CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
+
+dotnet ef database update \
+  --connection "$CONN_STRING" \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**BLOCKING** if migration fails on SQL Server. Common issues:
+- SQLite-only syntax in migrations (fix: regenerate migration)
+- Column type mismatches (fix: update EF configuration)
+- Missing foreign key targets (fix: reorder migrations)
+
+### Integration Tests on Real SQL Server
+
+```bash
+# Integration tests use DatabaseFixture → real SQL Server LocalDB
+# This validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs
+INT_TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
+if [ -n "$INT_TEST_PROJECT" ]; then
+  dotnet test "$INT_TEST_PROJECT" --no-build --verbosity normal
+fi
+```
+
+Tests running against SQL Server catch issues that SQLite misses:
+- Case sensitivity in string comparisons
+- Date/time function differences
+- IDENTITY vs AUTOINCREMENT behavior
+- Global query filter translation to T-SQL
+
+### Cleanup
+
+```bash
+sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$DB_NAME]; END" 2>/dev/null
+```