pal-e-docs

Review: Provision staging environment for deploy validation (re-review)

review-1946-2026-08-01-2 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review of board item #1946 after refinements applied to address 5 issues from review-1946-2026-08-01. Four of five issues resolved. Decomposition threshold still exceeded.

Previous Findings Status

# Finding Status
1 [SCOPE] Create user story "deploy-validation" on project-landscaping-assistant FIXED -- story now in user-stories table (role: Platform owner, parent: #342)
2 [BODY] Add caddy.sls file target FIXED -- now in File Targets under pal-e-platform/salt/pillar/
3 [BODY] Add production.rb file target FIXED -- now in File Targets under landscaping-assistant/ with config.hosts explanation
4 [BODY] Fix repo owner to ldraney/pal-e-platform FIXED -- Repo section now lists all 4 repos with correct owner
5 [DECOMPOSE] 8 AC across 4 repos OPEN -- still 8 AC, 7+ files, 4 repos. No sub-issues created.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage
  • [x] Repo -- now correctly lists all 4 repos with ldraney owner
  • [x] User Story
  • [x] Context
  • [x] File Targets -- now includes caddy.sls and production.rb
  • [x] Feature Flag
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All 12 required sections for a Feature issue are present.

Traceability

  • [x] story:deploy-validation label -- "Staging environment that auto-deploys every commit for deploy validation via observability before promoting to prod"
  • [x] story note verified -- found in project-landscaping-assistant user-stories section (row 14 of 17)
  • [x] arch:infra label -- Infrastructure: paldocs (Hetzner Edge, DNS, Traffic Routing)
  • [x] arch note verified -- arch-infra note exists in pal-e-docs (architecture note, status: active)
  • [x] Forgejo issue -- ldraney/landscaping-assistant#342, state: open
All three traceability legs present and verified.

File Targets

  • [x] pal-e-services/terraform/k3s.tfvars -- verified: file exists (symlink to secrets). Contains landscaping-assistant service entry (line 337), service_databases (line 40), Keycloak realm/client (line 191). ISS staging reference pattern confirmed: iss-staging databases (line 34), staging service (line 400).
  • [x] pal-e-platform/terraform/dns.tf -- verified: file exists. Contains godaddy_dns_record resources. Note: ticket says "add A record" but existing subdomain pattern (iss_dev, line 64) uses CNAME, not A record. Agent can determine correct record type from pattern. Minor inaccuracy, non-blocking.
  • [x] pal-e-platform/salt/pillar/caddy.sls -- verified: file exists. Contains 7 site entries including landscaping (line 17-20) and iss-dev (line 37-40). No ISS staging entry exists (ISS staging is Tailscale-only). Landscaping staging will be a new public-access pattern.
  • [x] pal-e-deployments/overlays/landscaping-assistant/staging/* -- correctly marked as new files. Parent directory exists with dev/ and prod/. ISS staging reference at overlays/intelligentstaffingsystems/staging/ confirmed with kustomization.yaml, deployment-patch.yaml, secrets.enc.yaml.
  • [x] landscaping-assistant/config/environments/production.rb -- verified: file exists. config.hosts (lines 97-99) currently allows landscaping-assistant.app, landscaping-assistant.tail5b443a.ts.net, landscaping-dev.tail5b443a.ts.net. Ticket correctly notes that staging.landscaping-assistant.app must be added.

Repo Placement

Issue filed on ldraney/landscaping-assistant as a cross-repo tracking issue. Repo section now correctly lists all 4 repos with ldraney owner. Checklist has per-repo PR items. Acceptable pattern for cross-repo infrastructure work.

Dependencies

  • #1945 (backlog): "Add dev.landscaping-assistant.app to Keycloak redirect URIs" -- similar Keycloak/DNS pattern, independent. Not blocking.
  • #1940 (qa): "Keycloak login/reset redirects to Tailscale URL instead of public domain" -- could affect staging login. Staging uses separate Keycloak realm, so independent. Not blocking.
  • #1460 (backlog): "Wire up landscaping-assistant.app custom domain" -- already done (item is in backlog but work appears complete given that landscaping-assistant.app is live). Not blocking.
  • No blocking dependencies found. Dependencies are not documented in the issue scope but none are blocking.

Acceptance Criteria

8 criteria, all agent-testable:
  • AC 1 (staging URL loads): testable via curl after deploy
  • AC 2 (auto-deploy): testable by checking Image Updater annotation in kustomization.yaml
  • AC 3-5 (observability): testable by checking ServiceMonitor, PrometheusRules, blackbox probe manifests
  • AC 6 (prod manual): testable by verifying no Image Updater annotation on prod overlay
  • AC 7-8 (separate DB, separate realm): testable by checking Terraform plan output
Test expectations include concrete commands (tofu plan, kubectl kustomize, curl /up, curl /). Test for curl / returning 200 (not 403) correctly validates the config.hosts fix. Adequate.

Blast Radius

All changes are additive -- new entries in Terraform maps, new overlay directory, new DNS record, new Caddy site entry, one new config.hosts entry. Prod overlay explicitly excluded in "Files NOT to touch" section. Low blast radius.
Note: ISS staging has no public DNS or Caddy entry (Tailscale-only). Landscaping-assistant staging will be the first staging environment with public access via the edge proxy. This is a minor architectural divergence from the ISS staging reference pattern, but the ticket correctly accounts for it by including dns.tf and caddy.sls targets.

Decomposition Assessment

NEEDS DECOMPOSITION -- thresholds still exceeded:
  • File targets: 7+ files across 4 repos (threshold: >3 files across >2 repos)
  • Acceptance criteria: 8 (threshold: >5)
  • Estimated agent work: >5 minutes (Terraform changes across 2 repos, SOPS encryption, kustomize overlay, DNS record, Caddy pillar, Keycloak realm, Rails config.hosts, 4 separate PRs)
  • Natural decomposition boundary: one sub-issue per repo/PR
[DECOMPOSE] Route to skill-decompose-ticket. Same decomposition as previous review:
  • pal-e-services: Add staging service, databases, Keycloak realm/client to k3s.tfvars
  • pal-e-platform: Add DNS record (dns.tf) + Caddy site entry (caddy.sls)
  • pal-e-deployments: Create staging overlay (kustomization.yaml, deployment-patch.yaml, secrets.enc.yaml)
  • landscaping-assistant: Add staging.landscaping-assistant.app to Rails config.hosts

Recommendation

  • [DECOMPOSE] 8 AC across 4 repos with 4 separate PRs required. Route to skill-decompose-ticket for automated sub-ticket creation. Suggested split: one sub-issue per repo (4 sub-issues). The parent issue (#342) becomes the umbrella/tracking issue.
All 4 previous [BODY] and [SCOPE] issues have been resolved. Only the decomposition requirement remains.