@polymorphism-tech/morph-spec 4.3.1 → 4.3.3

package/stacks/blazor-azure/.morph/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/stacks/blazor-azure/.morph/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
+```

package/stacks/blazor-azure/.morph/standards/workflows/thread-management.md

@@ -0,0 +1,113 @@
+# Workflow Standard: Thread Management
+
+## Thread Types
+
+| Type | Code | Purpose | Lifecycle |
+|------|------|---------|-----------|
+| Base | B-Thread | Default implementation thread | Bounded by feature phase |
+| Parallel | P-Thread | Concurrent isolated execution | Short (1 task scope) |
+| Fusion | F-Thread | Best-of-N competing implementations | Short (1 prompt scope) |
+| Long-Running | L-Thread | Multi-session persistent work | Days/weeks |
+| Zero-Touch | Z-Thread | Fully autonomous execution | Bounded by trust level |
+
+## Thread Lifecycle
+
+```
+pending → running → completed
+                  → failed → (retry) → running
+                           → killed
+```
+
+## Creating Threads
+```bash
+# Create a base thread (default)
+morph-spec threads status morph-next-gen
+
+# Create parallel threads for feature
+morph-spec spawn-team morph-next-gen --parallel backend,frontend,infra
+
+# Create fusion thread
+morph-spec agents fuse \
+  --prompt "Implement caching strategy for UserService" \
+  --count=3 \
+  --strategy=best-of-n \
+  --feature=morph-next-gen
+```
+
+## Thread State in state.json
+```json
+{
+  "threads": {
+    "thread-abc12345": {
+      "id": "thread-abc12345",
+      "type": "parallel",
+      "agent": "dotnet-senior",
+      "feature": "user-auth",
+      "status": "running",
+      "startedAt": "2026-02-19T00:00:00Z",
+      "events": [
+        { "type": "started", "timestamp": "..." },
+        { "type": "checkpoint_passed", "timestamp": "...", "checkpointNum": 1 }
+      ],
+      "metrics": {
+        "tasksCompleted": 3,
+        "checkpointsPassed": 1,
+        "errors": 0
+      }
+    }
+  }
+}
+```
+
+## Parallel Execution Rules (P-Threads)
+
+1. **File scope isolation**: Each P-Thread has exclusive write access to its files
+2. **No cross-thread dependencies**: P-Thread tasks are self-contained
+3. **Shared read access**: All P-Threads can read spec.md, standards, contracts
+4. **Merge on completion**: Coordinator merges results after all P-Threads complete
+5. **Max concurrent**: Default 3, max 5 (configurable in llm-interaction.json)
+
+## Dependency Analysis
+```bash
+# Analyze task dependencies for parallel opportunities
+morph-spec detect-workflow morph-next-gen
+
+# Output:
+# Parallelizable tasks: T001, T002, T003 (no dependencies)
+# Sequential: T004 (depends on T001), T005 (depends on T002)
+# Execution plan:
+#   Wave 1: [T001, T002, T003] (parallel)
+#   Wave 2: [T004, T005] (parallel, after wave 1)
+#   Wave 3: [T006] (sequential)
+```
+
+## Long-Running Threads (L-Threads)
+
+### Stop Hooks
+L-Threads run periodic stop hooks every 30 minutes:
+```json
+// llm-interaction.json
+{
+  "stopHooks": {
+    "enabled": true,
+    "interval": 30,
+    "maxRetries": 5,
+    "hooks": ["validate-and-continue", "validate-checkpoints"]
+  }
+}
+```
+
+### Resume Pattern
+```bash
+# Resume L-Thread from bundle
+morph-spec bundle load morph-next-gen
+# Load resume context, continue from checkpoint
+```
+
+## Monitoring
+```bash
+morph-spec threads list morph-next-gen
+morph-spec threads analytics morph-next-gen
+morph-spec threads wait-all morph-next-gen
+morph-spec threads wait-any morph-next-gen
+```

package/stacks/blazor-azure/CLAUDE.md

@@ -1,150 +1,155 @@
-# MORPH-SPEC - Instruções para Claude Code (Consumer)
+# MORPH-SPEC - Claude Code Instructions
 
 > by Polymorphism Tech
 
-Sistema de desenvolvimento orientado por especificações. Hub de agentes especializados em multi-stack (.NET/Blazor, .NET/Next.js) com Infrastructure as Code.
+Spec-driven development system. Specialized agent hub for multi-stack projects with Infrastructure as Code.
 
 ---
 
-## REGRAS CRÍTICAS
+## CRITICAL RULES
 
-### NUNCA:
-- Pular direto para código sem especificação
-- Implementar sem aprovação do design
-- Ignorar padrões em `.morph/standards/`
-- Criar recursos Azure manualmente (use Bicep)
-- Gerar código sem contracts definidos
+### NEVER:
+- Skip to code without a specification
+- Implement without design approval
+- Ignore standards in `.morph/standards/`
+- Create infrastructure manually
+- Generate code without defined contracts
 
-### SEMPRE:
-- Seguir as 5 fases obrigatórias
-- Gerar outputs em `.morph/features/{feature}/`
-- Documentar decisões em `decisions.md`
-- Checkpoint a cada 3 tasks implementadas
-- Usar Infrastructure as Code (Bicep)
+### ALWAYS:
+- Follow the 5 mandatory phases
+- Generate outputs in `.morph/project/outputs/{feature}/`
+- Document decisions in `decisions.md`
+- Checkpoint every 3 implemented tasks
+- Use Infrastructure as Code
 
 ---
 
-## WORKFLOW (5 Fases)
+## WORKFLOW (5 Phases)
 
-| Fase | Gatilho | Ações | Output | Pausa? |
-|------|---------|-------|--------|--------|
-| **1. SETUP** | Feature request | Ler project.md, identificar stack, ativar agentes, criar pasta | proposal.md | Não |
-| **2. DESIGN** | Setup concluído | Spec + contracts + decisions + custos + Bicep | spec.md, contracts.cs, decisions.md | **Sim** |
-| **3. CLARIFY** | Design aprovado | Ambiguidades, perguntas, edge cases | Spec atualizado | Não |
-| **4. TASKS** | Clarificações resolvidas | Quebrar em tasks, ordem, checkpoints, dependências | tasks.md | **Sim** |
-| **5. IMPLEMENT** | Tasks aprovadas | Task por task, checkpoint a cada 3, recap | Código + recap.md | Não |
+| Phase | Trigger | Actions | Output | Pause? |
+|-------|---------|---------|--------|--------|
+| **1. SETUP** | Feature request | Read project context, identify stack, activate agents, create folder | proposal.md | No |
+| **2. DESIGN** | Setup done | Spec + contracts + decisions + costs | spec.md, contracts, decisions.md | **Yes** |
+| **3. CLARIFY** | Design approved | Ambiguities, questions, edge cases | Updated spec | No |
+| **4. TASKS** | Clarifications resolved | Break into tasks, ordering, checkpoints, dependencies | tasks.md | **Yes** |
+| **5. IMPLEMENT** | Tasks approved | Task by task, checkpoint every 3, recap | Code + recap.md | No |
 
 ---
 
-## ESTRUTURA DO PROJETO
+## PROJECT STRUCTURE
 
 ```
-projeto/
+project/
 ├── CLAUDE.md
 ├── .morph/
-│   ├── project.md                  # Contexto
 │   ├── config/                     # config.json, agents.json
-│   ├── standards/                  # coding, architecture, azure
-│   ├── templates/                  # Templates para outputs
-│   ├── specs/                      # Specs ATIVAS
-│   ├── features/{feature-name}/    # Features EM DESENVOLVIMENTO
-│   │   ├── proposal.md, spec.md, tasks.md
-│   │   ├── contracts.cs, decisions.md, recap.md
-│   └── archive/                    # Features CONCLUÍDAS
-├── .claude/skills/                 # Agent skills
-└── infra/main.bicep + modules/    # IaC
+│   ├── standards/                  # coding, architecture, stack-specific
+│   ├── templates/                  # Output templates
+│   ├── project/
+│   │   ├── context/                # detection-log.md, project.md
+│   │   ├── standards/              # inferred.md, overrides.md
+│   │   └── outputs/{feature}/     # Features in development
+│   │       ├── proposal.md, spec.md, tasks.md
+│   │       ├── contracts, decisions.md, recap.md
+└── .claude/commands/               # Slash commands
 ```
 
 ---
 
-## AGENTES
-
-### Core (Sempre Ativos)
-
-| Agente | Responsabilidades |
-|--------|-------------------|
-| **Standards Architect** | Padrões, nomenclatura, revisão |
-| **Azure Architect** | Infra Azure, Bicep, Container Apps |
-| **Cost Guardian** | Custos, alertas, bloqueios |
-
-### Stack, Specialist, Integration, Infra
-
-> **Ref:** Root `CLAUDE.md` para tabela completa de agentes e keywords.
-
----
-
-## LIMITES DE CUSTO
-
-| Nível | Limite | Requisito |
-|-------|--------|-----------|
-| Sem aprovação | Free tier | Nenhum |
-| Com aprovação | Até $10/mês | Confirmação |
-| Acima de $10 | Justificativa | ADR |
-
----
-
-## INFRASTRUCTURE AS CODE
-
-> NUNCA criar recursos Azure manualmente. Tudo via Bicep.
-
-| Recurso | Abordagem |
-|---------|-----------|
-| Infra estática (SQL, Storage, Container Apps) | Bicep |
-| Recursos dinâmicos (Fabric, Azure AI) | SDK .NET |
-| CI/CD | YAML + Bicep |
+## AGENTS
+
+### Tier 1 — Orchestrators (Always Active)
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Standards Architect** | Standards, naming, review, cross-cutting concerns |
+| **AI System Architect** | Agent systems, AI integrations, LLM orchestration |
+| **Thread Orchestrator** | Parallel execution, thread management, context optimization |
+
+### Tier 2 — Domain Leaders
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Tech Lead** | Architecture decisions, code quality, task breakdown |
+| **DevOps Engineer** | CI/CD, deployment pipelines, infrastructure |
+| **QA Lead** | Test strategies, validation, quality gates |
+
+### Tier 3 — Specialists (Activated by keywords)
+
+| Agent | Keywords |
+|-------|---------|
+| **Next.js Expert** | nextjs, react, frontend, app router, pages |
+| **Blazor Builder** | blazor, razor, mudblazor, fluent ui |
+| **API Designer** | api, endpoint, rest, openapi, swagger |
+| **.NET Senior** | dotnet, csharp, minimal api, ef core |
+| **EF Modeler** | entity framework, migrations, dbcontext |
+| **Azure Architect** | azure, container apps, bicep, app service |
+| **Bicep Architect** | bicep, iac, arm template, azure resources |
+| **Azure Deploy Specialist** | deploy, ci/cd, github actions, azure devops |
+| **Container Specialist** | docker, dockerfile, compose, kubernetes |
+| **Supabase Expert** | supabase, postgresql, rls, realtime, pgvector |
+| **Azure Identity** | auth, authentication, entra id, jwt, oauth |
+| **Clerk Auth** | clerk, auth0, authentication, social login |
+| **Asaas Financial** | payment, billing, subscription, asaas |
+| **Resend Email** | email, resend, smtp, notifications |
+| **Hangfire Orchestrator** | background jobs, queue, scheduling, hangfire |
+| **MS Agent Expert** | semantic kernel, microsoft agents, ai pipeline |
+| **UI/UX Designer** | design, ux, wireframe, mockup, figma |
+| **SEO Growth Hacker** | seo, performance, analytics, lighthouse |
+| **PO/PM Advisor** | product, roadmap, requirements, user stories |
+| **Prompt Engineer** | prompts, system prompts, llm, few-shot |
+| **Context Optimizer** | context window, token optimization, chunking |
+| **Vector Search Expert** | vector db, embeddings, semantic search, rag |
+| **Observability Expert** | logging, tracing, metrics, opentelemetry |
+| **Code Analyzer** | refactor, analysis, code review, complexity |
+| **Testing Specialist** | tests, coverage, tdd, bdd, vitest, jest, xunit |
+
+### Tier 4 — Validators
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Contract Compliance Validator** | Ensures implementation matches spec contracts |
 
 ---
 
 ## TEMPLATES
 
-> SEMPRE use `bin/render-template.js` para renderizar. NUNCA preencha placeholders manualmente.
+> ALWAYS use `morph-spec template render` to render. NEVER fill placeholders manually.
 
 ### Placeholders: `{{PLACEHOLDER}}`
 
-| Placeholder | Exemplo |
+| Placeholder | Example |
 |-------------|---------|
 | `{{FEATURE_NAME}}` | `scheduled-reports` |
 | `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
 | `{{FEATURE_NAME_CAMEL}}` | `scheduledReports` |
-| `{{STACK}}` | `Blazor` |
+| `{{STACK}}` | `blazor-azure` or `nextjs-supabase` |
 | `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |
 
-### CLI
-
-```bash
-node bin/render-template.js <template> <output> <vars-json>
-# --verbose: show replacements | --dry-run: preview only
-```
-
-### Available Templates
-
-**MORPH outputs:** proposal, ui-design-system, ui-mockups, ui-components, ui-flows, spec, contracts.cs, decisions, tasks, recap
-
-**Code:** service.cs, repository.cs, agent.cs, job.cs, test.cs
-
 ---
 
-## COMANDOS
+## COMMANDS
 
-| Comando | Ação |
-|---------|------|
-| `/morph-proposal {feature}` | Spec pipeline completo (fases 0-4, auto-continuação com pausas) |
-| `/morph-apply {feature}` | Implementar feature (fase 5) |
+| Command | Action |
+|---------|--------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, auto-continuation with pauses) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
 | `/morph-status` | Dashboard |
-| `/morph-archive {feature}` | Arquivar feature concluída |
-| `/morph-infra {action}` | Gerenciar infra Bicep |
-| `/morph-preflight` | Validação pre-deploy Azure |
-| `/morph-troubleshoot {error}` | Troubleshooting de erros |
+| `/morph-archive {feature}` | Archive completed feature |
+| `/morph-infra {action}` | Manage infrastructure |
+| `/morph-preflight` | Pre-deploy validation |
+| `/morph-troubleshoot {error}` | Error troubleshooting |
 
 ---
 
-## REFERÊNCIAS
+## REFERENCES
 
-- `.morph/project.md` — Contexto do projeto
-- `.morph/standards/` — coding, architecture, azure
-- `.morph/templates/` — Templates para outputs
-- `.morph/config/agents.json` — Agentes
+- `.morph/config/config.json` — Project configuration
+- `.morph/config/agents.json` — Full agent definitions
+- `.morph/standards/` — Coding, architecture, stack-specific standards
+- `.morph/project/context/` — Detection log, project context
+- `.morph/project/standards/inferred.md` — Auto-detected project standards
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech*
+*MORPH-SPEC v4.3.0 by Polymorphism Tech*