Phase 1 -- Implementation Suggestions

Forward-looking improvements identified during Phase 1 implementation. Each suggestion lists what it improves, why it’s not in Phase 1’s scope, and what triggers acting on it.

S-1: Drift-check should distinguish “missing item” from “missing-by-design”

Today: tools/drift-check.ts iterates over ALL_OP_ITEMS and treats every “no item matched the secret reference query” as a failure. The decision (DQ-R1-007) to remove FREE_KANBAN_POSTMARK_ITEM from the Phase 1 typed surface was the right call, but the underlying mechanism is binary: an item either resolves or it doesn’t.

Suggestion: when Phase 3 reintroduces the typed reference for the Free Kanban Tool’s Postmark server token, the constant could declare a phase or readiness annotation — e.g., { phase: 3, requiredFromPhase: 3, ... }. The drift-check would then probe items at or before the operator’s “current phase” and report items beyond it as informational rather than failures.

Trigger: Phase 3 planning. Worth ~30 minutes of design work to avoid future “missing-by-design” false positives once the typed surface grows.

S-2: Drift-check could opportunistically check sender-signature / domain-verification status

Today: drift-check probes one endpoint (GET /servers?count=1&offset=0) and only confirms that a token authenticates. It does not check whether the account has any verified sending domains.

Suggestion: extend the probe to call GET /senders or the equivalent GET /senders/domains once it exists per Postmark’s API. Surface “account has zero verified sending domains” as a warning (not failure) — because Phase 1 doesn’t require any verified domains, but operators benefit from knowing the account’s onboarding state ahead of Phase 3.

Trigger: when Phase 3 starts implementation work. The signal is most useful immediately before Phase 3’s arda.ardamails.com verification; making it visible in the Phase 1 drift workflow lowers the surprise factor.

S-3: Adopt tools/set-gha-repo-secret.sh style for future operator helpers

Today: two operator helpers exist with the same op read | gh secret set pattern: tools/set-gha-org-secret.sh (bulk org-secrets sync; pre-existing) and tools/set-gha-repo-secret.sh (Phase 1 deliverable; single-shot, parameterised). Both are shell.

Suggestion: when a third or fourth such helper appears (e.g., for env-scoped secrets, or for syncing 1Password items that are not GHA secrets), extract the preflight + op read | gh secret set core into a shared sourceable helper (tools/lib-gh-secret.sh) so additions don’t keep duplicating ~15 lines of preflight.

Trigger: when a third tool with the same pattern is needed. Two is fine; three is the cue.

S-4: 2FA enable URLs in the runbook — write a discovery script

Today: the runbook hard-codes URLs for the Postmark Console. The 2FA enable URL is per-user and browser-session-dependent (top-right avatar menu); when an operator can’t find it, the runbook’s troubleshooting table guides them through alternatives.

Suggestion: write a small companion script that, given Postmark account-token credentials, calls the Postmark API to surface the user-management URL set for that account (Postmark exposes GET /users listings). Output something like “for user miguel@arda.cards on account PostmarkNonProd, your profile URL is X”. Eliminates the “is this still the right URL?” risk during walkthroughs.

Trigger: if a future operator hits the same dead-end on PostmarkNonProd or any other account. The cost (one small script) is low; the benefit (no walkthrough-time blocker) is meaningful.

S-5: Bake an “operator-walkthrough” smoke test into CI

Today: the runbook is human-driven. Drift-check provides a CI-runnable post-walkthrough validation, but the interactive steps (Postmark Console clicks, 1Password item inspection) are unreplicable in CI.

Suggestion: split the walkthrough into operator-only steps (Postmark UI, 1Password UI) and verifiable steps (op read, gh secret list, drift-check). Add a CI workflow that runs the verifiable subset on every PR touching tools/drift-check.ts or the runbook — catches drift between the runbook’s commands and what those commands actually return.

Trigger: low-priority. The current tools/drift-check.ts already covers the most important assertions. Worth doing if a future runbook edit introduces a verification command that breaks silently.

S-6: Recordings of op:// resolution in CI for audit

Today: drift-check authenticates via OP_SERVICE_ACCOUNT_TOKEN in CI, resolves references, calls Postmark, and reports a JSON result. The CI run logs are kept by GitHub Actions for the standard retention window.

Suggestion: extend the drift workflow to publish a structured audit log somewhere persistent (an S3 bucket, a CloudWatch log group). One-line per run with {timestamp, references_checked, references_resolved, postmark_calls_made, http_codes}. Useful for forensic review if a future drift incident requires “when did we last see this token resolve?”.

Trigger: when an audit demand surfaces. The cost (one bucket + one PutObject step in the workflow) is small; the design risk is bloat. Skip until needed.

S-7: Make tools/drift-check.ts aware of timestamps from Postmark

Today: a 200 response from Postmark confirms authentication. It doesn’t capture metadata about token age or rotation history.

Suggestion: when Postmark exposes “last-rotated” or “created-at” timestamps for account tokens (it currently exposes them for server tokens via GET /servers/<id>; account tokens may follow), surface them in the drift report so operators can see token age trends.

Trigger: a Postmark API addition. Worth bookmarking via the API observations note’s “version-pin” section.

S-8: Codify the per-phase worktree convention as a pre-commit check

Today: the project-level CLAUDE.md documents the per-phase worktree pattern (phase-N/<repo>/). The convention is human-followed.

Suggestion: add a pre-commit hook (or a CI lint) that fails if a worktree is committed at the old flat path while another phase’s worktree exists at the new path. Catches the “left a stray phase-1-docs branch in the flat documentation/ worktree” failure mode.

Trigger: when a third phase opens. Two phases (Phase 1, Phase 2) is small enough to remember by hand; three or more makes a check worth the maintenance cost.