Skip to content

docs(eng): document the merge-clearance escape hatches in the README #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mujtaba3B merged 1 commit into from
Jul 21, 2026
Merged

docs(eng): document the merge-clearance escape hatches in the README #60

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion eng/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The plugin ships its PR-lifecycle gates in `hooks/hooks.json`; installing the pl
| `pr-merge-gate.sh` | PreToolUse Bash | Blocks `gh pr merge` in an opted-in repo unless BOTH a valid HEAD-matched merge-clearance stamp AND a fresh, target-matched `/land-and-deploy` sentinel exist. The stamp can come from a bare `merge-clearance clear`; the sentinel can only come from actually invoking `/land-and-deploy`, so requiring both makes `/land-and-deploy` the single sanctioned CLI merge path (default-on fleet-wide). The local accident-guard half; the GitHub required check is the hard backstop. |
| `land-deploy-sentinel.sh` | PreToolUse Skill + UserPromptSubmit | Mints the `/land-and-deploy`-is-running sentinel the merge gate reads. Target-bound to repo + HEAD sha (+ PR number when resolvable), stored per-worktree in `<gitdir>/land-deploy-clearance`. Never blocks. |
| `review-skill-stamp.sh` | PostToolUse Bash | Records the reviewed HEAD when a review skill logs completion; a sub-signal merge-clearance reads. |
| `merge-clearance.sh` | (utility) | The pre-merge gauntlet: `check` renders the CodeRabbit + CI + review + QA checklist; `clear` writes the stamp and posts the `local-review/merge-clearance` GitHub status. Called by `/land-and-deploy`. External callers use the stable shim `~/.claude/scripts/merge-clearance.sh` (written by `bin/install`), which execs the newest installed plugin copy. |
| `merge-clearance.sh` | (utility) | The pre-merge gauntlet: `check` renders the CodeRabbit + CI + review + QA checklist; `clear` writes the stamp and posts the `local-review/merge-clearance` GitHub status. Called by `/land-and-deploy`. External callers use the stable shim `~/.claude/scripts/merge-clearance.sh` (written by `bin/install`), which execs the newest installed plugin copy. CI and CodeRabbit are hard; `--skip-review` / `--skip-qa` waive the two human-judgment dimensions. When CodeRabbit is RATE-LIMITED on a head (its commit status missing, stuck pending, or failed with a rate-limit description), a current `/eng:cr` review backstops it automatically. A GENUINE CodeRabbit failure takes the explicit `--override-cr-failure`, which also requires that current review, so the gate never loses both reviewers at once. Every waiver is recorded in the checklist, the `--json` verdict, the stamp evidence and the posted status description. |
| `apply-merge-clearance-protection.sh` | (utility) | Applies the GitHub branch ruleset (require CI + the clearance status check, `enforce_admins` on) that binds the web Merge button too. |

Pure decision logic lives in `merge-clearance-lib.sh` / `ship-pr-gate-lib.sh`, unit-tested by the bats suites in `hooks/tests/` (run them as individual files). The re-appliable gstack patch that wires `/land-and-deploy` into the gauntlet is `docs/land-and-deploy-merge-clearance.md`.
Expand Down
Loading