chore: adiciona .gitignore e commit.command

code/Engine/docs/06_BOAS_PRATICAS.md

@@ -0,0 +1,77 @@
+# 06 — Boas Práticas de Programação (G-ART)
+
+> **Propósito:** registrar as melhores práticas de programação a serem aplicadas
+> **sempre** que qualquer alteração ou correção for feita neste programa.
+> Servem de checklist obrigatório antes de concluir qualquer mudança.
+
+**Regra:** antes de considerar uma alteração concluída, confira os itens abaixo.
+Eles são o mesmo espírito do fluxo de validação pós-correção
+(`Engine/run_after_fix.sh`), mas cobrem também **qualidade de código** e
+**convenções do projeto**.
+
+---
+
+## 1. Correções de código
+
+1. **Sempre valide após corrigir** — rode `./Engine/run_after_fix.sh` (lint +
+   testes). Nunca declare uma correção pronta sem que lint e a suíte passem.
+2. **Toda correção já corrigida vira registro** — registre o problema em
+   `Engine/docs/05_EXPERIENCIAS.md` para que não se repita.
+3. **Mude o mínimo necessário** — altere apenas o que resolve o problema; evite
+   refatorar código não relacionado na mesma mudança.
+
+## 2. Tempo e FCPXML
+
+4. **Nunca use `float` para tempo** — toda duração/offset é `TimeValue`
+   (fração racional `"600/2400s"`). Float introduz erro de arredondamento.
+5. **`offset` é a posição na timeline; `start` é o in-point na origem** — não
+   confundir nas edições de clip.
+6. **Markers são filhos dos clips, não irmãos** — e `<spine>` é a storyline
+   primária; connected clips penduram-se com atributo `lane`.
+7. **Preserve sidecars em bundles `.fcpxmld`** — ao gravar um bundle, copie os
+   arquivos de dados; caso contrário destrói object-tracking/Cinematic.
+
+## 3. Estrutura e arquitetura
+
+8. **Mantenha o núcleo desacoplado** — `fcpxml/` não conhece o protocolo MCP;
+   `server.py` é a camada de transporte. Não vazem lógica MCP para o núcleo.
+9. **Use o padrão de dispatch** — sem cadeias gigantes de `if/elif`; use
+   `TOOL_HANDLERS` (dicionário nome → handler assíncrono).
+10. **Reaproveite os helpers centrais** — `_parse_project()`, `_resolve_io_paths()`,
+    `_setup_modifier()`, etc. Não duplique parse/validação de caminho.
+11. **Nunca sobrescreva o original** — use `generate_output_path()` e crie
+    `_modified`, `_chapters`, etc.
+12. **Mantenha o `MarkerType` como single source of truth** — a serialização
+    (parse/escrita) vive no enum, não espalhada por handlers.
+
+## 4. Segurança
+
+13. **Sempre use `safe_xml.py` (defusedxml)** — todos os entry points de parse;
+    jamais `xml.etree` cru com input não confiável.
+14. **Valide caminhos com `_validate_filepath` / `_validate_output_path`** — o
+    sandbox de I/O existe para impedir escrita fora do permitido.
+15. **Rejeite payloads excessivamente aninhados** — `_check_json_depth` protege
+    contra payloads além de 50 níveis.
+16. **Nunca registre/commite segredos ou chaves** — nem em logs, nem em código.
+
+## 5. Qualidade e clareza
+
+17. **Sem comentários desnecessários** — código deve ser autoexplicativo;
+    comente o *porquê*, não o *o quê*.
+18. **Mimice as convenções do projeto** — mesma estrutura de imports, nomes,
+    padrões e bibliotecas já usadas nas vizinhas.
+19. **Lazy import de dependências opcionais** — `media_intel` (librosa) e
+    `transcribe` (Whisper) importam sob demanda e degradam com graça (`None`).
+20. **Convenções de teste** — use `examples/sample.fcpxml` + fixtures XML inline;
+    `sample.fcpxml` NÃO é DTD-conformante, não o use como fixture de validade DTD.
+
+## 6. Checklist final antes de concluir uma alteração
+
+- [ ] `./Engine/run_after_fix.sh` passou (lint zero erros + todos os testes).
+- [ ] Problema registrado em `Engine/docs/05_EXPERIENCIAS.md` (se aplicável).
+- [ ] Nenhum `float` usado em matemática de tempo.
+- [ ] Nenhum caminho original sobrescrito.
+- [ ] `safe_xml.py` usado em todo parse de input não confiável.
+- [ ] Nenhum segredo registrado ou commitado.
+- [ ] Mudança mínima, sem refatoração não relacionada.
+- [ ] Boa prática nova aprendida adicionada a esta lista.