@polymorphism-tech/morph-spec 7.3.0 → 7.5.0

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-brainstorming
@@ -87,6 +87,10 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
    const riskList = getRiskSignals(signals);
    ```
 
+   **Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
+   `gateDecisions.proposal = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
+   (Edit em `.morph/features/**` é permitido pela allowlist). O hook `gate-guard.js` confere depois se a ação (pausar vs auto-aprovar) bateu com esta decisão e avisa em divergência. Sem o registro o guard não verifica — não pule.
+
    **Se `pause === true`** (manual mode OU risco detectado em auto), use `AskUserQuestion`:
 
    ```
@@ -112,7 +116,7 @@ O harness conhece o stack por padrão. Não pergunte sobre tecnologia a menos qu
    **Riscos:** {principal} (sinais detectados: nenhum)
    ```
 
-   O hook state-sync.js detecta a aprovação automaticamente. Em modo auto sem AskUserQuestion, a skill atualiza `.morph/state.json` via Edit direto (allowlist permite — ver settings.local.json).
+   No caminho manual, o hook state-sync.js detecta a aprovação automaticamente (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em modo auto sem AskUserQuestion, aprove via `morph-spec approve {feature} proposal --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta 2-plan/) — nunca via Edit à mão de state.json.
 
 ## Output esperado
 - `.morph/features/{feature}/0-proposal/proposal.md` — proposta aprovada

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-eval
@@ -32,9 +32,8 @@ Também invocado ao receber o retorno de um sub-agent com auto-score < 7.
 4. Calcule o score composto: (arch × 0.30) + (contracts × 0.25) + (quality × 0.25) + (tests × 0.20).
 
 5. Aja conforme o score composto:
-   - **8-10:** Aprovado — nenhuma saída necessária no contexto, siga para próxima tarefa.
-   - **6-7.9:** Feedback priorizado — liste o que melhorar (bloqueantes primeiro), modelo continua.
-   - **< 6:** Escale para revisão humana — produza relatório detalhado com scores por dimensão e itens bloqueantes.
+   - **9-10:** Aprovado — nenhuma saída necessária no contexto, a task avança.
+   - **< 9:** Produza **feedback priorizado** (bloqueantes primeiro) — este feedback é a entrada do loop de correção autônomo da `morph-apply`: ela re-invoca `morph-implement` passando esse feedback para a próxima tentativa. NÃO escale ao humano aqui; a escalada só acontece quando o loop esgota 3 tentativas sem atingir 9. O feedback deve ser acionável (o que corrigir, onde), não só descritivo.
 
 6. Registre o score no recap.md da tarefa avaliada.
 
@@ -45,7 +44,7 @@ Também invocado ao receber o retorno de um sub-agent com auto-score < 7.
 
 ## Output esperado
 - Score composto 0-10 com scores por dimensão
-- Ação tomada com base no score (aprovado / feedback / escalado)
+- Ação tomada com base no score (aprovado em >=9 / feedback acionável para o loop em <9)
 - Entrada no recap.md com scores
 - Trace atualizado com `eval_score` e `eval_dimensions`
 

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-implement
@@ -18,26 +18,36 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
 
 ## O que fazer
 
-1. Leia o mandate.md em `.morph/features/{feature}/2-plan/mandate.md`.
-   Identifique os standards obrigatórios e patterns proibidos para esta feature.
+1. **Garanta que o conteúdo do plano está no seu contexto antes de implementar** — `mandate.md`, `spec.md` e `decisions.md` de `.morph/features/{feature}/2-plan/`. Se você não tem o conteúdo atual desses arquivos em contexto (sessão fresca / cold start de `/morph-apply`, ou conteúdo possivelmente desatualizado), **use a tool Read para carregá-los**: primeiro `mandate.md`, depois `spec.md`, depois `decisions.md`.
+
+   > Por que "garanta que está em contexto" e não "sempre Read": numa sessão quente, onde você acabou de escrever esses arquivos no mesmo turno, o conteúdo já está disponível e um Read seria redundante. Mas o contrato é o conteúdo estar em contexto — não confie em cache de turnos anteriores que pode ter sido truncado ou evictado. Na dúvida, Read. Nunca implemente sem o mandate em contexto.
+
+   Do `mandate.md`, identifique os standards obrigatórios e patterns proibidos. Do `spec.md`, a arquitetura e as seções de FRs referenciadas pela `description` da task corrente. Do `decisions.md`, as ADRs já registradas — para não contradizê-las nem re-decidir o que já foi decidido.
+
+   **Se a `morph-apply` passou `feedback` de uma tentativa anterior** (loop de correção — a task foi implementada mas o `morph-eval` deu score < 9): isto NÃO é uma implementação do zero. Leia o feedback priorizado, identifique os pontos bloqueantes listados, e **corrija especificamente esses pontos** no código já existente. Não reescreva o que já passou; foque no que o eval apontou. Registre no recap qual feedback foi endereçado em qual tentativa.
 
 2. Identifique o standard mais relevante para a tarefa atual:
    - Consulte `framework/standards/STANDARDS.json` — filtre por `category` e `tags`.
-   - Leia apenas o arquivo `.md` do standard identificado (campo `path` no JSON).
+   - **Use a tool Read no arquivo `.md` do standard identificado** (campo `path` no JSON) — não baste o digest do index; abra o arquivo. O index só diz que o standard existe; as convenções estão no `.md`.
+   - **Tarefas de agente de IA (MAF):** Read os `framework/standards/ai-agents/*.md` relevantes para a task. Mesmo que você consulte docs externas (context7) para a superfície da API do `Microsoft.Agents.AI`, as **convenções de projeto** (single-agent por padrão, provider/caching/observability, A2A, middleware) vêm desses standards. Uma fonte externa não as conhece.
    - Se nenhum standard cobrir o caso, registre no decisions.md e adote o critério mais conservador.
 
 3. Identifique a persona de agente adequada para a tarefa:
-   - Consulte `framework/agents.json` — encontre o agente cujo `domains` cobre o domínio da tarefa.
-   - Leia o campo `persona` do agente e adote esse ponto de vista durante a implementação.
+   - **Use a tool Read em `.morph/framework/agents.json`** — não recupere a persona de memória. O registro existe para ser consultado; pular o Read significa que a persona vira um rótulo inventado em vez de uma seleção auditável. Encontre o agente cujo `domains` cobre o domínio da tarefa.
+   - Leia o campo `persona` do agente e adote esse ponto de vista durante a implementação. O array `standards` desse agente é o ponto de partida para o passo 2.
+   - O `**Persona:**` que você grava no recap (passo 6) **deve** ser o `name` exato de um agente que existe em `agents.json` — é assim que o reviewer audita de qual ponto de vista a task foi feita. Uma persona que não casa com nenhum agente do registro é um sinal de que o consult não aconteceu.
 
-4. Avalie se a task se qualifica para sub-agent dispatch (ver critérios em `.morph/framework/MORPH.md` seção 6):
-   - Duração estimada > 5 minutos (effort L ou XL)
-   - Mais de 3 tentativas de correção falharam no mesmo problema
-   - Análise de arquivo com > 500 linhas
-   - Task repetitiva com > 3 instâncias do mesmo padrão
-   - Risco de contaminar o contexto principal com detalhes de baixo nível irrelevantes para o fluxo
+4. Decida se a task deve ser despachada para um sub-agent. Dispatch é o **default** para o caso pesado/multi-domínio (ver `.morph/framework/MORPH.md` seção 6) — despache quando a task dispara qualquer gatilho:
+   - **Domínio diferente do que você tem carregado agora** (a persona do passo 3 difere da que você vinha usando) — gatilho mais importante: o especialista carrega seus próprios standards sem inchar seu contexto.
+   - Esforço L ou XL (duração estimada > 5 minutos).
+   - Mais de 3 tentativas de correção falharam no mesmo problema.
+   - Análise de arquivo com > 500 linhas.
+   - Task repetitiva com > 3 instâncias do mesmo padrão.
+   - Risco de contaminar o contexto principal com detalhes de baixo nível irrelevantes para o fluxo.
 
-   **Se sim — despache sub-agent com este template:**
+   Inline é aceitável só para tasks S/M **dentro do domínio já carregado**. Se for inline numa task que dispara um gatilho, registre a justificativa em uma linha no `decisions.md` — inline silencioso numa task pesada/multi-domínio é o anti-padrão da seção 6.
+
+   **Se for despachar — use este template (passe a persona e o standard escopados, nunca um agente genérico sem contexto de domínio):**
    ```
    Implementar [ID]: [title da task]
 
@@ -57,12 +67,30 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    Se encontrar ambiguidade de escopo não coberta pelo mandate, registre no decisions.md
    e resolva da forma mais conservadora — não pause para perguntar, a menos que seja bloqueante.
 
-6. Ao concluir a tarefa, atualize `recap.md` em `.morph/features/{feature}/3-implement/`:
-   - ID da tarefa concluída
-   - O que foi feito (2-3 frases)
-   - Arquivos modificados
-   - Standard consultado
-   - Problemas encontrados e como foram resolvidos
+6. Ao concluir a tarefa, **append** um bloco a `recap.md` em `.morph/features/{feature}/3-implement/`
+   usando este template **obrigatório** (campos não-opcionais — sem standard, a entrada não conta):
+
+   ```markdown
+   ## T{N} — {title}
+
+   **Standard:** {standard-id} (`.morph/framework/standards/{path}.md`)
+   **Persona:** {agent-name}
+   **Files:**
+   - `{path}`
+   - `{path}`
+
+   {2-3 frases sobre o que foi feito}
+
+   **Issues encontrados:** {breve descrição ou "nenhum"}
+   ```
+
+   Regras:
+   - **Standard é obrigatório** — sempre referenciar pelo menos um standard de
+     `framework/standards/STANDARDS.json` que justificou as escolhas de implementação.
+     Se nenhum standard existente cobre, registre a decisão em `decisions.md` E cite
+     `Standard: ad-hoc (see decisions.md ADR-{N})` no recap.
+   - Sem standard ⇒ a task falha no validador de Gate 3 (`validate-completion`)
+     e o reviewer não consegue auditar de onde veio a decisão técnica.
 
 7. Registre a entrada no trace de execução em `.morph/traces/YYYY-MM-DD-{feature}-implement.json`:
    - Crie o arquivo se não existir (use o schema em `framework/evals/trace-schema.md`)
@@ -81,9 +109,10 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
 
    `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`…).
+   grava o arquivo inteiro (Write) e é o caminho mais simples; **uma `Edit` que mexe
+   só nesses campos mutáveis também é permitida** — o hook `protect-spec-files` faz
+   diff semântico e libera Write ou Edit desde que nenhum campo de contrato do plano
+   (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) mude.
 
 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.
 

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-plan
@@ -20,7 +20,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
 ## O que fazer
 
-1. Leia o `proposal.md` em `.morph/features/{feature}/0-proposal/` para entender escopo e critérios de aceite.
+1. **Garanta que `proposal.md` e `stack-scan.md` estão no seu contexto antes de planejar.** Se não tem o conteúdo atual em contexto (sessão fresca, ou conteúdo possivelmente desatualizado), **use a tool Read para carregá-los** — não confie em cache de turnos anteriores. Na dúvida, Read. `.morph/features/{feature}/0-proposal/proposal.md` (escopo, critérios de aceite, riscos) e `.morph/features/{feature}/0-proposal/stack-scan.md` (contexto técnico detectado: greenfield vs brownfield, stack atual, drift). Em brownfield, o stack-scan informa decisões de spec/mandate — não invente padrões que conflitam com o detectado.
 
 2. Produza `spec.md` em `.morph/features/{feature}/2-plan/`:
    - Arquitetura da solução: quais componentes, como se conectam, fluxos de dados principais.
@@ -37,6 +37,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
      - 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).
+   - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - 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`.
@@ -93,6 +94,10 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    const { pause, reason } = shouldPauseGate(config, signals);
    ```
 
+   **Persista a decisão no `feature.json` autoritativo da feature ANTES de apresentar ou auto-aprovar** — grave
+   `gateDecisions.plan = { pause, reason, signals, trust, decidedAt: <ISO> }` em `.morph/features/{feature}/feature.json`
+   (Edit em `.morph/features/**` é permitido pela allowlist). Isso deixa o raciocínio de trust auditável no disco: o hook `gate-guard.js` confere depois se a ação tomada (pausar vs auto-aprovar) bateu com esta decisão e avisa em caso de divergência. Sem este registro o guard não tem como verificar — não pule.
+
    **Se `pause === true`**, use `AskUserQuestion`:
 
    ```
@@ -116,14 +121,14 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    **Tasks:** {N} | Esforço total: {soma} | Caminho crítico: {IDs sem deps paralelas}
    ```
 
-   O hook state-sync registra a aprovação automaticamente em answers de AskUserQuestion. Em auto sem AskUserQuestion, a skill edita `state.json` diretamente.
+   No caminho manual, o hook state-sync registra a aprovação automaticamente em answers de AskUserQuestion (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} plan --mode auto` (ou `morph-spec advance {feature}` para já criar a pasta da próxima fase) — nunca via Edit à mão de state.json.
 
 ## Output esperado
 
 - `.morph/features/{feature}/2-plan/spec.md` — especificação técnica completa
 - `.morph/features/{feature}/2-plan/mandate.md` — contrato de implementação
 - `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema
-- Gate 2 marcado aprovado em `state.json`
+- Gate 2 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
 
 ## Referências
 
@@ -131,5 +136,6 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 - `.morph/framework/standards/STANDARDS.json` — para identificar standards relevantes ao mandate
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
 - `.morph/features/{feature}/0-proposal/proposal.md` — escopo da feature
+- `.morph/features/{feature}/0-proposal/stack-scan.md` — contexto técnico detectado
 - `src/lib/tasks/tasks-json-parser.js` — `validateTasksJson`, `writeTasksJson`
 - `src/lib/risk-detector.js` — `shouldPauseGate`, `getRiskSignals`

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-proposal
@@ -17,7 +17,7 @@ Conduzir uma feature do request inicial até o plano aprovado (Gate 2), sem inte
 
 - Usuário pede "use /morph-proposal {feature}" ou "vamos planejar {feature}".
 - Início de qualquer feature nova num projeto morph-spec.
-- Em sessões retomadas, antes de continuar uma feature em progresso, verificar via `.morph/state.json` se a feature já passou pelos Gates.
+- Em sessões retomadas, antes de continuar uma feature em progresso, verificar via `.morph/features/{feature-name}/feature.json` (estado autoritativo da feature) se ela já passou pelos Gates.
 
 ## Argumentos
 
@@ -82,11 +82,12 @@ Escopo: {incluído} | Excluído: {exclusões}
 Stack: {compliance}
 ```
 
-O hook `state-sync.js` registra a aprovação automaticamente via PostToolUse em AskUserQuestion. Quando auto-aprovado, marcar manualmente:
+No caminho manual, o hook `state-sync.js` registra a aprovação automaticamente via PostToolUse quando a `AskUserQuestion` é respondida com "aprovado" (grava o gate no `feature.json` autoritativo, `approvedBy: "manual"`). Em `trust: auto` (sem AskUserQuestion), **aprove via CLI — nunca via Edit à mão de state.json**:
 
-```js
-// auto-aprovação: o hook detecta "aprovado" no answer label, mas em auto-mode
-// não há AskUserQuestion. Skill atualiza .morph/state.json via Edit fallback.
+```
+morph-spec approve {feature} proposal --mode auto
+# ou, para já aprovar o Gate 1 e criar a pasta 2-plan/ num passo só:
+morph-spec advance {feature}
 ```
 
 ### 4. Verificar retomada antes de morph-plan
@@ -128,7 +129,7 @@ Lógica idêntica ao passo 3 (`shouldPauseGate` + AskUserQuestion ou auto-aprova
 - `.morph/features/{feature}/2-plan/spec.md`
 - `.morph/features/{feature}/2-plan/mandate.md`
 - `.morph/features/{feature}/2-plan/tasks.json`
-- Gates 1 e 2 marcados aprovados em `.morph/state.json` (via hook state-sync).
+- Gates 1 e 2 registrados aprovados em `.morph/features/{feature}/feature.json` (autoritativo) — via `morph-spec approve`/`morph-spec advance` em auto, ou via hook state-sync no caminho manual.
 
 ## Referências
 

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-review
@@ -19,11 +19,14 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
 ## O que fazer
 
-1. Leia o mandate.md em `.morph/features/{feature}/2-plan/mandate.md`.
-   Liste os critérios de done, standards obrigatórios e patterns proibidos.
+1. **Garanta que todos os artefatos de plano estão no seu contexto antes de revisar.** Se você não tem o conteúdo atual em contexto (sessão fresca, ou conteúdo possivelmente desatualizado), **use a tool Read para carregá-los** — não confie em cache de turnos anteriores que pode ter sido truncado ou evictado. Na dúvida, Read:
+   - `.morph/features/{feature}/2-plan/mandate.md` — critérios de done, standards obrigatórios, patterns proibidos.
+   - `.morph/features/{feature}/2-plan/spec.md` — arquitetura, FRs/NFRs, contratos esperados.
+   - `.morph/features/{feature}/2-plan/decisions.md` (se existir) — ADRs que devem ter sido seguidos pela implementação. Use para validar coerência entre decisão registrada e código produzido.
 
-2. Leia o recap.md em `.morph/features/{feature}/3-implement/recap.md`.
-   Verifique se todas as tarefas têm entrada e se os problemas foram resolvidos.
+   > O contrato é o conteúdo estar em contexto, não o número de chamadas a Read. Numa sessão quente onde você acabou de produzir esses artefatos, eles já estão disponíveis. Mas uma revisão sem o mandate em contexto não é uma revisão — é um chute. Nunca produza o review-report sem ter o mandate, spec e decisions disponíveis.
+
+2. **Use a tool Read em `.morph/features/{feature}/3-implement/recap.md`**. Verifique se todas as tarefas têm entrada e se os problemas foram resolvidos.
 
 3. Para cada critério do mandate.md, verifique se foi atendido:
    - Se atendido: registre como "aprovado" com evidência (arquivo ou comportamento).
@@ -39,8 +42,10 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    - Lista de melhorias recomendadas (não bloqueantes)
    - Recomendação final: Aprovado / Rejeitar com condições / Reprovar
 
-6. Se houver itens bloqueantes (score < 6 em qualquer dimensão bloqueante), corrija antes
+6. Se houver itens bloqueantes (score < 8 em qualquer dimensão bloqueante), corrija antes
    de apresentar o review-report.md ao usuário. Não abra o Gate 3 com bloqueantes em aberto.
+   (A barra de avanço por task é 9; uma dimensão individual abaixo de 8 no review da feature
+   inteira é um bloqueante crítico que o loop de correção deveria ter pego.)
 
 7. Finalize o trace de execução em `.morph/traces/YYYY-MM-DD-{feature}-implement.json`:
    - Preencha `phase_summary.tasks_completed`, `tasks_failed`, `avg_eval_score`
@@ -83,17 +88,19 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    **Recomendação:** Aprovado
    ```
 
-   O hook state-sync detecta a aprovação em answers de AskUserQuestion e marca `features[X].approvalGates.review = true`. Em auto sem AskUserQuestion, a skill atualiza state.json direto.
+   No caminho manual, o hook state-sync detecta a aprovação em answers de AskUserQuestion e grava `approvalGates.review = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo da feature. Em auto sem AskUserQuestion, aprove via `morph-spec approve {feature} review --mode auto` — nunca via Edit à mão de state.json.
 
 ## Output esperado
 - `.morph/features/{feature}/4-review/review-report.md` com scores e recomendação
 - Trace da fase com `phase_summary` preenchido
-- Gate 3 marcado aprovado em state.json (auto ou manual)
+- Gate 3 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo), na forma canônica `{ approved, timestamp, approvedBy }` — via `morph-spec approve` em auto, ou pelo hook state-sync no caminho manual
 
 ## Referências
 - `.morph/framework/MORPH.md` — seção 5 (Gate 3), seção 1 (papel Evaluator), Trust Mode
 - `framework/skills/core/morph-eval/SKILL.md` — para calcular scores por dimensão
 - `.morph/framework/evals/trace-schema.md` — formato canônico do trace
 - `.morph/features/{feature}/2-plan/mandate.md` — critérios de done da feature
+- `.morph/features/{feature}/2-plan/spec.md` — arquitetura e contratos
+- `.morph/features/{feature}/2-plan/decisions.md` — ADRs registrados (se existir)
 - `.morph/features/{feature}/3-implement/recap.md` — registro de execução
 - `src/lib/risk-detector.js` — `shouldPauseGate` para Gate 3

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-stack-scan

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

@@ -4,7 +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.3.0"
+cliVersion: "7.5.0"
 ---
 
 # morph-standards