pal-e-docs

Review: API Projects/Repos/Tags/Search -- 8 endpoints

review-1569-2026-06-22 Review

review ready
Project

Verdict: APPROVED

Round 2 review of board item #1569 (paldocs#59). Issue body updated from Round 1: removed search_notes overlap with #57, added explicit AC for all 8 endpoints, arch-rails-api note confirmed to exist. Scope is clean and agent-ready.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- decomposed from paldocs#51
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- MCP layer needs Rails endpoints
  • [x] Context -- sub-ticket 3, search_notes overlap clarified
  • [x] File Targets -- 4 controllers + routes.rb
  • [x] Feature Flag -- none (additive API routes)
  • [x] Acceptance Criteria -- 8 items, one per endpoint
  • [x] Test Expectations -- request specs + integration + stub verification
  • [x] Constraints -- JSON format, no jbuilder, 501 stub
  • [x] Checklist -- 9 items
  • [x] Related -- project, story, arch, upstream/sibling/downstream all linked

Traceability

  • [x] story:consolidation label -- story-paldocs-consolidation
  • [x] story note verified -- found in project-paldocs user-stories section
  • [x] arch:rails-api label -- arch-rails-api
  • [x] arch note verified -- arch-rails-api note exists in pal-e-docs (note id 2094)
  • [x] Forgejo issue -- paldocs#59, state: open

File Targets

  • [x] app/controllers/api/projects_controller.rb -- does not exist yet (will be created). Parent dir app/controllers/api/ also does not exist yet, will be created by #57 (API namespace dependency)
  • [x] app/controllers/api/repos_controller.rb -- does not exist yet (will be created)
  • [x] app/controllers/api/tags_controller.rb -- does not exist yet (will be created)
  • [x] app/controllers/api/search_controller.rb -- does not exist yet (will be created)
  • [x] config/routes.rb -- exists, currently has no api namespace. Will be modified (api namespace added by #57 first)
  • [x] Models verified: Project, Repo, Tag models all exist in app/models/
  • [x] "Do not touch" boundaries clear: base_controller.rb (#57), notes_controller.rb (#57), existing UI controllers, models

Repo Placement

OK. Issue filed on ldraney/paldocs, all work targets paldocs. Single-repo change.

Dependencies

  • paldocs#49 (Schema ownership transfer) -- in_progress on board. Required for model scopes. Board item #1559.
  • paldocs#57 (API namespace + Notes controller) -- backlog on board. Creates the api/ directory, base_controller.rb, and api namespace in routes. Board item #1567. This ticket MUST complete before #59 can start.
  • paldocs#58 (Boards API) -- sibling, no ordering dependency. Board item #1568.
  • paldocs#61 (Hybrid search) -- downstream, fills the semantic stub. Board item #1570.
  • paldocs#54 (Paldocs MCP server) -- downstream consumer of these endpoints. Board item #1564.
Dependencies are well-documented in the issue body (Lineage + Related sections).

Acceptance Criteria

All 8 AC are verifiable by an agent via curl/rspec. Each criterion maps to exactly one endpoint. The 501 stub criterion for semantic search is testable (check status code + message). No ambiguous or untestable criteria.

Blast Radius

Low. All changes are additive API routes under /api/ namespace. No existing UI controllers or views are modified. The "Do not touch" section explicitly protects existing code. The semantic search stub (501) is a safe placeholder -- downstream #61 fills it later.
The arch-rails-api note currently shows ProjectsController as "GET /api/projects" only. This ticket expands it to include POST and DELETE. The arch note should be updated after implementation to reflect the full CRUD surface -- but this is normal post-merge documentation, not a scope issue.

Decomposition Assessment

4 file targets (controllers) + 1 routes file, all in 1 repo. 8 AC. Estimated agent time: ~3-4 minutes. The controllers are small (1-3 endpoints each), follow the same pattern, and are all in the same directory. No decomposition needed despite 8 AC -- the work is repetitive boilerplate, not complex logic.

Recommendation

  • [BODY] Update Forgejo issue title from "9 endpoints" to "8 endpoints" to match the body (search_notes was removed in Round 2 update). Current title: "API Projects, Repos, Tags, Search controllers -- 9 endpoints for MCP"
  • [LABEL] Board item #1569 title also says "9 endpoints" -- update to match
These are cosmetic title sync issues only. Scope is APPROVED as-is.