fix(docs): expose heading IDs in enumerator JSON

[clawsweeper]

Fixes #819

Summary

• add optional headingId to docs headings list --json heading objects
• add optional headingId to docs paragraphs list --json paragraph objects
• keep plain/TSV output unchanged and continue using docs named-range list for named range anchors
• document heading deep-link construction and add the release changelog entry

Notes

• Preserves existing run-link bookmarkId / headingId metadata in paragraph runs.
• Requested by @sebsnyk in docs: surface headingId (and bookmark/named-range anchors) in headings/paragraphs output for deep-linking #819.

Validation

• focused enumerator regression and plain-output compatibility tests
• semantic JSON key and omission assertions for headingId
• autoreview --mode branch --base origin/main --parallel-tests 'make ci': clean, no actionable findings
• make ci: pass

[clawsweeper]

Codex review: passed. Reviewed June 15, 2026, 11:27 AM ET / 15:27 UTC.

Summary
This PR adds optional headingId fields to Docs headings and paragraphs JSON output and covers them with enumerator tests.

Reproducibility: yes. Source inspection shows current main omits ParagraphStyle.HeadingId from headings and paragraphs JSON, and the PR adds a focused fixture test for that path.

Review metrics: none identified.

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.

Next step before merge

• No automated repair lane is needed because this PR is already the focused implementation candidate and has no actionable review findings.

Security
Cleared: The diff only changes internal Docs JSON structs and tests; it does not touch credentials, dependencies, workflows, or code-execution paths.

Review details

Best possible solution:

Land the narrow JSON-only headingId exposure with regression coverage if maintainers accept the expanded output contract, leaving named ranges on the existing named-range command surface.

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

Yes. Source inspection shows current main omits ParagraphStyle.HeadingId from headings and paragraphs JSON, and the PR adds a focused fixture test for that path.

Is this the best way to solve the issue?

Yes. Carrying the existing Docs API field through the enumerator model into JSON is the narrowest maintainable fix, and preserving TSV/plain output avoids changing the stable text format.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

• add P2: This is a bounded improvement to an existing Docs command surface with 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: The external-contributor proof gate does not apply to this ClawSweeper bot autofix PR; the PR body lists targeted unit, package, and CI validation.

Label justifications:

• P2: This is a bounded improvement to an existing Docs command surface with 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: The external-contributor proof gate does not apply to this ClawSweeper bot autofix PR; the PR body lists targeted unit, package, and CI validation.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its parseable stdout guidance and local unit-test expectations apply to this CLI output change. (AGENTS.md:1, 02c893f2e702)
• Current main omission: Current main has paragraph list/inspect JSON structs without a paragraph-level headingId and enumerateDocsParagraphs only carries NamedStyleType, so the linked request remains real on main. (internal/cmd/docs_enumerators.go:72, 02c893f2e702)
• Patch implementation: The PR diff adds HeadingID to both JSON item types, captures ParagraphStyle.HeadingId, and copies it through headings and paragraphs JSON paths while leaving TSV rendering unchanged. (internal/cmd/docs_enumerators.go:74, a8f8e863502e)
• Regression coverage: The PR adds a fixture-backed JSON test that verifies headings expose headingId, paragraphs expose it only on heading paragraphs, and normal paragraphs omit the field. (internal/cmd/docs_enumerators_test.go:203, a8f8e863502e)
• Linked issue context: The linked issue requests paragraph.paragraphStyle.headingId in headings and paragraphs output for Google Docs deep links, while noting bookmark and named-range anchors as adjacent scope.
• Feature-history routing: GitHub commit history for the enumerator files points to the content enumerator and paragraph run metadata commits as the main current-code provenance for this area. (internal/cmd/docs_enumerators.go)

Likely related people:

• Peter Steinberger: GitHub file history shows Peter authored the Docs content enumerator and paragraph-run metadata commits that define the affected output path. (role: feature-history owner; confidence: high; commits: e51f6be9dc38, 22c97dea8707, a31a878fdc7d; files: internal/cmd/docs_enumerators.go, internal/cmd/docs_enumerators_test.go)
• Sebastian Roth: Sebastian opened the linked deep-linking request and has recent merged Docs command work in this repository, making them useful workflow context for the output contract. (role: adjacent Docs contributor; confidence: medium; commits: f0dbde21f892, 58b866e9ac55, b646e886f6dd; files: internal/cmd, docs, CHANGELOG.md)

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.

[steipete]

Landed as f5cbba83f9a7178b5c91fcb40d9362a3740a626d.

Maintainer fixups added the changelog/docs entry and semantic JSON contract assertions for the literal headingId key and omission on normal paragraphs. Autoreview and full make ci passed; all GitHub checks were green. Thanks @sebsnyk for the request.