@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/docs/next-generation/THREAD-MANAGEMENT.md

@@ -1,240 +0,0 @@
-# Thread Management — MORPH-SPEC v3.0
-
-Thread management is the v3.0 system for coordinating multi-agent execution within a single feature. Threads allow parallel, sequential, and hybrid agent workflows with full lifecycle tracking.
-
----
-
-## Thread Types
-
-| Thread | Code | Purpose | Auto-kill? |
-|--------|------|---------|------------|
-| **Base Thread** | B | Single agent, sequential implementation | No |
-| **Parallel Thread** | P | Isolated domain worker in a parallel squad | No |
-| **Fusion Thread** | F | One of N agents solving the same problem | No |
-| **Long-Running** | L | Persistent background agent with stop hooks | Yes (on stop hook) |
-| **Zero-Touch** | Z | Autonomous agent with auto-approval (requires max trust) | No |
-
-### Choosing a Thread Type
-
-```
-Is this a single, sequential implementation?
-  └─ YES → B-Thread (Base)
-
-Do you want N agents working on different domains simultaneously?
-  └─ YES → P-Thread (Parallel) per domain
-
-Do you want N agents solving the SAME problem (pick best result)?
-  └─ YES → F-Thread (Fusion)
-
-Will the agent run for >30 minutes or need periodic check-ins?
-  └─ YES → L-Thread (Long-Running)
-
-Is trust level "maximum" (>95% checkpoint pass rate)?
-  └─ YES → Z-Thread (Zero-Touch) eligible
-```
-
----
-
-## Thread Lifecycle
-
-```
-pending → running → completed
-                 └→ failed
-                 └→ killed
-```
-
-Each thread stores its state in `.morph/state.json` under `threads`:
-
-```json
-{
-  "threads": {
-    "thr_abc12345": {
-      "id": "thr_abc12345",
-      "type": "parallel",
-      "feature": "user-auth",
-      "agent": "dotnet-senior",
-      "status": "running",
-      "startedAt": "2026-02-19T10:00:00Z",
-      "completedAt": null,
-      "metrics": {
-        "tasksCompleted": 3,
-        "filesCreated": 5,
-        "filesModified": 2,
-        "checkpointsPassed": 1,
-        "checkpointsFailed": 0
-      }
-    }
-  }
-}
-```
-
----
-
-## CLI Reference
-
-### List threads
-
-```bash
-morph-spec threads list
-morph-spec threads list --feature user-auth
-morph-spec threads list --status running
-morph-spec threads list --type parallel
-```
-
-### Thread status
-
-```bash
-morph-spec threads status thr_abc12345
-```
-
-### Kill a thread
-
-```bash
-morph-spec threads kill thr_abc12345
-```
-
-### Analytics
-
-```bash
-morph-spec threads analytics --feature user-auth
-```
-
-### Wait for completion
-
-```bash
-# Wait for ALL threads in a feature
-morph-spec threads wait-all user-auth --timeout 60
-
-# Wait for ANY thread to complete
-morph-spec threads wait-any user-auth --timeout 30
-```
-
----
-
-## P-Thread Isolation Rules
-
-Parallel threads (P-Threads) MUST follow strict isolation:
-
-| Rule | Description |
-|------|-------------|
-| **File ownership** | Each P-Thread writes ONLY to its assigned file set |
-| **Read-only shared** | Shared files (spec.md, contracts, standards) are READ-ONLY |
-| **No cross-writes** | Never write to another thread's files |
-| **Report on done** | Submit PARALLEL WORKER REPORT when complete |
-| **No external calls** | Don't spawn additional threads |
-
-### P-Thread Report Format
-
-```
-## PARALLEL WORKER REPORT
-
-**Thread ID:** {id}
-**Status:** completed | failed | blocked
-
-**Files Created:**
-- path/to/file1.cs
-- path/to/file2.cs
-
-**Tasks Completed:** T001, T002, T003
-
-**Blockers (if any):** None
-
-**Notes:** Any important implementation decisions
-```
-
----
-
-## L-Thread Stop Hooks
-
-Long-running threads respond to stop hooks. Configure in `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node framework/hooks/agent-teams/validate-and-continue.js {feature}"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Stop hooks run every N seconds (configurable in `zero-touch.json`):
-
-```json
-{
-  "monitoring": {
-    "stopHooks": {
-      "enabled": true,
-      "interval": 30,
-      "hooks": ["validate-and-continue", "validate-checkpoints"]
-    }
-  }
-}
-```
-
----
-
-## Thread Metrics Tracking
-
-Each feature tracks aggregate thread metrics in `state.json`:
-
-```json
-{
-  "features": {
-    "user-auth": {
-      "threadMetrics": {
-        "totalThreads": 3,
-        "completedThreads": 2,
-        "failedThreads": 0,
-        "parallelBatches": 1
-      }
-    }
-  }
-}
-```
-
-Access via:
-
-```bash
-morph-spec analytics feature user-auth
-```
-
----
-
-## Decision Tree: When to Use Threads
-
-```
-Feature complexity?
-  SIMPLE (1-5 files) → B-Thread only, no parallelization
-  MEDIUM (6-15 files) → Consider P-Threads by domain
-  HIGH (>15 files) → P-Threads mandatory for speed
-
-Multiple independent domains?
-  YES → Spawn P-Thread per domain (backend, frontend, infra)
-  NO  → Single B-Thread is fine
-
-Need best-quality output from N attempts?
-  YES → F-Thread (Fusion) with aggregation
-
-Long implementation (>30 mins estimated)?
-  YES → L-Thread with stop hooks for periodic validation
-
-Trust level maximum + fully automated pipeline?
-  YES → Z-Thread (check with: morph-spec trust status)
-```
-
----
-
-## Related
-
-- [Parallel Execution](PARALLEL-EXECUTION.md) — Squad templates and P-Thread coordination
-- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Token efficiency during thread execution
-- [Migration Guide](MIGRATION-GUIDE.md) — Upgrading state.json to v3.0 thread schema

package/docs/templates.md

@@ -1,418 +0,0 @@
-# MORPH-SPEC Templates Reference
-
-Documentação completa de todos os templates disponíveis.
-
----
-
-## Feature Templates
-
-Templates para documentação de features.
-
-### spec.md
-Template de especificação técnica.
-
-**Localização**: `.morph/templates/spec.md`
-
-**Seções**:
-- Visão Geral
-- Requisitos Funcionais
-- Requisitos Não-Funcionais
-- Arquitetura
-- Modelo de Dados
-- APIs
-- Segurança
-
-### tasks.md
-Template de breakdown de tasks.
-
-**Localização**: `.morph/templates/tasks.md`
-
-**Estrutura**:
-```markdown
-| ID | Task | Dependências | Estimativa |
-|----|------|--------------|------------|
-| T001 | Descrição | - | S/M/L |
-```
-
-### contracts.cs
-Template de contratos (interfaces, DTOs).
-
-**Localização**: `.morph/templates/contracts.cs`
-
-**Inclui**:
-- Interfaces de serviço
-- DTOs de request/response
-- Enums
-- Interfaces de repositório
-
-### decisions.md
-Template de Architecture Decision Records.
-
-**Localização**: `.morph/templates/decisions.md`
-
-**Formato ADR**:
-```markdown
-## ADR-001: Título
-
-**Status**: Proposed | Accepted | Deprecated
-
-**Context**: Descrição do contexto
-
-**Decision**: A decisão tomada
-
-**Consequences**: Impactos positivos e negativos
-```
-
-### recap.md
-Template de resumo pós-implementação.
-
-**Localização**: `.morph/templates/recap.md`
-
----
-
-## Code Templates
-
-Templates para geração de código.
-
-### component.razor
-Componente Blazor com parâmetros e lifecycle.
-
-**Localização**: `.morph/templates/component.razor`
-
-```razor
-@namespace {{Namespace}}.Components
-
-<div class="{{ComponentName | kebab-case}}">
-    @* Content *@
-</div>
-
-@code {
-    [Parameter] public string Title { get; set; }
-
-    protected override async Task OnInitializedAsync()
-    {
-        await base.OnInitializedAsync();
-    }
-}
-```
-
-### service.cs
-Serviço com injeção de dependência.
-
-**Localização**: `.morph/templates/service.cs`
-
-```csharp
-public interface I{{ServiceName}}Service
-{
-    Task<Result> ExecuteAsync(Request request, CancellationToken ct);
-}
-
-public class {{ServiceName}}Service : I{{ServiceName}}Service
-{
-    private readonly IRepository _repository;
-    private readonly ILogger<{{ServiceName}}Service> _logger;
-
-    public {{ServiceName}}Service(
-        IRepository repository,
-        ILogger<{{ServiceName}}Service> logger)
-    {
-        _repository = repository;
-        _logger = logger;
-    }
-}
-```
-
-### repository.cs
-Repositório EF Core.
-
-**Localização**: `.morph/templates/repository.cs`
-
-```csharp
-public interface I{{Entity}}Repository
-{
-    Task<{{Entity}}?> GetByIdAsync(int id, CancellationToken ct);
-    Task<IReadOnlyList<{{Entity}}>> GetAllAsync(CancellationToken ct);
-    Task AddAsync({{Entity}} entity, CancellationToken ct);
-    void Update({{Entity}} entity);
-    void Delete({{Entity}} entity);
-}
-```
-
-### test.cs
-Teste xUnit com FluentAssertions.
-
-**Localização**: `.morph/templates/test.cs`
-
-```csharp
-public class {{ServiceName}}ServiceTests
-{
-    private readonly Mock<IRepository> _repositoryMock;
-    private readonly {{ServiceName}}Service _sut;
-
-    public {{ServiceName}}ServiceTests()
-    {
-        _repositoryMock = new Mock<IRepository>();
-        _sut = new {{ServiceName}}Service(_repositoryMock.Object);
-    }
-
-    [Fact]
-    public async Task Method_Should_ReturnExpected_When_Condition()
-    {
-        // Arrange
-        // Act
-        // Assert
-    }
-}
-```
-
-### migration.cs
-Migration EF Core.
-
-**Localização**: `.morph/templates/migration.cs`
-
-### agent.cs
-Agente AI com Semantic Kernel.
-
-**Localização**: `.morph/templates/agent.cs`
-
-```csharp
-public class {{AgentName}}Agent
-{
-    private readonly Kernel _kernel;
-
-    [KernelFunction("function_name")]
-    [Description("Description of the function")]
-    public async Task<string> ExecuteAsync(
-        [Description("Parameter description")] string input)
-    {
-        // Implementation
-    }
-}
-```
-
-### job.cs
-Background job Hangfire.
-
-**Localização**: `.morph/templates/job.cs`
-
-```csharp
-public class {{JobName}}Job
-{
-    private readonly IService _service;
-    private readonly ILogger<{{JobName}}Job> _logger;
-
-    [AutomaticRetry(Attempts = 3)]
-    public async Task ExecuteAsync(JobParameters parameters)
-    {
-        _logger.LogInformation("Starting job {JobName}", nameof({{JobName}}Job));
-        // Implementation
-    }
-}
-```
-
----
-
-## IaC Templates (Bicep)
-
-Templates de Infrastructure as Code.
-
-### main.bicep
-Entry point que compõe todos os módulos.
-
-**Localização**: `.morph/templates/infra/main.bicep`
-
-**Parâmetros**:
-- `appName` - Nome da aplicação
-- `environment` - dev/staging/prod
-- `location` - Região Azure
-
-**Módulos incluídos**:
-- Container App Environment
-- Container App
-- SQL Database
-- Storage Account
-- Key Vault
-- Application Insights
-
-### container-app.bicep
-Azure Container Apps com auto-scaling.
-
-**Localização**: `.morph/templates/infra/container-app.bicep`
-
-**Features**:
-- Scale-to-zero
-- HTTP auto-scaling
-- Health probes (liveness + readiness)
-- Environment variables
-- Secrets integration
-
-### container-app-env.bicep
-Managed Environment para Container Apps.
-
-**Localização**: `.morph/templates/infra/container-app-env.bicep`
-
-**Inclui**:
-- Log Analytics workspace
-- Internal/External ingress
-
-### sql-database.bicep
-Azure SQL Database.
-
-**Localização**: `.morph/templates/infra/sql-database.bicep`
-
-**Tiers suportados**:
-- Free (32GB) - Desenvolvimento
-- Basic - Produção pequena
-- Standard - Produção
-
-### storage.bicep
-Storage Account com containers.
-
-**Localização**: `.morph/templates/infra/storage.bicep`
-
-**Containers padrão**:
-- uploads
-- reports
-- backups
-
-### key-vault.bicep
-Azure Key Vault.
-
-**Localização**: `.morph/templates/infra/key-vault.bicep`
-
-**Features**:
-- RBAC authorization
-- Soft delete
-- Purge protection (prod)
-
-### app-insights.bicep
-Application Insights para monitoring.
-
-**Localização**: `.morph/templates/infra/app-insights.bicep`
-
-### parameters.dev.json / parameters.prod.json
-Parâmetros por ambiente.
-
-**Localização**: `.morph/templates/infra/parameters.*.json`
-
----
-
-## Integration Templates
-
-Templates para integrações externas.
-
-### asaas-client.cs
-Cliente HTTP completo para Asaas.
-
-**Localização**: `.morph/templates/integrations/asaas-client.cs`
-
-**Endpoints**:
-- Customers (CRUD)
-- Payments (PIX, Boleto, Credit Card)
-- Subscriptions
-- Webhooks validation
-
-**Uso**:
-```csharp
-services.AddAsaasClient(options =>
-{
-    options.ApiKey = configuration["Asaas:ApiKey"];
-    options.Environment = AsaasEnvironment.Sandbox;
-});
-```
-
-### asaas-webhook.cs
-Controller para webhooks Asaas.
-
-**Localização**: `.morph/templates/integrations/asaas-webhook.cs`
-
-**Eventos suportados**:
-- PAYMENT_CREATED
-- PAYMENT_RECEIVED
-- PAYMENT_CONFIRMED
-- PAYMENT_OVERDUE
-- PAYMENT_REFUNDED
-- SUBSCRIPTION_*
-
-### clerk-config.cs
-Configuração de autenticação Clerk.
-
-**Localização**: `.morph/templates/integrations/clerk-config.cs`
-
-**Features**:
-- JWT validation
-- User claims
-- Middleware
-- Blazor integration
-
-### azure-identity-config.cs
-Microsoft Identity Platform.
-
-**Localização**: `.morph/templates/integrations/azure-identity-config.cs`
-
-**Modos**:
-- Web App (OpenID Connect)
-- API (JWT Bearer)
-- Blazor Server
-- Downstream APIs (Graph)
-
----
-
-## SaaS Templates
-
-Templates para aplicações SaaS.
-
-### subscription.cs
-Modelo completo de assinaturas.
-
-**Localização**: `.morph/templates/saas/subscription.cs`
-
-**Entidades**:
-- `Plan` - Planos com limites e features
-- `Subscription` - Assinatura do tenant
-- `SubscriptionPayment` - Histórico de pagamentos
-
-**Features**:
-- Ciclos mensais e anuais
-- Trial period
-- Status machine (Trial → Active → PastDue → Canceled)
-- Integração Asaas
-
-### tenant.cs
-Multi-tenancy completo.
-
-**Localização**: `.morph/templates/saas/tenant.cs`
-
-**Entidades**:
-- `Tenant` - Organização
-- `TenantUser` - Usuários do tenant
-
-**Features**:
-- Múltiplas estratégias de resolução:
-  - Subdomínio (`acme.app.com`)
-  - Header (`X-Tenant-ID`)
-  - Route (`/tenant/{slug}`)
-  - Claim (JWT)
-- EF Core query filters
-- Status management
-
----
-
-## Como Usar
-
-### 1. Copiar Template
-Os templates são automaticamente aplicados pelo MORPH durante `/morph-apply`.
-
-### 2. Substituir Placeholders
-Placeholders comuns:
-- `{{Namespace}}` - Namespace do projeto
-- `{{ServiceName}}` - Nome do serviço
-- `{{Entity}}` - Nome da entidade
-- `{{ComponentName}}` - Nome do componente
-
-### 3. Customizar
-Edite os templates em `.morph/templates/` para seu estilo.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*