feat(comments): add --since=<RFC3339> filter on docs/drive comments list

[sebsnyk]

Motivation

Polling for new comments without a since-filter forces clients to pull all comments and diff client-side. The Drive comments REST API supports startModifiedTime on comments.list — exposing it as a flag is a small change but a meaningful efficiency win for poll loops.

Verified against current source (v0.21.x): internal/cmd/drive_comments.go DriveCommentsListCmd and internal/cmd/docs_comments.go DocsCommentsListCmd expose --include-resolved, --max, --page, --all, --fail-empty — no time filter.

Repro

# Today, polling for comments touched in the last minute:
gog drive comments list <DOC_ID> --all -j | jq '.comments[] | select(.modifiedTime > "2026-06-04T10:00:00Z")'
# Fetches every page of every comment.

# Wanted:
gog drive comments list <DOC_ID> --since=2026-06-04T10:00:00Z

Proposed surface

gog drive comments list <fileId> --since=<RFC3339>
gog docs comments list <docId> --since=<RFC3339>

Wired to the startModifiedTime query parameter on comments.list.

Acceptance criteria

• --since accepts RFC3339 with timezone, rejects naked datetimes with a clear error.
• Server-side filtering verified via the same call returning fewer items than without --since.
• Combines correctly with --include-resolved, --max, --all.

References

• comments.list parameters (startModifiedTime): https://developers.google.com/workspace/drive/api/reference/rest/v3/comments/list

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 4, 2026, 7:53 AM ET / 11:53 UTC.

Summary
Keep open: current main still has no --since flag for Drive or Docs comment listing, and the shared Drive comments API call does not pass a startModifiedTime parameter. This is a narrow, VISION-aligned enhancement rather than an already-implemented cleanup.

Reproducibility: not applicable. as a bug reproduction: this is a feature request for a new CLI flag. Source inspection confirms the current command structs and shared API call do not expose the requested filter.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
This is a narrow aligned feature candidate with clear files, tests, and docs; the broader polling proposal at #690 should remain separate.

Review details

Best possible solution:

Add a shared modified-time filter for both comment-list commands while preserving existing pagination, resolved-comment filtering, JSON shape, and generated command docs.

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

Not applicable as a bug reproduction: this is a feature request for a new CLI flag. Source inspection confirms the current command structs and shared API call do not expose the requested filter.

Is this the best way to solve the issue?

Yes, the proposed narrow --since flag wired to Drive comments.list is the maintainable path. It should use strict RFC3339-with-timezone validation rather than the existing flexible tracking parser that accepts local or date-only inputs.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A local test can verify the startModifiedTime query parameter, but the final PR should include live Google proof that the server-side filter actually returns fewer or bounded comments.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label changes:

• add P2: This is a normal-priority Drive/Docs comments improvement with a clear limited blast radius for polling workflows.
• add impact:other: The issue affects automation efficiency for comment polling, which is meaningful but outside the specific owned impact categories.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority Drive/Docs comments improvement with a clear limited blast radius for polling workflows.
• impact:other: The issue affects automation efficiency for comment polling, which is meaningful but outside the specific owned impact categories.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd ./internal/timeparse
• make docs-commands
• Live Google check: compare gog drive comments list <fileId> --all -j with gog drive comments list <fileId> --since=<recent RFC3339> -j and confirm the filtered request returns the expected smaller/bounded result set.

What I checked:

• Repository policy read: AGENTS.md was read in full and its CLI/testing guidance was applied to the review and work-lane recommendation. (AGENTS.md:1, 3d5c9cef65fa)
• Drive comments list lacks the requested flag: DriveCommentsListCmd exposes fileId, max, page, all, fail-empty, and include-quoted, but no since/startModifiedTime field. (internal/cmd/drive_comments.go:23, 3d5c9cef65fa)
• Docs comments list lacks the requested flag: DocsCommentsListCmd exposes docId, include-resolved, max, page, all, and fail-empty, but no since/startModifiedTime field. (internal/cmd/docs_comments.go:24, 3d5c9cef65fa)
• Shared API call does not pass startModifiedTime: fetchDriveCommentsPage builds Comments.List with IncludeDeleted, PageSize, Fields, optional PageToken, and Context only. (internal/cmd/comment_ops.go:109, 3d5c9cef65fa)
• Generated command docs also lack the flag: The generated Drive and Docs comments-list command pages list the same current flags and do not document --since. (docs/commands/gog-docs-comments-list.md:35, 3d5c9cef65fa)
• Feature-history provenance: The relevant comments command files and shared helper were introduced in commit 2c84d89, which is tagged v0.21.0. (internal/cmd/comment_ops.go:57, 2c84d8981dd5)

Likely related people:

• Peter Steinberger: Git blame and git show attribute the Drive/Docs comments list commands and shared comment helper to commit 2c84d89. (role: introduced comments command surface; confidence: high; commits: 2c84d8981dd5; files: internal/cmd/drive_comments.go, internal/cmd/docs_comments.go, internal/cmd/comment_ops.go)

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.

[sebsnyk]

Cross-ref: #690 (gog drive/docs poll) consumes --since as the watermark primitive for docs comments poll — listed there as a hard dependency. Filing them as separate issues since --since stands alone as a low-level filter useful outside polling too.