Review: Keycloak ISS realm: self-registration, phone field, SMTP

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage -- Related to intelligentstaffingsystems#59
• [x] Repo -- present (but WRONG, see below)
• [x] User Story -- present
• [x] Context -- present, good background
• [x] File Targets -- present (but paths and repo are wrong)
• [x] Feature Flag -- none (appropriate for realm config)
• [x] Acceptance Criteria -- 7 items present
• [x] Test Expectations -- 4 manual tests
• [x] Constraints -- present
• [x] Checklist -- present
• [x] Related -- present

Traceability

• [x] story:registration label -- "Epic 1 (US-1.2-1.4)", Role: Visitor/Lead
• [x] story note verified -- found in project-iss user-stories section
• [x] arch:auth label -- present on board item
• [ ] arch note MISSING -- [SCOPE] Create architecture note arch-auth in pal-e-docs
• [x] Forgejo issue -- ldraney/pal-e-services#184, open

File Targets

• [ ] keycloak/themes/iss/login/register.ftl -- ISSUE: Wrong path AND wrong repo. The ISS Keycloak theme lives at keycloak-theme/iss/login/ in the intelligentstaffingsystems repo, not pal-e-services. Confirmed by existing files: keycloak-theme/iss/login/theme.properties, keycloak-theme/iss/login/resources/css/login.css, keycloak-theme/iss/login/resources/img/iss-logo.svg. Issue #17 (done) established this: "The theme directory lives in this repo for version control but is deployed to the cluster separately."
• [ ] keycloak/themes/iss/login/resources/css/register.css -- ISSUE: Same as above -- should be keycloak-theme/iss/login/resources/css/register.css in intelligentstaffingsystems repo.
• [ ] "Realm config (admin console or realm export)" -- ISSUE: Vague. Realm config changes go through terraform/k3s.tfvars and terraform/keycloak.tf in pal-e-services. However, self-registration and SMTP are ALREADY deployed via PR #178.

Repo Placement

• intelligentstaffingsystems: FreeMarker template (register.ftl) and CSS (register.css) -- the keycloak-theme directory lives here
• pal-e-services: Terraform realm config -- but self-registration (registration_allowed = true) and SMTP (Postmark) are already deployed via PR #178 (merged). The only remaining terraform work is adding verify_email to the realm config, which is currently NOT in variables.tf or keycloak.tf.

Dependencies

• Board item #1831 (intelligentstaffingsystems#59, Rails-side registration) is in backlog with sprint:A -- this ticket (#1864) is listed as its prerequisite. Dependency relationship is documented in the Lineage section.
• Board item #1786 (#6 Keycloak OIDC auth integration) is done -- completed prerequisite.
• Board item #1785 (#17 Keycloak login theme) is done -- established the theme directory structure at keycloak-theme/iss/.
• PR #178 (Add ISS service, Keycloak realm, client, and seed user) is merged -- already deployed self-registration, SMTP, roles, and default role assignment.
• PR #175 (Configure Keycloak SMTP via Postmark) is merged -- established the SMTP pattern.

Acceptance Criteria

• AC 1 (self-registration enabled): Already deployed via PR #178. Redundant unless verifying it's live.
• AC 4 (realm-level SMTP with Postmark): Already deployed via PR #178. Redundant.
• AC 5 (email verification required): verify_email is NOT in the current terraform variables or keycloak.tf. Requires adding this field to the terraform module before it can be set.
• AC 2, 3 (register.ftl, phone attribute): Valid new work, but belongs in intelligentstaffingsystems repo.
• AC 6 (ISS brand): Valid, belongs in intelligentstaffingsystems repo.
• AC 7 (existing login still works): Valid regression check.

Blast Radius

• Adding register.ftl changes the ISS theme from CSS-only to FreeMarker-based. This is the first FreeMarker template in the ISS theme (confirmed by current contents: only theme.properties, login.css, and iss-logo.svg). This could affect Keycloak upgrade compatibility -- FreeMarker templates are version-specific.
• The theme.properties currently has parent=keycloak -- the register.ftl must properly extend the parent template. Issue #17's constraints explicitly state "CSS-only overrides, no FreeMarker template changes" -- this ticket overrides that decision. The Context section acknowledges this ("adds the first FreeMarker template") but the architectural decision change should be documented.
• No blast radius on SMTP or self-registration -- those are already live.

Decomposition Assessment

• Ticket A (pal-e-services): Add verify_email to terraform realm config (variables.tf, keycloak.tf, k3s.tfvars). 1-2 AC, ~2 minutes agent work.
• Ticket B (intelligentstaffingsystems): Create register.ftl FreeMarker template with phone field, add register.css, update theme.properties. 3-4 AC, ~5 minutes agent work.

Recommendation

• [BODY] Fix file paths: keycloak/themes/iss/login/ should be keycloak-theme/iss/login/
• [BODY] Fix repo for FreeMarker/CSS work: belongs in ldraney/intelligentstaffingsystems, not ldraney/pal-e-services
• [BODY] Remove or mark as "already deployed" the self-registration and SMTP acceptance criteria (deployed via PR #178)
• [BODY] Replace vague "Realm config (admin console or realm export)" file target with specific terraform paths: terraform/variables.tf, terraform/keycloak.tf, and terraform/k3s.tfvars in pal-e-services -- specifically for adding verify_email
• [BODY] Add note that this introduces the first FreeMarker template to the ISS theme, changing it from CSS-only to template-based (architectural decision change from #17)
• [SCOPE] Create architecture note arch-auth in pal-e-docs
• [DECOMPOSE] Split cross-repo work: (A) pal-e-services ticket for verify_email terraform addition; (B) intelligentstaffingsystems ticket for register.ftl + register.css + phone field. Route to skill-decompose-ticket.