[Deep-Sixed]

3 of 4 restoring ideas from the retired Codex_Kernel repo. This PR is stacked on #21, which is stacked on #20. Merge in order.

Problem

To get approval for a protected push today, you push, read the hash from the rejection, then hand-write the operation JSON (type, refname, oldrev, newrev and, since #20, out_of_scope_paths). That's error-prone, and a single wrong field means the approval never matches.

Codex_Kernel had proposal_producer.py, which built the exact payload from the candidate commit before pushing, using the same code path as the gate. This PR brings that back.

Change

• gate.governed_operation() is split out of check_ref_update. It applies the branch reservations (handoff freeze, claim owner) and returns the approval-gated operation, or None. The hook and the new derivation both call it, so their results can't drift apart. Hook behaviour is unchanged, and all existing tests pass untouched.
• gate.derive_push_operation():
  • Reads the old revision from the hub's current ref and resolves --rev (default HEAD) in the pusher's clone.
  • Runs governed_operation against the hub with the clone's object store attached as a read-only alternate (GIT_ALTERNATE_OBJECT_DIRECTORIES). That mirrors how Git shows quarantined incoming objects to a real pre-receive hook, so nothing is fetched or written.
  • Supports --delete.
• CLI: quorumgit approve request --repo R --push REF (--from CLONE [--rev C] | --delete) [--pusher AGENT].
  • It prints the derived operation and opens the approval. If the push is ungoverned, it says so and requests nothing.
  • The positional JSON form still works. Passing both forms, or neither, is a usage error (exit 2).
• Hook rejections now end with the exact approve request --push … command to run.
• README: updated the approval walkthrough and command reference, and documented the derivation.

Tests

tests/test_push_request.py adds 8 tests. For each of these cases, the derived operation's hash equals the one the hook prints on rejection, and the push lands once that approval is granted:

• a protected push (also asserts the new commit never reaches the hub during derivation);
• an out-of-scope push;
• a force push, then a deletion;
• the full CLI flow.

It also covers: an ungoverned push derives None; branch reservations are enforced during derivation; bad inputs (nothing to push, unknown rev, nothing to delete); and usage errors.

Local results: pytest 154 passed, ruff clean, pyright 0 errors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mc44WsAZx9hzZdWEihDk5a

---

Generated by Claude Code

[Deep-Sixed]

Heads-up: the stack under this PR changed.

• Enforce claim scopes at push time #20 was closed in favour of Bind push authorization to Git's ref transaction; scope enforcement and full schema contract #10.
• Add a 2/3+1 quorum mode to repository approval policy #21 was rebuilt directly on main as a quorum mode for Move approval authority to the repository and continue retained worktrees #12's approval policy.

Until this PR is rebased, its diff against the old base branch shows unrelated changes. Because #10 rewrites the gate code this PR refactors (governed_operation), I'll rebase this PR and #25 onto main once #10 merges, rather than twice. The derivation will then be ported onto #10's reference-transaction flow, and the migration renumbered.

---

Generated by Claude Code

[Deep-Sixed]

Closing as superseded by #23, now on main. Its quorumgit approve prepare --repo R --ref X [--new rev | --delete] [-C clone] [--request] [--json] does the same thing as this PR: it reads objects from the pusher's clone and runs the hook's own derivation, printing the exact operations and hashes a push will need. It also has plan-only and JSON output.

---

Generated by Claude Code