@polymorphism-tech/morph-spec 7.1.0 → 7.1.1

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.22.1  
+**Version:** 7.1.1  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -365,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.22.1 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v7.1.1 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,14 +1,14 @@
-{
-  "name": "morph-spec",
-  "version": "4.22.1",
-  "displayName": "MORPH-SPEC Framework",
-  "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
-  "publisher": "polymorphism-tech",
-  "skills": {
-    "directory": "framework/skills",
-    "namespace": "morph-spec"
-  },
-  "hooks": {
-    "directory": "framework/hooks/claude-code"
-  }
-}
+{
+  "name": "morph-spec",
+  "version": "7.1.1",
+  "displayName": "MORPH-SPEC Framework",
+  "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
+  "publisher": "polymorphism-tech",
+  "skills": {
+    "directory": "framework/skills",
+    "namespace": "morph-spec"
+  },
+  "hooks": {
+    "directory": "framework/hooks/claude-code"
+  }
+}

package/docs/CHEATSHEET.md

@@ -1,199 +1,199 @@
-# morph-spec Cheat Sheet
-
-## Setup
-
-```bash
-npm install -g @polymorphism-tech/morph-spec   # install globally
-morph-spec init                                 # initialize project
-morph-spec init --wizard                        # interactive wizard
-morph-spec init --force                         # overwrite existing
-morph-spec update                               # sync framework files
-morph-spec doctor                               # health check
-morph-spec --version
-```
-
----
-
-## Phase workflow
-
-```
-proposal → [uiux] → design → plan → tasks → implement → [sync]
-```
-
-Phases in brackets are optional.
-
-| Phase | Directory | Output files | Gate |
-|-------|-----------|--------------|------|
-| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
-| uiux *(optional)* | `1-design/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
-| design | `2-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
-| plan | `3-plan/` | `plan.md` | ✅ Approval |
-| tasks | `4-tasks/` | `tasks.md` | ✅ Approval |
-| implement | `3-implement/` | code + `recap.md` | — |
-| sync *(optional)* | — | standards updated | — |
-
----
-
-## Slash commands (Claude Code)
-
-| Command | Description |
-|---------|-------------|
-| `/morph-proposal {feature}` | Full spec pipeline — phases 0–4 with approval gates |
-| `/morph-apply {feature}` | Implement approved feature — phase 5 |
-| `/morph-status` | Project-wide feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation (7 checks) |
-
----
-
-## CLI — project management
-
-```bash
-morph-spec init [--force] [--skip-mcp]
-morph-spec update [--templates] [--standards]
-morph-spec doctor
-```
-
----
-
-## CLI — feature workflow
-
-```bash
-morph-spec state list                          # all features
-morph-spec state get {feature} [--json]        # feature detail
-morph-spec state set {feature} {key} {value}   # update property
-morph-spec phase advance {feature}             # advance to next phase
-morph-spec status {feature} [--json] [--verbose]
-morph-spec task done {feature} {task-id}        # mark task complete
-morph-spec task start {feature} {task-id}      # start a task (dispatch gate)
-```
-
----
-
-## CLI — validation
-
-```bash
-morph-spec validate                            # all validators
-morph-spec validate architecture
-morph-spec validate packages
-morph-spec validate contrast [--wcag-aaa]
-morph-spec validate-feature {feature} [--phase {phase}] [--json]
-```
-
----
-
-## CLI — utilities
-
-```bash
-morph-spec generate recap {feature}           # auto-generate recap.md
-morph-spec template render {id} {output} {vars-json}
-morph-spec trust status [feature]
-morph-spec trust set {feature} {level} [reason]    # level: manual|high|auto
-morph-spec mcp setup [name] [--list] [--auto]
-```
-
----
-
-## State — mark-output
-
-```bash
-morph-spec state mark-output {feature} proposal
-morph-spec state mark-output {feature} spec
-morph-spec state mark-output {feature} contracts
-morph-spec state mark-output {feature} decisions
-morph-spec state mark-output {feature} tasks
-morph-spec state mark-output {feature} recap
-
-# UI outputs (camelCase or kebab-case both work)
-morph-spec state mark-output {feature} uiDesignSystem
-morph-spec state mark-output {feature} uiMockups
-morph-spec state mark-output {feature} uiComponents
-morph-spec state mark-output {feature} uiFlows
-```
-
----
-
-## State — agents
-
-```bash
-morph-spec state add-agent {feature} {agent-id}
-morph-spec state remove-agent {feature} {agent-id}
-```
-
----
-
-## Checkpoints
-
-```bash
-morph-spec checkpoint-save {feature}
-```
-
----
-
-## Approvals
-
-```bash
-morph-spec approve {feature} {gate}            # approve a gate
-morph-spec approval-status {feature}           # show gate status
-```
-
----
-
-## Directory structure
-
-```
-.morph/
-├── config/
-│   └── config.json               # project config (editable)
-├── framework/                    # READ-ONLY
-│   ├── agents.json               # 22 agents, 4 tiers
-│   ├── standards/                # 82 standards across 11 categories
-│   └── templates/                # code and IaC templates
-├── context/                      # project context (editable)
-│   ├── README.md
-│   └── standards.md
-├── features/
-│   └── {feature}/
-│       ├── 0-proposal/proposal.md
-│       ├── 1-design/design-system.md, mockups.md, components.md, flows.md
-│       ├── 2-design/spec.md, contracts.cs, decisions.md
-│       ├── 3-tasks/tasks.md
-│       └── 4-implement/recap.md
-├── checkpoints/
-├── logs/
-└── state.json                    # READ-ONLY — CLI managed
-
-.claude/
-├── commands/                     # slash commands
-├── skills/                       # framework skills (SKILL.md per dir)
-├── agents/                       # native subagents (22)
-│   ├── morph-{id}.md             # tier 1-2 agents
-│   └── morph-domain-{name}.md   # tier 3 domain agents
-├── rules/                        # path-scoped rules (6 files)
-└── settings.local.json           # hooks (10)
-```
-
----
-
-## Protected files
-
-These files are never edited directly. Use CLI commands or `morph-spec update` instead:
-
-| Path | Protected by |
-|------|-------------|
-| `.morph/state.json` | `permissions.deny` |
-| `.morph/framework/**` | `permissions.deny` |
-| Approved spec/contracts | `protect-spec-files.js` hook |
-
----
-
-## Links
-
-- [QUICKSTART.md](QUICKSTART.md) — step-by-step guide
-- [ARCHITECTURE.md](ARCHITECTURE.md) — system design
-- [CHANGELOG.md](../CHANGELOG.md) — release history
-- [npm](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
-- support@polymorphism.com.br
-
----
-
-*morph-spec v4.22.1 by Polymorphism Tech*
+# morph-spec Cheat Sheet
+
+## Setup
+
+```bash
+npm install -g @polymorphism-tech/morph-spec   # install globally
+morph-spec init                                 # initialize project
+morph-spec init --wizard                        # interactive wizard
+morph-spec init --force                         # overwrite existing
+morph-spec update                               # sync framework files
+morph-spec doctor                               # health check
+morph-spec --version
+```
+
+---
+
+## Phase workflow
+
+```
+proposal → [uiux] → design → plan → tasks → implement → [sync]
+```
+
+Phases in brackets are optional.
+
+| Phase | Directory | Output files | Gate |
+|-------|-----------|--------------|------|
+| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
+| uiux *(optional)* | `1-design/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
+| design | `2-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
+| plan | `3-plan/` | `plan.md` | ✅ Approval |
+| tasks | `4-tasks/` | `tasks.md` | ✅ Approval |
+| implement | `3-implement/` | code + `recap.md` | — |
+| sync *(optional)* | — | standards updated | — |
+
+---
+
+## Slash commands (Claude Code)
+
+| Command | Description |
+|---------|-------------|
+| `/morph-proposal {feature}` | Full spec pipeline — phases 0–4 with approval gates |
+| `/morph-apply {feature}` | Implement approved feature — phase 5 |
+| `/morph-status` | Project-wide feature status dashboard |
+| `/morph-preflight` | Pre-implementation validation (7 checks) |
+
+---
+
+## CLI — project management
+
+```bash
+morph-spec init [--force] [--skip-mcp]
+morph-spec update [--templates] [--standards]
+morph-spec doctor
+```
+
+---
+
+## CLI — feature workflow
+
+```bash
+morph-spec state list                          # all features
+morph-spec state get {feature} [--json]        # feature detail
+morph-spec state set {feature} {key} {value}   # update property
+morph-spec phase advance {feature}             # advance to next phase
+morph-spec status {feature} [--json] [--verbose]
+morph-spec task done {feature} {task-id}        # mark task complete
+morph-spec task start {feature} {task-id}      # start a task (dispatch gate)
+```
+
+---
+
+## CLI — validation
+
+```bash
+morph-spec validate                            # all validators
+morph-spec validate architecture
+morph-spec validate packages
+morph-spec validate contrast [--wcag-aaa]
+morph-spec validate-feature {feature} [--phase {phase}] [--json]
+```
+
+---
+
+## CLI — utilities
+
+```bash
+morph-spec generate recap {feature}           # auto-generate recap.md
+morph-spec template render {id} {output} {vars-json}
+morph-spec trust status [feature]
+morph-spec trust set {feature} {level} [reason]    # level: manual|high|auto
+morph-spec mcp setup [name] [--list] [--auto]
+```
+
+---
+
+## State — mark-output
+
+```bash
+morph-spec state mark-output {feature} proposal
+morph-spec state mark-output {feature} spec
+morph-spec state mark-output {feature} contracts
+morph-spec state mark-output {feature} decisions
+morph-spec state mark-output {feature} tasks
+morph-spec state mark-output {feature} recap
+
+# UI outputs (camelCase or kebab-case both work)
+morph-spec state mark-output {feature} uiDesignSystem
+morph-spec state mark-output {feature} uiMockups
+morph-spec state mark-output {feature} uiComponents
+morph-spec state mark-output {feature} uiFlows
+```
+
+---
+
+## State — agents
+
+```bash
+morph-spec state add-agent {feature} {agent-id}
+morph-spec state remove-agent {feature} {agent-id}
+```
+
+---
+
+## Checkpoints
+
+```bash
+morph-spec checkpoint-save {feature}
+```
+
+---
+
+## Approvals
+
+```bash
+morph-spec approve {feature} {gate}            # approve a gate
+morph-spec approval-status {feature}           # show gate status
+```
+
+---
+
+## Directory structure
+
+```
+.morph/
+├── config/
+│   └── config.json               # project config (editable)
+├── framework/                    # READ-ONLY
+│   ├── agents.json               # 22 agents, 4 tiers
+│   ├── standards/                # 82 standards across 11 categories
+│   └── templates/                # code and IaC templates
+├── context/                      # project context (editable)
+│   ├── README.md
+│   └── standards.md
+├── features/
+│   └── {feature}/
+│       ├── 0-proposal/proposal.md
+│       ├── 1-design/design-system.md, mockups.md, components.md, flows.md
+│       ├── 2-design/spec.md, contracts.cs, decisions.md
+│       ├── 3-tasks/tasks.md
+│       └── 4-implement/recap.md
+├── checkpoints/
+├── logs/
+└── state.json                    # READ-ONLY — CLI managed
+
+.claude/
+├── commands/                     # slash commands
+├── skills/                       # framework skills (SKILL.md per dir)
+├── agents/                       # native subagents (22)
+│   ├── morph-{id}.md             # tier 1-2 agents
+│   └── morph-domain-{name}.md   # tier 3 domain agents
+├── rules/                        # path-scoped rules (6 files)
+└── settings.local.json           # hooks (10)
+```
+
+---
+
+## Protected files
+
+These files are never edited directly. Use CLI commands or `morph-spec update` instead:
+
+| Path | Protected by |
+|------|-------------|
+| `.morph/state.json` | `permissions.deny` |
+| `.morph/framework/**` | `permissions.deny` |
+| Approved spec/contracts | `protect-spec-files.js` hook |
+
+---
+
+## Links
+
+- [QUICKSTART.md](QUICKSTART.md) — step-by-step guide
+- [ARCHITECTURE.md](ARCHITECTURE.md) — system design
+- [CHANGELOG.md](../CHANGELOG.md) — release history
+- [npm](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
+- support@polymorphism.com.br
+
+---
+
+*morph-spec v7.1.1 by Polymorphism Tech*

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).
 
 ---
 

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",

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -26,7 +26,7 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
 | Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
 | Jobs async | Hangfire — apenas se a feature requer processamento em background |
 
-**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions sem result pattern, Repository pattern (VSA usa handlers diretos).
+**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions sem result pattern, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
 
 ## O que fazer
 

package/framework/skills/core/morph-plan/SKILL.md

@@ -33,7 +33,9 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
      - `Guid.NewGuid()` → usar `Guid.CreateVersion7()`
      - Classes não-sealed sem justificativa documentada
      - Exceptions como fluxo de controle → usar result pattern com `result.Match()`
-     - Repository pattern / `IRepository<T>` → handlers VSA acessam DbContext diretamente
+     - Camada de Service/Manager entre handler e dados → handler usa `IRepository<T>` ou `DbContext` direto
+     - SQL cru (`FromSqlRaw`, `ExecuteQuery(string)`) sem justificativa em `decisions.md` → usar LINQ
+   - Política de acesso a dados (registre no mandate como orientação, não proibição): `IRepository<T>` + `IUnitOfWork` para CRUD simples; `ApplicationDbContext` injetado direto no slice para queries específicas (joins, projeção, paginação).
    - Checklist de done com critérios verificáveis por tarefa.
 
 4. Produza `tasks.json` em `.morph/features/{feature}/2-plan/` seguindo o schema em `.morph/framework/schemas/tasks.schema.json`.

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -28,7 +28,7 @@ Quando o projeto já tem código existente e você precisa entender o estado atu
 | Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
 | Jobs | Hangfire (apenas quando necessário) |
 
-**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern, `IRepository<T>`.
+**Padrões proibidos:** `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
 
 ## Greenfield short-circuit
 
@@ -61,7 +61,7 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    - Erros: Result pattern (`result.Match()`)
 
    ## Padrões proibidos
-   `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern, `IRepository<T>`.
+   `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados em VSA é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
 
    ## Recomendação
    Compliance trivial (greenfield). Prosseguir para morph-brainstorming.
@@ -101,7 +101,7 @@ Antes de despachar Explore, verifique se o projeto é greenfield:
    | Severidade | Critério |
    |------------|---------|
    | **Bloqueante** | Runtime diferente (.NET 8 ou anterior), ORM diferente (Dapper puro sem EF Core), banco diferente (MySQL, SQL Server) |
-   | **Alto** | `Guid.NewGuid()` generalizado, Repository pattern em toda a codebase, exceptions como fluxo de controle |
+   | **Alto** | `Guid.NewGuid()` generalizado, camada de Service/Manager entre handler e dados, SQL cru generalizado, exceptions como fluxo de controle |
    | **Médio** | Classes não-sealed, Pages Router em vez de App Router, biblioteca de UI diferente |
    | **Baixo** | Versões de pacotes desatualizadas mas compatíveis |
 

package/framework/standards/architecture/vertical-slice/vertical-slice.md

@@ -323,6 +323,12 @@ public interface IRepository<T> where T : class
 }
 ```
 
+**Quando NÃO usar o repository:** o `IRepository<T>` genérico cobre CRUD por chave.
+Para queries com join, projeção, paginação ou filtros compostos, injete
+`ApplicationDbContext` direto no handler e escreva o LINQ no slice — não polua a
+interface genérica com métodos de um único slice, e não use `ExecuteQuery(string sql)`.
+Veja `backend/dotnet/vsa-handler-patterns.md` → "When to Use DbContext Directly".
+
 ---
 
 ## DI Registration (Program.cs)
@@ -379,7 +385,7 @@ app.MapApiEndpoints();
 4. **`result.Match()`** nos endpoints — nunca acessar `result.Value` sem checar `IsSuccess`.
 5. **IApiEndpoint `internal sealed`** — endpoints não são públicos.
 6. **`{Entity}Errors` compartilhado** por todas as operações da feature (1 arquivo por feature, não por slice).
-7. **Repository injetado pelo handler** diretamente (sem Application Service layer).
+7. **Acesso a dados híbrido**: `IRepository<T>` injetado no handler para CRUD por chave; `ApplicationDbContext` injetado direto no slice para queries específicas (joins, projeção, paginação). Nunca uma Application Service layer entre handler e dados.
 8. **`IUnitOfWork.CommitAsync()`** em operações de escrita (Create, Update, Delete).
 9. **Sem validator em GetAll** — GetAllBooksHandler não tem validator (sem parâmetros para validar).
 

package/framework/standards/backend/dotnet/vsa-handler-patterns.md

@@ -197,6 +197,36 @@ public interface IUnitOfWork
 
 **Pattern:** `Repository.AddAsync()` -> `UnitOfWork.CommitAsync()` — always commit explicitly.
 
+### When to Use DbContext Directly Instead
+
+`IRepository<T>` is the right tool for CRUD by key. It is **not** the right tool for
+slice-specific queries — joins, projections, pagination, composite filters. For those,
+inject `ApplicationDbContext` directly into the handler and write the LINQ in the slice:
+
+```csharp
+public sealed class SearchBooksHandler(
+    ApplicationDbContext db) : IHandler<SearchBooksRequest, Result<IReadOnlyList<BookDto>>>
+{
+    public async Task<Result<IReadOnlyList<BookDto>>> HandleAsync(
+        SearchBooksRequest query, CancellationToken cancellationToken)
+    {
+        var books = await db.Books
+            .Where(b => b.Author.Contains(query.Author))
+            .OrderBy(b => b.Title)
+            .Skip(query.Skip).Take(query.Take)
+            .Select(b => new BookDto(b.Id, b.Title, b.Author))
+            .ToListAsync(cancellationToken);
+
+        return Result.Success<IReadOnlyList<BookDto>>(books);
+    }
+}
+```
+
+**Rule of thumb:** CRUD by key → `IRepository<T>` + `IUnitOfWork`. Anything that needs a
+custom query shape → `ApplicationDbContext` in the slice. Never reach for raw SQL
+(`FromSqlRaw`) unless a query genuinely cannot be expressed in LINQ — and document that
+in `decisions.md`.
+
 ---
 
 ## Feature Error Factory
@@ -272,6 +302,8 @@ builder.Services.AddExceptionHandler<CustomExceptionHandler>()
 | Share handlers across features | Each feature has its own handler, even if similar |
 | Use constructor + field for DI | Use primary constructors: `class Handler(IDep dep)` |
 | Group by technical concern (Controllers/, Services/) | Group by feature: `Features/BookFeature/CreateBook/` |
+| Force a slice-specific query through `IRepository<T>` | Inject `DbContext` and write LINQ in the slice |
+| Use raw SQL (`FromSqlRaw` / `ExecuteQuery(string)`) by default | Use LINQ; raw SQL only with a `decisions.md` justification |
 
 ---
 

package/framework/templates/CLAUDE.md.core.template

@@ -6,7 +6,7 @@
 
 VSA + .NET 10 + EF Core + Neon (Postgres) + Microsoft Agent Framework + Next.js (App Router) + Tailwind + Framer Motion + Shadcn + Hangfire (quando necessário).
 
-Padrões proibidos por padrão: `Guid.NewGuid()` (use `Guid.CreateVersion7()`), classes não-sealed sem justificativa, exceptions como fluxo de controle, Repository pattern.
+Padrões proibidos por padrão: `Guid.NewGuid()` (use `Guid.CreateVersion7()`), classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, SQL cru sem justificativa. Acesso a dados é híbrido: `IRepository<T>` + `IUnitOfWork` para CRUD; `DbContext` direto no slice para queries específicas.
 
 ## Harness
 

package/framework/templates/code/dotnet/backend/repository.cs

@@ -3,7 +3,6 @@
 // Generated by MORPH Framework
 // ============================================================
 
-using System.Data.Common;
 using Microsoft.EntityFrameworkCore;
 using {{pascalCase PROJECT_NAME}}.Database;
 
@@ -13,6 +12,9 @@ namespace {{pascalCase PROJECT_NAME}}.Repository;
 // IRepository<T> — Generic repository contract
 // ============================================================
 
+// Generic CRUD by key. For slice-specific queries (joins, projection, pagination),
+// inject ApplicationDbContext directly into the handler and write LINQ in the slice —
+// do NOT add query methods here, and do NOT use raw SQL.
 public interface IRepository<T> where T : class
 {
     Task<IEnumerable<T>> GetAllAsync(CancellationToken cancellationToken = default);
@@ -20,7 +22,6 @@ public interface IRepository<T> where T : class
     Task<T> AddAsync(T entity, CancellationToken cancellationToken = default);
     Task UpdateAsync(T entity, CancellationToken cancellationToken = default);
     Task DeleteAsync(T entity, CancellationToken cancellationToken = default);
-    IEnumerable<T> ExecuteQuery(string query, DbParameter[] dbParams);
     Task AddRangeAsync(IEnumerable<T> entities, CancellationToken cancellationToken = default);
     void RemoveRange(IEnumerable<T> entities);
 }
@@ -80,14 +81,6 @@ public class Repository<T> : IRepository<T> where T : class
         return Task.CompletedTask;
     }
 
-    public IEnumerable<T> ExecuteQuery(string query, DbParameter[] dbParams)
-    {
-        return _dbSet
-            .FromSqlRaw(query, dbParams)
-            .AsNoTracking()
-            .AsEnumerable();
-    }
-
     public async Task AddRangeAsync(IEnumerable<T> entities, CancellationToken cancellationToken = default)
     {
         await _dbSet.AddRangeAsync(entities, cancellationToken);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "7.1.0",
+  "version": "7.1.1",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",