Phase 2 -- Root Updates -- Task Plan

Execution plan for Phase 2, derived from ../specification.md. This document is the team’s executable view: tasks, owners, dependencies, worktree strategy, branch model, and acceptance gates. The specification remains the contract; the plan is how it gets done.

1. Overview

Phase 2 prepares the Root instance for the rev1 mail-integration architecture. The work is single-repository on the implementation side (Arda-cards/infrastructure), with a small set of cross-doc patches landing in parallel on the documentation side (Arda-cards/documentation).

Effort shape: 7 tasks (from ../specification.md § 2), 2 repositories, 1 worktree per repository, single-agent execution recommended (no parallel-agent split needed). Estimated wall-clock: 1-2 working days, dominated by the careful CFN-stack-name preservation review.

Highest-risk concern: the CFN stack-name immutability rule. A wrong third positional argument to RootDnsStack(...) deletes and recreates the production root stack, taking down every partition’s DNS-delegation chain. The plan front-loads the CFN-name preservation comment + V-IAC-003 grep test before any other change.

2. Repositories

Repository	Role	Branch	Base branch	Purpose
Arda-cards/documentation	downstream	jmpicnic/email-integration-phase-2-docs	jmpicnic/email-integration-phase-1-docs	Phase 2 planning artefacts; phases.md patch; DQ-R1-006; CHANGELOG.
Arda-cards/infrastructure	upstream	jmpicnic/email-integration-phase-2-infra	jmpicnic/email-integration-phase-1-infra	Renames; ardamails.com zone + export; instances/Root/dns.ts; deploy-root.sh path edit; CHANGELOG; tests.

The two PRs are independent — no code dependency from one repository on the other — but the documentation PR should land first or in parallel because the DQ-R1-006 decision is the contract that scopes the infrastructure work.

The branch model follows the project’s stacked-PR convention: phase-2-docs stacks on phase-1-docs (PR #69); phase-2-infra stacks on phase-1-infra (PR #446).

3. Phases (within Phase 2’s execution)

The seven specification tasks fall into three execution phases:

Execution Phase A: Documentation patches (already complete on PR #70)

#	Task	Repository	Acceptance criteria
T-D1	Author the five Phase 2 planning artefacts (analysis, requirements, specification, verification, exports)	documentation	Files exist with valid Starlight frontmatter; cross-links resolve; make pr-checks passes.
T-D2	Spec Task 6: patch ../../phases.md and add DQ-R1-006 to ../../decision-log.md	documentation	Phase 2 deliverables list updated; “after Phase 3 lands the zone” language dropped; Phase 3’s Corporate Email row extended; DQ-R1-006 present in decision table, the new “Round R1-Phase2” section, and the Summary table. Verifies V-DOC-002.
T-D3	Spec Task 7 (docs side): CHANGELOG entry under [0.30.0] (Added for the artefacts and decision; Changed for the phases.md patch)	documentation	make clq passes.

Status: complete. All three tasks are committed on jmpicnic/email-integration-phase-2-docs at commit fa0da41. PR #70 (draft) carries the diff. This task plan adds itself to the same PR as the final docs-side artefact.

Execution Phase B: Infrastructure implementation (sequential on a single branch)

The seven tasks from ../specification.md § 2 reduce to five infrastructure-side tasks (Tasks 1-5) plus the infrastructure CHANGELOG entry (Task 7-infra). They execute in the order shown; each task’s STOP point gates entry to the next.

#	Spec ref	Task	Acceptance criteria	Verifies
T-I1	Task 1	Rename apps/rootConfiguration/ → apps/Root/ (folder + import paths)	git mv preserves history; grep -rn "apps/rootConfiguration" returns zero hits; npm run build still succeeds (class still named RootConfigurationStack).	V-IAC-001
T-I2	Task 2	Rename RootConfigurationStack → RootDnsStack and update entry points	File rename via git mv; class rename; apps/Root/r53-zones.ts import updated; inline CFN-name preservation comment in place; third positional arg unchanged at "RootConfiguration"; npm run build clean.	V-IAC-002, V-IAC-003
T-I3	Task 3	Add instances/Root/dns.ts declarative configuration	New file exports the symbols listed in ../exports.md § 2; at least one apps/Root/* file imports from it; tsc --noEmit clean.	V-IAC-004
T-I4	Task 4	Add ardamails.com PublicHostedZone and its export	New r53.PublicHostedZone(zoneName: "ardamails.com") in RootDnsStack; Built, ExportKeys, ExportDefinition, publish() updated; cdk synth shows the new resource and a CFN Output with Export.Name = "arda-ardamails-zone".	V-ROOT-001, V-ROOT-002
T-I5	Task 5	Update deploy-root.sh (path-only)	Line 56’s --app argument references src/main/cdk/apps/Root/r53-zones.ts; no other change to the script.	V-OPS-001
T-I6	—	Author CDK Template-matcher unit tests + source-state grep tests	Tests in src/main/cdk/stacks/root/root-dns-stack.test.ts (and any source-state grep test file in apps/Root/) cover V-ROOT-001, V-ROOT-002, V-ROOT-003, V-IAC-003. npm test passes.	V-ROOT-001-003, V-IAC-003
T-I7	Task 7-infra	CHANGELOG entry under [2.29.0] (Changed for the renames; Added for the new zone + export)	clq validation passes (run via the infrastructure repo’s CI gate).	—

STOP — review and approval after T-I4. Run npx cdk diff --app ... against the deployed Root stack. The diff must be additive only: a new AWS::Route53::HostedZone for ardamails.com. and a new AWS::CloudFormation::Output named arda-ardamails-zone. No deletions, no replacements, no logical-ID changes on existing resources. If the diff shows anything else, abort and investigate. The success criteria are explicit, so this gate is cleared by the implementer (with AWS access to the Root account); a separate reviewer is not required.

Execution Phase C: PR closure

#	Task	Repository	Depends on	Acceptance criteria
T-C1	Mark documentation PR #70 ready for review (currently draft)	documentation	T-D1, T-D2, T-D3 (this plan)	Reviewer approves; CI green.
T-C2	Open infrastructure PR (Arda-cards/infrastructure)	infrastructure	T-I1 — T-I7	PR opens with the standard description template; CI green (npm run lint + build + test).
T-C3	Merge both PRs	—	T-C1 (merged), T-C2 (merged)	Both PRs merged. Post-merge CFN deploy of Root succeeds; cdk diff shows no drift.

The merge order is the human reviewer’s call. The two repos’ work is independent; no joint deployment is required. PR #70 (docs) can merge as soon as it is approved — it has zero impact on the infrastructure repo.

4. Dependency graph

5. Personas

Persona	Working directory	Agent name pattern
Documentation engineer	/Users/jmp/code/arda/projects/email-integration-worktrees/phase-2/documentation	docs-phase-2-<task> (Phase A, complete)
Infrastructure engineer	/Users/jmp/code/arda/projects/email-integration-worktrees/phase-2/infrastructure	infra-phase-2-<task> (Phase B)

A single-engineer execution can complete Phase B sequentially. Phase 2 has no operator-driven steps: the gates that historically required an “operator hat” (cdk diff at T-I4) are cleared by the implementer themselves, because the success criteria for each gate are explicit and verifiable from the implementer’s workstation (assuming the implementer has AWS access to the Root account; if not, the gate is cleared by whoever does have access).

6. Worktree strategy

The project follows a per-phase worktree convention: each active phase has its own subdirectory under projects/email-integration-worktrees/phase-N/, holding only the repositories that phase needs. Multiple phases coexist locally without branch-switching contention. Single worktree per repository within a phase; no multi-agent parallelism within a repository. Phase 2’s surface is too small to benefit from a parallel-agent split.

Repository	Worktree path	Branch	State
documentation	/Users/jmp/code/arda/projects/email-integration-worktrees/phase-2/documentation	jmpicnic/email-integration-phase-2-docs	Created 2026-05-05. Currently in use for Phase 2 documentation work (this task plan, the planning artefacts, the Phase 3 stub at 3-corporate-updates/).
infrastructure	/Users/jmp/code/arda/projects/email-integration-worktrees/phase-2/infrastructure	jmpicnic/email-integration-phase-2-infra	Created 2026-05-05; branch was created off jmpicnic/email-integration-phase-1-infra. Currently empty (no Phase 2 commits yet); ready for T-I1. After T-I1..T-I7 land, push and open the PR.

No integration branch is needed — the two repos’ work is independent and each lands on its own branch (PR #70 for docs; the new infra PR will be opened once T-I7 is committed).

7. Acceptance gates

A gate is a checkpoint where the team confirms readiness to proceed.

Gate	Trigger	Confirms
Gate 1: Documentation review (post T-D3 / pre T-C1)	All three docs tasks complete; make pr-checks passes	Reviewer agrees the planning artefacts are sound and the DQ-R1-006 framing is accepted.
Gate 2: Rename safe (post T-I2)	RootDnsStack rename done; CFN-name preservation comment present	Inline-comment grep test (V-IAC-003) passes; npm run build clean; no in-repo references to the old class or path remain.
Gate 3: cdk-diff additive only (post T-I4 / pre T-I5)	cdk diff --app apps/Root/r53-zones.ts against deployed Root	Diff is additive (one new zone, one new output). No deletions, no replacements, no logical-ID churn on existing resources. Hard stop if the diff shows anything else.
Gate 4: Infrastructure CI green (post T-I7 / pre T-C2)	npm run lint, npm run build, npm test all pass	Repo gate for opening the PR.
Gate 5: Phase 2 complete (post T-C3)	Both PRs merged; post-merge cdk diff of Root shows no drift	Phase 2’s exit criteria all met; downstream phases (3 / 4) unblocked.

8. Pre-execution checklist

Run through this list before T-I1 begins.

• PR #70 is at least at draft with the planning artefacts visible to the reviewer.
• PR #69 (Phase 1 docs) is approved and either merged or trivially mergeable so the rebase chain stays clean.
• PR #446 (Phase 1 infra) is in a similar state. If phase-1-infra is still open, branch phase-2-infra off it; if it has merged to main, branch off main.
• The implementer (or someone they can hand off to) has AWS access to the Root account, for cdk diff against the deployed stack at Gate 3.
• Local node_modules for the infrastructure repo are installed (npm install).

9. Post-execution checklist

After T-C3 merges:

• ../verification.md traceability table updated (every test row’s status is passed).
• ../../decision-log.md: DQ-R1-006 row’s Status is Resolved in the Summary table (already set in this PR; reconfirm post-merge).
• Phase 3 and Phase 4 implementors notified that the arda-ardamails-zone export and the AllowCreatingNSRecordsRole are available.
• (No worktrees to remove — existing worktrees are reused.)

10. Risk register

#	Risk	Likelihood	Impact	Mitigation
R-1	CFN stack id argument changed inadvertently during the rename	Low	Catastrophic — production Root stack is deleted and recreated; loses every Route53 zone, the IAM role partitions assume, and breaks the entire arda.cards family DNS chain.	Inline preservation comment at the constructor site (T-I2); grep test V-IAC-003 enforces both the literal "RootConfiguration" argument and the comment text; the cdk-diff additive-only check at Gate 3 catches any stack-recreation that would have slipped through (the cdk diff would show a delete + create rather than additive-only resources).
R-2	CDK assigns new logical IDs to existing resources after the rename, causing CFN drift	Low	High — a logical-ID churn on a PublicHostedZone triggers replacement, which changes the assigned NS values and breaks every downstream NS delegation.	Gate 3’s cdk diff review explicitly looks for any logical-ID changes on existing resources. If detected, reorder the rename so logical IDs are stable, or use RemovalPolicy.RETAIN overrides as a hotfix.
R-3	An in-repo import of the old RootConfigurationStack class or path is missed	Medium	Low — tsc --noEmit would flag it before deploy, but a missed reference in a script (non-TS) could ship.	Grep tests V-IAC-001, V-IAC-002 cover the source set. Phase 2 includes T-I1’s grep -rn "apps/rootConfiguration" pre-flight check.
R-4	ardamails.com registrar configuration does not match the Route53-assigned NS values	Low	Medium — DNS resolution for ardamails.com fails until corrected.	After first deploy, the operator confirms registrar NS values match the four Route53-assigned NS values and updates the registrar if needed. (Manual; documented in ../exports.md § 4.)
R-5	phase-1-infra PR (#446) merges and rebases shift the infrastructure stack base	Medium	Low	Use git rebase main (or gh stack sync if the stack is registered) before opening PR T-C2; CI re-runs catch any merge friction.

11. Out of scope of this plan

• NS-delegation entry for arda.ardamails.com — written by Phase 3’s Corporate stack via WriteNSRecordsToUpstreamDns; see DQ-R1-006.
• Reserving arda in the ardamails.com reserved-words list — Phase 3 deliverable.
• Per-partition mail sub-zones — Phase 4 deliverable.
• Tightening of AllowCreatingNSRecordsRole.allowedParentHostedZoneIds — not part of this project.
• Extraction of the IAM role to a RootSecurityStack — settled by DQ-013.

12. References

• ../specification.md — the contract this plan executes.
• ../requirements.md — requirement IDs referenced in acceptance criteria.
• ../verification.md — test IDs referenced in acceptance criteria.
• ../analysis.md — current-state assessment.
• ../exports.md — cross-phase contracts.
• ../../phases.md — Phase 2’s place in the overall project sequence (patched in PR #70).
• ../../decision-log.md — decisions including DQ-R1-006.