feat(sheets): add basic filter creation command

[clawsweeper]

Summary

• Add gog sheets filter set <spreadsheetId> <range> for creating a Sheets basic filter.
• Resolve A1 and named ranges through the existing Sheets range catalog helpers.
• Send a focused SetBasicFilterRequest through Spreadsheets.BatchUpdate, with dry-run and JSON output matching neighboring Sheets mutation commands.
• Regenerate command docs with make docs-commands.

Validation

• make fmt
• go test ./internal/cmd -run 'TestSheetsFilter|TestDryRunE2E_CommandsSkipAuthAPIAndFileWrites'
• make docs-commands
• make ci

Closes #899

[clawsweeper]

Codex review: passed. Reviewed July 5, 2026, 1:26 AM ET / 05:26 UTC.

Summary
Adds gog sheets filter set <spreadsheetId> <range>, generated command docs, a Sheets skill listing entry, and focused tests for SetBasicFilter request construction and dry-run behavior.

Reproducibility: not applicable. as a bug reproduction; this is a feature implementation PR. The feature gap is source-confirmed because current main and v0.32.0 do not expose a Sheets basic-filter command, while this branch adds one.

Review metrics: none identified.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #899
Summary: This PR is the candidate fix for the linked Sheets basic-filter feature request.

Members:

• canonical: gog sheets should support creating filters (setBasicFilter) #899 - The PR body closes the issue, and the issue automation comment identifies this PR as the implementation branch.

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:

• none.

Risk before merge

• [P1] I did not run tests or a live Google Sheets call during this read-only review; the branch has request-shape unit coverage, but runtime API acceptance still depends on CI or maintainer smoke proof.

Maintainer options:

1. Decide the mitigation before merge
   Land the narrow sheets filter set command after normal checks, keeping this first pass to basic filter creation and tracking criteria or sort support separately if users need it.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No ClawSweeper repair lane is needed because no discrete patch defect was found; maintainer merge handling and CI should gate the current head.

Security
Cleared: The diff adds bounded Go command code plus generated docs/tests and does not change dependencies, credentials, CI, install scripts, or package execution paths.

Review details

Best possible solution:

Land the narrow sheets filter set command after normal checks, keeping this first pass to basic filter creation and tracking criteria or sort support separately if users need it.

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

Not applicable as a bug reproduction; this is a feature implementation PR. The feature gap is source-confirmed because current main and v0.32.0 do not expose a Sheets basic-filter command, while this branch adds one.

Is this the best way to solve the issue?

Yes: using the existing range catalog and Sheets BatchUpdate mutation helpers is the narrowest maintainable implementation path for setBasicFilter. A broader generic batch-update command is not needed for this request.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: The PR implements a bounded Sheets feature gap linked to an open P2 issue and has limited blast radius.
• 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: This is a ClawSweeper bot/autofix PR, so the external-contributor real behavior proof gate does not apply.

Label justifications:

• P2: The PR implements a bounded Sheets feature gap linked to an open P2 issue and has limited blast radius.
• 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: This is a ClawSweeper bot/autofix PR, so the external-contributor real behavior proof gate does not apply.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR-review guidance requires gh pr view/gh pr diff review mode without branch changes, which was followed. (AGENTS.md:37, c0aac99f6be6)
• Linked issue remains canonical: The PR body uses closing syntax for gog sheets should support creating filters (setBasicFilter) #899, and the issue automation comment points back to this PR as the implementation candidate.
• Current main lacks the command: Current main's Sheets command registry lists existing Sheets subcommands but has no filter/basic-filter command, and a targeted grep for setBasicFilter/BasicFilter/basic filter/sheets filter returned no matches on current main. (internal/cmd/sheets.go:33, c0aac99f6be6)
• Latest release also lacks it: The latest release tag v0.32.0 has no matches for setBasicFilter/BasicFilter/basic filter/sheets filter in the command source, generated docs, or Sheets skill listing. (f20a26cd9e26)
• PR implementation follows local helpers: The branch adds SheetsFilterSetCmd, resolves the supplied range through fetchSpreadsheetRangeCatalog and resolveGridRangeWithCatalog, then sends one SetBasicFilterRequest through applySheetsBatchUpdate. (internal/cmd/sheets_filter.go:30, dba7ddbdf86d)
• Tests cover request shape and dry-run: The new tests verify a named range produces a setBasicFilter batchUpdate request with sheetId force-sent, and verify dry-run exits before creating a Sheets service. (internal/cmd/sheets_filter_test.go:17, dba7ddbdf86d)

Likely related people:

• Peter Steinberger: Authored the current release commit that owns the Sheets command registry and helpers, and authored recent BatchUpdate-backed Sheets features including validation, banding, merge/freeze/number-format areas. (role: recent area contributor; confidence: high; commits: f20a26cd9e26, e1be268f70a6, b83649577597; files: internal/cmd/sheets.go, internal/cmd/sheets_mutation_helpers.go, internal/cmd/sheets_range_resolve.go)
• Tsopic: Authored the adjacent gog sheets batch-update command and tests in the same Sheets command registry area. (role: adjacent contributor; confidence: medium; commits: f911d6b21835; files: internal/cmd/sheets.go, internal/cmd/sheets_batch_update_test.go, docs/commands/gog-sheets-batch-update.md)
• Shehryar: Credited on the commit that added several BatchUpdate-backed Sheets mutation commands that are closest to the new filter command's implementation style. (role: credited adjacent contributor; confidence: medium; commits: 004b68cc703f; files: internal/cmd/sheets.go, internal/cmd/sheets_freeze.go, internal/cmd/sheets_merge.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.