@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/.morph/plans/eager-watching-bunny.md

@@ -1,105 +0,0 @@
-# Plan: Fix Statusline Not Being Installed
-
-## Context
-
-`morph-spec init` is supposed to install the global statusline to `~/.claude/` so
-it appears in every Claude Code session. Two bugs exist:
-
-1. **`update.js` never calls `installGlobalStatusline`** — running `morph-spec update`
-   leaves the statusline missing or stale, and there is no path for existing users to
-   get it without running `init` from scratch.
-2. **No success confirmation in `init.js` output** — after a successful installation the
-   "Files installed:" list never mentions `~/.claude/statusline.sh`, so users assume
-   it was skipped (especially since failures are silently swallowed by a bare `catch {}`).
-
-Root cause confirmed by: reading `update.js` (no `installGlobalStatusline` import or call)
-and `init.js` lines 462–505 (success block omits statusline entry). Tests for
-`installGlobalStatusline` in isolation pass; there is no integration test covering the
-init/update flow.
-
----
-
-## Critical Files
-
-| File | Change |
-|------|--------|
-| `src/commands/project/update.js` | Add `installGlobalStatusline` import + call |
-| `src/commands/project/init.js` | Add `✓ ~/.claude/statusline.sh` to success output |
-| `test/hooks/hooks-installer.test.js` | Already has good coverage — no change needed |
-| `test/commands/init.test.js` | Add `statusline-installation` describe suite |
-
----
-
-## Implementation Steps
-
-### 1. `update.js` — Add statusline installation
-
-**File:** `src/commands/project/update.js`
-
-**Import change** (line 27 — extend existing destructure):
-```js
-import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
-```
-
-**Call** — insert after the CLAUDE.md sync block (after line 280, before "Update Claude
-Code hooks" at line 282):
-```js
-// Sync statusline globally to ~/.claude/
-updateSpinner.text = 'Syncing statusline to ~/.claude/...';
-const HOOKS_SRC = join(__dirname, '..', '..', '..', 'framework', 'hooks', 'claude-code');
-try {
-  await installGlobalStatusline(HOOKS_SRC);
-} catch {
-  // Non-critical: global dir may not be writable in all environments
-  logger.dim('  ⚠ Could not install statusline globally (non-critical)');
-}
-```
-
-**Success output** — add line after `.claude/CLAUDE.md` entry (around line 324):
-```js
-logger.dim('  ✓ ~/.claude/statusline.sh (global statusline synced)');
-```
-
-Note: `update.js` already uses `__dirname` (defined at line 6 via `fileURLToPath`),
-so use `__dirname` instead of `import.meta.dirname` to stay consistent with the file.
-
----
-
-### 2. `init.js` — Add statusline to success output
-
-**File:** `src/commands/project/init.js`
-
-After line 505 (`logger.dim('  ✓ .claude/agents/...')`), add:
-```js
-logger.dim('  ✓ ~/.claude/statusline.sh (global statusline installed)');
-```
-
-This line is unconditional — the installation is always attempted and the message
-reflects the intent (mirrors how skills/agents are always listed even without a flag).
-
----
-
-### 3. `test/commands/init.test.js` — Add statusline integration test suite
-
-Add a new `describe('statusline-installation')` block that:
-- Calls `installGlobalStatusline` directly with a `globalClaudeDirOverride` temp dir
-  and the real `framework/hooks/claude-code` source path
-- Asserts `statusline.sh` and `statusline.py` were copied
-- Asserts `settings.json` has a `statusLine` key pointing to `statusline.sh`
-
-This mirrors the pattern used by the `rules-installation` suite.
-
----
-
-## Verification
-
-```bash
-# Run full test suite — must stay green (678+ pass, 0 fail)
-node --test --test-concurrency=1
-
-# Smoke test update path
-node bin/morph-spec.js update --skip-detection --skip-mcp 2>&1 | grep -i statusline
-
-# Manually verify ~/.claude/statusline.sh exists and settings.json has statusLine key
-node -e "const s = require('fs').readFileSync(require('os').homedir()+'/.claude/settings.json','utf8'); console.log(JSON.parse(s).statusLine)"
-```

package/.morph/plans/temporal-seeking-nebula.md

@@ -1,45 +0,0 @@
-# Plan: Remove `detect` command and fix `init` for PowerShell execution
-
-## Context
-
-`morph-spec init` is run from PowerShell (not inside Claude Code), so `detectClaudeCode()` always returns false, making step 13 a dead code branch that shows a confusing warning. `morph-spec detect` is registered but provides no additional value beyond what `init` already does with `detectProject()`. `--wizard` is referenced in messages but was never registered as a CLI option. This plan removes the dead code and makes `init` self-sufficient.
-
-## What changes
-
-### 1. Delete `src/commands/project/detect.js`
-The command is obsolete — its functionality (stack/arch detection + saving to `.morph/project/context/`) is superseded by the `detectProject()` call already inside `init` at step 11c.
-
-### 2. `bin/morph-spec.js`
-- Remove `import { detectCommand }` (line 14)
-- Remove the `.command('detect')` block (lines 131–136)
-
-### 3. `src/commands/project/init.js`
-- Remove imports: `AutoContextOrchestrator` (line 21), `detectClaudeCode` (line 22)
-- **Remove step 13 entirely** (lines 509–540) — the entire `if (!options.skipDetection && detectClaudeCode())` / `else if` / `else` block
-- Fix context README.md template (line 110): remove `Run \`morph-spec detect\`` sentence, replace with `Edit this file to describe your project context.`
-- Fix Next Steps (line 470): remove `logger.step(1, 'Run detection: morph-spec detect')`, renumber remaining steps (step 1 → "Review .morph/config/config.json", step 2 → "Open project in VS Code with Claude Code", step 3 → "Start your first feature:")
-
-### 4. `src/commands/project/update.js`
-- Remove imports: `AutoContextOrchestrator`, `detectClaudeCode` (lines ~3–4 in that file)
-- Remove the `if (!options.skipDetection && detectClaudeCode())` / `else if` / `else` block (lines 331–363)
-
-## Files to modify
-- `bin/morph-spec.js`
-- `src/commands/project/init.js`
-- `src/commands/project/update.js`
-
-## Files to delete
-- `src/commands/project/detect.js`
-
-## Files NOT changed
-- `test/integration/wizard-fallback.test.js` — tests `mapAnswersToConfig()` from `wizard-questions.js`, unrelated to detect command; still passes
-- `test/commands/init.test.js` — no references to detect/wizard/detectClaudeCode; unaffected
-- `src/core/orchestrator.js`, `src/ui/wizard-questions.js`, `src/llm/environment-detector.js` — left in place (may be used elsewhere); just remove imports/usage from init+update
-- `src/lib/detectors/index.js` + `detectProject()` — **kept** in init (step 11c); this is the static file-based stack detection that works without Claude Code
-
-## Verification
-1. `node bin/morph-spec.js --help` — `detect` command should no longer appear
-2. `node bin/morph-spec.js init --help` — no `--skip-detection` or `--wizard` references
-3. `node bin/morph-spec.js update --help` — same
-4. Run test suite: `npm test` — should still pass 678 tests (no tests reference detect/wizard in init.test.js)
-5. Manual: run `morph-spec init` from PowerShell in a test project — should complete without the "Claude Code not detected" warning

package/CLAUDE.md

@@ -1,77 +0,0 @@
-# MORPH-SPEC Runtime Instructions
-
-> by Polymorphism Tech — Spec-driven development for .NET/Blazor/Next.js/Azure
-
----
-
-## Project Context
-
-@.morph/context/README.md
-
----
-
-## Critical Rules
-
-**NEVER:**
-- Skip to code without a specification
-- Implement without design approval
-- Ignore standards in `.morph/framework/standards/`
-- Create infrastructure manually
-- Generate code without defined contracts
-
-**ALWAYS:**
-- Follow the mandatory phases
-- Generate outputs in `.morph/features/{feature}/`
-- Document decisions in `decisions.md`
-- Checkpoint every 3 implemented tasks
-- Use Infrastructure as Code
-
----
-
-## Quick Reference
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation |
-
----
-
-## State & Outputs
-
-| Path | Notes |
-|------|-------|
-| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
-| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
-| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
-| `.morph/config/config.json` | Project configuration (editable) |
-
----
-
-## Phase Sequence
-
-```
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-```
-
-Use `morph-spec status {feature}` to see current phase and pending approval gates.
-
----
-
-## Agents
-
-Tier-1 and tier-2 MORPH agents are available as native subagents in `.claude/agents/`.
-They can be invoked directly by Claude Code during multi-agent workflows.
-
----
-
-## Context Window Tip
-
-When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
-MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
-
----
-
-*MORPH-SPEC v4.5.0 by Polymorphism Tech*

package/docs/claude-alignment-report.md

@@ -1,137 +0,0 @@
-# Claude Code Native Alignment Report — Round 2
-
-> **Date:** 2026-02-22
-> **Status:** Implemented
-> **Scope:** Memory/rules layer — building on Round 1 (commit 8c806c2)
-
----
-
-## Summary
-
-Round 2 of Claude Code native alignment identifies and adopts two native patterns from the official Claude Code memory documentation that were missed in Round 1:
-
-1. **`.claude/rules/*.md`** — Path-scoped, auto-loading instruction files
-2. **`@import` in CLAUDE.md** — Auto-import external files into session context
-
----
-
-## Native Patterns Now Adopted
-
-### 1. Path-Scoped Rules (`.claude/rules/`)
-
-**What it is:** Claude Code natively supports modular instruction files placed in `.claude/rules/`. Files without `paths:` frontmatter apply globally; files with `paths:` frontmatter auto-load only when Claude is working with matching files.
-
-**What we implemented:**
-
-| File | Scope | Paths |
-|------|-------|-------|
-| `morph-workflow.md` | Always active | (none — global) |
-| `csharp-standards.md` | C# files | `**/*.cs`, `**/*.csproj` |
-| `frontend-standards.md` | Blazor/TS/CSS | `**/*.razor`, `**/*.tsx`, `**/*.ts`, `**/*.css` |
-| `testing-standards.md` | Test files | `tests/**`, `**/*.test.*`, `**/*.spec.*`, `**/*Tests.cs` |
-| `infrastructure-standards.md` | Infra files | `**/*.bicep`, `**/Dockerfile`, `**/pipelines/**` |
-
-**Source material:** Distilled from `framework/standards/` (core/coding.md, backend/dotnet/core.md, core/testing.md, frontend/blazor/pitfalls.md, infrastructure/azure/azure.md, frontend/nextjs/nextjs-patterns.md).
-
-**Why it matters:** Previously, standards were buried in `.morph/framework/standards/` — Claude had to navigate deep paths to access them, and they were never automatically loaded. Path-scoped rules ensure Claude sees the right standards *automatically* when working on the right files, without any manual intervention.
-
-**Installation:** `morph-spec init` copies `framework/rules/` → `.claude/rules/` (step 9a in `initCommand()`).
-
-### 2. `@import` in CLAUDE.md
-
-**What it is:** Claude Code supports `@path/to/file` syntax inside CLAUDE.md to auto-import external files into the session context at startup.
-
-**What we implemented:** Added `@.morph/context/README.md` to `framework/CLAUDE.md`:
-
-```markdown
-## PROJECT CONTEXT
-
-@.morph/context/README.md
-```
-
-**Why it matters:** Previously, `framework/CLAUDE.md` referenced `.morph/context/README.md` only in text (e.g., "run `morph-spec detect` to see your stack"). The file was never actually loaded. Now, every Claude Code session in a user project automatically starts with the project context (stack, architecture, technologies) pre-loaded — no manual reading required.
-
----
-
-## What Remains Over-Engineered
-
-### Partially Redundant: Session Context Injection vs Auto Memory
-
-The `UserPromptSubmit` hook injects context into every session. This overlaps with:
-- Auto memory (`~/.claude/projects/.../memory/`) — Claude Code's native persistent context layer
-- The new `@import` in CLAUDE.md — project context auto-loaded at startup
-
-**Verdict:** Keep the hook for now. It handles dynamic state (current feature, active phase) that auto memory doesn't cover. Revisit in Round 3 — the hook may be reducible to only inject feature-specific state, not static project context.
-
-### Level 3–4 Skills Rarely Used
-
-`framework/skills/level-3-technologies/` and `level-4-patterns/` contain 30+ files that are rarely invoked. They're installed to `.claude/skills/` via symlinks/copies during init.
-
-**Verdict:** Keep for now — they're passive (loaded on-demand via `/skill-name`). Consider documenting them as "on-demand only" in the `morph-workflow.md` rule. Long-term, Level 3–4 could be removed from auto-install and accessed directly from `framework/skills/` when needed.
-
-### 37 Agents in `agents.json`
-
-The agent system has 37 agents across 4 tiers. For most projects, only 5–8 agents are active at any given time.
-
-**Verdict:** Acceptable complexity. Agents drive spawn prompts and workflow orchestration — they can't be replaced by documentation. The activation-by-keyword system (Tier 3) already limits unnecessary activation.
-
----
-
-## What Was Intentionally Kept (Justified)
-
-| Feature | Justification |
-|---------|--------------|
-| `state.json` + state machine | Claude Code has no native feature-tracking equivalent; phase enforcement requires runtime state |
-| `protect-spec-files.js` hook | Dynamically checks approval gate state before allowing spec file edits — cannot be replaced by static `permissions.deny` |
-| All 12 Claude Code hooks | Context injection (dynamic), output tracking (direct JSON I/O), tool failure logging all provide value beyond native capabilities |
-| `.morph/framework/standards/` | Deep reference library for agents; the rules layer distills it but doesn't replace it |
-| `permissions.deny` for state.json + framework | Already replaced `protect-readonly-files.js` hook in Round 1 — this is the right native approach |
-| Skills hierarchy (Level 0–2) | Level 0 (meta), Level 1 (phase workflows), Level 2 (domains) are actively invoked via `/skill-name` syntax |
-
----
-
-## Roadmap: Round 3 Candidates
-
-In priority order:
-
-1. **Session context hook reduction** — Trim `UserPromptSubmit` hook to inject only feature-specific dynamic state, relying on `@import` + rules for static context. Reduces hook complexity.
-
-2. **Level 3–4 skill audit** — Measure actual usage frequency. If consistently low, move these to a "pull-on-demand" model (reference from framework, not installed to `.claude/skills/`).
-
-3. **`morph-workflow.md` rule enhancement** — Add current workflow/phase detection so the always-active rule provides live feature status context (currently requires `morph-spec status` command).
-
-4. **User-level rules layer (`~/.claude/rules/`)** — A potential personal workflow preferences file for Polymorphism Tech developers (e.g., preferred stack defaults, commit message style). Not currently used.
-
-5. **Rules auto-update on `morph-spec update`** — Currently rules are only installed during `init`. The `update` command should sync `.claude/rules/` when framework rules change.
-
----
-
-## Files Changed in Round 2
-
-| Action | File |
-|--------|------|
-| Created | `framework/rules/morph-workflow.md` |
-| Created | `framework/rules/csharp-standards.md` |
-| Created | `framework/rules/frontend-standards.md` |
-| Created | `framework/rules/testing-standards.md` |
-| Created | `framework/rules/infrastructure-standards.md` |
-| Updated | `framework/CLAUDE.md` — added `@.morph/context/README.md` import |
-| Updated | `src/commands/project/init.js` — added step 9a: rules copy to `.claude/rules/` |
-| Created | `docs/claude-alignment-report.md` (this file) |
-
----
-
-## Round 1 Reference (commit 8c806c2)
-
-Round 1 implemented 7 tasks:
-1. Fixed circular hook bug in `track-output-creation.js`
-2. Native `permissions.deny` replaced `protect-readonly-files.js`
-3. Skills installed to `.claude/skills/` (flat, with symlinks on non-Windows)
-4. Global statusline installed to `~/.claude/`
-5. `PostToolUseFailure` hook: `handle-tool-failure.js`
-6. Standards registry: `framework/standards/STANDARDS.json` (74 entries)
-7. `framework/phases.json` — canonical phase definitions
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/docs/examples/order-management/contracts.cs

@@ -1,84 +0,0 @@
-// ============================================================
-// CONTRACTS: Order Management — Level 2 (Business Logic)
-// Example of correctly filled contracts-level2.cs template
-// Feature: order-management | Date: 2026-02-23
-// ============================================================
-
-using System;
-using System.Collections.Generic;
-using System.Threading;
-using System.Threading.Tasks;
-using MediatR;
-
-// ===== AGGREGATE ROOT =====
-// Implementado em: Domain/Orders/Aggregates/Order.cs
-//
-// Invariants (do spec.md > Aggregate Blueprint):
-//   - Confirm() só é válido se Status == Draft E Items.Any()
-//   - AddItem() lança DomainException se Status != Draft
-//   - Cancel() é válido de Draft ou Confirmed → Cancelled (terminal)
-
-namespace ExampleApp.Domain.Orders.Events;
-
-// ===== DOMAIN EVENTS =====
-
-public record OrderCreatedEvent(Guid OrderId, Guid UserId) : DomainEvent;
-public record OrderConfirmedEvent(Guid OrderId, Guid UserId, decimal Total) : DomainEvent; // Total as decimal for event serialization; Money value object lives inside the Aggregate
-public record OrderCancelledEvent(Guid OrderId, string Reason) : DomainEvent;
-
-namespace ExampleApp.Application.Orders.Commands;
-
-// ===== COMMANDS (CQRS) =====
-
-public record CreateOrderCommand(Guid UserId, List<CreateOrderItemRequest> Items)
-    : IRequest<CreateOrderResult>;
-public record CreateOrderResult(Guid OrderId);
-
-public record ConfirmOrderCommand(Guid OrderId) : IRequest;
-public record CancelOrderCommand(Guid OrderId, string Reason) : IRequest;
-
-namespace ExampleApp.Application.Orders.Queries;
-
-// ===== QUERIES =====
-
-public record GetOrderQuery(Guid OrderId) : IRequest<OrderDto?>;
-
-// PagedResult<T> — defined in Shared/Common/PagedResult.cs (shared framework type)
-public record ListOrdersByUserQuery(Guid UserId, int Page = 1, int PageSize = 20)
-    : IRequest<PagedResult<OrderDto>>;
-
-namespace ExampleApp.Application.Orders;
-
-// ===== DTOs (read models — nunca expõe o Aggregate diretamente) =====
-
-public record OrderDto(
-    Guid Id,
-    Guid UserId,
-    string Status,
-    decimal Total,
-    List<OrderItemDto> Items,
-    DateTime CreatedAt,
-    DateTime? UpdatedAt
-);
-
-public record OrderItemDto(Guid ProductId, int Quantity, decimal UnitPrice, decimal Subtotal);
-
-public record CreateOrderItemRequest(Guid ProductId, int Quantity, decimal UnitPrice);
-
-namespace ExampleApp.Domain.Orders;
-
-// ===== REPOSITORY (um por Aggregate Root) =====
-
-public interface IOrderRepository
-{
-    Task<Order?> GetAsync(Guid id, CancellationToken ct = default);
-    Task<List<Order>> GetByUserAsync(Guid userId, CancellationToken ct = default);
-    Task AddAsync(Order order, CancellationToken ct = default);
-    Task UpdateAsync(Order order, CancellationToken ct = default);
-    Task<bool> ExistsAsync(Guid id, CancellationToken ct = default);
-}
-
-// ===== EXCEPTIONS =====
-
-public class OrderNotFoundException(Guid id) : DomainException($"Order '{id}' not found.");
-public class OrderInvalidStateException(string message) : DomainException(message);

package/docs/examples/order-management/proposal.md

@@ -1,24 +0,0 @@
-# Proposal: Order Management
-
-**Feature:** order-management
-**Type:** Business Logic (Level 2)
-**Stack:** .NET 10 / C# 14, Blazor Server, EF Core, Azure SQL
-
-## User Story
-
-Como usuário autenticado, quero criar e gerenciar pedidos de compra para que eu possa
-acompanhar o status dos meus pedidos e receber notificações de mudanças.
-
-## Acceptance Criteria
-
-- [ ] Usuário pode criar um pedido com 1+ itens
-- [ ] Pedido começa no status Draft
-- [ ] Pedido só pode ser Confirmado se tiver pelo menos 1 item
-- [ ] Pedido Confirmado não pode receber mais itens
-- [ ] Total do pedido é calculado automaticamente
-- [ ] Sistema notifica quando pedido é Confirmado
-
-## Out of Scope
-
-- Pagamento (feature separada)
-- Envio/logística

package/docs/examples/order-management/spec.md

@@ -1,162 +0,0 @@
-# Feature Specification: Order Management
-
-| Field | Value |
-|-------|-------|
-| **ID** | order-management |
-| **Status** | Approved |
-| **Created** | 2026-02-23 |
-| **Stack** | .NET 10 / Blazor Server / EF Core |
-| **Complexity** | Medium |
-| **Agents** | Core: All / Specialists: domain-architect, ef-modeler, event-architect |
-
----
-
-## Overview
-
-**Problem:** Usuários precisam criar e gerenciar pedidos com rastreamento de status.
-
-**Solution:** Aggregate Order com factory method, invariants de estado, e Domain Events para notificações.
-
-**Success Criteria:**
-- [ ] Order CRUD com validações de negócio
-- [ ] Status tracking com transições controladas
-- [ ] Notificação ao confirmar pedido
-
----
-
-## Requirements
-
-**Functional:**
-FR001: Criar pedido com mínimo 1 item | FR002: Confirmar pedido (Draft → Confirmed) | FR003: Cancelar pedido (Draft/Confirmed → Cancelled) | FR004: Calcular total automaticamente
-
-**Non-Functional:**
-NFR001: Performance - operações < 200ms | NFR002: Consistência - invariants garantidas em toda operação
-
----
-
-## User Stories
-
-### US001: Criar Pedido
-**As** usuário autenticado **I want** criar um pedido com itens **so that** posso comprar produtos
-
-**Acceptance Criteria:**
-1. Pedido criado com status Draft
-2. Total calculado na criação
-
-**Edge Cases:** Lista de itens vazia → erro 400
-
----
-
-## Technical Design
-
-### Stack
-| Component | Technology |
-|-----------|------------|
-| Frontend | Blazor Server |
-| Backend | .NET 10 / C# 14 |
-| Database | Azure SQL / EF Core |
-
-### Data Model
-
-#### Order
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| UserId | Guid | FK (reference by ID — cross-aggregate) |
-| Status | OrderStatus | Enum |
-| CreatedAt | datetime2 | Default: GETUTCDATE() |
-| UpdatedAt | datetime2 | Nullable |
-
-#### OrderItem (owned entity)
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| OrderId | Guid | FK |
-| ProductId | Guid | Reference by ID |
-| Quantity | int | > 0 |
-| UnitPrice | decimal(18,2) | > 0 |
-
-### Contracts
-> **Ref:** `framework/templates/code/dotnet/contracts/contracts-level2.cs`
-
----
-
-## Domain Complexity
-
-**Nível:** 2 — Business Logic
-
-**Justificativa:** Order tem estados com transições controladas (Draft → Confirmed → Cancelled),
-invariants de negócio (não confirmar sem itens, não adicionar itens a pedido confirmado),
-cálculo derivado (Total), e outros módulos precisam reagir (NotificationService ao OrderConfirmed).
-
-**Padrões Aplicados:**
-- AggregateRoot com factory method estático
-- Value Objects: Money (UnitPrice, Total)
-- Domain Events: OrderCreatedEvent, OrderConfirmedEvent, OrderCancelledEvent
-- CQRS com MediatR
-
-**Padrões Omitidos:**
-- Bounded Contexts — sistema single-domain, desnecessário
-
----
-
-## Aggregate Blueprint (Nível 2+ apenas)
-
-### Aggregate Root: Order
-
-**Invariants:**
-- Order só pode ser Confirmado se Status == Draft E tiver pelo menos 1 item
-- Order Confirmado não pode receber mais itens (AddItem lança DomainException)
-- Order Cancelado não pode ser reativado (estado terminal)
-
-**Estados e Transições:**
-```
-{Draft} → Confirm() → {Confirmed}
-{Draft} → Cancel()  → {Cancelled}
-{Confirmed} → Cancel() → {Cancelled}
-```
-
-**Domain Events:**
-- `OrderCreatedEvent` — publicado ao criar (Create factory method)
-- `OrderConfirmedEvent` — publicado ao confirmar (Confirm method)
-- `OrderCancelledEvent` — publicado ao cancelar (Cancel method)
-
-**Value Objects:**
-- `Money` — UnitPrice e Total não são decimals simples: têm validação (> 0) e operações (Add, Multiply)
-
-**Referências Cross-Aggregate (por ID):**
-- `UserId: Guid` — nunca `User User { get; }`
-- `ProductId: Guid` em OrderItem — nunca `Product Product { get; }`
-
-### Linguagem Ubíqua
-
-| Termo | Definição | Código |
-|-------|-----------|--------|
-| Order | Pedido de compra de um usuário | `Order` (AggregateRoot) |
-| Draft | Pedido criado, ainda editável | `OrderStatus.Draft` |
-| Confirmed | Pedido submetido, não editável | `OrderStatus.Confirmed` |
-| Cancelled | Pedido cancelado, estado terminal | `OrderStatus.Cancelled` |
-| Confirm | Ato de finalizar e submeter um pedido | `Order.Confirm()` |
-| OrderItem | Linha de produto dentro de um pedido | `OrderItem` (Entity owned) |
-| Total | Soma calculada de todos os itens | `Order.Total` (property calculada) |
-
----
-
-## Flows
-
-### Confirmar Pedido
-**Trigger:** Usuário clica "Confirmar Pedido"
-1. Frontend → `POST /api/orders/{id}/confirm`
-2. API → `ConfirmOrderCommand(OrderId)`
-3. Handler → `repository.GetAsync(id)` → `order.Confirm()` → `repository.UpdateAsync(order)`
-4. `OrderConfirmedEvent` publicado → NotificationService envia email
-**End State:** Order.Status = Confirmed
-
----
-
-## Definition of Done
-- [ ] Aggregate implementado com todos os invariants
-- [ ] Domain Events publicados e consumidos
-- [ ] Testes unitários do Aggregate (sem EF)
-- [ ] Testes de integração do Handler
-- [ ] API endpoint documentado