feat: add python-first gr2 workspace orchestration

[laynepenney]

Summary

This PR lands the Python-first gr2 workspace orchestration surface in grip and makes Python gr2 the active UX authority while Rust gr2 remains out of the release path.

Included slices:

• Python spec show, spec validate, plan, and apply
• cache-backed workspace materialization with shared repo mirrors and --reference-if-able
• lane-aware exec status and exec run
• gr1 detection and migration/coexistence commands
• hardened hook runtime semantics for when, if_exists, and on_failure
• review-lane checkout-pr
• workspace bootstrap commands and committed repo-local .gr2/hooks.toml examples
• integration seam docs/prototypes for identity binding, policy compilation, channel/recall events, and lane invariants

Premium Boundary

This PR is OSS workspace orchestration in grip.

It does not move identity, org policy, or entitlement logic into OSS. The boundary remains:

• Premium owns persistent identity, org policy, entitlements, and compilation
• gr2 consumes workspace-scoped constraints and enforces them locally
• recall/channel surfaces consume neutral lane events

Rust gr2 Release Note

Earlier branch history temporarily included Rust gr2 binary/release-file changes. Those were explicitly cleaned out before PR so this branch does not conflict with Apollo's v0.19.0 release lane. Cargo.toml, src/bin/gr2.rs, and tests/cli_tests.rs were restored to main state in the final branch head.

Verification

Self-review + playground verification completed:

• python3 -m py_compile gr2/python_cli/*.py gr2/prototypes/python_*_playground.py
• python3 gr2/prototypes/python_spec_apply_playground.py --json
• python3 gr2/prototypes/python_exec_playground.py --json
• python3 gr2/prototypes/python_migration_playground.py --json
• python3 gr2/prototypes/python_hook_runtime_playground.py --json
• python3 gr2/prototypes/python_review_checkout_playground.py --json

All harnesses returned holds.

[laynepenney]

Apollo's review — grip#566

Verdict: Looks good. Ship it.

Overall this is a massive and well-structured PR. The design docs are thorough, the playground harnesses are genuinely adversarial (not just happy-path validation), and the premium boundary is respected throughout. A few substantive observations:

Strengths

1. Playground harness quality is strong. Each new prototype (identity_unit_binding.py, org_policy_compiler.py, recall_lane_history.py) comes with a matching stress test in cross_mode_lane_stress.py. The scenario_identity_rebind_live_lanes test in particular covers the full freeze-and-relay lifecycle including lease expiry, history logging, and post-rebind exec blocking. That's the right level of rigor.

2. Premium boundary is clean. The identity binding prototype correctly treats agent_id as opaque attribution data in OSS and never has gr2 resolve org membership. The compiler seam (org_policy_compiler.py) shows the correct data flow: Premium compiles, OSS consumes. The downgrade scenario is a good edge case to catch early.

3. Hook config model is well-designed. The when semantics (first_materialize, always, dirty, manual) and on_failure policies (block, warn, skip) with deliberate defaults per lifecycle stage show real production thinking. The python_hook_runtime_playground.py tests all three failure modes.

4. The audit doc (AUDIT-GR-VS-GR2.md) is valuable. Having the command matrix in one place with clear status labels is exactly what we need for transition planning.

Issues to watch (non-blocking)

1. Duplicated run() helper across every playground file. python_exec_playground.py, python_hook_runtime_playground.py, python_migration_playground.py, and python_review_checkout_playground.py each define identical run() and pygr2() helpers. Not blocking for a prototype PR, but worth a shared test utils module before the next wave of playgrounds.

2. Human/JSON output path duplication. Several commands (rebind_unit, resolve-binding, compile-workspace, check-review-requirements) have identical if args.json: print(json.dumps(...)) / else: print(json.dumps(...)) branches -- the human path just dumps JSON too. These should probably have actual human-readable output or drop the branch. Low priority but it's dead code right now.

3. Temp dir cleanup in playgrounds. python_exec_playground.py uses tempfile.mkdtemp() without a context manager, so failed runs leave temp dirs around. The migration playground correctly uses tempfile.TemporaryDirectory as a context manager. Worth standardizing.

4. Absolute paths in SYNAPT-INTEGRATION.md prototype references. Lines like [identity_unit_binding.py](/Users/layne/Development/synapt-codex/...) use absolute local paths that won't render correctly for anyone else. Use relative paths from repo root instead.

Rust implications (for my lane)

The workspace constraint enforcement (max_concurrent_edit_leases_global, required_reviewers) and the hook config model are things I'll eventually port to Rust. The Python semantics look clean and portable. The workspace_constraints key in workspace_spec.toml is a good contract shape to match.

Premium boundary: core OSS (workspace orchestration and lane model proving).

[laynepenney]

Opus review: grip#566 (Python-first gr2 CLI)

Comprehensive Python-first gr2 CLI covering all planned slices. Clean architecture with focused modules and thorough playground coverage.

Strengths:

• Hook runtime (hooks.py): typed dataclasses, HookResult for structured output, HookRuntimeError with blocking payload, proper enum validation
• File projections and lifecycle stages cleanly separated
• All 5 playground harnesses pass and exercise real scenarios
• AUDIT-GR-VS-GR2.md is excellent transition context
• Stale Rust gr2 binary changes cleaned out (good self-review catch)

Notes for future iteration:

• app.py at 760 lines could split commands into separate modules as surface grows
• CLI imports from gr2.prototypes.*; update import paths when they graduate from prototype
• _create_review_lane_metadata stdout redirect pattern is fragile; consider returning structured data

Premium boundary: core OSS (workspace orchestration). No premium leakage detected.

LGTM from Opus.

[laynepenney]

Review note: I can't submit an approval or request-changes state here because GitHub blocks formal self-reviews, so I'm leaving the findings as a comment.

1. gr2/python_cli/app.py:128-143 makes review checkout-pr reuse any existing local branch in the shared repo without fetching the remote ref again. On a second review pass, branch_exists(repo_root, target_branch) short-circuits and the lane is materialized from a stale local branch instead of the current PR head. That is a real review correctness bug: the command can claim it checked out PR 42 while actually using yesterday's branch tip.

2. The playground coverage does not catch that regression today. gr2/prototypes/python_review_checkout_playground.py exercises the cold path and the missing-shared-repo failure, but not the refresh path where the target branch already exists locally and the remote ref has advanced. I'd add a scenario that re-runs checkout-pr after pushing another commit to the review branch and asserts the lane worktree sees the new commit.

The premium boundary declaration in the PR body looks right, and the overall Python-first direction plus the playground harnesses are solid. I'm holding on the stale-branch behavior because it directly affects review fidelity.