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 Konsul (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

Rubrica normativa das dimensões pelas quais se avalia se uma arquitetura é boa de longo prazo. É a checklist concreta que o Princípio #2 (Quality > Speed) manda aplicar quando o `/k-go` ou qualquer IA desempata entre opções/abordagens. Escala (hyperscale) é UMA das dimensões, não o todo. Consolida o que estava espalhado (k-evolve §2, multi-tenant, reuse/sdk-first, security) num único lugar normativo e fecha 3 gaps: evolvabilidade, consistência de dados, reversibilidade.

architecture-quality

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

Sempre que Claude (qualquer IA da Stack) concluir que NÃO pode prosseguir numa atividade porque (a) o componente que precisa editar está com lock ativo de outra sessão, ou (b) um teste/build/processo pesado cujo resultado ou cujo recurso ela precisa está rodando — seja da própria sessão, seja de outra IA — ela DEVE, antes de ceder o turno, armar automaticamente um monitor de liberação. O monitor é híbrido: um watcher laptop-side que RE-ACIONA a sessão quando a condição limpa, MAIS um ping durável via koder-notify que alcança o operador mesmo se a sessão tiver encerrado antes da liberação.

blocked-work-monitor

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

Como expor os argumentos dos comandos slash `/k-*` (e demais comandos do context) de forma que o usuário os descubra e lembre. Diretriz mestra: **os parâmetros nunca moram no `description`** — moram no campo nativo `argument-hint` (autocomplete) e a referência completa fica no `/k-commands <cmd>`. O `description` responde só "o quê".

command-arguments

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

Quando uma sessão (qualquer IA da Stack) está USANDO uma instância instalada/em-execução de um componente Koder (ex.: um `kflow`, `kdb`, `kvs` instalado; um binário/CLI/daemon Koder) enquanto faz trabalho não-relacionado, e identifica um DEFEITO nesse componente (crash, saída errada, commit perdido, arquivo corrompido, regressão, perf cliff), ela é o sensor com o **contexto forense mais rico do instante**. Esta policy torna a resposta um reflexo único: SEMPRE registrar um ticket forense; e então, segundo houver ou não **lock duro** ativo, ou corrigir agora (se cabível) ou abrir o ticket + alerta de dependência + esperar o sinal-back do fixer. Costura peças que já existiam (lock-carve-out, blocked-work-monitor, broadcast-alerts, regression-tests, backlog `blocked-by`) num fluxo só.

component-bug-discovery

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

Antes de QUALQUER acesso ao celular físico do owner via ADB/IRIS (tap, texto, screencap, am start, instalar app, inspeção de UI, mirror), a IA DEVE adquirir um lock EXCLUSIVO do device (`device/owner-phone`) e liberá-lo ao terminar. Reusa o mecanismo de lock de componente (notices `lock-<slug>.md`, gitignored/local), mas o device-lock é HARD (exclusivo), não advisory: um celular físico não tem merge — duas IAs mandando comandos ao mesmo tempo se corrompem (troca de app, perda de foco, taps cruzados).

device-access-lock

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

Follow-up executável que NÃO exige decisão do owner = standing yes. A IA não pergunta "quer que eu faça?"; implementa (inline) ou enfileira em ticket e segue. Só sobe ao owner o que é genuinamente dele: decisão (owner-decision), aquisição de ativo (asset-acquisition) ou ação destrutiva/irreversível.

follow-up-autonomy

Ciclo de vida de todo gate de conformância na Koder Stack: como um check vira gate, o budget de falso-positivo obrigatório, o escape hatch auditado e a demoção automática. Operacionaliza stack-RFC-014 R3–R5. Um gate só recebe `block` depois de soak advisory→warn; todo `block` carrega `fp_budget`; estourar o budget demove pra `warn` e abre ticket de recalibração no componente dono. Sem esta policy, gates viram cultura de bypass.

gates

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 execução **pesada** — teste, build/compilação, packaging, publicação/release (pipeline de CI), ISO, benchmark, simulação ou qualquer cenário que possa travar/consumir excessivamente o host (CPU, RAM, swap, GPU, IO, kernel) — acontece em uma **VM 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.). As VMs **incus-backed** (Linux) são criadas via `klease create --ttl` (`infra/net/lease`) e reclamadas por TTL pelo `koder-leased` — ver §R2; isto fecha o problema da VM órfã. QEMU/KVM (Windows/Android) e Docker seguem provisionamento direto até o backend kbox do lease cobri-los.

heavy-work-isolation

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

Como toda IA apresenta uma LEVA de ícones candidatos pro owner escolher (aprovar/reprovar/excluir). Três invariantes duráveis: (1) a engenharia de ícones é obrigatória ANTES de apresentar — products.kmd + inscribed-glyph + ui-symbols + paleta KDS + `kicon validate/normalize`; (2) a leva vira um BATCH durável em meta/brand/icons/candidates/<id>/ com manifest.toml, IDs estáveis e bank.meaning; (3) a SUPERFÍCIE de revisão é a galeria de triagem padrão — não folhas PNG ad-hoc. A superfície é um ponteiro trocável: hoje a ponte triage-gen.py, amanhã os murais do Imago (imago#032). Resolve o sintoma recorrente: levas inconsistentes, ícones cortados, IDs renumerados, sem checagem claro/escuro.

icon-batch-presentation

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

Como toda IA apresenta uma LEVA de NOMES candidatos pro owner escolher (aprovar/reprovar/excluir/guardar-pra-reuso). O irmão da icon-batch-presentation, pra nomes em vez de ícones. Três invariantes duráveis: (1) a spec de naming é rodada ANTES de apresentar — colisão exact-match no component-names registry (R2/T3-T5) + regra de slug R4 — então a leva é confiável, não chutada; (2) os candidatos viram um BANCO durável (meta/brand/names/bank.json) com status por nome, e um nome reprovado pra um componente fica `available` e ressurge no próximo; (3) a SUPERFÍCIE de revisão é a página de triagem padrão (hoje name-triage.py serve) — não tabelas ad-hoc no chat toda vez. Resolve o sintoma recorrente: muitas levas de nomes até escolher, nomes bons perdidos, colisões não checadas.

name-batch-presentation

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

Todo componente Koder nasce instrumentado: structured logs, métricas (RED/USE), e traces distribuídos, correlacionados por um único `trace_id` que atravessa surfaces e serviços. Não se enxerga produção por acaso — instrumentação é parte do "done", não retrofit pós-incidente. Alerta em sintoma (SLO burn), nunca em causa ruidosa. Cardinalidade tem orçamento. Telemetria nunca vaza PII nem cruza tenant. Backend é o stack self-hosted em `infra/observe/`, não SaaS externo. É a dimensão D8 da rubrica de Solidez Arquitetural (`architecture-quality.kmd`) graduada a disciplina própria.

observability-first

Toda lista acionável que a IA coleta ou gera para o owner avaliar visualmente — tópicos/tarefas extraídos de chats (WhatsApp/Telegram), e batches de candidatos pra triagem (ícones, nomes, …) — DEVE ser apresentada no Operator Cockpit, nunca numa página/servidor ad-hoc. O comando que produz a lista termina exibindo a URL clicável do cockpit no chat.

operator-cockpit-standard-surface

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

Qualquer arquivo **temporário, scratch, experimento, render intermediário, dump, cache one-off ou artefato descartável** gerado por uma IA (Claude/Codex/ Gemini/Kimi/aider/plandex/etc.) ou por um processo seu DEVE ser criado **única e exclusivamente** dentro de `~/temp/`, num subdiretório descritivo que a IA escolher (ex.: `~/temp/<tarefa>-<YYYY-MM-DD>/`). **Nunca** soltar scratch na raiz da home (`~`), em `~/dev/` (acima do monorepo) ou dentro de um componente do monorepo. Motivo: scratch solto na home/dev acumula como entulho invisível, polui `git status`, vaza entre contas migradas e mistura-se com conteúdo real do owner. Esta policy nasceu da limpeza forense de 2026-06-11, que achou ~3 MB de scratch de IAs antigas (aider, plandex, CLI "Kode", roteador LLM, spinners, grids de ícone) largados em `~/dev` e `~` ao longo de mar–jun/2026.

scratch-location

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

Toda solução self-hosted da Koder Stack que importa conteúdo externo — bases de dados (geodados, células, endereços, modelos), pacotes espelhados, ou informação colhida da internet (rankings, radares, pesquisas) — deve ser PROJETADA, desde o primeiro slice, com uma estrutura de atualização periódica desse conteúdo: refresh incremental agendado, versionamento+rollback dos snapshots, métrica de frescor com alerta de SLA, e radar de fontes quando a fonte externa evolui. Complemento temporal da self-hosted-first: os 5 gates decidem SE self-hosteamos; esta policy garante que o que foi self-hosteado não apodrece. Diretiva do owner 2026-06-11 (sessão rastreador.crescer.net), ticket de origem projects/koder-stack#191.

self-hosted-data-refresh

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

This policy was renamed `test-host-isolation` → `heavy-work-isolation` on 2026-05-24. The slug "test" was too narrow: the principle isolates ANY heavy/long/destabilizing host work (test, build, compile, package, publish/CI, ISO, benchmark, simulation), not just tests.

test-host-isolation

Runbook para a ação "teste a iso" (Koder Kodix): 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