Convenções de ferramenta multi-superfície

Referência normativa canônica para colaboradores posteriores. Este documento espelha as seções de Convenções de ferramenta multi-superfície da especificação do projeto (Especificação §0.6 + §2.8 + §4.7); é a referência independente que acompanha o repositório publicado. A justificativa arquitetural está registrada em ADR-0003.

1. Por que no plural

Uma superfície de engenharia moderna é tocada por múltiplos runtimes de harness — consoles de chat, motores de autocompletar dentro do IDE, companheiros de programação em par e revisores de pull requests. Cada um lê seu próprio arquivo de configuração canônico. Se o projeto entrega apenas um desses arquivos, os runtimes restantes improvisam em silêncio contra convenções não declaradas; a memória interna do repositório que falta vaza de imediato.

O custo de uma superfície ausente é a deriva silenciosa no código gerado por máquina — o pior tipo de defeito, porque se acumula de forma invisível. Cada artefato gerado por máquina agrava a divergência; quando um revisor humano percebe a contradição, a base de código já carrega semanas de convenções inconsistentes.

A configuração do runtime de programação é plural pela realidade da implantação. O ecossistema publicado DEVE entregar um arquivo de memória de comportamento para o runtime do console de chat E um arquivo de instruções com escopo de repositório para o runtime de autocompletar dentro do IDE. As duas superfícies DEVEM ser mutuamente coerentes — sem contradição, sem deriva — e DEVEM codificar em conjunto as mesmas disciplinas.

2. O contrato de coerência

Cada superfície de convenções em escopo (§3) é um canal que expressa a especificação única de convenções do projeto. A especificação é decomposta em:

• Seções compartilhadas — Disciplina de planos, indagação estruturada (ou equivalente na superfície), Cabeçalho de autoria, Nomenclatura, Antipadrões, Hierarquia modal. Estas DEVEM aparecer em cada superfície obrigatória e DEVEM ser semanticamente equivalentes em todas as superfícies.
• Seções específicas da superfície — enquadramentos de capacidade, padrões de chamada de ferramentas, diferenças entre geração de código e chat. Estas PODEM diferir entre superfícies, mas NÃO DEVEM contradizer as seções compartilhadas.

O validador multi-surface-coherence (§7) é executado em cada execução de CI e no pre-commit, afirmando o contrato.

As duas (ou mais) superfícies são canais distintos que expressam uma única especificação. As seções compartilhadas DEVEM coincidir — semanticamente e, onde possível, também lexicalmente — em todas as superfícies. As seções específicas da superfície NÃO DEVEM contradizer as seções compartilhadas.

3. Superfícies em escopo

Para este trabalho, o operador optou pelas superfícies de assistente opcionais registradas pela fixture. As configurações raiz específicas de fornecedor não utilizadas estão ausentes de forma intencional; um arquivo de configuração específico de uma ferramenta é adicionado somente quando essa ferramenta é uma superfície de edição ativa para este repositório.

4. Lista de seções para o arquivo de instruções dentro do IDE

O arquivo de instruções com escopo de repositório sob .github/ DEVE conter, nesta ordem, as seguintes seções (cada uma com o texto de cabeçalho exato abaixo; os corpos das seções são redigidos, não estampados por template, mas cada um DEVE cobrir as afirmações listadas):

1. Project Context — um parágrafo: o que é este repositório, quem o usa, sua forma de nível superior. Concreto; sem marketing.
2. Coding Conventions — nomenclatura, hierarquia modal, frontmatter, estilo markdown, pontos de estilo específicos da linguagem onde divergem dos padrões.

3. File Headers — todo arquivo que o runtime gera DEVE começar com a linha canônica única SPDX-License-Identifier: MIT conforme site/content/docs/reference/authorship-header.mdx, na variante de comentário que corresponda ao tipo de arquivo. Apontador para scripts/inject-header.* e site/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — o runtime NÃO DEVE gerar código ou scripts que escrevam em um diretório de configuração da ferramenta (por exemplo ~/.claude/plans/ ou ~/.codex/.plans/) nem em qualquer outra localização global de planos. Os artefatos de planejamento vão para <project-root>/.apothem/plans/ (uma árvore <project-root>/.plans/ legada é atualizada via apothem migrate-workspace) conforme site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — quando o runtime estiver incerto, ele NÃO DEVE fabricar em silêncio. Em vez disso, insere um bloco de esclarecimento claramente marcado (por exemplo, um comentário # TODO(clarify): <question>) e levanta a pergunta no chat onde a superfície permitir. Sem APIs inventadas, sem nomes de modelo inventados, sem caminhos de arquivo inventados.
6. Forbidden Patterns — proibições explícitas: sem adjetivos de marketing, sem enchimento evasivo, sem detritos de depuração com console.log, sem caminhos absolutos codificados para o home do usuário, sem commitar segredos, sem commitar arquivos sob .apothem/plans/ (ou o legado .plans/), sem contradizer o arquivo canônico de instruções do projeto.
7. Output Format — o código/prosa gerado segue as convenções unificadas de saída conversacional: definitividade, seccionamento uniforme, densidade, disciplina de resumo, citações. Para o código: superfície pública documentada, tipada onde a linguagem suportar tipos, testada onde existir um andaime de testes.
8. Review Checklist — o que um revisor (humano ou runtime em modo de revisão de PR) DEVE verificar antes de aprovar: cabeçalho presente, nomenclatura conforme, sem escritas em .apothem/plans/, sem contradições com o arquivo canônico de instruções do projeto, validadores em verde localmente.
9. Pointers — links para AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, este documento de convenções, schemas/ e CONTRIBUTING.md.

O arquivo começa com a linha SPDX do cabeçalho de autoria canônico (variante Markdown) conforme site/content/docs/reference/authorship-header.mdx §2 — visível ou invisível conforme a política de visibilidade de cabeçalhos escolhida pelo projeto.

O arquivo de instruções dentro do IDE não é uma cópia literal de AGENTS.md nem de CLAUDE.md. AGENTS.md é a superfície canônica de instruções do projeto, CLAUDE.md a espelha para o Claude Code, e o arquivo de instruções dentro do IDE é vocalizado para um runtime de autocompletar de código no editor que emite sugestões que um desenvolvedor aceita ou rejeita. A informação (disciplinas, convenções, antipadrões) é idêntica; o enquadramento difere.

5. Referência da lista de afirmações

A fixture em tests/fixtures/multi-surface-claims.yaml enumera cada afirmação compartilhada. Entradas de exemplo:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical authorship-header banner per site/content/docs/reference/authorship-header.mdx."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

O validador analisa cada superfície, tenta encontrar a presença de cada afirmação na superfície (via hierarquia de cabeçalhos + extração de palavras-chave do corpo) e falha diante de qualquer ausência ou contradição.

6. Regra de reconciliação

Quando duas superfícies são detectadas como contraditórias em uma afirmação compartilhada, a reconciliação padrão é:

AGENTS.md é a voz canônica do projeto. Qualquer superfície contraditória é reescrita para espelhar a semântica de AGENTS.md em um enquadramento apropriado à superfície.

Uma sobrescrita específica da superfície só é permitida com um marcador explícito e interno ao arquivo <!-- coherence-override: <claim-id> --> que aponte para um ADR explicando a divergência deliberada. O marcador de sobrescrita é ele mesmo enumerado na lista de permitidos do validador e aparece no relatório de CI.

Para este repositório, a estratégia de reconciliação ratificada é agents-md-wins: AGENTS.md é canônico, e cada espelho de ferramenta ativa permanece semanticamente equivalente.

7. Validadores

Três validadores coimplementam o contrato de coerência:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• O primeiro afirma que o arquivo de instruções dentro do IDE existe, é analisado, contém cada seção canônica enumerada em §4 e começa com o banner de autoria canônico.
• O segundo analisa as seções canônicas de cada superfície; afirma que as seções compartilhadas são mutuamente consistentes sob um comparador normalizado (insensível a maiúsculas/minúsculas, tolerante a espaços em branco, permite paráfrase lexical mas exige equivalência semântica na lista de afirmações definida pela fixture).
• O terceiro afirma que a linha de copyright do LICENSE e a linha "Copyright (c)" do banner canônico nomeiam o mesmo autor.

8. Ciclo de vida da superfície

• Adicionar uma superfície. O operador opta por ela via canal de indagação estruturada ou via um posterior make surfaces-add <name>. O gerador redige a superfície contra a lista de afirmações, executa o validador e arquiva um ADR se for necessária uma sobrescrita específica da superfície.
• Remover uma superfície. A indagação estruturada confirma a remoção, um ADR registra a justificativa, a lista required-in do validador é alterada.
• Detecção de deriva. Qualquer commit que se desvie da lista de afirmações é rejeitado pelo pre-commit / CI; o autor do commit reescreve a superfície para restaurar a coerência.

Veja também

• ADR-0003 — justificativa arquitetural, alternativas consideradas.
• tests/fixtures/multi-surface-claims.yaml — a fixture canônica da lista de afirmações.
• AGENTS.md — a voz canônica do projeto.
• CLAUDE.md — o espelho do Claude Code.
• site/content/docs/reference/plans-discipline.mdx — a referência canônica da afirmação compartilhada Disciplina de planos.
• site/content/docs/reference/authorship-header.mdx — a referência canônica da afirmação compartilhada Cabeçalho de autoria.
• Especificação do projeto §0.6 + §2.8 + §4.7 — o texto canônico completo espelhado aqui.