[Absorbed] Exact-base boundary migration #135

Summary

Publish a versioned migration for the exact-base worktree-create request grammar introduced by #126 / PR #131.

The response envelope remains structurally compatible, but adding required --start-point to the existing worktree create command breaks the published v1 request grammar for machine callers. The safe replacement must be explicit and versioned; compatibility must never mean restoring ambient-HEAD behavior.

Measured contract break

The published v1 boundary previously allowed:

wh --json worktree create --repo <path> <owner> <repo> <job_id> <branch>

PR #131 changes that same command to require:

--start-point <commit-or-ref>

A v1 caller using the published request shape now fails in Clap before dispatch, receives human-readable stderr rather than a v1 JSON error envelope, and cannot negotiate the safer contract. The current compatibility policy covers response-envelope fields but does not define request-grammar versioning.

Implementation contract

• Define what the boundary version covers: response envelope, command names, required/optional request fields, error/exit semantics, and Python client negotiation.
• Publish an explicit v2 request surface that requires an exact start-point input and returns the verified canonical start/HEAD identity.
• Provide a fail-closed v1 migration behavior that old machine callers can classify programmatically. It may return a structured upgrade-required error, but it must never create from ambient HEAD.
• Update the Rust CLI, Python bridge/client, documentation, fixtures, and compatibility tests together.
• Define the support/deprecation window and how mixed Python/Rust versions report incompatibility.
• Preserve additive v1 response fields where useful, but do not label a required request-grammar change as merely additive.
• Do not introduce an optional-start-point compatibility path that can mutate from controller checkout state.

Acceptance criteria

• The compatibility policy explicitly versions request grammar as well as response envelopes.
• A v2-capable Python client selects the exact-base contract intentionally and verifies the returned canonical commit identities.
• A legacy v1 create request never mutates from ambient HEAD and receives a deterministic, machine-classifiable migration failure.
• Mixed-version tests cover v1 client/v2 binary, v2 client/v1 binary, missing start point, invalid start point, and successful exact-base creation.
• Help text, docs/json-contract.md, examples, and fixtures identify the selected boundary version unambiguously.
• No v1 or v2 execution path reuses an unproven branch or infers a start commit from the controller checkout.
• Cargo fmt, Clippy with warnings denied, Rust tests, Ruff, mypy, and Python tests pass.

Scope boundaries

This issue versions and migrates the Python/Rust request contract. It does not weaken #126, restore the removed ambient-HEAD path, implement fork-object import, or define general branch resume.

Relationships

• Parent: Epic: Phase 1 — Claude Code hook-based enforcement on writ #124
• Introduced by / related implementation: [Safety] Exact-base worktree creation so every subagent shares a verified identity #126 / PR fix(worktree): enforce exact-base creation identity #131
• Related original JSON contract: H1: JSON contract between Python and Rust (versioned) #40
• Blocked by: none
• Blocks: none
• Open PR collision: PR fix(worktree): enforce exact-base creation identity #131 currently owns the worktree CLI, Python bridge consumers, and JSON-contract documentation; begin implementation after that branch no longer owns them.

No native dependency edge is intended; the issue records a separately reviewable boundary migration.

— Issue authored by Codex (OpenAI), 2026-08-30.