@polymorphism-tech/morph-spec 7.1.0 → 7.2.0

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -1,72 +1,193 @@
-#!/usr/bin/env node
-
-/**
- * PreToolUse Hook: Protect Approved Spec Files
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Blocks Write/Edit to spec artifacts after their approval gate has passed:
- *   - 2-plan/spec.md, contracts.cs, tasks.md, etc. → blocked if 'plan' gate approved
- *   - 1-design/design-system.md, etc. → blocked if 'uiux' gate approved
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, isGateApproved } from '../../shared/state-reader.js';
-import {
-  isFeaturePath,
-  extractFeatureName,
-  getBasename,
-  PROTECTED_SPEC_FILES
-} from '../../shared/phase-utils.js';
-import { block, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-import { getFilePath } from '../../shared/payload-utils.js';
-
-try {
-  // Amend mode: bypass spec protection for legitimate in-implementation corrections
-  if (process.env.MORPH_AMEND_PHASE) {
-    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
-    pass();
-  }
-
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
-
-  // Only check files inside .morph/features/
-  if (!isFeaturePath(filePath)) pass();
-
-  const featureName = extractFeatureName(filePath);
-  if (!featureName) pass();
-
-  const filename = getBasename(filePath);
-  const requiredGate = PROTECTED_SPEC_FILES[filename];
-
-  // Not a protected file
-  if (!requiredGate) pass();
-
-  // Check if the gate has been approved
-  if (isGateApproved(featureName, requiredGate)) {
-    logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-    block(
-      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-      `Editing approved specs breaks the spec contract.\n\n` +
-      `If changes are truly needed, ask the user to revoke the gate approval\n` +
-      `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
-      `your edits, then re-present the gate for approval.`
-    );
-  }
-
-  // Gate not yet approved — allow editing
-  logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
-}
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Protect Approved Spec Files
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * Blocks Write/Edit to spec artifacts after their approval gate has passed:
+ *   - 2-plan/spec.md, mandate.md, etc. → blocked if 'plan' gate approved
+ *   - 1-design/design-system.md, etc. → blocked if 'uiux' gate approved
+ *
+ * Semantic exception for files in MUTABLE_SPEC_FIELDS (e.g. tasks.json):
+ * the plan contract is frozen, but per-task progress fields (status, outputs,
+ * notes) may still change during the implement phase. For those files a Write
+ * is allowed only when the semantic diff touches solely the mutable fields;
+ * Edit is always blocked because the legitimate progress path is a full Write
+ * via writeTasksJson(). This lets the implement phase record task status
+ * without unfreezing the plan.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, isGateApproved } from '../../shared/state-reader.js';
+import {
+  isFeaturePath,
+  extractFeatureName,
+  getBasename,
+  PROTECTED_SPEC_FILES,
+  MUTABLE_SPEC_FIELDS
+} from '../../shared/phase-utils.js';
+import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath, getToolName } from '../../shared/payload-utils.js';
+
+/**
+ * Compare two tasks.json structures and return the list of plan-contract
+ * violations — changes that touch anything other than the mutable fields.
+ *
+ * @param {object} oldDoc - parsed previous file content
+ * @param {object} newDoc - parsed proposed file content
+ * @param {string[]} mutableFields - field names allowed to change
+ * @returns {string[]} human-readable violation messages (empty = OK)
+ */
+function diffPlanContract(oldDoc, newDoc, mutableFields) {
+  const violations = [];
+  const mutable = new Set(mutableFields);
+
+  if (oldDoc.version !== newDoc.version) {
+    violations.push(`'version' changed (${oldDoc.version} → ${newDoc.version})`);
+  }
+  if (oldDoc.feature !== newDoc.feature) {
+    violations.push(`'feature' changed (${oldDoc.feature} → ${newDoc.feature})`);
+  }
+
+  const oldTasks = Array.isArray(oldDoc.tasks) ? oldDoc.tasks : [];
+  const newTasks = Array.isArray(newDoc.tasks) ? newDoc.tasks : [];
+
+  if (oldTasks.length !== newTasks.length) {
+    violations.push(`task count changed (${oldTasks.length} → ${newTasks.length}) — tasks cannot be added or removed`);
+  }
+
+  const oldById = new Map(oldTasks.map(t => [t.id, t]));
+  const newById = new Map(newTasks.map(t => [t.id, t]));
+
+  // A task present before must still exist (no removals / id renames).
+  for (const id of oldById.keys()) {
+    if (!newById.has(id)) violations.push(`task '${id}' was removed`);
+  }
+  for (const id of newById.keys()) {
+    if (!oldById.has(id)) violations.push(`task '${id}' was added`);
+  }
+
+  // For tasks present on both sides, only mutable fields may differ.
+  for (const [id, newTask] of newById) {
+    const oldTask = oldById.get(id);
+    if (!oldTask) continue;
+    const keys = new Set([...Object.keys(oldTask), ...Object.keys(newTask)]);
+    for (const key of keys) {
+      if (mutable.has(key)) continue;
+      if (JSON.stringify(oldTask[key]) !== JSON.stringify(newTask[key])) {
+        violations.push(`task '${id}': immutable field '${key}' changed`);
+      }
+    }
+  }
+
+  return violations;
+}
+
+try {
+  // Amend mode: bypass spec protection for legitimate in-implementation corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check files inside .morph/features/
+  if (!isFeaturePath(filePath)) pass();
+
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) pass();
+
+  const filename = getBasename(filePath);
+  const requiredGate = PROTECTED_SPEC_FILES[filename];
+
+  // Not a protected file
+  if (!requiredGate) pass();
+
+  // Gate not yet approved — allow editing
+  if (!isGateApproved(featureName, requiredGate)) {
+    logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+    pass();
+  }
+
+  // ── Gate approved — file is locked ──────────────────────────────────────
+  const mutableFields = MUTABLE_SPEC_FIELDS[filename];
+
+  // Files with mutable progress fields (e.g. tasks.json): allow a full Write
+  // that touches only those fields. Anything else stays blocked.
+  if (mutableFields) {
+    const toolName = getToolName(payload);
+    const newContent = payload?.tool_input?.content;
+
+    // Edit is never the legitimate progress path — progress is written as a
+    // full file via writeTasksJson(). Block Edit; fall through to the message.
+    if (toolName !== 'Write' || typeof newContent !== 'string') {
+      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+      block(
+        `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+        `Progress updates (${mutableFields.join(', ')}) must be written as a full-file\n` +
+        `Write, not an Edit. The plan contract (titles, dependencies, doneCriteria…)\n` +
+        `is frozen. To change the plan itself, ask the user to revoke the\n` +
+        `'${requiredGate}' gate in .morph/state.json, then re-present it for approval.`
+      );
+    }
+
+    // Semantic diff: old = current file on disk, new = proposed content.
+    // Any failure to read/parse → fail-open (pass), never a false block.
+    let oldDoc, newDoc;
+    try {
+      // filePath may already be absolute (Claude Code usually sends absolute
+      // paths); only join against cwd when it is relative.
+      const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
+      oldDoc = JSON.parse(readFileSync(absPath, 'utf-8'));
+      newDoc = JSON.parse(newContent);
+    } catch {
+      // Cannot compare — fail-open rather than block a possibly-valid write.
+      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+      pass();
+    }
+
+    const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
+    if (violations.length === 0) {
+      // Only mutable progress fields changed — this is a legitimate
+      // implement-phase update.
+      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+      pass();
+    }
+
+    logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+    block(
+      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+      `This Write changes the frozen plan contract:\n` +
+      violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
+      `During the implement phase only these fields may change: ${mutableFields.join(', ')}.\n` +
+      `To change the plan itself, ask the user to revoke the '${requiredGate}' gate\n` +
+      `in .morph/state.json, then re-present it for approval.`
+    );
+  }
+
+  // Fully-locked file (spec.md, mandate.md, design files): blanket block.
+  logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+  block(
+    `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+    `Editing approved specs breaks the spec contract.\n\n` +
+    `If changes are truly needed, ask the user to revoke the gate approval\n` +
+    `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
+    `your edits, then re-present the gate for approval.`
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/shared/phase-utils.js

@@ -65,6 +65,16 @@ export const PROTECTED_SPEC_FILES = {
   'tasks.json': 'plan',
 };
 
+/**
+ * For protected files that carry mutable progress fields: filename → the
+ * top-level array-item fields that may change after the gate is approved.
+ * When a protected file is listed here, the protect-spec-files hook does a
+ * semantic diff (allowing only these fields to change) instead of a blanket block.
+ */
+export const MUTABLE_SPEC_FIELDS = {
+  'tasks.json': ['status', 'outputs', 'notes'],
+};
+
 /**
  * Extract feature name from a .morph/features/{feature}/... path
  * @param {string} filePath - File path to analyze

package/framework/rules/morph-workflow.md

@@ -125,19 +125,26 @@ After making structural changes (new packages, dependencies, project config chan
 
 BEFORE implementing ANY task during the implement phase:
 
-1. **Read tasks.md** → identify the FR references for the current task (e.g., `[FR001, FR003]`)
-2. **Read spec.md** → the sections for those specific FRs
-3. **Read contracts.cs/.ts** → the DTOs/interfaces referenced by those FRs
+1. **Read tasks.json** → identify the current task object (`id`, `description`, `doneCriteria`, `dependencies`)
+2. **Read spec.md** → the FR sections that the task `description` references
+3. **Read the contracts** → the DTOs/interfaces are defined inside `spec.md` (v5 keeps contracts in the spec, not separate files)
 4. Only then begin implementation
 
 This is **NON-NEGOTIABLE**. The spec is the source of truth. Code that doesn't match the spec is a bug.
 
-Every task in `tasks.md` MUST have FR cross-references in this format:
-```
-### T001: Create user endpoint [FR001, FR003]
-- **Spec refs:** FR001 (user CRUD), FR003 (input validation)
-- **Contracts:** CreateUserRequest, CreateUserResponse, UserErrors
-- **Files:** Features/UserFeature/Create/Handler.cs, Validator.cs, Endpoint.cs
+Every task in `tasks.json` MUST reference its FR(s) in the `description` field so the link to the spec is explicit:
+```json
+{
+  "id": "T1",
+  "title": "Create user endpoint",
+  "description": "Implement user CRUD (FR001) and input validation (FR003). Contracts: CreateUserRequest, CreateUserResponse, UserErrors.",
+  "dependencies": [],
+  "effort": "M",
+  "doneCriteria": "POST /users creates a user and rejects invalid input",
+  "status": "pending",
+  "outputs": ["Features/UserFeature/Create/Handler.cs", "Validator.cs", "Endpoint.cs"],
+  "group": "backend"
+}
 ```
 
 ---

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

@@ -4,6 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-apply

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

@@ -4,6 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-brainstorming
@@ -26,7 +27,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-eval/SKILL.md

@@ -4,6 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
+cliVersion: "7.2.0"
 ---
 
 # morph-eval

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

@@ -4,6 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
+cliVersion: "7.2.0"
 ---
 
 # morph-implement
@@ -78,6 +79,12 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    await writeTasksJson(tasksPath, data);
    ```
 
+   `tasks.json` é protegido após o Gate 2, mas os campos de progresso (`status`,
+   `outputs`, `notes`) continuam graváveis durante a fase implement. `writeTasksJson`
+   grava o arquivo **inteiro** (Write) — esse é o caminho permitido. Nunca use a
+   tool `Edit` em `tasks.json` após o Gate 2: o hook `protect-spec-files` bloqueia
+   Edit e qualquer mudança em campos de plano (`title`, `dependencies`, `doneCriteria`…).
+
 9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
 
 ## Output esperado

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

@@ -4,6 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-plan
@@ -33,7 +34,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-proposal/SKILL.md

@@ -4,6 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-proposal

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

@@ -4,6 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-review

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

@@ -4,6 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-stack-scan
@@ -28,7 +29,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 +62,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 +102,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/skills/core/morph-standards/SKILL.md

@@ -4,6 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
+cliVersion: "7.2.0"
 ---
 
 # morph-standards

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.2.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/core/paths/output-schema.js

@@ -20,6 +20,11 @@ import { join } from 'path';
  *   phase        - The morph-spec phase that produces this output
  *   protected    - Whether the file requires an approval gate before editing
  *   approvalGate - (optional) Which gate protects this file
+ *   mutableFields- (optional) For protected JSON files: top-level array-item
+ *                  field names that MAY still change after the gate is approved.
+ *                  Lets the implement phase update task progress without
+ *                  unfreezing the plan contract. When present, the protect
+ *                  hook does a semantic diff instead of a blanket block.
  */
 export const OUTPUT_SCHEMA = {
   // 0-proposal/
@@ -36,7 +41,7 @@ export const OUTPUT_SCHEMA = {
   // 2-plan/
   spec:           { filename: 'spec.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
-  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
+  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan', mutableFields: ['status', 'outputs', 'notes'] },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
 
   // 3-implement/
@@ -119,6 +124,18 @@ export const PROTECTED_SPEC_FILES = Object.fromEntries(
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
+/**
+ * For protected files that carry mutable progress fields: filename → the
+ * top-level array-item fields that may change after the gate is approved.
+ * The protect-spec-files hook uses this to allow progress updates (e.g.
+ * task status) while still freezing the plan contract.
+ */
+export const MUTABLE_SPEC_FIELDS = Object.fromEntries(
+  Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields)
+    .map(([, entry]) => [entry.filename, entry.mutableFields])
+);
+
 // ============================================================================
 // Backwards-compat shim (will be removed in v5.1)
 // ============================================================================