Convenções de harness multissuperfície

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

1. Por que no pluralCopy Anchor Link

Uma superfície de engenharia moderna é tocada por vários harnesses — consoles de chat, mecanismos de autocompletar dentro do IDE, companheiros de programação em par e revisores de pull requests. Cada um lê o seu próprio arquivo de configuração canônico. Se o projeto distribui apenas um desses arquivos, os runtimes restantes improvisam silenciosamente com base em convenções não declaradas; a ausência de memória dentro do repositório vaza de imediato.

O custo de uma superfície ausente é o desvio silencioso no código gerado por máquina — a pior classe 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 dos runtimes de harness é plural pela realidade da implantação. O ecossistema publicado DEVE distribuir as três superfícies obrigatórias da §3: AGENTS.md, um arquivo de memória comportamental para o runtime de console de chat (CLAUDE.md) e um arquivo de instruções com escopo de repositório para o runtime de autocompletar dentro do IDE. As superfícies DEVEM ser mutuamente coerentes — sem contradição, sem desvio — e DEVEM codificar em conjunto as mesmas disciplinas.

2. O contrato de coerênciaCopy Anchor Link

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

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

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

As superfícies são canais diferentes que expressam uma única especificação. As seções compartilhadas DEVEM coincidir — semanticamente e, sempre que possível, lexicalmente — entre as superfícies. As seções específicas da superfície NÃO DEVEM contradizer as seções compartilhadas.

3. Superfícies no escopoCopy Anchor Link

Para este repositório, as superfícies de adesão opcional são as que a fixture da lista de afirmações (tests/fixtures/multi-surface-claims.yaml) relaciona em optional-in. Configurações raiz não utilizadas e específicas de fornecedor estão ausentes de propósito; um arquivo de configuração específico de uma ferramenta só é adicionado quando essa ferramenta é uma superfície de edição ativa neste repositório.

4. Lista de seções do arquivo de instruções dentro do IDECopy Anchor Link

O arquivo de instruções com escopo de repositório sob .github/ DEVE conter, nesta ordem, as seções a seguir (cada uma com o texto de cabeçalho exato abaixo; os corpos das seções são redigidos, não carimbados a partir de um 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 em nível superior. Concreto; sem marketing.
2. Coding Conventions — nomenclatura, hierarquia modal, frontmatter, estilo de 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 correspondente ao tipo de arquivo. Referência a scripts/inject-header.* e a site/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — o runtime NÃO DEVE gerar código nem scripts que gravem em um diretório de configuração de harness (por exemplo ~/.claude/plans/ ou ~/.codex/.plans/) nem em qualquer outro local global de planos. Os artefatos de planejamento vão para <project-root>/.apothem/plans/ (uma árvore legada <project-root>/.plans/ é atualizada via apothem migrate-workspace) conforme site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — quando o runtime estiver em dúvida, ele NÃO DEVE fabricar silenciosamente. Em vez disso, insere um bloco de esclarecimento claramente marcado (por exemplo, um comentário # TODO(clarify): <question>) e apresenta a pergunta no chat quando a superfície permitir. Nada de APIs inventadas, nomes de modelo inventados ou caminhos de arquivo inventados.
6. Forbidden Patterns — proibições explícitas: nada de adjetivos de marketing, nada de enchimento evasivo, nada de resíduos de depuração com console.log, nada de caminhos absolutos fixos para o diretório home do usuário, nada de commitar segredos, nada de commitar arquivos sob .apothem/plans/ (ou o legado .plans/), nada de contradizer o arquivo canônico de instruções do projeto.
7. Output Format — o código/a prosa gerados seguem as convenções unificadas de saída conversacional: assertividade, seccionamento uniforme, densidade, disciplina de resumo, citações. Para código: superfície pública documentada, tipado onde a linguagem suporta tipos, testado onde existe uma estrutura 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 em conformidade, nenhuma gravação em .apothem/plans/, nenhuma contradição 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, src/apothem/schemas/ e CONTRIBUTING.md.

O arquivo começa com a linha SPDX canônica do cabeçalho de autoria (variante Markdown) conforme site/content/docs/reference/authorship-header.mdx §2 — visível ou invisível conforme a política de visibilidade de cabeçalho 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 é redigido 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çõesCopy Anchor Link

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 SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  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 localizar a presença de cada afirmação na superfície (pela 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çãoCopy Anchor Link

Quando duas superfícies são detectadas em contradição sobre uma afirmação compartilhada, a reconciliação padrão é:

AGENTS.md é a voz canônica do projeto. Qualquer superfície em contradição é reescrita para espelhar a semântica de AGENTS.md com um enquadramento adequado à superfície.

Uma substituição específica da superfície só é permitida com um marcador explícito, dentro do arquivo, <!-- coherence-override: <claim-id> -->, que aponte para um ADR que explique a divergência deliberada. O próprio marcador de substituição é enumerado na lista de permissões 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 todo espelho de harness ativo permanece semanticamente equivalente.

7. ValidadoresCopy Anchor Link

Três validadores implementam em conjunto 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 verifica se o arquivo de instruções dentro do IDE existe, é analisado sem erros, contém todas as seções canônicas enumeradas na §4 e começa com a linha canônica SPDX-License-Identifier: MIT (variante Markdown).
• O segundo analisa as seções canônicas de cada superfície; verifica se as seções compartilhadas são mutuamente consistentes sob um comparador normalizado (sem distinção entre maiúsculas e minúsculas, tolerante a espaços em branco, que permite paráfrase lexical mas exige equivalência semântica na lista de afirmações definida pela fixture).
• O terceiro verifica apenas se o LICENSE da raiz traz uma linha Copyright (c) <name> analisável. Ele não lê os cabeçalhos por arquivo, que não carregam nome de autor.

8. Ciclo de vida das superfíciesCopy Anchor Link

• Adicionar uma superfície. O operador adere pelo canal de indagação estruturada. O gerador redige a superfície com base na lista de afirmações, executa o validador e registra um ADR se for necessária uma substituição específica da superfície.
• Remover uma superfície. A indagação estruturada confirma a remoção, um ADR registra a justificativa, e a lista required-in do validador é alterada.
• Detecção de desvio. Qualquer commit que divirja 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émCopy Anchor Link

• 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 para o 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.