pal-e-docs

Review: Upgrade Ruby, Keycloak, and OmniAuth versions

review-1182-2026-05-09 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, discovered during scaffold
  • [x] Repo — ldraney/pal-enterprises
  • [x] User Story — present, well-formed
  • [x] Context — thorough, includes version table
  • [x] File Targets — present with modify/don't-touch lists
  • [x] Acceptance Criteria — 5 criteria
  • [x] Test Expectations — 5 items with run command
  • [x] Constraints — 4 constraints listed
  • [x] Checklist — present
  • [x] Related — present
All required sections for the Feature template are present.

Traceability

  • [x] story:infra-upgrades label — present on board item
  • [ ] story note MISSING — [SCOPE] The project-pal-enterprises user-stories section has entries for landing-page, sso-gateway, and tool-dashboard, but no entry for infra-upgrades. Create user story entry on project-pal-enterprises.
  • [x] arch:keycloak label — present on board item
  • [ ] arch note MISSING — [SCOPE] No arch-keycloak note found in pal-e-docs. Create architecture note arch-keycloak for the Keycloak component.
  • [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/ldraney/pal-enterprises/issues/6, state: open

File Targets

  • [x] .ruby-version — verified: exists, currently contains ruby-3.4.8
  • [x] Gemfile — verified: exists, contains omniauth stack (omniauth_openid_connect, omniauth-rails_csrf_protection)
  • [x] Gemfile.lock — verified: exists, shows omniauth 1.9.2 (matches issue's "Current" column)
  • [x] k8s/dev.yaml — verified: exists, shows image: ruby:3.4-slim at line 47
  • [x] Dockerfile — verified: exists, shows ARG RUBY_VERSION=3.4.8 and ruby:$RUBY_VERSION-slim
  • [x] pal-e-platform: terraform/modules/keycloak/main.tf — verified: exists, shows image = "quay.io/keycloak/keycloak:26.0.7" at line 100
  • [x] pal-e-services: terraform/k3s.tfvars — verified: exists, contains keycloak realm and client config
All file targets verified against the codebase. Paths are accurate and contents match what the issue claims.

Repo Placement

The Forgejo issue is filed on ldraney/pal-enterprises, which is the primary repo. However, the issue scope explicitly touches THREE repos:
  • ldraney/pal-enterprises — Ruby version, Gemfile, Dockerfile, k8s/dev.yaml
  • ldraney/pal-e-platform — Keycloak image tag in terraform
  • ldraney/pal-e-services — potential realm schema changes in terraform
[DECOMPOSE] — Three repos affected. The Keycloak upgrade (pal-e-platform) and the Ruby/OmniAuth upgrade (pal-enterprises) are independent work streams that should be separate tickets. A single agent pass cannot PR across three repos.

Dependencies

  • Keycloak upgrade (26.0.7 to 26.6.1) must be applied and verified BEFORE the OIDC auth flow can be re-tested with the new OmniAuth version.
  • The constraint "Host (archbox) Ruby also needs updating — coordinate with westside-ror and pal-e-ror" introduces an undocumented coordination dependency. Both westside-ror and pal-e-ror are currently on Ruby 3.4.8 with the same image patterns.
  • No blocking items found on the board — no other items are currently in_progress.

Acceptance Criteria

AC #1-3 are verifiable for the pal-enterprises repo. AC #4 (Keycloak admin console version) requires the pal-e-platform change to be deployed first — this is a cross-repo dependency. AC #5 (test existing westside-app and pal-e-app auth flows) is a blast-radius validation that belongs on the Keycloak upgrade ticket, not the Ruby/OmniAuth ticket.
Missing AC: No acceptance criterion for verifying gem compatibility with Ruby 4.0 (the Constraints section mentions it but there is no testable AC).

Blast Radius

  • Keycloak upgrade affects 8+ OIDC clients: westside-app, westside-spa, mcd-tracker-app, mcd-tracker-ios, westside-ai-bot, playme2k, pal-e-app, westside-admin. All use the same Keycloak instance. The issue only mentions testing westside-app and pal-e-app, but all clients need validation.
  • Sibling Ruby apps on same version: westside-ror and pal-e-ror both use Ruby 3.4.8 with identical Dockerfile and k8s/dev.yaml patterns. The Constraints section notes "coordinate with westside-ror and pal-e-ror" but the scope does not include those repos.
  • Ruby 4.0 is a major version jump: This carries significant gem compatibility risk. The issue acknowledges this in Constraints but does not provide a verification step or fallback plan.

Decomposition Assessment

NEEDS DECOMPOSITION — This ticket violates the 5-minute rule on multiple axes:
  • 3+ repos: pal-enterprises, pal-e-platform, pal-e-services (3 repos)
  • 5 AC + 5 test expectations: 10 verifiable items total
  • Independent work streams: Ruby/OmniAuth upgrade and Keycloak upgrade are logically separate, with different risk profiles and blast radii
Recommended decomposition:
  • Sub-ticket 1: Upgrade Keycloak 26.0.7 to 26.6.1 (pal-e-platform) — terraform image tag change, review upgrade guide, validate all OIDC clients
  • Sub-ticket 2: Upgrade Ruby 3.4.8 to 4.0.2 + OmniAuth 2.x (pal-enterprises) — .ruby-version, Gemfile, Dockerfile, k8s/dev.yaml, gem compatibility verification
  • Sub-ticket 3 (optional): Coordinate Ruby 4.0 across sibling apps — westside-ror, pal-e-ror alignment

Recommendation

  • [SCOPE] Create user story entry "infra-upgrades" on project-pal-enterprises user-stories section.
  • [SCOPE] Create architecture note arch-keycloak for the Keycloak component.
  • [DECOMPOSE] 5 AC + 5 test items across 3 repos. Split into: (1) Keycloak upgrade on pal-e-platform, (2) Ruby/OmniAuth upgrade on pal-enterprises. Route to skill-decompose-ticket.
  • [BODY] Add AC for gem compatibility verification: "When I run bundle install on Ruby 4.0, all gems resolve without errors."
  • [BODY] AC #5 (test existing auth flows) should move to the Keycloak upgrade sub-ticket since it validates the Keycloak change, not the Ruby change.
  • [LABEL] Consider adding arch:rails-app label since the Ruby/OmniAuth upgrade is primarily a rails-app concern.