pal-e-docs

Review: Add page_note to project JSON response for MCP parity

review-1601-2026-06-24 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Spike #75 (PR #76) Gap 4
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- MCP consumer wants project JSON to include page_note
  • [x] Context -- pal-e-docs ProjectOut includes page_note, Rails project_json omits it
  • [x] File Targets -- app/controllers/api/notes_controller.rb
  • [x] Feature Flag -- none (appropriate for internal API field addition)
  • [x] Acceptance Criteria -- 3 criteria, all testable
  • [x] Test Expectations -- 2 unit tests + run command
  • [x] Constraints -- match PageNoteInfo shape exactly
  • [x] Checklist -- standard PR/tests/no-unrelated
  • [x] Related -- references project-pal-e-docs, Spike #75

Traceability

  • [x] story:consolidation label -- "absorb pal-e-docs into Rails monolith (schema, API, embeddings)"
  • [x] story note verified -- found as story-paldocs-consolidation in project-paldocs user-stories section
  • [x] arch:rails-api label -- references Rails API component
  • [ ] arch note MISSING -- no arch-rails-api note found in pal-e-docs. However, this is a shared label across 6+ board items on board-paldocs (e.g., #57 API namespace, #58 API Boards, #59 API Projects, #78, #79, #80, #81). Creating the arch note is a cross-cutting concern, not a blocker for this 1-point ticket. Flagged as [SCOPE] recommendation.
  • [x] Forgejo issue -- ldraney/paldocs#80, state: open

File Targets

  • [x] app/controllers/api/notes_controller.rb -- verified exists on main (commit 311f4a4). Contains project_json method at line 470 that currently omits page_note. The method serializes id, name, slug, platform, repo_url, is_public, created_at, updated_at. Adding page_note is straightforward.
  • [x] Project model -- belongs_to :page_note, class_name: "Note", optional: true confirmed in app/models/project.rb line 7. Association already exists.
  • [x] Existing tests at spec/requests/api/notes_spec.rb -- confirmed present, currently has no page_note assertions. Test run command bin/rails test test/requests/api/notes_* in the issue uses minitest path convention but the project uses RSpec (spec/ directory). Agent should use bundle exec rspec spec/requests/api/notes_spec.rb instead.

Repo Placement

OK. Issue filed on ldraney/paldocs, fix is in ldraney/paldocs. Single-repo change.

Dependencies

Depends on the API namespace (PR #66, already merged to main). No blocking items on the board. Spike #75 (in_progress, board item #1597) is the parent spike but this ticket was explicitly extracted as independent work -- no blocker.

Acceptance Criteria

  • [x] "project_json includes page_note: {id, title, slug} when project has a page note" -- testable, agent can create a project with a page_note association and assert JSON shape
  • [x] "project_json includes page_note: null when no page note" -- testable, existing project fixture has no page_note
  • [x] "Existing API specs updated to assert the new field" -- testable, clear scope
All criteria are machine-verifiable. Minor note: the test run command uses minitest convention but project uses RSpec. Agent will figure this out from the codebase.

Blast Radius

Low. project_json is called in exactly one place (note_json helper, line 442). Adding a field is additive and non-breaking. The eager-loading includes :project but not project: :page_note -- agent should add this to avoid N+1 queries (6 include sites in the controller). No downstream consumers beyond MCP clients that already expect the field from pal-e-docs.

Decomposition Assessment

1 file target, 1 repo, 3 acceptance criteria, estimated agent work under 5 minutes. No decomposition needed.

Recommendation

  • [SCOPE] Create architecture note arch-rails-api for the Rails API component. This affects 6+ tickets on board-paldocs. Not a blocker for this ticket, but should be created before the next sprint.
  • [BODY] Test run command uses minitest path: bin/rails test test/requests/api/notes_*. Project uses RSpec. Should be: bundle exec rspec spec/requests/api/notes_spec.rb. Minor -- agent will self-correct from codebase, but fixing improves template accuracy.