Spec — Backlog Ticket Numbering

Overview

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

A numeração NNN é *equencial 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 *mbiguidade*— #101 existe simultaneamente em projects/koder-stack, engines/kodec, services/ai, engines/lang/lang, infra/data/kdb e outros.

*lternativas avaliadas:*

*azõ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 (JiraLinearGithub project keys)
• Filename no disco continua NNN-titulo.md — só a *eferê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:

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

A declaração é *onte 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)

*umeraçã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 *ommit messages, conversas, memórias, docs, outros tickets* a forma canônica é:

<PREFIX>-NNN

Exemplos:

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

*orma 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, *cope é omitido*

Anti-patterns

#NNN casual sem prefix

*on't:*

ver #101 pra contexto

*o:*

ver KSTACK-101 pra contexto

*or 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/, projectsbacklog/, **/backlog/ (excluindo commits históricos via git log, que são imutáveis).

*xceçã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/

*on'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.

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

Renomear filenames retroativamente pra incluir prefix

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

*or quê:*filename no disco é NNN-...; prefix é convenção de *eferê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/, projectsbacklog/,

   **/backlog/

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

Migração retroativa

• *ilenames no disco*— não migrar; convenção é só pra referência
• *ommit messages históricos*— git log é imutável; aceita-se

  #NNN ambíguo em commits antigos

• *efs em docsspecspolicies vivos*— sweep one-shot na Fase D do

  KSTACK-104, registrado em git

• *FCs*— não tocar; já têm naming próprio (RFC-XXX)

Origem

KSTACK104 (`projects/koderstackbackloginprogress/104ticketnumberingjirastylemigration.md`). Decisão arquitetural D23 ratificada na sessão de 20260501 que entregou KSTACK-101 (Stack Framework — UI Styles + Settings + Spec Audit).