Phase 1 -- External Resources Provisioning -- Task Plan

Execution plan for Phase 1, 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 1 delivers the foundation of the email-integration project: the external resources Arda consumes (Postmark accounts, 1Password items, GitHub Actions secret) and the typed references downstream phases use to address them, plus the operator-facing documentation and the live drift-detection workflow.

Effort shape: 5 tasks, 2 repositories (infrastructure and documentation), 1 worktree per repository, single-agent execution recommended (no parallel-agent worktree split). Estimated wall-clock: 3-5 working days, depending on operator availability for the manual steps.

2. Repositories

Repository	Role	Branch	Purpose
Arda-cards/infrastructure	upstream	jmpicnic/email-integration-phase-1-infra	platform/ enrichment, drift workflow, removal of legacy parser-gated artifacts
Arda-cards/documentation	downstream	jmpicnic/email-integration-phase-1-docs	Postmark service overview, API observations note, operator runbook

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 operator runbook is referenced by Task 1.

3. Phases (within Phase 1’s execution)

The five spec tasks fall into three execution phases:

Execution Phase A: Documentation drafting (parallelisable with B and C)

#	Task	Repository	Depends On	Acceptance Criteria
T-A1	Draft current-system/oam/postmark-service/index.md (Postmark service overview)	documentation	—	Page exists with required content per REQ-DOC-001; make pr-checks passes
T-A2	Draft current-system/oam/postmark-service/postmark-api-observations.md	documentation	—	Page exists with required content per REQ-DOC-002; ~3-page target per REQ-DOC-003; make pr-checks passes
T-A3	Draft current-system/oam/postmark-service/operator-runbook.md	documentation	—	Page exists with all manual steps for REQ-EXT-001-REQ-EXT-005, troubleshooting table, sign-off section per REQ-OPS-001 — REQ-OPS-003; make pr-checks passes
T-A4	Update current-system/oam/index.md (or current-system/index.md) with discovery link	documentation	T-A1	Cross-link present per REQ-DOC-004; make test-links passes

Tasks T-A1, T-A2, T-A3 run in parallel; T-A4 follows once T-A1 lands.

Execution Phase B: Operator-driven external resources (sequenced after T-A3 reaches reviewable draft)

#	Task	Repository	Depends On	Acceptance Criteria
T-B1	Walk the operator runbook draft; confirm or complete each manual step	(none — external services)	T-A3 (draft)	All REQ-EXT-NNN items pass per V-EXT-001 — V-EXT-005; OP_SERVICE_ACCOUNT_TOKEN provisioned per V-CI-101
T-B2	Capture sign-off in the runbook (operator name, date, deviations)	documentation	T-B1	Sign-off section populated; runbook ready for merge

STOP — review and approval after T-B2. The team confirms the external resources are ready before code work proceeds.

Execution Phase C: infrastructure code work (parallelisable with A; gated on B for first deploy of drift workflow)

#	Task	Repository	Depends On	Acceptance Criteria
T-C1	Enrich platform/postmark-service.ts per spec Task 2	infrastructure	—	All exports per REQ-PLAT-001; tsc --noEmit passes; unit test V-PLAT-001 passes; CHANGELOG entry under “Added”
T-C2	Enrich platform/one-password.ts per spec Task 3	infrastructure	—	All exports per REQ-PLAT-002; unit test V-PLAT-002 passes; the no-string-literals lint test V-PLAT-003 passes (forward-looking; empty match set acceptable); CHANGELOG entry under “Added”
T-C3	Implement drift-check TypeScript module + unit tests	infrastructure	T-C1, T-C2	Module imports the constants from T-C1/T-C2; unit tests V-CI-001, V-CI-002, V-CI-003 pass
T-C4	Author the drift workflow at .github/workflows/external-resources-drift.yml (filename per OQ-1)	infrastructure	T-C3	Workflow file passes GitHub Actions schema validation; YAML structure matches spec Task 4; CHANGELOG entry under “Added”
T-C5	Trigger first workflow_dispatch run; confirm success	(CI)	T-C4, T-B2	Run completes successfully per V-CI-101, V-CI-102; no GitHub issue auto-created
T-C6	Delete the prior parser-gated HUMAN-STEPS.md and the parser code that referenced it (if any)	infrastructure	T-A3 (canonical runbook published)	Files removed; grep test V-OPS-002 returns zero matches; CHANGELOG entry under “Removed”
T-C7	Verify gh secret list returns no Postmark-token-named secrets	(CI / operator)	T-B2	Verification V-CI-103 passes

T-C1 and T-C2 are independent; T-C3 depends on both. T-C4 depends on T-C3. T-C5 depends on T-C4 + T-B2 (drift workflow needs the live external resources). T-C6 depends on the documentation runbook landing (T-A3) so operators have a replacement. T-C7 is a one-shot operator/CI check.

Execution Phase D: Wrap-up and PR closure

#	Task	Repository	Depends On	Acceptance Criteria
T-D1	Open documentation PR (Phase A + B sign-off)	documentation	T-A4, T-B2	PR opens; CI green; reviewer approves
T-D2	Open infrastructure PR (Phase C)	infrastructure	T-C7	PR opens; CI green; reviewer approves
T-D3	Merge both PRs	—	T-D1 (merged), T-D2 (merged)	Both PRs merged; T-C5 re-runs successfully on main to confirm post-merge state

STOP — documentation review after T-D1 reaches reviewable state. Confirm reviewer feedback before merging.

4. Dependency graph

5. Personas

Phase 1 is operator-driven and has a small code surface; a single engineer with operator privileges can execute the whole phase. If multiple agents are spawned, the natural split is along repository boundaries:

Persona	Working directory	Agent name pattern
Documentation engineer	/Users/jmp/code/arda/projects/email-integration-worktrees/documentation	docs-phase-1-<task> (e.g., docs-phase-1-runbook)
Infrastructure engineer	/Users/jmp/code/arda/projects/email-integration-worktrees/infrastructure	infra-phase-1-<task>
Operator (manual steps)	(browser + 1Password client + Postmark Console)	coord-phase-1-operator

For a single-agent run, the same engineer plays all three personas in sequence.

6. Worktree strategy

Single worktree per repository; no multi-agent parallelism within a repository.

Repository	Worktree path	Branch
infrastructure	/Users/jmp/code/arda/projects/email-integration-worktrees/infrastructure (existing)	jmpicnic/email-integration-phase-1-infra
documentation	/Users/jmp/code/arda/projects/email-integration-worktrees/documentation (existing)	jmpicnic/email-integration-phase-1-docs

If existing worktrees are committed to other branches, create new worktrees:

git -C /Users/jmp/code/arda/infrastructure worktree add \
  /Users/jmp/code/arda/projects/email-integration-worktrees/infrastructure-p1 \
  -b jmpicnic/email-integration-phase-1-infra

git -C /Users/jmp/code/arda/documentation worktree add \
  /Users/jmp/code/arda/projects/email-integration-worktrees/documentation-p1 \
  -b jmpicnic/email-integration-phase-1-docs

No integration branch needed — the two repos’ work is independent.

7. Acceptance gates

A gate is a checkpoint where the team confirms readiness to proceed. Phase 1’s gates:

Gate	Trigger	Confirms
Gate 1: Documentation drafted	T-A1, T-A2, T-A3 reach reviewable draft state	The runbook is usable for T-B1; reviewers can begin reading
Gate 2: External resources ready (post T-B2)	T-B1 / T-B2 sign-off captured	All external resources match Phase 1 target; code Phase C can proceed without further operator dependencies (except T-C5)
Gate 3: Drift workflow live (post T-C5)	First workflow_dispatch run green	The live drift contract is asserted; goal AC#7 contributing-state passes
Gate 4: Phase 1 complete (post T-D3)	Both PRs merged; post-merge drift run succeeds	Phase 1 acceptance criteria all passed; downstream phases unblocked

8. Pre-execution checklist

Run through this list before T-A1 begins:

• Worktrees exist on the target branches in both infrastructure and documentation.
• Operator has Postmark Console access for both PostmarkProd and PostmarkNonProd (or can request creation).
• Operator has 1Password access to the Arda-SystemsOAM vault.
• Operator has GitHub admin access to Arda-cards/infrastructure (for secret provisioning + workflow dispatch).
• tools/gha-secret.ts (or its current location at infrastructure/scripts/gha-secrets/) is functional.
• The team has reviewed and accepts ../specification.md § 5 Open Questions and Decisions; decisions are tracked in ../../decision-log.md with DQ-R1-NNN numbering.

9. Post-execution checklist

After T-D3 merges:

• verification.md traceability table updated: every test row’s status is passed.
• ../../decision-log.md updated with any DQ-R1-NNN entries opened during execution (per ../specification.md § 5).
• Worktree cleanup if temporary worktrees were created in § 6.
• Phase 3 and Phase 4 implementors notified that the platform/ typed constants are available to import.

10. Risk register

#	Risk	Likelihood	Impact	Mitigation
R-1	PostmarkNonProd account creation blocked by Postmark approval	Low	High (Phase 1 cannot complete without it)	Engage Postmark support proactively if creation does not complete within one business day
R-2	Drift workflow false-positive on first run (e.g., Postmark API rate limit)	Medium	Low (false issue auto-created; fix is to re-run)	Make the drift script tolerate one transient failure on retry
R-3	Documentation review surfaces structural changes after T-A3 lands	Medium	Medium (T-A3 may need re-work)	Open the documentation PR as a draft for early review; treat T-A1/T-A2/T-A3 as a single-PR atomic landing rather than three sequential PRs
R-4	Existing infrastructure/scripts/gha-secrets/ implementation is broken or non-functional	Low	Medium (Task 1 step 5 cannot complete)	Run a smoke test of the utility before T-B1; if broken, file a separate fix issue (out of scope of this project; the spec does not depend on the utility’s state beyond “it works once”)
R-5	First-run of drift workflow exposes a missing op:// reference	Low	Medium (re-do T-C1 / T-C2)	T-C3’s unit tests catch most cases; the live first run is a final defence
R-6	Open Question OQ-2 (drift-check location) resolves after T-C3 starts	Medium	Low	Track in decision log; document final location in the file’s docstring; the location is a path move, not a rewrite

11. Out of scope of this plan

• Decisions about retiring tools/gha-secret.ts — ../specification.md § 4 lists this as out of scope of the project.
• Path migration of any existing infrastructure/scripts/gha-secrets/ implementation to infrastructure/tools/gha-secret.ts — if it happens during this project, it is a side effort tracked separately.
• All work in operations and common-module repositories — those belong to Phase 5b.

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 that the plan operates against.
• ../exports.md — cross-phase contracts produced by this plan’s execution.
• ../../phases.md — Phase 1’s place in the overall project sequence.
• ../../decision-log.md — where decisions during execution are recorded.