pal-e-docs

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

review-1569-2026-06-23 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Feature Flag
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All required sections for the Feature template are present.

Traceability

  • [x] story:consolidation label -- story-paldocs-consolidation
  • [x] story note verified -- found in project-paldocs user-stories section
  • [x] arch:rails-api label -- rails-api component
  • [ ] arch note MISSING -- [SCOPE] Create architecture note arch-rails-api in pal-e-docs. Search returned zero results.
  • [x] Forgejo issue -- paldocs#59, open

File Targets

  • [x] app/controllers/api/projects_controller.rb -- to be created (directory exists via #57 merge at 311f4a4)
  • [x] app/controllers/api/repos_controller.rb -- to be created
  • [x] app/controllers/api/tags_controller.rb -- to be created
  • [x] app/controllers/api/search_controller.rb -- to be created
  • [x] config/routes.rb -- exists, API namespace already present from #57
  • [x] Do-not-touch list (base_controller.rb, notes_controller.rb, models, views) -- correct
ISSUE: The constraint says "list_projects defaults to active projects only (uses scope from #49)" but the projects table has NO status column. Schema columns: id, name, slug, platform, repo_url, created_at, is_public, page_note_id, updated_at. The model defines scope :active, -> { where(status: "active") } which will raise ActiveRecord::StatementInvalid at runtime. The agent implementing this ticket will be blocked on AC #1.

Repo Placement

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

Dependencies

  • paldocs#49 (schema ownership) -- closed/done. Upstream satisfied.
  • paldocs#57 (API namespace + notes controller) -- closed/done. Commit 311f4a4 merged. Base controller and API namespace exist in routes.
  • paldocs#58 (boards API) -- backlog, sibling. No blocking dependency. Can proceed in parallel.
  • paldocs#61 (hybrid search) -- backlog, downstream. Will fill the semantic stub. No block.
  • paldocs#52 (embedding pipeline) -- done. Needed for #61, not #59.
Dependencies correctly documented. No undocumented dependencies found.

Acceptance Criteria

8 AC, all verifiable via request specs. Test expectations match (request specs for all 8, integration test for project CRUD, 501 stub check). Run command bundle exec rspec is correct. Existing spec at spec/requests/api/notes_spec.rb provides the pattern.
AC #1 ("GET /api/projects returns active projects by default") will fail due to missing status column on projects table.

Blast Radius

Low risk. Additive API controllers in dedicated namespace. No existing UI controllers modified. The JSON response format constraint ("match pal-e-docs exactly") is achievable -- Notes controller already uses render json with helper methods. The scope :active bug on Project model exists in HEAD but no code currently calls it.

Decomposition Assessment

4 new controller files + routes change in 1 repo. 8 AC. Estimated agent work: 3-4 minutes. Within the 5-minute rule. No decomposition needed.

Recommendations

  • [BODY] Fix constraint and AC #1: the projects table has no status column. Either (a) add a file target for a migration adding status varchar(50) DEFAULT 'active' to projects, or (b) change the constraint to filter by is_public instead and update AC #1 to say "returns public projects by default." Also fix the existing scope :active on Project model to match whichever approach is chosen.
  • [SCOPE] Create architecture note arch-rails-api in pal-e-docs. This label is shared by 4 board items (#57, #58, #59, #61) and currently has no backing note.