pal-e-docs

Review: Automate Gmail OAuth re-auth lifecycle v3

review-359-2026-03-27-v3 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered. Prereq gmail-mcp#6 done.
  • [x] Repo -- forgejo_admin/pal-e-platform
  • [x] User Story -- "As a platform operator I want a single script..."
  • [x] Context -- Detailed background on 7-day expiry, 3 consumers, prereq satisfied.
  • [x] File Targets -- 2 create/modify, 3 do-not-touch. But see gap below.
  • [x] Acceptance Criteria -- 5 criteria.
  • [x] Test Expectations -- 3 items (manual, dry-run, error handling).
  • [x] Constraints -- 4 items (typo bridge, mount pattern, script style, repo scope).
  • [x] Checklist -- 5 items.
  • [x] Related -- 5 references including prior review notes.
All required template sections are present. Massive improvement from the BLOCK state (literal $NEW_BODY). All 3 resolved decisions are clearly documented in the body.

Traceability

  • [ ] story:X label -- MISSING. Board item #359 has arch:google-oauth,type:feature,scope:discovered but no story label. Prior reviews recommended story:platform-reliability. Still not added.
  • [x] arch:google-oauth label -- present on board item #359.
  • [x] Forgejo issue -- forgejo_admin/pal-e-platform#162, confirmed open.

File Targets

  • [x] scripts/gmail-reauth.sh (new) -- scripts/ directory verified (3 existing scripts). Convention reference update-kustomize-tag.sh exists and uses set -eu (not set -euo pipefail as stated in Constraints -- minor mismatch but acceptable).
  • [x] salt/pillar/secrets_registry.sls -- verified exists (287 lines). No existing Gmail OAuth entry. Adding under platform: section is consistent with existing structure.
  • [ ] PrometheusRule file target MISSING -- The "Resolved" section says "Add a PrometheusRule resource that fires when the gmail-oauth-token secret is older than 6 days. Ships with this ticket as an additional file target." However, the File Targets section does NOT list terraform/modules/monitoring/main.tf or any PrometheusRule resource. Existing PrometheusRules are defined as kubernetes_manifest resources in terraform/modules/monitoring/main.tf. This file target must be added.
  • [x] Do-not-touch files verified: ~/gmail-sdk/src/gmail_sdk/auth.py exists, ~/gmail-mcp/ exists, ~/pal-e-deployments/ exists.

Repo Placement

OK. pal-e-platform is the correct repo for the re-auth script and secrets_registry entry. The Resolved section correctly scopes out pal-e-mail PVC-to-secret migration to a separate pal-e-deployments ticket. The PrometheusRule also belongs in pal-e-platform (monitoring module lives here).

Dependencies

  • Board item #361 (gmail-mcp SSH reauth, forgejo_admin/gmail-mcp#6) -- in done column. Prerequisite satisfied.
  • No blockers -- nothing in in_progress or next_up conflicts with this work.
  • Downstream: pal-e-mail PVC migration -- explicitly scoped out to a separate pal-e-deployments ticket. Not a blocker for this ticket. Should be created as discovered scope after this lands.
  • Stale secret cleanup -- gmail-oauth-westsidebasketball (created 2026-03-19) exists alongside gmail-oauth-token. Issue correctly identifies this as stale and scopes cleanup into this ticket. Verified: basketball-api deployment mounts volume gmail-oauth from secret gmail-oauth-token (not the stale one).

Acceptance Criteria

5 ACs, all verifiable by an agent:
  • AC1: End-to-end script execution -- verifiable via dry-run + live test.
  • AC2: secrets_registry.sls entry -- verifiable via grep.
  • AC3: kubectl get secret verification -- verifiable command provided.
  • AC4: Scope validation (4 scopes) -- verifiable programmatically against token content.
  • AC5: Typo bridge -- verifiable by checking file read path vs secret write key.
Missing AC: No acceptance criterion for the PrometheusRule (day-6 alerting). The "Resolved" section commits to shipping it, but no AC validates it fires correctly. Need: "PrometheusRule gmail-oauth-expiry exists in monitoring namespace and targets basketball-api namespace secret age."
Missing AC: No acceptance criterion for stale secret deletion. The "Resolved" section says "Delete the stale secret as part of this ticket" but no AC captures: "kubectl get secret gmail-oauth-westsidebasketball -n basketball-api returns NotFound."

Blast Radius

  • Token filename typo bridge -- properly documented in AC #5 and Constraints. Local file gmail-westsidebasktball.json (verified present at ~/secrets/google-oauth/) maps to k8s secret key gmail-westsidebasketball.json (verified in gmail-oauth-token secret data keys). No blast radius concern.
  • pal-e-mail PVC -- correctly scoped out. After this ticket, pal-e-mail still reads from PVC (manual sync needed until migration ticket lands). Acceptable.
  • gmail-mcp -- reads directly from local filesystem. Re-auth script writes to the same local file, so gmail-mcp picks up the refresh automatically. No blast radius.
  • PrometheusRule -- adding a new rule to the monitoring module requires tofu apply. This is standard for this repo but the agent must include it in the PR.

Decomposition

3 file targets (script, secrets_registry, PrometheusRule), 1 repo, 5 ACs (+2 missing = 7 total). Estimated agent work: ~5 minutes. Borderline but feasible in a single pass since all targets are in the same repo and the PrometheusRule follows established patterns. No decomposition needed if the missing file target and ACs are added to the spec.

Recommendation

Three issues prevent READY status:
  • [LABEL] Add story:platform-reliability label to board item #359. (Carried forward from v1 and v2 reviews -- still not done.)
  • [BODY] Add terraform/modules/monitoring/main.tf to File Targets -- "add a kubernetes_manifest PrometheusRule resource for day-6 gmail-oauth-token secret age alerting, following the pattern of blackbox_alerts and embedding_alerts resources."
  • [BODY] Add 2 missing ACs: (a) PrometheusRule gmail-oauth-expiry exists and targets secret age >6d; (b) stale secret gmail-oauth-westsidebasketball deleted from basketball-api namespace.
All three are mechanical fixes -- no human decisions needed. Once applied, this ticket is READY.

Prior Review Lineage

  • review-359-2026-03-27 -- v1, NEEDS_REFINEMENT (4 issues)
  • review-359-2026-03-27-v2 -- v2, BLOCK ($NEW_BODY, 6 issues)
  • review-359-2026-03-27-v3 -- this review. Body rewritten, 3 of 6 prior issues resolved, 3 new/carried issues found.