pal-e-docs

Review: Ship paldocs.app to TestFlight — DNS + auth + turbo-ios

review-1520-2026-06-19 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, new initiative
  • [x] Repo — listed (primary + 4 ancillary)
  • [x] User Story — present, well-formed
  • [x] Context — thorough, references existing spike and reference implementation
  • [x] File Targets — extensive, organized by phase
  • [x] Feature Flag — "none" with rationale
  • [x] Acceptance Criteria — 9 criteria listed
  • [x] Test Expectations — 4 items with run command
  • [x] Constraints — 5 constraints listed
  • [x] Checklist — present
  • [x] Related — present
All required feature template sections are present and well-populated.

Traceability

  • [ ] story:ios-testflight label — story note MISSING. No story-paldocs-ios-testflight note exists in pal-e-docs. The project-paldocs user-stories section lists story-paldocs-auth, story-paldocs-kanban, and story-paldocs-project-pages but not an ios-testflight story. [SCOPE] Create user story note story-paldocs-ios-testflight and add entry to project-paldocs user-stories section. Alternatively, if auth is the primary story, relabel to story:auth and add iOS as a sub-scope.
  • [ ] arch:full-stack label — arch note MISSING. No arch-full-stack note exists in pal-e-docs. The work actually spans arch:ci-cd (DNS/Caddy), arch:keycloak (client config), arch:rails-views (auth controllers), and iOS (new domain). [SCOPE] Either create arch-full-stack as a composite architecture note, or decompose the ticket so each sub-ticket has a specific arch label.
  • [x] Forgejo issue — ldraney/paldocs#46, open

File Targets

Phase 1 — DNS (pal-e-platform):
  • [x] terraform/dns.tf — verified: exists at /home/ldraney/pal-e-platform/terraform/dns.tf. Contains GoDaddy A records for palinks.app and landscaping-assistant.app — pattern established.
  • [x] salt/pillar/caddy.sls — verified: exists at /home/ldraney/pal-e-platform/salt/pillar/caddy.sls. No paldocs config yet (0 matches) — confirms new work.
Phase 2 — Keycloak (pal-e-services):
  • [x] terraform/k3s.tfvars — verified: exists (symlink to secrets). Already contains a paldocs block with forgejo_repo, image_repo, port 3000. Note: this appears to be the FluxCD/deployment config, NOT the Keycloak client config. The issue says "add paldocs confidential client to pal-e-docs realm" — verify this is the correct file for Keycloak client definitions, or if a separate Keycloak terraform file is needed. [BODY] Clarify whether k3s.tfvars is the correct location for Keycloak client config, or if a dedicated Keycloak terraform file exists.
Phase 3 — Rails auth (paldocs):
  • [x] Gemfile — verified: exists. No omniauth references yet — clean starting point.
  • [x] config/initializers/omniauth.rb — does not exist yet (will be created). Initializers directory exists.
  • [x] app/controllers/sessions_controller.rb — does not exist yet (will be created). Controllers directory exists.
  • [x] app/controllers/application_controller.rb — verified: exists.
  • [x] config/routes.rb — verified: exists.
  • [x] Reference implementation files verified: ~/landscaping-assistant/config/initializers/omniauth.rb and ~/landscaping-assistant/app/controllers/sessions_controller.rb both exist.
Phase 3b — Deployment (pal-e-deployments):
  • [x] overlays/paldocs/prod/deployment-patch.yaml — verified: exists.
Phase 4 — iOS (paldocs-ios):
  • [ ] paldocs-ios repo — does NOT exist on Forgejo or locally. Must be created on MacBook. This is expected (issue says "new"), but the repo creation is an implicit prerequisite not captured in the checklist.
  • [x] macbook-ssh/docs/ — verified: exists. Contains dev-build-guide.md with HotwireNative references.
Related doc:
  • [x] docs/auth-visibility-architecture.md — verified: exists in paldocs repo.

Repo Placement

The Forgejo issue is filed on ldraney/paldocs, which is the primary repo. However, the work spans 5 repos: paldocs, pal-e-platform, pal-e-services, pal-e-deployments, and paldocs-ios (new). This is appropriate for the umbrella issue but reinforces the need for decomposition — each sub-ticket should be filed on its target repo.

Dependencies

  • Board item #1369 ("Deploy paldocs to production") is in next_up column. This is a prerequisite — DNS and public access require production deployment to be complete first. The issue does not document this dependency.
  • Backlog items #1387, #1388, #1389, #1390 are auth-related (story:auth) and may overlap or conflict with this ticket's auth implementation. Relationship is undocumented.
  • Keycloak pal-e-docs realm — issue states it exists. No verification needed but dependency is implicit.
  • GoDaddy domain ownership — issue states paldocs.app is purchased. Implicit dependency.
  • MacBook access — Phase 4 (iOS) requires MacBook for Xcode/TestFlight. Not executable by server-side agents.

Acceptance Criteria

9 acceptance criteria are listed. Assessment:
  • AC 1-2 (DNS/TLS): Verifiable via curl -I https://paldocs.app and redirect check. Automatable.
  • AC 3-6 (Auth flow): AC 3-5 partially testable via request specs. AC 6 (logout) requires Keycloak integration. Semi-automatable.
  • AC 7-9 (iOS): Requires physical device and TestFlight. Not automatable by agents — must be manual.
Missing AC: No criterion for www.paldocs.app CNAME/A record setup (only redirect behavior is specified, not DNS record creation).

Blast Radius

  • Caddy config: Adding a new site block to caddy.sls affects the reverse proxy for all sites. Pattern is established (palinks.app, landscaping-assistant.app) so risk is low if pattern is followed.
  • Keycloak realm: Adding a client to the existing pal-e-docs realm is additive — no risk to existing clients.
  • paldocs app: Adding auth to application_controller.rb affects ALL routes. Must ensure health check / readiness endpoints remain unauthenticated. The issue does not address this.
  • Existing auth backlog items: Items #1387-1390 (story:auth) in backlog may become partially completed or obsoleted by this ticket. Coordination needed.

Decomposition Assessment

NEEDS DECOMPOSITION.
  • 13+ file targets across 5 repos — exceeds threshold of 3 files across 2 repos
  • 9 acceptance criteria — exceeds threshold of 5
  • 4 distinct phases with different toolchains (Terraform, Salt, Ruby, Swift/Xcode)
  • Estimated agent work: well over 5 minutes per phase
  • Phase 4 (iOS) cannot be executed by server-side agents at all
Recommended decomposition into 4 sub-tickets matching the phases in the issue:
  • DNS + Caddy (pal-e-platform, ~3 pts) — arch:ci-cd
  • Keycloak client (pal-e-services, ~2 pts) — arch:keycloak
  • Rails auth + deployment secrets (paldocs + pal-e-deployments, ~5 pts) — arch:rails-views
  • iOS turbo-ios + TestFlight (paldocs-ios, ~5 pts) — arch:ios (new), MacBook-only

Recommendation

  • [SCOPE] Create user story note story-paldocs-ios-testflight (or relabel to story:auth if iOS is considered part of auth story) and add to project-paldocs user-stories section.
  • [SCOPE] Create architecture note arch-full-stack, or decompose so each sub-ticket uses a specific arch label.
  • [BODY] Clarify whether terraform/k3s.tfvars is the correct file for Keycloak client configuration (current content appears to be deployment/FluxCD config, not Keycloak).
  • [BODY] Add dependency note: blocked by #1369 (Deploy paldocs to production) which is in next_up.
  • [BODY] Add AC for health check endpoints remaining unauthenticated after auth is added.
  • [BODY] Add prerequisite to checklist: "paldocs-ios repo created on Forgejo/GitHub".
  • [BODY] Document relationship to existing auth backlog items #1387-1390 (story:auth) — are they superseded, prerequisites, or parallel?
  • [DECOMPOSE] 13+ file targets across 5 repos, 9 AC, 4 phases with different toolchains. Route to skill-decompose-ticket for sub-ticket creation.