Koder Governance Plane — overview
Glossário canônico e mapa do modelo de governança da Koder Stack: como as regras (specs/policies) são efetivamente CUMPRIDAS por agentes de IA, não só escritas. Consolida o vocabulário espalhado entre RFC-014 (harness), RFC-015 (Kanon), RFC-016 (governance plane), gates.kmd e architecture-quality.kmd num único lugar de referência. Não decide nada novo — nomeia e organiza o que já está ratificado.
O que é, em uma frase: o conjunto de mecanismos que faz as regras da Koder Stack (specs e policies) serem efetivamente cumpridas por agentes de IA — não apenas escritas e esperadas. O nome ratificado do todo é Koder Governance Plane (
stack-RFC-016); a disciplina é Governance-as-Code para trabalho conduzido por IA.
Este doc é glossário e mapa, não RFC: não decide nada novo. Consolida num só lugar o vocabulário que vive espalhado nas RFCs 014015016, em
gates.kmde emarchitecture-quality.kmd. Quando precisar do nome certo de uma peça do modelo de enforcement, é aqui.
1. O todo: Governance Plane (RFC-016)
A tese da RFC-016 (Accepted, north-star): o tenant declara regras (e meta-regras), os agentes são conduzidos proativamente a cumpri-las, e um gate determinístico dá o veredito. O diferencial sobre a categoria existente (OPA/Rego, "AI guardrails" genéricos) é a dupla condução + camada constitucional — regras sobre quem e como se autora regras —, que nenhum dos dois oferece junto. A máquina interna é a semente de um produto externalizável (nome ratificado: Koder Kodex); por isso é construída extraível desde o dia um (R1/R2 da RFC-016).
As quatro camadas (vocabulário RFC-016 §1)
| Camada | O que é | Protótipo interno hoje |
|---|---|---|
| Constitucional (meta-regras) | regras sobre quem/como autora regras | RFC-003: component-policy TIGHTEN/ADD, nunca LOOSEN |
| Tenancy / isolamento | cada tenant isolado | multi-tenant-by-default.kmd + dimensão D5 |
| Motor de regras | avalia as regras declaradas | koder-spec-audit → Kanon (RFC-015) |
| Condução | leva o agente a cumprir, proativamente | broadcast-alerts + hook JIT (RFC-014) |
2. O modelo de imposição: dois braços × dois tempos
A regra é imposta por dois braços, em dois tempos:
| Pre-action (antes da ação — barato) | Post-hoc (depois — detectivo) | |
|---|---|---|
| Condução (guia, não-bloqueante) | JIT inject (jit-spec-inject, RFC-014 fase 3) — injeta a spec na hora da ação |
broadcast-alerts; /k-meta-watch (anti-erosão, RFC-014 fase 6) |
| Gate (determinístico, bloqueante) | koder-spec-audit gate --staged no /k-commit (gates.kmd) |
CI / drift gate |
Princípio (RFC-014): "prevenir na ação custa menos que pegar no CI". A condução é o lembrete-guia; os dentes ficam no gate (gates.kmd: ciclo de vida
advisory → blockpor evidence-soak, com budget de falso-positivo e escape-hatch auditado).
3. Como o JIT inject decide o que lembrar (matching)
O jit-spec-inject casa a ação atual contra o registry spec-triggers.kmd por dois eixos (RFC-014 fase 3 + 3b):
- Path-triggered — o arquivo editado (Edit/Write) casa um glob
paths:.Cobre regras disparadas por edição (ex.: editar uma landing → ler a spec de landing).
- Action-triggered (fase 3b, "action-aware") — o comando Bash casa um
regex
bash_patterns:. Cobre regras comportamentais pós-ação (ex.: rodarsystemctl reload koder-jet→ cumprirdeploy-feedbacke emitir a URL clicável). Fecha o quadrante que regras puramente comportamentais deixavam vazio.
Ambos leem o mesmo registry e injetam o mesmo additionalContext; cobertura cresce editando o registry, não o hook (registry-driven, fail-open).
4. Glossário canônico
| Termo (oficial Koder) | É o quê | Onde |
|---|---|---|
| Koder Governance Plane | o todo: governance-as-code para trabalho de IA | stack-RFC-016 |
| Koder Kodex | o produto externalizável (nome ratificado) que extrai o Plane | RFC-016 |
| Spec-adherence harness | os trilhos de adesão (registry + hook + gate) | stack-RFC-014 |
| Kanon | a linguagem de regras (não-Turing-completa) + avaliador declarativo que substitui checkers Go hardcoded | stack-RFC-015 |
| Gate (de conformância) | check determinístico bloqueante; ciclo de vida advisory→block |
policies/gates.kmd |
| Fitness functions | as 12 dimensões de Solidez Arquitetural como funções verificáveis (quando o audit deixa de ser advisory) | policies/architecture-quality.kmd |
| JIT inject | injeção just-in-time da spec na hora da ação (condução pre-action) | jit-spec-inject.sh (RFC-014 fase 3) |
| Trigger registry | SSOT ação→spec; renderiza a tabela do CLAUDE.md (drift = CI fail) | registries/spec-triggers.kmd |
| Broadcast-alerts | avisos lidos por todas as sessões (locks, obrigações datadas) | specs/notices/broadcast-alerts.kmd |
| Condução | levar o agente a cumprir proativamente (vs. só bloquear) | RFC-016 §1 |
5. Relação com a terminologia da indústria
O Plane é governance-as-code, e dialoga com categorias conhecidas — mas tem nome próprio. Mapeamento honesto (para não confundir vocabulário importado com o da Stack):
| Termo da indústria | Equivalente / relação na Koder |
|---|---|
| Policy-as-code (OPA/Rego) | Governance-as-Code + Kanon (o "Rego" da Koder); o Plane vai além: adiciona condução + camada constitucional |
| AI guardrails | a camada de condução + gate; o Plane junta as duas com a constitucional, o que guardrails genéricos não fazem |
| Fitness functions (Evolutionary Architecture) | adotado literal em architecture-quality.kmd |
| Just-in-time / pre-commit hooks | o JIT inject e o gate no /k-commit |
Nota: "policy-as-code" e "agent governance" são rótulos da indústria — úteis como ponte, mas o nome oficial na Koder é Governance Plane / Governance-as- Code (RFC-016). Ao documentar internamente, preferir o vocabulário da Stack.
6. Mapa de arquivos
- Norte / produto:
rfcs/stack-RFC-016-koder-governance-plane.kmd - Harness:
rfcs/stack-RFC-014-spec-adherence-harness.kmd - Motor de regras:
rfcs/stack-RFC-015-kanon-declarative-rule-engine.kmd+specs/kanon/ - Gates (ciclo de vida):
policies/gates.kmd+registries/gates.md - Fitness functions:
policies/architecture-quality.kmd - Trigger registry (SSOT):
registries/spec-triggers.kmd - Hook de condução:
meta/context/claude/hooks/jit-spec-inject.sh - Avaliador:
products/dev/koder-tools/cmd/koder-spec-audit