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 6, 2026, 3:03 AM ET / 07:03 UTC.

Summary
The branch adds a --gradient-rule-json path to gog sheets conditional-format add, builds Sheets GradientRule batch update requests, recognizes gradient rules in list output, and updates docs plus tests.

Reproducibility: not applicable. as a bug reproduction; this is a feature PR. Source inspection of current main shows the add command only builds BooleanRule requests, while this head adds a gradient path with dry-run and unit coverage.

Review metrics: 2 noteworthy metrics.

• Changed surface: 7 files, +376/-30. The patch is focused on one Sheets command path but spans implementation, planner helper, docs, generated docs, and tests.
• User-facing CLI flags: 1 added. --gradient-rule-json is new public CLI surface and should remain compatible with the existing boolean-rule path.

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 feature request, and the issue comments link this PR as the 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 gog sheets conditional-format add --gradient-rule-json smoke transcript or screenshot if maintainers want runtime API proof before merge.

Risk before merge

• [P1] No redacted live Google Sheets spreadsheets.batchUpdate proof was present, so runtime API acceptance of the new gradient path was not independently verified in this read-only review.
• [P1] Tests were not rerun because this cleanup review must keep the checkout read-only; the PR body reports go test ./internal/sheetsconditional ./internal/cmd, make docs-commands, and make ci.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused flag after CI is clean, preserving boolean-rule compatibility and adding redacted live Sheets proof only if maintainers want integration confidence before merge.
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 because this PR has no actionable code finding; remaining work is normal maintainer review, CI gating, and optional live Sheets proof.

Security
Cleared: The diff changes Go request construction, docs, and tests only; it adds no dependencies, workflow permissions, credential handling, or supply-chain inputs.

Review details

Best possible solution:

Land the focused flag after CI is clean, preserving boolean-rule compatibility and adding redacted live Sheets proof only if maintainers want integration confidence before merge.

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

Not applicable as a bug reproduction; this is a feature PR. Source inspection of current main shows the add command only builds BooleanRule requests, while this head adds a gradient path with dry-run and unit coverage.

Is this the best way to solve the issue?

Yes: adding a raw Sheets API GradientRule JSON flag to the existing conditional-format command is a narrow maintainable path that preserves the boolean-rule interface.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is a low-risk feature extension for an existing Sheets command family, with limited blast radius and no blocked core workflow evidence.
• 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: Not applicable: this is a ClawSweeper bot autofix PR, so the external contributor proof gate does not apply; runtime Sheets proof remains optional maintainer validation.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully before review; its PR review guidance to use gh pr view / gh pr diff without switching branches was applied. (AGENTS.md:1, b609c221f4f6)
• Current main lacks gradient add inputs: On current main, SheetsConditionalAddCmd still requires boolean-rule --type and --format-json fields and has no GradientRuleJSON input. (internal/cmd/sheets_conditional.go:23, b609c221f4f6)
• Current main builds only BooleanRule requests: The current planner constructs sheets.ConditionalFormatRule{BooleanRule: ...} and never sets GradientRule, so the linked feature remains absent on main. (internal/sheetsconditional/conditional.go:54, b609c221f4f6)
• PR implements the gradient path: The PR head adds GradientRuleJSON, rejects mixed gradient/boolean inputs, decodes gradient JSON, builds a gradient request, and returns GRADIENT_RULE for JSON output. (internal/cmd/sheets_conditional.go:25, acaaafb001b4)
• Focused regression coverage: The PR head adds tests for building gradient requests, dry-run output, invalid JSON, mixed boolean flags, unknown color fields, alpha rejection, and zero color preservation. (internal/cmd/sheets_advanced_test.go:58, acaaafb001b4)
• 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 implementation PR.

Likely related people:

• steipete: Current-main blame and file history show Peter Steinberger introduced and recently maintained the Sheets conditional-format command, planner, and docs, and he also added the hardening commits on this PR head. (role: recent area contributor; confidence: high; commits: f20a26cd9e26, b83649577597, acaaafb001b4; files: internal/cmd/sheets_conditional.go, internal/sheetsconditional/conditional.go, docs/sheets-formatting.md)
• codBang: The changelog credits codBang's earlier Sheets formatting proposal for the conditional-format and banding command family, making them useful adjacent context for this area. (role: adjacent feature proposer; confidence: medium; commits: b83649577597; files: CHANGELOG.md, docs/sheets-formatting.md, internal/cmd/sheets_conditional.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.

Review history (1 earlier review cycle)

• reviewed 2026-07-05T03:02:43.481Z sha b59f75a :: passed. :: none

[steipete]

Landed in df7c9755aa4a15ce9cbed43e960df847dd1ae11d; maintainer changelog closeout in 57bcc147.

Validation:

• Final source-blind live Sheets E2E with clawdbot@gmail.com: disposable spreadsheet creation, dry-run with zero mutation, live MIN/NUMBER/MAX gradient creation, exact raw range/point/color readback, GRADIENT_RULE list output, mixed-mode/nested-typo/alpha/malformed-input rejection with state preserved, forced clear, and cleanup to trash. All 6 contract clauses passed.
• Local: full make test and make ci; focused command and planner suites; docs generation/coverage.
• Autoreview: iterated through nested generated-decoder and explicit-zero serialization findings; final full branch review clean with no accepted/actionable findings.
• Hosted CI: exact head acaaafb001b47bfa9e4052c0e0dc8e691bba584f; both Linux, macOS, Windows, and worker matrices plus Docker all passed.

Maintainer improvements use API-preferred colorStyle, strictly reject unknown nested RGB fields, preserve explicit zero RGB components, and reject alpha because the Sheets API silently drops it.