# ADR-0011: code is de bindende volgordesleutel voor stories en taken; priority is label

## Status

accepted

## Context

Vóór dit besluit werden stories en taken geordend op `[priority ASC, sort_order ASC]`.
Gebruikers konden de volgorde via drag-and-drop aanpassen (float-insertion in `sort_order`).
Dit leidde tot meerdere problemen:

1. **Onvoorspelbare uitvoervolgorde voor de AI-agent**: een agent die taken aanmaakt via
   `create_task` (in call-volgorde) zag die volgorde ongedaan gemaakt zodra een andere
   agent of gebruiker de `priority` aanpaste.
2. **Divergentie tussen `code` en `sort_order`**: `code` reflecteerde de aanmaak-volgorde
   (`T-1`, `T-2`, …), maar `sort_order` kon na herordening compleet anders zijn.
3. **DnD-reorder voor stories/taken was overbodig**: de enige betekenisvolle volgorde voor
   een AI-gedreven sprint is de creatie-volgorde van taken — handmatige herordening voegde
   verwarring toe zonder toegevoegde waarde.

## Beslissing

- **`code` is de bindende volgordesleutel** voor stories en taken.
- **`sort_order` is een numerieke spiegel van `code`**, berekend via `parseCodeNumber(code)`
  uit `lib/code.ts`. Hierbij extraheert `parseCodeNumber` het trailertal van de code-string
  (bijv. `"ST-042"` → `42`, `"T-7"` → `7`).
- **`sort_order` wordt automatisch gezet** bij `create` (server berekent de waarde) en bij
  code-edit (PATCH met nieuw `code`). Sprint-membership-acties laten `sort_order` ongemoeid.
- **Drag-and-drop herordening van stories en taken is verwijderd.** Enkel PBI-ordering
  gebruikt nog float-insertion (zie ADR-0002).
- **`priority` is een puur label** (urgentie-aanduiding voor de gebruiker). Geen enkele
  `orderBy` op stories of taken gebruikt nog `priority`.

## Gevolgen

### Positief

- De uitvoervolgorde van taken is deterministisch en gelijk aan de aanroep-volgorde van
  `create_task` — agents kunnen dit betrouwbaar afleiden zonder extra queries.
- `code` en `sort_order` zijn altijd in sync — geen divergentie meer na herordening.
- Minder complexiteit: geen reorder-route, geen reorder-server-actions, geen DnD-context
  in backlog-story-panel en task-panel.

### Negatief

- Gebruikers kunnen de volgorde van stories en taken niet handmatig herordenen via slepen.
  Volgorde aanpassen vereist nu het wijzigen van de `code` (of het aanmaken in de gewenste
  volgorde). Dit is een bewuste trade-off ten gunste van voorspelbaarheid voor de agent.
- `parseCodeNumber` retourneert `0` voor codes zonder numeriek suffix (bijv. `"CUSTOM-FOO"`).
  Zulke codes clusteren bij positie 0 — vermijdbaar door codes met een numeriek suffix te
  gebruiken.

## Zie ook

- [ADR-0002: float sort_order voor drag-and-drop (PBI-ordering)](./0002-float-sort-order.md)
- [docs/patterns/sort-order.md](../patterns/sort-order.md) — implementatiepatroon
- `lib/code.ts` — `parseCodeNumber`-helper