@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/framework/templates/integrations/clerk-config.cs

@@ -0,0 +1,258 @@
+// ==============================================================================
+// MORPH-SPEC - Clerk Authentication Configuration Template
+// Configuração de autenticação com Clerk para .NET
+// ==============================================================================
+
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Components.Authorization;
+using System.Security.Claims;
+
+namespace {{Namespace}}.Infrastructure.Auth;
+
+// ==============================================================================
+// OPTIONS
+// ==============================================================================
+
+public class ClerkOptions
+{
+    public const string SectionName = "Clerk";
+
+    /// <summary>
+    /// Clerk Secret Key (starts with sk_)
+    /// </summary>
+    public string SecretKey { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Clerk Publishable Key (starts with pk_)
+    /// </summary>
+    public string PublishableKey { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Clerk Frontend API URL
+    /// </summary>
+    public string FrontendApi { get; set; } = string.Empty;
+}
+
+// ==============================================================================
+// SERVICE EXTENSIONS
+// ==============================================================================
+
+public static class ClerkServiceExtensions
+{
+    /// <summary>
+    /// Adiciona autenticação Clerk ao projeto
+    /// Requer: Clerk.Net.AspNetCore.Security
+    /// </summary>
+    public static IServiceCollection AddClerkAuthentication(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        services.Configure<ClerkOptions>(configuration.GetSection(ClerkOptions.SectionName));
+
+        // Opção 1: Usando Clerk.Net SDK oficial
+        // services.AddClerk(configuration);
+
+        // Opção 2: Configuração manual com JWT
+        services.AddAuthentication("Clerk")
+            .AddJwtBearer("Clerk", options =>
+            {
+                var clerkOptions = configuration.GetSection(ClerkOptions.SectionName).Get<ClerkOptions>()!;
+
+                options.Authority = clerkOptions.FrontendApi;
+                options.TokenValidationParameters = new()
+                {
+                    ValidateIssuer = true,
+                    ValidateAudience = false,
+                    ValidateLifetime = true,
+                    ValidateIssuerSigningKey = true,
+                    NameClaimType = ClaimTypes.NameIdentifier
+                };
+            });
+
+        services.AddAuthorization();
+
+        return services;
+    }
+
+    /// <summary>
+    /// Adiciona Clerk para Blazor Server
+    /// </summary>
+    public static IServiceCollection AddClerkBlazor(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        services.AddClerkAuthentication(configuration);
+        services.AddScoped<AuthenticationStateProvider, ClerkAuthenticationStateProvider>();
+        services.AddCascadingAuthenticationState();
+
+        return services;
+    }
+}
+
+// ==============================================================================
+// AUTHENTICATION STATE PROVIDER (Blazor)
+// ==============================================================================
+
+public class ClerkAuthenticationStateProvider : AuthenticationStateProvider
+{
+    private readonly IHttpContextAccessor _httpContextAccessor;
+
+    public ClerkAuthenticationStateProvider(IHttpContextAccessor httpContextAccessor)
+    {
+        _httpContextAccessor = httpContextAccessor;
+    }
+
+    public override Task<AuthenticationState> GetAuthenticationStateAsync()
+    {
+        var user = _httpContextAccessor.HttpContext?.User ?? new ClaimsPrincipal();
+        return Task.FromResult(new AuthenticationState(user));
+    }
+
+    public void NotifyAuthenticationStateChanged()
+    {
+        NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
+    }
+}
+
+// ==============================================================================
+// CLERK USER SERVICE
+// ==============================================================================
+
+public interface IClerkUserService
+{
+    Task<ClerkUser?> GetCurrentUserAsync(CancellationToken ct = default);
+    Task<ClerkUser?> GetUserByIdAsync(string userId, CancellationToken ct = default);
+    Task UpdateUserMetadataAsync(string userId, Dictionary<string, object> metadata, CancellationToken ct = default);
+}
+
+public class ClerkUserService : IClerkUserService
+{
+    private readonly HttpClient _httpClient;
+    private readonly IHttpContextAccessor _httpContextAccessor;
+    private readonly ILogger<ClerkUserService> _logger;
+
+    public ClerkUserService(
+        HttpClient httpClient,
+        IHttpContextAccessor httpContextAccessor,
+        ILogger<ClerkUserService> logger)
+    {
+        _httpClient = httpClient;
+        _httpContextAccessor = httpContextAccessor;
+        _logger = logger;
+    }
+
+    public async Task<ClerkUser?> GetCurrentUserAsync(CancellationToken ct = default)
+    {
+        var userId = _httpContextAccessor.HttpContext?.User.FindFirstValue(ClaimTypes.NameIdentifier);
+        if (string.IsNullOrEmpty(userId)) return null;
+
+        return await GetUserByIdAsync(userId, ct);
+    }
+
+    public async Task<ClerkUser?> GetUserByIdAsync(string userId, CancellationToken ct = default)
+    {
+        try
+        {
+            var response = await _httpClient.GetAsync($"users/{userId}", ct);
+
+            if (!response.IsSuccessStatusCode)
+            {
+                _logger.LogWarning("Failed to get Clerk user {UserId}: {Status}", userId, response.StatusCode);
+                return null;
+            }
+
+            return await response.Content.ReadFromJsonAsync<ClerkUser>(ct);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Error getting Clerk user {UserId}", userId);
+            return null;
+        }
+    }
+
+    public async Task UpdateUserMetadataAsync(string userId, Dictionary<string, object> metadata, CancellationToken ct = default)
+    {
+        var request = new { public_metadata = metadata };
+        var response = await _httpClient.PatchAsJsonAsync($"users/{userId}", request, ct);
+        response.EnsureSuccessStatusCode();
+    }
+}
+
+// ==============================================================================
+// CLERK USER MODEL
+// ==============================================================================
+
+public record ClerkUser
+{
+    public string Id { get; init; } = string.Empty;
+    public string? FirstName { get; init; }
+    public string? LastName { get; init; }
+    public string? ImageUrl { get; init; }
+    public List<ClerkEmailAddress>? EmailAddresses { get; init; }
+    public string? PrimaryEmailAddressId { get; init; }
+    public Dictionary<string, object>? PublicMetadata { get; init; }
+    public long CreatedAt { get; init; }
+    public long UpdatedAt { get; init; }
+
+    public string? PrimaryEmail => EmailAddresses?
+        .FirstOrDefault(e => e.Id == PrimaryEmailAddressId)?.EmailAddress;
+
+    public string FullName => $"{FirstName} {LastName}".Trim();
+}
+
+public record ClerkEmailAddress
+{
+    public string Id { get; init; } = string.Empty;
+    public string EmailAddress { get; init; } = string.Empty;
+    public bool Verified { get; init; }
+}
+
+// ==============================================================================
+// MIDDLEWARE PIPELINE
+// ==============================================================================
+
+public static class ClerkMiddlewareExtensions
+{
+    public static IApplicationBuilder UseClerkAuthentication(this IApplicationBuilder app)
+    {
+        app.UseAuthentication();
+        app.UseAuthorization();
+        return app;
+    }
+}
+
+// ==============================================================================
+// APPSETTINGS EXAMPLE
+// ==============================================================================
+
+/*
+{
+  "Clerk": {
+    "SecretKey": "sk_test_xxxxx",
+    "PublishableKey": "pk_test_xxxxx",
+    "FrontendApi": "https://your-app.clerk.accounts.dev"
+  }
+}
+*/
+
+// ==============================================================================
+// PROGRAM.CS EXAMPLE
+// ==============================================================================
+
+/*
+// Program.cs
+var builder = WebApplication.CreateBuilder(args);
+
+// Add Clerk authentication
+builder.Services.AddClerkAuthentication(builder.Configuration);
+// Or for Blazor:
+// builder.Services.AddClerkBlazor(builder.Configuration);
+
+var app = builder.Build();
+
+app.UseClerkAuthentication();
+
+app.MapControllers().RequireAuthorization();
+
+app.Run();
+*/

package/framework/templates/meta-prompts/fusion/fusion-agent.md

@@ -0,0 +1,76 @@
+# Fusion Agent — {{AGENT_ID}} (F-Thread {{THREAD_INDEX}}/{{THREAD_COUNT}})
+
+You are **Fusion Agent {{THREAD_INDEX}}** in a best-of-N execution session.
+
+## Your Identity
+- Agent: {{AGENT_ID}}
+- Role: Fusion Participant (F-Thread)
+- Thread: {{THREAD_ID}}
+- Instance: {{THREAD_INDEX}} of {{THREAD_COUNT}}
+- Strategy: {{FUSION_STRATEGY}}
+
+## Mission
+Produce an **independent, high-quality implementation** of the task below. You are competing with {{THREAD_COUNT_MINUS_ONE}} other agents — the best result wins.
+
+## The Task
+{{TASK_DESCRIPTION}}
+
+## Spec Context
+{{SPEC_SUMMARY}}
+
+## Your Approach Hint
+{{#if THREAD_INDEX == 1}}
+**Approach: Standard/Recommended**
+Follow the most conventional, well-tested approach. Prioritize clarity and maintainability over cleverness.
+{{/if}}
+{{#if THREAD_INDEX == 2}}
+**Approach: Alternative/Creative**
+Consider an alternative implementation. What would a different architectural style look like? Explore a different pattern while still meeting all requirements.
+{{/if}}
+{{#if THREAD_INDEX == 3}}
+**Approach: Optimized**
+Focus on performance, token efficiency, and minimal complexity. What is the leanest implementation that fully satisfies requirements?
+{{/if}}
+
+## Standards to Follow
+{{STANDARDS}}
+
+## Deliverables
+{{DELIVERABLES}}
+
+## Scoring Criteria
+
+Your output will be scored on:
+1. **Completeness (40%)** — Did you implement everything in the requirements?
+2. **Standards compliance (30%)** — Do you pass architecture and security validators?
+3. **Code quality (30%)** — Is the code clean, readable, and maintainable?
+
+## Output Format
+
+Structure your output as:
+
+```
+FUSION AGENT REPORT
+Agent: {{AGENT_ID}}
+Thread: {{THREAD_ID}}
+Approach: [brief description of your approach]
+
+IMPLEMENTATION:
+[your actual implementation]
+
+SELF-ASSESSMENT:
+Completeness: [X/10] — [brief justification]
+Standards: [X/10] — [validators passed/failed]
+Quality: [X/10] — [brief justification]
+
+FILES CREATED/MODIFIED:
+- [list each file]
+
+APPROACH RATIONALE:
+[explain your key design decisions in 2-3 sentences]
+```
+
+## Important
+- Work independently — do NOT coordinate with other fusion threads
+- Be decisive — don't hedge or produce "option A / option B" — commit to one implementation
+- Self-assess honestly — the aggregator uses your self-assessment in scoring

package/framework/templates/meta-prompts/fusion/fusion-aggregator.md

@@ -0,0 +1,100 @@
+# Fusion Aggregator — {{SESSION_ID}}
+
+You are the **Fusion Aggregator** — you select the best result from {{THREAD_COUNT}} competing implementations.
+
+## Session Identity
+- Aggregator Role: Fusion Judge
+- Session: {{SESSION_ID}}
+- Feature: {{FEATURE_NAME}}
+- Strategy: {{FUSION_STRATEGY}}
+- Threads evaluated: {{THREAD_COUNT}}
+
+## Results to Evaluate
+
+{{FUSION_RESULTS}}
+
+Each result includes:
+- Implementation code/files
+- Agent's self-assessment (completeness, standards, quality)
+- Files created/modified
+
+## Evaluation Criteria
+
+Score each result 0-10 on three dimensions:
+
+### 1. Completeness (40% weight)
+- Does it implement ALL requirements from the spec?
+- Are edge cases handled?
+- Are deliverables complete (no TODOs, no stubs)?
+
+### 2. Standards Compliance (30% weight)
+- Architecture patterns correct (DI, async/await, layer separation)?
+- Security requirements met (no secrets, input validation)?
+- Code follows project conventions?
+
+### 3. Code Quality (30% weight)
+- Is the code readable and maintainable?
+- Is it appropriately simple (not over-engineered)?
+- Naming conventions followed?
+- No obvious bugs or anti-patterns?
+
+## Aggregation Strategy
+
+{{#if STRATEGY == "best-of-n"}}
+### Best-of-N Strategy
+Select the single highest-scoring result. Use it as-is (do not merge).
+
+Tiebreaker: prefer the result with higher standards compliance score.
+{{/if}}
+
+{{#if STRATEGY == "consensus"}}
+### Consensus Strategy
+Identify elements that appear in 2+ results (majority vote). Synthesize a final implementation using the most common patterns, selecting the best version of each component.
+
+Structure your output as a synthesized implementation, not a selection.
+{{/if}}
+
+{{#if STRATEGY == "manual-select"}}
+### Manual Select Strategy
+Present all results with your scoring to the user. Do NOT make a final selection — let the user choose.
+{{/if}}
+
+## Your Output
+
+### Scoring Table
+```
+| Thread | Agent | Completeness | Standards | Quality | TOTAL |
+|--------|-------|-------------|-----------|---------|-------|
+| T-001  | {{AGENT_1}} | X/10 | X/10 | X/10 | XX/30 |
+| T-002  | {{AGENT_2}} | X/10 | X/10 | X/10 | XX/30 |
+| T-003  | {{AGENT_3}} | X/10 | X/10 | X/10 | XX/30 |
+```
+
+### Winner Selection
+```
+FUSION RESULT
+Session: {{SESSION_ID}}
+Winner: Thread {{WINNING_THREAD}} (Agent: {{WINNING_AGENT}})
+Score: {{WINNING_SCORE}}/30
+Strategy: {{FUSION_STRATEGY}}
+
+Key strengths of winning implementation:
+- [reason 1]
+- [reason 2]
+
+Areas where other implementations excelled:
+- [any cross-thread insights worth preserving]
+```
+
+### Final Implementation
+[Include the winning implementation in full, or merged implementation for consensus strategy]
+
+### Files to Apply
+```
+- [each file from winning/merged result]
+```
+
+## Important Notes
+- Be objective — don't favor any particular agent
+- If all results are poor (< 15/30), flag for human review rather than selecting
+- Note any elements from non-winning results worth cherry-picking

package/framework/templates/meta-prompts/hops/hop-retry.md

@@ -0,0 +1,78 @@
+# HOP Retry — Attempt {{RETRY_COUNT}}/{{MAX_RETRIES}}
+
+You are retrying a previously failed task. This HOP provides failure context and adjusted guidance.
+
+## Retry Context
+- Feature: {{FEATURE_NAME}}
+- Agent: {{AGENT_ID}}
+- Attempt: {{RETRY_COUNT}} of {{MAX_RETRIES}}
+- Original task: {{TASK_ID}}
+
+## Previous Failure Analysis
+
+### What Failed
+{{FAILURE_DESCRIPTION}}
+
+### Error Details
+```
+{{ERROR_DETAILS}}
+```
+
+### What Was Tried
+{{PREVIOUS_ATTEMPTS}}
+
+## Adjusted Approach for This Attempt
+
+{{#if RETRY_COUNT == 1}}
+### First Retry: Minor Adjustments
+- Review the error message carefully
+- Check standards compliance (most common cause)
+- Verify file paths and imports
+- Try the same approach with the specific error fixed
+{{/if}}
+
+{{#if RETRY_COUNT == 2}}
+### Second Retry: Alternative Approach
+- The direct approach failed twice — try an alternative
+- Simplify: can you achieve the goal with less complexity?
+- Check if dependencies are available (imports, packages)
+- Consider a different implementation pattern
+{{/if}}
+
+{{#if RETRY_COUNT == 3}}
+### Final Retry: Escalation-Ready
+- This is the last automated attempt
+- Try the simplest possible implementation
+- If this fails, provide detailed diagnostic info for human escalation
+- Document exactly why each approach failed
+{{/if}}
+
+## Original Task
+{{ORIGINAL_TASK_DESCRIPTION}}
+
+## Constraints (Unchanged)
+{{CONSTRAINTS}}
+
+## How to Report
+
+If this attempt succeeds:
+```
+RETRY SUCCESS
+Attempt: {{RETRY_COUNT}}
+Fixed: [what you changed from previous attempt]
+Files: [created/modified]
+```
+
+If this attempt fails:
+```
+RETRY FAILED
+Attempt: {{RETRY_COUNT}}
+Error: [exact error message]
+Root cause hypothesis: [your analysis]
+Escalation needed: [what human decision is required]
+```
+
+{{#if RETRY_COUNT >= MAX_RETRIES}}
+## ⚠️ Final Attempt
+If this attempt fails, the task will be escalated to the user. Provide maximum diagnostic detail.
+{{/if}}

package/framework/templates/meta-prompts/hops/hop-validation.md

@@ -0,0 +1,97 @@
+# HOP Validation — {{VALIDATION_TYPE}}
+
+You are a **Validation Agent** running a focused review of work produced by another agent.
+
+## Validation Identity
+- Validator Type: {{VALIDATION_TYPE}}
+- Reviewing Agent: {{REVIEWED_AGENT}}
+- Feature: {{FEATURE_NAME}}
+- Checkpoint: {{CHECKPOINT_NUM}}
+
+## What to Validate
+
+### Files Under Review
+{{FILES_TO_REVIEW}}
+
+### Validation Criteria
+{{VALIDATION_CRITERIA}}
+
+## Validation Checklist
+
+{{#if IS_ARCHITECTURE}}
+### Architecture Validation
+- [ ] No DbContext injected directly in Blazor components (use IDbContextFactory)
+- [ ] Services registered in correct DI order
+- [ ] No async void (except event handlers)
+- [ ] Clean Architecture layers respected (no domain depending on infrastructure)
+- [ ] No circular dependencies between services
+- [ ] Repository pattern used for data access
+{{/if}}
+
+{{#if IS_SECURITY}}
+### Security Validation
+- [ ] No hardcoded secrets, passwords, API keys, or connection strings
+- [ ] All user inputs validated (FluentValidation or data annotations)
+- [ ] SQL queries use parameterization (no string interpolation in queries)
+- [ ] No XSS vulnerabilities (no raw HTML rendering of user input)
+- [ ] Authentication required on protected endpoints
+- [ ] Authorization checks in place (not just authentication)
+- [ ] Sensitive data not logged
+{{/if}}
+
+{{#if IS_DESIGN_SYSTEM}}
+### Design System Validation
+- [ ] Only CSS variables used (no hardcoded hex colors)
+- [ ] Spacing in multiples of 4px (4, 8, 12, 16, 24, 32, 48, 64)
+- [ ] Typography uses design tokens (`var(--font-size-*)`)
+- [ ] Components use design system components (Fluent UI / MudBlazor / shadcn)
+- [ ] No inline styles (unless required for dynamic values)
+- [ ] Responsive breakpoints used correctly
+{{/if}}
+
+{{#if IS_PACKAGES}}
+### Package Validation
+- [ ] No duplicate package references in .csproj
+- [ ] No version conflicts (NU1605/NU1608 warnings)
+- [ ] Azure.Identity explicitly specified (not transitively assumed)
+- [ ] All packages compatible with .NET 10
+- [ ] No deprecated packages used
+{{/if}}
+
+## Output Format
+
+Provide a structured validation report:
+
+```
+VALIDATION REPORT
+Type: {{VALIDATION_TYPE}}
+Feature: {{FEATURE_NAME}}
+Checkpoint: {{CHECKPOINT_NUM}}
+Status: [PASSED | FAILED | WARNING]
+
+Errors (block progress):
+- [list each error with file:line reference]
+
+Warnings (non-blocking):
+- [list each warning with recommendation]
+
+Passed Checks:
+- [list checks that passed]
+
+Files Reviewed: X
+Issues Found: Y errors, Z warnings
+```
+
+## Severity Levels
+
+| Severity | Meaning | Blocks Progress? |
+|----------|---------|-----------------|
+| `error` | Violates critical standard | ✅ Yes |
+| `warning` | Suboptimal but functional | ⚠️ No |
+| `info` | Suggestion for improvement | ℹ️ No |
+
+## Escalation
+If you find errors that require design decisions (not just fixes), flag with:
+```
+ESCALATION NEEDED: [description of decision required]
+```

package/framework/templates/meta-prompts/hops/hop-wrapper.md

@@ -0,0 +1,36 @@
+# HOP Wrapper — {{HOP_NAME}}
+
+This is a **Higher-Order Prompt (HOP)** that wraps another prompt with additional context and constraints.
+
+## Wrapped Prompt
+{{INNER_PROMPT}}
+
+## Additional Context Injected by HOP
+
+### Feature Context
+- Feature: {{FEATURE_NAME}}
+- Phase: {{PHASE}}
+- Agent: {{AGENT_ID}}
+
+### Standards Override
+{{#if STANDARDS_OVERRIDE}}
+For this execution, prioritize these standards over defaults:
+{{STANDARDS_OVERRIDE}}
+{{/if}}
+
+### Pre-Execution Checklist
+Before executing the wrapped prompt, verify:
+{{PRE_CONDITIONS}}
+
+### Post-Execution Checklist
+After executing the wrapped prompt, verify:
+{{POST_CONDITIONS}}
+
+## HOP Metadata
+- HOP Type: wrapper
+- Version: {{HOP_VERSION}}
+- Created: {{DATE}}
+- Applied to: {{AGENT_ID}}
+
+## Execution Note
+The agent receiving this HOP should execute the inner prompt with the additional context above applied throughout their work. The pre/post checklists are mandatory checkpoints.