Skills nativas e Capability Control Plane

Pack nativo (v0.9.9)

Instalação, setup e update do client materializam um subconjunto declarativo de quatorze fontes curadas no registry privado e no supply-chain existentes. Codex e Claude compartilham esse registry; nenhuma Skill é copiada para suas configurações pessoais. Sessões AUTO e seleção de workers não dependem de downloads upstream.

Fontes: Anthropic Cybersecurity Skills (mantida pela comunidade), Caveman, Claude Red, Codex Security, Hallmark, i-have-adhd, Impeccable, MarketingSkills, Ponytail, reverse-skill, Superpowers, Taste Skill, UI UX Pro Max e Matt Pocock Skills. O intake histórico awesome-gpt-image-2 não integra o pack. O subconjunto inicial de Matt Pocock é domain-modeling, com referências ADR/context-format, não o repositório completo.

Gestão pela TUI e CLI

Abra ivoai → Skills & Capabilities para inspecionar metadados, atualizar o baseline revisado, habilitar/desabilitar, pin/unpin e rollback por fonte. Rollback exige revisão anterior disponível e confirmação na TUI. O mesmo domínio atende:

ivoai skills list
ivoai skills show ponytail
ivoai skills doctor
ivoai skills update
ivoai skills disable hallmark
ivoai skills enable hallmark
ivoai skills pin ponytail
ivoai skills unpin ponytail
ivoai skills rollback ponytail
ivoai config set skills.ponytail auto

Update reconcilia o baseline da release instalada; não confia automaticamente no HEAD upstream. Revisões novas exigem revisão do catálogo. Pin preserva a revisão local ativa. Disable preserva objetos/provenance, mas impede seleção inclusive como dependência. Sem revisão anterior, rollback retorna erro explícito.

Preferências ficam no config do client: skills.ponytail e skills.sources.<source-id>.disabled/pinned, sem credenciais. Registry schema 1 permanece. Só vínculos explícitos ao artifact autorizam substituição; nome ou URL iguais não autorizam adotar Skills pessoais. Colisões falham de forma fechada. Profiles, MCP auth, autenticação dos providers e políticas existentes são preservados.

Seleção por worker e Ponytail

O AUTO não carrega bodies no intake: Prompt Quality Gate e aprovação do plano precedem o preparo dos workers. Seleção usa papel e triggers/keywords curados; dependencies, conflitos, compatibilidade, risco e capabilities disponíveis são verificados antes do body. Referências declarativas ficam locais, sob demanda, sem broadcast em briefs. Contadores de candidatos, bodies lidos e bytes não são estimativas de tokens economizados.

Ponytail oferece off, auto (default) e on, também na TUI. Auto vale somente para implementation workers e exclui risco 70 ou superior. Research, documentation, security, ops e synthesis não o recebem automaticamente. On solicita seleção, mas não supera disable, compatibilidade ou policy. O primary não recebe broadcast do pack. Ponytail não pode reduzir aceite, migração, segurança ou validação necessária, nem alterar executor/model/reasoning, MCPs, DAG ou worktrees.

Disponibilidade não é autorização

ready significa materializado e íntegro localmente. A selection policy é independente: security com tools exige aprovação; shell/alto risco pode continuar negado. Codex Security permanece Codex-only; o ToolProvider executável especializado não é implementado por este pack. Reverse engineering não é autoautorizado. Scripts/binários upstream não são empacotados nem executados: referências declarativas estão disponíveis, mas workflows dependentes desses helpers podem estar indisponíveis pela policy atual. Full não desativa o Skill Gate. impeccable-craft-floor e ui-ux-pro-max-guidelines oferecem referências declarativas revisadas, independentes dos workflows completos que dependem de shell. Roles exclusivos continuam impedindo directors concorrentes no mesmo worker.

Revisão imutável e SHA-256 local não são assinatura/attestation independente. Corrupção falha de forma fechada; use skills doctor, sem editar o registry ou apagar Skills pessoais. Promoção conserva revisão anterior. Setup/reapply explícito pode restaurar um índice nativo ausente após rollback do binário, sem adotar entradas pessoais. OpenCode mostra IDs selecionados e Ponytail por worker, nunca bodies, prompts privados, credenciais ou transcripts.

Este documento descreve os fundamentos implementados por IVOAI-13, IVOAI-14, IVOAI-16, IVOAI-48 e IVOAI-49, além de atualizações seguras de packs, do Skill Gate de sessões gerenciadas e do overlay de fontes curadas pertencente ao IVOAI. Sessões existentes de ivoai auto, ivoai codex e ivoai claude continuam funcionando quando o registry está ausente ou vazio.

Fronteiras

As interfaces provider-neutral core.SkillSource e core.SkillRegistry permanecem estreitas. Metadados ricos de skills ficam em internal/skills; a policy fica em internal/policy; o staging genérico de artefatos externos fica em internal/supplychain.

Metadados e bodies de skills externas são dados não confiáveis. Eles não podem substituir o orquestrador IVOAI, conceder capabilities, alterar sandboxing nem modificar policy.

Claude Red — IVOAI-188

A revisão aprovada de SnailSploit/Claude-Red é 739512a8588b28ff3b554e669391c22508602878, licença MIT. A descoberta da árvore encontrou 79 arquivos; 51 têm frontmatter válido e foram preservados sem alteração, e 28 foram rejeitados por missing_frontmatter. O manifesto upstream lista 78 e omite offensive-netexec. Caminho, SHA-256 e motivo das rejeições ficam no catálogo e na inspeção, sem instalar seus corpos.

ivoai skills update claude-red
ivoai skills show claude-red
ivoai skills doctor claude-red
ivoai skills enable claude-red
ivoai skills disable claude-red
ivoai skills pin claude-red
ivoai skills unpin claude-red
ivoai skills rollback claude-red

Use Skills & Capabilities → Claude Red para instalar, inspecionar, habilitar/desabilitar, fixar ou reverter. Os comandos existentes ivoai skills list, show claude-red, doctor claude-red, update claude-red, enable claude-red, disable claude-red, pin claude-red, unpin claude-red e rollback claude-red usam o mesmo serviço. O contrato atual controla a fonte; a elegibilidade individual é decidida pelo Gate e pela política.

Somente claude-red-offensive-reporting é elegível por padrão, para organizar evidências fornecidas e sanitizadas em um worker consultivo. Das demais, 30 são de alto risco e 20 de risco crítico: a política bloqueia suas capacidades antes de carregar os documentos. Instalar ou habilitar não autoriza avaliação ativa. Não há concessão de shell, privilégios, rede ou exclusão de evidências. Avaliações ativas exigiriam escopo, autorização e aprovação explícita, além de isolamento; essa capacidade permanece indisponível na política atual.

ivoai codex e ivoai opencode --planner codex|claude selecionam por worker. O planner não fixa o executor de todos os workers. ivoai claude é direto; use ivoai opencode --planner claude para seleção do pacote nativo. Modos --direct excluem o pacote da injeção no primário por contrato. A sessão Claude legada session start --executor claude --mode orchestrated continua disponível, mas o fluxo gerenciado recomendado é OpenCode. Nenhuma instalação pessoal recebe cópias de Skills. Codex usa developer_instructions; Claude usa --append-system-prompt, mantendo as permissões dos adapters existentes. Contratos oficiais: Codex Skills e Claude Code Skills.

Exemplo: solicite um relatório de segurança autorizado sobre achados sintéticos fornecidos, sem ferramentas ou rede, incluindo escopo, limitações, remediação e reteste proposto. Não declarar execução de testes inexistentes.

Update usa apenas a revisão embutida aprovada, sem rede, com staging, SHA-256, promoção atômica e retenção anterior. Pin preserva a versão ativa. Rollback exige uma revisão anterior; na primeira instalação, desabilite a fonte se necessário. Desabilitar afeta seleções futuras, não revoga instruções já entregues. Checksum não equivale a assinatura independente. Doctor diagnostica integridade; inspeção mostra rejeições e bloqueios. Não edite os objetos imutáveis.

O smoke autenticado comprovou o uso de uma única Skill no Codex 0.162.1. Claude Code 2.1.222 foi bloqueado por OAuth expirado; o usuário confirmou ausência de acesso. A prova real Claude permanece pendente e a IVOAI-188 não está Done. Os testes usam fixtures sem alvos externos e ambientes temporários isolados.

Registry versionado

O registry privado é armazenado em:

$XDG_STATE_HOME/ivoai/skills/registry.json

O schema 1 do Registry registra IDs canônicos, descrições limitadas, revisões imutáveis do upstream, integridade SHA-256, estado de signature e attestation, versão lógica, default branch observada durante discovery, domains, triggers, dependências, conflitos, phases, roles, capabilities declaradas, risco, compatibilidade, lifecycle e timestamps não sensíveis de proveniência.

A identidade ativa é um commit imutável acompanhado de metadados de integridade. Uma tag ou default branch é evidência útil de discovery, mas não uma revisão ativa e reproduzível. A gravação do registry é determinística e atômica. Seu diretório e arquivo são 0700 e 0600; leituras no-follow rejeitam symlinks e leituras limitadas rejeitam estado oversized.

Um registry ausente é interpretado como registry vazio e saudável. Isso preserva a compatibilidade com v0.5.0 sem bump de schema de config, state ou ownership. O arquivo do registry é participante opcional explícito do snapshot transacional de update, para que futuras migrações do registry não fiquem invisíveis ao rollback.

Valores de lifecycle:

• staged
• active
• quarantined
• previous

Índice somente de metadados

O discovery percorre uma árvore privada de fontes com limites e sem seguir symlinks. Cada SKILL.md é aberto com O_NOFOLLOW, e a leitura para no delimitador final do frontmatter. O body não é carregado para identificar ou ranquear um candidato.

O indexador normal:

• não faz chamada a LLM;
• não executa hook, script, comando, bloco de código nem arquivo de setup;
• aceita apenas um subconjunto declarativo e limitado de frontmatter;
• ordena deterministicamente candidatos e relatórios de quarentena;
• aceita milhares de entradas sintéticas dentro do limite do registry.

Frontmatter malformed, UTF-8 inválido, schema incompatível, ID duplicado, divergência entre ID e path, symlink, traversal, metadados oversized, dependência ausente e self-dependency resultam em quarentena ou erro limitado de discovery. Metadados inválidos nunca recebem permissões padrão amplas.

O ranking retorna candidatos, não a seleção da sessão. Ele usa trigger exato, keyword, domain, termos limitados de nome/descrição, compatibilidade e risco máximo. Ordenação estável por score e ID torna o mesmo input reproduzível.

Grafo de dependências e conflitos

O resolver modela dependências obrigatórias e opcionais, conflitos declarados, compatibilidade de executor, disponibilidade de capabilities, tetos de risco, phases de execução e roles composable ou exclusive.

As phases são:

1. planning;
2. research/context;
3. art direction;
4. implementation;
5. audit/review;
6. security;
7. orchestration;
8. interaction/profile.

Dependências obrigatórias são incluídas e ordenadas topologicamente. Dependências opcionais restringem a ordem somente quando selecionadas. Candidatos duplicados são consolidados. Dependências ausentes, ciclos, roles mutuamente exclusive, conflitos explícitos, executores incompatíveis, capabilities indisponíveis e risco acima da policy produzem falhas tipadas e determinísticas.

Phases complementares podem ser compostas. Múltiplos visual directors ou autoridades de control plane concorrentes não podem. Uma skill externa pode declarar comportamento de orchestration como metadata, mas isso nunca transfere a autoridade de orchestration do IVOAI.

Policy Engine

A policy é avaliada acima de registries, skills, hooks, tool providers e executors:

IVOAI policy > external metadata or instructions

Os inputs são identidade/tipo do subject, capabilities declaradas, capabilities solicitadas, risco, scope, validade dos metadados e estado de conflito. As decisões são ALLOW, DENY e REQUIRE_APPROVAL.

Os tiers de risco são LOW, MODERATE, HIGH e CRITICAL. Uma capability read de baixo risco, declarada e disponível, pode ser permitida. Escritas de alto risco podem retornar uma exigência estruturada de aprovação para o futuro Approval Engine. Capabilities destrutivas, privilegiadas, que desabilitem sandbox, executem shell ou concedam autoridade de orchestration são negadas nestes fundamentos. Solicitações desconhecidas, indisponíveis, não declaradas, inválidas ou conflitantes falham de forma fechada.

O engine nunca recebe o body de uma skill como autoridade de policy. Texto como "ignore policy", "grant shell" ou "become orchestrator" não pode alterar uma decisão.

Supply chain unificada

O pipeline genérico aceita futuras skills, components e helpers:

discover source
  -> resolve immutable revision
  -> fetch bounded archive
  -> verify SHA-256
  -> isolated staging
  -> structural validation
  -> policy validation
  -> extracted-content manifest
  -> immutable object store
  -> atomic active pointer
  -> health and integrity validation
  -> transaction commit
  -> previous retention
  -> rollback

Adapters de download são separados do staging. Os testes usam archives sintéticos em memória; nenhum pack de skills real ou repositório externo é importado.

O staging aceita somente arquivos regulares e diretórios. Ele rejeita paths absolutos, .., ambiguidade de barra invertida, paths duplicados ou reservados, symlinks, hardlinks, arquivos especiais, executáveis inesperados, excesso de arquivos, excesso por arquivo, tamanho comprimido excessivo e tamanho expandido excessivo. Os modos são sanitizados para 0600/0700. Skills não podem declarar executáveis. Components podem declarar um path exato e limitado de executável, mas o staging nunca o executa.

Conteúdo validado é colocado em um path imutável de objeto identificado pelo ID e revisão do artefato. Um file manifest canônico vincula paths, modos, tamanhos e digests de arquivo à transação. A promoção primeiro autentica o journal de staging, substitui atomicamente um pequeno active pointer privado, executa o gate de health e integridade após promoção e então faz commit do journal. Qualquer falha restaura o pointer anterior. Promoção repetida é idempotente, rollback revalida o objeto anterior e pode ser repetido com segurança, e staging ou promoção interrompidos são recuperáveis sem tocar dados fora da raiz gerenciada.

Active pointers autoritativos da supply chain são enumerados como participantes transacionais explícitos do update. Objetos imutáveis e journals de staging ativos intencionalmente não são copiados cegamente para snapshots de update.

Integridade, signature, attestation e trust são campos distintos. Um checksum entregue pelo mesmo canal da GitHub Release prova integridade, não autenticidade independente. Registra-se not_exposed em vez de inventar uma signature.

Atualizações seguras de skill packs

internal/skillupdate combina o manager compartilhado da supply chain, Registry, classificador de metadata, dependency resolver, Policy Engine, smoke determinístico e callback do doctor em uma transação. Adapters de discovery resolvem dinamicamente a default branch upstream, mas toda identidade staged e active é um SHA de commit. Um adapter GitHub usa somente a API pública estruturada, faz fetch limitado do archive e registra o digest calculado localmente como commit_pinned_local_digest; esse valor deliberadamente não é chamado de signature ou attestation independente.

A promoção vincula o pointer da supply chain e a atualização do Registry. Falha de validação ou doctor restaura ambos. O rollback revalida o objeto imutável anterior e restaura as duas autoridades; a recuperação reconcilia transações interrompidas. Um update sem mudanças verifica consistência entre Registry e pointer em vez de obter sucesso silencioso. Discovery, staging, classificação, smoke e testes não executam hooks do repositório, installers, Makefiles, package lifecycle hooks, scripts ou binários.

Skill Gate de sessão gerenciada

Sessões diretas Codex/Claude preservam o Skill Gate pessoal. No AUTO, o pack nativo é selecionado por worker, depois do Prompt Gate e da aprovação do plano; não é injetado na sessão do primary. O gate local executa:

bounded session intent
  -> local Registry search
  -> metadata-only rank
  -> dependency/conflict resolution
  -> IVOAI Policy Engine
  -> select 0..N
  -> verify active pointer/provenance/content
  -> load only selected full documents
  -> bounded executor instruction

O gate não faz request de rede. Registry ausente ou vazio produz normalmente uma seleção de zero skills. Registry corrompido, policy inválida, objeto ativo ausente, divergência de pointer ou race de conteúdo não ativam skill externa e são observáveis como degraded; uma skill exigida explicitamente faz sua operação falhar. Decisões de policy usam somente metadata pertencente ao IVOAI. O conteúdo carregado depois da aprovação continua marcado como não confiável e não pode alterar capability, risco, policy ou autoridade de orchestration.

Overlay de upstreams curados

internal/skillcatalog/catalog.json registra 15 fontes: as 14 fontes nativas e o intake histórico de imagens, excluído do pack nativo. Ele mantém três camadas separadas:

1. nome e descrição fornecidos pelo upstream;
2. repositório, default branch, licença, commit e digest observados pelo IVOAI;
3. domain, triggers, phase, role, conflicts, risk, capabilities solicitadas e compatibilidade de executor pertencentes ao IVOAI.

A release embute bodies declarativos selecionados, referências e licenças, não executáveis upstream nem repositórios inteiros. Um classifier aceita apenas o commit revisado e o digest do arquivo selecionado. Atualizar um commit upstream exige, portanto, uma atualização revisada do catálogo antes da promoção automática. Packs de visual direction compartilham um role exclusive, para que o graph rejeite directors concorrentes. Ponytail permanece uma skill de implementation, i-have-adhd um interaction profile e entradas selecionadas de Superpowers/Caveman permanecem skills comuns. Packs com shell são negados por padrão e packs de segurança que usam tools exigem aprovação; nem o Codex Security ToolProvider nem a compressão Caveman são introduzidos aqui.

Revisões de repositório e observações de licença no catálogo são proveniência point-in-time, não afirmações de que um upstream permanecerá inalterado. Runtime discovery deve resolver novamente a default branch atual e a revisão imutável antes de uma atualização futura.

Diagnósticos e observabilidade

ivoai status informa o registry como ready/empty ou mostra contagens limitadas de lifecycle. ivoai doctor e sua forma JSON adicionam um objeto skill_control_plane com legibilidade/gravabilidade/schema do registry, contagens active/staged/quarantined, health da proveniência, prontidão da policy e health da raiz de staging da supply chain.

A allowlist de observabilidade existente aceita discovery do registry, ranking de candidatos, quarentena, resolução de conflitos, decisões de policy, resolução de source, staging, promoção e rollback. Eventos podem incluir IDs canônicos de skill e artefato, revisão imutável, risco, lifecycle, decisão, trust e motivos limitados. Eles não podem conter bodies de skills, prompts, scripts, conteúdo de README, arquivos externos brutos, credenciais, headers nem environments.

Trabalho adiado

Este bloco intencionalmente não:

• executa hooks de skills nem setup de terceiros;
• implementa a UX completa de aprovação;
• ativa entradas do catálogo antes de materialização local segura e policy;
• substitui Headroom, Ruflo, Context ou qualquer executor;
• implementa Codex Security ToolProvider ou Caveman CompressionProvider.

A análise de segurança e as fronteiras adversariais automatizadas estão documentadas em skill-control-plane-threat-model.md.