@polymorphism-tech/morph-spec 4.3.1 → 4.3.3

package/stacks/nextjs-supabase/.morph/standards/context/analytics.md

@@ -0,0 +1,96 @@
+# Context Standard: Context Analytics
+
+## Overview
+Context analytics tracks token usage, identifies optimization opportunities, and monitors session efficiency.
+
+## Metrics Collected
+
+### Session Metrics
+- Session ID, start time, feature, agent
+- Token usage at session start vs end
+- Optimization actions taken
+- Files read (and token cost per file)
+
+### Context Efficiency Score
+```
+Efficiency = 1 - (contextTokens / totalContextCapacity)
+Target: > 0.6 (60% of context available for work)
+Warning: < 0.4 (less than 40% available)
+Critical: < 0.2 (less than 20% available)
+```
+
+## Viewing Analytics
+
+### Feature Analytics
+```bash
+morph-spec analytics feature morph-next-gen
+
+# Context Usage — morph-next-gen
+# ─────────────────────────────────────
+# Sessions: 12
+# Avg session tokens: 45,200
+# Total tokens used: 542,400
+#
+# Efficiency distribution:
+# Excellent (>0.8)  ████████░░  8/12 (67%)
+# Good (0.6-0.8)    ██░░░░░░░░  2/12 (17%)
+# Poor (<0.6)       ██░░░░░░░░  2/12 (17%)
+#
+# Top token consumers:
+#   CLAUDE.md              23,000 tokens (42%)
+#   standards/coding.md     2,100 tokens (4%)
+#   spec.md                 1,800 tokens (3%)
+#
+# Optimizations recommended:
+#   → Replace CLAUDE.md with priming file (save ~22,500 tokens)
+#   → Use context bundle for resume sessions
+```
+
+### Context Dashboard
+```bash
+morph-spec analytics context
+
+# Core Four Status
+# ─────────────────────────────────────
+# Context:  [████████░░░░░░░░░░░░] 41% (82,000/200,000 tokens)
+# Model:    claude-sonnet-4-6
+# Prompt:   3,200 tokens (current turn)
+# Tools:    12 tools active
+```
+
+## Optimization Triggers
+
+| Condition | Trigger | Action |
+|-----------|---------|--------|
+| Context > 75% | Warning | Suggest bundle creation |
+| Context > 90% | Critical | Auto-suggest micro-agent split |
+| CLAUDE.md loaded | Info | Suggest priming file |
+| > 5 standards loaded | Info | Suggest standards subset |
+| Unused MCP servers | Warning | Suggest MCP hygiene |
+
+## Analytics Storage
+Events stored in JSONL format at `.morph/analytics/`:
+- `threads-log.jsonl` — thread lifecycle events
+- `context-log.jsonl` — context optimization events
+- `trust-log.jsonl` — trust/approval events
+
+Each event:
+```json
+{
+  "timestamp": "2026-02-19T00:00:00Z",
+  "type": "context_warning",
+  "feature": "morph-next-gen",
+  "data": {
+    "contextPercent": 82,
+    "tokensUsed": 164000,
+    "totalCapacity": 200000,
+    "recommendation": "CREATE_BUNDLE"
+  }
+}
+```
+
+## Pruning
+Analytics auto-prune after 90 days. Manual prune:
+```bash
+morph-spec analytics project --prune 30
+```

package/stacks/nextjs-supabase/.morph/standards/context/bundles.md

@@ -0,0 +1,110 @@
+# Context Standard: Context Bundles
+
+## Overview
+Context bundles are compressed snapshots of feature state for resuming long-running sessions without re-reading all files.
+
+## What a Bundle Contains
+
+```json
+{
+  "bundleId": "morph-next-gen-20260219-001",
+  "feature": "morph-next-gen",
+  "createdAt": "2026-02-19T00:00:00Z",
+  "tokensEstimated": 14800,
+  "compressionRatio": 0.12,
+
+  "spec": {
+    "problem": "1-2 sentence problem statement",
+    "solution": "1-2 sentence solution approach",
+    "keyRequirements": ["REQ1", "REQ2", "REQ3"],
+    "dataModel": ["Entity1 (fields)", "Entity2 (fields)"]
+  },
+
+  "decisions": [
+    { "id": "ADR-001", "summary": "Chose X over Y because Z", "fullPath": "decisions.md#adr-001" }
+  ],
+
+  "tasks": {
+    "completed": ["T001", "T002", "T003"],
+    "inProgress": "T004",
+    "pending": ["T005", "T006"],
+    "total": 10,
+    "progress": "30%"
+  },
+
+  "checkpoints": [
+    { "num": 1, "passed": true, "validatorsRun": ["architecture", "security"] }
+  ],
+
+  "agents": ["dotnet-senior", "ef-modeler"],
+
+  "resumeHints": [
+    "Currently implementing: T004 - Create UserService",
+    "Last file modified: Services/UserService.cs",
+    "Pending issue: DbContext injection pattern needs review"
+  ]
+}
+```
+
+## Creating and Using Bundles
+
+### Create a Bundle (auto or manual)
+```bash
+# Auto-created on task completion (configured in llm-interaction.json)
+# Manual creation:
+morph-spec bundle create morph-next-gen
+
+# Output:
+# ✅ Bundle created: .morph/bundles/morph-next-gen-20260219-001.json
+# Original context: ~180,000 tokens
+# Bundle: ~15,000 tokens (compression: 92%)
+```
+
+### Load Bundle for Resume
+```bash
+# Load latest bundle for feature
+morph-spec bundle load morph-next-gen
+
+# Generates resume context to stdout:
+# "You are resuming the morph-next-gen feature. Current phase: implement.
+#  Last completed: T003. Next task: T004 (Create UserService)..."
+```
+
+### List Bundles
+```bash
+morph-spec bundle list morph-next-gen
+
+# ID                              Created       Tokens  Compression
+# morph-next-gen-20260219-001     2026-02-19    14,800  92%
+# morph-next-gen-20260218-001     2026-02-18    12,400  94%
+```
+
+## Bundle vs Full Context
+
+| Scenario | Use |
+|----------|-----|
+| Starting fresh implementation | Full spec + tasks + standards |
+| Resuming mid-session | Bundle (loads in seconds) |
+| Micro-agent handoff | Bundle with agent-specific slice |
+| Cross-day resume | Bundle + load specific changed files |
+
+## Auto-Bundle Configuration
+```json
+// .morph/config/llm-interaction.json
+{
+  "contextOptimization": {
+    "bundles": {
+      "enabled": true,
+      "directory": ".morph/bundles/",
+      "createOnTaskDone": true,
+      "maxBundles": 10
+    }
+  }
+}
+```
+
+## Bundle Lifecycle
+- Created: on task completion (if auto-enabled)
+- Retained: last 10 bundles per feature
+- Invalidated: when spec.md is modified (decisions changed)
+- Deleted: when feature is archived

package/stacks/nextjs-supabase/.morph/standards/context/priming.md

@@ -0,0 +1,78 @@
+# Context Standard: Priming Files
+
+## Overview
+Priming files are ~500-token summaries replacing the full CLAUDE.md (23K tokens) for focused work sessions.
+
+## When to Use Priming Files
+- Starting a new task where full CLAUDE.md is unnecessary
+- Micro-agent sessions with narrow scope
+- Parallel workers that only need domain-specific context
+
+## Available Priming Files
+
+| File | Focus | When to Use |
+|------|-------|-------------|
+| `.morph/context/feature-prime.md` | Feature implementation | Implementing a new feature |
+| `.morph/context/bug-prime.md` | Bug fixing | Fixing a reported bug |
+| `.morph/context/refactor-prime.md` | Refactoring | Code improvement without behavior change |
+| `.morph/context/design-prime.md` | Design phase | Creating spec.md, decisions.md |
+| `.morph/context/infra-prime.md` | Infrastructure | Bicep, Docker, deployment |
+
+## Loading a Priming File
+```bash
+# Load priming file into context
+morph-spec prime feature
+
+# Output: contents of feature-prime.md to stdout
+# AI should read this instead of full CLAUDE.md
+
+# For micro-agents:
+morph-spec micro-agent create bug-fixer \
+  --prime bug \
+  --standards "core/coding.md"
+```
+
+## Creating Custom Priming Files
+
+Keep priming files under 600 tokens (≈3000 characters):
+```markdown
+# {Context Name} — Quick Reference
+
+## Stack
+- Backend: .NET 10 Blazor Server
+- DB: Azure SQL (EF Core)
+- Deploy: Azure Container Apps
+
+## Key Patterns
+- Use IDbContextFactory<> (not DbContext directly)
+- Async/await throughout
+- DI order: DbContext → Services → Controllers
+
+## Current Feature
+{Feature summary in 2-3 sentences}
+
+## Critical Files
+- spec.md: [path]
+- contracts.cs: [path]
+- tasks.json: [path]
+
+## Do Not Touch
+- [files to avoid]
+```
+
+## Token Budget Guidelines
+
+| Context Type | Tokens | Use Case |
+|--------------|--------|----------|
+| Full CLAUDE.md | ~23,000 | Full orchestrator session |
+| Priming file | ~500 | Focused task session |
+| Context bundle | ~15,000 | Feature resume (compressed) |
+| Standards subset | ~2,000/file | Domain specialist |
+| Agent prompt | ~1,000 | Micro-agent task |
+
+## Optimization Flow
+1. Start with priming file (500 tokens)
+2. Load relevant standards (2,000 tokens/file, max 3 files)
+3. Load spec summary from metadata.json (not full spec.md)
+4. Load tasks.json for current phase only
+5. Total budget: target < 8,000 tokens for routine tasks

package/stacks/nextjs-supabase/.morph/standards/core/architecture.md

@@ -0,0 +1,185 @@
+# Architecture Standards
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** architecture, clean, solid, layers, di, separation of concerns
+> **Load When:** always
+
+Architecture patterns, layer responsibilities, and structural rules.
+
+---
+
+## Clean Architecture Layers
+
+```
+┌───────────────────────────────────────┐
+│ Web (Blazor/NextJS, API)              │ ← Entry, UI, controllers
+│ ┌─────────────────────────────────┐   │
+│ │ Infrastructure (EF, External)   │   │ ← Data, services
+│ │ ┌───────────────────────────┐   │   │
+│ │ │ Application (Services)    │   │   │ ← Business logic
+│ │ │ ┌───────────────────┐     │   │   │
+│ │ │ │ Domain (Entities) │     │   │   │ ← Core
+│ │ │ └───────────────────┘     │   │   │
+│ │ └───────────────────────────┘   │   │
+│ └─────────────────────────────────┘   │
+└───────────────────────────────────────┘
+```
+
+**Dependency Rule:** Inner layers NEVER reference outer layers.
+
+---
+
+## Layer Responsibilities
+
+| Layer | Contains | References | Key Packages |
+|-------|----------|------------|--------------|
+| **Domain** | Entities, Value Objects, Enums, Interfaces | None | None (pure C#) |
+| **Application** | Services, DTOs, Validators | Domain | FluentValidation, MediatR |
+| **Infrastructure** | DbContext, Repositories, External clients | Domain, Application | EF Core, HttpClient |
+| **Web** | Pages, Components, Controllers, Program.cs | All | Blazor, Fluent UI |
+
+---
+
+## Project Structure
+
+```
+src/{App}.Domain/
+  Entities/         Order.cs, Customer.cs
+  ValueObjects/     Money.cs, Address.cs
+  Enums/            OrderStatus.cs
+  Interfaces/       IOrderRepository.cs
+
+src/{App}.Application/
+  Services/         OrderService.cs
+  DTOs/             OrderResponse.cs
+  Validators/       CreateOrderValidator.cs
+
+src/{App}.Infrastructure/
+  Data/
+    AppDbContext.cs
+    Configurations/  OrderConfiguration.cs
+  Repositories/      OrderRepository.cs
+  Services/          AsaasPaymentService.cs
+
+src/{App}.Web/
+  Components/
+    Layout/          MainLayout.razor
+    Pages/           Orders.razor
+  wwwroot/
+  Program.cs
+```
+
+---
+
+## File Organization
+
+| Rule | Description |
+|------|-------------|
+| One class per file | `OrderService.cs` for `OrderService` |
+| Folder = namespace | `Entities/Order.cs` → `MyApp.Domain.Entities` |
+| No nested classes | Except private helpers |
+| Extensions per layer | `ServiceCollectionExtensions.cs` in each project |
+
+---
+
+## SOLID Quick Reference
+
+| Principle | Rule | Signal |
+|-----------|------|--------|
+| **S** Single Responsibility | One reason to change | Class > 300 lines? Mix DB + email + validation? Split. |
+| **O** Open/Closed | Extend via new classes | `switch` on type? Use polymorphism. |
+| **L** Liskov Substitution | Subtypes substitutable | Override throws `NotSupportedException`? Violation. |
+| **I** Interface Segregation | Small interfaces | Interface with 10+ methods? Split. |
+| **D** Dependency Inversion | Depend on abstractions | Concrete class in constructor? Use interface. |
+
+---
+
+## Service Patterns
+
+| Pattern | When | Complexity |
+|---------|------|-----------|
+| Direct DbContext | Simple CRUD, < 3 entities | Low |
+| Repository | Data abstraction, testability | Medium |
+| Repository Factory | Background ops, Hangfire | Medium |
+| CQRS | Read/write models differ | Medium-High |
+| MediatR | Decouple handlers, pipelines | Medium |
+
+```csharp
+public sealed class OrderService(IOrderRepository repository, ILogger<OrderService> logger) : IOrderService
+{
+    public async Task<Result<OrderResponse>> CreateAsync(CreateOrderRequest request, CancellationToken ct = default)
+    {
+        logger.LogInformation("Creating order for {CustomerId}", request.CustomerId);
+        if (request.Items.Count == 0)
+            return Result.Failure<OrderResponse>("Order must have items");
+
+        var order = Order.Create(request.CustomerId, request.Items);
+        await repository.AddAsync(order, ct);
+        await repository.SaveChangesAsync(ct);
+        return Result.Success(order.ToResponse());
+    }
+}
+```
+
+---
+
+## DI Registration Pattern
+
+```csharp
+// Program.cs
+builder.Services
+    .AddApplication()
+    .AddInfrastructure(builder.Configuration)
+    .AddWeb();
+
+// Application/Extensions/ServiceCollectionExtensions.cs
+public static IServiceCollection AddApplication(this IServiceCollection services)
+{
+    services.AddScoped<IOrderService, OrderService>();
+    services.AddValidatorsFromAssemblyContaining<CreateOrderValidator>();
+    return services;
+}
+
+// Infrastructure/Extensions/ServiceCollectionExtensions.cs
+public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration config)
+{
+    var conn = config.GetConnectionString("Default");
+    services.AddDbContext<AppDbContext>(o => o.UseSqlServer(conn));
+    services.AddDbContextFactory<AppDbContext>(o => o.UseSqlServer(conn));
+    services.AddScoped<IOrderRepository, OrderRepository>();
+    return services;
+}
+```
+
+---
+
+## Architecture Smells
+
+| Smell | Signal | Fix |
+|-------|--------|-----|
+| Circular dependency | A refs B, B refs A | Extract shared interface to lower layer |
+| Fat controller/page | Page > 50 lines logic | Extract to service |
+| Anemic domain | Entities data-only | Move behavior into entities |
+| God class | > 500 lines, 10+ deps | Split by responsibility |
+| Service locator | `IServiceProvider.GetService<T>()` | Constructor injection |
+| Over-abstraction | Interface, one impl, never mocked | Use concrete class |
+| Under-abstraction | External service called directly | Extract interface |
+| Leaking infrastructure | `DbContext` in Web layer | Route through Application |
+
+---
+
+## Checklist
+
+- [ ] No circular references (`dotnet build` clean)
+- [ ] Domain has zero NuGet packages
+- [ ] No unused project references
+- [ ] Every interface has consumer (no "just in case")
+- [ ] External services through interfaces
+- [ ] Configuration via Options pattern
+- [ ] No hardcoded secrets in code
+- [ ] All secrets in Key Vault or user-secrets
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/.morph/standards/core/coding.md

@@ -0,0 +1,214 @@
+# C# Coding Standards
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** coding, naming, async, style, conventions, csharp
+> **Load When:** always
+
+Single source of truth for C# naming conventions, code style, and enforcement.
+Based on [Microsoft C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) and [.NET Naming Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines).
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Classes | PascalCase | `OrderService` |
+| Interfaces | `I` + PascalCase | `IOrderService` |
+| Methods | PascalCase | `GetOrderAsync` |
+| Async methods | + `Async` suffix | `ProcessPaymentAsync` |
+| Properties | PascalCase | `OrderTotal` |
+| Constants | PascalCase | `DefaultPageSize` **NOT** `DEFAULT_PAGE_SIZE` |
+| Enums / Members | PascalCase | `OrderStatus.PendingPayment` **NOT** `PENDING_PAYMENT` |
+| Namespaces | PascalCase | `MyApp.Domain` |
+| Type parameters | `T` + PascalCase | `TEntity`, `TResult` |
+| Private fields | `_camelCase` | `_orderRepository` |
+| Static private | `s_camelCase` | `s_instance` |
+| Thread-static | `t_camelCase` | `t_contextId` |
+| Locals / Params | camelCase | `orderId`, `orderTotal` |
+
+### Acronyms
+
+| Length | Rule | Example |
+|--------|------|---------|
+| 2 chars | Both uppercase | `IO`, `UI` |
+| 3+ chars | PascalCase | `Html`, `Xml`, `Http` |
+
+### DON'T
+
+| Wrong | Right |
+|-------|-------|
+| `strName`, `iCount` | `name`, `count` |
+| `MAX_RETRY_COUNT` | `MaxRetryCount` |
+| `btnSubmit`, `lblName` | `submitButton`, `nameLabel` |
+| `order_total`, `get_order` | `orderTotal`, `GetOrder` |
+| `repo`, `ctx`, `mgr`, `svc` | `repository`, `context`, `manager`, `service` |
+| `Int32 count`, `String name` | `int count`, `string name` |
+
+---
+
+## Code Style
+
+### Modern C# (10+)
+
+```csharp
+namespace MyApp.Application.Services;  // File-scoped
+
+public sealed class OrderService(IOrderRepository repository) : IOrderService
+{
+    public async Task<Result<Order>> GetByIdAsync(int id, CancellationToken ct = default)
+    {
+        var order = await repository.GetByIdAsync(id, ct);
+        return order is null
+            ? Result.Failure<Order>("Not found")
+            : Result.Success(order);
+    }
+}
+```
+
+### Style Rules
+
+| Rule | Wrong | Right |
+|------|-------|-------|
+| `var` when obvious | `OrderDto order = new OrderDto()` | `var order = new OrderDto()` |
+| Target-typed `new` | `OrderDto order = new OrderDto()` | `OrderDto order = new()` |
+| Null checks | `== null`, `!= null` | `is null`, `is not null` |
+| Collections | `new List<int> { 1, 2 }` | `List<int> items = [1, 2]` |
+| Expression body | `{ return _name; }` | `=> _name;` |
+| Nullable refs | Disabled | `<Nullable>enable</Nullable>` |
+| Pattern matching | `if (x is int)` then cast | `if (x is int value)` |
+| Default `sealed` | Unsealed classes | `sealed` unless inheritance needed |
+
+### Complexity Thresholds
+
+| Metric | Limit |
+|--------|-------|
+| Method length | < 30 lines (prefer < 20) |
+| Method parameters | ≤ 4 (use record for more) |
+| Class length | < 300 lines |
+| Nesting depth | ≤ 3 levels |
+| Cyclomatic complexity | < 10 per method |
+
+---
+
+## Async Conventions
+
+```csharp
+// ALWAYS: Async suffix + CancellationToken
+public async Task<Order> GetOrderAsync(int id, CancellationToken ct = default)
+
+// NEVER: .Result or .Wait() (deadlock risk in Blazor Server)
+var order = await service.GetOrderAsync(id, ct);  // Correct
+var order = service.GetOrderAsync(id).Result;     // DEADLOCK
+
+// NEVER: async void (except event handlers)
+public async Task HandleClickAsync() { }  // Correct
+public async void HandleClick() { }       // exceptions lost
+```
+
+---
+
+## Dependency Injection
+
+| Lifetime | When | Example |
+|----------|------|---------|
+| **Scoped** | DbContext, per-request | `AddScoped<IOrderService, OrderService>()` |
+| **Singleton** | Factories, caches | `AddSingleton<IRepositoryFactory>()` |
+| **Transient** | Lightweight, stateless | `AddTransient<IValidator<Order>>()` |
+
+```csharp
+// Constructor injection with interfaces
+public sealed class OrderService(IOrderRepository repository, ILogger<OrderService> logger)
+
+// Service Locator anti-pattern
+var service = serviceProvider.GetService<IOrderService>();
+```
+
+---
+
+## Logging
+
+```csharp
+// Structured logging with message templates
+logger.LogInformation("Processing order {OrderId} for {CustomerId}", orderId, customerId);
+
+// String interpolation defeats structured logging
+logger.LogInformation($"Processing order {orderId}");  // WRONG
+
+// Include correlation IDs
+logger.LogError(ex, "Failed to process order {OrderId}", orderId);
+```
+
+| Level | When |
+|-------|------|
+| `Trace` | Fine-grained diagnostic (dev only) |
+| `Debug` | Internal state, troubleshooting |
+| `Information` | Normal operations (start, complete, key decisions) |
+| `Warning` | Unexpected but recoverable (retry, fallback) |
+| `Error` | Failure requiring attention |
+| `Critical` | System-level failure (app crash, data corruption) |
+
+---
+
+## Error Handling
+
+```csharp
+// Result pattern for business errors
+public async Task<Result<Order>> ProcessAsync(Guid id, CancellationToken ct)
+{
+    var order = await _repository.GetByIdAsync(id, ct);
+    if (order is null) return Result.Failure<Order>("Not found");
+    if (order.Status >= OrderStatus.Completed)
+        return Result.Failure<Order>("Already completed");
+    return Result.Success(order);
+}
+
+// Exceptions for infrastructure errors only
+// NEVER: empty catch or swallowed exceptions
+try { await _client.SendAsync(request, ct); }
+catch (Exception) { }  // WRONG
+
+// ALWAYS: preserve inner exception
+catch (HttpRequestException ex)
+{
+    throw new PaymentGatewayException("Payment failed", ex);
+}
+
+// ALWAYS: specific exception types
+catch (DbUpdateConcurrencyException ex) { /* handle */ }
+catch (Exception ex) { /* log and rethrow */ throw; }
+```
+
+---
+
+## .editorconfig Template
+
+Minimal `.editorconfig` for enforcement:
+
+```ini
+[*.cs]
+# Naming
+dotnet_naming_rule.interfaces.severity = error
+dotnet_naming_rule.interfaces.symbols = interface
+dotnet_naming_rule.interfaces.style = begins_with_i
+
+# File-scoped namespaces
+csharp_style_namespace_declarations = file_scoped:warning
+
+# var preferences
+csharp_style_var_when_type_is_apparent = true:suggestion
+
+# Null checks
+dotnet_style_prefer_is_null_check_over_reference_equality_method = true:warning
+
+# Async suffix
+dotnet_naming_rule.async_methods.severity = warning
+dotnet_naming_rule.async_methods.required_suffix = Async
+```
+
+Full template: `.editorconfig` in project root.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*