feat(v1.100 PR-P2-5): auto-elevate shim removal gate (G3-UN-SHIM-LOCK)

Pre-PR-23 assurance blocker #5 of 2 remaining. Adds a CI gate that
fails when the uninstall auto-elevate shim and uninstall mutation
code coexist. This enforces that when PR-23 lands, the shim is
removed in the SAME PR — preventing the scaffold-era "safe by default"
UX from silently flipping meaning the moment real mutation lands.

## Rule

| shim_present | mutation_present | Result |
|:-:|:-:|---|
| 1 | 1 | **FAIL** — shim + mutation cannot coexist |
| 1 | 0 | PASS — PR-22/P2-x scaffold state |
| 0 | 1 | PASS — post-PR-23, shim correctly removed |
| 0 | 0 | PASS — trivially clean |

## Detection

**Shim detection** (`cmd/nftban-installer/flags.go`, grep for either):
  - "auto-elevated to --dry-run"
  - "NO MUTATION WILL OCCUR (v1.100 PR-22 scope)"

Two independent markers — if one is removed by refactor, the other
still fires. Ensures the gate doesn't silently stop working.

**Mutation detection** (`internal/installer/uninstall/*.go` +
`cmd/nftban-installer/uninstall_dryrun.go`, Go only, excluding tests):
  - nft mutation verbs (add/create/delete/flush)
  - systemctl lifecycle verbs (start/stop/restart/reload/enable/
    disable/mask/unmask) via exec.Run or Service* methods
  - External firewall binaries (ufw, firewall-cmd, iptables-restore)
  - Filesystem writers (WriteFileAtomic, os.WriteFile, Create,
    Remove, RemoveAll, MkdirAll, Rename)
  - State persistence (sf.Transition)

## Scope lock

- NO code changes (no shim removal, no mutation added)
- NO CLI redesign
- Pure detection gate — fires if the coupling appears, silent otherwise

## Two acceptable shim remediations at PR-23 time

1. **Delete** the auto-elevate block entirely (`--mode=uninstall`
   mutates unless `--dry-run` is explicit)
2. **Convert** to explicit refusal requiring `--dry-run` or
   `--confirm-mutation` (no silent default either way)

## Also: tracking update

Marks blocker #4 (exec-trace CI gate, PR #488) as LANDED. Remaining
pre-PR-23 blockers: 2 (this PR = P2-5, plus P2-6 payload integrity).

Contract doc updated with the full decision table + detection logic
in internal/installer/uninstall/contract.md.

Refs: internal/installer/uninstall/contract.md §"Pre-PR-23 blockers"
      + §"G3-UN-SHIM-LOCK (PR-P2-5) — how the gate decides"
      + §"Audit C regression note" (where the two remediations were
      originally committed to)
Authorization: locked Phase 2 sequencing (2026-04-20)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: itcmsgr

.github/workflows/ci-uninstall-canonization.yml

@@ -82,6 +82,118 @@ jobs:
       # external-firewall touches into the uninstall code, CI fails BEFORE
       # the unit tests even run.
       # ------------------------------------------------------------------
+      # ------------------------------------------------------------------
+      # G3-UN-SHIM-LOCK (PR-P2-5) — lifecycle transition safety lock.
+      #
+      # The `flags.go` auto-elevate shim silently forces --dry-run when
+      # `--mode=uninstall` is invoked without an explicit --dry-run.
+      # This is correct ONLY during PR-22's scaffold era, when no
+      # mutation code exists in the uninstall package. The moment
+      # real mutation code lands (PR-23 Switch phase / authority
+      # release), the shim MUST be removed or converted to an explicit
+      # refusal. Leaving both in place teaches operators "--mode=
+      # uninstall is safe by default" right up until a silent semantic
+      # flip to mutation — the exact UX-drift attack the contract
+      # warns against.
+      #
+      # This gate fires BEFORE tests so any reviewer sees the coupling
+      # immediately. The rule:
+      #
+      #   shim_present  ∧  mutation_present  →  FAIL
+      #   shim_present  ∧ ¬mutation_present  →  PASS (PR-22 scaffold state)
+      #  ¬shim_present  ∧  mutation_present  →  PASS (post-PR-23, shim removed)
+      #  ¬shim_present  ∧ ¬mutation_present  →  PASS (trivial)
+      #
+      # Contract: internal/installer/uninstall/contract.md
+      #           §"Audit C regression note" and §"Pre-PR-23 blockers"
+      # ------------------------------------------------------------------
+      - name: G3-UN-SHIM-LOCK — auto-elevate shim may not coexist with uninstall mutation
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+
+          # Part 1 — shim presence signature. Two independent markers,
+          # both introduced by PR-22's flags.go block. Presence of
+          # EITHER is sufficient — this ensures trivial renames don't
+          # accidentally hide the shim from the gate.
+          shim_present=0
+          if grep -qE 'auto-elevated to --dry-run' cmd/nftban-installer/flags.go 2>/dev/null; then
+            shim_present=1
+          fi
+          if grep -qE 'NO MUTATION WILL OCCUR \(v1\.100 PR-22 scope\)' cmd/nftban-installer/flags.go 2>/dev/null; then
+            shim_present=1
+          fi
+
+          # Part 2 — mutation presence in the uninstall scope. Scope is
+          # the uninstall package + the uninstall dispatcher, Go files
+          # only, excluding tests (which may contain mutation strings
+          # as fixtures).
+          mutation_scope_files=$(find \
+            internal/installer/uninstall \
+            cmd/nftban-installer/uninstall_dryrun.go \
+            -type f -name '*.go' 2>/dev/null | grep -vE '_test\.go$' || true)
+
+          # Mutation-flavored patterns. Each targets a specific kernel /
+          # service / filesystem / external-firewall write path. Match
+          # any = mutation code has landed.
+          mutation_patterns=(
+              'exec\.Run\("nft"[^)]*add'
+              'exec\.Run\("nft"[^)]*create'
+              'exec\.Run\("nft"[^)]*delete'
+              'exec\.Run\("nft"[^)]*flush'
+              'exec\.Run\("systemctl"[^)]*stop'
+              'exec\.Run\("systemctl"[^)]*start'
+              'exec\.Run\("systemctl"[^)]*restart'
+              'exec\.Run\("systemctl"[^)]*reload'
+              'exec\.Run\("systemctl"[^)]*enable'
+              'exec\.Run\("systemctl"[^)]*disable'
+              'exec\.Run\("systemctl"[^)]*mask'
+              'exec\.Run\("systemctl"[^)]*unmask'
+              'exec\.ServiceStop\('
+              'exec\.ServiceStart\('
+              'exec\.ServiceEnable\('
+              'exec\.ServiceDisable\('
+              'exec\.ServiceMask\('
+              'exec\.ServiceUnmask\('
+              'exec\.Run\("ufw"'
+              'exec\.Run\("firewall-cmd"'
+              'exec\.Run\("iptables-restore"'
+              'exec\.WriteFileAtomic\('
+              'os\.WriteFile\('
+              'os\.Create\('
+              'os\.Remove\('
+              'os\.RemoveAll\('
+              'os\.MkdirAll\('
+              'os\.Rename\('
+              'sf\.Transition\('
+          )
+          mutation_present=0
+          if [[ -n "$mutation_scope_files" ]]; then
+            for pat in "${mutation_patterns[@]}"; do
+              if grep -nE "$pat" $mutation_scope_files 2>/dev/null; then
+                mutation_present=1
+              fi
+            done
+          fi
+
+          echo "G3-UN-SHIM-LOCK state: shim_present=$shim_present mutation_present=$mutation_present"
+
+          # Gate rule: the coupling is the failure.
+          if [[ "$shim_present" -eq 1 && "$mutation_present" -eq 1 ]]; then
+            echo "::error::G3-UN-SHIM-LOCK FAIL: uninstall mutation code present AND auto-elevate shim still exists in cmd/nftban-installer/flags.go"
+            echo "::error::The shim must be REMOVED or CONVERTED TO REFUSAL before any mutation code lands in internal/installer/uninstall/."
+            echo "::error::See internal/installer/uninstall/contract.md §'Audit C regression note' for the two acceptable remediations."
+            exit 1
+          fi
+
+          if [[ "$mutation_present" -eq 1 ]]; then
+            echo "G3-UN-SHIM-LOCK PASS — uninstall mutation has landed AND shim was correctly removed (post-PR-23 state)"
+          elif [[ "$shim_present" -eq 1 ]]; then
+            echo "G3-UN-SHIM-LOCK PASS — no uninstall mutation yet; auto-elevate shim allowed during PR-22/P2-x scaffold era"
+          else
+            echo "G3-UN-SHIM-LOCK PASS — neither shim nor uninstall mutation present"
+          fi
+
       - name: G3-UN-NO-MUTATION — structural audit of uninstall package
         shell: bash
         run: |

internal/installer/uninstall/contract.md

@@ -283,6 +283,7 @@ discipline.
 | 1 | Prior-authority record hardening | PR #484 / `3b834033` | Added `recorded_at`, `installer_version`, explicit `active_at_install=false` handling to `prior.go`; 5-state classification |
 | 2 | External-firewall detection unification | PR #486 / `49d98fc1` | `internal/installer/extfw` canonical detector; Option A CSF config-file signal shared across install/update/uninstall; multi-active → `Ambiguous` (no silent collapse); cross-caller consistency test locked as regression guard |
 | 3 | Kernel/service snapshot CI gate | PR #487 / (tracked post-merge) | `G3-KS-SNAPSHOT` added to all 3 canonization workflows; `scripts/ci-snapshot-kernel-service.sh` helper; hard-asserts kernel nft tables + firewall-adjacent service states byte-identical after every dry-run path |
+| 4 | Exec-trace CI gate | PR #488 / (tracked post-merge) | `G3-EXEC-TRACE` added to all 3 canonization workflows; `scripts/ci-exec-trace-assert.sh` wraps dry-runs under `strace -f -e trace=execve`; fails if any forbidden mutator (nft add/flush/delete, systemctl lifecycle verbs, ufw/firewall-cmd/iptables-restore, package-manager removal, userdel/groupdel) is spawned |
 
 ### Behavioral / semantic blockers (code contract changes)
 
@@ -294,8 +295,48 @@ discipline.
 
 | # | PR | Scope | Blocking because |
 |---|---|---|---|
-| 4 | Exec-trace CI gate | `strace -f -e trace=execve` (or equivalent) around dry-run paths; assert no forbidden mutators spawned | Strictest purity guarantee; catches dynamically-constructed commands that source grep cannot see |
-| 5 | Auto-elevate shim removal gate | CI rule: PR-23-class changes blocked while the shim block in `flags.go` still exists when any mutation code lands in `internal/installer/uninstall/` | Prevents scaffold-era UX semantics leaking into mutation-era behavior |
+| 5 | Auto-elevate shim removal gate | `G3-UN-SHIM-LOCK` CI rule: PR-23-class changes blocked while the shim block in `flags.go` still exists when any mutation code lands in `internal/installer/uninstall/` | Prevents scaffold-era UX semantics leaking into mutation-era behavior |
+
+### G3-UN-SHIM-LOCK (PR-P2-5) — how the gate decides
+
+The gate lives in `ci-uninstall-canonization.yml` and runs before the
+structural-audit + unit tests so reviewers see the coupling first. It
+performs two independent detections and applies one rule:
+
+- **Shim detection.** Grep `cmd/nftban-installer/flags.go` for either
+  of two stable signature strings introduced by PR-22's uninstall
+  auto-elevate block: `"auto-elevated to --dry-run"` or
+  `"NO MUTATION WILL OCCUR (v1.100 PR-22 scope)"`. Presence of either
+  sets `shim_present=1`.
+
+- **Mutation detection.** Grep `internal/installer/uninstall/*.go`
+  plus `cmd/nftban-installer/uninstall_dryrun.go` (Go files only,
+  excluding `_test.go`) for any forbidden mutation-flavored pattern:
+  `nft` mutation verbs, `systemctl` lifecycle verbs, `Service*`
+  executor methods, external-firewall binaries, `os.*` filesystem
+  writers, `sf.Transition(`. Match of any one sets `mutation_present=1`.
+
+Rule table:
+
+| `shim_present` | `mutation_present` | Result |
+|:-:|:-:|---|
+| 1 | 1 | **FAIL** — shim + mutation cannot coexist |
+| 1 | 0 | PASS — PR-22/P2-x scaffold state |
+| 0 | 1 | PASS — post-PR-23, shim correctly removed |
+| 0 | 0 | PASS — trivially clean |
+
+The gate is **pure detection** — it does NOT remove the shim, does
+NOT add mutation code, and does NOT change CLI behavior. It only
+ensures that when PR-23 (or any later PR) adds uninstall mutation,
+the shim is removed in the SAME PR and both land together.
+
+Two acceptable shim remediations at PR-23 time:
+
+1. **Delete** the auto-elevate block entirely (so `--mode=uninstall`
+   mutates unless `--dry-run` is explicit)
+2. **Convert** to an explicit refusal requiring the operator to choose
+   between `--dry-run` and `--confirm-mutation` (no silent default
+   behaviour in either direction)
 
 ### Later v1.100 work (preferred order, not dogmatic)