@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

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