Policies

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

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

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

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

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

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

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-retention

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sugerir nicknames curtos proativamente para objetos referenciados repetidamente (repos, servidores, diretórios, serviços, credenciais). Detectar colisões antes de propor.

mnemonics

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

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

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

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

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

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

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

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

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

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

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

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

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

runtime-source-of-truth

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

Apenas HTTPS; nada de HTTP, FTP ou Telnet em qualquer publish/deploy. Redirect 301 de http→https obrigatório onde aplicável.

security

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

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

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

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

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

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

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

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

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

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