[Agentic DX] libvcs: low-to-high lift API decomposition and contract roadmap

[tony]

Context

Review focused on src/libvcs/, especially the very large src/libvcs/cmd/git.py, plus sync APIs and docs.

Goal

Improve maintainability and machine-facing contracts without losing libvcs flexibility.

Low-lift ideas

• Document stable imports in libvcs.__init__ and reinforce them with contract tests.
• Standardize a typed command result model (cmd, returncode, stdout, stderr, timing).
• Add an "agent quickstart" section for common sync/update flows.

Medium-lift ideas

• Decompose cmd/git.py into smaller modules by concern (clone/fetch/worktree/remote/etc).
• Centralize subprocess execution + tracing hooks.
• Add subsystem-specific tests to reduce regression blast radius.

High-lift ideas

• Publish a machine-readable capability matrix (git/hg/svn feature support).
• Add a planning mode that emits intended operations before execution.

Done when

• Core modules are easier to navigate.
• Output and behavior contracts are explicit.
• Tooling can reason about capabilities without reading internals.