Phase 1 -- Implementation Changelog

A flat, chronological record of what landed during Phase 1 implementation. Cross-references the canonical CHANGELOG entries in the participating repositories.

Repositories and PRs

Repository	PR	Branch	Base	Role
Arda-cards/documentation	#69	jmpicnic/email-integration-phase-1-docs	jmpicnic/email-integration-rev1-design (PR #67)	Operator runbook, Postmark service docs, decision-log entries
Arda-cards/infrastructure	#446	jmpicnic/email-integration-phase-1-infra	main	platform/ typed surface, drift-check, drift workflow, GHA-secret tool

Documentation deliverables (PR #69)

CHANGELOG entry: [0.29.0] - 2026-05-05 — Added + Fixed.

• current-system/oam/postmark-service/index.md — Postmark service overview (account topology, credential storage, OAM model, drift cadence).
• current-system/oam/postmark-service/postmark-api-observations.md — API observations note (authentication models, error model, retry conventions, version-pin assumptions). The note is the source of truth for design-intent assumptions about the Postmark API surface.
• current-system/oam/postmark-service/operator-runbook.md — canonical operator runbook for Postmark account, 1Password item, and GitHub Actions secret provisioning. Replaces the parser-gated operator runbook (HUMAN-STEPS.md, deleted in Phase 1) used by the prior Phase-0 implementation. All <operator: confirm ...> placeholders resolved with the URLs Miguel supplied during the walkthrough.
• current-system/oam/index.md — discovery cross-link added to the new Postmark service section.
• Decision-log entries DQ-R1-001 through DQ-R1-005 (Round R1-Phase1) and DQ-R1-007 (also Round R1-Phase1; recorded vault separation for the Free Kanban Tool server token). The 1-external-resources/specification.md § 5 Open Questions table updated to point at the new entries.
• “Looking Ahead: Domain Verification (Phase 3 / Phase 4)” section added to the operator runbook — explains that the just-provisioned Postmark accounts are usable for API operations but require per-domain DKIM + Return-Path verification before live mail delivery, links to https://account.postmarkapp.com/signature_domains and the Postmark help article, and forward-references the Phase 3 stub at 3-corporate-updates/operator-domain-verification-checklist.md (introduced in PR #70).
• Operator runbook troubleshooting table extended with the case where the 2FA toggle is not visible at https://account.postmarkapp.com/account.
• Sign-off table populated with the 2026-05-05 walkthrough state. REQ-EXT-003 partial in the Deviations column; all other rows complete.
• “Post-Merge: First Drift-Workflow Run (T-C5) and GHA Secret Audit (T-C7)” section added.

Infrastructure deliverables (PR #446)

CHANGELOG entry: [2.28.0] - 2026-05-05 — Added + Fixed.

• src/main/cdk/platform/postmark-service.ts — enriched with POSTMARK_ACCOUNT_API_BASE_URL, POSTMARK_PLAN, POSTMARK_API_SURFACE. The two account constants (POSTMARK_PROD_ACCOUNT, POSTMARK_NONPROD_ACCOUNT) now derive their credentialReference from the canonical 1Password items in platform/one-password.ts.
• src/main/cdk/platform/one-password.ts — OnePasswordItem interface and three typed constants (POSTMARK_PROD_ITEM, POSTMARK_NONPROD_ITEM, IAC_SCRIPTS_SERVICE_ACCOUNT_ITEM). The Free Kanban Tool’s typed reference is not in Phase 1; it is reintroduced by Phase 3 with the new Arda-CorporateOAM vault per DQ-R1-007.
• src/main/cdk/platform/platform.test.ts — unit tests covering V-PLAT-001 (postmark-service surface), V-PLAT-002 (1Password item references), V-PLAT-003 (no inline op://Arda-SystemsOAM/ literals outside the canonical platform/ files).
• tools/drift-check.ts — dual-purpose drift-check module. Resolves every op:// reference declared in platform/one-password.ts, then probes each Postmark account credential against the Postmark Account API (GET /servers?count=1&offset=0 — the URL was corrected during walkthrough; see learnings.md). Exit 0 on green; exit 1 with a structured JSON diagnostic on any failure.
• tools/drift-check.test.ts — 14 Jest tests covering V-CI-001..003 + report-structure invariants.
• .github/workflows/external-resources-drift.yml — monthly-scheduled (0 9 1 * *) + workflow_dispatch workflow. Authenticates to 1Password via OP_SERVICE_ACCOUNT_TOKEN, runs tools/drift-check.ts, opens a labelled (drift,phase-1,external-resources) GitHub issue on failure. Filename per DQ-R1-001.
• tsconfig.tools.json — TypeScript project for tools/ type-checking.
• @1password/sdk@0.4.0 — production dependency added.
• tools/set-gha-repo-secret.sh — single-shot, parameterised CLI for provisioning a GitHub Actions repository secret from a 1Password reference. Wraps op read and gh secret set. Closes the open scope point in spec § 4 (“tools/gha-secret.ts utility itself is assumed in place”). See alternatives.md for the TypeScript-vs-shell choice.
• tools/set-gha-org-secret.sh — renamed from tools/sync-secrets-from-1password.sh for symmetry with the new sibling. No callers in CI / Makefile / scripts; historical references in completed-roadmap docs left intact.

Operational state at end of Phase 1 implementation

• All four Phase 1 typed op:// references resolve via the 1Password SDK (DesktopAuth locally + OP_SERVICE_ACCOUNT_TOKEN env in CI). Drift-check probe returns HTTP 200 against both Postmark accounts.
• OP_SERVICE_ACCOUNT_TOKEN provisioned on Arda-cards/infrastructure via tools/set-gha-repo-secret.sh. The token was rotated mid-walkthrough (operator action; see learnings.md).
• T-C5 (first workflow_dispatch run) deferred until PR #446 merges. T-C7 (GHA-secret audit) complete; one leftover from the prior Phase-0 implementation (POSTMARK_NONPROD_ACCOUNT_TOKEN) was deleted to restore V-CI-103 compliance.

Decisions recorded during Phase 1 implementation

#	Title	Round
DQ-R1-001	Drift workflow filename	R1-Phase1
DQ-R1-002	Drift-check TypeScript module location	R1-Phase1
DQ-R1-003	Operator runbook sign-off mechanism	R1-Phase1
DQ-R1-004	Disposition of legacy HUMAN-STEPS.md parser	R1-Phase1
DQ-R1-005	API-surface freshness cadence	R1-Phase1
DQ-R1-007	Vault separation for Free Kanban Tool server token	R1-Phase1

The full text of each decision is in ../../decision-log.md.