docspan 0.4.0__tar.gz → 0.5.0__tar.gz

{docspan-0.4.0 → docspan-0.5.0}/.github/workflows/publish.yml

@@ -3,6 +3,11 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git tag to build and publish (e.g. docspan-v0.4.0)"
+        required: true
 
 jobs:
   build:
@@ -10,19 +15,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          ref: ${{ inputs.ref || github.ref }}
           fetch-depth: 0  # needed for hatch-vcs version from git tags
-
       - name: Install uv
         uses: astral-sh/setup-uv@v4
-
       - name: Build package
         run: uv build
-
       - uses: actions/upload-artifact@v4.6.2
         with:
           name: dist
           path: dist/
-
   publish-testpypi:
     needs: build
     runs-on: ubuntu-latest
@@ -38,11 +40,9 @@ jobs:
         with:
           name: dist
           path: dist/
-
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
           repository-url: https://test.pypi.org/legacy/
-
   publish-pypi:
     needs: publish-testpypi
     runs-on: ubuntu-latest
@@ -58,5 +58,4 @@ jobs:
         with:
           name: dist
           path: dist/
-
       - uses: pypa/gh-action-pypi-publish@release/v1

docspan-0.5.0/.github/workflows/release-please.yml

@@ -0,0 +1,39 @@
+name: Release Please
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write  # to dispatch publish.yml below
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # release-please-action creates the GitHub Release using the default
+      # GITHUB_TOKEN. GitHub doesn't let events produced by that token
+      # trigger other workflows (loop-prevention), so publish.yml's
+      # `on: release: published` trigger never fires for these releases —
+      # dispatch it explicitly instead. workflow_dispatch is exempted from
+      # that restriction even when invoked with GITHUB_TOKEN.
+      - name: Trigger PyPI publish
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run publish.yml \
+            --repo "${{ github.repository }}" \
+            --ref main \
+            -f ref="${{ steps.release.outputs.tag_name }}"

docspan-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{docspan-0.4.0 → docspan-0.5.0}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0](https://github.com/tstapler/docspan/compare/docspan-v0.4.0...docspan-v0.5.0) (2026-08-14)
+
+
+### Features
+
+* **google-docs:** sectioned sync for large document mappings ([#106](https://github.com/tstapler/docspan/issues/106)) ([fe12122](https://github.com/tstapler/docspan/commit/fe121229c8b6b957254020fd2c06241f7506aa80))
+
+
+### Bug Fixes
+
+* **ci:** dispatch PyPI publish from release-please via workflow_dispatch ([e76ffb8](https://github.com/tstapler/docspan/commit/e76ffb8547bfd7d2d2b453a64a5fb3899445fc5f))
+* **confluence:** report internal anchors instead of writing a link to nowhere ([#105](https://github.com/tstapler/docspan/issues/105)) ([cd38f24](https://github.com/tstapler/docspan/commit/cd38f2415e37814e071a180182454d761cfcbfa9))
+* **google-docs:** reset table cell paragraph style to NORMAL_TEXT on fill ([e6db797](https://github.com/tstapler/docspan/commit/e6db797d51746c738586c3cab171367e23bd5be0))
+
 ## [0.4.0](https://github.com/tstapler/docspan/compare/docspan-v0.3.0...docspan-v0.4.0) (2026-08-13)
 
 
@@ -131,7 +145,9 @@ Each of these is tracked as a follow-up rather than half-addressed here.
 - A pull cannot express a `bookmark`/`bookmarkId` link, a link to a tab, or any link inside
   a table cell, so those are dropped from the pulled file without a report.
 - Confluence writes an internal anchor as a literal `#fragment` href, which it does not
-  resolve.
+  resolve. `push` now reports this as a warning naming the anchor(s) instead of shipping it
+  silently; the href itself is unchanged, since no live instance was available to establish
+  what Confluence actually generates for a heading.
 - An anchor that resolves to nothing is written as plain text, so a later pull replaces the
   author's `[text](#anchor)` with `text`. The push reports it; nothing does afterwards.
 - Such a push exits non-zero on every run, with no flag to suppress it.

{docspan-0.4.0 → docspan-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docspan
-Version: 0.4.0
+Version: 0.5.0
 Summary: Push and pull markdown to Google Docs and Confluence from a single CLI
 Project-URL: Homepage, https://github.com/tstapler/docspan
 Project-URL: Repository, https://github.com/tstapler/docspan

docspan-0.5.0/project_plans/gdocs-sectioned-sync/decisions/ADR-001-manifest-yaml-sidecar-keyed-by-heading-id.md

@@ -0,0 +1,24 @@
+# ADR-001: Manifest is a `_manifest.yaml` sidecar keyed by `heading_id`, never renumbered
+
+## Status
+Accepted
+
+## Context
+A sectioned mapping needs a durable record of (a) which on-disk section files correspond to which sections of the Google Doc, and (b) their canonical order, so that renames, reorders, and add/delete can be detected reliably instead of guessed from filenames or content.
+
+Three candidate identity/order mechanisms were evaluated (`project_plans/gdocs-sectioned-sync/research/build-vs-buy.md`):
+
+1. **Google Docs `NamedRange`/`namedRanges`** — visible to all collaborators, but has no Docs UI (a human can't see or fix it directly), names aren't required to be unique (so lookup-by-name isn't authoritative on its own — a `namedRangeId` still has to be tracked externally, meaning it doesn't eliminate the need for a manifest), and a single named range can silently split into multiple discontiguous ranges when a collaborator edits across its boundary — which complicates both splitting and reorder detection. It would also require new `CreateNamedRangeRequest`/`DeleteNamedRangeRequest` batchUpdate request types that `docs_request_builder.py` doesn't currently emit.
+2. **Filesystem/filename order** (bare slug or numeric prefix as sole order authority) — `ls`/`git diff --stat` order is convenient for humans but is not a stable identity: renumbering files on every insert/delete makes every unrelated file show as changed in git history (research/ux.md's "sharpest UX risk").
+3. **A flat, git-tracked YAML sidecar (`_manifest.yaml`) keyed by Google Docs' own persistent `heading_id`**, with `slug` and `filename` as companion, non-authoritative fields.
+
+## Decision
+The manifest is `_manifest.yaml`, a plain YAML file (not embedded front matter, not `.md`) living alongside section files in the sectioned mapping's directory. It is the single source of truth for section order and identity, keyed by `heading_id` (`DocsParagraphNode.heading_id`, `docs_structure_parser.py:188`). Filenames (`NN-slug.md`) are a human-readable cache of that order, not the authority — on push, manifest order wins over `ls` order or file-content order. `heading_id`s are assigned once (by Google Docs, not by docspan) and are never renumbered on reorder.
+
+Written/read atomically via temp-file-then-`os.replace`, mirroring the existing pattern in `config.py:126-167`'s `save_config`.
+
+## Consequences
+- Manifest and section files must be kept in sync at all times; any code path that mutates one without the other risks the desync failure mode called out in pitfalls research. Atomic directory-level writes (Epic 6 in `implementation/plan.md`) exist specifically to bound this risk.
+- `heading_id` does not survive delete+reinsert in Google Docs (confirmed via `heading_anchors.py` and `tabs.py:38-55`), so reorder must be implemented as an in-place move, not delete+reinsert — see ADR-002. This ADR and ADR-002 are coupled: choosing `heading_id` as identity is only safe because ADR-002 commits to preserving it across reorders.
+- Manifest is git-trackable plain text, giving full diff visibility — but that also means a manifest is one more file a human could hand-edit incorrectly; a lint/warning for manifest/directory-contents mismatch is recommended future work (noted in `research/ux.md`'s "discoverability" unstated need) but not required for v1.
+- `NamedRange` remains available as a *future, redundant* corroborating identity mechanism if manifest drift proves to be a real-world problem — explicitly not needed for v1, so this decision doesn't foreclose it.

docspan-0.5.0/project_plans/gdocs-sectioned-sync/decisions/ADR-002-reorder-as-in-place-move.md

@@ -0,0 +1,25 @@
+# ADR-002: Section reorder is implemented as an in-place move, not delete+reinsert
+
+## Status
+Accepted — Task 3.2.2's spike concluded (see Consequences): the Docs API batchUpdate surface has no move-equivalent primitive, so rung 3 of the fallback ladder shipped (`_classify_section_reorder` / `push_sectioned` in `src/docspan/backends/google_docs/backend.py`, ~lines 940-986): `heading_id` churn is accepted as a documented limitation and surfaced as a push warning when a reordered section also carries a content edit. No move primitive or copy-then-delete fallback was implemented.
+
+## Context
+When a sectioned mapping's local directory reflects two sections having swapped order (or a section relocated elsewhere in the document) relative to the stored manifest, `docspan push` must translate that into Google Docs batchUpdate requests.
+
+The most naive implementation — delete the moved section's content range and reinsert it (as fresh markdown) at its new position — is the same mechanism the existing single-file push already uses for ordinary content edits (`_build_push_plan`'s diff-and-emit pipeline, `docs_request_builder.py`). But `heading_id` is confirmed (via `heading_anchors.py`'s docstring and `tabs.py:38-55`) to **not survive delete+reinsert**: Google Docs assigns a fresh `heading_id` to any newly-inserted heading paragraph, even if its text is byte-identical to what was deleted.
+
+This matters because:
+- ADR-001 makes `heading_id` the manifest's identity key. Regenerating it on every reorder would mean the manifest's identity mapping goes stale on the very operation (reorder) it exists to detect.
+- Any cross-section anchor link pointing at that heading (`heading_anchors.py`'s anchor resolution) would silently break — the link would point at a `heading_id` that no longer exists — with no error surfaced at push time, only a broken link discovered later.
+- This is exactly the kind of failure mode research (`research/pitfalls.md`) flags as needing a design-time decision, since it changes what "detecting a reorder" has to compile down to in `docs_request_builder.py`, not something safe to discover mid-implementation.
+
+## Decision
+Reorder of a section (a move that changes position without changing content) is implemented as an in-place move of the existing content range, preserving its `heading_id`, rather than as delete-old-content + insert-new-content-from-markdown. Add/delete/reorder classification (Task 3.2.1 in `implementation/plan.md`) uses `difflib.SequenceMatcher` over `heading_id` sequences (stored-manifest-order vs. current-local-directory-order) specifically so that "moved" is a distinguishable classification from "deleted + inserted," and the move path is only taken for entries the classifier marks as moved-not-changed.
+
+The concrete Docs API batchUpdate request shape for the move itself is **not yet finalized** — `docs_request_builder.py` today only expresses insert/delete/style-update requests, no "move a range" primitive. Task 3.2.2 in the implementation plan is an explicit design spike to determine whether the Docs API exposes a true move-equivalent request, or whether the safest available approximation is copy-content-to-new-position followed by delete-of-the-old-range *only after* the insert succeeds (still avoiding a naive delete-then-reinsert-from-markdown, which is what would regenerate the `heading_id`).
+
+## Consequences
+- Task 3.2.2's spike (recorded here rather than left as an open Unresolved Question in `implementation/plan.md`) found no Docs API batchUpdate request that expresses "move a range" — `docs_request_builder.py`'s `build()` only ever emits equal/delete/insert/replace opcodes. Rung 1 (a true move primitive) is therefore unavailable, and rung 2 (copy-then-delete-after-insert-succeeds) was not implemented — it would need new request-shape code beyond anything demonstrated necessary once rung 3 covered the observed cases.
+- Rung 3 shipped instead: for a *pure* reorder (manifest order changed, section content itself untouched), `docs_request_builder.py`'s `_repair` step folds the swapped run's content pairs back to `equal` opcodes, so `heading_id` is preserved for free and zero batch_update requests are emitted (a true no-op push, `status="skipped"`). `heading_id` churn only actually occurs when the reordered section *also* carries a genuine content edit the differ cannot fold back to `equal` — that case is written as ordinary delete+insert, the `heading_id` does not survive, and `push_sectioned` attaches a `status="warning"` message naming the reordered sections. The next `pull_sectioned` re-derives the manifest fresh, so the churn is self-healing rather than a lasting inconsistency; cross-section anchors pointing at a churned heading are not automatically re-resolved and can go stale until that next pull.
+- Reorder-only pushes remain simpler than the move primitive this ADR originally anticipated, since the reused diff tail (`docs_request_builder.py:1133-1195`'s write-backwards, highest-anchor-first ordering) needed no new request type — `_classify_section_reorder` only changes what warning is attached, never what gets emitted.
+- Edit-and-rename-in-the-same-cycle (a heading both moved and heavily content-edited at once) remains an accepted, named limitation — the classifier cannot always disambiguate "moved-and-edited" from "deleted-and-a-different-section-inserted-at-that-position" from content alone. This is the same case that now hits the rung-3 heading_id-churn path above; this ADR does not attempt further disambiguation.

docspan-0.5.0/project_plans/gdocs-sectioned-sync/decisions/ADR-003-sectioned-pull-always-structural-path.md

@@ -0,0 +1,19 @@
+# ADR-003: Sectioned pull always uses the structural path, never Drive HTML export
+
+## Status
+Accepted
+
+## Context
+`GoogleDocsBackend.pull()` today has two distinct code paths (`backend.py`):
+- **Default path** (`tab_id is None`, lines ~910-950): fetches the doc via Drive's HTML export and converts it with `DocumentConverter().html_to_markdown()`. `DocsStructureParser` is used here only throwaway, for anchor upgrading — its parsed node list is discarded, not what gets written to disk.
+- **Structural path** (`tab_id is not None`, lines ~874-908): parses the doc into a flat `List[DocsParagraphNode]` via `DocsStructureParser`, projects it through `project()`, and writes the *parsed node list itself* (via `render_nodes_to_markdown()`) to disk.
+
+Sectioned pull needs to partition the document at a configured heading level (`split_level`) into N separate markdown files. Drive's HTML export is an opaque, whole-document conversion — architecture research (`research/architecture.md`) confirmed it cannot be scoped to a heading range or otherwise handed a "start here, stop there" instruction. Only the structural path's flat node list is something `section_splitter.py` (a new module) can walk and cut at heading boundaries, because the split happens against the same node representation `render_nodes_to_markdown()` consumes.
+
+## Decision
+`backend.pull_sectioned()` always parses via `DocsStructureParser` + `project()` (the structural path), regardless of whether the mapping targets a tab or the default document — never via Drive HTML export, even though non-sectioned pull on the default (non-tab) path still uses HTML export today. Splitting happens after `project()` runs, not before, so each section's node list is already reduced to "what markdown can represent" form before being cut into groups — avoiding disagreement about residue handling at section boundaries (e.g. an empty paragraph immediately before a heading).
+
+## Consequences
+- Sectioned pull's output may have subtly different formatting-fidelity characteristics than a non-sectioned pull of the same document would have had via the default HTML-export path, since it's a genuinely different conversion pipeline (structural vs. HTML-export). This is judged acceptable because sectioned mode is opt-in and net-new — there is no existing sectioned-mode behavior to regress relative to.
+- This makes the structural path (already used for tab-scoped docs) load-bearing for a second, independent reason (sectioning). Any future bug fix to the structural path's fidelity now has two justifications to preserve behavior for, and tests should cover both tab-scoped and sectioned-but-non-tab-scoped documents through it — two structural pull paths existing simultaneously (tab-scoping and sectioning) was explicitly flagged as a "Rabbit Hole" in requirements.md and needs a test matrix covering their interaction (a sectioned mapping targeting a specific tab).
+- `render_nodes_to_markdown()`'s only stateful pass (`_group_code_runs`) was confirmed to be a local pass over the given list — safe to invoke once per section rather than once per document — so no shared cross-section state needs to be threaded through the splitter.

docspan-0.5.0/project_plans/gdocs-sectioned-sync/implementation/adversarial-review.md

@@ -0,0 +1,28 @@
+# Adversarial Review: gdocs-sectioned-sync (iteration 2)
+**Date**: 2026-08-13
+**Verdict**: CONCERNS
+
+## Blockers
+(none)
+
+## Concerns
+- [x] Task 3.1.3 (`implementation/plan.md:202`) — **Resolved.** Plan.md now specifies only "pass a section file's own path (never the bare sectioned directory)" as `markdown_path`, dropping the previously-offered directory option that resolved one level too high against `build_source`'s `.parent` behavior. Also added a fixture requirement (Story 7.1/7.2) for colliding same-named images across two sections, surfaced as a `warning`/`error` per the Observability Plan.
+- [x] Citation in Task 5.2.1 — **Resolved.** plan.md now cites `MappingState` at `core/state.py:12` and `SyncState.get`/`update` at `core/state.py:40-43`, not `orchestrator.py:81-143`.
+- [ ] **Accepted limitation, not fixed.** No dedicated task for a manifest-vs-on-disk consistency pre-diff check (e.g., manifest lists a filename absent from disk, or a stray `.md` file not in the manifest) before push-time diffing begins. Coverage is implicit via Task 2.2.1 (pull-side matching) and Story 3.2 (add/delete/reorder detection derived from directory listing vs. manifest); this is judged sufficient for v1 given the appetite, and is not named as a separate pre-diff validation step.
+- [ ] **Accepted limitation, not fixed.** Concurrent pull/push race handling has no explicit task or acceptance criterion (e.g., two processes racing on the same sectioned directory, or a push racing a manifest write). Single-file docspan mappings have the same unaddressed race today; sectioned mode does not regress this, and dedicated locking is out of scope for v1.
+- [ ] Partial-API-failure coverage for the reorder fallback (copy-to-new-position + delete-old-range-after-insert) remains thin. Task 6.1.2's "keep the full reassembled request list within a single `batchUpdate` call wherever possible" implicitly gives the fallback's two operations atomicity (Docs batchUpdate applies all sub-requests as one transaction), but the plan never states this connection explicitly for Story 3.2/ADR-002's fallback path — a reader has to infer it. Recommend a one-line cross-reference in Task 3.2.3 or ADR-002 Consequences.
+
+## Minors
+- Preamble sentinel-key format (Task 2.1.2, `plan.md:187`) is still only "e.g. a fixed sentinel key" — no concrete value chosen. Left as-is.
+- YAML library choice for `manifest.py` (Task 1.2.1) is still unspecified; `config.py` uses `import yaml` (PyYAML) while `pyproject.toml` also lists `ruamel.yaml>=0.18.0` as a dependency — the plan doesn't say which one `ManifestStore` should use. Left as-is.
+- Comment-bucketing misassignment edge case (near-duplicate quoted text appearing in two sections) is not more deeply treated than iteration 1; Task 4.1.1's "first match wins in manifest order" is a defined-but-not-obviously-correct tiebreak for that case. Left as-is.
+
+## Prior-blocker resolution status
+
+1. **Resolved.** Step 0.5 (`plan.md:21`) and Task 3.1.3 (`plan.md:202`) now correctly describe `_build_push_plan`'s real signature/behavior, verified independently against `backend.py:172-299`: `_build_push_plan(local_path, doc_id, tab_id=None)` reads `pathlib.Path(local_path).read_text()` at line 195 and calls `resolve_document_images(image_nodes, local_path, ...)` at line 208 — matching the plan's citations. Task 3.1.3 adds a concrete `content: Optional[str] = None` parameter to skip the read when pre-assembled content is supplied, leaving single-file `push()`/`preview_push()` unaffected (`content=None`). The "unchanged" claim is now correctly scoped to only the diff/request-emission tail (`_build_push_plan`'s post-front-half code, confirmed unchanged in the read source at `backend.py:232-299`), not the whole function. One residual inaccuracy in the same task's image-path guidance is flagged above as a concern (not a blocker — the correct alternative is also given in the same sentence).
+
+2. **Resolved.** Task 1.1.2 (`plan.md:172`) now specifies a concrete `@model_validator(mode="after")` on `Mapping` enforcing `sectioned == (split_level is not None)`, raising `ValueError` for both the `sectioned=True, split_level=None` and `sectioned=False, split_level=<set>` cases, and Story 1.1's Given/When/Then acceptance criteria (`plan.md:167-170`) reflect both invalid combinations plus the two valid ones. `config.py`'s current `Mapping` class (confirmed at `src/docspan/config.py:78-88`) has no existing validator, matching the plan's note that this introduces the pattern.
+
+3. **Resolved.** New Story 7.5 (`plan.md:268-272`) and Task 7.5.1 deliver a `sectioned` × `tab_id` test matrix, explicitly citing ADR-003. It covers the three combinations that matter: both set (correct tab + same split as unscoped), `sectioned` true with `tab_id` unset (regression vs. Story 7.1), and `tab_id` set with `sectioned` false (regression check that sectioned code doesn't affect the existing tab-scoped path). The fourth combination (neither set) is already exercised by pre-existing tests, so its omission here is reasonable.
+
+4. **Resolved.** A "Go/no-go gate" section (`plan.md:210-214`) now sits explicitly between Task 3.2.2 and Task 3.2.3, naming three tiers: a real move primitive, ADR-002's documented copy-then-delete-after-insert fallback, and (if even that is infeasible) accepting `heading_id` churn as a documented limitation — matching what ADR-002's Decision/Consequences sections actually say (verified by reading `decisions/ADR-002-reorder-as-in-place-move.md`). Story 7.3's acceptance criteria (`plan.md:261`) are rewritten to hold under either outcome ("go" preserves both `heading_id`s; "no-go" asserts the documented churn explicitly), so they don't need rewriting once the spike resolves.

docspan-0.5.0/project_plans/gdocs-sectioned-sync/implementation/architecture-review.md

@@ -0,0 +1,31 @@
+# Architecture Review: gdocs-sectioned-sync
+**Date**: 2026-08-13
+**Verdict**: CONCERNS
+
+## Constitution Violations
+- N/A — no `docs/adr/ADR-000-architecture-constitution.md` found in the repo (checked `docs/adr/` and repo-wide for `ADR-000*`).
+
+## Blockers
+
+None. All plan citations against actual source were verified accurate (`Mapping` at `src/docspan/config.py:78`, the three `m.local == file` sites at `src/docspan/cli/main.py:466,578,789`, `DiffTooExpensive`/`_bounded_opcodes` at `docs_request_builder.py:53-113`, write-backwards ordering at `build()` starting `docs_request_builder.py:1133`, `heading_id` capture at `docs_structure_parser.py:188/578`, and the claim that the request builder has no "move" primitive today — confirmed only insert/delete/style-update requests exist). No story bakes in a correctness or safety defect severe enough to block; the issues below are all fixable by restructuring specific tasks before Epic 1/2 implementation starts.
+
+## Concerns
+
+- [ ] **Task 1.1.1/1.1.2 (illegal state: `sectioned`/`split_level` pair)** — `Mapping.sectioned: bool = False` and `Mapping.split_level: Optional[str] = None` are two independently-optional fields, so `sectioned=True, split_level=None` and `sectioned=False, split_level="HEADING_1"` are both representable, and Task 1.1.2 only validates the *value* of `split_level` (one of HEADING_1..6), not the *conjunction* with `sectioned`. Remediation: add a pydantic `model_validator(mode="after")` on `Mapping` that raises when `sectioned and split_level is None`, and either clears or rejects a set `split_level` when `sectioned` is False. This is a config-parse-boundary fix (Lens 2 point 7), consistent with the existing "parse at the boundary" pattern `load_config` already follows for Confluence env-var defaults.
+
+- [ ] **Task 1.2.1 (`heading_id` sentinel conflation for preamble)** — the manifest's `heading_id` field is documented to hold either a real Docs `headingId` or a synthetic sentinel for the preamble section (Domain Glossary: "Preamble / section 0"). Loading a real Docs ID and a manufactured sentinel into the same `str` field is exactly the kind of illegal-state-representable case Lens 2 point 6 flags — a future reader (or a diff routine) can't tell "real heading_id" from "sentinel" without out-of-band knowledge, and a pathological doc with a heading whose ID collides with the sentinel string is a real (if rare) correctness bug with no defense. Remediation: make `SectionManifestEntry.heading_id: Optional[str]` (`None` = preamble, matching how `DocsParagraphNode.heading_id` already models "no heading" as `None` at `docs_structure_parser.py:188`), and special-case the preamble entry positionally (always index 0, matched by position not key) in the Epic 3 SequenceMatcher pass rather than round-tripping a magic string through the identity system.
+
+- [ ] **Task 4.1.1 (comment bucketing: silent mis-assignment, not just non-assignment)** — bucketing is "first section (in manifest order) whose rendered text contains the quoted substring wins." The plan only names a residue case for *zero* matches ("unassigned"); it has no case for the quoted text substring-matching *more than one* section (a repeated phrase, a shared boilerplate line, or a short/generic quote). Today's `first-match-wins` will silently attach the comment to the wrong section with no warning — worse than "unassigned," since a human won't know to look for it. Remediation: track match count per comment across sections; when count > 1, emit an "ambiguous — assigned to section N by manifest-order tiebreak" warning-level residue (same status shape as the existing "unmatched" residue) so at least it's visible, rather than a silent success.
+
+- [ ] **Story 3.2 / DDD aggregate boundary (no `SectionedDocument` aggregate)** — the plan spreads "sectioned document" invariants (manifest order matches on-disk files, every manifest entry has a corresponding file, section count is consistent) across `ManifestStore`, `section_splitter.py`, and procedural code inside `backend.py`'s `pull_sectioned`/`push_sectioned` bodies, with no single object whose constructor enforces them. This is a missing aggregate root/value-object (Lens 1 point 3): nothing stops `push_sectioned` from reading a manifest with 5 entries against a directory with 4 files except an ad hoc check wherever someone remembers to add one. Remediation: introduce a `SectionedDocument` value object with a single factory (`SectionedDocument.load(directory) -> SectionedDocument`) that validates manifest/file consistency once at load time and raises/reports a clear error, and have both `pull_sectioned` and `push_sectioned` construct/return this type rather than juggling loose `(manifest, list[Path])` tuples inline.
+
+- [ ] **Task 5.1.1 / cli/main.py path-resolution (SRP creep risk, not the pattern itself)** — replacing the three `m.local == file` exact-match sites with a "Specification pattern" predicate is the right direction, but the plan doesn't specify where this predicate lives. If it's added as a private helper duplicated near each of the three call sites (natural path of least resistance during implementation), the three sites drift independently over time the same way the current exact-match duplication already has (three separate `next((m for m in config.mappings if ...), None)` idioms doing the same lookup). Remediation: land it as one function, e.g. `resolve_mapping_for_path(config, path) -> Optional[Mapping]`, used by all three CLI call sites plus `orchestrator.py`'s dispatch — not three independent predicates.
+
+- [ ] **Epic 5, Story 5.2 (state-keying migration is additive, but undocumented for existing sectioned re-runs)** — `SyncState.mappings` is a flat `dict[str, MappingState]` keyed by arbitrary path strings (`src/docspan/core/state.py:22,40-44`), so keying one entry per section-file path instead of one per `mapping.local` is mechanically trivial, confirming the plan's claim that `merge.py`/the content-hash store need no change. But the plan doesn't say what happens to the *existing* single `mapping.local`-keyed entry if a mapping is later switched from non-sectioned to sectioned (Migration Plan only covers the reverse: sectioned-absent → unchanged). Since that conversion is out of migration scope per the requirements ("No auto-migration of existing single-file mappings"), this is likely fine as long as `.markgate-state.json` isn't left with a dangling stale entry under the old path — worth one line in Epic 5 to state that a converted mapping's stale `mapping.local` entry is simply orphaned (harmless, ignorable) rather than silently reused.
+
+## Nitpicks
+
+- **"Chain-of-Responsibility" label on comment bucketing (Task 4.1.1)** and **"Specification pattern" label on CLI path resolution (Task 5.1.1)** are both GoF-pattern names applied to what implementation will likely be a single linear-scan function and a single predicate function, respectively (Lens 3 point 9). Naming the pattern in the plan is fine as design vocabulary, but implementers should not build handler-class hierarchies or a `Specification` interface/composite for either — a plain function is the right amount of structure here, and the plan should say so explicitly to head off over-engineering during Epic 4/5 implementation.
+- **`_bounded_opcodes` is a private (underscore-free but module-private-by-convention) helper** in `docs_request_builder.py` (`docs_request_builder.py:80-113`) that Task 3.2.1 plans to reuse for section-level `heading_id` sequence alignment. Its signature (`List[Tuple]` in, generic) is already reusable as-is, but it's imported today only from within its own module. Worth a one-line task to confirm/export it as an intentional shared utility (or move it to a small `diff_utils.py`) before Epic 3 imports it cross-module, rather than reaching into another module's underscore-adjacent internals ad hoc.
+- **`pull_sectioned`/`push_sectioned` as new `GoogleDocsBackend` methods (winning Architecture A)** is the right call given `push()`/`pull()` are already 130-380 lines each (confirmed: `backend.py` is 1228 lines total, `pull` starts at line 852, `push` at line 377 running to `pull`'s start — a ~475-line span for `push` alone including its helpers). Recommend Epic 2/3 acceptance criteria explicitly cap `pull_sectioned`/`push_sectioned` themselves to thin dispatch (manifest load → split/concat → delegate), so the size problem the plan correctly avoided in Option B doesn't quietly reappear inside the new methods instead of the old ones.
+- **Primitive-obsession lens (heading_id/slug/filename as bare `str`)** is technically present (Lens 2 point 5) but is consistent with the rest of the codebase's convention — `DocsParagraphNode.heading_id: Optional[str]`, `style: str`, etc. are already unwrapped strings throughout `docs_structure_parser.py`. Not worth introducing `NewType` wrappers against the grain of the existing style; the sentinel-conflation concern above is the sharper, actionable version of this issue and supersedes it.