Governance¶

📚 Enterprise Documentation Engine¶

Toda alteração estrutural (schema, contratos de API, fluxos críticos ou governança) exige atualização da documentação em /docs.
O snapshot de schema é gerado automaticamente por scripts/generate-schema-snapshot.js via leitura da view vw_schema_snapshot.
PRs sem atualização documental obrigatória devem ser considerados inválidos.
O pipeline de docs em .github/workflows/docs.yml executa geração de snapshot + build + deploy para GitHub Pages.
Para o deploy de docs funcionar, os secrets SUPABASE_URL e SUPABASE_SERVICE_ROLE_KEY devem existir no repositório (Settings → Secrets and variables → Actions).

Operação¶

Atualize os arquivos de especificação em /docs.
Gere snapshot local (quando necessário): bash node scripts/generate-schema-snapshot.js
Valide o build: bash mkdocs build

Dependency & install governance (Codex/CI)¶

Para evitar regressões de ERR_MODULE_NOT_FOUND em ambientes limpos:

O repositório deve funcionar em ambiente limpo usando apenas dependências versionadas no próprio repo.
Não depender de pacotes npm globais/sistêmicos.
Nunca commitar node_modules.
Dependências de backend/runtime da API devem ser declaradas em package.json (raiz).
Dependências de web app e tooling web devem ser declaradas em web/package.json.
Dependências do pacote aninhado web/design-source devem ser declaradas em web/design-source/package.json.
Cada escopo de pacote deve manter seu próprio lockfile atualizado:
package-lock.json (raiz)
web/package-lock.json
web/design-source/package-lock.json
Mudanças de tooling/config que introduzam import direto de pacote externo devem atualizar o package.json do escopo correto.
ESLint/tooling deve usar apenas configuração e dependências declaradas no repositório.

Validação mínima de instalação limpa:

npm ci
node scripts/preflight-env.mjs api
node -e "import('./controllers/adminSystemController.js').then(()=>console.log('adminSystemController import ok'))"

cd web && npm ci && npm run lint -- --no-error-on-unmatched-pattern web/src/app/page.tsx

cd web/design-source && npm ci

Regra de freshness do snapshot de schema (obrigatória quando o guard estiver ativo)¶

docs/system/schema-current.json é tratado como artefato com freshness gate em validações de commit/CI.
Se o fluxo validar generated_at como “hoje”, o snapshot deve ser regenerado no mesmo dia antes de finalizar commits.
Regeneração recomendada: bash env -u SUPABASE_URL -u SUPABASE_SERVICE_ROLE_KEY node scripts/generate-schema-snapshot.js (ou node scripts/generate-schema-snapshot.js com credenciais válidas).
Sempre regenere o snapshot antes de atualizar/commitar documentação de sistema dependente de estado atual de schema.
Se não regenerar quando o guard estiver ativo, o commit/CI pode falhar por snapshot desatualizado.

Governança adicional — AI Copilot¶

Toda ação de IA deve gerar log em ai_action_logs com payload de entrada/saída e modo de execução.
Operações de mutação devem seguir confirmação explícita (execute_with_confirmation) e oferecer trilha para undo.
Alterações de código iniciadas pela IA devem obrigatoriamente gerar PATCH PLAN + PR, sem escrita direta em produção.
Acesso ao Copilot limitado a administradores com rate limit aplicado.

REGRA CRÍTICA DE MANUTENÇÃO DE CÓDIGO¶

Nenhum agente (Codex ou humano) pode:

remover funções existentes
alterar assinatura de função existente
remover campos existentes
alterar rotas existentes
alterar comportamento existente

A menos que haja pedido explícito do proprietário do projeto.

Sempre aplicar:

BACKWARD COMPATIBILITY FIRST

Se um campo novo for criado, o campo antigo deve continuar funcionando.

REGRA DE EVOLUÇÃO DE SCHEMA¶

Se uma coluna for substituída por outra (ex: source_lang → source_language):

1) nova coluna é criada 2) dados são migrados 3) código suporta ambas 4) coluna antiga só pode ser removida em versão futura explicitamente aprovada

Universal Taxonomy System¶

Universal Taxonomy Engine¶

O Spoke Plus utiliza um sistema centralizado de taxonomias.

Esse sistema é responsável por padronizar todas as classificações usadas pelo projeto.

Ele é composto por duas tabelas principais:

taxonomy_categories
taxonomy_values

taxonomy_categories define os tipos de taxonomia existentes.

taxonomy_values define os valores dentro de cada categoria.

Todo o sistema deve referenciar essas tabelas.

Regra obrigatória de modelagem¶

Nenhuma tabela deve armazenar classificações como texto livre.

Sempre usar referências por ID para taxonomias.

Exemplos corretos:

vocabulary.pos_id
vocabulary.lemma_type_id
sentences.register_id
exercises.exercise_type_id

Categorias de taxonomia (mínimo obrigatório)¶

CEFR levels
POS
lemma types
themes
semantic domains
content types
exercise types
skill types
difficulty levels
languages
registers
translation quality
asset types
review workflow
data integrity status

Regra de backend¶

Todo controller/service/script de importação/batch/AI pipeline que receber classificação deve validar:

se o value_id existe em taxonomy_values
se o valor pertence à categoria correta (taxonomy_categories.slug)

Utilitário central obrigatório: validateTaxonomy(category_slug, value_id).

Princípio final¶

Taxonomy defines structure. Structure defines meaning. Meaning defines learning.

System Integrity coverage rule¶

All new system features must provide System Integrity coverage.

Required implementation pattern:

Register the feature in services/systemFeatureRegistry.js.
Declare route/page scope, API endpoints, schema dependencies, taxonomy dependencies, and critical UI actions.
Provide integrity validation coverage through tests and/or Playwright scenario metadata.

A feature is considered incomplete if it is not registered in the System Feature Registry.

Phase 7 Governance Gate Policy (P7-S1)¶

Canonical freeze for destructive/retirement-class eligibility gates: docs/system/observability-phase7-p7s1-policy-contract-freeze.md.
Phase 7 remains read/evaluate/audit only; no executor/destructive behavior is authorized in this phase.