pal-e-docs

Review: Sprint schema -- migrations + models for wave planning (round 3)

review-1560-2026-06-22-r3 Review

review ready
Project

Verdict: READY

Round 3 re-review after decomposition. All three round 2 findings are resolved: read-only contradiction removed, arch:rails-db label added, ticket decomposed into schema-only (#50) and UI (#56). Scope is tight and fits within the 5-minute rule.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- depends on paldocs#49 (schema ownership transfer)
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- well-formed As/I want/So that
  • [x] Context -- clear explanation: schema half of sprint planner dogfood, UI comes in #56
  • [x] File Targets -- 7 create/modify targets + 3 do-not-touch entries
  • [x] Feature Flag -- none (correct: new tables and model code, no impact on existing pages)
  • [x] Acceptance Criteria -- 5 criteria, all model-level
  • [x] Test Expectations -- 4 test entries + run command (bundle exec rspec)
  • [x] Constraints -- dependency documented, status values defined, nullable fields specified, unique index specified
  • [x] Checklist -- 7 items
  • [x] Related -- project, story, arch notes, upstream/downstream
All required sections for a Feature issue are present. Template is complete.

Traceability

  • [x] story:sprint-orchestration label -- present on board item #1560
  • [x] story note verified -- story-paldocs-sprint-orchestration (id 2093) exists in pal-e-docs, project paldocs
  • [x] story listed on project page -- found in project-paldocs user-stories section
  • [x] arch:rails-db label -- present on board item #1560 (added since round 2)
  • [x] arch note verified -- arch-rails-db (id 1840) exists in pal-e-docs, project paldocs
  • [x] Forgejo issue -- ldraney/paldocs#50, state: open
Traceability triangle is complete. All backing notes exist and are linked from the project page.

File Targets

  • [x] db/migrate/XXXXXX_create_sprints.rb -- new file. db/migrate/ dir exists with 2 existing migrations (20260606, 20260613)
  • [x] db/migrate/XXXXXX_create_sprint_projects.rb -- new file, same dir
  • [x] db/migrate/XXXXXX_add_sprint_fields_to_board_items.rb -- new file, same dir
  • [x] app/models/sprint.rb -- new file. app/models/ dir exists with 7 existing models
  • [x] app/models/sprint_project.rb -- new file, same dir
  • [x] app/models/board_item.rb -- exists. Currently has COLUMNS constant, belongs_to :board, and column validation. Issue correctly describes adding sprint/wave associations and scopes
  • [x] app/models/project.rb -- exists. Currently has has_many :notes, :repos and belongs_to :page_note. Issue correctly describes adding has_many :sprint_projects, :sprints through
  • [x] db/structure.sql do-not-touch -- correct, file does not exist yet (awaits paldocs#49)
  • [x] app/controllers/ do-not-touch -- correct, UI is paldocs#56
  • [x] app/views/ do-not-touch -- correct, UI is paldocs#56
All file targets verified. Existing files match what the issue describes. New files target valid parent directories. The do-not-touch boundaries correctly exclude controller/view/route work (split to #56).

Repo Placement

OK. Issue filed on ldraney/paldocs, all file targets are within paldocs repo. Single-repo change.

Dependencies

  • paldocs#49 (schema ownership transfer) -- explicitly documented as upstream dependency. Board item #1559 is in todo column. This ticket cannot start until #49 merges (needs structure.sql and migration infrastructure). Correctly documented in both Lineage and Constraints.
  • paldocs#56 (sprint planning UI) -- explicitly documented as downstream. Board item #1566 is in backlog. #56 depends on this ticket for models and schema. Correctly documented.
  • No circular or undocumented dependencies found.

Acceptance Criteria

5 acceptance criteria, all in When/Then format. Assessment:
  • [x] AC 1: Sprint.create with correct defaults -- model-testable via unit spec
  • [x] AC 2: sprint.projects returns selected projects -- model-testable via association spec
  • [x] AC 3: BoardItem.where(sprint:, wave_number:) scoping -- model-testable via scope spec
  • [x] AC 4: sprint.board_items returns tagged items -- model-testable via association spec
  • [x] AC 5: Sprint status scopes (.planning, .active, .complete) -- model-testable via scope spec
  • All criteria are purely data-layer and verifiable with rspec-rails (confirmed in Gemfile). No UI criteria -- correctly split to #56.
  • No contradictions found (round 2 read-only constraint removed).

Blast Radius

  • BoardItem model changes -- adding sprint_id (FK) and wave_number columns. Both nullable, so existing BoardItem usage in boards_controller.rb, board_items_controller.rb, and views is unaffected. No existing queries filter on these columns.
  • Project model changes -- adding has_many :sprint_projects. Existing associations (notes, repos, page_note) are unaffected.
  • No controller/view/route changes -- schema-only ticket, blast radius is minimal.
  • No similar patterns in sibling services affected.

Decomposition Assessment

No decomposition needed. Post-decomposition scope is within bounds:
  • File count: 7 file targets (3 new migrations + 2 new models + 2 model modifications)
  • AC count: 5 acceptance criteria
  • Test count: 4 test expectations
  • Estimated agent work: Under 5 minutes -- migrations and model code are formulaic Rails patterns
  • All three axes are within the 5-minute rule thresholds.

Round 2 Issues Resolution

  • [x] [BODY] Read-only v1 contradiction -- RESOLVED. Constraint removed. All AC are write operations (create, set, query). No contradiction.
  • [x] [LABEL] arch:rails-db label -- RESOLVED. Board item #1560 now has labels: type:feature,story:sprint-orchestration,arch:rails-db.
  • [x] [DECOMPOSE] Split schema from UI -- RESOLVED. This ticket (#50) is schema+models only. UI split to #56 (board item #1566).

Recommendation

No action needed. Ticket is ready for implementation.