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.

The monorepo uses a two-level backlog structure:

  • Module-level (<module>/backlog/) — work scoped to a single component (features, bugs, integrations). Lives inside the module it tracks.
  • Project-level (projects/<project>/backlog/) — cross-cutting initiatives that span multiple modules or have no single module home. Lives in the monorepo root projects/ directory.

Module-level Backlog

When the user asks to implement something in a product repository, before implementing:

  1. Create the ticket in <module>/backlog/pending/NNN-title-slug.md and commit.
  2. When starting implementation, move the file to <module>/backlog/in-progress/ and commit.
  3. When finished and user-approved, move to <module>/backlog/done/ and commit.

Directory Structure

<module>/backlog/
  pending/
  in-progress/
  done/

Project-level Backlog

For cross-cutting work, use projects/<project>/backlog/. Current projects:

Project Path Covers
koder-stack projects/koder-stack/backlog/ Stack-wide maintenance: housekeep, spec rollouts, landing pages, doc audits
kode-model projects/kode-model/backlog/ Kode AI model training: hardware, data, fine-tuning, eval, modalities
kode-relay projects/kode-relay/backlog/ Kode Relay server: protocol, session management, account managers, deploy
kode-cli projects/kode-cli/backlog/ Kode CLI client: TUI, auth, tool execution, feature parity
infra-gchat projects/infra-gchat/backlog/ GChat bridge: bot setup, groups, avatar, feature parity
koder-kit projects/koder-kit/backlog/ SDK base + IPC inter-app: spec do protocolo, koder_kit Flutter, bindings por linguagem/plataforma
google-workspace projects/google-suite/backlog/ Integração Google Workspace: Gmail connector, Drive connector, OAuth SSO, Kompass org sync, Keys OAuth vault

Project backlogs use the same pending/in-progress/done/ structure and NNN numbering as module backlogs.

To add a new project: create projects/<slug>/backlog/{pending,in-progress,done}/ and document it in this table.

Status ↔ location consistency (KDB-321)

The Status: field in the frontmatter and the directory the file lives in are two views of the same fact — they must agree at all times.

Status: Required directory
pending backlog/pending/
in-progress backlog/in-progress/
done backlog/done/

Invariants:

  1. Whenever a ticket transitions, both must change in the same commit. Updating one without the other is a misfile.
  2. The directory is the source of truth for tooling that can't read frontmatter (e.g. git ls-files | grep done/). The frontmatter is the source of truth for tooling that follows file moves across renames.
  3. CI lint: koder-spec-audit backlog --check-status-location walks every backlog/{pending,in-progress,done}*.{md,kmd} and fails when a file's directory disagrees with its Status: field.

Anti-pattern (history): infra/data/kdb/backlog/done/046-opentelemetry-instrumentation.kmd was filed in done/ while the body explicitly said "kdb-next: PARCIAL, Go kdb: AUSENTE" and frontmatter said Status: pending. The misfile was caught manually during /k-evolve infra/data/kdb (2026-05-09) and the file was moved back to pending/ — this rule formalizes that fix.

When closing a ticket whose work is partial: do not move to done/ to "clean it up". Either keep it in pending/`in-progress and split off a follow-up ticket for the remainder, or close as done` only when the body honestly declares the partial scope as complete.

Gated tickets — non-actionable for an external reason (gated_by:)

A pending/ ticket whose work an AI session cannot advance right now for a named external reason carries a gated_by: frontmatter field. It stays in pending/ (it is unfinished work, not done; a separate directory would become a graveyard and would break every `pending