@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

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

@@ -0,0 +1,131 @@
+# 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

@@ -0,0 +1,121 @@
+# 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

@@ -0,0 +1,114 @@
+# 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

@@ -0,0 +1,132 @@
+# 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

@@ -0,0 +1,112 @@
+# 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
+```