jovd83/hitl-monitor-eu-ai-act

Habilidade de Supervisão HITL para o Ato de IA da UE

Use esta habilidade para transformar um fluxo de agente pouco supervisionado em um modelo operacional revisável, interrompível e auditável.

Trate isso como uma habilidade de camada de supervisão. Produza artefatos de engenharia concretos, como políticas, esquemas, transferências, relatórios voltados para revisores, máquinas de estado e fluxos de auditoria. Não recorra a um ensaio genérico de conformidade.

Missão

Projetar uma supervisão que um revisor real possa usar sob pressão:

• explicar por que a ação foi pausada
• mostrar evidências, incertezas e riscos conhecidos em linguagem simples
• preservar contratos legíveis por máquina para política, transferência e tratamento de decisões
• suportar os caminhos: aprovar, modificar, rejeitar, encerrar e solicitar mais contexto
• definir explicitamente comportamento de timeout, escalação e revisão obsoleta
• manter separados a execução em tempo real, a persistência local da habilidade e a infraestrutura de memória compartilhada

Recepção da Tarefa

Antes de produzir artefatos, estabeleça a imagem operacional mínima:

• runtime alvo ou framework de orquestração
• efeitos colaterais que o agente pode acionar
• domínios de risco, como dinheiro, identidade, acesso, segurança ou dados regulados
• superfície de checkpoint, armazenamento ou escalação existente
• função esperada do revisor, se conhecida
• tipo de entrega solicitada

Se a solicitação for subespecificada, faça apenas as perguntas mínimas necessárias para evitar um design enganoso. Caso contrário, prossiga com padrões conservadores e rotule-os claramente.

Modos de Entrega

Escolha o modo de saída mais restrito útil e combine modos apenas quando a tarefa assim exigir.

1. Revisão com foco em descobertas

Use quando o usuário pedir uma revisão, crítica ou avaliação de retrofit.

Retorne:

• descobertas ordenadas por gravidade primeiro
• padrões inseguros e riscos de viés de automação
• limites de controle ausentes
• campos de contrato ou auditoria ausentes
• o caminho de correção mínimo viável

2. Pacote de arquitetura

Use quando o usuário precisar de um design de sistema ou modelo operacional.

Retorne:

• limites de componentes e confiança
• fluxo de pausa e retomada
• comportamento de timeout e escalação
• transições de estado
• suposições de armazenamento e auditoria

3. Pacote de contrato

Use quando o usuário precisar de artefatos tipados ou payloads prontos para implementação.

Retorne:

• política de interceptação alinhada a ../schemas/interception-policy.schema.json
• pacote de transferência alinhado a ../schemas/handover-packet.schema.json
• decisão de revisão alinhada a ../schemas/review-decision.schema.json
• suposições em nível de campo onde os contratos do repositório não determinam totalmente a resposta

4. Pacote para revisor

Use quando o usuário quiser um relatório legível por humanos ou superfície de aprovação.

Retorne:

• uma transferência neutra em markdown alinhada com ../examples/handover-report.template.md
• o pacote legível por máquina correspondente quando o detalhe de implementação estiver no escopo
• perguntas do revisor, caminhos de não aprovação e metadados de prazo ou escalação

5. Pacote de implementação

Use quando o usuário quiser código, pseudocódigo, APIs ou orientação de integração específica para a stack.

Retorne:

• código ou pseudocódigo alinhado à stack
• formas validadas de política, transferência e decisão
• regras de ocultação e auditoria
• tratamento de timeout, revisão obsoleta e segurança contra repetições

Fluxo de Trabalho Operacional

1. Estabeleça o limite

Identifique o runtime, os efeitos colaterais, a superfície de persistência e o artefato exato que o usuário precisa.

Se o framework for desconhecido, projete um limite de supervisor independente de runtime e marque as suposições explicitamente.

2. Fundamente o design nos objetivos legais de controle

Leia legal-controls.md antes de redigir o modelo de controle.

Traduza os objetivos de controle em comportamento de engenharia:

• o humano pode entender o que está pendente
• o humano pode detectar incertezas, anomalias e limitações
• o humano pode modificar, rejeitar, reverter ou interromper a ação
• o evento pode ser reconstruído posteriormente a partir de política, pacote, decisão e evidência de rastreamento

Não otimize o design para a confirmação mais rápida.

3. Defina a política de interceptação

Quando a tarefa precisar de regras operacionais, produza um contrato de política tipado alinhado a ../schemas/interception-policy.schema.json.

Cubra pelo menos estas famílias de gatilho:

• baixa confiança ou evidência insuficiente
• ações sensíveis ou irreversíveis
• anomalias ou comportamento instável
• falhas repetidas ou loops
• violações de política, como proveniência ausente, ocultação, função do revisor ou pré-requisitos de revisão

Se os limites estiverem ausentes, escolha padrões conservadores e rotule-os como padrões.

4. Construa o pacote de transferência

Quando a tarefa precisar de um payload de pausa legível por máquina, alinhe-se a ../schemas/handover-packet.schema.json.

No mínimo, preserve:

• identificadores de execução, rastreamento e política
• resumo da ação pendente
• argumentos de máquina ocultados
• resumo de evidências
• resumo de incertezas
• riscos conhecidos
• perguntas do revisor e ações recomendadas
• função do revisor, prazo e fallback de timeout
• referências de auditoria e notas de ocultação

Não exija a divulgação de cadeia de pensamento oculta. Prefira resumos de raciocínio concisos e referências de evidência.

5. Defina o contrato de decisão

Quando a tarefa precisar de comportamento de retomada ou substituição, alinhe-se a ../schemas/review-decision.schema.json.

Suporte o conjunto fechado de decisões:

• approve
• modify
• reject
• kill
• request_more_context

Para modify, exija substituições estruturadas e mantenha a ação original bloqueada a menos que o revisor permita explicitamente o contrário.

6. Implemente pausa e retomada com segurança

Leia hitl-patterns.md ao projetar o fluxo de runtime.

Prefira primitivas nativas de checkpoint ou interrupção em vez de polling ad hoc.

Torne estes estados explícitos:

• running
• paused awaiting review
• approved
• modified
• rejected
• halted
• timed out
• resumed

Nunca retome a partir de texto livre do revisor sozinho.

7. Projete auditabilidade e observabilidade

Leia observability-and-logging.md ao escolher a telemetria.

Conecte:

• solicitação ou execução original
• avaliação da política
• criação da transferência
• decisão humana
• execução retomada ou interrompida
• resultado final

Prefira armazenamento somente de anexação ou à prova de adulteração quando o ambiente suportar.

Contrato de Resposta Obrigatório

Siga estas regras de resposta, a menos que o usuário peça explicitamente algo mais restrito:

• Mantenha a lógica da política, o payload de transferência e a decisão de revisão separados. Não os mescle em um objeto indiferenciado.
• Acompanhe a saída legível por máquina com uma breve explicação humana sempre que um revisor precisar agir sobre ela.
• Para tarefas de crítica ou revisão, apresente as descobertas primeiro.
• Para tarefas de implementação, prefira artefatos tipados em vez de orientação apenas em prosa.
• Rotule suposições em vez de inventar silenciosamente requisitos ausentes de produto ou legais.
• Se um campo solicitado não estiver disponível, diga que não está disponível. Não o invente.

Lista de Verificação Mínima de Segurança

Se você estiver produzindo um pacote de transferência ou revisão sob pressão de tempo, não omita estes itens:

• referência à política e por que a revisão é necessária
• resumo da ação pendente
• por que a ação está sendo proposta agora
• resumo de evidências
• resumo de incertezas
• riscos conhecidos
• perguntas do revisor
• ações do revisor além da aprovação
• função e prazo do revisor
• comportamento de timeout ou escalação
• referências de auditoria ou rastreamento
• status de revisão necessária

Limites de Memória

Use a memória deliberadamente:

• Memória de runtime: estado de execução ativo, contexto de rastreamento, snapshot de evidências e payload de revisão pendente apenas para a execução atual.
• Memória local da habilidade: artefatos do repositório, como esquemas, exemplos, fixtures de avaliação e documentos de referência.
• Memória compartilhada: infraestrutura externa entre agentes para conhecimento reutilizável durável. Não implemente essa infraestrutura dentro desta habilidade, a menos que o usuário peça explicitamente por um limite de integração.

Regras de promoção:

• não persista automaticamente o estado de runtime
• não promova automaticamente padrões locais do projeto para a memória compartilhada
• promova apenas conhecimento estável, auditável e com escopo apropriado

Diretrizes de Segurança

• Não reivindique conformidade legal apenas pelo uso da habilidade.
• Não reduza a supervisão a um botão de aprovação mais uma pontuação de confiança.
• Não exponha segredos, credenciais ou telemetria interna irrestrita aos revisores.
• Não misture lógica de controle de runtime com infraestrutura de memória compartilhada.
• Não invente requisitos de produto que alterem materialmente o risco sem rotulá-los como suposições.
• Não apresente um pacote legível por máquina como explicação humana suficiente por si só.
• Não deixe o comportamento de timeout ou revisão obsoleta indefinido quando o fluxo de trabalho puder pausar no tempo.
• Não deixe a identidade ou função do revisor desaparecer da trilha de decisão.

Armadilhas Comuns

Evite estas armadilhas frequentes de implementação:

• Viés de Automação: Revisores geralmente clicam em "Aprovar" sem ler a transferência. Combata isso exigindo um "Modificador" ou fazendo uma pergunta específica no handover_packet.
• A Armadilha do Estado Obsoleto: Uma revisão pode acontecer minutos ou horas após a pausa. Garanta que o sistema verifique se as condições originais (por exemplo, preço, inventário ou contexto de segurança) ainda são válidas antes de retomar.
• Lacuna de Contexto: Se a transferência for muito técnica, o revisor não pode exercer supervisão significativa. Sempre acompanhe os argumentos de máquina com um evidence_summary legível por humanos.
• Aprovações Implícitas: Nunca trate um "Timeout" como uma "Aprovação" implícita em cenários de alto risco. Timeouts geralmente devem acionar um caminho de kill ou escalate para permanecerem em conformidade.
• Vazamento de Dados em Transferências: Tenha cuidado para não incluir PII ou segredos no pacote de transferência que o revisor não deva ver, mesmo que esses dados fizessem parte do raciocínio interno do agente.
• O Anti-padrão "Espera Ocupada": Evite bloquear o processo do agente ou manter um estado de execução contínuo enquanto espera pela revisão manual. Use frameworks com suporte nativo a interrupção ou snapshots de estado duráveis para evitar exaustão de recursos e permitir sessões de revisão que duram dias.
• Validação Apenas por UI: Nunca confie apenas em botões de front-end para ações de "Aprovar" ou "Modificar" em domínios de alto risco. Sempre valide o payload final de review-decision contra o handover-packet do lado do servidor para garantir uma trilha de auditoria à prova de adulteração do que foi realmente revisado.
• Exclusão de Contexto de Rastreamento: Não exclua as chamadas de ferramenta intermediárias ou o raciocínio interno depois que uma decisão for tomada. Retenha metadados de rastreamento suficientes (conformidade com o Artigo 12) para que um auditor posterior possa reconstruir o ambiente exato em que o agente estava quando propôs a ação.
• A Armadilha da Aprovação Conversacional: Evite retomar o agente com base em uma simples mensagem de chat como "parece bom" ou "ok". Force o feedback humano em um contrato estruturado de review-decision para preservar a justificativa tipada e manter a responsabilidade pela substituição.

Tratamento de Falhas

Se a tarefa for subespecificada ou o ambiente for fraco, degrade-se graciosamente:

• framework desconhecido: use um design de wrapper de supervisor e rotule as suposições
• plano de armazenamento ausente: descreva o limite mínimo de persistência antes de continuar
• política quebrada ou ausente: elabore uma política tipada inicial e marque-a como proposta
• função de revisor desconhecida: use um placeholder conservador e destaque-o
• nenhuma stack de observabilidade: use IDs de correlação e eventos de auditoria somente de anexação como linha de base de fallback
• fluxo de trabalho inseguro existente: retorne as descobertas primeiro e mostre o caminho de correção mínimo viável

Referências

Leia apenas o que a tarefa precisa:

• legal-controls.md: requisitos de controle e fundamentação legal
• hitl-patterns.md: padrões de pausa, retomada, máquina de estado e timeout
• handover-schema.md: orientação de contrato para artefatos de política, pacote e decisão
• observability-and-logging.md: design de auditoria e telemetria