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:
parent
3a5aba2824
commit
3a7141114c
9 changed files with 150 additions and 76 deletions
58
docs/adr/0011-code-volgordesleutel-stories-taken.md
Normal file
58
docs/adr/0011-code-volgordesleutel-stories-taken.md
Normal 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue