spec 1.0 · normativo

A Camada de Contexto

Uma camada de contexto Leji é um conjunto versionado e governado de documentos legíveis por humanos que registra como uma equipe pensa sobre o próprio trabalho: linguagem do domínio, invariantes do sistema, convenções, travas de proteção e registros de decisão. Pessoas e agentes a consultam durante o trabalho e propõem mudanças pelo mesmo processo de revisão e aprovação. Ela fica sob controle de versão para que o histórico, a atualidade e a aprovação continuem verificáveis; a mecânica está em Requisitos, abaixo, e as formas de participação estão em Participação.

Participação#

A participação em uma camada de contexto é definida pelo papel, não pela ferramenta. A leitura, a proposta, a revisão e a aprovação podem acontecer em qualquer interface que preserve a semântica de revisão e aprovação do repositório; não é preciso conhecer git ou linha de comando diretamente para participar.

Todo mundo com acesso lê. Acesso significa acesso prático pelas ferramentas normais da equipe, não acesso a shell no repositório.
Qualquer um propõe; pessoas aprovam. Uma proposta é um pedido intencional de mudança na camada de contexto. Ela MAY ser escrita diretamente por uma pessoa, gerada por um agente a partir do pedido de uma pessoa, ou gerada por um agente a partir do trabalho observado. Na prática, os agentes redigem a maior parte das mudanças de contexto; a contribuição humana irredutível é a governança: propor a intenção e aprovar o que se torna canônico. A pessoa que aprova uma mudança responde pelo significado e pela consequência dela, não por operar pessoalmente o sistema de controle de versão.
Significado humano, superfície legível por máquina. Os documentos legíveis por humanos são a fonte normativa do contexto operacional de uma equipe. Os arquivos legíveis por máquina (manifesto, índice, changelog) existem para que as ferramentas possam localizar, indexar, validar e sincronizar esse significado; eles nunca o substituem.

A forma normativa desses fluxos, o círculo (todo mundo lê, qualquer um propõe, pessoas aprovam), está definida em governance.md.

Lendo um registro#

O conteúdo governado vem em dois tipos, definidos em content-categories.md: intenção, mantida como verdade presente, e registros, evidência datada que o estado posterior supera em vez de corrigir. Ambos são igualmente governados; o que difere é o que um leitor pode fazer com o que carregou. Um leitor MUST NOT tratar um registro como intenção atual: um registro informa com o peso de evidência verdadeira dentro do limite que declara, e um leitor que apresenta as afirmações de um registro como o estado presente das coisas, sem dizê-lo, está fabricando uma atualidade que o documento não tem. Isso espelha a regra do modo degradado, abaixo: nos dois casos, a obrigação do leitor é saber, e dizer, que tipo de atualidade está segurando.

Requisitos#

A camada de contexto MUST viver em um repositório git e MUST ser versionada junto com o trabalho que descreve (o mesmo repositório, ou um repositório de contexto dedicado consumido conforme distribution.md). O repositório git é o que torna verificáveis o histórico da camada de contexto, a atualidade do checkout e a integridade somente acréscimo do changelog; o ferramental conforme deriva os três dele. Ler a camada de contexto sem esse repositório é um modo suportado, porém degradado, definido em Modos de leitura.
Um repositório que adota Leji MUST ter um arquivo de manifesto, leji.json, na raiz do repositório, válido segundo context-manifest.schema.json. O manifesto é o ponto de entrada da máquina: ele declara a versão da especificação (a chave autonomeadora leji), o nome da camada de contexto, a raiz do contexto, o caminho do perfil de boot, os mapeamentos de categoria, uma declaração opcional de conformidade e a propriedade. Ele MAY carregar também um mapa agents que liga identificadores de papel (por exemplo thought-partner, reviewer) a documentos de perfil de agente: os protocolos engajam papéis; o mapa decide quem os preenche. O mapa é um diretório de papéis, não uma ordem de carregamento: uma ligação, inclusive uma na chave default, nunca faz um perfil ser lido; só a seção Carregamento do perfil de boot faz isso.
O manifesto MAY declarar atores: participantes nomeados que podem preencher papéis. Cada ator declara os papéis para os quais é elegível e um modelo de comando por papel. Chavear o comando pelo papel é justamente o ponto: um mesmo ator pode exigir uma invocação diferente conforme o papel que está preenchendo, então um único comando por ator não daria conta de expressar isso. Os papéis declarados de um ator e as chaves de seus comandos MUST ser o mesmo conjunto. Onde um papel tem atores, o perfil de agente a ele ligado MUST NOT declarar também invocation: dois comandos autoritativos sem precedência declarada são uma contradição, e a camada a resolve declarando o comando em um único lugar. Atores são opcionais e a maioria das camadas não precisa de nenhum. Eles se justificam quando um papel tem mais de um ator elegível, ou quando um ator precisa de uma invocação diferente conforme o papel que preenche; qualquer um dos dois já basta, e um papel cujo único ator precisa de um só comando é bem servido pelo host e pelo invocation do próprio perfil. Declarar um ator não concede autoridade nenhuma: diz quem pode ser chamado a preencher um papel, nunca quem pode aprovar.

Modelos de comando, onde quer que apareçam (os valores de commands de um ator e o invocation.command de um perfil de agente), seguem uma única regra. Um modelo é uma linha de comando para o shell que o invocador escolher; um engajamento que não tenha formato de shell (uma chamada estruturada de argv, um spawn dentro do processo) não é representável por esses campos na linha 1.0. Todo modelo MUST conter o marcador <prompt>, e cada ocorrência MUST figurar como uma palavra de shell própria e sem aspas, em posição de argumento, nunca dentro de aspas nem colada a outro texto. A substituição é de passada única: as ocorrências presentes no modelo escrito são substituídas simultaneamente, exatamente uma vez, de modo que a string literal <prompt> dentro do texto do prompt permaneça dado e nunca seja reexpandida. A entrega pertence ao invocador, e o contrato é o resultado exigido, não o algoritmo de aspas: cada ocorrência produz exatamente um argumento cujo valor é igual ao texto do prompt, sem que nada dele seja avaliado como sintaxe de shell. O que os schemas verificam é a presença de um ponto de substituição; posicionamento e entrega cabem a esta regra exigir e ao invocador honrar.
O manifesto MUST declarar uma raiz do contexto (rootPath). O padrão RECOMMENDED é docs/. Todos os caminhos da camada de contexto são no estilo POSIX, relativos à raiz do repositório. rootPath declara onde a camada de contexto vive; ele não rebaseia os caminhos que governa: as entradas do índice, as páginas fixadas, os caminhos dos perfis e todo outro caminho em todo artefato Leji resolvem a partir da raiz do repositório, inclusive os que repetem o prefixo de rootPath. O homepage, o logo e o favicon do visualizador são a exceção: eles são escritos relativos à raiz do contexto, e um caminho relativo à raiz do repositório que fique sob ela também é aceito. Os caminhos de categoria e de machine SHOULD ficar sob rootPath; os validadores avisam quando não ficam.
A camada de contexto MUST ter um perfil de boot conforme boot-profile.md. O local padrão RECOMMENDED é docs/boot-profile.md; o bootProfilePath do manifesto declara o local efetivo.
O conteúdo da camada de contexto MUST ser legível por humanos antes de tudo. Markdown é o formato RECOMMENDED para prosa; metadados estruturados usam frontmatter YAML ou os artefatos JSON definidos em machine-readable-surface.md. Um documento que só uma máquina consegue ler não pertence à camada de contexto.
A camada de contexto MUST ter um dono nomeado (owners.primary no manifesto): uma pessoa responsável pela atualidade dela. Camadas de contexto sem dono apodrecem.

Modos de leitura: canônico e degradado#

Uma camada de contexto é lida em dois modos; um leitor MUST saber em qual modo está, porque as garantias são diferentes. Um leitor determina seu modo a partir do que consegue resolver: é canônico quando há um leji.json alcançável na raiz do repositório e, além dele, pelo menos um entre uma árvore de trabalho git e a identidade de revisão do repositório na plataforma hospedeira; conteúdo alcançado como arquivos simples sem nenhum dos dois é degradado.

Canônico. O leitor resolve a camada de contexto através do seu repositório git: um checkout, ou a visão do repositório na plataforma hospedeira. Histórico, atualidade do checkout e integridade do changelog são verificáveis, e o conteúdo aprovado é sabidamente atual até a revisão lida.
Degradado. O leitor alcança a camada de contexto como conteúdo de arquivo simples, sem árvore de trabalho git acessível nem metadados de versão: arquivos enviados, sincronizados ou copiados para outra interface sem o repositório. A leitura de arquivos simples é de primeira classe para leitura (os documentos são legíveis por humanos por exigência, e o changelog legível por máquina ainda transmite a recência declarada), mas um leitor em modo degradado MUST tratar a atualidade do checkout e o estado de aprovação como desconhecidos, nunca como atuais (ver governance.md, Atualidade). O changelog é a superfície portátil de recência declarada nesse modo; ele não estabelece, por si só, que a cópia corresponde ao repositório canônico.

A leitura degradada amplia quem e o que pode consumir uma camada de contexto; ela nunca é um caminho para a autoridade canônica. Uma mudança só se torna canônica através do processo de revisão e aprovação apoiado em git, e uma cópia degradada não consegue satisfazer as verificações de modo canônico das quais a federação depende (atualidade do pin, estado de pin desatualizado, integridade da propriedade e acesso a mount restrito, conforme distribution.md).

A regra do adaptador de fornecedor#

Arquivos de configuração de host de agente (por exemplo CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .cursor/rules, .windsurfrules, .github/copilot-instructions.md):

MUST NOT guardar conteúdo canônico da camada de contexto.
Se presentes, MUST redirecionar para o perfil de boot (tipicamente um ponteiro de uma linha).
MAY carregar mecânicas específicas do host que não têm significado fora daquele host de agente (escolha de modelo, configurações do executor), desde que nenhum conhecimento da equipe viva ali.
O ferramental descobre quais pontos de entrada verificar a partir de duas fontes: a lista opcional vendorAdapters do manifesto e um conjunto conhecido e publicado (os arquivos nomeados acima). A lista de exemplo acima é esse conjunto conhecido para esta linha; um host cujo ponto de entrada não esteja nela só é verificado quando o manifesto o nomeia em vendorAdapters.

As convenções de ponto de entrada que existem dizem a um host de agente onde olhar; Leji define o que o agente encontra ali. Uma única fonte de verdade, com todos os participantes lendo dela.

O que a camada de contexto não é (não normativo)#

Não é um wiki. Nada obriga um wiki a se manter atual. A camada de contexto continua viva porque os agentes a leem a cada tarefa (contexto errado produz saída errada, e isso se sente na hora), as mudanças passam pela revisão como o código, e o ferramental torna a desatualização visível.
Não é documentação no sentido tradicional. A documentação descreve o que o sistema faz, depois do fato. A camada de contexto descreve como a equipe pensa, no presente, e é lida o tempo todo por pessoas e agentes.
Não é um template para importar. Contexto emprestado fica desatualizado de imediato. O valor de uma camada de contexto é ser a representação da própria equipe; Leji padroniza o formato e a governança, não o conteúdo.