fix(merge-guard): unify branch_set + mass_target onto injective netstring _canonical_join SSOT (issue 1136) (#1145)

* fix(merge-guard): unify branch_set + mass_target onto injective netstring _canonical_join SSOT (issue 1136)

#1136 is a delimiter-class canonical-identity collision, not a single-delimiter
bug: mass_target's identity was non-injective at two git-legal delimiters (the
refspec comma AND the remote/refspec boundary), letting two distinct destructive
sets share one identity (a cross-set under-block).

Replace the hand-rolled delimiter joins in both destructive-set identity encoders
with one pure netstring/length-prefix primitive, `_canonical_join(items)` = the
`len:value` framing, injective by construction and content-agnostic:
- branch_set  = _canonical_join(sorted(set(names)))
- mass_target = _canonical_join([flags_part, remote, *sorted(set(refspecs))])

The structural delimiters are eliminated (subsumed by framing), closing the whole
delimiter class at once. The \x00implicit sentinel stays unchanged (its NUL keeps
it disjoint from a real remote literally named "implicit" under framing). Refspecs
are now deduped (a duplicate ref is the same destructive target).

Over-block is closed by construction: mint and read derive the identity from the
same _canonical_join via the one extract_command_context SSOT, so a faithful click
self-matches. No mint/read call site is split.

Format-pinned tests updated to be format-following (assert against _canonical_join
calls, not hardcoded literals); format-agnostic distinctness/reorder/absence
asserts left intact. Doc-drift comment in merge_guard_pre corrected; stale
encoding prose in the shared-hook docstrings brought in line with the framing.

* chore(release): bump plugin version to 4.5.7

Canonical-identity SSOT fix (issue 1136) — merge_guard mass_target + branch_set
delimiter-class collision closed via the shared injective netstring _canonical_join.

* test(merge-guard): #1136 canonical-join SSOT SACROSANCT cert — injectivity proof + closure + over-block corpus

52-row bidirectional certification for the canonical-identity SSOT (issue 1136):
- Injectivity by exhibited inverse: a total constructive left-inverse decode
  round-trips every edge (empty list/item, embedded colon/digits/NUL, multi-digit
  lengths, netstring-looking content) plus a 5000-random property test — bounds the
  shared-helper concentration hazard by construction, not by sampling.
- Closure: base (9256c93, baked in-test via git-show+exec) COLLIDES -> HEAD
  REFUSES for BOTH the comma AND the boundary witnesses, at the identity level AND
  the real mint->execute gate (a 2-set token no longer authorizes the 3-set).
- Over-block primary corpus (the cardinal direction): faithful mass/branch deletes
  mint and self-match; reorder and dedup still match.
- Doubled surface base-vs-HEAD, sentinel isolation, the dedup behavior row, and the
  colon force-delete edge.

Full suite: 11114 passed / 11 skipped / 0 failed / 0 errors (python 3.12.7).

* test(merge-guard): harden #1136 cert non-vacuity — self-contained base-through-gate row + HASH_3 control

Self-critical cert review strengthenings on #1136's core claim (both were
empirically confirmed, not fixing a hole — the pre-registered vacuity suspects
were falsified):
- Add `hash-in-remote` (the HASH_3 form `git push "origin#a" --delete b c`) to the
  over-block self-match corpus — the missing mintable + self-authorizing control
  that proves the # cross-set DENY is a WRONG-SET denial, not an unmintable-always-
  deny artifact.
- New test_base_encoder_through_real_gate_cross_authorizes: patches the baked base
  encoder into the one SSOT and asserts the collision CROSS-AUTHORIZES at the real
  mint->execute gate for BOTH witnesses — making the closure non-vacuity SELF-
  CONTAINED (no longer relying on an out-of-file monkeypatch).

Cert 52 -> 54 rows. Full suite 11116 passed / 11 skipped / 0 failed / 0 errors.

* ci(merge-guard): make baked-base cert files CI-portable under shallow clone

The #1136 and (pre-existing) #1129-R2 certification files load a base classifier
via `git show <base-sha>:...` at module load. CI's actions/checkout does a shallow
clone (fetch-depth 1) lacking those base commits, so `git show` failed and BOTH
files aborted collection — taking the whole suite down (0 tests run). Surfaced by
CI + the Copilot review.

Two complementary fixes (defense-in-depth), modeled on the existing
test_merge_guard_1118_recert.py precedent:
- .github/workflows/tests.yml: fetch-depth: 0 on checkout, so CI has full history
  and every baked-base non-vacuity differential actually RUNS in CI.
- Both cert files: _load_classifier returns None on git-show failure (collection
  succeeds), the module-level base symbols are None-safe, and a @requires_history
  skip gates ONLY the base-vs-HEAD differential rows — the HEAD-side closure/REFUSE
  assertions and absolute invariants stay unguarded so a fix-revert is still caught
  even under a shallow clone.

No behavioral assertion altered (R2 cert: guards only). Full suite 11119 passed /
11 skipped / 0 failed / 0 errors.

Author: michael-wojcik

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "PACT",
       "source": "./pact-plugin",
       "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
-      "version": "4.5.6",
+      "version": "4.5.7",
       "author": {
         "name": "Synaptic-Labs-AI"
       },

.github/workflows/tests.yml

@@ -81,6 +81,13 @@ jobs:
       # These majors run on Node24 (checkout@v4 / setup-python@v5 were Node20,
       # deprecated by GitHub — forced off by 2026-06-16, so re-pinned forward).
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          # Full history so the baked-base cert files can `git show <base-sha>`
+          # (their base-vs-HEAD non-vacuity differentials). The default shallow
+          # clone (fetch-depth: 1) lacks the base commits -> `git show` fails ->
+          # those files abort collection (0 tests run). Full history makes every
+          # differential RUN in CI; the in-file self-skip guards are the fallback.
+          fetch-depth: 0
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:

README.md

@@ -605,7 +605,7 @@ When installed as a plugin, PACT lives in your plugin cache:
 │   └── cache/
 │       └── pact-plugin/
 │           └── PACT/
-│               └── 4.5.6/       # Plugin version
+│               └── 4.5.7/       # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/

pact-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "4.5.6",
+  "version": "4.5.7",
   "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
   "author": {
     "name": "Synaptic-Labs-AI",

pact-plugin/README.md

@@ -1,6 +1,6 @@
 # PACT — Orchestration Harness for Claude Code
 
-> **Version**: 4.5.6
+> **Version**: 4.5.7
 
 Turn a single Claude Code session into a managed team of specialist AI agents that prepare, design, build, and test your code systematically.
 

pact-plugin/hooks/merge_guard_pre.py

@@ -556,7 +556,7 @@ def _token_matches_command(token: dict, command: str) -> bool:
         # SSOT), so a scalar token can NOT authorize a set command or vice-versa
         # (the absent-key side fails _both_present_equal), and a {a,b} token can
         # NOT authorize {a,b,c} (unequal canonical strings) while a {b,a} reorder
-        # MATCHES (both canonicalize to `a,b`). The #1032 under-block is closed by
+        # MATCHES (both canonicalize to the SAME string). The #1032 under-block is closed by
         # equality; both sides derive via the ONE extract_command_context SSOT so
         # mint and read cannot drift.
         return (

pact-plugin/hooks/shared/merge_guard_common.py

@@ -168,6 +168,7 @@
 import re
 import shlex
 import time
+from collections.abc import Sequence
 from pathlib import Path
 
 from .paths import get_claude_config_dir
@@ -875,32 +876,44 @@ def _extract_branch_name(command: str) -> str | None:
     return _strip_surrounding_quotes(positionals[0])
 
 
+def _canonical_join(items: Sequence[str]) -> str:
+    """Netstring/length-prefix encode a sequence of strings into ONE canonical
+    identity STRING, injective by construction (a left-inverse decoder exists), so
+    distinct sequences never collide REGARDLESS of item content — incl. commas, '@',
+    '#', ':' and NUL. Pure + deterministic (no sort, no dedup — the caller supplies a
+    canonical ordered list). Stays a `str` (the token persists as JSON; compared by
+    str()-equality, never decoded). Shared SSOT for branch_set + mass_target (#1136)."""
+    return "".join(f"{len(i)}:{i}" for i in items)
+
+
 def _extract_branch_delete_set(command: str) -> str | None:
     """Extract the canonical MULTI-branch identity of a force-delete command.
 
     The MULTI-target sibling of _extract_branch_name (which owns the SINGLE
     branch). Handles the CLI `git branch -D|--delete --force <a> <b> ...` form
     with TWO OR MORE positional branch names, returning a canonical
-    sort+dedup+quote-strip identity STRING joined on NUL (`\x00`), or None
+    sort+dedup+quote-strip identity STRING (the shared netstring `_canonical_join`
+    SSOT), or None
     when fewer than two branch names are positively extractable (<2 -> defers to
     the scalar _extract_branch_name path — the BOUNDARY discriminator, so a
     command populates EXACTLY ONE of `branch` / `branch_set`).
 
-    Mirrors the _extract_mass_delete_target precedent (#1062b): an
+    Shares the _extract_mass_delete_target encoder (#1062b/#1136): an
     ORDER-INDEPENDENT identity STRING (never a tuple/list — a token persists as
     JSON, and the read side compares via `str()`, so a list<->tuple round-trip
     must never enter the identity), built + canonicalized in this ONE shared SSOT
     so mint and read derive byte-identical strings (D2 symmetry by construction).
-    The join separator is NUL (`\x00`): git forbids control bytes in branch
-    names, so no name can contain it and the joined identity is INJECTIVE —
-    distinct branch SETS never collide. (A bare `,` was NOT injective: a branch
-    literally named `a,b` collided with the set {a, b}, cross-authorizing distinct
-    sets — the F1 review finding. NUL is JSON/str()-safe: json escapes it on dump,
-    restores it on load, and str() is stable, so the round-trip holds.)
+    Encoding is the netstring `_canonical_join` (`len:name` framing): the identity
+    is INJECTIVE by construction and CONTENT-AGNOSTIC, so distinct branch SETS never
+    collide regardless of name content — no separator has to be ref-illegal. (A bare
+    `,` join was NOT injective: a branch literally named `a,b` collided with the set
+    {a, b}, cross-authorizing distinct sets — the F1 review finding; framing closes
+    that class outright. The string is JSON/str()-safe: json round-trips it and str()
+    is stable, so the identity survives token persistence.)
     Set-EQUALITY on this INJECTIVE string then closes the #1032 multi-target
     under-block UNCONDITIONALLY: a `{a,b}` token cannot authorize `{a,b,c}`
     (unequal strings) while a `{b,a}` reorder MATCHES (both canonicalize to the
-    same NUL-joined string).
+    same string).
 
     Uses the SAME tokenization as _extract_branch_name (executable-prefix
     truncation at a benign continuation/redirect via _executable_prefix, then drop
@@ -921,12 +934,13 @@ def _extract_branch_delete_set(command: str) -> str | None:
     if len(positionals) < 2:
         return None
     names = sorted({_strip_surrounding_quotes(t) for t in positionals})
-    # Join on NUL (\x00) — a REF-ILLEGAL separator (git forbids control bytes in
-    # branch names) so no name can contain it -> the identity is INJECTIVE and
-    # distinct sets never collide (the F1 fix; a bare `,` collided a branch named
-    # `a,b` with the set {a, b}). JSON/str()-safe, so D2 mint==read symmetry and
-    # the JSON token round-trip both hold.
-    return "\x00".join(names) or None
+    # Encode via the shared netstring SSOT (_canonical_join): each name is framed as
+    # `len:name`, so the identity is INJECTIVE by construction and CONTENT-AGNOSTIC —
+    # distinct sets never collide regardless of name content, without depending on any
+    # separator being ref-illegal (an earlier bare `,` join collided a branch named
+    # `a,b` with the set {a, b}). JSON/str()-safe, so mint==read symmetry and the JSON
+    # token round-trip both hold.
+    return _canonical_join(names) or None
 
 
 def _extract_force_push_target_ref(command: str) -> str | None:
@@ -1102,14 +1116,15 @@ def _extract_mass_delete_target(command: str) -> str | None:
     benign `-o ci.skip` does not over-bind; privileged flags ride the existing #1042
     `bound_flags` axis. Derived identically on BOTH arms via this ONE SSOT → mint==read
     parity by construction; recognition⟺mintability (the arm returns the op IFF this is
-    non-None) → #1064-impossible. Returns a READABLE tuple, never a hash:
+    non-None) → #1064-impossible. Returns a READABLE netstring identity STRING
+    (`len:value`-framed field tuple; no `@`/`#`/`,` delimiters; #1136), never a hash:
 
-        <sorted-mass-flags>@<remote-or-implicit-marker>[#<sorted-refspecs>]
-        git push --mirror origin               → --mirror@origin
-        git push --mirror                      → --mirror@\\x00implicit (implicit-remote MINTABLE)
-        git push --prune origin refs/heads/main → --prune@origin#refs/heads/main
-        git push origin --delete a b           → --delete@origin#a,b (binds the EXACT deleted set)
-        git push origin :a :b                  → --delete@origin#a,b
+        _canonical_join([<sorted-mass-flags>, <remote-or-implicit-marker>, *<sorted-deduped-refspecs>])
+        git push --mirror origin               → 8:--mirror6:origin
+        git push --mirror                      → 8:--mirror9:\\x00implicit (implicit-remote MINTABLE)
+        git push --prune origin refs/heads/main → 7:--prune6:origin15:refs/heads/main
+        git push origin --delete a b           → 8:--delete6:origin1:a1:b (binds the EXACT deleted set)
+        git push origin :a :b                  → 8:--delete6:origin1:a1:b
 
     BOUNDARY (lead-mandated, no double-classification): a SINGLE-ref delete is owned by
     `_extract_remote_ref_delete_target` (tried FIRST in the recognition arm). This
@@ -1162,10 +1177,11 @@ def _extract_mass_delete_target(command: str) -> str | None:
     else:
         return None
 
-    target = f"{flags_part}@{remote}"
-    if refspecs:
-        target += "#" + ",".join(refspecs)
-    return target
+    # Encode the destructive identity via the shared netstring SSOT (_canonical_join):
+    # framing subsumes the old `@`/`#`/`,` delimiters, so the identity is injective for
+    # ANY field content (closes the #1136 `#`/comma collision class). Dedup refspecs
+    # (a duplicate ref is the same target); empty refspecs frame uniformly (no `#`).
+    return _canonical_join([flags_part, remote, *sorted(set(refspecs))])
 
 
 # -----------------------------------------------------------------------------
@@ -1427,11 +1443,11 @@ def extract_command_context(command: str, flag_scan_text: str | None = None) ->
         pr_number:  str  (merge / close)
         branch:     str  (branch-delete — SINGLE target, exactly 1 positional)
         branch_set: str  (branch-delete — MULTI target #1129, >=2 positionals) —
-                     canonical sort+dedup+quote-strip names joined on NUL (`\x00`,
-                     a ref-illegal separator → injective, no delimiter collision)
+                     canonical sort+dedup+quote-strip names via the shared netstring _canonical_join (`len:name` framing,
+                     injective by construction, content-agnostic — no delimiter collision)
         target_ref: str  (force-push / push-to-main, KD-6; remote-ref-delete #1062a)
-        mass_target: str (remote-mass-delete #1062b) — normalized identity tuple
-                     <sorted-mass-flags>@<remote-or-implicit-marker>[#<sorted-refspecs>]
+        mass_target: str (remote-mass-delete #1062b) — normalized identity STRING
+                     _canonical_join([<sorted-mass-flags>, <remote-or-implicit-marker>, *<sorted-deduped-refspecs>])
         protected_branch: str (branch-protection #1063) — the branch from the
                      branches/<b>/protection URL path
         bound_flags: list[str]  (#1042) — sorted normalized privileged flags;

pact-plugin/tests/test_merge_guard_1129_r1_branch_set.py

@@ -34,13 +34,12 @@
     detect_command_operation_type,
     extract_command_context,
     _extract_branch_delete_set,
+    _canonical_join,
 )
 from merge_guard_pre import _token_matches_command  # noqa: E402
 
 # FORCE flag assembled at runtime — no raw `git branch -D` literal in the source.
 _D = "-" + "D"
-# The canonical branch_set join separator (NUL, ref-illegal → injective; F1 fix).
-_SEP = "\x00"
 
 
 def _cmd(flags: str, names: list[str]) -> str:
@@ -69,7 +68,7 @@ def test_multi_branch_force_delete_mints_branch_set_and_self_matches(flags):
     assert ctx.get("operation_type") == "branch-delete"
     # The additive key is populated with the canonical sorted identity, and the
     # scalar `branch` key stays ABSENT (mutual exclusivity).
-    assert ctx.get("branch_set") == _SEP.join(["A", "B", "C"])
+    assert ctx.get("branch_set") == _canonical_join(["A", "B", "C"])
     assert "branch" not in ctx
     # The faithful click now mints+matches (the over-block cure).
     assert _matches(cmd, cmd) is True
@@ -109,7 +108,7 @@ def test_duplicate_names_dedup_to_same_set():
 
 def test_slashed_branch_names_mint_and_match():
     cmd = _cmd(_D, ["feature/x", "feature/y"])
-    assert extract_command_context(cmd).get("branch_set") == _SEP.join(["feature/x", "feature/y"])
+    assert extract_command_context(cmd).get("branch_set") == _canonical_join(["feature/x", "feature/y"])
     assert _matches(cmd, cmd) is True
 
 
@@ -126,7 +125,7 @@ def test_lowercase_delete_stays_ungated(flags):
 def test_branch_set_is_order_independent_canonical_string():
     a = _extract_branch_delete_set(_cmd(_D, ["A", "B", "C"]))
     b = _extract_branch_delete_set(_cmd(_D, ["C", "B", "A"]))
-    assert a == b == _SEP.join(["A", "B", "C"])
+    assert a == b == _canonical_join(["A", "B", "C"])
     assert isinstance(a, str)  # STRING, never a tuple/list (JSON round-trip safety)
     # Fewer than two positionals -> None -> defers to the scalar `branch` path.
     assert _extract_branch_delete_set(_cmd(_D, ["solo"])) is None

pact-plugin/tests/test_merge_guard_1129_r1_cert.py

@@ -240,11 +240,11 @@ def test_persisted_token_branch_set_is_canonical_string(self, tmp_path):
         assert len(tokens) == 1
         payload = json.loads(tokens[0].read_text())
         # The token carries the shared-SSOT context; branch_set is the canonical,
-        # sorted, NUL-joined STRING (#1135 F1 — NUL is git-forbidden in ref names, so
-        # the joined identity is INJECTIVE; a list/tuple would have survived the JSON
+        # sorted, netstring-framed STRING (the shared _canonical_join SSOT, #1136 —
+        # injective by construction); a list/tuple would have survived the JSON
         # round-trip as a list and broken str-comparison matching).
         ctx = payload.get("context", payload)
-        assert ctx.get("branch_set") == "aa\x00bb\x00cc"
+        assert ctx.get("branch_set") == mgc._canonical_join(["aa", "bb", "cc"])
         assert isinstance(ctx.get("branch_set"), str)
         # And a reordered exec of the same set authorizes against the persisted token.
         assert _execute(_cmd(_D, ["bb", "cc", "aa"]), tmp_path) == ALLOW
@@ -260,7 +260,7 @@ class TestGatherCorrectness:
     def test_dash_flag_is_not_gathered_as_a_branch(self, tmp_path):
         # `-r` (a dash-flag) must be dropped; only the two real names form the set.
         cmd = _cmd(_D + " -r", ["origin/x", "origin/y"])
-        assert mgc.extract_command_context(cmd).get("branch_set") == "origin/x\x00origin/y"
+        assert mgc.extract_command_context(cmd).get("branch_set") == mgc._canonical_join(["origin/x", "origin/y"])
         minted, rc = _roundtrip(cmd, cmd, tmp_path)
         assert minted == 1
         assert rc == ALLOW
@@ -374,15 +374,15 @@ class TestCommaNameCollisionClosed:
     """#1135 F1: git ref names PERMIT commas, so the OLD `,`-joined branch_set was
     non-injective — {aa,'bb,cc'} (2 branches) and {aa,bb,cc} (3 branches) both joined
     to `aa,bb,cc`, letting a 2-branch token authorize a 3-branch delete (a cross-set
-    UNDER-BLOCK; the review witness). The NUL join (git-forbidden in ref names) makes
-    the identity INJECTIVE: the two sets now produce distinct strings, so the token no
+    UNDER-BLOCK; the review witness). The netstring _canonical_join SSOT (#1136) makes
+    the identity INJECTIVE by construction: the two sets now produce distinct strings, so the token no
     longer cross-authorizes. The over-block direction is untouched (see the self-match)."""
 
     def test_two_set_and_three_set_no_longer_collide(self):
         two = mgc._extract_branch_delete_set(_cmd(_D, ["aa", "bb,cc"]))       # {aa, 'bb,cc'}
         three = mgc._extract_branch_delete_set(_cmd(_D, ["aa", "bb", "cc"]))  # {aa, bb, cc}
         assert two != three, "comma-named 2-set must not collide with the 3-set (F1)"
-        assert two == "aa\x00bb,cc" and three == "aa\x00bb\x00cc"
+        assert two == mgc._canonical_join(["aa", "bb,cc"]) and three == mgc._canonical_join(["aa", "bb", "cc"])
 
     def test_two_set_token_does_not_authorize_three_set_delete(self, tmp_path):
         # The review's cross-set under-block witness — now REFUSED.
@@ -434,7 +434,7 @@ def _q(self, names):
         return _GB + _D + " " + " ".join("'%s'" % n for n in names)
 
     def test_quoted_names_canonicalize_quote_insensitively(self):
-        assert mgc._extract_branch_delete_set(self._q(["aa", "bb"])) == "aa\x00bb"
+        assert mgc._extract_branch_delete_set(self._q(["aa", "bb"])) == mgc._canonical_join(["aa", "bb"])
 
     def test_quoted_mint_authorizes_unquoted_exec(self, tmp_path):
         minted, rc = _roundtrip(self._q(["aa", "bb"]), _cmd(_D, ["aa", "bb"]), tmp_path)