MaxLaurieHutchinson/skill-evaluation-graph

SEG: Skill Evaluation Graph: Driver Procedural para Auditoria e Otimização de Skills de Agentes

Transforme skills de agentes em ativos de engenharia confiáveis, eficientes em tokens e prontos para produção. Avalia precisão de acionamento, arquitetura de divulgação progressiva, orientação comportamental, determinismo de execução, segurança operacional e economia de tokens.

---

Matriz de Referência Rápida

Aspecto	Propósito	Recurso Autoritativo
Terminologia Canônica	Vocabulário autoritativo e definições de domínio	references/terminology.md
Rubrica de Auditoria de 6 Pilares	Definições objetivas de pontuação de 1 a 5	references/audit-rubric.md
Catálogo de Antipadrões	Guia de diagnóstico para 14 defeitos recorrentes de skills	references/anti-patterns.md
Engenharia de Contexto	Padrões de divulgação progressiva em vários níveis	references/progressive-disclosure-patterns.md
Grafo de Avaliação e Loop	Manual do Motor de Loop Avaliador Autônomo	references/workflow-graph-and-evaluator-loop.md
Compatibilidade de Harness	Mapeamentos de ferramentas entre plataformas (Antigravity/Claude/Codex)	references/harness-tool-matrix.md
Executor de Testes Comportamentais	Avaliação de Controle vs. Tratamento e testes ao vivo	scripts/eval_skill.py
Auditoria de Reivindicações de Capacidade	Realidade técnica e classificação de evidências	references/claim-audit.md
Modelo de Scorecard	Modelo padronizado de relatório de avaliação	assets/skill-audit-scorecard-template.md
Exemplo de Scorecard	Relatório de avaliação completo exemplar	assets/example-scorecard.md
Scorecard de Autoavaliação	Scorecard de linha de base da autoavaliação do SEG	assets/self-audit-scorecard.md
Alinhamento com Padrões	Estrutura de 14 etapas do Applied AI Wiki	references/wiki-standard-alignment.md
Proteção do Agente	Contrato de contribuidor anti-alucinação	assets/agent-contributor-contract-template.md

[!IMPORTANT] Terminologia Canônica: Use references/terminology.md como vocabulário canônico do SEG. Não introduza sinônimos para conceitos definidos sem atualizar o glossário.

---

Arquitetura do Grafo de Fluxo de Trabalho

[Nó 1: Recepção e Escopo]
          │
          ▼
[Nó 2: Execução Paralela do DAG Avaliador]
  (Esquema, Links, Tokens, Segurança/Privacidade, Portabilidade, Roteamento de Acionamento, Política de Comportamento)
          │
          ▼
[Nó 3: Junção de Evidências Multinó]
          │
          ▼
[Nó 4: Oráculo Avaliador de Múltiplos Portões]
          │
  ┌───────┼───────────────────────────────┐
  ▼       ▼                               ▼
[Nó 5A: ACEITAR]              [Nó 5B/5C: REVISAR]            [Nó 5D: ESCALAR]
(Scorecard & Recibo)  (Verificar Sandbox -> Visualizar/Mutar)   (Atenção Humana Necessária)

---

Driver de Execução Procedural

Siga estas etapas em sequência ao auditar ou otimizar uma skill de agente:

Etapa 1: Identificar Skill Alvo e Verificar Escopo

1. Localize o diretório alvo que contém SKILL.md.
2. Inspecione o inventário do pacote em SKILL.md, references/, scripts/ e assets/.
3. Verifique os manifestos de compatibilidade do harness hospedeiro (.codex-plugin/plugin.json, CLAUDE.md, AGENTS.md, .agents/plugins/marketplace.json).

Etapa 2: Ler a Terminologia Canônica

Consulte references/terminology.md antes de registrar as descobertas. Garanta que todos os comentários e relatórios usem nomes canônicos exatos (por exemplo, Static Quality Score, Oracle Verdict, Evaluation Integrity Gate, Pre-mutation Snapshot).

Etapa 3: Executar o Grafo de Avaliação

Execute o DAG de avaliação paralela modular via scripts/run_loop.py:

# Avaliação somente leitura e visualização de diff (padrão)
python "<skill-dir>/scripts/run_loop.py" "<target-skill-path>" --target-score 95 --max-iterations 3

# Com entrega de scorecard mediante aceitação
python "<skill-dir>/scripts/run_loop.py" "<target-skill-path>" --scorecard "<target-skill-path>/scorecard.md"

Os nós avaliadores executam em ondas de dependência paralelas:

• schema: Valida frontmatter YAML, nomenclatura e campos obrigatórios.
• links_syntax: Resolve links relativos, regras de salto único e blocos de código.
• tokens: Perfila o orçamento de tokens nos 5 níveis de divulgação progressiva.
• safety_privacy: Detecta comandos destrutivos e exposições de caminhos na estação de trabalho.
• portability: Valida o plugin OpenAI Codex e manifestos de marketplace.
• trigger_routing: Verifica acionadores de descrição do frontmatter e limites negativos.
• behaviour_policy: Impõe diretrizes anti-racionalização.

Etapa 4: Juntar Evidências e Avaliar Portões

As evidências de todos os nós são sintetizadas em JoinedEvidence. O EvaluatorOracle impõe 5 portões obrigatórios:

1. Portão de Integridade da Avaliação (Portão 0): Falha fechada se qualquer avaliador encontrar um erro não tratado, exceder o tempo limite ou pular inesperadamente.
2. Portão de Conformidade com a Especificação: Falha se algum nó relatar um SPECIFICATION_ERROR (por exemplo, esquema de marketplace inválido ou frontmatter quebrado).
3. Portão de Segurança e Privacidade: Falha em comandos destrutivos ou vazamentos de caminhos na estação de trabalho.
4. Portão de Integridade de Links: Falha em links relativos de markdown quebrados.
5. Portão de Política de Pontuação de Qualidade Estática: Verifica se a pontuação geral atende ao --target-score (padrão: 95).

Etapa 5: Processar Veredito do Oráculo

• ACCEPT (Nó 5A): Todos os portões obrigatórios foram aprovados e a pontuação de qualidade estática $\ge 95$. Gere scorecard e recibo de avaliação. Status: COMPLETED (ou MUTATED se reparos foram aplicados).
• REVISE (Nó 5B/5C): Defeitos corrigíveis detectados. Prossiga para a Etapa 6.
• ESCALATE (Nó 5D): Bloqueios não resolvíveis ou teto de iteração atingido. Para para intervenção humana com lista detalhada de bloqueios. Status: ESCALATED.

Etapa 6: Derivar Reparo, Verificar em Sandbox e Mutar com Autoridade

Quando o veredito é REVISE:

1. plan_repairs() deriva propostas de patch determinísticas a partir das descobertas.
2. RepairIsolator prepara propostas em uma sandbox de rascunho isolada (tempfile.TemporaryDirectory).
3. O candidato é reavaliado dentro da sandbox usando o DAG e o Oráculo para verificar:
   • O Portão de Integridade da Avaliação passa.
   • Os portões obrigatórios não regridem.
   • Nenhuma nova descoberta ERROR é introduzida.
   • A pontuação de qualidade estática ou a contagem de descobertas melhora estritamente.
4. Se o candidato passar na verificação:
   • Padrão (Somente Leitura): O diff unificado é exibido para revisão humana. A skill alvo no disco permanece intocada. Status: PREVIEWED.
   • Com --apply: Patches verificados são gravados no disco com proteção de snapshot pré-mutação (um diretório de recuperação irmão com nome único). Status: MUTATED.
5. O loop é retomado para a próxima iteração até ACCEPT ou o máximo de iterações esgotado.

Etapa 7: Opcionalmente, Executar Testes Comportamentais

O catálogo versionado incluído está em evaluations/scenarios/. Instale as dependências Python de requirements.txt antes de executar o SEG.

Para validação dinâmica da execução da skill, execute scripts/eval_skill.py:

# Simulação offline de cenários anti-racionalização
python "<skill-dir>/scripts/eval_skill.py" "<target-skill-path>"

# Teste ao vivo autenticado do Codex CLI com diretório inicial isolado
python "<skill-dir>/scripts/eval_skill.py" "<target-skill-path>" --live --harness codex --trials 1 --timeout 90

Etapa 8: Produzir Scorecard Baseado em Evidências

Gere o scorecard de auditoria finalizado via scripts/audit_skill.py:

python "<skill-dir>/scripts/audit_skill.py" "<target-skill-path>" --scorecard "<output-scorecard.md>"

O scorecard projeta estritamente as evidências medidas do DAG e do Oráculo:

• A recomendação corresponde ao Veredito do Oráculo (ACCEPT, REVISE, ESCALATE).
• Os pilares medidos da rubrica projetam as métricas do avaliador.
• Pilares não medidos relatam explicitamente NOT EVALUATED.
• Um recibo de avaliação à prova de violação é salvo com o resumo SHA256 sobre o estado de execução finalizado.

---

Invariantes de Qualidade

• Zero Links Quebrados: Cada link relativo de markdown deve ser resolvido dentro do diretório da skill.
• Salto Único Estrito: Nenhum arquivo de referência pode vincular a um arquivo de referência secundário.
• Conformidade de Orçamento: SKILL.md não deve exceder 300 linhas ou 2500 tokens.
• Portabilidade Autocontida: Zero caminhos de máquina codificados ou diretórios home de usuário.
• Integridade da Evidência: Scorecards e recibos devem refletir evidências verificáveis sem pontuações fabricadas.