feat: criado monitoramento contínuo de trilhas com varredura recur

- criado monitoramento contínuo de trilhas com varredura recursiva e baixa prioridade
- gerado e validado plano editorial revisável do depoimento da Erika sem aplicação na timeline
- adicionada leitura e comparação estrutural da timeline após aplicar planos de edição
- limitadas as classificações de trilhas às duas maiores probabilidades de cada categoria
- limpo o catálogo musical para reiniciar as análises sem remover dados de vídeo

Resumo:
- 34 arquivos alterados
- 6 novos
- 28 modificados
- 0 removidos

 28 files changed, 833 insertions(+), 75 deletions(-)

Arquivos:
  - .jhonny/analises.db
  - code/cep-plugin/index.html
  - code/cep-plugin/main.js
  - code/engine/analisar_trilhas.py
  - code/engine/aplicar_plano_de_edicao.py
  - code/engine/consultar_detalhes_de_trilha.py
  - code/engine/editor/__init__.py
  - code/engine/editor/aplicador_de_plano_de_edicao.py
  - code/engine/editor/backup_de_sequencia.py
  - code/engine/editor/escrita/escrita_no_editor.py
  - code/engine/editor/modelos.py
  - code/engine/editor/validacao_semantica.py
  - code/engine/integracoes/audio/classificador_de_musica_essentia.py
  - code/engine/integracoes/audio/modelos_de_analise_musical.py
  - code/engine/integracoes/audio/provider_de_analise_musical_essentia.py
  - code/engine/persistencia/esquema.py
  - code/engine/persistencia/repositorio_de_trilhas.py
  - code/engine/testes/duplos_de_premiere.py
  - code/engine/testes/test_aplicador_de_plano_de_edicao.py
  - code/engine/testes/test_aplicar_plano_de_edicao.py
  - code/engine/testes/test_escrita_no_editor.py
  - code/engine/testes/test_leitor_de_plano_de_edicao.py
  - code/engine/testes/test_validador_semantico_de_plano.py
  - code/plugins/premiere-pro/skills/editar-por-voz/SKILL.md
  - code/plugins/premiere-pro/skills/editar-por-voz/criterios/08-formato-de-saida.md
  - code/plugins/premiere-pro/skills/editar-por-voz/criterios/10-revisao-humana.md
  - code/src/tools/timeline.ts
  - code/tests/tools/tool-modules.test.ts
  - .jhonny/planos/
  - code/.jhonny/analises.db-shm
  - code/.jhonny/analises.db-wal
  - code/engine/editor/verificador_da_aplicacao.py
  - code/engine/testes/test_verificador_da_aplicacao.py
  - code/plugins/premiere-pro/skills/editar-por-voz/criterios/11-gancho.md

code/engine/analisar_trilhas.py

@@ -6,6 +6,7 @@ import argparse
 import json
 from pathlib import Path
 import sys
+import time
 
 CAMINHO_DO_CODIGO = Path(__file__).resolve().parent.parent
 if str(CAMINHO_DO_CODIGO) not in sys.path:
@@ -33,18 +34,14 @@ def executar(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None, apena
     try:
         repositorio = RepositorioDeTrilhasSQLite(conexao)
         trilhas = repositorio.registrar_pasta_e_arquivos(pasta, arquivos)
+        repositorio.reabrir_analises_sem_etiquetas()
+        trilhas = repositorio.registrar_pasta_e_arquivos(pasta, arquivos)
         if apenas_listar:
             emitir("catalogo_atualizado", trilhas=[
                 {"nome": trilha.nome_do_arquivo, "caminho": str(trilha.caminho), "status": trilha.status}
                 for trilha in trilhas
             ])
             return 0
-        classificador = (
-            ClassificadorDeMusicaEssentia(diretorio_dos_modelos)
-            if diretorio_dos_modelos and diretorio_dos_modelos.is_dir()
-            else None
-        )
-        analisador = AnalisadorDeMusicaInstrumentalEssentia(classificador=classificador)
         pendentes = tuple(trilha for trilha in trilhas if trilha.status != "concluida")
         emitir(
             "lote_iniciado",
@@ -53,22 +50,39 @@ def executar(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None, apena
             nomes=[trilha.nome_do_arquivo for trilha in pendentes],
             trilhas=[{"nome": trilha.nome_do_arquivo, "caminho": str(trilha.caminho), "status": trilha.status} for trilha in trilhas],
         )
+        if not pendentes:
+            emitir("lote_concluido", total=0, percentual=100)
+            return 0
+        classificador = (
+            ClassificadorDeMusicaEssentia(diretorio_dos_modelos)
+            if diretorio_dos_modelos and diretorio_dos_modelos.is_dir()
+            else None
+        )
+        analisador = AnalisadorDeMusicaInstrumentalEssentia(classificador=classificador)
         for ordem, trilha in enumerate(pendentes, start=1):
             repositorio.iniciar_analise(trilha.identificador)
-            emitir("trilha_iniciada", nome=trilha.nome_do_arquivo, indice=ordem, total=len(trilhas), percentual=(ordem - 1) * 100 / max(1, len(trilhas)))
+            emitir("trilha_iniciada", nome=trilha.nome_do_arquivo, caminho=str(trilha.caminho), indice=ordem, total=len(trilhas), percentual=(ordem - 1) * 100 / max(1, len(trilhas)))
             try:
                 resultado = analisador.analisar(trilha.caminho)
                 repositorio.registrar_analise(trilha, resultado)
-                emitir("trilha_concluida", nome=trilha.nome_do_arquivo, indice=ordem, total=len(trilhas), percentual=ordem * 100 / max(1, len(trilhas)))
+                emitir("trilha_concluida", nome=trilha.nome_do_arquivo, caminho=str(trilha.caminho), indice=ordem, total=len(trilhas), percentual=ordem * 100 / max(1, len(trilhas)))
             except (OSError, RuntimeError, ValueError) as erro:
                 repositorio.registrar_erro(trilha.identificador, str(erro))
-                emitir("trilha_com_erro", nome=trilha.nome_do_arquivo, indice=ordem, total=len(trilhas), erro=str(erro), percentual=ordem * 100 / max(1, len(trilhas)))
+                emitir("trilha_com_erro", nome=trilha.nome_do_arquivo, caminho=str(trilha.caminho), indice=ordem, total=len(trilhas), erro=str(erro), percentual=ordem * 100 / max(1, len(trilhas)))
         emitir("lote_concluido", total=len(trilhas), percentual=100)
         return 0
     finally:
         conexao.close()
 
 
+def executar_continuamente(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None, intervalo: float) -> int:
+    """Mantém a pasta monitorada e processa novas trilhas em baixa frequência."""
+    while True:
+        executar(pasta, banco, diretorio_dos_modelos)
+        emitir("worker_aguardando", intervalo=intervalo)
+        time.sleep(intervalo)
+
+
 def principal() -> None:
     """Lê argumentos e executa o lote de análise."""
     argumentos = argparse.ArgumentParser()
@@ -76,8 +90,12 @@ def principal() -> None:
     argumentos.add_argument("--banco", type=Path, default=Path(".jhonny/analises.db"))
     argumentos.add_argument("--modelos", type=Path, default=None)
     argumentos.add_argument("--listar", action="store_true")
+    argumentos.add_argument("--continuo", action="store_true")
+    argumentos.add_argument("--intervalo", type=float, default=20.0)
     opcoes = argumentos.parse_args()
     try:
+        if opcoes.continuo:
+            raise SystemExit(executar_continuamente(opcoes.pasta, opcoes.banco, opcoes.modelos, opcoes.intervalo))
         raise SystemExit(executar(opcoes.pasta, opcoes.banco, opcoes.modelos, opcoes.listar))
     except (OSError, RuntimeError, ValueError) as erro:
         emitir("lote_com_erro", erro=str(erro))

code/engine/aplicar_plano_de_edicao.py

@@ -37,8 +37,10 @@ from engine.editor import (
     LeitorDePlanoDeEdicao,
     MapeadorDeTempoDeOrigemParaTimeline,
     PlanoDeEdicao,
+    ResultadoDaVerificacao,
     TipoDeAcao,
     ValidadorSemanticoDePlano,
+    VerificadorDaAplicacao,
 )
 from engine.integracoes.premiere.cliente_mcp import ClienteMCPPorStdio
 from engine.integracoes.premiere.cliente_mcp_com_pausa import ClienteMCPComPausa
@@ -52,6 +54,14 @@ CAMINHO_DO_SERVIDOR_MCP = CAMINHO_DO_CODIGO / "dist" / "index.js"
 CAMINHO_DO_BANCO = CAMINHO_DO_CODIGO.parent / ".jhonny" / "analises.db"
 
 
+def _garantir_backup_para_ganchos(plano: PlanoDeEdicao, backup_criado: bool) -> None:
+    """Bloqueia ganchos quando não há uma cópia recuperável da sequência."""
+    if plano.acoes_do_tipo(TipoDeAcao.GANCHO) and not backup_criado:
+        raise ErroDePlanoInvalido(
+            "A ação hook não foi aplicada porque o Premiere não confirmou o backup da sequência."
+        )
+
+
 def _validar_integridade_semantica(
     plano: PlanoDeEdicao,
     plano_id: int | None,
@@ -59,7 +69,10 @@ def _validar_integridade_semantica(
     exigir_validacao: bool = False,
 ) -> None:
     """Valida palavras, frases e respiros antes de iniciar a sessão do Premiere."""
-    if not plano.acoes_do_tipo(TipoDeAcao.CORTE):
+    if not (
+        plano.acoes_do_tipo(TipoDeAcao.CORTE)
+        or plano.acoes_do_tipo(TipoDeAcao.GANCHO)
+    ):
         return
     if plano_id is None:
         if exigir_validacao:
@@ -119,6 +132,7 @@ def _registrar_no_banco(
     sequencia: str,
     plano_id: int | None = None,
     caminho_do_banco: Path = CAMINHO_DO_BANCO,
+    verificacao: ResultadoDaVerificacao | None = None,
 ) -> None:
     """Guarda no banco de análises o plano aplicado e o resultado da aplicação.
 
@@ -145,11 +159,14 @@ def _registrar_no_banco(
         if plano_id is None:
             plano_id = repositorio.registrar_plano(plano_de_dict(dados))
         aplicadas = sum(1 for item in resultado.resultados if item.sucesso)
+        verificacao_aprovada = verificacao is None or verificacao.aprovada
+        mensagem = verificacao.mensagem if verificacao is not None else None
         repositorio.registrar_aplicacao(
             plano_id,
-            sucesso=resultado.todas_bem_sucedidas,
+            sucesso=resultado.todas_bem_sucedidas and verificacao_aprovada,
             acoes_aplicadas=aplicadas,
             sequencia=sequencia,
+            mensagem=mensagem,
         )
     except (OSError, ValueError, sqlite3.Error) as erro:
         print(f"Plano aplicado, mas não foi possível registrá-lo no banco: {erro}",
@@ -186,9 +203,11 @@ def executar(
 
         # A engine é a única responsável pelo backup. A validação semântica já
         # aconteceu antes da conexão, portanto um plano bloqueado não duplica
-        # a sequência. Uma falha no backup fica registrada em stderr.
+        # a sequência. Gancho é recusado sem backup porque combina mais de
+        # uma mutação estrutural; as demais ações preservam o fluxo legado.
         sequencia_ativa = conversor_de_timeline.converter(acesso_ao_editor.obter_timeline_ativa())
         backup_ok = BackupDaSequencia(cliente).criar_backup(sequencia_ativa.identificador)
+        _garantir_backup_para_ganchos(plano, backup_ok)
         print(
             "Backup da sequência criado." if backup_ok else "Não foi possível criar o backup automático; aplicando mesmo assim.",
             file=sys.stderr,
@@ -201,15 +220,28 @@ def executar(
             mapeador=MapeadorDeTempoDeOrigemParaTimeline(),
         )
         resultado = aplicador.aplicar(plano)
+        timeline_depois = conversor_de_timeline.converter(
+            acesso_ao_editor.obter_timeline_ativa()
+        )
+        verificacao = VerificadorDaAplicacao().verificar(
+            sequencia_ativa, timeline_depois, plano
+        )
 
     _registrar_no_banco(
         caminho_do_plano, resultado, sequencia_ativa.nome,
         plano_id=plano_id, caminho_do_banco=caminho_do_banco,
+        verificacao=verificacao,
     )
 
     return {
         "arquivo_de_origem": plano.arquivo_de_origem,
-        "todas_bem_sucedidas": resultado.todas_bem_sucedidas,
+        "todas_bem_sucedidas": resultado.todas_bem_sucedidas and verificacao.aprovada,
+        "verificacao": {
+            "aprovada": verificacao.aprovada,
+            "mensagem": verificacao.mensagem,
+            "divergencias": list(verificacao.divergencias),
+            "avisos": list(verificacao.avisos),
+        },
         "acoes": [
             {
                 "tipo": item.acao.tipo.value,

code/engine/consultar_detalhes_de_trilha.py

@@ -21,7 +21,8 @@ def consultar(caminho: Path, banco: Path) -> dict[str, object]:
         analise = conexao.execute(
             """SELECT a.id, a.provedor, a.modelo, a.duracao_em_segundos,
                       a.batidas_por_minuto, a.tonalidade, a.modo,
-                      a.intensidade, a.dancabilidade
+                      a.intensidade, a.dancabilidade, a.temas_json,
+                      a.instrumentos_json, a.etiquetas_json
                FROM trilhas_musicais t
                JOIN analises_musicais a ON a.trilha_id = t.id
               WHERE t.caminho = ?
@@ -44,6 +45,9 @@ def consultar(caminho: Path, banco: Path) -> dict[str, object]:
             "modo": analise["modo"],
             "intensidade": analise["intensidade"],
             "dancabilidade": analise["dancabilidade"],
+            "temas": json.loads(analise["temas_json"] or "[]"),
+            "instrumentos": json.loads(analise["instrumentos_json"] or "[]"),
+            "etiquetas_audio": json.loads(analise["etiquetas_json"] or "[]"),
             "etiquetas": [dict(etiqueta) for etiqueta in etiquetas],
         }
     finally:

code/engine/editor/__init__.py

@@ -1,4 +1,4 @@
-"""Aplicação de planos de edição (cortes, zooms, marcadores) na timeline do Premiere.
+"""Aplicação de planos de edição (cortes, ganchos e destaques) no Premiere.
 
 Lê o JSON de ações produzido pelas skills de seleção de trechos
 (``kind``/``start``/``end``/``params``/``reason``), traduz os tempos de
@@ -19,6 +19,7 @@ from .leitura import LeitorDePlanoDeEdicao
 from .mapeamento import MapeadorDeTempoDeOrigemParaTimeline
 from .modelos import AcaoDeEdicao, PlanoDeEdicao, TipoDeAcao
 from .validacao_semantica import ProblemaSemanticoDoPlano, ValidadorSemanticoDePlano
+from .verificador_da_aplicacao import ResultadoDaVerificacao, VerificadorDaAplicacao
 
 __all__ = [
     "AcaoDeEdicao",
@@ -37,4 +38,6 @@ __all__ = [
     "ResultadoDaAplicacao",
     "TipoDeAcao",
     "ValidadorSemanticoDePlano",
+    "ResultadoDaVerificacao",
+    "VerificadorDaAplicacao",
 ]

code/engine/editor/aplicador_de_plano_de_edicao.py

@@ -60,7 +60,9 @@ class AplicadorDePlanoDeEdicao:
        tudo que vem depois dele. Processar do fim para o começo garante que
        a posição de um corte ainda não aplicado nunca é afetada pelos
        cortes já aplicados.
-    2. Marcadores e zooms por último, depois que a timeline já está no
+    2. O gancho para abertura vem depois dos cortes. Ele localiza o trecho por
+       tempo da mídia original e cria uma cópia no começo da sequência.
+    3. Marcadores e zooms por último, depois que a timeline já está no
        formato final. Zoom (``set_clip_properties``) muda uma propriedade do
        *clipe inteiro*, não de um trecho dele — se dois zooms caíssem em
        instantes diferentes do mesmo clipe ainda não dividido pelos cortes,
@@ -107,10 +109,15 @@ class AplicadorDePlanoDeEdicao:
 
     def aplicar(self, plano: PlanoDeEdicao) -> ResultadoDaAplicacao:
         """Aplica todas as ações de ``plano`` e devolve o resultado de cada uma."""
-        pontuais = [acao for acao in plano.acoes if acao.tipo is not TipoDeAcao.CORTE]
+        ganchos = plano.acoes_do_tipo(TipoDeAcao.GANCHO)
+        pontuais = [
+            acao for acao in plano.acoes
+            if acao.tipo not in {TipoDeAcao.CORTE, TipoDeAcao.GANCHO}
+        ]
         cortes = sorted(plano.acoes_do_tipo(TipoDeAcao.CORTE), key=lambda acao: acao.inicio, reverse=True)
 
         resultados = [self._aplicar_corte(acao, plano.arquivo_de_origem) for acao in cortes]
+        resultados += [self._aplicar_gancho(acao, plano.arquivo_de_origem) for acao in ganchos]
         resultados += [self._aplicar_acao_pontual(acao, plano.arquivo_de_origem) for acao in pontuais]
         return ResultadoDaAplicacao(tuple(resultados))
 
@@ -189,6 +196,78 @@ class AplicadorDePlanoDeEdicao:
         except ErroDeEdicao as erro:
             return ResultadoDaAcao(acao, False, str(erro))
 
+    def _aplicar_gancho(self, acao: AcaoDeEdicao, arquivo_de_origem: str) -> ResultadoDaAcao:
+        """Recorta uma cópia de um par simples e a insere na abertura."""
+        try:
+            faixas = self._timeline_atual().faixas
+            faixas_afetadas = [
+                faixa for faixa in faixas
+                if any(
+                    self._sobrepoe(clipe, acao.inicio, acao.fim)
+                    for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+                )
+            ]
+            videos = [faixa for faixa in faixas_afetadas if faixa.tipo == "video"]
+            audios = [faixa for faixa in faixas_afetadas if faixa.tipo == "audio"]
+            if len(videos) != 1 or len(audios) != 1:
+                raise ErroDeMapeamentoDeTempo(
+                    "A ação hook exige exatamente uma faixa de vídeo e uma de áudio com o trecho de origem."
+                )
+            faixas_adicionais_ocupadas = [
+                faixa.identificador
+                for faixa in faixas
+                if faixa not in faixas_afetadas and faixa.clipes
+            ]
+            if faixas_adicionais_ocupadas:
+                raise ErroDeMapeamentoDeTempo(
+                    "A ação hook exige uma sequência simples; há conteúdo nas faixas adicionais: "
+                    + ", ".join(faixas_adicionais_ocupadas)
+                )
+            for faixa in faixas_afetadas:
+                afetados = [
+                    clipe for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+                    if self._sobrepoe(clipe, acao.inicio, acao.fim)
+                ]
+                if len(afetados) != 1:
+                    raise ErroDeMapeamentoDeTempo(
+                        f"A ação hook precisa estar contida em um único clipe da faixa {faixa.identificador!r}."
+                    )
+                intervalo_na_origem = afetados[0].intervalo_na_origem
+                if (
+                    intervalo_na_origem is None
+                    or acao.inicio < intervalo_na_origem.inicio - _TOLERANCIA_DE_BORDA_EM_SEGUNDOS
+                    or acao.fim > intervalo_na_origem.fim + _TOLERANCIA_DE_BORDA_EM_SEGUNDOS
+                ):
+                    raise ErroDeMapeamentoDeTempo(
+                        f"A ação hook ultrapassa o clipe da faixa {faixa.identificador!r}."
+                    )
+                inicio_na_timeline = self._borda_de_entrada(afetados[0], acao.inicio)
+                if inicio_na_timeline <= _TOLERANCIA_DE_BORDA_EM_SEGUNDOS:
+                    raise ErroDeMapeamentoDeTempo("O trecho da ação hook já está no início da sequência.")
+                if min(clipe.intervalo_na_timeline.inicio for clipe in faixa.clipes) > _TOLERANCIA_DE_BORDA_EM_SEGUNDOS:
+                    raise ErroDeMapeamentoDeTempo(
+                        f"A faixa {faixa.identificador!r} não começa em 0s; o gancho foi recusado."
+                    )
+
+            alvos = [
+                clipe
+                for faixa in faixas_afetadas
+                for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+                if self._sobrepoe(clipe, acao.inicio, acao.fim)
+            ]
+            if len(alvos) != 2:
+                raise ErroDeMapeamentoDeTempo(
+                    "O Premiere não localizou exatamente um clipe de vídeo e um de áudio para a ação hook."
+                )
+            self.escrita.duplicar_trecho_vinculado_para_o_inicio(
+                [clipe.identificador for clipe in alvos],
+                acao.inicio,
+                acao.fim,
+            )
+            return ResultadoDaAcao(acao, True, "gancho vinculado duplicado no início")
+        except ErroDeEdicao as erro:
+            return ResultadoDaAcao(acao, False, str(erro))
+
     def _preparar_alvos_da_faixa(
         self, faixa: Faixa, acao: AcaoDeEdicao, arquivo_de_origem: str
     ) -> list[Clipe]:

code/engine/editor/backup_de_sequencia.py

@@ -21,8 +21,8 @@ class BackupDaSequencia:
     def criar_backup(self, identificador_da_sequencia: str) -> bool:
         """Duplica a sequência. Devolve ``True`` se conseguiu, ``False`` se o Premiere recusou.
 
-        Não levanta exceção numa recusa: a engine registra a falha e continua
-        a aplicação solicitada, deixando a ausência de backup visível.
+        Não levanta exceção numa recusa: o chamador decide se a ação pode
+        continuar. Ganchos estruturais são bloqueados sem essa confirmação.
         """
         try:
             self.cliente_mcp.chamar("duplicate_sequence", {"sequence_id": identificador_da_sequencia})

code/engine/editor/escrita/escrita_no_editor.py

@@ -1,8 +1,9 @@
 """Escrita de mutações na sequência ativa do Premiere via MCP.
 
 Isola o nome das ferramentas MCP e o formato de argumentos externos
-(``split_clip``, ``remove_from_timeline``, ``remove_linked_from_timeline``, ``set_clip_properties``,
-``add_marker``) do resto do domínio. Quem chama esta classe fala só em
+(``split_clip``, ``remove_from_timeline``, ``remove_linked_from_timeline``,
+``duplicate_linked_range_to_start``, ``set_clip_properties``, ``add_marker``) do
+resto do domínio. Quem chama esta classe fala só em
 segundos de timeline, identificador de clipe e fator de escala — nunca em
 nomes de ferramenta ou ticks do Premiere.
 """
@@ -113,6 +114,34 @@ class EscritaNoEditor:
                 f"Não foi possível remover o par vinculado {identificadores_dos_clipes!r}: {erro}"
             ) from erro
 
+    def duplicar_trecho_vinculado_para_o_inicio(
+        self,
+        identificadores_dos_clipes: list[str],
+        inicio_na_origem: float,
+        fim_na_origem: float,
+    ) -> None:
+        """Copia parte de um par de vídeo e áudio para o início da sequência.
+
+        A ferramenta externa executa inserção com ripple, mantém a ocorrência
+        original intacta e confirma posição, duração e sincronismo. A operação
+        é recusada quando os identificadores não formam um par simples.
+        """
+        if len(identificadores_dos_clipes) != 2:
+            raise ErroDeEscritaNoEditor("O gancho exige exatamente um clipe de vídeo e um de áudio.")
+        try:
+            self.cliente_mcp.chamar(
+                "duplicate_linked_range_to_start",
+                {
+                    "node_ids": identificadores_dos_clipes,
+                    "source_in_seconds": inicio_na_origem,
+                    "source_out_seconds": fim_na_origem,
+                },
+            )
+        except ErroDeFerramentaMCP as erro:
+            raise ErroDeEscritaNoEditor(
+                f"Não foi possível duplicar o par vinculado {identificadores_dos_clipes!r} no início: {erro}"
+            ) from erro
+
     def aplicar_zoom(self, identificador_do_clipe: str, fator_de_escala: float) -> None:
         """Aplica um punch-in no clipe, escalando-o por ``fator_de_escala`` (1.0 = tamanho original).
 

code/engine/editor/modelos.py

@@ -14,12 +14,13 @@ from typing import Any
 
 
 class TipoDeAcao(str, Enum):
-    """Os quatro tipos de ação que o plano de edição pode descrever."""
+    """Os tipos de ação que o plano de edição pode descrever."""
 
     CORTE = "cut"
     ZOOM = "zoom"
     TEXTO = "text"
     MARCADOR = "marker"
+    GANCHO = "hook"
 
 
 @dataclass(frozen=True)
@@ -46,6 +47,13 @@ class AcaoDeEdicao:
             )
         if not self.motivo.strip():
             raise ValueError("Ação inválida: motivo não pode ser vazio.")
+        if self.tipo is TipoDeAcao.GANCHO:
+            destino = self.parametros.get("target", 0)
+            manter_original = self.parametros.get("keep_original", True)
+            if isinstance(destino, bool) or not isinstance(destino, (int, float)) or float(destino) != 0.0:
+                raise ValueError("Gancho inválido: params.target precisa ser 0 nesta versão.")
+            if manter_original is not True:
+                raise ValueError("Gancho inválido: params.keep_original precisa ser true.")
 
     @property
     def duracao(self) -> float:
@@ -63,6 +71,16 @@ class PlanoDeEdicao:
     def __post_init__(self) -> None:
         if not self.arquivo_de_origem.strip():
             raise ValueError("Plano de edição inválido: arquivo de origem não informado.")
+        ganchos = self.acoes_do_tipo(TipoDeAcao.GANCHO)
+        if len(ganchos) > 1:
+            raise ValueError("Plano de edição inválido: esta versão aceita somente uma ação hook.")
+        if ganchos:
+            gancho = ganchos[0]
+            for acao in self.acoes:
+                if acao is gancho:
+                    continue
+                if acao.inicio < gancho.fim and gancho.inicio < acao.fim:
+                    raise ValueError("Plano de edição inválido: outra ação não pode sobrepor o trecho do hook.")
 
     def acoes_do_tipo(self, tipo: TipoDeAcao) -> tuple[AcaoDeEdicao, ...]:
         """Devolve, na ordem original, só as ações do tipo informado."""

code/engine/editor/validacao_semantica.py

@@ -1,4 +1,4 @@
-"""Validação semântica das bordas de cortes antes de alterar a timeline."""
+"""Validação semântica de cortes e ganchos antes de alterar a timeline."""
 
 from __future__ import annotations
 
@@ -21,7 +21,7 @@ class ProblemaSemanticoDoPlano:
 
 
 class ValidadorSemanticoDePlano:
-    """Protege palavras, frases completas e respiros nas emendas de cortes."""
+    """Protege palavras, frases completas e respiros nas emendas editoriais."""
 
     _TOLERANCIA_EM_SEGUNDOS = 0.01
     _PONTUACAO_DE_FECHAMENTO = (".", "!", "?", "…")
@@ -37,12 +37,17 @@ class ValidadorSemanticoDePlano:
         plano: PlanoDeEdicao,
         falas: tuple[SegmentoDeTranscricao, ...],
     ) -> tuple[ProblemaSemanticoDoPlano, ...]:
-        """Devolve todos os problemas semânticos encontrados nas ações de corte."""
+        """Devolve os problemas semânticos encontrados em cortes e ganchos."""
         cortes = tuple(
             (indice, acao)
             for indice, acao in enumerate(plano.acoes)
             if acao.tipo is TipoDeAcao.CORTE
         )
+        ganchos = tuple(
+            (indice, acao)
+            for indice, acao in enumerate(plano.acoes)
+            if acao.tipo is TipoDeAcao.GANCHO
+        )
         palavras = tuple(
             sorted(
                 (palavra for fala in falas for palavra in fala.palavras),
@@ -54,6 +59,9 @@ class ValidadorSemanticoDePlano:
             problemas.extend(self._validar_palavras_interceptadas(indice, corte, palavras))
             problemas.extend(self._validar_borda_inicial(indice, corte, cortes, palavras))
             problemas.extend(self._validar_borda_final(indice, corte, cortes, falas, palavras))
+        for indice, gancho in ganchos:
+            problemas.extend(self._validar_palavras_interceptadas(indice, gancho, palavras))
+            problemas.extend(self._validar_frase_do_gancho(indice, gancho, falas, palavras))
         return tuple(problemas)
 
     def garantir_valido(
@@ -61,7 +69,7 @@ class ValidadorSemanticoDePlano:
         plano: PlanoDeEdicao,
         falas: tuple[SegmentoDeTranscricao, ...],
     ) -> None:
-        """Levanta erro explicativo quando qualquer corte ameaça a fala mantida."""
+        """Levanta erro explicativo quando uma emenda ameaça a integridade da fala."""
         problemas = self.validar(plano, falas)
         if not problemas:
             return
@@ -70,6 +78,71 @@ class ValidadorSemanticoDePlano:
             "Plano bloqueado pela validação de integridade da fala: " + detalhes
         )
 
+    def _validar_frase_do_gancho(
+        self,
+        indice: int,
+        gancho: AcaoDeEdicao,
+        falas: tuple[SegmentoDeTranscricao, ...],
+        palavras: tuple[PalavraDeTranscricao, ...],
+    ) -> list[ProblemaSemanticoDoPlano]:
+        """Confirma que o gancho duplicado começa e termina como uma fala completa."""
+        contidas = tuple(
+            palavra for palavra in palavras
+            if gancho.inicio - self._TOLERANCIA_EM_SEGUNDOS <= palavra.inicio
+            and palavra.fim <= gancho.fim + self._TOLERANCIA_EM_SEGUNDOS
+        )
+        if not contidas:
+            return [ProblemaSemanticoDoPlano(
+                codigo="gancho_sem_fala",
+                mensagem=f"ação {indice + 1}: o trecho do gancho não contém palavras temporizadas",
+                indice_da_acao=indice,
+                instante=gancho.inicio,
+            )]
+
+        primeira, ultima = contidas[0], contidas[-1]
+        problemas: list[ProblemaSemanticoDoPlano] = []
+        if primeira.inicio - gancho.inicio < self._margem_minima - self._TOLERANCIA_EM_SEGUNDOS:
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="margem_inicial_do_gancho_insuficiente",
+                mensagem=(
+                    f"ação {indice + 1}: deixe ao menos {self._margem_minima:.2f}s antes "
+                    f'da primeira palavra do gancho "{primeira.texto}"'
+                ),
+                indice_da_acao=indice,
+                instante=gancho.inicio,
+            ))
+        if gancho.fim - ultima.fim < self._margem_minima - self._TOLERANCIA_EM_SEGUNDOS:
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="margem_final_do_gancho_insuficiente",
+                mensagem=(
+                    f"ação {indice + 1}: deixe ao menos {self._margem_minima:.2f}s após "
+                    f'a última palavra do gancho "{ultima.texto}"'
+                ),
+                indice_da_acao=indice,
+                instante=gancho.fim,
+            ))
+        fala_inicial = self._fala_da_palavra(primeira, falas)
+        primeira_letra = next((letra for letra in primeira.texto if letra.isalpha()), "")
+        comeca_no_meio = (
+            fala_inicial is not None
+            and primeira.inicio > fala_inicial.inicio + self._TOLERANCIA_EM_SEGUNDOS
+        ) or bool(primeira_letra and primeira_letra.islower())
+        if comeca_no_meio:
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="gancho_comeca_no_meio_da_frase",
+                mensagem=f'ação {indice + 1}: o gancho começa em "{primeira.texto}", no meio da frase',
+                indice_da_acao=indice,
+                instante=gancho.inicio,
+            ))
+        if not ultima.texto.rstrip().endswith(self._PONTUACAO_DE_FECHAMENTO):
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="gancho_termina_no_meio_da_frase",
+                mensagem=f'ação {indice + 1}: o gancho termina em "{ultima.texto}" sem concluir a frase',
+                indice_da_acao=indice,
+                instante=gancho.fim,
+            ))
+        return problemas
+
     def _validar_palavras_interceptadas(
         self,
         indice: int,

code/engine/editor/verificador_da_aplicacao.py

@@ -0,0 +1,183 @@
+"""Verificação estrutural da timeline depois da aplicação de um plano.
+
+Compara a cobertura de origem que deveria sobreviver aos cortes com a
+cobertura realmente lida no Premiere depois da mutação. A verificação não
+avalia pixels, áudio ou qualidade editorial; ela detecta sobras, lacunas e
+desalinhamentos estruturais em cada tipo de faixa.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..dominio import Clipe, Faixa, IntervaloDeTempo, Timeline
+from .modelos import PlanoDeEdicao, TipoDeAcao
+
+
+_TOLERANCIA_EM_SEGUNDOS = 0.05
+
+
+@dataclass(frozen=True)
+class ResultadoDaVerificacao:
+    """Resultado da comparação entre a timeline esperada e a timeline lida."""
+
+    aprovada: bool
+    divergencias: tuple[str, ...] = ()
+    avisos: tuple[str, ...] = ()
+
+    @property
+    def mensagem(self) -> str:
+        """Resume a verificação em uma mensagem adequada para o histórico."""
+        if self.aprovada:
+            mensagem = "verificação pós-aplicação aprovada"
+        else:
+            mensagem = "verificação pós-aplicação reprovada: " + " | ".join(self.divergencias)
+        if self.avisos:
+            mensagem += "; avisos: " + " | ".join(self.avisos)
+        return mensagem
+
+
+class VerificadorDaAplicacao:
+    """Confere se a cobertura de mídia depois da aplicação bate com o plano."""
+
+    def __init__(self, tolerancia_em_segundos: float = _TOLERANCIA_EM_SEGUNDOS) -> None:
+        """Configura a tolerância de arredondamento do Premiere."""
+        if tolerancia_em_segundos < 0:
+            raise ValueError("A tolerância da verificação não pode ser negativa.")
+        self._tolerancia = tolerancia_em_segundos
+
+    def verificar(
+        self,
+        timeline_antes: Timeline,
+        timeline_depois: Timeline,
+        plano: PlanoDeEdicao,
+    ) -> ResultadoDaVerificacao:
+        """Compara os intervalos de origem sobreviventes antes e depois da aplicação."""
+        tipos_de_faixa = {faixa.tipo for faixa in timeline_antes.faixas}
+        divergencias: list[str] = []
+        avisos: list[str] = []
+        cortes = tuple(
+            acao for acao in plano.acoes if acao.tipo is TipoDeAcao.CORTE
+        )
+        for tipo_de_faixa in sorted(tipos_de_faixa):
+            esperados = self._intervalos_esperados(
+                timeline_antes, tipo_de_faixa, plano.arquivo_de_origem, cortes
+            )
+            encontrados = self._intervalos_da_timeline(
+                timeline_depois, tipo_de_faixa, plano.arquivo_de_origem
+            )
+            if not self._intervalos_equivalentes(esperados, encontrados):
+                divergencias.append(
+                    f"faixa {tipo_de_faixa}: esperado {self._formatar_intervalos(esperados)}, "
+                    f"encontrado {self._formatar_intervalos(encontrados)}"
+                )
+        avisos.extend(self._avisar_material_posterior_à_ultima_acao(
+            timeline_depois, plano, tipo_de_faixa
+        ))
+        return ResultadoDaVerificacao(not divergencias, tuple(divergencias), tuple(avisos))
+
+    def _avisar_material_posterior_à_ultima_acao(
+        self, timeline: Timeline, plano: PlanoDeEdicao, tipo_de_faixa: str
+    ) -> list[str]:
+        """Sinaliza material depois da última ação para revisão editorial."""
+        if not plano.acoes:
+            return []
+        ultima_acao = max(plano.acoes, key=lambda acao: acao.fim)
+        if ultima_acao.tipo is not TipoDeAcao.CORTE:
+            return []
+        sobras = [
+            clipe.intervalo_na_origem.fim
+            for faixa in timeline.faixas
+            if faixa.tipo == tipo_de_faixa
+            for clipe in self._clipes_do_arquivo(faixa, plano.arquivo_de_origem)
+            if clipe.intervalo_na_origem.inicio >= ultima_acao.fim - self._tolerancia
+            and clipe.intervalo_na_origem.fim > ultima_acao.fim + self._tolerancia
+        ]
+        if not sobras:
+            return []
+        return [
+            f"faixa {tipo_de_faixa}: há material após a última ação, "
+            f"a partir de {ultima_acao.fim:.2f}s; conferir possível sobra"
+        ]
+
+    def _intervalos_esperados(
+        self,
+        timeline: Timeline,
+        tipo_de_faixa: str,
+        arquivo_de_origem: str,
+        cortes: tuple,
+    ) -> tuple[tuple[float, float], ...]:
+        intervalos: list[tuple[float, float]] = []
+        for faixa in timeline.faixas:
+            if faixa.tipo != tipo_de_faixa:
+                continue
+            for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem):
+                intervalos.extend(self._subtrair_cortes(clipe.intervalo_na_origem, cortes))
+        return self._normalizar_intervalos(intervalos)
+
+    def _intervalos_da_timeline(
+        self, timeline: Timeline, tipo_de_faixa: str, arquivo_de_origem: str
+    ) -> tuple[tuple[float, float], ...]:
+        intervalos = [
+            (clipe.intervalo_na_origem.inicio, clipe.intervalo_na_origem.fim)
+            for faixa in timeline.faixas
+            if faixa.tipo == tipo_de_faixa
+            for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+        ]
+        return self._normalizar_intervalos(intervalos)
+
+    def _subtrair_cortes(self, intervalo: IntervaloDeTempo, cortes: tuple) -> list[tuple[float, float]]:
+        partes = [(intervalo.inicio, intervalo.fim)]
+        for corte in cortes:
+            novas_partes: list[tuple[float, float]] = []
+            for inicio, fim in partes:
+                if corte.fim <= inicio or corte.inicio >= fim:
+                    novas_partes.append((inicio, fim))
+                    continue
+                if inicio < corte.inicio:
+                    novas_partes.append((inicio, min(fim, corte.inicio)))
+                if corte.fim < fim:
+                    novas_partes.append((max(inicio, corte.fim), fim))
+            partes = novas_partes
+        return partes
+
+    def _intervalos_equivalentes(
+        self, esperados: tuple[tuple[float, float], ...], encontrados: tuple[tuple[float, float], ...]
+    ) -> bool:
+        if len(esperados) != len(encontrados):
+            return False
+        return all(
+            abs(inicio_esperado - inicio_encontrado) <= self._tolerancia
+            and abs(fim_esperado - fim_encontrado) <= self._tolerancia
+            for (inicio_esperado, fim_esperado), (inicio_encontrado, fim_encontrado)
+            in zip(esperados, encontrados)
+        )
+
+    def _clipes_do_arquivo(self, faixa: Faixa, arquivo_de_origem: str) -> list[Clipe]:
+        nome_alvo = arquivo_de_origem.rsplit("/", 1)[-1].lower()
+        return [
+            clipe for clipe in faixa.clipes
+            if clipe.intervalo_na_origem is not None
+            and (clipe.nome or "").rsplit("/", 1)[-1].lower() == nome_alvo
+        ]
+
+    def _normalizar_intervalos(
+        self, intervalos: list[tuple[float, float]]
+    ) -> tuple[tuple[float, float], ...]:
+        ordenados = sorted(intervalos)
+        unidos: list[list[float]] = []
+        for inicio, fim in ordenados:
+            if fim <= inicio + self._tolerancia:
+                continue
+            if unidos and inicio <= unidos[-1][1] + self._tolerancia:
+                unidos[-1][1] = max(unidos[-1][1], fim)
+            else:
+                unidos.append([inicio, fim])
+        return tuple((inicio, fim) for inicio, fim in unidos)
+
+    @staticmethod
+    def _formatar_intervalos(intervalos: tuple[tuple[float, float], ...]) -> str:
+        """Formata intervalos para mensagens curtas e conferíveis."""
+        if not intervalos:
+            return "[]"
+        return "[" + ", ".join(f"{inicio:.2f}-{fim:.2f}s" for inicio, fim in intervalos) + "]"

code/engine/integracoes/audio/classificador_de_musica_essentia.py

@@ -36,7 +36,7 @@ class ClassificadorDeMusicaEssentia:
 
     def classificar(
         self, arquivo: str | Path,
-    ) -> tuple[tuple[PontuacaoDeEtiqueta, ...], tuple[PontuacaoDeEtiqueta, ...]]:
+    ) -> tuple[tuple[PontuacaoDeEtiqueta, ...], tuple[PontuacaoDeEtiqueta, ...], tuple[PontuacaoDeEtiqueta, ...]]:
         """
         Classifica o gênero e o humor diretamente do conteúdo do arquivo.
 
@@ -71,11 +71,19 @@ class ClassificadorDeMusicaEssentia:
         embedding = modelo_de_embedding(audio)
         previsao_de_genero = modelo_de_genero(embedding)
         previsao_de_humor = modelo_de_humor(embedding)
+        pontuacoes_de_humor = self._converter_pontuacoes(previsao_de_humor, "humor")
+        nomes_de_tema = {"action", "adventure", "advertising", "background", "children", "christmas", "commercial", "corporate", "documentary", "drama", "film", "game", "movie", "nature", "sport", "trailer", "travel"}
         return (
-            self._converter_pontuacoes(previsao_de_genero, "genero"),
-            self._converter_pontuacoes(previsao_de_humor, "humor"),
+            self._duas_maiores(self._converter_pontuacoes(previsao_de_genero, "genero")),
+            self._duas_maiores(tuple(item for item in pontuacoes_de_humor if item.etiqueta not in nomes_de_tema)),
+            self._duas_maiores(tuple(item for item in pontuacoes_de_humor if item.etiqueta in nomes_de_tema)),
         )
 
+    @staticmethod
+    def _duas_maiores(pontuacoes: tuple[PontuacaoDeEtiqueta, ...]) -> tuple[PontuacaoDeEtiqueta, ...]:
+        """Retorna as duas maiores probabilidades, preservando o ranking."""
+        return pontuacoes[:2]
+
     def _obter_modelos(self, classe_de_embedding: Any, classe_de_classificacao: Any):
         if self._modelos_carregados is not None:
             return self._modelos_carregados

code/engine/integracoes/audio/modelos_de_analise_musical.py

@@ -41,5 +41,7 @@ class ResultadoDaAnaliseMusical:
     etiquetas: tuple[str, ...] = field(default_factory=tuple)
     pontuacoes_de_genero: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
     pontuacoes_de_humor: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
+    pontuacoes_de_tema: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
+    temas: tuple[str, ...] = field(default_factory=tuple)
     provedor: str = "Essentia"
     modelo: str | None = None

code/engine/integracoes/audio/provider_de_analise_musical_essentia.py

@@ -57,8 +57,12 @@ class AnalisadorDeMusicaInstrumentalEssentia:
             raise ValueError("O Essentia devolveu uma análise vazia.")
         pontuacoes_de_genero: tuple[Any, ...] = ()
         pontuacoes_de_humor: tuple[Any, ...] = ()
+        pontuacoes_de_tema: tuple[Any, ...] = ()
         if self._classificador is not None:
-            pontuacoes_de_genero, pontuacoes_de_humor = self._classificador.classificar(caminho)
+            classificacoes = self._classificador.classificar(caminho)
+            pontuacoes_de_genero, pontuacoes_de_humor = classificacoes[:2]
+            if len(classificacoes) > 2:
+                pontuacoes_de_tema = classificacoes[2]
         generos = (
             tuple(item.etiqueta for item in pontuacoes_de_genero)
             if pontuacoes_de_genero
@@ -70,7 +74,7 @@ class AnalisadorDeMusicaInstrumentalEssentia:
             else self._etiquetas(dados, ("mood", "moods"))
         )
         return self._converter_resultado(
-            caminho, dados, pontuacoes_de_genero, pontuacoes_de_humor, generos, humores,
+            caminho, dados, pontuacoes_de_genero, pontuacoes_de_humor, generos, humores, pontuacoes_de_tema,
         )
 
     def _obter_extrator(self) -> Callable[[str], tuple[Any, Any]]:
@@ -94,6 +98,7 @@ class AnalisadorDeMusicaInstrumentalEssentia:
         pontuacoes_de_humor: tuple[Any, ...] = (),
         generos: tuple[str, ...] = (),
         humores: tuple[str, ...] = (),
+        pontuacoes_de_tema: tuple[Any, ...] = (),
     ) -> ResultadoDaAnaliseMusical:
         return ResultadoDaAnaliseMusical(
             caminho_do_arquivo=caminho,
@@ -105,10 +110,12 @@ class AnalisadorDeMusicaInstrumentalEssentia:
             dancabilidade=self._numero(self._buscar(dados, "rhythm.danceability")),
             generos=generos,
             humores=humores,
+            temas=tuple(item.etiqueta for item in pontuacoes_de_tema),
             instrumentos=self._etiquetas(dados, ("instrument", "instruments")),
             etiquetas=self._etiquetas(dados, ("tags", "semantic")),
             pontuacoes_de_genero=pontuacoes_de_genero,
             pontuacoes_de_humor=pontuacoes_de_humor,
+            pontuacoes_de_tema=pontuacoes_de_tema,
             modelo=self._nome_do_modelo,
         )
 

code/engine/persistencia/esquema.py

@@ -94,6 +94,9 @@ CREATE TABLE IF NOT EXISTS analises_musicais (
     modo TEXT,
     intensidade REAL,
     dancabilidade REAL,
+    temas_json TEXT,
+    instrumentos_json TEXT,
+    etiquetas_json TEXT,
     resultado_bruto_json TEXT,
     criada_em TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
 );
@@ -512,6 +515,9 @@ _VIEWS = (
 )
 
 _COLUNAS_ACRESCENTADAS: tuple[tuple[str, str, str], ...] = (
+    ("analises_musicais", "temas_json", "TEXT"),
+    ("analises_musicais", "instrumentos_json", "TEXT"),
+    ("analises_musicais", "etiquetas_json", "TEXT"),
     ("segmentos_de_transcricao", "energia_rms", "REAL"),
     ("segmentos_de_transcricao", "pitch_mediano_hz", "REAL"),
     ("segmentos_de_transcricao", "pitch_desvio_hz", "REAL"),

code/engine/persistencia/repositorio_de_trilhas.py

@@ -78,9 +78,24 @@ class RepositorioDeTrilhasSQLite:
                 (trilha_id,),
             )
 
+    def reabrir_analises_sem_etiquetas(self, pasta_id: int | None = None) -> None:
+        """Volta a enfileirar análises antigas que não têm classificação semântica."""
+        filtro = "" if pasta_id is None else " AND t.pasta_id = ?"
+        parametros = () if pasta_id is None else (pasta_id,)
+        with self.conexao:
+            self.conexao.execute(
+                """UPDATE trilhas_musicais AS t SET status = 'aguardando', erro = NULL
+                   WHERE t.status = 'concluida' AND EXISTS (
+                       SELECT 1 FROM analises_musicais AS a
+                       WHERE a.trilha_id = t.id
+                         AND NOT EXISTS (SELECT 1 FROM etiquetas_musicais e WHERE e.analise_id = a.id)
+                   )""" + filtro,
+                parametros,
+            )
+
     def registrar_analise(self, trilha: TrilhaMusical, resultado: ResultadoDaAnaliseMusical) -> None:
         """Grava descritores e etiquetas produzidos pelo áudio da trilha."""
-        bruto = json.dumps({"generos": resultado.generos, "humores": resultado.humores}, ensure_ascii=False)
+        bruto = json.dumps({"generos": resultado.generos, "humores": resultado.humores, "temas": resultado.temas, "instrumentos": resultado.instrumentos, "etiquetas": resultado.etiquetas}, ensure_ascii=False)
         with self.conexao:
             self.conexao.execute(
                 "UPDATE trilhas_musicais SET hash_do_conteudo = ?, status = 'concluida', erro = NULL, atualizada_em = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
@@ -88,14 +103,14 @@ class RepositorioDeTrilhasSQLite:
             )
             cursor = self.conexao.execute(
                 """INSERT INTO analises_musicais
-                   (trilha_id, provedor, modelo, duracao_em_segundos, batidas_por_minuto, tonalidade, modo, intensidade, dancabilidade, resultado_bruto_json)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                   (trilha_id, provedor, modelo, duracao_em_segundos, batidas_por_minuto, tonalidade, modo, intensidade, dancabilidade, temas_json, instrumentos_json, etiquetas_json, resultado_bruto_json)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                 (trilha.identificador, resultado.provedor, resultado.modelo, resultado.duracao_em_segundos,
                  resultado.batidas_por_minuto, resultado.tonalidade, resultado.modo, resultado.intensidade,
-                 resultado.dancabilidade, bruto),
+                 resultado.dancabilidade, json.dumps(resultado.temas, ensure_ascii=False), json.dumps(resultado.instrumentos, ensure_ascii=False), json.dumps(resultado.etiquetas, ensure_ascii=False), bruto),
             )
             analise_id = cursor.lastrowid
-            for tipo, etiquetas in (("genero", resultado.pontuacoes_de_genero), ("humor", resultado.pontuacoes_de_humor)):
+            for tipo, etiquetas in (("genero", resultado.pontuacoes_de_genero), ("humor", resultado.pontuacoes_de_humor), ("tema", resultado.pontuacoes_de_tema)):
                 self.conexao.executemany(
                     "INSERT INTO etiquetas_musicais(analise_id, tipo, etiqueta, confianca, ordem) VALUES (?, ?, ?, ?, ?)",
                     ((analise_id, tipo, item.etiqueta, item.confianca, ordem) for ordem, item in enumerate(etiquetas)),

code/engine/testes/duplos_de_premiere.py

@@ -5,7 +5,8 @@ têm posição na timeline diferente da posição no arquivo de origem — o mes
 descompasso encontrado no projeto real entre ``inicio_na_timeline`` e
 ``inicio_na_origem`` do banco de análises. Implementa só as ferramentas MCP
 que o módulo ``engine.editor`` usa: ``get_active_sequence``, ``split_clip``,
-``remove_from_timeline``, ``remove_linked_from_timeline``, ``set_clip_properties`` e ``add_marker``.
+``remove_from_timeline``, ``remove_linked_from_timeline``,
+``duplicate_linked_range_to_start``, ``set_clip_properties`` e ``add_marker``.
 """
 
 from __future__ import annotations
@@ -100,6 +101,7 @@ class ClienteMCPFalso(ClienteMCP):
             "split_clip": self._simular_split_clip,
             "remove_from_timeline": self._simular_ripple_delete,
             "remove_linked_from_timeline": self._simular_remocao_vinculada,
+            "duplicate_linked_range_to_start": self._simular_gancho_vinculado_no_inicio,
             "set_clip_properties": self._simular_set_clip_properties,
             "add_marker": self._simular_add_marker,
             "undo": self._simular_undo,
@@ -223,6 +225,43 @@ class ClienteMCPFalso(ClienteMCP):
             self._simular_ripple_delete({"node_id": identificador, "ripple": True})
         return {"removed": True, "verified": True}
 
+    def _simular_gancho_vinculado_no_inicio(self, argumentos: dict[str, Any]) -> dict[str, Any]:
+        """Duplica um par isolado no início e preserva sua ocorrência original."""
+        identificadores = argumentos["node_ids"]
+        encontrados: list[tuple[str, _ClipeFalso]] = []
+        for identificador_da_faixa, clipes in self._faixas.items():
+            for clipe in clipes:
+                if clipe.identificador in identificadores:
+                    encontrados.append((identificador_da_faixa, clipe))
+        if len(encontrados) != 2 or {faixa.split("_")[0] for faixa, _ in encontrados} != {"video", "audio"}:
+            raise ErroDeFerramentaMCP("O gancho exige um par de vídeo e áudio existente.")
+        inicios = {round(clipe.inicio_na_timeline, 6) for _, clipe in encontrados}
+        fins = {round(clipe.fim_na_timeline, 6) for _, clipe in encontrados}
+        if len(inicios) != 1 or len(fins) != 1:
+            raise ErroDeFerramentaMCP("O par não ocupa o mesmo intervalo.")
+
+        self._salvar_estado()
+        inicio_na_origem = float(argumentos["source_in_seconds"])
+        fim_na_origem = float(argumentos["source_out_seconds"])
+        duracao = fim_na_origem - inicio_na_origem
+        novos_ids: list[str] = []
+        for identificador_da_faixa, clipe in encontrados:
+            faixa = self._faixas[identificador_da_faixa]
+            for outro in faixa:
+                outro.inicio_na_timeline += duracao
+                outro.fim_na_timeline += duracao
+            novo = self._novo_clipe(
+                clipe.nome,
+                0.0,
+                duracao,
+                inicio_na_origem,
+                fim_na_origem,
+            )
+            faixa.append(novo)
+            faixa.sort(key=lambda item: item.inicio_na_timeline)
+            novos_ids.append(novo.identificador)
+        return {"duplicated": True, "verified": True, "insertedNodeIds": novos_ids}
+
     def _simular_set_clip_properties(self, argumentos: dict[str, Any]) -> dict[str, Any]:
         """Aceita a alteração de propriedades sem simular geometria (não é usada pelos testes)."""
         del argumentos

code/engine/testes/test_aplicador_de_plano_de_edicao.py

@@ -249,6 +249,64 @@ class TesteAplicadorDePlanoDeEdicao(unittest.TestCase):
         self.assertEqual(len(chamadas_de_marcador), 1)
         self.assertIn("MASTOPEXIA", chamadas_de_marcador[0][1]["comments"])
 
+    def test_gancho_isola_video_e_audio_e_duplica_no_inicio(self):
+        cliente = ClienteMCPFalso(clipe_unico=True)
+        aplicador = AplicadorDePlanoDeEdicao(
+            acesso_ao_editor=AcessoAoEditor(AcessoATimeline(cliente)),
+            conversor_de_timeline=ConversorDeTimeline(),
+            escrita=EscritaNoEditor(cliente),
+            mapeador=MapeadorDeTempoDeOrigemParaTimeline(),
+        )
+        plano = PlanoDeEdicao("0E6A8290.mp4", (
+            AcaoDeEdicao(
+                TipoDeAcao.GANCHO,
+                inicio=80.0,
+                fim=90.0,
+                motivo="gancho de abertura",
+                parametros={"target": 0, "keep_original": True},
+            ),
+        ))
+
+        resultado = aplicador.aplicar(plano)
+
+        self.assertTrue(resultado.todas_bem_sucedidas, msg=[item.detalhe for item in resultado.falhas])
+        ganchos = [chamada for chamada in cliente.chamadas if chamada[0] == "duplicate_linked_range_to_start"]
+        self.assertEqual(len(ganchos), 1)
+        self.assertEqual(len(ganchos[0][1]["node_ids"]), 2)
+        self.assertEqual(cliente._faixas["video_0"][0].inicio_na_origem, 80.0)
+        self.assertEqual(cliente._faixas["audio_0"][0].inicio_na_origem, 80.0)
+        self.assertEqual(cliente._faixas["video_0"][0].inicio_na_timeline, 0.0)
+        self.assertEqual(cliente._faixas["audio_0"][0].inicio_na_timeline, 0.0)
+        self.assertEqual(
+            sum(1 for clipe in cliente._faixas["video_0"] if clipe.inicio_na_origem == 80.0),
+            2,
+        )
+        self.assertEqual(
+            sum(1 for clipe in cliente._faixas["audio_0"] if clipe.inicio_na_origem == 80.0),
+            2,
+        )
+
+    def test_gancho_e_executado_apos_cortes_e_antes_de_zoom(self):
+        cliente = ClienteMCPFalso(clipe_unico=True)
+        aplicador = AplicadorDePlanoDeEdicao(
+            acesso_ao_editor=AcessoAoEditor(AcessoATimeline(cliente)),
+            conversor_de_timeline=ConversorDeTimeline(),
+            escrita=EscritaNoEditor(cliente),
+            mapeador=MapeadorDeTempoDeOrigemParaTimeline(),
+        )
+        plano = PlanoDeEdicao("0E6A8290.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 20.0, 30.0, "retirar bastidor"),
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 80.0, 90.0, "gancho"),
+            AcaoDeEdicao(TipoDeAcao.ZOOM, 100.0, 105.0, "ênfase", {"scale": 1.15}),
+        ))
+
+        resultado = aplicador.aplicar(plano)
+
+        self.assertTrue(resultado.todas_bem_sucedidas, msg=[item.detalhe for item in resultado.falhas])
+        nomes = [nome for nome, _ in cliente.chamadas]
+        self.assertLess(nomes.index("remove_linked_from_timeline"), nomes.index("duplicate_linked_range_to_start"))
+        self.assertLess(nomes.index("duplicate_linked_range_to_start"), nomes.index("set_clip_properties"))
+
 
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_aplicar_plano_de_edicao.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from unittest.mock import patch
 
 from engine import aplicar_plano_de_edicao
-from engine.editor import ErroDePlanoInvalido
+from engine.editor import AcaoDeEdicao, ErroDePlanoInvalido, PlanoDeEdicao, TipoDeAcao
 
 
 class TesteResolucaoDoNode(unittest.TestCase):
@@ -62,6 +62,23 @@ class TestePreValidacaoDoPlano(unittest.TestCase):
         validar.assert_called_once()
         resolver_node.assert_not_called()
 
+    def test_gancho_exige_backup_confirmado(self) -> None:
+        """A operação composta não começa quando a recuperação não foi criada."""
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 10.0, 15.0, "gancho"),
+        ))
+
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "não confirmou o backup"):
+            aplicar_plano_de_edicao._garantir_backup_para_ganchos(plano, False)
+
+    def test_corte_preserva_comportamento_legado_quando_backup_falha(self) -> None:
+        """A exigência adicional fica restrita ao gancho estrutural."""
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 10.0, 15.0, "retirada"),
+        ))
+
+        aplicar_plano_de_edicao._garantir_backup_para_ganchos(plano, False)
+
     def test_painel_rejeita_corte_sem_plano_associado_ao_banco(self) -> None:
         """Não permite contornar a validação colando um corte sem transcrição vinculada."""
         with tempfile.TemporaryDirectory() as pasta:

code/engine/testes/test_escrita_no_editor.py

@@ -71,5 +71,19 @@ class TesteDividirClipeSeNecessario(unittest.TestCase):
             self._dividir("razor changed the track clip count from 4 to 7, expected 5")
 
 
+class TesteDuplicarTrechosVinculados(unittest.TestCase):
+    """Cobre o contrato estreito da escrita do gancho editorial."""
+
+    def test_exige_exatamente_dois_identificadores(self):
+        escrita = EscritaNoEditor(_ClienteQueRecusa("não deveria chamar"))
+        with self.assertRaisesRegex(ErroDeEscritaNoEditor, "exatamente"):
+            escrita.duplicar_trecho_vinculado_para_o_inicio(["somente-video"], 10.0, 15.0)
+
+    def test_converte_falha_da_ferramenta_em_erro_de_escrita(self):
+        escrita = EscritaNoEditor(_ClienteQueRecusa("faixa adicional ocupada"))
+        with self.assertRaisesRegex(ErroDeEscritaNoEditor, "faixa adicional ocupada"):
+            escrita.duplicar_trecho_vinculado_para_o_inicio(["video", "audio"], 10.0, 15.0)
+
+
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_leitor_de_plano_de_edicao.py

@@ -66,6 +66,50 @@ class TesteLeitorDePlanoDeEdicao(unittest.TestCase):
                 "actions": [{"kind": "voar", "start": 0, "end": 1, "reason": "x"}],
             })
 
+    def test_le_gancho_duplicado_para_o_inicio(self):
+        plano = self.leitor.ler_de_dicionario({
+            "source": "a.mp4",
+            "actions": [{
+                "kind": "hook",
+                "start": 40,
+                "end": 46,
+                "reason": "gancho de abertura",
+                "params": {"target": 0, "keep_original": True},
+            }],
+        })
+        self.assertEqual(plano.acoes[0].tipo, TipoDeAcao.GANCHO)
+        self.assertEqual(plano.acoes[0].parametros["target"], 0)
+
+    def test_gancho_para_destino_diferente_do_inicio_e_rejeitado(self):
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "target precisa ser 0"):
+            self.leitor.ler_de_dicionario({
+                "source": "a.mp4",
+                "actions": [{
+                    "kind": "hook", "start": 40, "end": 46,
+                    "reason": "reordenar", "params": {"target": 12},
+                }],
+            })
+
+    def test_gancho_que_remove_o_original_e_rejeitado(self):
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "keep_original precisa ser true"):
+            self.leitor.ler_de_dicionario({
+                "source": "a.mp4",
+                "actions": [{
+                    "kind": "hook", "start": 40, "end": 46,
+                    "reason": "abertura", "params": {"keep_original": False},
+                }],
+            })
+
+    def test_corte_sobreposto_ao_gancho_e_rejeitado(self):
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "não pode sobrepor"):
+            self.leitor.ler_de_dicionario({
+                "source": "a.mp4",
+                "actions": [
+                    {"kind": "cut", "start": 42, "end": 44, "reason": "cortar"},
+                    {"kind": "hook", "start": 40, "end": 46, "reason": "abertura"},
+                ],
+            })
+
     def test_fim_menor_ou_igual_ao_inicio_levanta_erro(self):
         with self.assertRaises(ErroDePlanoInvalido):
             self.leitor.ler_de_dicionario({

code/engine/testes/test_validador_semantico_de_plano.py

@@ -1,4 +1,4 @@
-"""Testes de regressão da integridade semântica dos cortes editoriais."""
+"""Testes de regressão da integridade semântica das emendas editoriais."""
 
 import unittest
 
@@ -8,7 +8,7 @@ from engine.scanner.modelos import PalavraDeTranscricao, SegmentoDeTranscricao
 
 
 class TesteValidadorSemanticoDePlano(unittest.TestCase):
-    """Impede cortes de palavra e retomadas no meio de uma frase."""
+    """Impede cortes de palavra, frases incompletas e ganchos truncados."""
 
     def setUp(self) -> None:
         """Cria o validador com a margem segura usada pela aplicação real."""
@@ -104,6 +104,46 @@ class TesteValidadorSemanticoDePlano(unittest.TestCase):
 
         self.assertIn("palavra_interceptada", {problema.codigo for problema in problemas})
 
+    def test_aceita_gancho_de_frase_completa_com_margens(self) -> None:
+        falas = (
+            SegmentoDeTranscricao(0.0, 4.0, "Antes.", palavras=(
+                PalavraDeTranscricao("Antes.", 3.4, 4.0),
+            )),
+            SegmentoDeTranscricao(10.4, 13.5, "Gancho completo.", palavras=(
+                PalavraDeTranscricao("Gancho", 10.4, 10.9),
+                PalavraDeTranscricao("completo.", 13.0, 13.5),
+            )),
+            SegmentoDeTranscricao(20.0, 21.0, "Depois.", palavras=(
+                PalavraDeTranscricao("Depois.", 20.0, 21.0),
+            )),
+        )
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 10.1, 13.8, "gancho"),
+        ))
+
+        self.assertEqual(self.validador.validar(plano, falas), ())
+
+    def test_rejeita_gancho_que_termina_com_frase_truncada(self) -> None:
+        falas = (
+            SegmentoDeTranscricao(0.0, 4.0, "Antes.", palavras=(
+                PalavraDeTranscricao("Antes.", 3.4, 4.0),
+            )),
+            SegmentoDeTranscricao(10.4, 13.5, "Trazer uma seguran", palavras=(
+                PalavraDeTranscricao("Trazer", 10.4, 10.9),
+                PalavraDeTranscricao("seguran", 13.0, 13.5),
+            )),
+            SegmentoDeTranscricao(20.0, 21.0, "Depois.", palavras=(
+                PalavraDeTranscricao("Depois.", 20.0, 21.0),
+            )),
+        )
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 10.1, 13.8, "gancho"),
+        ))
+
+        problemas = self.validador.validar(plano, falas)
+
+        self.assertIn("gancho_termina_no_meio_da_frase", {problema.codigo for problema in problemas})
+
 
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_verificador_da_aplicacao.py

@@ -0,0 +1,72 @@
+"""Testes da leitura estrutural depois da aplicação do plano."""
+
+import unittest
+
+from engine.dominio import Clipe, Faixa, IntervaloDeTempo, Timeline
+from engine.editor.modelos import AcaoDeEdicao, PlanoDeEdicao, TipoDeAcao
+from engine.editor.verificador_da_aplicacao import VerificadorDaAplicacao
+
+
+class TesteVerificadorDaAplicacao(unittest.TestCase):
+    """Garante que sobras e lacunas na timeline sejam detectadas."""
+
+    def _timeline(self, fim_do_ultimo_clipe: float) -> Timeline:
+        """Monta uma timeline simples com vídeo e áudio vinculados por intervalo."""
+        faixas = []
+        for tipo in ("video", "audio"):
+            faixas.append(Faixa(
+                f"{tipo}_0", tipo, tipo, 0, [Clipe(
+                    f"clipe_{tipo}", "fonte.mp4",
+                    IntervaloDeTempo(0.0, fim_do_ultimo_clipe),
+                    IntervaloDeTempo(0.0, fim_do_ultimo_clipe),
+                )]
+            ))
+        return Timeline("sequencia", "Sequência", 100.0, faixas=faixas)
+
+    def test_aprova_cobertura_exata_depois_do_corte(self):
+        """Aprova quando os dois tipos de faixa preservam exatamente o esperado."""
+        antes = self._timeline(100.0)
+        depois = Timeline("sequencia", "Sequência", 90.0, faixas=[
+            Faixa("video_0", "video", "video", 0, [
+                Clipe("v1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("v2", "fonte.mp4", IntervaloDeTempo(10, 90), IntervaloDeTempo(20, 100)),
+            ]),
+            Faixa("audio_0", "audio", "audio", 0, [
+                Clipe("a1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("a2", "fonte.mp4", IntervaloDeTempo(10, 90), IntervaloDeTempo(20, 100)),
+            ]),
+        ])
+        plano = PlanoDeEdicao("fonte.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 10, 20, "remover trecho"),
+        ))
+
+        resultado = VerificadorDaAplicacao().verificar(antes, depois, plano)
+
+        self.assertTrue(resultado.aprovada)
+        self.assertTrue(resultado.avisos)
+
+    def test_reprova_quando_sobra_um_trecho_na_timeline(self):
+        """Reprova quando o Premiere deixa uma sobra além do plano."""
+        antes = self._timeline(100.0)
+        depois = Timeline("sequencia", "Sequência", 91.0, faixas=[
+            Faixa("video_0", "video", "video", 0, [
+                Clipe("v1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("v2", "fonte.mp4", IntervaloDeTempo(10, 91), IntervaloDeTempo(20, 101)),
+            ]),
+            Faixa("audio_0", "audio", "audio", 0, [
+                Clipe("a1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("a2", "fonte.mp4", IntervaloDeTempo(10, 91), IntervaloDeTempo(20, 101)),
+            ]),
+        ])
+        plano = PlanoDeEdicao("fonte.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 10, 20, "remover trecho"),
+        ))
+
+        resultado = VerificadorDaAplicacao().verificar(antes, depois, plano)
+
+        self.assertFalse(resultado.aprovada)
+        self.assertIn("esperado", resultado.mensagem)
+
+
+if __name__ == "__main__":
+    unittest.main()