@polymorphism-tech/morph-spec 7.3.0 → 7.4.0

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

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.4.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 em `state.json` ANTES de apresentar ou auto-aprovar** — grave
+   `features[feature].gateDecisions.plan = { pause, reason, signals, trust, decidedAt: <ISO> }`
+   (Edit em `.morph/state.json` é permitido). 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`:
 
    ```
@@ -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.4.0"
 ---
 
 # morph-proposal

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.4.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`
@@ -95,5 +100,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 - `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.4.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.4.0"
 ---
 
 # morph-standards