Best possible solution:

Land the feature after normal maintainer review, completed CI, and a small fix for the header/footer create validation gap.

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

Yes for the review finding: source inspection shows header/footer create skips placement validation when only --occurrence or --match-case is provided. I did not execute the PR branch or live Google API commands in this read-only review.

Is this the best way to solve the issue?

Mostly yes: the PR reuses existing Docs placement and request plumbing, but header/footer create should validate anchor-only flags consistently before merge.

Full review comments:

• [P3] Validate anchor-only header/footer flags — internal/cmd/docs_header_footer.go:191
hasPlacement only considers --index, --at-end, and --at, so gog docs header create <doc> --occurrence 2 or --match-case skips DocsBodyPlacementFlags.plan and silently creates the default header instead of returning the existing usage errors for anchor-only flags. Include those flags in validation before creating the segment.
  Confidence: 0.86

Overall correctness: patch is correct
Overall confidence: 0.78

AGENTS.md: found and applied where relevant.

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

Label changes:

• add P3: This is useful Docs ergonomics and feature work with limited immediate blast radius, not an urgent regression.
• 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 to this collaborator-authored PR; the body still records make ci and live Google Docs validation.

Label justifications:

• P3: This is useful Docs ergonomics and feature work with limited immediate blast radius, not an urgent regression.
• 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 to this collaborator-authored PR; the body still records make ci and live Google Docs validation.

Acceptance criteria:

• [P1] go test ./internal/cmd ./internal/docsedit.

What I checked:

• Repository policy read: AGENTS.md was read fully and its PR review-mode instruction applies: inspect the PR with gh view/diff and do not switch branches or mutate the checkout. (AGENTS.md:1, 0d260ac968f0)
• PR metadata and scope: GitHub reports this as an open, mergeable collaborator-authored PR closing feat(docs): promote sed-brace structural ops to first-class commands (insert-footnote / insert-section-break / insert-hr / section columns) #856 and feat(docs): write headers and footers (createHeader / createFooter / deleteHeader / deleteFooter) #857, with 44 files changed and verification claiming make ci plus live Google Docs runs. (f36226fd207e)
• Structural command implementation: The head adds command structs and runners for footnotes, section breaks, horizontal rules, and section columns with shared placement handling. (internal/cmd/docs_structural.go:25, f36226fd207e)
• Header/footer implementation: The head adds header and footer list/create/delete command groups and segment mutation result plumbing. (internal/cmd/docs_header_footer.go:16, f36226fd207e)
• Review finding source: Header/footer create only treats --index, --at-end, or --at as placement, so --occurrence or --match-case without --at skip the placement validator and are silently ignored. (internal/cmd/docs_header_footer.go:191, f36226fd207e)
• Segment editing implementation: The head extends insert, update, delete, find-range, and format to resolve exact header/footer/footnote segments and apply segmentId to Docs requests. (internal/cmd/docs_target.go:32, f36226fd207e)

Likely related people:

• steipete: Current-main blame and recent logs tie the Docs command registry, write/update/format paths, and adjacent Docs command work to Peter Steinberger. (role: primary Docs surface contributor; confidence: high; commits: 508a4d3cd368, 360310f49093, 0d260ac968f0; files: internal/cmd/docs.go, internal/cmd/docs_edit.go, internal/cmd/docs_format.go)
• sebsnyk: The linked feature issues were authored by sebsnyk, and visible history shows Sebastian Roth contributed adjacent positional markdown insertion used by the Docs editing surface. (role: recent adjacent contributor and feature reporter; confidence: medium; commits: ab9a331d4c07; files: internal/cmd/docs_edit.go)

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

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