[herosjourney]

Problem

Two gaps between what heroku-to-aws asks and what it hands back:

1. Clarify Q10 asks "DNS strategy" and defaults to route53, but Generate emits no Route 53 at all. The guide's cutover section was two lines: {{app_domain}} → CNAME → {{ALB_DNS_NAME}} and "set TTL low (60s)". A founder who answered Route 53 got nothing for it, and Elastic Beanstalk web environments had no 443 listener, so a custom domain pointed at them served plain HTTP.
2. MIGRATION_GUIDE.md had no rollback content (grep -i rollback across the three generate files: 0 hits), and "Decommission Heroku" appeared twice, once as an orphaned heading with no body.

Both are from the evaluation's "artifacts that run" list; both are things a startup hits at 2 a.m. on cutover night.

Change

dns.tf — generate-terraform.md Step 9.5

Emitted when dns_strategy == "route53" and the inventory has at least one domain resource (so a run with no custom domain never gets an unusable file).

• ACM certificate for every custom domain, DNS-validated in the same apply. The ALB HTTPS listener (Step 6) and EB web environments (Step 6.5, new aws:elbv2:listener:443 settings) use it; var.acm_certificate_arn is dropped when dns.tf exists.
• Weighted cutover. For each non-apex hostname, two CNAMEs with the same name — Heroku target and AWS target — split by cutover_weight. 0 is all-Heroku (the default), 100 is all-AWS, and lowering it is the rollback. Three terraform apply -var cutover_weight=N calls replace hand-edited records.
• Apex handling stated honestly. Route 53 cannot CNAME or ALIAS an apex to an external host, so the apex cannot be weighted against Heroku. It gets a single ALIAS created only at weight 100, and the guide says to test on www. first.
• Variables with placeholder-rejecting validation: hosted_zone_id, heroku_dns_targets (map hostname → …herokudns.com; discovery records hostname and sni_endpoint but not the DNS target today — called out, with the heroku domains command), cutover_weight (0–100 integer). Output dns_cutover shows live weights per hostname. The zone is a data source, never a resource — the user may already serve other records from it.

MIGRATION_GUIDE.md — generate-docs.md

• Phase 5 Cutover now has a pre-cutover checklist (TTL lowered 24 h earlier, DNS targets written down, fresh export on full_cutover), then exactly one of two DNS subsections: the Route 53 path as 10 % → 50 % → 100 % with what to watch at each step, or the external-provider path with per-record instructions and the ALIAS/ANAME note. The heroku maintenance:on write-freeze is placed where it belongs for full_cutover (after 100 %, not before).
• Phase 6 Rollback (new): 72-hour window; a trigger table tied to the Phase 4 checks (health path, 5xx rate, p95, functional tests, row counts); a per-phase table with the rollback action, data at risk, and RTO; "DNS back to Heroku" as one apply (or the provider edit); and "Writes after cutover" — on full_cutover the AWS database has rows Heroku never saw, so the user must accept the gap or reverse-sync before heroku maintenance:off; on data-first nothing is lost because the database already lives on AWS.
• Phase 7 Decommission: duplicate heading removed; decommission gated on the rollback window.

generate.md postconditions

MIGRATION_GUIDE.md must have Cutover and Rollback sections in order with Decommission after, and the Rollback section must name a DNS-revert action and a post-cutover-writes statement. terraform/dns.tf must exist with its three variables and the ACM validation when the Route 53 condition holds, and must not exist otherwise.

Scope

Three files in skills/heroku-to-aws/references/phases/generate/, prose only. No schema, shared, or vendored changes; no change to any Clarify question. Merge-tree clean against #383 (which touches generate.md preconditions, not postconditions).

Tested

• tools/validate.py, full-repo markdownlint: pass.
• check-skill-refs.py from ci(aws-startup-advisor): reference-path lint — every file path a skill mentions must exist #387 run against this tree: PASS — 1111 reference(s) checked, 0 missing.
• Walked the template by hand for the four combinations (Fargate/EB × route53/external) and both migration_approach values; the conditional-section rules in generate-docs.md say which blocks render in each.

Not in this PR

• Capturing the Heroku DNS target during Discover (heroku domains --json has it) so heroku_dns_targets could be pre-filled. One small follow-up touching discover-live.md and schema-discover-heroku.md.
• An HTTP→HTTPS redirect on the EB load balancer (needs an .ebextensions or nginx config; the ALB path already redirects).
• A rollback.sh wrapper. With Route 53 the rollback is one terraform apply; a script would add a layer without adding safety.

[leon1418]

[🤖 AI review 🤖]

Reviewed 185dbcb5c6e1a762e1d174f820c8a92f33b18b24 with OCR delegation, a repository review, and one fresh independent general review. The complete correction list is grouped into the eight inline comments:

1. [P1] Use the DNS preference field that Clarify actually writes.
2. [P1] Make the advertised database verification command read-only.
3. [P1] Base rollback actions on the actual database handoff and retained access.
4. [P1] Make DNS authority and existing records part of the cutover lifecycle.
5. [P1] Preserve domain, application, zone, and web-endpoint associations.
6. [P2] Handle EKS explicitly before choosing the Beanstalk fallback.
7. [P2] Accept the documented Cedar Private Space DNS target format.
8. [P1] Persist the rollback weight before later Terraform applies.

Validation: manifest validation, plugin parity, plugin specification checks, changed-file Markdown lint, and git diff --check passed. Both reviewers executed the generated PostgreSQL script with local command stubs; the parent also checked the exact cutover variable with the Terraform CLI. Captured CI checks passed. No live cloud, DNS, or database changes were made. The findings concern behavior not covered by those passing structural checks.

[leon1418]

[🤖 AI review 🤖] REQUEST_CHANGES after a complete startups-hybrid-v1 follow-up at 450aab80169c96cea2dc217fc7315397e471c0a9 (base 1de6d7a92f4bfc114bc74eae3587619716328402). OCR delegation, the parent repository review, one fresh isolated independent reviewer, candidate verification, and the convergence gate are complete.

The consolidated remaining correction list is:

1. Complete database failback: drain every writer, keep AWS writers stopped through later applies, and fully reset the restore target (original failback concern remains).
2. Make the new read-only verifier fail on query errors.
3. Preserve authoritative Heroku DNS before Phase 1 teardown.
4. Initialize Terraform before the new DNS imports.
5. Complete the EKS HTTPS handoff on port 443.
6. Omit PostgreSQL prerequisites/failback for designs without Postgres.

The verifier, import ordering, and EKS TLS gaps were introduced by the fixes. The DNS teardown and no-Postgres paths were present in the earlier reviewed source; I missed them then. Details and bounded acceptance criteria are in the original threads and the new inline comment. Four fully fixed original conversations were verified and resolved; other conversations stay open.

Validation: manifest, plugin parity, specification, changed-file Markdown lint and diff checks passed; 96 existing report tests passed. Exact Bash stubs and local-only Terraform probes exercised the failures. Current captured CI passed. No live cloud/database operations or source changes were performed. Approval remains user-only.

[leon1418]

[🤖 AI review 🤖] Reviewed c8048ac4313e3c209f599bd0b3edb7fc9c718ede with OCR delegation, a fresh independent general reviewer, the parent repository review, and a complete convergence-v1 evidence gate.

Five correction groups remain:

1. P1 — Reverse handoff: finish cross-route shutdown/persistence, use the correct EKS paths, prevent compute changes in DNS rollback plans, and restore Heroku formation/jobs after verified failback. See the original failback thread.
2. P1 — Forward full cutover: stop Heroku background writers before the final export and keep them stopped while AWS is primary. I missed this existing behavior in the previous review.
3. P2 — DNS adoption: the new early cd terraform/ makes the later import block enter a nonexistent nested directory. Keep the init/import/apply sequence in the intended directory.
4. P2 — EKS TLS check: validate the custom certificate hostname while connecting to the new load balancer before DNS moves.
5. P2 — Route regeneration: explicitly reconcile a retained dns.tf when switching to external DNS/EKS; preserve user edits and retain the read-only gate. I previously missed this incomplete transition.

Verified corrected causes: read-only query failure handling, Phase 1 DNS preservation, initialization ordering, EKS port 443, and no-Postgres failback rendering. New errors in the repaired import/TLS sequences are called out separately. Original threads receive the detailed evidence; only the fully addressed verifier and no-Postgres conversations are eligible for resolution.

Validation: repository manifest/spec/parity checks and changed-file Markdown lint pass; git diff --check passes; independent embedded-script, Terraform, directory and TLS probes retained. The initial npm authentication failure was preserved and the public-registry retry passed. Nine current GitHub checks report success. No source edits, commits, pushes or live cloud/database changes were made. Approval remains for the user; no review is dismissed.