feat(docs write): pre-flight orphan-comment check on --replace --markdown

[sebsnyk]

Motivation

A full-body markdown rewrite (gog docs write --replace --markdown --file=...) silently leaves any comment anchored to a phrase that disappears from the body as "orphaned". The comment is still attached to the file but is no longer anchored to live content, which is invisible until a reader notices. For docs collaborating with reviewers, this is a credibility leak: their notes effectively vanish.

The Docs API already returns quotedFileContent on comments.list, so a pre-flight check is straightforward: for every open comment, look up its quote, normalise whitespace + HTML entities, and check whether it survives in the incoming body.

Pairs with

• feat(docs comments): add locate subcommand to resolve a comment to a body range #687 docs comments locate — the orphan check is locate applied per open comment. If feat(docs comments): add locate subcommand to resolve a comment to a body range #687 ships, the implementation reduces to "for each open comment, call locate, treat orphaned: true as a would-orphan hit". Reusing the locate path keeps the normalisation rules consistent (a comment that survives --check-orphans is also resolvable by locate after the write). If feat(docs comments): add locate subcommand to resolve a comment to a body range #687 has not landed yet, this issue can still ship with the normalisation logic inlined; refactor when feat(docs comments): add locate subcommand to resolve a comment to a body range #687 lands.

Repro

# Reviewer leaves a comment on the phrase "rule extensions".
# Author rewrites the body and accidentally drops the phrase:
gog docs write <DOC_ID> --replace --markdown --file new.md
# Comment is now orphaned. Author has no idea.

Proposed surface

gog docs write <docId> --replace --markdown --file <md> --check-orphans
gog docs write <docId> --replace --markdown --file <md> --allow-orphans

Default behaviour change candidate: warn-on-orphan (with --allow-orphans to silence), or strict block-on-orphan (with --allow-orphans to override). Pick whichever fits the project's policy on backward-compat.

The pre-flight logic:

1. Read comments.list for the doc, including quotedFileContent.
2. For each open (unresolved) comment, take quotedFileContent.value, HTML-entity-decode it, normalise whitespace.
3. Apply the same normalisation to the incoming markdown body.
4. If the quote does not appear, mark the comment as "would orphan" and either warn or refuse.

Exit code 5 (or another well-defined non-zero) when orphans would happen and --allow-orphans was not given.

Acceptance criteria

• Detects orphans on a 3-reviewer test doc with mixed entity-encoded quotes (', ", &).
• Reports the orphaned comments grouped by author with the first 80 chars of the comment content + the first 60 chars of the quote.
• --allow-orphans proceeds silently.
• Resolved comments are skipped.
• Works under --tab= resolution.

References

• comments.list response (quotedFileContent.value): https://developers.google.com/workspace/drive/api/reference/rest/v3/comments/list
• gog upstream context: gog already exposes gog drive comments list --include-quoted -j --all; this issue lifts that into the write path.

[clawsweeper]

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

Summary
Keep open: current main still rewrites markdown without listing comments or checking whether quoted anchors survive, while the existing comments plumbing already exposes quoted content. The requested safety check is plausible, but the warn-vs-block default and its relationship to the open find-range/comment-locate work need maintainer product direction first.

Reproducibility: no. high-confidence live reproduction was established. Source inspection shows the write paths do not list comments before replacement, but the actual orphaning behavior needs a live Google Docs document with anchored comments to validate.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
Maintainers should choose warn vs block, exit-code behavior, and whether this waits for #682 and #687 before implementation.

Review details

Best possible solution:

Define the compatibility policy first, then add a shared preflight that reuses locate/find-range normalization and keeps stdout parseable with human warnings on stderr.

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

No high-confidence live reproduction was established. Source inspection shows the write paths do not list comments before replacement, but the actual orphaning behavior needs a live Google Docs document with anchored comments to validate.

Is this the best way to solve the issue?

Unclear until maintainers choose the default policy. The narrowest maintainable path is likely to reuse the open locate/find-range normalization work rather than invent a second comment-quote matcher in docs write.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Choosing strict block-by-default could break existing scripts that rely on docs write --replace --markdown; warning-only may not prevent accidental orphaning.
• The entity/whitespace normalization and tab behavior need live Google Docs validation because the requested behavior depends on Drive comments and Docs body semantics.
• Implementing this before the open find-range/comment-locate primitives may duplicate normalization rules that should become shared infrastructure.

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

Label changes

Label justifications:

• P3: This is a useful but non-urgent Docs safety enhancement with limited blast radius and an unresolved product-policy choice.
• impact:other: The affected impact is reviewer comment discoverability during Google Docs rewrites, which is meaningful but outside the specific owned impact classes.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its parseable stdout and testing guidance is relevant to any future warning/error surface and validation plan. (AGENTS.md:18, 3d5c9cef65fa)
• Vision fit and discussion gate: VISION.md fits small Google Workspace safety primitives, but says behavior changes and hard-to-live-test features should be discussed first. (VISION.md:23, 3d5c9cef65fa)
• Docs write has no orphan-check flags: DocsWriteCmd exposes text/file, replace/append, markdown, layout, and tab flags, but no check-orphans or allow-orphans option. (internal/cmd/docs_edit.go:36, 3d5c9cef65fa)
• Whole-document markdown replace bypasses comments: The no-tab markdown replace path prepares markdown and calls Drive Files.Update; it does not call Drive comments listing or inspect quotedFileContent. (internal/cmd/docs_edit.go:248, 3d5c9cef65fa)
• Tab markdown replace deletes and reinserts content without comment preflight: The tab path clears the selected tab body with DeleteContentRange and reinserts rendered markdown, but has no orphan-comment guard before deletion. (internal/cmd/docs_edit.go:429, 3d5c9cef65fa)
• Quoted-comment primitive already exists: Comment field selections include quotedFileContent, and docs comments list filters open comments by default, giving part of the requested data source. (internal/cmd/comment_ops.go:16, 3d5c9cef65fa)

Likely related people:

• Peter Steinberger: The available local history and blame attribute the current docs write, tab replacement, and comments plumbing to the v0.21.0 release commit authored by Peter Steinberger. (role: recent area contributor; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/docs_edit.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.