git-pr-ops-core

name	git-pr-ops-core
description	Shared reference for the git-pr-ops cluster: the gated review→prepare→merge pipeline, the `.local/` artifact handoff (review.json findings), head-SHA pinning, the push/merge safety rules (force-with-lease, no auto-merge, never push main), and the finding-severity contract. USE WHEN preparing or merging a GitHub PR, resolving review findings, or wiring the issue→PR flow — the interlocking rules every spoke shares.
cluster	git-pr-ops
version	1.0.0

git-pr-ops Core

Shared model for the git-pr-ops cluster. The review, prepare, and merge spokes all depend on these interlocking conventions — keep them consistent here so no spoke contradicts another.

1. The pipeline (this cluster's defining feature)

Work moves through three gated stages, each producing an artifact the next stage consumes. The stages are ordered and not optional: a later stage refuses to run without the prior artifact.

review-pr ──review.json──> prepare-pr ──prep.env──> merge-pr ──> MERGED
 (read-only)               (resolve + push)         (squash + pin)

• review-pr is read-only: it analyzes the diff against the merge-base and emits both a human report (.local/review.md, sections A–J) and machine-readable findings (.local/review.json). It never pushes, merges, or keeps code changes. → review-pr
• prepare-pr consumes review.json, resolves every required finding (see §3), runs the gates, and pushes the fixes to the PR head with --force-with-lease. It emits .local/prep.env (carrying PREP_HEAD_SHA) and ends by printing PR is ready for /merge-pr. → prepare-pr
• merge-pr consumes prep.env, verifies required checks, and performs a deterministic squash merge pinned to PREP_HEAD_SHA (--match-head-commit), with co-author trailers and post-merge verification. It ends in MERGED. → merge-pr

Rule: never skip a stage or hand-edit past the artifact gate. The artifacts in .local/ are the contract between stages — they live in the PR worktree (.worktrees/pr-<PR>) and must exist and be valid before the next stage runs.

2. The .local/ artifact set

Artifact	Produced by	Consumed by	Purpose
review.md	review-pr	human	readable review, sections A–J
review.json	review-pr	prepare-pr	structured findings + recommendation
prep.md	prepare-pr	human	resolved-findings + gate summary
prep.env	prepare-pr	merge-pr	PREP_HEAD_SHA + merge context
pr-meta.env / *-context.env	wrapper scripts	the stages	PR metadata, merge-base, mode

The wrapper scripts (scripts/pr-review, scripts/pr-prepare, scripts/pr-merge, scripts/pr) are cwd-agnostic — run them from the repo root or inside the PR worktree.

3. Finding-severity contract

review.json carries findings with a severity. The prepare stage's obligation is severity-driven:

• BLOCKER — must be resolved before prepare can push. Hard gate.
• IMPORTANT — must be resolved before prepare can push. Hard gate.
• NIT / MINOR — optional; resolve if cheap, otherwise note and move on.

Minimum review.json shape: a recommendation (e.g. READY FOR /prepare-pr), a findings[] array (id, severity, title, area, fix), a tests object (ran, gaps, result), a docs status, and changelog (changelog is mandatory in this workflow). Keep prepare's scope tight — resolve the findings, update the changelog/docs, nothing gratuitous.

4. Push & merge safety (default-deny)

The base branch is sacred; the PR head is the only writable target, and only carefully:

• Never git push directly, and never push to main/the base branch.
• Prepare pushes only to the PR head, only with --force-with-lease against the known head SHA (idempotent if local prep HEAD already equals the remote PR head; one automatic rebase + gate-rerun
  • lease-retry is allowed).
• Merge is head-SHA pinned (--match-head-commit) so a race can't merge unreviewed commits.
• Never gh pr merge --auto in this flow.
• Merge ends in MERGED, never CLOSED; cleanup (worktree/branch) happens only after a confirmed merge. Do not delete the worktree mid-pipeline.

5. The other two lanes

Two spokes feed or report on the pipeline rather than walking it:

• gh-issues — autonomous issue→PR engine. Fetches issues via the GitHub REST API (curl + a repo-scoped GH_TOKEN), spawns parallel sub-agents that each branch fix/issue-<N>, implement a minimal fix, test, open a PR, and (in a later phase) address review comments. Supports fork mode, --watch, and --cron. Each sub-agent uses a confidence gate (skip if < 7/10) and never force-pushes or touches the base branch. → gh-issues
• github-next-wave-orchestrator — read-only repo scan → a Status Report (repo pulse, issue landscape, PR/CI health, Green/Yellow/Red readiness) + a ranked Next Wave plan. Executes only on explicit approval; never fabricates state, never closes issues or merges PRs unprompted. → github-next-wave-orchestrator

Both ultimately feed the review→prepare→merge pipeline once a PR exists.

6. The gh CLI vs the REST API

• gh CLI (github spoke) is the default for interactive/ad-hoc work — issues, PRs, CI runs, gh api for anything the subcommands don't cover. Always pass --repo owner/repo when outside a git dir, or use URLs directly. → github
• curl + REST is used by gh-issues precisely because it runs in environments where gh may be absent; it carries GH_TOKEN as a Bearer token. The pipeline wrappers (review/prepare/merge) use gh under the hood for metadata and diffs.

7. Shared guardrails

• The pipeline is gated, not optional: review-pr → prepare-pr → merge-pr, each blocked on the prior .local/ artifact.
• Review is read-only; resolve all BLOCKER + IMPORTANT findings before pushing.
• Push only to the PR head, only with --force-with-lease; never push the base branch.
• Merge is head-SHA pinned, required-check gated, squash, and ends in MERGED. No --auto.
• Changelog is mandatory; state every required finding resolved and every gate result.
• Cleanup only after a confirmed merge; never delete a worktree mid-pipeline.
• Autonomous lanes (gh-issues, next-wave) never close issues, merge PRs, or fabricate state without explicit approval; sub-agents stop below their confidence threshold rather than guess.