fix(docs): preserve tab markdown nested lists

[steipete]

Summary

• Parse indented markdown list markers for the local tab writer and carry nesting levels through docs write --replace --markdown --tab.
• Emit one Docs list block with leading tabs for nesting, then override mixed child marker presets so ordered parent / unordered child cases round-trip as nested lists.
• Fix docs export --tab tab resolution by requesting tab metadata with includeTabsContent=true and a narrow tab field mask.

Fixes #696.

Proof

• go test ./internal/cmd -run 'TestParseMarkdown_NestedLists|TestParseMarkdown_NestedListsFourSpaceBlock|TestParseMarkdown_IndentedListMarkerWithoutParent|TestParseMarkdown_TopLevelListResetsNestedIndentStack|TestMarkdownToDocsRequests_NestedLists|TestMarkdownToDocsRequests_MixedListChildrenStayNested|TestDocsWrite_MarkdownReplaceWithTab_NestedLists|TestMarkdownToDocsRequests_AppendBulletsAndCode|TestResolveTabID' -count=1
• go test ./internal/cmd/...
• make ci
• /Users/steipete/Projects/agent-scripts/skills/autoreview/scripts/autoreview --mode local clean: no accepted/actionable findings
• Live E2E with clawdbot@gmail.com: scratch doc 1u395M6fn_9xohN2K-rKymuTCr3SOfQzjm1DSBsFlUQs, tab t.2u7ivet9p9b7; raw_levels_ok:true, raw_max_depth_level:8, raw_bullet_count:21, export_nested_ok:true, cleanup_trashed:true, gog_pr696_e2e_rc:0.
• Live E2E covered 2-space, 4-space, tab indentation, ordered lists, mixed ordered parent / unordered child export, and Docs levels 0..8. The issue text mentioned 10 levels, but the current official Docs API ListProperties reference says lists have at most 9 nesting levels, level 0 through level 8: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#ListProperties

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 7, 2026, 2:58 AM ET / 06:58 UTC.

Summary
The branch teaches the Docs tab-local markdown parser/formatter to preserve nested list levels, adjusts tab export tab resolution, and adds regression tests plus changelog notes.

Reproducibility: yes. from source and the linked public repro, but not from an executed local test in this read-only review. Current main parses list markers only at column 0 and formats parsed list items without nested-level handling.

Review metrics: 2 noteworthy metrics.

• Changed files: 8 files, +406/-47. The patch spans shared markdown parsing/formatting plus tab export, so reviewers should consider both write and export behavior.
• Test surface: 5 test files changed. Regression coverage is added for parsing, request generation, tab-scoped writes, and tab resolution.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
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] This read-only review did not execute the reported tests locally; CI should still gate the exact PR head before merge.

Maintainer options:

1. Decide the mitigation before merge
   Land the focused parser/formatter and tab-export fix after normal CI and maintainer review, leaving bug(docs write --tab): markdown path drops nested-list nesting (children render as plain text) #696 to close via the linked merge.
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; the branch already supplies a focused implementation and live proof, so the remaining action is normal PR review and CI gating.

Security
Cleared: The diff is limited to Docs command code, tests, and changelog notes; it does not add dependency, CI, credential, or code-execution surface.

Review details

Best possible solution:

Land the focused parser/formatter and tab-export fix after normal CI and maintainer review, leaving #696 to close via the linked merge.

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

Yes from source and the linked public repro, but not from an executed local test in this read-only review. Current main parses list markers only at column 0 and formats parsed list items without nested-level handling.

Is this the best way to solve the issue?

Yes. The PR repairs the existing tab-local markdown conversion with Docs leading-tab list semantics and fixes tab export metadata resolution rather than adding a new mode or config surface.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 490a9cb3556f.

Label changes

Label changes:

• add P2: This fixes an existing Docs markdown tab fidelity bug with limited blast radius.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live E2E output against a scratch Google Doc showing nested levels and markdown export round-trip success.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live E2E output against a scratch Google Doc showing nested levels and markdown export round-trip success.

Label justifications:

• P2: This fixes an existing Docs markdown tab fidelity bug with limited blast radius.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix live E2E output against a scratch Google Doc showing nested levels and markdown export round-trip success.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix live E2E output against a scratch Google Doc showing nested levels and markdown export round-trip success.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR review-mode guidance applies here by keeping the review read-only and avoiding branch changes. (AGENTS.md:1, 490a9cb3556f)
• Current parser gap: Current main recognizes numbered and unordered list markers only at column 0, so indented child markers fall through as paragraph content in the local markdown parser. (internal/cmd/docs_markdown.go:161, 490a9cb3556f)
• Current formatter gap: Current main creates bullet paragraphs per parsed list item but has no nested-level or leading-tab handling for child list items. (internal/cmd/docs_formatter.go:192, 490a9cb3556f)
• Current tab export resolver: Current main resolves tab IDs without IncludeTabsContent, matching the PR's export-side fix target. (internal/cmd/docs_tab_export.go:107, 490a9cb3556f)
• PR diff inspected: The patch changes the parser, Docs request formatter, tab export resolver, and focused tests for nested lists and tab resolution. (fda05f7d076b)
• Real behavior proof in PR body: The PR body reports targeted unit tests, package tests, make ci, autoreview, and a live Google Docs E2E run with raw_levels_ok:true, export_nested_ok:true, and cleanup_trashed:true. (fda05f7d076b)

Likely related people:

• sebsnyk: Commit 58b866e introduced docs write --replace --markdown --tab, and commit b646e88 introduced the native bullet/code markdown formatter behavior that this PR extends. (role: feature contributor and prior reporter; confidence: high; commits: 58b866e9ac55, b646e886f6dd; files: internal/cmd/docs_edit.go, internal/cmd/docs_write_markdown_tab_test.go, internal/cmd/docs_formatter.go)
• steipete: Recent current-main and merged PR history show work on the same Docs markdown parser/tab path, including paragraph-break and strikethrough fixes. (role: recent adjacent area contributor; confidence: high; commits: e4941e776504, 490a9cb3556f; files: internal/cmd/docs_markdown.go, internal/cmd/docs_formatter.go, internal/cmd/docs_write_markdown_tab_test.go)
• Vinston: Commit e2d41ad added the sedmat Docs formatting code with nested-list precedent using Docs list behavior adjacent to this markdown formatter work. (role: adjacent nested-list implementation contributor; confidence: low; commits: e2d41ad87c56; files: internal/cmd/docs_sed_nesting.go, internal/cmd/docs_sed_helpers.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.

[steipete]

Landed in e0926bc.

Proof:

• Focused regression tests: go test ./internal/cmd -run 'TestParseMarkdown_NestedLists|TestParseMarkdown_NestedListsFourSpaceBlock|TestParseMarkdown_IndentedListMarkerWithoutParent|TestParseMarkdown_TopLevelListResetsNestedIndentStack|TestMarkdownToDocsRequests_NestedLists|TestMarkdownToDocsRequests_MixedListChildrenStayNested|TestDocsWrite_MarkdownReplaceWithTab_NestedLists|TestMarkdownToDocsRequests_AppendBulletsAndCode|TestResolveTabID' -count=1
• Broader local tests: go test ./internal/cmd/...
• Full local gate: make ci
• Autoreview: /Users/steipete/Projects/agent-scripts/skills/autoreview/scripts/autoreview --mode local clean, no accepted/actionable findings
• GitHub checks: PR ci test, worker, darwin-cgo-build, windows all passed; PR docker image passed; duplicate push CI also passed
• Live E2E with clawdbot@gmail.com: scratch doc 1u395M6fn_9xohN2K-rKymuTCr3SOfQzjm1DSBsFlUQs, tab t.2u7ivet9p9b7; raw_levels_ok:true, raw_max_depth_level:8, raw_bullet_count:21, export_nested_ok:true, cleanup_trashed:true, gog_pr696_e2e_rc:0

Caveat: #696 mentioned 10 levels, but current Google Docs API ListProperties documents at most 9 nesting levels, level 0 through level 8. Live proof covers that API maximum.