Phase 3 -- Corporate Updates -- Task Plan
Execution plan for Phase 3, derived from ../specification.md. This document is the team’s executable view: tasks, dependencies, worktree strategy, branch model, acceptance gates, and the risk register. The specification remains the contract; the plan is how it gets done.
1. Overview
Section titled “1. Overview”Phase 3 stands up the Corporate instance group with its first asset (the Free Kanban Tool) using the Revision-1 declarative pattern. The work is two-repository:
Arda-cards/documentation— destination for all long-lived documentation deliverables this phase produces, each landing under the standard tree for its kind:- Project artifacts at
roadmap/in-progress/email-integration/3-corporate-updates/— the Pass-1 / Pass-2 planning files and the implementation byproducts (implementation/*.md). - Design / decision-log entries at
roadmap/in-progress/email-integration/decision-log.md(Round R1-Phase3). - Operator runbook at
process/sre/runbooks/<name>.md— the long-lived runbook for the Postmark domain-verification procedure that Phase 3 establishes and future Corporate or partition consumers reuse. The Phase-1 stub at3-corporate-updates/operator-domain-verification-checklist.mdis the seed; the expanded runbook is authored at the SRE runbooks home, not in the project directory. - Current-system pages at
current-system/oam/andcurrent-system/runtime/— describing what was built, post-deploy. - Anything written for an audience beyond the implementer (operators, future implementers, reviewers, integrators) lives in this repository under one of the trees above.
- Project artifacts at
Arda-cards/infrastructure— IaC code (CDK constructs, stacks, app, instance config), the Corporate CLI, the drift-detection workflow, and per-repo concerns (infrastructure/CHANGELOG.md,infrastructure/knowledge-base/if any new repo-specific patterns surface).
A small set of operator actions (out of either repository’s source control) brackets the deploy: provisioning a Google-Workspace mailbox, running the Corporate CLI from the operator workstation, and the optional Postmark Console click-through for sandbox-to-live approval.
Effort shape: 21 tasks across four execution phases plus closure (Phase A: 3 contract-docs tasks; Phase B: 10 infrastructure tasks; Phase C: 5 deploy + verification tasks including the new T-O0 pre-deploy state assertion; Phase D: 3 system-docs + byproduct tasks; Phase E: 5 PR-closure tasks). Single-engineer execution is feasible. Estimated wall-clock: 3-5 working days for Phases A through C, dominated by the Postmark thin-wrapper authoring (I3) and the Corporate CLI (I9). Phase D’s wall-clock depends on what’s discovered during the deploy.
Two project-wide working agreements (per spec § 1.5 and § 1.6) bind every task in this plan:
- Tests ship with code. Every task that introduces or modifies executable code carries parallel tests in the same PR; the STOP gate does not clear without passing tests.
- Documentation gets a quality review. Every task that produces durable documentation is reviewed by a specialized agent (
technical-writerorquality-reviewerwith a docs brief) before its STOP gate clears.
Agent execution notes (orchestration metadata)
Section titled “Agent execution notes (orchestration metadata)”This subsection lists the Claude Code skills relevant to each phase’s tasks. It is not specification content — it is guidance for an AI sub-agent executing the work. Human readers can skip this without loss.
Implementation skills (Phase B + Phase C):
typescript-coding— TypeScript style for new constructs, stacks, instance config, andcorporate-cli.ts.cdk-infrastructure— CDK conventions; CFN-stack-name immutability; the platform-vs-stacks-vs-constructs hierarchy.unit-tests-infra— CDKTemplate-matcher + injected-dependency tests (mirrorstools/drift-check.test.ts).postmark— Postmark Account API conventions for server / sending-domain creation,verifyDkim/verifyReturnPath, idempotent list-then-create, webhook config. Heavy relevance to Tasks I3 and I9.api-access— credentialed API patterns: 1Password DesktopAuth (local) /OP_SERVICE_ACCOUNT_TOKEN(CI); bounded retries; redacted logging.
Documentation and decision skills (Phases A and D):
document-writing+path-conventions—.md-extension link convention; frontmatter; en_US locale.plantuml-diagrams— the dependency graph in § 4 follows this skill; future architectural diagrams (e.g., a CLI sequence diagram in Phase D) follow the same conventions.decision-log— Round R1-Phase3 was authored under this skill. New questions during implementation becomeDQ-R1-017+entries.design-document— when a deeper design pass is needed (e.g., a sequence diagram for the Phase A orchestration), follow this convention.
Process and PR skills (every phase):
pr-steward— once each PR opens, this skill drives CI monitoring, reviewer-comment triage, and mergeable-state confirmation. Phase 1 / Phase 2 used it for every comment round; Phase 3 follows the same pattern.gh-stack— the documentation Wave-1 PR is the latest entry in the stacked-PR chain (rev1-design→phase-1-docs→phase-2-docs→phase-3); cascade-rebase via this skill when lower PRs merge.release-lifecycle— CHANGELOG version-bump rules (validated byclq); one-entry-per-PR discipline.implementation-task— the analysis / planning / byproduct workflow. Phase D’simplementation/*.mdbyproducts are authored under this skill.
Highest-risk concerns:
- Resource-touching deploy (Task O2). The first Corporate-Resource-Group deploy creates a new hosted zone, NS-delegation record, SPF / DMARC records, Free Kanban DNS records, a Postmark Sender Signature, a Postmark server, and a 1Password item. The blast radius is contained (no existing partition is affected; the
ardamails.comzone gains one new sub-zone delegation), but the AWS-impact is real and rollback for the Postmark + 1P side requires manual operator action (perphases.md§ Phase 3 Recovery). - Phase A token-handling correctness. The Postmark Server API token is shown once at server creation. Phase A (
corporate-cli prepare) must persist it to 1Password before any other side-effect that could fail; failure semantics are documented inDQ-R1-013. - CFN stack-name immutability for the new Corporate stacks. The CDK
idargument passed toCorporateMailDns(...)andFreeKanbanToolMailDns(...)becomes the published CloudFormation stack name and must not change in any future PR.
2. Repositories
Section titled “2. Repositories”| Repository | PR wave | Branch | Base branch | Purpose |
|---|---|---|---|---|
Arda-cards/documentation | Wave 1: contract docs PR | jmpicnic/email-integration-phase-3 | jmpicnic/email-integration-phase-2-docs | Phase 3 contract planning artifacts (Pass 1 + Pass 2); phases.md patches; Round R1-Phase3 in decision-log.md. Does not include current-system/ pages, the operator runbook, or the implementation byproducts — those land in Wave 2. |
Arda-cards/infrastructure | Single PR | jmpicnic/email-integration-phase-3 | jmpicnic/email-integration-phase-2-infra | Construct rename + new constructs; Postmark thin-wrappers; Corporate stacks; Corporate App; instance config; Corporate CLI; drift workflow; CHANGELOG; tests. |
Arda-cards/documentation | Wave 2: system-docs PR (post-deploy, Phase D) | jmpicnic/email-integration-phase-3 | main (Wave 1 has already merged) | current-system/oam/ and current-system/runtime/ pages describing what was built; the long-lived operator runbook at process/sre/runbooks/postmark-domain-verification.md; 3-corporate-updates/implementation/*.md byproducts; CHANGELOG amendment. |
All branches across the three rows share the same name — jmpicnic/email-integration-phase-3. The repository the branch lives in is identified by the repository row, not by a branch suffix. In the documentation repo the same name is reused across Waves 1 and 2: Wave 1’s branch is deleted (or auto-deleted on merge); Wave 2’s branch is created fresh from main after Wave 1 merges. At no point do two branches with this name coexist in the same repository.
The Wave-1 contract docs PR and the infrastructure PR are independent — no code dependency from one repository on the other — but the contract docs PR should land first or in parallel because the contract (the planning artifacts and the Round R1-Phase3 decisions) is what the implementer’s PR description references. The Wave-2 system docs PR is chronologically last: it opens after both Wave-1 PRs have merged and Phase C’s deploy has completed.
The branch model follows the project’s stacked-PR convention: Wave 1 in documentation stacks on phase-2-docs (PR #70); the infrastructure branch stacks on phase-2-infra (PR #448); Wave 2 in documentation opens directly off main (since Wave 1 has merged by then). Per the branch-naming rule recorded in the project-level CLAUDE.md under projects/email-integration-worktrees/, Phase 3 branches use the canonical name jmpicnic/email-integration-phase-3 in every repository they appear in.
3. Phases (within Phase 3’s execution)
Section titled “3. Phases (within Phase 3’s execution)”The specification tasks fall into four execution phases. The split honors the principle that contract documentation comes first (so the implementer has a target) and system documentation comes last (so it benefits from deploy-time learnings, the Phase 2 IMPORT-detour pattern being the canonical example of why this matters).
Execution Phase A: Contract documentation (this PR)
Section titled “Execution Phase A: Contract documentation (this PR)”| # | Spec ref | Task | Repository | Acceptance criteria | Verifies |
|---|---|---|---|---|---|
| T-D1 | Task D1 | Author Pass-2 planning artifacts (requirements, specification, verification, exports, plan/task-plan — this file) | documentation | Files exist with valid Starlight frontmatter; cross-links resolve; make pr-checks passes. analysis.md and decision-log.md Round R1-Phase3 already landed in the Pass-1 commit. | V-DOC-001 |
| T-D3 | Task D3 | Patch phases.md Phase 3 deliverables table (Postmark Sender Signature row + corporate-drift.yml row) | documentation | Patch applied; reviewer confirms it reflects the spec’s deliverable list. | V-DOC-001 |
| T-D4 | Task D4 | CHANGELOG entry under [0.31.0] for the contract artifacts | documentation | make clq passes; entry covers requirements.md, specification.md, verification.md, exports.md, plan/task-plan.md, the phases.md patch, and the Round R1-Phase3 entries. | — |
All Phase A tasks land on
jmpicnic/email-integration-phase-3(this branch / this PR). System documentation (D2) and byproducts (D5) explicitly do not land here — they live in Phase D’s follow-up PR.
Execution Phase B: Infrastructure implementation (sequential within dependency graph)
Section titled “Execution Phase B: Infrastructure implementation (sequential within dependency graph)”The nine specification tasks I1-I9 plus the infrastructure CHANGELOG (Task I10) execute on jmpicnic/email-integration-phase-3 in the Arda-cards/infrastructure repository (same canonical branch name as in documentation; the repo identity disambiguates them). Each task’s STOP point gates entry to its successors.
| # | Spec ref | Task | Acceptance criteria | Verifies |
|---|---|---|---|---|
| T-I1 | Task I1 | Rename route-53-hosted-zone.ts → dns-zone.ts; migrate every caller | git mv preserves history; grep -rn "Route53HostedZone|route-53-hosted-zone" returns zero hits across src/, tools/, apps/; npm run build, npm test, and the existing CDK matrix all pass; per-app template diff against the pre-rename baseline is empty. | V-IAC-002 |
| T-I2 | Task I2 | Add dns-email-records.ts xgress construct | New construct + tests; npx jest for the new test file passes; construct synthesizes against a fixture hosted zone. | V-IAC-003 |
| T-I3 | Task I3 | Add Postmark thin-wrapper constructs (server.ts, sending-domain.ts) | New constructs under platform/constructs/postmark/; injected-mock unit tests cover idempotency, Built shape, error handling. | V-IAC-001 |
| T-I4 | Task I4 | Reintroduce FREE_KANBAN_POSTMARK_ITEM; extend ari-configuration.ts; extend drift-check | Typed reference declared with the Arda-CorporateOAM vault and item title; reserved-words constant added; tools/drift-check.test.ts updated (count 3 → 4); the OP_SERVICE_ACCOUNT_TOKEN-resolution test still asserts only the three Phase-1 items. | V-IAC-007, V-IAC-008, V-CI-004 |
| T-I5 | Task I5 | Add instances/Corporate/free-kanban-tool.ts declarative configuration | New file imports from platform/postmark-service.ts and platform/one-password.ts; exports the typed FREE_KANBAN_CONFIG object. | V-IAC-006 |
| T-I6 | Task I6 | Add Corporate stacks (CorporateMailDns, FreeKanbanToolMailDns) | Stacks composed per the spec; CDK Template tests pass; inline CFN-stack-name preservation comments in place at each constructor call. | V-CORP-001-V-CORP-005, V-CORP-008, V-IAC-004 |
| T-I7 | Task I7 | Add apps/Corporate/index.ts (App class) + tools/cdk-corporate.ts (entry script) + CI step | App synthesizes via cdk-corporate.ts against fixture context; ci-corporate-check.js exercises the synth in CI. | V-IAC-005 |
| T-I8 | Task I8 | Add corporate-drift.yml workflow + driver | Workflow file lints; driver tests pass with injected mocks; manual workflow_dispatch smoke run is deferred to Phase C (after deploy). | V-CI-001, V-CI-002, V-CI-003 (post-deploy) |
| T-I9 | Task I9 | Author tools/corporate-cli.ts (Phase A + Phase B subcommands + verify) | CLI has prepare, deploy, verify subcommands at minimum; tests cover idempotency, conflict-check, server-token write ordering, redaction; after server creation Phase A emits a server-delivery-type log event (info for Live, warn for Sandbox/unknown) derived from GET /servers/{id} — not from any account-level endpoint (there is no Postmark account sandbox API); corporate-cli prepare free-kanban --dry-run smoke against a NonProd fixture succeeds. | V-CLI-001-V-CLI-008 |
| T-I10 | Task X (infra portion) | CHANGELOG entry under [2.30.0] (Added for the new constructs / stacks / app / instance / CLI / workflow / typed reference / reserved-words; Changed for the route-53-hosted-zone.ts → dns-zone.ts rename) | clq validation passes via the infrastructure repo’s CI gate. | — |
STOP — review and approval after T-I9. Run corporate-cli prepare free-kanban --dry-run --account postmark-non-prod. Confirm the structured output (account-token resolution, conflict-check pass, server-listing succeeds, the dry-run summary matches expectations). Run npx cdk diff --app "npx ts-node src/main/cdk/tools/cdk-corporate.ts" against fresh empty state — the synthesized template should be identical to the local fixture’s expectations. The next task (O2) is the first Resource-touching deploy.
Execution Phase C: Operator deploy + verification
Section titled “Execution Phase C: Operator deploy + verification”| # | Spec ref | Task | Repository / system | Depends on | Acceptance criteria | Verifies |
|---|---|---|---|---|---|---|
| T-O0 | Task O0 | Pre-deploy state assertion — AWS, Postmark, 1Password, GitHub, repo state | All systems Phase 3 will touch | Wave-1 contract docs PR merged; infra PR ready (CI green) | Every assertion in spec § Task O0 passes; if any fails, abort and investigate before proceeding. | — |
| T-O1 | Task O1 | Provision dmarc-reports@arda.cards mailbox in Arda’s Google Workspace | Google Workspace (operator) | T-O0 cleared | Mailbox exists; test mail to it returns receipt within 2 minutes. | V-OPS-001 |
| T-O2 | Task O2 | Phase A run + Phase B deploy (corporate-cli prepare free-kanban; corporate-cli deploy free-kanban) | PostmarkProd, Arda-CorporateOAM, platformRoot AWS | T-I9 merged; T-O1 confirmed | Phase A creates Sender Signature, server, 1P item, cdk.context.json. cdk diff is additive-only. After confirmation, cdk deploy succeeds. Final cdk diff against deployed = zero differences. | V-CORP-001-V-CORP-010, V-CLI-002-V-CLI-007 |
| T-O3 | Task O3 | Post-deploy verification + operator companion | PostmarkProd, recipient inbox, documentation | T-O2 deployed | verifyDkim and verifyReturnPath API calls return verified. (If sandbox) sandbox-to-live approval submitted. End-to-end smoke send: Authentication-Results shows dkim=pass, spf=pass, dmarc=pass. Operator companion published. | V-CORP-007, V-OPS-002-V-OPS-004, V-DOC-004 |
| T-O4 | — | Trigger the first scheduled corporate-drift.yml run (or manual workflow_dispatch) | Arda-cards/infrastructure Actions | T-O2 deployed | Workflow run completes successfully on green Corporate state; on injected drift, opens an issue with the configured labels. | V-CI-001-V-CI-003 |
Execution Phase D: System documentation + byproducts (follow-up docs PR)
Section titled “Execution Phase D: System documentation + byproducts (follow-up docs PR)”Authored after Phase C deploys and verifies. A new branch in Arda-cards/documentation — reusing the canonical name jmpicnic/email-integration-phase-3 after Wave 1 has merged and its branch has been deleted — opens off main. This PR holds only the post-implementation deliverables.
| # | Spec ref | Task | Repository | Depends on | Acceptance criteria | Verifies |
|---|---|---|---|---|---|---|
| T-D2 | Task D2 | Author the current-system/ pages by content type (OAM and runtime) describing what was built | documentation | T-O2 deployed; T-O3 verified | New pages under current-system/oam/ and current-system/runtime/; cross-links resolve; make test-links zero broken; make test-smoke passes. Pages reflect the deployed state, not the prescribed state. | V-DOC-003 |
| T-D5 | Task D5 | Author Phase 3 implementation byproducts (implementation/{changelog,learnings,suggestions,alternatives,skipped,specification-post}.md) | documentation | T-O3, T-O4 complete | Byproducts authored per the implementation-task skill convention; cross-link with Phase 1 / Phase 2 byproducts; specification-post.md records any contract drift discovered during implementation. | V-DOC-004 |
| T-D6 | Task D6 | New top CHANGELOG entry covering D2 + D5 | documentation | T-D2, T-D5 | make clq passes; entry covers the system documentation pages and the byproducts. | — |
Why the follow-up PR: holding the contract docs PR (this branch) open until after deploy would couple unrelated review cycles. The cleaner shape is: contract docs PR closes once approved; system docs PR opens after deploy and contains content that benefits from the deploy experience.
Execution Phase E: PR closure
Section titled “Execution Phase E: PR closure”| # | Task | Repository | Depends on | Acceptance criteria |
|---|---|---|---|---|
| T-X1 | Mark contract documentation PR (this branch’s PR) ready for review | documentation | T-D1, T-D3, T-D4 | Reviewer approves; CI green. |
| T-X2 | Open infrastructure PR (Arda-cards/infrastructure) | infrastructure | T-I1 — T-I10; T-O2 (deploy verifies the diff) | PR opens; CI green; reviewer approves. |
| T-X3 | Merge contract docs PR + infra PR | — | T-X1 (merged), T-X2 (merged) | Both PRs merged. |
| T-X4 | Open follow-up system-documentation PR (Phase D) | documentation | T-X3 (contract docs merged); T-D2, T-D5, T-D6 ready | PR opens; CI green; reviewer approves. |
| T-X5 | Merge system-documentation PR | — | T-X4 (merged) | PR merged. |
The merge order is the human reviewer’s call. The two implementation repos’ work is independent; the deploy gate (T-O2) precedes the infrastructure-PR merge because the deploy is the final source of truth for the diff. The system-documentation PR merge (T-X5) is by construction the last gate to clear for this phase.
4. Dependency graph
Section titled “4. Dependency graph”Two arrow types in the graph: solid arrows are blocking dependencies between coding tasks; dotted arrows are “becomes-available” relationships (the downstream task can start as soon as the upstream is reviewable, even before merge). Phase A’s tasks dotted-into Phase B’s roots reflect that the implementer can begin Phase B against an open contract docs PR.
5. Acceptance gates
Section titled “5. Acceptance gates”Seven gates clear before Phase 3 is “done”:
- Gate 1 — Contract documentation published. All Pass-2 artifacts present;
phases.mdpatched; CHANGELOG entry valid;make pr-checksclean; documentation-quality-review pass clean. Cleared by reviewer of the contract documentation PR. - Gate 2 — Infrastructure code complete and tested. All I-tasks committed;
npm run lint,npm run build,npm testclean; CDK matrix CI exercisesapps/Corporate/; every code task ships with passing tests per spec § 1.5. Cleared by reviewer of the infrastructure PR. - Gate 3 — Pre-deploy state confirmed. Every assertion in spec § Task O0 (T-O0) passes — prior PRs merged; AWS state matches Phase-2 baseline; no leftover Corporate state in PostmarkProd /
Arda-CorporateOAM; account credentials resolve. Cleared by the operator running T-O0. - Gate 4 — Operator prerequisites confirmed.
dmarc-reports@arda.cardsmailbox provisioned (T-O1) AND the dry-run check (corporate-cli prepare ... --dry-run) succeeds. Cleared by the operator. - Gate 5 — Phase B deploy clean.
cdk diff apps/Corporate/against deployed reports zero differences (post-deploy).digconfirms every record. Postmark API confirms Sender Signature is verified for both DKIM and Return-Path. 1Password resolves the Free Kanban server-token reference. Cleared by the operator after T-O2 + initial steps of T-O3. - Gate 6 — End-to-end smoke send passes. Test email from Free Kanban Tool to a non-owner address shows
dkim=pass,spf=pass,dmarc=pass. Operator notes captured. Cleared by the operator at the end of T-O3. - Gate 7 — System documentation + runbook published. Cleared by reviewer of the system-docs PR. Two-tier checklist:
- Automated (CI validates):
current-system/oam/andcurrent-system/runtime/pages exist;process/sre/runbooks/postmark-domain-verification.mdexists; the six byproduct files are present under3-corporate-updates/implementation/;make pr-checks(clq+ build + link check + smoke tests) is green. - Reviewer judges: pages reflect what was actually deployed (not the pre-deploy guess); the runbook captures only steps without an API equivalent;
specification-post.mdrecords any contract drift found during implementation; the documentation-quality-review pass surfaces no blockers.
- Automated (CI validates):
The first scheduled corporate-drift.yml run (T-O4) is a confirmation gate but not blocking the phase: a drift detected in the first month is investigated and fixed under follow-up cycles, not under Phase 3.
6. Risk register
Section titled “6. Risk register”| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Postmark Server API token write to 1Password fails after server creation; token is unrecoverable from Postmark’s side. | Low | High (token gone; Postmark delete-server is destructive) | DQ-R1-013: in-memory buffer + retries; on permanent failure, redacted summary lets the operator paste the token via DesktopAuth before exiting Phase A. CLI tests cover the failure path. |
WriteNSRecordsToUpstreamDns CR Lambda fails at deploy time (cross-account assume-role failure even in same-account case). | Medium | Medium (NS record absent; arda.ardamails.com resolves but is not delegated from ardamails.com) | Pre-deploy: validate the role ARN exists and the CR Lambda’s IAM permissions are correct. On failure, re-run the deploy after fixing the role; CR is idempotent on stack update. |
| CFN stack-name immutability violated on a later edit. | Low | Catastrophic (CFN deletes-and-recreates the stack) | Inline source-code comment at every Corporate stack constructor call explicitly forbids changing the third positional argument. Unit test (CDK Template-matcher with grep on the source) asserts the comment exists. The PR-steward triage table flags any change to the constructor call. |
| Sandbox-to-live approval delays Phase B for 24+ hours. | Low (account may already be live; depends on PostmarkProd provisioning history) | Medium (smoke send in T-O3 cannot complete until live) | T-I9’s CLI surfaces the sandbox/live status at Phase A entry, so the operator knows up front. T-O3 step ordering tolerates an asynchronous wait: verifyDkim / verifyReturnPath succeed regardless of sandbox status; the smoke send is the only step requiring live status. |
Reserved-words extension conflicts with existing partition zone configurations (e.g., a partition tenant has slug arda). | Very low (documented reserved name; no observed conflict) | High (partition deploys break) | Pre-T-I4: grep partition instances/Alpha*/...ts for the literal string "arda" as a tenant slug. Confirm no match. |
dmarc-reports@arda.cards mailbox not provisioned in time; DMARC rua references a non-existent address. | Low (T-O1 is a 5-minute Google Workspace step) | Low (DMARC monitoring still works; the receiver-side bounce of rua mail is a deliverability concern but not a phase-blocker) | T-O1 is gated before T-O2 in the dependency graph. |
| Postmark sandbox quota or rate-limit hit during Phase A’s verify-loop. | Low | Low (Phase A retries; permanent failure surfaces a clear message) | The CLI’s verify step backs off on 429; tests cover the path. |
cdk.context.json write race when multiple operators run Phase A concurrently for different assets. | Very low (single-operator workflow) | Low (last write wins; subsequent re-runs converge) | Document operator workflow in the operator companion: one Phase A at a time per asset. |
7. Worktree strategy
Section titled “7. Worktree strategy”Single worktree per repository per PR wave. No multi-agent parallelism within a repository:
| Worktree path | Branch | Wave / Phase served | State |
|---|---|---|---|
projects/email-integration-worktrees/phase-3/documentation/ | jmpicnic/email-integration-phase-3 (in documentation repo) | Wave 1 — Phase A (contract docs) | Created 2026-05-06. Currently in use for Phase 3 contract documentation (this task plan and the other Pass-2 artifacts). Removed once Wave-1 merges. |
projects/email-integration-worktrees/phase-3/infrastructure/ | jmpicnic/email-integration-phase-3 (in infrastructure repo) | Phase B + C | Not yet created. Created when Phase B begins; branch off jmpicnic/email-integration-phase-2-infra. Removed once the infra PR merges. |
projects/email-integration-worktrees/phase-3/documentation/ | jmpicnic/email-integration-phase-3 (in documentation repo, recreated) | Wave 2 — Phase D (system docs + runbook + byproducts) | Not yet created. Created after Phase C deploy completes; branch off main (Wave 1 has already merged). Reuses the same path and the same branch name as the Wave-1 worktree, after the Wave-1 worktree has been removed. Removed once Wave-2 merges. |
All worktrees use the canonical branch name jmpicnic/email-integration-phase-3. The branch is unique by repository (one in documentation, one in infrastructure); within the documentation repo it is reused across Waves 1 and 2 sequentially, never simultaneously. Per the project-level CLAUDE.md’s branch-naming rule, the canonical name has no per-repo or per-wave suffix.
No integration branch is needed — each PR is independent and lands on its own branch.
8. Operator runbook touchpoints
Section titled “8. Operator runbook touchpoints”Operator actions concentrated in Phase C:
| Task | Operator action | Channel | Time |
|---|---|---|---|
| T-O0 | Run pre-deploy state assertion (gh pr view ..., cdk diff, Postmark Account API list calls, op read smoke) | Operator workstation | ~5 min |
| T-O1 | Provision dmarc-reports@arda.cards mailbox | Google Workspace admin console | ~5 min |
| T-O2 | Run corporate-cli prepare free-kanban | Operator workstation (DesktopAuth for 1Password) | ~3-5 min including conflict-check + verifyDkim/verifyReturnPath roundtrip |
| T-O2 | Review cdk diff and confirm corporate-cli deploy free-kanban | Operator workstation | ~2-5 min |
| T-O3 (sandbox-only) | Submit Postmark sandbox-to-live approval | Postmark Console | <5 min submit; 24h-3d approval wait |
| T-O3 | End-to-end smoke send | Free Kanban Tool UI | <2 min |
| T-O4 | Manual workflow_dispatch of corporate-drift.yml | GitHub Actions UI | ~3-5 min run |
The “API-over-GUI” rule from ../specification.md § 1.3 keeps Console visits to a minimum; only the sandbox-to-live submit is unavoidable when applicable.
9. References
Section titled “9. References”../analysis.md— gap analysis.../requirements.md— numbered requirements.../specification.md— task contract this plan executes.../verification.md— test catalogue with verification methods.../exports.md— cross-phase contracts produced.../operator-domain-verification-checklist.md— operator companion (stub at Pass-1; expanded just-in-time during T-O3).../../phases.md— full phase plan; Phase 3 section is patched in this round (T-D3).../../decision-log.md— decisions including newDQ-R1-009..016.
Copyright: © Arda Systems 2025-2026, All rights reserved