@polymorphism-tech/morph-spec 6.0.0 → 7.0.0

package/README.md

@@ -67,11 +67,11 @@ your-project/
 │   ├── context/                     # Project context (README.md, standards.md)
 │   ├── features/                    # Active features
 │   │   └── {feature}/
-│   │       ├── 0-proposal/          # User story + acceptance criteria
-│   │       ├── 1-ui/                # UI/UX design (optional, UI-heavy features)
-│   │       ├── 2-design/            # Technical spec, contracts, decisions
-│   │       ├── 3-tasks/             # Atomic task list
-│   │       └── 4-implement/         # Recap and implementation notes
+│   │       ├── 0-proposal/          # Problem statement + acceptance criteria
+│   │       ├── 1-design/            # UI/UX design (optional, UI-heavy features)
+│   │       ├── 2-plan/              # spec.md + mandate.md + tasks.json
+│   │       ├── 3-implement/         # Recap and implementation notes
+│   │       └── 4-review/            # Review report + Gate 3
 │   └── state.json                   # READ-ONLY — managed by CLI only
 └── .claude/
     ├── commands/                    # Slash commands
@@ -88,29 +88,30 @@ your-project/
 Features move through structured phases. Some are optional depending on feature type.
 
 ```
-proposal → [uiux] → design → plan → tasks → implement → [sync]
+proposal → [design] → plan → implement → review
 ```
 
-Phases in brackets are optional. `uiux` applies to UI-heavy features. `sync` is a post-implementation reconciliation step.
+`design` is optional — applies only to UI-heavy features.
 
 ### Phase outputs
 
 
-| Phase     | Directory      | Key files                                                     |
-| --------- | -------------- | ------------------------------------------------------------- |
-| Proposal  | `0-proposal/`  | `proposal.md`                                                 |
-| UI/UX     | `1-ui/`        | `design-system.md`, `mockups.md`, `components.md`, `flows.md` |
-| Design    | `2-design/`    | `spec.md`, `contracts.cs`, `decisions.md`                     |
-| Plan      | `3-plan/`      | `plan.md`                                                     |
-| Tasks     | `4-tasks/`     | `tasks.md`                                                    |
-| Implement | `5-implement/` | `recap.md`                                                    |
+| Phase     | Directory       | Key files                                                          |
+| --------- | --------------- | ------------------------------------------------------------------ |
+| Proposal  | `0-proposal/`   | `proposal.md`, `stack-scan.md`, `migration-plan.md` (optional)     |
+| Design    | `1-design/`     | `design-system.md`, `mockups.md`, `components.md`, `flows.md`      |
+| Plan      | `2-plan/`       | `spec.md`, `mandate.md`, `tasks.json`, `decisions.md`              |
+| Implement | `3-implement/`  | `recap.md` + source code                                           |
+| Review    | `4-review/`     | `review-report.md`                                                 |
 
 
 ### Approval gates
 
-- **Design gate** — Spec must be approved before moving to Plan.
-- **Plan gate** — Plan must be approved before moving to Tasks.
-- **Tasks gate** — Task list must be approved before implementation starts.
+- **Gate 1 (Proposal)** — Problem statement must be approved before plan.
+- **Gate 2 (Plan)** — Spec + mandate + tasks must be approved before implement.
+- **Gate 3 (Review)** — Review report must be approved before archive.
+
+In `trust: "auto"` mode (default), gates auto-pass without risk signals. See `framework/MORPH.md` for risk-signal details.
 
 Check gate status:
 

package/docs/CHEATSHEET.md

@@ -25,11 +25,11 @@ Phases in brackets are optional.
 | Phase | Directory | Output files | Gate |
 |-------|-----------|--------------|------|
 | proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
-| uiux *(optional)* | `1-ui/` | `design-system.md`, `mockups.md`, `components.md`, `flows.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 | `5-implement/` | code + `recap.md` | — |
+| implement | `3-implement/` | code + `recap.md` | — |
 | sync *(optional)* | — | standards updated | — |
 
 ---
@@ -154,7 +154,7 @@ morph-spec approval-status {feature}           # show gate status
 ├── features/
 │   └── {feature}/
 │       ├── 0-proposal/proposal.md
-│       ├── 1-ui/design-system.md, mockups.md, components.md, flows.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

package/docs/QUICKSTART.md

@@ -57,10 +57,10 @@ Loads project context from `.morph/context/`, confirms stack and active agents.
 ### Phase 2 — UI/UX (conditional)
 
 Only runs if frontend agents are active. Claude generates:
-- `1-ui/design-system.md` — colors, typography, spacing
-- `1-ui/mockups.md` — ASCII wireframes
-- `1-ui/components.md` — component specs
-- `1-ui/flows.md` — user flows and edge cases
+- `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.
 

package/framework/CLAUDE.md

@@ -52,4 +52,17 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 7 personas de domínio dispatchávels via Agent tool:
 `dotnet-senior`, `ef-modeler`, `maf-expert`, `nextjs-expert`, `ui-designer`, `infra-engineer`, `evaluator`.
 
+## Regra de precedência de skills
+
+Em projetos morph-spec, prefira as skills `morph-*` sobre as equivalentes `superpowers:*`:
+
+| Em vez de | Use |
+|-----------|-----|
+| `superpowers:brainstorming` | `morph-brainstorming` |
+| `superpowers:writing-plans` | `morph-plan` |
+| `superpowers:executing-plans` | `morph-apply` |
+| `superpowers:test-driven-development` | seguir `mandate.md` (TDD está embutido) |
+
+As skills `morph-*` aplicam Gates, leem o estado da feature em `.morph/` e produzem outputs com os paths corretos. As `superpowers:*` são genéricas e não conhecem o contexto morph-spec.
+
 *MORPH-SPEC v5 by Polymorphism Tech*

package/framework/MORPH.md

@@ -15,7 +15,7 @@ Entre gates, você opera com autonomia total. O dev valida. Você executa.
 | Situação                                                              | O que você faz                                                                |
 |-----------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | Gate 1 / 2 / 3 aprovado                                               | Avançar para próxima fase imediatamente                                       |
-| Tarefa completada na fase implement                                   | Iniciar a próxima tarefa do tasks.md sem aguardar instrução                   |
+| Tarefa completada na fase implement                                   | Iniciar a próxima task do tasks.json sem aguardar instrução                   |
 | Ambiguidade de escopo coberta pelo mandate                            | Resolver conservadoramente e registrar em decisions.md                        |
 | Ambiguidade bloqueante (requisito ausente ou contraditório)           | UMA pergunta via AskUserQuestion                                              |
 | Sub-agent com auto-score ≥ 7                                          | Integrar ao recap.md e continuar                                              |
@@ -76,14 +76,14 @@ Os papéis não são exclusivos — numa sessão longa você transita entre Orch
 
 O fluxo padrão de uma feature tem quatro fases. Cada fase tem uma pasta dedicada em `.morph/features/{feature}/`.
 
-| Fase        | Pasta          | Gate              | O que termina a fase                          |
-|-------------|----------------|-------------------|-----------------------------------------------|
-| proposal    | `0-proposal/`  | Aprovação humana  | `proposal.md` aprovado e commitado            |
-| plan        | `2-plan/`      | Aprovação humana  | `spec.md`, `mandate.md`, `tasks.md` aprovados |
-| implement   | `3-implement/` | Nenhum            | Todas as tarefas do tasks.md com status Done  |
-| review      | `4-review/`    | Aprovação humana  | `review-report.md` aprovado e commitado       |
+| Fase        | Pasta          | Gate                  | O que termina a fase                            |
+|-------------|----------------|-----------------------|-------------------------------------------------|
+| proposal    | `0-proposal/`  | Gate 1 (trust-aware)  | `proposal.md` aprovado e commitado              |
+| plan        | `2-plan/`      | Gate 2 (trust-aware)  | `spec.md`, `mandate.md`, `tasks.json` aprovados |
+| implement   | `3-implement/` | Nenhum                | Todas as tasks do tasks.json com status `done`  |
+| review      | `4-review/`    | Gate 3 (trust-aware)  | `review-report.md` aprovado e commitado         |
 
-A fase `1-ui/` (design system, mockups, flows) é opcional — aplica-se apenas a features com componentes de UI novos e deve ser explicitamente requisitada pelo usuário.
+A fase `1-design/` (design system, mockups, flows) é opcional — aplica-se apenas a features com componentes de UI novos e deve ser explicitamente requisitada pelo usuário.
 
 Não avance de fase sem o gate correspondente ter sido confirmado.
 
@@ -104,7 +104,7 @@ Não invente caminhos alternativos.
 
 - `mandate.md` — contrato de implementação: stack exata, standards obrigatórios (com links), patterns explicitamente proibidos, checklist de done com critérios verificáveis. O mandate.md é lido no início de cada tarefa de implementação — deve ser específico o suficiente para resolver ambiguidades sem consultar o Orchestrator.
 
-- `tasks.md` — lista ordenada de tarefas com IDs únicos (T1, T2...), dependências explícitas entre tarefas, estimativa de esforço, critério de done verificável por tarefa. Cada entrada no recap.md deve referenciar um ID do tasks.md.
+- `tasks.json` — task list estruturada validada contra `framework/schemas/tasks.schema.json`. Cada task tem `id` (T1, T2...), `title`, `description`, `dependencies` (array de IDs), `effort` (S/M/L/XL), `doneCriteria`, `status` (pending/in_progress/done/skipped/blocked) e `outputs` (paths esperados). Cada entrada no recap.md deve referenciar um ID do tasks.json.
 
 - `decisions.md` — log de decisões técnicas: qual era a alternativa, por que foi descartada, quem decidiu. Criado quando surgir a primeira decisão não trivial. Não é obrigatório — só existe se houver decisões que precisam de rastreabilidade.
 
@@ -148,29 +148,42 @@ O agente responsável por um domínio está listado em `framework/agents.json`.
 
 ---
 
-## 5. Gates de Aprovação
+## 5. Gates de Aprovação (Trust Mode)
 
-Gates são pontos obrigatórios de pausa. Não avance sem confirmação humana explícita.
+Gates são pontos de **pausa potencial**. Em `trust: "auto"` (default), gates **auto-passam** se nenhum sinal de risco for detectado — apenas exibem um summary curto. Em `trust: "manual"` OU se um sinal de risco fizer fire, o gate pausa via `AskUserQuestion` com options padrão:
 
-**Gate 1 — Proposta aprovada**
-Condição: o usuário leu e aprovou o `proposal.md`.
-Como ativar: apresente o proposal, aguarde resposta explícita ("aprovado", "pode avançar", "lgtm" ou equivalente).
-Nunca assuma aprovação silenciosa. Se o usuário responder com uma pergunta, responda a pergunta e reapresente o gate.
-Sinal de gate aberto: resposta que confirma que pode avançar para o planejamento.
+```
+- "aprovado, prosseguir"
+- "preciso ajustar"
+- "cancelar feature"   (Gate 3 usa "rollback" em vez de "cancelar")
+```
 
-**Gate 2 — Plano aprovado**
-Condição: o usuário leu e aprovou `spec.md`, `mandate.md` e `tasks.md`.
-Como ativar: use o template de apresentação do Gate 2 em `framework/skills/core/morph-plan/SKILL.md` passo 5. Apresente o gate completo — spec em uma frase, mandate resumido, tasks com estimativa, decisões de arquitetura se houver.
-Se o usuário pedir ajustes, aplique e reapresente o gate completo antes de avançar.
-Sinal de gate aberto: aprovação explícita de todos os três artefatos, ou "pode implementar".
-Atenção: aprovação parcial ("o spec está bom") não abre o gate — todos os três precisam ser confirmados.
+**Sinais de risco que forçam pausa em auto** (detectados via `src/lib/risk-detector.js`):
 
-**Gate 3 — Review aprovado**
-Condição: o usuário leu e aprovou o `review-report.md`.
-Como ativar: apresente o relatório com scores e feedback. Se houver itens bloqueantes (score < 6), não apresente o gate — corrija primeiro, reavalite, então apresente o relatório final.
-Sinal de gate aberto: aprovação do review-report.md com ciência dos scores.
+| Sinal | Threshold | Quando aplica |
+|-------|-----------|---------------|
+| `designSystemDivergence` | true | Brainstorming detecta fontes conflitantes (spec antigo vs bundle local) |
+| `standardsViolations` | array.length > 0 | Mandate ou implementation viola padrões proibidos |
+| `evalScore` | < 8 | morph-eval/morph-review produz score abaixo do mínimo |
+| `taskCount` | > 20 | Escopo grande — provavelmente vale revisar antes de implementar |
 
-**Comportamento padrão fora de gate:** trabalhe com autonomia total. Gates só existem nestes três pontos. Não pause para confirmação no meio de implementação a menos que encontre uma ambiguidade de escopo que o mandate não cobre — nesse caso, registre a ambiguidade no decisions.md, resolva da forma mais conservadora possível, e sinalize na entrega da tarefa.
+**Gate 1 — Proposta**
+- Sinais: `designSystemDivergence`, `standardsViolations` (improvável).
+- Skill responsável: `morph-brainstorming`.
+
+**Gate 2 — Plano**
+- Sinais: todos do Gate 1 + `taskCount`, `standardsViolations` em mandate.
+- Skill responsável: `morph-plan`.
+
+**Gate 3 — Review**
+- Sinais: `evalScore` composite, `standardsViolations` detectadas em implementation.
+- Skill responsável: `morph-review`.
+
+Para alterar o modo: editar `.morph/config/config.json → trust` (`"auto"` ou `"manual"`). Configs sem o campo `trust` defaultam para `"auto"`.
+
+**Comportamento padrão fora de gate:** trabalhe com autonomia total. Gates só existem nestes três pontos. Não pause para confirmação no meio de implementação a menos que encontre uma ambiguidade de escopo que o mandate não cobre — nesse caso, registre a ambiguidade no decisions.md, resolva da forma mais conservadora possível, e sinalize na entrega da task.
+
+**O hook state-sync.js** detecta as respostas dos Gates automaticamente: quando uma `AskUserQuestion` é respondida com label começando em "aprovado", marca o gate correspondente em `.morph/state.json`. Em modo auto sem AskUserQuestion, a skill atualiza state.json diretamente (allowlist permite Edit em `.morph/state.json`).
 
 ---
 
@@ -219,15 +232,23 @@ O padrão de dispatch e o template de prompt para sub-agents estão detalhados e
 Skills são documentos de instrução que você invoca sob demanda. Eles ficam em `framework/skills/core/`.
 Não invoque uma skill fora do momento indicado.
 
-| Skill                 | Path                                               | Quando invocar                                              |
-|-----------------------|----------------------------------------------------|-------------------------------------------------------------|
-| morph-brainstorming   | `framework/skills/core/morph-brainstorming/SKILL.md` | Ao receber um novo request de feature (antes de morph-plan) |
-| morph-stack-scan      | `framework/skills/core/morph-stack-scan/SKILL.md`  | Em projetos existentes, para detectar desvios de stack      |
-| morph-plan            | `framework/skills/core/morph-plan/SKILL.md`        | Ao iniciar a fase de planejamento                           |
-| morph-implement       | `framework/skills/core/morph-implement/SKILL.md`   | Ao iniciar cada tarefa de implementação                     |
-| morph-eval            | `framework/skills/core/morph-eval/SKILL.md`        | Após concluir uma tarefa ou fase                            |
-| morph-review          | `framework/skills/core/morph-review/SKILL.md`      | Ao iniciar a fase de revisão                                |
-| morph-standards       | `framework/skills/core/morph-standards/SKILL.md`   | Quando precisar localizar ou aplicar um standard específico |
+| Skill                 | Path                                               | Quando invocar                                                          |
+|-----------------------|----------------------------------------------------|-------------------------------------------------------------------------|
+| **morph-proposal**    | `framework/skills/core/morph-proposal/SKILL.md`    | **Orquestrador**: brainstorming → Gate 1 → plan → Gate 2 (entry point) |
+| **morph-apply**       | `framework/skills/core/morph-apply/SKILL.md`       | **Orquestrador**: DAG-adaptive implement loop → review → Gate 3        |
+| morph-brainstorming   | `framework/skills/core/morph-brainstorming/SKILL.md` | Invocada pela morph-proposal — entendimento de negócio + stack-scan    |
+| morph-stack-scan      | `framework/skills/core/morph-stack-scan/SKILL.md`  | Detecta stack atual; curto-circuita em greenfield                       |
+| morph-plan            | `framework/skills/core/morph-plan/SKILL.md`        | Invocada pela morph-proposal — produz spec/mandate/tasks.json           |
+| morph-implement       | `framework/skills/core/morph-implement/SKILL.md`   | Invocada pela morph-apply — executa cada task                           |
+| morph-eval            | `framework/skills/core/morph-eval/SKILL.md`        | Após concluir uma task ou fase                                          |
+| morph-review          | `framework/skills/core/morph-review/SKILL.md`      | Invocada pela morph-apply — produz review-report + Gate 3               |
+| morph-standards       | `framework/skills/core/morph-standards/SKILL.md`   | Quando precisar localizar ou aplicar um standard específico             |
+
+**Entry points** para o usuário:
+- `/morph-proposal {feature}` → invoca `Skill(morph-proposal)`, que orquestra brainstorming + plan
+- `/morph-apply {feature}` → invoca `Skill(morph-apply)`, que orquestra implement + review
+
+Os slash commands são atalhos: o agente pode chamar `Skill(morph-proposal)` diretamente quando o usuário pede "use /morph-proposal".
 
 Cada skill contém instruções de execução passo a passo. Leia, siga, não desvie sem justificativa registrada no recap.md.
 

package/framework/commands/morph-apply.md

@@ -6,7 +6,9 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, Skil
 
 # /morph-apply — NLH Implementation
 
-Executa as tarefas do `tasks.md` em sequência sem pausa, depois apresenta o Gate 3.
+Executa as tasks de uma feature até o Gate 3.
+
+**Implementação:** este slash command é um atalho. O agente deve invocar `Skill(morph-apply)` com o nome da feature. A skill decide adaptativamente entre execução sequencial (auto-advance entre tasks) ou paralela (Agent dispatch para tasks independentes) baseado no DAG do `tasks.json`. Termina com `morph-review` + Gate 3 trust-aware.
 
 ## Argumentos
 
@@ -17,29 +19,10 @@ Executa as tarefas do `tasks.md` em sequência sem pausa, depois apresenta o Gat
 Antes de começar, verifique:
 - `.morph/features/{feature-name}/2-plan/spec.md` existe
 - `.morph/features/{feature-name}/2-plan/mandate.md` existe
-- `.morph/features/{feature-name}/2-plan/tasks.md` existe
-- `.morph/features/{feature-name}/3-implement/recap.md` existe ou pode ser criado
+- `.morph/features/{feature-name}/2-plan/tasks.json` existe e é válido contra o schema
 
 Se algum estiver faltando, abortar e pedir ao usuário para rodar `/morph-proposal {feature-name}` primeiro.
 
-## Fluxo
-
-1. **Loop de tarefas** — para cada tarefa pendente em `tasks.md`:
-   - Invocar a skill `morph-implement` em `framework/skills/core/morph-implement/`.
-   - A skill executa a tarefa, registra em `recap.md`, atualiza o trace.
-   - **Auto-advance:** ao concluir uma tarefa, passar imediatamente para a próxima sem aguardar instrução do usuário.
-   - Pausar apenas se encontrar ambiguidade bloqueante não coberta pelo `mandate.md`.
-
-2. **Após todas as tarefas concluídas, invocar `morph-review`** (skill em `framework/skills/core/morph-review/`):
-   - Lê `mandate.md` e `recap.md`.
-   - Aplica `morph-eval` para gerar scores por dimensão.
-   - Produz `review-report.md` em `.morph/features/{feature-name}/4-review/`.
-   - Apresenta o **Gate 3**.
-
-3. **Aguardar aprovação do Gate 3.**
-   - Resposta válida: "aprovado", "merge".
-   - Se houver itens bloqueantes (score < 6): corrija antes de apresentar o gate.
-
 ## Anti-padrões
 
 - Não pausar entre tarefas para confirmação — o tasks.md já foi aprovado no Gate 2.

package/framework/commands/morph-archive.md

@@ -30,7 +30,7 @@ If any precondition fails, stop and report what is missing instead of archiving.
    .morph/features/{feature}/  →  .morph/archive/{feature}/
    ```
    Use `Bash` (`mv` on POSIX, `Move-Item` on Windows). Preserve all phase subfolders
-   (`0-proposal/`, `1-ui/`, `2-plan/`, `3-implement/`, `4-review/`).
+   (`0-proposal/`, `1-design/`, `2-plan/`, `3-implement/`, `4-review/`).
 
 3. **Update state.json**:
    - Set `features[name].status = 'completed'`

package/framework/commands/morph-proposal.md

@@ -8,6 +8,8 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, Skil
 
 Conduz a feature do request inicial até o Gate 2 (plano aprovado), sem intervenção do usuário entre os gates.
 
+**Implementação:** este slash command é um atalho. O agente deve invocar `Skill(morph-proposal)` com o nome da feature como argumento. A skill encadeia automaticamente `morph-brainstorming` → Gate 1 → `morph-plan` → Gate 2. Em `trust: "auto"` (default), gates auto-passam sem sinais de risco.
+
 ## Argumentos
 
 `{feature-name}` — nome em kebab-case da feature.

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -7,7 +7,7 @@
  *
  * Ensures writes to .morph/features/{feature}/ go to the current phase's subfolder:
  *   proposal → only 0-proposal/
- *   uiux → only 1-ui/
+ *   uiux → only 1-design/
  *   plan → only 2-plan/
  *   implement → 3-implement/ + any source code (unrestricted)
  *   review → only 4-review/

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

@@ -7,7 +7,7 @@
  *
  * 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-ui/design-system.md, etc. → blocked if 'uiux' gate approved
+ *   - 1-design/design-system.md, etc. → blocked if 'uiux' gate approved
  *
  * Fail-open: exits 0 on any error.
  */

package/framework/hooks/claude-code/core/state-sync.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * state-sync.js — PostToolUse hook
+ *
+ * Keeps .morph/state.json in sync with the agent's actions, without requiring
+ * the agent to think about state. Fail-open: any error returns {} silently.
+ *
+ * Triggers:
+ *  - Write/Edit of .morph/features/{feature}/0-proposal/proposal.md  → register feature
+ *  - Write/Edit of .morph/features/{feature}/{phase}/{output}        → mark output created
+ *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
+ */
+
+import { readFileSync, existsSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { loadState, stateExists } from '../../shared/state-reader.js';
+
+const STATE_FILE = '.morph/state.json';
+
+const PHASE_FOLDERS = {
+  '0-proposal': 'proposal',
+  '1-design': 'design',
+  '1-ui': 'uiux', // legacy alias — still recognized during folder transition
+  '2-plan': 'plan',
+  '3-implement': 'implement',
+  '4-review': 'review',
+  '5-implement': 'implement', // legacy alias
+};
+
+function exit(output = {}) {
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function extractFeatureName(filePath) {
+  if (!filePath) return null;
+  const normalized = String(filePath).replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+function extractPhaseFolder(filePath) {
+  if (!filePath) return null;
+  const normalized = String(filePath).replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/[^/]+\/([^/]+)\//);
+  if (!match) return null;
+  return PHASE_FOLDERS[match[1]] ?? null;
+}
+
+function extractFilename(filePath) {
+  const normalized = String(filePath).replace(/\\/g, '/');
+  return normalized.split('/').pop();
+}
+
+/**
+ * Atomic write — temp file then rename. Mirrors state-manager.js semantics.
+ */
+function writeStateAtomic(cwd, state) {
+  const path = join(cwd, STATE_FILE);
+  const tmpPath = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+  renameSync(tmpPath, path);
+}
+
+function registerFeatureIfMissing(state, featureName) {
+  if (!state.features) state.features = {};
+  if (state.features[featureName]) return false;
+
+  const now = new Date().toISOString();
+  state.features[featureName] = {
+    status: 'in_progress',
+    createdAt: now,
+    updatedAt: now,
+    approvalGates: { proposal: false, plan: false, review: false },
+    outputs: {},
+  };
+
+  if (!state.metadata) state.metadata = {};
+  state.metadata.totalFeatures = Object.keys(state.features).length;
+  return true;
+}
+
+function trackOutput(state, featureName, filePath) {
+  const filename = extractFilename(filePath);
+  const feature = state.features[featureName];
+  if (!feature) return false;
+  feature.outputs ??= {};
+  const normalizedPath = String(filePath).replace(/\\/g, '/');
+  const wasMissing = !feature.outputs[filename]?.created;
+  feature.outputs[filename] = {
+    created: true,
+    path: normalizedPath,
+  };
+  feature.updatedAt = new Date().toISOString();
+  return wasMissing;
+}
+
+function findActiveFeature(state) {
+  if (!state.features) return null;
+  const entries = Object.entries(state.features);
+  const active = entries.find(([, f]) => f.status === 'in_progress');
+  if (active) return active[0];
+  return entries[0]?.[0] ?? null;
+}
+
+function isApprovalAnswer(answer) {
+  if (typeof answer !== 'string') return false;
+  const lower = answer.toLowerCase();
+  return (
+    lower.startsWith('aprovado') ||
+    lower.includes('pode avan') ||
+    lower.includes('pode implementar') ||
+    lower.includes('pode prosseguir')
+  );
+}
+
+function gateFromQuestion(question) {
+  if (typeof question !== 'string') return null;
+  const lower = question.toLowerCase();
+  if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
+  if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';
+  if (lower.includes('gate 3') || lower.includes('review')) return 'review';
+  return null;
+}
+
+function handleWriteEdit(input, cwd) {
+  const filePath = input.tool_input?.file_path;
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) return false;
+
+  const state = loadState(cwd);
+  if (!state) return false;
+
+  let changed = registerFeatureIfMissing(state, featureName);
+  const phase = extractPhaseFolder(filePath);
+  if (phase) {
+    const outputChanged = trackOutput(state, featureName, filePath);
+    changed = changed || outputChanged;
+  }
+
+  if (changed) {
+    writeStateAtomic(cwd, state);
+  }
+  return true;
+}
+
+function handleAskUserQuestion(input, cwd) {
+  const answers = input.tool_response?.answers ?? input.tool_response?.responses ?? {};
+  if (typeof answers !== 'object' || answers === null) return false;
+
+  const state = loadState(cwd);
+  if (!state) return false;
+
+  const featureName = findActiveFeature(state);
+  if (!featureName) return false;
+
+  let changed = false;
+  for (const [question, answer] of Object.entries(answers)) {
+    if (!isApprovalAnswer(answer)) continue;
+    const gate = gateFromQuestion(question);
+    if (!gate) continue;
+
+    state.features[featureName].approvalGates ??= {};
+    if (state.features[featureName].approvalGates[gate] !== true) {
+      state.features[featureName].approvalGates[gate] = true;
+      state.features[featureName].updatedAt = new Date().toISOString();
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    writeStateAtomic(cwd, state);
+  }
+  return true;
+}
+
+async function main() {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) {
+    exit();
+    return;
+  }
+
+  const input = readStdin();
+  const toolName = input.tool_name;
+
+  try {
+    if (toolName === 'Write' || toolName === 'Edit') {
+      handleWriteEdit(input, cwd);
+    } else if (toolName === 'AskUserQuestion') {
+      handleAskUserQuestion(input, cwd);
+    }
+  } catch {
+    // fail-open
+  }
+
+  exit();
+}
+
+main().catch(() => exit());

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

@@ -8,15 +8,16 @@
  */
 
 /** Phase order */
-export const PHASE_ORDER = ["proposal","uiux","plan","implement","review"];
+export const PHASE_ORDER = ["proposal","uiux","plan","implement","review","sync"];
 
 /** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
   proposal: '0-proposal',
-  uiux: '1-ui',
+  uiux: '1-design',
   plan: '2-plan',
   implement: '3-implement',
   review: '4-review',
+  sync: '3-implement',
 };
 
 /** Map output type (camelCase) → phase that produces it */
@@ -47,7 +48,7 @@ export const FILENAME_TO_OUTPUT = {
   'flows.md': 'uiFlows',
   'spec.md': 'spec',
   'mandate.md': 'mandate',
-  'tasks.md': 'tasks',
+  'tasks.json': 'tasks',
   'decisions.md': 'decisions',
   'recap.md': 'recap',
   'review-report.md': 'reviewReport',
@@ -61,7 +62,7 @@ export const PROTECTED_SPEC_FILES = {
   'flows.md': 'uiux',
   'spec.md': 'plan',
   'mandate.md': 'plan',
-  'tasks.md': 'plan',
+  'tasks.json': 'plan',
 };
 
 /**

package/framework/hooks/shared/state-reader.js

@@ -110,7 +110,7 @@ export function derivePhaseForFeature(featureName, projectPath) {
     ['4-review', 'review'],
     ['3-implement', 'implement'],
     ['2-plan', 'plan'],
-    ['1-ui', 'uiux'],
+    ['1-design', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
   for (const [folder, phase] of phaseMap) {

package/framework/phases.json

@@ -21,7 +21,7 @@
     "uiux": {
       "id": "uiux",
       "index": 1,
-      "folder": "1-ui",
+      "folder": "1-design",
       "displayName": "UI/UX Design",
       "optional": true,
       "goals": [