pal-e-docs

Review: feat: add Postgres trigger to bump projects.updated_at (re-review)

review-1344-2026-06-06-r2 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review after refinement. Previous review: review-1344-2026-06-06 (NEEDS_REFINEMENT). The DDL ownership conflict -- the primary blocker -- has been resolved in the issue body. Two traceability notes claimed as created were not found in pal-e-docs.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovery context provided
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- properly formatted As/I want/So that
  • [x] Context -- clear motivation, solution approach explained, DDL ownership change explicitly documented
  • [x] File Targets -- 3 files to modify/create, 1 exclusion documented
  • [x] Acceptance Criteria -- 9 items, well-scoped (Python compatibility AC added since last review)
  • [x] Test Expectations -- 4 manual checks + run command
  • [x] Constraints -- shared DB, NULL handling, plpgsql, arch-rails-db reference
  • [x] Checklist -- present
  • [x] Related -- project + related issue #14 + arch note + story note linked

Traceability

  • [x] story:project-pages label -- present on board item
  • [ ] story note MISSING -- story-paldocs-project-pages does not exist in pal-e-docs. The project-paldocs user-stories section still reads "No user-story notes created yet." The issue body references this note in the Related section, but it was not created. [SCOPE] Create story note story-paldocs-project-pages and add entry to project-paldocs user-stories section.
  • [x] arch:rails-db label -- present on board item
  • [ ] arch note MISSING -- arch-rails-db does not exist in pal-e-docs (search returned zero results). The issue body and Constraints section both reference this note, but it was not created. [SCOPE] Create architecture note arch-rails-db documenting the DDL ownership split (Python owns table creation, Rails owns supplementary DDL like triggers/indexes).
  • [x] Forgejo issue -- ldraney/paldocs#13, state: open

File Targets

  • [x] db/migrate/YYYYMMDD_add_project_activity_trigger.rb -- db/migrate/ directory does not exist yet. This is expected: Rails will create it on first migration. The issue body now explicitly documents the DDL ownership change justifying Rails-managed migrations for triggers. config/application.rb already has dump_schema_after_migration = false and migration_error = false, which are compatible with this approach.
  • [x] bin/docker-entrypoint -- verified exists (6 lines). Currently contains comment "Shared database -- Rails does not manage migrations. Skip db:prepare." The entrypoint will need updating to run db:migrate and the comment updated. File is consistent with what the ticket describes.
  • [x] docs/data-model.md -- verified exists (129 lines). Contains "Shared Database" section (line 124) stating "all DDL is managed by the FastAPI pal-e-docs service" and "No db/schema.rb or db/migrate/ in this repo" (line 126). Both statements will need updating to reflect the DDL ownership change. File target is correct.
  • [x] app/controllers/projects_controller.rb -- verified: sort query is Project.order(updated_at: :desc) on line 3. Correctly excluded from modification targets.

Repo Placement

OK. Issue is filed on ldraney/paldocs (the Rails app). The DDL ownership change is now explicitly documented in the issue body -- Rails manages supplementary DDL (triggers, indexes) while Python continues to own table creation. This is a single-repo change.

Dependencies

  • Issue #14 (spike: audit infra/pipeline gaps) is referenced as related. It is currently in_progress on the board (item #1345). The ticket says entrypoint pattern depends on this spike, but the trigger migration itself can proceed independently. No hard blocker.
  • Item #1343 (feat: render project page note content) shares the story:project-pages label and is in backlog. No conflict -- they are independent features.

Acceptance Criteria

9 ACs, all testable by an agent. The new AC #9 ("Python pal-e-docs layer is unaffected -- trigger is transparent at the DB level") addresses the previous review's concern about Python compatibility. Test expectations include manual verification of Python API writes. The bin/rails db:migrate run command is valid. ACs are complete and verifiable.

Blast Radius

  • The Python pal-e-docs API writes heavily to the notes table (create, update, bulk operations via MCP). The Postgres trigger will fire on every Python write. The trigger is simple (bump parent project's updated_at) and should be transparent, but AC #9 and test expectation #4 now cover this verification.
  • Board items and blocks (children of notes) also represent project activity but are not covered by this trigger. This is acceptable scope -- the ticket focuses on notes as the primary activity signal. Future tickets could extend the trigger.

Decomposition Assessment

3 file targets in 1 repo, 9 acceptance criteria. The 9 ACs are at the threshold but the implementation is cohesive -- a single migration file, an entrypoint update, and a doc update. Estimated agent work is under 5 minutes. No decomposition needed.

Recommendations

  • [SCOPE] Create architecture note arch-rails-db in pal-e-docs. The issue body and Constraints section reference it, but it does not exist. This note should document the DDL ownership split: Python owns table creation (Alembic), Rails owns supplementary DDL (triggers, indexes via db/migrate).
  • [SCOPE] Create story note story-paldocs-project-pages in pal-e-docs and add an entry to the project-paldocs user-stories section. The issue references this story, but neither the note nor the project page entry exist.