Review: Spike: Keycloak integration and role-based schema design (re-review)

Verdict: APPROVED

Previous Findings Resolution

• [x] Finding 1: project-palinks note missing -- RESOLVED. project-palinks note created as project-page type with Vision, Status, Architecture, Roles, User Stories, Repos, and Board sections. The user-stories section lists story:auth-roles which maps to this spike.
• [x] Finding 2: arch-palinks note missing -- RESOLVED. arch-palinks note created as doc type with Overview and Key Decisions sections. Auth decision documented as "Keycloak OIDC (planned). Two roles: superadmin, member." References repo docs/architecture.md for details.
• [x] Finding 3: Role model inconsistency -- RESOLVED. Issue body now includes "Role model reconciliation" sub-question: "The canonical model is two Keycloak roles (superadmin, member) plus anonymous." docs/architecture.md role table fixed to superadmin/member/anonymous. docs/visibility.md aligned with same three tiers. project-palinks Roles section matches. Minor: docs/user-stories.md US-3 and US-9 still use "Admin" and "lead/collaborator" as role names, but the spike itself is scoped to reconcile these -- acceptable as-is.
• [x] Finding 4: Deliverable overlap with existing docs -- RESOLVED. Issue deliverable now reads: "docs/auth.md created -- consolidates auth design from existing docs/architecture.md and docs/visibility.md into a single reference." Clear intent: consolidation, not duplication.
• [x] Finding 5: Undocumented dependencies -- RESOLVED. Issue Related section now lists: "#17 -- visibility tier definitions (depends on this spike's role model)" and "#19 -- seed data (consumes schema decisions from this spike)." Both issues verified open in Forgejo.

Template Completeness

• [x] Type -- Spike
• [x] Lineage -- Standalone, adequate context
• [x] Repo -- Multiple (palinks, pal-e-platform, pal-e-services, pal-e-deployments)
• [x] Question -- Well-structured with sub-questions covering Keycloak setup, Rails schema, role model reconciliation, OIDC flow, platform provisioning
• [x] Deliverables -- docs/auth.md (consolidation) + follow-up tickets
• [x] Time-box -- 3 hours
• [x] Related -- Lists affected repos, #15, #17, #19

Traceability

• [x] story:auth-roles label -- present on board item
• [x] story note verified -- project-palinks user-stories section lists story:auth-roles as "Keycloak auth, roles, visibility, feature flags"
• [x] arch:palinks label -- present on board item
• [x] arch note verified -- arch-palinks note exists in pal-e-docs with Key Decisions section covering auth, visibility, feature flags, click tracking
• [x] Forgejo issue -- ldraney/palinks#16, state: open

File Targets

• [x] docs/auth.md -- does NOT exist yet (correct for a spike deliverable to be created)
• [x] docs/architecture.md -- EXISTS, role table aligned to superadmin/member/anonymous canonical model
• [x] docs/visibility.md -- EXISTS, three tiers (superadmin, member, public) consistent with architecture
• [x] docs/user-stories.md -- EXISTS, US-4 and US-8 directly relevant. Note: US-3 and US-9 still reference "Admin" and "lead/collaborator" -- acceptable since the spike is scoped to reconcile the role model

Repo Placement

Dependencies

• #15 (Route palinks.app domain) -- noted in Related section. OIDC redirect URIs depend on domain. Both in backlog, no blocking conflict.
• #17 (Visibility tier assignment, board item #1379) -- documented in issue body as dependent on this spike's role model. Verified open in Forgejo.
• #19 (Dev seed data, board item #1381) -- documented in issue body as consuming schema decisions from this spike. Verified open in Forgejo.
• No existing Keycloak/OIDC code in codebase (confirmed by grep). Current schema: single links table, no users/visibility/feature_flags.

Acceptance Criteria

• docs/auth.md created as consolidation doc -- verifiable by file existence and content review
• Follow-up tickets created -- verifiable by checking Forgejo issues
• Consolidation framing eliminates the previous ambiguity about whether this duplicates existing docs

Blast Radius

• No existing auth code to disrupt -- zero Keycloak/OIDC references in Ruby files
• Schema is minimal (single links table) -- additive changes only
• Cross-repo investigation is reading, not writing
• Role model stale references in user-stories.md are contained to that file and will be reconciled as part of spike output

Decomposition Assessment

Recommendations