Phase 1 -- Specification Post-Implementation

Reflects the specification as actually implemented. The original ../specification.md remains as the contract that drove implementation; this document records deltas between the contract and reality. Where the implementation matches the spec, the spec stands; only differences are listed here.

Deltas vs the original specification

D-1: `FREE_KANBAN_POSTMARK_ITEM` typed reference removed

Original spec (Task 3, REQ-PLAT-002): declared four typed constants in platform/one-password.ts — POSTMARK_PROD_ITEM, POSTMARK_NONPROD_ITEM, IAC_SCRIPTS_SERVICE_ACCOUNT_ITEM, FREE_KANBAN_POSTMARK_ITEM.

Implemented: three typed constants. FREE_KANBAN_POSTMARK_ITEM is removed from Phase 1 because the underlying 1Password item is created by Phase 3 (Corporate CLI Phase A), not Phase 1. The vault for the Free Kanban item is also different (Arda-CorporateOAM per DQ-R1-007, not Arda-SystemsOAM).

Reason: see DQ-R1-007 and alternatives.md A-3, A-4. A typed reference exists when the resource exists; forward-declaring creates verification noise.

D-2: `tools/gha-secret.ts` not implemented; `tools/set-gha-repo-secret.sh` ships instead

Original spec (Task 1, REQ-EXT-005): “If missing or stale, provision it using the existing tools/gha-secret.ts utility.”

Implemented: tools/set-gha-repo-secret.sh (parameterised single-shot shell script) instead. Sibling rename tools/sync-secrets-from-1password.sh → tools/set-gha-org-secret.sh for naming symmetry.

Reason: see alternatives.md A-1. The shell substitute closes the same operator workflow with ~130 lines vs ~1370 for the TypeScript port shape used by the prior Phase-0 implementation; spec § 4 explicitly carves the tools/gha-secret.ts migration as out of scope.

D-3: Drift-check URL corrected to include `offset=0`

Original spec (Task 4, REQ-CI-002): the drift-check probes the Postmark Account API; the example URL referenced GET /servers?count=1.

Implemented: GET /servers?count=1&offset=0. Postmark’s API rejects the call when either count or offset is missing (HTTP 422 with ErrorCode 600). The URL is asserted in tools/drift-check.test.ts.

Reason: see learnings.md L-1. The original URL was a bug discovered by running drift-check live during the walkthrough; fix landed in PR #446 commit 691ba1d and the API observations note (postmark-api-observations.md) was updated in tandem to document the requirement.

D-4: REQ-EXT-003 (PostmarkNonProd 2FA) recorded as Partial

Original spec (Task 2, Step 3.2): “Enable 2FA on the owner mailbox” for PostmarkNonProd.

Implemented: account is on Platform plan with valid token; 2FA toggle was not located in the Postmark Console UI on walkthrough date.

Reason: see learnings.md L-8 and skipped.md SK-1. The 2FA enable surface is per-user (not per-account-settings); the user-profile URL was not located for the PostmarkNonProd login. The runbook’s troubleshooting table records the dead-end. Re-run row 3 of the sign-off table when a future walkthrough has access to the user-profile menu.

D-5: T-C5 (first `workflow_dispatch` run) deferred to post-merge

Original spec (Task 4 STOP / V-CI-102): “Workflow first run completes successfully.”

Implemented: deferred until PR #446 merges to main. Pre-merge dispatches return HTTP 404 because GitHub Actions registers workflows when they appear on the default branch.

Reason: see learnings.md L-9 and skipped.md SK-2. GitHub Actions design constraint. The runbook’s new “Post-Merge: First Drift-Workflow Run (T-C5) and GHA Secret Audit (T-C7)” section captures the post-merge command sequence.

D-6: T-C7 surfaced and remediated a leftover GHA secret

Original spec: T-C7 verifies no Postmark-token-named GHA secrets exist (V-CI-103).

Implemented: audit found POSTMARK_NONPROD_ACCOUNT_TOKEN set 2026-04-30 from the prior Phase-0 era. Deleted; re-audit returned zero matches.

Reason: see learnings.md L-10. The leftover violated the rev1 design (no Postmark tokens as GHA secrets). The deletion is recorded in the runbook’s post-merge section as the canonical remediation pattern for any future rediscovery.

D-7: New “Looking Ahead: Domain Verification” runbook section

Original spec: didn’t anticipate the operator-readable surface for Phase 3 / Phase 4 domain verification.

Implemented: a new section in 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. Forward-references 3-corporate-updates/operator-domain-verification-checklist.md (Phase 3 stub introduced in PR #70).

Reason: see learnings.md L-7. Surfaced from the Postmark help article during walkthrough; warrants an operator heads-up in the Phase 1 runbook so future operators know what’s coming.

D-8: Free Kanban Tool vault changed from `Arda-SystemsOAM` to `Arda-CorporateOAM`

Original spec / cross-cutting-design.md: Free Kanban Tool’s Postmark server token in Arda-SystemsOAM.

Implemented: separate vault Arda-CorporateOAM; item titled Free-Kanban-Generator-Postmark-Server; canonical reference op://Arda-CorporateOAM/Free-Kanban-Generator-Postmark-Server/credential.

Reason: DQ-R1-007. Bounded blast-radius posture: a CI-side compromise of OP_SERVICE_ACCOUNT_TOKEN (scoped read-only to Arda-SystemsOAM) does not yield the Free Kanban Tool’s runtime sending credential. cross-cutting-design.md, phases.md, and architecture-overview.md updated in tandem.

Acceptance state at end of Phase 1 implementation

Per the operator runbook’s sign-off table (2026-05-05):

Sign-off row	State	Notes
1 — PostmarkProd account (REQ-EXT-001)	Complete	2FA enabled, account-level token generated, on Platform plan
2 — PostmarkProd token in 1Password (REQ-EXT-002)	Complete	Resolves; drift-check probe HTTP 200
3 — PostmarkNonProd account (REQ-EXT-003)	Partial (D-4)	Account + token complete; 2FA toggle deferred
4 — All 1Password items populated (REQ-EXT-004)	Complete	Three Phase-1 items in `Arda-SystemsOAM` (D-1)
5 — GHA secret provisioned (REQ-EXT-005 / REQ-CI-001)	Complete	Provisioned via `tools/set-gha-repo-secret.sh` (D-2)
Post-provisioning connectivity check	Complete	`tools/drift-check.ts` returns 5 passed / 0 failed
T-C5 — First `workflow_dispatch` run	Deferred (D-5)	Post-merge of PR #446
T-C7 — `gh secret list` audit	Complete	Leftover deleted (D-6)

What this enables for downstream phases

Capability	Phase 1 deliverable that enables it	Consumer
Address Postmark accounts by typed reference	`POSTMARK_PROD_ACCOUNT`, `POSTMARK_NONPROD_ACCOUNT` in `platform/postmark-service.ts`	Phase 3 (Corporate CLI), Phase 4 (per-partition deploy), drift workflow
Resolve `op://` references at deploy time and runtime	`OP_SERVICE_ACCOUNT_TOKEN` GHA secret + `@1password/sdk` dep + `tools/drift-check.ts` template	Phase 3 / Phase 4 deploys, all future drift workflows
Run `gh secret set` operator-style	`tools/set-gha-repo-secret.sh`	Phase 3 / Phase 4 if/when they need new repo-scoped secrets
Operator runbook pattern for new external resources	`current-system/oam/postmark-service/operator-runbook.md` (sign-off table; troubleshooting table; “Looking Ahead” section)	Phase 3’s `3-corporate-updates/operator-domain-verification-checklist.md` (mirrors structure)

References

changelog.md — what landed.
learnings.md — what we learned.
alternatives.md — options weighed.
suggestions.md — forward-looking improvements.
skipped.md — what was deliberately skipped.
../specification.md — the original contract.
../../decision-log.md — decisions DQ-R1-001..007.