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

[mujtaba3B]

Summary

Post-ship docs sync for eng 2.8.0 (#59), caught by /document-release during close-out.

eng/README.md's hook table describes merge-clearance.sh as "check renders the checklist; clear writes the stamp and posts the status" and stops there. It never mentioned that dimensions can be waived at all. That gap is older than #59 (the CodeRabbit rate-limit backstop landed in eng 2.3.0 and was never documented), but #59 made it matter: it added an operator-facing flag, --override-cr-failure, that appeared in no tracked doc. The only place it existed was the script's own usage output.

The row now states the full contract:

• CI and CodeRabbit are hard; --skip-review / --skip-qa waive the two human-judgment dimensions.
• A rate-limited CodeRabbit (status missing, stuck pending, or failed with a rate-limit description) auto-satisfies when a current /eng:cr review backstops the head.
• A genuine CodeRabbit failure needs 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.

QA

Docs-only: one line, one tracked file, no scripts touched and no behavior change. The bookkeeping fast lane applies (it auto-waives the /eng:cr stamp and the QA checklist for a docs-only diff while keeping CI and CodeRabbit hard), which is also why this PR opened without its own /qa:plan.

Verified by reading the shipped merge-clearance.sh usage block and blocker logic at 9a1e724 to confirm every claim in the new text matches the code as merged.

Summary by CodeRabbit

• Documentation
  • Expanded guidance for the merge-clearance utility, including review and QA waivers, rate-limit handling, override requirements, and checklist/status recording.
  • Clarified how external callers should use the stable integration point.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 97457457-c0e5-4695-9062-58f66cc89930

📥 Commits

Reviewing files that changed from the base of the PR and between 9a1e724 and 57b28a4.

📒 Files selected for processing (1)

• eng/README.md

---

📝 Walkthrough

Walkthrough

Expanded eng/README.md to document merge-clearance.sh behavior, including review and QA waivers, CodeRabbit rate-limit recovery, override requirements, and recorded gate output.

Changes

Merge clearance documentation

Layer / File(s)	Summary
Document merge-clearance behavior eng/README.md	Documents check and clear responsibilities, stable shim usage, waiver flags, CodeRabbit backstop handling, override conditions, and checklist, verdict, stamp, and status output.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• mujtaba3B/gstack-extensions#44: Documents behavior tied to merge-clearance CodeRabbit rate-limit handling and failure overrides.

Poem

A clearance gate now speaks more clear,
With waiver flags and stamps held dear.
Rate limits find a backstop bright,
Current reviews keep overrides right.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the README documentation update about merge-clearance escape hatches.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}