Phase 4 — Planning Shape Evaluation

1. Purpose

This document records the assessment of Phase 4’s size and shape against the canonical project-decomposition thresholds, with a recommended planning shape for implementation execution. It is produced before run-level planning artefacts so the decomposition choice is explicit and challengeable.

Inputs evaluated:

../design/specification.md — task contract (T-I, T-O, T-D series; STOP gates; AWS-impact classification).
design/plan/task-plan.md (since removed; see § 7) — existing execution view authored at design time.
../design/analysis.md — capability decomposition + 7-PR rollout DAG.
../goal.md — Phase 4 origin of intent + scope + deliverables.

2. Sizing assessment

2.1 Quantitative thresholds

Factor	Single-team threshold	Phase 4 value	Verdict
Total tasks	1–15	29 (T-I1..T-I13 + T-O1..T-O8 + T-D1..T-D8)	Split
Distinct phases with sequential dependencies	1–2	4 (Execution Phase A workspace; Phase B per-partition rollout × 4 partitions; Phase C drift; Phase D documentation)	Split
Distinct persona types needed	1–4	2 (`devops-engineer` for PRs #1–#6; `technical-writer` + `quality-reviewer` for PR #7)	Below threshold
Estimated working directories	1	2 base + run-N worktrees (`phase-4/documentation` + per-run infrastructure worktrees `phase-4/infrastructure-run-{1,2,3,6}`). Post-DQ-R1-026 the original `infrastructure-run-{3-stage, 4-demo, 5-prod}` worktrees collapse into a single `phase-4/infrastructure-run-3` cascade worktree.	Split
Cross-cutting concerns (handoffs, gates)	0–1	6+ (per-task STOP gates; T-O1 pre-flight; T-O2 Root no-drift; per-partition `cdk diff` approval; T-O4 Postmark Compliance reply; T-O8 first scheduled drift run; operator sign-off table)	Split
Tasks with external validation	1–5	12+ per rollout (4 partitions × `dig` for {NS, SPF, DMARC, DKIM, Return-Path} + Postmark Console verification per partition + AWS SDK + `gh` checks)	Split

5 of 6 quantitative factors indicate split.

2.2 Qualitative factors

Context window pressure: HIGH. A single team-lead tracking the four per-partition rollouts (each with operator dependencies, cdk diff review, sign-off recording) plus the drift workflow plus the documentation retrofit would burn context per partition. The DQ-R1-021 amendment (partial order dev → {stage || demo} → prod) allows the two middle partitions to be authored by distinct agents on distinct worktrees, which further reduces per-agent context pressure.
Error blast radius: HIGH. DQ-R1-021’s dev-first / prod-last invariants exist precisely to limit blast. A prod deploy failure that contaminated the prior partitions would be the worst case; per-partition isolation is load-bearing. The partial-ordering refinement preserves these invariants (dev validates the design before any other partition; prod waits for both stage and demo to be signed off) while allowing the two middle partitions to overlap.
Natural phase boundaries: STRONG. Every PR ends with operator gates that pause execution (cdk diff review, Postmark Console verification, dig confirms, sign-off entry, Postmark Compliance reply). The user/operator is the choreographer between PRs whether or not the decomposition is formalised.

All three qualitative factors apply.

3. Recommended planning shape

Decompose into runs. The original 7-PR rollout pinned in ../design/specification.md § 3 maps to a run structure prescribed by the decomposition skill. After PR #462 entered review, the three sequential per-partition rollout runs (originally run-3-stage-rollout, run-4-demo-rollout, run-5-prod-rollout) collapsed into a single operator-cascade run per DQ-R1-026. The five-run shape that results is still below the per-team threshold internally; the consolidated run-3-operator-cascade absorbs the partial-ordering choreography (dev → {stage || demo} → prod) inside its single PR.

3.1 Run mapping (post DQ-R1-026)

Run	PR	Group(s)	Scope	Tasks	Working dir(s)	AWS impact
`run-1-workspace-refactors`	#1	G-A	Construct generalisation + byte-identity guard + accessor + reserved-words extension + helper extraction	T-I1, T-I2, T-I3, T-I7, T-I9, T-D1, T-D3, T-O2 (post-merge)	`phase-4/infrastructure` (+ verification entry on doc side)	Synth-only + Root read-only diff
`run-2-dev-rollout`	#2 (PR #462)	G-B+C+D	Code for all four active partitions (dev / stage / demo / prod) — `platforms.ts` `mail` blocks, `PartitionEmailStack`, Pre-Deploy CLI, `amm.sh` step, four `mail` blocks in `platforms.ts`. No partition deploys at this run’s boundary.	T-I4, T-I5-dev/stage/demo/prod, T-I6, T-I8, T-I10, T-D1, T-D8	`phase-4/infrastructure-run-2`	Synth-only at this run’s boundary
`run-3-operator-cascade`	#3	G-B+C+D operator surface	Operator-driven cascade across `dev` → T-O4 → `{stage \|\| demo}` → `prod`. Single PR captures CHANGELOG + accumulated `cdk.context.json` + any code fixes.	T-O1-{dev,stage,demo,prod}, T-O3, T-O4, T-O5, T-O6, T-O7, T-D1, T-D8	`phase-4/infrastructure-run-3`	Resource-touching (Alpha002 + Alpha001) — production deploy included
`run-6-drift-workflow`	#4	G-E	`runtime-platform-drift.yml` + driver + shared utility extraction	T-I11, T-I12, T-I13, T-D1, T-D8, T-O8	`phase-4/infrastructure-run-6`	None (workflow + driver only)
`run-7-documentation`	#5	G-F	current-system retrofit + rotation runbook + `secret-delivery-pattern.md` content fill + docs CHANGELOG	T-D4, T-D5, T-D6, T-D7, T-D2	`phase-4/documentation`	None

Run numbering retains the gap at run-4 / run-5 to keep cross-references in specification.md, verification.md, and PR #462’s CHANGELOG entry stable. PR sequence numbers (#1 through #5) reflect the actual count of PRs after DQ-R1-026.

3.2 Execution model

Each run gets its own project-plan.md (task list + persona assignments + worktree section + entry/exit criteria) and validate-exit.sh (executable exit-criteria check).
A top-level choreography.md captures sequencing, operator-gate handoffs, and artifact dependencies between runs.
Each run launches independently via /launch-team plan/runs/run-N-<name>; the user is the choreographer between runs (resolving operator gates, monitoring Postmark Compliance ticket, approving cdk diff per partition).
Per-run context isolation: launching run-3-operator-cascade does not require the team-lead to re-track run-1’s construct generalisation in detail — it is done and verified.

3.3 Why formalise the already-implicit decomposition

The PR sequence in ../design/specification.md § 3 already describes the same 7-run shape. Formalising adds:

Executable exit gates: the spec’s STOP gates are prose; validate-exit.sh makes them mechanically runnable (e.g., dig NS dev.ardamails.com @8.8.8.8 | grep -q ardamails-ns).
Explicit choreography document: per the decomposition skill, “describes the execution sequence, artifact dependencies, and hand-off protocol between runs”. Useful when 4 of 7 runs include operator gates.
Re-launchability: if a cascade entry inside run-3-operator-cascade needs a second attempt (transient AWS issue, mid-deploy halt), the entry boundary inside the run is clean — re-run that partition’s amm.sh invocation against the existing worktree without disturbing prior partitions in the cascade.
Permission-prompt economy (see § 5): one bash validate-exit.sh invocation encapsulates many checks behind a single harness Bash call.

Cost: ~7 small docs (~50–80 lines each) + 7 short shell scripts, derived mechanically from the existing specification.md / task-plan.md. Modest.

4. Alternative shape (lower ceremony)

Keep design/plan/task-plan.md (since removed; see § 7) as the single execution doc; launch teams ad-hoc per PR; rely on the user as operator/choreographer using the spec’s STOP gates. Works because the PR sequence is itself the natural decomposition, but loses:

The executable exit gates.
The explicit choreography document.
Per-run context isolation when launching.

5. Open questions and decisions

#	Question	Status
1	Should the formal decomposition produce one `plan/` directory at the project root, or extend the existing `design/plan/` location of `task-plan.md`?	Open — current `design/plan/task-plan.md` is inside `design/`; if `plan/` lives at the project root, the two locations diverge. Sub-question: does `task-plan.md` move out of `design/plan/` once the run-level plans exist?
2	Does the documentation worktree (`phase-4/documentation`) need its own run for the design-doc maintenance during implementation, or only for run 7’s content retrofit?	Working assumption: design-doc maintenance ride alongside the relevant infra run’s PR description / comments, not as a separate run. Run 7 is the only standalone docs run.
3	Does `run-6-drift-workflow` block on the cascade reaching `prod`, or can it land after the cascade’s `dev` entry verifies?	Per `../design/analysis.md` DAG: soft dependency — can land any time after Run-3’s `dev` cascade entry verifies. Recommendation: open Run-6 once `dev` is live so the drift probe is exercised early.
4	(Resolved by DQ-R1-026) Should the per-partition rollout be one run per partition (original shape: three CHANGELOG-only PRs) or one cascade run (new shape: one PR with execution log + accumulated `cdk.context.json` + any code fixes)?	Resolved: cascade. The execution log is the durable artefact; three sequential CHANGELOG-only PRs added review churn without commensurate content.

6. References

process/craft/analysis-and-design/project-decomposition.md — canonical decomposition skill.
process/craft/project-management/project-planning.md — single-team planning workflow (for projects below the split threshold).
../design/specification.md — Phase 4 task contract.
design/plan/task-plan.md (since removed; see § 7) — existing design-time execution view (see § 7 below for relationship to this evaluation).
../design/analysis.md — capability decomposition + DAG.
../goal.md — Phase 4 intent.

7. Relationship to the original `design/plan/task-plan.md`

The original design/plan/task-plan.md was an execution view authored as part of the Phase 4 design package. It contained the 7-PR rollout, dependency DAG, acceptance gates, risk register, persona table, and worktree strategy in a single file.

Decision adopted (2026-05-12): the formalised decomposition was applied (Option A in § 3) AND the original task-plan.md was removed. Its valuable content was extracted into the new plan/ tree before deletion:

The 7-PR rollout, dependency DAG, and acceptance gates moved into choreography.md at the run level.
Each PR’s task list, exit criteria, and worktree details moved into runs/run-N-<name>/project-plan.md per run (see runs/run-1-workspace-refactors/project-plan.md for the canonical shape).
Skills consulted, the CI Observer note, the project-closure procedure (move to roadmap/completed/, worktree retirement commands, implementation byproducts list), and the Phase 4 completion checklist moved into choreography.md §§ 7, 8, 9, 10.
The risk register stays where it always was, in ../design/specification.md § 5 (the original task-plan.md § 6 was an explicit duplicate of that section).

The original task-plan.md is preserved in git log for historical reference; the live tree is the formalised decomposition.