janpeter/Scrum4Me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/docs/adr/0011-code-volgordesleutel-stories-taken.md
Janpeter Visser ff22196714
Sprint: Stories en taken krijgen één voorspelbare volgorde gekoppeld aan hun code; drag-and-drop herordening voor stories/taken verdwijnt, priority wordt puur label. (#201) 
* feat(code): add parseCodeNumber helper to lib/code.ts

Pure helper that extracts the trailing numeric sequence from a code string
(ST-007 → 7, T-42 → 42). Non-conforming codes fall back to Number.MAX_SAFE_INTEGER
so they sort to the end. Includes 5 unit tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(tasks): add code field to BacklogTask type and all task selects

Adds `code: string | null` to BacklogTask interface and includes it in
all Prisma task.findMany selects (backlog API, stories tasks API, page
hydration routes). Updates coerceTaskPayload and test fixtures to match.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(sort-order): derive story/task sort_order from parseCodeNumber(code)

All create paths (createStoryAction, saveTask, createTaskAction,
materializeIdeaPlanAction) and code-edit paths (updateStoryAction, saveTask
update) now set sort_order = parseCodeNumber(code) instead of last+1.
Removes stale last-record queries from create paths.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(sort-order): decouple sprint membership actions from sort_order

createSprintAction and addStoryToSprintAction no longer write sort_order
when adding stories to a sprint. sort_order is derived from code via
parseCodeNumber, so membership should only set sprint_id + status.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(ordering): remove priority from all story/task orderBy

Story- en taak-ordering is nu puur sort_order asc (created_at als
tiebreaker). PBI-ordering (priority + sort_order) blijft ongewijzigd.

Gewijzigd: backlog/route, pbis/stories/route, claude-context/route,
next-story/route, workspace/route, tasks/route, sprint-runs (query +
in-memory sort), solo-workspace-server, page.tsx (app + mobile + sprint),
store compareStory, actions/sprints story-query, next-story test.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* refactor(dnd): remove drag-and-drop reorder for stories and tasks

- Remove reorderStoriesAction, reorderTasksAction, reorderSprintStoriesAction
- Delete REST route app/api/stories/[id]/tasks/reorder/route.ts
- Remove DnD from backlog story-panel and task-panel (flat list)
- Remove reorder-within-sprint branch from sprint-board-client handleDragEnd
- Switch SortableSprintRow to plain SprintRow using useDraggable (membership drag kept)
- Remove all DnD from task-list (status toggle + edit kept)
- Remove story-order/task-order/sprint-story-order/sprint-task-order mutation types and store handlers
- Remove related tests for deleted reorder route; fix sprint store tests

* feat(backlog): toon code-badge op backlog-taakkaarten

Geeft code={task.code} door aan <BacklogCard> in TaskCard (task-panel.tsx).
BacklogCard rendert de CodeBadge al conditionally — alleen de prop ontbrak.

* feat(migration): backfill story/task sort_order from code numeric suffix

One-time Prisma migration that sets sort_order = trailing numeric part
of code for all existing stories and tasks, consistent with
parseCodeNumber (fallback = Number.MAX_SAFE_INTEGER for non-conforming
codes). PBIs are intentionally excluded.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 19:02:36 +02:00

2.8 KiB
Raw Blame History

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