Make PRs the convention (stacked via gh stack or Graphite when helpful)

[yulonglin]

Flips the repo's git convention from "direct pushes to main, PRs only for large merges" to PRs by default:

• Reviewable changes go through a PR; direct pushes to main are reserved for trivial/mechanical changes (typo, version bump, doc touch-up).
• Large changes that review better as a chain use stacked PRs — gh stack (the official github/gh-stack extension, suggested by gh core since v2.90.0; installed gh here is 2.45.0, so one-time gh extension install github/gh-stack) or Graphite.

Files changed:

• CLAUDE.md — Top Rules bullet flipped; Worktrees section notes that cwmerge/cwrm integrate locally without review, so that path is for trivial changes and reviewable work pushes the branch + opens a PR.
• claude/rules/refusal-alternatives.md — the "action over ceremony" section previously told agents not to propose PRs on personal repos; PRs are now carved out as the exception.
• claude/hooks/approval_classifier_rules.md — direct pushes to the resolved destination remote's default branch (<remote>/HEAD, not hard-coded origin/main/master) are auto-allowed only for trivial/mechanical changes; substantive ones classify as unsure (manual confirm), and the broader working-branch allow rule can no longer cover a session that started on the default branch. This changes live permission behavior on merge (the file is symlinked into ~/.claude/).
• claude/hooks/approval_classifier.py — for push commands the hook now injects a deterministic "Git context" block (current branch, destination remote's default branch, push destination, commits being pushed, diffstat) into the classifier prompt; previously a bare git push reached the model with no branch or diff at all, making the rules above unenforceable. The block resolves the actual destination ref (git push origin main / origin HEAD:main from a feature branch still updates main), follows -C to describe the repo the push targets, reports that repo's credential-redacted push URL (what the personal-repo trust rule keys on — the push URL, not the fetch URL, since pushurl can differ, with userinfo stripped so embedded HTTPS tokens never reach the classifier backends), reads the default branch from the live destination push endpoint without executing Git transport (local remotes are read as HEAD data; GitHub remotes use fixed api.github.com metadata; unsupported/failed lookups become unknown rather than trusting stale refs/remotes/<remote>/HEAD), routes bare pushes through git's documented resolution (branch.<name>.pushRemote → remote.pushDefault → branch.<name>.remote → origin; push.default picks the ref, including tracked-name resolution for upstream), and surfaces force/delete markers including +refspec. The compound-safe fast path's git denylist patterns tolerate global options (git -C x push can no longer be auto-allowed as a safe compound). Anything the parser can't fully model fails closed: multi-ref modes and their Git-accepted abbreviations (--all/--mirror/--tags/configured push refspecs/push.default=matching) report an unknown destination, while directory/repo/config/shell-state redirection (cd x && git push, a prior state-changing statement, env/wrapper prefixes, shell-expanded arguments, --git-dir, GIT_DIR=, -c/--config-env) emits no block at all — both map to unsure, the manual prompt. Bundled short flags (-fq/-dq), abbreviated force/delete options and +refspec retain their destructive markers. The rendered block is built once and reused identically by both classifier backends, so API fallback does not rerun Git probes after its timeout budget is computed. Covered by tests/test_approval_classifier_git_context.py (real temp repos, 39 tests; 65/65 with the other suites).
• claude/skills/commit-push-sync/SKILL.md — PR-convention gate runs before Step 2 commits (topic branch first, so the default branch never advances; asks before switching shared HEAD in the root checkout), with a re-check at Step 4; PR creation has three mutually exclusive paths: gh stack submit for a tracked stack, push/update an existing PR while preserving its base, or create a new unstacked PR with explicit --base/--title/--body-file; ambiguous parentage asks rather than substituting the repository default or whatever the main checkout currently has checked out.
• claude/skills/merge-worktree/SKILL.md, claude/skills/finishing-a-development-branch/SKILL.md — direct local merge reframed as the trivial-change path; reviewable changes default to push + PR, with the actual PR base established independently from the main worktree's current branch (the finishing skill recommends its existing option 2).
• scripts/shared/helpers.sh — install_gh_cli now provisions the gh-stack extension on both exit paths: idempotent (skips when listed), defers with a warning when gh isn't authenticated yet (matching the installer's deferred-auth philosophy).

Eight rounds of Codex review plus one required focused code-review pass drove the scope, each converging on narrower issues: round 1 flagged workflows bypassing the convention, the classifier auto-allowing main pushes, and gh stack not provisioned; round 2 caught the working-branch allow-rule loophole and /commit-push-sync's missing PR path; round 3 caught hard-coded branch names, the gate firing after the commit already landed on main, and the two merge skills; round 4 caught that the classifier had no git state to classify pushes with (fixed with the injected Git context block above), plus three skill-workflow gaps (stale sync classification after the topic-branch switch, the dirty-main-tree check blocking the PR path in /merge-worktree, and gh pr create without --title hanging non-interactive runs); round 5 caught two bypasses of the new gate — option-prefixed pushes (git -C x push) skipping classification via the fast path, and the context block naming HEAD instead of the push destination; round 6 caught five more push forms whose context would have been authoritative but wrong (--all/--mirror, +refspec force marker, cd/--git-dir redirection, --repo remote selection, -C cross-repo trust); round 7 caught the config layer (-c command-line overrides, push.default=matching, pushRemote/pushDefault routing, per-remote default branches, pushurl vs fetch URL) plus one real security issue — remote URLs with embedded HTTPS credentials would have been sent to the classifier backends, now redacted — and gh pr create missing --base in the merge-worktree skill's stacked case; round 8 caught prior shell-state mutation, push.default=upstream with a differently named tracked branch, bundled destructive flags, duplicate Git probes consuming the fallback timeout, a missing value-option operand, and both skills still lacking a reliable stacked base. The focused pass then caught the final sibling cases: branch.<name>.remote precedence, shell-expanded destination tokens, abbreviated multi-ref flags, a test that did not exercise the actual fallback call site, and existing-PR/stack paths that were not mutually exclusive with gh pr create. The final convergence review then closed the last general classes: shell chains bypassing specific fast allows, abbreviated value-option operands, remote.<name>.mirror, stale local default-branch symrefs, slash-containing remote names, namespace/bare redirection, and aggregate probe timing. A final focused security pass rejected git ls-remote for the live-default check because repository-controlled SSH/credential/remote-helper configuration could execute before approval; the shipped resolver performs no Git transport and fails closed outside local-data/GitHub-API endpoints. The parser now fails closed whenever it cannot prove a single static destination rather than trying to model arbitrary shell and Git programs. One implementation note: @{push} looked like the clean way to resolve bare-push destinations but was measured (git 2.43) to resolve to a single ref under push.default=matching (where the push updates many branches) and to error on triangular remote.pushDefault setups (where the destination is well-defined) — so the hook mirrors Git's documented resolution order explicitly instead. One known follow-up, deliberately out of scope:

• cwmerge/cwrm (shell functions in config/aliases/claude.sh) still integrate locally without review — they could grow a guard or --pr path rather than relying on the doc note.

Testing & risk

• Commands run: rg sweeps for stale statements of the old convention (none remain outside the changed files); uv run --with pytest python -m pytest tests/test_approval_classifier_git_context.py tests/test_approval_classifier_thinking.py tests/test_validate_claude_settings.py — 65/65 passing; python3 -m py_compile claude/hooks/approval_classifier.py; git diff --check; bash -n scripts/shared/helpers.sh + shellcheck clean. Host: Ubuntu (Linux 6.8).
• Risk: low for docs; the classifier rule change adds friction (manual confirm) to substantive direct-to-main pushes on personal repos — that is the intended behavior flip, but it takes effect globally on merge via the ~/.claude symlink. The classifier code change only fires on Bash commands matching git … push; local read-only Git probes share a 3s aggregate budget, strip execution-routing environment variables, and disable external diff/textconv, while default-branch freshness uses only local HEAD data or a bounded fixed-host api.github.com metadata read — never Git transport. Every unsupported or failed resolution degrades to an absent/"unknown" block, which the rules map to unsure — i.e. a manual prompt, never a silent auto-allow.

This PR is itself the first exercise of the convention. It's independent of #66 (no code dependency), so no stack needed.

https://claude.ai/code/session_01Mm1WU9eHyEYQWVUPtq46Um