feat: install.sh --merge-permissions — prompted, backed-up merge of the governance gate (#70)

[mattwillems-exabeam]

Closes #70.

Problem

The governance gate is opt-in on every install path. install.sh verified the merge and warned loudly when it was missing (gate_on()), but nothing ever performed it — so the shipped default was gate OFF until the operator hand-edits ~/.claude/settings.json, and the installer was a detection control rather than an enforcement one.

What this adds

--merge-permissions merges skills/soc-investigate/settings.snippet.json into the operator's settings. An interactive run whose gate reads OFF now shows exactly which rules it would add (via the merger's --dry-run) and asks y/N first.

Consent is preserved by construction:

• Nothing merges by default.
• -y does not authorise it — "assume yes" answers the installer's own questions, it does not license a write to the operator's settings. Installation alone never touches settings.json (the RFE's stated non-goal).
• --checks-only outranks the flag entirely (reported with a ↷ line, not silently).

The merge engine (skills/soc-investigate/merge_permissions.py) is:

• Backed up first — timestamped copy beside the original, carrying its mode.
• Additive only — operator rules are never removed, reordered, or retiered.
• Refusing on tier conflict — if a rule already sits in a different tier than the snippet specifies, that's operator intent or a mis-merge a human should resolve. It writes nothing and names the rule plus both tiers.
• Restoring on write failure, and idempotent.

Worth re-running even when the gate reads ON: a hand-merge of just the two ask lines leaves the containment deny list missing, so "gate on" is not the same as "snippet merged".

Verification after the merge is the pre-existing gate_on() re-read, not the merger's exit code — the same "a 0-exit doesn't prove it landed" discipline the install block already uses. No python3 or no snippet reports "cannot merge, here's the manual path", never a false green, mirroring the existing "cannot verify ≠ OFF" rule.

Placement

The merger lives beside the snippet it merges, so the two travel together — if the snippet is present, the merger is too. Same clone-path constraint as the bridge check, and the pair survives #66's move into plugin/ intact.

Testing

tests/test_merge_permissions.py — 25 tests, weighted toward the refusals (every one must write nothing): tier conflict, malformed settings, wrong-shaped snippet, simulated mid-write failure, --dry-run. Plus what must survive: operator rules, unrelated top-level keys, key order, file mode, and an invariant tying the merge back to install.sh's own gate check.

Full suite: 263 passed (238 + 25).

End-to-end against a throwaway HOME and a stubbed claude CLI: flag merges (allow +18, ask +4, deny +68 — 90 rules); -y alone writes nothing; re-run is a byte-identical no-op; conflict writes nothing and makes no backup; operator's rules preserved (19 allow / 69 deny / 4 ask, model intact); interactive accept merges, decline and EOF do not.

Bug found while testing

shutil.copyfile doesn't carry permissions, so a 600 settings.json was being rewritten 644 (mode copied back from the fresh backup) and its backup landed world-readable. The mode is now read off the live file and the backup uses copy2. Both pinned by tests.

🤖 Generated with Claude Code

[mattwillems-exabeam]

Follow-up commit ae637e7 — a defect this PR would have introduced, found while scoping a plugin-smoke.sh leg for the new flag.

install.sh hardcoded $HOME/.claude/settings.json. That was survivable while the governance block only read: under a relocated config dir it reports the gate's state from a file the running Claude Code ignores — able to say "gate ON" about a gate that isn't in effect, the dangerous direction. It stops being survivable now that the block can write, where the same assumption merges the gate into a file that never takes effect: a green "gate ON" protecting nothing.

Now resolves SOCXEN_SETTINGS_FILE → $CLAUDE_CONFIG_DIR/settings.json → ~/.claude/settings.json, with every message naming the resolved path. SOCXEN_SETTINGS_FILE is the same explicit escape hatch EXABEAM_ENV_FILE already gives the credentials path.

Verified both overrides write to the override and leave $HOME/.claude/settings.json absent.

Why it matters beyond correctness: plugin-smoke.sh isolates whole installs in throwaway CLAUDE_CONFIG_DIRs. Without this, a smoke leg exercising --merge-permissions would have escaped its sandbox and rewritten the maintainer's real ~/.claude/settings.json on every release run.

Holding the smoke leg itself for a follow-up: #66 already rewrites plugin-smoke.sh (version_at / fabricate_marketplace prior-worktree fallbacks), so adding a leg here would just manufacture a conflict in that file. Better sequenced after #66 lands.

[mattwillems-exabeam]

Rebased onto dev @ 21e2a0b (#74's containment deny-list fix) and force-pushed.

Zero file overlap between the two changes, so the rebase was clean. Full suite green against the new snippet: 263 passed, with the deny tier now at 68 rules ({allow: 18, ask: 4, deny: 68}).

Worth noting for review: tests/test_merge_permissions.py needed no changes for #74. Every assertion derives its expected rules from the shipped settings.snippet.json rather than hardcoding names or counts, so retiering or expanding the snippet can't silently invalidate the merge tests — the one thing it does hardcode is the two gated dismiss/close verbs, which is the invariant we want pinned.

Also dropped two stale "17-entry" references in comments here (ac4bf41) — the point they were making never depended on the count, and #74 moved it. Note the PR description above still says "17-entry" for the same reason; read it as "the containment deny list".

[virtualsteve-exa]

Code-owner review, verified hands-on. APPROVING on content — this is an exemplary implementation of #70, and the consent semantics are exactly right. Needs a rebase (and one sequencing decision) before merge; details below.

Verified on the branch

• Suite: 263 passed (238 + your 25), matching the PR's claim.
• The merge engine earns the trust its job requires. Read in full: additive-only via mutation of the loaded object (operator key order and unknown top-level settings survive by construction), exact-string tier-conflict refusal with the wildcard non-inference explicitly reasoned, atomic same-directory os.replace, live-file mode carried (not backup-derived — the 600→644 bug you caught and pinned), copy2 backup so the backup itself can't leak, restore-on-write-failure with the "both failed, your original is at X" worst case handled, and distinct exit codes so an unhandled traceback's exit 1 can't impersonate an answer.
• The installer wiring holds the #70 non-goal precisely: -y answers the installer's questions but never licenses the settings write; --checks-only outranks the flag visibly; non-tty gets the warning, not a hung prompt; the interactive offer previews the exact additions via --dry-run before asking; and success is judged by the pre-existing gate_on() re-read — with the "merger said 0 but the gate reads OFF" case reported as a failure, which is the correct trust direction.
• The SOCXEN_SETTINGS_FILE / CLAUDE_CONFIG_DIR resolution fix is load-bearing, not cosmetic — your CHANGELOG framing is right that hardcoding was survivable for a read and unsurvivable for a write. Good catch; the Praxen scan's finding 001 evidence (gate_on reading a file the running Claude Code may ignore) is partially addressed by this too.
• Docs: installation.md's new section states the consent model plainly. CHANGELOG under [Unreleased] — placement note below.

Before merge

1. Rebase over current dev (0.6.9 + #77 + #78 landed under you — the conflict is your [Unreleased] CHANGELOG block vs the 0.6.9 entry; keep yours above ## [0.6.9]). Nothing else you touch collides.
2. Re-run your end-to-end pass after the rebase and refresh the numbers in the PR body: post-#74 the merge adds allow +18, ask +4, deny +68 (the body's deny +17 predates the containment fix your own commit 3 already accounted for in the docs).
3. Sequencing with #66 (your call, both approved from my side): I'd land #66 first, then relocate this PR's pieces in the rebase — install.sh → plugin/install.sh, merge_permissions.py → plugin/skills/soc-investigate/, tests stay at root. The merger-beside-snippet placement you chose survives the move by design, which you clearly anticipated ("the pair survives #66's move intact").

Non-blocking observations

• backup_path() is second-granularity — two merges in the same second reuse a name. Harmless (the second backup is a copy of the first's result), not worth code.
• When #66's layout lands, SCRIPT_DIR-relative SNIPPET/MERGER paths resolve correctly from plugin/install.sh unchanged — verified the relative structure holds.

Nice work — the "cannot do it ≠ pretend it's done" discipline runs through every path here, and the tests are weighted exactly where the risk is (the refusals that must write nothing).

[mattwillems-exabeam]

Rebased onto dev @ a413686 — 0ade179. Both pre-merge items done.

1. CHANGELOG. [Unreleased] kept above ## [0.6.9] as you asked; that was the only conflict in the rebase — nothing else collided, as predicted.

2. Numbers refreshed, and the end-to-end pass re-run rather than re-quoted. Suite: 263 passed (238 + 25). All six installer scenarios re-verified against the post-#74 snippet:

Scenario	Result
--merge-permissions	gate ON — {allow: 18, ask: 4, deny: 68}
-y alone	nothing written, warning only
re-run over merged	"already merged, nothing to change"
tier conflict	✗ stopped, nothing written, file unchanged
operator rules preserved	19 allow / 69 deny / 4 ask, model intact
--checks-only + flag	↷ ignored, nothing written

PR body updated: deny +17 → deny +68 (90 rules), and the preserved-rules line now reads 19/69/4.

Worth noting the merge tests again needed zero changes across #74 and this rebase — deriving expected rules from the shipped snippet rather than hardcoding them is what made both a non-event.

On sequencing: taking your recommendation — land #66 first, then I'll relocate this PR's pieces into plugin/install.sh and plugin/skills/soc-investigate/merge_permissions.py in the follow-up rebase. Tests stay at root.

One thing outside both PRs that you may not have hit: GitHub Actions has not run on either of these branches' force-pushed heads. ac4bf41 sat with zero check-runs for nine hours while other PRs in the repo ran normally; Actions is enabled, no queued or approval-blocked runs, and neither workflow has a path filter. I cycled both PRs closed/reopened to force a reopened event and that didn't produce runs either. Since main is branch-protected on Repo invariants + signoff, this could stall the promotion window — flagging in case it's something you can see from the org side.

[mattwillems-exabeam]

Correction to my last note: CI is running normally again. Both checks are green on both PRs' current heads — #73 0ade179 and #66 d17fa41, Repo invariants + signoff pass on each. The gap was real (ac4bf41 genuinely had zero check-runs for nine hours, and the close/reopen cycle didn't shake it loose) but it cleared on its own with these pushes, so there's nothing for you to chase unless it recurs. Sorry for the false alarm — flagging the resolution so it doesn't cost you a look.