Spec — Backlog Ticket Numbering

Overview

A Koder Stack usa um esquema híbrido de numeração de tickets:

Layer	Forma	Onde
Disco (filename)	NNN-titulo-slug.md	<module-or-project>/backlog/{pending,in-progress,done}/
Referência cross-stack	<PREFIX>-NNN	commit message, conversa, doc, memória, outros tickets

A numeração NNN é sequencial dentro de cada backlog (não global). O prefix é único por módulo e definido na koder.toml do módulo.

Por que prefix?

A Stack tem dezenas de backlogs (módulos + projetos cross-cutting). Numeração puramente sequencial gera ambiguidade — #101 existe simultaneamente em projects/koder-stack, engines/kodec, services/ai, engines/lang/lang, infra/data/kdb e outros.

Alternativas avaliadas:

Modelo	Veredicto
Per-backlog sequencial (sem prefix)	ambíguo cross-stack
Globalmente único (#1234)	rejeitado — race conditions, perde narrativa per-módulo
Prefixed Jira-style (KSTACK-101, KTERM-42)	escolhido — inequívoco, sem coordenação central, familiar
UUID / hash / date-based	rejeitados — inhumano ou verboso

Razões da escolha:

• Inequívoco em commit messages, conversas, memórias
• Zero contador global → não cria hot file / race conditions
• Convenção familiar — todo dev reconhece PROJ-NNN (Jira/Linear/Github project keys)
• Filename no disco continua NNN-titulo.md — só a referência muda

Schema de prefix

<PREFIX> ::= [A-Z][A-Z0-9_]{1,9}

• 2–10 caracteres
• Começa com letra maiúscula
• Só letras maiúsculas, dígitos, underscore
• Único cross-stack — colisão não permitida

Exemplos válidos: KSTACK, KTERM, KIT, KODEC, LANG, KDB, JET, HUB, KODE, BOT, EYE, JET, K8S_OPS.

Exemplos inválidos: kterm (lowercase), K (curto demais), KODER-STACK (hifen), KODERSTACKPLATFORM (longo demais).

Declaração no koder.toml

Cada módulo (ou projeto cross-cutting) com backlog declara seu prefix:

[backlog]
prefix = "KSTACK"

Sem essa seção, o módulo:

• Não tem backlog (válido — nem todo módulo precisa) — no audit, OK.
• Tem <module>/backlog/ mas não declarou prefix — drift advisory.

A declaração é fonte da verdade local. O registry global (meta/docs/stack/registries/ticket-prefixes.md) é derivável dela.

Schema do filename

<module>/backlog/{pending,in-progress,done}/NNN-<title-slug>.md

• NNN — 3 dígitos (zero-padded), sequencial dentro do backlog
• <title-slug> — kebab-case, ASCII
• Extensão: .md (default), .kmd per policies/document-format.kmd, ou .kd quando o ticket é tratado como source code do módulo (ex.: engines/lang/lang/backlog/done/043-selfhost-bootstrap-self-compile.kd)

Numeração não reusa: tickets em done/ mantêm seu número; o próximo ticket pega max(existing) + 1 cruzando pending/, in-progress/, done/.

Schema de referência

Em commit messages, conversas, memórias, docs, outros tickets, a forma canônica é:

<PREFIX>-NNN

Exemplos:

• KSTACK-101, KSTACK-104
• KTERM-42
• KODEC-23
• JET-7

Forma estendida (quando precisar desambiguar contra módulo com mesmo prefix em fork/clone — raro):

<scope>/<PREFIX>-NNN

Ex.: koder/KSTACK-104. Em uso normal dentro do monorepo, scope é omitido.

Anti-patterns

#NNN casual sem prefix

Don't:

ver #101 pra contexto

Do:

ver KSTACK-101 pra contexto

Por quê: #101 é ambíguo — a leitura humana ou de IA precisa adivinhar qual módulo. O audit numbering-audit.sh reporta drift sempre que encontrar #\d+ em arquivos sob meta/, projects/*/backlog/, **/backlog/ (excluindo commits históricos via git log, que são imutáveis).

Exceção: dentro do próprio ticket, referência ao próprio número (no título, no corpo "este #104") é OK — o contexto do filename já desambigua.

Reusar números de tickets em done/

Don't: numerar próximo ticket 046 se já existe 046-foo.md em done/. Mesmo que o ticket original tenha sido cancelado, o número fica queimado.

Do: sempre max(NNN across pending/+in-progress/+done/) + 1.

Renomear filenames retroativamente pra incluir prefix

Don't: renomear 101-stack-framework.md pra KSTACK-101-stack-framework.md.

Por quê: filename no disco é NNN-...; prefix é convenção de referência, não de filename. Renomear quebra git blame/history sem benefício — quem lê o path já sabe o módulo.

Ferramenta de criação — koder-ticket

A criação de tickets (especialmente em sessões paralelas que podem race no mesmo NNN) é serializada via binário koder-ticket em dev/koder-tools/:

koder-ticket new <module> "<title>"   # cria NNN-<slug>.md atomicamente
koder-ticket list <module>            # lista tickets + status
koder-ticket move <ID> <state>        # KTERM-42 → in-progress / done
koder-ticket id <path>                # filename → KTERM-42
koder-ticket path <ID>                # KTERM-42 → filename
koder-ticket grep <text>              # busca cross-stack

Ver dev/koder-tools/koder-ticket/README.md (a criar em Fase C de KSTACK-104).

Audit

numbering-audit.sh (sibling deste arquivo) percorre o monorepo procurando:

1. Módulos com <module>/backlog/ mas sem [backlog] prefix em koder.toml
2. Filenames de ticket que não casam ^\d{3}-[a-z0-9-]+\.md$
3. Referências #\d+ casuais em arquivos sob meta/, projects/*/backlog/, **/backlog/

Severity: advisory — reporta no /k-housekeep Fase 0.5, não bloqueia commit. Drift em commits históricos é tolerado.

Migração retroativa

• Filenames no disco — não migrar; convenção é só pra referência
• Commit messages históricos — git log é imutável; aceita-se #NNN ambíguo em commits antigos
• Refs em docs/specs/policies vivos — sweep one-shot na Fase D do KSTACK-104, registrado em git
• RFCs — não tocar; já têm naming próprio (RFC-XXX)

Origem

KSTACK-104 (projects/koder-stack/backlog/in-progress/104-ticket-numbering-jira-style-migration.md). Decisão arquitetural D23 ratificada na sessão de 2026-05-01 que entregou KSTACK-101 (Stack Framework — UI Styles + Settings + Spec Audit).