docs+tests(sort-order): update for code-binding order on stories/tasks

- Rewrite docs/patterns/sort-order.md: float-insertion PBI only; story/task
  sort_order = parseCodeNumber(code), never drag/membership mutated
- Update plan-to-pbi-flow.md: sort_order auto, sprint_id param, priority=label
- Update make-plan.md: priority=label, array order = execution order
- Update rest-contract.md: fix sprint-tasks ordering, remove reorder endpoint
- Add ADR-0011: code is bindende volgordesleutel voor stories/taken
- Regenerate docs/INDEX.md via npm run docs
- Remove reorderStoriesAction/reorderTasksAction mocks from backlog tests
- Remove dnd-kit mocks from task-panel test (panel no longer uses dnd)
- Extend materializeIdeaPlanAction test: assert sort_order=parseCodeNumber(code)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scrum4Me Agent 2026-05-14 18:13:42 +02:00
parent 3a5aba2824
commit 3a7141114c
9 changed files with 150 additions and 76 deletions

View file

@ -0,0 +1,58 @@
# 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