feat(gmail): warn on rich draft downgrade

[steipete]

Summary

• land the contributor work from feat(gmail): warn when drafts update downgrades a rich-text draft to plain-only #955 as one maintainer-reviewed commit
• warn on stderr before a plain-only draft update removes an existing rich-text body
• keep JSON stdout clean and keep advisory MIME inspection failures non-fatal
• ignore HTML nested below an attachment boundary
• add the Unreleased changelog credit for @mcinteerj

Proof

• make ci
• focused draft-update regression suite, including advisory/required read failures and attached-message HTML
• contributor-provided exact-head live Gmail proof on feat(gmail): warn when drafts update downgrades a rich-text draft to plain-only #955: warning emitted for a real multipart draft downgrade, valid JSON remained on stdout, and supplying HTML preserved multipart/alternative

Autoreview: clean, no accepted/actionable findings.

Co-authored-by: Jake mcinteerj@gmail.com

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 5, 2026, 9:04 AM ET / 13:04 UTC.

ClawSweeper review

What this changes

The PR warns on stderr when a Gmail rich-text draft is replaced with plain text only, while preserving JSON stdout and making the additional MIME inspection non-fatal when it is advisory.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep open for normal collaborator PR review: current main lacks this warning, and the patch has no supported correctness or security blocker. The linked contributor proof and focused regression coverage support the maintainer landing path.

Priority: P2
Reviewed head: c68441a99f8f714ba980414e9e06c61dd8b81b1b

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	Strong live proof and focused coverage support a narrow, well-contained Gmail safety improvement.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR body points to redacted live Gmail before-and-after output for the contributor implementation, showing the warning, clean JSON stdout, and the HTML-preserving path.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body points to redacted live Gmail before-and-after output for the contributor implementation, showing the warning, clean JSON stdout, and the HTML-preserving path.
Evidence reviewed	4 items	Implementation path: The PR detects an existing text/html body outside named attachment subtrees, performs advisory inspection when the update supplies no HTML, and emits the warning through stderr. Regression coverage: Five focused cases cover attachment-contained HTML, warning and no-warning paths, the all-fields path, and advisory versus required draft-read failures. Live behavior proof: The PR body links to #955, whose redacted real-Gmail transcript shows the warning, clean JSON stdout, and preservation of multipart/alternative when HTML is supplied.
Findings	None	None.
Security	None	None.

How this fits together

Gmail draft updates can read an existing draft, rebuild its MIME message, and submit the replacement through the Gmail API. This change inspects the stored MIME structure before rebuilding so users learn when a plain-only update will remove rich text.

flowchart LR
  A[Draft update flags] --> B[Gmail draft update]
  B --> C[Read stored draft]
  C --> D[Inspect MIME body]
  D --> E[Warn on rich-text downgrade]
  E --> F[Rebuild message]
  F --> G[Update Gmail draft]

Loading

Before merge

• Complete next step (P2) - No mechanical repair is needed; this collaborator-authored landing PR only needs the repository’s normal review and required-check gates.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and tests	production +45/-3, tests +291	The small command-path change is backed by substantially larger targeted regression coverage.
Files affected	3 files: implementation, tests, release note	The patch remains focused on one Gmail draft-update behavior.

Root-cause cluster

Relationship: canonical
Canonical: #957
Summary: This collaborator landing PR is the canonical current review path for the rich-draft downgrade warning.

Members:

• superseded: feat(gmail): warn when drafts update downgrades a rich-text draft to plain-only #955 - This PR explicitly lands the contributor work, includes its proof provenance, and adds the requested contributor credit.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Land the focused stderr-only safeguard after normal required checks complete, retaining the advisory-read behavior so a warning lookup cannot block an otherwise valid update.

Do we have a high-confidence way to reproduce the issue?

Yes—current source rebuilds draft MIME from supplied bodies, and the provided real-Gmail transcript demonstrates that a rich draft updated with only plain text loses its HTML part without this warning.

Is this the best way to solve the issue?

Yes—the stderr-only warning is the narrowest maintainable safeguard because the requested plain-body replacement remains unchanged and machine-readable stdout stays intact.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d4a1a6e94707.

Labels

Label changes:

• add P2: This is a bounded user-facing Gmail draft safety improvement without evidence of urgent service disruption.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body points to redacted live Gmail before-and-after output for the contributor implementation, showing the warning, clean JSON stdout, and the HTML-preserving path.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body points to redacted live Gmail before-and-after output for the contributor implementation, showing the warning, clean JSON stdout, and the HTML-preserving path.

Label justifications:

• P2: This is a bounded user-facing Gmail draft safety improvement without evidence of urgent service disruption.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body points to redacted live Gmail before-and-after output for the contributor implementation, showing the warning, clean JSON stdout, and the HTML-preserving path.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body points to redacted live Gmail before-and-after output for the contributor implementation, showing the warning, clean JSON stdout, and the HTML-preserving path.

Evidence

What I checked:

• Implementation path: The PR detects an existing text/html body outside named attachment subtrees, performs advisory inspection when the update supplies no HTML, and emits the warning through stderr. (internal/cmd/gmail_drafts.go:888, c68441a99f8f)
• Regression coverage: Five focused cases cover attachment-contained HTML, warning and no-warning paths, the all-fields path, and advisory versus required draft-read failures. (internal/cmd/gmail_drafts_cmd_test.go:1063, c68441a99f8f)
• Live behavior proof: The PR body links to feat(gmail): warn when drafts update downgrades a rich-text draft to plain-only #955, whose redacted real-Gmail transcript shows the warning, clean JSON stdout, and preservation of multipart/alternative when HTML is supplied. (c68441a99f8f)
• Current-main and ownership provenance: Current main is the PR base d4a1a6e; recent draft-update semantics appear to date to the reply-lineage repair, which is the most relevant current-main ownership trail. (internal/cmd/gmail_drafts.go:882, 4985e2681e31)

Likely related people:

• chrischall: Introduced the current-main draft-update reply and stored-draft handling that this patch extends. (role: recent area contributor; confidence: high; commits: 4985e2681e31; files: internal/cmd/gmail_drafts.go)
• Peter Steinberger: Recently maintained the Gmail draft-update command and authored this collaborator landing commit. (role: recent area contributor; confidence: medium; commits: 6db9b084fd28, c68441a99f8f; files: internal/cmd/gmail_drafts.go)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.