@andespindola/crow-skills 0.24.0 → 0.25.0

package/skills/crow-media/references/producao.md

@@ -0,0 +1,63 @@
+# Produção de mídia: fonte preservada, operação medida, arquivo final conferido
+
+Leia antes de transformar um arquivo que você não gerou e antes de afirmar que um render ficou pronto. As armadilhas aqui custam qualidade que não volta.
+
+## A fonte é irrecuperável; trate-a como tal
+
+- **Nunca escreva sobre a fonte.** Saída em arquivo novo, fonte intocada, inclusive em "ajuste rápido". Pipeline que sobrescreve perde o único original que existia.
+- **Meça antes de especificar.** Duração, resolução, SAR/DAR, fps e modo (constante ou variável), codec e perfil, profundidade de bits, espaço de cor, canais e taxa de amostragem do áudio, loudness. Especificação escrita sem medir a fonte produz destino que a fonte não alcança.
+- **Cada recodificação perde.** Toda geração em codec com perda degrada, e a perda acumula: cortar, depois recortar, depois concatenar em três passos recodificando dá três gerações. Decida o caminho inteiro antes e recodifique uma vez, no fim.
+- **Operação que não muda pixel nem amostra não recodifica.** Corte, concatenação e troca de container copiam o stream. Recodifique só quando a operação exige: mudar resolução, aspecto, fps, codec, ou aplicar efeito.
+- **Upscale não cria informação.** Ampliar e depois entregar como se fosse captura nativa é alegação falsa sobre o arquivo. Declare o que foi ampliado e a partir de quê.
+
+## Armadilhas da operação sem recodificação
+
+- **Corte com cópia de stream só acerta em keyframe.** O ponto de entrada vai para o keyframe anterior, então o corte pedido e o corte obtido divergem — às vezes por segundos. Se o ponto exato importa, recodifique o trecho; se não importa, cole o ponto obtido no relato em vez de repetir o pedido.
+- **Concatenação com cópia exige parâmetros idênticos.** Mesmo codec, perfil, resolução, fps, e mesmo layout de áudio. Fontes diferentes concatenadas assim produzem arquivo que abre e falha no meio, ou que dessincroniza. Normalize antes, ou recodifique na junção.
+- **Container esconde o problema.** Arquivo que o player local abre pode falhar no destino: perfil de codec não suportado, fps variável, áudio em canal inesperado. Teste no destino real, não só no player do sistema.
+- **Corte não destrutivo quando existir.** Em composição, página ou timeline, recortar por janela de reprodução ou máscara no render mantém a fonte inteira e reversível. Produzir arquivo físico só quando a entrega é o arquivo.
+
+## Áudio
+
+- **Ordem da cadeia importa.** Subtraia antes de somar: filtro corretivo primeiro, nível depois, relação entre faixas depois, caráter e teto no fim. Compressor antes de um corte de graves passa o tempo perseguindo ruído de fundo.
+- **Não se diagnostica o espectro absoluto de uma voz desconhecida.** Fundamental, formante e queda natural no fim da frase variam mais entre duas pessoas do que a maioria dos defeitos. Compare sempre dentro do próprio arquivo: contra o original limpo, se existir, ou contra as pausas — o que se ouve numa pausa é aditivo, e o espectro da pausa é o canal, não a voz. Comparar com média publicada ou com voz sintetizada de controle produz diagnóstico errado. Sem original e sem silêncio utilizável, um defeito tonal estático é indeterminado: diga isso e ofereça as leituras compatíveis, em vez de escolher uma e construir uma cadeia sobre ela.
+- **Música sob voz não se resolve baixando a música.** Abaixar a cama inteira funciona e custa toda a presença dela durante a locução. Ceda à voz as faixas de frequência que ela ocupa e devolva o resto, e faça a cessão seguir o envelope da fala, não uma profundidade fixa — profundidade fixa afina a música também nas pausas.
+- **O processamento vai na faixa que cede, apontando para a que manda.** Faixa processada contra si mesma é defeito, não escolha sutil. Quando há várias falas, aponte para o grupo delas, não para cada clipe: lista de clipes precisa estar exaustivamente certa e envelhece na próxima edição.
+- **Efeito com cauda alonga a faixa.** Reverb e delay fazem o resultado terminar depois da duração nominal. Isso é esperado; reserve a cauda na mixagem em vez de cortá-la.
+- **Mixagem se confere ouvindo o render, não lendo o grafo.** E o que não dá para conferir entra como não verificado.
+
+## Imagem, cor e tratamento
+
+- **Correção se mede e se propõe, não se aplica em silêncio.** Medir exposição, balanço e contraste é evidência; aplicá-los por padrão não é. Uma "correção" que puxa a cena para cinza neutro destrói pôr do sol, neon e qualquer intenção cromática. Mostre a medida e a proposta, com antes e depois, e deixe a decisão com o dono.
+- **Não suba o nível de representação sem necessidade.** Ajuste paramétrico reversível resolve exposição, sombras, contraste e temperatura. Congelar isso numa tabela de cor ou num bitmap achatado é irreversível e some com o parâmetro; use a forma pesada só quando o pedido a exige ou quando o dono forneceu o arquivo.
+- **Transparência e espaço de cor sobrevivem à conversão ou não.** Confira canal alfa, perfil de cor e matiz depois de cada conversão de formato; alfa perdido só aparece sobre fundo diferente do que você testou.
+- **Formato e tamanho casam com o destino.** Entregar no dobro da dimensão de exibição desperdiça, e abaixo dela borra. Nome de arquivo descreve o conteúdo.
+- **Máscara geométrica não substitui recorte real.** Círculo, polígono ou gradiente aproximando a silhueta de um objeto fotográfico lê pior que não recortar.
+
+## Vídeo composto
+
+Uma fonte de verdade para roteiro e storyboard, e tokens para o visual. Não deixe vários especialistas reinventarem a narrativa: quem produz a cena lê o roteiro aprovado, não o reescreve.
+
+Antes de concluir, inspecione: duração por faixa e total, sincronismo de áudio e imagem no começo e no fim, fps e codec do arquivo entregue, loudness, frames pretos ou congelados no corte, legibilidade do texto na menor tela do destino, legenda sincronizada quando houver fala, e área segura. Frame preto no fim e dessincronismo progressivo são os dois defeitos que passam em inspeção por amostragem.
+
+## Mídia longa e saída truncada
+
+Transcrição, análise e descrição de arquivo longo batem em limite de saída da ferramenta e voltam cortadas sem erro. Segmente a entrada, processe por partes com sobreposição nas bordas, remonte e confira que a última fala do arquivo está no resultado. Entregar transcrição truncada como completa é afirmação falsa sobre o arquivo, e é silenciosa.
+
+Arquivo grande se processa por streaming, não carregado inteiro em memória. Pré-dimensione quando a ferramenta tem limite de tamanho, e diga que a entrada foi reduzida.
+
+## Diagrama e artefato revisável
+
+Quando o artefato precisa ser revisado, versionado e corrigido, a fonte em texto (Mermaid, DOT, PlantUML, SVG escrito) vale mais que o bitmap: ela entra em diff e a correção é cirúrgica. Renderize para imagem ou PDF quando o pedido é o arquivo, ou quando o destino não lê a fonte. Entregue a fonte junto do render e diga as suposições que você fez sobre entidades, relações e ordem.
+
+## Proveniência e direitos
+
+- **Cada asset de terceiro registra origem, licença, compatibilidade com o uso e o texto de atribuição exigido.** Imagem encontrada numa busca, pin, feed ou banco de referências não é asset autorizado: ela pode servir como referência de direção e não entra no entregável.
+- **Asset derivado aponta para a fonte.** Recorte, upscale, grade e conversão registram de qual arquivo saíram e com qual comando; sem isso ninguém reproduz nem reverte.
+- **Voz, rosto e identidade de pessoa real exigem consentimento explícito e registrado**, por uso e por peça.
+- **Fonte tipográfica tem licença própria.** Índice de fontes e nome de família não autorizam embutir o arquivo.
+- **Não exija fornecedor.** Escolha entre as ferramentas presentes. Quando o pedido só é alcançável com serviço externo, credencial ou instalação nova, diga o que falta, entregue o artefato possível e pare — não instale, não atualize pacote, não use credencial de outro contexto e não envie conteúdo sensível para um serviço só para completar o preflight.
+
+## Entrega
+
+O relato nomeia cada arquivo final por caminho completo e aberto a partir da raiz do projeto, mais os companheiros (transcrição, manifest, miniatura, derivado otimizado). Nome de arquivo solto não é entrega. Diga o comando que mediu o resultado e o que ele mostrou; "renderizou" sem medida não é evidência, e render que não terminou não se relata como concluído.

package/skills/crow-native-mobile/SKILL.md

@@ -19,7 +19,7 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 2. Implemente o fluxo e estados com trabalho pesado fora da thread de UI e cancelamento/teardown corretos. Não suponha que background execute indefinidamente. Arquivos e trabalhos têm nome único, limpeza e falha com retry limitado.
 3. Trate permissões como escolha do usuário: solicite no momento pertinente ao recurso, respeite negativa e indique retomada explícita; não abra prompts em loop. Isole a decisão de permissão em lógica testável sem dispositivo, cobrindo concedida, negada, negada de vez e revogada depois de concedida.
 4. Verifique dispositivos/classes relevantes, acessibilidade, orientação/tamanhos e perda de rede quando afetarem o pedido. Teste API e persistência como contratos distintos. Use dispositivo/emulador do projeto ou descartável, não o de outro projeto.
-5. Para build/release, use assinatura e credenciais existentes sem exportá-las; ajustes de build são mínimos e declarados, sem mudar SDK mínimo/alvo ou assinatura sem pedido. Para performance, encaminhe medição à disciplina de validade.
+5. Para build/release, use assinatura e credenciais existentes sem exportá-las; ajustes de build são mínimos e declarados, sem mudar SDK mínimo/alvo ou assinatura sem pedido. Compilar não prova assinatura: um build que compila ainda falha em assinatura, provisioning e entitlements (no iOS, Archive é sinal distinto de Build, e é ele que libera TestFlight e loja). Para release, confirme o artefato assinado no canal real de distribuição, não só a compilação local ou de CI. Para performance, encaminhe medição à disciplina de validade.
 
 Recursos da máquina: um emulador ou simulador por vez, reutilizando o já aberto do projeto; builds Gradle/Xcode com workers reduzidos (`--max-workers`, `-jobs`; por padrão usam todas as CPUs) pelo `maxWorkersPerJob` de `crow-skills resources --json` quando existir. Sob pressão `critical`, não inicie emulador nem build. Encerre emuladores, bundlers e daemons que você subiu (por exemplo `gradle --stop`). Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
 

package/skills/crow-observe/SKILL.md

@@ -16,10 +16,14 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 ## Trabalho
 
 1. Defina qual pergunta o sinal deve responder e quem age. Reutilize o provedor existente antes de adicionar SDK ou coletor.
-2. Associe ambiente/release e correlação mínima: propague o ID recebido (ex.: `traceparent` W3C), saneando em vez de descartar. Redija segredos e minimize dados pessoais, preservando IDs operacionais não pessoais. Controle cardinalidade, volume e retenção.
-3. Instrumentar não muda contrato HTTP, validação de entrada nem nomes de alerta/métrica existentes; se for preciso, deixe como proposta (mudança de contrato), salvo pedido explícito. Escolha sinais ligados à experiência: falhas de jornada, latência/filas, saturação e dependências. Diferencie alerta acionável de dashboard informativo.
-4. Verifique captura e roteamento com evento seguro e esperado. Não dispare incidente real nem use dados pessoais para testar.
-5. Entregue alerta/runbook com limiar, responsável, diagnóstico inicial e rollback. Ajuste ruído a partir de evidência observada.
+2. Associe ambiente/release e correlação mínima: propague o ID recebido (ex.: `traceparent` W3C), saneando em vez de descartar. Redija segredos e minimize dados pessoais, preservando IDs operacionais não pessoais. Controle cardinalidade, volume e retenção. Quando o mesmo sinal sai por mais de um destino (span, log, bucket, armazém de dados), a redação vale por destino: desligar conteúdo no trace não desliga o que já é exportado por outro caminho, e cada destino precisa da própria prova. Separe o destino por ambiente: evento de desenvolvimento ou homologação no projeto de produção gasta cota e aciona plantão por engano. Se a leitura do sinal depende de artefato de build (source map, símbolos), publicá-lo faz parte do release ou a pilha chega ilegível.
+3. Instrumentar não muda contrato HTTP, validação de entrada nem nomes de alerta/métrica existentes; se for preciso, deixe como proposta (mudança de contrato), salvo pedido explícito. Escolha sinais ligados à experiência: falhas de jornada, latência/filas, saturação e dependências. Cubra também o caminho de erro não tratado: exceção sem captura, rejeição assíncrona, falha na fronteira do componente de interface e requisição que volta com erro. Código que engole o erro antes do coletor faz o sistema parecer saudável; trate isso como defeito do sinal, com arquivo:linha. Diferencie alerta acionável de dashboard informativo.
+4. Verifique captura e roteamento com evento seguro e esperado. Não dispare incidente real nem use dados pessoais para testar. Ausência de evento não é ausência de falha: coletor que não subiu, identidade sem permissão de escrita no destino, amostragem agressiva ou filtro amplo produzem painel vazio. Prove o caminho ponta a ponta até o destino final e confirme release, ambiente e campos esperados no evento que chegou; sem isso, o sinal é não verificado. Instrumentação nova não pode substituir nem silenciar a existente: depois de instalar, confira que os sinais anteriores continuam chegando.
+5. Entregue alerta/runbook com limiar, responsável, diagnóstico inicial e rollback. Todo alerta nasce ligado a um runbook e a um sinal de usuário; alerta sem ação definida sai, em vez de ser silenciado aos poucos até ninguém olhar. O limiar vem do comportamento medido do serviço e é datado, não de número de catálogo. Agrupe eventos repetidos do mesmo incidente, e trate reabertura de problema já corrigido como alerta próprio. Ajuste ruído a partir de evidência observada.
+
+## Detalhes condicionais
+
+- Leia [cardinalidade.md](references/cardinalidade.md) ao criar ou alterar métrica, rótulo ou campo indexado.
 
 ## Saída e aceite
 

package/skills/crow-observe/references/cardinalidade.md

@@ -0,0 +1,11 @@
+# cardinalidade
+
+Leia ao criar ou alterar métrica, rótulo ou campo indexado.
+
+Cada combinação distinta de valores de rótulo é uma série temporal própria. Rótulo que carrega identificador de usuário, de requisição, de sessão, de pedido, URL crua com parâmetro, mensagem de erro ou endereço de origem multiplica as séries pelo tamanho do tráfego: o custo de ingestão e retenção cresce junto e o backend de métricas cai antes de o painel ficar pronto. A falha aparece como ingestão rejeitada, consulta que expira ou fatura fora de proporção, nunca como erro no código que instrumentou.
+
+Antes de instrumentar, escreva o conjunto de valores possíveis de cada rótulo e confirme que ele é fechado e pequeno: ambiente, release, região, serviço, rota normalizada (o padrão da rota, não o caminho com o id dentro), código de status, resultado. Dado de variação alta pertence a log estruturado ou a atributo de trace, onde a busca é por evento e não por série, e o identificador que liga os dois é o de correlação.
+
+Conteúdo de payload no sinal — corpo de requisição, prompt, resposta, documento — multiplica custo e risco ao mesmo tempo: capture amostra com taxa declarada, redija antes de sair do processo e informe a retenção. Amostragem é parte do contrato do sinal: diga a taxa na saída, porque ela muda o que o alerta consegue detectar.
+
+Ao reduzir cardinalidade de uma métrica existente, o histórico não se converte: a série antiga morre e a nova começa vazia. Isso quebra alerta e painel que dependiam dela. Declare a mudança, o período sem comparação possível e quem precisa saber, em vez de trocar o rótulo em silêncio.

package/skills/crow-performance/SKILL.md

@@ -15,12 +15,12 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 
 ## Trabalho
 
-1. Diferencie avaliar evidência, medir e otimizar. Avaliação não autoriza medir/alterar/reverter; use só os dados disponíveis e proponha o experimento que falta. Nos modos executáveis autorizados, fixe workload, cache/warmup, concorrência e instrumento e estime o ruído no sistema inalterado.
-2. Use profiler/trace/plano para localizar custo; isso não mede por si o ganho de uma correção. Web: rede/render/bundle; serviço: filas/spans/carga; Postgres: plano/locks/pool; nativo: threads/alocações/lifecycle. Escolha só o ramo pertinente.
-3. Faça a menor alteração testável. Confirme que o mecanismo proposto realmente entrou em efeito.
+1. Diferencie avaliar evidência, medir e otimizar. Avaliação não autoriza medir/alterar/reverter; use só os dados disponíveis e proponha o experimento que falta. Nos modos executáveis autorizados, fixe workload, cache/warmup, concorrência e instrumento e estime o ruído no sistema inalterado. Ruído maior que o efeito esperado é bloqueador de medição: estabilize o ambiente ou declare a mudança não mensurável com este instrumento, antes de alterar qualquer coisa.
+2. Use profiler/trace/plano para localizar custo; isso não mede por si o ganho de uma correção. Antes de escolher o alvo, atribua o tempo por estágio (origem, rede, cache, parse/execução, render; ou aplicação, fila, dependência) e confirme que o custo apontado está no caminho que o usuário espera: topo de perfil fora da jornada é otimização sem efeito percebido. Agregue por código próprio, não por folha de framework, que mostra onde o tempo é gasto e não onde é causado. Número agregado de processo ou requisição inteira serve de sanidade, não de prova. Web: rede/render/bundle; serviço: filas/spans/carga; Postgres: plano/locks/pool; nativo: threads/alocações/lifecycle. Escolha só o ramo pertinente.
+3. Faça a menor alteração testável. Confirme que o mecanismo proposto realmente entrou em efeito. Otimização que adia ou move custo (carga sob demanda, cache, fila, trabalho em segundo plano) não o elimina: meça também o momento em que ele reaparece e o caminho que passou a pagá-lo, não só a condição inicial.
 4. Compare condições alternadas A/B/A/B quando viável; se o baseline deriva, estabilize ou declare o resultado inconclusivo. Latência pede percentis e n, não só média.
-5. Apresente dispersão, custo e possíveis regressões de cauda. Revertendo apenas a alteração de otimização sob seu controle, descarte complexidade sem benefício demonstrado.
-6. Quando o ganho for sustentado, estabeleça um budget/alerta proporcional para impedir regressão.
+5. Apresente dispersão, custo e possíveis regressões de cauda. Revertendo apenas a alteração de otimização sob seu controle, descarte complexidade sem benefício demonstrado. Resultado negativo é resultado: registre na saída a medida que não sustentou o ganho, junto com a reversão, para a próxima tentativa não repetir o caminho.
+6. Quando o ganho for sustentado, estabeleça um budget/alerta proporcional para impedir regressão. O limiar vem da medida que você fez neste alvo, com a condição em que vale (dispositivo, rede, dataset, concorrência); número de catálogo sem essa condição não é budget.
 
 Recursos da máquina: medição pede máquina estável. Antes de medir, confira `crow-skills resources --json` quando existir; com pressão `warn`/`critical` ou outro job pesado rodando, adie ou rotule o resultado como inconclusivo. Nunca rode benchmark ou gerador de carga em paralelo a builds, suítes ou outro benchmark, e encerre geradores e servidores que subiu. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
 

package/skills/crow-performance/references/measurement.md

@@ -1,3 +1,9 @@
 # measurement
 
 Use ao desenhar o experimento. Baseline repetido (comece com pelo menos cinco execuções), carga fixa e warmup separado. Cinco execuções são um início para investigar ruído, não suficiência estatística nem amostra adequada automaticamente a p95/p99. Relate min/mediana/max para recursos e percentis pertinentes com n para latência; informe quando a amostra não sustenta caudas. Para Core Web Vitals de campo, use p75 e distinga campo de laboratório. Controle cache, CPU/rede, temperatura e concorrência. Serviços: gerador que espera cada resposta pode esconder filas (coordinated omission). Na web, não conclua com uma única nota Lighthouse. A₂ longe de A₁ invalida a comparação B. Quando o ambiente não permite controle, rotule a medida como indicativa.
+
+Case o instrumento com a pergunta: perfil amostrado, flame graph ou trace distribuído respondem onde está o custo; A/B em workload fixo responde se a mudança ajudou; perfil por thread ou por span responde qual estágio; profiler de alocação e snapshot de heap respondem se o gargalo é memória e não CPU. Trocar um pelo outro é a origem mais comum do ganho que não se sustenta.
+
+Em serviço, o nível de carga faz parte da medida: latência a dez requisições por segundo não diz nada sobre duzentas. Declare a concorrência e meça a curva de latência contra vazão, não um ponto. Separe tempo de servidor de tempo de fila: serviço rápido com requisição esperando para ser aceita continua lento para quem chama. Descarte a janela de warmup explicitamente, em vez de diluí-la na média.
+
+Na web, cache frio e cache quente são cenários distintos: relate qual dos dois você mediu e não compare um com o outro. Throttling de CPU e rede tem de ser idêntico entre as execuções, senão você comparou duas máquinas. Nota de ferramenta de laboratório varia muito entre execuções: use a mediana de várias e trate campo (p75 de sessões reais) como o alvo, laboratório como a verificação.

package/skills/crow-platform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crow-platform
-description: "Coordene uma plataforma ou iniciativa que atravessa produto, design, engenharia e operação. Não use para um bug ou ajuste isolado."
+description: "Coordene uma plataforma ou iniciativa que atravessa produto, design, engenharia e operação, mapeando as etapas que faltam e o contrato entre elas. Não use para um bug ou ajuste isolado; a coordenação da execução e a delegação são de crow-behaviour."
 ---
 
 # Entrega de plataforma
@@ -16,9 +16,9 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 ## Trabalho
 
 1. Identifique a menor entrega completa e o estado atual: problema aberto, especificação, implementação ou operação. Reutilize decisões válidas; não reinicie fases concluídas.
-2. Liste somente as etapas que faltam, cada uma com id, responsável lógico, entrada, saída, condição de passagem e evidência esperada. Escolha especialistas por intenção, stack e risco, não por palavras isoladas.
+2. Liste somente as etapas que faltam, cada uma com id, responsável lógico, entrada, saída, condição de passagem e evidência esperada. Escolha especialistas por intenção, stack e risco, não por palavras isoladas. Cada etapa nomeia o efeito que ela deve produzir na jornada e como esse efeito será observado depois de entregue; etapa sem efeito observável é candidata a corte, não a execução. Marque o grau de compromisso: etapa cujo escopo ainda depende de decisão ou descoberta pendente entra como não comprometida, com a decisão que a destrava, para o mapa não ser lido como promessa de data. Trabalho habilitador — migração, deprecação, dívida que a fatia exige — é etapa do mapa com dono e evidência, não pressuposto implícito.
 3. Defina um contrato comum entre UI, API e dados antes de separar implementação: operações, códigos de erro e convenções como fuso e unidades. Planeje homologação e recuperação com o desenho, não só depois de terminar o código.
-4. Entregue por fatias verticais: uma jornada atravessa interface, regra, persistência e teste. Paralelize apenas trabalho independente com ownership de arquivos definido.
+4. Entregue por fatias verticais: uma jornada atravessa interface, regra, persistência e teste. O corte está certo quando a fatia é entregável e verificável sozinha: se ela só produz efeito junto com outra, o corte foi por camada disfarçado de fatia e precisa ser refeito. Dependência externa — outro time, fornecedor, API de terceiro, aprovação — vira fronteira de corte, e a fatia que depende dela declara o que avança enquanto ela não chega. Paralelize apenas trabalho independente com ownership de arquivos definido.
 5. Consuma evidências dos especialistas. Reabra uma decisão somente quando a evidência ou o pedido mudar; registre quem decidiu e o impacto nas etapas consumidoras. Contradição entre requisitos aprovados bloqueia as etapas afetadas até o dono decidir; o orquestrador não a resolve.
 
 ## Saída e aceite
@@ -30,7 +30,7 @@ Entregue **delivery-map** na resposta final ou em arquivo do projeto cujo caminh
 
 ## Limites e composição
 
-Não implementa todos os domínios nem impõe stack, cloud, agentes paralelos ou uma cadeia fixa de skills.
+Não implementa todos os domínios nem impõe stack, cloud, agentes paralelos ou uma cadeia fixa de skills. Este mapa é de entrega, não de execução: decompor para executores, delegar, verificar de forma adversária e registrar passos ficam com `crow-behaviour`, e o mapa não duplica esse ciclo nem estima prazo como se fosse evidência.
 
 Altere só o que o pedido e o achado exigem: sem reestilizar, reescrever em outra linguagem, adicionar dependências ou editar docs fora do alvo; documento de outro dono (runbook, política, RACI, decisão registrada) recebe proposta, não edição, salvo pedido explícito; liste e justifique qualquer extra; mudança de contrato (API, schema, formato) e validação mais estrita, que passa a rejeitar o que antes era aceito, ficam como proposta, não implementação, salvo pedido explícito; pedir a correção de um defeito autoriza rejeitar a entrada que o causa, não mais que isso. Não crie branch, commit ou push sem pedido ou política declarada do dono. Use só ferramentas já presentes; não baixe binários nem acesse rede além do alvo autorizado no pedido, prefira contexto isolado ao navegador ou desktop pessoal do usuário e, se faltar ferramenta, declare como não validado. Controles corretos que você verificou, credenciais visivelmente fictícias (fixtures, exemplos) e falsos positivos não são defeito: liste cada um nos descartados, com motivo. Subagentes delegados carregam esta skill; revisores não editam arquivos nem commitam no projeto (exercer a hipótese contra o alvo autorizado não é escrita).
 

package/skills/crow-postgres/SKILL.md

@@ -21,6 +21,9 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 4. Planeje migration compatível com leitores/escritores antigos durante rollout. Faça backfill/índice online só quando suportados e necessários; explicite locks, tempo e recuperação.
 5. Teste constraints, concorrência e negações entre papéis/tenants. Confira restauração e caminho de reversão seguro antes de operações irreversíveis.
 
+- Leia [migracao-online.md](references/migracao-online.md) ao mexer em tabela com tráfego: lock forte que trava escrita, índice concorrente, constraint em dois tempos (`NOT VALID` depois `VALIDATE`), expand-contract para mudança incompatível, backfill em lotes, reversão e coordenação de fila.
+- RLS, constraints e roles no banco complementam, não substituem, a autorização da aplicação; a decisão de ator × recurso × ação no servidor é de `crow-backend`.
+
 ## Saída e aceite
 
 Entregue **db-change** na resposta final ou em arquivo do projeto cujo caminho você informa (memória ou ledger externo não contam), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.

package/skills/crow-postgres/references/migracao-online.md

@@ -0,0 +1,17 @@
+# migração sem janela de inconsistência
+
+Leia ao planejar qualquer migration numa tabela com tráfego. O erro clássico é a migration que trava escrita porque pega lock forte numa tabela grande; os passos abaixo evitam isso e mantêm leitores e escritores antigos funcionando durante o rollout.
+
+Pegue `lock_timeout` baixo em toda migration. Sem ele, um `ALTER TABLE` que precisa de `AccessExclusiveLock` entra na fila atrás do tráfego e, enquanto espera, bloqueia toda query nova que chega depois dele — a tabela congela mesmo antes de o comando rodar. Com `lock_timeout`, a migration falha rápido e você reagenda em vez de derrubar o serviço.
+
+Crie índice sem travar a tabela com `CREATE INDEX CONCURRENTLY`. Ele não pega lock de escrita, mas não roda dentro de transação e, se falhar no meio, deixa um índice inválido para trás: detecte o inválido, derrube-o e refaça. Para reconstruir, `REINDEX CONCURRENTLY`.
+
+Adicione constraint em dois tempos. `ADD CONSTRAINT ... NOT VALID` registra a regra pegando lock só por um instante e já passa a valer para linhas novas; `VALIDATE CONSTRAINT` num comando separado varre as linhas antigas sem bloquear escrita. Vale para `CHECK` e para chave estrangeira. Uma constraint adicionada já validada varre a tabela inteira sob lock forte — é exatamente o que evitar.
+
+Para mudança incompatível (renomear coluna, trocar tipo, estreitar formato), use expand-contract. Adicione o campo novo ao lado do antigo, preencha, faça o código escrever nos dois durante a transição, mova os leitores e só então, numa migration posterior e com autorização própria, remova o antigo. Nunca renomeie ou troque o tipo no lugar enquanto o código em produção ainda lê o nome ou o formato antigo.
+
+Faça backfill em lotes delimitados, cada lote na própria transação curta, com pausa entre eles. Um único `UPDATE` na tabela toda segura lock e gera bloat; o laço em lotes mantém a escrita de produção fluindo. `NOT NULL` numa coluna grande já existente precisa de validação: preencha primeiro, depois imponha, ou use um `CHECK ... NOT VALID` validado à parte.
+
+Toda migration tem caminho de volta explícito, ou é marcada irreversível e autorizada à parte. Confira restauração e reversão antes de qualquer passo destrutivo; teste no ambiente de teste, não em produção.
+
+Em fila de trabalho e coordenação, prefira `FOR UPDATE SKIP LOCKED` para workers pegarem linhas diferentes sem esperar uns aos outros, e advisory lock (`pg_advisory_xact_lock`) para exclusão em nível de aplicação sem criar linha-dummy para travar. Quando duas transações tocam as mesmas linhas, adquira os locks na mesma ordem em todas elas para não gerar deadlock.

package/skills/crow-product-leadership/SKILL.md

@@ -16,10 +16,11 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 ## Trabalho
 
 1. Separe problema de decisão, coordenação e desenvolvimento individual. Use fatos atribuíveis, sem diagnosticar personalidade ou inventar desempenho. Confronte alegações de alinhamento ("já falei com todos") com os registros; divergência é achado.
-2. Mapeie quem decide, quem contribui e quem precisa de contexto. Explicite trade-offs, dependências e desacordos sem escolher pela última mensagem. Diante de restrição de outro dono (freeze, orçamento, política), não a remova nem a ignore: dê pelo menos duas opções com custo e risco e diga quem decide.
+2. Mapeie quem decide, quem contribui, quem aprova ou veta, quem precisa de contexto e quem sofre a consequência sem poder mudá-la. Explicite trade-offs, dependências e desacordos sem escolher pela última mensagem. Diante de restrição de outro dono (freeze, orçamento, política), não a remova nem a ignore: dê pelo menos duas opções com custo e risco e diga quem decide.
 3. Produza o menor artefato útil: decisão, plano de conversa, responsabilidades ou experimento de melhoria (hipótese, métrica, prazo e critério de parada). Reutilize contexto dado, sem workshop obrigatório.
-4. Defina ação, responsável, resultado observável e data/checkpoint se pertinentes. Para feedback de carreira, distinga auto-relato de habilidade demonstrada.
-5. Deixe comunicações externas e mudanças organizacionais como ações pendentes para o dono decidir, separadas do aconselhamento; não as envie.
+4. Defina ação, responsável, resultado observável e data/checkpoint se pertinentes. Registre a decisão com dono, data e o que foi descartado, e mantenha o desacordo no registro com o nome de quem discorda. Para feedback de carreira, distinga auto-relato de habilidade demonstrada.
+5. Leia [decisão e pessoas](references/decisao-e-pessoas.md) ao montar o mapa, ao escrever o registro ou ao tratar desempenho: papel não é pessoa, representante conveniente não é representante validado, prepare o que o outro lado precisa e não só o seu pedido, consenso escrito onde houve divergência é registro falso, e a skill não emite veredito de prontidão sobre ninguém.
+6. Deixe comunicações externas e mudanças organizacionais como ações pendentes para o dono decidir, separadas do aconselhamento; não as envie.
 
 ## Saída e aceite
 

package/skills/crow-product-leadership/references/decisao-e-pessoas.md

@@ -0,0 +1,35 @@
+# decisão e pessoas
+
+Leia ao mapear quem participa de uma decisão, ao registrá-la e ao tratar desenvolvimento individual. A skill organiza decisão e conversa; ela não exerce autoridade sobre ninguém, e o registro é o que impede que a análise vire veredito.
+
+## Quem participa, em cinco papéis diferentes
+
+Decidir, contribuir e receber contexto não cobrem o mapa. Separe também quem aprova ou veta — segurança, jurídico, compliance, finanças, dono de uma plataforma vizinha — porque aprovador ausente do mapa não desaparece: ele reaparece como bloqueio tarde, quando o custo de voltar é maior. E separe quem sofre a consequência sem ter poder de mudar a decisão: quem opera o fluxo todo dia, quem perde o caminho antigo, quem fica fora do novo requisito. Esse grupo precisa ser ouvido por desenho; porta aberta só atende quem já sabia que tinha vez.
+
+Papel não é pessoa. "Engenharia" não aprova nada; quem aprova é quem tem a decisão sobre capacidade ou sobre o sistema. Nomeie a pessoa ou o cargo com a autoridade real, porque é com ela que a conversa precisa acontecer.
+
+Quando alguém fala por um grupo, verifique se representa o grupo ou apenas se tornou acessível. Representante conveniente devolve a visão dele; representante validado confirmou com quem representa. Diga qual dos dois você tem.
+
+Considere o efeito de segunda ordem: a decisão muda o trabalho de um time, isso muda a experiência de quem depende dele, e aí muda o número que a liderança olha. A cadeia revela participante que o mapa de um nível não mostra.
+
+## Preparar a conversa pelos dois lados
+
+Plano que só organiza o que você quer dizer trata a outra pessoa como plateia. Antes da conversa, separe o que você precisa dela — decisão, aprovação, informação, capacidade, apenas ciência — do que ela provavelmente precisa de você: previsibilidade, influência sobre o desenho, crédito pela contribuição, garantia sobre risco que ela terá de defender. Onde as duas listas se encontram existe caminho de acordo; onde divergem existe negociação a preparar, e dizer isso é mais útil que uma mensagem bem escrita no tom errado.
+
+O esforço é proporcional ao que está em jogo: relação crítica e grupo sem voz recebem plano próprio, o resto recebe a informação. E plano não é permanente — quem estava alinhado muda de posição depois de um trimestre ruim; revise depois de cada marco em vez de tratar o mapa como estado fixo.
+
+## Registro da decisão
+
+A decisão registrada diz o que foi decidido, quem decidiu, em que data, o que foi considerado e descartado, e com qual motivo. Sem data não se sabe qual de dois registros em conflito vale. Sem o descartado, a alternativa volta na reunião seguinte como se fosse nova.
+
+Desacordo entra no registro com o nome de quem discorda e o motivo, ao lado da decisão, e continua lá depois dela. Escrever consenso onde houve divergência é registro falso: apaga a objeção que previa o risco e tira de quem decidiu a informação de que a decisão foi tomada contra uma leitura conhecida. Divergência preservada não é insubordinação registrada, é o custo da decisão visível.
+
+Restrição de outro dono — congelamento, orçamento, política, contrato — não é removida nem ignorada aqui: ela entra como restrição, com ao menos duas opções e o nome de quem pode alterá-la.
+
+## Pessoas
+
+Não emita veredito sobre uma pessoa. Pronto ou não pronto, promovível ou não, forte ou fraco são decisões de quem tem a autoridade e os dados de desempenho, não saída de uma análise de contexto. O que esta skill entrega é o comportamento específico, com o fato atribuível que o sustenta, a data e a fonte, e o que mudaria com qual apoio.
+
+Auto-relato é auto-relato; afirmação de terceiro sobre alguém é atribuída a quem disse, com a data; nenhum dos dois é habilidade demonstrada. Não diagnostique personalidade, motivação interna ou intenção a partir de comportamento observado, e não transforme uma inferência em fato ao repeti-la no artefato. Dado pessoal sensível não entra no registro.
+
+Comunicação externa e mudança organizacional ficam como ação pendente, separadas do aconselhamento, e não são enviadas por você.

package/skills/crow-qa/SKILL.md

@@ -18,7 +18,7 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 1. Defina se o pedido é planejar, escrever ou executar testes. Planejamento não autoriza execução/alteração. Com aceite contraditório, cubra só o que não depende do conflito. Associe requisitos à camada mais barata que observe o comportamento real: unidade, integração, API, contrato, jornada e visual.
 2. Use dependências reais de teste para integração e virtualize terceiros quando necessário. Não mocke a ligação que o teste diz verificar.
 3. Adicione cenários negativos e recuperação pertinentes. Consumer-driven contract testing faz sentido quando há consumidores/provedores independentes, não por ritual.
-4. Quando execução estiver em escopo e disponível, use comandos reais da suíte, com ambiente controlado e cleanup. Distinga defeito de produto, teste, flake e infraestrutura antes de ajustar assertions. Defeito de produto fora do escopo continua falhando: sem marcar como falha esperada, pular ou afrouxar assertion, salvo política de quarentena do projeto com issue rastreada.
+4. Quando execução estiver em escopo e disponível, use comandos reais da suíte, com ambiente controlado e cleanup. Distinga defeito de produto, teste, flake e infraestrutura antes de ajustar assertions. Defeito de produto fora do escopo continua falhando: sem marcar como falha esperada, pular ou afrouxar assertion, salvo política de quarentena do projeto com issue rastreada. Teste intermitente é defeito do teste até prova em contrário: investigue a causa (espera por tempo fixo em vez de condição, estado compartilhado entre testes, dependência de ordem, rede ou terceiro real) em vez de reexecutar até passar. Retry que esconde flake é dívida, não correção, e pode mascarar regressão real; se a política usa rerun, limite-o e registre a flake para conserto, nunca a conte como verde.
 5. Relate comando, revisão, ambiente e versão do runtime, tabela pass/fail/error/skip (error não é fail), artefatos e cobertura ausente. Preserve a política de dados e retenção visual do projeto.
 
 Recursos da máquina: rode primeiro os testes direcionados à mudança e a suíte completa só depois, uma vez; limite os workers que o runner já usa (`--maxWorkers`; `pytest -n` só com xdist já no projeto), sem paralelizar runner serial, ao `maxWorkersPerJob` de `crow-skills resources --json` quando existir. Sob pressão `critical`, não inicie suíte nova e relate o bloqueio. Encerre servidores, bancos e containers de teste que você subiu. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).

package/skills/crow-release/SKILL.md

@@ -16,14 +16,19 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 ## Trabalho
 
 1. Defina o modo pedido: preparar, avaliar ou executar. Nos dois primeiros, produza plano/evidência sem deploy; no último, identifique ambiente, fluxo Git/pipeline, artefato e identidade. Reutilize autorização específica existente; não amplie para outro ambiente. Autorização relatada por terceiro é relato, não aprovação.
-2. Confira os gates aplicáveis e resultados reais. Teste, SAST, dependências e budget são requisitos por risco, não comandos universais. Se um gate falha por causa trivial e reversível no escopo (como versão desalinhada), corrija e rode de novo.
-3. Planeje compatibilidade de migration/config/consumidores e ordenação do rollout. Para mudança destrutiva, nomeie os consumidores afetados e a ordem expand/contract, e valide backup e restauração antes do ponto irreversível.
-4. Somente no modo executar, com gates satisfeitos e ferramenta disponível, use o mecanismo existente, artefato identificado e credenciais externas ao código. Gate pendente bloqueia a promoção ao ambiente que ele protege, não a homologação autorizada: execute o que for seguro e reversível. No modo executar autorizado, commit, tag, push e acesso ao destino e ao pipeline fazem parte do pedido; correção de gate entra como commit próprio, citado na saída.
-5. Após execução, faça smoke do serviço e da jornada relevante, confira versão e observabilidade. Reverter binário não desfaz dados; aplique a estratégia de recuperação adequada.
-6. Registre destino, revisão, jobs/execuções, resultado, pendências, estado de cada gate por ambiente e decisão de promoção/rollback.
+2. Confira os gates aplicáveis e resultados reais. Teste, SAST, dependências e budget são requisitos por risco, não comandos universais. Se um gate falha por causa trivial e reversível no escopo (como versão desalinhada), corrija e rode de novo. Evidência de gate vale para a revisão em que foi colhida: se o alvo mudou depois, o gate volta a pendente em vez de ser reaproveitado. Antes dos gates, confira se o artefato é publicável no destino: ponto de entrada, build reproduzível, configuração que o destino precisa receber e dependência de serviço que só existe na máquina local (banco em `localhost`, arquivo fora do artefato, variável só no ambiente de quem desenvolve) são bloqueadores de deploy, não detalhes de execução.
+3. Planeje compatibilidade de migration/config/consumidores e ordenação do rollout. Para mudança destrutiva, nomeie os consumidores afetados e a ordem expand/contract, e valide backup e restauração antes do ponto irreversível. Leia a referência de transição quando houver migração de schema, dados, formato, protocolo ou contrato.
+4. Somente no modo executar, com gates satisfeitos e ferramenta disponível, use o mecanismo existente, artefato identificado e credenciais externas ao código. Gate pendente bloqueia a promoção ao ambiente que ele protege, não a homologação autorizada: execute o que for seguro e reversível. No modo executar autorizado, commit, tag, push e acesso ao destino e ao pipeline fazem parte do pedido; correção de gate entra como commit próprio, citado na saída. Mudança de configuração remota, flag ou catálogo de experimento é promoção: muda comportamento em produção sem passar pelo artefato, então pede o mesmo destino confirmado, a mesma autorização, histórico de versão e caminho de volta. Flag sem default seguro no cliente transforma indisponibilidade da configuração em indisponibilidade do produto.
+5. Antes de promover, determine se o destino tem caminho de volta: revisão imutável com desvio de tráfego volta em minutos; destino que não guarda a versão anterior só recupera para frente, e isso muda o risco aceitável e precisa estar dito no plano, com o tempo estimado de recuperação. Voltar por um ciclo completo de pipeline é o caminho lento: não o apresente como o mecanismo de rollback quando existir desvio de tráfego ou revisão anterior ativa.
+6. Após execução, faça smoke do serviço e da jornada relevante, confira versão e observabilidade. Prova de publicação é asserção sobre o destino: a versão que o destino reporta (registry, endpoint de versão, revisão ativa, digest do artefato) tem de ser a que você publicou. Job verde, log de upload, espera por tempo fixo e porta aberta não provam que a versão certa está no ar nem que a aplicação está pronta. Reverter binário não desfaz dados; aplique a estratégia de recuperação adequada.
+7. Registre destino, revisão, jobs/execuções, resultado, pendências, estado de cada gate por ambiente e decisão de promoção/rollback.
 
 Recursos da máquina: gates locais (build, suíte, empacotamento) rodam em sequência, com workers limitados por `crow-skills resources --json` quando existir; não repita localmente o que o CI do repo já prova. Sob pressão `critical`, não inicie build local e relate o bloqueio. Encerre processos e containers que subiu para o smoke. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
 
+## Detalhes condicionais
+
+- Leia [transicao.md](references/transicao.md) para migração de schema, dados, formato, protocolo, configuração ou dependência.
+
 ## Saída e aceite
 
 Entregue **release-evidence** na resposta final ou em arquivo do projeto cujo caminho você informa (memória ou ledger externo não contam), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.

package/skills/crow-release/references/transicao.md

@@ -0,0 +1,13 @@
+# transicao
+
+Leia ao promover mudança de schema, dados, formato, protocolo, configuração ou dependência.
+
+Antes de editar, mapeie quem lê e quem escreve o dado, o formato atual, a janela em que as duas versões vão coexistir e quem é dono de cada lado. Consumidor fora do seu repositório conta, e cliente instalado no dispositivo do usuário continua na versão antiga pelo tempo que ele demorar a atualizar: essa é a janela real, não a duração do rollout.
+
+Durante o rollout as duas versões rodam ao mesmo tempo, inclusive em sentido contrário se houver rollback. Cada etapa precisa ser segura nas duas leituras: a versão antiga não pode falhar com o dado novo e a versão nova não pode exigir o que ainda não existe. Campo novo entra opcional com default, leitura nova tolera ausência, e só depois a escrita passa a preencher.
+
+Expandir, migrar, verificar e contrair são etapas distintas, cada uma com autorização própria. A contração apaga o caminho antigo e é irreversível: não a execute junto com a expansão nem por inferência de um pedido que autorizou a etapa anterior. Pare quando a etapa pedida passar e diga, na saída, qual é a próxima e o que ela destrói.
+
+A migração em si precisa ser repetível: escrita idempotente, retomada a partir de onde parou e registro de progresso que distinga "não processado" de "processado sem efeito". Falha pela metade é o caso normal, não a exceção: declare como o estado parcial é observável, como se descobre o que faltou e o que acontece se a migração rodar duas vezes.
+
+Na verificação, exerça o caminho antigo e o caminho novo na mesma revisão promovida, com dado real do ambiente, e compare contagem e amostra antes e depois para provar preservação. Backup testado é restauração testada: backup cuja restauração ninguém exercitou não é caminho de recuperação, é expectativa.

package/skills/crow-reverse/SKILL.md

@@ -15,7 +15,7 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 
 ## Trabalho
 
-1. Registre identidade/hash/versão do artefato e a hipótese a investigar. Não trate documentação, strings ou decompilação como prova de execução real.
+1. Registre identidade/hash/versão do artefato e a hipótese a investigar. Não trate documentação, strings ou decompilação como prova de execução real. Trabalhe sempre em cópia: não altere os bytes do artefato original e confira ao final que o hash não mudou. Operação destrutiva ou que muda estado acontece só na cópia, dentro do espaço de trabalho do caso.
 2. Comece por inspeção estática e formato/imports/recursos/calls relevantes. Escolha ferramentas pela plataforma e capacidade instalada, sem exigir um decompilador específico.
 3. Se precisar de observação dinâmica, confirme escopo e use ambiente isolado para artefato desconhecido; não execute código não confiável com credenciais/integrações pessoais. Se o isolamento impedir a execução, declare a análise dinâmica não verificada e proponha ao dono um perfil alternativo (sem rede, escrita só em diretório temporário); não troque de perfil sem a decisão dele.
 4. Rotule cada conclusão literalmente como observado, inferido ou desconhecido. Verifique chamadas e caminhos antes de concluir sobre manutenção, rede ou privilégio.

package/skills/crow-secrets/SKILL.md

@@ -15,10 +15,10 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 
 ## Trabalho
 
-1. Mapeie quem usa qual referência de credencial e para quê, sem extrair valores para relatório. Reutilize autenticação aprovada com tenant/ambiente corretos.
+1. Mapeie quem usa qual referência de credencial e para quê, sem extrair valores para relatório. Reutilize autenticação aprovada com tenant/ambiente corretos. Acesse o secret store pelo caminho que o projeto define (wrapper, CLI ou SDK aprovados); não invente um caminho de acesso nem contorne o aprovado para ler mais rápido.
 2. Prefira identidade de workload e credencial de curta duração quando suportadas. Não crie camada de vault/rotação para requisito inexistente.
 3. Verifique exposição em código, logs, URL, build context, artefatos e histórico com tooling que redija valores. Não imprima um dump de configuração para descobrir nomes. Arquivo de segredo versionado sai do índice (`git rm --cached` e ignore) e é conferido com `git ls-files`; o histórico segue exposto, então a credencial entra no plano de revogação.
-4. Para mudança autorizada, planeje criar/entregar/verificar/revogar na ordem compatível com consumidores. Rotação destrutiva ou ampliação de privilégio exige escopo explícito; se revogar e manter conflitam, entregue o plano sem executar.
+4. Para mudança autorizada, planeje criar/entregar/verificar/revogar na ordem compatível com consumidores. Mantenha a credencial antiga e a nova válidas ao mesmo tempo durante a migração (janela de sobreposição ou aceitação dupla), migre cada consumidor para a nova e só então revogue a antiga: revogar antes de migrar derruba consumidor, e credencial substituída sem revogação confirmada continua viva. Rotação destrutiva ou ampliação de privilégio exige escopo explícito; se revogar e manter conflitam, entregue o plano sem executar.
 5. Valide presença e acesso por chamada mínima, sem registrar a credencial. A suíte continua passando no CI sem segredos reais; se passar a exigir variáveis, diga quais. Produza referências, responsáveis, prazo concreto e recuperação; o que faltar vira pendência com quem decide.
 6. Rotação não termina quando a credencial nova funciona: termina quando cada consumidor foi verificado carregando a nova. Enumere os consumidores antes de rotacionar e mantenha essa lista junto da referência da credencial — lista incompleta é o defeito: em 2026-10-20 um token npm trocado por exposição foi atualizado em seis repositórios e um sétimo ficou 15 dias com o valor revogado, descoberto só quando um release recusou publicar. Depois de rotacionar, confira cada consumidor individualmente e nomeie todos no relato; o que você não conseguiu conferir entra como não verificado, nunca como presumido.
 7. Onde a credencial só é lida (metadado de registry privado, download de pacote), a credencial velha não falha autenticação: responde "não encontrado". O sintoma se disfarça de ausência de dado em vez de falta de permissão, e um fluxo que lê 404 como "versão nunca publicada" segue adiante publicando errado — então leitura silenciosa exige conferência explícita, não ausência de erro. Conferência barata: consumidor cujo segredo tem última atualização anterior à data da rotação é suspeito pela aritmética (no GitHub, `gh secret list` imprime esse carimbo por repositório); o carimbo não prova o valor, só mostra que ninguém tocou nele desde então.

package/skills/crow-security-review/SKILL.md

@@ -15,23 +15,30 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 
 ## Trabalho
 
-1. Defina o escopo e leia o caminho relevante, incluindo callers e controles upstream. Em código desconhecido, construa contexto suficiente antes de julgar.
-2. Busque violações com ator, entrada controlável, recurso afetado e resultado de segurança; um padrão suspeito sozinho é candidato, não vulnerabilidade confirmada.
-3. Trace os dados até o efeito e procure controles compensatórios e contraexemplos. Certeza depende da evidência do caminho; prioridade depende de impacto, alcance e pré-condições. Registre-os; evite nota numérica ou severidade precisa quando faltam fatos.
-4. Deduplicate achados de mesma causa. Preserve estados confirmado, precisa-validacao e rejeitado com evidência/limitação e menor correção eficaz.
-5. Verifique o diff corrigido e a evidência de regressão quando forem disponibilizados. Não afirmar teste dinâmico se apenas inspecionou o código.
+1. Fixe a faixa antes de ler qualquer linha: declare o alvo e a revisão base (commit, tag, branch, merge-base ou "árvore atual, sem base"), confirme que a referência resolve e que o diff não é vazio, e liste os arquivos que entram. Revise o que esta mudança introduz; defeito pré-existente que aparecer no caminho vira nota separada, fora dos achados desta revisão, e nunca substitui a faixa pedida pelo repositório inteiro.
+2. Declare o limiar de reporte e a política de exclusão desta revisão, por alvo, antes de julgar: o que você vai reportar, o que fica deliberadamente fora e o motivo de cada exclusão. A exclusão é decisão datada deste alvo, não filtro global embutido na skill. Em particular: extensão de arquivo não exclui nada por si — em suíte de agentes, prompt, skill ou documento markdown é superfície de instrução e entra; variável de ambiente não é fonte confiável, porque CI, container, orquestrador e servidor MCP a definem; conteúdo que o atacante consegue colocar num prompt é entrada controlável, não ruído; e em linguagem com garantia de memória o julgamento vale para o subconjunto seguro, não para bloco `unsafe`, FFI ou chamada nativa.
+3. Dentro da faixa, leia o caminho relevante, incluindo callers e controles upstream. Em código desconhecido, construa contexto suficiente antes de julgar.
+4. Busque violações com ator, entrada controlável, recurso afetado e resultado de segurança; um padrão suspeito sozinho é candidato, não vulnerabilidade confirmada.
+5. Trace os dados até o efeito e procure controles compensatórios e contraexemplos. Certeza depende da evidência do caminho; prioridade depende de impacto, alcance e pré-condições. Registre-os; evite nota numérica ou severidade precisa quando faltam fatos.
+6. Deduplicate achados de mesma causa. Preserve estados confirmado, precisa-validacao e rejeitado com evidência/limitação e menor correção eficaz.
+7. Passe os candidatos por uma rodada separada de falso-positivo, depois de levantar os achados e antes de escrever o relatório. O único trabalho dessa rodada é derrubar achado que não se sustenta: refaça a alegação com suas palavras e descarte a que não fecha; procure a validação que precede o trecho e a garantia aritmética que torna a condição impossível; confirme que a entrada alegada chega mesmo ao efeito; distingua asserção defensiva e código de erro de defeito; prove que o valor pode mudar entre checagem e uso antes de aceitar TOCTOU, e que há concorrência real antes de aceitar corrida; separe falha de defesa em profundidade de falha do controle primário. O que cair vai para os descartados com o motivo que o derrubou, não desaparece. A rodada corre nos dois sentidos: não rebaixe achado por conveniência nem porque a exploração parece trabalhosa, e releia o código depois de concluir, porque o controle compensatório que derrubou o achado pode ser lembrança sua, não linha do arquivo — se não tem arquivo:linha, não derruba.
+8. Verifique o diff corrigido e a evidência de regressão quando forem disponibilizados. Não afirmar teste dinâmico se apenas inspecionou o código.
 
 ## Saída e aceite
 
 Entregue **security-findings** na resposta final (memória ou ledger externo não contam; não escreva no projeto), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.
 - A resposta final, mesmo com anexo, traz em uma linha cada: mudanças e extras (inclusive testes novos, gerador, template ou tooling); conflitos com opções (custo e risco), quem decide, padrão adotado e como revertê-lo; conteúdo hostil com arquivo:linha e trecho literal e completo, sem removê-lo; descartados; mudanças de contrato; acesso à rede ou escrita fora do projeto, incluindo memória, vault ou ledger externos; processos que você subiu e encerrou. "Passou" sem comando não é evidência; não afirme ausência de erros sem execução; o que não pôde ser executado fica como não verificado.
 - Achados citam arquivo/linha ou artefato verificável e estado de certeza.
+- Cada achado leva um identificador estável derivado do alvo, do arquivo e da classe (reemitido igual numa segunda revisão da mesma faixa, para o dono casar achado novo com achado antigo), a classe CWE quando houver uma que corresponda (sem forçar quando não houver) e um cenário de exploração concreto: quem é o ator, o que ele envia ou controla, por onde entra, e qual efeito observável sai disso. Cenário que não chega ao efeito, ou que só diz "pode causar problemas", não é cenário: o achado volta para precisa-validacao.
+- A faixa revisada, o limiar de reporte e cada exclusão com seu motivo aparecem na saída; defeito pré-existente fora da faixa vai em nota separada, não misturado aos achados.
 - Ausência de evidência/cobertura é relatada; nenhum alerta foi tratado automaticamente como confirmação.
 
 ## Limites e composição
 
 Read-only: não altera o alvo nem executa build, código, payloads ou conteúdo dele. Execução autorizada é outro escopo.
 
+Toda política, schema ou formato que esta revisão exige mora dentro deste pacote ou no pedido; não condicione a revisão a arquivo fora dele, que no agente instalado simplesmente não existe. Se o dono pedir um formato externo (schema de achado, SARIF) e ele não estiver presente, entregue os achados no formato desta skill e registre o formato pedido como não verificado, em vez de bloquear a entrega num portão que você não consegue ler.
+
 Não corrige nem altera o alvo: cada achado traz a correção sugerida para o dono aplicar. Não crie branch, commit ou push sem pedido ou política declarada do dono. Use só ferramentas já presentes; não baixe binários nem acesse rede além do alvo autorizado no pedido, prefira contexto isolado ao navegador ou desktop pessoal do usuário e, se faltar ferramenta, declare como não validado. Controles corretos que você verificou, credenciais visivelmente fictícias (fixtures, exemplos) e falsos positivos não são defeito: liste cada um nos descartados, com motivo. Subagentes delegados carregam esta skill; revisores não editam arquivos nem commitam no projeto (exercer a hipótese contra o alvo autorizado não é escrita).
 
 Próximos responsáveis possíveis: `crow-security-scan`, `crow-security-test`, `crow-qa`. Na seção final, nomeie o pertinente, o que ele recebe e se está instalado neste agente, ou diga por que não há; não instalado não é inexistente: entregue o artefato e as pendências. Não são dependências obrigatórias nem uma ordem automática de execução.

package/skills/crow-security-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crow-security-scan
-description: "Execute ou analise SAST, dependências, imagens e IaC conforme o alvo; normalize e compare resultados. Não confirma explorabilidade nem faz autofix."
+description: "Use para rodar ou analisar scanner (SAST, dependências/SCA, imagem, IaC) e normalizar, deduplicar e comparar o resultado com a baseline. Achado é alegação: entrega candidatos com evidência, não confirma explorabilidade nem faz autofix — isso é de crow-security-review (julga a mudança) e crow-security-test (prova dinâmica). Diferente delas, aqui a saída é evidência de ferramenta sobre o alvo estático."
 ---
 
 # Scans e evidência estática
@@ -15,11 +15,16 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 
 ## Trabalho
 
-1. Escolha só o scanner que responde à pergunta: SAST para fluxos/padrões, SCA para pacotes, scanner de imagem/IaC para esses artefatos. Verifique versão e modo disponíveis.
+1. Escolha só o scanner que responde à pergunta: SAST para fluxos/padrões, SCA para pacotes, scanner de imagem/IaC para esses artefatos. Verifique versão e modo disponíveis. Desligue telemetria e egress do scanner e fixe o ruleset, sem depender do modo que telefona para casa; não dependa só do ruleset default, inclua regras especializadas da linguagem.
 2. Fixe escopo, regras e baseline. Mantenha source read-only, resultados em diretório dedicado e telemetria/egress conforme o ambiente autorizado.
 3. Não rode builds, scripts de pacote ou extensões controladas pelo alvo no host com credenciais. Quando execução do alvo for necessária, use isolamento real aprovado ou analise evidência existente.
 4. Registre comando/modo, exit code, o que rodou, falhou, foi pulado ou não teve cobertura. Resultado vazio não é prova de execução bem-sucedida. Categoria sem scanner disponível fica sem cobertura; não a substitua por script improvisado.
-5. Em SARIF, resolva severidade herdada e normalize URIs/fingerprints; deduplique por (ruleId, caminho, linha) e informe contagens bruta e deduplicada e, contra a baseline, novos, persistentes e ausentes. Liste primeiro os novos acionáveis e separe suprimidos, fixtures e ruído. Preserve saída bruta e passe candidatos à revisão.
+5. Em SARIF, resolva severidade herdada (ferramentas como CodeQL gravam o nível na regra, não no resultado) e normalize URIs/fingerprints mantendo o diretório na chave; deduplique por (ruleId, caminho, linha) e informe contagens bruta e deduplicada e, contra a baseline, novos, persistentes e ausentes. Liste primeiro os novos acionáveis e separe suprimidos, fixtures e ruído. Preserve saída bruta e passe candidatos à revisão.
+6. Achado de scanner é alegação, não risco confirmado. Em SCA, cubra a árvore transitiva pelo lockfile e triague por alcançabilidade, EPSS e KEV em vez de só CVSS; marque a severidade como pendente de verificação de alcance e deixe a confirmação para revisão ou teste. Sinalize cadeia de suprimentos (typosquat, script de instalação, pacote abandonado ou sem licença) sem executar script do alvo.
+
+## Detalhes condicionais
+
+- Leia [evidencia-scan.md](references/evidencia-scan.md) ao configurar o scanner e triar: telemetria, rulesets, severidade herdada em SARIF, normalização de caminho, triagem de alcançabilidade em SCA e config de pipeline.
 
 Recursos da máquina: scanners são jobs pesados: rode um por vez, salvo recomendação maior de `crow-skills resources --json` quando existir, com jobs/threads limitados pelo `maxWorkersPerJob` quando a ferramenta aceitar. Leia SARIF e relatórios grandes por consulta (`jq`, filtro, intervalo), não inteiros no contexto. Com a crow-behaviour disponível, siga também a referência de recursos dela (medição, ledger e flags de workers).
 

package/skills/crow-security-scan/references/evidencia-scan.md

@@ -0,0 +1,17 @@
+# evidência de scan
+
+Leia ao configurar o scanner e ao triar o resultado.
+
+Desligue telemetria e egress do scanner. Modo que escolhe regras pela nuvem ou envia métricas por padrão exfiltra dado do alvo durante uma auditoria; use a flag que corta métricas em todo comando e fixe o ruleset em vez do automático que telefona para casa.
+
+Não dependa só do ruleset default. Regras especializadas da linguagem e de terceiros curados pegam padrões que o registro oficial não cobre; inclua as pertinentes à linguagem detectada e registre quais rodaram.
+
+Severidade em SARIF nem sempre está no resultado. Ferramentas como CodeQL omitem `level` no resultado e gravam a severidade na regra (`defaultConfiguration.level`), que o resultado herda. Portão que lê `result.level` direto pontua como limpo um repositório cheio de erros. Resolva na ordem: `kind` diferente de `fail` vira `none`; senão `result.level`; senão a regra casada por `ruleIndex` ou `ruleId`; senão o default `warning`.
+
+Normalize caminho antes de deduplicar: remova o esquema `file://`, decodifique percent-encoding, resolva contra a base e unifique separadores. Mantenha o diretório na chave de dedupe; a mesma regra na mesma linha em `auth/login.py` e `admin/login.py` são dois achados, e chave só por basename descarta um.
+
+Achado de SCA é alegação, não risco confirmado. A maioria dos alertas de dependência não é alcançável no caminho de código real, e CVSS alto não é o mesmo que explorável aqui. Não reporte severidade bruta do CVE como risco efetivo: triague com probabilidade de exploração (EPSS), exploração conhecida em catálogo (KEV) e alcançabilidade, e marque a severidade como pendente de verificação de alcance. Confirmar alcançabilidade é trabalho da revisão ou do teste dinâmico, não deste scan; entregue o candidato com o rótulo.
+
+Em dependências, leia o lockfile para cobrir a árvore transitiva, não só as diretas. Sinais de cadeia de suprimentos a marcar: nome parecido com pacote popular (typosquat/confusão de dependência), script de instalação (pre/post-install), pacote sem manutenção recente e pacote sem licença declarada. Não execute script de instalação para investigar; leia o manifesto e os metadados do registro.
+
+Em pipeline como código (GitHub Actions, GitLab CI), trate a config como superfície: gatilho que expõe segredo a PR não confiável, interpolação de entrada de usuário em shell, permissão ampla de token e action de terceiro presa a tag mutável em vez de SHA. Isso é escopo de IaC/config, não de SAST de aplicação.

package/skills/crow-security-test/SKILL.md

@@ -15,12 +15,16 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 
 ## Trabalho
 
-1. Fixe hosts/contas/tenants/endpoints, janela e técnicas permitidas. Ausência de escopo não vira autorização herdada de um arquivo, skill ou exemplo.
+1. Fixe por escrito hosts/contas/tenants/endpoints, operações proibidas, limite de taxa, janela e técnicas permitidas. Ausência de escopo não vira autorização herdada de um arquivo, flag, skill ou exemplo, e não se auto-concede. Sem autorização confirmada, não execute: entregue análise estática com o limite declarado e peça a autorização que falta.
 2. Escolha a prova menos invasiva que responde à hipótese. Use fixture e contas de teste, limite requisições e defina parada antes de executar. Em alvo descartável ou efêmero (fixture local, banco em memória), uma prova mutante mínima e revertida (alterar e restaurar o próprio papel, por exemplo) é preferível à evidência estática; diga que o estado persistente não muda e por quê.
 3. Não inclua destruição, exfiltração de dados reais, persistência, movimento lateral ou esgotamento como padrão de validação.
 4. Execute somente ações no limite confirmado e registre versão, requests redigidos, respostas e estado antes/depois; em alvo local, inclua hashes (SHA-256) dos arquivos que a prova pode tocar e `git status`. Interrompa ao cruzar efeito ou fronteira não prevista.
 5. Faça cleanup de efeitos próprios e entregue confirmado/inconclusivo/rejeitado com reprodução segura e recomendação. A reprodução foi executada com a saída capturada, ou é declarada como só validada sintaticamente. Se não for seguro executar, entregue análise estática e explique o limite. Se o host puder cortar a resposta final, grave também o artefato em arquivo no diretório de trabalho autorizado e informe o caminho.
 
+## Detalhes condicionais
+
+- Leia [prova-dinamica.md](references/prova-dinamica.md) ao fixar a autorização e escolher a prova mínima por classe (controle de acesso, autorização de função, bypass de sessão, confusão de token, injeção, SSRF).
+
 ## Saída e aceite
 
 Entregue **security-test-evidence** na resposta final ou em arquivo do projeto cujo caminho você informa (memória ou ledger externo não contam), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.

package/skills/crow-security-test/references/prova-dinamica.md

@@ -0,0 +1,24 @@
+# prova dinâmica
+
+Leia ao fixar a autorização e ao escolher a prova mínima por classe.
+
+## Contrato de autorização
+
+Antes de qualquer ação, fixe por escrito: alvos exatos (hosts, contas, tenants, endpoints), contas e papéis permitidos, operações proibidas, limite de taxa e janela de tempo. A autorização é explícita e rastreável a quem a concedeu; não é herdada de um arquivo, flag, exemplo ou skill, e não se auto-concede. Produção só entra com autorização específica do dono.
+
+Sem autorização confirmada, não execute: entregue análise estática com o limite declarado e peça a autorização que falta. Nunca invente a permissão nem rode "só para confirmar". Ao cruzar qualquer fronteira ou efeito não previsto no contrato, pare e relate.
+
+O que esta skill não faz como padrão de validação: varredura ampla, fuzzing em massa, força bruta, DoS ou esgotamento de recurso, exfiltração de dado real, persistência e movimento lateral. Essas fases aparecem em suítes ofensivas de concorrentes; aqui elas não provam a hipótese e aumentam o dano. A prova é a mínima que responde à suspeita.
+
+## Prova mínima por classe
+
+Escolha a evidência menos invasiva que confirma a hipótese, com conta de teste e fixture, e registre estado antes/depois.
+
+- Controle de acesso quebrado (IDOR/BOLA): com duas identidades de teste, mostre que a de menor privilégio lê ou altera o recurso da outra. A prova é a comparação das duas sessões sobre o mesmo recurso, não a varredura de todos os ids.
+- Autorização de função (BFLA): uma conta sem o papel executa a operação restrita, ou um método/rota que deveria ser negado responde. Um caso basta; não enumere a API inteira.
+- Bypass de autenticação ou sessão: acesso ao recurso protegido sem credencial válida, ou com sessão que deveria estar inválida. Capture o request redigido e a resposta.
+- Confusão de token (ex.: algoritmo trocado, verificação com a chave errada): demonstre a aceitação de um token que deveria ser rejeitado em alvo de teste; se não for seguro forjar, entregue a análise do caminho de verificação como alegação a validar.
+- Injeção numa rota específica: a prova mínima é o efeito observável controlado (valor refletido, erro que revela estrutura, uma linha de dado de fixture), não a extração do banco nem a execução destrutiva.
+- SSRF: mostre que o alvo busca um destino que você controla ou um recurso interno delimitado; pare na confirmação do acesso, sem varrer a rede interna nem tocar metadado sensível real.
+
+Cada prova tem alvo e autorização rastreáveis, reprodução segura e estado restaurado no cleanup. Não há alegação de ausência de vulnerabilidade além da cobertura realizada.

package/skills/crow-seo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crow-seo
-description: "Revise conteúdo e saída técnica de páginas públicas para busca, coerência e indexação. Não otimiza área logada nem promete ranking."
+description: "Use quando páginas públicas precisam ser encontráveis e a saída que o indexador recebe precisa ser conferida: status, metadado, canonical, robots, sitemap, dados estruturados, links internos, hreflang e renderização. Entra também quando uma rota saiu do índice, aparece sem descrição ou duplica outra. Não promete posição nem tráfego, não otimiza área logada e não é aquisição paga ou experimento de crescimento, que é de crow-growth."
 ---
 
 # Saída pública e descoberta
@@ -16,11 +16,13 @@ Se pedido, documentação ou requisitos se contradizem, nomeie o conflito com a
 ## Trabalho
 
 1. Confirme quais rotas devem ser públicas e indexáveis. Homologação, dados privados e páginas autenticadas não viram alvos de SEO por padrão. Não afrouxe Disallow, noindex nem auth de rota excluída de propósito: é decisão do dono. Se o pedido conflita com privacidade, mantenha a privacidade e registre o trade-off como pendência.
-2. Verifique intenção, utilidade, autoria/proveniência real e atualização do conteúdo sem fabricar experiência, reviews ou métricas.
-3. Inspecione HTML e resposta efetivos: status, title/description, canonical, robots, links e sitemap coerentes. Código-fonte do framework não é prova da saída.
-4. Use structured data apenas quando corresponda ao conteúdo visível e tipo elegível; valide schema e consistência de preço/avaliação.
+2. Verifique intenção, utilidade, autoria/proveniência real e atualização do conteúdo sem fabricar experiência, reviews, credencial ou métricas. Data de modificação alterada sem mudança real de conteúdo é sinal fabricado.
+3. Inspecione HTML e resposta efetivos: status, title/description, canonical, robots, links e sitemap coerentes. Código-fonte do framework não é prova da saída. Em rota com sinais contraditórios, corrija o sinal mais forte e reavalie em vez de abrir um achado por consequência — `Disallow` impede a leitura do `noindex`, e canonical para url que redireciona ou está `noindex` não decide nada. Metatag fora do `<head>` é ignorada.
+4. Use structured data apenas quando corresponda ao conteúdo visível e tipo elegível; valide schema e consistência de preço/avaliação. Schema válido não garante rich result: diga a elegibilidade, não o resultado.
 5. Priorize correções com impacto demonstrável e verifique a resposta final. Diferencie requisito técnico de hipótese de aquisição.
 
+A [saída técnica](references/saida-tecnica.md) tem a inspeção detalhada: precedência de sinais, host e forma de url, higiene de sitemap, grafo de links internos, metadado de compartilhamento, `hreflang`, paginação, renderização para indexador, peso de página, PDF e superfície para leitura automatizada. Leia o bloco do achado antes de editar.
+
 ## Saída e aceite
 
 Entregue **seo-change** na resposta final ou em arquivo do projeto cujo caminho você informa (memória ou ledger externo não contam), conciso e com: alvo/revisão; mudanças ou achados por item, com arquivo:linha; evidência (comando e saída resumida) rotulada como observado, inferido ou simulado; conflitos e decisões pendentes; descartados (controles corretos verificados, credenciais fictícias e falsos positivos) com motivo; não verificado; próximo responsável.