pal-e-docs

Review: Phase status → board item column sync on note update

review-1600-2026-06-24 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Spike #75 (PR #76) — Gap 9
  • [x] Repo — ldraney/paldocs
  • [x] User Story — well-formed As-a/I-want/So-that
  • [x] Context — clear explanation of pal-e-docs vs Rails gap
  • [x] File Targets — 3 targets listed
  • [x] Feature Flag — none (correct, internal model change)
  • [x] Acceptance Criteria — 3 criteria
  • [ ] Test Expectations — ISSUE: run command uses Minitest convention (bin/rails test test/requests/api/notes_*) but project uses RSpec. Correct command: bundle exec rspec spec/requests/api/notes_spec.rb
  • [x] Constraints — 2 constraints listed
  • [x] Checklist — standard 3-item
  • [x] Related — references project and spike

Traceability

  • [x] story:consolidation label — story-paldocs-consolidation
  • [x] story note verified — found in project-paldocs user-stories section: "absorb pal-e-docs into Rails monolith (schema, API, embeddings)"
  • [x] arch:rails-api label — rails-api component
  • [ ] arch note MISSING — [SCOPE] search for "arch-rails-api" returned no results in pal-e-docs. Create architecture note arch-rails-api for the Rails API component.
  • [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/ldraney/paldocs/issues/79, open

File Targets

  • [x] app/controllers/api/notes_controller.rb — verified: exists at HEAD (commit 311f4a4). Update action at lines 167-233 handles status changes (lines 197-199) but has no board item sync logic. This is the correct location for the change.
  • [x] app/models/board_item.rb — verified: exists at HEAD. Currently has COLUMNS constant and basic associations but no status-to-column mapping method. Correct location for the class method.
  • [x] Reference: pal-e-docs/src/pal_e_docs/routes/notes.py (_status_to_column) — verified: function at line 310, STATUS_TO_COLUMN dict at line 302. Mapping: not-started→backlog, in-progress→in_progress, completed→done, deferred→done, nil→backlog.

Repo Placement

OK — issue filed on ldraney/paldocs, all file targets are in ldraney/paldocs. Reference to pal-e-docs is read-only (pattern to match). Single-repo change.

Dependencies

  • Depends on #57 (API namespace + Notes controller) — DONE, merged as commit 311f4a4.
  • Related to Spike #75 (MCP compatibility analysis) — currently in_progress on the board. This ticket was born from that spike's Gap 9 finding. Not a hard blocker — the gap is well-defined and the fix is standalone.
  • No other board items blocked by this ticket.

Acceptance Criteria

  • [x] AC1: "When a phase note's status changes via PATCH /api/notes/:slug, the linked board_item column updates" — testable via request spec. The board_item links to notes via note_slug column in the board_items table.
  • [x] AC2: "Status-to-column mapping matches pal-e-docs behavior" — testable via unit test against the STATUS_TO_COLUMN dict (4 mappings + nil default).
  • [x] AC3: "Non-phase notes are unaffected" — testable via negative request spec (update a doc note's status, verify no board_item changes).
All criteria are agent-verifiable. Test commands need correction (see recommendation).

Blast Radius

Low blast radius. The change adds logic to the update action only. The BoardItem model gains a pure class method. No existing behavior is modified — the sync is additive. The board_items table already has a note_slug column used by pal-e-docs for exactly this purpose.
No similar gap exists in other controllers — only the API notes controller handles status updates via JSON API.

Decomposition Assessment

No decomposition needed. 2 file targets in 1 repo, 3 acceptance criteria, estimated agent work well under 5 minutes. Single focused change.

Recommendations

  • [BODY] Fix test run command: bin/rails test test/requests/api/notes_* → bundle exec rspec spec/requests/api/notes_spec.rb
  • [SCOPE] Create architecture note arch-rails-api for the Rails API component in pal-e-docs. This note should document the API namespace, controller hierarchy, authentication approach, and endpoint inventory.