@polymorphism-tech/morph-spec 9.8.0 → 10.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CLAUDE.md +10 -10
  2. package/README.md +4 -4
  3. package/bin/morph-spec.js +40 -43
  4. package/claude-plugin.json +1 -1
  5. package/docs/CHEATSHEET.md +1 -1
  6. package/docs/QUICKSTART.md +1 -1
  7. package/framework/CLAUDE.md +24 -30
  8. package/framework/MORPH.md +47 -123
  9. package/framework/agents.json +6 -374
  10. package/framework/commands/morph-apply.md +1 -1
  11. package/framework/commands/morph-archive.md +4 -3
  12. package/framework/commands/morph-hotfix.md +8 -30
  13. package/framework/commands/morph-infra.md +2 -2
  14. package/framework/commands/morph-media.md +10 -9
  15. package/framework/commands/morph-review.md +15 -0
  16. package/framework/commands/morph-status.md +1 -1
  17. package/framework/docs/CLI.md +83 -94
  18. package/framework/evals/review-checklist.md +45 -53
  19. package/framework/hooks/README.md +4 -4
  20. package/framework/hooks/claude-code/core/README.md +1 -1
  21. package/framework/hooks/claude-code/core/denylist.json +4 -4
  22. package/framework/hooks/claude-code/core/gate-guard.js +9 -0
  23. package/framework/hooks/claude-code/core/masked-exit.js +49 -0
  24. package/framework/hooks/claude-code/core/state-sync.js +4 -1
  25. package/framework/hooks/claude-code/core/telemetry-log.js +1 -2
  26. package/framework/hooks/claude-code/core/test-budget.js +10 -70
  27. package/framework/hooks/claude-code/core/validate-completion.js +11 -24
  28. package/framework/hooks/claude-code/core/worktree-context.js +5 -22
  29. package/framework/hooks/claude-code/core/worktree-create.js +6 -45
  30. package/framework/hooks/claude-code/core/worktree-env-inject.js +2 -10
  31. package/framework/hooks/shared/e2e-check.js +0 -0
  32. package/framework/hooks/shared/gate-event.js +2 -2
  33. package/framework/hooks/shared/graph-refresh.js +20 -3
  34. package/framework/hooks/shared/heavy-command.js +32 -1
  35. package/framework/hooks/shared/heavy-config.js +1 -1
  36. package/framework/hooks/shared/next-step.js +63 -24
  37. package/framework/hooks/shared/phase-utils.js +6 -9
  38. package/framework/hooks/shared/report-progress.js +86 -0
  39. package/framework/hooks/shared/state-reader.js +3 -2
  40. package/framework/hooks/statusline.js +332 -0
  41. package/framework/phases.json +32 -10
  42. package/framework/rules/ai-agents-standards.md +9 -1
  43. package/framework/rules/csharp-standards.md +4 -0
  44. package/framework/rules/ef-standards.md +20 -0
  45. package/framework/rules/frontend-standards.md +1 -1
  46. package/framework/rules/implement-report.md +25 -0
  47. package/framework/rules/infrastructure-standards.md +2 -0
  48. package/framework/rules/nextjs-standards.md +7 -0
  49. package/framework/rules/plan-grammar.md +53 -0
  50. package/framework/rules/ui-design.md +27 -0
  51. package/framework/schemas/config.schema.json +11 -18
  52. package/framework/schemas/feature.schema.json +7 -1
  53. package/framework/skills/core/create-umbraco-lp/SKILL.md +1 -1
  54. package/framework/skills/core/create-umbraco-lp/references/umbraco-lp-patterns.md +1 -1
  55. package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md +2 -2
  56. package/framework/skills/core/morph-apply/SKILL.md +38 -166
  57. package/framework/skills/core/morph-apply/references/debugging.md +8 -0
  58. package/framework/skills/core/morph-apply/references/hotfix.md +42 -0
  59. package/framework/skills/core/morph-apply/references/machine.md +29 -0
  60. package/framework/skills/core/{morph-media/SKILL.md → morph-apply/references/media.md} +11 -74
  61. package/framework/skills/core/morph-apply/references/review.md +65 -0
  62. package/framework/skills/core/morph-plan/SKILL.md +42 -108
  63. package/framework/skills/core/morph-plan/references/critique.md +40 -0
  64. package/framework/skills/core/morph-plan/references/interview.md +25 -0
  65. package/framework/skills/core/morph-uiux/SKILL.md +47 -64
  66. package/framework/skills/core/morph-uiux/surfaces.json +32 -0
  67. package/framework/standards/STANDARDS.json +32 -5
  68. package/framework/standards/STANDARDS.meta.json +5 -1
  69. package/framework/standards/ai-agents/agent-session.md +2 -3
  70. package/framework/standards/ai-agents/context-providers.md +2 -2
  71. package/framework/standards/ai-agents/durable-workflows-hitl.md +2 -2
  72. package/framework/standards/ai-agents/providers/model-registry.md +2 -2
  73. package/framework/standards/ai-agents/rag-custom-pgvector.md +6 -6
  74. package/framework/standards/ai-agents/setup.md +1 -1
  75. package/framework/standards/ai-agents/tool-adapters.md +2 -2
  76. package/framework/standards/architecture/stack-baseline.md +47 -0
  77. package/framework/standards/backend/integrations/neon-auth/neon-auth.md +2 -4
  78. package/framework/standards/frontend/design-system/ai-image-generation.md +51 -12
  79. package/framework/standards/frontend/design-system/ai-video-generation.md +50 -4
  80. package/framework/standards/frontend/design-system/art-direction.md +2 -2
  81. package/framework/standards/frontend/scroll-driven/frame-scrub.md +12 -2
  82. package/framework/standards/frontend/scroll-driven/scroll-components.md +76 -4
  83. package/framework/templates/REGISTRY.json +1 -2
  84. package/framework/templates/context/ARCHITECTURE.md +1 -1
  85. package/framework/templates/docs/plan.md +12 -12
  86. package/framework/templates/docs/ui-mockups.md +17 -105
  87. package/package.json +1 -1
  88. package/src/commands/e2e/e2e.js +88 -23
  89. package/src/commands/graph/diff.js +74 -0
  90. package/src/commands/graph/status.js +1 -1
  91. package/src/commands/observability/cost.js +2 -4
  92. package/src/commands/observability/telemetry.js +1 -1
  93. package/src/commands/project/doctor.js +23 -39
  94. package/src/commands/project/fleet.js +5 -6
  95. package/src/commands/project/init.js +63 -36
  96. package/src/commands/project/stack-scan.js +3 -42
  97. package/src/commands/project/stack-set.js +26 -0
  98. package/src/commands/project/status.js +12 -13
  99. package/src/commands/project/update.js +39 -3
  100. package/src/commands/project/worktree.js +3 -14
  101. package/src/commands/state/advance.js +17 -17
  102. package/src/commands/state/approve.js +0 -6
  103. package/src/commands/state/archive.js +27 -1
  104. package/src/commands/state/auto-approval.js +1 -1
  105. package/src/commands/state/create.js +0 -5
  106. package/src/commands/state/gate-check.js +37 -30
  107. package/src/commands/state/gate-decision.js +3 -2
  108. package/src/commands/state/next.js +1 -0
  109. package/src/commands/state/recap.js +67 -0
  110. package/src/commands/state/report-check.js +36 -178
  111. package/src/commands/validation/plan-check.js +16 -11
  112. package/src/commands/validation/validate-feature.js +3 -3
  113. package/src/commands/validation/verify.js +3 -6
  114. package/src/core/paths/output-schema.js +3 -3
  115. package/src/core/state/state-manager.js +2 -4
  116. package/src/dashboard/app/components/CommandPalette.jsx +2 -5
  117. package/src/dashboard/app/components/GatePauses.jsx +116 -0
  118. package/src/dashboard/app/components/SessionMap.jsx +77 -0
  119. package/src/dashboard/app/pages/Activity.jsx +4 -0
  120. package/src/dashboard/app/pages/AgentMap.jsx +1 -2
  121. package/src/dashboard/app/pages/FeatureDetail.jsx +129 -186
  122. package/src/dashboard/app/pages/Features.jsx +7 -7
  123. package/src/dashboard/app/pages/PhasePipeline.jsx +1 -1
  124. package/src/dashboard/app/pages/Portfolio.jsx +40 -5
  125. package/src/dashboard/scanner/activity-scanner.js +29 -0
  126. package/src/dashboard/scanner/agents-scanner.js +11 -14
  127. package/src/dashboard/scanner/features-scanner.js +45 -24
  128. package/src/dashboard/scanner/project-api.js +11 -2
  129. package/src/dashboard/scanner/skills-scanner.js +11 -1
  130. package/src/lib/e2e/applicability.js +3 -1
  131. package/src/lib/git/tree-state.js +1 -16
  132. package/src/lib/graph/diff-tree.js +127 -0
  133. package/src/lib/graph/graphify-runtime.js +12 -5
  134. package/src/lib/installers/memory-installer.js +2 -2
  135. package/src/lib/installers/rules-installer.js +57 -0
  136. package/src/lib/installers/stack-assets.js +17 -0
  137. package/src/lib/installers/stack-sync.js +219 -0
  138. package/src/lib/plan/checks.js +55 -110
  139. package/src/lib/plan/critique.js +28 -0
  140. package/src/lib/plan/media.js +42 -0
  141. package/src/lib/plan/plan-html.js +125 -0
  142. package/src/lib/plan/plan-parser.js +34 -45
  143. package/src/lib/recap/piper.js +36 -0
  144. package/src/lib/recap/recap.js +232 -0
  145. package/src/lib/review-reports.js +28 -4
  146. package/src/lib/risk-detector.js +90 -11
  147. package/src/lib/specs/screen-checklist.js +33 -48
  148. package/src/lib/stack/dotnet-build-ignores.js +8 -9
  149. package/src/lib/telemetry/metrics.js +27 -29
  150. package/src/lib/validators/reuse/reuse-validator.js +1 -9
  151. package/src/lib/validators/verify-runner.js +0 -7
  152. package/src/lib/worktree/fleet-scanner.js +7 -20
  153. package/src/lib/worktree/worktree-audit.js +0 -37
  154. package/src/scripts/setup-infra.js +15 -50
  155. package/src/utils/agents-installer.js +27 -201
  156. package/src/utils/hooks-installer.js +11 -95
  157. package/framework/hooks/claude-code/core/warn-bash-source-write.js +0 -23
  158. package/framework/hooks/claude-code/statusline.py +0 -699
  159. package/framework/hooks/claude-code/statusline.sh +0 -11
  160. package/framework/hooks/shared/agent-reap.js +0 -74
  161. package/framework/hooks/shared/slice-progress.js +0 -110
  162. package/framework/skills/core/morph-hotfix/SKILL.md +0 -133
  163. package/framework/skills/core/morph-machine/SKILL.md +0 -46
  164. package/framework/skills/core/morph-review/SKILL.md +0 -129
  165. package/framework/skills/core/morph-standards/SKILL.md +0 -52
  166. package/framework/standards/PROVENANCE.json +0 -119
  167. package/src/commands/project/worktree-reap.js +0 -34
  168. package/src/commands/state/handoff.js +0 -65
  169. package/src/commands/validation/mutate.js +0 -263
  170. package/src/commands/validation/scout-check.js +0 -28
  171. package/src/lib/generators/handoff-generator.js +0 -172
  172. package/src/lib/mutation/adapters.js +0 -79
  173. package/src/lib/mutation/commands.js +0 -61
  174. package/src/lib/mutation/dotnet-introspection.js +0 -281
  175. package/src/lib/mutation/manifest.js +0 -144
  176. package/src/lib/mutation/plan.js +0 -44
  177. package/src/lib/mutation/report.js +0 -68
  178. package/src/lib/mutation/runner.js +0 -301
  179. package/src/lib/mutation/schemata.js +0 -60
  180. package/src/lib/mutation/snapshot.js +0 -65
  181. package/src/lib/mutation/subset.js +0 -109
  182. package/src/lib/mutation/trx.js +0 -50
  183. package/src/lib/scout/scout-check.js +0 -293
  184. package/src/lib/validators/traceability-check.js +0 -103
  185. package/src/lib/worktree/agent-reaper.js +0 -247
@@ -1,189 +1,113 @@
1
1
  # MORPH.md — Natural Language Harness
2
2
 
3
- > Leia uma vez por sessão (e de novo após `/compact`). Os comandos imprimem a própria mecânica (sinais, vereditos, próximo passo); referência completa em `.morph/framework/CLI.md`.
4
- >
5
- > **Depois de ler:** `morph-spec next <f>` decide o passo do disco (fase, gates, relatórios, verify).
3
+ > Leia uma vez por sessão (e de novo após `/compact`). `morph-spec next <f>` decide o passo a partir do disco; a mecânica de cada comando está na saída dele e em `.morph/framework/CLI.md`.
6
4
 
7
5
  ---
8
6
 
9
7
  ## 0. Contrato de Autonomia
10
8
 
11
- Entre gates, você opera sozinho: o dev valida, você executa.
9
+ Entre gates, você opera sozinho: faz o que `next` mandar (`implement`, `verify`, `fix`, `review`, `finish`) sem esperar instrução nem anunciar.
12
10
 
13
11
  | Situação | O que você faz |
14
12
  | --- | --- |
15
- | Entre gates (gate aprovado, fatia relatada, verify verde ou vermelho) | Faz o que `morph-spec next <f>` mandar — `dispatch`, `verify` (uma vez, sem filtro), `fix`, `review`, `finish` — sem esperar instrução nem anunciar |
16
- | Ambiguidade de escopo coberta pelo plano | Resolve pelo lado conservador e registra no relatório |
17
- | Ambiguidade bloqueante (requisito ausente ou contraditório) | Uma pergunta via `AskUserQuestion` |
18
- | Cenário `Cn` sem evidência | Loop de correção com o feedback, como o verify vermelho, antes da review |
19
- | `next` devolve `escalate` | `AskUserQuestion` (aceitar/continuar/parar), o único ponto de pausa do loop; nunca uma 4ª tentativa por conta própria |
20
- | `verify` exit 3 | fila cheia, não vermelho: no máximo uma chamada nova, nunca laço de espera |
13
+ | Ambiguidade que o plano cobre | resolve pelo lado conservador e anota em `## Notas` do `report.md` |
14
+ | Ambiguidade bloqueante (requisito ausente ou contraditório) | uma pergunta via `AskUserQuestion` |
15
+ | `next` devolve `escalate` (3 verify vermelhos seguidos) | `AskUserQuestion`: aceitar, continuar ou parar. Nunca uma 4ª tentativa por conta própria |
16
+ | `verify` exit 3 | fila cheia, não vermelho: no máximo uma chamada nova |
21
17
 
22
- **Regra de ouro:** dúvida que não bloqueia → resolva e registre; dúvida que bloqueia → uma pergunta, no máximo. Vale **depois** do gate do plano: na abertura, o **modo entrevista** (`morph-plan` §3) pergunta até fechar o entendimento, e esse é o comportamento desejado.
23
-
24
- **A prova é o código:** `morph-spec verify` prova o determinístico; o cenário `Cn` do `checks.json` prova o comportamento (no CI: `verify {f} --ci`, mesmo stamp). Estilo é nota do revisor, nunca bloqueio.
25
-
26
- ---
27
-
28
- ## Stack baked-in
29
-
30
- O harness conhece o stack. Só pergunte sobre tecnologia com ambiguidade real.
31
-
32
- | Camada | Stack |
33
- | --- | --- |
34
- | Backend | .NET 10 + VSA (feature-folder: handler + validator + endpoint + errors + tests) |
35
- | ORM/DB | EF Core + Neon (Postgres) |
36
- | Erros | Result pattern com `result.Match()` |
37
- | IA | Microsoft Agent Framework (MAF), quando houver agentes |
38
- | Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
39
- | Jobs async | Hangfire, só com razão real |
40
-
41
- Padrões proibidos (os standards detalham; o mecânico, o build e o lint cobram): exception como fluxo de controle (o Result põe o erro esperado no tipo); Service/Manager entre handler e dados; `IRepository<T>`/`IUnitOfWork` (`DbSet<T>` já é repository); SQL cru sem ADR; redeclarar tipo que já existe (antes, `morph-spec graph explain <nome>`, sem grafo `grep -rn`; criar exige `CRIAR` com `why` em `## Reuso`).
18
+ Na abertura do plano vale o contrário: o modo entrevista pergunta até fechar o entendimento. **A prova é o código:** `verify` prova o determinístico, o Gate 3 prova cada cenário `Cn`. Estilo é nota, nunca bloqueio.
42
19
 
43
20
  ---
44
21
 
45
22
  ## 1. Papéis
46
23
 
47
- A transição entre papéis é explícita: conclua ou registre no relatório antes de mudar.
48
-
49
- **Orchestrator** — abertura e transições de fase: escopo, plano, gates. Não escreve código: se começou a implementar, trocou de papel sem querer.
24
+ **Você** planeja, implementa o plano inteiro nesta janela, corrige e fecha. O que aprendeu implementando vale para o resto da feature: não existe handoff.
50
25
 
51
- **Specialist** — implementação: executa as fatias do plano, consulta os standards da fatia, grava `3-implement/reports/F{n}.md`. Não cria fatia nova: acréscimo pequeno vai no relatório; fato errado do plano vai em `## Errata` (§3); escopo mudou → `morph-spec unapprove {f} plan`, porque o plano aprovado está congelado.
52
-
53
- **Evaluator** — o Gate 3 são sub-agents com contexto fresco, nunca quem implementou: `morph-verifier` prova cada `Cn` (default NÃO PROVADO), `morph-reviewer` julga o diff (escopo, arquitetura, regressão) e `morph-security` (opus, só com caminho sensível) procura o caminho de exploração. Revisor e segurança leem só o SHA revisado; a mutação do verificador espera os dois. Seguem `.morph/framework/evals/review-checklist.md`: `SHIP`/`FIX`, bloqueador só com evidência tipada. Não rodam a suíte nem reescrevem código.
26
+ **Gate 3** são sub-agents em contexto fresco, porque o que você sabe é exatamente o ponto cego que eles existem para não herdar: `morph-verifier` executa cada `Cn` contra a app, `morph-reviewer` julga o diff contra o plano, `morph-security` (só com caminho sensível) procura o caminho de exploração. Nenhum deles reescreve código.
54
27
 
55
28
  ---
56
29
 
57
30
  ## 2. Fases
58
31
 
59
- Cada fase tem pasta em `.morph/features/{feature}/`. Identidade do projeto: `.morph/config/config.json` (commitado).
60
-
61
- | Fase | Pasta | Gate | O que termina a fase |
32
+ | Fase | Pasta | Gate | Termina com |
62
33
  | --- | --- | --- | --- |
63
- | plan | `2-plan/` | plano (trust-aware) | `plan.md` + `checks.json` (`plan-check`) aprovados |
64
- | uiux (opcional) | `1-design/` | uiux (trust-aware) | design e checklist de tela aprovados |
65
- | implement | `3-implement/` | nenhum | toda fatia com relatório final em `reports/F{n}.md` |
66
- | review | `4-review/` | Gate 3 (trust-aware) | `verifier.md` + `reviewer.md` (+ `security.md`; chore: só `reviewer.md`) e o gate aprovado |
34
+ | plan | `2-plan/` | plano | `plan.md` + `checks.json` (`plan-check`) aprovados |
35
+ | uiux (opcional) | `1-design/` | uiux | protótipos escolhidos e checklist de tela |
36
+ | implement | `3-implement/` | — | todo `Cn` `feito` no `report.md` e `verify` verde |
37
+ | review | `4-review/` | Gate 3 | `verifier.md` + `reviewer.md` (+ `security.md`) e o gate aprovado |
67
38
 
68
- Sequência: `plan → [uiux] → implement → review`. Não avance sem o gate da fase.
69
-
70
- A fase `plan` abre com a escolha do **modo de descoberta** (só `feature`/`bug`): **entrevista** (uma pergunta por vez até a árvore de decisões zerar; o gate do plano pausa sempre, porque confirmar o entendimento compartilhado é o gate) ou **automático** (até 4 perguntas, só sobre nós abertos; gate trust-aware). Nos dois, a varredura roda antes de qualquer pergunta: fato que `morph-spec stack-scan`, o contexto ou os ADRs respondem não vira pergunta. Detalhes em `morph-plan`.
39
+ `plan → [uiux] → implement → review`. Feature/bug com superfície de UI toma o ramo uiux (`advance --design`), decidido uma vez na `morph-plan`.
71
40
 
72
41
  ### 2.1 Roteamento por tipo de trabalho
73
42
 
74
- Toda feature nasce com `description` obrigatória e um `workType`: `morph-spec create <f> --description "<o quê/porquê>" --type <tipo>` (ou `--request "<pedido>"`, que classifica e semeia a descrição).
43
+ `morph-spec create <f> --request "<pedido>"` (ou `--type <t> --description "…"`).
75
44
 
76
45
  | Tipo | Pipeline | Gates |
77
46
  | --- | --- | --- |
78
- | `feature` | plan → [uiux] → implement → review | plano, [uiux], review |
79
- | `bug` | plano enxuto (repro + diagnóstico) → implement → review | plano, review |
80
- | `chore` | `plan.md` curto, gate do plano carimbado por política → implement → review leve | só review |
81
- | `hotfix` | scout (diagnóstico read-only) → fix cirúrgico → aprovação humana obrigatória → test loop → ship | 3, sempre humano |
82
-
83
- **Ramo uiux (critério objetivo):** feature/bug que cria ou altera superfície de UI (componente, página, tela, estilo, navegação) toma o ramo `1-design/` depois do gate do plano (`morph-spec advance {feature} --design`, também com o gate já aprovado pelo humano; nunca `1-design/` à mão); sem superfície de UI, direto para implement. Skill: `morph-uiux`. A `morph-plan` §6 decide uma vez; nenhum outro ponto redecide.
47
+ | `feature` | plan → [uiux] → implement → review | plano, [uiux], Gate 3 |
48
+ | `bug` | plano enxuto (repro + causa) → implement → review | plano, Gate 3 |
49
+ | `chore` | plano curto carimbado → implement → só revisor | Gate 3 |
50
+ | `hotfix` | plano curto carimbado → fix → `verifier.md` seu → humano | Gate 3, sempre humano |
84
51
 
85
- **Skip:** `chore`/`hotfix` começam em `implement` com um `plan.md` curto de uma fatia (hotfix: C1 = sintoma ausente, C2 = regressão) e `plan-check`; trocar o tipo: `morph-spec retype`.
86
-
87
- **Branch:** toda feature nasce em `morph/{f}`, ramificada da default, com ou sem `--worktree`, e fecha igual nos dois com `morph-spec finish <f> --pr|--merge` (§2.2).
52
+ Toda feature nasce em `morph/{f}` e fecha com `morph-spec finish <f> --pr|--merge`.
88
53
 
89
54
  ### 2.2 Desenvolvimento paralelo por worktree (frota)
90
55
 
91
- Features independentes rodam em paralelo, uma por worktree e uma instância de Claude Code por worktree: `create <f> --worktree` (ou `worktree setup <f>`) na branch `morph/{f}`.
56
+ Features independentes rodam em paralelo, **uma feature = um worktree = uma sessão**: `create <f> --worktree`. Dentro de uma feature, nunca paralelo.
92
57
 
93
- - **Uma feature = um worktree = uma instância.** `feature.json` viaja commitado em `morph/{f}`; a cópia da raiz é esqueleto.
94
- - **Só o morph cria worktree:** `worktree setup <f>` (feature) ou `worktree provision <n>` (isolamento de fatia, branch `morph-task/<n>`). `EnterWorktree`/`-w`/`isolation:"worktree"` passam pelo hook `WorktreeCreate` e caem no contêiner (`worktrees/` ou `worktree.root`); fora dele = criado sem o morph (`doctor --worktrees`). Já existe: abra o `claude` DENTRO dela; `EnterWorktree(path)` sempre pede aprovação. Infra (`node_modules`, `.claude`, `.morph/framework`) entra por junction; faltou → `worktree link --all`.
95
- - **Só o morph remove worktree.** Qualquer outra remoção atravessa a junction e apaga o conteúdo real da raiz (os hooks barram as formas conhecidas; o explorador, não). Fechar = `morph-spec finish <f> --pr|--merge`; só desmontar = `morph-spec worktree remove <f>`. Sobra de sub-agent (`agent-<hex>`): `worktree reap` remove só a que parou limpa e sem commit exclusivo.
96
- - **Ambiente dedicado:** o setup escreve `.morph/worktree.env` (`PORT`, `API_PORT`, `POSTGRES_PORT`, `COMPOSE_PROJECT_NAME=morph-{f}`) e cada worktree sobe o seu compose; o hook de Bash injeta as variáveis (fora do Claude, `eval "$(morph-spec env)"`). `finish` derruba o stack com volumes (`--keep-volumes` preserva). Fora do `verify`, build e teste pesados vão por `heavy run -- <cmd>`.
97
- - **Migração destrutiva → integre antes de abrir irmãos:** os irmãos ramificam do schema velho e quebram no merge.
98
- - **`node_modules` é junction compartilhada:** dependência mudada afeta todos os irmãos; integre antes de seguir em paralelo.
99
- - **Handoff:** `.morph/features/{f}/handoff.md` (regenerável por `morph-spec handoff <f>`): leia antes de re-derivar contexto; nunca edite.
100
- - **Ownership:** sem lock; colisão se resolve no plano (ondas do `plan-check`) e por construção (uma feature = um escritor). Visão agregada: `fleet`.
101
- - **Fechamento:** aprove o Gate 3 e rode `morph-spec finish <f> --pr|--merge`. **`--pr` não integra:** a feature fica `aguardando-merge` até alguém mergear, nunca "entregue" só por `finished: true`.
58
+ - **Só o morph cria worktree:** `worktree setup <f>` (feature) ou `worktree provision <n>` (árvore avulsa); `EnterWorktree`/`claude -w` passam pelo hook `WorktreeCreate`. Já existe: abra o `claude` dentro dela.
59
+ - **Só o morph remove worktree.** `finish` ou `worktree remove`; qualquer outra remoção atravessa a junction e apaga a raiz.
60
+ - **Ambiente dedicado:** `.morph/worktree.env` (`PORT`, `API_PORT`, `POSTGRES_PORT`, `COMPOSE_PROJECT_NAME`) e compose próprio; `finish` derruba com volumes (`--keep-volumes` preserva). Build e teste pesados fora do `verify` vão por `heavy run -- <cmd>`.
61
+ - Migração destrutiva ou dependência nova: integre antes de abrir irmãos. Visão agregada: `fleet`.
62
+ - **`--pr` não integra:** a feature fica `aguardando-merge` até o merge.
102
63
 
103
64
  ---
104
65
 
105
66
  ## 3. Contratos de Output
106
67
 
107
- ### Plan (`2-plan/`)
108
-
109
- - `plan.md` — fonte única da feature (esqueleto do `create`; chore/hotfix: você o cria), gramática em `morph-spec plan-check --help`. Lido uma vez por sessão e pós-`/compact`.
110
- - `checks.json` — escrito só pelo `plan-check`; é a régua que o verificador prova item a item.
111
- - `stack-scan.md` e `scout-map.md` (§6) — insumos do plano.
112
-
113
- **Congelamento:** aprovado o gate do plano, o corpo do `plan.md` trava: quem implementa não afrouxa o critério que prova o trabalho. Fato que o código desmente vai em `## Errata` no fim (append-only); escopo mudou → `morph-spec unapprove {f} plan`.
114
-
115
- ### Implement (`3-implement/`)
116
-
117
- - `3-implement/reports/F{n}.md` — um por fatia (sub-agent, ou você se inline); formato em `morph-apply`.
118
- - `3-implement/evidencias/{Cn}.md` — no cenário `prova: eval` (entrada, modelo, saída, veredito) ou `prova: manual` (passo e resultado).
119
-
120
- ### Review (`4-review/`)
121
-
122
- - `verifier.md`, `reviewer.md`, `security.md` (só com caminho sensível) — formato em `.morph/framework/evals/review-checklist.md`; vale o último veredito.
68
+ - `plan.md` (`2-plan/`) — fonte única, lida uma vez por sessão e de novo após `/compact` (gramática: `plan-check --help`). Aprovado, o corpo congela: fato que o código desmente vai em `## Errata` no fim; escopo mudou → `unapprove {f} plan`.
69
+ - `2-plan/checks.json` — escrito só pelo `plan-check`; a régua do Gate 3.
70
+ - `3-implement/report.md` — tabela `| Cn | status | evidência |` (`pendente`/`feito`/`bloqueado`) e `## Notas` append-only. É a sua memória depois de um `/compact`: atualize ao fechar cada `Cn`.
71
+ - `3-implement/evidencias/{Cn}.md` — só para `prova: eval` ou `manual`.
72
+ - `4-review/{verifier,reviewer,security}.md` — formato em `.morph/framework/evals/review-checklist.md`; vale o último veredito.
123
73
 
124
74
  ---
125
75
 
126
76
  ## 4. Como consultar Standards
127
77
 
128
- Nunca carregue todos os standards: custa contexto em toda chamada e você não sabe quais importam antes de começar. Disclosure progressivo, por fatia:
129
-
130
- 1. `morph-spec standards --find "<domínio/tecnologia da fatia>"` → top 3 como `id · path · digest`, com as âncoras de seção. O `digest` costuma bastar.
131
- 2. Não bastou → `morph-spec standards --show <id>#<âncora>` imprime só aquela seção.
132
- 3. Só então o arquivo inteiro (campo `path`), quando precisar do exemplo completo.
133
- 4. Registre no `**Standards:**` do relatório qual standard aplicou. Dois em conflito → o mais específico ao stack, com o conflito no relatório. Nenhum cobre o caso → registre o critério adotado; não invente standard, porque padrão não documentado é dívida disfarçada.
134
-
135
- Inline, o campo `persona` do domínio em `.morph/framework/agents.json` dá o ponto de vista e o rigor.
78
+ Nunca carregue todos. `morph-spec standards --find "<tema>"` dá o top 3 com digest (costuma bastar) → `--show <id>#<âncora>` só a seção → o arquivo inteiro só pelo exemplo completo. As regras de cada domínio chegam pela rule do stack (`.claude/rules/`, por `paths:`) quando você toca o arquivo. Nenhum standard cobre: anote o critério nas `## Notas`; não invente standard.
136
79
 
137
80
  ---
138
81
 
139
82
  ## 5. Gates de Aprovação (Trust Mode)
140
83
 
141
- Em `trust: "auto"` (default, `.morph/config/config.json → trust`), um gate sem sinal de risco passa com um resumo curto. Em `trust: "manual"` ou com sinal de risco, pausa via `AskUserQuestion` com as opções `"aprovado, prosseguir"` / `"preciso ajustar"` / `"cancelar feature"` (no Gate 3, `"rollback"` no lugar de cancelar).
142
-
143
- **Quem decide é o código:** `morph-spec gate-check <feature> <gate>` coleta os sinais do disco, decide a pausa (`shouldPauseGate`), grava `gateDecisions` e imprime o sinal que pausou. Só o que a sessão sabe e o disco não mostra entra por `--signals`:
144
-
145
- | Sinal | Quando você o passa |
146
- | --- | --- |
147
- | `designSystemDivergence` | fontes de design conflitantes (tokens, versão, fonte aprovada) |
148
- | `standardsViolations` | plano ou código viola um padrão proibido (lista não vazia) |
149
-
150
- Risco que nenhum sinal representa: `morph-spec gate-decision <feature> <gate> --pause <bool> --reason <txt>`. Sinais completos: CLI.md (`gate-check`).
151
-
152
- **Gates por tipo:** o Gate 3 vale para todos; em `hotfix` é sempre humano (o `approve` recusa `--mode auto`) e exige só `4-review/verifier.md`, escrito pelo orquestrador.
84
+ **Quem decide é o código:** `gate-check <f> <gate>` decide pelo disco a pausa e quem a resolve. O que o disco não mostra vai por `--signals` (lista no `CLI.md`); outro risco, `gate-decision <f> <gate> --pause <bool> --reason <txt>`.
153
85
 
154
- **Aprovar é sempre pela CLI, nunca editando o estado:** em `trust: auto`, `morph-spec approve <feature> <gate> --mode auto`, ou `morph-spec advance <feature>` (aprova e cria a pasta da próxima fase; `--design` toma o ramo uiux). No caminho humano, o hook `state-sync` grava a resposta "aprovado, prosseguir" da pergunta que nomeia a feature; outra resposta → `morph-spec approve`.
86
+ - `pause: false` → uma linha e `approve <f> <gate> --mode auto` (ou `advance`).
87
+ - `resolver: session` → faça o que a `reason` diz e rode `gate-check` de novo, sem perguntar.
88
+ - `resolver: human` → `AskUserQuestion` que **nomeia a feature** ("Gate do plano — Plano de {f} aprovado?"): o `state-sync` grava a aprovação por ela.
89
+ - Hotfix: `approve` recusa `--mode auto`. Estado só pela CLI, nunca no `feature.json`.
155
90
 
156
91
  ---
157
92
 
158
- ## 6. Sub-agents
159
-
160
- Trabalho pesado ou de outro domínio vai para um sub-agent com persona e standards escopados — o modo padrão, porque ele carrega o domínio sem inchar o contexto principal. Despache quando houver:
161
-
162
- - **domínio diferente do corrente** (backend agora, a próxima fatia é frontend/UI/dados) — o gatilho mais importante;
163
- - esforço L/XL (> 5 min), arquivo com mais de 500 linhas, mais de 3 repetições do mesmo padrão, ou detalhe de baixo nível que contaminaria o contexto.
93
+ ## 6. Contexto
164
94
 
165
- Inline vale para fatia pequena no domínio já carregado; inline numa fatia que dispara um gatilho exige uma linha de porquê no relatório. Não despache quando o overhead passa da economia ou a fatia muda arquitetura que você precisa validar antes.
95
+ Uma pergunta decide se algo sai da sua janela: **o que você já sabe ajuda, atrapalha ou não importa?**
166
96
 
167
- **Mecanismo:** `subagent_type: "morph-{id}"` (ex.: `morph-dotnet-senior`); a persona é o system prompt, gerada de `agents.json` em `.claude/agents/`. Tipo não registrado: `general-purpose` com o `persona` colado no prompt, registrado no relatório da fatia.
97
+ - **Ajuda** → faça aqui. Domínio diferente, arquivo grande ou tarefa longa não são motivo para despachar: o plano inteiro se implementa nesta sessão, em sequência. Se a janela encher, `/compact` — o `report.md` e o plano guardam o estado.
98
+ - **Atrapalha** → Gate 3, em contexto fresco (`morph-apply` › `references/review.md`).
99
+ - **Não importa** → pesquisa externa sem nada do projeto pode ir a um sub-agent descartável.
168
100
 
169
- **Scout:** `morph-scout` localiza com `morph-spec graph affected|explain` e cai para grep sem grafo. Obrigatório no início de um hotfix, default no plano de feature grande ou brownfield (`morph-plan` §4). Devolve um mapa (Observado/Inferido) em `2-plan/scout-map.md`; rode `morph-spec scout-check <mapa> --json` antes de usá-lo. Reprovado → re-despache uma vez com as falhas; segunda reprovação → grep você mesmo e escale.
170
-
171
- **O prompt leva só o que muda por fatia** (`morph-apply` §3): cenários que ela cobre, arquivos, standards, caminho do relatório. As cláusulas fixas de todo dispatch de implementador vivem no corpo gerado da persona (`## Contrato de dispatch`), o único texto que todo dispatch carrega. Não passe histórico da conversa nem saída de outras tarefas.
172
-
173
- **O arquivo é o retorno; a última mensagem é cortesia** (pode não chegar): leia o relatório no caminho canônico.
101
+ Rode build e teste quando quiser enquanto implementa; a prova do gate é um `verify <f>` sem filtro.
174
102
 
175
103
  ### Protocolo de auditoria do relatório
176
104
 
177
- Relatório ausente não prova que o agente falhou, e relatório presente não prova que ele está certo (um gravado cedo fica completo e velho). A pergunta é "o trabalho entrou, e é isto que ele diz?", respondida por evidência: `morph-spec report-check <feature> [F1 F2 …] --json` dá o veredito e a ação (`hint`) de cada fatia, e a tabela de ação está em `morph-apply` §5. `report-stale` e `work-landed-report-missing` nunca se resolvem re-despachando: o trabalho já entrou.
178
-
179
- **Teto de turnos:** o corte é cego; relatório `PARCIAL` vira `report-incomplete` com ação `resume`: retome o mesmo agente, não carimbe DEGRADADO.
180
-
181
- **Paralelo:** fluxos genuinamente independentes (backend ‖ frontend) vão ao mesmo tempo, um agente por fatia, até 4. As ondas saem do `plan-check`. Colisão que escapou do plano → a segunda fatia vai num worktree próprio, em rolling: a cada relatório o orquestrador integra por merge e despacha a próxima pronta (`morph-apply` §4). A feature só segue para a review com `verify` verde e cada cenário com evidência (§0).
105
+ O arquivo é o retorno; a mensagem final do sub-agent é cortesia. `morph-spec report-check <f> --json` diz o estado de cada relatório do Gate 3: `complete` não se despacha de novo; `partial` (`PARCIAL` na 1ª linha) ou ausente → despache. Rodada de confirmação depois de uma correção é um dispatch **novo** com o `sha` novo, nunca uma conversa com o agente anterior.
182
106
 
183
107
  ---
184
108
 
185
109
  ## 7. Skills disponíveis
186
110
 
187
- **Skills core** (`.claude/skills/{nome}/SKILL.md`, invocadas no momento indicado na descrição de cada uma): `morph-plan` (entrada: roteia, varre, entrevista, `plan.md`, gate do plano) · `morph-apply` (fatias → verify → review) · `morph-uiux` · `morph-review` · `morph-hotfix` · `morph-standards` · `morph-media` · `morph-machine`.
111
+ **Skills core** (`.claude/skills/{nome}/SKILL.md`): `morph-plan` (pedido → plano aprovado) · `morph-apply` (plano → código → verify → Gate 3 → finish; hotfix e chore são deltas dela) · `morph-uiux` (opções renderizadas → protótipo → gate uiux).
188
112
 
189
- `/morph-plan` invoca a skill direto; `/morph-apply` e `/morph-hotfix` são atalhos da skill homônima. Desvio do passo a passo vai justificado no relatório.
113
+ `/morph-plan`, `/morph-apply`, `/morph-hotfix` e `/morph-review` invocam a skill no passo certo. Detalhe sob demanda em `references/` de cada skill.