Policy — Implementation Backlog

The monorepo uses a *wo-level backlog structure*

• *odule-level*(<module>/backlog/) — work scoped to a single component (features, bugs, integrations). Lives inside the module it tracks.
• *rojectlevel*(projects/<project>/backlog/) — crosscutting 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, *efore 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 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 *wo views of the same fact*— they must agree at all times.

*nvariants:*

1. Whenever a ticket transitions, *oth*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.

*ntipattern (history):*`infradatakdbbacklogdone/046opentelemetryinstrumentation.kmd was filed in done/` while the body explicitly said "kdbnext: PARCIAL, Go kdb: AUSENTE" and frontmatter said Status: pending. The misfile was caught manually during /k-evolve infra/data/kdb (20260509) and the file was moved back to pending/ — this rule formalizes that fix.

*hen 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.

Numbering

Sequential per backlog (001, 002, 003, ...). *efore opening a new ticket* list existing NNN-* files across pending/, in-progress/, and done/ to avoid colliding with another parallel session that may have claimed the same number.

For crossstack references (commit messages, conversations, memories, docs, other tickets), use the *irastyle prefixed form*<PREFIX>-NNN (e.g. KSTACK-104, KTERM-42). The filename on disk stays NNN-titulo.md; the prefix is a convention for *eference only* Each moduleproject with a backlog declares its prefix in [backlog] prefix in its koder.toml and is listed in `metadocsstackregistries/ticket-prefixes.md`.

See specs/backlog/numbering.kmd for the full schema, anti-patterns, and audit rules.

Cross-stack references

When a ticket, doc, policy, or memory needs to refer to a ticket in another module:

Antipattern: #101 written in CLAUDE.md, in a memory file, in a commit message that touches multiple modules, or in a doc under meta/docs/stack/. The `numberingaudit.sh` reports this as drift advisory.

Ticket Template

# NNN — Title

- **Date:** YYYY-MM-DD
- **Priority:** alta|média|baixa
- **Status:** pending|in-progress|done

## Pedido

(description of what the user asked for)

## Notas de implementação

(filled during/after implementation)

Rationale

Module backlogs are the authoritative source for "what was planned vs what was done" in each component — they survive session handoffs, parallelsession coordination, and context loss. Project backlogs provide the same guarantees for multimodule initiatives that would otherwise have no natural home.