@polymorphism-tech/morph-spec 7.0.0 → 7.1.1

package/docs/QUICKSTART.md

@@ -1,200 +1,200 @@
-# morph-spec Quick Start
-
-## Install
-
-```bash
-npm install -g @polymorphism-tech/morph-spec
-```
-
-> The installer automatically configures your PowerShell PATH on Windows. If `morph-spec` is not found, open a new terminal window.
-
----
-
-## 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 10 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–6 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 2 — UI/UX (conditional)
-
-Only runs if frontend agents are active. Claude generates:
-- `1-design/design-system.md` — colors, typography, spacing
-- `1-design/mockups.md` — ASCII wireframes
-- `1-design/components.md` — component specs
-- `1-design/flows.md` — user flows and edge cases
-
-You approve the UI design before design phase begins.
-
-### Phase 3 — Design
-
-Claude produces the technical specification:
-- `2-design/spec.md` — full requirements, use cases, validations
-- `2-design/contracts.cs` — C# interfaces, DTOs, enums
-- `2-design/decisions.md` — architectural decision records (ADRs)
-
-You review and approve the design.
-
-### Phase 4 — Clarify
-
-Claude identifies 3–7 ambiguities in the spec, asks you to resolve them, then updates the spec. No gate.
-
-### Phase 6 — 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
-```
-
-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 T001
-```
-
-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/
-│   ├── 2-design/
-│   └── 3-tasks/
-└── payment-flow/
-    ├── 0-proposal/
-    └── 2-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.22.1 by Polymorphism Tech*
+# morph-spec Quick Start
+
+## Install
+
+```bash
+npm install -g @polymorphism-tech/morph-spec
+```
+
+> The installer automatically configures your PowerShell PATH on Windows. If `morph-spec` is not found, open a new terminal window.
+
+---
+
+## 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 10 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–6 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 2 — UI/UX (conditional)
+
+Only runs if frontend agents are active. Claude generates:
+- `1-design/design-system.md` — colors, typography, spacing
+- `1-design/mockups.md` — ASCII wireframes
+- `1-design/components.md` — component specs
+- `1-design/flows.md` — user flows and edge cases
+
+You approve the UI design before design phase begins.
+
+### Phase 3 — Design
+
+Claude produces the technical specification:
+- `2-design/spec.md` — full requirements, use cases, validations
+- `2-design/contracts.cs` — C# interfaces, DTOs, enums
+- `2-design/decisions.md` — architectural decision records (ADRs)
+
+You review and approve the design.
+
+### Phase 4 — Clarify
+
+Claude identifies 3–7 ambiguities in the spec, asks you to resolve them, then updates the spec. No gate.
+
+### Phase 6 — 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
+```
+
+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 T001
+```
+
+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/
+│   ├── 2-design/
+│   └── 3-tasks/
+└── payment-flow/
+    ├── 0-proposal/
+    └── 2-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 v7.1.1 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -16,7 +16,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 - Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
 - Modificar `spec.md`, `mandate.md`, `tasks.md` depois do Gate 2 — eles estão congelados.
 - Listar perguntas em texto simples — sempre use a tool `AskUserQuestion` (1-4 perguntas por chamada).
-- Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern.
+- Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, ou SQL cru sem justificativa.
 
 **SEMPRE:**
 - Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.

package/framework/MORPH.md

@@ -48,7 +48,10 @@ Padrões proibidos automaticamente injetados no mandate:
 - `Guid.NewGuid()` → `Guid.CreateVersion7()`
 - Classes não-sealed sem justificativa
 - Exceptions como fluxo de controle
-- Repository pattern / `IRepository<T>` (VSA usa handlers diretos no DbContext)
+- Camada de Service/Manager entre handler e dados — o handler fala com `IRepository<T>` ou `DbContext`, nunca com um service
+- SQL cru (`FromSqlRaw`, `ExecuteQuery(string)`) sem justificativa em `decisions.md` — use LINQ
+
+Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD simples; `ApplicationDbContext` injetado direto no slice quando a query for específica (joins, projeção, paginação, filtros compostos).
 
 ---