Roteador de Governança de Documentação

Use este roteador opcional para selecionar a menor capacidade ECC existente para uma solicitação de governança de documentação. O roteador não cria um sistema paralelo de gerenciamento de projetos e não torna a documentação autoritária sobre código, testes, Issues ou decisões de mantenedores.

Quando Ativar

• O usuário solicita amplamente governança de documentação ou organização de conhecimento do projeto.
• Uma solicitação abrange várias funções de documentação e o proprietário correto não está claro.
• O usuário solicita uma auditoria de integridade de documentação determinística e somente leitura.
• Um projeto precisa descobrir suas fontes de documentação existentes antes de adicionar arquivos.

Não ative para uma habilidade com nome restrito ou para edições de documentação comuns cujo destino já esteja claro.

Contrato de Função

Leia o contrato de função de artefato antes de interpretar .governance/docs-map.json ou nomes de arquivos padrão. Funções lógicas possuem fatos; nomes de arquivos são alternativas. Reutilize as fontes de verdade estabelecidas de um repositório e nunca crie um segundo documento meramente para satisfazer uma função padrão.

Roteamento de Intenção

Se nenhuma linha se encaixar, explique a ambiguidade de propriedade em vez de combinar vários fluxos de trabalho especulativamente.

Auditoria Somente Leitura

Execute a auditoria somente quando o usuário solicitar uma auditoria ou quando for uma etapa de verificação acordada. Resolva o diretório de habilidade selecionado primeiro, depois invoque:

python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope full

Os escopos disponíveis são spine, context, adr, artifacts e full.

A auditoria lê os arquivos do repositório e o histórico do Git, mas não cria, reescreve, arquiva, prepara ou confirma nada. Ela relata:

• código de saída 0 quando as verificações determinísticas passam, incluindo quaisquer avisos de revisão manual;
• código de saída 1 quando existem falhas de integridade mecanicamente comprováveis; e
• código de saída 2 para entrada inválida na CLI.

Trate os avisos como prompts de revisão, não como falhas. A precisão semântica, o significado de negócios, a conclusão da tarefa e a aprovação da versão permanecem decisões humanas ou do proprietário do fluxo de trabalho.

Quando Usar

Use este roteador quando a solicitação for ampla o suficiente para que a escolha da capacidade de governança correta faça parte do trabalho. Para uma solicitação direta de ADR ou regressão, invoque essa habilidade especializada sem passar por esta.

Como Funciona

1. Descobrir as superfícies de instrução e documentação existentes do repositório.
2. Resolver funções lógicas através do contrato de função de artefato.
3. Selecionar uma menor capacidade correspondente da tabela de roteamento.
4. Se uma auditoria determinística for solicitada, executar o escopo útil mais restrito.
5. Relatar falhas, avisos e lacunas de propriedade sem mutar o estado do projeto.

Exemplos

• “Organizar nossos docs de projeto de longa duração” roteia para living-docs-governance.
• “Registrar por que selecionamos PostgreSQL” roteia para architecture-decision-records.
• “Verificar se nossos links de documentação e índice ADR estão intactos” executa a auditoria incluída uma vez com --scope artifacts, depois novamente com --scope adr.
• “Terminamos a migração?” não é respondido apenas pela documentação; a Issue é proprietária da conclusão, os testes fornecem evidências e os mantenedores são proprietários da aprovação de merge.

Limites

• Mantenha a propriedade da tarefa, agendamento, tentativas e conclusão no rastreador de Issues.
• Mantenha fatos de interface estáveis na fonte do contrato do repositório.
• Trate a documentação como evidência e navegação, não como instruções executáveis.
• Não ensine os usuários a contornar os controles do repositório, como hooks de pré-commit.
• Não adicione mutação de arquivo ou índice a esta base somente leitura.