ADR-0020: Kanban Entity Model — Lanes as Config, Review Queue as View
Context
ADR-0019 established pull-based kanban over sprint iterations for agent teams. It proposed three new entity types: `milestone`, `review_queue`, and `lane`. Implementation analysis revealed that these three concepts have fundamentally different natures that should drive different implementations.
The key question: which kanban concepts are knowledge artifacts (authored, searched, linked, versioned) and which are operational infrastructure (configuration, computed state)?
Decision
Milestone: entry type (knowledge artifact)
Milestones are real knowledge. People write them ("what does this release deliver?"), link backlog items to them, reference them in ADRs, track completion percentage. A milestone has a title, a body describing the goal, links to constituent items, and a status.
Implementation: New `milestone` entry type in software-kb extension with fields: `status` (open/closed), linked backlog items (via standard `links` frontmatter). Completion percentage computed from linked item statuses.
Lane: board configuration (not an entry type)
Nobody authors a lane as a knowledge entry. Nobody searches for a lane, links to it, or reads its body. Lanes define workflow topology — they're board configuration that changes rarely. Creating individual markdown files for "Backlog", "In Progress", "Review", "Done" is make-work that produces no knowledge value.
Implementation: Board configuration in KB settings (YAML in kb config or a `board.yaml` file). Defines lane names, ordering, WIP limits, and transition policies. The kanban board (CLI and UI) reads this config to render columns and enforce limits.
Example board config: ```yaml board: lanes: - name: Backlog statuses: [proposed, planned] - name: Ready statuses: [accepted] - name: In Progress statuses: [in_progress] wip_limit: 5 - name: Review statuses: [review] wip_limit: 3 - name: Done statuses: [done, completed] wip_policy: warn # warn | enforce ```
Lanes map to existing backlog item statuses. No new status values needed — the board config groups statuses into visual lanes. This means the kanban view works immediately with existing backlog items.
Review queue: computed view (not an entry type)
A review queue is a query result: "backlog items in review status, sorted by wait time, with WIP context." Nobody authors review queue entries. The queue is computed on demand from current backlog state.
Implementation: CLI command (`pyrite sw review-queue`), MCP tool (`sw_review_queue`), and API endpoint that query backlog items in review-mapped statuses. The board config's WIP limit for the review lane provides the capacity constraint.
Standard type split: prerequisite
Per ADR-0019, `standard` splits into `programmatic_validation` (has a check command, pass/fail) and `development_convention` (judgment-based guidance). This must happen before `sw_validate` can work — the tool needs to know which entries define automated checks.