Phase 2 -- Implementation Changelog

A flat, chronological record of what landed during Phase 2 implementation. Cross-references the canonical CHANGELOG entries in the participating repositories.

Repositories and PRs

Repository	PR	Branch	Base	Role
Arda-cards/documentation	#70	jmpicnic/email-integration-phase-2-docs	jmpicnic/email-integration-phase-1-docs (PR #69)	Phase 2 planning artifacts; phases.md patches; DQ-R1-006, DQ-R1-008; project-completion byproducts for Phase 1 and Phase 2
Arda-cards/infrastructure	#448	jmpicnic/email-integration-phase-2-infra	jmpicnic/email-integration-phase-1-infra (PR #446)	apps/Root/ rename, RootDnsStack rename, instances/Root/dns.ts, ardamails.com PublicHostedZone (imported), deploy-root.sh path update

Documentation deliverables (PR #70)

CHANGELOG entry: [0.30.0] - 2026-05-05 — Added.

• 2-root-updates/analysis.md, requirements.md, specification.md, verification.md, exports.md — the Phase 2 planning bundle following the 1-external-resources/ pattern.
• 2-root-updates/plan/task-plan.md — executable task plan with T-I1..T-I7 Implementation, T-V1..T-V8 Verification, T-C1..T-C5 Closure tasks.
• phases.md — Phase 2 deliverables row updated (NS-delegation row removed; ardamails.com zone declaration row added); Phase 2 exit criterion narrowed to forward declaration; Phase 3 Corporate stack row extended with the WriteNSRecordsToUpstreamDns instantiation.
• decision-log.md — DQ-R1-006 (locus of cross-zone NS-delegation writes) under Round R1-Phase2; DQ-R1-008 (adopt-vs-create the existing ardamails.com zone) added after Phase 2 implementation surfaced the pre-existing zone.
• 1-external-resources/implementation/ — six project-completion byproducts for Phase 1 (changelog, learnings, suggestions, alternatives, skipped, specification-post). Authored from this worktree because Phase 2’s phase-2-docs branch is the docs head where Phase-1 implementation outcomes were captured after PR #69 stabilised.
• 2-root-updates/implementation/ — six project-completion byproducts for Phase 2 (this directory).

Infrastructure deliverables (PR #448)

CHANGELOG entry: [2.29.0] - 2026-05-05 — Changed + Added.

• Renames (Tasks T-I1, T-I2):
  • src/main/cdk/apps/rootConfiguration/ → src/main/cdk/apps/Root/ (folder rename via git mv; preserves history).
  • src/main/cdk/stacks/root/root-configuration-stack.ts → src/main/cdk/stacks/root/root-dns-stack.ts; class RootConfigurationStack → RootDnsStack.
  • deploy-root.sh line 56 — --app path updated to point at the renamed folder.
  • In-repo imports of the old class / paths updated.
• CFN stack-name preservation (Task T-I2): the third positional argument to the renamed stack remains the literal string "RootConfiguration". An inline single-line comment // CFN stack name MUST remain "RootConfiguration" -- changing it would force CloudFormation to delete and recreate the stack. sits immediately above the constructor call in apps/Root/r53-zones.ts. Asserted at test time by V-IAC-003.
• Declarative configuration (Task T-I3): new src/main/cdk/instances/Root/dns.ts exporting ROOT_ZONE_NAMES (appArdaCards, ioArdaCards, authArdaCards, assetsArdaCards, ardamails) and expectedExports (matching RootDnsStack.exportDefinition keys). apps/Root/r53-zones.ts now consumes the constants from this file for the new ardamails.com zone.
• ardamails.com PublicHostedZone (Task T-I4) declared in RootDnsStack:
  • Logical ID ArdamailsZone (CFN-mangled to ArdamailsZone1DCDDC15).
  • comment: "HostedZone created by Route53 Registrar" — mirrors the AWS-default comment string on the live zone (DQ-R1-008 forward-compatibility).
  • applyRemovalPolicy(cdk.RemovalPolicy.RETAIN) — defends the imported zone against accidental cdk destroy.
• Stack export (Task T-I4): Built interface extended with ardamailsZone: string; exportDefinition extended with { exportName: "arda-ardamails-zone", description: "The Hosted Zone Id for the ardamails.com mail-root zone" }; publish() wires the field through.
• Tests (Task T-V1, V-ROOT-001 strict-match):
  • src/main/cdk/stacks/root/root-dns-stack.test.ts — new strict-equality test that locks the synthesized AWS::Route53::HostedZone block to Name: "ardamails.com.", HostedZoneConfig.Comment: "HostedZone created by Route53 Registrar", DeletionPolicy: "Retain", UpdateReplacePolicy: "Retain". Adopts the discipline noted in learnings.md L-3.
  • Existing tests for the four arda.cards family zones and the AllowCreatingNSRecordsRole continue to pass unchanged.
• No new dependencies added by Phase 2 (CDK + Route53 + IAM constructs already present).

Operational state at end of Phase 2 implementation

The Phase 2 deploy ran in two CloudFormation operations against the live RootConfiguration stack on 2026-05-05 (see learnings.md L-1, L-2):

1. IMPORT change-set with a stripped template (deployed-state + ArdamailsZone resource only — no Outputs added, no other resource modifications). CFN reported Action: Import, Replacement: null, Scope: []. Stack transitioned to IMPORT_COMPLETE. The pre-existing zone Z0721066239FWCD47EJDX is now CDK/CFN-managed under the logical ID ArdamailsZone1DCDDC15. The four AWS-assigned nameservers (ns-2046.awsdns-63.co.uk, ns-944.awsdns-54.net, ns-158.awsdns-19.com, ns-1497.awsdns-59.org) are unchanged; the registrar’s NS chain remains intact.
2. Normal cdk deploy with the full synthesized template, adding the ardamailsZone Output (publishing the arda-ardamails-zone CFN export name) and reconciling CDKMetadata. Stack transitioned to UPDATE_COMPLETE. Final cdk diff reported zero differences.

State that downstream phases can rely on:

• arda-ardamails-zone CFN export resolves to Z0721066239FWCD47EJDX.
• The AllowCreatingNSRecordsRole IAM role (deterministic name from aws-configuration.ALLOW_WRITE_NS_RECORDS_ROLE.name) is unchanged; Phase 3 Corporate and Phase 4 partition stacks will assume it for WriteNSRecordsToUpstreamDns writes per DQ-R1-006.
• The four arda.cards family zones (app, io, auth, assets) and their CFN exports are unchanged.

Decisions recorded during Phase 2 implementation

#	Title	Round
DQ-R1-006	Locus of cross-zone NS-delegation writes	R1-Phase2
DQ-R1-008	Adopt vs create the existing ardamails.com hosted zone	R1-Phase2

The full text of each decision is in ../../decision-log.md.

DQ-013 (IAM role extraction from root stack) had been resolved in pre-rev1 work; Phase 2 honours it by leaving the role inside RootDnsStack.

Cross-cutting

• The per-phase worktree convention introduced in CLAUDE.md enabled Phase-2 documentation refinement (phase-2/documentation/) and Phase-2 infrastructure work (phase-2/infrastructure/) to proceed concurrently with Phase-1 PR review (phase-1/...). The DQ-R1-008 remediation — which involved staging a stripped CFN template and running it through aws cloudformation create-change-set --change-set-type IMPORT — happened end-to-end in the phase-2/infrastructure/ worktree without touching the Phase 1 worktrees.