Review: Sprint 2: SDK implementation -- postmark-account-sdk

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type -- Feature
• [x] Lineage
• [x] Repo
• [x] User Story
• [x] Context
• [x] File Targets
• [x] Feature Flag -- none (appropriate for SDK/infra work)
• [x] Acceptance Criteria -- 6 items
• [x] Test Expectations
• [x] Constraints
• [x] Checklist
• [x] Related

Traceability

• [x] story:sdk label -- Postmark SDK Foundation
• [x] story note verified -- story-postmark-sdk exists in pal-e-docs
• [ ] story note on project page MISSING -- [SCOPE] No project-postmark project page exists. The story note story-postmark-sdk references postmark-project-page in its Related section, suggesting this page should be created.
• [x] arch:api label present
• [ ] arch note WRONG PROJECT -- [LABEL] arch-api note exists but belongs to prediction-assistant (Kalshi), not postmark. The postmark project uses arch-domain-postmark, arch-dataflow-postmark, arch-deployment-postmark. Label should be arch:domain-postmark to reference the correct architecture note.
• [x] Forgejo issue -- ldraney/postmark-account-sdk#2, open

File Targets

• [x] pyproject.toml -- new file, project config
• [x] src/postmark_account_sdk/ -- new package directory
• [x] tests/conftest.py -- new file, shared fixtures
• [x] tests/test_servers.py -- covers Server Management API (5 endpoints)
• [x] tests/test_domains.py -- covers Domains API (9 endpoints)
• [x] tests/test_sender_signatures.py -- covers Sender Signatures API (8 endpoints)
• [ ] tests/test_templates.py -- MISSING: [BODY] Templates API group (PUT /templates/push) has no test file listed. The swagger spec defines 4 API tag groups but only 3 test files are listed. AC #5 requires "Tests are organized by API group matching the swagger spec sections."

Repo Placement

Dependencies

• Blocked by #1 (docs PR) -- RESOLVED (issue #1 closed, PR #4 merged). Blocker cleared.
• Sibling: ldraney/postmark-server-sdk#2 (board item #1914, 8 points) -- parallel server SDK issue, same sprint 2, same pattern. No ordering dependency between the two SDKs.
• Downstream: Sprint 3 items depend on SDKs being complete:
• Dependencies are documented in the Lineage and Related sections.

Acceptance Criteria

• AC1: "Every endpoint in postmark-account-api.yaml has at least one test" -- verifiable by cross-referencing swagger paths vs test coverage. Swagger has 22 endpoints across 4 groups.
• AC2: "All tests pass against the real Postmark API" -- verifiable via pytest tests/ -v
• AC3: "SDK client handles auth via POSTMARK_ACCOUNT_TOKEN env var" -- verifiable
• AC4: "Error responses are handled gracefully" -- slightly vague but acceptable (agent can interpret as proper exception handling)
• AC5: "Tests are organized by API group matching the swagger spec sections" -- verifiable, but contradicted by missing templates test file in File Targets
• AC6: "Destructive tests are safe" -- verifiable and important for account-level operations. Good addition vs the sibling server-sdk issue.

Blast Radius

Decomposition Assessment

• File targets: 6 files (should be 7 with templates) in 1 repo -- under the >3 files across >2 repos threshold
• Acceptance criteria: 6 items -- at the >5 threshold boundary
• Estimated agent work: Single repo, clear swagger spec as source of truth, clear pattern to follow (forgejo-sdk). 4 API groups, 22 total endpoints. Manageable in a single agent pass despite being a 5-point story.

Recommendations

• [BODY] Add tests/test_templates.py to File Targets -- Templates API (PUT /templates/push) is the 4th API group in the swagger spec. AC #5 requires tests organized by API group.
• [LABEL] Change arch:api label to arch:domain-postmark -- the arch-api note belongs to prediction-assistant, not postmark. The correct postmark arch note is arch-domain-postmark which documents the PostmarkAccountSDK entity model.
• [SCOPE] Create project-postmark project page with user-stories section -- the story note story-postmark-sdk exists but no project page hosts it. The story note itself references postmark-project-page as a parent.