pal-e-docs

Review: feat: deployment overlays, dev environment subdomain, and Makefile

review-1868-2026-07-17 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, references #3, #4, #5, PR #534
  • [x] Repo — Multi-repo (3 repos listed)
  • [x] User Story — Developer-focused, well-formed
  • [x] Context — Thorough current state and deliverables
  • [x] File Targets — 14+ targets across 3 repos with exclusion list
  • [x] Feature Flag — none (infrastructure, acceptable)
  • [x] Acceptance Criteria — 14 items
  • [x] Test Expectations — 8 items with run commands
  • [x] Constraints — 8 items, well-scoped
  • [x] Checklist — 6 items
  • [x] Related — comprehensive cross-references

Traceability

  • [x] story:project-setup label — verified in project-iss user-stories section (Key: project-setup, Backing: "README + docs/architecture.md + docs/adoption-plan.md", Role: Developer)
  • [x] arch:infra label — present on board item
  • [ ] arch note MISSING — [SCOPE] No arch-infra note found in pal-e-docs. Create architecture note arch-infra for the infrastructure component.
  • [x] Forgejo issue — #77, open, valid URL

File Targets

intelligentstaffingsystems repo (this repo):
  • [ ] Makefile — does not exist yet (create — correct per ticket)
  • [x] docker-compose.yml — verified: exists, update target. Currently minimal (web + db services, port 9999).
  • [x] docs/local-dev-setup.md — verified: exists, update target. Currently documents docker compose commands manually; Makefile would wrap these.
  • [x] docs/architecture.md — verified: exists, update target.
  • [x] docs/pipeline.md — verified: exists, update target.
  • [x] config/environments/production.rb — verified: exists. Currently has config.hosts << "intelligentstaffingsystems.ai" and config.hosts << "iss.tail5b443a.ts.net". Ticket correctly notes dev subdomain may need adding.
pal-e-deployments repo:
  • [ ] overlays/intelligentstaffingsystems/ — does not exist yet (create — correct per ticket)
  • [x] overlays/westside-ror/prod/ — verified: exists as reference pattern with kustomization.yaml, deployment-patch.yaml
  • [x] overlays/westside-ror/dev/ — verified: exists as reference pattern with deployment.yaml, ingress.yaml, kustomization.yaml, service.yaml
  • [x] overlays/dev-tunnel/ — verified: exists on main (configmap, deployment, ingress, kustomization, namespace, service, README)
  • [x] bases/standard/ — verified: exists (deployment, hpa, kustomization, networkpolicy, service, servicemonitor)
godaddy-tofu repo — REPO PLACEMENT ERROR:
  • [ ] DNS record for dev.intelligentstaffingsystems.ai — ISSUE: godaddy-tofu is a custom Go Terraform PROVIDER (manages GoDaddy API). It does NOT contain DNS record configurations. DNS records are managed in pal-e-platform/terraform/dns.tf. PR #534 ("Wire intelligentstaffingsystems.ai to production edge") is in pal-e-platform, not godaddy-tofu. The Caddy vhost changes are also in pal-e-platform/salt/pillar/caddy.sls.

Repo Placement

MISMATCH: The issue lists ldraney/godaddy-tofu as one of three target repos for DNS work. However, godaddy-tofu is a Go Terraform provider implementation (manages GoDaddy API). The actual DNS record configurations live in pal-e-platform/terraform/dns.tf, and Caddy vhost configs live in pal-e-platform/salt/pillar/caddy.sls. PR #534, which the issue cites as the reference for domain wiring, is in pal-e-platform, not godaddy-tofu.
The correct repo list should be:
  • ldraney/intelligentstaffingsystems — Makefile, docker-compose, docs
  • ldraney/pal-e-deployments — kustomize overlays (prod + dev)
  • ldraney/pal-e-platform — DNS records (terraform/dns.tf) and Caddy vhost (salt/pillar/caddy.sls)

Dependencies

  • #3 (Bootstrap Rails app — done) — foundation, no blocker
  • #4 (Register ISS in pal-e-services — done) — created tfvars entry this overlay fulfills
  • #5 (Deployment overlay stub — done) — original stub, superseded by this ticket
  • PR #534 (pal-e-platform, closed) — wired apex domain, reference for dev subdomain DNS
  • #69 (config.hosts DNS rebinding — validation) — established the config.hosts pattern; not a blocker but closely related
  • No blocking dependencies found. All foundation work is done.

Acceptance Criteria

14 acceptance criteria, all testable by an agent:
  • Overlay existence: verifiable with ls
  • ArgoCD sync: verifiable with kustomize build
  • DNS record: verifiable with dig after terraform apply
  • Makefile targets: verifiable by running each make target
  • No host Ruby: verifiable by inspecting Makefile targets use docker compose
  • README with mermaid: verifiable with read
  • Doc references: verifiable with grep
  • config.hosts: verifiable with read
  • Keycloak redirects: verifiable in pal-e-services tfvars
All criteria are well-defined and automatable. However, 14 criteria is well above the 5-criterion decomposition threshold.

Blast Radius

  • config.hosts changes for the dev subdomain only affect the Rails production environment — low risk since the same pattern was established in #69.
  • The Makefile wraps existing docker compose commands — no new runtime behavior, just a convenience layer.
  • Keycloak redirect URI additions (if needed) affect authentication flow — must stay in sync across pal-e-services and the app.
  • The dev-tunnel overlay introduces a new kubernetes deployment path — review the existing dev-tunnel pattern carefully to avoid port/ingress conflicts.
  • No similar bug patterns found elsewhere; this is new infrastructure creation.

Decomposition Assessment

NEEDS DECOMPOSITION — route to skill-decompose-ticket
  • File targets: 14+ across 3 repos (threshold: >3 across >2 repos) — EXCEEDED
  • Acceptance criteria: 14 (threshold: >5) — EXCEEDED
  • Estimated agent work: Well over 5 minutes — creating overlay directories with kustomization/patches/SOPS secrets, DNS terraform, Caddy vhost, Makefile, docker-compose updates, and 4 doc files — EXCEEDED
Suggested decomposition axes (3 sub-tickets, one per repo):
  • pal-e-deployments: prod + dev overlays (kustomization, patches, secrets, READMEs)
  • pal-e-platform: dev subdomain DNS record + Caddy vhost
  • intelligentstaffingsystems: Makefile + docker-compose updates + docs updates + config.hosts

Recommendation

  • [BODY] Fix repo placement: replace ldraney/godaddy-tofu with ldraney/pal-e-platform for DNS/Caddy work. Update File Targets section accordingly — DNS record goes in terraform/dns.tf, Caddy vhost in salt/pillar/caddy.sls.
  • [BODY] Fix Constraints section: change "DNS changes go through godaddy-tofu" to "DNS changes go through pal-e-platform/terraform/ (using the godaddy-tofu provider)".
  • [BODY] Fix Checklist: change "one per repo: pal-e-deployments, godaddy-tofu, intelligentstaffingsystems" to "one per repo: pal-e-deployments, pal-e-platform, intelligentstaffingsystems".
  • [SCOPE] Create architecture note arch-infra for the infrastructure component in pal-e-docs.
  • [DECOMPOSE] 14+ file targets across 3 repos, 14 AC, estimated >5 min agent work — route to skill-decompose-ticket. Suggested split: one sub-ticket per repo (pal-e-deployments overlays, pal-e-platform DNS+Caddy, ISS Makefile+docs).