docs-sync — code↔docs drift orchestrator

Orchestrates four subagents (planner, searcher, editor, curator) to detect and fix documentation drift in parallel git worktrees, then atomically amend the commit before push.

Workflow#

1. Stale-worktree cleanup — unconditionally remove any leftover docs-sync-* worktrees from previous runs before doing anything else. They are always garbage.
2. Hook check — on first run, offer to install a pre-push git hook so the command runs automatically. On subsequent runs, skip this prompt silently.
3. Detect changed code + docs layout — compute the diff between HEAD and the remote merge-base. If no non-documentation files changed, exit cleanly. Also detect whether docs/ is a regular folder or a git submodule (changes the apply/commit flow at step 8).
4. MCP probe — verify the markdown-lsp MCP server is reachable. Abort with a clear error if it is not; never block push silently.
5. Plan clusters (Haiku) — the docs-planner subagent groups changed code files into semantic clusters and produces a hypothesis per cluster about which docs sections might have drifted.
6. Fan out per cluster (parallel) — for each cluster, create an isolated git worktree (in the main repo for regular docs/, or inside the submodule when docs/ is a submodule), then invoke docs-searcher (Haiku) to locate drifted pages with a confidence score.
7. Edit drifted pages (Sonnet) — for each cluster whose confidence meets the threshold, invoke docs-editor (Sonnet) in the worktree to rewrite the affected sections.
8. Curate (Sonnet) — the docs-curator subagent receives all editor hunks, resolves cross-cluster conflicts, normalizes style, drops speculative edits AND verifies grounding of CLI commands / URLs / version numbers against the original diff, then produces a final edit list.
9. Apply atomically (branches on docs layout):
   • Regular folder: apply final edits in main repo → git add docs/ → git commit --amend --no-edit.
   • Submodule: apply final edits in a submodule worktree → commit inside the submodule → ask the user before pushing to the submodule's public remote → on consent, push + fast-forward the submodule + amend HEAD in the parent.
10. Cleanup — remove worktrees unconditionally on success or no-op; keep them on awaiting_push_consent or hard failure for triage.
11. Emit structured report — final JSON to stdout with status, submodule_commit, main_repo_commit, remote_pushes_pending, worktrees_cleaned, human_review_needed. Parent orchestrators rely on this contract.

Guardrails#

• Never block a push in warn mode (the default). Only exit non-zero when the repo explicitly sets mode: block in .docs-sync.json.
• Never amend if the curated edit list is empty — log "no doc edits needed" and exit cleanly.
• Cap the diff passed to the planner at 50 KB; truncate larger diffs with a note.
• No single editor pass may rewrite more than the configured diffCap fraction (default 0.4) of a page — edits beyond that threshold are dropped by the curator.
• On subagent timeout, skip that cluster and log it; do not abort the remaining clusters.
• If the MCP server is unreachable, abort the workflow and print a one-line warning; do not silently pass.
• Keep worktrees in place on awaiting_push_consent or hard failure for triage. Clean them up unconditionally on success or no-op.
• Submodule public push needs consent. When docs/ is a submodule, pushing to its remote is a public action — always ask the user with a concrete one-line offer naming the SHA, remote and branch before pushing. The local commit is safe to do without asking; only the push needs consent. Override with submoduleAutoPush: true in .docs-sync.json (CI only).
• No fabricated CLI commands, URLs, or version numbers. Editors and curator must ground every concrete claim in the original diff, the project's README/package.json, or the existing page. When in doubt, link the README instead of guessing the install command.

MCP Tools#

Acceptance Criteria#

• Stale docs-sync-* worktrees from previous runs removed silently before any work
• Pre-push hook offer shown only on first run; subsequent runs skip it
• Clean exit with no edits when no non-doc code files changed
• MCP probe runs before any subagent invocation; failure aborts with a message
• Submodule detection runs before worktree creation; submodule worktrees created inside the submodule, not the main repo
• Planner returns clusters; fallback to top-level dir grouping on failure
• All cluster worktrees created and searched in parallel
• Editor only invoked for clusters with confidence >= threshold (default 0.6)
• Curator resolves conflicts across clusters, drops speculative edits, AND drops fabricated CLI commands / URLs / versions not present in the diff or repo metadata
• Amend commits only when the curated edit list is non-empty
• Warn-mode never exits non-zero; block-mode exits non-zero on detected drift
• For submodule case: local commit happens without user prompt; public push gated by a concrete consent question naming SHA, remote and branch
• Worktrees removed unconditionally on success or no-op; preserved on awaiting_push_consent or hard failure with a log file
• Final stdout is a single structured JSON report with status, commits, pending pushes, and human-review flags