[Agentic DX] vcspull: low-to-high lift schema/versioning roadmap

[tony]

Context

Review focused on src/vcspull/cli/*, existing JSON/NDJSON outputs, and command metadata/docs.

Goal

Build on strong current CLI ergonomics with explicit schema/versioning and planning contracts.

Low-lift ideas

• Publish schema docs for JSON/NDJSON outputs and include schema version in payloads.
• Add vcspull schema helper to print or export current output/config schemas.
• Document command exit codes in one canonical table.

Medium-lift ideas

• Reduce parser/option duplication via shared argument builders where drift still exists.
• Add plan-only mode that emits per-repo action graph without side effects.
• Add contract tests for schema stability.

High-lift ideas

• Publish machine-readable capability metadata for provider/import backends.
• Add compatibility policy for output schema evolution.

Done when

• Consumers can rely on versioned structured output.
• Planned actions are inspectable before execution.
• Schema drift is caught by tests.