A fronteira META vs CHILD

A ideia mais importante de todas no ai-core-kit é que ele vive em duas camadas que nunca devem ser confundidas. Acerte essa fronteira e todo o resto — idempotência, higiene de template, o contract gate, telemetry — se encaixa. Erre-a e você vaza ferramental meta-only para projetos child ou tenta aplicar regras de child ao próprio kit.

As duas camadas

META = construir a máquina que estampa o padrão. CHILD = o que a máquina estampa.

Design-contract-first, API-first e o contract gate são regras da camada CHILD. Eles são autorados aqui como templates e hooks que embarcam no child — eles não governam como o próprio meta-repo é construído.

Por que o repo META parece “incompleto”

Como contract-first é uma regra de child, o repo META deliberadamente:

• não carrega nenhum project.manifest.yaml e nenhuma instância de contrato (esses são artefatos de child produzidos pela entrevista); e
• não conecta nenhum hook de contract-gate próprio (ele passaria vaziamente — não há manifesto de child para ele ler).

Isso é intencional, não uma lacuna. O payload de contrato vive apenas sob templates/ e é exatamente o que o /ack-init renderiza em um fork.

A dependência de sentido único

A dependência corre estritamente META → CHILD, nunca de volta:

• O renderizador lê de templates/ e escreve na árvore de trabalho do child.
• Um child nunca lê de volta para o ferramental .claude/ do kit, o motor de discovery ou o orquestrador.
• O renderizador copia apenas arquivos sob templates/. A árvore .claude/ da META (skills de ferramental de build como skill-creator, mcp-builder, o orquestrador) é nunca copiada para um child (invariante I7, imposta como regra de render: renderizar apenas A PARTIR de templates/).

É isso que permite ao kit carregar maquinário meta-only poderoso sem nenhum risco de ele vazar para os projetos que gera.

Invariantes de forkabilidade

Três regras concretas tornam um child renderizado um repo limpo e autocontido:

1. A árvore .claude/ da META nunca é copiada para um child. Apenas templates/ é renderizado. Agentes meta-only (Research, Discovery), o MCP de telemetry e o orquestrador nunca podem aparecer em um fork.
2. Os hooks do child usam o literal ${CLAUDE_PROJECT_DIR}. Um comando de hook renderizado é python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/contract-gate — nunca um caminho absoluto e nunca um caminho relativo a templates/. O motor de render até afirma, antes de escrever qualquer arquivo do child, que o conteúdo não contém nenhuma substring templates/archetypes/ e nenhum caminho absoluto do kit; uma violação aborta o render.
3. As variáveis de template do child são ${dotted.path} em snake_case, resolvidas a partir de managed: no manifesto do child. O regex de render casa apenas caminhos pontilhados em minúsculas, que é precisamente por que a variável de shell em maiúsculas ${CLAUDE_PROJECT_DIR} sobrevive à substituição intocada.

Um quarto padrão de forkabilidade, mais silencioso, vive no próprio manifesto: discovery.enabled tem como padrão off (invariante I7), então o motor de discovery da META nunca é conectado a um fork a menos que o operador opte deliberadamente por isso. O kit pode carregar uma capacidade poderosa de discovery de codebase sem que ela se torne uma dependência surpresa de todo child.

Segurança de dois lados: fail-closed no tempo de autoria, fail-open no tempo de execução

A fronteira é imposta assimetricamente de propósito (invariante I6):

• Fail-closed no tempo de autoria. /ack-init valida o manifesto contra o JSON-Schema congelado antes de renderizar. Um manifesto inválido aborta e não escreve nada. A guarda do meta-repo é o mesmo princípio: rodar /ack-init no próprio kit recusa terminantemente.
• Fail-open no tempo de execução. Um manifesto corrompido ou ausente no momento do consumo (por exemplo, o contract gate lendo-o) degrada o gate para o modo off mais um aviso no stderr — ele nunca sai com 2 e nunca trava uma sessão.

Por que essa fronteira importa

• Isolamento — ferramental meta-only e payload do child podem evoluir independentemente; nenhum contamina o outro.
• Idempotência — como apenas managed: é regenerado e apenas rendered_files[] é possuído, as re-execuções são byte-estáveis e nunca sobrescrevem edições manuais. Veja Motor de render — idempotência.
• Higiene de template — os condicionais vivem no manifesto e em diretórios _when.*, não como fluxo de controle dentro dos templates, então o payload permanece auditável.
• Dependência de sentido único — um child é um snapshot limpo que não deve nada de volta ao kit.

Como os archetypes se situam dentro da camada CHILD

Tudo o que um fork pode se tornar também é payload do CHILD autorado sob templates/. A primeira pergunta do manifesto — archetype — escolhe qual árvore de template é renderizada: backend-api, fullstack e saas são os três archetypes profundos (persistência completa, spec de API e scaffolding do contract gate), enquanto monorepo, library-sdk e infra-iac renderizam um core mínimo. Nada disso vive na árvore .claude/ da META; é todo scaffolding selecionável sob templates/archetypes/, que é por que um novo archetype é uma tarefa de autoria na camada CHILD, não uma mudança no ferramental do próprio kit. Infraestrutura-como-código é deliberadamente ortogonal: features.iac mais o bloco iac permitem que qualquer archetype adicione infra, então IaC não é um sexto archetype exceto para o repo puro infra-iac. Veja a visão geral de archetypes para a matriz completa.

Onde os contratos vivem

Os contratos P3 congelados que cruzam essa fronteira — o schema do manifesto, o banco de perguntas e o contrato de render — são documentados a seguir em Entrevista → Manifesto → Render e Contrato do motor de render.

Veja também: Visão geral de archetypes · Motor de render — idempotência · o contract gate, uma regra da camada CHILD, em Contract gate.