Policies
Behavioural rules enforced across the Stack.
-
Agent-guardrails
mandatory
Three-layer guardrail contract for any Koder-built AI agent harness (kode, kortex, agents, voice). Defines the minimum input/output/tool guards every agent must enforce, independent of the active permission mode. Operationalised by the harness tool router (kode #047 `PreToolUse` hook) and audited via `koder-spec-audit policies agent-guardrails`. Sibling of `reuse-first.kmd` and `hyperscale-first.kmd`: where reuse is about shared code and hyperscale about shared cost, guardrails are about shared safety.
agent-guardrails -
AI content disclosure
ratified
mandatory
Comportamento exigido para disclosure de conteúdo gerado por IA em produtos Koder. Cobre QUANDO e ONDE o disclaimer mecânico de `specs/ai-ui/ai-disclaimer.kmd` MUST aparecer. Companion da spec — spec define mecanismo (3 tiers + i18n + dismissal); policy define o comportamento exigido.
ai-content-disclosure -
Always-on
mandatory
Todo componente Koder é desenhado pra estar **sempre no ar e operante**, em todos os sentidos: usuários em qualquer versão (N, N-1, N-2 dentro da janela suportada) conseguem usar; rollout de nova versão atravessando milhares de servidores por dias não causa quebra em ponta alguma; servidor cai, rede oscila, dependência falha — produto degrada com graça, nunca trava nem perde dado. Maintenance window é anti-padrão. Flag day é anti-padrão. "Atualize todo mundo antes de mudar" é anti-padrão. A inviolabilidade da experiência atravessa **versão, topologia, conectividade e surface**.
always-on -
Analytics on Koder Public Surfaces
mandatory
Privacy-respecting analytics policy for Koder public surfaces (kds.koder.dev, www.koder.dev, hub.koder.dev, <slug>.koder.dev, product landings). Defines what may be collected, what must NOT be collected, the required tooling stance (self-hosted only), DNT respect, retention windows, dashboard access, and the contract with visitors. Companion policy to security.kmd and the multi-tenancy contract.
analytics -
Android UI Inspection (Koder Eye-first)
mandatory
Em sessão com Android conectado via ADB, preferir Koder Eye (HTTP API em 127.0.0.1:9876 após `adb forward tcp:9876 tcp:9876`) a screenshots crus. ~10× menos tokens, bounds/IDs/estado exatos do OS. Cair pra screencap só em casos visuais (ícone, cor, canvas, FLAG_SECURE).
android-ui-inspection -
Implementation Backlog
mandatory
Estrutura de backlog em dois níveis: módulo (`<module>/backlog/`) para trabalho com escopo único; projeto (`projects/<project>/backlog/`) para iniciativas cross-cutting. Em cada caso, fluxo `pending → in-progress → done`, numeração sequencial NNN-titulo-slug.md.
backlog -
Chat Formatting
Regras de formatação de mensagens no chat (Claude Code, Codex CLI, Gemini, qualquer agente que escreva no terminal do usuário). Diretriz mestra: **maximize affordance** — cada elemento que o usuário poderia querer copiar, abrir ou referenciar deve estar em um formato que o renderizador transforma em interação direta.
chat-formatting -
Checkpoint Blob Retention
draft
checkpoint-retention -
Code First
mandatory
Encode lógica determinística em binário (Go/Rust); deixe lógica analítica em LLM (markdown). Múltiplas IAs (Claude, Codex, Gemini) interpretam markdown de forma sutilmente diferente — binário garante resultado idêntico cross-LLM. Stack hoje tem ~10% binário e ~90% markdown — invertido. Esta policy é expansão do princípio #3 de `policies/stack-principles.kmd`.
code-first -
Command Creation
mandatory
Processo de criação de comando `/k-*` novo: 5-question Divide-and-Conquer checklist, decisão Code-First (markdown vs binary), uso do scaffolder `/k-new command`, conformidade com `specs/commands/structure.kmd`. Não criar comando do zero quando reuso é possível; não criar markdown quando lógica é determinística.
command-creation -
Content location — single source of truth por categoria
mandatory
Tabela canônica de "tipo de conteúdo → path no monorepo". Onde cada categoria de documento, asset ou metadata vive de forma única, sem duplicação nem symlink. Resolve o gap que existia na Stack: módulos às vezes mantinham specs inline (KMD), às vezes em meta/docs/stack/ (KVG), sem regra explícita. Esta policy cravra a regra. Aplica-se a conteúdo de leitura humana — não a estrutura de módulos (RFC-003) ou de Sectors (RFC-006), que têm policies próprias.
content-location -
Decision Graph
Método para reduzir N decisões abertas a ~3 decisões-mestre via grafo de dependência. Quando uma sessão de planning enfrenta 5+ open questions, mapear quais decisões cascateiam e isolar as não-deriváveis. Aplica Meta First (princípio #1) ao próprio processo de decisão.
decision-graph -
Deploy Feedback
mandatory
Após qualquer deploy ou publish, reportar URL clicável (linha autônoma, não enterrada no resumo) para o usuário verificar no browser. Para landing pages, e mais genericamente para qualquer alteração visualmente avaliável em página web já publicada, publicar automaticamente sem perguntar — caso contrário o usuário não tem como avaliar.
deploy-feedback -
Design System Governance
mandatory
Define quem ratifica novas specs UI/UX, processo de breaking change, ciclo de deprecation, cadência de versionamento, e co-existência com a landing `kds.koder.dev`. Funcional foundational da RFC-001 Koder Design System.
design-governance -
Dev-Phase Default Password
mandatory
Single default password used for test users, fixtures, and seed accounts across the Koder Stack during the development (pre- homologation) phase. It exists to speed up account switching during E2E tests and internal demos without forcing every engineer or AI agent to manage 20 distinct passwords. **This policy automatically expires when the Koder Stack enters official homologation** — it does not roll into production.
dev-default-password -
Dev-phase destructive operations allowed (pre-launch only)
mandatory
Enquanto a Koder Stack está em fase pré-launch e o único usuário é a equipe Koder, operações destrutivas reais (DELETE de versão, DELETE de app, rename livre sem reservation) são **permitidas** em componentes do registry/storage, gated por flag explícita `KODER_HUB_DEV_DESTRUCTIVE=1`. Quando a Stack atinge a primeira release pública para usuários externos, este bypass **some**: yank/rename canônicos passam a ser as únicas operações disponíveis.
dev-phase-destructive-allowed -
Device Mirror Durante Acesso de IA (Koder Eye)
mandatory
Sempre que uma IA acessar um dispositivo Android conectado por ADB (USB ou Wi-Fi), ela deve iniciar o serviço de espelhamento do Koder Eye e abrir a aba `http://localhost:9876/mirror` no browser do operador antes do primeiro toque/screencap. Operador acompanha o que a IA faz sem precisar olhar pra tela do celular.
device-mirror-during-ai-access -
Divide and Conquer
mandatory
Antes de criar comando, spec, policy ou binário novo, listar o que já existe que pode ser reusado. Aplicar a regra dos 3: extrair pattern comum quando a 3ª instância aparecer; tolera duplicação curta. Esta policy é expansão do princípio #4 de `policies/stack-principles.kmd`.
divide-and-conquer -
Document format — prefer .kmd
mandatory
Documentos versionados no monorepo Koder devem usar a extensão `.kmd` (Koder Markdown) por default. `.md` continua aceito apenas em arquivos cujo nome literal é exigido por ferramentas externas (Claude Code lê `CLAUDE.md`; forges renderizam `README.md`/`LICENSE.md`/etc.) ou em conteúdo gerado por terceiros sob nosso controle limitado. KMD é um superset de CommonMark — renomear `.md → .kmd` em si não exige mudança de conteúdo; o que ganhamos é parse semântico, frontmatter checado, cross-refs validadas, e preview first-class no Koder Dok / Koder Flow.
document-format -
Environments policy — dev / stg / prd
environments -
Error Reporting Retention
mandatory
Janelas de retenção pra eventos do reporter público (design-error / design-feedback) — raw 7 dias, aggregated counts 24 meses; deletion-by-user inaplicável (sem koder_user_id).
error-reporting-retention -
Headless-first — UI fully automatable / testable without a human display
mandatory
Toda UI da Koder Stack (Flutter, GTK/Adwaita, Wayland client, compositor, TUI, web, installer, initramfs) deve nascer com um caminho headless completo: input programático + observação determinística + golden capture, exercitando o MESMO binário que o usuário vê (sem mocks no caminho de render). "Funciona na minha tela" não é estado válido pra promote-to-prod — só "passa headless E na tela". Esta policy NÃO é o RFC de arquitetura — esse é `stack-RFC-005-full-headless-testability` (3 camadas SDK, fidelity contract, `.kdt` DSL, etc.). Aqui ficam as regras comportamentais enforce-ables; o RFC define o como técnico.
headless-first -
Headless Self-Check Before User Handoff
mandatory
Sempre que houver um caminho headless/programático para verificar uma mudança (screenshot via Chrome headless, curl + asserção, comando CLI com fixture, parse de output, etc.), Claude deve rodar esse check **antes** de pedir avaliação humana e reportar o resultado junto com o pedido. Reserva o tempo do usuário para a parcela que só humano resolve.
headless-self-check -
Hyperscale-first
mandatory
Toda decisão de implementação segue a tríade: escalabilidade (estruturas que funcionam em 100×), eficiência (menor overhead em I/O, cache, índice, streaming), sustentabilidade (código que um eng novo entende em 10 min). Esforço igual → escolher a que escala melhor. Esforço desproporcional → ship a simples + ticket de follow-up para promoção.
hyperscale-first -
Identity Data Retention
mandatory
Janelas de retenção pra dados de autenticação do Koder ID (auth_flows, auth_events, sso_sessions, lockouts) + right-to-erasure + data-export. Sibling de error-reporting-retention.kmd; cobre LGPD Art. 15-16 e GDPR Art. 5(1)(e).
identity-data-retention -
Language
mandatory
pt-BR no chat com o usuário (exceto código-fonte e identificadores técnicos). en-US em todas as superfícies de produto Koder (READMEs, sites, apps, mensagens de erro user-facing). Regras de i18n por surface.
language -
Lock carve-out — collision-free ops allowed under sibling-session lock
mandatory
Quando outra sessão tem lock ativo em `<component>` (per `tasks/concurrent-lock.md`) mas a operação pedida pelo owner tem zero risco de collision com o trabalho da sessão dona do lock, carve-out é permitido sob procedimento estrito: courtesy notice em `meta/context/notices/active/` + frontmatter pointer no artefato + `git commit -o <pathspec>` pra não contaminar o index. Operações collision-free são pre-cataloged em §R2; tudo fora dessa lista exige o lock arquivado antes.
lock-carve-out -
Mnemonics
Sugerir nicknames curtos proativamente para objetos referenciados repetidamente (repos, servidores, diretórios, serviços, credenciais). Detectar colisões antes de propor.
mnemonics -
Labeled Multi-Choice Questions
mandatory
Quando uma resposta exige escolha entre alternativas, rotular cada opção com letra (a/b/c/d) ou número (1/2/3/4) para permitir resposta de 1 caractere. Aplicar mesmo em questionamentos curtos ou casuais.
multi-choice-questions -
Multi-tenant by default
mandatory
Todo schema, API, storage e fluxo de dados na Koder Stack é desenhado desde o primeiro commit considerando N koder_user_id e N workspace_id independentes, com isolamento estrito entre tenants. Single-tenant ou shared-state global é anti-pattern. "Vamos abstrair depois" não é válido — adicionar tenant_id retroativo é refactor doloroso e error-prone.
multi-tenant-by-default -
Naming Aliases
mandatory
Behavioral guidance for *when* to create an alias for a Koder Stack component, and *when not to*. Aliases are the compact/colloquial form of reference (kflow, kdrafts, kterm) registered in meta/docs/stack/registries/component-names.md. Mechanism (regex, uniqueness, max 3) lives in specs/naming/forms.kmd; this policy decides the human judgement of which components deserve one.
naming-aliases -
Recommendation Required
mandatory
Toda multi-choice question feita pela IA ao usuário deve trazer recomendação explícita — não apenas enumerar opções. Estende `policies/multi-choice-questions.kmd` (que cobre rotulagem) com a obrigação de ter posição. Acelera decisão e força a IA a aplicar julgamento técnico em vez de dump neutro de alternativas.
recommendation-required -
Koder Hub — slug naming and immutability
mandatory
Slugs publicados no Koder Hub são **imutáveis após o primeiro publish**. Renomear um produto se faz via `khub rename`, que cria um redirect permanente (301) do slug antigo para o novo. Slugs retirados **nunca** são recicláveis por outros produtos. O modelo é o do npm, crates.io e Apple Bundle ID — depois que um nome é usado, ele fica reservado pra sempre àquele app, mesmo após rename.
registry-naming -
Regression Tests per Bug
mandatory
Toda correção de bug exige teste de regressão (3 categorias: behavioral, golden, estrutural) que falhe sem o fix e passe com ele. Testes ficam em tests/regression/. Registry: registries/regression-test-cases.md.
regression-tests -
Release Workflow (UI components)
mandatory
Fluxo obrigatório para publicar release de qualquer componente com UI (desktop, mobile, web, TV). Tag formato `<área>/<componente>/v*`, secrets necessários, regras pra adicionar/renomear/arquivar componente no pipeline. Distinto de `policies/deploy-feedback.kmd` (notificação pós-deploy) e `specs/releases/packaging.kmd` (formatos de pacote).
releases -
Reuse-first
mandatory
Antes de implementar padrão cross-cutting (tema, layout, navegação, auth, erros, telemetria, update, i18n, IPC, logging, store, build-tooling, protocol), verificar a biblioteca/framework/CLI compartilhado adequado. Se o padrão pertence a uma biblioteca compartilhada e ainda não está lá, criar/estender lá primeiro — não no caller. Esta é a meta-policy de reuso da Stack; sub-policies em `policies/reuse/<category>-first.kmd` adicionam regras categóricas (SemVer, a11y baseline, hash stability, wire compat, …) sem redeclarar a árvore de decisão. Mecanismo de enforcement do RFC-001 do koder_kit.
reuse-first -
Build Tooling First
mandatory
Sub-policy de `reuse-first` para CLIs e helpers de build-time (`kicon`, `koder-stackdoc`, `koder-test-gate`, `khub`, e similares). Herda decision tree, protocolo pré-Write e promotion pipeline da meta; acrescenta apenas as regras categoricamente distintas: determinismo (input idêntico → output idêntico, hash-stable), idempotência, no-network em mainline path, self-stamping de artefatos, alinhamento com `code-first` (3+ usos → binary).
reuse/build-tooling-first -
Protocol First
mandatory
Sub-policy de `reuse-first` para wire formats e protocol clients cross-cutting (koder_ipc, koder_chat, koder_store, observability envelopes, kpkg, federation protocol). Herda decision tree, protocolo pré-Write e promotion pipeline da meta; acrescenta apenas as regras categoricamente distintas: RFC ratificado antes do mainline, version negotiation no envelope, BC por N versões, schema evolution (add OK; rename/remove = major), cross-implementation tests.
reuse/protocol-first -
Runtime Lib First
mandatory
Sub-policy de `reuse-first` para libs runtime compartilhadas (Go, JS, Python, Rust, plus libs cross-language como koder_ipc / koder_chat). Herda decision tree, protocolo pré-Write e promotion pipeline da meta; acrescenta apenas as regras categoricamente distintas de runtime libs: SemVer estrito, API stability tiers, paridade multi-linguagem, benchmarks obrigatórios, coverage ≥ 85%, wire compat client-N ↔ server-N-1.
reuse/runtime-lib-first -
Search Tooling First
mandatory
Sub-policy de `reuse-first` para search engines e CLIs de busca da Koder Stack (Krep engine + krep CLI, e quaisquer componentes futuros sob `engines/search/`). Herda decision tree, protocolo pré-Write e promotion pipeline da meta; acrescenta apenas as regras categoricamente distintas: contrato MCP estável, cobertura de linguagens em modo estrutural, graceful shutdown do daemon, versionamento de formato de índice, NDJSON canônico como saída, p99 latency como métrica primária, concorrência segura de queries.
reuse/search-tooling-first -
UI Framework First
mandatory
Sub-policy de `reuse-first` para padrões UI cross-cutting. Herda decision tree, protocolo pré-Write e promotion pipeline da meta; acrescenta apenas as regras categoricamente distintas de UI: theme contract, safe-area, a11y baseline, i18n, paridade entre variantes (mobile/desktop/web/TV) e disciplina de testes (golden + a11y).
reuse/ui-framework-first -
Koda runtime — source of truth
ratified
runtime-source-of-truth -
SDK-first (legacy alias)
redirect
mandatory
Renamed to `reuse-first` per `policies-RFC-001-reuse-first-hierarchy.md`. This stub keeps existing references resolving while the sweep updates callers. New refs should target `policies/reuse-first.kmd`.
sdk-first -
Secure Protocols Only
mandatory
Apenas HTTPS; nada de HTTP, FTP ou Telnet em qualquer publish/deploy. Redirect 301 de http→https obrigatório onde aplicável.
security -
Self-Hosted First
mandatory
Quando uma decisão de stack tech tiver duas opções viáveis — um componente Koder self-hosted e uma alternativa externa — preferir o Koder se ele passar nos 5 gates desta policy para o caso-de-uso específico. A política é algoritmo-estático, dado-dinâmico: os gates e o protocolo vivem aqui; o status por componente vive em `koder.toml [self_hosted]` blocks; um registry auto-gerado agrega; a IA consulta o registry, não esta policy. Subsume a decisão histórica de `web-server.kmd` (Koder Jet) e a Diretriz do Flipping Point do kodec em CLAUDE.md como casos aplicados.
self-hosted-first -
Stack Principles
mandatory
Princípios raízes que guiam toda decisão arquitetural na Koder Stack. Princípios são guidelines (julgamento), NÃO regras (deterministic). Princípios podem entrar em conflito; cada par conflitante traz uma heurística de resolução pré-pensada para que IAs e humanos possam prosseguir sem deadlock. Princípio #1 (Meta First) é o lens através do qual os demais são aplicados.
stack-principles -
Test Host Isolation — heavy / risky / graphical tests run on dedicated VMs, not the developer laptop
mandatory
Toda execução de teste, build pesado, simulação ou cenário que possa travar/consumir excessivamente o host (CPU, RAM, swap, GPU, IO, kernel) acontece em uma **VM de teste dedicada** hospedada em `s.khost1`, **nunca diretamente na máquina do desenvolvedor** (laptop, workstation). As VMs são compartilhadas entre IAs e humanos — para evitar interferência cruzada, cada VM aceita **uma única sessão de execução por vez** (mecânica de lock per-VM, análoga ao `koder-lock` de componentes). VMs cobrem 3 famílias de targets (linux / windows / android) através de qualquer tecnologia de virtualização (LXC, Docker, QEMU/KVM, emulador Android, etc.).
test-host-isolation -
Test the Koder Linux ISO
mandatory
Runbook para a ação "teste a iso" (Koder Linux): preparar VM/host de teste, bootar a ISO, validar instalação e branding. Procedimento usado por agentes e humanos.
test-iso -
Testing Policy
Quando rodar cada categoria de teste, prioridades, gating no CI, política de flakes, política de skips. Complementa `specs/testing/taxonomy.md` (definições) e `specs/testing/coverage-matrix.md` (componente → categorias).
testing -
Text Search
mandatory
Substring and full-text search inside the Koder Stack uses the kdb-native substrate; external search engines (Elasticsearch, Meilisearch, Algolia, Typesense, Solr, Sphinx) are not adopted as dependencies of any Koder component. The substrate ships in two shapes — trigram inverted index for `LIKE` / `ILIKE` / similarity (PG `pg_trgm` equivalent) and GIN over tokenized columns for full-text (PG `tsvector` equivalent). Both live in `kdb-record` and are queried through `kdb-pgwire`'s standard SQL surface. Applied case of `self-hosted-first.kmd` for the search domain.
text-search -
Username Allocation (Koder ID)
mandatory
Regras de alocação de usernames no Koder ID: reservas, padrões proibidos, migração. Depende de RFC-012 (account models) e RFC-013 (invite chain). Status: Draft (proprietário: Koder ID team).
username-allocation -
Web server — Koder Jet por default
mandatory
Koder Jet é o **único** web server / reverse proxy oficial da Koder Stack desde 2026-04-05. Toda configuração de site, vhost, TLS, redirect ou static serving da stack vai em sites.toml do Jet — não Caddy, não nginx, não Apache, não Traefik. Caddy permanece em uso pontual em casos legados explicitamente registrados; tudo novo é Jet.
web-server -
Windows Builds
mandatory
Como produzir artefatos Windows por tipo de módulo da Koder Stack. Distingue o que funciona direto no Linux (Go cross-compile, MSI via wixl) do que exige delegar para máquina Windows via WinRM (Flutter desktop). Inclui receita pra k.win.
windows-builds -
Working Tree Resolution — agentic methodology
mandatory
Como um agente Koder Stack resolve pendências do working tree do monorepo sem auto-commit-cego. O agente inspeciona, raciocina e age conforme cada finding, usando o modelo de quatro destinos (commit, stash, ticket, delete) definido aqui. Esta policy é a spec do comando `/k-tidy`.
working-tree-resolution