@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/.morph/framework/standards/observability/logging.md

@@ -1,131 +0,0 @@
-# Observability Standard: Logging
-
-## Overview
-Structured logging with Serilog, enrichers, sinks, and log level configuration.
-
-## Serilog Setup
-
-### Package Installation
-```xml
-<PackageReference Include="Serilog.AspNetCore" Version="8.*" />
-<PackageReference Include="Serilog.Enrichers.Environment" Version="3.*" />
-<PackageReference Include="Serilog.Enrichers.Process" Version="3.*" />
-<PackageReference Include="Serilog.Enrichers.Thread" Version="4.*" />
-<PackageReference Include="Serilog.Sinks.ApplicationInsights" Version="4.*" />
-```
-
-### Program.cs Configuration
-```csharp
-Log.Logger = new LoggerConfiguration()
-    .ReadFrom.Configuration(builder.Configuration)
-    .Enrich.FromLogContext()
-    .Enrich.WithEnvironmentName()
-    .Enrich.WithMachineName()
-    .Enrich.WithProcessId()
-    .Enrich.WithThreadId()
-    .WriteTo.Console(outputTemplate:
-        "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}")
-    .WriteTo.ApplicationInsights(
-        builder.Configuration["ApplicationInsights:ConnectionString"],
-        TelemetryConverter.Traces)
-    .CreateLogger();
-
-builder.Host.UseSerilog();
-```
-
-### appsettings.json Level Configuration
-```json
-{
-  "Serilog": {
-    "MinimumLevel": {
-      "Default": "Information",
-      "Override": {
-        "Microsoft": "Warning",
-        "Microsoft.Hosting.Lifetime": "Information",
-        "System": "Warning",
-        "Microsoft.EntityFrameworkCore": "Warning"
-      }
-    }
-  }
-}
-```
-
-## Structured Logging Patterns
-
-### Correct: Structured Properties
-```csharp
-// ✅ Use structured logging — properties are searchable in App Insights
-logger.LogInformation("User {UserId} created order {OrderId} for {Amount:C}",
-    userId, orderId, amount);
-
-// ✅ Log exceptions with context
-logger.LogError(ex, "Failed to process payment for order {OrderId} (attempt {Attempt}/{MaxAttempts})",
-    orderId, attempt, maxAttempts);
-```
-
-### Wrong: String Interpolation
-```csharp
-// ❌ Never use string interpolation — loses structured properties
-logger.LogInformation($"User {userId} created order {orderId}");
-
-// ❌ Never concatenate
-logger.LogError("Failed for order " + orderId);
-```
-
-## Log Scopes
-```csharp
-// Add correlation context for a request scope
-using (logger.BeginScope(new Dictionary<string, object>
-{
-    ["CorrelationId"] = correlationId,
-    ["UserId"] = userId,
-    ["Feature"] = "checkout"
-}))
-{
-    // All logs within this scope include the properties above
-    await ProcessCheckoutAsync(cart);
-}
-```
-
-## Log Categories — What to Log
-
-| Level | When |
-|-------|------|
-| `Trace` | Never in production (dev only) |
-| `Debug` | Detailed flow, timing — disabled in prod |
-| `Information` | Business events: order created, user signed in, job started |
-| `Warning` | Degraded state: retry, rate limit, cache miss cascade |
-| `Error` | Handled exceptions: payment failed, validation error |
-| `Critical` | System failures: database unavailable, startup failure |
-
-## Sensitive Data — NEVER Log
-- Passwords or hashed passwords
-- Credit card numbers or CVV
-- Social security numbers
-- JWT tokens or API keys
-- Full connection strings
-- PII beyond user ID (no email, phone, address)
-
-## Performance Logging Pattern
-```csharp
-public class PerformanceLoggingBehavior<TRequest, TResponse>
-    : IPipelineBehavior<TRequest, TResponse>
-{
-    private readonly ILogger<PerformanceLoggingBehavior<TRequest, TResponse>> _logger;
-
-    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken ct)
-    {
-        var sw = Stopwatch.StartNew();
-        var response = await next();
-        sw.Stop();
-
-        if (sw.ElapsedMilliseconds > 500)
-        {
-            _logger.LogWarning("Slow request {RequestName} took {ElapsedMs}ms",
-                typeof(TRequest).Name, sw.ElapsedMilliseconds);
-        }
-
-        return response;
-    }
-}
-```

package/.morph/framework/standards/observability/metrics.md

@@ -1,121 +0,0 @@
-# Observability Standard: Metrics
-
-## Overview
-Custom metrics with .NET Meters API and Azure Monitor integration.
-
-## Metrics Setup
-
-### Packages
-```xml
-<PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.*" />
-<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="0.*" />
-```
-
-### Meter Definition (per feature/service)
-```csharp
-// Define meters as static singletons
-public static class AppMetrics
-{
-    private static readonly Meter Meter = new("MyApp.Business", "1.0.0");
-
-    // Counters (monotonically increasing)
-    public static readonly Counter<long> OrdersCreated =
-        Meter.CreateCounter<long>("orders.created", "orders", "Total orders created");
-
-    public static readonly Counter<long> PaymentsFailed =
-        Meter.CreateCounter<long>("payments.failed", "failures", "Total payment failures");
-
-    // Histograms (distributions)
-    public static readonly Histogram<double> OrderProcessingTime =
-        Meter.CreateHistogram<double>("orders.processing_time", "ms", "Order processing duration");
-
-    // Gauges (current value)
-    public static readonly ObservableGauge<int> ActiveConnections =
-        Meter.CreateObservableGauge<int>("connections.active", GetActiveConnections, "connections");
-
-    private static int GetActiveConnections() => ConnectionPool.ActiveCount;
-}
-```
-
-### Recording Metrics
-```csharp
-// Counter increment
-AppMetrics.OrdersCreated.Add(1, new TagList
-{
-    { "status", "success" },
-    { "payment_method", order.PaymentMethod }
-});
-
-// Histogram measurement
-var sw = Stopwatch.StartNew();
-await ProcessOrderAsync(order);
-AppMetrics.OrderProcessingTime.Record(sw.ElapsedMilliseconds, new TagList
-{
-    { "order_type", order.Type },
-    { "region", order.Region }
-});
-```
-
-### Register with OpenTelemetry
-```csharp
-builder.Services.AddOpenTelemetry()
-    .WithMetrics(metrics =>
-    {
-        metrics
-            .AddAspNetCoreInstrumentation()
-            .AddHttpClientInstrumentation()
-            .AddRuntimeInstrumentation()
-            .AddMeter("MyApp.Business")
-            .AddAzureMonitorMetricExporter(opts =>
-            {
-                opts.ConnectionString = config["ApplicationInsights:ConnectionString"];
-            });
-    });
-```
-
-## Required Business Metrics
-
-| Metric | Type | Tags | Why |
-|--------|------|------|-----|
-| `requests.total` | Counter | route, method, status | Request volume |
-| `requests.duration` | Histogram | route, status | Latency distribution |
-| `errors.total` | Counter | type, severity | Error rate |
-| `{domain}.operations` | Counter | operation, result | Business KPIs |
-| `db.query_duration` | Histogram | table, operation | DB performance |
-| `queue.depth` | Gauge | queue_name | Backlog monitoring |
-| `cache.hit_rate` | Gauge | cache_name | Cache effectiveness |
-
-## KQL Metric Queries
-
-### Request Volume by Endpoint
-```kql
-customMetrics
-| where name == "requests.total" and timestamp > ago(1h)
-| summarize total = sum(value) by bin(timestamp, 5m), tostring(customDimensions["route"])
-| render timechart
-```
-
-### P50/P95/P99 Latency
-```kql
-customMetrics
-| where name == "requests.duration" and timestamp > ago(1h)
-| summarize
-    p50 = percentile(value, 50),
-    p95 = percentile(value, 95),
-    p99 = percentile(value, 99)
-  by bin(timestamp, 5m)
-| render timechart
-```
-
-## Naming Conventions
-
-| Pattern | Example | Description |
-|---------|---------|-------------|
-| `{domain}.{noun}.{verb}` | `orders.items.created` | Domain event count |
-| `{resource}.{metric}` | `db.query_duration` | Resource measurement |
-| `{service}.{noun}.active` | `connections.sockets.active` | Current state |
-
-Rules:
-- Lowercase with dots as separators
-- Use consistent units: `ms` for duration, `bytes` for size, `count` for dimensionless
-- Include relevant tags (avoid high-cardinality tags like userId)

package/.morph/framework/standards/observability/monitoring.md

@@ -1,114 +0,0 @@
-# Observability Standard: Monitoring
-
-## Overview
-Application Insights configuration and KQL query patterns for production monitoring.
-
-## Application Insights Setup
-
-### Connection String (not Instrumentation Key)
-```csharp
-// appsettings.json — use connection string, not key
-{
-  "ApplicationInsights": {
-    "ConnectionString": "InstrumentationKey=..." // from Key Vault
-  }
-}
-
-// Program.cs
-builder.Services.AddApplicationInsightsTelemetry(
-    builder.Configuration["ApplicationInsights:ConnectionString"]);
-```
-
-### Sampling Configuration
-```csharp
-builder.Services.Configure<TelemetryConfiguration>(config =>
-{
-    var sampler = new AdaptiveSamplingTelemetryProcessor(null!);
-    sampler.MaxTelemetryItemsPerSecond = 5; // Limit volume
-    sampler.ExcludedTypes = "Request"; // Don't sample requests
-    config.TelemetryProcessorChainBuilder.Use(_ => sampler).Build();
-});
-```
-
-### Dependency Tracking
-```csharp
-// Auto-tracked: HTTP, SQL, Azure SDK calls
-// Manual tracking for custom operations:
-using var operation = telemetryClient.StartOperation<DependencyTelemetry>("ServiceBus.Send");
-operation.Telemetry.Type = "Azure Service Bus";
-operation.Telemetry.Target = queueName;
-try
-{
-    await sender.SendMessageAsync(message);
-    operation.Telemetry.Success = true;
-}
-catch (Exception ex)
-{
-    operation.Telemetry.Success = false;
-    telemetryClient.TrackException(ex);
-    throw;
-}
-```
-
-## KQL Queries — Common Scenarios
-
-### Request Success Rate (last 24h)
-```kql
-requests
-| where timestamp > ago(24h)
-| summarize
-    total = count(),
-    failed = countif(success == false),
-    successRate = round(100.0 * countif(success == true) / count(), 2)
-| project total, failed, successRate
-```
-
-### Slow Requests (> 2s)
-```kql
-requests
-| where duration > 2000 and timestamp > ago(1h)
-| project timestamp, name, url, duration, resultCode, cloud_RoleInstance
-| order by duration desc
-| take 20
-```
-
-### Exception Summary
-```kql
-exceptions
-| where timestamp > ago(24h)
-| summarize count() by type, outerMessage
-| order by count_ desc
-| take 10
-```
-
-### Dependency Failures
-```kql
-dependencies
-| where success == false and timestamp > ago(1h)
-| project timestamp, name, type, target, duration, resultCode, data
-| order by timestamp desc
-```
-
-### User Activity Heatmap
-```kql
-customEvents
-| where timestamp > ago(7d)
-| summarize events = count() by bin(timestamp, 1h), name
-| render timechart
-```
-
-## Alerting Rules
-
-| Alert | Condition | Severity |
-|-------|-----------|----------|
-| High error rate | `requests` failure rate > 5% for 5 min | Critical |
-| Slow response | P95 latency > 3s for 10 min | Warning |
-| Exception spike | Exception count > 100/min | Critical |
-| Dependency failure | Any dependency > 10 failures/min | Warning |
-
-## Dashboard Required Sections
-- Request volume + success rate (1h/24h/7d)
-- Top slow endpoints
-- Exception breakdown by type
-- Dependency health grid
-- Active user count

package/.morph/framework/standards/observability/tracing.md

@@ -1,132 +0,0 @@
-# Observability Standard: Distributed Tracing
-
-## Overview
-OpenTelemetry distributed tracing for cross-service correlation and performance analysis.
-
-## OpenTelemetry Setup
-
-### Packages
-```xml
-<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.*" />
-<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.*" />
-<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.*" />
-<PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.*" />
-<PackageReference Include="Azure.Monitor.OpenTelemetry.AspNetCore" Version="1.*" />
-```
-
-### Program.cs Configuration
-```csharp
-builder.Services.AddOpenTelemetry()
-    .WithTracing(tracing =>
-    {
-        tracing
-            .AddAspNetCoreInstrumentation(opts =>
-            {
-                opts.RecordException = true;
-                opts.Filter = ctx => !ctx.Request.Path.StartsWithSegments("/health");
-            })
-            .AddHttpClientInstrumentation()
-            .AddSqlClientInstrumentation(opts => opts.SetDbStatementForText = true)
-            .AddSource(ActivitySource.Name) // Custom activities
-            .AddAzureMonitorTraceExporter(opts =>
-            {
-                opts.ConnectionString = config["ApplicationInsights:ConnectionString"];
-            });
-    });
-
-// Custom ActivitySource for domain operations
-public static class Telemetry
-{
-    public static readonly ActivitySource ActivitySource = new("MyApp", "1.0.0");
-}
-```
-
-## Custom Span Creation
-
-### Service Method Tracing
-```csharp
-public async Task<Order> ProcessOrderAsync(CreateOrderCommand command)
-{
-    using var activity = Telemetry.ActivitySource.StartActivity("ProcessOrder");
-    activity?.SetTag("order.userId", command.UserId.ToString());
-    activity?.SetTag("order.itemCount", command.Items.Count.ToString());
-
-    try
-    {
-        var order = await _repository.CreateAsync(command);
-        activity?.SetTag("order.id", order.Id.ToString());
-        activity?.SetStatus(ActivityStatusCode.Ok);
-        return order;
-    }
-    catch (Exception ex)
-    {
-        activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
-        activity?.RecordException(ex);
-        throw;
-    }
-}
-```
-
-### Baggage (Cross-Service Context)
-```csharp
-// Set correlation ID in baggage (propagates across HTTP calls)
-Activity.Current?.SetBaggage("correlationId", correlationId);
-Activity.Current?.SetBaggage("userId", userId.ToString());
-
-// Read baggage downstream
-var correlationId = Activity.Current?.GetBaggageItem("correlationId");
-```
-
-## Trace Context Propagation
-
-### HTTP Client (auto-propagated)
-```csharp
-// HttpClient automatically propagates W3C trace context
-// Configure in DI:
-builder.Services.AddHttpClient("ExternalApi")
-    .AddOpenTelemetryInstrumentation();
-```
-
-### Service Bus (manual propagation)
-```csharp
-// Sender: inject trace context into message properties
-var message = new ServiceBusMessage(body);
-var activity = Activity.Current;
-if (activity != null)
-{
-    message.ApplicationProperties["traceparent"] = activity.Id;
-    message.ApplicationProperties["tracestate"] = activity.TraceStateString;
-}
-
-// Receiver: restore trace context from message
-if (message.ApplicationProperties.TryGetValue("traceparent", out var traceparent))
-{
-    using var linkedActivity = Telemetry.ActivitySource.StartActivity(
-        "ProcessMessage",
-        ActivityKind.Consumer,
-        parentId: traceparent.ToString()!);
-    await ProcessAsync(message);
-}
-```
-
-## Trace Sampling Strategy
-
-| Environment | Strategy | Rate |
-|-------------|----------|------|
-| Development | Always | 100% |
-| Staging | Adaptive | 10% + errors |
-| Production | Adaptive | 5% + errors |
-
-```csharp
-// Production adaptive sampling (errors always sampled)
-.AddAspNetCoreInstrumentation(opts =>
-{
-    opts.Enrich = (activity, eventName, obj) =>
-    {
-        if (obj is HttpResponse response && response.StatusCode >= 400)
-        {
-            activity.SetSampled(true); // Always sample errors
-        }
-    };
-})
-```

package/.morph/framework/standards/workflows/parallel-execution.md

@@ -1,112 +0,0 @@
-# Workflow Standard: Parallel Execution
-
-## When to Use Parallel Execution
-
-| Condition | Decision |
-|-----------|----------|
-| 5+ independent tasks | Use P-Threads |
-| Multi-domain (backend + frontend + infra) | Use P-Threads with squad templates |
-| 15+ files to create | Use P-Threads |
-| Tasks have zero dependency overlap | Use P-Threads |
-| Tasks share file scope | Do NOT parallelize |
-| Sequential data flow required | Do NOT parallelize |
-
-## Parallelization Planning
-
-### Step 1: Dependency Analysis
-```bash
-morph-spec detect-workflow user-auth
-
-# Identifies: parallelizable tasks, sequential chains, waves
-```
-
-### Step 2: File Scope Assignment
-Assign exclusive file ownership to each parallel worker:
-
-```
-Worker A (Backend):    Entities/, Services/, Controllers/, DTOs/
-Worker B (Frontend):   Pages/, Components/, CSS/
-Worker C (Infra):      infra/bicep/, .github/workflows/
-```
-
-No overlap allowed. If overlap is unavoidable, make it sequential.
-
-### Step 3: Choose Squad Template
-```bash
-morph-spec squad-template use full-stack --feature=user-auth
-
-# Creates execution plan based on full-stack.json template:
-# - dotnet-senior (backend lead)
-# - blazor-builder (frontend lead)
-# - bicep-architect (infra lead)
-# - thread-orchestrator (coordinator)
-```
-
-## Execution Flow
-
-```
-Orchestrator
-    │
-    ├── spawn parallel: Worker A (files: Entities/, Services/)
-    ├── spawn parallel: Worker B (files: Pages/, Components/)
-    └── spawn parallel: Worker C (files: infra/)
-    │
-    │   [Workers execute concurrently — no interaction]
-    │
-    ├── wait-all (poll or explicit sync)
-    │
-    ├── merge results (check for conflicts)
-    ├── run integration validation
-    └── report consolidated output
-```
-
-## Conflict Resolution
-
-### File Conflicts (two workers wrote same file)
-```bash
-# This should NOT happen if scopes are properly defined
-# If it does:
-morph-spec agents review aggregate user-auth \
-  --agents=dotnet-senior,blazor-builder \
-  --strategy=best-of-n
-```
-
-### Interface Mismatches (A expects contract B didn't fulfill)
-- Document the mismatch in the coordinator report
-- Fix in post-merge sequential step
-- Update contracts.cs to reflect actual implementation
-
-## Fusion vs Parallel
-
-| Aspect | Parallel (P-Thread) | Fusion (F-Thread) |
-|--------|--------------------|--------------------|
-| Goal | Divide scope | Compete on same scope |
-| Output | Different files | Same files, best one wins |
-| Workers collaborate? | No | No |
-| Merge | Combine all files | Select best implementation |
-| Use case | Large features | Design decisions, quality optimization |
-
-## Configuration
-```json
-// llm-interaction.json
-{
-  "parallelExecution": {
-    "enabled": true,
-    "maxConcurrent": 3,
-    "defaultStrategy": "best-of-n"
-  }
-}
-```
-
-## Squad Templates
-
-Pre-defined squad configurations in `framework/squad-templates/`:
-- `full-stack.json` — Backend + Frontend + Infra (6 agents)
-- `backend-only.json` — Backend specialists only (4 agents)
-- `frontend-only.json` — Frontend specialists only (3 agents)
-
-```bash
-morph-spec squad-template list
-morph-spec squad-template show full-stack
-morph-spec squad-template use full-stack --feature=user-auth
-```