Requisição 177 — Contrato de Documentação, `c2f docs:audit`, `c2f docs:extract` e Piloto Bilíngue (FEAT-014, fase 1)

Origem: FEAT-014, decisões D1, D3, D6 e D9 (2026-09-25). Lote Vinculado: BATCH-182. Status: approved. Autonomia: Nível 1 (supervisionado).

1. Contexto

As docs de ai-workspace/{pt-br,en}/docs/ estão defasadas. Exemplos: gestor.php tem 68 de 76 funções não documentadas; interface.php tem 57 de 58 não documentadas e 25 funções citadas que não existem; 14 bibliotecas e 9 módulos não têm doc. Falta um contrato que torne a defasagem mensurável e uma rotina que a reduza incrementalmente.

2. Contrato normativo

2.1 Taxonomia (nova árvore, convivendo com o legado até a migração)

Os nomes de pasta e as chaves são em inglês e idênticos nos dois idiomas. Isso garante o espelhamento por caminho e a URL pública /docs/... (D5).

ai-workspace/<idioma>/docs/
├── guides/        concepts/        whats-new/
└── reference/{libraries,modules,api,cli,hooks}/

• Espelhamento obrigatório: pt-br/docs/<rel>.md ↔ en/docs/<rel>.md, mesmo caminho relativo (D3).

• URL pública: docs/<rel sem .md>/. Um index.md vira a raiz da pasta.

• Docs legadas (sem frontmatter, fora da nova árvore) continuam no lugar e aparecem no audit como legacy, até serem migradas por uma onda.

2.2 Frontmatter (YAML simples, chave: valor, listas com - item)

2.3 Bloco extraído

Docs de reference/libraries/ contêm o bloco:

C2FFUNCTIONREFERENCEBLOCK

• É regenerado pelo comando.

• O texto fora do bloco é autoral e preservado.

3. Escopo técnico

1. c2f docs:audit (cli/src/Commands/DocsAuditCommand.php + cli/src/Support/Docs/*). Diagnósticos por doc, cada um com severidade:

   • frontmatter inválido ou ausente;

   • section divergente da pasta;

   • par de idioma ausente;

   • sources inexistentes;

   • sources alteradas depois de verified_at (via git log);

   • bloco extraído desatualizado;

   • cobertura: biblioteca gestor/bibliotecas/*.php sem reference/libraries/<nome>.md e módulo gestor/modulos/* sem reference/modules/<id>.md;

   • contagem de docs legadas.

   • Saída: ranking em tabela, com --json, --limit=N e --strict (exit 1 com erros).

2. c2f docs:extract <biblioteca>|--all:

   • lê as funções de gestor/bibliotecas/<nome>.php via tokenizer (nome, parâmetros com default, linha, resumo do docblock);

   • reescreve o bloco nas duas línguas;

   • com --check, só verifica, sem escrever.

3. Piloto (D6): três docs escritas do zero a partir da leitura do código, em pt-br e en:

   • guides/documentation.md: como escrever e publicar docs (contrato, fluxo, comandos);

   • reference/libraries/modelo.md: gestor/bibliotecas/modelo.php;

   • reference/modules/menus.md: módulo menus (administração, schema de itens, widget, templates, disponibilidade por perfil).

4. Índices docs/index.md (pt-br e en) apresentando a nova árvore.

5. Testes PHPUnit dos parsers de frontmatter, extração e diagnósticos (com fixtures em diretório temporário).

4. Critérios de Aceite

1. php cli/c2f.php docs:audit lista o ranking sem erro e marca as 3 docs piloto como válidas.

2. php cli/c2f.php docs:extract modelo --check retorna 0 após a extração.

3. As 3 docs piloto existem em pt-br e en, com frontmatter válido e conteúdo conferido contra o código.

4. PHPUnit verde, incluindo os testes novos. git diff --check limpo.