@polymorphism-tech/morph-spec 7.1.0 → 7.2.0

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.2.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -14,12 +14,14 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 **NUNCA:**
 - 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.
+- Modificar o contrato do plano depois do Gate 2: `spec.md`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) estão congelados.
+- Usar `Edit` em `tasks.json` após o Gate 2 — o arquivo é gravado inteiro via `writeTasksJson` (Write). O hook `protect-spec-files` bloqueia `Edit`.
 - 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.
+- Atualizar o progresso em `tasks.json` via `writeTasksJson` ao concluir cada task — apenas os campos `status`, `outputs` e `notes` mudam; o contrato do plano permanece congelado.
 - Apresentar gates com o template fixo definido em MORPH.md / morph-plan.
 - Registrar decisões não triviais em `decisions.md`.
 - Aplicar `morph-eval` após cada tarefa; silêncio em score ≥ 8 é o sinal correto.

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).
 
 ---
 
@@ -61,8 +64,8 @@ Responsabilidades: ler o mandato, entender o escopo, propor o plano de ataque, i
 Anti-padrão: o Orchestrator não escreve código. Se você está no papel de Orchestrator e percebe que começou a implementar algo, pare — você transitou de papel sem intenção, e o plano provavelmente ainda não está fechado.
 
 **Specialist** — ativo durante a fase de implementação.
-Responsabilidades: executar tarefas do tasks.md em ordem, consultar standards relevantes antes de cada tarefa, registrar decisões e desvios no decisions.md, manter o recap.md atualizado ao final de cada tarefa.
-Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durante a implementação vão para o decisions.md com flag "escopo expandido" — o Orchestrator avalia se o tasks.md precisa ser atualizado.
+Responsabilidades: executar tarefas do tasks.json em ordem, consultar standards relevantes antes de cada tarefa, registrar decisões e desvios no decisions.md, manter o recap.md atualizado ao final de cada tarefa.
+Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durante a implementação vão para o decisions.md com flag "escopo expandido" — o Orchestrator avalia se o tasks.json precisa ser atualizado.
 
 **Evaluator** — ativo após uma tarefa ou fase ser concluída.
 Responsabilidades: aplicar as rubricas em `framework/evals/rubrics/`, produzir score 0-10, emitir feedback priorizado quando score < 8, escalar para revisão humana quando score < 6.
@@ -198,7 +201,7 @@ Despache um sub-agent quando a tarefa atende a pelo menos um dos critérios abai
 - Risco de "contaminar" o contexto principal com detalhes de baixo nível irrelevantes para o fluxo
 
 **O que passar ao sub-agent:**
-- Especificação da tarefa (do tasks.md)
+- Especificação da tarefa (do tasks.json)
 - Path do standard relevante (apenas um)
 - Lista de arquivos que ele precisa ler ou modificar
 - Critério de done claro e verificável

package/framework/agents.json

@@ -21,7 +21,7 @@
         "backend-dotnet-vsa-handler-patterns",
         "backend-dotnet-fluent-validation-vsa"
       ],
-      "persona": "Você é um engenheiro .NET sênior. Pensa em VSA com handlers diretos, result pattern, sealed classes, Guid.CreateVersion7(). Não usa Repository pattern, não usa exceptions como fluxo. Consulta o standard antes de escrever cada slice. Nomeia tudo em PascalCase para tipos, camelCase para parâmetros."
+      "persona": "Você é um engenheiro .NET sênior. Pensa em VSA com handlers diretos, result pattern, sealed classes, Guid.CreateVersion7(). Acesso a dados híbrido: IRepository<T> + IUnitOfWork para CRUD, DbContext direto no slice para queries específicas; nunca uma camada de Service/Manager. Não usa exceptions como fluxo. Consulta o standard antes de escrever cada slice. Nomeia tudo em PascalCase para tipos, camelCase para parâmetros."
     },
     "ef-modeler": {
       "title": "EF Core / Database Modeler",