Phase 4 — Run 1: Workspace Refactors (G-A)

Overview

Branch / PR: jmpicnic/email-integration-phase-4 (infra worktree) → PR phase-4-G-A against Arda-cards/infrastructure main. Group: G-A (per ../../../design/analysis.md § 12.1). Tasks: T-I1, T-I2, T-I3, T-I7, T-I9, T-D1 (verification entries for those tasks), T-D3 (infra CHANGELOG), T-O2 (post-merge operator verification). Working directory: /Users/jmp/code/arda/projects/email-integration-worktrees/phase-4/infrastructure. AWS impact: Synth-only for the code change; Resource-read-only for T-O2 (compares against deployed Root template). Personas: devops-engineer for T-I*; quality-reviewer for the PR; user as operator for T-O2 (post-merge).

This run completes the workspace-level prerequisites for the per-partition rollouts. It does not deploy any new AWS resources; the Root account’s existing CFN template must remain byte-identical post-merge (REQ-IAC-002).

Entry criteria

The Setup phase in ../../choreography.md § 2 is complete: .claude/settings.local.json has the prompt-minimisation allowlist; validate-exit.sh scripts in this run can be invoked without ad-hoc prompts.
Phase 3 infrastructure PR #450 is merged (origin/main HEAD reflects Phase 3 closure). Confirmed during the rebase that landed PR #454.
jmpicnic/email-integration-phase-4 (infrastructure) is on origin and one merged ESLint PR (#454) is part of main OR the same branch carries the ESLint commits forward (current state).
phase-4/infrastructure worktree exists and is clean.

Tasks

Task	Description	Files touched	Persona
T-I1	Generalise `AllowCreatingNSRecordsRole` construct (discriminated-union trust principal) + class rename with construct ID preserved at call site	`src/main/cdk/constructs/oam/allow-creating-{ns,dns}-records-role.ts` + its test	`devops-engineer`
T-I2	Byte-equality unit test for the Root-account instantiation	`src/main/cdk/stacks/root/root-dns-stack.test.ts` (or sibling) + baseline JSON fixture	`devops-engineer`
T-I3	Add `postmarkCredentialOpReference(partition)` accessor	`src/main/cdk/platform/postmark-service.ts` + its test	`devops-engineer`
T-I7	Reserved-words list extension (`prod`, `demo`, `dev`, `stage`, `kyle`)	Phase 3 reserved-words registry file + its test	`devops-engineer`
T-I9	Extract TypeScript helpers from `corporate-cli` to `tools/lib/` (minimal cut per B3)	`tools/corporate-cli.ts` + new `tools/lib/*.ts` + tests	`devops-engineer`
T-D1	Author / extend V-NNN verification entries for the above	`documentation` worktree → `4-runtime-platform-updates/design/verification.md`	`devops-engineer` / `technical-writer`
T-D3	Infra `CHANGELOG.md` entry for this PR	`CHANGELOG.md`	`devops-engineer`
T-O2	Operator: post-merge, synth `RootDnsStack` and diff against deployed Root CFN	none (read-only operator check)	user (operator)

Detailed task specs in ../../../design/specification.md §§ T-I1..T-I3, T-I7, T-I9, T-D1, T-D3, T-O2.

Worktree strategy

Single working directory: /Users/jmp/code/arda/projects/email-integration-worktrees/phase-4/infrastructure. No nested worktrees. The verification entry (T-D1) requires a small edit on the documentation worktree (phase-4/documentation); the agent makes that edit directly, no separate worktree.

Validation

validate-exit.sh in this directory programmatically checks all entry and exit criteria. Invoke it from the run directory after each authoring iteration and before requesting merge.

Exit criteria

npm run build exits 0 in phase-4/infrastructure.
npm run lint exits 0 (zero new violations).
npm run test:eslint-rules exits 0.
npm test exits 0; in particular T-I2’s byte-identity test PASSES against the checked-in baseline.
T-I1’s construct tests cover both trustPrincipal.kind modes (lambdaOrgID and stsAssumeRole) + validateProps error paths.
T-I3’s accessor test asserts the four expected op://Arda-{Env}OAM/Postmark/credential references.
T-I7’s reserved-words test contains prod, demo, dev, stage, kyle, arda.
T-I9’s tools/lib/*.test.ts files exist and pass; tools/corporate-cli.ts imports from tools/lib/ (no inline reimplementation).
CHANGELOG.md has a new [X.Y.Z] - <today> entry under the file-edit model; section order Changed/Removed → Added/Deprecated → Fixed/Security; no ### Changed block if all changes are internal lint-config / refactors (per workspace memory feedback_changelog_categories).
PR opened on Arda-cards/infrastructure against main; checks green; reviewer approval received.
Post-merge: T-O2 — aws cloudformation get-template --stack-name RootConfiguration --profile Admin-Alpha1 matches a fresh cdk synth of RootDnsStack. Empty diff. Operator records in sign-off table.

References

../../choreography.md — sequencing across runs.
../../evaluation.md — decomposition rationale.
../../../design/specification.md — task contract.
../../../design/verification.md — V-IAC-001, V-IAC-002, V-PART-007, V-IAC-007, V-CLI-003.
../../../../decision-log.md — DQ-R1-020 (construct generalisation + rename override).