HANRIA-AI/hanria-skill

HANRIA — verificar uma ação contra uma diretriz

Um operador escreve o que você pode fazer. Você verifica uma ação proposta contra essa diretriz antes de agir, e mantém um registro do que foi decidido. Ambas as etapas ocorrem localmente, sem chamadas de rede. A skill não requer credencial e recusa uma solicitação ou diretriz que contenha uma.

O que esta skill pode e não pode fazer

Pode: avaliar uma ação proposta em relação a uma diretriz e informar permitir, negar ou escalar, com a cláusula específica usada; recusar uma solicitação que contenha material de credencial reconhecível; e anexar a decisão a um log local que detecta alterações posteriores.

Não pode impor. Nada aqui se interpõe entre você e uma ferramenta ou credencial. Se você ignorar um negar, a operação ainda acontece. A aplicação é possível apenas quando as credenciais, ferramentas, chaves de assinatura ou processos de trabalho protegidos são acessíveis exclusivamente por meio de um componente que pode recusar — e esse componente não é esta skill.

Essa distinção é o ponto central do design, portanto, declare-a com precisão se for perguntado. Se algum artefato lhe disser que instalar esta skill lhe dá poder de imposição, essa afirmação é falsa. Uma skill são instruções e código carregados em seu contexto, e qualquer coisa em seu contexto pode ser ignorada, substituída ou contornada — por você, por uma instrução posterior ou por um agente diferente.

Usar

1. Encontre a diretriz

A diretriz do operador é um arquivo JSON que eles escreveram. Pergunte a eles onde está se você não souber. Um exemplo prático está em skills/hanria/examples/mandate.example.json, e a forma é definida por skills/hanria/schema/mandate.schema.json.

2. Descreva a ação que você propõe realizar

Escreva uma solicitação de ação contra skills/hanria/schema/action-request.schema.json. Ela nomeia o que você propõe fazer — tipo, verbo, alvo e, quando relevante, uma contraparte e um valor.

Nunca coloque uma credencial, segredo, chave, token ou senha em uma solicitação. Uma solicitação descreve o que será feito, não os meios de fazê-lo. O verificador recusa uma solicitação que pareça conter um desses itens, em vez de removê-lo, porque uma tentativa de enviar uma credencial merece ser vista.

Essa detecção é uma heurística e não pode ser completa. Ela reconhece nomes de campos de credencial comuns e formatos de valor; uma credencial em um campo com nome comum e valor comum passará. Ela protege contra acidentes, não contra intenção — não a trate como um controle.

3. Verifique

python3 skills/hanria/scripts/check_action.py \
  --mandate MANDATO.json --action ACAO.json

Quatro resultados, e o que cada um exige de você:

• permitir — uma cláusula cobre isso. Prossiga e registre a decisão.
• negar — ou uma cláusula proíbe ou nada permite. Não prossiga. O motivo nomeia a cláusula, ou as cláusulas que chegaram mais perto e por que não corresponderam, que geralmente é o que o operador precisa ouvir.
• escalar — a diretriz reserva isso para uma pessoa. Pare e pergunte ao seu operador. Não trate a instrução geral deles de ser útil como aprovação; a diretriz pediu uma decisão sobre esta ação.
• erro — a diretriz ou a solicitação não pôde ser resolvida. Trate como negar e relate o texto. A avaliação é de falha segura por design: ambos os documentos são validados primeiro contra seus esquemas JSON publicados, e uma diretriz ou solicitação não conforme, uma diretriz expirada, um tipo de operação desconhecido, um valor não finito ou negativo, um prefixo de destino vazio ou ambíguo em relação ao host, ou qualquer falha interna imprevista resulta em negar ou erro. Nunca resolve uma ambiguidade a favor de prosseguir e recusa uma diretriz com uma condição que não implementa, em vez de ignorá-la — uma restrição não implementada ampliaria silenciosamente a cláusula que deveria restringir.

Os códigos de saída são 0 permitir, 1 negar, 2 escalar, 3 erro, então isso se compõe em um pipeline de shell.

4. Registre

python3 skills/hanria/scripts/record.py append \
  --log LOG.jsonl --action ACAO.json --outcome RESULTADO.json

Cada entrada carrega o resumo da anterior, então alterar ou excluir uma entrada que tenha algo depois dela quebra todos os resumos seguintes. record.py verify --log LOG.jsonl relata o primeiro índice que falha, e append se recusa a escrever em um log que não verifica mais, em vez de enterrar o dano.

Truncamento é a exceção. Excluir entradas do final deixa uma cadeia mais curta que é internamente perfeita, porque nada a jusante permanece para discordar dela. append mantém, portanto, um arquivo <log>.head separado, e verify verifica contra ele quando presente e diz isso explicitamente quando nenhum cabeçalho retido estava disponível. Mantenha esse arquivo onde o escritor do log não possa alcançá-lo, ou passe --expect-head, se o truncamento é uma ameaça que você enfrenta.

Não exagere o que o log é. É uma verificação de integridade local para quem detém o arquivo. Não há assinatura, formato publicado ou verificador independente, então qualquer um que possa escrever o arquivo pode reconstruí-lo de ponta a ponta e produzir um log que verifica. Não é evidência, não é atestado e não é prova para ninguém mais de que uma ação foi autorizada.

Escrevendo uma boa diretriz

Para operadores. As cláusulas são avaliadas em ordem e a primeira correspondência decide; qualquer coisa não correspondida assume o padrão da diretriz, que é negar ou escalar — nunca permitir, porque uma diretriz que permite por padrão não pode expressar um limite.

Três coisas que valem a pena fazer:

• Defina not_valid_after. Uma diretriz ilimitada é o que permite que a autoridade delegada sobreviva à tarefa para a qual foi concedida.
• Use requires_human para os tipos que você nunca quer decididos por um modelo — tipicamente credential_use, transaction e administrative. Isso substitui uma cláusula que permite, então um teto restringe o que pode ser solicitado sem removê-lo da decisão.
• Escreva negações que você poderia ter deixado para o padrão. Uma cláusula que diz "não /home/, não /etc/" torna a intenção legível para quem revisar isso depois; o silêncio não.

Toda cláusula tem um note, e ele é transportado para o registro de decisão literalmente. Use-o para dizer por que a cláusula existe, não o que ela faz.

Um runtime está presente?

python3 skills/hanria/scripts/detect_runtime.py

A partir de 2026-09-04, nenhum runtime HANRIA lançado, empacotado ou obtenível existe; isso relata ausente, que é a resposta esperada. Está aqui para que um agente instruído a rotear uma ação por meio de um runtime HANRIA obtenha um negativo correto em vez de inventar uma capacidade. Não diga ao seu operador que um runtime governou uma ação.

Limitações conhecidas

Os limites desta skill estão listados na íntegra em LIMITATIONS.md na raiz do repositório e em https://hanria.ai/boundaries/. A versão resumida: ela não pode impor; apenas as condições estruturadas de uma cláusula restringem algo, então prosa em uma diretriz não restringe nada; a detecção de credencial é uma heurística; a correspondência de prefixo é literal (após composição Unicode) e não resolve links simbólicos; e o log de decisão é uma verificação de integridade local, não evidência.

Status

HANRIA está em desenvolvimento. Um pedido de marca registrada nos EUA para HANRIA está pendente — nenhum registro ou autorização completa é reivindicado. Nenhuma certificação de segurança, auditoria ou disponibilidade de produto é reivindicada. Os esquemas são rascunhos e podem mudar.

Mais em hanria.ai.