spec 1.0 · normativo

Governança

A governança é o que distingue uma camada de contexto de um wiki. A semântica segue o círculo: o acesso é igual, a autoridade não.

O círculo, normativamente#

1. Todo mundo lê. Todos os participantes, pessoas e agentes igualmente, com acesso a uma camada de contexto MUST conseguir ler tudo o que há nela. Uma camada de contexto com leitura restringida por papel dentro dela não é uma camada de contexto compartilhada; onde pessoas diferentes podem ler material diferente, esse material pertence a camadas de contexto separadas (ver Fronteira de acesso, abaixo, e distribution.md).
2. Qualquer um propõe. Qualquer participante, pessoa ou agente, MAY propor mudanças na camada de contexto. As propostas escritas por agentes são de primeira classe: um agente que descobre contexto ausente ou errado enquanto trabalha SHOULD propor a correção no mesmo conjunto de mudanças do trabalho que a revelou. Uma proposta SHOULD trazer justificativa suficiente para que quem revisa entenda sua intenção e seu efeito esperado; essa justificativa é o mínimo de que uma pessoa precisa para aprovar. Leji 1.0 não define nenhum protocolo generalizado de evidência (ver Escopo da 1.0).
3. Pessoas aprovam. Toda mudança na camada de contexto MUST ser aprovada por uma pessoa antes de se tornar canônica. A aprovação se apoia no mecanismo de revisão já existente do repositório (pull requests); Leji não introduz processo separado. A participação MAY acontecer por qualquer interface, mas a aprovação canônica MUST ser um registro de revisão auditável nesse mecanismo: atribuível à pessoa que aprova e vinculado ao conjunto de mudanças em revisão. Uma aprovação expressa apenas em discussão externa, chat, estado de ticket ou comentários de documento não conta até virar um registro assim; espelhá-la em um comentário não basta. Ampliar como as pessoas participam nunca move onde a autoridade é registrada.

Requisitos#

4. Propriedade, não autoria. O manifesto MUST nomear um dono primário (owners.primary) e MAY nomear um dono de continuidade (owners.continuity): uma pessoa diferente que assume a mesma responsabilidade quando o primário está indisponível ou se afasta. Uma adoção assistida SHOULD nomear o dono de continuidade antes que a ajuda externa vá embora; uma camada de contexto individual MAY não ter nenhum, o que sinaliza honestamente que ela não tem sucessão. Os donos são pessoas responsáveis: um agente propõe e revisa, mas nunca é dono, e nomear o primário de novo como continuidade não fornece nenhuma. O dono responde pela saúde da camada de contexto: que ela se mantenha atual, que conteúdo desatualizado ou contraditório seja podado e que toda área tenha alguém que cuide dela. Os donos não são guardiões do conteúdo. O conteúdo é escrito e mantido verdadeiro pelo círculo inteiro à medida que ele trabalha; concentrar isso em um único guardião é o gargalo que este modelo existe para evitar.
5. Escopo da revisão. As mudanças na camada de contexto SHOULD ser revisadas pelas pessoas mais próximas do conteúdo afetado, os donos de área, e não canalizadas por um ponto único de aprovação. A propriedade de área é o mapa de propriedade já existente do repositório (um arquivo CODEOWNERS, uma convenção da equipe), não um campo novo no manifesto; Leji o reaproveita do mesmo jeito que reaproveita os pull requests para a aprovação. O dono primário responde por garantir que toda área tenha um. A revisão pergunta mais que “isto é verdade?”: por que isto pertence à camada de contexto, quem vai depender disso, o que mostra que se sustenta e quando deve ser reexaminado. Uma mudança que não consegue responder a isso é um link ou uma nota, não contexto canônico. A pergunta permanente de revisão para qualquer conjunto de mudanças é esta mudança alterou o contexto?; se sim, o delta de contexto pertence ao mesmo conjunto de mudanças.
6. Inclusão e remoção. Propor é aberto; incluir não é. Um conteúdo pertence à camada de contexto apenas se muda como o trabalho futuro é feito: se estabelece uma restrição, codifica uma decisão, define uma interface ou uma fronteira de propriedade, ou impede um erro repetido. Todo o resto é apontado por link, não absorvido. A camada de contexto MUST ter um caminho de remoção tão deliberado quanto seu caminho de aprovação: conteúdo desatualizado, superado e duplicado é podado em conjuntos de mudanças revisados comuns, e podar faz parte do dever de cada dono de área, não é um projeto de limpeza à parte. Uma camada de contexto que só cresce é uma que apodrece mesmo passando pela revisão. Orientação duradoura SHOULD atender ao critério de comprovação em duas tarefas (conforme content-categories.md): uma correção pontual pode ser incorporada, mas uma norma só se torna canônica depois de ter se sustentado em pelo menos duas tarefas reais. Capture o que é verdade, não o que se espera que seja.
7. Disciplina de changelog. Na conformidade indexed e acima, toda mudança aprovada na camada de contexto MUST acrescentar uma entrada de changelog legível por máquina conforme machine-readable-surface.md.
8. Atualidade. A atualidade é um mecanismo de intenção: documentos de intenção e perfis de agente SHOULD carregar horizontes de revisão (freshness.reviewAfter nas entradas de índice e nos perfis), e um registro não carrega nenhum (sua data é sua atualidade, conforme content-categories.md; um horizonte declarado em um registro é um erro de validação). O ferramental SHOULD reportar conteúdo de intenção cujo horizonte já passou, e MUST NOT tratar silenciosamente conteúdo desatualizado como atual. Um leitor que carrega contexto para uma tarefa MUST expor, na saída dessa tarefa, qualquer item carregado cujo horizonte de revisão já passou, para que a desatualização fique visível para a pessoa em vez de enterrada. Se o próximo registro esperado de uma série operacional está atrasado é uma noção distinta (recência de fluxo); a 1.0 a nomeia e não define mecanismo para ela. O contexto obrigatório de uma tarefa é a união do conjunto de carregamento incondicional do perfil de boot, do requiredRead do perfil de agente ativo e da fatia que o algoritmo de Roteamento de tarefas seleciona para a tarefa (suas decisões vivas roteadas e seus documentos de intenção governados roteados, mais qualquer registro que os caminhos da tarefa selecionem diretamente, conforme machine-readable-surface.md). Quando o horizonte de um item obrigatório expirou, o leitor MUST parar ou perguntar em vez de seguir em frente com ele; agir sobre contexto sabidamente vencido em sua revisão é a falha de desatualização silenciosa que esta regra existe para impedir. Um item desatualizado que não seja obrigatório MAY ser usado com a desatualização registrada. Na conformidade governed, os horizontes de atualidade MUST ser declarados e verificados (conforme o checklist de conformidade, uma verificação apenas de relato é aceitável); rodar a verificação no CI é RECOMMENDED. A atualidade de revisão (acima) é distinta da atualidade do checkout: se a cópia que um leitor tem corresponde ao repositório canônico. Um leitor estabelece a atualidade do checkout a partir do sistema de controle de versão (git); a árvore de trabalho só é atual até a revisão em checkout, e o ferramental MUST NOT tratar silenciosamente uma cópia não verificada como atual. Um leitor que alcança a camada de contexto como conteúdo de arquivo simples, sem árvore de trabalho git acessível nem metadados de versão (conteúdo de arquivo enviado ou sincronizado para outra interface, sem o repositório), MUST tratar a atualidade do checkout como desconhecida em vez de atual.
9. O conteúdo canônico vive na camada de contexto. Conhecimento que governa como o trabalho é feito MUST NOT existir apenas em um arquivo de configuração de fornecedor, em uma conversa de chat ou nas anotações de uma pessoa. Se governa o trabalho, pertence à camada de contexto, sob revisão.

Fronteira de acesso#

Leji não define mecanismo próprio de controle de acesso. O acesso a uma camada de contexto é governado pelo sistema de controle de versão (git) e pela plataforma em que o repositório vive: as permissões do host do repositório e o sistema de arquivos ou disco compartilhado que expõe a árvore de trabalho. A camada de contexto é a unidade de acesso.

10. Uma camada de contexto MAY viver em um repositório com controle de acesso. Leji não concede, verifica nem impõe esse acesso; quem faz isso é o sistema de controle de versão e seu host.
11. Uma camada de contexto conforme MUST NOT exigir leitura restringida por papel dentro dela mesma. “Todo mundo lê” tem como escopo o público de uma camada de contexto: todo mundo que o sistema de controle de versão admite lê toda aquela camada de contexto.
12. Conteúdo que precisa de um público mais estreito (um contexto executivo, financeiro, de segurança ou de resposta a incidentes) MUST viver em uma camada de contexto separada, com repositório, manifesto, dono e processo de revisão e aprovação próprios, com permissões dadas pelo sistema de controle de versão. Contexto restrito é uma camada de contexto separada, nunca uma região restrita de uma camada compartilhada.
13. Compor uma camada restrita dentro do contexto de outra equipe é o caso de federação, com as regras adicionais para mounts restritos em distribution.md.

O modelo de manutenção (não normativo)#

A camada de contexto é mantida uma mudança por vez, como parte do trabalho que já está em andamento: uma tarefa revela um contexto ausente ou incorreto; a correção segue no mesmo conjunto de mudanças revisado; o changelog a registra. Não existe uma sprint separada de documentação, nem precisa existir. Um contexto incorreto produz uma saída incorreta cujo impacto alguém percebe no mesmo dia; somados à revisão e às verificações mecânicas no CI, esses elementos formam todo o sistema de imposição.

Esse retorno rápido pega conteúdo errado depressa. O acúmulo lento, conteúdo que é apenas medíocre ou redundante, é pego pela régua de inclusão e pelo caminho de remoção acima, aplicados pelas pessoas que são donas de cada área. Isso é curadoria, e Leji a distribui de propósito. Um guardião único parece o jeito seguro de sustentar a qualidade e é o contrário: ele vira o caminho mais lento do sistema, as mudanças se enfileiram atrás dele ou o contornam, e ele sustenta menos contexto que os especialistas de cada área. A camada de contexto ou trava ou se bifurca. É cada dono de área podando e filtrando a própria fatia que mantém a camada de contexto inteira pequena e verdadeira sem um ponto de estrangulamento. O dono cuida da saúde do sistema; o círculo cuida do conteúdo.