pal-e-docs

Review: Scaffold Rails app with landing page, contact form, and Keycloak SSO dashboard

review-1176-2026-05-08 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All required sections for a Feature issue are present and well-structured.

Traceability

  • [x] story:sso-gateway label — verified in project-pal-enterprises user-stories table (Role: Authenticated user, Metric: Single login grants access to all platform tools)
  • [x] story:landing-page label — verified in project-pal-enterprises user-stories table (Role: Visitor, Metric: Can understand services offered and submit contact form)
  • [ ] arch:rails-app label — arch note MISSING — [SCOPE] Create architecture note arch-rails-app for component rails-app
  • [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/forgejo_admin/pal-enterprises/issues/1, state: open
  • [ ] sop-keycloak-client-creation — referenced in Context and Constraints but does not exist in pal-e-docs — [SCOPE] Create SOP note sop-keycloak-client-creation

File Targets

This is a greenfield scaffold — all 14 file targets are new files to create. No existing files to verify against. File paths are well-structured and follow Rails conventions. The explicit "Files NOT relevant" section (no migrations) is a good scope boundary.
  • [x] Gemfile — standard Rails dependency file
  • [x] config/database.yml — proper for CNPG connection
  • [x] config/environments/development.rb — Rails convention
  • [x] config/initializers/omniauth.rb — correct location for OmniAuth config
  • [x] config/routes.rb — standard Rails routing
  • [x] app/controllers/pages_controller.rb — valid path
  • [x] app/controllers/contacts_controller.rb — valid path
  • [x] app/controllers/sessions_controller.rb — valid path
  • [x] app/controllers/dashboard_controller.rb — valid path
  • [x] app/views/pages/home.html.erb — valid path
  • [x] app/views/contacts/new.html.erb — valid path
  • [x] app/views/dashboard/index.html.erb — valid path
  • [x] k8s/dev.yaml — follows westside-ror pattern
  • [x] app/mailers/contact_mailer.rb — valid path

Repo Placement

OK — issue is filed on forgejo_admin/pal-enterprises and all work targets the same repo. No cross-repo concerns.

Dependencies

  • Keycloak pal-e realm must exist (it does, per Context)
  • New OIDC client pal-enterprises must be registered — depends on sop-keycloak-client-creation which does not exist yet
  • CNPG cluster must allow connections from user ldraney
  • Postgres namespace NetworkPolicy must be updated to allow pal-enterprises
  • No blocking items on the board — only one other item (repo placeholder #1177)
  • References westside-ror k8s pattern — should verify that repo/pattern is accessible to implementing agent

Acceptance Criteria

10 acceptance criteria. Each is testable by an agent in principle:
  • AC 1-3: Landing page and contact form — verifiable via request specs or system tests
  • AC 4-5: Keycloak flow — requires mock or real Keycloak; integration test mentioned in Test Expectations covers this
  • AC 6-7: Dashboard access and sign-out — verifiable via controller tests
  • AC 8: Auth guard — covered by unit test expectation
  • AC 9: k8s deployment — requires cluster access, not automatable in unit tests but verifiable post-deploy
  • AC 10: Health check — verifiable via request spec
Criteria are well-written and specific. However, 10 AC across 14 files is too much for a single pass.

Blast Radius

  • pal-e-hub — this replaces it. Decommission plan not mentioned but acceptable for a greenfield ticket (decommission would be a separate ticket)
  • Postgres NetworkPolicy change could affect other services if done incorrectly — bounded risk
  • Keycloak client registration is a platform-wide SSO concern — if misconfigured, could affect existing pal-e-hub flows

Decomposition Assessment

NEEDS DECOMPOSITION — This ticket violates all three thresholds of the 5-minute rule:
  • 14 file targets (threshold: >3)
  • 10 acceptance criteria (threshold: >5)
  • Estimated agent work: 20-30 minutes across Rails scaffold, Keycloak integration, mailer setup, k8s deployment, and tests
Suggested decomposition:
  • Phase 1: Rails scaffold + landing page — Gemfile, routes, pages_controller, home view, health check, basic k8s/dev.yaml
  • Phase 2: Contact form + mailer — contacts_controller, contact view, contact_mailer, email delivery
  • Phase 3: Keycloak SSO integration — omniauth initializer, sessions_controller, auth callback, session management
  • Phase 4: Authenticated dashboard — dashboard_controller, dashboard view, auth guard, sign-out

Recommendations

  • [SCOPE] Create architecture note arch-rails-app for component rails-app
  • [SCOPE] Create SOP note sop-keycloak-client-creation (referenced in issue body but does not exist)
  • [DECOMPOSE] 14 files, 10 AC — route to skill-decompose-ticket for automated sub-ticket creation