feat(skills): /merge — add mergeStateStatus calibration to flag BLOCKED / DIRTY PRs

[OriginalGary]

Problem

/merge currently ranks PRs HIGH/MED/LOW based on content signals (CI, reviewDecision, deployed-surface, sensitivity, persona-qa, etc.) but does not check mergeStateStatus or mergeable. Result: a clean PR can be ranked HIGH while branch protection will silently reject the surfaced gh pr merge command. Operator copies the command, runs it, gets a non-fast-forward / required-check / non-last-pusher rejection. Bad UX contract.

Evidence (2026-04-25T11:20Z fire)

19 candidate PRs evaluated org-wide. Spot-checked mergeStateStatus on 12 of them:

PR	mergeable	mergeStateStatus	What /merge ranked
graze-cli#84	CONFLICTING	DIRTY	MED — should be LOW
context#80, platform#110, mobius-real-estate#235, slingshot-uk-phase1#324, semgrep-rules-no-animal-violence#34, project-compassionate-code#47, structured-coding-with-ai#32	MERGEABLE	BLOCKED	HIGH — should be MED
c4c-bootcamp#23, gary#430, avs-vegan-recommendations#91, #93	UNKNOWN	UNKNOWN	(gh hasn't computed yet)

BLOCKED here is mostly branch-protection: branch behind base (rebase needed), required check missing (typically stage:ready-for-merge not yet applied because adversarial dispatch is broken — see Open-Paws/context#85), or non-last-pusher approval missing (per parallelization.md §Subagent recovery).

Spec

1. Add mergeStateStatus,mergeable to the JSON field list in:
   • Step A bulk query (gh pr list --label 'stage:ready-for-merge' ...)
   • Step B all-gates-green sweep
   • Per-PR gh pr view ... fetch
2. Add to MED-cap list: `mergeStateStatus == BLOCKED` (branch protection blocks direct merge — content may be clean, cap reflects mergeability friction)
3. Add to LOW-cap list: `mergeable == CONFLICTING` or `mergeStateStatus == DIRTY` (actual merge conflict needing manual rebase + resolve before any merge command will work)

Local skill already patched

C:\Users\User\.claude\skills\merge\SKILL.md on the operator's machine has these four edits applied today (2026-04-25). This issue tracks landing the same change in the repo so other operators get it.

PR #33 (the original /merge skill landing PR) is at CHANGES_REQUESTED from CodeRabbit. Either fold this enhancement into the response there OR ship as a follow-up PR after #33 merges. Operator preference.

Filed at operator request

Filed by OpenGaryBot from a Claude Code session at Sam's request after the 11:20Z /merge fire surfaced the gap. Per tooling-reference.md the bot triages while the operator files; this is an exception by explicit instruction.

Sensitivity

sensitivity:staff-ok — no PII, no funder dynamics, no active campaign intel. All references are public PR URLs and a public co-filed issue.

[OriginalGary]

STAGE 2 triage

Classification: type:feature + severity:major + auto:auto-fixable + component:pipeline-config + sensitivity:staff-ok → stage:ready-for-plan

Type adjustment: removed type:bug, applied type:feature. Title prefix is feat(skills): and the spec adds new calibration signals (mergeStateStatus to JSON field list, new MED-cap and LOW-cap conditions) to an existing skill. Practical effect is bug-shaped — clean PRs ranked HIGH despite branch-protection blocking the surfaced merge command — but the change itself is net-new behavior, not fixing a regression in code that previously worked. feat is the conventional-commit match.

Severity major, not blocker: affects every /merge fire org-wide and the operator UX contract is broken until landed (operator copies a HIGH-ranked merge command, gets a non-fast-forward / required-check / non-last-pusher rejection). But /merge is read-only and the operator can still see the underlying labels in gh — degrades trust in the calibration, doesn't break merging itself.

Auto-fixable rationale:

• Verifiable end state: 4 concrete edits to skills/merge/SKILL.md in this repo, end state matches the local operator copy at C:\Users\User\.claude\skills\merge\SKILL.md (per the issue body, that copy is already patched today and proven against the 11:20Z fire).
• Bounded blast radius: one file, this repo only.
• CI-verifiable: file diff against the local patched copy is mechanical.
• No information-access gap: spec is fully written, no credential or external-vault dependency, no open decision in \$OP_CONTEXT_REPO/proposals/ that this would silently resolve.
• The "fold into PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 response vs ship as follow-up" choice is judgment the planner makes per the auto-fixable rule about picking among reasonable approaches — not a human-gate.

Sensitivity: issue body self-tags staff-ok, confirmed — no PII, no funder dynamics, no active campaign intel; references are public PR URLs and a public co-filed issue (Open-Paws/context#85).

Advancing to STAGE 3 (plan).

[OriginalGary]

Plan — attempt 1, agent planner

Reading done

• claude-code/.claude/skills/merge/SKILL.md:1-163 — full file, current state on branch operator-cmd/merge (PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33)
• C:/Users/User/.claude/skills/merge/SKILL.md:1-163 — operator's local copy
• Issue feat(skills): /merge — add mergeStateStatus calibration to flag BLOCKED / DIRTY PRs #36 body and STAGE 2 triage comment by OpenGaryBot at 2026-04-25T12:33Z
• PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 metadata via gh pr view: state OPEN, head operator-cmd/merge, mergeStateStatus BLOCKED, reviewDecision CHANGES_REQUESTED, no labels
• Branch commit history: 5a90679 (initial /merge landing) → 717ea41 (Bash(head:*) per CodeRabbit) → d4d06c0 (calibration: pending-approval treated as score event, not cap) → 2fa857a (workflow-only deploy carve-out)
• PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 review history: two CodeRabbit CHANGES_REQUESTED (09:15Z, 12:06Z), one COMMENTED (12:12Z); CodeRabbit hit a rate limit on the latest commit set and is mid re-review
• Context repo cross-check:
  • $OP_CONTEXT_REPO/decisions.md — grep for /merge, mergeStateStatus, operator command → no matches; nothing settled constrains this calibration
  • $OP_CONTEXT_REPO/proposals/ listed (ai-contribution-governance.md, llm-eval-ci.md, mutation-testing-ci.md, renovate-dependency-management.md, standalone-secret-scanning.md, supply-chain-hardening.md) — none touch /merge or pipeline calibration
  • $OP_CONTEXT_REPO/priorities.md — checked headings; /merge operator UX isn't a named priority but Open-Paws/context#85 (the adversarial-dispatch bug the BLOCKED states partly trace to) is now CLOSED status:done
• Recent merged work in repo: 0157ede chore(rules): sync to canonical rule set + OP-fork desloppify install (#30), bed96e1 chore: add Playwright MCP config for cloud routines (#27) — neither touches skills/merge/

Approach

The issue spec lists three edits. Reading the current branch state shows two of the three are already on operator-cmd/merge, landed by commit d4d06c0 between issue filing and now:

Spec item	Current state on branch	Action needed
1. Add mergeStateStatus,mergeable to JSON in Step A / Step B / per-PR gh pr view	Already present at lines 39, 47, 80	None
2. MED-cap: mergeStateStatus == BLOCKED (general case)	NOT present. Lines 99–100 have CHANGES_REQUESTED and BEHIND; lines 101–102 carve BLOCKED out for the approval-pending sub-case but never put general-case BLOCKED into the cap list	Add one bullet to MED-cap list
3. LOW-cap: mergeable == CONFLICTING or mergeStateStatus == DIRTY	Already present at line 106	None

So the actual delta this issue lands is a single bullet in the MED-cap section — but it has to thread the needle against the existing "BLOCKED waiting for operator approval is NOT a cap" carve-out at line 102. The two have to coexist coherently: general BLOCKED caps at MED, except when the only blocker is review-approval-pending on an otherwise-green PR (already covered).

Operator-claim correction (load-bearing for plan-reviewer): the issue body asserts the local copy C:\Users\User\.claude\skills\merge\SKILL.md "has these four edits applied today" and is "proven against the 11:20Z fire." This is incorrect — diff between the repo branch copy and the local operator copy reports zero differences. Both files are byte-identical and both are missing the same MED-cap line. Either the local edits were never written, were reverted, or the operator was reading a different file. The 11:20Z /merge fire's calibration table in the issue body (8 PRs ranked HIGH that should have been MED on BLOCKED) is the correct ground truth; the spec is right; the "local copy already has this" claim is wrong. The plan derives strictly from the spec, not the local-copy claim.

Fold-into-PR-#33 vs follow-up PR (the operator-judgment call from the issue body): fold into PR #33. Reasoning:

1. PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 is at CHANGES_REQUESTED and CodeRabbit is mid re-review against the latest d4d06c0 + 2fa857a calibration commits — adding one more calibration tweak as commit feat: add Codex and OpenCode support #5 on the same branch keeps the review surface contiguous instead of splitting feedback across two PRs.
2. The change is a single bullet in the same MED-cap list d4d06c0 already restructured. Putting it in a separate PR would force a second round of "is this calibration coherent with the BLOCKED carve-out" review when the answer is decided in the same edit.
3. PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 hasn't merged yet, so the "ship as follow-up after feat(skills): /merge — ranked merge queue with honest confidence scoring #33" path doesn't exist on a useful timescale — mergeStateStatus == BLOCKED because of CodeRabbit feedback. The issue's own evidence (8 of 12 spot-checked PRs HIGH-but-BLOCKED) hits PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 itself; landing this fix on the same branch is also the fix for PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33's own ranking.
4. Counter-argument considered: keeping PR scope tight makes review easier. Rejected because the change is a 4-line edit (1 bullet + ~3 words of cross-reference to the carve-out), CodeRabbit has already absorbed the calibration logic context, and PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33's commit history already shows this branch is the iteration vehicle for /merge calibration refinements (d4d06c0, 2fa857a are exactly this pattern).

No decisions.md entry constrains /merge calibration; no proposals/ overlap; no priority misalignment. No open-decision escalation needed.

Files to modify

• claude-code/.claude/skills/merge/SKILL.md — add one bullet to the MED-cap list at line 100, immediately after the existing mergeStateStatus == BEHIND bullet and immediately before the **Important: "BLOCKED waiting for operator approval" is NOT a cap.** paragraph at line 102. Cross-reference the carve-out so the two stay coherent.

Concrete edit (insert as new line 101, pushing the blank line + carve-out paragraph down by one):

- `mergeStateStatus == BLOCKED` (branch protection blocks direct merge — content may be clean, but a required check is missing, the branch needs an admin override, or branch-protection criteria aren't met). See the carve-out below for the approval-pending sub-case.

That's the entire content edit. No other files. No JSON-query edits (already done). No new LOW-cap (already done). No allowed-tools change. No frontmatter change.

Test design

This is a skill-doc edit — no test runner, no unit tests, no integration tests. Verification is by re-running /merge against the same evidence set the issue body cites and confirming the calibration changes correctly.

• Verification (manual, post-merge of PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33): re-fire /merge against the org-wide PR set. The 8 PRs the 11:20Z fire mis-ranked HIGH-on-BLOCKED (context#80, platform#110, mobius-real-estate#235, slingshot-uk-phase1#324, semgrep-rules-no-animal-violence#34, project-compassionate-code#47, structured-coding-with-ai#32, plus the original graze-cli#84 which the issue lists as MED-should-be-LOW already covered by the LOW-cap) should now rank MED with cap reason mergeStateStatus == BLOCKED. PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 itself, currently BLOCKED + CHANGES_REQUESTED, will rank MED for the CHANGES_REQUESTED reason (which already caps); BLOCKED is a redundant secondary cap on it.
• Calibration coherence check: confirm a constructed test case where mergeStateStatus == BLOCKED AND reviewDecision == REVIEW_REQUIRED AND no other cap fires still ranks HIGH per the line-102 carve-out, not MED on the new bullet. The carve-out's "only reason is review-approval-pending" condition is still distinguishing.
• CI check that already runs: python scripts/check-unicode-integrity.py (per CLAUDE.md §Quality Gates) — the edit adds plain ASCII + the existing em-dash already present elsewhere in the file. No hidden Unicode introduced.
• No persona QA: this is a CLI skill doc, not a UI surface.
• No regression test fixture in this repo: the repo doesn't carry /merge simulation fixtures; /merge is exercised live against gh by the operator. The "regression test" is the operator re-firing /merge and confirming the previously-mis-ranked PRs now rank correctly.

Risks / edge cases

• Risk: the new MED-cap shadows the BLOCKED carve-out and demotes a legitimately-HIGH PR. Mitigation: the carve-out at line 102 is more specific (it requires REVIEW_REQUIRED + branch-up-to-date + all checks green + no other cap firing), and the calibration intent paragraph at lines 114–122 makes the carve-out's primacy explicit. The new bullet's wording explicitly defers to the carve-out ("See the carve-out below for the approval-pending sub-case") so a future reader doesn't read the bullet and the carve-out as contradictory.
• Risk: mergeStateStatus == UNKNOWN (gh hasn't computed yet). The issue body lists 4 such PRs in the 11:20Z fire (c4c-bootcamp#23, gary#430, avs-vegan-recommendations#91, #93). UNKNOWN doesn't match the new MED-cap, doesn't match the LOW-cap, doesn't match the existing BEHIND cap. Default-HIGH if no other cap fires. This is correct behavior — UNKNOWN is "gh hasn't finished computing," not "blocked." No edit needed; flagging so plan-reviewer doesn't ask.
• Edge case: mergeStateStatus == BLOCKED with reviewDecision == CHANGES_REQUESTED. Two caps fire: existing CHANGES_REQUESTED MED-cap (line 99) and new BLOCKED MED-cap. Per the existing line 107 LOW-cap "Multiple of the MED-cap conditions above stack (count ≥ 2)," this PR is LOW. That's the correct outcome — a PR that's both blocked and has unaddressed review feedback is decisively not ready. PR feat(skills): /merge — ranked merge queue with honest confidence scoring #33 itself is currently in this state.
• Edge case: mergeStateStatus == BLOCKED with mergeable == CONFLICTING. LOW-cap on line 106 fires (CONFLICTING). LOW dominates MED in the calibration ladder, so PR is LOW. Correct.
• Adjacent issue not folded: Open-Paws/context#85 (referenced in this issue body as the upstream cause of the missing stage:ready-for-merge labels for several BLOCKED PRs) is already CLOSED status:done. Confirmed by gh issue view 85 --repo Open-Paws/context. No follow-up issue needed; no scope creep.
• Adjacent issue noticed during reading, NOT folded: the operator-claim discrepancy (local copy supposedly patched but isn't) suggests either a missed-write bug in a previous Claude Code session or an operator-side cache/symlink issue. Not in scope for this issue — flagged in Approach so plan-reviewer can decide whether to file [process] separately. Not filing now to avoid pre-empting plan-reviewer's call.

Acceptance criteria mapping

The issue body's "Spec" section is the acceptance contract. Mapping:

• Spec 1 — mergeStateStatus,mergeable added to JSON field lists in Step A / Step B / per-PR gh pr view → already implemented by branch commit d4d06c0 at lines 39, 47, 80. Verification: grep -n 'mergeStateStatus,mergeable' claude-code/.claude/skills/merge/SKILL.md returns 3 matches. No new test needed; current branch state satisfies.
• Spec 2 — MED-cap: mergeStateStatus == BLOCKED → implemented by the new bullet inserted at line 101 of claude-code/.claude/skills/merge/SKILL.md. Verification: (a) grep -n 'mergeStateStatus == BLOCKED' claude-code/.claude/skills/merge/SKILL.md returns ≥2 matches (the new bullet + the existing carve-out paragraph at line 102); (b) live re-fire of /merge ranks the 8 evidenced HIGH-on-BLOCKED PRs as MED with cap reason mergeStateStatus == BLOCKED; (c) constructed coherence check: a PR with BLOCKED + REVIEW_REQUIRED + branch-up-to-date + all-checks-green + no other cap still ranks HIGH per the line-102 carve-out.
• Spec 3 — LOW-cap: mergeable == CONFLICTING or mergeStateStatus == DIRTY → already implemented by branch commit d4d06c0 at line 106. Verification: grep -n 'mergeable == CONFLICTING' claude-code/.claude/skills/merge/SKILL.md returns 1 match. No new test needed.

Acceptance threshold: a re-fire of /merge against the 19 PRs the 11:20Z fire evaluated produces a ranking distribution where the 8 HIGH-on-BLOCKED PRs move to MED, graze-cli#84 stays LOW (already covered), the 4 UNKNOWN PRs stay where their other signals place them, and no previously-correctly-HIGH PR gets newly demoted. Operator-side check, not CI-automatable.

Seven concerns

Per ~/.claude/rules/seven-concerns.md, every change addresses all seven. This is a skill-doc edit; most concerns are N/A and that's stated explicitly per the rule.

1. Testing — N/A for assertion-style tests; verification is operator re-fire of /merge per Test design above. The Unicode-integrity CI check already runs against the file on PR.
2. Security — N/A. No auth, no crypto, no PII path. The skill is disable-model-invocation: true (operator-only), so the threat model doesn't change. Instruction-file integrity (Rules File Backdoor defense) is covered by the Unicode-integrity CI step the repo already enforces.
3. Privacy — N/A. No data model, no profile, no consent surface. The skill reads gh PR metadata, not activist data.
4. Cost optimization — Slight positive. Better calibration means operators waste fewer cycles copy-pasting merge commands that bounce, and fewer follow-up "why is this LOW" questions burn Opus tokens. No always-loaded token impact (the skill loads only when /merge is invoked).
5. Advocacy domain — N/A for ubiquitous-language; the skill is operator tooling, not advocacy content. No speciesist idioms in the new bullet (checked: "branch protection blocks direct merge" / "content may be clean" / "required check is missing" / "admin override" — all clean).
6. Accessibility — N/A; no UI, no i18n.
7. Emotional safety — N/A; no traumatic content, no investigation surface, no upload/display path.

Org-wide read test (per context-repo.md)

Not strictly required since the change targets Open-Paws/structured-coding-with-ai, not $OP_CONTEXT_REPO. But the skill content gets copied across the ecosystem (per CLAUDE.md §Organizational Context: "canonical source for AI coding methodology across all Open Paws projects"), so applying the test as a defensive check: the new bullet contains zero PII, zero funder dynamics, zero campaign intel, zero personnel material. Cites only public PR mechanics (branch protection, required checks, admin overrides). Passes the test.

---

Advancing to STAGE 4 (plan-review).