Skip to main content

Task Breakdown: Taxonomy System

Feature ID: taxonomy-system Status: Done (Retrospective) Last updated: 2026-05-01

Phase 1 — Service​

  • T1. WorkTaxonomyService with categories CRUD.
  • T2. Tags CRUD on the same service.
  • T3. Collections CRUD on the same service.
  • T4. slugifyText() shared util used everywhere.
  • T5. Case-insensitive duplicate-name guard.
  • T6. Slug id immutability on update.

Phase 2 — Storage​

  • T7. YAML readers/writers for categories.yml, tags.yml, collections.yml.
  • T8. Item YAML references by slug id.

Phase 3 — Access control​

  • T9. Wire WorkOwnershipService.ensureAccess into reads.
  • T10. Wire ensureCanEdit into writes.

Phase 4 — API​

  • T11. Controller endpoints for all three entity types.
  • T12. Combined categories-tags list endpoint (returns all three dimensions in one response).
  • T13. e2e tests for each endpoint and each role.

Phase 5 — Pipeline integration​

  • T14. Standard Pipeline categorization step routes through the taxonomy service.
  • T15. Tags deduplication / normalisation happens before persisting.

Phase 6 — Web​

  • T16. Items → Categories / Tags / Collections tabs.
  • T17. CRUD modals.

Phase 7 — Observability​

  • T18. category_change, tag_change, collection_change emit Work Changelog entries.

Phase 8 — Docs​

  • T19. User-facing doc docs/features/taxonomy-system.md.
  • T20. Cross-link from collections.md and work-changelog.md.
  • T21. Retrospective spec/plan/tasks.

Definition of Done​

  • All tasks shipped, tests pass, docs present, constitution gates verified.