feat(claude+pr): first-class Claude Code integration and gx pr command suite (#600)

- skill_guard.py: add claude/, codex/, cursor/ to default agent-branch
  prefixes (was agent/ only) so the harness-managed branches each tool uses
  are recognized without env-setup. Add GUARDEX_AGENT_BRANCH_PREFIXES_ONLY
  env to lock down namespaces. Generalize the in-hook regex allowlist for
  push/checkout to cover all four prefixes.

- src/pr.js + src/cli/commands/pr.js: new `gx pr` command suite that
  centralizes PR-from-worktree plumbing — open (idempotent), status,
  sync, watch, list, ready, review. Detects base branch from origin/HEAD,
  generates titles/bodies from commits, supports auto-merge with
  configurable strategy, watches CI/merge state until merged / failed /
  timeout.

- src/cli/commands/claude.js: new `gx claude install / check / doctor /
  uninstall`. Installs .claude/settings.json (deep-merging with any
  user-defined hooks so we never clobber custom entries), copies managed
  hooks + slash commands, ensures the gitguardex skill is present, and
  repairs the CLAUDE.md -> AGENTS.md symlink. `check` is read-only;
  `doctor` is `check --fix`.

- .claude/commands/: ship /gx-status, /gx-doctor, /gx-pivot, /gx-pr,
  /gx-finish, /gx-setup slash commands documenting the canonical flow.

- AGENTS.md: add a Claude Code quickstart block at the top covering
  branch awareness, slash commands, PR flow, and `gx claude install`.

- Tests: claude-install (12 cases) and pr-module (8 cases) covering
  settings merge idempotency, hook/slash install, symlink repair,
  base-branch + title + body generation, and error paths. Updated
  skill-guard-hook test to reflect the new default prefixes (claude/,
  codex/, cursor/) and the new exclusive-mode env. Local repos in test
  helpers now disable commit signing so sandboxes with broken signing
  servers don't poison the suite.

https://claude.ai/code/session_01P6xFS4dDv2MnJ63XyxRbid

Co-authored-by: Claude <noreply@anthropic.com>

Author: NagyVikt

.claude/commands/gx-doctor.md

@@ -0,0 +1,14 @@
+# /gx-doctor
+
+Run repo repair + verification.
+
+Steps:
+1. `gx doctor` — installs/refreshes Guardex scaffolding, prunes stale worktrees, auto-finishes ready PRs.
+2. If issues remain, surface them with the relevant fix command (`gx setup`, `gx claude install`, `gx locks claim`, etc.).
+3. Report final state as `Repo is fully safe` or list outstanding errors/warnings.
+
+Useful flags to pass through:
+- `--dry-run` — preview without writing.
+- `--current` — limit to the top-level repo (no recursive scan).
+- `--no-wait-for-merge` — skip the auto-finish PR-merge polling.
+- `--json` — machine-readable output for scripts.

.claude/commands/gx-finish.md

@@ -0,0 +1,32 @@
+# /gx-finish
+
+Finish the current agent worktree task end-to-end: commit (if needed),
+push, open PR, wait for merge, prune the worktree.
+
+Default invocation for the current agent branch:
+
+```
+gx branch finish \
+  --branch "$(git branch --show-current)" \
+  --base main \
+  --via-pr \
+  --wait-for-merge \
+  --cleanup
+```
+
+To sweep every finished agent lane in this repo at once:
+
+```
+gx finish --all
+```
+
+Pre-conditions:
+- Working tree is clean OR commits are already in the worktree.
+- `gh auth status` is healthy (or `GITHUB_TOKEN` is set).
+- Tests for the touched area pass (run `npm test`/equivalent first).
+
+If branch protection blocks the merge, the flow returns the PR URL and
+sets auto-merge. Re-run `/gx-pr watch` to follow it.
+
+Do NOT replace this with standalone `git push` + `gh pr create` — those
+skip Guardex's cleanup, lock release, and worktree prune.

.claude/commands/gx-pivot.md

@@ -0,0 +1,28 @@
+# /gx-pivot
+
+Pivot the current session onto a fresh agent worktree so edits stop being
+blocked by skill_guard on a protected/non-agent branch.
+
+Usage:
+
+```
+gx pivot "<task description>" "<agent-name>"
+```
+
+Example:
+
+```
+gx pivot "Add /pr open" "claude-pr-flow"
+```
+
+Output prints `WORKTREE_PATH=...` and `BRANCH=agent/claude-pr-flow/<slug>`.
+`cd` into the worktree path, then continue editing.
+
+When to use:
+- `skill_guard` blocked an edit/Bash on `main`, `dev`, or any non-agent branch.
+- Starting a brand-new task in a fresh session.
+
+When NOT to use:
+- You're already inside an agent worktree and just want to continue. Stay put.
+- The task is a typo / 1-line tweak the user explicitly marked `quick:` /
+  `tiny:` / `just:` — those skip orchestration.

.claude/commands/gx-pr.md

@@ -0,0 +1,34 @@
+# /gx-pr
+
+Drive a pull request from the current agent worktree.
+
+Default (`/gx-pr` with no args): show PR status for the current branch +
+CI rollup.
+
+Subcommands:
+
+| Subcommand | Effect |
+|---|---|
+| `gx pr` / `gx pr status` | Print PR number, URL, mergeability, CI summary. |
+| `gx pr open` | Idempotent: push branch + create draft PR if none exists. |
+| `gx pr sync` | Push, ensure PR exists, optionally `--auto-merge` / `--ready`. |
+| `gx pr watch` | Poll PR until merged / failed / timeout (`--timeout 600`). |
+| `gx pr ready` | Promote draft → ready for review. |
+| `gx pr list` | List open PRs in the current repo. |
+| `gx pr review --provider claude` | Run AI PR review. |
+
+Flags:
+
+- `--base <branch>` (default: detected from `origin/HEAD`)
+- `--title "..."`, `--body "..."`
+- `--no-draft`, `--no-push`
+- `--auto-merge`, `--merge-strategy squash|merge|rebase`
+- `--json` for machine-readable output
+
+When to use vs `gx branch finish`:
+
+- `gx pr ...` is the *low-level* PR plumbing for an agent that wants
+  explicit control (status checks, ad-hoc PR creation outside a finish flow).
+- `gx branch finish --via-pr --wait-for-merge --cleanup` is still the
+  default *end-of-task* command and handles PR + auto-merge + worktree
+  cleanup in one shot. Use that when the work is genuinely done.

.claude/commands/gx-setup.md

@@ -0,0 +1,23 @@
+# /gx-setup
+
+Install gitguardex scaffolding into the current repo (or a target one).
+
+```
+gx setup            # current repo
+gx setup --target /path/to/repo
+gx setup --dry-run  # preview without writing
+```
+
+What it does:
+
+1. Installs companion tools (interactive prompt; skip with `--no-global-install`).
+2. Bootstraps `.omc/`, `.githooks/`, lock registry, OpenSpec scaffolding.
+3. Configures git hooks (`pre-commit`, `pre-push`, `post-checkout`) to defend
+   the protected base branch.
+4. Optionally installs Spec Kit (`--no-speckit` to opt out).
+5. Runs a final scan and prints any remaining safety findings.
+
+After `gx setup`, also run `gx claude install` (or `/gx-setup --claude`) to
+wire up Claude Code hooks, slash commands, and the agent skill.
+
+Then: `gx pivot "<task>" "<agent>"` to start work, or `gx status` to verify.

.claude/commands/gx-status.md

@@ -0,0 +1,13 @@
+# /gx-status
+
+Show the gitguardex status of the current repo: branch, guardex toggle,
+worktree count, agent-branch list, pending findings, and protected-base
+health.
+
+```
+gx status                # human-readable
+gx status --json         # machine-readable
+gx status --strict       # treat warnings as failures (exit 1 on any)
+```
+
+When status reports findings, run `/gx-doctor` to repair.

.claude/hooks/skill_guard.py

@@ -27,10 +27,20 @@ def emit_event(*_a: object, **_k: object) -> None:
 SHELL_GUARD_OVERRIDE_ENV = "ALLOW_BASH_ON_NON_AGENT_BRANCH"
 PRIMARY_WORKTREE_AGENT_EDIT_OVERRIDE_ENV = "ALLOW_CODE_EDIT_ON_PRIMARY_WORKTREE"
 # Extra agent-branch prefixes (comma- or space-separated). The hardcoded
-# "agent/" prefix is always recognized; this env var adds session-managed
-# prefixes like "claude/" without forcing repos to fork the hook.
+# defaults below are always recognized; this env var adds session-managed
+# prefixes without forcing repos to fork the hook.
+#
+# Defaults cover the common agentic-CLI branch namespaces:
+#   - "agent/"   — Guardex / Codex / generic agent branches
+#   - "claude/"  — Claude Code session branches (e.g. claude/improve-X-Segmk)
+#   - "codex/"   — Codex Cloud session branches
+#   - "cursor/"  — Cursor background-agent branches
+#
+# Repos that want to restrict to a single prefix should set
+# GUARDEX_AGENT_BRANCH_PREFIXES_ONLY=1 along with an explicit list.
 AGENT_BRANCH_PREFIXES_ENV = "GUARDEX_AGENT_BRANCH_PREFIXES"
-DEFAULT_AGENT_BRANCH_PREFIXES = ("agent/",)
+AGENT_BRANCH_PREFIXES_EXCLUSIVE_ENV = "GUARDEX_AGENT_BRANCH_PREFIXES_ONLY"
+DEFAULT_AGENT_BRANCH_PREFIXES = ("agent/", "claude/", "codex/", "cursor/")
 PATCH_FILE_HEADER_RE = re.compile(
     r"^\*\*\* (?:Update|Add|Delete) File:\s+(.+?)\s*$",
     re.MULTILINE,
@@ -51,13 +61,16 @@ def emit_event(*_a: object, **_k: object) -> None:
     re.compile(r"^git\s+pull(?:\s+--ff-only|\s+--rebase|\s+origin\s+\S+)?\s*$"),
     re.compile(r"^git\s+pull\s+--ff-only(?:\s+\S+){0,2}\s*$"),
     re.compile(r"^git\s+pull\s+--rebase(?:\s+\S+){0,2}\s*$"),
-    # Pushing agent/* branches from any cwd is safe — guarded branch namespace.
-    re.compile(r"^git\s+push(?:\s+(?:-u|--set-upstream))?\s+\S+\s+agent/[^\s]+(?:\s|$)"),
-    re.compile(r"^git\s+push(?:\s+(?:-u|--set-upstream))?\s+\S+\s+HEAD:agent/[^\s]+(?:\s|$)"),
+    # Pushing/checking out branches in any recognized agent namespace is safe.
+    # The capture group lists each default prefix; extra prefixes from
+    # GUARDEX_AGENT_BRANCH_PREFIXES are honored at branch-detection time, so
+    # these regexes only need to cover the built-in namespaces.
+    re.compile(r"^git\s+push(?:\s+(?:-u|--set-upstream))?\s+\S+\s+(?:agent|claude|codex|cursor)/[^\s]+(?:\s|$)"),
+    re.compile(r"^git\s+push(?:\s+(?:-u|--set-upstream))?\s+\S+\s+HEAD:(?:agent|claude|codex|cursor)/[^\s]+(?:\s|$)"),
     re.compile(
         r"^gh\s+(?:auth\s+status|repo\s+view|pr\s+(?:list|view|checks|status|create|edit|comment|review|ready|reopen|merge)|issue\s+(?:list|view|status|create|comment)|run\s+(?:list|view|watch)|workflow\s+(?:list|view|run))\b"
     ),
-    re.compile(r"^git\s+(?:checkout|switch)\s+agent/[^\s]+(?:\s|$)"),
+    re.compile(r"^git\s+(?:checkout|switch)\s+(?:agent|claude|codex|cursor)/[^\s]+(?:\s|$)"),
     re.compile(r"^(?:ls|cat|head|tail|wc|nl|sed\s+-n|rg|find|stat|du|df|ps|ss|which|command\s+-v)\b"),
     # All gitguardex CLI subcommands are themselves safety-aware; trust them on protected branches.
     re.compile(r"^(?:gx|guardex|gitguardex|multiagent-safety)\s+\S+\b"),
@@ -297,11 +310,20 @@ def _parse_branch_prefixes(raw: str) -> tuple[str, ...]:
 
 
 def agent_branch_prefixes() -> tuple[str, ...]:
-    """Active agent-branch prefixes: defaults plus GUARDEX_AGENT_BRANCH_PREFIXES."""
+    """Active agent-branch prefixes: defaults plus GUARDEX_AGENT_BRANCH_PREFIXES.
+
+    If GUARDEX_AGENT_BRANCH_PREFIXES_ONLY=1, only the explicit env list is used
+    (defaults are dropped). This is for repos that want to lock down which
+    namespaces count as agent-managed.
+    """
     extras = _parse_branch_prefixes(os.environ.get(AGENT_BRANCH_PREFIXES_ENV, ""))
+    exclusive = os.environ.get(AGENT_BRANCH_PREFIXES_EXCLUSIVE_ENV, "").strip().lower() in {
+        "1", "true", "yes", "on",
+    }
+    base = () if exclusive else DEFAULT_AGENT_BRANCH_PREFIXES
     seen: set[str] = set()
     out: list[str] = []
-    for prefix in (*DEFAULT_AGENT_BRANCH_PREFIXES, *extras):
+    for prefix in (*base, *extras):
         if prefix not in seen:
             seen.add(prefix)
             out.append(prefix)

AGENTS.md

@@ -7,6 +7,28 @@ This document is the agent contract for this repo. It applies identically to Cod
 - Optimize for task completion with low token use.
 - Prefer phase-based execution over conversational micro-steps.
 
+## Claude Code quickstart
+
+If you are a Claude Code session arriving in this repo for the first time:
+
+1. **Branch awareness** — `skill_guard.py` accepts `agent/*`, `claude/*`,
+   `codex/*`, and `cursor/*` as agent-managed branch namespaces by default.
+   Your harness-assigned `claude/<...>` branch is recognized; you don't need
+   to set `GUARDEX_AGENT_BRANCH_PREFIXES`. If you ever do need to lock down
+   namespaces, set `GUARDEX_AGENT_BRANCH_PREFIXES_ONLY=1` plus an explicit
+   list.
+2. **Slash commands** — `/gx-status`, `/gx-doctor`, `/gx-pivot`,
+   `/gx-pr`, `/gx-finish`, `/gx-setup` are available out of the box. See
+   `.claude/commands/`.
+3. **PR flow** — when you need explicit PR control, use `gx pr open`,
+   `gx pr status`, `gx pr sync`, or `gx pr watch`. For end-of-task
+   commit + push + PR + merge + cleanup, still use the non-negotiable
+   `gx branch finish --via-pr --wait-for-merge --cleanup`.
+4. **Repo wiring** — `gx claude install` writes `.claude/settings.json`,
+   hooks, slash commands, and the gitguardex skill into a target repo.
+   `gx claude check` diagnoses drift without writing; `gx claude doctor`
+   diagnoses and repairs.
+
 ## ExecPlans
 
 When writing complex features or significant refactors, use an ExecPlan (as described in `.agent/PLANS.md`) from design to implementation.