merge-guard: raise Layer-1 retirement granularity to op+target+flags (v4.4.55)

[michael-wojcik]

Summary

Raises merge-guard Layer-1 token retirement granularity from op+target to op+target+bound_flags (#1100), curing a bounded re-approval friction: a successful bare same-op/same-target command (e.g. gh pr close 5) no longer retires an operator's approved escalated flag-carrying token (e.g. {close, 5, [--delete-branch]}). Follow-on to #1097 (target-aware retirement).

What changed

Confined to _retire_token_for_command in pact-plugin/hooks/merge_guard_post.py — a PostToolUse observer (fires after a successful execution; never gates a command). Two independent, both-safe moves compose:

• The flag-inequality skip is purely subtractive (if set(ctx.bound_flags) != cmd_flags: continue) — fewer tokens on the flag axis; byte-mirrors the read arm's existing security: --admin and other privileged flags ride past merge-guard auth binding #1042 set-equality (merge_guard_pre.py:559).
• The cmd_target derivation switches to leg-isolated extract_command_context (mirroring the read arm at merge_guard_pre.py:536-540), so target + flags are derived from one SSOT call — mint, read, and retirement agree on (op, target, bound_flags) identity by construction.

Reuse-only: the mint already stores bound_flags (SSOT merge_guard_common.py:1400); the read arm already set-compares it. No mint / read / shared-extractor edits.

Safety — dual-independent certification

Certified SAFE-TO-MERGE by two independent adversarial streams — a pact-security-engineer review (8-item verification table) and a 3-lens adversarial break-sweep — which converged on the same conclusion and the same single (now-fixed) doc-precision nit:

• No laundering. The authorization arm (_token_matches_command / check_merge_authorization) is untouched; it binds (op, target, bound_flags) exactly and consumes on match. Any surviving under-retired token can replay only as its identical approved command — MAX_USES(2) + TTL(300s) bounded — never a different destructive command.
• Over-block structurally impossible. The observer discards its return value and sys.exit(0); it never emits a permissionDecision. The cardinal-sin direction is out of reach by construction.
• Self-consume preserved (including the flagless [] == [] case); extraction-symmetric (derives flags via the extract_privileged_flags SSOT, never _normalized_flags); target-less narrowing is inert (a target-less token fails the read arm's positive per-op-class target match → authorizes nothing, and no production mint ever creates one).

This aligns with the merge-guard design principle: a faithful single-command click always mints and merges; over-block is wrong by definition. Retirement is an observer that only ever removes tokens — it never grants authorization — so this change is laundering-safe by construction.

Tests

New TestFlagAwareRetirement: matching-flag self-consume (incl. flagless), friction-cured survival (both directions), flag-normalization equivalence (-d==--delete-branch, --repo=/-R/--repo , reorder, dup, value-mismatch), a seam-independent black-box flip + an SSOT-neuter non-vacuity proof, and a both-modes session matrix. Plus a post→pre seam integration test, and an intent-preserving fix to the pre-existing #1097 target-axis non-vacuity probe (token made flagless so it isolates the target predicate under the new flag axis; target non-vacuity still proven).

Full suite: 10620 passed, 11 skipped, 0 failed, 0 errors.

Version

PATCH bump 4.4.54 → 4.4.55 — a bounded friction refinement; no user-visible behavioral surface change.

---

Completes ACs of #1100; closure pending post-install live-probe.

[Copilot]

Pull request overview

This PR refines merge-guard’s Layer-1 retirement behavior so that a successful command only retires an authorization token when (op_type, target, bound_flags, session) match—preventing a bare same-op/same-target command from burning a previously approved flag-escalated token for that same target.

Changes:

• Updated merge_guard_post._retire_token_for_command to derive command context via leg-isolated extract_command_context and to require set-equality on bound_flags before retiring a token.
• Added/expanded tests validating self-consume retirement, survival on flag mismatch, normalization equivalence, and an end-to-end post→pre seam scenario.
• Bumped documented/plugin version strings from 4.4.54 → 4.4.55.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pact-plugin/hooks/merge_guard_post.py	Tightens token retirement matching to include privileged-flag identity and uses leg-isolated context extraction.
pact-plugin/tests/test_merge_guard.py	Adds comprehensive flag-aware retirement test matrix and adjusts a target-axis non-vacuity test to remain isolated under the new flag axis.
pact-plugin/tests/test_merge_guard_seam_integration.py	Adds an end-to-end disk-seam test ensuring escalated tokens survive bare retirement and still authorize.
README.md	Updates cache-path version example to 4.4.55.
pact-plugin/README.md	Updates displayed plugin version to 4.4.55.
pact-plugin/.claude-plugin/plugin.json	Bumps plugin version to 4.4.55.
.claude-plugin/marketplace.json	Bumps marketplace plugin version to 4.4.55.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.