@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/docs/COMMAND-FLOWS.md

@@ -0,0 +1,368 @@
+# morph-spec — Command Flow Diagrams
+
+> Each diagram shows the sequence of CLI calls and internal function calls for each slash command.
+
+---
+
+## 1. /morph-proposal
+
+```mermaid
+flowchart TD
+    START(["/morph-proposal FEATURE"]) --> A
+
+    A["state get FEATURE"] --> B{"Exists?"}
+    B -->|yes| C["Identify current phase\nResume from where it stopped"]
+    B -->|no| D["Start Phase 0 from scratch"]
+    C --> D
+
+    subgraph P0 ["PHASE 0 — PROPOSAL"]
+        D --> E["detect-agents INPUT"]
+        E --> E1["loadAgentsConfig() ← agents.json"]
+        E1 --> E2["detectAgents() — keyword matching"]
+        E2 --> E3["analyzeRequestComplexity()"]
+        E3 --> E4["getStandardsListForAgent()\nloadStandardsForAgent()"]
+        E4 --> F["Render proposal.md via template"]
+        F --> G1["state set FEATURE status draft"]
+        G1 --> G2["state set FEATURE phase proposal"]
+        G2 --> G3["state mark-output FEATURE proposal"]
+        G3 --> G4["state add-agent FEATURE agent-id × N"]
+        G4 --> PAUSE0(["⏸ GATE — approve proposal"])
+    end
+
+    PAUSE0 -->|approved| H
+
+    subgraph P1 ["PHASE 1 — SETUP (auto, no gate)"]
+        H["Read .morph/context/"] --> I["Confirm detected stack"]
+        I --> J["List active agents"]
+        J --> J2["state set FEATURE phase setup"]
+    end
+
+    J2 --> UICHECK{"uiux-designer\nin activeAgents?"}
+
+    subgraph P15 ["PHASE 1.5 — UI/UX (conditional)"]
+        UICHECK -->|yes| L["Generate wireframes + design system\n(.claude/skills/phase-uiux/SKILL.md)"]
+        L --> PAUSEUI(["⏸ GATE — approve UI/UX"])
+    end
+
+    UICHECK -->|no| M
+    PAUSEUI -->|approved| M
+
+    subgraph P2 ["PHASE 2 — DESIGN"]
+        M["Generate spec.md\n(.claude/skills/phase-design/SKILL.md)"] --> N["Generate contracts.cs"]
+        N --> O["Generate decisions.md with ADRs"]
+        O --> P["Estimate costs per resource"]
+        P --> Q1["state mark-output FEATURE spec"]
+        Q1 --> Q2["state mark-output FEATURE contracts"]
+        Q2 --> Q3["state mark-output FEATURE decisions"]
+        Q3 --> PAUSE2(["⏸ GATE — approve design"])
+    end
+
+    PAUSE2 -->|approved| R
+
+    subgraph P3 ["PHASE 3 — CLARIFY"]
+        R["Identify ambiguities in spec\n(.claude/skills/phase-clarify/SKILL.md)"] --> S["Generate 3-7 questions"]
+        S --> WAIT(["⏳ Waiting for user answers"])
+        WAIT -->|answered| T["Update spec with clarifications\nand edge cases"]
+        T --> T2["state set FEATURE phase clarify"]
+    end
+
+    T2 --> U
+
+    subgraph P4 ["PHASE 4 — TASKS"]
+        U["Break spec into tasks T001-TXXX\n(.claude/skills/phase-tasks/SKILL.md)"] --> V["Define order and dependencies"]
+        V --> W["Checkpoints every 3 tasks"]
+        W --> X1["state mark-output FEATURE tasks"]
+        X1 --> X2["state set FEATURE tasks.total N"]
+        X2 --> PAUSE4(["⏸ GATE — approve tasks"])
+    end
+
+    PAUSE4 -->|approved| END(["✅ Planning complete\nRun /morph-apply FEATURE"])
+```
+
+---
+
+## 2. /morph-apply
+
+```mermaid
+flowchart TD
+    START(["/morph-apply FEATURE"]) --> A
+
+    A["state get FEATURE"] --> B{"All phases\ncomplete?"}
+    B -->|no| ERR(["❌ ERROR — phase X not complete\nRun /morph-proposal FEATURE"])
+    B -->|yes| C
+
+    subgraph PREP ["INITIALIZATION"]
+        C["Read 1-design/spec.md + 3-tasks/tasks.md + 1-design/contracts.cs"] --> D
+        D["Read framework/standards/\n.morph/context/"] --> E1
+        E1["state set FEATURE phase implement"] --> E2
+        E2["state set FEATURE status in_progress"] --> E3
+        E3["state set FEATURE tasks.total N"]
+    end
+
+    E3 --> LOOP_START
+
+    subgraph LOOP ["LOOP — For each task in order"]
+        LOOP_START["Select next task"] --> F
+        F["task start FEATURE task-id"] --> F1
+        F1["spawn task-manager.cjs start"] --> G
+        G["Implement code\nfollowing contracts.cs + standards"] --> H
+        H["task done FEATURE task-id"] --> H1
+        H1["spawn task-manager.cjs done"] --> VAL_START
+
+        subgraph VAL ["Automatic validators (hooks)"]
+            VAL_START["security-expert\nSQL injection, XSS, hardcoded secrets"] --> V2
+            V2["architecture-expert\nIDbContextFactory, async/await, DI order"] --> V3
+            V3["packages-validator\nNuGet conflicts, vulnerabilities"] --> V4
+            V4["blazor-concurrency-validator\nLifecycle, thread safety"]
+        end
+
+        V4 --> VRESULT{"Validation\npassed?"}
+        VRESULT -->|no| FIX["Fix violations\nDO NOT use --skip-validation"] --> H
+        VRESULT -->|yes| CHK{"task_count\nmultiple of 3?"}
+        CHK -->|yes| CP["state checkpoint FEATURE\nstate list"]
+        CHK -->|no| NEXT
+        CP --> NEXT{"Next task\nexists?"}
+        NEXT -->|yes| LOOP_START
+    end
+
+    NEXT -->|no| FIN1
+
+    subgraph FIN ["FINALIZATION"]
+        FIN1["generate recap FEATURE"] --> FIN2
+        FIN2["extractFeatureMetadata()\nWrites 4-implement/recap.md"] --> FIN3
+        FIN3["state set FEATURE status done"] --> FIN4
+        FIN4["state mark-output FEATURE recap"] --> FIN5
+        FIN5["phase advance FEATURE"]
+    end
+
+    FIN5 --> END(["✅ Feature complete\nRun /morph-archive FEATURE"])
+```
+
+---
+
+## 3. /morph-status
+
+```mermaid
+flowchart TD
+    START(["/morph-status"]) --> A
+
+    A["state list"] --> B
+    B["StateManager.getSummary()"] --> C
+    C["StateManager.listFeatures()"] --> D
+    D["Read .morph/state.json"] --> DASH
+
+    DASH["Display dashboard\nfeatures | phases | tasks X/Y | agents | costs"] --> EXTRA
+
+    EXTRA{"Specific feature\nrequested?"} -->|yes| G
+    EXTRA -->|no| CHECK
+
+    G["state get FEATURE"] --> G1["StateManager.getFeature()"] --> CHECK
+
+    subgraph CHECK_BLOCK ["Additional checks"]
+        CHECK["Check .morph/config/config.json"] --> CHECK2
+        CHECK2["Check .morph/framework/standards/ present"] --> CHECK3
+        CHECK3["Check .morph/archive/\ncompleted features"]
+    end
+
+    CHECK3 --> SUGEST["Suggest next actions\n/morph-proposal | /morph-apply | /morph-archive"]
+
+    SUGEST --> END(["✅ Dashboard displayed"])
+```
+
+---
+
+## 4. /morph-archive
+
+```mermaid
+flowchart TD
+    START(["/morph-archive FEATURE"]) --> A
+
+    A["Read .morph/features/FEATURE/3-tasks/tasks.md"] --> B
+    B{"All tasks\ncomplete?"} -->|no| ERR(["❌ Feature not ready\nFinish pending tasks first"])
+    B -->|yes| C
+
+    C(["Confirm with user\nthat archiving is OK"]) --> D
+
+    subgraph RECAP ["RECAP"]
+        D["Update 4-implement/recap.md"] --> D1
+        D1["Fill in final metrics\n(tasks, time, actual vs estimated cost)"] --> D2
+        D2["Document lessons learned"]
+    end
+
+    D2 --> E{"Does spec define permanent\nsystem behavior?"}
+
+    E -->|yes| F["Extract spec → .morph/specs/DOMAIN/\nBecomes the 'current truth' of the system"]
+    F --> G
+    E -->|no| G
+
+    subgraph MOVE ["MOVE"]
+        G["Move full directory:\n.morph/features/FEATURE/\n→ .morph/archive/FEATURE/"]
+    end
+
+    G --> H
+
+    subgraph METRICS ["METRICS UPDATE"]
+        H["Increment completed features counter"] --> I
+        I["Update total accumulated cost"] --> J
+        J["Update total time spent"]
+    end
+
+    J --> END(["✅ Feature archived at\n.morph/archive/FEATURE/"])
+```
+
+---
+
+## 5. /morph-infra
+
+```mermaid
+flowchart TD
+    START(["/morph-infra ACTION"]) --> ROUTE
+
+    ROUTE{"Action?"}
+
+    ROUTE -->|init| INIT_1
+    ROUTE -->|validate| VAL_1
+    ROUTE -->|plan| PLAN_1
+    ROUTE -->|deploy| DEP_1
+    ROUTE -->|destroy| DES_1
+
+    subgraph INIT ["INIT — Initialize IaC"]
+        INIT_1["Copy templates from\n.morph/framework/templates/infrastructure/"] --> INIT_2
+        INIT_2["Create infra/ structure\nmain.bicep\nparameters.dev.json, parameters.prod.json\nmodules/*.bicep"] --> INIT_3
+        INIT_3["Replace placeholders\nAPP_NAME, SUBSCRIPTION_ID\nRESOURCE_GROUP"] --> INIT_4
+        INIT_4["Document structure in decisions.md"]
+        INIT_4 --> INIT_END(["✅ Done — run /morph-infra validate"])
+    end
+
+    subgraph VALIDATE ["VALIDATE — Validate Templates"]
+        VAL_1["az bicep build --file infra/main.bicep"] --> VAL_2
+        VAL_2["Check required parameters"] --> VAL_3{"No errors?"}
+        VAL_3 -->|yes| VAL_OK(["✅ Templates valid"])
+        VAL_3 -->|no| VAL_ERR(["❌ Report syntax errors"])
+    end
+
+    subgraph PLAN ["PLAN — Preview Changes"]
+        PLAN_1["az account show"] --> PLAN_2{"Authenticated\nto Azure?"}
+        PLAN_2 -->|no| PLAN_ERR(["❌ Run az login"])
+        PLAN_2 -->|yes| PLAN_3["az deployment group what-if\n--template-file infra/main.bicep\n--parameters parameters.ENV.json"]
+        PLAN_3 --> PLAN_4["Display summary:\nCREATE / MODIFY / DELETE\n+ estimated costs"]
+        PLAN_4 --> PLAN_PAUSE(["⏸ GATE — wait for approval\nbefore running deploy"])
+    end
+
+    subgraph DEPLOY ["DEPLOY — Execute Deploy"]
+        DEP_1["Verify plan approval"] --> DEP_2
+        DEP_2["az group create --name rg-APP-ENV\n--location brazilsouth"] --> DEP_3
+        DEP_3["az deployment group create\n--template-file infra/main.bicep\n--parameters parameters.ENV.json"] --> DEP_4
+        DEP_4["Capture outputs:\nContainer App URL\nSQL Connection String\nKey Vault URI"] --> DEP_5
+        DEP_5["Update documentation\nwith deploy info"]
+        DEP_5 --> DEP_END(["✅ Deploy complete"])
+    end
+
+    subgraph DESTROY ["DESTROY — Remove Resources"]
+        DES_1(["⚠️ WARNING: irreversible action"]) --> DES_2
+        DES_2["List all resources\nthat will be deleted"] --> DES_3
+        DES_3(["⏸ GATE — require explicit confirmation\n'yes, delete'"]) --> DES_4
+        DES_4["az group delete --name rg-APP-ENV\n--yes --no-wait"]
+        DES_4 --> DES_END(["✅ Resources removed"])
+    end
+```
+
+---
+
+## 6. /morph-preflight
+
+```mermaid
+flowchart TD
+    START(["/morph-preflight azure"]) --> C1
+
+    subgraph CHECKS ["7 SEQUENTIAL CHECKS"]
+        C1["Check 1 — Package Conflicts\ndotnet restore --verbosity normal\ngrep NU1605 NU1608"] --> R1{"OK?"}
+        R1 -->|✅| C2
+        R1 -->|❌| FIX1["Fix: declare Azure.Identity\nwith explicit version in .csproj"] --> C2
+
+        C2["Check 2 — EF Core Migrations\ndotnet ef migrations has-pending-model-changes\n--project src/Infrastructure --startup-project src/Web"] --> R2{"OK?"}
+        R2 -->|✅| C3
+        R2 -->|❌| FIX2["Fix: dotnet ef migrations add NAME"] --> C3
+
+        C3["Check 3 — Dockerfile\ndocker build --check .\nVerify multi-stage, EXPOSE, ENTRYPOINT"] --> R3{"Applicable\nand OK?"}
+        R3 -->|✅ or N/A| C4
+        R3 -->|❌| FIX3["Fix: correct Dockerfile"] --> C4
+
+        C4["Check 4 — Blazor .NET 10 Assets\ngrep RequiresAspNetWebAssets *.csproj"] --> R4{"OK?"}
+        R4 -->|✅ or N/A| C5
+        R4 -->|❌| FIX4["Fix: add RequiresAspNetWebAssets=true\nto .csproj"] --> C5
+
+        C5["Check 5 — Bicep Syntax\naz bicep build --file infra/main.bicep --stdout"] --> R5{"OK?"}
+        R5 -->|✅| C6
+        R5 -->|❌| FIX5["Fix: correct Bicep syntax errors"] --> C6
+
+        C6["Check 6 — Key Vault Config\ngrep KeyVaultUri appsettings*.json\ngrep IsDevelopment Program.cs"] --> R6{"OK?"}
+        R6 -->|✅| C7
+        R6 -->|❌| FIX6["Fix: add KeyVaultUri\nDO NOT gate on IsDevelopment"] --> C7
+
+        C7["Check 7 — Connection Strings\ngrep 'Password= Pwd= Secret='\nappsettings*.json excluding Development"] --> R7{"OK?"}
+        R7 -->|✅| SUM
+        R7 -->|⚠️| WARN["Warning: move secrets to Key Vault"] --> SUM
+    end
+
+    SUM["Display summary\nN passed / N failed / N warnings"] --> RESULT
+
+    RESULT{"Any\nfailures?"} -->|yes| BLOCK(["❌ BLOCKED\nDo not deploy until resolved!"])
+    RESULT -->|no| PASS(["✅ Ready to deploy to Azure"])
+```
+
+---
+
+## 7. /morph-troubleshoot
+
+```mermaid
+flowchart TD
+    START(["/morph-troubleshoot KEYWORDS"]) --> A
+
+    A["troubleshootCommand(keywords, options)"] --> LISTCAT
+
+    LISTCAT{"--list-categories?"} -->|yes| CATS["getCategories()\nList: blazor, efcore, azure, auth, deploy"]
+    CATS --> END_CATS(["✅ Categories displayed"])
+
+    LISTCAT -->|no| L1_START
+
+    subgraph L1 ["Level 1 — Known Issues Index (Primary)"]
+        L1_START["searchIndex(searchTerms, options)"] --> L1A
+        L1A["Search JSON database\nof known issues"] --> L1B{"Filter\n--category?"}
+        L1B -->|yes| L1C["Filter by category"]
+        L1B -->|no| L1D["Match all keywords"]
+        L1C --> L1RESULT
+        L1D --> L1RESULT["Return matches with score"]
+    end
+
+    L1RESULT --> CHECK1{"Enough\nresults?"}
+    CHECK1 -->|yes| FORMAT
+
+    subgraph L2 ["Level 2 — Grep Standards (Automatic fallback)"]
+        CHECK1 -->|no| L2_START["searchGrep(searchTerms, options)"]
+        L2_START --> L2A["grep framework/standards/*.md"]
+        L2A --> L2B["grep .morph/framework/standards/*.md"]
+        L2B --> L2C["Deduplicate against Level 1 results"]
+        L2C --> L2D["Merge and limit to 10 results"]
+    end
+
+    L2D --> CHECK2{"Enough\nresults?"}
+    CHECK2 -->|yes| FORMAT
+
+    subgraph L3 ["Level 3 — Web Search (If needed)"]
+        CHECK2 -->|no| L3_START["WebSearch — external sources"]
+        L3_START --> L3A["site:github.com/dotnet/aspnetcore ERROR\nsite:github.com/dotnet/efcore ERROR"]
+        L3_START --> L3B["site:stackoverflow.com blazor ERROR\nsite:stackoverflow.com azure ERROR"]
+        L3_START --> L3C["site:learn.microsoft.com ERROR\nsite:learn.microsoft.com/azure ERROR"]
+        L3A & L3B & L3C --> L3MERGE["Consolidate relevant links"]
+    end
+
+    L3MERGE --> FORMAT
+
+    subgraph FMT ["Output Formatting"]
+        FORMAT["formatResult(result, verbose)\nRoot cause + Solution + Fix code"] --> FSUM
+        FSUM["formatSummary(stats)\nTotal found per level (L1/L2/L3)"]
+    end
+
+    FSUM --> END(["✅ Results displayed\nin standard format"])
+```

package/docs/QUICKSTART.md

@@ -0,0 +1,212 @@
+# morph-spec Quick Start
+
+## Install
+
+```bash
+npm install -g @polymorphism-tech/morph-spec
+```
+
+Or use `npx` without a global install:
+
+```bash
+npx @polymorphism-tech/morph-spec init
+```
+
+> **Windows / nvm-windows:** Global installs may not appear on PATH. Use `npx` or add the npm prefix to PATH manually: `npm config get prefix`, then add `{prefix}` to your PATH.
+
+---
+
+## Initialize a project
+
+Navigate to your project root and run:
+
+```bash
+morph-spec init
+```
+
+`init` does the following:
+- Auto-detects your stack (Blazor, Next.js, Node.js, monorepo)
+- Creates `.morph/` with framework files, standards, and templates
+- Creates `.morph/context/` with inferred project context
+- Installs `.claude/skills/`, `.claude/agents/`, `.claude/rules/`
+- Writes `.claude/settings.local.json` with 11 Claude Code hooks
+- Copies `CLAUDE.md` with runtime instructions
+
+Verify the installation:
+
+```bash
+morph-spec doctor
+```
+
+---
+
+## Your first feature
+
+Open your project in Claude Code and run:
+
+```
+/morph-proposal my-feature
+```
+
+Replace `my-feature` with a short kebab-case name for your feature (e.g., `user-notifications`, `payment-flow`).
+
+The proposal pipeline runs phases 0–4 with three approval gates:
+
+### Phase 0 — Proposal
+
+Claude analyzes your request, detects which agents are relevant, and produces `0-proposal/proposal.md`. You review it and approve (or request changes).
+
+### Phase 1 — Setup
+
+Loads project context from `.morph/context/`, confirms stack and active agents. No approval needed.
+
+### Phase 1.5 — UI/UX (conditional)
+
+Only runs if frontend agents are active. Claude generates:
+- `2-ui/design-system.md` — colors, typography, spacing
+- `2-ui/mockups.md` — ASCII wireframes
+- `2-ui/components.md` — component specs
+- `2-ui/flows.md` — user flows and edge cases
+
+You approve the UI design before design phase begins.
+
+### Phase 2 — Design
+
+Claude produces the technical specification:
+- `1-design/spec.md` — full requirements, use cases, validations
+- `1-design/contracts.cs` — C# interfaces, DTOs, enums
+- `1-design/decisions.md` — architectural decision records (ADRs)
+
+You review and approve the design.
+
+### Phase 3 — Clarify
+
+Claude identifies 3–7 ambiguities in the spec, asks you to resolve them, then updates the spec. No gate.
+
+### Phase 4 — Tasks
+
+Claude breaks the spec into atomic tasks (`T001`, `T002`, …) saved to `3-tasks/tasks.md`. You approve the task list.
+
+At this point, planning is complete:
+
+```
+✅ Planning complete — run /morph-apply my-feature to implement
+```
+
+---
+
+## Implement
+
+```
+/morph-apply my-feature
+```
+
+Claude reads `spec.md`, `contracts.cs`, and `tasks.md`, then implements task by task:
+- Starts each task, writes the code, marks it done
+- Runs 5 validators automatically after each task: security, architecture, packages, design system, Blazor concurrency
+- Auto-checkpoints every 3 tasks (validates, saves state)
+- Generates `4-implement/recap.md` on completion
+
+---
+
+## During development
+
+Check feature state:
+
+```bash
+morph-spec state get my-feature
+morph-spec status my-feature
+```
+
+See what phase the feature is in and which approval gates have been passed:
+
+```bash
+morph-spec state show my-feature
+```
+
+Advance to the next phase manually (when needed):
+
+```bash
+morph-spec phase advance my-feature
+```
+
+Mark a task complete:
+
+```bash
+morph-spec task done my-feature
+```
+
+Run validators at any time:
+
+```bash
+morph-spec validate                    # all validators
+morph-spec validate architecture       # specific validator
+morph-spec validate packages
+```
+
+---
+
+## Multiple features
+
+You can have multiple features in progress simultaneously. Each has its own directory under `.morph/features/`:
+
+```
+.morph/features/
+├── user-notifications/
+│   ├── 0-proposal/
+│   ├── 1-design/
+│   └── 3-tasks/
+└── payment-flow/
+    ├── 0-proposal/
+    └── 1-design/
+```
+
+See all feature states:
+
+```bash
+morph-spec state list
+```
+
+---
+
+## Keeping up to date
+
+When a new version of `@polymorphism-tech/morph-spec` is published:
+
+```bash
+# Update the CLI
+npm install -g @polymorphism-tech/morph-spec@latest
+
+# Update framework files in your project
+morph-spec update
+
+# Verify
+morph-spec doctor
+```
+
+`morph-spec update` re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md`. It does not touch your config, context, or feature outputs.
+
+---
+
+## Tips
+
+**Use `/morph-proposal` even for small features.** The proposal phase catches scope creep, identifies the right agents, and generates contracts early — before implementation makes it expensive to change direction.
+
+**Approve explicitly at each gate.** The design gate exists to prevent implementing the wrong thing. If something in `spec.md` or `contracts.cs` looks off, say so before approving.
+
+**ADRs belong in `decisions.md`.** When Claude makes an architectural choice, it documents it there. Read it after Design completes. Decisions drive the validators that run during implementation.
+
+**`morph-spec doctor` is your first debugging step.** If something is behaving unexpectedly, doctor will surface version mismatches, missing files, and hook configuration issues.
+
+---
+
+## Next steps
+
+- [CHEATSHEET.md](CHEATSHEET.md) — command reference
+- [ARCHITECTURE.md](ARCHITECTURE.md) — system design and agent hierarchy
+- [CHANGELOG.md](../CHANGELOG.md) — release history
+- `.morph/framework/standards/` — all coding and architecture standards
+
+---
+
+*morph-spec v4.6.0 by Polymorphism Tech*

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

@@ -0,0 +1,84 @@
+// ============================================================
+// 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

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