feat(sheets): add gradient conditional formatting

[clawsweeper]

Summary

• add --gradient-rule-json to gog sheets conditional-format add for Sheets API ConditionalFormatRule.gradientRule
• preserve the existing boolean-rule --type / --expr / --format-json path and reject mixed boolean/gradient inputs
• update Sheets formatting docs plus generated command reference and add focused unit/dry-run/list coverage

Release note

gog sheets conditional-format add can now create gradient conditional formatting rules from Sheets API JSON.

Fixes #900

Validation

• go test ./internal/sheetsconditional ./internal/cmd
• make docs-commands
• make ci

[clawsweeper]

Codex review: passed. Reviewed July 4, 2026, 11:02 PM ET / 03:02 UTC.

Summary
The PR adds --gradient-rule-json to gog sheets conditional-format add, builds Sheets GradientRule requests, rejects mixed boolean/gradient inputs, and updates docs plus focused tests.

Reproducibility: not applicable. as a bug reproduction; this is a feature PR. Source inspection confirms current main lacks a gradient-rule creation path, and the patch adds one with request-building and dry-run coverage.

Review metrics: 2 noteworthy metrics.

• Changed surface: 7 files, +252/-30. The patch touches the command implementation, planner helper, docs, generated command docs, and tests.
• User-facing flags: 1 added. --gradient-rule-json is new CLI surface and should match the maintainer-preferred raw JSON flag pattern.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #900
Summary: This PR is the active candidate fix for the linked gradient conditional-format feature request.

Members:

• canonical: gog sheets should support conditional formatting with gradients (gradientRule) #900 - The PR body uses closing syntax for this open issue, and the issue comments record this PR as the generated implementation result.

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

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Add a redacted live Sheets smoke transcript, screenshot, or recording if maintainers want runtime API proof before merge.

Mantis proof suggestion
A visible Sheets proof would materially show that the new CLI path creates an actual color-scale conditional format. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: create a Sheets gradient conditional format with gog and show command output plus the resulting color scale.

Risk before merge

• [P1] The PR body lists unit/docs/CI validation but no live Google Sheets spreadsheets.batchUpdate proof, so maintainers may want a redacted live smoke run before merging the new API path.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused gradient-rule flag after CI and, ideally, live redacted Sheets proof confirm the generated request is accepted and visibly applies a color scale.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No repair lane is needed right now because the PR has no actionable code finding; remaining action is normal maintainer review, CI completion, and optional live Sheets proof.

Security
Cleared: The diff only changes Go command/request construction, docs, and tests; it does not add dependencies, workflow permissions, credential handling, or supply-chain inputs.

Review details

Best possible solution:

Land the focused gradient-rule flag after CI and, ideally, live redacted Sheets proof confirm the generated request is accepted and visibly applies a color scale.

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

Not applicable as a bug reproduction; this is a feature PR. Source inspection confirms current main lacks a gradient-rule creation path, and the patch adds one with request-building and dry-run coverage.

Is this the best way to solve the issue?

Yes: extending the existing sheets conditional-format add command with an alternative raw GradientRule JSON flag is the narrowest maintainable path and follows existing --*-json patterns.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P3: This is a low-risk feature extension for an existing Sheets command family, with limited blast radius and no evidence of a blocked core workflow.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external contributor proof gate does not apply because this is a ClawSweeper bot autofix PR; no live Sheets proof was posted.

Label justifications:

• P3: This is a low-risk feature extension for an existing Sheets command family, with limited blast radius and no evidence of a blocked core workflow.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external contributor proof gate does not apply because this is a ClawSweeper bot autofix PR; no live Sheets proof was posted.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md has 49 lines and was read fully; its PR review/read-only guidance and stdout/stderr/testing guidance were applied. (AGENTS.md:1, c0aac99f6be6)
• Current main boolean-only CLI surface: Current main requires --type and --format-json on SheetsConditionalAddCmd and parses only the boolean-rule path. (internal/cmd/sheets_conditional.go:23, c0aac99f6be6)
• Current main boolean-only request builder: The current planner constructs sheets.ConditionalFormatRule{BooleanRule: ...} and never sets GradientRule. (internal/sheetsconditional/conditional.go:54, c0aac99f6be6)
• PR diff implements the requested path: The patch adds GradientRuleJSON, gradient JSON parsing, BuildGradientAddRequest, gradient list typing, docs, and unit/dry-run coverage. (internal/cmd/sheets_conditional.go, b59f75a25e04)
• Linked canonical issue: The PR body closes the open feature request at gog sheets should support conditional formatting with gradients (gradientRule) #900, and that issue records this PR as the generated implementation result.
• No competing canonical item found: Search for the central terms found only the linked issue and this PR, so this remains the active implementation candidate.

Likely related people:

• Peter Steinberger: Blame and file history show the current Sheets conditional-format command, planner, and docs were introduced in the v0.32.0 release work by this author. (role: recent area contributor; confidence: high; commits: f20a26cd9e26, c0aac99f6be6; files: internal/cmd/sheets_conditional.go, internal/sheetsconditional/conditional.go, docs/sheets-formatting.md)
• codBang: The earlier closed Sheets advanced-formatting proposal covered the same conditional-format/banding command family, and the changelog credits that proposal for the shipped feature area. (role: adjacent feature proposer; confidence: medium; commits: c3699717a3ff; files: internal/cmd/sheets.go, internal/cmd/sheets_advanced.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.